@moureau/pipeflow 0.0.1 → 0.0.3

package/dist/types/conversations/orchestration/coordination/coordination.d.ts

@@ -0,0 +1,192 @@
+import type { Agent } from "../../../agents/agent.js";
+import type { LLM, LLMMessage, LLMToolDefinition } from "../../../providers/llm/types.js";
+/**
+ * One task delegated to an agent: a self-contained prompt for a roster member.
+ */
+export interface DelegatedTask {
+    agent: string;
+    prompt: string;
+}
+/**
+ * The outcome of a delegated agent run (or sub-coordination, via `error`).
+ */
+export interface DelegationResult {
+    agent: string;
+    text: string;
+    error?: string;
+}
+/** What a coordination's LLM may decide to do next. */
+export type DelegateAction = {
+    action: "agents";
+    tasks: DelegatedTask[];
+} | {
+    action: "coordination";
+    coordination: string;
+    input?: unknown;
+} | {
+    action: "clarify";
+    missing: string[];
+} | {
+    action: "user";
+    question: string;
+} | {
+    action: "complete";
+    output: string;
+};
+/**
+ * The runtime a coordination reasons against: the roster, every registered
+ * coordination, and the primitives for delegating work. Supplied by the
+ * orchestrator, so coordinations never couple to it directly.
+ */
+export interface CoordinationRuntime {
+    readonly agents: readonly Agent[];
+    readonly coordinations: readonly Coordination[];
+    /** Shared LLM used for coordination reasoning. */
+    readonly llm: LLM;
+    /** Shared conversation history, seeded into fresh runs. */
+    readonly history: readonly LLMMessage[];
+    /** Run one or more agents in parallel (text-only) and return their outputs. */
+    delegateAgentTasks(tasks: DelegatedTask[]): Promise<DelegationResult[]>;
+    /**
+     * Ask the user a question. Never returns: it throws `CoordinationSuspension`
+     * carrying the innermost frame, which the orchestrator catches to park the
+     * execution until the user answers.
+     */
+    askUser(frame: PendingFrame, question: string): Promise<never>;
+    /** Stream a delta to speech (TTS narration). */
+    onDelta(delta: string): void;
+    /** Flush pending narration (e.g. before delegating or suspending). */
+    flushSpeech(): void;
+    /** Speak a standalone sentence (e.g. a `complete` output). */
+    speak(sentence: string): void;
+    /** True once an interrupt/stop has cancelled this run. */
+    isCancelled(): boolean;
+    /** Throw if the run exceeded the coordination step budget. */
+    checkBudget(): void;
+}
+export interface CoordinationOptions {
+    name: string;
+    /** System prompt describing the coordination's reasoning role. */
+    prompt?: string;
+    /** Overrides the runtime's shared LLM for this coordination. */
+    llm?: LLM;
+    maxTokens?: number;
+    /** Hard wall-clock limit for a single run (including suspensions). */
+    maxDurationMs?: number;
+    /**
+     * Deterministic cap on user-question rounds per run (both the structured
+     * `clarify` action and open-ended `user` questions, across suspensions).
+     * Once exhausted, the coordination is told to state reasonable
+     * assumptions and complete. Defaults to 2.
+     */
+    maxQuestionRounds?: number;
+}
+/**
+ * A coordination registered in the orchestrator by name — the registry key
+ * is the coordination's name, so it is not repeated here.
+ */
+export type CoordinationRegistration = Omit<CoordinationOptions, "name">;
+/**
+ * Render a batched clarification question from the missing details, so the
+ * wording is deterministic regardless of how the model phrases the labels.
+ */
+export declare function renderClarifyQuestion(missing: string[]): string;
+/**
+ * The system prompt for a `clarify` coordination: a generic,
+ * domain-agnostic information-acquisition unit. It turns an underspecified
+ * request into a clear one by asking the user for missing details via the
+ * structured `clarify` action (batched), with a hard two-round cap enforced
+ * by the runtime. Register it alongside `understand`:
+ *
+ * ```ts
+ * coordinations: { clarify: { prompt: buildClarifyPrompt() } }
+ * ```
+ */
+export declare function buildClarifyPrompt(): string;
+/**
+ * The resumable state of one coordination invocation. Plain data so it can be
+ * parked in a `PendingExecution` while waiting for the user.
+ */
+export interface CoordinationState {
+    messages: LLMMessage[];
+    startedAt: number;
+    /** Everything the coordination has spoken so far, for the final record. */
+    narration: string;
+    /** How many user-question rounds this run has used (across suspensions). */
+    questionRounds: number;
+    /** Tool call id awaiting a sub-coordination result, for resume replies. */
+    pendingToolCallId?: string;
+}
+/** One frame of a suspended execution stack (outermost first). */
+export interface PendingFrame {
+    coordination: Coordination;
+    state: CoordinationState;
+}
+/** Thrown when a coordination asks the user; carries the whole frame stack. */
+export declare class CoordinationSuspension extends Error {
+    readonly frames: PendingFrame[];
+    readonly question: string;
+    constructor(frames: PendingFrame[], question: string);
+}
+/** Thrown when a coordination run is cancelled (interrupt/stop). */
+export declare class CoordinationCancelled extends Error {
+    constructor();
+}
+/** Thrown when a coordination exceeded its step or duration budget. */
+export declare class CoordinationBudgetExceeded extends Error {
+    constructor(detail: string);
+}
+/**
+ * The tool definition that lets a coordination's LLM choose the next execution
+ * target: agents (one or more, in parallel), another coordination, the user,
+ * or completion.
+ *
+ * The parameters are deliberately FLAT (action enum + optional fields) even
+ * though the parser enforces a discriminated union per action. Why: Amazon
+ * Bedrock (nova) ignores `oneOf` in tool input schemas, which makes the tool
+ * effectively empty — the model stops calling it and answers directly instead
+ * (measured: 0/2 tool calls and ~5k-token essays vs reliable ~1s calls with
+ * the flat shape). The flat schema works across every provider tested; the
+ * discriminated contract is enforced when the call is parsed, and an invalid
+ * combination costs one bounded retry rather than a broken tool.
+ */
+export declare function delegateToolDefinition(agents: readonly Agent[], coordinations: readonly Coordination[]): LLMToolDefinition;
+export declare function parseDelegateAction(argumentsJson: string, agents: readonly Agent[], coordinations: readonly Coordination[]): DelegateAction;
+/**
+ * A hardcoded reasoning/control-flow unit. Unlike an `Agent` (input → LLM →
+ * output), a coordination decides *what should happen next*: run agents, pass
+ * work to another coordination, ask the user, or complete. Definitions are
+ * stateless; each invocation carries its own `CoordinationState`, which can be
+ * parked (suspended) while waiting for the user and resumed later.
+ */
+export declare class Coordination {
+    readonly name: string;
+    readonly prompt: string;
+    readonly maxTokens: number | undefined;
+    readonly maxDurationMs: number | undefined;
+    readonly maxQuestionRounds: number;
+    private readonly runtime;
+    private readonly llm;
+    private cachedToolDefinition;
+    private cachedSchema;
+    constructor(options: CoordinationOptions, runtime: CoordinationRuntime);
+    /** The delegate tool definition, generated once from the roster. */
+    private toolDefinition;
+    /** Parse a `delegate` tool call against the roster's strict schema. */
+    private parseDelegate;
+    /** Run the coordination with fresh state (seeded with the shared history). */
+    run(input?: unknown): Promise<unknown>;
+    /** Resume a suspended state with the user's answer. */
+    resume(state: CoordinationState, answer: string): Promise<unknown>;
+    /** Continue a suspended state with an injected message (e.g. a sub-result). */
+    continueWith(state: CoordinationState, message: LLMMessage): Promise<unknown>;
+    /**
+     * The coordination loop: one LLM round trip per iteration, choosing the next
+     * execution target via the `delegate` tool. Throws `CoordinationSuspension`
+     * when asking the user; the state carried in the suspension is resumable.
+     */
+    private loop;
+    /** Delegate to a sub-coordination, attaching this frame on suspension. */
+    private delegateToCoordination;
+    private completeOutput;
+}

package/dist/types/conversations/orchestration/coordination/index.d.ts

@@ -0,0 +1,2 @@
+export { Coordination, CoordinationSuspension, CoordinationCancelled, CoordinationBudgetExceeded, delegateToolDefinition, parseDelegateAction, } from "./coordination.js";
+export type { CoordinationOptions, CoordinationRuntime, CoordinationState, DelegateAction, DelegatedTask, DelegationResult, PendingFrame, } from "./coordination.js";

package/dist/types/conversations/orchestration/orchestrator/coordination-runner/coordination-runner.d.ts

@@ -0,0 +1,108 @@
+import type { Agent } from "../../../../agents/agent.js";
+import type { Conversation } from "../../../conversation/conversation.js";
+import type { LLM } from "../../../../providers/llm/types.js";
+import type { Turn } from "../../../types.js";
+import { Coordination, type CoordinationRegistration, type CoordinationRuntime } from "../../coordination/coordination.js";
+import { ConversationHistory } from "../history/history.js";
+import type { GenerationRunner } from "../generation/generation.js";
+import type { SpeechPipeline } from "../speech/speech.js";
+import type { ToolCallManager } from "../tools/tools.js";
+export interface CoordinationRunnerOptions {
+    conversation: Conversation;
+    /** Live roster accessor (read at coordination-run time). */
+    agents(): Agent[];
+    /** Live shared-LLM accessor (undefined in transcription-only mode). */
+    llm(): LLM | undefined;
+    /** The conversation's message log, seeded into fresh coordination runs. */
+    history: ConversationHistory;
+    historyWindow: Parameters<ConversationHistory["windowed"]>[0];
+    speech: SpeechPipeline;
+    generation: GenerationRunner;
+    tools: ToolCallManager;
+    /** Safety bound on LLM reasoning steps per coordination execution. */
+    maxCoordinationSteps: number;
+    maxToolIterations: number;
+    temperature?: number;
+    maxTokens?: number;
+    /** The orchestrator's current generation epoch (bumped on interrupt/stop). */
+    currentEpoch(): number;
+    /** True while the orchestrator is started and the epoch is current. */
+    isCurrent(epoch: number): boolean;
+}
+/**
+ * The application-specific execution of coordinations: binds the generic
+ * `Coordination` primitives to the orchestrator's machinery (roster, shared
+ * LLM, history, speech, delegation, budgets, cancellation) and owns the
+ * suspension/resume lifecycle — the parked frame stack, the step budget, and
+ * the coordination generation records.
+ */
+export declare class CoordinationRunner {
+    /** Coordinations registered by name (the key is the coordination's name). */
+    readonly coordinations: Record<string, Coordination>;
+    /** The built-in `understand` coordination, when one is active. */
+    understand: Coordination | null;
+    private readonly conversation;
+    private readonly agents;
+    private readonly llm;
+    private readonly history;
+    private readonly historyWindow;
+    private readonly speech;
+    private readonly generation;
+    private readonly tools;
+    private readonly maxCoordinationSteps;
+    private readonly maxToolIterations;
+    private readonly temperature;
+    private readonly maxTokens;
+    private readonly currentEpoch;
+    private readonly isCurrent;
+    private coordinationEpoch;
+    private coordinationStepCount;
+    private coordinationRunId;
+    private pendingExecution;
+    constructor(options: CoordinationRunnerOptions);
+    /**
+     * Register coordinations by name. The built-in `understand` runs unaddressed
+     * turns: it decides whether to delegate to agents, ask the user, or answer
+     * directly. Apps can override it by registering their own "understand" key,
+     * and add their own (e.g. clarify, review).
+     */
+    register(registrations: Record<string, CoordinationRegistration>, agents: readonly Agent[]): void;
+    /** True while a coordination is parked waiting for the user to answer. */
+    hasPending(): boolean;
+    /** Drop a parked execution (interrupt, stop). */
+    cancel(): void;
+    /**
+     * Run the built-in `understand` coordination on an unaddressed turn. A
+     * streaming generation is opened for the conversation's default agent; the
+     * coordination's final answer (or question) completes it.
+     */
+    runDefault(turn: Turn): Promise<void>;
+    /**
+     * Resume a parked coordination with the user's answer, propagating the
+     * result back up the frame stack to the outermost coordination.
+     */
+    resume(turn: Turn): Promise<void>;
+    /**
+     * The runtime the coordinations reason against. Binds the coordination
+     * primitives (delegate to agents, ask the user, speech, budget, cancellation)
+     * to the runner's machinery without coupling `Coordination` to it.
+     */
+    runtime(): CoordinationRuntime;
+    /** Complete the current generation and record the coordination's answer. */
+    private finalizeOutput;
+    /** Park a suspended coordination: record the question and store the stack. */
+    private recordSuspension;
+    /** Throw the suspension that parks a coordination waiting for the user. */
+    private askUser;
+    /** Enforce the per-execution reasoning step budget. */
+    private checkBudget;
+    private emitError;
+    /** Run delegated agent tasks in parallel and surface their work. */
+    private delegateAgentTasks;
+    /**
+     * Execute one dispatched task as a sub-generation: the target agent's own
+     * LLM, context, and tools, running text-only (no TTS). The final text is
+     * returned so the coordinator can merge it into the spoken answer.
+     */
+    private runSubGeneration;
+}

package/dist/types/conversations/orchestration/orchestrator/coordination-runner/index.d.ts

@@ -0,0 +1,2 @@
+export { CoordinationRunner } from "./coordination-runner.js";
+export type { CoordinationRunnerOptions } from "./coordination-runner.js";

package/dist/types/conversations/orchestration/orchestrator/generation/generation.d.ts

@@ -0,0 +1,60 @@
+import type { LLM, LLMToolCall, LLMToolDefinition, LLMMessage } from "../../../../providers/llm/types.js";
+import type { ResolvedToolCall } from "../tools/tools.js";
+export interface GenerationRequest {
+    /** Display name stamped on assistant tool-call messages. */
+    agentName: string;
+    llm: LLM;
+    /**
+     * The conversation messages; the loop appends the assistant tool-call
+     * message and the resolved tool results onto this array.
+     */
+    messages: LLMMessage[];
+    tools: LLMToolDefinition[];
+    temperature?: number;
+    maxTokens?: number;
+    /** Safety bound on tool-call round trips per generation. */
+    maxToolIterations: number;
+    /** False once the run is stale (interrupt/stop); aborts the loop. */
+    isCurrent(): boolean;
+    /**
+     * Whether outgoing messages keep per-agent `name` fields on system and
+     * assistant messages. Multi-agent conversations need them so the model can
+     * tell which agent said what in the shared history. Single-agent
+     * conversations drop them: with one agent the names carry no information,
+     * and some providers render a message `name` as a role header ("Scout:")
+     * that weaker models imitate — every reply then starts by speaking the
+     * agent's name. Default true.
+     */
+    agentNames?: boolean;
+    /** Streamed text; `textBefore` is the running text prior to this delta. */
+    onDelta?(delta: string, textBefore: string): void;
+    /** Hand tool calls to the application and resolve their results. */
+    resolveToolCalls(calls: LLMToolCall[]): Promise<ResolvedToolCall[]>;
+}
+export type GenerationStatus = "done" | "interrupted" | "error";
+export interface GenerationOutcome {
+    /** Everything the model produced (or produced before failing). */
+    text: string;
+    status: GenerationStatus;
+    /** The provider error, when `status` is "error". */
+    error?: unknown;
+    /**
+     * How many tool rounds were resolved before the run ended (only present
+     * when at least one). Lets callers retry a no-output failure safely:
+     * re-running a generation whose tools already executed would repeat their
+     * side effects.
+     */
+    toolRounds?: number;
+}
+/**
+ * Owns the LLM tool loop shared by top-level generations and delegated
+ * sub-generations: stream deltas, collect tool calls, resolve them through
+ * the application, and repeat up to `maxToolIterations`.
+ *
+ * It is deliberately ignorant of the conversation lifecycle — persistence,
+ * transcripts, speech, and history are the caller's concern, decided from
+ * the returned `GenerationOutcome`.
+ */
+export declare class GenerationRunner {
+    run(request: GenerationRequest): Promise<GenerationOutcome>;
+}

package/dist/types/conversations/orchestration/orchestrator/generation/index.d.ts

@@ -0,0 +1,2 @@
+export { GenerationRunner } from "./generation.js";
+export type { GenerationOutcome, GenerationRequest, GenerationStatus, } from "./generation.js";

package/dist/types/conversations/orchestration/orchestrator/history/history.d.ts

@@ -0,0 +1,62 @@
+import type { Conversation } from "../../../conversation/conversation.js";
+import type { Generation, Participant, Turn } from "../../../types.js";
+import type { LLMMessage } from "../../../../providers/llm/types.js";
+/**
+ * A human-readable "now" stamp appended to dispatched prompts so
+ * time-sensitive tasks (flights, meetings, deadlines) have temporal context.
+ */
+export declare function formatTimeContext(date?: Date): string;
+/**
+ * A short context suffix appended automatically to every user turn, so the
+ * model knows the time and who is speaking (and who else is in the
+ * conversation) — e.g. "enhance the message I just sent" resolves to a real
+ * user id. Applied once, when the turn enters history; every generation path
+ * (direct, coordination, delegated) seeds from that history.
+ */
+export declare function formatTurnContext(participant: Participant, participants: readonly Participant[], date?: Date): string;
+/** How much conversational history an LLM request may carry. */
+export interface HistoryWindow {
+    /** Keep at most this many user turns (the current turn is always kept). */
+    maxTurns: number;
+    /** Drop oldest whole messages until the window fits this many characters. */
+    maxChars: number;
+}
+/**
+ * Bounds conversation history for an LLM request: keep the most recent
+ * `maxTurns` user turns (plus anything after them), then drop oldest whole
+ * messages until the window fits `maxChars`. The current turn is the last
+ * user message and always survives. Provider TTFT grows with input size, so
+ * a bounded window keeps requests in the fast regime.
+ */
+export declare function windowHistory(history: LLMMessage[], { maxTurns, maxChars }: HistoryWindow): LLMMessage[];
+/**
+ * The conversation's LLM message log: every user turn and agent reply, plus
+ * the turn-context formatting and windowing applied when a request is built.
+ * The orchestrator's `Conversation` remains the source of truth for turns,
+ * transcripts, and generations — this is the derived prompt log only.
+ */
+export declare class ConversationHistory {
+    private readonly messages;
+    /**
+     * The user-message form of a turn: display name, text, and the automatic
+     * context suffix (time + speaker + roster) baked in at history time.
+     */
+    turnMessage(turn: Turn, conversation: Conversation): string;
+    /** Append a participant turn as a user message. */
+    addUserTurn(turn: Turn, conversation: Conversation): void;
+    /** Append an agent reply as an assistant message. */
+    addAssistant(agentName: string, text: string): void;
+    /**
+     * Rehydrate from persisted turns and completed top-level generations.
+     * Sub-generations are summarized inside the coordinator's own answer, so
+     * only top-level responses rehydrate into history.
+     */
+    rehydrate(turns: readonly Turn[], generations: readonly Generation[], conversation: Conversation): void;
+    /** The full message log. */
+    get all(): readonly LLMMessage[];
+    /**
+     * The message log bounded for an LLM request: the full log when `window`
+     * is `false`, otherwise the bounded window.
+     */
+    windowed(window: HistoryWindow | false): LLMMessage[];
+}

package/dist/types/conversations/orchestration/orchestrator/history/index.d.ts

@@ -0,0 +1 @@
+export { ConversationHistory, formatTimeContext, formatTurnContext, windowHistory, type HistoryWindow, } from "./history.js";

package/dist/types/conversations/orchestration/orchestrator/index.d.ts

@@ -1,2 +1,12 @@
 export { Orchestrator } from "./orchestrator.js";
 export type { OrchestratorOptions } from "./orchestrator.js";
+export { ConversationHistory, formatTimeContext, formatTurnContext, windowHistory, type HistoryWindow, } from "./history.js";
+export { buildUnderstandPrompt, findAddressedAgent, findAgentByName, pickAgent } from "./routing.js";
+export { GenerationRunner } from "./generation.js";
+export type { GenerationOutcome, GenerationRequest, GenerationStatus } from "./generation.js";
+export { SpeechPipeline } from "./speech.js";
+export type { SpeechPipelineOptions } from "./speech.js";
+export { ToolCallManager } from "./tools.js";
+export type { ResolvedToolCall } from "./tools.js";
+export { CoordinationRunner } from "./coordination-runner.js";
+export type { CoordinationRunnerOptions } from "./coordination-runner.js";

package/dist/types/conversations/orchestration/orchestrator/orchestrator.d.ts

@@ -4,67 +4,109 @@ import type { Persistence } from "../../../persistence/persistence.js";
 import type { LLM } from "../../../providers/llm/types.js";
 import type { STT } from "../../../providers/stt/types.js";
 import type { TTS } from "../../../providers/tts/types.js";
+import type { CoordinationRegistration } from "../coordination/coordination.js";
+import { type HistoryWindow } from "./history/history.js";
 export interface OrchestratorOptions {
     conversation: Conversation;
     /**
-     * The agent driving the realtime loop. Omit it for transcription-only
-     * mode (audio in, turns and transcripts out — no LLM or TTS required).
+     * The agents the orchestrator routes turns to. With more than one agent,
+     * unaddressed turns run through the built-in `understand` coordination,
+     * which can delegate to agents, ask the user, or answer directly. Omit
+     * for transcription-only mode (audio in, turns and transcripts out — no
+     * LLM or TTS required).
      */
-    agent?: Agent;
-    /** Defaults to the agent's LLM. */
+    agents?: Agent[];
+    /** Defaults to the first agent's LLM. */
     llm?: LLM;
-    stt: STT;
-    /** Required when an agent is attached. */
+    /** STT for voice turns. Omit for text-only conversations (`send()`). */
+    stt?: STT;
+    /** TTS for spoken output. Not required for text-only conversations. */
     tts?: TTS;
     /** Used to rehydrate conversation history on start. */
     persistence?: Persistence;
-    /** How long to wait for the application to resolve a tool call. */
+    /** How long to wait for a tool call to resolve (auto-executed or app-managed). */
     toolTimeoutMs?: number;
     /** Safety bound on tool-call round trips per generation. */
     maxToolIterations?: number;
+    /**
+     * Execute the agents' tools automatically (default `true`), feeding each
+     * tool's result — or a caught error — back into the model loop, like
+     * `Agent.run()` does. Set `false` for the application-managed contract:
+     * listen for `tool-call` events and resolve each call yourself with
+     * `conversation.resolveToolCall()`. The `tool-call` event fires in both
+     * modes, so apps can observe every call.
+     */
+    autoExecuteTools?: boolean;
+    /**
+     * Additional coordinations the runtime can delegate to, registered by
+     * name (the key is the coordination's name).
+     */
+    coordinations?: Record<string, CoordinationRegistration>;
+    /** Safety bound on LLM reasoning steps per coordination execution. */
+    maxCoordinationSteps?: number;
     temperature?: number;
     maxTokens?: number;
+    /**
+     * How much conversation history each LLM request carries (default
+     * `{ maxTurns: 5, maxChars: 4000 }` — provider TTFT grows with input size,
+     * and a bounded window keeps requests in the fast regime). Pass `false` to
+     * always send the full history.
+     */
+    historyWindow?: HistoryWindow | false;
+    /**
+     * How many TTS synthesis requests may be in flight at once (default 2).
+     * More lets the sentences of a multi-sentence reply synthesize in parallel
+     * (kills the gaps between them) at the cost of provider concurrency — some
+     * free TTS variants rate-limit concurrent requests. Passed through to the
+     * speech pipeline; see `SpeechPipelineOptions.maxConcurrentRequests`.
+     */
+    maxConcurrentTtsRequests?: number;
 }
 /**
- * The realtime conversation state machine.
+ * The realtime conversation state machine and multi-agent coordinator.
  *
- * Wires the conversation to the providers:
+ * Wires the conversation to the providers and routes each turn to an agent.
+ * The heavy machinery lives in focused collaborators — history, routing,
+ * generation, speech, tools, and coordination — so this class owns only the
+ * lifecycle and event wiring:
  *
  * ```text
- * audio-in ──► STT ──► turn ──► LLM ──► TTS ──► audio-out
- *                              │
- *                              └─► tool-call ──► app resolves ──► resume
+ * audio-in ──► STT ──► turn ──► coordinator ──► agent ──► LLM ──► TTS ──► audio-out
+ *                                    │
+ *                                    └─► tool-call ──► tool runs ──► resume
  * ```
  *
  * Deltas stream to TTS immediately (so the agent can narrate while a tool
- * runs), tool calls pause the generation until the application resolves
- * them, and interruptions cancel the current generation — discarding any
- * stale tool results or audio via a generation epoch.
+ * runs), tool calls pause the generation while the tool executes — the
+ * framework runs the agent's own tools by default, or the application
+ * resolves them when `autoExecuteTools` is off — and interruptions cancel
+ * the current generation, discarding any stale tool results or audio via a
+ * generation epoch.
  */
 export declare class Orchestrator {
     private readonly conversation;
-    private readonly agent;
+    private readonly agents;
     private readonly llm;
     private readonly stt;
     private readonly tts;
     private readonly persistence;
-    private readonly toolTimeoutMs;
     private readonly maxToolIterations;
+    private readonly historyWindow;
     private readonly temperature;
     private readonly maxTokens;
+    private readonly history;
+    private readonly speech;
+    private readonly tools;
+    private readonly generation;
+    private readonly coordination;
     private started;
     private generating;
     private epoch;
+    private generationChain;
     private readonly unsubscribers;
     private readonly sttSessions;
-    private readonly history;
-    private readonly toolWaiters;
-    private generationChain;
-    private speechChain;
-    private speechBuffer;
     private pendingTurns;
     private pendingGenerations;
-    private audioSequence;
     private turnSequence;
     constructor(options: OrchestratorOptions);
     /**
@@ -83,16 +125,11 @@ export declare class Orchestrator {
     private onFinal;
     private processTurn;
     private onInterrupt;
-    private onToolCallResult;
+    /** Cancel every LLM in play: the shared one and each agent's own. */
+    private stopLlms;
     private onProviderError;
     private queueGeneration;
     private generate;
     private runGeneration;
-    private resolveToolCalls;
-    private waitForToolResult;
-    private cancelToolWaiters;
-    private feedDelta;
-    private flushSpeech;
-    /** Synthesize a sentence and push the audio chunks out to the app. */
-    private speak;
+    private enqueueCoordinationRun;
 }

package/dist/types/conversations/orchestration/orchestrator/routing/index.d.ts

@@ -0,0 +1 @@
+export { buildUnderstandPrompt, findAddressedAgent, findAgentByName, pickAgent, } from "./routing.js";

package/dist/types/conversations/orchestration/orchestrator/routing/routing.d.ts

@@ -0,0 +1,19 @@
+import type { Agent } from "../../../../agents/agent.js";
+/**
+ * Pick the agent that should handle a turn.
+ *
+ * The first agent whose name or alias appears in the turn text wins;
+ * otherwise the first agent in the roster is the default. Matching is
+ * case-insensitive substring matching, so "ask the technical specialist"
+ * addresses an agent named "Technical Specialist" (or aliased "tech").
+ */
+export declare function pickAgent(agents: readonly Agent[], text: string): Agent | null;
+/**
+ * Like `pickAgent` but without the default: only returns an agent the turn
+ * explicitly addresses by name or alias.
+ */
+export declare function findAddressedAgent(agents: readonly Agent[], text: string): Agent | null;
+/** Resolve a task's agent by exact name or alias (case-insensitive). */
+export declare function findAgentByName(agents: readonly Agent[], nameOrAlias: string): Agent | null;
+/** The built-in coordinator: understands the request and decides what's next. */
+export declare function buildUnderstandPrompt(agents: readonly Agent[]): string;

package/dist/types/conversations/orchestration/orchestrator/speech/index.d.ts

@@ -0,0 +1,2 @@
+export { SpeechPipeline } from "./speech.js";
+export type { SpeechPipelineOptions } from "./speech.js";