@moureau/pipeflow 0.0.1 → 0.0.2

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,43 @@
+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;
+    /** 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;
+}
+/**
+ * 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,17 +4,23 @@ 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;
@@ -22,18 +28,35 @@ export interface OrchestratorOptions {
     toolTimeoutMs?: number;
     /** Safety bound on tool-call round trips per generation. */
     maxToolIterations?: number;
+    /**
+     * 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;
+    /**
+     * Bounds 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;
 }
 /**
- * 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 ──► app resolves ──► resume
  * ```
  *
  * Deltas stream to TTS immediately (so the agent can narrate while a tool
@@ -43,28 +66,28 @@ export interface OrchestratorOptions {
  */
 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 +106,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";

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

@@ -0,0 +1,49 @@
+import type { Conversation } from "../../../conversation/conversation.js";
+import type { TTS } from "../../../../providers/tts/types.js";
+export interface SpeechPipelineOptions {
+    /** TTS provider; omitted for text-only conversations. */
+    tts?: TTS;
+    conversation: Conversation;
+    /**
+     * True while the generation that produced the speech is still current.
+     * The captured generation epoch is passed back in, so an interrupt (epoch
+     * bump) or a stop drops queued and in-flight synthesis.
+     */
+    isCurrent(epoch: number): boolean;
+}
+/**
+ * Turns the LLM delta stream into speakable audio: expose the text stream
+ * semantically (`text-delta`), buffer sentences through the `TextChunker`,
+ * and synthesize each chunk through the TTS provider on a serial chain.
+ *
+ * Owns the chunker, the speech epoch (bumped by `stop()`), the synthesis
+ * chain, and the audio sequence — the orchestrator only decides *when*
+ * speech is current.
+ */
+export declare class SpeechPipeline {
+    private readonly tts;
+    private readonly conversation;
+    private readonly isCurrent;
+    private readonly chunker;
+    private speechEpoch;
+    private chain;
+    private audioSequence;
+    constructor(options: SpeechPipelineOptions);
+    /**
+     * Stream an LLM delta to the application and the TTS pipeline. Empty
+     * deltas (reasoning-only frames) are skipped so they never reach the
+     * text-delta event or the chunker.
+     */
+    feed(delta: string, epoch: number): void;
+    /** Speak any remaining buffered text as a final chunk. */
+    flush(epoch: number): void;
+    /** Synthesize a sentence and push the audio chunks out to the app. */
+    speak(sentence: string, epoch: number): void;
+    /**
+     * Stop the current TTS playback and drop buffered text without cancelling
+     * the generation (barge-in, interrupt, stop).
+     */
+    stop(): void;
+    /** Resolve when queued TTS synthesis has settled. */
+    waitForIdle(): Promise<void>;
+}

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

@@ -0,0 +1,2 @@
+export { ToolCallManager } from "./tools.js";
+export type { ResolvedToolCall } from "./tools.js";

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

@@ -0,0 +1,31 @@
+import type { Conversation } from "../../../conversation/conversation.js";
+import type { LLMToolCall } from "../../../../providers/llm/types.js";
+import type { ToolCallResult } from "../../../types.js";
+export interface ResolvedToolCall {
+    id: string;
+    name: string;
+    result?: unknown;
+    error?: string;
+}
+/**
+ * Tracks tool calls handed to the application and resolves them once the
+ * application reports back (or a timeout fires). Stale results — timed out,
+ * already resolved, or superseded by an interrupt — are dropped.
+ */
+export declare class ToolCallManager {
+    private readonly conversation;
+    private readonly timeoutMs;
+    private readonly waiters;
+    constructor(conversation: Conversation, timeoutMs: number);
+    /**
+     * Hand the calls to the application and resolve each one once it is
+     * answered or times out. Returns them in call order, with either a result
+     * or an error string.
+     */
+    resolveCalls(calls: LLMToolCall[]): Promise<ResolvedToolCall[]>;
+    /** Resolve a waiter from a `tool-call-result` event; stale results drop. */
+    handleResult(result: ToolCallResult): void;
+    /** Force-resolve every pending call (interrupt, stop). */
+    cancelAll(reason: string): void;
+    private wait;
+}

package/dist/types/conversations/orchestration/test-harness.d.ts

@@ -0,0 +1,96 @@
+import { Tool } from "../../agents/tools/tools.js";
+import { Conversation } from "../conversation/conversation.js";
+import { MemoryPersistence } from "../../persistence/adapters/memory/memory.js";
+import { Orchestrator } from "./orchestrator/orchestrator.js";
+import type { HistoryWindow } from "./orchestrator/history/history.js";
+import type { LLM, LLMEvent, LLMRequest } from "../../providers/llm/types.js";
+import type { STT, STTOptions, STTSession } from "../../providers/stt/types.js";
+import type { TTS, TTSRequest } from "../../providers/tts/types.js";
+export type LLMScript = (request: LLMRequest, signal: AbortSignal) => AsyncIterable<LLMEvent>;
+export declare class FakeLLM implements LLM {
+    private readonly script;
+    readonly requests: LLMRequest[];
+    readonly stopCalls: number[];
+    private readonly controllers;
+    constructor(script: LLMScript);
+    stream(request: LLMRequest): AsyncGenerator<LLMEvent>;
+    stop(): void;
+}
+export declare class FakeSTT implements STT {
+    readonly sessions: FakeSTTSession[];
+    readonly startOptions: STTOptions[];
+    start(options?: STTOptions): FakeSTTSession;
+    cancel(): void;
+}
+export type FakeSessionEvent = "partial" | "final" | "error";
+export declare class FakeSTTSession implements STTSession {
+    readonly written: Uint8Array[];
+    ended: number;
+    private readonly listeners;
+    write(audio: Uint8Array): void;
+    end(): Promise<void>;
+    on(event: "partial", listener: (transcript: string) => void): void;
+    on(event: "final", listener: (transcript: string) => void): void;
+    on(event: "error", listener: (error: Error) => void): void;
+    emitPartial(text: string): void;
+    emitFinal(text: string): void;
+    emitError(error: Error): void;
+}
+export declare class FakeTTS implements TTS {
+    private readonly chunksFor;
+    readonly requests: TTSRequest[];
+    private readonly controllers;
+    constructor(chunksFor: (text: string) => Uint8Array[]);
+    stream(request: TTSRequest): AsyncGenerator<Uint8Array>;
+    stop(): void;
+}
+/**
+ * A TTS that streams one chunk at a time with a delay, so audio is still
+ * mid-flight when an interrupt arrives.
+ */
+export declare class SlowTTS implements TTS {
+    private readonly chunksFor;
+    private readonly delayMs;
+    readonly requests: TTSRequest[];
+    private readonly controllers;
+    constructor(chunksFor: (text: string) => Uint8Array[], delayMs?: number);
+    stream(request: TTSRequest): AsyncGenerator<Uint8Array>;
+    stop(): void;
+}
+export type TtsHarness = FakeTTS | SlowTTS;
+export interface Harness {
+    conversation: Conversation;
+    orchestrator: Orchestrator;
+    llm: FakeLLM;
+    stt: FakeSTT;
+    tts: TtsHarness;
+    persistence: MemoryPersistence;
+}
+export declare function setup(options: {
+    script: LLMScript;
+    ttsChunks?: (text: string) => Uint8Array[];
+    tts?: TtsHarness;
+    tools?: Tool<never, unknown>[];
+    toolTimeoutMs?: number;
+    context?: string;
+    /** Inject a real LLM (e.g. an adapter over a mocked fetch) instead of a scripted fake. */
+    llm?: LLM;
+    /** Override the conversation-history window (default 5 turns / 4k chars). */
+    historyWindow?: HistoryWindow | false;
+}): Promise<Harness>;
+export declare function waitFor(condition: () => boolean, timeoutMs?: number): Promise<void>;
+export declare function speak(harness: Harness, userId: string, text: string): Promise<void>;
+export declare function respond(text: string): LLMScript;
+export type RosterHarness = Harness & {
+    llms: Map<string, FakeLLM>;
+};
+export declare function setupRoster(options: {
+    coordinatorScript: LLMScript;
+    scripts: Record<string, LLMScript>;
+    tools?: Record<string, Tool<never, unknown>[]>;
+    coordinations?: Record<string, {
+        prompt: string;
+        llm: FakeLLM;
+    }>;
+    maxCoordinationSteps?: number;
+}): Promise<RosterHarness>;

package/dist/types/conversations/orchestration/text-chunker/index.d.ts

@@ -0,0 +1 @@
+export * from './text-chunker.js';

package/dist/types/conversations/orchestration/text-chunker/text-chunker.d.ts

@@ -0,0 +1,39 @@
+/**
+ * Streaming text segmenter for speech.
+ *
+ * Turns an incremental LLM token stream into speakable chunks with a boundary
+ * hierarchy, so TTS never waits indefinitely for punctuation:
+ *
+ * 1. **Strong boundary** — `. ! ? \n` flush immediately (sentence end).
+ * 2. **Soft boundary** — once the buffer is long enough, split at the last
+ *    `, ; :` that yields a chunk of at least `minSoftLength` characters.
+ * 3. **Hard cap** — at `maxLength` the buffer flushes regardless of
+ *    punctuation.
+ *
+ * The heuristics are intentionally internal and benchmark-driven rather than
+ * configurable through the public API.
+ */
+export interface TextChunkerOptions {
+    /** Buffer length at which a soft boundary becomes eligible. Default 80. */
+    targetLength?: number;
+    /** Hard cap before an unconditional flush. Default 140. */
+    maxLength?: number;
+    /** Smallest chunk a soft boundary may produce. Default 40. */
+    minSoftLength?: number;
+}
+export declare class TextChunker {
+    private readonly targetLength;
+    private readonly maxLength;
+    private readonly minSoftLength;
+    private buffer;
+    constructor(options?: TextChunkerOptions);
+    /** Feed tokens; returns zero or more complete chunks to synthesize. */
+    push(delta: string): string[];
+    /** Flush any remaining buffered text as a final chunk (or null). */
+    flush(): string | null;
+    /** Drop the buffer (interrupt, stop). */
+    clear(): void;
+    private takeNext;
+    /** Cut the buffer through index `i` (inclusive) and return the text. */
+    private takeThrough;
+}