@bluewombat/slot-kit 0.1.0

package/README.md

@@ -0,0 +1,99 @@
+# Slot kit
+
+What a slot needs to answer the Transformer that spawned it.
+
+A slot is an opaque command. Implementer spawns a Builder and its Gates,
+FeatureBreakdown spawns a Planner, and each one reads argv and writes **one JSON
+line on stdout**. That is the whole contract, and nothing here is required to
+meet it: a shell script that prints the right line is a Gate. This package is
+the plumbing every slot written in Node would otherwise write again — and it is
+what keeps the shipped slots from each growing their own version of it.
+
+The behaviour a slot must have is specified where its caller is:
+[Implementer](../../kernel/implementer/SPECS.md) for Builders and Gates,
+[FeatureBreakdown](../../kernel/feature-breakdown/SPECS.md) for Planners.
+Slots that use this kit: [`@bluewombat/slots`](../../plugins/slots/README.md).
+
+## Install
+
+```bash
+npm install @bluewombat/slot-kit
+```
+
+## A Gate
+
+```js
+#!/usr/bin/env node
+import { GATE_FLAGS, emitVerdict, ownArgv } from "@bluewombat/slot-kit";
+
+const globs = ownArgv(process.argv, GATE_FLAGS);
+if (globs.length === 0) {
+  emitVerdict("fail-blocking", "This Gate needs at least one glob.");
+  process.exit(0);
+}
+emitVerdict("pass");
+```
+
+`ownArgv` is the first thing a slot needs: it is spawned with its own options
+first and the caller's flags appended, and it must not trip over the second set.
+
+## What it holds
+
+| Area       | Exports                                                                                                                                                                |
+| ---------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
+| argv       | `ownArgv`, `splitRunner`, `take`, `stageOf`, `GATE_FLAGS`, `BUILDER_FLAGS`, `PLANNER_FLAGS`                                                                            |
+| options    | `parseOptions` — a spec of flags, with choices, fallbacks and repeatable ones                                                                                          |
+| stdout     | `emitVerdict`, `emitFailure`, `emitPlan`, `emitRefusal`                                                                                                                |
+| agent CLIs | `findExecutable`, `runAgent`, `readResult`, `finishRun`, `failureOf`                                                                                                   |
+| prompts    | `renderPrompt`, `readTemplate`, `PROMPT_RULES` — fill is generic; each role owns its names                                                                             |
+| roles      | `parseRole`, `loadPrompt`, `loadRules`, `fillPrompt`, `spawnFilled`, `transcriptArgs`, `ROLE_OPTIONS` — a role fills its template and hands it to the agent after `--` |
+| transcript | `openTranscript`, `transcriptFor`, `TRANSCRIPT_PARTS`                                                                                                                  |
+| plans      | `checkPlan`                                                                                                                                                            |
+| paths      | `pathMatchesGlob`                                                                                                                                                      |
+
+Each `emit*` takes an optional `write`, which is how they are tested without a
+process. Everything else is a plain function over its arguments; `finishRun` is
+the one exception, and ends the process on purpose.
+
+## The three roles
+
+| Role    | Spawned by       | Answers                                                                       |
+| ------- | ---------------- | ----------------------------------------------------------------------------- |
+| Planner | FeatureBreakdown | `{"subtasks":[…]}`, or `{"outcome":"refused",…}` for an unsplittable one      |
+| Builder | Implementer      | Nothing on a pass — the workspace is the answer. `{"outcome":…}` on a failure |
+| Gate    | Implementer      | `{"verdict":"pass"}`, or `fail-retryable` / `fail-blocking` with a `report`   |
+
+A verdict is not an exit code. A Gate that exits non-zero without a line on
+stdout has not answered.
+
+## Stack
+
+Repository stack — TypeScript, Node 24.20, Biome, `node:test`. See
+[docs/DEVELOPMENT.md](../../../docs/DEVELOPMENT.md).
+
+## Commands (development)
+
+| Task      | Command          |
+| --------- | ---------------- |
+| Lint      | `npm run lint`   |
+| Format    | `npm run format` |
+| Typecheck | `npm run tsc`    |
+| Test      | `npm test`       |
+| Build     | `npm run build`  |
+
+## Layout
+
+```
+src/
+  index.ts       the whole surface
+  argv.ts        who each argv token belongs to
+  options.ts     a slot's own flags
+  emit.ts        the one line on stdout
+  agent.ts       find, run, and read an agent CLI
+  finish.ts      how a finished agent run classifies
+  prompt.ts      generic fill, rules, agent prompt (already rendered)
+  role.ts        parse a role, fill its template, spawn the agent after `--`
+  transcript.ts  one file per turn, when a Project asks for one
+  plan.ts        whether a Plan can be acted on
+  glob.ts        path globs
+```

package/dist/agent.d.ts

@@ -0,0 +1,70 @@
+/**
+ * What every slot that drives an agent CLI needs, and nothing about any one of
+ * them. A Builder and a Planner answer different contracts; finding a binary,
+ * running it and reading its result is the same work twice.
+ */
+/**
+ * First executable among `names`, looked up name by name so a precise name
+ * anywhere wins over a generic one early on PATH. PATH first, then the
+ * directories an installer is known to use.
+ */
+export declare function findExecutable(names: readonly string[], extraDirs?: readonly string[]): string | undefined;
+export type AgentRun = {
+    /** Absent when the CLI never started. */
+    code?: number | null | undefined;
+    signal?: NodeJS.Signals | null | undefined;
+    /** Set when the CLI never started. */
+    error?: Error | undefined;
+    stdout: string;
+    stderr: string;
+    /** Both streams in arrival order. */
+    output: string;
+    startedAt: Date;
+    endedAt: Date;
+    durationMs: number;
+};
+export type AgentInvocation = {
+    file: string;
+    args: readonly string[];
+    cwd: string;
+};
+/**
+ * Run the agent to completion, streaming its output to stderr as it comes so
+ * an operator can watch. stdout stays the contract channel of the slot.
+ *
+ * Resolves with `output` — both streams in arrival order, which is what a
+ * failure report should quote — `stdout` alone, which is what a structured
+ * `--output-format` has to be parsed from, and `stderr` alone, which is where
+ * an agent says what it did.
+ */
+export declare function runAgent({ file, args, cwd }: AgentInvocation): Promise<AgentRun>;
+/**
+ * What an agent CLI writes on stdout so the role that spawned it can classify
+ * the run. Dates and `Error` do not survive JSON, so they are strings here.
+ */
+export type SerializedRun = {
+    name: string;
+    bin: string;
+    code: number | null;
+    signal: string | null;
+    error?: string;
+    stdout: string;
+    stderr: string;
+    output: string;
+    startedAt: string;
+    endedAt: string;
+    durationMs: number;
+};
+/** The JSON an agent CLI writes after a vendor run. */
+export declare function serializeRun(run: AgentRun, about: {
+    name: string;
+    bin: string;
+}): SerializedRun;
+/**
+ * Rebuild the run an agent CLI serialized. `undefined` when the payload is not
+ * one — a pre-run refusal is `{ error }` with no `startedAt`.
+ */
+export declare function deserializeRun(raw: Record<string, unknown>): AgentRun | undefined;
+/** The CLI's own result object: the last line of stdout that is one. */
+export declare function readResult(stdout: string): Record<string, unknown> | undefined;
+//# sourceMappingURL=agent.d.ts.map

package/dist/agent.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.d.ts","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"AAIA;;;;GAIG;AAEH;;;;GAIG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,SAAS,MAAM,EAAE,EACxB,SAAS,GAAE,SAAS,MAAM,EAAO,GAChC,MAAM,GAAG,SAAS,CAgBpB;AAED,MAAM,MAAM,QAAQ,GAAG;IACrB,yCAAyC;IACzC,IAAI,CAAC,EAAE,MAAM,GAAG,IAAI,GAAG,SAAS,CAAC;IACjC,MAAM,CAAC,EAAE,MAAM,CAAC,OAAO,GAAG,IAAI,GAAG,SAAS,CAAC;IAC3C,sCAAsC;IACtC,KAAK,CAAC,EAAE,KAAK,GAAG,SAAS,CAAC;IAC1B,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,qCAAqC;IACrC,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,IAAI,CAAC;IAChB,OAAO,EAAE,IAAI,CAAC;IACd,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,MAAM,MAAM,eAAe,GAAG;IAC5B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACxB,GAAG,EAAE,MAAM,CAAC;CACb,CAAC;AAEF;;;;;;;;GAQG;AACH,wBAAgB,QAAQ,CAAC,EAAE,IAAI,EAAE,IAAI,EAAE,GAAG,EAAE,EAAE,eAAe,GAAG,OAAO,CAAC,QAAQ,CAAC,CAqDhF;AAED;;;GAGG;AACH,MAAM,MAAM,aAAa,GAAG;IAC1B,IAAI,EAAE,MAAM,CAAC;IACb,GAAG,EAAE,MAAM,CAAC;IACZ,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,EAAE,MAAM,CAAC;IAClB,OAAO,EAAE,MAAM,CAAC;IAChB,UAAU,EAAE,MAAM,CAAC;CACpB,CAAC;AAEF,uDAAuD;AACvD,wBAAgB,YAAY,CAAC,GAAG,EAAE,QAAQ,EAAE,KAAK,EAAE;IAAE,IAAI,EAAE,MAAM,CAAC;IAAC,GAAG,EAAE,MAAM,CAAA;CAAE,GAAG,aAAa,CAc/F;AAED;;;GAGG;AACH,wBAAgB,cAAc,CAAC,GAAG,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,QAAQ,GAAG,SAAS,CAgBjF;AAED,wEAAwE;AACxE,wBAAgB,UAAU,CAAC,MAAM,EAAE,MAAM,GAAG,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,GAAG,SAAS,CAiB9E"}

package/dist/agent.js

@@ -0,0 +1,147 @@
+import { spawn } from "node:child_process";
+import { accessSync, constants } from "node:fs";
+import { delimiter, join } from "node:path";
+/**
+ * What every slot that drives an agent CLI needs, and nothing about any one of
+ * them. A Builder and a Planner answer different contracts; finding a binary,
+ * running it and reading its result is the same work twice.
+ */
+/**
+ * First executable among `names`, looked up name by name so a precise name
+ * anywhere wins over a generic one early on PATH. PATH first, then the
+ * directories an installer is known to use.
+ */
+export function findExecutable(names, extraDirs = []) {
+    const dirs = [...(process.env.PATH ?? "").split(delimiter), ...extraDirs].filter((dir) => dir.length > 0);
+    for (const name of names) {
+        for (const dir of dirs) {
+            const candidate = join(dir, name);
+            try {
+                accessSync(candidate, constants.X_OK);
+                return candidate;
+            }
+            catch {
+                // try the next directory
+            }
+        }
+    }
+    return undefined;
+}
+/**
+ * Run the agent to completion, streaming its output to stderr as it comes so
+ * an operator can watch. stdout stays the contract channel of the slot.
+ *
+ * Resolves with `output` — both streams in arrival order, which is what a
+ * failure report should quote — `stdout` alone, which is what a structured
+ * `--output-format` has to be parsed from, and `stderr` alone, which is where
+ * an agent says what it did.
+ */
+export function runAgent({ file, args, cwd }) {
+    return new Promise((resolve) => {
+        const startedAt = new Date();
+        const child = spawn(file, [...args], { cwd, stdio: ["ignore", "pipe", "pipe"] });
+        let stdout = "";
+        let stderr = "";
+        let output = "";
+        let settled = false;
+        const settle = (result) => {
+            if (settled) {
+                return;
+            }
+            settled = true;
+            process.off("SIGTERM", stop);
+            process.off("SIGINT", stop);
+            const endedAt = new Date();
+            resolve({
+                stdout,
+                output,
+                ...result,
+                stderr,
+                startedAt,
+                endedAt,
+                durationMs: endedAt.getTime() - startedAt.getTime(),
+            });
+        };
+        const stop = () => {
+            child.kill("SIGKILL");
+        };
+        process.on("SIGTERM", stop);
+        process.on("SIGINT", stop);
+        child.stdout?.setEncoding("utf8");
+        child.stderr?.setEncoding("utf8");
+        child.stdout?.on("data", (chunk) => {
+            stdout += chunk;
+            output += chunk;
+            process.stderr.write(chunk);
+        });
+        child.stderr?.on("data", (chunk) => {
+            stderr += chunk;
+            output += chunk;
+            process.stderr.write(chunk);
+        });
+        child.on("error", (error) => {
+            settle({ error, stdout, output });
+        });
+        child.on("exit", (code, signal) => {
+            settle({ code, signal, stdout, output });
+        });
+    });
+}
+/** The JSON an agent CLI writes after a vendor run. */
+export function serializeRun(run, about) {
+    return {
+        name: about.name,
+        bin: about.bin,
+        code: run.code ?? null,
+        signal: run.signal ?? null,
+        ...(run.error === undefined ? {} : { error: run.error.message }),
+        stdout: run.stdout,
+        stderr: run.stderr,
+        output: run.output,
+        startedAt: run.startedAt.toISOString(),
+        endedAt: run.endedAt.toISOString(),
+        durationMs: run.durationMs,
+    };
+}
+/**
+ * Rebuild the run an agent CLI serialized. `undefined` when the payload is not
+ * one — a pre-run refusal is `{ error }` with no `startedAt`.
+ */
+export function deserializeRun(raw) {
+    if (typeof raw.startedAt !== "string" || typeof raw.endedAt !== "string") {
+        return undefined;
+    }
+    const signal = raw.signal;
+    return {
+        code: typeof raw.code === "number" ? raw.code : null,
+        signal: typeof signal === "string" ? signal : null,
+        ...(typeof raw.error === "string" ? { error: new Error(raw.error) } : {}),
+        stdout: typeof raw.stdout === "string" ? raw.stdout : "",
+        stderr: typeof raw.stderr === "string" ? raw.stderr : "",
+        output: typeof raw.output === "string" ? raw.output : "",
+        startedAt: new Date(raw.startedAt),
+        endedAt: new Date(raw.endedAt),
+        durationMs: typeof raw.durationMs === "number" ? raw.durationMs : 0,
+    };
+}
+/** The CLI's own result object: the last line of stdout that is one. */
+export function readResult(stdout) {
+    const lines = stdout.split("\n").filter((line) => line.trim().length > 0);
+    for (let i = lines.length - 1; i >= 0; i--) {
+        const line = lines[i];
+        if (line === undefined) {
+            continue;
+        }
+        try {
+            const parsed = JSON.parse(line);
+            if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+                return parsed;
+            }
+        }
+        catch {
+            // not this line
+        }
+    }
+    return undefined;
+}
+//# sourceMappingURL=agent.js.map

package/dist/agent.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"agent.js","sourceRoot":"","sources":["../src/agent.ts"],"names":[],"mappings":"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"}

package/dist/argv.d.ts

@@ -0,0 +1,43 @@
+/**
+ * A slot is spawned with two argv sections: its own options, written by the
+ * Project, then the flags the Transformer appends about the work at hand. The
+ * slot never chose the second set and must not trip over it, so it needs to
+ * know which tokens are whose.
+ */
+/** Flags Implementer appends after a Gate's own argv. */
+export declare const GATE_FLAGS: ReadonlySet<string>;
+/** Flags Implementer appends after a Builder's own argv. */
+export declare const BUILDER_FLAGS: ReadonlySet<string>;
+/** Flags FeatureBreakdown appends after a Planner's own argv. */
+export declare const PLANNER_FLAGS: ReadonlySet<string>;
+export declare const PUBLISHER_FLAGS: ReadonlySet<string>;
+export declare const REFRESHER_FLAGS: ReadonlySet<string>;
+/** Flags Host appends after a Describer's own argv. */
+export declare const MESSAGE_FLAGS: ReadonlySet<string>;
+/**
+ * Argv tokens that belong to the slot, not to the Transformer that spawned it.
+ *
+ * `caller` is that Transformer's flag set — `GATE_FLAGS`, `BUILDER_FLAGS`,
+ * `PLANNER_FLAGS`, `PUBLISHER_FLAGS` or
+ * `REFRESHER_FLAGS`. Each of them takes a value, so a match consumes two tokens.
+ */
+export declare function ownArgv(argv: readonly string[], caller: ReadonlySet<string>): string[];
+/**
+ * The Project's `--` splits this slot's own flags from the agent command it
+ * hands the rendered prompt to.
+ *
+ * Absent, or with nothing after it, there is no agent to run: a role that
+ * builds a prompt has nowhere to send it.
+ */
+export declare function splitRunner(tokens: readonly string[]): {
+    ok: true;
+    own: string[];
+    runner: string[];
+} | {
+    ok: false;
+};
+/** The value after `flag`, or nothing when the flag is absent or last. */
+export declare function take(argv: readonly string[], flag: string): string | undefined;
+/** What a Gate is looking at, when it makes a difference to the answer. */
+export declare function stageOf(argv: readonly string[]): string;
+//# sourceMappingURL=argv.d.ts.map

package/dist/argv.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.d.ts","sourceRoot":"","sources":["../src/argv.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,yDAAyD;AACzD,eAAO,MAAM,UAAU,EAAE,WAAW,CAAC,MAAM,CAOzC,CAAC;AAEH,4DAA4D;AAC5D,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAQ5C,CAAC;AAEH,iEAAiE;AACjE,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAK5C,CAAC;AAEH,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAA0C,CAAC;AAE3F,eAAO,MAAM,eAAe,EAAE,WAAW,CAAC,MAAM,CAAyB,CAAC;AAE1E,uDAAuD;AACvD,eAAO,MAAM,aAAa,EAAE,WAAW,CAAC,MAAM,CAK5C,CAAC;AAEH;;;;;;GAMG;AACH,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,GAAG,MAAM,EAAE,CActF;AAED;;;;;;GAMG;AACH,wBAAgB,WAAW,CACzB,MAAM,EAAE,SAAS,MAAM,EAAE,GACxB;IAAE,EAAE,EAAE,IAAI,CAAC;IAAC,GAAG,EAAE,MAAM,EAAE,CAAC;IAAC,MAAM,EAAE,MAAM,EAAE,CAAA;CAAE,GAAG;IAAE,EAAE,EAAE,KAAK,CAAA;CAAE,CAU/D;AAED,0EAA0E;AAC1E,wBAAgB,IAAI,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,IAAI,EAAE,MAAM,GAAG,MAAM,GAAG,SAAS,CAG9E;AAED,2EAA2E;AAC3E,wBAAgB,OAAO,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,MAAM,CAGvD"}

package/dist/argv.js

@@ -0,0 +1,92 @@
+/**
+ * A slot is spawned with two argv sections: its own options, written by the
+ * Project, then the flags the Transformer appends about the work at hand. The
+ * slot never chose the second set and must not trip over it, so it needs to
+ * know which tokens are whose.
+ */
+/** Flags Implementer appends after a Gate's own argv. */
+export const GATE_FLAGS = new Set([
+    "--id",
+    "--attempt",
+    "--gate-id",
+    "--intention",
+    "--definition-of-done",
+    "--stage",
+]);
+/** Flags Implementer appends after a Builder's own argv. */
+export const BUILDER_FLAGS = new Set([
+    "--id",
+    "--attempt",
+    "--intention",
+    "--definition-of-done",
+    "--report",
+    "--report-from",
+    "--context",
+]);
+/** Flags FeatureBreakdown appends after a Planner's own argv. */
+export const PLANNER_FLAGS = new Set([
+    "--key",
+    "--intention",
+    "--max-units",
+    "--title",
+]);
+export const PUBLISHER_FLAGS = new Set(["--id", "--ref", "--target"]);
+export const REFRESHER_FLAGS = new Set(["--target"]);
+/** Flags Host appends after a Describer's own argv. */
+export const MESSAGE_FLAGS = new Set([
+    "--id",
+    "--title",
+    "--intention",
+    "--target",
+]);
+/**
+ * Argv tokens that belong to the slot, not to the Transformer that spawned it.
+ *
+ * `caller` is that Transformer's flag set — `GATE_FLAGS`, `BUILDER_FLAGS`,
+ * `PLANNER_FLAGS`, `PUBLISHER_FLAGS` or
+ * `REFRESHER_FLAGS`. Each of them takes a value, so a match consumes two tokens.
+ */
+export function ownArgv(argv, caller) {
+    const out = [];
+    for (let i = 2; i < argv.length; i++) {
+        const token = argv[i];
+        if (token === undefined) {
+            continue;
+        }
+        if (caller.has(token)) {
+            i += 1;
+            continue;
+        }
+        out.push(token);
+    }
+    return out;
+}
+/**
+ * The Project's `--` splits this slot's own flags from the agent command it
+ * hands the rendered prompt to.
+ *
+ * Absent, or with nothing after it, there is no agent to run: a role that
+ * builds a prompt has nowhere to send it.
+ */
+export function splitRunner(tokens) {
+    const at = tokens.indexOf("--");
+    if (at < 0) {
+        return { ok: false };
+    }
+    const runner = tokens.slice(at + 1);
+    if (runner.length === 0) {
+        return { ok: false };
+    }
+    return { ok: true, own: tokens.slice(0, at), runner };
+}
+/** The value after `flag`, or nothing when the flag is absent or last. */
+export function take(argv, flag) {
+    const index = argv.indexOf(flag);
+    return index < 0 ? undefined : argv[index + 1];
+}
+/** What a Gate is looking at, when it makes a difference to the answer. */
+export function stageOf(argv) {
+    const at = argv.indexOf("--stage");
+    return at < 0 ? "unit" : (argv[at + 1] ?? "unit");
+}
+//# sourceMappingURL=argv.js.map

package/dist/argv.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"argv.js","sourceRoot":"","sources":["../src/argv.ts"],"names":[],"mappings":"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"}

package/dist/emit.d.ts

@@ -0,0 +1,61 @@
+/**
+ * The one line a slot puts on stdout.
+ *
+ * stdout is the contract channel and carries nothing else: whatever a slot has
+ * to say to a watching operator goes to stderr. Each role answers a different
+ * shape, so each has its own function rather than one that takes a kind.
+ */
+/** A Gate's answer on the work in front of it. */
+export type Verdict = "pass" | "fail-retryable" | "fail-blocking";
+/** A Builder's answer when its pass did not produce work. */
+export type Failure = Exclude<Verdict, "pass">;
+export type Write = (line: string) => void;
+/** A Gate's verdict, with the report the next Attempt is given. */
+export declare function emitVerdict(verdict: Verdict, report?: string, write?: Write): void;
+/** A Builder's failure. A pass says nothing: the workspace is the answer. */
+export declare function emitFailure(outcome: Failure, report: string, write?: Write): void;
+/** A Plan on stdout, and nothing else on it. */
+export declare function emitPlan(subtasks: unknown, write?: Write): void;
+/**
+ * Where the work now is, for the Authority to read.
+ *
+ * The reference is opaque above this line: a branch name, a directory, a URL —
+ * whatever the Publisher put in front of the judge, named the way that judge
+ * asks for it.
+ */
+export declare function emitPublication(ref: string, write?: Write): void;
+/**
+ * The work could not be placed where the Authority reads.
+ *
+ * A refusal, not a crash: the Submission does not happen and the reason travels
+ * back. A Publisher that could not run at all exits non-zero and says why on
+ * stderr instead.
+ */
+export declare function emitPublishRefusal(reason: string, write?: Write): void;
+/**
+ * What a commit should say: a subject line, and the body under it when there
+ * is one. Host writes the subject as the first line and the body after a
+ * blank one; how a Project words either is the slot's, not Host's.
+ */
+export declare function emitMessage(subject: string, body?: string, write?: Write): void;
+/**
+ * The work line copy now holds what the Authority holds.
+ *
+ * Nothing to bring back is a success, not a special case: a Refresher that
+ * found the copy already up to date answers the same way.
+ */
+export declare function emitRefreshed(write?: Write): void;
+/**
+ * The copy could not be brought up to date.
+ *
+ * Work started on a copy that is behind is built on a version that no longer
+ * exists, so this refusal stops the pass rather than letting it run.
+ */
+export declare function emitRefreshRefusal(reason: string, write?: Write): void;
+/**
+ * The FeatureStandard cannot be split. This is a verdict on the intention, not
+ * a failure of the slot: a slot that could not answer must exit non-zero and
+ * say why on stderr, so the Breakdown is retried rather than the feature buried.
+ */
+export declare function emitRefusal(reason: string, write?: Write): void;
+//# sourceMappingURL=emit.d.ts.map

package/dist/emit.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.d.ts","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAEH,kDAAkD;AAClD,MAAM,MAAM,OAAO,GAAG,MAAM,GAAG,gBAAgB,GAAG,eAAe,CAAC;AAElE,6DAA6D;AAC7D,MAAM,MAAM,OAAO,GAAG,OAAO,CAAC,OAAO,EAAE,MAAM,CAAC,CAAC;AAE/C,MAAM,MAAM,KAAK,GAAG,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;AAM3C,mEAAmE;AACnE,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,SAAK,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAExF;AAED,6EAA6E;AAC7E,wBAAgB,WAAW,CAAC,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAE3F;AAED,gDAAgD;AAChD,wBAAgB,QAAQ,CAAC,QAAQ,EAAE,OAAO,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAEzE;AAED;;;;;;GAMG;AACH,wBAAgB,eAAe,CAAC,GAAG,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAE1E;AAED;;;;;;GAMG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,OAAO,EAAE,MAAM,EAAE,IAAI,CAAC,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAEzF;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,KAAK,GAAE,KAAgB,GAAG,IAAI,CAE3D;AAED;;;;;GAKG;AACH,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAEhF;AAED;;;;GAIG;AACH,wBAAgB,WAAW,CAAC,MAAM,EAAE,MAAM,EAAE,KAAK,GAAE,KAAgB,GAAG,IAAI,CAEzE"}

package/dist/emit.js

@@ -0,0 +1,77 @@
+/**
+ * The one line a slot puts on stdout.
+ *
+ * stdout is the contract channel and carries nothing else: whatever a slot has
+ * to say to a watching operator goes to stderr. Each role answers a different
+ * shape, so each has its own function rather than one that takes a kind.
+ */
+const toStdout = (line) => {
+    process.stdout.write(line);
+};
+/** A Gate's verdict, with the report the next Attempt is given. */
+export function emitVerdict(verdict, report = "", write = toStdout) {
+    write(`${JSON.stringify({ verdict, report })}\n`);
+}
+/** A Builder's failure. A pass says nothing: the workspace is the answer. */
+export function emitFailure(outcome, report, write = toStdout) {
+    write(`${JSON.stringify({ outcome, report })}\n`);
+}
+/** A Plan on stdout, and nothing else on it. */
+export function emitPlan(subtasks, write = toStdout) {
+    write(`${JSON.stringify({ subtasks })}\n`);
+}
+/**
+ * Where the work now is, for the Authority to read.
+ *
+ * The reference is opaque above this line: a branch name, a directory, a URL —
+ * whatever the Publisher put in front of the judge, named the way that judge
+ * asks for it.
+ */
+export function emitPublication(ref, write = toStdout) {
+    write(`${JSON.stringify({ ref })}\n`);
+}
+/**
+ * The work could not be placed where the Authority reads.
+ *
+ * A refusal, not a crash: the Submission does not happen and the reason travels
+ * back. A Publisher that could not run at all exits non-zero and says why on
+ * stderr instead.
+ */
+export function emitPublishRefusal(reason, write = toStdout) {
+    write(`${JSON.stringify({ outcome: "refused", reason })}\n`);
+}
+/**
+ * What a commit should say: a subject line, and the body under it when there
+ * is one. Host writes the subject as the first line and the body after a
+ * blank one; how a Project words either is the slot's, not Host's.
+ */
+export function emitMessage(subject, body, write = toStdout) {
+    write(`${JSON.stringify(body === undefined ? { subject } : { subject, body })}\n`);
+}
+/**
+ * The work line copy now holds what the Authority holds.
+ *
+ * Nothing to bring back is a success, not a special case: a Refresher that
+ * found the copy already up to date answers the same way.
+ */
+export function emitRefreshed(write = toStdout) {
+    write(`${JSON.stringify({ ok: true })}\n`);
+}
+/**
+ * The copy could not be brought up to date.
+ *
+ * Work started on a copy that is behind is built on a version that no longer
+ * exists, so this refusal stops the pass rather than letting it run.
+ */
+export function emitRefreshRefusal(reason, write = toStdout) {
+    write(`${JSON.stringify({ outcome: "refused", reason })}\n`);
+}
+/**
+ * The FeatureStandard cannot be split. This is a verdict on the intention, not
+ * a failure of the slot: a slot that could not answer must exit non-zero and
+ * say why on stderr, so the Breakdown is retried rather than the feature buried.
+ */
+export function emitRefusal(reason, write = toStdout) {
+    write(`${JSON.stringify({ outcome: "refused", code: "not-specifiable", reason })}\n`);
+}
+//# sourceMappingURL=emit.js.map

package/dist/emit.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"emit.js","sourceRoot":"","sources":["../src/emit.ts"],"names":[],"mappings":"AAAA;;;;;;GAMG;AAUH,MAAM,QAAQ,GAAU,CAAC,IAAI,EAAE,EAAE;IAC/B,OAAO,CAAC,MAAM,CAAC,KAAK,CAAC,IAAI,CAAC,CAAC;AAC7B,CAAC,CAAC;AAEF,mEAAmE;AACnE,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,MAAM,GAAG,EAAE,EAAE,QAAe,QAAQ;IAChF,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC;AAED,6EAA6E;AAC7E,MAAM,UAAU,WAAW,CAAC,OAAgB,EAAE,MAAc,EAAE,QAAe,QAAQ;IACnF,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AACpD,CAAC;AAED,gDAAgD;AAChD,MAAM,UAAU,QAAQ,CAAC,QAAiB,EAAE,QAAe,QAAQ;IACjE,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,QAAQ,EAAE,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,eAAe,CAAC,GAAW,EAAE,QAAe,QAAQ;IAClE,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,GAAG,EAAE,CAAC,IAAI,CAAC,CAAC;AACxC,CAAC;AAED;;;;;;GAMG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,QAAe,QAAQ;IACxE,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,OAAe,EAAE,IAAa,EAAE,QAAe,QAAQ;IACjF,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AACrF,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,aAAa,CAAC,QAAe,QAAQ;IACnD,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,EAAE,EAAE,IAAI,EAAE,CAAC,IAAI,CAAC,CAAC;AAC7C,CAAC;AAED;;;;;GAKG;AACH,MAAM,UAAU,kBAAkB,CAAC,MAAc,EAAE,QAAe,QAAQ;IACxE,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AAC/D,CAAC;AAED;;;;GAIG;AACH,MAAM,UAAU,WAAW,CAAC,MAAc,EAAE,QAAe,QAAQ;IACjE,KAAK,CAAC,GAAG,IAAI,CAAC,SAAS,CAAC,EAAE,OAAO,EAAE,SAAS,EAAE,IAAI,EAAE,iBAAiB,EAAE,MAAM,EAAE,CAAC,IAAI,CAAC,CAAC;AACxF,CAAC"}

package/dist/finish.d.ts

@@ -0,0 +1,26 @@
+import type { AgentRun } from "./agent.js";
+import type { Failure } from "./emit.js";
+export type FinishedRun = {
+    run: AgentRun;
+    bin: string;
+    name: string;
+};
+/**
+ * How a finished run reads: what to answer, and the report to answer it with.
+ *
+ * Separate from `finishRun` because the classification is the part worth
+ * checking, and `finishRun` ends the process.
+ */
+export declare function failureOf(run: AgentRun, bin: string, name: string): {
+    outcome: Failure;
+    report: string;
+};
+/**
+ * Answer the Builder contract for a finished run, then leave.
+ *
+ * Every agent Builder ends here so they classify the same way: exit 0 is a
+ * completed pass, and everything else is `fail-blocking` when the CLI itself is
+ * unusable, `fail-retryable` when the agent failed at the work.
+ */
+export declare function finishRun({ run, bin, name }: FinishedRun): never;
+//# sourceMappingURL=finish.d.ts.map

package/dist/finish.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"finish.d.ts","sourceRoot":"","sources":["../src/finish.ts"],"names":[],"mappings":"AAAA,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,YAAY,CAAC;AAE3C,OAAO,KAAK,EAAE,OAAO,EAAE,MAAM,WAAW,CAAC;AAgBzC,MAAM,MAAM,WAAW,GAAG;IAAE,GAAG,EAAE,QAAQ,CAAC;IAAC,GAAG,EAAE,MAAM,CAAC;IAAC,IAAI,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE;;;;;GAKG;AACH,wBAAgB,SAAS,CACvB,GAAG,EAAE,QAAQ,EACb,GAAG,EAAE,MAAM,EACX,IAAI,EAAE,MAAM,GACX;IAAE,OAAO,EAAE,OAAO,CAAC;IAAC,MAAM,EAAE,MAAM,CAAA;CAAE,CAYtC;AAED;;;;;;GAMG;AACH,wBAAgB,SAAS,CAAC,EAAE,GAAG,EAAE,GAAG,EAAE,IAAI,EAAE,EAAE,WAAW,GAAG,KAAK,CAOhE"}