mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 08:22:20 +02:00
Third PR: depends on #15728 and #15727. The user has reviewed and authorized merging this experimental feature stack. ## 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 repeatable qualification for the Speko voice task integration. > - This PR depends on #15728, which depends on #15727. 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 a real Paperclip server/database E2E fixture that stubs only external Speko transport and the execution provider. - Add authenticated multi-user and cross-company qualification journeys. - Add Storybook interaction, accessibility, responsive, and visual-suite integration. - Add an E01–E16 runbook, component-to-story inventory, and current redacted qualification report. - Keep historical private call traces out of the PR. Provider proof tools are opt-in. ## Verification - All 21 standalone proof tests and browser client/server syntax checks pass. They cover signatures, redaction, cleanup retry, final audio saves, bounded report transport and late server write ordering. No live calls were placed. - All 27 focused UI/controller regressions, UI typecheck, token gates, and 28 map/catalog structural tests pass. The shared connection cache test covers pause/resume invalidation during the 30-second fresh period. - Storybook builds 157 Speko production-component stories. The complete prior 156-story set passed all 624 checks on UI source249cbc616a. After the final cache repair, all 152 affected page/launcher checks passed across both themes, 390/1200 widths and reduced motion. Real microphone access and external provider requests are blocked. - Hosted Storybook origin isolation and representative narrow-screen stories pass. Provider requests remain blocked. - Source annotations follow the current generated-catalog contract. No generated catalog or lockfile is included. Three inherited GitHub-heading tests passed after master reconciliation. - Commit905bc5da5dhas 55 passing checks, including required verify/E2E gates, and a fresh Greptile 5/5 review with zero unresolved findings. Local fixture success does not establish provider or spoken-playback acceptance. - The separate integrated browser run passed two journeys and failed browser answer retrieval. Real browser/telephone playback and timing acceptance remain outstanding. See the dated qualification report and E01–E16 runbook. Speko stays experimental. ## 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>
125 lines
6.8 KiB
JavaScript
125 lines
6.8 KiB
JavaScript
import assert from "node:assert/strict";
|
|
import { randomBytes } from "node:crypto";
|
|
import { once } from "node:events";
|
|
import test from "node:test";
|
|
import { Webhook } from "standardwebhooks";
|
|
import { BODY_LIMIT, createProof, createProofServer, TOOL_PATH, toolDefinitions, WAIT_MS } from "./proof.mjs";
|
|
|
|
const secret = () => `whsec_${randomBytes(32).toString("base64")}`;
|
|
function fixture(options = {}) {
|
|
const signingSecret = secret();
|
|
const proof = createProof({ signingSecret, ...options });
|
|
const signer = new Webhook(signingSecret);
|
|
let sequence = 0;
|
|
function request(tool, args, { session = "session_1", call = `call_${++sequence}`, timestamp = new Date(), signing = signer } = {}) {
|
|
const body = JSON.stringify({ tool, args, session_id: session, tool_call_id: call, idempotency_key: `${session}:${call}` });
|
|
const id = `${session}:${call}`;
|
|
const headers = { "webhook-id": id, "webhook-timestamp": String(Math.floor(timestamp.getTime() / 1000)), "webhook-signature": signing.sign(id, timestamp, body) };
|
|
return { body, headers, send: () => proof.handle(body, headers) };
|
|
}
|
|
return { proof, request };
|
|
}
|
|
|
|
test("requires HTTPS and keeps each fetch below the four-second provider limit", () => {
|
|
for (const origin of ["http://example.com", "https://user:secret@example.com", "https://example.com/path", "https://example.com?key=secret"]) {
|
|
assert.throws(() => toolDefinitions(origin));
|
|
}
|
|
const tools = toolDefinitions("https://example.com");
|
|
assert.equal(tools.length, 2);
|
|
assert.ok(tools.every(({ source }) => source.timeoutMs < 4000 && source.timeoutMs > WAIT_MS && !source.secret));
|
|
});
|
|
|
|
test("rejects missing, wrong, stale, future and tampered signatures", async () => {
|
|
const { proof, request } = fixture();
|
|
const valid = request("submit_request", { text: "synthetic request" });
|
|
assert.equal((await proof.handle(valid.body, {})).status, 401);
|
|
assert.equal((await proof.handle(valid.body + " ", valid.headers)).status, 401);
|
|
for (const options of [{ signing: new Webhook(secret()) }, { timestamp: new Date(Date.now() - 360_000) }, { timestamp: new Date(Date.now() + 360_000) }]) {
|
|
assert.equal((await request("submit_request", { text: "test" }, options).send()).status, 401);
|
|
}
|
|
assert.equal(proof.evidence().acceptedRequests, 0);
|
|
});
|
|
|
|
test("deduplicates concurrent retries and rejects changed arguments and session substitution", async () => {
|
|
const { proof, request } = fixture();
|
|
const original = request("submit_request", { text: "private phrase" }, { call: "same" });
|
|
const responses = await Promise.all([original.send(), original.send(), original.send()]);
|
|
assert.ok(responses.every((response) => response.body.requestCount === 1));
|
|
assert.equal((await request("submit_request", { text: "changed" }, { call: "same" }).send()).status, 409);
|
|
assert.equal((await request("submit_request", { text: "test" }, { session: "other" }).send()).status, 403);
|
|
assert.equal(proof.evidence().acceptedRequests, 1);
|
|
assert.ok(!JSON.stringify(proof.evidence()).includes("private phrase"));
|
|
});
|
|
|
|
test("waits 60 seconds, admits follow-ups to one job and distinguishes result retrieval from speech", async () => {
|
|
let clock = 0;
|
|
const waits = [];
|
|
const { proof, request } = fixture({ now: () => clock, wait: async (duration) => { waits.push(duration); clock += duration; } });
|
|
assert.equal((await request("get_updates", { cursor: 0 }).send()).status, 409);
|
|
assert.equal((await request("submit_request", { text: "start" }).send()).body.status, "pending");
|
|
assert.equal((await request("get_updates", { cursor: 1 }).send()).status, 400);
|
|
let response;
|
|
for (let i = 0; i < 24; i++) {
|
|
if (i === 6) assert.equal((await request("submit_request", { text: "followup" }).send()).body.requestCount, 2);
|
|
response = await request("get_updates", { cursor: 0 }).send();
|
|
if (i < 23) assert.equal(response.body.status, "pending");
|
|
}
|
|
assert.equal(clock, 60_000);
|
|
assert.ok(waits.every((duration) => duration <= 2500));
|
|
assert.equal(response.body.status, "completed");
|
|
assert.match(response.body.updates[0].text, /Verification number \d{4}\. Follow-up count 1/);
|
|
assert.deepEqual((await request("get_updates", { cursor: 1 }).send()).body.updates, []);
|
|
assert.equal(proof.evidence().liveQualification, "not_established");
|
|
assert.equal(proof.evidence().resultReturned, true);
|
|
});
|
|
|
|
test("close during a bounded wait prevents further result delivery", async () => {
|
|
let release;
|
|
const { proof, request } = fixture({ wait: () => new Promise((resolve) => { release = resolve; }) });
|
|
await request("submit_request", { text: "start" }).send();
|
|
const polling = request("get_updates", { cursor: 0 }).send();
|
|
await Promise.resolve();
|
|
proof.close();
|
|
release();
|
|
assert.equal((await polling).status, 410);
|
|
assert.equal((await request("submit_request", { text: "late" }).send()).status, 410);
|
|
});
|
|
|
|
test("expires the single-run receiver and caps authenticated deliveries", async () => {
|
|
let clock = 0;
|
|
const { proof, request } = fixture({ now: () => clock });
|
|
for (let i = 0; i < 500; i++) {
|
|
assert.equal((await request("submit_request", { text: "synthetic" }).send()).status, 200);
|
|
}
|
|
assert.equal((await request("submit_request", { text: "over limit" }).send()).status, 429);
|
|
clock = 15 * 60_000;
|
|
assert.equal((await request("submit_request", { text: "expired" }).send()).status, 410);
|
|
assert.equal(proof.evidence().acceptedRequests, 500);
|
|
});
|
|
|
|
test("rejects invalid args and bodies before accepting work", async () => {
|
|
const { proof, request } = fixture();
|
|
for (const [tool, args] of [["unknown", {}], ["submit_request", { text: "" }], ["submit_request", { text: "ok", authority: "admin" }], ["get_updates", { cursor: -1 }], ["get_updates", { cursor: 0.5 }]]) {
|
|
assert.equal((await request(tool, args).send()).status, 400);
|
|
}
|
|
assert.equal((await proof.handle("x".repeat(BODY_LIMIT + 1), {})).status, 413);
|
|
assert.equal(proof.evidence().acceptedRequests, 0);
|
|
});
|
|
|
|
test("HTTP surface only accepts JSON on the signed tool route", async (t) => {
|
|
const { proof, request } = fixture();
|
|
const server = createProofServer(proof);
|
|
t.after(() => { server.closeAllConnections(); server.close(); });
|
|
server.listen(0, "127.0.0.1");
|
|
await once(server, "listening");
|
|
const base = `http://127.0.0.1:${server.address().port}`;
|
|
assert.equal((await fetch(`${base}/health`)).status, 200);
|
|
assert.equal((await fetch(`${base}/api/companies`)).status, 404);
|
|
assert.equal((await fetch(`${base}${TOOL_PATH}`, { method: "POST", body: "{}" })).status, 415);
|
|
const signed = request("submit_request", { text: "start" });
|
|
const response = await fetch(`${base}${TOOL_PATH}`, { method: "POST", headers: { ...signed.headers, "content-type": "application/json" }, body: signed.body });
|
|
assert.equal(response.status, 200);
|
|
assert.equal(response.headers.get("cache-control"), "no-store");
|
|
assert.equal((await response.json()).requestCount, 1);
|
|
});
|