@voxagent/bridge 0.1.0

package/dist/permissions.js

@@ -0,0 +1,221 @@
+/**
+ * @file In-meeting permission broker.
+ *
+ * The Claude driver hands off to this broker via a callback whenever a tool
+ * call needs human approval. The broker:
+ *   1. Picks an auto-decision when the workspace policy can answer locally
+ *      (reads = allow, writes/edits inside cwd = allow, etc.).
+ *   2. Otherwise emits a `agent.permission_request` event into the room and
+ *      blocks until the corresponding `permission.response` arrives — or
+ *      until the request times out / the run is aborted.
+ *
+ * The broker has no LiveKit awareness; it takes a pair of callbacks (publish,
+ * resolve) so it can be unit-tested in isolation and the room runtime owns
+ * the actual data-channel plumbing.
+ */
+import { randomUUID } from 'node:crypto';
+import { sep } from 'node:path';
+import { log } from './logging.js';
+const READ_ONLY_TOOLS = new Set(['Read', 'Glob', 'Grep', 'WebFetch', 'WebSearch']);
+const SAFE_RECURSIVE_TOOLS = new Set(['Task']);
+const FILE_WRITE_TOOLS = new Set(['Edit', 'MultiEdit', 'Write', 'NotebookEdit']);
+const DEFAULT_TIMEOUT_MS = 90_000;
+export class PermissionBroker {
+    policy;
+    pending = new Map();
+    timeoutMs;
+    publisher = null;
+    queuedRequests = [];
+    constructor(policy, deps = {}) {
+        this.policy = policy;
+        this.timeoutMs = deps.timeoutMs ?? DEFAULT_TIMEOUT_MS;
+    }
+    /**
+     * Wires the broker to a transport. Called by the room runtime once it has
+     * a connected LiveKit data channel. Any requests that arrived earlier are
+     * flushed in order.
+     */
+    attachPublisher(publish) {
+        this.publisher = publish;
+        const queued = this.queuedRequests;
+        this.queuedRequests = [];
+        for (const event of queued) {
+            try {
+                publish(event);
+            }
+            catch (error) {
+                log.warn('permission_publish_flush_failed', {
+                    requestId: event.requestId,
+                    message: error instanceof Error ? error.message : String(error),
+                });
+            }
+        }
+    }
+    detachPublisher() {
+        this.publisher = null;
+    }
+    /**
+     * Decides whether a tool call can proceed. Synchronously resolves for
+     * trivially-safe tools; otherwise asks the room and awaits a response.
+     */
+    async decide(args) {
+        if (this.policy.fullAccess) {
+            return { decision: 'allow' };
+        }
+        if (READ_ONLY_TOOLS.has(args.toolName) || SAFE_RECURSIVE_TOOLS.has(args.toolName)) {
+            return { decision: 'allow' };
+        }
+        const inWorkspace = this.fileToolStaysInWorkspace(args.toolName, args.toolInput);
+        if (inWorkspace === true)
+            return { decision: 'allow' };
+        const requestId = randomUUID();
+        const summary = summarizeToolCall(args.toolName, args.toolInput);
+        const reason = summarizeReason(args.toolName, args.toolInput, inWorkspace, this.policy.workspaceCwd);
+        const riskLevel = computeRisk(args.toolName, args.toolInput);
+        const event = {
+            type: 'agent.permission_request',
+            requestId,
+            runId: args.runId,
+            toolName: args.toolName,
+            toolInput: args.toolInput,
+            summary,
+            reason,
+            riskLevel,
+        };
+        log.info('permission_request_dispatched', {
+            requestId,
+            toolName: args.toolName,
+            summary,
+            riskLevel,
+        });
+        return new Promise((resolve) => {
+            const timer = setTimeout(() => {
+                if (!this.pending.has(requestId))
+                    return;
+                this.pending.delete(requestId);
+                log.warn('permission_request_timeout', { requestId, toolName: args.toolName });
+                resolve({
+                    decision: 'deny',
+                    message: 'Permission request timed out without a response from the room.',
+                });
+            }, this.timeoutMs);
+            this.pending.set(requestId, {
+                resolve: (decision) => {
+                    resolve({
+                        decision,
+                        ...(decision === 'deny' ? { message: 'Denied by host.' } : {}),
+                    });
+                },
+                timer,
+            });
+            if (this.publisher) {
+                try {
+                    this.publisher(event);
+                }
+                catch (publishError) {
+                    clearTimeout(timer);
+                    this.pending.delete(requestId);
+                    log.error('permission_publish_failed', {
+                        requestId,
+                        message: publishError instanceof Error ? publishError.message : String(publishError),
+                    });
+                    resolve({
+                        decision: 'deny',
+                        message: 'Could not deliver permission request to the room.',
+                    });
+                }
+            }
+            else {
+                // No transport yet — buffer until attachPublisher() flushes us.
+                this.queuedRequests.push(event);
+            }
+        });
+    }
+    /** Called by the room runtime when a `permission.response` event arrives. */
+    resolve(requestId, decision) {
+        const entry = this.pending.get(requestId);
+        if (!entry)
+            return false;
+        this.pending.delete(requestId);
+        clearTimeout(entry.timer);
+        entry.resolve(decision);
+        return true;
+    }
+    /** Cancel every outstanding request (e.g. on shutdown / run abort). */
+    cancelAll(reason = 'deny') {
+        for (const [, entry] of this.pending) {
+            clearTimeout(entry.timer);
+            entry.resolve(reason);
+        }
+        this.pending.clear();
+    }
+    /**
+     * Returns `true` when the file path is safely inside the workspace, `false`
+     * when it points outside, and `null` when the tool isn't a file-write tool
+     * (caller falls through to the room).
+     */
+    fileToolStaysInWorkspace(toolName, toolInput) {
+        if (!FILE_WRITE_TOOLS.has(toolName))
+            return null;
+        const filePath = extractFilePath(toolInput);
+        if (!filePath)
+            return false;
+        return isPathInsideWorkspace(filePath, this.policy.workspaceCwd);
+    }
+}
+function extractFilePath(input) {
+    if (!input || typeof input !== 'object')
+        return null;
+    const obj = input;
+    const candidate = obj.file_path ?? obj.path ?? obj.notebook_path;
+    return typeof candidate === 'string' && candidate.length > 0 ? candidate : null;
+}
+function isPathInsideWorkspace(filePath, workspaceCwd) {
+    const cwdNorm = workspaceCwd.replace(/[/\\]+$/, '') + sep;
+    const fileNorm = filePath.endsWith(sep) ? filePath : filePath + (filePath.includes(sep) ? '' : sep);
+    if (filePath === workspaceCwd)
+        return true;
+    return filePath.startsWith(cwdNorm) || fileNorm.startsWith(cwdNorm);
+}
+function summarizeToolCall(toolName, toolInput) {
+    if (!toolInput || typeof toolInput !== 'object')
+        return toolName;
+    const obj = toolInput;
+    if (toolName === 'Bash' && typeof obj.command === 'string') {
+        const cmd = obj.command.trim();
+        return `Bash: ${cmd.length > 120 ? `${cmd.slice(0, 117)}…` : cmd}`;
+    }
+    const path = extractFilePath(toolInput);
+    if (path)
+        return `${toolName}: ${path}`;
+    return toolName;
+}
+function summarizeReason(toolName, toolInput, workspaceFlag, workspaceCwd) {
+    if (toolName === 'Bash') {
+        const cmd = typeof toolInput?.command === 'string'
+            ? toolInput.command
+            : '';
+        if (/\b(rm|sudo|chmod|chown|mv\s+\/|curl\s+.*\|\s*sh|wget\s+.*\|\s*sh)\b/.test(cmd)) {
+            return 'Shell command flagged as potentially destructive.';
+        }
+        return 'Shell commands always require approval outside full-access mode.';
+    }
+    if (workspaceFlag === false) {
+        return `Path is outside the workspace (${workspaceCwd}).`;
+    }
+    return 'Tool not on the auto-approve list — approval required.';
+}
+function computeRisk(toolName, toolInput) {
+    if (toolName === 'Bash') {
+        const cmd = typeof toolInput?.command === 'string'
+            ? toolInput.command
+            : '';
+        if (/\b(rm\s+-rf|sudo|curl\s+.*\|\s*sh|wget\s+.*\|\s*sh)\b/.test(cmd))
+            return 'high';
+        return 'medium';
+    }
+    if (FILE_WRITE_TOOLS.has(toolName))
+        return 'medium';
+    return 'low';
+}
+//# sourceMappingURL=permissions.js.map

package/dist/permissions.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"permissions.js","sourceRoot":"","sources":["../src/permissions.ts"],"names":[],"mappings":"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"}

package/dist/protocol.d.ts

@@ -0,0 +1,181 @@
+/**
+ * @file Wire protocol shared between the bridge process and the web client.
+ *
+ * Both packages import these types so adding/changing an event type fails the
+ * type checker on both ends. Runtime exports are intentionally minimal — the
+ * web side only uses the type aliases.
+ */
+export declare const PROTOCOL_VERSION: 1;
+/**
+ * LiveKit data channel topic used for all bridge ↔ room control messages.
+ *
+ * Keeps event traffic isolated from any other future data-channel usage.
+ */
+export declare const BRIDGE_TOPIC: "voxagent.bridge";
+/**
+ * Identity prefix reserved for the bridge participant.
+ *
+ * The web token route refuses to mint identities matching this prefix to
+ * prevent browser participants from impersonating the agent.
+ */
+export declare const AGENT_IDENTITY_PREFIX: "agent:";
+/**
+ * Builds the canonical agent identity for one room.
+ *
+ * @param roomId - Room identifier the bridge will pair with.
+ * @returns LiveKit participant identity string.
+ */
+export declare function buildAgentIdentity(roomId: string): string;
+/**
+ * Returns true when an identity string matches the reserved agent prefix.
+ */
+export declare function isAgentIdentity(identity: string): boolean;
+export type AgentBackend = 'claude' | 'codex';
+export interface CapabilitiesInfo {
+    backend: AgentBackend;
+    /** Skill names discovered on the host. */
+    skills: string[];
+    /** Plugin names discovered on the host. */
+    plugins: string[];
+    /** MCP server identifiers (configured names) discovered on the host. */
+    mcpServers: string[];
+    /** Working directory the bridge will run the agent in. */
+    cwd: string;
+    /** Bridge package version. */
+    bridgeVersion: string;
+}
+export interface BridgeHelloEvent {
+    type: 'bridge.hello';
+    protocolVersion: typeof PROTOCOL_VERSION;
+    capabilities: CapabilitiesInfo;
+}
+export interface BridgeByeEvent {
+    type: 'bridge.bye';
+    reason: 'shutdown' | 'error' | 'unpaired';
+    message?: string;
+}
+export interface AgentRunStartEvent {
+    type: 'agent.run_start';
+    runId: string;
+    promptId: string;
+    startedAtMs: number;
+}
+export interface AgentTextDeltaEvent {
+    type: 'agent.text_delta';
+    runId: string;
+    delta: string;
+    /** Monotonic sequence within the run for ordering. */
+    seq: number;
+}
+export interface AgentTextDoneEvent {
+    type: 'agent.text_done';
+    runId: string;
+    text: string;
+}
+export interface AgentToolUseStartEvent {
+    type: 'agent.tool_use_start';
+    runId: string;
+    toolUseId: string;
+    /** Tool name (e.g. "Bash", "Edit", "Read", or any MCP tool). */
+    name: string;
+    /** Best-effort input snapshot (may be partial during streaming). */
+    input: unknown;
+}
+export interface AgentToolUseProgressEvent {
+    type: 'agent.tool_use_progress';
+    runId: string;
+    toolUseId: string;
+    /** Plain-text progress chunk (e.g. streaming Bash stdout). */
+    chunk: string;
+}
+export interface AgentToolUseEndEvent {
+    type: 'agent.tool_use_end';
+    runId: string;
+    toolUseId: string;
+    status: 'success' | 'error';
+    output: unknown;
+    latencyMs?: number;
+}
+export interface AgentThinkingDeltaEvent {
+    type: 'agent.thinking_delta';
+    runId: string;
+    delta: string;
+}
+export interface AgentRunEndEvent {
+    type: 'agent.run_end';
+    runId: string;
+    reason: 'completed' | 'interrupted' | 'error';
+    message?: string;
+    totalLatencyMs?: number;
+}
+export type PermissionRiskLevel = 'low' | 'medium' | 'high';
+export interface AgentPermissionRequestEvent {
+    type: 'agent.permission_request';
+    requestId: string;
+    runId: string;
+    toolName: string;
+    toolInput: unknown;
+    /** One-line human-readable summary used as the modal title. */
+    summary: string;
+    /** Why approval is being asked — e.g. "outside workspace", "shell command". */
+    reason: string;
+    riskLevel: PermissionRiskLevel;
+}
+export interface AgentPermissionResolvedEvent {
+    type: 'agent.permission_resolved';
+    requestId: string;
+    decision: 'allow' | 'deny' | 'expired';
+}
+export type BridgeOutboundEvent = BridgeHelloEvent | BridgeByeEvent | AgentRunStartEvent | AgentTextDeltaEvent | AgentTextDoneEvent | AgentToolUseStartEvent | AgentToolUseProgressEvent | AgentToolUseEndEvent | AgentThinkingDeltaEvent | AgentRunEndEvent | AgentPermissionRequestEvent | AgentPermissionResolvedEvent;
+export interface PromptUserTurnEvent {
+    type: 'prompt.user_turn';
+    promptId: string;
+    /** Display name of the speaker who triggered this prompt. */
+    speaker: string;
+    /** Stable speaker identity (LiveKit participant identity). */
+    speakerIdentity: string;
+    /** Latest line that addressed the agent. */
+    text: string;
+    /** Sliding transcript window for context. */
+    transcriptWindow: TranscriptWindowEntry[];
+    /** Active room metadata used for prompt grounding. */
+    room: {
+        id: string;
+        name: string;
+        participants: string[];
+    };
+}
+export interface TranscriptWindowEntry {
+    speaker: string;
+    text: string;
+    timestampMs: number;
+}
+export interface PromptInterruptEvent {
+    type: 'prompt.interrupt';
+    /** Optional run ID — when omitted, interrupts whatever is active. */
+    runId?: string;
+}
+export interface PromptCancelPendingEvent {
+    type: 'prompt.cancel_pending';
+}
+export interface PermissionResponseEvent {
+    type: 'permission.response';
+    requestId: string;
+    decision: 'allow' | 'deny';
+}
+export type BridgeInboundEvent = PromptUserTurnEvent | PromptInterruptEvent | PromptCancelPendingEvent | PermissionResponseEvent;
+export type BridgeEvent = BridgeOutboundEvent | BridgeInboundEvent;
+/**
+ * Encodes an event for transmission over the LiveKit data channel.
+ *
+ * @param event - Bridge event to serialize.
+ * @returns UTF-8 encoded JSON byte payload.
+ */
+export declare function encodeBridgeEvent(event: BridgeEvent): Uint8Array;
+/**
+ * Decodes a LiveKit data-channel payload back into a bridge event.
+ *
+ * Returns `null` when the payload is not valid JSON or not a known event.
+ */
+export declare function decodeBridgeEvent(payload: Uint8Array): BridgeEvent | null;
+//# sourceMappingURL=protocol.d.ts.map

package/dist/protocol.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.d.ts","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"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"}

package/dist/protocol.js

@@ -0,0 +1,63 @@
+/**
+ * @file Wire protocol shared between the bridge process and the web client.
+ *
+ * Both packages import these types so adding/changing an event type fails the
+ * type checker on both ends. Runtime exports are intentionally minimal — the
+ * web side only uses the type aliases.
+ */
+export const PROTOCOL_VERSION = 1;
+/**
+ * LiveKit data channel topic used for all bridge ↔ room control messages.
+ *
+ * Keeps event traffic isolated from any other future data-channel usage.
+ */
+export const BRIDGE_TOPIC = 'voxagent.bridge';
+/**
+ * Identity prefix reserved for the bridge participant.
+ *
+ * The web token route refuses to mint identities matching this prefix to
+ * prevent browser participants from impersonating the agent.
+ */
+export const AGENT_IDENTITY_PREFIX = 'agent:';
+/**
+ * Builds the canonical agent identity for one room.
+ *
+ * @param roomId - Room identifier the bridge will pair with.
+ * @returns LiveKit participant identity string.
+ */
+export function buildAgentIdentity(roomId) {
+    return `${AGENT_IDENTITY_PREFIX}${roomId}`;
+}
+/**
+ * Returns true when an identity string matches the reserved agent prefix.
+ */
+export function isAgentIdentity(identity) {
+    return identity.startsWith(AGENT_IDENTITY_PREFIX);
+}
+/**
+ * Encodes an event for transmission over the LiveKit data channel.
+ *
+ * @param event - Bridge event to serialize.
+ * @returns UTF-8 encoded JSON byte payload.
+ */
+export function encodeBridgeEvent(event) {
+    return new TextEncoder().encode(JSON.stringify(event));
+}
+/**
+ * Decodes a LiveKit data-channel payload back into a bridge event.
+ *
+ * Returns `null` when the payload is not valid JSON or not a known event.
+ */
+export function decodeBridgeEvent(payload) {
+    try {
+        const text = new TextDecoder().decode(payload);
+        const parsed = JSON.parse(text);
+        if (typeof parsed.type !== 'string')
+            return null;
+        return parsed;
+    }
+    catch {
+        return null;
+    }
+}
+//# sourceMappingURL=protocol.js.map

package/dist/protocol.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"protocol.js","sourceRoot":"","sources":["../src/protocol.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,MAAM,CAAC,MAAM,gBAAgB,GAAG,CAAU,CAAC;AAE3C;;;;GAIG;AACH,MAAM,CAAC,MAAM,YAAY,GAAG,iBAA0B,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,CAAC,MAAM,qBAAqB,GAAG,QAAiB,CAAC;AAEvD;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc;IAC/C,OAAO,GAAG,qBAAqB,GAAG,MAAM,EAAE,CAAC;AAC7C,CAAC;AAED;;GAEG;AACH,MAAM,UAAU,eAAe,CAAC,QAAgB;IAC9C,OAAO,QAAQ,CAAC,UAAU,CAAC,qBAAqB,CAAC,CAAC;AACpD,CAAC;AAgLD;;;;;GAKG;AACH,MAAM,UAAU,iBAAiB,CAAC,KAAkB;IAClD,OAAO,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,IAAI,CAAC,SAAS,CAAC,KAAK,CAAC,CAAC,CAAC;AACzD,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,iBAAiB,CAAC,OAAmB;IACnD,IAAI,CAAC;QACH,MAAM,IAAI,GAAG,IAAI,WAAW,EAAE,CAAC,MAAM,CAAC,OAAO,CAAC,CAAC;QAC/C,MAAM,MAAM,GAAG,IAAI,CAAC,KAAK,CAAC,IAAI,CAAuB,CAAC;QACtD,IAAI,OAAO,MAAM,CAAC,IAAI,KAAK,QAAQ;YAAE,OAAO,IAAI,CAAC;QACjD,OAAO,MAAqB,CAAC;IAC/B,CAAC;IAAC,MAAM,CAAC;QACP,OAAO,IAAI,CAAC;IACd,CAAC;AACH,CAAC"}

package/dist/room.d.ts

@@ -0,0 +1,52 @@
+/**
+ * @file Room runtime — joins LiveKit, publishes agent voice, drives the agent.
+ *
+ * Lifecycle:
+ *   1. Connect to LiveKit with the bridge JWT.
+ *   2. Publish the agent audio track so other participants subscribe to it.
+ *   3. Send `bridge.hello` over the data channel so the UI knows we're paired.
+ *   4. Listen for `prompt.user_turn` from any participant.
+ *   5. For each prompt, run the driver; fan events into:
+ *        - data channel (text deltas, tool events) for UI
+ *        - TTS engine (text deltas) → AudioSource (PCM frames) for voice
+ *        - cloud action ingest (tool start/end) for the persisted timeline
+ */
+import type { BridgeConfig } from './config.js';
+import type { AgentDriver } from './drivers/index.js';
+import type { PairResult } from './pair.js';
+import { PermissionBroker } from './permissions.js';
+import { type CapabilitiesInfo } from './protocol.js';
+interface RoomRuntimeOptions {
+    config: BridgeConfig;
+    pair: PairResult;
+    driver: AgentDriver;
+    capabilities: CapabilitiesInfo;
+    permissionBroker: PermissionBroker;
+}
+export declare class BridgeRoomRuntime {
+    private readonly options;
+    private room;
+    private audio;
+    private tts;
+    private activeRun;
+    private deltaSeq;
+    private shuttingDown;
+    private pendingPrompts;
+    constructor(options: RoomRuntimeOptions);
+    start(): Promise<void>;
+    shutdown(reason?: 'shutdown' | 'error'): Promise<void>;
+    private handleDisconnect;
+    private handleDataReceived;
+    private enqueuePrompt;
+    private drainPrompts;
+    private interruptActiveRun;
+    private runPrompt;
+    private pumpAudio;
+    private handleDriverEvent;
+    private publishEvent;
+    private ingestActionStart;
+    private ingestActionEnd;
+    private callIngest;
+}
+export {};
+//# sourceMappingURL=room.d.ts.map

package/dist/room.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"room.d.ts","sourceRoot":"","sources":["../src/room.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;GAYG;AAUH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,aAAa,CAAC;AAChD,OAAO,KAAK,EAAE,WAAW,EAAe,MAAM,oBAAoB,CAAC;AAEnE,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAC5C,OAAO,EAAE,gBAAgB,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,EAML,KAAK,gBAAgB,EAEtB,MAAM,eAAe,CAAC;AAGvB,UAAU,kBAAkB;IAC1B,MAAM,EAAE,YAAY,CAAC;IACrB,IAAI,EAAE,UAAU,CAAC;IACjB,MAAM,EAAE,WAAW,CAAC;IACpB,YAAY,EAAE,gBAAgB,CAAC;IAC/B,gBAAgB,EAAE,gBAAgB,CAAC;CACpC;AASD,qBAAa,iBAAiB;IAShB,OAAO,CAAC,QAAQ,CAAC,OAAO;IARpC,OAAO,CAAC,IAAI,CAAO;IACnB,OAAO,CAAC,KAAK,CAAoC;IACjD,OAAO,CAAC,GAAG,CAA0B;IACrC,OAAO,CAAC,SAAS,CAA0B;IAC3C,OAAO,CAAC,QAAQ,CAAK;IACrB,OAAO,CAAC,YAAY,CAAS;IAC7B,OAAO,CAAC,cAAc,CAA6B;gBAEtB,OAAO,EAAE,kBAAkB;IAIlD,KAAK,IAAI,OAAO,CAAC,IAAI,CAAC;IA6DtB,QAAQ,CAAC,MAAM,GAAE,UAAU,GAAG,OAAoB,GAAG,OAAO,CAAC,IAAI,CAAC;IAkCxE,OAAO,CAAC,gBAAgB,CAKtB;IAEF,OAAO,CAAC,kBAAkB,CA0BxB;IAEF,OAAO,CAAC,aAAa;YASP,YAAY;IAU1B,OAAO,CAAC,kBAAkB;YAUZ,SAAS;YAwDT,SAAS;YAcT,iBAAiB;YA2FjB,YAAY;YAgBZ,iBAAiB;YASjB,eAAe;YASf,UAAU;CAuBzB"}