@dna113p/machines 0.2.0 → 0.3.1

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[]>;

package/dist/src/catalog.js

@@ -1,6 +1,16 @@
-import { loadAgentBindings } from "./agent-bindings.js";
+import { fallbackPresets, loadAgentBindings } from "./agent-bindings.js";
 import { acpAgent } from "./acp.js";
+import { AgentLimitError } from "./agent-limit.js";
 import { agyAgent } from "./agy.js";
+import { chatGptWebAgent } from "./chatgpt-web.js";
+import { claudeAgent } from "./claude.js";
+import { codexAgent } from "./codex.js";
+import { deepseekAgent } from "./deepseek.js";
+import { decisionAgent } from "./decision.js";
+import { jevAgent, jevProvider } from "./jev.js";
+import { layaAgent, layaProvider } from "./laya.js";
+import { vonAgent, vonProvider } from "./von.js";
+import { openRouterDecisionAgent, openRouterDecisionProvider } from "./openrouter.js";
 import { discoverMachines, machinesUserHome } from "./discovery.js";
 import { loadMachineModule, readAgentRoles, requireMachineDescription } from "./machine-module.js";
 export async function inspectMachines(location = {}) {
@@ -35,18 +45,25 @@ export async function inspectAgentPresets(location = {}) {
     const home = location.home ?? machinesUserHome();
     const configured = await configuredAgentPresets(cwd, home);
     return Object.entries(configured.presets)
-        .map(([name, preset]) => ({
-        name,
-        description: preset.description,
-        ...(preset.harness === undefined ? {} : { harness: preset.harness }),
-        ...(preset.model === undefined ? {} : { model: preset.model }),
-        ...(preset.thinking === undefined ? {} : { thinking: preset.thinking }),
-        source: configured.sources[name] ?? "unknown",
-    }))
+        .map(([name, preset]) => {
+        const fallback = fallbackPresets(name, preset, configured.fallback);
+        return {
+            name,
+            description: preset.description,
+            ...(preset.harness === undefined ? {} : { harness: preset.harness }),
+            ...(preset.model === undefined ? {} : { model: preset.model }),
+            ...(preset.thinking === undefined ? {} : { thinking: preset.thinking }),
+            ...(fallback === undefined ? {} : { fallback }),
+            source: configured.sources[name] ?? "unknown",
+        };
+    })
         .sort((left, right) => left.name.localeCompare(right.name));
 }
 export async function configuredAgentPresets(cwd, home) {
-    const configured = await loadAgentBindings(cwd, home, { acpAgent, agyAgent });
+    const configured = await loadAgentBindings(cwd, home, {
+        acpAgent, AgentLimitError, agyAgent, chatGptWebAgent, claudeAgent, codexAgent, deepseekAgent, decisionAgent, jevAgent, jevProvider,
+        openRouterDecisionAgent, openRouterDecisionProvider, layaAgent, layaProvider, vonAgent, vonProvider,
+    });
     const defaultRunner = acpAgent("npx", ["-y", "pi-acp"], {
         harness: "pi-acp",
         output: "capture",
@@ -55,8 +72,19 @@ export async function configuredAgentPresets(cwd, home) {
         harness: "agy",
         output: "capture",
     });
+    const claudeRunner = claudeAgent("claude", [], { output: "capture" });
+    const codexRunner = codexAgent("codex", [], { output: "capture" });
+    const chatGptWebRunner = chatGptWebAgent({ output: "capture" });
+    const deepseekRunner = deepseekAgent("dsh", [], { output: "capture" });
+    const jevRunner = jevAgent();
+    const openRouterRunner = openRouterDecisionAgent();
+    const layaRunner = layaAgent();
+    const vonRunner = vonAgent();
     return {
-        agents: { default: defaultRunner, agy: agyRunner, ...configured.agents },
+        agents: {
+            default: defaultRunner, agy: agyRunner, claude: claudeRunner, codex: codexRunner, "chatgpt-web": chatGptWebRunner, deepseek: deepseekRunner, jev: jevRunner,
+            "openrouter-decision": openRouterRunner, laya: layaRunner, von: vonRunner, ...configured.agents,
+        },
         presets: {
             default: {
                 description: "Runs the current Pi Agent through ACP",
@@ -68,9 +96,53 @@ export async function configuredAgentPresets(cwd, home) {
                 harness: "agy",
                 runner: agyRunner,
             },
+            claude: {
+                description: "Runs the Claude Code CLI headlessly with its own login and permission rules",
+                harness: "claude",
+                runner: claudeRunner,
+            },
+            codex: {
+                description: "Runs the Codex CLI in a read-only sandbox",
+                harness: "codex",
+                runner: codexRunner,
+            },
+            "chatgpt-web": {
+                description: "Runs a new ChatGPT web conversation that works locally through rig-bridge",
+                harness: "chatgpt-web",
+                runner: chatGptWebRunner,
+            },
+            deepseek: {
+                description: "Runs DeepSeek Harness (dsh) through ACP",
+                harness: "dsh",
+                runner: deepseekRunner,
+            },
+            jev: {
+                description: "Classifies supplied evidence with Jev; does not execute tools",
+                harness: "jev",
+                runner: jevRunner,
+            },
+            "openrouter-decision": {
+                description: "Classifies supplied evidence through OpenRouter Decisions; does not execute tools",
+                harness: "openrouter-decision",
+                runner: openRouterRunner,
+            },
+            laya: {
+                description: "Classifies supplied evidence through a self-hosted Laya bridge; does not execute tools",
+                harness: "laya",
+                runner: layaRunner,
+            },
+            von: {
+                description: "Classifies supplied evidence through a self-hosted Von server; does not execute tools",
+                harness: "von",
+                runner: vonRunner,
+            },
             ...configured.presets,
         },
-        sources: { default: "built in", agy: "built in", ...configured.sources },
+        sources: {
+            default: "built in", agy: "built in", claude: "built in", codex: "built in", "chatgpt-web": "built in", deepseek: "built in", jev: "built in",
+            "openrouter-decision": "built in", laya: "built in", von: "built in", ...configured.sources,
+        },
+        ...(configured.fallback === undefined ? {} : { fallback: configured.fallback }),
     };
 }
 function errorMessage(cause) {

package/dist/src/chatgpt-web.d.ts

@@ -0,0 +1,143 @@
+import type { AgentReporter, AgentRequest, Event } from "./index.ts";
+/** CSS selectors for the ChatGPT page. Override them when the web UI changes. */
+export interface ChatGptWebSelectors {
+    readonly composer: string;
+    readonly send: string;
+    readonly stop: string;
+    readonly assistant: string;
+    readonly plus: string;
+    readonly menuItem: string;
+    /** A control only a signed-out page shows. Links and buttons labelled "Log in" or "Sign in" also count. */
+    readonly signIn: string;
+}
+/** Each list names the page as it is today and as it was before, for accounts a rollout has not reached. */
+export declare const defaultChatGptWebSelectors: ChatGptWebSelectors;
+export interface ChatGptWebBrowserLaunch {
+    /** Chromium-family executable. Defaults to `CHATGPT_WEB_BROWSER`, then a PATH search. */
+    readonly executable?: string;
+    /** Dedicated browser profile holding the ChatGPT login. */
+    readonly userDataDir?: string;
+    readonly headless?: boolean;
+    readonly args?: readonly string[];
+}
+/** Explicit handoff notification recorded by rig-bridge when an assistant finishes a stretch of work. */
+export interface RigBridgeHandoff {
+    readonly id: string;
+    readonly projectId: string;
+    readonly threadId: string;
+    readonly runId?: string;
+    readonly reason: "completed" | "needs_input" | "blocked" | "failed" | "cancelled" | string;
+    readonly summary: string;
+    readonly createdAt: number;
+}
+/** Event returned by the ChatGPT Web runner, enriched with handoff and conversation metadata. */
+export interface ChatGptWebEvent extends Event {
+    readonly type: string;
+    readonly summary?: string;
+    readonly message?: string;
+    readonly handoff?: RigBridgeHandoff;
+    /** The chat's lasting address. Absent when ChatGPT did not show one before the run ended. */
+    readonly conversation?: string;
+}
+export interface RigBridgeStatusView {
+    readonly version?: string;
+    readonly startedAt?: number;
+    readonly uptimeSeconds?: number;
+    readonly workspacesCount?: number;
+    readonly activeCommandsCount?: number;
+    readonly workspaces: readonly {
+        readonly id: string;
+        readonly projectId?: string;
+        readonly threadId?: string;
+        readonly cwd: string;
+        readonly createdAt?: number;
+    }[];
+    readonly notifications?: readonly RigBridgeHandoff[];
+    readonly unreadCount?: number;
+}
+export interface ChatGptWebAgentOptions {
+    readonly env?: Readonly<Record<string, string>>;
+    readonly harness?: string;
+    /** Start page: ChatGPT, a Project, or a GPT. Defaults to `CHATGPT_WEB_URL` or https://chatgpt.com/. */
+    readonly url?: string;
+    /** Model slug appended as `?model=`. Defaults to `CHATGPT_WEB_MODEL`. */
+    readonly model?: string;
+    /** DevTools endpoint. Defaults to `CHATGPT_WEB_CDP_URL` or http://127.0.0.1:9222. */
+    readonly cdpUrl?: string;
+    /** Launch a persistent, detached browser when the endpoint is unreachable. Defaults to true. */
+    readonly launch?: boolean | ChatGptWebBrowserLaunch;
+    /**
+     * Name the rig-bridge app has in this person's ChatGPT, matched against the text of the composer's add menu.
+     * Defaults to `CHATGPT_WEB_CONNECTOR` or "rig-bridge".
+     */
+    readonly connector?: string;
+    /** Try to enable the connector from the composer's + menu. Defaults to true. */
+    readonly selectConnector?: boolean;
+    /** Click visible tool confirmation buttons. Defaults to false. */
+    readonly approveToolCalls?: boolean;
+    readonly approveLabels?: readonly string[];
+    /** rig-bridge status endpoint used for activity, or false. Defaults to `RIG_BRIDGE_STATUS_URL` or :8767. */
+    readonly bridgeStatusUrl?: string | false;
+    /** Automatically mark handoff notifications read on rig-bridge when completed. Defaults to true. */
+    readonly acknowledgeHandoff?: boolean;
+    readonly timeoutMs?: number;
+    /** How long the composer may take to appear after the tab opens. Defaults to 45 seconds. */
+    readonly composerTimeoutMs?: number;
+    /** Quiet period after generation stops before the reply is treated as final. */
+    readonly settleMs?: number;
+    readonly pollMs?: number;
+    /** Keep the tab after success. Failed runs always keep their tab for inspection. */
+    readonly keepTab?: boolean;
+    readonly selectors?: Partial<ChatGptWebSelectors>;
+    readonly output?: "capture" | "stream";
+}
+/** Finds a Chromium-family browser able to expose the DevTools protocol. */
+export declare function findChromeExecutable(env?: Readonly<Record<string, string | undefined>>): Promise<string | undefined>;
+export declare function defaultChatGptWebProfile(env?: Readonly<Record<string, string | undefined>>): string;
+/** Builds the conversation opener that points ChatGPT at the local workspace through rig-bridge. */
+export declare function chatGptWebPrompt(request: AgentRequest & {
+    readonly cwd: string;
+}, connector: string): string;
+export type ChatGptWebAgentRunner = (request: AgentRequest, report?: AgentReporter) => Promise<ChatGptWebEvent>;
+/** One message for an existing ChatGPT web conversation that works in `cwd` through rig-bridge. */
+export interface ChatGptWebContinueInput {
+    /** Conversation URL, such as the `conversation` of an earlier ChatGPT Web event. */
+    readonly conversation: string;
+    /** Message to send. It is submitted exactly as given. */
+    readonly text: string;
+    readonly cwd: string;
+    /** Only count a handoff from this rig-bridge thread. */
+    readonly bridgeThreadId?: string;
+}
+export type ChatGptWebContinueRunner = (input: ChatGptWebContinueInput, report?: AgentReporter) => Promise<ChatGptWebEvent>;
+/** Runs one fresh ChatGPT web conversation that works in the request's directory via rig-bridge. */
+export declare function chatGptWebAgent(options?: ChatGptWebAgentOptions): ChatGptWebAgentRunner;
+/**
+ * Sends one message to an existing ChatGPT web conversation and returns the next rig-bridge handoff.
+ * The handoff is the whole result: assistant messages are never read from the page.
+ */
+export declare function chatGptWebContinue(options?: ChatGptWebAgentOptions): ChatGptWebContinueRunner;
+/** Fetches the latest bridge status from rig-bridge. */
+export declare function fetchRigBridgeStatus(statusUrl?: string): Promise<RigBridgeStatusView | undefined>;
+/** Finds the most recent handoff notification from rig-bridge matching the given directory or thread. */
+export declare function fetchLatestRigBridgeHandoff(options?: {
+    readonly cwd?: string;
+    readonly threadId?: string;
+    readonly statusUrl?: string;
+    readonly since?: number;
+}): Promise<RigBridgeHandoff | undefined>;
+/** Acknowledges / marks read a handoff on rig-bridge. */
+export declare function acknowledgeRigBridgeHandoff(handoffId: string, options?: {
+    readonly statusUrl?: string;
+}): Promise<boolean>;
+/**
+ * Creates an Operation for a Machine that inspects rig-bridge for the latest handoff notification,
+ * returning an Event with `type = handoff.reason` and attaching `summary` and `handoff`.
+ */
+export declare function rigBridgeHandoffOperation(options?: {
+    readonly cwd?: string;
+    readonly threadId?: string;
+    readonly statusUrl?: string;
+    readonly since?: number;
+    readonly acknowledge?: boolean;
+}): () => Promise<ChatGptWebEvent>;