mirror of
https://github.com/paperclipai/paperclip.git
synced 2026-11-06 23:20:53 +01:00
Runtime #15727 is merged. This PR adds the UI. Qualification follows in
#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 the Speko setup and call controls to the existing Apps
and task UI.
> - This PR depends on #15727. The qualification suite follows
separately. 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 the Speko Apps catalog entry, provider artwork, and browser SDK.
- Reuse existing agents in setup. Keep the optional Company Phone Agent
in the catalog, with connection instructions available to any assigned
agent.
- Add task voice controls, transcripts, phone callbacks, inbound-line
settings, and call Activity entries.
- Surface retryable connection and incoming-task inventory failures,
preserve active call controls and cached tasks, restore keyboard focus
after recovery, and bound notification polling so a stuck request cannot
hide later results.
- Put Save & exit and Connect Speko in the credential step’s shared
footer.
- Add deterministic production-component Storybook fixtures for setup,
lifecycle, failures, permissions, and phone surfaces.
- Include voice components in the design guide. Stories never request a
real microphone or place calls.
## Verification
- 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 source 249cbc616a. 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.
- Source annotations follow the current generated-catalog contract. No
generated catalog or lockfile is included. Three inherited
GitHub-heading tests passed after master reconciliation.
- Latest-head CI and Greptile review must pass before merge. 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>
65 lines
3.8 KiB
TypeScript
65 lines
3.8 KiB
TypeScript
import { Mic, MicOff, Phone, PhoneOff, RotateCcw, Volume2 } from "lucide-react";
|
|
import { useEffect, useRef } from "react";
|
|
import { Button } from "@/components/ui/button";
|
|
import { cn } from "@/lib/utils";
|
|
|
|
export const VOICE_CONTROL_STATES = ["idle", "connecting", "listening", "speaking", "working", "interrupted", "reconnecting", "ending", "ended", "failed", "cleanup_failed"] as const;
|
|
export type VoiceControlState = typeof VOICE_CONTROL_STATES[number];
|
|
const labels: Record<VoiceControlState, string> = {
|
|
idle: "Ready to talk", connecting: "Connecting…", listening: "Listening", speaking: "Speaking",
|
|
working: "Working on your task", interrupted: "Listening to your follow-up", reconnecting: "Reconnecting…",
|
|
ending: "Ending call…", ended: "Call ended", failed: "Voice connection unavailable", cleanup_failed: "Call closure unconfirmed",
|
|
};
|
|
export interface VoiceControlsProps {
|
|
state: VoiceControlState;
|
|
agentName: string;
|
|
muted?: boolean;
|
|
busy?: boolean;
|
|
playbackBlocked?: boolean;
|
|
canRepeat?: boolean;
|
|
onRepeat?: () => void;
|
|
error?: string;
|
|
announcement?: string;
|
|
onStart: () => void;
|
|
onMute: () => void;
|
|
onEnd: () => void;
|
|
onResumeAudio: () => void;
|
|
className?: string;
|
|
}
|
|
export function VoiceControls({ state, agentName, muted = false, busy = false, playbackBlocked = false, canRepeat = false, onRepeat, error, announcement, onStart, onMute, onEnd, onResumeAudio, className }: VoiceControlsProps) {
|
|
const inactive = state === "idle" || state === "ended" || state === "failed";
|
|
const connecting = state === "connecting" || state === "reconnecting";
|
|
const startButton = useRef<HTMLButtonElement>(null);
|
|
const restoreFocus = useRef(false);
|
|
useEffect(() => {
|
|
if (!inactive || !restoreFocus.current) return;
|
|
restoreFocus.current = false;
|
|
if (document.activeElement === document.body) startButton.current?.focus();
|
|
}, [inactive]);
|
|
return (
|
|
<section aria-label={`Voice conversation with ${agentName}`} className={cn("flex min-w-0 flex-col gap-3", className)}>
|
|
<div className="flex min-w-0 flex-col gap-1">
|
|
<h3 className="break-words text-sm font-medium">Talk to {agentName}</h3>
|
|
<p role="status" className="text-sm text-muted-foreground">{labels[state]}{muted && !inactive ? " · Microphone muted" : ""}</p>
|
|
</div>
|
|
{error && <p role="alert" className="text-sm text-destructive">{error}</p>}
|
|
<div className="flex flex-wrap gap-2">
|
|
{inactive ? (
|
|
<Button ref={startButton} size="sm" disabled={busy} onClick={onStart}><Phone aria-hidden="true" />{state === "failed" ? "Try again" : "Start voice"}</Button>
|
|
) : (
|
|
<>
|
|
<Button size="sm" variant="outline" aria-pressed={muted} disabled={busy || connecting || state === "ending" || state === "cleanup_failed"} onClick={onMute}>
|
|
{muted ? <MicOff aria-hidden="true" /> : <Mic aria-hidden="true" />}{muted ? "Unmute" : "Mute"}
|
|
</Button>
|
|
<Button size="sm" variant="outline" disabled={state === "ending"} onClick={() => { restoreFocus.current = true; onEnd(); }}><PhoneOff aria-hidden="true" />{state === "cleanup_failed" ? "Retry ending call" : "End call"}</Button>
|
|
</>
|
|
)}
|
|
{canRepeat && onRepeat && !inactive && <Button size="sm" variant="outline" disabled={busy || connecting || state === "ending" || state === "cleanup_failed"} onClick={onRepeat}><RotateCcw aria-hidden="true" />Repeat answer</Button>}
|
|
{playbackBlocked && !inactive && <Button size="sm" variant="outline" onClick={onResumeAudio}><Volume2 aria-hidden="true" />Enable audio</Button>}
|
|
</div>
|
|
{!inactive && <p className="text-xs text-muted-foreground">Ending the call keeps your task running. Speko voice charges are separate from agent costs.</p>}
|
|
<span className="sr-only" aria-live="polite" aria-atomic="true">{announcement}</span>
|
|
</section>
|
|
);
|
|
}
|