mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-10-21 08:22:20 +02: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>
191 lines
6.2 KiB
TypeScript
191 lines
6.2 KiB
TypeScript
import { describe, expect, it } from "vitest";
|
|
import {
|
|
isPrivateWebhookHttpRequest,
|
|
isSecretSensitiveHttpRequest,
|
|
shouldSilenceHttpSuccessLog,
|
|
} from "../middleware/http-log-policy.js";
|
|
|
|
describe("isPrivateWebhookHttpRequest", () => {
|
|
it("protects the native webhook namespace, including rejected methods and query data", () => {
|
|
for (const provider of [
|
|
"slack",
|
|
"github",
|
|
"discord",
|
|
"telegram",
|
|
"microsoft-teams",
|
|
]) {
|
|
for (const method of ["POST", "GET", "PUT", "DELETE"]) {
|
|
for (const suffix of ["", "/", "?ignored=private"]) {
|
|
const path = `/api/chat-webhooks/endpoint-1/${provider}${suffix}`;
|
|
expect(isPrivateWebhookHttpRequest(method, path)).toBe(true);
|
|
expect(isSecretSensitiveHttpRequest(method, path)).toBe(true);
|
|
}
|
|
}
|
|
}
|
|
expect(
|
|
isPrivateWebhookHttpRequest("POST", "/API/CHAT-WEBHOOKS/id/SLACK"),
|
|
).toBe(true);
|
|
for (const path of [
|
|
"/api/voice-webhooks",
|
|
"/api/voice-webhooks/id/tools",
|
|
"http://host.invalid/api/voice-webhooks/../private-component",
|
|
"/api/routine-triggers/public",
|
|
"/api/routine-triggers/public/private-id/fire",
|
|
"https://host.invalid/api/routine-triggers/public/../private-id",
|
|
"/api/chat-webhooks",
|
|
"/api/chat-webhooks/id",
|
|
"/api/chat-webhooks/id/slack/history",
|
|
"/api/chat-webhooks//slack",
|
|
"/api/chat-webhooks/%2Fprivate/%XX",
|
|
"http://host.invalid/api/chat-webhooks/id/slack?private=true",
|
|
"http://host.invalid/api/chat-webhooks/../private-component",
|
|
"HTTPS://user:private@host.invalid/API/CHAT-WEBHOOKS/id/SLACK/",
|
|
])
|
|
expect(isPrivateWebhookHttpRequest("POST", path)).toBe(true);
|
|
});
|
|
|
|
it("does not change adjacent non-webhook routes", () => {
|
|
for (const path of [
|
|
"/api/routine-triggers/id/rotate-secret",
|
|
"/api/routine-triggers/public-extra/id/fire",
|
|
"/api/chat-webhooks-extra/id/slack",
|
|
"https://host.invalid/api/chat-webhooks-extra/id/slack",
|
|
"/api/other/chat-webhooks/id/slack",
|
|
"/api/chat-endpoints/id/test",
|
|
"/chat-webhooks/id/slack",
|
|
])
|
|
expect(isPrivateWebhookHttpRequest("POST", path)).toBe(false);
|
|
expect(
|
|
isPrivateWebhookHttpRequest(undefined, "/api/chat-webhooks/id/slack"),
|
|
).toBe(false);
|
|
expect(isPrivateWebhookHttpRequest("POST", undefined)).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("isSecretSensitiveHttpRequest", () => {
|
|
it("protects Slack registration, installation, recovery, and all callback methods", () => {
|
|
for (const suffix of ["registration", "install", "resume"]) expect(isSecretSensitiveHttpRequest("POST", `/api/chat-endpoints/id/slack/${suffix}`)).toBe(true);
|
|
for (const method of ["GET", "POST", "DELETE"]) for (const path of ["/api/chat-slack/oauth/callback?code=canary", "https://paperclip.test/API/CHAT-SLACK/OAUTH/callback?code=canary"])
|
|
expect(isSecretSensitiveHttpRequest(method, path)).toBe(true);
|
|
});
|
|
it("identifies credential-bearing chat setup mutations", () => {
|
|
expect(
|
|
isSecretSensitiveHttpRequest(
|
|
"POST",
|
|
"/api/chat-endpoints/endpoint-1/setup",
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
isSecretSensitiveHttpRequest(
|
|
"POST",
|
|
"/api/chat-endpoints/endpoint-1/setup-secret?rotation=true",
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
isSecretSensitiveHttpRequest(
|
|
"GET",
|
|
"/api/chat-endpoints/endpoint-1/setup",
|
|
),
|
|
).toBe(false);
|
|
expect(
|
|
isSecretSensitiveHttpRequest(
|
|
"POST",
|
|
"/api/chat-endpoints/endpoint-1/test",
|
|
),
|
|
).toBe(false);
|
|
});
|
|
});
|
|
|
|
describe("shouldSilenceHttpSuccessLog", () => {
|
|
it("silences cached 304 responses", () => {
|
|
expect(
|
|
shouldSilenceHttpSuccessLog("GET", "/api/issues/PAP-1383", 304),
|
|
).toBe(true);
|
|
});
|
|
|
|
it("silences successful polling endpoints", () => {
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/api/health", 200)).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/api/companies/5cbe79ee-acb3-4597-896e-7662742593cd/heartbeat-runs",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/api/heartbeat-runs/b7044268-19b6-4b3a-a9f3-9c57dce70253/log?offset=1103894&limitBytes=256000",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/api/companies/5cbe79ee-acb3-4597-896e-7662742593cd/live-runs?minCount=3",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"HEAD",
|
|
"/api/companies/5cbe79ee-acb3-4597-896e-7662742593cd/sidebar-badges",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/api/companies/5cbe79ee-acb3-4597-896e-7662742593cd/issues?includeRoutineExecutions=true",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/api/companies/5cbe79ee-acb3-4597-896e-7662742593cd/activity",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
});
|
|
|
|
it("silences successful static asset requests", () => {
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/", 200)).toBe(true);
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/index.html", 200)).toBe(true);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/@fs/Users/dotta/paperclip/ui/src/main.tsx",
|
|
200,
|
|
),
|
|
).toBe(true);
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/src/App.tsx?t=123", 200)).toBe(
|
|
true,
|
|
);
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/site.webmanifest", 200)).toBe(
|
|
true,
|
|
);
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/sw.js", 200)).toBe(true);
|
|
});
|
|
|
|
it("keeps normal successful application requests", () => {
|
|
expect(
|
|
shouldSilenceHttpSuccessLog("GET", "/api/issues/PAP-1383", 200),
|
|
).toBe(false);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog("PATCH", "/api/issues/PAP-1383", 200),
|
|
).toBe(false);
|
|
});
|
|
|
|
it("keeps failing requests visible", () => {
|
|
expect(shouldSilenceHttpSuccessLog("GET", "/api/health", 500)).toBe(false);
|
|
expect(
|
|
shouldSilenceHttpSuccessLog(
|
|
"GET",
|
|
"/@fs/Users/dotta/paperclip/ui/src/main.tsx",
|
|
404,
|
|
),
|
|
).toBe(false);
|
|
});
|
|
});
|