@intentius/chant 0.124.12 → 0.124.14

package/dist/op/steward-beside.js

@@ -0,0 +1,169 @@
+/**
+ * An Op a steward runs beside its turns (#2861): how a run of it is started,
+ * held and asked for.
+ *
+ * A local steward runs the Ops it lists one turn at a time (#2750). An Op
+ * listed under `beside` (`./steward.ts`) is the steward's too, but a run of it
+ * is not a turn: the operator (`./operator.ts`) starts it as a `chant run
+ * <op>` process of its own and goes on with its rounds, so converge keeps its
+ * cadence while a build of half an hour runs.
+ *
+ * - The run holds the Op's own lease (`refs/chant/lease/<op>`, the lease a
+ *   round's tick of any Op takes), renewed every third of its time to live
+ *   for as long as the run lasts, and released when it ends. That is what
+ *   makes it one run at a time, whoever starts it: the operator, or a person's
+ *   `chant run <op>`, which takes this lease and not the steward's turn.
+ * - The process the operator starts carries `CHANT_STEWARD`, so its run record
+ *   names the steward, a decision point it asks is the steward's, and the
+ *   operator resumes it once the question is answered, by starting another
+ *   such process. Its work lease holder is `<steward>/<op>@<operator>`, which
+ *   is how `workspace status` finds it under the steward.
+ */
+import { spawn } from "node:child_process";
+import { runOpLocally, OpRunFailure } from "./local-executor.js";
+import { parseDuration } from "./duration.js";
+import { acquireLease, releaseLease, DEFAULT_LEASE_TTL_MS } from "../lifecycle/lease.js";
+import { readinessKeys } from "./steward.js";
+/** The exit code `chant run` gives a run that stopped at a gate or on an open decision point. */
+const WAITING_EXIT = 3;
+/**
+ * Start `chant run <op>` as a process of its own: the same node, loader and
+ * entry script this process runs as, in the project directory, with
+ * `CHANT_STEWARD` naming the steward and `--holder` naming the holder.
+ */
+export function spawnBesideRun(start) {
+    const args = [
+        ...process.execArgv,
+        process.argv[1],
+        "run",
+        start.op.name,
+        "--holder",
+        start.holder,
+        ...(start.env ? ["--env", start.env] : []),
+    ];
+    const child = spawn(process.execPath, args, {
+        cwd: start.cwd,
+        env: { ...process.env, CHANT_STEWARD: start.steward },
+        stdio: ["ignore", "inherit", "inherit"],
+    });
+    const done = new Promise((resolve) => {
+        child.once("error", (err) => resolve({ code: null, error: err.message }));
+        child.once("exit", (code, signal) => resolve(signal ? { code: null, error: `stopped by ${signal}` } : { code }));
+    });
+    return {
+        done,
+        // `chant run` stops its Op and releases its leases on SIGINT.
+        stop: () => {
+            if (child.exitCode === null && child.signalCode === null)
+                child.kill("SIGINT");
+        },
+    };
+}
+/**
+ * A launcher that runs the Op in this process, as an async task, under the
+ * same lease a `chant run` of it takes. For tests, and for an embedder whose
+ * activities are its own: the run does not enter the steward's turn (that is
+ * a property of the process, and the operator's own turns share it), so its
+ * record names the steward and a decision point it asks does not.
+ */
+export function inProcessBesideLauncher(activities, profiles) {
+    return (start) => {
+        const controller = new AbortController();
+        const done = (async () => {
+            const held = await holdBesideLease(start.op.name, start.holder, { cwd: start.cwd, ttlMs: start.leaseTtlMs });
+            if (!held.acquired)
+                return { code: 1, error: `the lease of "${start.op.name}" is held by ${held.heldBy ?? "another holder"}` };
+            try {
+                const result = await runOpLocally(start.op, activities, profiles, controller.signal, {
+                    steward: start.steward,
+                    // #2522: the same `--env` the spawned launcher passes on the command line.
+                    ...(start.env ? { env: start.env } : {}),
+                    ledger: { cwd: start.cwd },
+                    work: { holder: start.holder },
+                });
+                return { code: result.status === "gated" || result.status === "waiting" ? WAITING_EXIT : 0 };
+            }
+            catch (err) {
+                return { code: 1, error: err instanceof OpRunFailure ? `Op "${start.op.name}" failed` : err instanceof Error ? err.message : String(err) };
+            }
+            finally {
+                await held.release();
+            }
+        })();
+        return { done, stop: () => controller.abort() };
+    };
+}
+/**
+ * Take the Op's own lease for one run beside the steward's turns, and renew
+ * it every third of its time to live until `release` is called. A run of half
+ * an hour keeps it; a process that dies stops renewing and the lease expires.
+ * Refused when another holder has it: a run of the Op is in flight.
+ */
+export async function holdBesideLease(op, holder, opts = {}) {
+    const ttlMs = opts.ttlMs ?? DEFAULT_LEASE_TTL_MS;
+    const first = await acquireLease(op, holder, { cwd: opts.cwd, ttlMs });
+    if (!first.acquired)
+        return { acquired: false, ...(first.heldBy?.holder ? { heldBy: first.heldBy.holder } : {}) };
+    const lease = first.lease;
+    // A renewal that fails is retried on the next beat; one the lease refuses
+    // means another holder took it after it expired, and there is nothing to renew.
+    const timer = setInterval(() => {
+        void acquireLease(op, holder, { cwd: opts.cwd, ttlMs, mode: "renew", token: lease.token }).catch(() => undefined);
+    }, Math.max(1, Math.floor(ttlMs / 3)));
+    timer.unref?.();
+    let released = false;
+    return {
+        acquired: true,
+        lease,
+        release: async () => {
+            if (released)
+                return;
+            released = true;
+            clearInterval(timer);
+            await releaseLease(op, holder, lease.token, { cwd: opts.cwd }).catch(() => false);
+        },
+    };
+}
+/** How long a ready step may run when it names no `timeout`. */
+export const DEFAULT_READY_TIMEOUT_MS = 120000;
+/**
+ * Run a steward's `ready` step for an Op beside its turns (#2861) and read
+ * its answer with {@link readinessKeys}. The step is one activity call, with
+ * its own `timeout` or {@link DEFAULT_READY_TIMEOUT_MS}; it runs outside any
+ * run, so it writes no record, and it is the author's to keep it a read.
+ */
+export async function askReady(step, activities, signal) {
+    const fn = activities.get(step.fn);
+    if (!fn)
+        return { error: `its ready step's activity "${step.fn}" is not loaded` };
+    const timeoutMs = step.timeout ? parseDuration(step.timeout) : DEFAULT_READY_TIMEOUT_MS;
+    const controller = new AbortController();
+    const onAbort = () => controller.abort();
+    signal?.addEventListener("abort", onAbort, { once: true });
+    let timer;
+    try {
+        const call = Promise.resolve(fn({ ...(step.args ?? {}) }, controller.signal));
+        call.catch(() => { });
+        const result = await Promise.race([
+            call,
+            new Promise((_, reject) => {
+                timer = setTimeout(() => {
+                    controller.abort();
+                    reject(new Error(`timed out after ${timeoutMs}ms`));
+                }, timeoutMs);
+            }),
+        ]);
+        const answer = readinessKeys(result);
+        if (!answer)
+            return { error: "its ready step answered neither true, false, null, a string nor a list" };
+        return answer;
+    }
+    catch (err) {
+        return { error: err instanceof Error ? err.message : String(err) };
+    }
+    finally {
+        if (timer)
+            clearTimeout(timer);
+        signal?.removeEventListener("abort", onAbort);
+    }
+}

package/dist/op/steward-points.js

@@ -0,0 +1,138 @@
+/**
+ * A decision point asked inside an Op run (#2749), and in a steward's turn in
+ * particular.
+ *
+ * An Op that needs a decision (the factory's builder tier, whether to ship)
+ * calls {@link askPointInRun} from one of its activities, such as the decide
+ * activity (#2740). It asks the point through `askPoint` (ws-058,
+ * `../workspace/decide.ts`), which records the question and its answer as a
+ * record, and then:
+ *
+ * - an `answered` question returns its answer, and the Op goes on;
+ * - an `escalated` or `proposed` question is open, so the activity throws
+ *   {@link PointWait}. The executor ends the run there with status `waiting`,
+ *   as a gate ends it with `gated`: no later step runs, no `onFailure` phase
+ *   runs, and the run ledger records the question the run is waiting on.
+ *
+ * The question stays open in the workspace, where `chant workspace points
+ * --open`, MCP's `workspace-points` and hud read it, and a person answers it
+ * with `points answer`. Nothing waits in the meantime: the next run asks the
+ * same point with the same inputs, finds the answer record, and goes on. A
+ * local steward re-runs a waiting Op on the first round after its question is
+ * answered (`./operator.ts`).
+ *
+ * ## In a steward's turn
+ *
+ * A steward runs unattended, so two more rules hold when the process is a
+ * steward's turn (`./steward-turn.ts`):
+ *
+ * - The model call goes through the broker. The caller supplies the call as a
+ *   {@link BrokeredModelAsk}, which is handed the box capability to reach the
+ *   model through, and only a capability the steward declares
+ *   (`declareSteward({ capabilities })`, #2726). A steward that names none,
+ *   or holds a vault, makes no model call: the model decider is recorded as
+ *   not reached and the question goes to people.
+ * - The question is written on the `chant/lifecycle` branch, not in the
+ *   checkout (#2786): the working tree is the coding agent's, and an Op's
+ *   leased worktree goes when the run ends. `points` reads it from there
+ *   (`../workspace/answers-ledger.ts`), and a person's answer goes there too.
+ * - The question names the steward and its run in its source block, and
+ *   neither the steward's turn nor the steward's name can answer it: `points
+ *   answer` refuses inside a steward's turn (`answer-in-steward-turn`) and
+ *   leaves the asking steward out of the quorum.
+ *
+ * The question never goes to the steward's own thread: on Fountain that thread
+ * is the steward's, and nobody reads it for questions.
+ */
+var _a;
+import { currentStewardTurn } from "./steward-turn.js";
+/** The box capability a model call goes through when the caller names none. */
+export const DEFAULT_INFERENCE_CAPABILITY = "inference";
+/** The marker {@link PointWait} carries, so a copy of core linked twice still recognises it. */
+const POINT_WAIT = Symbol.for("chant.op.PointWait");
+/**
+ * Thrown by an activity whose decision point is open. Not a failure: the
+ * executor ends the run with status `waiting` (see the module doc).
+ */
+export class PointWait extends Error {
+    constructor(question) {
+        super(`waiting on decision point ${question.point} (${question.id}, ${question.state}): ` +
+            `a person answers it through hud or \`chant workspace points answer ${question.id}\``);
+        this.question = question;
+        this[_a] = true;
+        this.name = "PointWait";
+    }
+}
+_a = POINT_WAIT;
+/** Is this a {@link PointWait}? Duck-typed on the shared symbol. */
+export function isPointWait(err) {
+    return !!err && typeof err === "object" && err[POINT_WAIT] === true && "question" in err;
+}
+/** What a steward reaches through its broker, read from its declaration when the turn named only the steward. */
+async function stewardCapabilities(turn, cwd) {
+    if (turn.capabilities !== undefined)
+        return { capabilities: turn.capabilities, vault: turn.vault ?? null };
+    const { discoverStewards } = await import("./discover.js");
+    const found = (await discoverStewards({ cwd })).stewards.get(turn.steward)?.declaration;
+    return { capabilities: found?.capabilities ?? [], vault: found?.vault ?? null };
+}
+/**
+ * The {@link ModelAsk} a point is asked with. In a steward's turn the call is
+ * made only through a capability the steward declares; otherwise it throws,
+ * which the chain records as the model not being reached.
+ */
+export async function brokeredModelAsk(ask, opts) {
+    const capability = opts.capability ?? DEFAULT_INFERENCE_CAPABILITY;
+    const via = { capability, broker: opts.broker ?? null };
+    const turn = opts.turn === undefined ? currentStewardTurn() : opts.turn;
+    if (!turn)
+        return (request) => ask(request, via);
+    const { capabilities, vault } = await stewardCapabilities(turn, opts.cwd);
+    if (!capabilities.includes(capability)) {
+        const why = vault !== null
+            ? `the steward ${turn.steward} holds the vault ${vault} and names no brokered capabilities, and a steward's model call goes through the broker`
+            : `the steward ${turn.steward} does not name the brokered capability ${capability}` +
+                (capabilities.length ? ` (it names ${capabilities.join(", ")})` : "") +
+                `, and a steward holds no credential of its own`;
+        return async () => {
+            throw new Error(why);
+        };
+    }
+    return (request) => ask(request, via);
+}
+/**
+ * Ask a decision point from inside an Op run. Resolves with the answer when
+ * the question is answered, and throws {@link PointWait} when it is open.
+ * Any other problem (the points can't be read, the inputs are wrong, a model
+ * declared `unreachable: "fail"` could not answer) throws an ordinary error,
+ * which fails the step.
+ */
+export async function askPointInRun(opts) {
+    const turn = opts.turn === undefined ? currentStewardTurn() : opts.turn;
+    const ask = opts.ask ? await brokeredModelAsk(opts.ask, { capability: opts.capability, broker: opts.broker, turn, cwd: opts.cwd }) : undefined;
+    const { askPoint } = await import("../workspace/decide.js");
+    const doc = await askPoint({
+        cwd: opts.cwd,
+        point: opts.point,
+        inputs: opts.inputs,
+        ...(opts.subject !== undefined ? { subject: opts.subject } : {}),
+        ...(opts.kind !== undefined ? { kind: opts.kind } : {}),
+        ...(ask ? { ask } : {}),
+        ...(opts.on !== undefined ? { on: opts.on } : {}),
+        ...(opts.store !== undefined ? { store: opts.store } : {}),
+        ...(turn ? { steward: { name: turn.steward, ...(turn.run ? { run: turn.run } : {}) } } : {}),
+    });
+    if ("error" in doc)
+        throw new Error(`decision point ${opts.point}: ${doc.error.code}: ${doc.error.message}`);
+    const q = doc.question;
+    if (q.state === "answered" && q.answer !== null)
+        return { answer: q.answer, question: q };
+    throw new PointWait({
+        id: q.id,
+        point: q.point,
+        state: q.state === "proposed" ? "proposed" : "escalated",
+        path: q.path,
+        subject: q.subject,
+        steward: q.askedBy?.steward ?? null,
+    });
+}

package/dist/op/steward-turn.js

@@ -0,0 +1,59 @@
+/**
+ * Whether this process is a steward's turn, and whose (#2749).
+ *
+ * A steward runs unattended. In the local form, `chant operator --steward`
+ * is the steward for as long as it runs; on Fountain, the Agent's `chant acp
+ * --steward <name>` session is. Two things read this: a decision point asked
+ * during the turn (`./steward-points.ts`), which records the steward on the
+ * question and makes its model call through the steward's brokered
+ * capability, and `points answer`, which refuses to record an answer from a
+ * steward's own turn, as the gate ledger's origin rule refuses a gate
+ * resolved on the channel that reached it.
+ *
+ * Like the gate origin (`../lifecycle/gate-origin.ts`) this is a property of
+ * the process, set once at its entry point, not a parameter threaded through
+ * every executor and activity. It is also exported to child processes as
+ * `CHANT_STEWARD`, so a `chant workspace points answer` an Op shells out to
+ * is refused the same way.
+ */
+/** The environment variable a steward's turn carries into child processes. */
+export const STEWARD_ENV = "CHANT_STEWARD";
+let ambient;
+/**
+ * Declare that this process is a steward's turn. Called once by `chant
+ * operator --steward` and `chant acp --steward`; also exports
+ * {@link STEWARD_ENV} so a child process knows it too.
+ */
+export function setStewardTurn(turn) {
+    ambient = { ...turn };
+    process.env[STEWARD_ENV] = turn.steward;
+}
+/**
+ * Be a steward's turn until the returned function is called, which puts back
+ * whatever was there before. `chant operator --steward` enters one per Op run,
+ * naming the run, so a question asked during it names the run too.
+ */
+export function enterStewardTurn(turn) {
+    const before = ambient;
+    const envBefore = process.env[STEWARD_ENV];
+    setStewardTurn(turn);
+    return () => {
+        ambient = before;
+        if (envBefore === undefined)
+            delete process.env[STEWARD_ENV];
+        else
+            process.env[STEWARD_ENV] = envBefore;
+    };
+}
+/** The steward whose turn this process is, or undefined. */
+export function currentStewardTurn() {
+    if (ambient)
+        return ambient;
+    const name = process.env[STEWARD_ENV];
+    return name && name.trim() !== "" ? { steward: name.trim() } : undefined;
+}
+/** Forget the turn. For tests, which must not leak a steward into each other. */
+export function resetStewardTurn() {
+    ambient = undefined;
+    delete process.env[STEWARD_ENV];
+}