@dna113p/machines 0.2.0 → 0.3.0

package/dist/mcp/server.js

@@ -6,15 +6,19 @@ import { Server } from "@modelcontextprotocol/sdk/server/index.js";
 import { StdioServerTransport } from "@modelcontextprotocol/sdk/server/stdio.js";
 import { CallToolRequestSchema, ListResourcesRequestSchema, ListToolsRequestSchema, ReadResourceRequestSchema, } from "@modelcontextprotocol/sdk/types.js";
 import * as v from "valibot";
+import { isJsonValue } from "../src/json.js";
 import { MachineSession as RunSession } from "../src/session.js";
 import { listAgentPresets, listMachines } from "../src/launcher.js";
+import { watchRunInbox } from "../src/run-inbox.js";
+import { createRunStatusPublisher, runStatusDirectory } from "../src/run-status.js";
+import { machineCoordinatorGuidelines, machineDiscoveryDescription, machineSupervisionGuidelines } from "../src/coordinator-guidance.js";
 const widgetUri = "ui://machines/run-v1.html";
 const cwd = v.pipe(v.string(), v.nonEmpty("cwd must be a non-empty absolute path"), v.check(isAbsolute, "cwd must be an absolute path"));
 const listInput = v.strictObject({ cwd });
 const startInput = v.strictObject({
     cwd,
     machine: v.pipe(v.string(), v.nonEmpty("machine must not be empty")),
-    input: v.optional(v.string()),
+    input: v.optional(v.custom(isJsonValue)),
     agents: v.optional(v.record(v.pipe(v.string(), v.nonEmpty("Agent role names must not be empty")), v.pipe(v.string(), v.nonEmpty("Agent preset names must not be empty")))),
 });
 const statusInput = v.strictObject({
@@ -40,7 +44,7 @@ const tools = [
     {
         name: "machine_list",
         title: "List Machines",
-        description: "List Machines available to the current project, why to use them, and any missing Agent bindings.",
+        description: machineDiscoveryDescription,
         inputSchema: locationInputSchema,
         annotations: { readOnlyHint: false, destructiveHint: true, openWorldHint: true },
     },
@@ -67,8 +71,7 @@ const tools = [
                     description: "Exact Machine name returned by machine_list",
                 },
                 input: {
-                    type: "string",
-                    description: "Clear task or input for the Machine",
+                    description: "JSON-serializable task or structured input for the Machine",
                 },
                 agents: {
                     type: "object",
@@ -135,6 +138,13 @@ const tools = [
 ];
 export class MachineSession {
     #session = new RunSession();
+    #published = new Map();
+    #inboxes = new Map();
+    /** The inbox delivery being handed to the session, named in the update that leaves its request. */
+    #taking;
+    constructor() {
+        this.#session.subscribe(({ run }) => this.#publish(run));
+    }
     async list(input) {
         const { cwd } = parse(listInput, input);
         const machines = await listMachines({ cwd });
@@ -160,7 +170,8 @@ export class MachineSession {
                 const identity = [agent.harness, agent.model, agent.thinking]
                     .filter((part) => part !== undefined)
                     .join(" · ");
-                return `${agent.name} — ${agent.description}${identity === "" ? "" : ` (${identity})`}\n  ${agent.source}`;
+                const fallback = agent.fallback === undefined ? "" : ` · fallback: ${agent.fallback.join(", ") || "none"}`;
+                return `${agent.name} — ${agent.description}${identity === "" ? "" : ` (${identity})`}\n  ${agent.source}${fallback}`;
             }).join("\n\n");
         return result(text, { agents });
     }
@@ -179,6 +190,58 @@ export class MachineSession {
     }
     close() {
         this.#session.close();
+        // Closing terminates the session's runs without a final event.
+        for (const publisher of this.#published.values())
+            publisher.finish({ error: "Machine session closed" });
+        this.#published.clear();
+        for (const inbox of this.#inboxes.values())
+            inbox.stop();
+        this.#inboxes.clear();
+    }
+    #publish(run) {
+        let publisher = this.#published.get(run.id);
+        if (publisher === undefined) {
+            publisher = createRunStatusPublisher({
+                id: run.id,
+                machine: run.machine,
+                path: run.path,
+                cwd: run.cwd,
+                startedAt: run.startedAt,
+            });
+            this.#published.set(run.id, publisher);
+        }
+        const human = run.status === "waiting" ? run.human : undefined;
+        this.#watchInbox(run.id, human);
+        if (run.status === "running" || run.status === "waiting") {
+            publisher.update({
+                status: run.status, state: run.state, agent: run.agent, limit: run.limit, human, delivery: this.#taking,
+            });
+            return;
+        }
+        publisher.finish(run.status === "completed" ? { state: run.state } : { error: run.error ?? "Machine run failed" });
+        this.#published.delete(run.id);
+    }
+    /** A published request can also be answered, or asked about, through the run's inbox by `machine respond`. */
+    #watchInbox(runId, request) {
+        const watched = this.#inboxes.get(runId);
+        if (watched?.requestId === request?.requestId)
+            return;
+        watched?.stop();
+        this.#inboxes.delete(runId);
+        const directory = runStatusDirectory();
+        if (request === undefined || directory === undefined)
+            return;
+        const stop = watchRunInbox(directory, runId, request, (response, delivery) => {
+            // The session leaves the request before either call returns. A tool call
+            // may have answered first; the session then refuses this one unpublished.
+            this.#taking = delivery;
+            const sent = typeof response === "string"
+                ? this.#session.respond({ runId, requestId: request.requestId, response })
+                : this.#session.ask({ runId, requestId: request.requestId, question: response.text });
+            this.#taking = undefined;
+            sent.catch(() => { });
+        });
+        this.#inboxes.set(runId, { requestId: request.requestId, stop });
     }
 }
 export function createMachinesMcpServer(widgetHtml = readFileSync(new URL("../codex/machines/ui/machines.html", import.meta.url), "utf8")) {
@@ -186,11 +249,8 @@ export function createMachinesMcpServer(widgetHtml = readFileSync(new URL("../co
     const server = new Server({ name: "machines", version: "0.1.0" }, {
         capabilities: { tools: {}, resources: {} },
         instructions: [
-            "Use machine_list when the user names a Machine or a reusable multi-step workflow may fit.",
-            "Choose by description rather than guessing a Machine name.",
-            "machine_start is asynchronous; continue the conversation while it runs.",
-            "Use machine_status for authoritative progress and machine_respond only after the Human's answer is clear.",
-            "If no Machine fits a one-off task, handle it normally. Ask before creating persistent Machine policy.",
+            ...machineCoordinatorGuidelines,
+            ...machineSupervisionGuidelines,
         ].join(" "),
     });
     server.onclose = () => session.close();
@@ -264,6 +324,8 @@ function formatSnapshot(run) {
             run.agent.thinking === undefined ? undefined : `thinking ${run.agent.thinking}`,
         ].filter((part) => part !== undefined).join(" · ")}`);
     }
+    if (run.limit !== undefined)
+        lines.push(`Limit: ${run.limit.text}`);
     if (run.human !== undefined) {
         lines.push(`Human: ${run.human.prompt}`, `Request id: ${run.human.requestId}`);
         if (run.human.choices !== undefined)

package/dist/pi-extension/index.js

@@ -10,6 +10,8 @@ import { realpathSync } from "node:fs";
 import { dirname, resolve } from "node:path";
 import { fileURLToPath, pathToFileURL } from "node:url";
 import { Type } from "typebox";
+import { assertJsonValue } from "../src/json.js";
+import { machineCoordinatorGuidelines, machineDiscoveryDescription } from "../src/coordinator-guidance.js";
 const sourceFile = realpathSync(fileURLToPath(import.meta.url));
 const sourceRoot = resolve(dirname(sourceFile), "..");
 const moduleExtension = sourceFile.endsWith(".ts") ? "ts" : "js";
@@ -105,12 +107,9 @@ export default function machinesExtension(pi) {
     pi.registerTool({
         name: "machine_list",
         label: "List Machines",
-        description: "List available Machines, their purpose, Agent roles, and missing bindings.",
-        promptSnippet: "Discover reusable asynchronous Machines with machine_list before starting one.",
-        promptGuidelines: [
-            "Use machine_list when the user asks to run a Machine or a reusable multi-step workflow may fit; choose an existing Machine by its description rather than guessing its name.",
-            "If no Machine fits, handle a one-off task normally. For a reusable workflow, propose a short state sequence and ask before creating persistent Machine policy.",
-        ],
+        description: machineDiscoveryDescription,
+        promptSnippet: "Discover and use Machines before delegated or multi-step work.",
+        promptGuidelines: machineCoordinatorGuidelines,
         parameters: Type.Object({}, { additionalProperties: false }),
         executionMode: "parallel",
         async execute(_id, _params, _signal, _onUpdate, context) {
@@ -156,7 +155,8 @@ export default function machinesExtension(pi) {
                     const identity = [agent.harness, agent.model, agent.thinking]
                         .filter((part) => part !== undefined)
                         .join(" · ");
-                    return `${agent.name} — ${agent.description}${identity === "" ? "" : ` (${identity})`}\n  ${agent.source}`;
+                    const fallback = agent.fallback === undefined ? "" : ` · fallback: ${agent.fallback.join(", ") || "none"}`;
+                    return `${agent.name} — ${agent.description}${identity === "" ? "" : ` (${identity})`}\n  ${agent.source}${fallback}`;
                 }).join("\n");
             return result(text, {
                 summary: `${agents.length} Agent preset${agents.length === 1 ? "" : "s"}`,
@@ -177,13 +177,15 @@ export default function machinesExtension(pi) {
         ],
         parameters: Type.Object({
             machine: Type.String({ description: "Exact Machine name from machine_list" }),
-            input: Type.Optional(Type.String({ description: "The task or input for the Machine" })),
+            input: Type.Optional(Type.Unknown({ description: "JSON-serializable task or structured input for the Machine" })),
             agents: Type.Optional(Type.Record(Type.String(), Type.String(), { description: "Optional Machine role to configured Agent preset name" })),
         }, { additionalProperties: false }),
         async execute(_id, rawParams, _signal, _onUpdate, context) {
             useContext(context);
             const machine = requiredString(rawParams.machine, "machine");
-            const input = optionalString(rawParams.input, "input");
+            const input = rawParams.input;
+            if (input !== undefined)
+                assertJsonValue(input, "Machine input");
             const agents = optionalStringRecord(rawParams.agents, "agents");
             const runs = await getSession();
             const run = await runs.start({
@@ -263,6 +265,8 @@ function formatSnapshot(run) {
     ];
     if (run.agent !== undefined)
         lines.push(`Agent: ${formatAgent(run.agent)}`);
+    if (run.limit !== undefined)
+        lines.push(`Limit: ${run.limit.text}`);
     if (run.human !== undefined) {
         lines.push(`Human: ${run.human.prompt}`, `Request id: ${run.human.requestId}`);
         if (run.human.choices !== undefined)
@@ -314,6 +318,9 @@ function widgetLines(runs, theme, width) {
                 lines.push(`${edge("│")}   ${theme.fg("warning", promptLine)}`);
             }
         }
+        else if (run.limit !== undefined) {
+            lines.push(`${edge("│")}   ${theme.fg("warning", run.limit.text)}`);
+        }
         else if (run.agent !== undefined) {
             lines.push(`${edge("│")}   ${theme.fg("muted", formatAgent(run.agent))}`);
         }

package/dist/src/acp.js

@@ -21,7 +21,8 @@ export function acpAgent(command, args = [], options = {}) {
         child.stderr.setEncoding("utf8");
         child.stderr.on("data", (chunk) => {
             stderr += chunk;
-            process.stderr.write(chunk);
+            if (options.output !== "capture")
+                process.stderr.write(chunk);
         });
         try {
             await waitForSpawn(child);

package/dist/src/agent-bindings.d.ts

@@ -5,11 +5,17 @@ export interface AgentPreset {
     readonly harness?: string;
     readonly model?: string;
     readonly thinking?: string;
+    /** Presets that take over at a usage limit, in order, instead of the shared list. `[]` never swaps. */
+    readonly fallback?: readonly string[];
 }
 export interface LoadedAgentBindings {
     readonly agents: Readonly<Record<string, AgentRunner>>;
     readonly presets: Readonly<Record<string, AgentPreset>>;
     readonly sources: Readonly<Record<string, string>>;
+    /** The shared fallback list from the nearest file that exports one. */
+    readonly fallback?: readonly string[];
 }
 export type AgentAdapters = Readonly<Record<string, unknown>>;
 export declare function loadAgentBindings(cwd?: string, home?: string, adapters?: AgentAdapters): Promise<LoadedAgentBindings>;
+/** The presets that take over from one preset at a usage limit: its own chain, else the shared list without itself. */
+export declare function fallbackPresets(name: string, preset: Pick<AgentPreset, "fallback">, shared: readonly string[] | undefined): readonly string[] | undefined;

package/dist/src/agent-bindings.js

@@ -10,7 +10,7 @@ import { stat } from "node:fs/promises";
 import { join, resolve } from "node:path";
 import { pathToFileURL } from "node:url";
 import { machinesUserHome, nearestMachinesDirectory } from "./discovery.js";
-const presetFields = new Set(["description", "runner", "harness", "model", "thinking"]);
+const presetFields = new Set(["description", "runner", "harness", "model", "thinking", "fallback"]);
 export async function loadAgentBindings(cwd = process.cwd(), home = machinesUserHome(), adapters = {}) {
     const globalPath = join(home, ".machines", "agents.ts");
     const projectDirectory = await nearestMachinesDirectory(cwd);
@@ -23,17 +23,24 @@ export async function loadAgentBindings(cwd = process.cwd(), home = machinesUser
     const agents = {};
     const presets = {};
     const sources = {};
+    let fallback;
     for (const path of paths) {
         if (!await isFile(path))
             continue;
-        const bindings = await loadBindingFile(path, adapters);
-        for (const [name, preset] of Object.entries(bindings)) {
+        const loaded = await loadBindingFile(path, adapters);
+        for (const [name, preset] of Object.entries(loaded.presets)) {
             agents[name] = preset.runner;
             presets[name] = preset;
             sources[name] = path;
         }
+        // The nearer file's list replaces the other; the lists are never merged.
+        fallback = loaded.fallback ?? fallback;
     }
-    return { agents, presets, sources };
+    return { agents, presets, sources, ...(fallback === undefined ? {} : { fallback }) };
+}
+/** The presets that take over from one preset at a usage limit: its own chain, else the shared list without itself. */
+export function fallbackPresets(name, preset, shared) {
+    return preset.fallback ?? shared?.filter((other) => other !== name);
 }
 async function loadBindingFile(path, adapters) {
     let loaded;
@@ -82,9 +89,32 @@ async function loadBindingFile(path, adapters) {
             ...optionalField(candidate.harness, "harness", name, path),
             ...optionalField(candidate.model, "model", name, path),
             ...optionalField(candidate.thinking, "thinking", name, path),
+            ...(candidate.fallback === undefined
+                ? {}
+                : { fallback: fallbackNames(candidate.fallback, `Agent preset "${name}" fallback in "${path}"`, name) }),
         };
     }
-    return bindings;
+    const shared = loaded.fallback;
+    return {
+        presets: bindings,
+        ...(shared === undefined ? {} : { fallback: fallbackNames(shared, `Agent bindings "${path}" fallback export`) }),
+    };
+}
+function fallbackNames(value, subject, self) {
+    if (!Array.isArray(value))
+        throw new Error(`${subject} must be an array of preset names`);
+    const names = [];
+    for (const name of value) {
+        if (typeof name !== "string" || name.trim() === "" || name !== name.trim() || /\r|\n|\t/u.test(name)) {
+            throw new Error(`${subject} must contain only non-empty, trimmed, one-line preset names`);
+        }
+        if (names.includes(name))
+            throw new Error(`${subject} names "${name}" more than once`);
+        if (name === self)
+            throw new Error(`${subject} must not name the preset itself`);
+        names.push(name);
+    }
+    return names;
 }
 function optionalField(value, field, name, path) {
     return value === undefined

package/dist/src/agent-limit.d.ts

@@ -0,0 +1,25 @@
+/** A provider usage limit that ended an Agent turn. */
+export interface AgentLimit {
+    /** The runner's harness label, for example "claude" or "codex". */
+    readonly harness: string;
+    /** The preset name. Runners leave it unset; the caller that selected the preset fills it in. */
+    readonly agent?: string;
+    /** The provider's name for the limit when known, for example "five_hour", "seven_day_opus", or "usage". */
+    readonly kind?: string;
+    /** Epoch milliseconds, only when the provider states when the limit resets. */
+    readonly resetsAt?: number;
+}
+declare const brand: unique symbol;
+/** Thrown by an Agent runner when the provider refuses a turn because a usage limit is reached. */
+export declare class AgentLimitError extends Error {
+    readonly limit: AgentLimit;
+    /** Every limit behind the failure when several presets were tried, each naming its preset in `agent`. */
+    readonly limits?: readonly AgentLimit[];
+    readonly [brand] = true;
+    constructor(message: string, limit: AgentLimit, options?: ErrorOptions & {
+        readonly limits?: readonly AgentLimit[];
+    });
+}
+/** Returns the usage limit behind a failure, searching its `cause` chain. */
+export declare function agentLimitOf(cause: unknown): AgentLimit | undefined;
+export {};

package/dist/src/agent-limit.js

@@ -0,0 +1,34 @@
+// A registered symbol identifies the error across module copies (source, `dist`,
+// another package's installed copy), where `instanceof` would not.
+const brand = Symbol.for("machines.agent-limit");
+const maximumCauseDepth = 8;
+/** Thrown by an Agent runner when the provider refuses a turn because a usage limit is reached. */
+export class AgentLimitError extends Error {
+    limit;
+    /** Every limit behind the failure when several presets were tried, each naming its preset in `agent`. */
+    limits;
+    [brand] = true;
+    constructor(message, limit, options) {
+        super(message, options);
+        this.name = "AgentLimitError";
+        this.limit = limit;
+        if (options?.limits !== undefined)
+            this.limits = options.limits;
+    }
+}
+/** Returns the usage limit behind a failure, searching its `cause` chain. */
+export function agentLimitOf(cause) {
+    let current = cause;
+    for (let depth = 0; depth < maximumCauseDepth; depth += 1) {
+        if (current === null || typeof current !== "object")
+            return undefined;
+        if (brand in current && current[brand] === true && "limit" in current && isAgentLimit(current.limit)) {
+            return current.limit;
+        }
+        current = "cause" in current ? current.cause : undefined;
+    }
+    return undefined;
+}
+function isAgentLimit(value) {
+    return value !== null && typeof value === "object" && "harness" in value && typeof value.harness === "string";
+}

package/dist/src/agent-limits.d.ts

@@ -0,0 +1,37 @@
+import { type AgentLimit } from "./agent-limit.ts";
+import type { AgentRunner } from "./index.ts";
+export interface LimitPolicy {
+    /** Longest one invocation waits for a reset, from its first wait. `0` never waits. */
+    readonly maxWaitMs: number;
+    /** How long a limit with no stated reset is trusted before the request is tried again. */
+    readonly probeMs: number;
+    readonly now?: () => number;
+    /** A replacement must let `now` advance by about the time it was asked to sleep. */
+    readonly sleep?: (ms: number) => Promise<void>;
+}
+export interface LimitCandidate {
+    /** The preset name. */
+    readonly name: string;
+    readonly runner: AgentRunner;
+    readonly harness?: string;
+}
+interface RememberedLimit {
+    readonly limit: AgentLimit;
+    /** When the preset is worth trying again. */
+    readonly until: number;
+    /** Whether `until` is the provider's stated reset rather than the next probe. */
+    readonly known: boolean;
+}
+/** Presets known to be at a limit, by name. One per prepared run, shared by its roles, never stored. */
+export type LimitMemory = Map<string, RememberedLimit>;
+export declare const defaultProbeMs: number;
+export declare function createLimitMemory(): LimitMemory;
+/**
+ * Runs one role's request on the first candidate that is not at a usage limit.
+ * A limited candidate hands the same request to the next one; when all are
+ * limited the request waits for a reset within the policy, or fails.
+ * A request with `limits: "report"` is tried on the bound candidate alone, and
+ * its limit is thrown at once.
+ */
+export declare function limitAwareRunner(role: string, candidates: readonly LimitCandidate[], memory: LimitMemory, policy: LimitPolicy): AgentRunner;
+export {};

package/dist/src/agent-limits.js

@@ -0,0 +1,212 @@
+import { AgentLimitError, agentLimitOf } from "./agent-limit.js";
+export const defaultProbeMs = 15 * 60_000;
+// A provider's reset time is when its window ends, not when it accepts requests again.
+const resetMarginMs = 60_000;
+// Short sleeps measured against the clock notice a reset that passed while the computer was suspended.
+const tickMs = 60_000;
+const handoffNote = [
+    "Note: a previous Agent working on this assignment was interrupted by a usage limit and may have",
+    "left partial work in the workspace. Inspect the current state and continue the same assignment",
+    "rather than starting over.",
+].join(" ");
+export function createLimitMemory() {
+    return new Map();
+}
+/**
+ * Runs one role's request on the first candidate that is not at a usage limit.
+ * A limited candidate hands the same request to the next one; when all are
+ * limited the request waits for a reset within the policy, or fails.
+ * A request with `limits: "report"` is tried on the bound candidate alone, and
+ * its limit is thrown at once.
+ */
+export function limitAwareRunner(role, candidates, memory, policy) {
+    const bound = candidates[0];
+    if (bound === undefined)
+        throw new Error(`Agent role "${role}" needs at least one preset`);
+    const now = policy.now ?? Date.now;
+    const sleep = policy.sleep ?? timerSleep;
+    const named = (name) => name === role ? name : `${name} (role ${role})`;
+    const limited = (name, retrying) => {
+        const remembered = memory.get(name);
+        return remembered !== undefined && remembered.until > now() && retrying?.has(remembered) !== true;
+    };
+    // The state decides what its limit means, so nothing is swapped, waited for, or reported as an update.
+    const reported = async (request, report) => {
+        const known = memory.get(bound.name);
+        if (known !== undefined && known.until > now()) {
+            throw new AgentLimitError(`${named(bound.name)} is at its usage limit (${resetText(known)})`, known.limit);
+        }
+        try {
+            const event = await bound.runner(request, report);
+            if (known !== undefined && memory.get(bound.name) === known)
+                memory.delete(bound.name);
+            return event;
+        }
+        catch (cause) {
+            const limit = agentLimitOf(cause);
+            if (limit === undefined)
+                throw cause;
+            // The run's other roles skip this preset, and the limit names it.
+            throw new AgentLimitError(cause instanceof Error ? cause.message : String(cause), remember(bound, limit).limit, { cause });
+        }
+    };
+    return async (request, report) => {
+        if (request.limits === "report")
+            return reported(request, report);
+        // A state is announced after its Agent starts, in the same tick. Observers
+        // attach an update to the announced state, so none is reported before then.
+        const tell = async (update) => {
+            await Promise.resolve();
+            report?.(update);
+        };
+        let interrupted = false;
+        let lastFailure;
+        let deadline;
+        // A wait is reported once, and lasts until a candidate gets past its limit.
+        let waiting = false;
+        let retrying = new Set();
+        for (;;) {
+            let passedOver;
+            for (const [index, candidate] of candidates.entries()) {
+                if (limited(candidate.name, retrying)) {
+                    passedOver ??= candidate;
+                    continue;
+                }
+                if (passedOver !== undefined && !interrupted && !waiting) {
+                    // Another role of this run found the limit, so this one names the preset it runs on instead.
+                    // After a wait the preset is named when the Agent resumes.
+                    await tell(swapped(named(passedOver.name), "is at", memory.get(passedOver.name), passedOver, candidate));
+                }
+                passedOver = undefined;
+                const resume = () => {
+                    if (!waiting)
+                        return;
+                    waiting = false;
+                    report?.({
+                        type: "limit",
+                        status: "resumed",
+                        agent: bound.name,
+                        ...(candidate === bound ? {} : { to: candidate.name }),
+                        text: `${named(bound.name)} waited for a usage limit to reset; continuing${candidate === bound ? "" : ` with ${candidate.name}`}`,
+                    });
+                };
+                const tried = memory.get(candidate.name);
+                let limit;
+                try {
+                    const event = await candidate.runner(interrupted ? withHandoffNote(request) : request, 
+                    // A limited turn can still report its identity and the provider's message; a tool call is work.
+                    !waiting ? report : (update) => {
+                        if (update.type === "tool")
+                            resume();
+                        report?.(update);
+                    });
+                    resume();
+                    // What was remembered for a preset that answers is out of date, also for the run's other roles.
+                    if (tried !== undefined && memory.get(candidate.name) === tried)
+                        memory.delete(candidate.name);
+                    return event;
+                }
+                catch (cause) {
+                    limit = agentLimitOf(cause);
+                    if (limit === undefined)
+                        throw cause;
+                    lastFailure = cause;
+                }
+                interrupted = true;
+                const remembered = remember(candidate, limit);
+                const next = candidates.slice(index + 1).find((later) => !limited(later.name, retrying));
+                // Also while a wait is reported: each probe that moves on to another preset is a swap.
+                if (next !== undefined)
+                    await tell(swapped(named(candidate.name), "reached", remembered, candidate, next));
+            }
+            const limits = candidates.flatMap((candidate) => {
+                const remembered = memory.get(candidate.name);
+                return remembered === undefined ? [] : [{ candidate, remembered }];
+            });
+            const started = now();
+            deadline ??= started + policy.maxWaitMs;
+            const closes = deadline;
+            const wakes = policy.maxWaitMs <= 0 ? [] : limits.flatMap(({ remembered }) => {
+                if (remembered.known) {
+                    return remembered.until <= closes ? [{ remembered, at: remembered.until + resetMarginMs }] : [];
+                }
+                // The last probe of a limit with no stated reset is at the deadline.
+                return started < closes ? [{ remembered, at: Math.min(remembered.until, closes) }] : [];
+            });
+            if (wakes.length === 0)
+                throw exhausted(role, limits, policy.maxWaitMs, lastFailure);
+            const wakeAt = Math.min(...wakes.map((wake) => wake.at));
+            // A reset that passed while a later candidate was working needs no wait.
+            if (!waiting && wakeAt > now()) {
+                waiting = true;
+                const resets = wakes.filter((wake) => wake.remembered.known).map((wake) => wake.remembered.until);
+                const until = timestamp(resets.length === 0 ? closes : Math.min(...resets));
+                const others = candidates.slice(1).map((candidate) => candidate.name);
+                await tell({
+                    type: "limit",
+                    status: "waiting",
+                    agent: bound.name,
+                    until,
+                    text: `${named(bound.name)}${others.length === 0
+                        ? " reached its usage limit"
+                        : ` and its fallback${others.length === 1 ? "" : "s"} (${others.join(", ")}) reached their usage limits`}; ${resets.length === 0 ? `no reset is stated, retrying until ${until}` : `waiting for the reset at ${until}`}`,
+                });
+            }
+            for (let remaining = wakeAt - now(); remaining > 0; remaining = wakeAt - now()) {
+                await sleep(Math.min(remaining, tickMs));
+            }
+            retrying = new Set(wakes.filter((wake) => wake.at <= wakeAt).map((wake) => wake.remembered));
+        }
+    };
+    function remember(candidate, limit) {
+        const at = now();
+        // A reset that has already passed says nothing about when to try again.
+        const known = limit.resetsAt !== undefined && limit.resetsAt > at;
+        const remembered = {
+            limit: { ...limit, agent: candidate.name },
+            until: known ? limit.resetsAt : at + policy.probeMs,
+            known,
+        };
+        memory.set(candidate.name, remembered);
+        return remembered;
+    }
+}
+function withHandoffNote(request) {
+    return { ...request, prompt: `${request.prompt}\n\n${handoffNote}` };
+}
+function swapped(subject, verb, remembered, from, to) {
+    return {
+        type: "limit",
+        status: "swapped",
+        agent: from.name,
+        to: to.name,
+        text: `${subject} ${verb} its usage limit (${resetText(remembered)}); continuing with ${to.name}`,
+    };
+}
+function exhausted(role, limits, maxWaitMs, cause) {
+    const described = limits.map(({ candidate, remembered }) => {
+        const details = [candidate.harness ?? remembered.limit.harness, remembered.limit.kind, resetText(remembered)];
+        return `${candidate.name} (${details.filter((detail) => detail !== undefined).join(", ")})`;
+    });
+    const reason = maxWaitMs <= 0
+        ? "waiting for a reset is off"
+        : `none is available within the ${formatMinutes(maxWaitMs)} wait limit`;
+    const known = limits.filter(({ remembered }) => remembered.known)
+        .sort((left, right) => left.remembered.until - right.remembered.until);
+    const earliest = (known[0] ?? limits[0])?.remembered.limit ?? { harness: "unknown" };
+    return new AgentLimitError(`Agent role "${role}" is at a usage limit on every allowed preset: ${described.join("; ")}; ${reason}`, earliest, { limits: limits.map(({ remembered }) => remembered.limit), ...(cause === undefined ? {} : { cause }) });
+}
+function resetText(remembered) {
+    return remembered?.known === true ? `resets ${timestamp(remembered.until)}` : "reset unknown";
+}
+function timestamp(time) {
+    return new Date(time).toISOString().replace(/\.\d{3}Z$/u, "Z");
+}
+function formatMinutes(milliseconds) {
+    const minutes = Math.round(milliseconds / 6_000) / 10;
+    return `${minutes}-minute`;
+}
+// The timer stays referenced: a waiting run is working, and must keep its process alive.
+function timerSleep(milliseconds) {
+    return new Promise((resolve) => { setTimeout(resolve, milliseconds); });
+}

package/dist/src/agent-protocol.js

@@ -2,7 +2,9 @@ export function agentPrompt(request) {
     return [
         request.prompt,
         "",
-        "Complete the work using the available tools.",
+        "You are already executing one Agent state inside a Machine. Complete this assigned state using the available tools.",
+        "Do not re-delegate this assignment or start the parent workflow again unless the assignment explicitly requires bounded nested work.",
+        "Return evidence and an allowed outcome to the owning Machine; it controls verification, transitions, and Human decisions.",
         `Allowed outcome types: ${request.outcomes.join(", ")}.`,
         "When finished, end your final response with exactly one line in this form:",
         'MACHINES_EVENT {"type":"completed"}',

package/dist/src/catalog.d.ts

@@ -14,6 +14,8 @@ export interface AgentPresetSummary {
     readonly harness?: string;
     readonly model?: string;
     readonly thinking?: string;
+    /** The presets that take over at a usage limit, in order; absent when none is configured. */
+    readonly fallback?: readonly string[];
     readonly source: string;
 }
 export interface LauncherLocation {
@@ -24,6 +26,7 @@ interface ResolvedAgentPresets {
     readonly agents: Readonly<Record<string, AgentRunner>>;
     readonly presets: Readonly<Record<string, AgentPreset>>;
     readonly sources: Readonly<Record<string, string>>;
+    readonly fallback?: readonly string[];
 }
 export declare function inspectMachines(location?: LauncherLocation): Promise<readonly MachineSummary[]>;
 export declare function inspectAgentPresets(location?: LauncherLocation): Promise<readonly AgentPresetSummary[]>;