@pasko70/pibo 1.0.0

package/dist/remote/session-client.js

@@ -0,0 +1,189 @@
+import { randomUUID } from "node:crypto";
+import { connect } from "node:net";
+import { DEFAULT_REMOTE_AGENT_HOST, DEFAULT_REMOTE_AGENT_PORT, encodeRemoteAgentFrame, } from "./protocol.js";
+function parseJsonLine(line) {
+    try {
+        return JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+}
+function isBinding(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return typeof candidate.sessionKey === "string" && typeof candidate.originalProfile === "string";
+}
+function isCapabilities(value) {
+    if (!value || typeof value !== "object")
+        return false;
+    const candidate = value;
+    return Array.isArray(candidate.actions);
+}
+export function createRemoteSlashCommandMap(capabilities) {
+    const commands = new Map();
+    for (const action of capabilities.actions) {
+        for (const slashCommand of action.slashCommands) {
+            commands.set(`/${slashCommand}`, action.name);
+        }
+    }
+    return commands;
+}
+export class RemoteAgentSessionClient {
+    socket;
+    binding;
+    capabilities;
+    eventListeners = new Set();
+    pendingResponses = new Map();
+    buffer = "";
+    constructor(socket, attached) {
+        this.socket = socket;
+        this.binding = attached.binding;
+        this.capabilities = attached.capabilities;
+        this.socket.on("data", (chunk) => this.handleData(String(chunk)));
+        this.socket.once("close", () => this.rejectPendingResponses(new Error("Remote agent connection closed")));
+        this.socket.once("error", (error) => this.rejectPendingResponses(error));
+    }
+    static async connect(options = {}) {
+        const resolvedOptions = {
+            host: options.host ?? DEFAULT_REMOTE_AGENT_HOST,
+            port: options.port ?? DEFAULT_REMOTE_AGENT_PORT,
+            sessionName: options.sessionName ?? "default",
+            profile: options.profile ?? "pibo-minimal",
+        };
+        const socket = connect({ host: resolvedOptions.host, port: resolvedOptions.port });
+        socket.setEncoding("utf-8");
+        await new Promise((resolve, reject) => {
+            socket.once("connect", resolve);
+            socket.once("error", reject);
+        });
+        const attached = await attachRemoteAgent(socket, resolvedOptions);
+        return new RemoteAgentSessionClient(socket, attached);
+    }
+    onEvent(listener) {
+        this.eventListeners.add(listener);
+        return () => this.eventListeners.delete(listener);
+    }
+    getSlashCommands() {
+        return createRemoteSlashCommandMap(this.capabilities);
+    }
+    sendMessage(text) {
+        return this.sendInput({ type: "message", text });
+    }
+    sendExecution(action, params) {
+        return this.sendInput(params === undefined ? { type: "execution", action } : { type: "execution", action, params });
+    }
+    close() {
+        this.socket.end();
+    }
+    sendInput(input) {
+        return this.sendRequest({ type: "remote_input", id: randomUUID(), input });
+    }
+    sendRequest(frame) {
+        if (this.socket.destroyed) {
+            return Promise.reject(new Error("Remote agent connection is closed"));
+        }
+        return new Promise((resolve, reject) => {
+            this.pendingResponses.set(frame.id, { resolve, reject });
+            this.socket.write(encodeRemoteAgentFrame(frame));
+        });
+    }
+    handleData(chunk) {
+        this.buffer += chunk;
+        let newlineIndex = this.buffer.indexOf("\n");
+        while (newlineIndex !== -1) {
+            const line = this.buffer.slice(0, newlineIndex).trim();
+            this.buffer = this.buffer.slice(newlineIndex + 1);
+            this.handleFrame(line ? parseJsonLine(line) : undefined);
+            newlineIndex = this.buffer.indexOf("\n");
+        }
+    }
+    handleFrame(frame) {
+        if (!frame)
+            return;
+        if (frame.type === "remote_res") {
+            const pending = this.pendingResponses.get(frame.id);
+            if (!pending)
+                return;
+            this.pendingResponses.delete(frame.id);
+            if (frame.ok) {
+                pending.resolve(frame);
+            }
+            else {
+                pending.reject(new Error(frame.error?.message ?? "Remote request failed"));
+            }
+            return;
+        }
+        if (frame.type === "remote_event") {
+            for (const listener of this.eventListeners) {
+                listener(frame.payload);
+            }
+        }
+    }
+    rejectPendingResponses(error) {
+        for (const pending of this.pendingResponses.values()) {
+            pending.reject(error);
+        }
+        this.pendingResponses.clear();
+    }
+}
+async function attachRemoteAgent(socket, options) {
+    const id = randomUUID();
+    return await new Promise((resolve, reject) => {
+        let buffer = "";
+        const cleanup = () => {
+            socket.off("data", onData);
+            socket.off("error", onError);
+            socket.off("close", onClose);
+        };
+        const onError = (error) => {
+            cleanup();
+            reject(error);
+        };
+        const onClose = () => {
+            cleanup();
+            reject(new Error("Remote agent connection closed before attach completed"));
+        };
+        const onData = (chunk) => {
+            buffer += String(chunk);
+            let newlineIndex = buffer.indexOf("\n");
+            while (newlineIndex !== -1) {
+                const line = buffer.slice(0, newlineIndex).trim();
+                buffer = buffer.slice(newlineIndex + 1);
+                const frame = line ? parseJsonLine(line) : undefined;
+                if (frame?.type === "remote_res" && frame.id === id) {
+                    cleanup();
+                    if (!frame.ok) {
+                        reject(new Error(frame.error?.message ?? "Remote attach failed"));
+                        return;
+                    }
+                    const payload = frame.payload;
+                    if (!isBinding(payload?.binding)) {
+                        reject(new Error("Remote attach response did not include a binding"));
+                        return;
+                    }
+                    if (!isCapabilities(payload.capabilities)) {
+                        reject(new Error("Remote attach response did not include capabilities"));
+                        return;
+                    }
+                    resolve({
+                        binding: payload.binding,
+                        capabilities: payload.capabilities,
+                    });
+                    return;
+                }
+                newlineIndex = buffer.indexOf("\n");
+            }
+        };
+        socket.on("data", onData);
+        socket.once("error", onError);
+        socket.once("close", onClose);
+        socket.write(encodeRemoteAgentFrame({
+            type: "remote_attach",
+            id,
+            sessionName: options.sessionName,
+            profile: options.profile,
+        }));
+    });
+}

package/dist/runs/registry.js

@@ -0,0 +1,323 @@
+import { randomUUID } from "node:crypto";
+const DEFAULT_CONSUMED_TERMINAL_TTL_MS = 5 * 60 * 1000;
+const DEFAULT_DETACHED_TERMINAL_TTL_MS = 60 * 1000;
+function now() {
+    return new Date().toISOString();
+}
+function snapshot(record) {
+    const output = {
+        runId: record.runId,
+        kind: record.kind,
+        ownerPiboSessionId: record.ownerPiboSessionId,
+        status: record.status,
+        completionPolicy: record.completionPolicy,
+        consumed: record.consumed,
+        toolName: record.toolName,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+    };
+    if (record.summary)
+        output.summary = record.summary;
+    if (record.completedAt)
+        output.completedAt = record.completedAt;
+    return output;
+}
+function terminal(status) {
+    return status === "completed" || status === "failed" || status === "cancelled";
+}
+export class PiboRunRegistry {
+    options;
+    runs = new Map();
+    waiters = new Map();
+    constructor(options = {}) {
+        this.options = options;
+        if (this.options.store) {
+            this.options.store.recoverInterruptedRuns();
+            for (const record of this.options.store.listRuns({ includeConsumed: true, includeDetached: true })) {
+                this.runs.set(record.runId, recordFromStored(record));
+            }
+        }
+    }
+    startToolRun(input) {
+        this.prune();
+        if (this.options.store) {
+            const stored = this.options.store.createRun({
+                ownerPiboSessionId: input.ownerPiboSessionId,
+                toolName: input.toolName,
+                completionPolicy: input.completionPolicy ?? "tracked",
+                params: input.params,
+                retryable: input.retryable ?? false,
+                maxAttempts: input.maxAttempts ?? 1,
+            });
+            const record = recordFromStored(stored);
+            this.runs.set(record.runId, record);
+            return snapshot(record);
+        }
+        const timestamp = now();
+        const runId = `run_${randomUUID()}`;
+        const record = {
+            runId,
+            kind: "tool",
+            ownerPiboSessionId: input.ownerPiboSessionId,
+            status: "running",
+            completionPolicy: input.completionPolicy ?? "tracked",
+            consumed: false,
+            toolName: input.toolName,
+            createdAt: timestamp,
+            updatedAt: timestamp,
+            summary: `${input.toolName} run is running.`,
+            retryable: input.retryable ?? false,
+            maxAttempts: Math.max(1, input.maxAttempts ?? 1),
+        };
+        this.runs.set(runId, record);
+        return snapshot(record);
+    }
+    complete(runId, result) {
+        const record = this.runs.get(runId);
+        if (!record || terminal(record.status))
+            return undefined;
+        record.status = "completed";
+        record.result = result;
+        record.summary = `${record.toolName} run completed.`;
+        this.finish(record);
+        this.options.store?.updateRun(runId, record);
+        if (record.jobId)
+            this.options.store?.ack(record.jobId, `run-registry:${process.pid}`);
+        return snapshot(record);
+    }
+    fail(runId, error) {
+        const record = this.runs.get(runId);
+        if (!record || terminal(record.status))
+            return undefined;
+        record.status = "failed";
+        record.error = error;
+        record.summary = `${record.toolName} run failed.`;
+        this.finish(record);
+        this.options.store?.updateRun(runId, record);
+        if (record.jobId)
+            this.options.store?.fail(record.jobId, `run-registry:${process.pid}`, error);
+        return snapshot(record);
+    }
+    list(ownerPiboSessionId, options = {}) {
+        this.prune();
+        return [...this.runs.values()]
+            .filter((record) => record.ownerPiboSessionId === ownerPiboSessionId)
+            .filter((record) => options.includeConsumed || !record.consumed)
+            .filter((record) => options.includeDetached || record.completionPolicy !== "detached")
+            .map(snapshot);
+    }
+    status(ownerPiboSessionId, runId) {
+        return snapshot(this.requireOwned(ownerPiboSessionId, runId));
+    }
+    async wait(ownerPiboSessionId, runId, timeoutMs) {
+        const record = this.requireOwned(ownerPiboSessionId, runId);
+        if (terminal(record.status))
+            return { ...snapshot(record), timedOut: false };
+        const boundedTimeoutMs = Math.max(0, Math.min(timeoutMs, 300000));
+        const completed = await new Promise((resolve) => {
+            const timeout = setTimeout(() => {
+                removeWaiter();
+                resolve(undefined);
+            }, boundedTimeoutMs);
+            const waiter = {
+                resolve: (updated) => {
+                    clearTimeout(timeout);
+                    resolve(updated);
+                },
+            };
+            const removeWaiter = () => {
+                const waiters = this.waiters.get(runId);
+                if (!waiters)
+                    return;
+                const index = waiters.indexOf(waiter);
+                if (index >= 0)
+                    waiters.splice(index, 1);
+                if (waiters.length === 0)
+                    this.waiters.delete(runId);
+            };
+            const waiters = this.waiters.get(runId) ?? [];
+            waiters.push(waiter);
+            this.waiters.set(runId, waiters);
+        });
+        if (!completed)
+            return { ...snapshot(record), timedOut: true };
+        return { ...snapshot(completed), timedOut: false };
+    }
+    read(ownerPiboSessionId, runId) {
+        const record = this.requireOwned(ownerPiboSessionId, runId);
+        if (terminal(record.status)) {
+            record.consumed = true;
+            record.updatedAt = now();
+            this.options.store?.updateRun(runId, record);
+        }
+        const output = { ...snapshot(record) };
+        if (record.result)
+            output.result = record.result;
+        if (record.error)
+            output.error = record.error;
+        return output;
+    }
+    cancel(ownerPiboSessionId, runId) {
+        const record = this.requireOwned(ownerPiboSessionId, runId);
+        if (!terminal(record.status)) {
+            record.status = "cancelled";
+            record.summary = `${record.toolName} run cancelled.`;
+            this.finish(record);
+            if (record.jobId)
+                this.options.store?.fail(record.jobId, `run-registry:${process.pid}`, "Run was cancelled.");
+        }
+        record.consumed = true;
+        record.updatedAt = now();
+        this.options.store?.updateRun(runId, record);
+        return snapshot(record);
+    }
+    ack(ownerPiboSessionId, runId) {
+        const record = this.requireOwned(ownerPiboSessionId, runId);
+        record.acknowledgedStatus = record.status;
+        if (terminal(record.status))
+            record.consumed = true;
+        record.updatedAt = now();
+        this.options.store?.updateRun(runId, record);
+        return snapshot(record);
+    }
+    createNotification(ownerPiboSessionId, options = {}) {
+        const records = [...this.runs.values()].filter((record) => this.needsNotification(record, ownerPiboSessionId, options));
+        if (records.length === 0)
+            return undefined;
+        for (const record of records) {
+            record.notifiedStatus = record.status;
+            this.options.store?.updateRun(record.runId, record);
+        }
+        const notification = {
+            completed: [],
+            failed: [],
+            cancelled: [],
+            running: [],
+        };
+        for (const record of records) {
+            const item = snapshot(record);
+            if (record.status === "completed")
+                notification.completed.push(item);
+            else if (record.status === "failed")
+                notification.failed.push(item);
+            else if (record.status === "cancelled")
+                notification.cancelled.push(item);
+            else
+                notification.running.push(item);
+        }
+        return notification;
+    }
+    hasPendingNotification(ownerPiboSessionId, options = {}) {
+        return [...this.runs.values()].some((record) => this.needsNotification(record, ownerPiboSessionId, options));
+    }
+    cancelOwnerRuns(ownerPiboSessionId, reason = "Owner Pibo session was disposed.") {
+        const cancelled = [];
+        for (const record of this.runs.values()) {
+            if (record.ownerPiboSessionId !== ownerPiboSessionId || terminal(record.status))
+                continue;
+            record.status = "cancelled";
+            record.error = reason;
+            record.consumed = true;
+            record.summary = `${record.toolName} run cancelled.`;
+            this.finish(record);
+            this.options.store?.updateRun(record.runId, record);
+            if (record.jobId)
+                this.options.store?.fail(record.jobId, `run-registry:${process.pid}`, reason);
+            cancelled.push(snapshot(record));
+        }
+        return cancelled;
+    }
+    cancelAll(reason = "Run registry was disposed.") {
+        const cancelled = [];
+        for (const record of this.runs.values()) {
+            if (terminal(record.status))
+                continue;
+            record.status = "cancelled";
+            record.error = reason;
+            record.consumed = true;
+            record.summary = `${record.toolName} run cancelled.`;
+            this.finish(record);
+            this.options.store?.updateRun(record.runId, record);
+            if (record.jobId)
+                this.options.store?.fail(record.jobId, `run-registry:${process.pid}`, reason);
+            cancelled.push(snapshot(record));
+        }
+        return cancelled;
+    }
+    prune(options = {}) {
+        const nowMs = options.nowMs ?? Date.now();
+        const consumedTerminalTtlMs = options.consumedTerminalTtlMs ??
+            this.options.consumedTerminalTtlMs ??
+            DEFAULT_CONSUMED_TERMINAL_TTL_MS;
+        const detachedTerminalTtlMs = options.detachedTerminalTtlMs ??
+            this.options.detachedTerminalTtlMs ??
+            DEFAULT_DETACHED_TERMINAL_TTL_MS;
+        let pruned = 0;
+        for (const [runId, record] of this.runs) {
+            if (!terminal(record.status) || !record.completedAt)
+                continue;
+            const ageMs = nowMs - Date.parse(record.completedAt);
+            const shouldPrune = (record.completionPolicy === "detached" && ageMs >= detachedTerminalTtlMs) ||
+                (record.completionPolicy === "tracked" && record.consumed && ageMs >= consumedTerminalTtlMs);
+            if (!shouldPrune)
+                continue;
+            this.runs.delete(runId);
+            pruned += 1;
+        }
+        if (this.options.store) {
+            this.options.store.pruneRuns({ consumedTerminalTtlMs, detachedTerminalTtlMs, nowMs });
+        }
+        return pruned;
+    }
+    requireOwned(ownerPiboSessionId, runId) {
+        const record = this.runs.get(runId);
+        if (!record || record.ownerPiboSessionId !== ownerPiboSessionId) {
+            throw new Error(`Unknown run "${runId}" for session "${ownerPiboSessionId}"`);
+        }
+        return record;
+    }
+    needsNotification(record, ownerPiboSessionId, options = {}) {
+        return (record.ownerPiboSessionId === ownerPiboSessionId &&
+            record.completionPolicy === "tracked" &&
+            !record.consumed &&
+            record.acknowledgedStatus !== record.status &&
+            (options.includeAlreadyNotified || record.notifiedStatus !== record.status));
+    }
+    finish(record) {
+        const timestamp = now();
+        record.updatedAt = timestamp;
+        record.completedAt = timestamp;
+        this.resolveWaiters(record);
+    }
+    resolveWaiters(record) {
+        const waiters = this.waiters.get(record.runId);
+        if (!waiters)
+            return;
+        this.waiters.delete(record.runId);
+        for (const waiter of waiters) {
+            waiter.resolve(record);
+        }
+    }
+}
+function recordFromStored(record) {
+    return {
+        runId: record.runId,
+        kind: record.kind,
+        ownerPiboSessionId: record.ownerPiboSessionId,
+        status: record.status,
+        completionPolicy: record.completionPolicy,
+        consumed: record.consumed,
+        toolName: record.toolName,
+        createdAt: record.createdAt,
+        updatedAt: record.updatedAt,
+        summary: record.summary,
+        completedAt: record.completedAt,
+        result: record.result,
+        error: record.error,
+        notifiedStatus: record.notifiedStatus,
+        acknowledgedStatus: record.acknowledgedStatus,
+        jobId: record.jobId,
+        retryable: record.retryable,
+        maxAttempts: record.maxAttempts,
+    };
+}

package/dist/runs/tools.js

@@ -0,0 +1,185 @@
+import { StringEnum, Type } from "@mariozechner/pi-ai";
+import { defineTool } from "@mariozechner/pi-coding-agent";
+function resultText(prefix, value) {
+    return `${prefix}\n${JSON.stringify(value, null, 2)}`;
+}
+function textFromToolResult(result) {
+    if (!Array.isArray(result.content))
+        return undefined;
+    const text = result.content
+        .map((part) => {
+        if (!part || typeof part !== "object")
+            return "";
+        const candidate = part;
+        return candidate.type === "text" && typeof candidate.text === "string" ? candidate.text : "";
+    })
+        .filter(Boolean)
+        .join("\n");
+    return text || undefined;
+}
+function requireTool(tools, name) {
+    const tool = tools.find((candidate) => candidate.name === name);
+    if (!tool) {
+        throw new Error(`Unknown or non-yieldable tool "${name}"`);
+    }
+    return tool;
+}
+export function createRunToolDefinitions(yieldableTools, controller) {
+    const toolNames = yieldableTools.map((tool) => tool.name);
+    return [
+        defineTool({
+            name: "pibo_run_start",
+            label: "Pibo Run Start",
+            description: "Start a yieldable tool as a yielded run. Use tracked when the result may matter later; use detached only for intentional fire-and-forget work.",
+            promptSnippet: "Use pibo_run_start to run a yieldable tool in the background. It returns a runId. Use pibo_run_read for completed results and pibo_run_wait/status/list/cancel/ack to manage runs.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                toolName: StringEnum(toolNames, { description: "Yieldable tool name to start" }),
+                arguments: Type.Any({ description: "Arguments object for the selected tool" }),
+                completionPolicy: Type.Optional(StringEnum(["tracked", "detached"], {
+                    description: "tracked reminds this agent about completion; detached is fire-and-forget and creates no automatic reminders.",
+                    default: "tracked",
+                })),
+            }),
+            async execute(toolCallId, params, signal, onUpdate, ctx) {
+                const tool = requireTool(yieldableTools, params.toolName);
+                const run = controller.startToolRun({
+                    toolName: tool.name,
+                    params: params.arguments,
+                    completionPolicy: params.completionPolicy,
+                    async execute() {
+                        const result = await tool.execute(toolCallId, params.arguments, signal, onUpdate, ctx);
+                        const resultObject = result;
+                        const text = textFromToolResult(resultObject);
+                        if (resultObject.isError === true) {
+                            throw new Error(text ?? `${tool.name} returned an error result.`);
+                        }
+                        return {
+                            text,
+                            details: resultObject.details ?? result,
+                        };
+                    },
+                });
+                return {
+                    content: [{ type: "text", text: resultText(`Started yielded run ${run.runId}.`, run) }],
+                    details: run,
+                };
+            },
+        }),
+        defineTool({
+            name: "pibo_run_list",
+            label: "Pibo Run List",
+            description: "List yielded runs owned by this agent session.",
+            promptSnippet: "Use pibo_run_list to inspect yielded runs owned by this session.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                includeConsumed: Type.Optional(Type.Boolean({ description: "Include already read, cancelled, or acknowledged runs" })),
+                includeDetached: Type.Optional(Type.Boolean({ description: "Include fire-and-forget detached runs" })),
+            }),
+            async execute(_toolCallId, params) {
+                const runs = controller.listRuns({
+                    includeConsumed: params.includeConsumed,
+                    includeDetached: params.includeDetached,
+                });
+                return {
+                    content: [{ type: "text", text: resultText("Runs:", { runs }) }],
+                    details: { runs },
+                };
+            },
+        }),
+        defineTool({
+            name: "pibo_run_status",
+            label: "Pibo Run Status",
+            description: "Read compact status for one yielded run.",
+            promptSnippet: "Use pibo_run_status to inspect one yielded run without reading its full result.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                runId: Type.String({ description: "Run id returned by pibo_run_start" }),
+            }),
+            async execute(_toolCallId, params) {
+                const run = controller.getRunStatus(params.runId);
+                return {
+                    content: [{ type: "text", text: resultText(`Run ${run.runId} status: ${run.status}.`, run) }],
+                    details: run,
+                };
+            },
+        }),
+        defineTool({
+            name: "pibo_run_wait",
+            label: "Pibo Run Wait",
+            description: "Wait a bounded time for a yielded run. Timeout is normal and does not mean failure.",
+            promptSnippet: "Use pibo_run_wait when blocked on a run. Timeout is normal; call again or continue other work.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                runId: Type.String({ description: "Run id returned by pibo_run_start" }),
+                timeoutMs: Type.Optional(Type.Number({ description: "Maximum wait time in milliseconds, clamped to 300000" })),
+            }),
+            async execute(_toolCallId, params) {
+                const run = await controller.waitForRun(params.runId, params.timeoutMs ?? 30000);
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: resultText(run.timedOut
+                                ? `Run ${run.runId} is still ${run.status}; wait timed out.`
+                                : `Run ${run.runId} reached ${run.status}.`, run),
+                        },
+                    ],
+                    details: run,
+                };
+            },
+        }),
+        defineTool({
+            name: "pibo_run_read",
+            label: "Pibo Run Read",
+            description: "Read the terminal result or error for a yielded run.",
+            promptSnippet: "Use pibo_run_read to retrieve a completed or failed run result. Reading terminal tracked runs consumes reminders.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                runId: Type.String({ description: "Run id returned by pibo_run_start" }),
+            }),
+            async execute(_toolCallId, params) {
+                const run = controller.readRun(params.runId);
+                const text = run.result?.text ?? run.error ?? `Run ${run.runId} is ${run.status}; no terminal result is available yet.`;
+                return {
+                    content: [{ type: "text", text }],
+                    details: run,
+                };
+            },
+        }),
+        defineTool({
+            name: "pibo_run_cancel",
+            label: "Pibo Run Cancel",
+            description: "Cancel a yielded run if possible and suppress future reminders.",
+            promptSnippet: "Use pibo_run_cancel when a yielded run is no longer needed.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                runId: Type.String({ description: "Run id returned by pibo_run_start" }),
+            }),
+            async execute(_toolCallId, params) {
+                const run = await controller.cancelRun(params.runId);
+                return {
+                    content: [{ type: "text", text: resultText(`Cancelled run ${run.runId}.`, run) }],
+                    details: run,
+                };
+            },
+        }),
+        defineTool({
+            name: "pibo_run_ack",
+            label: "Pibo Run Ack",
+            description: "Acknowledge a yielded run update and suppress reminders for its current state.",
+            promptSnippet: "Use pibo_run_ack when you intentionally do not need to read a completed result or do not need more reminders for the current running state.",
+            executionMode: "parallel",
+            parameters: Type.Object({
+                runId: Type.String({ description: "Run id returned by pibo_run_start" }),
+            }),
+            async execute(_toolCallId, params) {
+                const run = controller.ackRun(params.runId);
+                return {
+                    content: [{ type: "text", text: resultText(`Acknowledged run ${run.runId}.`, run) }],
+                    details: run,
+                };
+            },
+        }),
+    ];
+}