@code-yeongyu/senpi-agent-core 2026.9.30 → 2026.10.1

package/dist/harness/pico3/kinds/job.js

@@ -0,0 +1,143 @@
+const failed = (reason, detail) => ({
+    status: "failed",
+    failure: { reason, detail },
+});
+const notice = (text, now) => ({
+    kind: "pi.notice",
+    model: [{ role: "user", content: text, timestamp: now }],
+});
+const jobKind = {
+    name: "pi.job",
+    slot: () => ({}),
+    describe: (task) => ({
+        stage: task.checkpoint?.phase ?? "starting",
+        ...(task.slot ?? {}),
+    }),
+    inflight: ["spawning", "running"],
+    phases: {
+        async waiting(task, runtime, ctx) {
+            await runtime.sleep(task.checkpoint.untilMs, ctx);
+            return spawn(task, task.checkpoint.occurrence, runtime, ctx);
+        },
+        async spawning(task, runtime, ctx) {
+            return reconcile(task, task.checkpoint, runtime, ctx);
+        },
+        async running(task, runtime, ctx) {
+            return reconcile(task, task.checkpoint, runtime, ctx);
+        },
+    },
+    async initial(task, runtime, ctx) {
+        if (runtime.processHost === undefined)
+            return { done: () => failed("spawn", "no process host") };
+        const now = runtime.now();
+        const untilMs = task.input.notBefore ?? now;
+        if (untilMs > now)
+            return { next: { phase: "waiting", untilMs, occurrence: 1 } };
+        return spawn(task, 1, runtime, ctx);
+    },
+    async abort(task, runtime, ctx) {
+        const checkpoint = task.checkpoint;
+        if (checkpoint === undefined || checkpoint.phase === "waiting" || runtime.processHost === undefined)
+            return async () => ({ killed: false });
+        await runtime.processHost.kill(checkpoint.key, "SIGTERM", ctx);
+        await runtime.sleep(runtime.now() + 5000, ctx);
+        await runtime.processHost.kill(checkpoint.key, "SIGKILL", ctx);
+        return async () => ({ killed: true });
+    },
+};
+export const job = Object.freeze(jobKind);
+async function spawn(task, occurrence, runtime, ctx) {
+    const key = `${task.id}:${occurrence}`;
+    await runtime.commit((tx) => tx.checkpoint({ phase: "spawning", key, occurrence }), ctx);
+    try {
+        await runtime.processHost.start(key, task.input, ctx);
+    }
+    catch (error) {
+        if (ctx.abortSignal?.aborted)
+            throw error;
+        return {
+            done: async (tx, current) => {
+                if (task.input.notify)
+                    await tx.write(current.conversationId, notice(`job ${task.id} failed to start: ${String(error)}`, runtime.now()));
+                return failed("spawn", String(error));
+            },
+        };
+    }
+    await runtime.commit((tx) => tx.checkpoint({ phase: "running", key, occurrence }), ctx);
+    return poll(task, key, occurrence, runtime, ctx);
+}
+async function reconcile(task, checkpoint, runtime, ctx) {
+    if (runtime.processHost === undefined)
+        return { done: () => failed("interrupted", "no process host after restart") };
+    let status;
+    try {
+        status = await runtime.processHost.status(checkpoint.key, ctx);
+    }
+    catch (error) {
+        return { done: () => failed("interrupted", `host status failed: ${String(error)}`) };
+    }
+    if (status.status === "unknown") {
+        if (!task.input.rerun)
+            return { done: () => failed("interrupted", "process outcome unknown") };
+        return spawn(task, checkpoint.occurrence, runtime, ctx);
+    }
+    if (checkpoint.phase === "spawning") {
+        await runtime.commit((tx) => tx.checkpoint({ phase: "running", key: checkpoint.key, occurrence: checkpoint.occurrence }), ctx);
+    }
+    return poll(task, checkpoint.key, checkpoint.occurrence, runtime, ctx);
+}
+async function poll(task, key, occurrence, runtime, ctx) {
+    for (let attempt = 0;; attempt++) {
+        let status;
+        try {
+            status = await runtime.processHost.status(key, ctx);
+        }
+        catch (error) {
+            return { done: () => failed("interrupted", `host status failed: ${String(error)}`) };
+        }
+        if (status.status === "unknown") {
+            if (!task.input.rerun)
+                return { done: () => failed("interrupted", "process outcome unknown") };
+            return spawn(task, occurrence, runtime, ctx);
+        }
+        const snapshot = status;
+        await runtime.commit((tx, current) => {
+            const output = tx.slot({ id: current.id, kind: jobKind });
+            output.stdout = snapshot.stdout;
+            output.stderr = snapshot.stderr;
+            output.droppedStdout = snapshot.droppedStdout;
+            output.droppedStderr = snapshot.droppedStderr;
+            if (snapshot.status === "exited")
+                output.exitCode = snapshot.exitCode;
+        }, ctx);
+        if (snapshot.status === "exited") {
+            const { exitCode, stdout, stderr } = snapshot;
+            if (task.input.every === undefined) {
+                return {
+                    done: async (tx, current) => {
+                        if (task.input.notify)
+                            await tx.write(current.conversationId, notice(`job ${task.id} exited with code ${exitCode}`, runtime.now()));
+                        return { status: "completed", result: { exitCode, occurrences: occurrence, stdout, stderr } };
+                    },
+                };
+            }
+            const untilMs = runtime.now() + task.input.every;
+            return {
+                next: async (tx, current) => {
+                    if (task.input.notify)
+                        await tx.write(current.conversationId, notice(`job ${task.id} occurrence ${occurrence} exited with code ${exitCode}`, runtime.now()));
+                    const output = tx.slot({ id: current.id, kind: jobKind });
+                    output.stdout = "";
+                    output.stderr = "";
+                    output.droppedStdout = 0;
+                    output.droppedStderr = 0;
+                    delete output.exitCode;
+                    output.occurrence = occurrence + 1;
+                    return { phase: "waiting", untilMs, occurrence: occurrence + 1 };
+                },
+            };
+        }
+        await runtime.sleep(runtime.now() + Math.min(1000, 100 * 2 ** Math.min(attempt, 4)), ctx);
+    }
+}
+//# sourceMappingURL=job.js.map

package/dist/harness/pico3/kinds/plugin.d.ts

@@ -0,0 +1,15 @@
+import { type JsonValue, type Kind } from "../types.ts";
+export type PluginInput = {
+    handler: string;
+    input: JsonValue;
+};
+type PluginCheckpoint = {
+    phase: "started";
+};
+type PluginFailure = {
+    reason: "missing_handler" | "threw";
+    detail: string;
+};
+export declare const plugin: Readonly<Kind<PluginInput, PluginCheckpoint, import("@earendil-works/chord").JsonValue, PluginFailure, null, object, import("../types.ts").KindConfig<import("../types.ts").ConfigShape, import("../types.ts").ConfigShape>, import("../types.ts").JsonObject, import("../types.ts").TaskTx>>;
+export {};
+//# sourceMappingURL=plugin.d.ts.map

package/dist/harness/pico3/kinds/plugin.js

@@ -0,0 +1,35 @@
+import { toStored } from "../types.js";
+import { taskApi } from "./task-api.js";
+const pluginKind = {
+    name: "pi.plugin",
+    inflight: ["started"],
+    phases: {
+        async started(task, runtime, ctx) {
+            return run(task, runtime, ctx);
+        },
+    },
+    async initial(task, runtime, ctx) {
+        await runtime.commit((tx) => tx.checkpoint({ phase: "started" }), ctx);
+        return run(task, runtime, ctx);
+    },
+    async abort() {
+        return async () => null;
+    },
+};
+export const plugin = Object.freeze(pluginKind);
+async function run(task, runtime, ctx) {
+    const handler = runtime.plugins.get(task.input.handler);
+    if (handler === undefined) {
+        return { done: () => ({ status: "failed", failure: { reason: "missing_handler", detail: task.input.handler } }) };
+    }
+    try {
+        const result = toStored(await handler(task.input.input, taskApi(task, runtime), ctx));
+        return { done: () => ({ status: "completed", result }) };
+    }
+    catch (error) {
+        if (ctx.abortSignal?.aborted)
+            throw error;
+        return { done: () => ({ status: "failed", failure: { reason: "threw", detail: String(error) } }) };
+    }
+}
+//# sourceMappingURL=plugin.js.map

package/dist/harness/pico3/kinds/post-tools.d.ts

@@ -0,0 +1,22 @@
+import type { Context } from "@earendil-works/chord";
+import { type CoreKind, type HookInfo, type Id } from "../types.ts";
+export type PostToolsInput = {
+    inputs: Id[];
+    assistant: Id;
+    tools: Id[];
+};
+export type PostToolsResult = {
+    successor?: Id;
+    ended?: "terminate" | "handoff";
+};
+export interface PostToolsHooks {
+    afterTools(assistant: Id, results: Id[], info: HookInfo, ctx: Context): void | Promise<void>;
+}
+export declare const postToolsConfig: {
+    readonly sticky: {
+        readonly steeringMode: "all" | "one-at-a-time";
+        readonly followUpMode: "all" | "one-at-a-time";
+    };
+};
+export declare const postTools: CoreKind<PostToolsInput, never, PostToolsResult, never, null, PostToolsHooks, typeof postToolsConfig>;
+//# sourceMappingURL=post-tools.d.ts.map

package/dist/harness/pico3/kinds/post-tools.js

@@ -0,0 +1,145 @@
+import { toStored } from "../types.js";
+export const postToolsConfig = {
+    sticky: {
+        steeringMode: "one-at-a-time",
+        followUpMode: "one-at-a-time",
+    },
+};
+export const postTools = {
+    name: "pi.post_tools",
+    turn: true,
+    config: postToolsConfig,
+    phases: {},
+    async initial(task, rt, ctx) {
+        const rows = await rt.commit(async (tx) => {
+            const assistant = await tx.entry(task.input.assistant);
+            const calls = (assistant?.model?.[0]?.content ?? []).filter((content) => content.type === "toolCall");
+            return Promise.all(task.input.tools.map(async (id, index) => {
+                const toolTask = (await tx.task(id));
+                const call = calls[index];
+                if (toolTask.outcome?.status === "completed") {
+                    const result = toolTask.outcome.result;
+                    return {
+                        call,
+                        entry: result.entry,
+                        control: result.control,
+                        missing: undefined,
+                    };
+                }
+                if (toolTask.outcome?.status === "aborted") {
+                    const aborted = toolTask.outcome.result;
+                    return {
+                        call,
+                        entry: aborted.entry,
+                        control: undefined,
+                        missing: aborted.entry === undefined ? "aborted" : undefined,
+                    };
+                }
+                return { call, entry: undefined, control: undefined, missing: "orphaned" };
+            }));
+        }, ctx);
+        const results = rows.map((row) => row.entry).filter((entry) => entry !== undefined);
+        await rt.hooks.each(ctx, (hook, api) => hook.afterTools?.(task.input.assistant, results, api, ctx));
+        return {
+            done: async (tx, current) => {
+                const conversationId = current.conversationId;
+                const head = await tx.newestEntry(conversationId, { withHead: true });
+                const state = tx.rewindable(conversationId);
+                const selectedTools = [...state.selectedTools];
+                let terminate = false;
+                let handoff;
+                for (const row of rows) {
+                    for (const name of row.control?.addTools ?? [])
+                        if (!selectedTools.includes(name))
+                            selectedTools.push(name);
+                    if (row.control?.terminate)
+                        terminate = true;
+                    if (row.control?.handoff !== undefined)
+                        handoff = row.control.handoff;
+                }
+                if (selectedTools.length !== state.selectedTools.length) {
+                    state.selectedTools = selectedTools;
+                    tx.emit({ type: "config.changed", keys: ["selectedTools"] });
+                }
+                for (const row of rows) {
+                    if (row.missing === undefined)
+                        continue;
+                    tx.appendEntry(conversationId, {
+                        kind: "pi.tool_result",
+                        model: [
+                            toStored({
+                                role: "toolResult",
+                                toolCallId: row.call.id,
+                                toolName: row.call.name,
+                                content: [{ type: "text", text: `Tool result unavailable: task ${row.missing}.` }],
+                                isError: true,
+                                timestamp: rt.now(),
+                            }),
+                        ],
+                        data: { diagnostics: [{ severity: "error", message: row.missing, code: row.missing }] },
+                    });
+                    tx.emit({
+                        type: "warning",
+                        source: "post_tools",
+                        message: `synthesized ${row.missing} tool result for ${row.call.id}`,
+                    });
+                }
+                let headBoundary = head?.id;
+                if (handoff !== undefined) {
+                    headBoundary = tx.appendEntry(conversationId, {
+                        kind: "pi.handoff",
+                        head: "self",
+                        model: [{ role: "user", content: handoff, timestamp: rt.now() }],
+                    });
+                }
+                if (handoff !== undefined || terminate) {
+                    tx.sticky(conversationId).turn = { tools: [] };
+                    await tx.resolveInputs(task.input.inputs, { status: "done", answer: task.input.assistant });
+                    tx.emit({ type: "turn.ended", inputs: task.input.inputs, status: "done", answer: task.input.assistant });
+                    const { triggers } = await tx.boundary(conversationId, "final", headBoundary);
+                    if (triggers.length > 0)
+                        tx.emit({ type: "turn.started", inputs: triggers });
+                    const ended = handoff !== undefined ? "handoff" : "terminate";
+                    return {
+                        status: "completed",
+                        result: triggers.length > 0
+                            ? { ended, successor: tx.createTask({ kind: "pi.generation", input: { inputs: triggers } }) }
+                            : { ended },
+                    };
+                }
+                const { triggers, terminated } = await tx.boundary(conversationId, "postTools", headBoundary);
+                if (terminated) {
+                    tx.sticky(conversationId).turn = { tools: [] };
+                    await tx.resolveInputs(task.input.inputs, { status: "unanswered", reason: "terminated" });
+                    tx.emit({ type: "turn.ended", inputs: task.input.inputs, status: "unanswered", reason: "terminated" });
+                    if (triggers.length > 0)
+                        tx.emit({ type: "turn.started", inputs: triggers });
+                    return {
+                        status: "completed",
+                        result: triggers.length > 0
+                            ? { successor: tx.createTask({ kind: "pi.generation", input: { inputs: triggers } }) }
+                            : {},
+                    };
+                }
+                return {
+                    status: "completed",
+                    result: {
+                        successor: tx.createTask({
+                            kind: "pi.generation",
+                            input: { inputs: [...task.input.inputs, ...triggers] },
+                        }),
+                    },
+                };
+            },
+        };
+    },
+    async abort(task) {
+        return async (tx, current) => {
+            tx.sticky(current.conversationId).turn = { tools: [] };
+            await tx.resolveInputs(task.input.inputs, { status: "unanswered", reason: "aborted" });
+            tx.emit({ type: "turn.ended", inputs: task.input.inputs, status: "unanswered", reason: "aborted" });
+            return null;
+        };
+    },
+};
+//# sourceMappingURL=post-tools.js.map

package/dist/harness/pico3/kinds/task-api.d.ts

@@ -0,0 +1,3 @@
+import type { Runtime, Task, ToolApi } from "../types.ts";
+export declare function taskApi(task: Task, runtime: Runtime): ToolApi;
+//# sourceMappingURL=task-api.d.ts.map

package/dist/harness/pico3/kinds/task-api.js

@@ -0,0 +1,45 @@
+export function taskApi(task, runtime) {
+    const isKind = (value) => typeof value === "object" && value !== null && "name" in value && "initial" in value;
+    return {
+        taskId: task.id,
+        conversationId: task.conversationId,
+        callId: "",
+        stream: () => {
+            throw new Error("stream is only available to tools");
+        },
+        progress: () => {
+            throw new Error("progress is only available to tools");
+        },
+        memo: (() => Promise.reject(new Error("memo is only available to tools"))),
+        async conversation(spec, ctx) {
+            const id = await runtime.createOwnedConversation(spec, ctx);
+            return {
+                id,
+                send: async (input, childContext) => {
+                    const inputId = await runtime.sendOwned(id, input, childContext);
+                    return {
+                        id: inputId,
+                        wait: (waitContext) => runtime.waitForInput(inputId, waitContext),
+                        result: (resultContext) => runtime.commit((tx) => tx.input(inputId), resultContext),
+                    };
+                },
+                abort: (childContext) => runtime.abortConversation(id, childContext),
+            };
+        },
+        task: ((kind, input, opts, ctx) => {
+            if (!isKind(kind))
+                throw new Error("task(): pass a kind token");
+            return runtime.commit((tx) => tx.createTask(kind, input, opts), ctx);
+        }),
+        getTask: async (ref, ctx) => (await runtime.commit((tx) => tx.task(ref.id), ctx)),
+        waitForTask: (ref, ctx) => runtime.waitForTask(ref.id, ctx),
+        slot: (ref, ctx) => runtime.commit(async (tx) => {
+            const storedTask = await tx.task(ref.id);
+            if (storedTask === undefined)
+                return undefined;
+            return (tx.snapshot({ doc: "sticky", conversationId: storedTask.conversationId }).tasks[ref.id] ??
+                undefined);
+        }, ctx),
+    };
+}
+//# sourceMappingURL=task-api.js.map

package/dist/harness/pico3/kinds/tool.d.ts

@@ -0,0 +1,43 @@
+import type { Context } from "@earendil-works/chord";
+import type { ToolCall } from "@earendil-works/pi-ai";
+import { type AnyToolDeclaration, type BeforeToolApi, type CoreKind, type HookInfo, type HookResult, type Id, type Step, type Stored, type ToolControl, type ToolResult } from "../types.ts";
+export type StoredToolCall = Stored<ToolCall>;
+export type ToolInput = {
+    assistant: Id;
+    call: StoredToolCall;
+    offered: string[];
+    index: number;
+};
+export type ToolCheckpoint = {
+    phase: "started";
+    replay: "safe" | "unsafe";
+    call: StoredToolCall;
+};
+export type ToolTaskResult = {
+    entry: Id;
+    control?: ToolControl;
+};
+/** Hook points this kind calls. Register with `h.hooks(namespace, kinds.tool, { … })`. */
+export interface ToolHooks {
+    /** Before invocation, before `started`. Chain on `call`; `{ block }` stops it. A throw blocks. */
+    beforeTool(call: StoredToolCall, api: BeforeToolApi, ctx: Context): HookResult<{
+        call?: StoredToolCall;
+        block?: string;
+    }>;
+    /** After the tool returns; may replace the result. Chain. */
+    afterTool(call: StoredToolCall, result: ToolResult, api: HookInfo & {
+        readonly callId: string;
+    }, ctx: Context): HookResult<ToolResult>;
+}
+/** Validate arguments with the tool's real schema (TypeBox 1.x). */
+export declare function invalid(declaration: AnyToolDeclaration, call: StoredToolCall): string | undefined;
+export declare const tool: CoreKind<ToolInput, ToolCheckpoint, ToolTaskResult, never, {
+    entry: Id;
+}, ToolHooks>;
+export declare const DEFAULT_BOUNDS: {
+    maxBytes: number;
+    maxLines: number;
+    retain: "head";
+};
+export type { Step };
+//# sourceMappingURL=tool.d.ts.map