@alpacakit/agents 0.1.0-beta.19

package/dist/structured/run-structured.js

@@ -0,0 +1,202 @@
+/**
+ * Structured output (design "Structured output"): a decorator over
+ * kernel runs. Repair happens WITHIN one candidate — it composes below
+ * the fleet, never inside it. Exhausted repairs fail with
+ * `output_rejected` carrying the issue list.
+ */
+import { AGENT_ERROR_CODE, AgentError, } from "../core/error.js";
+import { EventBroadcast } from "../kernel/handle.js";
+import { DEFAULT_MARKERS, defaultExtractionStrategies, extractBlock, parseJsonResilient, } from "./extract.js";
+const DEFAULT_MAX_REPAIRS = 2;
+const PREVIOUS_BLOCK_TRUNCATE_CHARS = 12_000;
+const STRUCTURED_RUN_OPTION_KEY = "contract";
+export const CONTRACT_PROMPT_PLACEMENT = {
+    append: "append",
+    embedded: "embedded",
+};
+export function isStructuredRunOptions(options) {
+    return STRUCTURED_RUN_OPTION_KEY in options;
+}
+export function resolveStructuredRunOptions(options) {
+    const { contract, ...runOptions } = options;
+    return { runOptions, contract };
+}
+function defaultContractInstruction(markers) {
+    return [
+        "Reply with a single JSON value that satisfies the requested contract.",
+        `Wrap it between the exact markers ${markers.start} and ${markers.end}.`,
+        "Do not put anything else between the markers.",
+    ].join("\n");
+}
+function defaultRepairPrompt(ctx) {
+    const issueLines = ctx.issues.map((issue) => `- ${issue.path.join(".") || "(root)"}: ${issue.message}`);
+    const previous = ctx.previousBlock === null
+        ? "(no output block was found)"
+        : ctx.previousBlock.slice(0, PREVIOUS_BLOCK_TRUNCATE_CHARS);
+    return [
+        ctx.basePrompt,
+        "",
+        ctx.contractInstruction,
+        "",
+        "Your previous reply did not satisfy the contract.",
+        "Previous block:",
+        previous,
+        "Problems:",
+        ...issueLines,
+        "Reply again with only the corrected JSON between the markers.",
+    ].join("\n");
+}
+function toIssuePath(path) {
+    if (path === undefined) {
+        return [];
+    }
+    return path.map((segment) => {
+        const key = typeof segment === "object" && segment !== null && "key" in segment
+            ? segment.key
+            : segment;
+        return typeof key === "number" ? key : String(key);
+    });
+}
+function toIssues(issues) {
+    return issues.map((issue) => ({
+        path: toIssuePath(issue.path),
+        code: "schema",
+        message: issue.message,
+    }));
+}
+function resolveParse(schema) {
+    if (typeof schema === "function") {
+        return async (block) => schema(block);
+    }
+    return async (block) => {
+        const parsed = parseJsonResilient(block);
+        if (!parsed.ok) {
+            return {
+                ok: false,
+                issues: [{ path: [], code: "invalid_json", message: parsed.error }],
+            };
+        }
+        const validated = await schema["~standard"].validate(parsed.value);
+        if (validated.issues !== undefined) {
+            return { ok: false, issues: toIssues(validated.issues) };
+        }
+        return { ok: true, value: validated.value };
+    };
+}
+function resolveContract(contract) {
+    const markers = contract.markers ?? DEFAULT_MARKERS;
+    const validate = contract.validate?.bind(contract);
+    const instruction = contract.renderContract?.(markers) ?? defaultContractInstruction(markers);
+    return {
+        parse: resolveParse(contract.schema),
+        markers,
+        strategies: contract.extractionStrategies ?? defaultExtractionStrategies,
+        instruction,
+        initialPrompt: contract.promptPlacement === CONTRACT_PROMPT_PLACEMENT.append
+            ? (basePrompt) => `${basePrompt}\n\n${instruction}`
+            : (basePrompt) => basePrompt,
+        maxRepairs: contract.repair?.maxAttempts ?? DEFAULT_MAX_REPAIRS,
+        shouldRetry: contract.repair?.shouldRetry ?? (() => true),
+        renderRepairPrompt: contract.repair?.renderRepairPrompt ?? defaultRepairPrompt,
+        validate: validate === undefined
+            ? async () => []
+            : async (value) => validate(value),
+    };
+}
+async function evaluateRun(contract, text) {
+    const block = extractBlock(text, contract.markers, contract.strategies);
+    if (block === null) {
+        return {
+            block,
+            outcome: {
+                ok: false,
+                issues: [
+                    {
+                        path: [],
+                        code: "no_output_block",
+                        message: "No output block was found in the agent's reply",
+                    },
+                ],
+            },
+        };
+    }
+    const outcome = await contract.parse(block);
+    if (!outcome.ok) {
+        return { block, outcome };
+    }
+    const semanticIssues = await contract.validate(outcome.value);
+    if (semanticIssues.length > 0) {
+        return { block, outcome: { ok: false, issues: semanticIssues } };
+    }
+    return { block, outcome };
+}
+export function startStructuredRun(input) {
+    const broadcast = new EventBroadcast();
+    const result = driveStructured(input, broadcast);
+    // A caller may only iterate events; keep the result rejection observed.
+    result.catch(() => { });
+    return Object.assign(result, { events: broadcast.events, result });
+}
+async function driveStructured(input, broadcast) {
+    const resolved = resolveContract(input.contract);
+    const attempts = [];
+    let prompt = resolved.initialPrompt(input.options.prompt);
+    let lastIssues = [];
+    let lastRun = null;
+    try {
+        for (let attempt = 0; attempt <= resolved.maxRepairs; attempt += 1) {
+            const result = await forwardRun(input.runAttempt({ ...input.options, prompt }), broadcast);
+            lastRun = result;
+            const { block, outcome } = await evaluateRun(resolved, result.text);
+            if (outcome.ok) {
+                return { output: outcome.value, result, attempts };
+            }
+            lastIssues = outcome.issues;
+            attempts.push({ runId: result.runId, issues: outcome.issues, block });
+            if (attempt >= resolved.maxRepairs ||
+                !resolved.shouldRetry(outcome.issues, attempt + 1)) {
+                break;
+            }
+            prompt = resolved.renderRepairPrompt({
+                basePrompt: input.options.prompt,
+                contractInstruction: resolved.instruction,
+                attempt: attempt + 1,
+                issues: outcome.issues,
+                previousBlock: block,
+                markers: resolved.markers,
+            });
+        }
+        const errorOptions = {
+            code: AGENT_ERROR_CODE.outputRejected,
+            message: "Structured output contract was not satisfied within the repair budget",
+            data: { issues: lastIssues, attempts: attempts.length },
+            agentId: input.agentId,
+            started: true,
+        };
+        if (lastRun !== null) {
+            errorOptions.runId = lastRun.runId;
+        }
+        throw new AgentError(errorOptions);
+    }
+    finally {
+        broadcast.end();
+    }
+}
+/**
+ * Forward one run's events into the structured broadcast, then return its
+ * result. The pump is awaited even on failure so no attempt's events leak
+ * past the structured stream into the next attempt.
+ */
+async function forwardRun(handle, broadcast) {
+    const pumping = (async () => {
+        for await (const event of handle.events) {
+            broadcast.push(event);
+        }
+    })();
+    try {
+        return await handle.result;
+    }
+    finally {
+        await pumping;
+    }
+}

package/dist/structured/standard-schema.d.ts

@@ -0,0 +1,34 @@
+/**
+ * Standard Schema v1 interface, vendored per the spec's guidance
+ * (https://standardschema.dev) so no validator library types cross the
+ * package boundary. zod v4, valibot, and arktype all implement this.
+ */
+export type StandardSchemaV1<Input = unknown, Output = Input> = {
+    readonly "~standard": StandardSchemaProps<Input, Output>;
+};
+export type StandardSchemaProps<Input, Output> = {
+    readonly version: 1;
+    readonly vendor: string;
+    readonly validate: (value: unknown) => StandardSchemaResult<Output> | Promise<StandardSchemaResult<Output>>;
+    readonly types?: StandardSchemaTypes<Input, Output> | undefined;
+};
+export type StandardSchemaResult<Output> = StandardSchemaSuccessResult<Output> | StandardSchemaFailureResult;
+export type StandardSchemaSuccessResult<Output> = {
+    readonly value: Output;
+    readonly issues?: undefined;
+};
+export type StandardSchemaFailureResult = {
+    readonly issues: ReadonlyArray<StandardSchemaIssue>;
+};
+export type StandardSchemaIssue = {
+    readonly message: string;
+    readonly path?: ReadonlyArray<PropertyKey | StandardSchemaPathSegment> | undefined;
+};
+export type StandardSchemaPathSegment = {
+    readonly key: PropertyKey;
+};
+export type StandardSchemaTypes<Input, Output> = {
+    readonly input: Input;
+    readonly output: Output;
+};
+//# sourceMappingURL=standard-schema.d.ts.map

package/dist/structured/standard-schema.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"standard-schema.d.ts","sourceRoot":"","sources":["../../src/structured/standard-schema.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,MAAM,MAAM,gBAAgB,CAAC,KAAK,GAAG,OAAO,EAAE,MAAM,GAAG,KAAK,IAAI;IAC9D,QAAQ,CAAC,WAAW,EAAE,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,CAAC;CAC1D,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,KAAK,EAAE,MAAM,IAAI;IAC/C,QAAQ,CAAC,OAAO,EAAE,CAAC,CAAC;IACpB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,QAAQ,EAAE,CACjB,KAAK,EAAE,OAAO,KACX,oBAAoB,CAAC,MAAM,CAAC,GAAG,OAAO,CAAC,oBAAoB,CAAC,MAAM,CAAC,CAAC,CAAC;IAC1E,QAAQ,CAAC,KAAK,CAAC,EAAE,mBAAmB,CAAC,KAAK,EAAE,MAAM,CAAC,GAAG,SAAS,CAAC;CACjE,CAAC;AAEF,MAAM,MAAM,oBAAoB,CAAC,MAAM,IACnC,2BAA2B,CAAC,MAAM,CAAC,GACnC,2BAA2B,CAAC;AAEhC,MAAM,MAAM,2BAA2B,CAAC,MAAM,IAAI;IAChD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC;IACvB,QAAQ,CAAC,MAAM,CAAC,EAAE,SAAS,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,2BAA2B,GAAG;IACxC,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC,mBAAmB,CAAC,CAAC;CACrD,CAAC;AAEF,MAAM,MAAM,mBAAmB,GAAG;IAChC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,IAAI,CAAC,EACV,aAAa,CAAC,WAAW,GAAG,yBAAyB,CAAC,GACtD,SAAS,CAAC;CACf,CAAC;AAEF,MAAM,MAAM,yBAAyB,GAAG;IACtC,QAAQ,CAAC,GAAG,EAAE,WAAW,CAAC;CAC3B,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,KAAK,EAAE,MAAM,IAAI;IAC/C,QAAQ,CAAC,KAAK,EAAE,KAAK,CAAC;IACtB,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;CACzB,CAAC"}

package/dist/structured/standard-schema.js

@@ -0,0 +1,6 @@
+/**
+ * Standard Schema v1 interface, vendored per the spec's guidance
+ * (https://standardschema.dev) so no validator library types cross the
+ * package boundary. zod v4, valibot, and arktype all implement this.
+ */
+export {};

package/dist/testing/fake-agent.d.ts

@@ -0,0 +1,32 @@
+import type { AgentError } from "../core/error.js";
+import type { AgentEvent } from "../core/run.js";
+import type { AgentDefinition } from "../kernel/definition.js";
+import type { ResolvedRunOptions } from "../kernel/options.js";
+export declare const FAKE_AGENT_BEHAVIOR_KIND: {
+    readonly succeed: "succeed";
+    readonly fail: "fail";
+    readonly waitForAbort: "wait-for-abort";
+};
+export type FakeAgentBehavior = {
+    kind: typeof FAKE_AGENT_BEHAVIOR_KIND.succeed;
+    text: string;
+    events?: AgentEvent[];
+} | {
+    kind: typeof FAKE_AGENT_BEHAVIOR_KIND.fail;
+    error: AgentError;
+} | {
+    kind: typeof FAKE_AGENT_BEHAVIOR_KIND.waitForAbort;
+};
+export type FakeAgentCall = {
+    options: ResolvedRunOptions;
+    env: Record<string, string>;
+};
+export type FakeAgentDefinition<Id extends string> = AgentDefinition<Id> & {
+    readonly calls: FakeAgentCall[];
+};
+/**
+ * In-process fake for composition-layer tests. Behaviors are consumed in
+ * order; the last one repeats.
+ */
+export declare function fakeAgent<const Id extends string>(id: Id, behavior: FakeAgentBehavior | FakeAgentBehavior[]): FakeAgentDefinition<Id>;
+//# sourceMappingURL=fake-agent.d.ts.map

package/dist/testing/fake-agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-agent.d.ts","sourceRoot":"","sources":["../../src/testing/fake-agent.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AACnD,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,eAAe,EAAc,MAAM,yBAAyB,CAAC;AAC3E,OAAO,KAAK,EAAE,kBAAkB,EAAE,MAAM,sBAAsB,CAAC;AAE/D,eAAO,MAAM,wBAAwB;;;;CAI3B,CAAC;AAEX,MAAM,MAAM,iBAAiB,GACzB;IACE,IAAI,EAAE,OAAO,wBAAwB,CAAC,OAAO,CAAC;IAC9C,IAAI,EAAE,MAAM,CAAC;IACb,MAAM,CAAC,EAAE,UAAU,EAAE,CAAC;CACvB,GACD;IAAE,IAAI,EAAE,OAAO,wBAAwB,CAAC,IAAI,CAAC;IAAC,KAAK,EAAE,UAAU,CAAA;CAAE,GACjE;IAAE,IAAI,EAAE,OAAO,wBAAwB,CAAC,YAAY,CAAA;CAAE,CAAC;AAE3D,MAAM,MAAM,aAAa,GAAG;IAC1B,OAAO,EAAE,kBAAkB,CAAC;IAC5B,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAC7B,CAAC;AAEF,MAAM,MAAM,mBAAmB,CAAC,EAAE,SAAS,MAAM,IAAI,eAAe,CAAC,EAAE,CAAC,GAAG;IACzE,QAAQ,CAAC,KAAK,EAAE,aAAa,EAAE,CAAC;CACjC,CAAC;AAEF;;;GAGG;AACH,wBAAgB,SAAS,CAAC,KAAK,CAAC,EAAE,SAAS,MAAM,EAC/C,EAAE,EAAE,EAAE,EACN,QAAQ,EAAE,iBAAiB,GAAG,iBAAiB,EAAE,GAChD,mBAAmB,CAAC,EAAE,CAAC,CAoCzB"}

package/dist/testing/fake-agent.js

@@ -0,0 +1,43 @@
+export const FAKE_AGENT_BEHAVIOR_KIND = {
+    succeed: "succeed",
+    fail: "fail",
+    waitForAbort: "wait-for-abort",
+};
+/**
+ * In-process fake for composition-layer tests. Behaviors are consumed in
+ * order; the last one repeats.
+ */
+export function fakeAgent(id, behavior) {
+    const behaviors = Array.isArray(behavior) ? behavior : [behavior];
+    const calls = [];
+    let callIndex = 0;
+    async function* run(options, ctx) {
+        calls.push({ options, env: ctx.env });
+        const current = behaviors[Math.min(callIndex, behaviors.length - 1)] ??
+            {
+                kind: FAKE_AGENT_BEHAVIOR_KIND.succeed,
+                text: "",
+            };
+        callIndex += 1;
+        if (current.kind === FAKE_AGENT_BEHAVIOR_KIND.fail) {
+            throw current.error;
+        }
+        if (current.kind === FAKE_AGENT_BEHAVIOR_KIND.waitForAbort) {
+            await new Promise((resolve) => {
+                ctx.signal.addEventListener("abort", () => resolve(), { once: true });
+            });
+            throw new Error("aborted");
+        }
+        for (const event of current.events ?? []) {
+            yield event;
+        }
+        return {
+            text: current.text,
+            model: null,
+            exit: null,
+            raw: null,
+            usage: null,
+        };
+    }
+    return { id, run, calls };
+}

package/dist/testing/fake-clock.d.ts

@@ -0,0 +1,8 @@
+import type { Clock } from "../core/ports.js";
+export type FakeClock = Clock & {
+    /** Advance time, firing due timers in order. */
+    advance(ms: number): void;
+    pendingTimerCount(): number;
+};
+export declare function fakeClock(startMs?: number): FakeClock;
+//# sourceMappingURL=fake-clock.d.ts.map

package/dist/testing/fake-clock.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-clock.d.ts","sourceRoot":"","sources":["../../src/testing/fake-clock.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,KAAK,EAAE,MAAM,kBAAkB,CAAC;AAE9C,MAAM,MAAM,SAAS,GAAG,KAAK,GAAG;IAC9B,gDAAgD;IAChD,OAAO,CAAC,EAAE,EAAE,MAAM,GAAG,IAAI,CAAC;IAC1B,iBAAiB,IAAI,MAAM,CAAC;CAC7B,CAAC;AAQF,wBAAgB,SAAS,CAAC,OAAO,SAAI,GAAG,SAAS,CA+ChD"}

package/dist/testing/fake-clock.js

@@ -0,0 +1,44 @@
+export function fakeClock(startMs = 0) {
+    let nowMs = startMs;
+    let nextOrder = 0;
+    const timers = new Set();
+    const dueTimer = (until) => {
+        let earliest = null;
+        for (const timer of timers) {
+            if (timer.at > until) {
+                continue;
+            }
+            if (earliest === null ||
+                timer.at < earliest.at ||
+                (timer.at === earliest.at && timer.order < earliest.order)) {
+                earliest = timer;
+            }
+        }
+        return earliest;
+    };
+    return {
+        now: () => nowMs,
+        setTimeout: (callback, delayMs) => {
+            const timer = {
+                at: nowMs + delayMs,
+                order: nextOrder,
+                callback,
+            };
+            nextOrder += 1;
+            timers.add(timer);
+            return () => timers.delete(timer);
+        },
+        advance: (ms) => {
+            const target = nowMs + ms;
+            let timer = dueTimer(target);
+            while (timer !== null) {
+                nowMs = Math.max(nowMs, timer.at);
+                timers.delete(timer);
+                timer.callback();
+                timer = dueTimer(target);
+            }
+            nowMs = target;
+        },
+        pendingTimerCount: () => timers.size,
+    };
+}

package/dist/testing/fake-exec.d.ts

@@ -0,0 +1,26 @@
+import type { Exec, ExecChunk, ExecExit, ExecSpawnOptions, InteractiveExecSpawnOptions } from "../core/ports.js";
+export type FakeExecScript = {
+    chunks?: ExecChunk[];
+    exitCode?: number;
+    /** Absent = exited without a signal. */
+    exitSignal?: string;
+    /** Keep the stream open until killed (timeout / early-completion tests). */
+    hang?: boolean;
+    /** Survive SIGTERM so SIGKILL escalation can be observed. */
+    ignoreSigterm?: boolean;
+    onWrite?: (text: string, controls: {
+        stdout(text: string): void;
+        stderr(text: string): void;
+        exit(exit: ExecExit): void;
+    }) => void;
+};
+export type FakeExec = Exec & {
+    readonly spawns: (ExecSpawnOptions | InteractiveExecSpawnOptions)[];
+    readonly stdinWrites: string[][];
+    /** Kill signals recorded per spawn, in order. */
+    readonly kills: string[][];
+    /** Commands `which` should report as missing. */
+    readonly missingCommands: Set<string>;
+};
+export declare function fakeExec(scripts?: FakeExecScript[]): FakeExec;
+//# sourceMappingURL=fake-exec.d.ts.map

package/dist/testing/fake-exec.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-exec.d.ts","sourceRoot":"","sources":["../../src/testing/fake-exec.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EACV,IAAI,EACJ,SAAS,EACT,QAAQ,EACR,gBAAgB,EAEhB,2BAA2B,EAC5B,MAAM,kBAAkB,CAAC;AAG1B,MAAM,MAAM,cAAc,GAAG;IAC3B,MAAM,CAAC,EAAE,SAAS,EAAE,CAAC;IACrB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,wCAAwC;IACxC,UAAU,CAAC,EAAE,MAAM,CAAC;IACpB,4EAA4E;IAC5E,IAAI,CAAC,EAAE,OAAO,CAAC;IACf,6DAA6D;IAC7D,aAAa,CAAC,EAAE,OAAO,CAAC;IACxB,OAAO,CAAC,EAAE,CACR,IAAI,EAAE,MAAM,EACZ,QAAQ,EAAE;QACR,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,MAAM,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;QAC3B,IAAI,CAAC,IAAI,EAAE,QAAQ,GAAG,IAAI,CAAC;KAC5B,KACE,IAAI,CAAC;CACX,CAAC;AAEF,MAAM,MAAM,QAAQ,GAAG,IAAI,GAAG;IAC5B,QAAQ,CAAC,MAAM,EAAE,CAAC,gBAAgB,GAAG,2BAA2B,CAAC,EAAE,CAAC;IACpE,QAAQ,CAAC,WAAW,EAAE,MAAM,EAAE,EAAE,CAAC;IACjC,iDAAiD;IACjD,QAAQ,CAAC,KAAK,EAAE,MAAM,EAAE,EAAE,CAAC;IAC3B,iDAAiD;IACjD,QAAQ,CAAC,eAAe,EAAE,GAAG,CAAC,MAAM,CAAC,CAAC;CACvC,CAAC;AAEF,wBAAgB,QAAQ,CAAC,OAAO,GAAE,cAAc,EAAO,GAAG,QAAQ,CA4EjE"}

package/dist/testing/fake-exec.js

@@ -0,0 +1,69 @@
+import { AsyncQueue } from "../core/async-queue.js";
+import { OUTPUT_CHANNEL, PROCESS_SIGNAL } from "../core/values.js";
+export function fakeExec(scripts = []) {
+    const remaining = [...scripts];
+    const spawns = [];
+    const stdinWrites = [];
+    const kills = [];
+    const missingCommands = new Set();
+    return {
+        spawns,
+        stdinWrites,
+        kills,
+        missingCommands,
+        which: (command) => Promise.resolve(missingCommands.has(command) ? null : `/fake/bin/${command}`),
+        spawn: (options) => {
+            spawns.push(options);
+            const script = remaining.shift() ?? {};
+            const killSignals = [];
+            const writes = [];
+            kills.push(killSignals);
+            stdinWrites.push(writes);
+            const chunks = new AsyncQueue();
+            for (const chunk of script.chunks ?? []) {
+                chunks.push(chunk);
+            }
+            let settleExit = () => { };
+            const exit = new Promise((resolve) => {
+                settleExit = resolve;
+            });
+            let finished = false;
+            const finish = (value) => {
+                if (finished) {
+                    return;
+                }
+                finished = true;
+                chunks.end();
+                settleExit(value);
+            };
+            const controls = {
+                stdout: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stdout, text }),
+                stderr: (text) => chunks.push({ channel: OUTPUT_CHANNEL.stderr, text }),
+                exit: finish,
+            };
+            if (script.hang !== true) {
+                finish({
+                    code: script.exitCode ?? 0,
+                    signal: script.exitSignal ?? null,
+                });
+            }
+            return {
+                chunks,
+                exit,
+                writeStdin: (text) => {
+                    writes.push(text);
+                    script.onWrite?.(text, controls);
+                },
+                endStdin: () => { },
+                kill: (signal) => {
+                    killSignals.push(signal);
+                    if (signal === PROCESS_SIGNAL.sigterm &&
+                        script.ignoreSigterm === true) {
+                        return;
+                    }
+                    finish({ code: null, signal });
+                },
+            };
+        },
+    };
+}

package/dist/testing/fake-secrets.d.ts

@@ -0,0 +1,3 @@
+import type { SecretResolver } from "../core/ports.js";
+export declare function fakeSecretResolver(values: Record<string, string>): SecretResolver;
+//# sourceMappingURL=fake-secrets.d.ts.map

package/dist/testing/fake-secrets.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"fake-secrets.d.ts","sourceRoot":"","sources":["../../src/testing/fake-secrets.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAEvD,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,GAC7B,cAAc,CAIhB"}

package/dist/testing/fake-secrets.js

@@ -0,0 +1,5 @@
+export function fakeSecretResolver(values) {
+    return {
+        resolve: (id) => Promise.resolve(values[id] ?? null),
+    };
+}

package/dist/testing/index.d.ts

@@ -0,0 +1,10 @@
+/**
+ * `@alpacakit/agents/testing` — fakes for every port. Dev-only; the
+ * kernel and fleet are fully testable without spawning anything.
+ * In-memory stores are NOT here: they are real adapters in the root.
+ */
+export { FAKE_AGENT_BEHAVIOR_KIND, type FakeAgentBehavior, type FakeAgentCall, type FakeAgentDefinition, fakeAgent, } from "./fake-agent.js";
+export { type FakeClock, fakeClock } from "./fake-clock.js";
+export { type FakeExec, type FakeExecScript, fakeExec } from "./fake-exec.js";
+export { fakeSecretResolver } from "./fake-secrets.js";
+//# sourceMappingURL=index.d.ts.map

package/dist/testing/index.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../../src/testing/index.ts"],"names":[],"mappings":"AAAA;;;;GAIG;AAEH,OAAO,EACL,wBAAwB,EACxB,KAAK,iBAAiB,EACtB,KAAK,aAAa,EAClB,KAAK,mBAAmB,EACxB,SAAS,GACV,MAAM,iBAAiB,CAAC;AACzB,OAAO,EAAE,KAAK,SAAS,EAAE,SAAS,EAAE,MAAM,iBAAiB,CAAC;AAC5D,OAAO,EAAE,KAAK,QAAQ,EAAE,KAAK,cAAc,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC9E,OAAO,EAAE,kBAAkB,EAAE,MAAM,mBAAmB,CAAC"}

package/dist/testing/index.js

@@ -0,0 +1,9 @@
+/**
+ * `@alpacakit/agents/testing` — fakes for every port. Dev-only; the
+ * kernel and fleet are fully testable without spawning anything.
+ * In-memory stores are NOT here: they are real adapters in the root.
+ */
+export { FAKE_AGENT_BEHAVIOR_KIND, fakeAgent, } from "./fake-agent.js";
+export { fakeClock } from "./fake-clock.js";
+export { fakeExec } from "./fake-exec.js";
+export { fakeSecretResolver } from "./fake-secrets.js";

package/package.json

@@ -0,0 +1,75 @@
+{
+  "name": "@alpacakit/agents",
+  "version": "0.1.0-beta.19",
+  "description": "Run AI coding agents programmatically: execute, stream, classify failures, fail over.",
+  "license": "MIT",
+  "type": "module",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    },
+    "./config": {
+      "types": "./dist/config/index.d.ts",
+      "import": "./dist/config/index.js"
+    },
+    "./config/extension": {
+      "types": "./dist/config/extension.d.ts",
+      "import": "./dist/config/extension.js"
+    },
+    "./config/xdg": {
+      "types": "./dist/config/xdg.d.ts",
+      "import": "./dist/config/xdg.js"
+    },
+    "./codex": {
+      "types": "./dist/codex/index.d.ts",
+      "import": "./dist/codex/index.js"
+    },
+    "./keyring": {
+      "types": "./dist/keyring/index.d.ts",
+      "import": "./dist/keyring/index.js"
+    },
+    "./testing": {
+      "types": "./dist/testing/index.d.ts",
+      "import": "./dist/testing/index.js"
+    }
+  },
+  "types": "./dist/index.d.ts",
+  "files": [
+    "dist",
+    "README*.md",
+    "LICENSE"
+  ],
+  "publishConfig": {
+    "access": "public",
+    "registry": "https://registry.npmjs.org/"
+  },
+  "engines": {
+    "node": ">=22.19.0"
+  },
+  "dependencies": {
+    "zod": "^4.3.6",
+    "@alpacakit/core": "0.1.0-beta.19"
+  },
+  "devDependencies": {
+    "typescript": "^5.9.3",
+    "vitest": "^4.0.18"
+  },
+  "peerDependencies": {
+    "@earendil-works/pi-coding-agent": "0.75.5",
+    "@napi-rs/keyring": "^1.3.0"
+  },
+  "peerDependenciesMeta": {
+    "@earendil-works/pi-coding-agent": {
+      "optional": true
+    },
+    "@napi-rs/keyring": {
+      "optional": true
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.build.json",
+    "typecheck": "tsc -p tsconfig.json --noEmit",
+    "test": "vitest run"
+  }
+}