@pipedog/core 0.0.0 → 0.1.0

package/dist/pipeline/worker_observer.d.ts

@@ -0,0 +1,131 @@
+/**
+ * Worker observer for managing pipeline frame observers.
+ *
+ * Provides a proxy observer system that manages multiple observers for
+ * pipeline frame events, ensuring that observer processing doesn't block the
+ * main pipeline execution.
+ */
+import { Queue, type Task } from "@pipedog/asyncio";
+import type { Frame } from "../frames/frames.ts";
+import { BaseObserver, type BaseObserverOptions, FrameProcessed, FramePushed, ProcessorSetUp } from "../observers/base_observer.ts";
+import type { BaseTaskManager } from "../utils/asyncio/task_manager.ts";
+/**
+ * Proxy data for managing observer tasks and queues.
+ *
+ * This represents the data received from the main observer that is queued
+ * for later processing.
+ *
+ * - `queue`: queue for frame data awaiting observer processing.
+ * - `task`: task running the observer's frame processing loop.
+ * - `observer`: the actual observer instance being proxied.
+ */
+export declare class Proxy {
+    queue: Queue<unknown>;
+    task: Task<unknown>;
+    observer: BaseObserver;
+    constructor(options: {
+        queue: Queue<unknown>;
+        task: Task<unknown>;
+        observer: BaseObserver;
+    });
+}
+/**
+ * Frames held weakly by id, like Python's `weakref.WeakValueDictionary`: an
+ * entry goes away with its frame.
+ */
+declare class WeakFrameMap {
+    #private;
+    has(id: number): boolean;
+    set(id: number, frame: Frame): void;
+    /** Number of frames still alive, like `len()` of a `WeakValueDictionary`. */
+    get size(): number;
+    /** The frames still alive, like `WeakValueDictionary.values()`. */
+    values(): IterableIterator<Frame>;
+}
+export interface WorkerObserverOptions extends BaseObserverOptions {
+    /** List of observers to manage. Defaults to an empty list. */
+    observers?: BaseObserver[] | null;
+}
+/**
+ * Proxy observer that manages multiple observers without blocking the pipeline.
+ *
+ * This is a pipeline frame observer that is meant to be used as a proxy to
+ * the user provided observers. That is, this is the observer that should be
+ * passed to the frame processors. Then, every time a frame is pushed this
+ * observer will call all the observers registered to the pipeline worker.
+ *
+ * This observer makes sure that passing frames to observers doesn't block the
+ * pipeline by creating a queue and a worker for each user observer. When a
+ * frame is received, it will be put in a queue for efficiency and later
+ * processed by each worker.
+ *
+ * It also tells a frame's first push from the ones that follow, and only
+ * passes the first one to observers that want a frame once.
+ *
+ * Dropped from upstream (deprecated): `on_startup_warmup` / `StartupWarmup`.
+ */
+export declare class WorkerObserver extends BaseObserver {
+    protected _observers: BaseObserver[];
+    protected _proxies: Map<BaseObserver, Proxy> | null;
+    protected _framesPushed: WeakFrameMap;
+    constructor(options?: WorkerObserverOptions);
+    /**
+     * Add a new observer to the managed list.
+     *
+     * @param observer The observer to add.
+     */
+    addObserver(observer: BaseObserver): void;
+    /**
+     * Remove an observer and clean up its resources.
+     *
+     * @param observer The observer to remove.
+     */
+    removeObserver(observer: BaseObserver): Promise<void>;
+    /**
+     * Set up a proxy for every managed observer.
+     *
+     * Processors report their own setup to observers, so the proxies are in
+     * place before any of them is set up.
+     *
+     * @param taskManager The task manager the proxies run their tasks on.
+     */
+    setup(taskManager: BaseTaskManager | unknown): Promise<void>;
+    /**
+     * Cleanup all proxy observers.
+     *
+     * Tearing down is best effort: an observer that raises is logged and the
+     * rest are still cleaned up.
+     */
+    cleanup(): Promise<void>;
+    /** Forward pipeline started signal to all managed observers. */
+    onPipelineStarted(): Promise<void>;
+    /**
+     * Queue frame data for all managed observers.
+     *
+     * @param data The frame processing event data to distribute to observers.
+     */
+    onProcessFrame(data: FrameProcessed): Promise<void>;
+    /**
+     * Queue frame data for the managed observers.
+     *
+     * A repeated push only reaches the observers that want every push.
+     *
+     * @param data The frame push event data to distribute to observers.
+     */
+    onPushFrame(data: FramePushed): Promise<void>;
+    /**
+     * Queue processor setup timing for all managed observers.
+     *
+     * @param data The processor setup event data to distribute to observers.
+     */
+    onProcessorSetup(data: ProcessorSetUp): Promise<void>;
+    /** Create a proxy for a single observer. */
+    protected _createProxy(observer: BaseObserver): Proxy;
+    /** Create proxies for all observers. */
+    protected _createProxies(observers: BaseObserver[]): Map<BaseObserver, Proxy>;
+    protected _sendToProxy(data: unknown): Promise<void>;
+    /** Handle frame processing for a single observer. */
+    protected _proxyTaskHandler(queue: Queue<unknown>, observer: BaseObserver): Promise<void>;
+}
+export {};
+//# sourceMappingURL=worker_observer.d.ts.map

package/dist/pipeline/worker_observer.js

@@ -0,0 +1,274 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/pipeline/worker_observer.py
+/**
+ * Worker observer for managing pipeline frame observers.
+ *
+ * Provides a proxy observer system that manages multiple observers for
+ * pipeline frame events, ensuring that observer processing doesn't block the
+ * main pipeline execution.
+ */
+import { currentTask, Queue, rethrowIfCancelled } from "@pipedog/asyncio";
+import { BaseObserver, FrameProcessed, FramePushed, ProcessorSetUp, } from "../observers/base_observer.js";
+import { logger } from "../utils/logger.js";
+/**
+ * Proxy data for managing observer tasks and queues.
+ *
+ * This represents the data received from the main observer that is queued
+ * for later processing.
+ *
+ * - `queue`: queue for frame data awaiting observer processing.
+ * - `task`: task running the observer's frame processing loop.
+ * - `observer`: the actual observer instance being proxied.
+ */
+// biome-ignore lint/suspicious/noShadowRestrictedNames: upstream name (worker_observer.Proxy).
+export class Proxy {
+    queue;
+    task;
+    observer;
+    constructor(options) {
+        this.queue = options.queue;
+        this.task = options.task;
+        this.observer = options.observer;
+    }
+}
+/** Internal sentinel queued to observers when the pipeline has started. */
+class _PipelineStartedSignal {
+}
+/**
+ * Frames held weakly by id, like Python's `weakref.WeakValueDictionary`: an
+ * entry goes away with its frame.
+ */
+class WeakFrameMap {
+    #refs = new Map();
+    #registry = new FinalizationRegistry((id) => {
+        const ref = this.#refs.get(id);
+        if (ref && ref.deref() === undefined)
+            this.#refs.delete(id);
+    });
+    has(id) {
+        return this.#refs.get(id)?.deref() !== undefined;
+    }
+    set(id, frame) {
+        this.#refs.set(id, new WeakRef(frame));
+        this.#registry.register(frame, id);
+    }
+    /** Number of frames still alive, like `len()` of a `WeakValueDictionary`. */
+    get size() {
+        let n = 0;
+        for (const ref of this.#refs.values()) {
+            if (ref.deref() !== undefined)
+                n++;
+        }
+        return n;
+    }
+    /** The frames still alive, like `WeakValueDictionary.values()`. */
+    *values() {
+        for (const ref of this.#refs.values()) {
+            const frame = ref.deref();
+            if (frame !== undefined)
+                yield frame;
+        }
+    }
+}
+/**
+ * Proxy observer that manages multiple observers without blocking the pipeline.
+ *
+ * This is a pipeline frame observer that is meant to be used as a proxy to
+ * the user provided observers. That is, this is the observer that should be
+ * passed to the frame processors. Then, every time a frame is pushed this
+ * observer will call all the observers registered to the pipeline worker.
+ *
+ * This observer makes sure that passing frames to observers doesn't block the
+ * pipeline by creating a queue and a worker for each user observer. When a
+ * frame is received, it will be put in a queue for efficiency and later
+ * processed by each worker.
+ *
+ * It also tells a frame's first push from the ones that follow, and only
+ * passes the first one to observers that want a frame once.
+ *
+ * Dropped from upstream (deprecated): `on_startup_warmup` / `StartupWarmup`.
+ */
+export class WorkerObserver extends BaseObserver {
+    _observers;
+    // Becomes a map after setup() is called.
+    _proxies = null;
+    // Frames pushed so far, held weakly: an entry goes away with its frame, so
+    // this tracks the frames in flight, not every frame ever pushed.
+    _framesPushed = new WeakFrameMap();
+    constructor(options = {}) {
+        super(options);
+        this._observers = options.observers ?? [];
+    }
+    /**
+     * Add a new observer to the managed list.
+     *
+     * @param observer The observer to add.
+     */
+    addObserver(observer) {
+        // Add the observer to the list.
+        this._observers.push(observer);
+        // After setup(), create the proxy immediately; setup() handles earlier additions.
+        if (this._proxies !== null) {
+            const proxy = this._createProxy(observer);
+            this._proxies.set(observer, proxy);
+        }
+    }
+    /**
+     * Remove an observer and clean up its resources.
+     *
+     * @param observer The observer to remove.
+     */
+    async removeObserver(observer) {
+        // If the observer has a proxy, remove it.
+        if (this._proxies && this._proxies.size > 0 && this._proxies.has(observer)) {
+            const proxy = this._proxies.get(observer);
+            // Remove the proxy so it doesn't get called anymore.
+            this._proxies.delete(observer);
+            // Cancel the proxy worker right away. An observer removing itself runs
+            // on that worker, which can't be cancelled from inside, so the worker
+            // ends itself instead.
+            if (proxy.task !== currentTask()) {
+                await this.cancelTask(proxy.task);
+            }
+            // Shutdown only cleans up the observers in _proxies.
+            await observer.cleanup();
+        }
+        // Remove the observer from the list.
+        const index = this._observers.indexOf(observer);
+        if (index >= 0) {
+            this._observers.splice(index, 1);
+        }
+    }
+    /**
+     * Set up a proxy for every managed observer.
+     *
+     * Processors report their own setup to observers, so the proxies are in
+     * place before any of them is set up.
+     *
+     * @param taskManager The task manager the proxies run their tasks on.
+     */
+    async setup(taskManager) {
+        await super.setup(taskManager);
+        this._proxies = this._createProxies(this._observers);
+        for (const observer of this._proxies.keys()) {
+            await observer.setup(taskManager);
+        }
+    }
+    /**
+     * Cleanup all proxy observers.
+     *
+     * Tearing down is best effort: an observer that raises is logged and the
+     * rest are still cleaned up.
+     */
+    async cleanup() {
+        await super.cleanup();
+        if (!this._proxies || this._proxies.size === 0) {
+            return;
+        }
+        for (const proxy of this._proxies.values()) {
+            await this.cancelTask(proxy.task);
+        }
+        for (const observer of this._proxies.keys()) {
+            try {
+                await observer.cleanup();
+            }
+            catch (e) {
+                rethrowIfCancelled(e);
+                logger.error(`Error cleaning up ${observer}: ${e instanceof Error ? e.message : e}`);
+            }
+        }
+    }
+    /** Forward pipeline started signal to all managed observers. */
+    async onPipelineStarted() {
+        await this._sendToProxy(new _PipelineStartedSignal());
+    }
+    /**
+     * Queue frame data for all managed observers.
+     *
+     * @param data The frame processing event data to distribute to observers.
+     */
+    async onProcessFrame(data) {
+        await this._sendToProxy(data);
+    }
+    /**
+     * Queue frame data for the managed observers.
+     *
+     * A repeated push only reaches the observers that want every push.
+     *
+     * @param data The frame push event data to distribute to observers.
+     */
+    async onPushFrame(data) {
+        if (!this._proxies || this._proxies.size === 0) {
+            return;
+        }
+        const frame = data.frame;
+        data.firstPush = !this._framesPushed.has(frame.id);
+        if (data.firstPush) {
+            this._framesPushed.set(frame.id, frame);
+        }
+        for (const proxy of this._proxies.values()) {
+            if (data.firstPush || proxy.observer.observeEveryPush) {
+                await proxy.queue.put(data);
+            }
+        }
+    }
+    /**
+     * Queue processor setup timing for all managed observers.
+     *
+     * @param data The processor setup event data to distribute to observers.
+     */
+    async onProcessorSetup(data) {
+        await this._sendToProxy(data);
+    }
+    /** Create a proxy for a single observer. */
+    _createProxy(observer) {
+        const queue = new Queue();
+        const task = this.createTask(() => this._proxyTaskHandler(queue, observer), "_proxyTaskHandler");
+        return new Proxy({ queue, task, observer });
+    }
+    /** Create proxies for all observers. */
+    _createProxies(observers) {
+        const proxies = new Map();
+        for (const observer of observers) {
+            const proxy = this._createProxy(observer);
+            proxies.set(observer, proxy);
+        }
+        return proxies;
+    }
+    async _sendToProxy(data) {
+        if (!this._proxies || this._proxies.size === 0) {
+            return;
+        }
+        for (const proxy of this._proxies.values()) {
+            await proxy.queue.put(data);
+        }
+    }
+    /** Handle frame processing for a single observer. */
+    async _proxyTaskHandler(queue, observer) {
+        while (true) {
+            const data = await queue.get();
+            if (data instanceof _PipelineStartedSignal) {
+                await observer.onPipelineStarted();
+            }
+            else if (data instanceof FramePushed) {
+                await observer.onPushFrame(data);
+            }
+            else if (data instanceof FrameProcessed) {
+                await observer.onProcessFrame(data);
+            }
+            else if (data instanceof ProcessorSetUp) {
+                await observer.onProcessorSetup(data);
+            }
+            queue.taskDone();
+            // Stop once the observer has removed itself (see removeObserver()).
+            const proxy = this._proxies && this._proxies.size > 0 ? this._proxies.get(observer) : null;
+            if (!proxy || proxy.queue !== queue) {
+                break;
+            }
+        }
+    }
+}
+//# sourceMappingURL=worker_observer.js.map

package/dist/pipeline/worker_ready_decorator.d.ts

@@ -0,0 +1,45 @@
+/** Decorator for marking methods as worker-ready handlers. */
+type AnyFn = (...args: any[]) => any;
+/** A function marked by `workerReady()`. */
+export type WorkerReadyHandler<F extends AnyFn = AnyFn> = F & {
+    workerReadyName: string;
+};
+/**
+ * Mark a method as a handler for a specific worker becoming ready.
+ *
+ * Decorated methods are automatically collected by `BaseWorker` at
+ * initialization. When the worker starts, it calls `watchWorkers` for the
+ * decorated handlers. When a watched worker registers, the decorated method
+ * is called with the ready data.
+ *
+ * The returned decorator works both as a standard (TC39) method decorator and
+ * as a plain function, since runtimes that strip types (Node) do not run
+ * decorator syntax.
+ *
+ * @example
+ * class MyWorker extends BaseWorker {
+ *   async onGreeterReady(data: WorkerReadyData): Promise<void> {
+ *     await this.activateWorker("greeter", { args: ... });
+ *   }
+ *   static {
+ *     workerReady({ name: "greeter" })(this.prototype.onGreeterReady);
+ *   }
+ * }
+ *
+ * @param options.name The name of the worker to watch.
+ */
+export declare function workerReady(options: {
+    name: string;
+}): <F extends AnyFn>(fn: F, _context?: unknown) => F;
+/**
+ * Collect all `workerReady` decorated bound methods from an object.
+ *
+ * Walks the prototype chain from the object's own class up, so an override in
+ * a subclass shadows the parent's method of the same name.
+ *
+ * @returns A map from worker name to the bound method.
+ * @throws Error If two handlers watch the same worker name.
+ */
+export declare function _collectWorkerReadyHandlers(obj: object): Map<string, AnyFn>;
+export {};
+//# sourceMappingURL=worker_ready_decorator.d.ts.map

package/dist/pipeline/worker_ready_decorator.js

@@ -0,0 +1,76 @@
+// Copyright (c) 2024-2026, Daily
+// Copyright (c) 2026, pipedog contributors
+// SPDX-License-Identifier: BSD-2-Clause
+//
+// Ported from pipecat: src/pipecat/pipeline/worker_ready_decorator.py
+/**
+ * Mark a method as a handler for a specific worker becoming ready.
+ *
+ * Decorated methods are automatically collected by `BaseWorker` at
+ * initialization. When the worker starts, it calls `watchWorkers` for the
+ * decorated handlers. When a watched worker registers, the decorated method
+ * is called with the ready data.
+ *
+ * The returned decorator works both as a standard (TC39) method decorator and
+ * as a plain function, since runtimes that strip types (Node) do not run
+ * decorator syntax.
+ *
+ * @example
+ * class MyWorker extends BaseWorker {
+ *   async onGreeterReady(data: WorkerReadyData): Promise<void> {
+ *     await this.activateWorker("greeter", { args: ... });
+ *   }
+ *   static {
+ *     workerReady({ name: "greeter" })(this.prototype.onGreeterReady);
+ *   }
+ * }
+ *
+ * @param options.name The name of the worker to watch.
+ */
+export function workerReady(options) {
+    const { name } = options;
+    return function decorator(fn, _context) {
+        fn.workerReadyName = name;
+        return fn;
+    };
+}
+/**
+ * Collect all `workerReady` decorated bound methods from an object.
+ *
+ * Walks the prototype chain from the object's own class up, so an override in
+ * a subclass shadows the parent's method of the same name.
+ *
+ * @returns A map from worker name to the bound method.
+ * @throws Error If two handlers watch the same worker name.
+ */
+export function _collectWorkerReadyHandlers(obj) {
+    const seen = new Set();
+    const handlers = new Map();
+    const handlerNames = new Map();
+    let proto = Object.getPrototypeOf(obj);
+    while (proto !== null && proto !== Object.prototype) {
+        for (const attrName of Object.getOwnPropertyNames(proto)) {
+            if (seen.has(attrName)) {
+                continue;
+            }
+            seen.add(attrName);
+            const descriptor = Object.getOwnPropertyDescriptor(proto, attrName);
+            // Skip accessors so collecting never runs a getter.
+            const val = descriptor && "value" in descriptor ? descriptor.value : undefined;
+            if (typeof val === "function" && typeof val.workerReadyName === "string") {
+                const workerName = val.workerReadyName;
+                if (handlers.has(workerName)) {
+                    const existing = handlerNames.get(workerName);
+                    throw new Error(`Duplicate @worker_ready handler for '${workerName}': ` +
+                        `'${attrName}' conflicts with '${existing}'`);
+                }
+                const method = obj[attrName];
+                handlers.set(workerName, method.bind(obj));
+                handlerNames.set(workerName, attrName);
+            }
+        }
+        proto = Object.getPrototypeOf(proto);
+    }
+    return handlers;
+}
+//# sourceMappingURL=worker_ready_decorator.js.map

package/dist/processors/aggregators/async_tool_messages.d.ts

@@ -0,0 +1,146 @@
+/**
+ * Helpers for the async-tool message protocol used in LLM contexts.
+ *
+ * When a function is registered with `cancelOnInterruption: false`, the
+ * `LLMUserContextAggregator` / `LLMAssistantContextAggregator` pair appends
+ * async-tool messages to the conversation context as the underlying task
+ * progresses:
+ *
+ * - A `started` message (`role="tool"`) is appended immediately when the tool
+ *   starts running.
+ * - An `intermediate` message (`role="developer"`) is appended each time an
+ *   intermediate result is reported via
+ *   `resultCallback(..., new FunctionCallResultProperties({ isFinal: false }))`.
+ * - A `final` message (`role="developer"`) is appended when the task
+ *   finishes. A task that is cancelled instead of finishing settles the same
+ *   way, carrying a cancellation notice in place of a result.
+ *
+ * The `final` message exists so a result that arrives after the LLM has moved
+ * on still reaches it. When the result arrives first, before any model
+ * response or any new user or assistant message, there is nothing to catch up
+ * on: the `started` message is overwritten with the result, as for a
+ * synchronous call, and no `final` message is written. A cancellation always
+ * gets a `final` message, because it has to tell the LLM the task did not
+ * complete.
+ *
+ * This module is the single source of truth for the on-the-wire payload shape:
+ *
+ * - The aggregator uses the `build*Message` functions when injecting messages.
+ * - Realtime LLM services use `parseMessage` to detect async-tool messages
+ *   while iterating the context, then read `payload.result` and deliver it via
+ *   their formal tool-result channel.
+ *
+ * Internally, `AsyncToolMessagePayload` is the canonical structured form; the
+ * on-the-wire JSON string is always derived from it (never stored) so the two
+ * representations can't drift.
+ *
+ * Consumers are expected to import the module rather than its individual
+ * functions.
+ *
+ * @example
+ * import * as asyncToolMessages from "@pipedog/core/processors/aggregators/async_tool_messages";
+ * asyncToolMessages.buildStartedMessage(toolCallId);
+ * asyncToolMessages.parseMessage(msg);
+ */
+import type { LLMStandardMessage } from "./llm_context.ts";
+export type AsyncToolMessageKind = "started" | "intermediate" | "final";
+/**
+ * Standing guidance composed into the system instruction whenever an async
+ * tool is registered. The per-result message says the same thing, but it
+ * arrives buried in a context whose most recent turn may be the user asking
+ * for something else; a model weighing the two follows the nearer, louder
+ * request. This states the policy before any result exists, so it is in force
+ * when one arrives.
+ */
+export declare const ASYNC_TOOL_INSTRUCTIONS: string;
+export interface AsyncToolMessagePayloadOptions {
+    kind: AsyncToolMessageKind;
+    toolCallId: string;
+    status: "running" | "finished";
+    description: string;
+    result: string | null;
+}
+/**
+ * The structured contents of an async-tool message in an LLM context.
+ *
+ * - `kind`: which of the three async-tool message stages this is.
+ * - `toolCallId`: the id of the tool invocation this payload relates to.
+ * - `status`: `"running"` for started/intermediate, `"finished"` for the
+ *   final message.
+ * - `description`: human-readable description from the payload. May be empty.
+ * - `result`: for `intermediate` and `final` messages, the JSON-encoded result
+ *   string (or the literal `"COMPLETED"` if the function returned no value).
+ *   `null` for `started` messages.
+ */
+export declare class AsyncToolMessagePayload {
+    readonly kind: AsyncToolMessageKind;
+    readonly toolCallId: string;
+    readonly status: "running" | "finished";
+    readonly description: string;
+    readonly result: string | null;
+    constructor(options: AsyncToolMessagePayloadOptions);
+}
+/**
+ * Build a `started` async-tool message for an LLM context.
+ *
+ * Append the returned message to the LLM context immediately when an async
+ * function call (registered with `cancelOnInterruption: false`) starts
+ * running. The message lets the model know a task is in flight and that its
+ * results will arrive later in subsequent `developer`-role messages.
+ *
+ * @param toolCallId The id of the tool invocation this message is for.
+ * @returns A message ready to pass to `LLMContext.addMessage`.
+ */
+export declare function buildStartedMessage(toolCallId: string): LLMStandardMessage;
+/**
+ * Build an intermediate-result async-tool message for an LLM context.
+ *
+ * Append the returned message to the LLM context each time the running async
+ * function reports a non-final result via
+ * `resultCallback(..., new FunctionCallResultProperties({ isFinal: false }))`.
+ *
+ * @param toolCallId The id of the tool invocation the result is for.
+ * @param result The JSON-encoded result string (caller is responsible for
+ *   encoding the function's actual return value, typically via
+ *   `JSON.stringify`).
+ * @returns A message ready to pass to `LLMContext.addMessage`.
+ */
+export declare function buildIntermediateResultMessage(toolCallId: string, result: string): LLMStandardMessage;
+/**
+ * Build a final-result async-tool message for an LLM context.
+ *
+ * Append the returned message to the LLM context when the async function
+ * finishes. After this message no further async-tool messages will arrive for
+ * this `tool_call_id`.
+ *
+ * @param toolCallId The id of the tool invocation the result is for.
+ * @param result The JSON-encoded result string, or the literal `"COMPLETED"`
+ *   sentinel when the function returned nothing (matching the same convention
+ *   used for synchronous tool calls).
+ * @returns A message ready to pass to `LLMContext.addMessage`.
+ */
+export declare function buildFinalResultMessage(toolCallId: string, result: string): LLMStandardMessage;
+/**
+ * Build a message settling a cancelled async-tool call in an LLM context.
+ *
+ * Append the returned message to the LLM context when an async function call
+ * is cancelled (by a timeout or at the model's request) instead of running to
+ * completion. It settles the `tool_call_id` the same way a final result does,
+ * carrying a cancellation notice in place of a result.
+ *
+ * @param toolCallId The id of the tool invocation that was cancelled.
+ * @returns A message ready to pass to `LLMContext.addMessage`.
+ */
+export declare function buildCancelledMessage(toolCallId: string): LLMStandardMessage;
+/**
+ * Decode an async-tool message payload, or return null if not async-tool.
+ *
+ * @param message A standard message from the LLM context. Callers iterating
+ *   over `LLMContext.getMessages()` should filter out `LLMSpecificMessage`
+ *   entries first; only `LLMStandardMessage` values can carry async-tool
+ *   payloads.
+ * @returns An `AsyncToolMessagePayload` if the message is a recognized
+ *   async-tool payload, otherwise `null`.
+ */
+export declare function parseMessage(message: LLMStandardMessage): AsyncToolMessagePayload | null;
+//# sourceMappingURL=async_tool_messages.d.ts.map