@gigaai/newton 0.3.0

package/README.md

@@ -0,0 +1,142 @@
+# Newton
+
+Newton runs deterministic multi-agent workflows. A workflow is a plain
+JavaScript file; the control flow (loops, fan-out, conditionals) is your code,
+and the non-deterministic parts are delegated to coding agents over the
+[Agent Client Protocol](https://agentclientprotocol.com) — Codex, Claude Code,
+Gemini CLI, or any other ACP-speaking agent.
+
+No config files, no server, no accounts. `newton run workflow.js` in a
+workspace and it works.
+
+## Install
+
+```bash
+npm install -g @gigaai/newton   # or: npx @gigaai/newton
+```
+
+Or grab a standalone binary from
+[Releases](https://github.com/GigaML/newton/releases) — no Node required.
+
+Agents authenticate themselves: `openai` uses your existing `codex` login (or
+`OPENAI_API_KEY` / `CODEX_API_KEY`). Check your environment with `newton doctor`.
+
+## Quick start
+
+```js
+// hello.js
+export const meta = {
+  name: 'hello',
+  description: 'Two scouts in parallel, then a structured synthesis.',
+}
+
+phase('Scout')
+const notes = await parallel([
+  () => agent('Describe the layout of this repository.', { provider: 'openai', model: 'gpt-5.5', access: 'read' }),
+  () => agent('Find the entry points of this repository.', { provider: 'openai', model: 'gpt-5.5', access: 'read' }),
+])
+
+phase('Synthesize')
+const report = await agent(`Merge these notes:\n\n${notes.filter(Boolean).join('\n\n')}`, {
+  provider: 'openai',
+  model: 'gpt-5.5',
+  access: 'read',
+  schema: { type: 'object', required: ['summary'], properties: { summary: { type: 'string' } } },
+})
+
+return { report }
+```
+
+```bash
+newton run hello.js
+```
+
+Progress streams to stderr; the result JSON prints to stdout. Pass `--json`
+for NDJSON events instead — built for driving Newton from another agent.
+
+## Workflow API
+
+A workflow file is `export const meta = { name, description }` followed by a
+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)`. |
+| `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. |
+| `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']`.
+
+## Providers
+
+| Provider | Aliases | Model override | Runs via |
+|---|---|---|---|
+| `codex` | `openai` | yes | bundled codex-acp adapter |
+| `claude` | `anthropic` | yes | claude-agent-acp adapter |
+| `gemini` | `google` | yes | `gemini --experimental-acp` |
+| `qwen` | `qwen-code` | yes | `qwen --acp` |
+| `cursor` | `cursor-agent` | no | cursor-agent-acp adapter |
+| `opencode` | | no | `opencode acp` |
+| `goose` | | no | `goose acp` |
+| `copilot` | `github-copilot` | no | copilot-language-server `--acp` |
+
+Resolution order per provider: newton's own node_modules → PATH → `npx -y`.
+Agents authenticate themselves with their normal logins; `newton agents`
+detects which ones are installed and signed in on this machine.
+
+Model selection works two ways: providers with a CLI/env knob get it passed
+directly, and for everything else Newton matches `model:` against the models
+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
+workflows: nondeterminism would silently break `--resume` replay. Pass
+timestamps in via `--args`.
+
+## Runs, traces, resume
+
+Every run writes durable artifacts to `.newton/runs/<runId>/` in the
+workspace:
+
+- `journal.jsonl` — every lifecycle event, including each agent's prompt and
+  full result.
+- `agents/<n>.jsonl` — the complete ACP wire trace per agent: every message
+  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.
+
+## CLI
+
+```
+newton run <workflow.js>   --args <json> --cwd <dir> --resume <runId> --json
+                           --budget <tokens> --max-agents <n> --timeout <seconds>
+                           --concurrency <n>
+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
+```
+
+Exit codes: `0` success, `1` workflow error, `2` usage error.
+
+## Development
+
+```bash
+npm install
+npm run check      # build + validate the example
+node dist/cli.js run examples/hello.js
+```
+
+Standalone binaries are built with `bun build --compile` (see
+`.github/workflows/release.yml`); pushing a `v*` tag publishes to npm and
+attaches binaries to a GitHub Release.

package/dist/acp.js

@@ -0,0 +1,257 @@
+import { spawn } from "node:child_process";
+import { readFile, writeFile } from "node:fs/promises";
+import { resolve } from "node:path";
+import { Readable, Writable } from "node:stream";
+import { ClientSideConnection, ndJsonStream, PROTOCOL_VERSION, } from "@agentclientprotocol/sdk";
+import { resolveAgentCommand } from "./providers.js";
+import { VERSION } from "./version.js";
+const READ_ONLY_TOOL_KINDS = new Set(["read", "search", "fetch", "think", "other"]);
+function pickPermissionOption(params, access) {
+    const readOnly = access === "read";
+    const toolKind = params.toolCall.kind ?? "other";
+    const wantAllow = !readOnly || READ_ONLY_TOOL_KINDS.has(toolKind);
+    const preference = wantAllow
+        ? ["allow_always", "allow_once"]
+        : ["reject_once", "reject_always"];
+    for (const kind of preference) {
+        const option = params.options.find((o) => o.kind === kind);
+        if (option)
+            return { outcome: { outcome: "selected", optionId: option.optionId } };
+    }
+    const fallback = params.options[0];
+    if (fallback)
+        return { outcome: { outcome: "selected", optionId: fallback.optionId } };
+    return { outcome: { outcome: "cancelled" } };
+}
+const liveChildren = new Set();
+function killAll() {
+    for (const child of liveChildren)
+        child.kill("SIGKILL");
+}
+process.once("exit", killAll);
+for (const signal of ["SIGINT", "SIGTERM"]) {
+    process.once(signal, () => {
+        killAll();
+        process.exit(130);
+    });
+}
+/**
+ * Run one agent turn over ACP: spawn the agent, initialize, open a session,
+ * send the prompt, and collect streamed output until the turn stops.
+ * `promptAgain` allows follow-up turns in the same session (structured-output retries).
+ */
+export class AcpAgentSession {
+    child;
+    connection;
+    sessionId;
+    sessionInfo;
+    request;
+    text = "";
+    toolCalls = 0;
+    usage = null;
+    stderrTail = [];
+    constructor(request) {
+        this.request = request;
+    }
+    async prompt() {
+        try {
+            await this.ensureSession();
+            return await this.promptAgain(this.request.prompt);
+        }
+        catch (error) {
+            return this.failure(error);
+        }
+    }
+    /** Open a session and report what the agent exposes, without prompting. */
+    async inspect() {
+        await this.ensureSession();
+        return {
+            modes: this.sessionInfo?.modes ?? null,
+            configOptions: this.sessionInfo?.configOptions ?? [],
+        };
+    }
+    async promptAgain(prompt) {
+        try {
+            const connection = this.connection;
+            const sessionId = this.sessionId;
+            this.text = "";
+            this.request.trace({ type: "prompt", prompt });
+            let timer;
+            const timedOut = new Promise((resolveTimeout) => {
+                timer = setTimeout(() => resolveTimeout("timeout"), this.request.timeoutMs);
+            });
+            const turn = connection.prompt({
+                sessionId,
+                prompt: [{ type: "text", text: prompt }],
+            });
+            const outcome = await Promise.race([turn, timedOut]);
+            clearTimeout(timer);
+            if (outcome === "timeout") {
+                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: "timeout",
+                    usage: this.usage,
+                    toolCalls: this.toolCalls,
+                    error: `agent timed out after ${this.request.timeoutMs}ms`,
+                };
+            }
+            this.usage = outcome.usage ?? this.usage;
+            return {
+                text: this.text,
+                stopReason: outcome.stopReason,
+                usage: this.usage,
+                toolCalls: this.toolCalls,
+            };
+        }
+        catch (error) {
+            return this.failure(error);
+        }
+    }
+    close() {
+        if (this.child && !this.child.killed)
+            this.child.kill("SIGTERM");
+        if (this.child)
+            liveChildren.delete(this.child);
+        this.child = undefined;
+    }
+    failure(error) {
+        this.close();
+        const message = error instanceof Error ? error.message : String(error);
+        const stderr = this.stderrTail.join("").trim();
+        this.request.trace({ type: "error", message, stderr });
+        return {
+            text: this.text,
+            stopReason: "error",
+            usage: this.usage,
+            toolCalls: this.toolCalls,
+            error: stderr ? `${message}\n${stderr.slice(-2000)}` : message,
+        };
+    }
+    async ensureSession() {
+        if (this.sessionId)
+            return;
+        const { spec, cwd, trace } = this.request;
+        const resolved = resolveAgentCommand(spec);
+        trace({ type: "spawn", command: resolved.command, args: resolved.args });
+        const child = spawn(resolved.command, resolved.args, {
+            cwd,
+            env: { ...process.env, ...resolved.env },
+            stdio: ["pipe", "pipe", "pipe"],
+        });
+        this.child = child;
+        liveChildren.add(child);
+        child.once("exit", () => liveChildren.delete(child));
+        child.stderr.setEncoding("utf8");
+        child.stderr.on("data", (data) => {
+            this.stderrTail.push(data);
+            if (this.stderrTail.length > 50)
+                this.stderrTail.shift();
+            trace({ type: "stderr", data });
+        });
+        const spawned = new Promise((resolveSpawn, rejectSpawn) => {
+            child.once("spawn", () => resolveSpawn());
+            child.once("error", (error) => rejectSpawn(error));
+        });
+        await spawned;
+        const stream = ndJsonStream(Writable.toWeb(child.stdin), Readable.toWeb(child.stdout));
+        const clientHandler = {
+            requestPermission: (params) => {
+                const response = pickPermissionOption(params, this.request.spec.access);
+                trace({ type: "permission", request: params, response });
+                return response;
+            },
+            sessionUpdate: (params) => this.handleUpdate(params),
+            readTextFile: async (params) => {
+                const content = await readFile(resolve(cwd, params.path), "utf8");
+                return { content };
+            },
+            writeTextFile: async (params) => {
+                if (this.request.spec.access === "read") {
+                    throw new Error("write rejected: agent has read-only access");
+                }
+                await writeFile(resolve(cwd, params.path), params.content, "utf8");
+                return {};
+            },
+        };
+        const connection = new ClientSideConnection(() => clientHandler, stream);
+        this.connection = connection;
+        await connection.initialize({
+            protocolVersion: PROTOCOL_VERSION,
+            clientInfo: { name: "newton", version: VERSION },
+            clientCapabilities: {
+                fs: { readTextFile: true, writeTextFile: true },
+                session: { configOptions: {} },
+            },
+        });
+        const session = await connection.newSession({ cwd: resolve(cwd), 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);
+        }
+    }
+    /**
+     * Providers without a CLI/env model knob may still expose model choice as an
+     * ACP session config option — match the requested model against it.
+     */
+    async selectModelViaProtocol(session, model) {
+        const flatten = (options) => {
+            const values = options.options;
+            if (values.length > 0 && "group" in values[0]) {
+                return values.flatMap((g) => g.options);
+            }
+            return values;
+        };
+        const selects = (session.configOptions ?? []).filter((o) => o.type === "select" && (o.category === "model" || (!o.category && /model/i.test(o.id))));
+        const wanted = model.toLowerCase();
+        for (const option of selects) {
+            const values = flatten(option);
+            const match = values.find((v) => v.value === model) ??
+                values.find((v) => v.name.toLowerCase() === wanted) ??
+                values.find((v) => v.value.toLowerCase().includes(wanted) || v.name.toLowerCase().includes(wanted));
+            if (match) {
+                if (option.currentValue !== match.value) {
+                    await this.connection.setSessionConfigOption({
+                        sessionId: this.sessionId,
+                        configId: option.id,
+                        value: match.value,
+                    });
+                }
+                this.request.trace({ type: "model_selected", configId: option.id, value: match.value });
+                return;
+            }
+        }
+        const available = selects.flatMap((o) => flatten(o).map((v) => v.value));
+        throw new Error(available.length
+            ? `model "${model}" not available for this agent; available: ${available.join(", ")}`
+            : `model "${model}" requested but this agent exposes no model selection (drop the model option); check \`newton models ${this.request.spec.provider ?? ""}\``);
+    }
+    handleUpdate(params) {
+        this.request.trace({ type: "update", update: params.update });
+        const update = params.update;
+        switch (update.sessionUpdate) {
+            case "agent_message_chunk":
+                if (update.content.type === "text") {
+                    this.text += update.content.text;
+                    this.request.onActivity?.("message", update.content.text);
+                }
+                break;
+            case "agent_thought_chunk":
+                if (update.content.type === "text") {
+                    this.request.onActivity?.("thought", update.content.text);
+                }
+                break;
+            case "tool_call":
+                this.toolCalls += 1;
+                this.request.onActivity?.("tool", update.title ?? update.kind ?? "tool");
+                break;
+            default:
+                break;
+        }
+    }
+}

package/dist/cli.js

@@ -0,0 +1,220 @@
+#!/usr/bin/env node
+import { accessSync, constants } from "node:fs";
+import { AcpAgentSession } from "./acp.js";
+import { compileWorkflow, loadWorkflow, runWorkflow } from "./executor.js";
+import { HumanReporter, JsonReporter } from "./progress.js";
+import { describeProviders } from "./providers.js";
+import { VERSION } from "./version.js";
+const USAGE = `newton — deterministic multi-agent workflows over ACP
+
+Usage:
+  newton run <workflow.js> [options]   Run a workflow in the current directory
+  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
+
+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
+  --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)
+  --timeout <seconds>  Per-agent timeout (default 1200)
+  --concurrency <n>    Concurrent agents (default min(16, cores-2))
+
+Workflows are plain JavaScript: \`export const meta = { name, description }\`
+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"]).
+
+Runs are recorded under .newton/runs/<runId>/ — journal.jsonl plus a full
+per-agent ACP trace.`;
+function parseArgs(argv) {
+    const positional = [];
+    const flags = {};
+    for (let i = 0; i < argv.length; i++) {
+        const token = argv[i];
+        if (!token.startsWith("--")) {
+            positional.push(token);
+            continue;
+        }
+        const name = token.slice(2);
+        const next = argv[i + 1];
+        if (next !== undefined && !next.startsWith("--")) {
+            flags[name] = next;
+            i++;
+        }
+        else {
+            flags[name] = true;
+        }
+    }
+    return { positional, flags };
+}
+function fail(message) {
+    process.stderr.write(`error: ${message}\n`);
+    process.exit(2);
+}
+function intFlag(flags, name) {
+    const raw = flags[name];
+    if (raw === undefined)
+        return undefined;
+    const value = Number(raw);
+    if (!Number.isInteger(value) || value <= 0)
+        fail(`--${name} requires a positive integer`);
+    return value;
+}
+async function commandRun(positional, flags) {
+    const file = positional[0];
+    if (!file)
+        fail("newton run requires a workflow file");
+    let args;
+    if (typeof flags.args === "string") {
+        try {
+            args = JSON.parse(flags.args);
+        }
+        catch {
+            args = flags.args; // plain-string args are fine; don't force JSON quoting
+        }
+    }
+    const json = flags.json === true;
+    const reporter = json ? new JsonReporter() : new HumanReporter();
+    const timeoutSeconds = intFlag(flags, "timeout");
+    const result = await runWorkflow({
+        file,
+        args,
+        cwd: typeof flags.cwd === "string" ? flags.cwd : process.cwd(),
+        resumeRunId: typeof flags.resume === "string" ? flags.resume : undefined,
+        budgetTokens: intFlag(flags, "budget"),
+        maxAgents: intFlag(flags, "max-agents"),
+        agentTimeoutMs: timeoutSeconds ? timeoutSeconds * 1000 : undefined,
+        concurrency: intFlag(flags, "concurrency"),
+        reporter,
+    });
+    reporter.done(result);
+    if (!json) {
+        process.stdout.write(`${JSON.stringify(result, null, 2)}\n`);
+    }
+    process.exit(result.status === "ok" ? 0 : 1);
+}
+function commandValidate(positional) {
+    const file = positional[0];
+    if (!file)
+        fail("newton validate requires a workflow file");
+    const workflow = loadWorkflow(file);
+    compileWorkflow(workflow);
+    process.stdout.write(`${JSON.stringify({ ok: true, name: workflow.meta.name, description: workflow.meta.description, phases: workflow.meta.phases ?? [] }, null, 2)}\n`);
+}
+function commandDoctor(flags) {
+    const providers = describeProviders();
+    let workspaceWritable = true;
+    try {
+        accessSync(process.cwd(), constants.W_OK);
+    }
+    catch {
+        workspaceWritable = false;
+    }
+    if (flags.json === true) {
+        const report = { newton: VERSION, node: process.version, workspace: process.cwd(), workspaceWritable, providers };
+        process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+        return;
+    }
+    process.stdout.write(`newton ${VERSION} · node ${process.version}\n`);
+    process.stdout.write(`workspace: ${process.cwd()}${workspaceWritable ? "" : " (NOT writable)"}\n\n`);
+    const rank = { ok: 0, unknown: 1, none: 2 };
+    const mark = { ok: "✔", unknown: "?", none: "✖" };
+    const width = Math.max(...providers.map((p) => p.provider.length));
+    for (const p of [...providers].sort((a, b) => rank[a.auth.state] - rank[b.auth.state])) {
+        const aliases = p.aliases.length ? ` (aka ${p.aliases.join(", ")})` : "";
+        process.stdout.write(`${mark[p.auth.state]} ${p.provider.padEnd(width)}  ${p.auth.detail}${aliases}\n` +
+            `  ${" ".repeat(width)}  via ${p.resolvesVia}\n`);
+    }
+    process.stdout.write(`\n✔ signed in · ? undetectable · ✖ needs setup\n`);
+}
+async function commandModels(positional, flags) {
+    const provider = positional[0];
+    if (!provider)
+        fail("newton models requires a provider (see `newton agents`)");
+    const session = new AcpAgentSession({
+        spec: { provider },
+        prompt: "",
+        cwd: process.cwd(),
+        timeoutMs: 60_000,
+        trace: () => { },
+    });
+    try {
+        const info = await session.inspect();
+        if (flags.json === true) {
+            process.stdout.write(`${JSON.stringify(info, null, 2)}\n`);
+            return;
+        }
+        const selects = info.configOptions.filter((o) => o.type === "select");
+        if (selects.length === 0 && !info.modes) {
+            process.stdout.write(`${provider}: exposes no session options; it uses its own configured model\n`);
+            return;
+        }
+        for (const option of selects) {
+            process.stdout.write(`${option.name} [${option.id}]${option.category ? ` (${option.category})` : ""}\n`);
+            const values = option.options.flatMap((v) => ("group" in v ? v.options : [v]));
+            for (const value of values) {
+                const current = value.value === option.currentValue ? " (current)" : "";
+                process.stdout.write(`  ${value.value}${value.name !== value.value ? ` — ${value.name}` : ""}${current}\n`);
+            }
+        }
+        if (info.modes) {
+            process.stdout.write(`Modes [current: ${info.modes.currentModeId}]\n`);
+            for (const mode of info.modes.availableModes) {
+                process.stdout.write(`  ${mode.id}${mode.name !== mode.id ? ` — ${mode.name}` : ""}\n`);
+            }
+        }
+    }
+    catch (error) {
+        fail(error.message);
+    }
+    finally {
+        session.close();
+    }
+}
+async function main() {
+    const [command, ...rest] = process.argv.slice(2);
+    const { positional, flags } = parseArgs(rest);
+    switch (command) {
+        case "run":
+            await commandRun(positional, flags);
+            break;
+        case "validate":
+            try {
+                commandValidate(positional);
+            }
+            catch (error) {
+                fail(error.message);
+            }
+            break;
+        case "models":
+            await commandModels(positional, flags);
+            break;
+        case "agents":
+        case "doctor":
+            commandDoctor(flags);
+            break;
+        case "version":
+        case "--version":
+        case "-v":
+            process.stdout.write(`${VERSION}\n`);
+            break;
+        case undefined:
+        case "help":
+        case "--help":
+        case "-h":
+            process.stdout.write(`${USAGE}\n`);
+            break;
+        default:
+            fail(`unknown command "${command}"\n\n${USAGE}`);
+    }
+}
+main().catch((error) => {
+    process.stderr.write(`error: ${error instanceof Error ? (error.stack ?? error.message) : String(error)}\n`);
+    process.exit(1);
+});