outsrc 0.2.0

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Proticom
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,188 @@
+# outsrc
+
+Good work takes a team. outsrc lets a Grok Bot hand coding tasks to Claude Code, Codex or Grok Build on your computer. Each task runs in its own git worktree, and the result comes back to an inbox.
+
+Site: https://outsrc.ing
+
+## Install
+
+Add the Outsrc bot from Bot Exchange. The listing is not live yet. Once installed, the bot walks you through setup on your computer.
+
+This repository is the open-source harness the bot runs. You only need it to build your own bot, contribute, or run outsrc by hand.
+
+## Security
+
+outsrc is not a sandbox. Agents run as you, on your computer, in the repositories you allow. Review their work before you ship it. Details: https://outsrc.ing/security.md
+
+To report a vulnerability, see [SECURITY.md](SECURITY.md).
+
+### What outsrc adds over calling the CLIs directly
+
+- **Only the repositories you chose**, each job in its own git worktree and branch. Your checkout stays untouched.
+- **No inherited secrets.** Jobs get only `PATH`, `HOME`, `USER`, `LANG`, `TMPDIR` and `TERM` from your environment.
+- **Read-only reviews.** Reviews never get the flags that skip approvals, and plugin reviews never get `--write`.
+- **Reviewing a branch does not run the branch.** Hooks and MCP servers in a branch's `.claude/`, `.codex/`, `.grok/`, `.cursor/` or `.mcp.json` run commands as soon as a CLI opens the folder. For reviews, outsrc keeps those files out of the worktree (git still shows them in the diff), Claude loads only your own settings and no MCP servers, and repository `setup` commands do not run. Tested with a branch that tried each route: called directly, Claude ran its hooks and MCP server, and Codex ran its MCP server when the repository was trusted. Through outsrc, none ran.
+- **Prompts stay text.** outsrc passes `--` before the prompt, so a message starting with `--` cannot set an option.
+- **No chains.** Jobs run with `OUTSRC_JOB=1`, and an outsrc server started inside a job refuses `send`.
+- **Separate callers.** Each caller sees only its own threads.
+- **Private state.** `~/.outsrc` is created readable by you only.
+- **Bounded jobs.** By default at most 4 jobs at once and 2 hours per run; the owner can change both (see Settings). `stop` signals a process only if it is still the job outsrc started.
+- **Pinned vendor engines**, checked daily for upstream changes.
+
+## Running the harness yourself
+
+It needs Node 22.12 or later (22.x, 24.x or 26+), git, and at least one of the `claude`, `codex` or `grok` CLIs, logged in.
+
+```bash
+npm install -g outsrc
+outsrc init
+```
+
+Install it globally rather than running it through `npx`: agents launch the installed copy, and the npx cache moves. Upgrade with `npm install -g outsrc@latest`.
+
+`outsrc init` is safe to rerun and keeps existing settings. It:
+
+1. Checks Node and git, finds the installed CLIs and checks each is logged in.
+2. Downloads the pinned Codex and Grok plugin engines into `~/.outsrc/engines/`. Claude Code is not needed for this. `--no-plugins` calls the CLIs directly instead.
+3. Asks which repositories agents may work in. Repositories are added only by running `outsrc` on this computer; MCP callers cannot add them.
+4. Asks for the limits: how many jobs may work at once, and how long a run may take (see Settings).
+5. Writes `~/.outsrc/config.toml` and reports on each target.
+6. Offers to register outsrc as an MCP server with each installed CLI.
+
+For agents and scripts, `outsrc init --json --repo <path> [--repo <path>] [--local claude,codex,grok] [--max-jobs <n|unlimited>] [--max-run-minutes <n|unlimited>]` prints one JSON event per line and exits with code 3 when a person has to act, such as logging in to a CLI. Rerun it after that step. Without `--local`, nothing is registered. A `settings` event lists the limits, repositories and targets so the agent can review them with the owner.
+
+`outsrc doctor` rechecks the configuration. `OUTSRC_HOME` moves the state directory away from `~/.outsrc`, which outsrc keeps readable by you only.
+
+## Settings
+
+`outsrc config` lists every setting with its current value, its default and what it means. `outsrc config set <key> <value>` changes one, and `outsrc config unset <key>` restores the default or removes an entry. Each change is checked against the whole configuration before the file is written, the previous file is kept as `config.toml.bak`, and running MCP servers pick it up on their next call. MCP callers can read settings with the `settings` tool but cannot change them: only someone who can run `outsrc` on this computer can.
+
+| Key | Values | Default |
+| --- | --- | --- |
+| `limits.max_jobs` | a positive whole number, or `unlimited` | 4 |
+| `limits.max_run_minutes` | a positive whole number, or `unlimited` | 120 |
+| `repos.<alias>` | `{"path": "/absolute/path"}` to add; `unset` to remove | |
+| `repos.<alias>.setup`, `.auto_commit`, `.retention_days` | see Repository options | none, `false`, none |
+| `targets.<name>` | a JSON object, such as `{"adapter": "claude", "command": "claude"}` | |
+| `targets.<name>.permissions` | `auto` or `ask` | `auto` |
+| `targets.<name>.effort.default`, `.effort.allowed` | a value, and a comma list | |
+| `targets.<name>.models.default`, `.models.allowed` | a value, and a comma list | the CLI's choice |
+| `targets.<name>.description`, `.cost_note`, `.command`, `.args`, `.adapter` | see Targets | |
+
+Values are read as JSON when they parse (`true`, `14`, `[["npm","ci"]]`) and as text otherwise. Aliases may contain dots: `outsrc config set repos.outsrc.ing.auto_commit true` works.
+
+Unlimited is allowed, and `outsrc config` prints what it risks. With no job cap, a looping or confused bot can start many agents at once, slowing the computer and running up usage and rate limits. With no time limit, a stuck agent (waiting for input, a test runner in watch mode, a loop) runs until someone stops it.
+
+## Callers
+
+Each client connects as a named caller: `outsrc-mcp --caller grok`, or `--caller <id>` on CLI commands. A caller sees and controls only its own threads. Another caller's thread answers exactly like one that does not exist.
+
+Every job runs with `OUTSRC_JOB=1` in its environment. An outsrc server started inside a job refuses `send`, so a delegated agent cannot hand work on to another agent. Only the caller that started a job can send more work.
+
+## How a conversation works
+
+1. Call `list_repos` and `list_targets`.
+2. Call `send` with `repo`, `target` and `message`. Optional: `model`, `effort`, `kind` (`task`, `review` or `adversarial_review`), `ref` (the branch, tag or commit to start from) and `base` (what a review compares against).
+3. Poll `inbox` at its `retry_after_seconds`. The delay grows from 30 seconds to 5 minutes as a run ages, and working runs include recent log lines.
+4. If the status is `needs_input`, the agent stopped with a question. Answer with `send({thread_id, message})`. outsrc resumes the same vendor session in the same worktree. Finished threads accept follow-ups the same way.
+
+Pass a stable `request_id` when retrying a `send`. The same request returns the original thread and run; the same ID with different content is an error.
+
+## Tools
+
+The MCP tools and the CLI commands return the same JSON.
+
+| Tool | What it does |
+| --- | --- |
+| `list_repos` | Repositories agents may work in |
+| `list_targets` | Available agents, their models and effort levels, and the owner's cost notes |
+| `send` | Start a task, or continue a finished or waiting thread |
+| `inbox` | A thread's status, question, or final answer with findings |
+| `threads` | This caller's threads and their status |
+| `settings` | Every setting with its value, default and meaning (read-only) |
+| `history` | Every run in a thread, with its message and result |
+| `log` | A slice of a run's log |
+| `diff` | Changes since the thread started, committed or not (256 KiB by default) |
+| `stop` | Cancel a running thread |
+| `discard` | Delete a finished thread's worktree and branch, keeping its results |
+
+CLI only: `outsrc config set` and `unset` change settings, `outsrc prune` deletes finished worktrees past their retention period, `outsrc migrate` imports threads from earlier versions, and `outsrc plugins` checks the plugin engines.
+
+## Repository options
+
+```toml
+[[repos]]
+alias = "example"
+path = "/absolute/path/example"
+setup = [["npm", "ci"]]   # runs once in a new task worktree, before the first run
+auto_commit = true        # commit a successful task's changes
+retention_days = 30       # let prune remove finished worktrees after 30 days
+```
+
+All three options are optional. A failed setup fails the run. outsrc does not copy `.env` files or other untracked files into worktrees. Running and waiting threads are never pruned, and saved results outlive their worktrees.
+
+## Targets
+
+A target is one agent outsrc can start. `list_targets` shows what is configured, and `config.example.toml` has a starting point.
+
+| Adapter | Runs |
+| --- | --- |
+| `claude` | The Claude Code CLI |
+| `codex`, `grok` | The Codex or Grok Build CLI directly |
+| `codex-plugin`, `grok-plugin` | The vendors' plugin engines (below) |
+| `custom` | Any command that prints outsrc's JSON result |
+
+`permissions = "auto"` lets a task edit files and run commands without approval: Claude `--permission-mode bypassPermissions`, Codex `--approve-for-me`, Grok `--always-approve`, or `--write` for a plugin. `permissions = "ask"` leaves those flags off. Reviews always run as `ask`, whatever the target says, and without the branch's agent settings (see Security).
+
+A custom target prints one JSON object with `kind` (`completed`, `needs_input` or `failed`), `message`, `sessionId` and `findings`. Its `args` may use `{session_id}` (required to resume), `{worktree}`, `{model}`, `{effort}` and `{schema}`. outsrc appends the prompt as the last argument.
+
+Each finding has `priority` (`P0` to `P3`), `title`, `body`, `path` (or null) and `line` (or null).
+
+## Vendor plugin engines
+
+The `codex-plugin` and `grok-plugin` adapters drive the vendors' own Claude Code plugins, [openai/codex-plugin-cc](https://github.com/openai/codex-plugin-cc) and [xai-org/grok-build-plugin-cc](https://github.com/xai-org/grok-build-plugin-cc), both Apache-2.0. The plugin launches the CLI and supplies the review prompts, output schema and, for Codex, the built-in reviewer. outsrc keeps the mailbox, worktrees, repository list and filtered environment. It runs the engine scripts directly; no Claude Code session is involved.
+
+`engines.lock.json` pins each plugin to one git commit that passed the live smoke test, the way a lock file pins dependencies. `init` fetches exactly that commit. An upstream change reaches you only when an outsrc release moves the pin. If the pinned engine is missing, outsrc falls back to a Claude Code install of the same plugin, which is not pinned. A target's `command` can point at any copy of `codex-companion.mjs` or `grok-bridge.mjs`.
+
+| Request | Plugin command |
+| --- | --- |
+| `task` | Codex `task`, Grok `run`, with `--write` when permissions are `auto` |
+| follow-up | the same command with `--resume-last` |
+| `review` with `base` | the plugin's diff review against `base` |
+| `adversarial_review` with `base` | Codex `adversarial-review` or Grok `critique`, with the message as the focus |
+| review without `base` | a read-only task with review instructions |
+| `stop` | the plugin's `cancel` or `stop`, then the job's process group |
+
+Each thread has its own plugin data directory, and after every Codex run outsrc stops the app-server that the plugin leaves running.
+
+Grok and Docker Desktop on macOS: Grok's read-only sandbox refuses to start when `/var/run/docker.sock` is a symlink, which Docker Desktop creates by default. In Docker Desktop, turn off Settings → Advanced → "Allow the default Docker socket to be used", then run `sudo rm /var/run/docker.sock` in a terminal. The `docker` CLI keeps working. This affects Grok reviews, not Grok write tasks.
+
+### When a plugin changes
+
+The plugin scripts are the vendors' internal CLIs, not a documented API. outsrc checks them three ways:
+
+- `outsrc plugins` checks the installed engines without running a model: the subcommands and flags outsrc uses, the environment names, the Codex shutdown hook, and a JSON status call. Each engine is `ok`, `unverified` (compatible, but not the pinned version) or `broken`.
+- `doctor` and `list_targets` include the same result, so a caller sees a warning too.
+- `.github/workflows/plugin-drift.yml` runs the check daily against both upstream repositories and opens an issue when either drifts.
+
+To move a pin, run `outsrc engines pin <codex-plugin|grok-plugin> <commit|branch|tag>`. It updates `engines.lock.json` only if the contract check passes. Then run `npm run smoke:plugins` and keep the change only if that passes too.
+
+## Limits
+
+outsrc checks that thread and run paths stay inside its state directory, and it signals a process only if it is still the job outsrc started. By default at most 4 threads work at once and a run is stopped after 2 hours (both settings). A run log stops growing at 1 MiB, and `log` returns at most 8 KiB.
+
+None of this confines a task. A worktree is not a sandbox, and the filtered environment is not a credential boundary. The prompt asks agents not to push or open pull requests, but nothing enforces that.
+
+A task trusts the code it starts from: a task on someone else's branch (`ref`) runs that branch's code and settings with the task's permissions, so review such a branch first. A reviewed branch's `CLAUDE.md` or `AGENTS.md` still reaches the reviewer and can try to steer its answer, though the reviewer cannot edit or run anything. Grok skips a project's settings only while the folder is untrusted, so do not mark your home folder or `~/.outsrc` as trusted in Grok.
+
+## Development
+
+From a checkout: `npm install`, `npm run build`, then `npm link` to put the checkout's `outsrc` on your PATH.
+
+`npm run verify` builds, type-checks, runs the tests, then repeats the MCP workflow against the built server. `npm test` runs the tests alone. Tests use real git worktrees and child processes with a fixture agent.
+
+Two live checks use your own provider accounts and can cost money: `npm run smoke:native` runs a question and a follow-up through each CLI target, and `npm run smoke:plugins` does the same plus an adversarial review through each plugin engine.
+
+## License
+
+MIT. See `LICENSE`.

package/config.example.toml

@@ -0,0 +1,46 @@
+# Copy to ~/.outsrc/config.toml (or let `outsrc init` write one).
+# Paths must be absolute git checkouts on THIS machine. Agents cannot add repos via tools.
+
+[[repos]]
+alias = "example"
+path = "/absolute/path/to/your/repo"
+# Optional setup commands run once in a new worktree, before the first run.
+# setup = [["npm", "ci"]]
+# auto_commit = true
+# retention_days = 30
+
+# Drives openai/codex-plugin-cc, resolved from the pin in engines.lock.json (or Claude Code's copy).
+# Set command to codex-companion.mjs in a clone of that repository when neither is present.
+# adapter = "codex" calls the Codex CLI directly instead.
+[targets.codex]
+adapter = "codex-plugin"
+permissions = "auto"
+description = "Coding tasks and code review through the Codex plugin, including its built-in and adversarial reviewers."
+cost_note = "Uses this machine's Codex account; pricing depends on that account and selected model."
+
+[targets.codex.models]
+default = "gpt-5.6"
+allowed = ["gpt-5.6"]
+
+[targets.codex.effort]
+default = "medium"
+allowed = ["none", "minimal", "low", "medium", "high", "xhigh"]
+
+[targets.claude]
+adapter = "claude"
+permissions = "auto"
+command = "claude"
+args = []
+description = "Coding tasks and review through the locally installed Claude Code CLI."
+cost_note = "Uses this machine's Claude account. Configure model choices for your plan."
+
+[targets.claude.effort]
+default = "medium"
+allowed = ["low", "medium", "high", "xhigh", "max"]
+
+# Drives xai-org/grok-build-plugin-cc. adapter = "grok" calls the Grok Build CLI directly instead.
+[targets.grok]
+adapter = "grok-plugin"
+permissions = "auto"
+description = "Coding tasks and critique through the Grok Build plugin."
+cost_note = "Uses this machine's Grok account. Configure model choices for your plan."

package/dist/adapters.d.ts

@@ -0,0 +1,110 @@
+import { z } from "zod";
+import { type PluginAdapter } from "./plugins.js";
+import type { TaskKind } from "./types.js";
+export type Adapter = "claude" | "codex" | "grok" | "custom" | PluginAdapter;
+export type AdapterTarget = {
+    adapter: Adapter;
+    command: string;
+    args: string[];
+};
+export type InvocationOptions = {
+    target: AdapterTarget;
+    worktree: string;
+    prompt: string;
+    model: string | null;
+    effort: string | null;
+    sessionId: string | null;
+    schemaPath: string;
+    permissions: "auto" | "ask";
+    kind: TaskKind;
+    base: string | null;
+    dataDir: string;
+    threadId: string;
+};
+export declare const FindingSchema: z.ZodObject<{
+    priority: z.ZodEnum<{
+        P0: "P0";
+        P1: "P1";
+        P2: "P2";
+        P3: "P3";
+    }>;
+    title: z.ZodString;
+    body: z.ZodString;
+    path: z.ZodNullable<z.ZodString>;
+    line: z.ZodNullable<z.ZodNumber>;
+}, z.core.$strip>;
+export type Finding = z.infer<typeof FindingSchema>;
+declare const ResultSchema: z.ZodObject<{
+    kind: z.ZodEnum<{
+        completed: "completed";
+        failed: "failed";
+        needs_input: "needs_input";
+    }>;
+    message: z.ZodString;
+    findings: z.ZodArray<z.ZodObject<{
+        priority: z.ZodEnum<{
+            P0: "P0";
+            P1: "P1";
+            P2: "P2";
+            P3: "P3";
+        }>;
+        title: z.ZodString;
+        body: z.ZodString;
+        path: z.ZodNullable<z.ZodString>;
+        line: z.ZodNullable<z.ZodNumber>;
+    }, z.core.$strip>>;
+}, z.core.$strip>;
+export type AgentOutput = z.infer<typeof ResultSchema> & {
+    sessionId: string | null;
+};
+export declare const AGENT_OUTPUT_SCHEMA: {
+    type: string;
+    properties: {
+        kind: {
+            type: string;
+            enum: string[];
+        };
+        message: {
+            type: string;
+        };
+        findings: {
+            type: string;
+            items: {
+                type: string;
+                properties: {
+                    priority: {
+                        type: string;
+                        enum: string[];
+                    };
+                    title: {
+                        type: string;
+                    };
+                    body: {
+                        type: string;
+                    };
+                    path: {
+                        type: string[];
+                    };
+                    line: {
+                        type: string[];
+                    };
+                };
+                required: string[];
+                additionalProperties: boolean;
+            };
+        };
+    };
+    required: string[];
+    additionalProperties: boolean;
+};
+export declare function buildInvocation(options: InvocationOptions): {
+    command: string;
+    args: string[];
+    env?: Record<string, string>;
+};
+export declare function parseAgentOutput(input: {
+    adapter: Adapter;
+    stdout: string;
+    exitCode: number | null;
+}): AgentOutput;
+export {};

package/dist/adapters.js

@@ -0,0 +1,246 @@
+import { z } from "zod";
+import { permissionFlags } from "./permissions.js";
+import { isPluginAdapter, parsePluginOutput, pluginInvocation } from "./plugins.js";
+export const FindingSchema = z.object({
+    priority: z.enum(["P0", "P1", "P2", "P3"]),
+    title: z.string().min(1),
+    body: z.string().min(1),
+    path: z.string().nullable(),
+    line: z.number().int().positive().nullable(),
+});
+const ResultSchema = z.object({
+    kind: z.enum(["completed", "needs_input", "failed"]),
+    message: z.string().trim().min(1),
+    findings: z.array(FindingSchema),
+});
+export const AGENT_OUTPUT_SCHEMA = {
+    type: "object",
+    properties: {
+        kind: { type: "string", enum: ["completed", "needs_input"] },
+        message: { type: "string" },
+        findings: {
+            type: "array",
+            items: {
+                type: "object",
+                properties: {
+                    priority: { type: "string", enum: ["P0", "P1", "P2", "P3"] },
+                    title: { type: "string" },
+                    body: { type: "string" },
+                    path: { type: ["string", "null"] },
+                    line: { type: ["integer", "null"] },
+                },
+                required: ["priority", "title", "body", "path", "line"],
+                additionalProperties: false,
+            },
+        },
+    },
+    required: ["kind", "message", "findings"],
+    additionalProperties: false,
+};
+function substitute(args, options) {
+    const variables = {
+        worktree: options.worktree,
+        model: options.model ?? "",
+        effort: options.effort ?? "",
+        session_id: options.sessionId ?? "",
+        schema: options.schemaPath,
+    };
+    return args.map((arg) => {
+        let value = arg;
+        for (const [name, replacement] of Object.entries(variables)) {
+            value = value.replaceAll(`{${name}}`, replacement);
+        }
+        return value;
+    });
+}
+function nativeArgs(adapter, args) {
+    const values = new Set([
+        "--model", "-m", "--effort", "--reasoning-effort", "--output-format",
+        "--json-schema", "--output-schema", "--resume", "-r",
+    ]);
+    const result = [];
+    for (let index = 0; index < args.length; index++) {
+        const arg = args[index];
+        if (arg === undefined)
+            continue;
+        if (values.has(arg)) {
+            index++;
+            continue;
+        }
+        if ([...values].some((flag) => arg.startsWith(`${flag}=`)))
+            continue;
+        if (adapter === "codex") {
+            if (index === 0 && arg === "exec")
+                continue;
+            if (arg === "--json")
+                continue;
+            if ((arg === "-c" || arg === "--config") &&
+                /^(model_reasoning_effort|model_service_tier)=/.test(args[index + 1] ?? "")) {
+                index++;
+                continue;
+            }
+        }
+        else if (arg === "-p" || arg === "--print" || arg === "--single") {
+            if (adapter === "grok" && args[index + 1] && !args[index + 1]?.startsWith("-"))
+                index++;
+            continue;
+        }
+        result.push(arg);
+    }
+    return result;
+}
+export function buildInvocation(options) {
+    const { target, model, effort, sessionId, prompt } = options;
+    // Review and adversarial_review are always read-only, whatever the target's permissions setting.
+    const effectivePermissions = options.kind === "task" ? options.permissions : "ask";
+    if (isPluginAdapter(target.adapter)) {
+        return pluginInvocation(target.adapter, {
+            script: target.command, worktree: options.worktree, prompt, model, effort, sessionId,
+            kind: options.kind, base: options.base, permissions: effectivePermissions,
+            dataDir: options.dataDir, threadId: options.threadId,
+        });
+    }
+    const adapter = target.adapter;
+    const configured = substitute(target.args, options);
+    if (adapter === "custom") {
+        if (sessionId && !target.args.some((arg) => arg.includes("{session_id}"))) {
+            throw new Error("custom adapter cannot resume without a {session_id} argument");
+        }
+        return {
+            command: target.command,
+            args: [...configured, ...permissionFlags(target.command, configured, effectivePermissions), prompt],
+        };
+    }
+    const extra = nativeArgs(adapter, configured);
+    const permissions = permissionFlags(target.command, extra, effectivePermissions);
+    const modelArgs = model === null ? [] : ["--model", model];
+    switch (adapter) {
+        case "claude":
+            return {
+                command: target.command,
+                args: [
+                    ...extra, "-p", "--output-format", "json", "--json-schema", JSON.stringify(AGENT_OUTPUT_SCHEMA),
+                    ...modelArgs, ...(effort === null ? [] : ["--effort", effort]),
+                    ...(sessionId === null ? [] : ["--resume", sessionId]), ...permissions,
+                    // A review reads someone else's branch: load only the user's own settings, and no MCP servers.
+                    ...(options.kind === "task" ? [] : ["--setting-sources", "user", "--strict-mcp-config"]), "--", prompt,
+                ],
+            };
+        case "codex": {
+            const configuration = [
+                "-c", "model_service_tier=fast",
+                ...(effort === null ? [] : ["-c", `model_reasoning_effort=${effort}`]),
+            ];
+            const output = ["--json", "--output-schema", options.schemaPath, ...modelArgs];
+            return {
+                command: target.command,
+                args: [
+                    "exec", ...extra, ...configuration, ...permissions,
+                    ...(sessionId === null ? output : ["resume", ...output, sessionId]),
+                    "--", prompt,
+                ],
+            };
+        }
+        case "grok":
+            return {
+                command: target.command,
+                args: [
+                    ...extra, "--output-format", "json", "--json-schema", JSON.stringify(AGENT_OUTPUT_SCHEMA),
+                    ...modelArgs, ...(effort === null ? [] : ["--reasoning-effort", effort]),
+                    ...(sessionId === null ? [] : ["--resume", sessionId]), ...permissions,
+                    ...(prompt.startsWith("-") ? [`--single=${prompt}`] : ["-p", prompt]),
+                ],
+            };
+        default: {
+            const exhaustive = adapter;
+            throw new Error(`unknown adapter: ${exhaustive}`);
+        }
+    }
+}
+const EnvelopeSchema = z.object({
+    type: z.string().optional(),
+    session_id: z.string().min(1).optional(),
+    sessionId: z.string().min(1).optional(),
+    structured_output: z.unknown().optional(),
+    structuredOutput: z.unknown().optional(),
+    result: z.string().optional(),
+    text: z.string().optional(),
+    is_error: z.boolean().optional(),
+    errors: z.array(z.string()).optional(),
+    message: z.unknown().optional(),
+});
+const CodexEventSchema = z.object({
+    type: z.string(),
+    thread_id: z.string().min(1).optional(),
+    message: z.string().optional(),
+    error: z.object({ message: z.string() }).optional(),
+    item: z.object({ type: z.string(), text: z.string().optional() }).optional(),
+});
+function failed(message, sessionId = null) {
+    return { kind: "failed", message, sessionId, findings: [] };
+}
+export function parseAgentOutput(input) {
+    if (isPluginAdapter(input.adapter))
+        return parsePluginOutput(input.stdout, input.exitCode);
+    let sessionId = null;
+    try {
+        let value;
+        if (input.adapter === "codex") {
+            let finalText;
+            let complete = false;
+            for (const line of input.stdout.trim().split("\n").filter((line) => line.trim())) {
+                const event = CodexEventSchema.parse(JSON.parse(line));
+                if (event.type === "thread.started")
+                    sessionId = event.thread_id ?? sessionId;
+                if (event.type === "turn.failed" || event.type === "error") {
+                    return failed(event.error?.message ?? event.message ?? "Codex turn failed", sessionId);
+                }
+                if (event.type === "item.completed" && event.item?.type === "agent_message") {
+                    finalText = event.item.text;
+                }
+                if (event.type === "turn.completed")
+                    complete = true;
+            }
+            if (!complete || !finalText) {
+                const message = input.exitCode === 0 ? "Codex did not return a completed turn" :
+                    `Agent process exited with ${input.exitCode ?? "a signal"} before completing Codex turn`;
+                return failed(message, sessionId);
+            }
+            value = JSON.parse(finalText);
+        }
+        else if (input.adapter === "custom") {
+            const custom = ResultSchema.extend({ sessionId: z.string().min(1).nullable() }).parse(JSON.parse(input.stdout));
+            sessionId = custom.sessionId;
+            value = custom;
+        }
+        else {
+            const raw = JSON.parse(input.stdout);
+            const messages = z.array(EnvelopeSchema).safeParse(raw);
+            const envelope = messages.success ? messages.data.findLast((message) => message.type === "result") : EnvelopeSchema.parse(raw);
+            if (!envelope)
+                return failed("Agent output did not include a final result", sessionId);
+            sessionId = envelope.session_id ?? envelope.sessionId ?? null;
+            if (envelope.is_error || envelope.type === "error") {
+                const message = typeof envelope.message === "string" ? envelope.message : "Agent reported an error";
+                return failed(envelope.errors?.join("\n") || envelope.result || message, sessionId);
+            }
+            value = envelope.structured_output ?? envelope.structuredOutput;
+            if (value === undefined && input.adapter === "grok" && envelope.text) {
+                value = JSON.parse(envelope.text);
+            }
+        }
+        if (input.exitCode !== 0)
+            return failed(`Agent process exited with ${input.exitCode ?? "a signal"}`, sessionId);
+        const result = ResultSchema.parse(value);
+        if (result.kind === "needs_input" && sessionId === null) {
+            return failed("Agent requested input without a resumable session ID", sessionId);
+        }
+        return { ...result, sessionId };
+    }
+    catch {
+        if (input.exitCode !== 0) {
+            return failed(`Agent process exited with ${input.exitCode ?? "a signal"} without valid ${input.adapter} output`, sessionId);
+        }
+        return failed(`Invalid ${input.adapter} agent output`, sessionId);
+    }
+}

package/dist/cli.d.ts

@@ -0,0 +1,2 @@
+#!/usr/bin/env node
+export {};