Files
PaperClipAI/server/src/__tests__/speko-call-report.test.ts
T
DottaandPaperclip 3ec7309d91 feat(voice): add experimental Speko task connection runtime (#15727)
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>
2026-10-09 21:54:11 -05:00

39 lines
3.5 KiB
TypeScript

import { VOICE_RESULT_NOTIFICATION, VOICE_REPEAT_NOTIFICATION } from "@paperclipai/shared";
import { describe, expect, it } from "vitest";
import { parseSpekoCallReport } from "../services/voice/speko-call-report.js";
const turn = { id: "turn", index: 0, source: "user", text: "Hello", started_at: "2026-10-07T17:00:00Z", ended_at: null };
const report = { id: "call", duration_seconds: 60, report: { session_id: "call", updated_at: "2026-10-07T17:01:00Z", cost_micro_usd: "999999999999999999999999999999", transcript: { entries: [turn] } } };
describe("Speko call report projection", () => {
it("allowlists spoken turns and exact costs without provider metadata or recordings", () => {
const result = parseSpekoCallReport({ ...report, recording_resource_uri: "private-recording", metadata: { token: "private" } }, "call");
expect(result).toMatchObject({ complete: true, costMicroUsd: report.report.cost_micro_usd, transcript: [{ speaker: "caller", text: "Hello" }] });
expect(JSON.stringify(result)).not.toContain("private");
});
it("deduplicates turns, sorts them, excludes system text, and redacts known credentials", () => {
const result = parseSpekoCallReport({ ...report, report: { ...report.report, transcript: { entries: [turn, {...turn, text: "server-key"}, {...turn, id: "hidden", source: "system", text: "private prompt"}, {...turn, id: "second", source: "agent", index: 2, latency_status: "interrupted"}] } } }, "call", ["server-key"]);
expect(result.transcript).toHaveLength(2);
expect(result.transcript[0]?.text).toBe("[REDACTED]");
expect(result.transcript[1]).toMatchObject({ speaker: "agent", interrupted: true });
});
it("excludes application control messages that the provider labels as user turns", () => {
const entries = [turn, ...[VOICE_RESULT_NOTIFICATION, VOICE_REPEAT_NOTIFICATION].map((text, index) => ({...turn, id: `control-${index}`, index: index + 1, text}))];
expect(parseSpekoCallReport({...report, report: {...report.report, transcript: {entries}}}, "call").transcript).toEqual([expect.objectContaining({text: "Hello", speaker: "caller"})]);
});
it("preserves unavailable costs and partial transcript status", () => {
expect(parseSpekoCallReport({ id: "call", transcript: {entries: [turn]} }, "call")).toMatchObject({ complete: false, costMicroUsd: null, durationSeconds: null });
});
it("projects the real finalized report's camelCase timestamps", () => {
const {started_at, ended_at, ...rest} = turn;
const result = parseSpekoCallReport({...report, report: {...report.report, transcript: {entries: [{...rest, startedAt: started_at, endedAt: ended_at}]}}}, "call");
expect(result).toMatchObject({complete: true, transcript: [{startedAt: started_at, endedAt: null}]});
expect(() => parseSpekoCallReport({...report, report: {...report.report, transcript: {entries: [rest]}}}, "call")).toThrow();
});
it("normalizes real-provider fractional durations for durable integer storage", () => {
expect(parseSpekoCallReport({...report, duration_seconds: 65.6}, "call").durationSeconds).toBe(66);
expect(() => parseSpekoCallReport({...report, duration_seconds: Infinity}, "call")).toThrow();
});
it("rejects cross-call reports and invalid cost or transcript data", () => {
for (const value of [{...report, id: "other"}, {...report, report: {...report.report, session_id: "other"}}, {...report, report: {...report.report, cost_micro_usd: "-1"}}, {...report, report: {...report.report, transcript: {entries: [{...turn, index: -1}]}}}]) expect(() => parseSpekoCallReport(value, "call")).toThrow();
});
});