@dna113p/machines 0.2.0 → 0.3.1

package/dist/examples/deepseek.js

@@ -0,0 +1,27 @@
+import assert from "node:assert/strict";
+import { mkdtemp, readFile, rm } from "node:fs/promises";
+import { tmpdir } from "node:os";
+import { join } from "node:path";
+import { deepseekAgent } from "../src/deepseek.js";
+import { agent, final, machine, operation, run } from "../src/index.js";
+// Requires an installed, configured dsh ACP profile. May use model credits.
+// No automatic permission approval; all work is requested in this temporary cwd.
+const cwd = await mkdtemp(join(tmpdir(), "machines-deepseek-example-"));
+try {
+    const workflow = machine({
+        initial: "write",
+        states: {
+            write: agent('Create hello.txt in your working directory containing exactly "Hello from DeepSeek.\\n". Do not modify any other files.', { completed: "verify" }, { cwd }),
+            verify: operation(async () => {
+                assert.equal(await readFile(join(cwd, "hello.txt"), "utf8"), "Hello from DeepSeek.\n");
+                return { type: "verified" };
+            }, { verified: "done" }),
+            done: final(),
+        },
+    });
+    const result = await run(workflow, { agents: { default: deepseekAgent() } });
+    console.log(`write --completed--> verify --verified--> ${String(result.value)}`);
+}
+finally {
+    await rm(cwd, { recursive: true, force: true });
+}

package/dist/mcp/server.d.ts

@@ -4,6 +4,7 @@ import { type CallToolResult } from "@modelcontextprotocol/sdk/types.js";
 export type { RunSnapshot } from "../src/session.ts";
 export declare class MachineSession {
     #private;
+    constructor();
     list(input: unknown): Promise<CallToolResult>;
     agents(input: unknown): Promise<CallToolResult>;
     start(input: unknown): Promise<CallToolResult>;

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,12 +170,14 @@ 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 });
     }
     async start(input) {
-        const run = await this.#session.start(parse(startInput, input));
+        // This server publishes its runs itself, so that they also take responses through their inbox.
+        const run = await this.#session.start({ ...parse(startInput, input), publishRunStatus: false });
         return result(`Started ${run.machine}.\nRun id: ${run.id}\nStatus: ${run.status}`, { run });
     }
     status(input) {
@@ -179,6 +191,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 +250,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 +325,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 {};