@voicelayer/sdk 0.4.1 → 0.5.0

package/dist/{text-session-BB0dLLH2.d.ts → text-session-Bf4Jni7H.d.ts}

@@ -1,5 +1,6 @@
 import { JobContext, voice } from '@livekit/agents';
 import { z } from 'zod';
+import { O as OnQuery } from './types-KqrAfY85.js';
 import OpenAI from 'openai';
 
 type SessionState = 'initializing' | 'idle' | 'listening' | 'thinking' | 'speaking';
@@ -14,6 +15,8 @@ interface UserInputEvent {
 }
 interface AgentTurnEvent {
     readonly text: string;
+    /** The caller cut the line off (barge-in). Its echo can land after the caller's turn, so it never takes the floor. */
+    readonly interrupted?: boolean;
 }
 interface DtmfEvent$1 {
     readonly digit: string;
@@ -240,7 +243,7 @@ interface UserTurn {
 }
 interface FakeSessionAdapter extends SessionAdapter {
     emitUserInput(e: UserInputEvent): void;
-    emitAgentTurn(text: string): void;
+    emitAgentTurn(text: string, interrupted?: boolean): void;
     emitDtmf(digit: string): void;
     /** Drives 'state' with correct oldState/rawOldState AND runs the SAME
      *  arm/cancel + idle-release as production. Unknown string => 'thinking'. */
@@ -366,6 +369,9 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         max: z.ZodOptional<z.ZodNumber>;
         enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
         ask: z.ZodOptional<z.ZodString>;
+        /** false ⇒ written by the agent itself (a tool's output, an assignment), never said by the caller — the runtime
+         *  doesn't extract it from their words. Absent ⇒ the caller may say it. */
+        fromCaller: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
         name: string;
@@ -375,6 +381,7 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         min?: number | undefined;
         max?: number | undefined;
         enum?: string[] | undefined;
+        fromCaller?: boolean | undefined;
     }, {
         type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
         name: string;
@@ -384,30 +391,36 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         min?: number | undefined;
         max?: number | undefined;
         enum?: string[] | undefined;
+        fromCaller?: boolean | undefined;
     }>, "many">;
     completionGate: z.ZodObject<{
         requiredFields: z.ZodArray<z.ZodString, "many">;
         backendAck: z.ZodOptional<z.ZodObject<{
             url: z.ZodString;
             timeoutMs: z.ZodNumber;
+            allowPrivateNetwork: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             url: string;
             timeoutMs: number;
+            allowPrivateNetwork?: boolean | undefined;
         }, {
             url: string;
             timeoutMs: number;
+            allowPrivateNetwork?: boolean | undefined;
         }>>;
     }, "strip", z.ZodTypeAny, {
         requiredFields: string[];
         backendAck?: {
             url: string;
             timeoutMs: number;
+            allowPrivateNetwork?: boolean | undefined;
         } | undefined;
     }, {
         requiredFields: string[];
         backendAck?: {
             url: string;
             timeoutMs: number;
+            allowPrivateNetwork?: boolean | undefined;
         } | undefined;
     }>;
     triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -458,6 +471,11 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
         auth: z.ZodEnum<["none", "connection"]>;
         connectionRef: z.ZodOptional<z.ZodString>;
+        /**
+         * Self-hosted workers only: allow a private / loopback address (a localhost service of your own). A platform
+         * worker (it holds the internal service token) never honours it.
+         */
+        allowPrivateNetwork: z.ZodOptional<z.ZodBoolean>;
     }, "strip", z.ZodTypeAny, {
         name: string;
         url: string;
@@ -465,6 +483,7 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         input: Record<string, "string" | "number" | "boolean">;
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
         auth: "none" | "connection";
+        allowPrivateNetwork?: boolean | undefined;
         headers?: Record<string, string> | undefined;
         connectionRef?: string | undefined;
     }, {
@@ -474,9 +493,11 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         input: Record<string, "string" | "number" | "boolean">;
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
         auth: "none" | "connection";
+        allowPrivateNetwork?: boolean | undefined;
         headers?: Record<string, string> | undefined;
         connectionRef?: string | undefined;
     }>, "many">>;
+    displayName: z.ZodOptional<z.ZodString>;
     speech: z.ZodOptional<z.ZodObject<{
         interruption: z.ZodOptional<z.ZodObject<{
             enabled: z.ZodOptional<z.ZodBoolean>;
@@ -646,6 +667,7 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         backendAck?: {
             url: string;
             timeoutMs: number;
+            allowPrivateNetwork?: boolean | undefined;
         } | undefined;
     };
     fields: {
@@ -657,6 +679,7 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         min?: number | undefined;
         max?: number | undefined;
         enum?: string[] | undefined;
+        fromCaller?: boolean | undefined;
     }[];
     handoff?: {
         fallback?: string | undefined;
@@ -695,9 +718,11 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         input: Record<string, "string" | "number" | "boolean">;
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
         auth: "none" | "connection";
+        allowPrivateNetwork?: boolean | undefined;
         headers?: Record<string, string> | undefined;
         connectionRef?: string | undefined;
     }[] | undefined;
+    displayName?: string | undefined;
     program?: {
         v: 1;
         id: string;
@@ -730,6 +755,7 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         backendAck?: {
             url: string;
             timeoutMs: number;
+            allowPrivateNetwork?: boolean | undefined;
         } | undefined;
     };
     fields: {
@@ -741,6 +767,7 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         min?: number | undefined;
         max?: number | undefined;
         enum?: string[] | undefined;
+        fromCaller?: boolean | undefined;
     }[];
     handoff?: {
         fallback?: string | undefined;
@@ -779,9 +806,11 @@ declare const ProcessSchemaDTO: z.ZodObject<{
         input: Record<string, "string" | "number" | "boolean">;
         method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
         auth: "none" | "connection";
+        allowPrivateNetwork?: boolean | undefined;
         headers?: Record<string, string> | undefined;
         connectionRef?: string | undefined;
     }[] | undefined;
+    displayName?: string | undefined;
     program?: {
         v: 1;
         id: string;
@@ -854,6 +883,9 @@ declare const AgentDTO: z.ZodObject<{
             max: z.ZodOptional<z.ZodNumber>;
             enum: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
             ask: z.ZodOptional<z.ZodString>;
+            /** false ⇒ written by the agent itself (a tool's output, an assignment), never said by the caller — the runtime
+             *  doesn't extract it from their words. Absent ⇒ the caller may say it. */
+            fromCaller: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
             name: string;
@@ -863,6 +895,7 @@ declare const AgentDTO: z.ZodObject<{
             min?: number | undefined;
             max?: number | undefined;
             enum?: string[] | undefined;
+            fromCaller?: boolean | undefined;
         }, {
             type: "string" | "number" | "boolean" | "string[]" | "datetime" | "email" | "phone";
             name: string;
@@ -872,30 +905,36 @@ declare const AgentDTO: z.ZodObject<{
             min?: number | undefined;
             max?: number | undefined;
             enum?: string[] | undefined;
+            fromCaller?: boolean | undefined;
         }>, "many">;
         completionGate: z.ZodObject<{
             requiredFields: z.ZodArray<z.ZodString, "many">;
             backendAck: z.ZodOptional<z.ZodObject<{
                 url: z.ZodString;
                 timeoutMs: z.ZodNumber;
+                allowPrivateNetwork: z.ZodOptional<z.ZodBoolean>;
             }, "strip", z.ZodTypeAny, {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             }, {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             }>>;
         }, "strip", z.ZodTypeAny, {
             requiredFields: string[];
             backendAck?: {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             } | undefined;
         }, {
             requiredFields: string[];
             backendAck?: {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             } | undefined;
         }>;
         triggers: z.ZodOptional<z.ZodArray<z.ZodObject<{
@@ -946,6 +985,11 @@ declare const AgentDTO: z.ZodObject<{
             headers: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
             auth: z.ZodEnum<["none", "connection"]>;
             connectionRef: z.ZodOptional<z.ZodString>;
+            /**
+             * Self-hosted workers only: allow a private / loopback address (a localhost service of your own). A platform
+             * worker (it holds the internal service token) never honours it.
+             */
+            allowPrivateNetwork: z.ZodOptional<z.ZodBoolean>;
         }, "strip", z.ZodTypeAny, {
             name: string;
             url: string;
@@ -953,6 +997,7 @@ declare const AgentDTO: z.ZodObject<{
             input: Record<string, "string" | "number" | "boolean">;
             method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
             auth: "none" | "connection";
+            allowPrivateNetwork?: boolean | undefined;
             headers?: Record<string, string> | undefined;
             connectionRef?: string | undefined;
         }, {
@@ -962,9 +1007,11 @@ declare const AgentDTO: z.ZodObject<{
             input: Record<string, "string" | "number" | "boolean">;
             method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
             auth: "none" | "connection";
+            allowPrivateNetwork?: boolean | undefined;
             headers?: Record<string, string> | undefined;
             connectionRef?: string | undefined;
         }>, "many">>;
+        displayName: z.ZodOptional<z.ZodString>;
         speech: z.ZodOptional<z.ZodObject<{
             interruption: z.ZodOptional<z.ZodObject<{
                 enabled: z.ZodOptional<z.ZodBoolean>;
@@ -1134,6 +1181,7 @@ declare const AgentDTO: z.ZodObject<{
             backendAck?: {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             } | undefined;
         };
         fields: {
@@ -1145,6 +1193,7 @@ declare const AgentDTO: z.ZodObject<{
             min?: number | undefined;
             max?: number | undefined;
             enum?: string[] | undefined;
+            fromCaller?: boolean | undefined;
         }[];
         handoff?: {
             fallback?: string | undefined;
@@ -1183,9 +1232,11 @@ declare const AgentDTO: z.ZodObject<{
             input: Record<string, "string" | "number" | "boolean">;
             method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
             auth: "none" | "connection";
+            allowPrivateNetwork?: boolean | undefined;
             headers?: Record<string, string> | undefined;
             connectionRef?: string | undefined;
         }[] | undefined;
+        displayName?: string | undefined;
         program?: {
             v: 1;
             id: string;
@@ -1218,6 +1269,7 @@ declare const AgentDTO: z.ZodObject<{
             backendAck?: {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             } | undefined;
         };
         fields: {
@@ -1229,6 +1281,7 @@ declare const AgentDTO: z.ZodObject<{
             min?: number | undefined;
             max?: number | undefined;
             enum?: string[] | undefined;
+            fromCaller?: boolean | undefined;
         }[];
         handoff?: {
             fallback?: string | undefined;
@@ -1267,9 +1320,11 @@ declare const AgentDTO: z.ZodObject<{
             input: Record<string, "string" | "number" | "boolean">;
             method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
             auth: "none" | "connection";
+            allowPrivateNetwork?: boolean | undefined;
             headers?: Record<string, string> | undefined;
             connectionRef?: string | undefined;
         }[] | undefined;
+        displayName?: string | undefined;
         program?: {
             v: 1;
             id: string;
@@ -1324,6 +1379,7 @@ declare const AgentDTO: z.ZodObject<{
             backendAck?: {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             } | undefined;
         };
         fields: {
@@ -1335,6 +1391,7 @@ declare const AgentDTO: z.ZodObject<{
             min?: number | undefined;
             max?: number | undefined;
             enum?: string[] | undefined;
+            fromCaller?: boolean | undefined;
         }[];
         handoff?: {
             fallback?: string | undefined;
@@ -1373,9 +1430,11 @@ declare const AgentDTO: z.ZodObject<{
             input: Record<string, "string" | "number" | "boolean">;
             method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
             auth: "none" | "connection";
+            allowPrivateNetwork?: boolean | undefined;
             headers?: Record<string, string> | undefined;
             connectionRef?: string | undefined;
         }[] | undefined;
+        displayName?: string | undefined;
         program?: {
             v: 1;
             id: string;
@@ -1428,6 +1487,7 @@ declare const AgentDTO: z.ZodObject<{
             backendAck?: {
                 url: string;
                 timeoutMs: number;
+                allowPrivateNetwork?: boolean | undefined;
             } | undefined;
         };
         fields: {
@@ -1439,6 +1499,7 @@ declare const AgentDTO: z.ZodObject<{
             min?: number | undefined;
             max?: number | undefined;
             enum?: string[] | undefined;
+            fromCaller?: boolean | undefined;
         }[];
         handoff?: {
             fallback?: string | undefined;
@@ -1477,9 +1538,11 @@ declare const AgentDTO: z.ZodObject<{
             input: Record<string, "string" | "number" | "boolean">;
             method: "GET" | "POST" | "PUT" | "PATCH" | "DELETE";
             auth: "none" | "connection";
+            allowPrivateNetwork?: boolean | undefined;
             headers?: Record<string, string> | undefined;
             connectionRef?: string | undefined;
         }[] | undefined;
+        displayName?: string | undefined;
         program?: {
             v: 1;
             id: string;
@@ -1510,6 +1573,57 @@ declare const AgentDTO: z.ZodObject<{
 }>;
 type AgentDTO = z.infer<typeof AgentDTO>;
 
+/** Policy embedded in AgentConfig — caps + UX wording. */
+declare const ConsultationPolicy: z.ZodObject<{
+    enabled: z.ZodDefault<z.ZodBoolean>;
+    defaultTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    maxCumulativeHoldMs: z.ZodDefault<z.ZodNumber>;
+    holdPhrase: z.ZodDefault<z.ZodString>;
+    fallbackPhrase: z.ZodDefault<z.ZodString>;
+    callEndFallback: z.ZodDefault<z.ZodString>;
+    urgencyOverrides: z.ZodOptional<z.ZodObject<{
+        low: z.ZodOptional<z.ZodNumber>;
+        normal: z.ZodOptional<z.ZodNumber>;
+        high: z.ZodOptional<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        low?: number | undefined;
+        high?: number | undefined;
+        normal?: number | undefined;
+    }, {
+        low?: number | undefined;
+        high?: number | undefined;
+        normal?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    enabled: boolean;
+    defaultTimeoutMs: number;
+    maxTimeoutMs: number;
+    maxCumulativeHoldMs: number;
+    holdPhrase: string;
+    fallbackPhrase: string;
+    callEndFallback: string;
+    urgencyOverrides?: {
+        low?: number | undefined;
+        high?: number | undefined;
+        normal?: number | undefined;
+    } | undefined;
+}, {
+    enabled?: boolean | undefined;
+    defaultTimeoutMs?: number | undefined;
+    maxTimeoutMs?: number | undefined;
+    maxCumulativeHoldMs?: number | undefined;
+    holdPhrase?: string | undefined;
+    fallbackPhrase?: string | undefined;
+    callEndFallback?: string | undefined;
+    urgencyOverrides?: {
+        low?: number | undefined;
+        high?: number | undefined;
+        normal?: number | undefined;
+    } | undefined;
+}>;
+type ConsultationPolicy = z.infer<typeof ConsultationPolicy>;
+
 declare const FlowProgram: z.ZodObject<{
     v: z.ZodLiteral<1>;
     id: z.ZodString;
@@ -1653,6 +1767,7 @@ interface GateSpec {
     readonly backendAck?: {
         readonly url: string;
         readonly timeoutMs: number;
+        readonly allowPrivateNetwork?: boolean;
     };
 }
 /**
@@ -1938,20 +2053,719 @@ declare function dtmfDigitToCode(digit: string): number | null;
 /** Inverse of dtmfDigitToCode. Returns null for codes outside 0..15. */
 declare function dtmfCodeToDigit(code: number): string | null;
 
+interface ReadinessResult {
+    readonly ok: boolean;
+    /** Human-readable explanation when ok=false. Surfaced in metadata. */
+    readonly detail?: string;
+}
+interface ReadinessProbe {
+    readonly name: string;
+    check(): Promise<ReadinessResult>;
+}
+/** Aggregate result the SDK records in metadata.readiness. */
+interface ReadinessReport {
+    readonly probe: string;
+    readonly ok: boolean;
+    readonly detail?: string;
+}
+/**
+ * Run all probes in parallel. A probe that throws is reported as not-ok with
+ * the error message as detail; one bad probe never sinks the others.
+ */
+declare function runProbes(probes: readonly ReadinessProbe[]): Promise<ReadinessReport[]>;
+/** Probe that passes iff process.env[name] is non-empty after trimming. */
+declare function envProbe(name: string): ReadinessProbe;
+/**
+ * Probe wrapping an arbitrary async function. Returning a value (or void)
+ * means ok; throwing means not-ok. Compact escape hatch — promote to a real
+ * probe class when reuse appears.
+ */
+declare function asyncProbe(name: string, fn: () => Promise<unknown>): ReadinessProbe;
+/**
+ * Probe that fetches a URL and considers any 2xx/3xx response ok. Useful for
+ * upstream health-checks (e.g. an LLM gateway's /healthz). Default 3s timeout.
+ */
+declare function urlProbe(name: string, url: string, opts?: {
+    timeoutMs?: number;
+    method?: 'GET' | 'HEAD';
+}): ReadinessProbe;
+
+declare class VoiceLayerError extends Error {
+    readonly name: string;
+}
+declare class VoiceLayerAuthError extends VoiceLayerError {
+    readonly status: number;
+    readonly name: string;
+    constructor(message: string, status: number);
+}
+declare class VoiceLayerNetworkError extends VoiceLayerError {
+    readonly name: string;
+    readonly cause?: unknown;
+    constructor(message: string, cause?: unknown);
+}
+declare class VoiceLayerValidationError extends VoiceLayerError {
+    readonly issues: unknown;
+    readonly name: string;
+    constructor(message: string, issues: unknown);
+}
+declare class VoiceLayerHttpError extends VoiceLayerError {
+    readonly status: number;
+    readonly body: unknown;
+    readonly name: string;
+    constructor(message: string, status: number, body: unknown);
+}
+
+type AgentLifecycleEvent = {
+    type: 'registered';
+    agent: AgentDTO;
+} | {
+    type: 'readiness';
+    report: readonly ReadinessReport[];
+    allOk: boolean;
+} | {
+    type: 'heartbeat';
+    agent: AgentDTO;
+} | {
+    type: 'heartbeat_error';
+    error: VoiceLayerError | Error;
+    consecutiveFailures: number;
+    willRetry: boolean;
+} | {
+    type: 'heartbeat_recovered';
+    afterFailures: number;
+} | {
+    type: 're_registered';
+    agent: AgentDTO;
+    reason: 'agent_not_found';
+} | {
+    type: 'status_changed';
+    status: AgentStatus;
+    detail?: string;
+} | {
+    type: 'metadata_updated';
+} | {
+    type: 'deregistered';
+    reason: 'manual' | 'signal';
+};
+type AgentEventListener = (event: AgentLifecycleEvent) => void;
+interface AgentEventEmitter {
+    on(listener: AgentEventListener): () => void;
+    /** @internal — used by the lifecycle to publish events. */
+    emit(event: AgentLifecycleEvent): void;
+}
+
+/** Primitive field types accepted in a process definition. */
+type ProcessFieldType = 'string' | 'string[]' | 'number' | 'boolean' | 'datetime' | 'email' | 'phone';
+interface ProcessField {
+    readonly type: ProcessFieldType;
+    readonly required?: boolean;
+    /** Regex pattern for `string` / `string[]` items. */
+    readonly pattern?: RegExp;
+    /** Inclusive lower bound on a number or array length. */
+    readonly min?: number;
+    /** Inclusive upper bound on a number or array length. */
+    readonly max?: number;
+    /** One of N — restricts the captured value to this set. */
+    readonly enum?: readonly string[];
+    /** Override the auto-generated prompt for capturing this field. */
+    readonly ask?: string;
+    /** Override the field-extraction hint shown to the LLM. */
+    readonly extract?: string;
+    /** false ⇒ the agent writes this field itself (a tool's output, an assignment); it is never extracted from the
+     *  caller's words. Default true. */
+    readonly fromCaller?: boolean;
+}
+type CompletionStrategy = 'all-required-captured' | 'all-captured' | {
+    custom: (data: Record<string, unknown>, ctx: AgentContext) => boolean | Promise<boolean>;
+};
+interface ProcessBackendAck {
+    /** URL to POST captured data to. The call cannot complete until this 2xx's. */
+    readonly url: string;
+    /** Capped at 10 s whatever is set here — the call's completion waits on it. */
+    readonly timeoutMs?: number;
+    readonly headers?: Readonly<Record<string, string>>;
+    /**
+     * Self-hosted workers only: allow a private / loopback URL (your own localhost service). Off by default. A platform
+     * worker (it holds INTERNAL_SERVICE_TOKEN) never honours it.
+     */
+    readonly allowPrivateNetwork?: boolean;
+}
+interface ProcessDefinition<T extends Record<string, ProcessField> = Record<string, ProcessField>> {
+    /** Field schema. Order is preserved when the SDK auto-asks for fields. */
+    readonly collect: T;
+    /** When the call can end. Defaults to 'all-required-captured'. */
+    readonly completeWhen?: CompletionStrategy;
+    /** Optional external system that must ACK before completion. */
+    readonly backendAck?: ProcessBackendAck;
+    /** Fires once all completion conditions are met. */
+    readonly onComplete?: (data: InferProcessData<T>, ctx: AgentContext) => Promise<void> | void;
+    /** Fires whenever a field is captured (good for live CRM updates). */
+    readonly onField?: <K extends keyof T>(field: K, value: InferFieldValue<T[K]>, ctx: AgentContext) => Promise<void> | void;
+}
+/** Inferred TS type for the data bag a process produces. */
+type InferProcessData<T extends Record<string, ProcessField>> = {
+    [K in keyof T]: T[K]['required'] extends true ? InferFieldValue<T[K]> : InferFieldValue<T[K]> | undefined;
+};
+type InferFieldValue<F extends ProcessField> = F['type'] extends 'string' ? string : F['type'] extends 'string[]' ? string[] : F['type'] extends 'number' ? number : F['type'] extends 'boolean' ? boolean : F['type'] extends 'datetime' ? Date : F['type'] extends 'email' ? string : F['type'] extends 'phone' ? string : never;
+type TriggerCondition = RegExp | `signal:${string}` | ((text: string, ctx: AgentContext) => boolean | Promise<boolean>);
+type TriggerAction = 'handoff' | 'endCall' | {
+    say: string;
+} | {
+    run: (ctx: AgentContext) => Promise<void> | void;
+}
+/** Jump the flow-graph cursor to a node id. Only meaningful under the graph
+ *  interpreter (the flat goals+rails path has no cursor and ignores it). */
+ | {
+    goto: string;
+};
+interface TriggerDefinition {
+    readonly on: TriggerCondition;
+    readonly then: TriggerAction;
+    /** If set, the trigger only fires while the named field is uncaptured. */
+    readonly onlyWhile?: string;
+}
+interface HandoffConfig {
+    /** Default human number when a trigger says { then: 'handoff' }. */
+    readonly fallback: string;
+    /** Map signal/trigger names to specific destinations. */
+    readonly routes?: Readonly<Record<string, string>>;
+    /** Build the briefing text passed to the human agent (or PSTN whisper). */
+    readonly briefing?: (args: {
+        readonly data: Record<string, unknown>;
+        readonly transcript: TranscriptHandle;
+        readonly call: AgentContext['call'];
+    }) => string | Promise<string>;
+    /**
+     * 'warm' (default) dials the human into the room as a conference, lets the
+     * agent brief them live, then drops the agent — caller + human stay
+     * connected. 'cold' is a blind SIP REFER: the caller is transferred away
+     * immediately. Warm falls back to cold when no outbound trunk is configured.
+     */
+    readonly mode?: 'warm' | 'cold';
+}
+interface TranscriptHandle {
+    /** Last N turns as `speaker: text` lines. */
+    tail(n: number): string;
+    full(): string;
+}
+/**
+ * Memory scope. `'participant'` and `'caller'` are synonyms — `'caller'`
+ * is the historical name from the 1:1 era; new code should prefer
+ * `'participant'`, which makes the multi-party semantics explicit.
+ */
+type MemoryScope = 'call' | 'caller' | 'participant' | 'account' | 'platform';
+interface MemoryConfig {
+    /** Which scope to persist to. Defaults to 'caller'. */
+    readonly scope?: MemoryScope;
+    readonly retentionDays?: number;
+    /** Fields auto-redacted on write. Recognized: ssn, dob, email, phone, ccn. */
+    readonly piiFields?: readonly string[];
+    /** Opt in to cross-tenant aggregate memory (anonymized). */
+    readonly platformOptIn?: boolean;
+}
+/**
+ * Multi-participant configuration. Optional — when omitted, the agent runs
+ * in 1:1 mode (one human + one agent) and the SDK still populates
+ * `ctx.room.participants` so participant-aware code paths work.
+ */
+interface ParticipantsConfig {
+    /**
+     * Fires when a human participant joins the room. In 1:1 calls this
+     * fires once at session start for the caller. In multi-party calls it
+     * fires per join.
+     */
+    readonly onJoin?: (participant: Participant, ctx: AgentContext) => Promise<void> | void;
+    /** Fires when a participant disconnects (hangup, transfer, kick). */
+    readonly onLeave?: (participant: Participant, ctx: AgentContext) => Promise<void> | void;
+    /**
+     * Synchronously enrich a participant's attribute bag before `onJoin`
+     * fires. Useful for phone-number → language lookups, etc. The returned
+     * map is merged into `participant.attributes`.
+     */
+    readonly attributes?: (participant: Participant) => Readonly<Record<string, string>> | Promise<Readonly<Record<string, string>>>;
+    /**
+     * Reject participants beyond this count. Default: unlimited. The cap
+     * is enforced by the worker when wiring participant lifecycle.
+     */
+    readonly max?: number;
+}
+/**
+ * A connector instance. Created by per-system factories like `salesforce()`,
+ * `twilio()`, etc. The factory returns an opaque handle that the SDK wires
+ * into `ctx.connectors` and (when `expose: true`) into the LLM tool list.
+ */
+interface ConnectorInstance<TName extends string = string, TApi = unknown> {
+    readonly __connector: true;
+    readonly name: TName;
+    readonly api: TApi;
+    /** If true, every method on `api` becomes an LLM-callable tool. */
+    readonly expose?: boolean;
+}
+type ComplianceTag = 'tcpa' | 'hipaa' | 'pci' | 'gdpr' | 'soc2';
+/**
+ * Duck-typed pipeline component markers. The SDK never inspects these — they
+ * are passed through to LiveKit's AgentSession as-is. Three ways to satisfy:
+ *
+ *   1. SDK factory:    `deepgram.tts({ model: 'aura-2' })`
+ *   2. Wrapped LK:     `wrap(new TTS({...}), { trace: true })`
+ *   3. User-built:     class MyTTS extends BaseTTS { ... }   // BaseTTS
+ *                                                            // re-exported
+ *                                                            // from the SDK
+ *
+ * Anything implementing the duck-type — even a plain object — is accepted.
+ */
+interface STTProvider {
+    readonly __vlPipeline?: 'stt';
+}
+interface LLMProvider {
+    readonly __vlPipeline?: 'llm';
+}
+interface TTSProvider {
+    readonly __vlPipeline?: 'tts';
+}
+interface VADProvider {
+    readonly __vlPipeline?: 'vad';
+}
+interface TurnDetectorProvider {
+    readonly __vlPipeline?: 'turn';
+}
+/**
+ * Speech-to-speech / realtime model marker (OpenAI Realtime, Gemini Live).
+ * A realtime model handles STT + LLM + TTS + turn-taking server-side, so when
+ * `models.realtime` is set the SDK builds the AgentSession around it and
+ * ignores the stt/llm/tts slots.
+ */
+interface RealtimeProvider {
+    readonly __vlPipeline?: 'realtime';
+}
+/**
+ * Lazy form so users can pick a provider per call (e.g. by caller locale).
+ * The factory runs once per call, before AgentSession is constructed, so it
+ * receives the call envelope (callerId, to, metadata) rather than the full
+ * AgentContext (which depends on AgentSession existing).
+ */
+type ProviderFactory<T> = (call: CallInfo) => T | Promise<T>;
+interface ModelConfig {
+    /**
+     * String form: 'openai/gpt-4o' (resolves via SDK defaults).
+     * Instance form: any LLMProvider (LK plugin, wrap()-ed, or user-built).
+     * Factory form: `(ctx) => provider` for per-call selection.
+     */
+    readonly llm?: string | LLMProvider | ProviderFactory<LLMProvider>;
+    readonly stt?: string | STTProvider | ProviderFactory<STTProvider>;
+    readonly tts?: string | TTSProvider | ProviderFactory<TTSProvider>;
+    /** VAD has no string form — always pass an instance or factory. */
+    readonly vad?: VADProvider | ProviderFactory<VADProvider>;
+    readonly turnDetector?: TurnDetectorProvider | ProviderFactory<TurnDetectorProvider>;
+    /**
+     * Speech-to-speech / realtime model. When set, the STT→LLM→TTS pipeline is
+     * bypassed: the realtime model drives the whole turn. No string form — pass
+     * an instance (`openai.realtime({ voice: 'alloy' })`) or a per-call factory.
+     */
+    readonly realtime?: RealtimeProvider | ProviderFactory<RealtimeProvider>;
+    /** Spoken language; defaults to 'en-US'. Used by string-form defaults. */
+    readonly language?: string;
+}
+/**
+ * Answering-machine detection mode for outbound calls. Mirrors
+ * `OutboundConfig.amd` in @voicelayer/agent-spec.
+ *
+ *   'off'              — never run AMD; treat every answer as a human.
+ *   'detect'           — leave the voicemail message (or hang up) the moment
+ *                        a machine greeting is recognised.
+ *   'detectMessageEnd' — recognise the machine, then wait for the greeting to
+ *                        finish (an explicit "after the tone"-style cue or the
+ *                        greeting going quiet) before leaving the message.
+ */
+type AmdMode = 'off' | 'detect' | 'detectMessageEnd';
+/**
+ * Outbound-only behavior. AMD never runs on inbound calls (the runtime gates
+ * on the dispatch-metadata `direction`), so these knobs are inert unless the
+ * call was placed via the outbound path.
+ */
+interface OutboundCallConfig {
+    /** Answering-machine detection mode. Defaults to 'off'. */
+    readonly amd?: AmdMode;
+    /**
+     * Spoken (via TTS) when a machine is detected. When unset, the agent hangs
+     * up on detection instead of leaving a message.
+     */
+    readonly voicemailScript?: string;
+}
+/**
+ * Barge-in tuning. The pipeline allows interruptions by default (LK defaults:
+ * any speech ≥500ms cuts the agent off). These knobs tune that behavior per
+ * agent WITHOUT switching to puppet/hostControlled mode — e.g. a senior-living
+ * help desk wants `minWords: 2` so backchannels ("mm-hm", "okay") don't
+ * truncate the agent mid-sentence, while a fast-paced escalation desk keeps
+ * the zero-word default. Set `enabled: false` to make the agent
+ * non-interruptible (kiosk / broadcast announcements).
+ */
+interface InterruptionConfig {
+    /** Allow the caller to barge in over agent speech. Default true. */
+    readonly enabled?: boolean;
+    /** Words the caller must say before it counts as an interruption. Default 0
+     *  (any speech interrupts). 2–3 filters out backchannels. */
+    readonly minWords?: number;
+    /** Minimum caller speech duration (ms) to count as an interruption. Default 500. */
+    readonly minDuration?: number;
+}
+/**
+ * End-of-turn detection tuning: how long the pipeline waits after the caller
+ * stops speaking before treating the turn as finished. Raise `minDelay` for
+ * callers who pause mid-thought (e.g. elderly speakers); lower it for
+ * fast-paced lines.
+ */
+interface EndpointingConfig {
+    /** Minimum silence (ms) before the caller's turn is considered done. Default 500. */
+    readonly minDelay?: number;
+    /** Hard ceiling (ms) after which the turn ends regardless. Default 3000. */
+    readonly maxDelay?: number;
+}
+/**
+ * Speech polish. `pronunciations` rewrites brand names / acronyms / jargon to
+ * a spoken form before TTS (e.g. `{ VoiceLayer: 'Voice Layer', API: 'A P I' }`)
+ * via applyPronunciations(). `backgroundAudio` plays ambient room tone under
+ * the agent so silence feels less dead (a URL or a named preset).
+ * `interruption` + `endpointing` tune barge-in and turn-taking per agent.
+ */
+interface SpeechConfig {
+    readonly pronunciations?: Readonly<Record<string, string>>;
+    readonly backgroundAudio?: string | {
+        readonly url?: string;
+        readonly volume?: number;
+    };
+    readonly interruption?: InterruptionConfig;
+    readonly endpointing?: EndpointingConfig;
+}
+/** What caused the call to end. Surfaced to `endCall.onEnd` + logs. */
+type EndCallTrigger = 
+/** The LLM invoked the built-in `end_call` tool. */
+'tool'
+/** An external controller (MCP host) sent a `hangup` command. */
+ | 'host'
+/** The dead-air backstop fired (`idleHangupMs` of silence while idle). */
+ | 'idle'
+/** The hard per-call ceiling fired (`maxCallDurationMs` elapsed). */
+ | 'max_duration'
+/** The last non-agent participant left the room. */
+ | 'participant-left'
+/** A flow/graph run finished and asked to hang up. */
+ | 'flow'
+/** The realtime engine closed / disconnected under the session. */
+ | 'engine-closed'
+/** `ctx.endCall()` called directly from user code. */
+ | 'user';
+/** Passed to `endCall.onEnd` describing the teardown about to happen. */
+interface EndCallInfo {
+    /** Why the call is ending (e.g. the `end_call` tool's `reason`). */
+    readonly reason?: string;
+    /** What triggered the hang-up. */
+    readonly trigger: EndCallTrigger;
+    /** The teardown strategy that will run (after the policy is resolved). */
+    readonly teardown: 'room' | 'agent';
+}
+/**
+ * Controls how the agent ENDS a call. The SDK — not the agent prompt or an
+ * external puppet driver — owns teardown, so a hang-up is reliable even when
+ * the realtime transport has died mid-wrap.
+ *
+ * Defaults are "best case" and active without opt-in: the whole LiveKit room
+ * is deleted (which drops the SIP/PSTN leg too, so the carrier gets a BYE),
+ * a guarantee-watchdog re-attempts teardown if the first try doesn't land, and
+ * a dead-air backstop hangs up after the line has been silent too long. Every
+ * knob is overridable; set a field to `false` to disable that guard.
+ */
+interface EndCallPolicy {
+    /**
+     * Teardown strategy. `'room'` (default) deletes the LiveKit room via the
+     * room service — this removes the SIP participant too, so the call actually
+     * disconnects on the carrier side. `'agent'` only drops the agent's own
+     * participant (leaves any SIP leg up); use it only when something else owns
+     * the room lifecycle.
+     */
+    readonly teardown?: 'room' | 'agent';
+    /**
+     * After a hang-up is requested, keep re-attempting teardown until the room
+     * is actually gone or this many ms elapse. Guards against a teardown call
+     * that silently doesn't land (transport race, transient room-service error).
+     * Default 4000. `false` disables (single best-effort attempt).
+     */
+    readonly guaranteeMs?: number | false;
+    /**
+     * Dead-air backstop: when the agent is idle (waiting on the caller) and the
+     * line stays silent — no agent turn, no caller speech — for this many ms,
+     * end the call. Catches a wedged session whose normal `end_call` never ran.
+     * Only armed while the agent is idle, so it never interrupts agent speech or
+     * a long tool call. Default 20000. `false` disables.
+     */
+    readonly idleHangupMs?: number | false;
+    /**
+     * Hard call ceiling: hang up once the call has run this many ms from when
+     * the session becomes ready, regardless of activity. Catches runaway calls
+     * that never end naturally (stuck loops, hijacked keys dialing premium
+     * numbers). Fires with trigger `'max_duration'`. Default 3600000 (60
+     * minutes). `false` disables.
+     */
+    readonly maxCallDurationMs?: number | false;
+    /**
+     * Hook fired the moment a hang-up is decided, just before teardown — for
+     * every trigger (tool, host, idle, max_duration, engine-closed, …). Return
+     * `false` to take over teardown yourself (the SDK then does nothing — the
+     * call will NOT end unless you end it). Returning anything else (or nothing)
+     * runs the default teardown. Throwing is caught + logged, then the default
+     * teardown still runs (safe by default).
+     *
+     * EXCEPT a host hangup (`trigger: 'host'` — MCP `call_hangup`): the host is
+     * the operator, so the hook is told (with the host's reason) and given 2
+     * seconds, but can't keep the call open; the room is always deleted, even
+     * after an earlier hang-up was vetoed and whatever `teardown` says (0.2.0).
+     */
+    readonly onEnd?: (ctx: AgentContext, info: EndCallInfo) => boolean | void | Promise<boolean | void>;
+}
+type ShorthandPrimitive = 'string' | 'number' | 'boolean';
+type ToolInputShape = Record<string, ShorthandPrimitive> | z.ZodTypeAny;
+interface ToolDefinition<I = unknown, R = unknown> {
+    readonly description: string;
+    readonly input: ToolInputShape;
+    readonly run: (input: I, ctx: AgentContext) => Promise<R> | R;
+    /**
+     * Capability this tool requires. Action Guard hard-blocks the call if not
+     * declared (PRD §B.5 — "no soft failures, ever"). Defaults to
+     * `tool.<name>` when omitted; passing a domain-scoped string
+     * (`crm.write`, `payment.refund`) lets multiple tools share a capability
+     * for centralised policy.
+     */
+    readonly capability?: string;
+}
+/**
+ * Optional security adapters. The SDK always enforces the local-only synchronous
+ * guards (PRD §B.2 input regex, §B.3 system seal + PII tokenisation, §B.4
+ * markdown strip + PII partial-mask, §B.5 capability check). Setting any of
+ * these augments the local floor with external services. Each is independently
+ * optional — none has to be live for the floor guards to function.
+ *
+ * URLs can also come from env (`SECURITY_LLM_GUARD_URL`,
+ * `SECURITY_PRESIDIO_ANALYZER_URL`, `SECURITY_PRESIDIO_ANONYMIZER_URL`,
+ * `SECURITY_OPA_URL`, `SECURITY_OPA_DECISION_PATH`); explicit config wins.
+ */
+interface SecurityConfig {
+    /** Disable the primitive entirely. Use only for tests. Production code MUST NOT set this. */
+    readonly disabled?: boolean;
+    /** External LLM-Guard adapter for richer injection detection. */
+    readonly llmGuardUrl?: string;
+    /** Presidio analyzer URL for PII detection beyond local regex. */
+    readonly presidioAnalyzerUrl?: string;
+    /** Presidio anonymizer URL — if set, output is redacted before TTS. */
+    readonly presidioAnonymizerUrl?: string;
+    /** OPA decision API base URL (e.g. `http://opa:8181`). */
+    readonly opaUrl?: string;
+    /** OPA decision path (e.g. `voicelayer/security/decision`). */
+    readonly opaDecisionPath?: string;
+    /** Per-request timeout for security adapter calls. */
+    readonly adapterTimeoutMs?: number;
+}
+/**
+ * Marks an agent as a *flow-runtime* worker: instead of a fixed process it
+ * resolves the deployed flow from the dispatch metadata (`agentId`) at call
+ * time, fetches that agent's compiled process_schema, and boots from it. One
+ * process serves many flows (the shared pool). See defineFlowRuntime().
+ */
+interface FlowRuntimeConfig {
+    /** Prepended to the flow's compiled say/confirm prompt fragments. */
+    readonly basePrompt?: string;
+    /** Spoken (verbatim) before hanging up when a flow call's schema cannot be
+     *  loaded. A failed flow boot NEVER silently answers as a generic assistant. */
+    readonly bootFailureMessage?: string;
+}
+/** Output content-moderation guard config (P5). Mirrors @voicelayer/plugin-guard's
+ *  GuardConfig; the pure inspector lives in runtime/guard.ts. */
+interface GuardConfig {
+    /** Flag content longer than this many characters. Default 8000. */
+    readonly maxLength?: number;
+    /** Substrings that flag content (case-insensitive). Default none. */
+    readonly bannedSubstrings?: readonly string[];
+}
+interface AgentConfig<TProcess extends Record<string, ProcessField> = Record<string, ProcessField>> {
+    /** Lowercase, kebab-case identifier. Used for LiveKit dispatch + presence. */
+    readonly name: string;
+    /** System prompt the LLM sees. */
+    readonly prompt: string;
+    /** Fixed opening line, spoken instantly via TTS at the start of the default
+     *  conversation flow — NO LLM. Eliminates the dead air of an LLM-generated
+     *  greeting (the first generateReply must process the whole system prompt).
+     *  Absent → the SDK falls back to an LLM-generated greeting. */
+    readonly greeting?: string;
+    /** Agent-level Instructions (the routing/decision layer): plain-language guidance
+     *  for WHEN the agent acts, appended below the persona under a `# Routing` header.
+     *  Interpolated with {{ }} by the process runtime. Optional. */
+    readonly routingInstructions?: string;
+    /** Capability tags surfaced in the dashboard. */
+    readonly capabilities?: readonly string[];
+    /** Semantic version. Defaults to AGENT_VERSION env or '0.0.0'. */
+    readonly version?: string;
+    /** dev / stg / prd. Defaults to AGENT_ENVIRONMENT env or 'dev'. */
+    readonly environment?: AgentEnvironment;
+    readonly process?: ProcessDefinition<TProcess>;
+    readonly triggers?: Readonly<Record<string, TriggerDefinition>>;
+    readonly handoff?: HandoffConfig;
+    readonly memory?: MemoryConfig;
+    readonly participants?: ParticipantsConfig;
+    readonly connectors?: Readonly<Record<string, ConnectorInstance>>;
+    readonly compliance?: readonly ComplianceTag[];
+    readonly models?: ModelConfig;
+    readonly outbound?: OutboundCallConfig;
+    readonly speech?: SpeechConfig;
+    readonly endCall?: EndCallPolicy;
+    readonly tools?: Readonly<Record<string, ToolDefinition>>;
+    /** Per-agent registry-tool scoping (stored ToolBinding names, applied at
+     *  boot). Non-empty → only these dashboard HTTP tools attach; absent/[] →
+     *  every enabled registry tool attaches (the historical default). */
+    readonly toolBindings?: readonly string[];
+    readonly security?: SecurityConfig;
+    /** Output content-moderation guard (P5). When set, each assistant turn is
+     *  inspected and a violation is recorded as an engine.guard.blocked event on
+     *  the call timeline. OBSERVE-ONLY on voice — it audits, it does not unsay a
+     *  spoken turn. Absent → no guard. */
+    readonly guard?: GuardConfig;
+    /**
+     * Per-call ConsultationPolicy used by the built-in `ask_host` tool. When
+     * omitted the SDK uses the contract defaults (30s per-consult, 120s
+     * cumulative). Plan-first calls override this at boot from
+     * `plan.draftConfig.consultation`. See
+     * packages/contracts/src/consultation.ts for the schema + semantics.
+     */
+    readonly consultation?: ConsultationPolicy;
+    /**
+     * Use your existing text agent as the LLM. When set (and `models.llm` is
+     * unset), defineAgent wires the pipeline's LLM slot to this function: the
+     * caller's STT transcript is passed to `onQuery`, and its returned text (or
+     * streamed pieces) is spoken by TTS. The "two lines, keep your stack" path.
+     *
+     * Equivalent to `models: { llm: connector.llm({ onQuery }) }`. For a remote
+     * brain instead, use `connector.llm({ url })` (direct) or a tunnel transport.
+     * See docs/specs/voice-brain-connector/.
+     */
+    readonly onQuery?: OnQuery;
+    readonly onUtterance?: (text: string, ctx: AgentContext) => Promise<void> | void;
+    readonly onFieldCaptured?: (field: string, value: unknown, ctx: AgentContext) => Promise<void> | void;
+    readonly onCallEnd?: (outcome: CallOutcomeSummary, ctx: AgentContext) => Promise<void> | void;
+    readonly onEvent?: (event: AgentLifecycleEvent) => void;
+    /** Replace the default conversation loop. The SDK does NOT auto-greet. */
+    readonly onCall?: (ctx: AgentContext) => Promise<void>;
+    readonly readiness?: readonly ReadinessProbe[];
+    /**
+     * Run as a remote-controlled (puppet) agent: no autonomous LLM loop, no
+     * process/triggers pipeline. STT utterances are still published to
+     * `call-events:{callId}` via the existing transcript-segments sync, and
+     * the SDK subscribes to `call-control:{room}` to receive `say`,
+     * `hangup`, `dtmf` commands from an external driver (typically the MCP
+     * server invoked by a coding agent).
+     *
+     * When this is on, `process`, `triggers`, `onUtterance`, `onCall` are
+     * ignored. `tools`, `connectors`, `memory` still work.
+     */
+    readonly puppetMode?: boolean;
+    /**
+     * Host-controlled autonomous agent (the "smart puppet"). UNLIKE puppetMode,
+     * the agent keeps its REAL LLM and drives the conversation itself from its
+     * prompt (the per-call `intent` is appended at boot). Since 0.2.0 EVERY
+     * agent listens on its call's control channel (the MCP host can interject
+     * with `say`, `hangup` or send `dtmf`, and answer `ask_host`), so this flag
+     * now only shapes turn handling for a host-driven call. Use this for an agent that takes a customer's
+     * intent and runs the call like a human secretary, asking the host for any
+     * info it's missing. Mutually exclusive in spirit with puppetMode (which is
+     * the older NoOp "dumb mouth").
+     */
+    readonly hostControlled?: boolean;
+    /** When set, this agent boots each call from a deployed flow's process_schema. */
+    readonly flowRuntime?: FlowRuntimeConfig;
+    /**
+     * Opt a hand-coded (non-flow) agent into the dashboard-driven pipeline: on
+     * each call the SDK fetches this agent's PUBLISHED configuration (a saved
+     * dashboard draft applies only once the owner publishes it) and applies
+     * the operator-selected voice / model / STT over the coded defaults. The
+     * pipeline *mode* (cascade vs realtime) stays pinned to what the code
+     * declares — a stale `mode=realtime` in the dashboard can't flip a
+     * cascade-only worker. Flow agents (`flowRuntime`) get this implicitly and
+     * may additionally switch mode; this flag is the SDK opt-in. The agent id is
+     * read from dispatch metadata (the inbound router injects it from
+     * phone_numbers.agentId), so it's a no-op for calls without one.
+     */
+    readonly pipelineFromConfig?: boolean;
+    /**
+     * Opt this agent into MCP-layer visibility. When true, on register the API
+     * also writes an `agent_config` row keyed by (project_id, name,
+     * environment) so MCP / dashboard / REST can list and inspect this agent
+     * (and, post-step-7, drive call_say / call_send_guidance / etc against
+     * its live calls).
+     *
+     * Defaults to true so newly-registered agents show up in dashboards and
+     * MCP-host listings without opt-in. Pass `false` for autonomous-only
+     * agents that should stay invisible to MCP. See
+     * docs/architecture/contracts-design.md §2b.
+     */
+    readonly mcpExposed?: boolean;
+}
+interface CallOutcomeSummary {
+    readonly reason: 'completed' | 'handoff' | 'caller_hung_up' | 'agent_hung_up' | 'error';
+    readonly durationMs: number;
+    readonly processCompleted: boolean;
+    readonly fieldsCaptured: number;
+    readonly handoffOccurred: boolean;
+}
+/**
+ * Identity helper that gives users a typed `defineProcess` entry point with
+ * full inference on `onComplete`'s `data` argument.
+ *
+ *   defineProcess({
+ *     collect: { name: { type: 'string', required: true } },
+ *     onComplete: (data) => { data.name // string },
+ *   })
+ */
+declare function defineProcess<T extends Record<string, ProcessField>>(def: ProcessDefinition<T>): ProcessDefinition<T>;
+
 /** What the agent passes into recordEvent — id/at filled in by the runtime. */
 interface RecordEventInput {
     readonly kind: string;
     readonly source?: ProcessLifecycleEvent['source'];
     readonly data?: Record<string, unknown>;
 }
+/** What the current step (a flow's graph step) tells the extractor about a caller turn. Absent ⇒ no step (a plain
+ *  agent): every field the caller may say is extracted, as before. */
+interface IngestOptions {
+    /** The phone / number field the step is collecting — its value may be split across this step's turns (G-26). */
+    readonly numberField?: string;
+    /** The fields the step names (an ask's slot, the slots an llm step's exits read, a playbook's required fields).
+     *  Before the completion gate every field the caller may say is extracted (volunteered out of order counts); after
+     *  it, only these — a confirm's "yes" costs no extractor call. A value the caller gave for a field named here
+     *  changes only on an explicit correction; a value the flow set is open. (process-completion.test.ts) */
+    readonly stepFields?: readonly string[];
+    /** The field the step just asked the caller for — this turn is the answer. The extractor runs first, as for any
+     *  field; when it returns nothing for a free-text field (a `string` with no pattern or enum, the caller may say it:
+     *  a message, a name, notes, a reason) and the turn isn't filler ("Yes, please.", "Okay."), the turn itself is the
+     *  value — so caller text the model refuses as an instruction ("this is a test, please ignore") is still captured,
+     *  at no extra model call. (burn-down G-26, owner retest 2026-10-02; flow-graph-free-text.test.ts) */
+    readonly answering?: string;
+}
 interface ProcessRuntime {
     /** Add field-collection guidance to the system prompt. */
     augmentPrompt(basePrompt: string): string;
     /** Run on each finalized caller utterance. */
-    ingest(utterance: string, ctx: AgentContext): Promise<void>;
+    ingest(utterance: string, ctx: AgentContext, opts?: IngestOptions): Promise<void>;
+    /** A declared field, as a step needs to know it (absent for an unknown field, and on a runtime with no fields):
+     *  its type; free text (a `string`, no pattern, no enum); whether the caller may say it (not `fromCaller: false`). */
+    fieldInfo?(name: string): {
+        readonly type: ProcessField['type'];
+        readonly freeText: boolean;
+        readonly fromCaller: boolean;
+    } | undefined;
+    /** Where a captured value came from: the caller's words (the extractor, or a free-text answer), or the agent (a set
+     *  node, a tool, prefill — captureField). Undefined when not captured. A model reads caller values fenced (§B.9). */
+    origin?(name: string): 'caller' | 'agent' | undefined;
     /** Read the current captured data bag (used by handoff briefings). */
     getData(): Record<string, unknown>;
-    /** True if the process completion gate has fired. */
+    /** True once the completion gate has been satisfied (and onComplete fired). Capture continues after it. */
     isComplete(): boolean;
     /**
      * Capture a field directly — bypasses the LLM extractor. Used by
@@ -1974,6 +2788,59 @@ interface ProcessRuntime {
     subscribe(listener: (snap: ProcessSnapshot$1) => void): () => void;
 }
 
+interface AgentToolSpec {
+    readonly name: string;
+    readonly description: string;
+    readonly input: Record<string, 'string' | 'number' | 'boolean'>;
+}
+interface AgentToolCall {
+    readonly name: string;
+    readonly args: Record<string, unknown>;
+    readonly ok: boolean;
+    readonly status: number;
+    readonly data: unknown;
+}
+interface AgentTurnRequest {
+    /** Fully composed node prompt (goal + instructions + slots + gate status). */
+    readonly instructions: string;
+    /** In-node conversation so far (the runner is stateless across turns). */
+    readonly transcript: ReadonlyArray<{
+        readonly role: 'assistant' | 'user';
+        readonly text: string;
+    }>;
+    /** Registry tools scoped to this node. */
+    readonly tools: ReadonlyArray<AgentToolSpec>;
+    /** Named exits (the node's ports). Empty → the exit tool is not offered. */
+    readonly exits: ReadonlyArray<{
+        readonly id: string;
+        readonly description: string;
+    }>;
+    /** Slot names the exit tool may report as captured (fed back to the slot store). */
+    readonly captureVars: ReadonlyArray<string>;
+    /** Execute one scoped tool by name (the registry proxy). */
+    readonly runTool: (name: string, args: Record<string, unknown>) => Promise<{
+        ok: boolean;
+        status: number;
+        data: unknown;
+    }>;
+    readonly model?: string;
+    readonly temperature?: number;
+    readonly maxToolCalls?: number;
+}
+interface AgentTurnResult {
+    /** What to speak this turn ('' when the model exited without a closing line). */
+    readonly say: string;
+    /** Structured completion, when the model called the exit tool. */
+    readonly exit?: {
+        readonly port: string;
+        readonly vars: Record<string, string>;
+    };
+    /** Every tool invocation made this turn, in order. */
+    readonly toolCalls: ReadonlyArray<AgentToolCall>;
+}
+/** Run one caller-turn of the agent loop. null → unavailable/error (fail safe). */
+type AgentRunner = (req: AgentTurnRequest) => Promise<AgentTurnResult | null>;
+
 /** How the whole flow run finished. */
 type FlowOutcome = {
     readonly kind: 'completed';
@@ -1990,6 +2857,159 @@ type FlowOutcome = {
     readonly nodeId: string;
     readonly message: string;
 };
+/** Knowledge-base retrieval (rag node). Default impl POSTs /v1/knowledge/search. */
+type KnowledgeResolver = (q: {
+    readonly query: string;
+    readonly limit?: number;
+    readonly minScore?: number;
+    readonly filterMetadata?: Record<string, unknown>;
+}) => Promise<{
+    readonly found: boolean;
+    readonly chunks: ReadonlyArray<{
+        readonly content: string;
+        readonly score: number;
+        readonly metadata?: Record<string, unknown>;
+    }>;
+}>;
+/** Resolve a stored vault connection ref to auth headers (connection-auth tools).
+ *  Only used by the LOCAL fallback tool path; when a ToolExecutor is wired the
+ *  credential is resolved server-side and never reaches this worker. */
+type SecretResolver = (connectionRef: string) => Promise<{
+    ok: true;
+    headers: Record<string, string>;
+} | {
+    ok: false;
+    reason: string;
+}>;
+/** Execute a flow `tool` node's HTTP call SERVER-SIDE. The platform endpoint
+ *  renders the caller-controlled `{key}` placeholders, blocks private/loopback/
+ *  metadata hosts (SSRF), and attaches the vault credential AFTER the URL passes
+ *  the guard — so the credential never reaches this worker and a poisoned URL
+ *  can't exfiltrate it. Injected only when the worker holds the internal service
+ *  token; absent → the tool executor falls back to a local fetch (dev/self-host). */
+type ToolExecutor = (req: {
+    readonly name: string;
+    readonly url: string;
+    readonly method: string;
+    readonly headers?: Record<string, string>;
+    readonly input?: Record<string, unknown>;
+    readonly auth?: 'connection';
+    readonly connectionRef?: string;
+}) => Promise<{
+    readonly ok: boolean;
+    readonly status: number;
+    readonly data: unknown;
+}>;
+/** Evaluate a sandboxed code/expression node (server-side; never on the call path). */
+type CodeResolver = (src: {
+    readonly expression: string;
+    readonly scope: Record<string, unknown>;
+}) => Promise<{
+    ok: true;
+    outputs: Record<string, unknown>;
+    next?: string;
+} | {
+    ok: false;
+    error: string;
+}>;
+/** Silently pick one of a classify node's options (intent routing); returns the
+ *  chosen option id, or null if undecided. Default impl is a small LLM call. */
+type ClassifyResolver = (input: {
+    readonly instructions: string;
+    readonly options: ReadonlyArray<{
+        id: string;
+        label: string;
+    }>;
+    readonly lastUtterance?: string;
+    readonly slots: Record<string, unknown>;
+}) => Promise<string | null>;
+/** Resolve a reusable library playbook by name to the bits the playbook executor
+ *  needs: its instructions, the union of its exit conditions' required variables
+ *  (the completeness gate), and — when the library entry carries them — its tool
+ *  bindings and model knobs (all optional, additive). null when not found. */
+type PlaybookResolver = (name: string) => Promise<{
+    instructions: string;
+    requiredFields: string[];
+    tools?: string[];
+    model?: string;
+    temperature?: number;
+    exits?: Array<{
+        id: string;
+        description: string;
+    }>;
+} | null>;
+/** The project's HTTP-tools registry, scoped for the agent loop: list the tool
+ *  specs (for the LLM's schema) and execute one by NAME — execution proxies to
+ *  the server-side endpoint, so the URL/credential never reach this worker. */
+interface RegistryToolsResolver {
+    catalog(): Promise<ReadonlyArray<AgentToolSpec>>;
+    run(name: string, args: Record<string, unknown>): Promise<{
+        ok: boolean;
+        status: number;
+        data: unknown;
+    }>;
+}
+/** Resolve a reusable component (subflow node) by ref to a compiled FlowProgram the
+ *  interpreter can run inline. null when the referenced flow isn't found / unpublished
+ *  (the subflow executor then degrades to a recorded no-op and advances). */
+type FlowResolver = (ref: string) => Promise<FlowProgram | null>;
+/** Side-effect surface injected once by runFlowProgram. Every member is optional;
+ *  a missing resolver makes its executor degrade to a recorded no-op (never throws,
+ *  never blocks the call). Kept off AgentContext so the contract stays small and
+ *  executors stay unit-testable with fakes. */
+interface GraphResolvers {
+    readonly knowledge?: KnowledgeResolver;
+    readonly secrets?: SecretResolver;
+    /** Server-side SSRF-guarded HTTP tool executor (tool node). When present the
+     *  tool executor routes through it instead of fetching locally. */
+    readonly toolExecutor?: ToolExecutor;
+    readonly code?: CodeResolver;
+    readonly classify?: ClassifyResolver;
+    readonly playbooks?: PlaybookResolver;
+    readonly flows?: FlowResolver;
+    /** LLM-with-tools loop for agent (playbook) nodes with tool scope. */
+    readonly agentRunner?: AgentRunner;
+    /** Name-referenced project tool registry (catalog + server-side execute). */
+    readonly registryTools?: RegistryToolsResolver;
+}
+
+/** A library playbook as GET /v1/playbooks (and the API's PlaybooksService) lists it — the fields a flow reads. */
+interface PlaybookLibraryEntry {
+    readonly name: string;
+    readonly instructions?: string;
+    readonly model?: string | null;
+    readonly temperature?: number | null;
+    readonly tools?: ReadonlyArray<string | {
+        readonly toolName?: string;
+    }>;
+    readonly exitConditions?: ReadonlyArray<{
+        readonly id?: string;
+        readonly name?: string;
+        readonly description?: string;
+        readonly requiredVariables?: readonly string[];
+    }>;
+}
+/** What a playbook step needs from a library entry: its instructions + the union of its exit conditions' required
+ *  variables (the completeness gate), and — when the entry carries them — tool bindings, model knobs, exits. One
+ *  mapping for the voice worker (over HTTP) and a host that reads its own library (the API's text engine). */
+declare function toPlaybookResolution(pb: PlaybookLibraryEntry): NonNullable<Awaited<ReturnType<PlaybookResolver>>>;
+
+type HostLookup = (hostname: string) => Promise<ReadonlyArray<{
+    readonly address: string;
+    readonly family: number;
+}>>;
+/**
+ * Turn the private-network opt-in off for this whole process, for good. A host running OTHER people's flows (the
+ * VoiceLayer API's text engine) calls this at boot: there, a private address is the platform's own network, whatever
+ * an author wrote. There is deliberately no way to turn it back on.
+ */
+declare function denyPrivateNetwork(): void;
+/**
+ * Whether an author's `allowPrivateNetwork` from a stored schema (a schema tool, a backendAck) is honoured in this
+ * process. It takes a POSITIVE opt-in by whoever runs the worker — `VL_ALLOW_PRIVATE_NETWORK=1` — never the absence of
+ * something; and never on a platform worker (INTERNAL_SERVICE_TOKEN) or after denyPrivateNetwork().
+ */
+declare function privateNetworkOptInHonoured(): boolean;
 
 /**
  * Run `fn` with `client` as the internal helpers' OpenAI client. The scope follows the async work `fn` starts (an
@@ -2023,6 +3043,18 @@ interface RunTextSessionOptions {
     /** Fires when the interpreter finishes a turn and blocks for the next user
      *  message — the per-turn boundary used by the live driver below. */
     readonly onAwaitInput?: () => void;
+    /**
+     * The project-scoped services the flow's data steps call (tool / rag / subflow / playbook / registry tool), built by
+     * the host for the conversation's project. A step whose resolver is absent records why and takes its no-op path. A
+     * multi-tenant host MUST pass a `toolExecutor` (its server-side SSRF-guarded executor): without one a tool step
+     * fetches from this process — guarded (safe-fetch.ts), but with no connection auth and none of the host's audit.
+     */
+    readonly resolvers?: GraphResolvers;
+    /**
+     * `false` — this host runs other people's flows: no step may reach a private address, whatever an author opted
+     * into. Applies to the whole process and can't be undone (denyPrivateNetwork); there is no `true`.
+     */
+    readonly allowPrivateNetwork?: false;
 }
 interface TextSession {
     /** Feed an inbound user message (a final turn). */
@@ -2050,6 +3082,8 @@ interface RunTextTranscriptOptions {
     readonly generate?: (instructions?: string) => Promise<string>;
     readonly call?: RunTextSessionOptions['call'];
     readonly maxSteps?: number;
+    readonly resolvers?: GraphResolvers;
+    readonly allowPrivateNetwork?: false;
 }
 interface TextTranscriptResult {
     readonly replies: readonly string[];
@@ -2096,4 +3130,4 @@ type RunLiveTextOptions = Omit<RunTextSessionOptions, 'onAgentText' | 'onAwaitIn
  *  interpreter blocks for the next message, or the flow ends. */
 declare function runLiveTextConversation(opts: RunLiveTextOptions): LiveTextConversation;
 
-export { type UserStateEvent as $, AgentDTO as A, type SessionEvent as B, type CallInfo as C, type DtmfEvent as D, type EndCallControllerHandle as E, type FakeSessionAdapter as F, type SessionEventMap as G, type SessionFactory as H, type InboundOptions as I, type SessionFactoryInput as J, type SessionOutbound as K, LK_AGENT_STATE_MAP as L, type MemoryHandle as M, NON_BUSY_STATES as N, type SessionState as O, type Participant as P, type SpeechResult as Q, type RespondOptions as R, type SayOptions as S, type SpeechTarget as T, type StateChangeEvent as U, type TextSession as V, type TextTranscriptResult as W, type TtsVoiceConfig as X, type TurnEvent as Y, type Unsubscribe as Z, type UserInputEvent as _, AgentStatus as a, type UserTurn as a0, applySpeechTurnHandling as a1, dtmfCodeToDigit as a2, dtmfDigitToCode as a3, duck as a4, mute as a5, normalizeState as a6, passthrough as a7, runTextSession as a8, runTextTranscript as a9, transform as aa, type GraphTraceEvent as ab, type LiveTextConversation as ac, type LiveTurnResult as ad, type RunLiveTextOptions as ae, runLiveTextConversation as af, runWithOpenAIScope as ag, AgentEnvironment as b, type AgentContext as c, ProcessSchemaDTO as d, type AgentTurnEvent as e, type AudioProfile as f, type AudioSurface as g, type ChannelKind as h, type DtmfHandler as i, type EndCallOutcome as j, type FloorControlConfig as k, type MetricsEvent as l, ParticipantId as m, type ParticipantKind as n, type ParticipantSet as o, type ProcessSnapshot as p, type Room as q, type RouteEntry as r, type RoutingRule as s, type RoutingSnapshot as t, type RunTextSessionOptions as u, type RunTextTranscriptOptions as v, type SendDtmfOptions as w, type SessionAdapter as x, type SessionCapabilities as y, type SessionErrorEvent as z };
+export { NON_BUSY_STATES as $, AgentEnvironment as A, type DtmfHandler as B, type ConnectorInstance as C, type DtmfEvent as D, type EndCallControllerHandle as E, type EndCallInfo as F, type EndCallOutcome as G, type HandoffConfig as H, type EndCallPolicy as I, type EndCallTrigger as J, type EndpointingConfig as K, type LLMProvider as L, type ModelConfig as M, type FakeSessionAdapter as N, type FloorControlConfig as O, ProcessSchemaDTO as P, type InboundOptions as Q, type ReadinessProbe as R, type STTProvider as S, type TTSProvider as T, type InferProcessData as U, type VADProvider as V, type InterruptionConfig as W, LK_AGENT_STATE_MAP as X, type MemoryHandle as Y, type MemoryScope as Z, type MetricsEvent as _, type AgentLifecycleEvent as a, urlProbe as a$, type Participant as a0, ParticipantId as a1, type ParticipantKind as a2, type ParticipantSet as a3, type ParticipantsConfig as a4, type ProcessBackendAck as a5, type ProcessFieldType as a6, type ProcessSnapshot as a7, type ReadinessReport as a8, type ReadinessResult as a9, type TriggerAction as aA, type TriggerCondition as aB, type TtsVoiceConfig as aC, type TurnEvent as aD, type Unsubscribe as aE, type UserInputEvent as aF, type UserStateEvent as aG, type UserTurn as aH, VoiceLayerAuthError as aI, VoiceLayerError as aJ, VoiceLayerHttpError as aK, VoiceLayerNetworkError as aL, VoiceLayerValidationError as aM, applySpeechTurnHandling as aN, asyncProbe as aO, defineProcess as aP, dtmfCodeToDigit as aQ, dtmfDigitToCode as aR, duck as aS, envProbe as aT, mute as aU, normalizeState as aV, passthrough as aW, runProbes as aX, runTextSession as aY, runTextTranscript as aZ, transform as a_, type RespondOptions as aa, type Room as ab, type RouteEntry as ac, type RoutingRule as ad, type RoutingSnapshot as ae, type RunTextSessionOptions as af, type RunTextTranscriptOptions as ag, type SayOptions as ah, type SecurityConfig as ai, type SendDtmfOptions as aj, type SessionAdapter as ak, type SessionCapabilities as al, type SessionErrorEvent as am, type SessionEvent as an, type SessionEventMap as ao, type SessionFactory as ap, type SessionFactoryInput as aq, type SessionOutbound as ar, type SessionState as as, type ShorthandPrimitive as at, type SpeechResult as au, type SpeechTarget as av, type StateChangeEvent as aw, type TextSession as ax, type TextTranscriptResult as ay, type ToolInputShape as az, AgentDTO as b, type FlowResolver as b0, type GraphResolvers as b1, type GraphTraceEvent as b2, type KnowledgeResolver as b3, type LiveTextConversation as b4, type LiveTurnResult as b5, type PlaybookLibraryEntry as b6, type PlaybookResolver as b7, type RegistryToolsResolver as b8, type RunLiveTextOptions as b9, denyPrivateNetwork as ba, privateNetworkOptInHonoured as bb, runLiveTextConversation as bc, runWithOpenAIScope as bd, toPlaybookResolution as be, type AgentEventEmitter as c, type AgentContext as d, type AgentConfig as e, type ProcessField as f, type ProviderFactory as g, type RealtimeProvider as h, type TurnDetectorProvider as i, type ProcessDefinition as j, type TriggerDefinition as k, type MemoryConfig as l, type ToolDefinition as m, type SpeechConfig as n, type ToolExecutor as o, type HostLookup as p, type AgentEventListener as q, type AgentTurnEvent as r, type AudioProfile as s, type AudioSurface as t, type CallInfo as u, type CallOutcomeSummary as v, type ChannelKind as w, type CompletionStrategy as x, type ComplianceTag as y, ConsultationPolicy as z };