@pasko70/pibo 1.9.9 → 1.9.10

package/dist/resources/reaper.js

@@ -0,0 +1,145 @@
+import { applyResourceReapPlan, planResourceReap } from "./lifecycle.js";
+import { claimResourceReaperOwnership, defaultResourceReaperStatePath, releaseResourceReaperOwnership, writeResourceReaperState, } from "./reaper-state.js";
+export class ResourceReaperService {
+    options;
+    intervalMs;
+    initialDelayMs;
+    statePath;
+    lockPath;
+    plan;
+    apply;
+    now;
+    timer;
+    running = false;
+    stopped = true;
+    ownsTimer = false;
+    state;
+    constructor(options = {}) {
+        this.options = options;
+        this.intervalMs = Math.max(1_000, options.intervalMs ?? readPositiveInteger(process.env.PIBO_RESOURCE_REAPER_INTERVAL_MS) ?? 5 * 60_000);
+        this.initialDelayMs = Math.max(0, options.initialDelayMs ?? readNonNegativeInteger(process.env.PIBO_RESOURCE_REAPER_INITIAL_DELAY_MS) ?? 30_000);
+        this.statePath = options.statePath ?? defaultResourceReaperStatePath();
+        this.lockPath = `${this.statePath}.lock`;
+        this.plan = options.plan ?? planResourceReap;
+        this.apply = options.apply ?? applyResourceReapPlan;
+        this.now = options.clock ?? (() => new Date());
+    }
+    async start() {
+        if (!this.stopped)
+            return;
+        this.ownsTimer = await claimResourceReaperOwnership(this.lockPath);
+        if (!this.ownsTimer)
+            return;
+        this.stopped = false;
+        const now = this.now();
+        this.state = {
+            status: "running",
+            pid: process.pid,
+            startedAt: now.toISOString(),
+            intervalMs: this.intervalMs,
+            nextRunAt: new Date(now.getTime() + this.initialDelayMs).toISOString(),
+        };
+        await this.persist();
+        this.arm(this.initialDelayMs);
+    }
+    async stop() {
+        this.stopped = true;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = undefined;
+        if (this.state && this.ownsTimer) {
+            this.state = { ...this.state, status: "stopped", nextRunAt: undefined };
+            await this.persist();
+        }
+        if (this.ownsTimer)
+            await releaseResourceReaperOwnership(this.lockPath);
+        this.ownsTimer = false;
+    }
+    async runNow() {
+        if (!this.ownsTimer || this.running)
+            return undefined;
+        this.running = true;
+        const runAt = this.now();
+        try {
+            const plan = await this.plan({
+                includeDev: this.options.includeDev,
+                maxAgeMinutes: this.options.maxAgeMinutes,
+                idleTimeoutMinutes: this.options.idleTimeoutMinutes,
+                unmanagedBrowserGraceMinutes: this.options.unmanagedBrowserGraceMinutes,
+                browserPoolRoot: this.options.browserPoolRoot,
+                browserUseHome: this.options.browserUseHome,
+                exemptBrowserPids: this.options.exemptBrowserPids,
+                now: runAt,
+            });
+            const result = await this.apply(plan);
+            this.state = {
+                ...(this.state ?? {
+                    status: "running",
+                    pid: process.pid,
+                    startedAt: runAt.toISOString(),
+                    intervalMs: this.intervalMs,
+                }),
+                status: "running",
+                lastRunAt: runAt.toISOString(),
+                nextRunAt: new Date(this.now().getTime() + this.intervalMs).toISOString(),
+                lastResult: {
+                    browserPools: result.browserResults.filter((item) => item.reaped).length,
+                    unmanagedBrowsers: result.terminatedUnmanagedBrowsers.length,
+                    staleFiles: result.removedStaleFiles.length,
+                    computeWorkers: result.removedComputeWorkers.length,
+                },
+                lastError: undefined,
+            };
+            console.error(JSON.stringify({ event: "resource_reaper_finished", at: runAt.toISOString(), ...this.state.lastResult }));
+            await this.persist();
+            return result;
+        }
+        catch (error) {
+            const message = error instanceof Error ? error.message : String(error);
+            this.state = {
+                ...(this.state ?? {
+                    status: "running",
+                    pid: process.pid,
+                    startedAt: runAt.toISOString(),
+                    intervalMs: this.intervalMs,
+                }),
+                status: "running",
+                lastRunAt: runAt.toISOString(),
+                nextRunAt: new Date(this.now().getTime() + this.intervalMs).toISOString(),
+                lastError: message,
+            };
+            console.error(JSON.stringify({ event: "resource_reaper_failed", at: runAt.toISOString(), error: message }));
+            await this.persist();
+            return undefined;
+        }
+        finally {
+            this.running = false;
+        }
+    }
+    arm(delayMs) {
+        if (this.stopped)
+            return;
+        if (this.timer)
+            clearTimeout(this.timer);
+        this.timer = setTimeout(() => {
+            void this.runNow().finally(() => this.arm(this.intervalMs));
+        }, delayMs);
+        this.timer.unref?.();
+    }
+    async persist() {
+        if (this.state)
+            await writeResourceReaperState(this.statePath, this.state);
+    }
+}
+function readPositiveInteger(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed > 0 ? parsed : undefined;
+}
+function readNonNegativeInteger(value) {
+    if (!value)
+        return undefined;
+    const parsed = Number(value);
+    return Number.isInteger(parsed) && parsed >= 0 ? parsed : undefined;
+}

package/dist/runs/registry.js

@@ -0,0 +1,360 @@
+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,
+        controllerPiboSessionId: record.controllerPiboSessionId,
+        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();
+    listeners = new Set();
+    subscribe(listener) {
+        this.listeners.add(listener);
+        return () => this.listeners.delete(listener);
+    }
+    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({
+                controllerPiboSessionId: input.controllerPiboSessionId,
+                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);
+            const output = snapshot(record);
+            this.notify({ type: "run_started", run: output });
+            return output;
+        }
+        const timestamp = now();
+        const runId = `run_${randomUUID()}`;
+        const record = {
+            runId,
+            kind: "tool",
+            controllerPiboSessionId: input.controllerPiboSessionId,
+            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);
+        const output = snapshot(record);
+        this.notify({ type: "run_started", run: output });
+        return output;
+    }
+    complete(runId, result) {
+        const record = this.runs.get(runId);
+        if (!record || terminal(record.status))
+            return undefined;
+        const previousStatus = record.status;
+        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}`);
+        const output = snapshot(record);
+        this.notify({ type: "run_changed", run: output, previousStatus });
+        return output;
+    }
+    fail(runId, error) {
+        const record = this.runs.get(runId);
+        if (!record || terminal(record.status))
+            return undefined;
+        const previousStatus = record.status;
+        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);
+        const output = snapshot(record);
+        this.notify({ type: "run_changed", run: output, previousStatus, reason: error });
+        return output;
+    }
+    list(controllerPiboSessionId, options = {}) {
+        this.prune();
+        return [...this.runs.values()]
+            .filter((record) => record.controllerPiboSessionId === controllerPiboSessionId)
+            .filter((record) => options.includeConsumed || !record.consumed)
+            .filter((record) => options.includeDetached || record.completionPolicy !== "detached")
+            .map(snapshot);
+    }
+    listAll(options = {}) {
+        this.prune();
+        return [...this.runs.values()]
+            .filter((record) => options.includeConsumed || !record.consumed)
+            .filter((record) => options.includeDetached || record.completionPolicy !== "detached")
+            .map(snapshot);
+    }
+    status(controllerPiboSessionId, runId) {
+        return snapshot(this.requireRunForController(controllerPiboSessionId, runId));
+    }
+    async wait(controllerPiboSessionId, runId, timeoutMs) {
+        const record = this.requireRunForController(controllerPiboSessionId, 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(controllerPiboSessionId, runId) {
+        const record = this.requireRunForController(controllerPiboSessionId, runId);
+        if (terminal(record.status)) {
+            record.consumed = true;
+            record.updatedAt = now();
+            this.options.store?.updateRun(runId, record);
+            this.notify({ type: "run_consumed", run: snapshot(record) });
+        }
+        const output = { ...snapshot(record) };
+        if (record.result)
+            output.result = record.result;
+        if (record.error)
+            output.error = record.error;
+        return output;
+    }
+    cancel(controllerPiboSessionId, runId) {
+        const record = this.requireRunForController(controllerPiboSessionId, runId);
+        const previousStatus = record.status;
+        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);
+        const output = snapshot(record);
+        this.notify({ type: "run_changed", run: output, previousStatus, reason: "Run was cancelled." });
+        return output;
+    }
+    ack(controllerPiboSessionId, runId) {
+        const record = this.requireRunForController(controllerPiboSessionId, runId);
+        record.acknowledgedStatus = record.status;
+        if (terminal(record.status))
+            record.consumed = true;
+        record.updatedAt = now();
+        this.options.store?.updateRun(runId, record);
+        const output = snapshot(record);
+        this.notify({ type: "run_acknowledged", run: output });
+        return output;
+    }
+    createNotification(controllerPiboSessionId, options = {}) {
+        const records = [...this.runs.values()].filter((record) => this.needsNotification(record, controllerPiboSessionId, 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(controllerPiboSessionId, options = {}) {
+        return [...this.runs.values()].some((record) => this.needsNotification(record, controllerPiboSessionId, options));
+    }
+    cancelControllerRuns(controllerPiboSessionId, reason = "Controller Pibo session was disposed.") {
+        const cancelled = [];
+        for (const record of this.runs.values()) {
+            if (record.controllerPiboSessionId !== controllerPiboSessionId || 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);
+            const output = snapshot(record);
+            this.notify({ type: "run_changed", run: output, previousStatus: "running", reason });
+            cancelled.push(output);
+        }
+        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);
+            const output = snapshot(record);
+            this.notify({ type: "run_changed", run: output, previousStatus: "running", reason });
+            cancelled.push(output);
+        }
+        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);
+            this.notify({ type: "run_removed", runId, controllerPiboSessionId: record.controllerPiboSessionId });
+            pruned += 1;
+        }
+        if (this.options.store) {
+            this.options.store.pruneRuns({ consumedTerminalTtlMs, detachedTerminalTtlMs, nowMs });
+        }
+        return pruned;
+    }
+    requireRunForController(controllerPiboSessionId, runId) {
+        const record = this.runs.get(runId);
+        if (!record || record.controllerPiboSessionId !== controllerPiboSessionId) {
+            throw new Error(`Unknown run "${runId}" for session "${controllerPiboSessionId}"`);
+        }
+        return record;
+    }
+    needsNotification(record, controllerPiboSessionId, options = {}) {
+        return (record.controllerPiboSessionId === controllerPiboSessionId &&
+            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);
+        }
+    }
+    notify(event) {
+        for (const listener of this.listeners)
+            listener(event);
+    }
+}
+function recordFromStored(record) {
+    return {
+        runId: record.runId,
+        kind: record.kind,
+        controllerPiboSessionId: record.controllerPiboSessionId,
+        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 "@earendil-works/pi-ai";
+import { defineTool } from "@earendil-works/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,
+                };
+            },
+        }),
+    ];
+}