mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-28 04:02:18 +01:00
First PR: runtime. UI: #15728. Qualification: #15729.
## Thinking Path
> - Paperclip manages agent work through tasks and governed connections.
> - Chat connections already bind external conversations to those tasks.
> - Speko handles voice and telephony, while the selected Paperclip
agent does the work.
> - A call needs durable session authority, ordered follow-ups, and safe
result delivery.
> - This PR adds an explicit voice transport to the existing connection
runtime.
> - The UI and qualification suites follow in linked PRs. Speko stays
experimental.
## Linked Issues or Issue Description
**Problem or motivation**
Phone and browser voice conversations cannot use the chat connection
task lifecycle. A separate voice runtime is needed to preserve task
authority, retries, and reply history.
**Proposed solution**
Add company-scoped voice sessions, signed callbacks, durable replies,
inbound intake, and an agent-facing outbound-call tool. Reuse existing
tasks, queues, secrets, and publications.
**Roadmap alignment**
This extends the experimental chat connector entry points under Agent
Chat and Connected Apps. The project owner requested this feature.
Refs #11418 for the original provider catalog proposal. This
implementation uses the newer chat connection infrastructure rather than
an MCP catalog-only integration. Refs #15721 for remote OpenCode
startup.
## What Changed
- Add additive voice schema, shared contracts, session APIs, and
provider callbacks.
- Bind browser, inbound, and outbound sessions to an endpoint, task, and
selected agent.
- Add low-trust guest intake in an explicitly selected sandbox and keep
ordinary approval rules.
- Submit task work through session-scoped tools and push approved
replies through Speko POST /v1/calls/{id}/messages.
- Distinguish provider acceptance from confirmed spoken playback.
Reconcile reports without downloading recordings.
- Add protocol, migration, persistence, provider, and
delivery-diagnostic tests.
## Verification
- Master 3389bea708 is integrated. Database/shared builds, server
typecheck, migration upgrade/replay checks, and 46
communication-guidance/provider/protocol tests passed.
- The final persistence suite passed 85 real-database tests. Five
focused native continuation/authorization regressions passed. Five
callback ownership/rotation tests passed after the last runtime repair.
- Review repairs cover reconnect ownership, current caller authority,
duplicate delivery, multipart answers, task-page answers, guest question
handling, and saved sandbox recovery.
- A real OpenCode/OpenRouter DeepSeek task ran in Daytona and saved a
correct disk-space answer. This did not establish live-call playback.
- Full local typecheck/build passed before the final repairs; focused
typechecks passed after them. Latest-head CI runs the repository gates.
- The separate integrated browser qualification passed two journeys and
failed browser answer retrieval. The feature remains experimental. The
report in #15729 records this failure and outstanding real-provider
acceptance.
- No lockfiles are included. Speko migrations follow master as
0324–0330.
## Risks
- Voice sessions add migrations and provider-dependent lifecycle
behavior. Migrations preserve existing chat and AI transports.
- Callback origins must be reachable HTTPS. Provider keys and signing
secrets remain vaulted.
- Unverified callers receive task-scoped low-trust authority. Caller ID
does not grant private task access.
- Outbound telephony incurs provider charges. Provider acceptance is not
proof that the caller heard an answer.
- Keep the feature behind the existing experimental chat setting until
the real browser, inbound, outbound, and delayed-result acceptance
matrix passes.
## Model Used
OpenAI Codex, GPT-6, with tool use and code execution. The exact serving
model ID and context window are not exposed in this session.
## Checklist
- [x] I have included a thinking path that traces from project context
to this change
- [x] I have specified the model used (with version and capability
details)
- [x] I have checked ROADMAP.md and confirmed this PR does not duplicate
planned core work
- [x] I have searched GitHub for duplicate or related PRs and linked
them above
- [x] I have either (a) linked existing issues with `Fixes: #` / `Closes
#` / `Refs #` OR (b) described the issue in-PR following the relevant
issue template
- [x] I have not referenced internal/instance-local Paperclip issues or
links (only public GitHub `#NNN` / `github.com/paperclipai/paperclip`
URLs)
- [x] My branch name describes the change (e.g. `docs/...`, `fix/...`)
and contains no internal Paperclip ticket id or instance-derived details
- [ ] I have run tests locally and they pass
- [x] I have added or updated tests where applicable
- [x] I have updated relevant documentation to reflect my changes
- [x] I have considered and documented any risks above
- [x] All Paperclip CI gates are green
- [x] Greptile is 5/5 with no open P2s, recommendations, or follow-ups
- [x] I will address all Greptile and reviewer comments before
requesting merge
---------
Co-authored-by: Paperclip <noreply@paperclip.ing>
48 lines
4.0 KiB
TypeScript
48 lines
4.0 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
||
import { parseSpekoDeliveryDiagnostics } from "../services/voice/speko-delivery-diagnostics.js";
|
||
const acceptedAt = "2026-10-09T13:39:14.340Z";
|
||
const deliveries = [{messageId: "msg_test", acceptedAt}];
|
||
function fixture() {
|
||
const prompt = "Paperclip pushes approved task answers. private prompt credential";
|
||
return {
|
||
call: {id: "call_test", status: "ended", ended_at: "2026-10-09T13:39:36.000Z",
|
||
recording_url: "https://private.example/recording", phone: "+12015551234", metadata: {token: "private-token"},
|
||
pipeline_config: {kind: "s2s", systemPrompt: prompt, s2s: {systemPrompt: prompt, tools: [{name: "submit_request"}]},
|
||
tools: [{name: "submit_request", source: {secret: "private-secret"}}, {name: "private-custom-tool"}],
|
||
idleRePrompts: {enabled: true, delayMs: 5000, maxPrompts: 10, messages: ["private idle text"]}},
|
||
report: {session_id: "call_test", updated_at: "2026-10-09T13:39:40.000Z", transcript: {entries: [
|
||
{id: "before", index: 0, source: "agent", text: "private spoken answer", startedAt: "2026-10-09T13:39:09.000Z"},
|
||
{id: "after1", index: 1, source: "agent", text: "I'm still working on it.", startedAt: "2026-10-09T13:39:16.637Z"},
|
||
{id: "after2", index: 2, source: "agent", text: "I’m still working on it.", startedAt: "2026-10-09T13:39:24.420Z"},
|
||
]}}},
|
||
events: {events: [
|
||
{session_id: "call_test", event_type: "worker.duplex.started", occurred_at: "2026-10-09T13:38:13.882Z", payload: {data: {provider: "openai", model: "gpt-live-1", backendModel: "gpt-5.6-luna", sipInbound: true, toolCount: 3, token: "private-worker-token"}}},
|
||
{session_id: "call_test", event_type: "call.message_sent", status: "pending", occurred_at: acceptedAt, payload: {messageId: "msg_test", text: "private result text", mode: "respond"}},
|
||
{session_id: "call_test", event_type: "call.message_sent", status: "pending", payload: {messageId: "other_message", text: "another private result"}},
|
||
]},
|
||
};
|
||
}
|
||
describe("Speko delivery diagnostics", () => {
|
||
it("correlates message acceptance, worker configuration and idle speech without claiming playback", () => {
|
||
const f = fixture(), result = parseSpekoDeliveryDiagnostics(f.call, f.events, "call_test", deliveries);
|
||
expect(result).toMatchObject({transcriptComplete: true, agentTurnCount: 3,
|
||
runtime: {model: "gpt-live-1", backendModel: "gpt-5.6-luna", sipInbound: true, fallbackObserved: false},
|
||
configuration: {promptsMatch: true, automaticPushInstruction: true, topLevelTools: ["submit_request"], idleRepromptsEnabled: true, idleRepromptDelayMs: 5000},
|
||
messages: [{messageId: "msg_test", providerMessageEventCount: 1, providerMessageEventStatus: "pending", agentTurnsAfterAcceptance: 2, workingRepromptsAfterAcceptance: 2, playback: "unknown"}]});
|
||
const serialized = JSON.stringify(result);
|
||
for (const forbidden of ["private", "+12015551234", "other_message", "still working"]) expect(serialized).not.toContain(forbidden);
|
||
});
|
||
it("rejects cross-call substitution in call detail or events", () => {
|
||
const f = fixture();
|
||
expect(() => parseSpekoDeliveryDiagnostics({...f.call, id: "other_call"}, f.events, "call_test", deliveries)).toThrow();
|
||
expect(() => parseSpekoDeliveryDiagnostics(f.call, {events: [{session_id: "other_call", event_type: "call.message_sent"}]}, "call_test", deliveries)).toThrow();
|
||
});
|
||
it("does not infer playback or expose arbitrary status/model text from incomplete reports", () => {
|
||
const result = parseSpekoDeliveryDiagnostics({id: "call_test", status: "private status", pipeline_config: {systemPrompt: "private prompt"}},
|
||
{events: [{event_type: "worker.duplex.started", payload: {data: {model: "private model"}}}]}, "call_test", deliveries);
|
||
expect(result).toMatchObject({callStatus: null, transcriptComplete: false, runtime: {model: null},
|
||
messages: [{providerMessageEventCount: 0, agentTurnsAfterAcceptance: 0, playback: "unknown"}]});
|
||
expect(JSON.stringify(result)).not.toContain("private");
|
||
});
|
||
});
|