@belonguniverseai/react-sdk 0.1.8 → 0.2.0

package/dist/embed/voice-call.d.ts

@@ -0,0 +1,210 @@
+import { AgentLineStatus } from './voice-call-lines.ts';
+export type CallStatus = "idle" | "connecting" | "in_call" | "error";
+/**
+ * One row of the call's execution timeline (the CallScreen activity card):
+ * what the user said, what the voice agent said, each step the Belong agent
+ * took, and the success/completion marker. `atMs` is wall-clock; the screen
+ * renders it relative to `callStartedAtMs` (00:02-style).
+ */
+export type CallTimelineEntry = {
+    readonly id: number;
+    readonly atMs: number;
+    readonly kind: "user" | "agent" | "step" | "success" | "error" | "skill" | "schedule";
+    readonly text: string;
+    /** Agent tag for Operator-mode rows (e.g. "A2"); absent for foreground rows. */
+    readonly lineTag?: string;
+};
+export type CallState = {
+    readonly status: CallStatus;
+    readonly muted: boolean;
+    /** Screen dismissed while the call keeps running (audio + timeline live on;
+     * the rail button restores the view). Header ✕ minimizes — it must NOT
+     * hang up: ✕ means "dismiss this view" everywhere else in the dock. */
+    readonly minimized: boolean;
+    /** Live caption of what the USER last said (server-side transcription). */
+    readonly userCaption: string;
+    /** Live caption of what the model is SAYING (output transcript deltas). */
+    readonly assistantCaption: string;
+    /** True from a send_to_belong_agent dispatch until its reply is delivered. */
+    readonly agentBusy: boolean;
+    /** Current tool phase of the delegated run (drives the orb's work badge). */
+    readonly workPhase: "coding" | "files" | "actions" | null;
+    /** True while the voice model is producing a spoken response. */
+    readonly speaking: boolean;
+    /** True between the user finishing an utterance and the model responding —
+     * the "Thinking…" window on the call screen. */
+    readonly thinking: boolean;
+    /** Wall-clock start of the current call; 0 while idle. */
+    readonly callStartedAtMs: number;
+    /** Rolling execution timeline, oldest first (capped). */
+    readonly timeline: readonly CallTimelineEntry[];
+    readonly errorMessage?: string;
+};
+/**
+ * ChatRoute pushes Belong-agent progress into the call timeline (tool-phase
+ * steps while a delegated run streams). No-op when no call is active.
+ */
+export declare const pushCallStep: (text: string) => void;
+/** ChatRoute surfaces call-relevant notices (skill lookup misses, catalog
+ * failures) on the timeline so the user can SEE why nothing ran. */
+export declare const pushCallNotice: (kind: "step" | "error", text: string) => void;
+/** Hard ceiling on the rendered digest — a compact recap, not a transcript. */
+export declare const CONTEXT_DIGEST_MAX_CHARS = 1000;
+/**
+ * Pure core: render the most recent `user`/`agent` timeline entries (up to
+ * {@link CONTEXT_DIGEST_MAX_ENTRIES}) as `User: …` / `Agent: …` lines, oldest
+ * first, capped at {@link CONTEXT_DIGEST_MAX_CHARS}. Each entry's text is
+ * already capped by `appendTimeline` (`TIMELINE_TEXT_MAX_CHARS`), so this only
+ * caps the JOINED digest. Returns `""` when there are no such entries.
+ * Exported standalone (no store dependency) so it gets a direct unit test —
+ * `buildCallContextDigest` below is the store's zero-arg wrapper over it.
+ */
+export declare const buildContextDigestFromEntries: (entries: readonly CallTimelineEntry[]) => string;
+/** Store wrapper: the call's own timeline, digested. line-dispatch.ts calls
+ * this for every background-line dispatch. */
+export declare const buildCallContextDigest: () => string;
+export declare const peekCallState: () => CallState;
+export declare const subscribeCallState: (listener: () => void) => (() => void);
+/**
+ * ChatRoute subscribes here: each fired request travels the normal message
+ * pipeline (the same path a typed turn takes), keeping runs durable and
+ * on-ledger. The unsubscribe teardown mirrors `subscribeTranscript`.
+ */
+export declare const subscribeCallDelegate: (listener: (requestText: string) => void) => (() => void);
+/**
+ * Voice approvals: the realtime model's `resolve_approval` tool fans out
+ * here; ChatRoute resolves the pending approval card through the SAME
+ * server-authoritative path the on-screen buttons use (§28 — the backend
+ * still validates its own preconditions).
+ */
+export declare const subscribeCallApprovalDecision: (listener: (decision: "approved" | "rejected") => void) => (() => void);
+export type CallSkillInvokeResult = {
+    readonly status: "dispatched";
+    readonly skill: string;
+    readonly text: string;
+} | {
+    readonly status: "candidates";
+    readonly candidates: readonly {
+        readonly name: string;
+        readonly description: string;
+    }[];
+}
+/** The catalog loaded fine and is genuinely empty — a valid tenant state,
+ * NOT a failure ("no skills configured" ≠ "couldn't load"). */
+ | {
+    readonly status: "empty";
+} | {
+    readonly status: "unavailable";
+};
+export declare const registerCallSkillResolver: (resolver: (req: {
+    readonly query: string;
+    readonly args: string;
+}) => CallSkillInvokeResult) => (() => void);
+export declare const registerCallScheduleDispatcher: (dispatcher: (req: {
+    readonly time: string;
+    readonly task: string;
+}) => void) => (() => void);
+declare let lineDispatcher: ((req: {
+    readonly line: number;
+    readonly request: string;
+    readonly label: string;
+    readonly isNewLine: boolean;
+}) => void) | null;
+export declare const registerCallLineDispatcher: (dispatcher: NonNullable<typeof lineDispatcher>) => (() => void);
+export declare const registerCallLineViewSwitcher: (switcher: (sessionId: string) => void) => (() => void);
+/**
+ * ChatRoute calls this when a tool-approval card appears while a call is
+ * live: the ask lands on the timeline and the voice model asks the user to
+ * approve or reject out loud.
+ */
+export declare const notifyCallApprovalRequired: (timelineText: string) => void;
+/** Live speech level, 0..1 (max of agent voice + user mic). */
+export declare const peekCallAudioLevel: () => number;
+/** ChatRoute reports a tool-phase change on the delegated run — the strongest
+ * progress signal, spoken (rate-limited) and already on the timeline. */
+export declare const notifyCallProgress: (hint: string) => void;
+/** ChatRoute mirrors the run's current tool phase — the orb wears it as a
+ * small work badge while the agent is busy. */
+export declare const setCallWorkPhase: (phase: CallState["workPhase"]) => void;
+/**
+ * Click-path twin of `show_agent_line`: the lines strip chip on CallScreen
+ * calls this directly (no tool-call round trip, no ack). No-op when the line
+ * is unknown, never bound to a session, or no view switcher is registered
+ * (e.g. ChatRoute hasn't mounted).
+ */
+export declare const showLineOnScreen: (line: number) => void;
+export declare const startCall: () => Promise<void>;
+export declare const endCall: () => void;
+export declare const toggleCallMuted: () => void;
+/** Dismiss a sticky error state (the overlay's ✕). */
+export declare const dismissCallError: () => void;
+/** Hide the call screen without ending the call (header ✕ / Escape). */
+export declare const minimizeCallScreen: () => void;
+/** Bring a minimized call screen back (the rail's in-call button). */
+export declare const restoreCallScreen: () => void;
+/**
+ * ChatRoute calls this when the delegated run finishes: the assistant's final
+ * text rides into the call as a system message and the model narrates it.
+ * No-op when the call has ended meanwhile — the reply is still on screen.
+ */
+export declare const deliverAgentReply: (text: string) => void;
+/**
+ * ChatRoute calls this when the delegated run FAILS (stream error, run_error).
+ * Without it the call stays silently "Working…" forever — the voice agent
+ * must tell the user something went wrong and offer to retry.
+ */
+export declare const deliverAgentFailure: (message: string) => void;
+/** A background line finished: relay its final text, naming the line. */
+export declare const deliverLineReply: (line: number, text: string) => void;
+/**
+ * A background line published an artifact: OPEN it on screen, mirroring
+ * chat.tsx's foreground auto-open effect exactly — ALWAYS docked (a persisted
+ * fullscreen pref would swallow the whole app), the same closable/resizable
+ * panel a click on the artifact card gives. Deduped per artifactId (replays /
+ * reconnects re-emit the part). NO spoken response: the line's finish reply
+ * already narrates the result; a second voice line would double-speak.
+ */
+export declare const deliverLineArtifact: (line: number, artifact: {
+    readonly artifactId: string;
+    readonly title: string;
+    readonly mimeType: string;
+}) => void;
+/** A background line failed: tell the user, naming the agent. */
+export declare const deliverLineFailure: (line: number, message: string) => void;
+/** A background line is blocked on a tool approval — steer the user to it. */
+export declare const notifyLineApprovalNeeded: (line: number, timelineText: string) => void;
+/** A background line advanced a phase — land a tagged row + a spoken nudge.
+ * Guarded like its delivery siblings: a stale phase from an ended call (there
+ * is no registry write here) must not touch a new call's timeline. */
+export declare const notifyLinePhase: (line: number, phaseLabel: string) => void;
+/** True while a call holds the audio path — ChatRoute gates TTS autoplay on it. */
+export declare const isCallActive: () => boolean;
+/**
+ * TEST-ONLY (window.belong.__forceCallState): force the call store into a
+ * given visual state WITHOUT any WebRTC/mic — drives the CallScreen + rail
+ * animations in E2E and sandboxed browsers where getUserMedia is unavailable.
+ * Never touches the transport; ending the forced state is `endCall()`.
+ */
+export declare const __forceCallState: (patch: Partial<CallState>) => void;
+/** TEST-ONLY companion: append a timeline row while in a forced state. */
+export declare const __forceCallTimelineEntry: (kind: CallTimelineEntry["kind"], text: string, lineTag?: string) => void;
+/** TEST-ONLY companion: drive the orb's audio level without Web Audio. */
+export declare const __forceCallAudioLevel: (level: number) => void;
+/**
+ * TEST-ONLY (window.belong.__forceAgentLines): force the agent-lines
+ * switchboard into a given state WITHOUT any HTTP dispatch — drives the
+ * CallScreen lines strip in E2E and sandboxed browsers. Resets the registry,
+ * then replays the same store calls a live Operator run makes: `openAgentLine`
+ * to create each background line (sequential, mirroring real dispatch),
+ * `bindLineSession` + `setLineStatus` to fill it in. Line 1 is the existing
+ * foreground line and is updated in place rather than opened. Entries are
+ * replayed in ascending `line` order regardless of input order, so lines 2/3
+ * always land on their expected slots.
+ */
+export declare const __forceAgentLines: (forced: readonly {
+    line: number;
+    label: string;
+    status: AgentLineStatus;
+    sessionId?: string;
+}[]) => void;
+export {};

package/dist/i18n/messages/en.d.ts

@@ -419,6 +419,70 @@ export declare const en: {
         readonly stopSpeaking: "Stop speaking";
         readonly micError: "Microphone error";
     };
+    readonly callOverlay: {
+        readonly connecting: "Calling…";
+        readonly live: "Live call";
+        readonly agentWorking: "Belong agent is working…";
+        readonly mute: "Mute microphone";
+        readonly unmute: "Unmute microphone";
+        readonly endCall: "End call";
+        readonly dismiss: "Dismiss";
+        readonly startCall: "Start voice call";
+    };
+    readonly callScreen: {
+        readonly title: "Voice call";
+        readonly connecting: "Connecting the call…";
+        readonly listening: "Listening";
+        readonly speaking: "Speaking";
+        readonly working: "Working on it…";
+        readonly muted: "Mic muted";
+        readonly youSaid: "You said";
+        readonly agentSaid: "Agent";
+        readonly step: "Working";
+        readonly done: "Done";
+        readonly failed: "Failed";
+        readonly speakHint: "Speak to the agent…";
+        readonly readyHint: "I'm listening — speak when you're ready.";
+        readonly thinkingHint: "Thinking…";
+        readonly speakingHint: "Speaking…";
+        readonly workingWithBelong: "Working with the Belong agent…";
+        readonly close: "Hide call view";
+        readonly returnToCall: "Return to call";
+        readonly retry: "Call again";
+        readonly viewChat: "View chat";
+        readonly approvalNeeded: "Approval needed — say approve or reject";
+        readonly approvedByVoice: "Approved by voice";
+        readonly rejectedByVoice: "Rejected by voice";
+        readonly openedArtifact: "Opened {{title}} on screen";
+        readonly skill: "Skill";
+        readonly schedule: "Scheduled";
+        readonly skillNotFound: "No exact skill match for “{{query}}”";
+        readonly skillCatalogUnavailable: "Skill catalog unavailable — retrying";
+        readonly noSkillsConfigured: "No skills configured in this workspace";
+        readonly phaseCoding: "Writing code";
+        readonly phaseFiles: "Working with files";
+        readonly phaseActions: "Taking actions";
+        readonly lines: "Agents";
+        readonly lineLabel: "Agent {{line}}";
+        readonly mainAgentLabel: "Main agent";
+        readonly lineNeedsApproval: "needs approval";
+        readonly lineWorking: "working";
+        readonly lineReady: "ready";
+        readonly lineFailed: "failed";
+        readonly ambientTypingCode: "Typing code…";
+        readonly ambientReviewingDiff: "Reviewing the diff…";
+        readonly ambientRunningChecks: "Running checks…";
+        readonly ambientSearchingFiles: "Searching files…";
+        readonly ambientReadingDocuments: "Reading documents…";
+        readonly ambientOrganizingResults: "Organizing results…";
+        readonly ambientClickingThrough: "Clicking through…";
+        readonly ambientFillingDetails: "Filling in details…";
+        readonly ambientCheckingResult: "Checking the result…";
+        readonly ambientThinkingItThrough: "Thinking it through…";
+        readonly ambientSearching: "Searching…";
+        readonly ambientTyping: "Typing…";
+        readonly ambientDoubleChecking: "Double-checking…";
+    };
     readonly chat: {
         readonly queued: "Queued";
         readonly notDelivered: "Not delivered — please resend";

package/dist/types/public.d.ts

@@ -234,6 +234,29 @@ export type BelongGlobal = {
     readonly registerUiAction: <I, O>(name: string, handler: UiActionHandler<I, O>) => void;
     /** TEST-ONLY: inject a final voice transcript as if spoken. */
     readonly __pushVoiceTranscript?: (text: string) => void;
+    /** TEST-ONLY: force the live-call visual state (no WebRTC/mic involved). */
+    readonly __forceCallState?: (patch: {
+        status?: "idle" | "connecting" | "in_call" | "error";
+        muted?: boolean;
+        userCaption?: string;
+        assistantCaption?: string;
+        agentBusy?: boolean;
+        workPhase?: "coding" | "files" | "actions" | null;
+        speaking?: boolean;
+        thinking?: boolean;
+        errorMessage?: string;
+    }) => void;
+    /** TEST-ONLY: append a live-call timeline row. */
+    readonly __forceCallTimelineEntry?: (kind: "user" | "agent" | "step" | "success" | "error" | "skill" | "schedule", text: string, lineTag?: string) => void;
+    /** TEST-ONLY: drive the call orb's audio level (0..1) without Web Audio. */
+    readonly __forceCallAudioLevel?: (level: number) => void;
+    /** TEST-ONLY: force the agent-lines switchboard state without HTTP dispatch. */
+    readonly __forceAgentLines?: (lines: readonly {
+        line: number;
+        label: string;
+        status: "working" | "ready" | "failed" | "needs_approval";
+        sessionId?: string;
+    }[]) => void;
 };
 declare global {
     var belong: BelongGlobal | undefined;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@belonguniverseai/react-sdk",
-  "version": "0.1.8",
+  "version": "0.2.0",
   "description": "Belong — embeddable React AI assistant dock. Mount <BelongWidget> in your app tree with getToken dependency-injection auth.",
   "license": "UNLICENSED",
   "type": "module",