@moureau/pipeflow 0.0.2 → 0.0.3

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

@@ -1,31 +1,65 @@
 import type { Conversation } from "../../../conversation/conversation.js";
 import type { LLMToolCall } from "../../../../providers/llm/types.js";
 import type { ToolCallResult } from "../../../types.js";
+import type { Tool } from "../../../../agents/tools/tools.js";
 export interface ResolvedToolCall {
     id: string;
     name: string;
     result?: unknown;
     error?: string;
 }
+export interface ToolCallManagerOptions {
+    /**
+     * The tools the framework can execute on the agent's behalf, keyed by
+     * name. Built from the orchestrated agents' tool registries.
+     */
+    tools?: ReadonlyMap<string, Tool<never, unknown>>;
+    /**
+     * Execute tool calls automatically (default `true`), feeding each tool's
+     * result — or a caught error — back into the model loop. Set `false` to
+     * keep the application-managed contract: listen for `tool-call`, execute
+     * the tool in your own backend, and report back with
+     * `resolveToolCall()`. `tool-call` events are still emitted for
+     * visibility in either mode.
+     */
+    autoExecute?: boolean;
+}
 /**
- * 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.
+ * Resolves the tool calls a generation issues. By default it runs the
+ * matching tool itself (the conversation agents' tools auto-execute, exactly
+ * like `Agent.run()`); with `autoExecute: false` it hands the calls 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 tools;
+    private readonly autoExecute;
     private readonly waiters;
-    constructor(conversation: Conversation, timeoutMs: number);
+    constructor(conversation: Conversation, timeoutMs: number, options?: ToolCallManagerOptions);
     /**
-     * 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.
+     * Resolve a batch of tool calls. In auto-execute mode each call's tool
+     * runs on the agent's behalf (errors caught and returned to the model);
+     * otherwise the application resolves them. Either way the calls are
+     * emitted as `tool-call` events and resolved 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;
+    /**
+     * Execute one tool call and resolve it with the tool's result (or a
+     * caught error). If the application already resolved the call in its
+     * `tool-call` handler — the app-managed path — the tool is not run twice.
+     */
+    private runToolAndResolve;
+    /** Resolve through the conversation only while the call is still pending. */
+    private resolveIfPending;
+    private isPending;
+    private parseArguments;
     private wait;
 }

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

@@ -77,6 +77,8 @@ export declare function setup(options: {
     llm?: LLM;
     /** Override the conversation-history window (default 5 turns / 4k chars). */
     historyWindow?: HistoryWindow | false;
+    /** Auto-execute the agent's tools (default true); see OrchestratorOptions. */
+    autoExecuteTools?: boolean;
 }): Promise<Harness>;
 export declare function waitFor(condition: () => boolean, timeoutMs?: number): Promise<void>;
 export declare function speak(harness: Harness, userId: string, text: string): Promise<void>;
@@ -93,4 +95,6 @@ export declare function setupRoster(options: {
         llm: FakeLLM;
     }>;
     maxCoordinationSteps?: number;
+    /** Auto-execute the agents' tools (default true); see OrchestratorOptions. */
+    autoExecuteTools?: boolean;
 }): Promise<RosterHarness>;

package/dist/types/pipeflow/pipeflow.d.ts

@@ -9,6 +9,14 @@ export interface PipeflowOptions {
     stt?: STT;
     tts?: TTS;
     persistence?: Persistence;
+    /**
+     * Default for created conversations: auto-execute the agents' tools
+     * (default `true`), feeding each tool's result back into the model loop.
+     * Set `false` to resolve tool calls from your own backend via
+     * `resolveToolCall()`. Override per conversation in
+     * `pipeflow.conversations.create()`.
+     */
+    autoExecuteTools?: boolean;
 }
 /**
  * The Pipeflow entry point.

package/dist/types/providers/llm/types.d.ts

@@ -42,7 +42,10 @@ export interface LLMToolDefinition {
  * - `prompted` — no `tools`; the same envelope is requested by appending an
  *   instruction to the last user message. The universal fallback: works on
  *   any chat model, at the cost of extraction/repair/retry, higher token
- *   use, and tail-latency risk.
+ *   use, and tail-latency risk. Because nothing constrains the output, a
+ *   model that ignores the envelope and replies in plain prose is answered
+ *   directly — its text is treated as the reply rather than failing the
+ *   generation.
  */
 export type ToolMode = "native" | "envelope" | "prompted";
 /**

package/dist/types/providers/stt/adapters/openrouter/openrouter.d.ts

@@ -23,6 +23,68 @@ export interface OpenRouterSTTOptions extends STTOptions {
      * sent as-is.
      */
     audioFormat?: OpenRouterAudioFormat;
+    /**
+     * Strip common whisper hallucinations from transcripts: asterisk stage
+     * directions ("*Dramatic music*"), repeated filler phrases ("Thank you.
+     * Thank you."), and pure-filler clips whisper emits on near-silence
+     * ("Thank you.", "E aí.", "Bye.", …). Set `false` to pass transcripts
+     * through untouched. Default `true`.
+     */
+    filterHallucinations?: boolean;
+    /**
+     * Extra phrases (lowercased) treated as hallucinations on top of the
+     * built-in multilingual filler list — for fillers whisper "hears" in the
+     * languages you deploy. A transcript that is *entirely* built from known
+     * fillers is dropped. Default none.
+     */
+    fillerPhrases?: string[];
+    /**
+     * Energy floor (0–1 RMS, on the raw sample range) for transcribing a
+     * buffered `pcm` clip. Near-silence clips — the ones whisper hallucinates
+     * "E aí." / "Thank you." / *stage directions* on — are skipped entirely
+     * (no transcription request, no `final`), instead of being filtered after
+     * the fact. Real speech sits far above any reasonable floor; start around
+     * `0.01`–`0.02` and raise it if artifacts persist. Only applies to
+     * `audioFormat: "pcm"` (the only format whose samples are measurable).
+     * Default: no floor (transcribe everything the client sends).
+     */
+    minClipRms?: number;
+    /**
+     * Called for every buffered `pcm` clip with its measured mean RMS and
+     * whether it was transcribed — for logging the real distribution and
+     * tuning `minClipRms` against it (speech clips sit far above artifact
+     * clips). Fires when this callback or `minClipRms` is set.
+     */
+    onClipEnergy?: (rms: number, transcribed: boolean) => void;
+    /**
+     * Abort a transcription request that produces no response within this
+     * long (default 30000ms). Transcriptions are serialized on one session
+     * chain, so a hung provider request would otherwise block every later
+     * clip (each turn silently waits) until the server restarts. Raise it for
+     * very long clips or slow providers.
+     */
+    transcriptionTimeoutMs?: number;
+    /**
+     * Sampling temperature (0–1) for transcription. Lower is more
+     * deterministic; whisper's API default is already 0, so this is rarely the
+     * lever for hallucinations.
+     */
+    temperature?: number;
+    /**
+     * Provider-specific passthrough, serialized as the `provider` multipart
+     * field. OpenRouter ignores the top-level `prompt` field ("accepted but
+     * ignored"), so the only way to reach whisper's prompt — vocabulary /
+     * context steering — is per-provider:
+     *
+     * ```ts
+     * providerOptions: { options: { groq: { prompt: "Transcribe exactly what is said." } } }
+     * ```
+     *
+     * Only the options for the provider that actually serves the request are
+     * forwarded, so the key must match the serving provider (openai, groq,
+     * together, …).
+     */
+    providerOptions?: Record<string, unknown>;
     /** Injectable fetch, mainly for tests. */
     fetch?: FetchLike;
 }
@@ -54,6 +116,13 @@ export declare class OpenRouterSTT implements STT {
     private readonly sessions;
     constructor(options: OpenRouterSTTOptions);
     start(options?: STTOptions): STTSession;
+    /**
+     * Live-tunable energy floor (0–1 RMS) for `pcm` clips: raise it to skip
+     * more near-silence clips (the whisper hallucinations), lower it to keep
+     * quieter speech. Applies to all sessions immediately.
+     */
+    set minClipRms(value: number | undefined);
+    get minClipRms(): number | undefined;
     cancel(): void;
 }
 export declare class OpenRouterSession implements STTSession {
@@ -65,14 +134,24 @@ export declare class OpenRouterSession implements STTSession {
     private readonly sampleRate;
     private readonly silenceMs;
     private readonly audioFormat;
+    private readonly filterHallucinations;
+    private readonly fillerPhrases;
+    private readonly onClipEnergy;
+    private readonly transcriptionTimeoutMs;
+    private readonly temperature;
+    private readonly providerOptions;
     private readonly fetchImpl;
+    /** The adapter's live options object; live-tunable fields are read here. */
+    private readonly liveOptions;
+    /** Live-tunable energy floor, read through the adapter (not a snapshot). */
+    private get minClipRms();
     private chunks;
     private timer;
     private chain;
     private readonly controllers;
     private ended;
     private aborted;
-    constructor(options: OpenRouterSTTOptions);
+    constructor(options: OpenRouterSTTOptions, liveOptions: OpenRouterSTTOptions);
     write(audio: Uint8Array): void;
     end(): Promise<void>;
     /** Drop buffered audio and abort in-flight requests (cancel). */
@@ -82,6 +161,12 @@ export declare class OpenRouterSession implements STTSession {
     on(event: "error", listener: (error: Error) => void): void;
     on(event: "close", listener: () => void): void;
     /** Queue a transcription of whatever audio is buffered (serialized). */
+    /**
+     * Queue a transcription of whatever audio is buffered (serialized). The
+     * clip boundary is frozen *now* — the moment the trailing silence was
+     * detected — so audio that arrives while this transcription is queued or
+     * in flight starts the next clip instead of being swept into this one.
+     */
     private flush;
     private takeBuffer;
     private transcribe;
@@ -92,3 +177,20 @@ export declare class OpenRouterSession implements STTSession {
  * The header is the standard 44-byte RIFF/WAVE layout.
  */
 export declare function toWav(pcm: Uint8Array, sampleRate: number): Uint8Array;
+/**
+ * Mean RMS of linear16 PCM (mono), in the 0–1 sample range. Used as the
+ * clip-level energy floor: near-silence clips sit far below real speech.
+ */
+export declare function pcmRms(pcm: Uint8Array): number;
+/**
+ * Clean a whisper transcript of its most common hallucinations, returning
+ * "" when nothing worth speaking remains:
+ *
+ * 1. Asterisk stage directions ("*Dramatic music*", "*laughs*") are
+ *    dropped — whisper transcribes background noise as stage notes.
+ * 2. Consecutive repeated sentences ("Thank you. Thank you.") collapse to
+ *    one — a doubled filler is a classic near-silence artifact.
+ * 3. A transcript built entirely from filler phrases (the built-in
+ *    multilingual list plus `extraFillers`) is dropped.
+ */
+export declare function cleanTranscript(text: string, extraFillers?: string[]): string;

package/dist/types/providers/tts/adapters/kokoro/kokoro.d.ts

@@ -42,7 +42,7 @@ export declare class KokoroTTS implements TTS {
     private readonly chunkSize;
     private readonly streaming;
     private readonly fetchImpl;
-    private abort;
+    private readonly streams;
     constructor(options?: KokoroOptions);
     stop(): void;
     stream(request: TTSRequest): AsyncGenerator<Uint8Array>;

package/dist/types/providers/tts/adapters/openrouter/openrouter.d.ts

@@ -7,19 +7,36 @@ export interface OpenRouterTTSOptions {
     /**
      * TTS model. Defaults to the free `fish-audio/s2.1-pro-free:free` variant —
      * fast, per-character priced. Pass `fish-audio/s2.1-pro` for the paid tier
-     * (no free-variant rate limits).
+     * (no free-variant rate limits). Note the free variant is intermittently
+     * unavailable on OpenRouter (404 "No endpoints found").
      */
     model?: string;
     /**
-     * Default voice, sent when the request carries none. Omitted entirely when
-     * unset: providers with a built-in default voice (e.g. fish-audio) accept
-     * omission, and some reject an explicit `voice` outright — while providers
-     * that require one (e.g. OpenAI TTS) need it set. Voice support varies by
-     * model and provider.
+     * Default voice, sent when the request carries none. Set it for a
+     * consistent voice: the default fish model accepts exactly `"alloy"` and
+     * rejects other names, and omitting `voice` lets the free variant vary the
+     * voice per request. Models like OpenAI TTS require a voice. Voice support
+     * varies by model and provider.
      */
     voice?: string;
+    /**
+     * Output format used when the request doesn't specify one. `"pcm"` (the
+     * default) is the lowest-latency realtime format, but its sample rate is
+     * provider-defined and opaque — clients must know it. `"mp3"` is
+     * self-describing: decoders read the real rate from the stream.
+     */
+    format?: "pcm" | "mp3";
     /** Size of the audio chunks yielded from the response stream. Default 8192. */
     chunkSize?: number;
+    /**
+     * Abort a synthesis that delivers no audio bytes for this long (default
+     * 15000ms). A provider connection that goes silent — or never responds —
+     * would otherwise wedge the speech pipeline forever, since the pipeline
+     * holds one synthesis slot and its delivery chain until the stream ends.
+     * Any byte resets the clock; a genuinely slow synthesis just needs a
+     * response within this window.
+     */
+    idleTimeoutMs?: number;
     /** Injectable fetch, mainly for tests. */
     fetch?: FetchLike;
 }
@@ -36,9 +53,11 @@ export declare class OpenRouterTTS implements TTS {
     private readonly baseUrl;
     private readonly model;
     private readonly voice;
+    private readonly format;
     private readonly chunkSize;
+    private readonly idleTimeoutMs;
     private readonly fetchImpl;
-    private abort;
+    private readonly streams;
     constructor(options: OpenRouterTTSOptions);
     stop(): void;
     stream(request: TTSRequest): AsyncGenerator<Uint8Array>;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@moureau/pipeflow",
-  "version": "0.0.2",
+  "version": "0.0.3",
   "type": "module",
   "private": false,
   "sideEffects": false,
@@ -28,6 +28,12 @@
       "require": "./dist/cjs/index.js",
       "default": "./dist/esm/index.js"
     },
+    "./client": {
+      "types": "./dist/types/client/index.d.ts",
+      "import": "./dist/esm/client/index.js",
+      "require": "./dist/cjs/client/index.js",
+      "default": "./dist/esm/client/index.js"
+    },
     "./providers": {
       "types": "./dist/types/providers/index.d.ts",
       "import": "./dist/esm/providers/index.js",