@fabric-harness/sdk 1.9.0 → 1.11.0

package/dist/voice.d.ts

@@ -0,0 +1,108 @@
+import type { CostBudgetTracker, CostLimitContext } from './cost-budget.js';
+import type { ModelUsage } from './model.js';
+import type { ToolDef } from './tools.js';
+/**
+ * Bidirectional voice / audio streaming surface. fabric-harness ships an
+ * OpenAI Realtime implementation; bring-your-own-vendor for Anthropic /
+ * Gemini Live / on-prem TTS+ASR pipelines.
+ *
+ * Audio frames flow in raw bytes — the standard format is PCM 16-bit
+ * little-endian at 24kHz mono (OpenAI Realtime default). Telephony
+ * bridges (Twilio Media Streams μ-law 8kHz, etc.) resample at the edge.
+ *
+ * Tool execution is the *caller's* responsibility: a `tool_call` event
+ * surfaces, the host code runs the tool through whatever governance gates
+ * apply (approvals, cost caps, rate limits), then calls
+ * `submitToolResult({ id, output })`. Voice sessions deliberately don't
+ * own the loop machinery — this keeps the audio path lean and lets users
+ * apply the v1-era policy primitives unchanged.
+ */
+export type VoiceAudioFormat = 'pcm16' | 'g711_ulaw' | 'g711_alaw';
+export interface VoiceConnectOptions {
+    /** Initial system instructions / persona. */
+    instructions?: string;
+    /** Voice timbre id (provider-specific, e.g. 'alloy', 'nova', 'verse'). */
+    voice?: string;
+    /** Audio format used on both directions. Default 'pcm16' at 24kHz mono. */
+    audioFormat?: VoiceAudioFormat;
+    /** Tools the model can call. Same shape as session.prompt() tools. */
+    tools?: ToolDef[];
+    /** Turn-detection mode (provider-specific). Default 'server_vad'. */
+    turnDetection?: 'server_vad' | 'none';
+    /** Sample rate hint for the provider. Default 24000 (PCM16). */
+    sampleRate?: number;
+    /**
+     * Optional cost budget tracker. Observed on every `response_done` with
+     * usage. Voice sessions thus participate in the same per-call /
+     * per-session / per-tenant ceilings as text agents (v1.4 + v1.6).
+     */
+    costBudget?: CostBudgetTracker;
+    /**
+     * Required when `costBudget.onExceed === 'approve'`. Returns true to
+     * resume, false to throw `CostLimitExceededError`.
+     */
+    requestCostLimitApproval?: (ctx: CostLimitContext) => Promise<boolean>;
+    /** Abort signal — closes the session when fired. */
+    signal?: AbortSignal;
+}
+/**
+ * Events streamed from a `VoiceSession`. `audio_delta` carries raw audio
+ * bytes; `text_delta` and `transcript` carry text; `tool_call` and
+ * `response_done` mark structured boundaries; `error` is fatal.
+ */
+export type VoiceEvent = {
+    type: 'session_open';
+} | {
+    type: 'audio_delta';
+    audio: Uint8Array;
+} | {
+    type: 'text_delta';
+    delta: string;
+    role: 'assistant' | 'user';
+} | {
+    type: 'transcript';
+    text: string;
+    role: 'assistant' | 'user';
+} | {
+    type: 'tool_call';
+    id: string;
+    name: string;
+    input: unknown;
+} | {
+    type: 'response_done';
+    usage?: ModelUsage;
+} | {
+    type: 'cost_limit';
+    scope: 'call' | 'session' | 'cross-process';
+    observedUsd: number;
+    limitUsd: number;
+    scopeKey?: string;
+} | {
+    type: 'error';
+    message: string;
+};
+export interface VoiceToolResultInput {
+    /** Tool-call id from the matching `tool_call` event. */
+    id: string;
+    /** JSON-serializable output — stringified before sending. */
+    output: unknown;
+}
+export interface VoiceSession {
+    /** Append a raw audio frame. Format matches `VoiceConnectOptions.audioFormat`. */
+    sendAudio(frame: Uint8Array): Promise<void>;
+    /** Send a text turn (the model responds with audio + text). */
+    sendText(text: string): Promise<void>;
+    /** Submit a tool-call result back to the model after a `tool_call` event. */
+    submitToolResult(input: VoiceToolResultInput): Promise<void>;
+    /** Cancel the in-progress response (barge-in). */
+    cancelResponse(): Promise<void>;
+    /** Async iterable of events. Closes when the session ends or aborts. */
+    events(): AsyncIterable<VoiceEvent>;
+    /** Tear down the underlying connection. */
+    close(): Promise<void>;
+}
+export interface VoiceProvider {
+    name: string;
+    connect(options: VoiceConnectOptions): Promise<VoiceSession>;
+}
+//# sourceMappingURL=voice.d.ts.map

package/dist/voice.d.ts.map

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

package/dist/voice.js

@@ -0,0 +1,2 @@
+export {};
+//# sourceMappingURL=voice.js.map

package/dist/voice.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"voice.js","sourceRoot":"","sources":["../src/voice.ts"],"names":[],"mappings":""}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@fabric-harness/sdk",
-  "version": "1.9.0",
+  "version": "1.11.0",
   "description": "Headless TypeScript framework for building durable, deployable autonomous agents — core SDK.",
   "license": "Apache-2.0",
   "author": "Fabric",