@gigaai/newton 0.3.0 → 0.4.1

package/README.md

@@ -61,19 +61,26 @@ script body. The body runs as an async function with these in scope:
 
 | Primitive | What it does |
 |---|---|
-| `agent(prompt, opts?)` | Run one agent turn; returns its final text, or a schema-validated object when `opts.schema` is set. Returns `null` on agent failure — filter with `.filter(Boolean)`. |
+| `agent(prompt, opts?)` | Run one agent turn; returns its final text, or a schema-validated object when `opts.schema` is set. Transient failures (provider 5xx/overload, rate limits, dropped connections) retry up to twice with backoff; returns `null` on lasting failure — filter with `.filter(Boolean)`. |
 | `parallel(thunks)` | Run `() => …` tasks concurrently; a failed task resolves to `null`. Barrier: waits for all. |
 | `pipeline(items, ...stages)` | Each item flows through the stages independently — no barrier between stages. Stage signature: `(prev, item, index)`. |
 | `phase(title)` | Group subsequent agents in progress output. |
 | `log(message)` | Narrator line in progress output and the journal. |
+| `workflow(nameOrPath, args?)` | Run one child workflow. Bare names resolve from `.newton/workflows/<name>.js`; paths resolve relative to the calling workflow. Nesting is limited to one child level. |
 | `args` | Whatever you passed via `--args` (JSON-parsed when possible). |
 | `budget` | `{ total, spent(), remaining() }` for the `--budget` output-token ceiling. |
 
 `agent()` options: `provider` (see below), `model`, `effort` (`low`–`xhigh`),
 `access` (`read` | `write` | `full` — sandbox posture), `schema` (JSON Schema
 for structured output, validated with automatic retries), `label`, `phase`,
-`cwd`, `timeoutMs`, and `command` — an escape hatch to run any ACP agent,
-e.g. `command: ['my-agent', '--acp']`.
+`cwd`, `timeoutMs`, `isolation: 'worktree'` for disposable per-agent git
+worktrees, `mcp` (`true` for all `.mcp.json` servers, or a list of names/inline
+servers), `config` (ACP `configId` to string value), and `command` — an escape
+hatch to run any ACP agent, e.g. `command: ['my-agent', '--acp']`.
+
+Workflow scripts run in a sandboxed JavaScript realm: Node globals such as
+`process`, `fetch`, and `setTimeout` are not available, and `console.log()`
+routes through `log()` into progress output and the journal.
 
 ## Providers
 
@@ -98,7 +105,7 @@ the agent advertises over ACP (session config options) and selects it
 protocol-side. `newton models <provider>` shows what an agent exposes;
 requesting a model an agent doesn't offer fails with the available list.
 
-`Date.now()`, argless `new Date()`, and `Math.random()` throw inside
+`Date.now()`, argless `new Date()`, and `Math.random()` also throw inside
 workflows: nondeterminism would silently break `--resume` replay. Pass
 timestamps in via `--args`.
 
@@ -113,15 +120,32 @@ workspace:
   chunk, tool call, and permission decision.
 
 `newton run workflow.js --resume <runId>` replays successful agent results
-from a previous run's journal — identical calls return instantly and only new
-or changed calls hit real agents.
+from a previous run's journal. The default `--resume-mode prefix` replays by
+call position until the first changed agent call, then runs that call and
+everything after it live. `--resume-mode hash` uses the legacy hash replay:
+identical calls return instantly no matter where they appear.
+
+Long runs can be detached and controlled from another shell:
+
+- `newton run workflow.js --detach` starts in the background and prints
+  `{ runId, pid }`.
+- `newton runs [--json]` lists `.newton/runs/*` with status, agent count,
+  output tokens, and pid.
+- `newton watch <runId> [--json]` replays the journal from the beginning and
+  keeps tailing until the run ends.
+- `newton skip <runId> <agentId>` asks a queued or live agent to cancel;
+  `agent()` returns `null` and the workflow continues.
 
 ## CLI
 
 ```
 newton run <workflow.js>   --args <json> --cwd <dir> --resume <runId> --json
+                           --resume-mode <prefix|hash> --detach
                            --budget <tokens> --max-agents <n> --timeout <seconds>
                            --concurrency <n>
+newton runs [--json]             list runs under .newton/runs
+newton watch <runId> [--json]    replay/tail a run's journal
+newton skip <runId> <agentId>    cancel one agent; workflow continues
 newton validate <workflow.js>   parse + compile without spawning agents
 newton agents [--json]          supported agents: installed? signed in? (alias: doctor)
 newton models <provider>        ask an agent which models/modes it exposes

package/dist/acp.js

@@ -50,8 +50,14 @@ export class AcpAgentSession {
     toolCalls = 0;
     usage = null;
     stderrTail = [];
+    aborted;
+    abortSignal;
+    resolveAbortSignal;
     constructor(request) {
         this.request = request;
+        this.abortSignal = new Promise((resolveAbort) => {
+            this.resolveAbortSignal = resolveAbort;
+        });
     }
     async prompt() {
         try {
@@ -72,6 +78,15 @@ export class AcpAgentSession {
     }
     async promptAgain(prompt) {
         try {
+            if (this.aborted) {
+                return {
+                    text: this.text,
+                    stopReason: "cancelled",
+                    usage: this.usage,
+                    toolCalls: this.toolCalls,
+                    error: this.aborted,
+                };
+            }
             const connection = this.connection;
             const sessionId = this.sessionId;
             this.text = "";
@@ -84,7 +99,7 @@ export class AcpAgentSession {
                 sessionId,
                 prompt: [{ type: "text", text: prompt }],
             });
-            const outcome = await Promise.race([turn, timedOut]);
+            const outcome = await Promise.race([turn, timedOut, this.abortSignal]);
             clearTimeout(timer);
             if (outcome === "timeout") {
                 await connection.cancel({ sessionId }).catch(() => { });
@@ -99,6 +114,19 @@ export class AcpAgentSession {
                     error: `agent timed out after ${this.request.timeoutMs}ms`,
                 };
             }
+            if (outcome === "aborted") {
+                await connection.cancel({ sessionId }).catch(() => { });
+                // Give the agent a moment to flush final updates, then hard-stop.
+                await Promise.race([turn.catch(() => { }), new Promise((r) => setTimeout(r, 3000))]);
+                this.close();
+                return {
+                    text: this.text,
+                    stopReason: "cancelled",
+                    usage: this.usage,
+                    toolCalls: this.toolCalls,
+                    error: this.aborted,
+                };
+            }
             this.usage = outcome.usage ?? this.usage;
             return {
                 text: this.text,
@@ -111,6 +139,10 @@ export class AcpAgentSession {
             return this.failure(error);
         }
     }
+    abort(reason) {
+        this.aborted = reason;
+        this.resolveAbortSignal("aborted");
+    }
     close() {
         if (this.child && !this.child.killed)
             this.child.kill("SIGTERM");
@@ -187,13 +219,17 @@ export class AcpAgentSession {
                 session: { configOptions: {} },
             },
         });
-        const session = await connection.newSession({ cwd: resolve(cwd), mcpServers: [] });
+        const session = await connection.newSession({ cwd: resolve(cwd), mcpServers: this.request.mcpServers ?? [] });
         this.sessionId = session.sessionId;
         this.sessionInfo = session;
         trace({ type: "session", sessionId: session.sessionId, configOptions: session.configOptions ?? null });
         if (this.request.spec.model && !resolved.modelHandled) {
             await this.selectModelViaProtocol(session, this.request.spec.model);
         }
+        for (const [configId, value] of Object.entries(this.request.config ?? {})) {
+            await connection.setSessionConfigOption({ sessionId: this.sessionId, configId, value });
+            trace({ type: "config_set", configId, value });
+        }
     }
     /**
      * Providers without a CLI/env model knob may still expose model choice as an

package/dist/cli.js

@@ -1,7 +1,11 @@
 #!/usr/bin/env node
-import { accessSync, constants } from "node:fs";
+import { spawn } from "node:child_process";
+import { accessSync, closeSync, constants, mkdirSync, openSync } from "node:fs";
+import { dirname, join, resolve } from "node:path";
 import { AcpAgentSession } from "./acp.js";
+import { listRuns, readStatus, requestSkip, tailJournal } from "./control.js";
 import { compileWorkflow, loadWorkflow, runWorkflow } from "./executor.js";
+import { newRunId } from "./journal.js";
 import { HumanReporter, JsonReporter } from "./progress.js";
 import { describeProviders } from "./providers.js";
 import { VERSION } from "./version.js";
@@ -9,6 +13,10 @@ const USAGE = `newton — deterministic multi-agent workflows over ACP
 
 Usage:
   newton run <workflow.js> [options]   Run a workflow in the current directory
+  newton run <workflow.js> --detach     Start in the background; prints { runId, pid }
+  newton runs [--json]                List runs under .newton/runs with status
+  newton watch <runId> [--json]       Tail a run's journal as live progress
+  newton skip <runId> <agentId>       Cancel one agent; agent() returns null, run continues
   newton validate <workflow.js>       Parse + compile a workflow without running agents
   newton agents [--json]              Supported agents: installed? signed in? (alias: doctor)
   newton models <provider> [--json]   Ask an agent which models it exposes
@@ -17,6 +25,8 @@ Run options:
   --args <json>        Value exposed to the script as \`args\`
   --cwd <dir>          Workspace agents operate in (default: current directory)
   --resume <runId>     Replay cached agent results from a previous run
+  --resume-mode <prefix|hash>  Resume matching: positional prefix (default) or hash replay
+  --detach             Start the run in the background
   --json               NDJSON events on stdout instead of human output
   --budget <tokens>    Output-token ceiling; agent() throws once exhausted
   --max-agents <n>     Agent-call cap (default 200)
@@ -28,7 +38,11 @@ followed by a script body using agent()/parallel()/pipeline()/phase()/log(),
 with \`args\` and \`budget\` in scope. agent() opts: provider (codex | claude |
 gemini | qwen | cursor | opencode | goose | copilot), model, effort, access
 (read | write | full), schema, label, phase, cwd, command (any ACP agent,
-e.g. ["my-agent", "--acp"]).
+e.g. ["my-agent", "--acp"]), isolation ('worktree'), mcp (true | names/servers
+from .mcp.json), config ({configId: value}).
+Workflows may call workflow(nameOrPath, args) one level deep; bare names resolve
+from .newton/workflows/<name>.js.
+Scripts run sandboxed: no process/fetch/setTimeout; console.log routes to log().
 
 Runs are recorded under .newton/runs/<runId>/ — journal.jsonl plus a full
 per-agent ACP trace.`;
@@ -66,10 +80,47 @@ function intFlag(flags, name) {
         fail(`--${name} requires a positive integer`);
     return value;
 }
+function resumeModeFlag(flags) {
+    const raw = flags["resume-mode"];
+    if (raw === undefined)
+        return undefined;
+    if (raw === "prefix" || raw === "hash")
+        return raw;
+    fail("--resume-mode requires prefix or hash");
+}
+function commandRunDetached(file, flags) {
+    const cwd = typeof flags.cwd === "string" ? resolve(flags.cwd) : process.cwd();
+    const runId = newRunId();
+    const runDir = join(cwd, ".newton", "runs", runId);
+    mkdirSync(runDir, { recursive: true });
+    const fd = openSync(join(runDir, "detach.log"), "a");
+    const argv = [process.argv[1], "run", resolve(file), "--json", "--run-id", runId, "--cwd", cwd];
+    for (const name of ["args", "resume", "resume-mode", "budget", "max-agents", "timeout", "concurrency"]) {
+        const value = flags[name];
+        if (typeof value === "string")
+            argv.push(`--${name}`, value);
+    }
+    let child;
+    try {
+        child = spawn(process.execPath, argv, { detached: true, stdio: ["ignore", fd, fd] });
+    }
+    finally {
+        closeSync(fd);
+    }
+    if (!child)
+        fail("failed to start detached run");
+    child.unref();
+    process.stdout.write(`${JSON.stringify({ runId, pid: child.pid }, null, 2)}\n`);
+    process.exit(0);
+}
 async function commandRun(positional, flags) {
     const file = positional[0];
     if (!file)
         fail("newton run requires a workflow file");
+    const resumeMode = resumeModeFlag(flags);
+    if (flags.detach === true) {
+        commandRunDetached(file, flags);
+    }
     let args;
     if (typeof flags.args === "string") {
         try {
@@ -87,6 +138,9 @@ async function commandRun(positional, flags) {
         args,
         cwd: typeof flags.cwd === "string" ? flags.cwd : process.cwd(),
         resumeRunId: typeof flags.resume === "string" ? flags.resume : undefined,
+        resumeMode,
+        runId: typeof flags["run-id"] === "string" ? flags["run-id"] : undefined,
+        detached: typeof flags["run-id"] === "string",
         budgetTokens: intFlag(flags, "budget"),
         maxAgents: intFlag(flags, "max-agents"),
         agentTimeoutMs: timeoutSeconds ? timeoutSeconds * 1000 : undefined,
@@ -99,6 +153,126 @@ async function commandRun(positional, flags) {
     }
     process.exit(result.status === "ok" ? 0 : 1);
 }
+function commandRuns(flags) {
+    const workspace = process.cwd();
+    const rows = listRuns(workspace);
+    if (flags.json === true) {
+        process.stdout.write(`${JSON.stringify(rows.map(({ runId, stale, status }) => ({ runId, stale, ...(status ?? {}) })), null, 2)}\n`);
+        return;
+    }
+    if (rows.length === 0) {
+        process.stdout.write("no runs under .newton/runs\n");
+        return;
+    }
+    const table = [
+        ["runId", "status", "agents", "out-tok", "pid", "name"],
+        ...rows.map(({ runId, stale, status }) => [
+            runId,
+            stale ? "stale" : (status?.status ?? "—"),
+            status ? String(status.agents) : "",
+            status ? String(status.outputTokens) : "",
+            status ? String(status.pid) : "",
+            status?.name ?? "",
+        ]),
+    ];
+    const widths = table[0].map((_, index) => Math.max(...table.map((row) => row[index].length)));
+    for (const row of table) {
+        process.stdout.write(`${row.map((value, index) => value.padEnd(widths[index])).join("  ")}\n`);
+    }
+}
+async function commandWatch(positional, flags) {
+    const runId = positional[0];
+    if (!runId)
+        fail("newton watch requires a run id");
+    const runDir = join(process.cwd(), ".newton", "runs", runId);
+    try {
+        accessSync(runDir, constants.F_OK);
+    }
+    catch {
+        fail(`no run "${runId}"`);
+    }
+    const journalPath = join(runDir, "journal.jsonl");
+    const json = flags.json === true;
+    const reporter = new HumanReporter();
+    let startT;
+    let exitCode = 0;
+    const keepAlive = setInterval(() => { }, 1 << 30);
+    let handle;
+    handle = tailJournal(journalPath, (entry) => {
+        if (json) {
+            process.stdout.write(`${JSON.stringify(entry)}\n`);
+        }
+        else {
+            switch (entry.type) {
+                case "workflow_start":
+                    startT = Date.parse(String(entry.t));
+                    reporter.start({ name: String(entry.name), description: "" }, String(entry.runId), dirname(journalPath));
+                    break;
+                case "phase":
+                    reporter.phase(String(entry.title));
+                    break;
+                case "log":
+                    reporter.log(String(entry.message));
+                    break;
+                case "agent_start":
+                    reporter.agentStart(Number(entry.id), String(entry.label), entry.spec, entry.phase, false);
+                    break;
+                case "agent_end": {
+                    if (entry.cached === true) {
+                        reporter.agentStart(Number(entry.id), String(entry.label), {}, entry.phase, true);
+                    }
+                    const ok = entry.status === "ok";
+                    reporter.agentEnd(Number(entry.id), ok, Number(entry.seconds ?? 0), ok ? (entry.cached ? "cached" : `${entry.toolCalls ?? 0} tools`) : String(entry.error ?? "error"));
+                    break;
+                }
+                case "workflow_child_start":
+                    reporter.log(`▸ workflow ${entry.name}`);
+                    break;
+                case "workflow_child_end":
+                    reporter.log(`${entry.status === "ok" ? "✔" : "✖"} workflow ${entry.name}`);
+                    break;
+            }
+        }
+        if (entry.type === "workflow_end") {
+            const endT = Date.parse(String(entry.t));
+            exitCode = entry.status === "ok" ? 0 : 1;
+            if (!json) {
+                reporter.done({
+                    runId,
+                    status: entry.status,
+                    result: entry.result,
+                    error: entry.error,
+                    agents: Number(entry.agents ?? 0),
+                    outputTokens: Number(entry.outputTokens ?? 0),
+                    durationMs: startT ? Math.max(0, endT - startT) : 0,
+                });
+            }
+            clearInterval(keepAlive);
+            handle.stop();
+            process.exit(exitCode);
+        }
+    });
+}
+function commandSkip(positional) {
+    const runId = positional[0];
+    const rawAgentId = positional[1];
+    if (!runId || !rawAgentId)
+        fail("newton skip requires a run id and agent id");
+    const agentId = Number(rawAgentId);
+    if (!Number.isInteger(agentId) || agentId <= 0)
+        fail("agentId requires a positive integer");
+    try {
+        requestSkip(process.cwd(), runId, agentId);
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    process.stdout.write(`skip requested: run ${runId} agent #${agentId}\n`);
+    const status = readStatus(join(process.cwd(), ".newton", "runs", runId));
+    if (status?.status !== "running") {
+        process.stderr.write(`warning: run ${runId} status is ${status?.status ?? "unknown"}; skip may have no effect\n`);
+    }
+}
 function commandValidate(positional) {
     const file = positional[0];
     if (!file)
@@ -184,6 +358,15 @@ async function main() {
         case "run":
             await commandRun(positional, flags);
             break;
+        case "runs":
+            commandRuns(flags);
+            break;
+        case "watch":
+            await commandWatch(positional, flags);
+            break;
+        case "skip":
+            commandSkip(positional);
+            break;
         case "validate":
             try {
                 commandValidate(positional);

package/dist/control.js

@@ -0,0 +1,169 @@
+import { closeSync, mkdirSync, openSync, readFileSync, readSync, readdirSync, renameSync, statSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+export function writeStatus(runDir, status) {
+    const tmpPath = join(runDir, "status.json.tmp");
+    const statusPath = join(runDir, "status.json");
+    writeFileSync(tmpPath, `${JSON.stringify(status, null, 2)}\n`, "utf8");
+    renameSync(tmpPath, statusPath);
+}
+export function readStatus(runDir) {
+    try {
+        return JSON.parse(readFileSync(join(runDir, "status.json"), "utf8"));
+    }
+    catch {
+        return undefined;
+    }
+}
+export function pidAlive(pid) {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch (error) {
+        return errorCode(error) === "EPERM";
+    }
+}
+export function listRuns(workspace) {
+    const runsDir = join(workspace, ".newton", "runs");
+    let runIds;
+    try {
+        runIds = readdirSync(runsDir, { withFileTypes: true })
+            .filter((entry) => entry.isDirectory())
+            .map((entry) => entry.name)
+            .sort()
+            .reverse();
+    }
+    catch {
+        return [];
+    }
+    return runIds.map((runId) => {
+        const status = readStatus(join(runsDir, runId));
+        return {
+            runId,
+            status,
+            stale: status?.status === "running" && !pidAlive(status.pid),
+        };
+    });
+}
+export function requestSkip(workspace, runId, agentId) {
+    const runDir = join(workspace, ".newton", "runs", runId);
+    try {
+        if (!statSync(runDir).isDirectory()) {
+            throw new Error("not a directory");
+        }
+    }
+    catch {
+        throw new Error(`no run "${runId}" under .newton/runs`);
+    }
+    const controlDir = join(runDir, "control");
+    mkdirSync(controlDir, { recursive: true });
+    writeFileSync(join(controlDir, `skip-${agentId}`), "", "utf8");
+}
+export function readSkipRequests(runDir) {
+    const ids = new Set();
+    let entries;
+    try {
+        entries = readdirSync(join(runDir, "control"));
+    }
+    catch {
+        return ids;
+    }
+    for (const entry of entries) {
+        const match = /^skip-(\d+)$/.exec(entry);
+        if (!match)
+            continue;
+        const id = Number(match[1]);
+        if (Number.isInteger(id))
+            ids.add(id);
+    }
+    return ids;
+}
+export function tailJournal(journalPath, onEntry, pollMs = 300) {
+    let offset = 0;
+    let partial = Buffer.alloc(0);
+    let stopped = false;
+    function emitLine(line) {
+        const text = line.toString("utf8");
+        if (!text.trim())
+            return;
+        let entry;
+        try {
+            entry = JSON.parse(text);
+        }
+        catch {
+            // Ignore incomplete/corrupt journal lines; later valid lines still stream.
+            return;
+        }
+        if (entry !== null && typeof entry === "object" && !Array.isArray(entry)) {
+            onEntry(entry);
+        }
+    }
+    function consume(chunk) {
+        const data = partial.length === 0 ? chunk : Buffer.concat([partial, chunk]);
+        let lineStart = 0;
+        for (let i = 0; i < data.length; i++) {
+            if (data[i] !== 10)
+                continue;
+            emitLine(data.subarray(lineStart, i));
+            lineStart = i + 1;
+        }
+        partial = lineStart < data.length ? data.subarray(lineStart) : Buffer.alloc(0);
+    }
+    function tick() {
+        if (stopped)
+            return;
+        let size;
+        try {
+            const stat = statSync(journalPath);
+            if (!stat.isFile())
+                return;
+            size = stat.size;
+        }
+        catch {
+            return;
+        }
+        if (size < offset) {
+            offset = 0;
+            partial = Buffer.alloc(0);
+        }
+        if (size === offset)
+            return;
+        let fd;
+        try {
+            fd = openSync(journalPath, "r");
+            const length = size - offset;
+            const chunk = Buffer.alloc(length);
+            const bytesRead = readSync(fd, chunk, 0, length, offset);
+            if (bytesRead <= 0)
+                return;
+            offset += bytesRead;
+            consume(bytesRead === chunk.length ? chunk : chunk.subarray(0, bytesRead));
+        }
+        catch {
+            return;
+        }
+        finally {
+            if (fd !== undefined) {
+                try {
+                    closeSync(fd);
+                }
+                catch {
+                    // A close failure should not stop journal polling.
+                }
+            }
+        }
+    }
+    const timer = setInterval(tick, pollMs);
+    timer.unref();
+    return {
+        stop() {
+            stopped = true;
+            clearInterval(timer);
+        },
+    };
+}
+function errorCode(error) {
+    return typeof error === "object" && error !== null && "code" in error
+        ? error.code
+        : undefined;
+}