outsrc 0.2.0

package/dist/types.d.ts

@@ -0,0 +1,181 @@
+import type { Limits } from "./limits.js";
+import type { AdapterTarget, Finding } from "./adapters.js";
+export type ThreadId = string & {
+    readonly __brand: "ThreadId";
+};
+export type RunId = string & {
+    readonly __brand: "RunId";
+};
+export type Alias = string & {
+    readonly __brand: "Alias";
+};
+export type TargetName = string & {
+    readonly __brand: "TargetName";
+};
+export declare const MINTED_THREAD_ID: RegExp;
+export declare const STORAGE_ID: RegExp;
+export declare const CALLER: RegExp;
+export declare const DEFAULT_CALLER = "local";
+export declare function parseCaller(raw: string): string;
+export declare function parseThreadId(raw: string): ThreadId;
+export declare function parseRunId(raw: string): RunId;
+export declare function parseAlias(raw: string): Alias;
+export declare function parseTargetName(raw: string): TargetName;
+export type PermissionMode = "auto" | "ask";
+export type TaskKind = "task" | "review" | "adversarial_review";
+export type RepoConfig = {
+    alias: string;
+    path: string;
+    setup?: string[][];
+    autoCommit?: boolean;
+    retentionDays?: number;
+};
+export type TargetConfig = {
+    adapter?: AdapterTarget["adapter"];
+    command: string;
+    args: string[];
+    permissions?: PermissionMode;
+    models?: {
+        default: string;
+        allowed: string[];
+    };
+    effort?: {
+        default: string;
+        allowed: string[];
+    };
+    description?: string;
+    costNote?: string;
+};
+export type Config = {
+    repos: RepoConfig[];
+    targets: Record<string, TargetConfig>;
+    limits?: Limits;
+};
+export type ThreadRecord = {
+    version: 2;
+    id: ThreadId;
+    caller: string;
+    repo: Alias;
+    target: TargetName;
+    model: string | null;
+    effort: string | null;
+    taskKind: TaskKind;
+    base: string | null;
+    worktree: string;
+    branch: string;
+    baseCommit: string;
+    createdAt: string;
+    latestRunId: string;
+};
+export type RunRecord = {
+    id: string;
+    threadId: ThreadId;
+    requestId: string | null;
+    message: string;
+    createdAt: string;
+    sessionId: string | null;
+};
+export type RunSpec = {
+    threadId: ThreadId;
+    runId: string;
+    runDir: string;
+    worktree: string;
+    baseCommit: string;
+    target: AdapterTarget;
+    model: string | null;
+    effort: string | null;
+    permissions: PermissionMode;
+    sessionId: string | null;
+    prompt: string;
+    setup: string[][];
+    autoCommit: boolean;
+    kind: TaskKind;
+    base: string | null;
+    deadlineMs?: number | null;
+};
+export type RunResult = {
+    kind: "completed" | "needs_input" | "failed" | "cancelled";
+    message: string;
+    sessionId: string | null;
+    findings: Finding[];
+    exitCode: number | null;
+    finishedAt: string;
+    diffstat: string;
+    commit: string | null;
+};
+export type SendInput = {
+    message: string;
+    repo?: string;
+    target?: string;
+    thread_id?: string;
+    request_id?: string;
+    model?: string;
+    effort?: string;
+    kind?: TaskKind;
+    base?: string;
+    ref?: string;
+};
+export type SendResult = {
+    ok: true;
+    delivered: true;
+    thread_id: ThreadId;
+    run_id: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type ThreadStatus = "working" | "needs_input" | "succeeded" | "failed" | "cancelled";
+export type InboxResult = {
+    ok: true;
+    status: "working";
+    retry_after_seconds: number;
+    run_id: string;
+    progress: string;
+} | {
+    ok: true;
+    status: "needs_input";
+    retry_after_seconds: number;
+    run_id: string;
+    message: string;
+    question_id: string;
+    session_id: string | null;
+} | {
+    ok: true;
+    status: "succeeded" | "failed" | "cancelled";
+    run_id: string;
+    message: string;
+    branch: string;
+    worktree: string;
+    diffstat: {
+        raw: string;
+    };
+    exit_code: number | null;
+    session_id: string | null;
+    findings: Finding[];
+    commit: string | null;
+} | {
+    ok: false;
+    error: string;
+};
+export type LogResult = {
+    ok: true;
+    text: string;
+} | {
+    ok: false;
+    error: string;
+};
+export type StopResult = {
+    ok: true;
+    stopped: true;
+} | {
+    ok: false;
+    error: string;
+};
+export type MailboxContext = {
+    home: string;
+    caller?: string;
+    config: Config;
+    retryAfterSeconds?: number;
+    wrapperCommand?: string[];
+    nodeExecutable?: string;
+};

package/dist/types.js

@@ -0,0 +1,35 @@
+export const MINTED_THREAD_ID = /^[0-9a-f]{16}$/;
+export const STORAGE_ID = /^[a-z0-9][a-z0-9_-]{0,63}$/;
+// Who is connected: each registration of the server names its caller, and a caller sees only its own threads.
+export const CALLER = /^[a-z0-9][a-z0-9-]{0,31}$/;
+export const DEFAULT_CALLER = "local";
+export function parseCaller(raw) {
+    const caller = raw.trim();
+    if (!CALLER.test(caller))
+        throw new Error("caller must match ^[a-z0-9][a-z0-9-]{0,31}$");
+    return caller;
+}
+export function parseThreadId(raw) {
+    const id = raw.trim();
+    if (!MINTED_THREAD_ID.test(id))
+        throw new Error("thread_id must be 16 lowercase hex characters");
+    return id;
+}
+export function parseRunId(raw) {
+    const id = raw.trim();
+    if (!STORAGE_ID.test(id))
+        throw new Error("run_id must be a single storage id");
+    return id;
+}
+export function parseAlias(raw) {
+    const alias = raw.trim();
+    if (!alias)
+        throw new Error("repo is required");
+    return alias;
+}
+export function parseTargetName(raw) {
+    const target = raw.trim();
+    if (!target)
+        throw new Error("target is required");
+    return target;
+}

package/dist/workspace.d.ts

@@ -0,0 +1,18 @@
+export type WorkspaceDiff = {
+    patch: string;
+    stat: string;
+    truncated: boolean;
+};
+export declare function getBaseCommit(repo: string): string;
+export declare function collectWorkspaceDiff(input: {
+    workspace: string;
+    baseCommit: string;
+    maxBytes?: number;
+}): WorkspaceDiff;
+export declare function commitWorkspace(input: {
+    workspace: string;
+    message: string;
+}): {
+    commit: string;
+    changed: boolean;
+};

package/dist/workspace.js

@@ -0,0 +1,66 @@
+import { execFileSync, spawnSync } from "node:child_process";
+import { copyFileSync, existsSync, mkdtempSync, rmSync } from "node:fs";
+import { tmpdir } from "node:os";
+import { join, resolve } from "node:path";
+const DEFAULT_DIFF_BYTES = 256 * 1024;
+function git(args, workspace, env = process.env) {
+    return execFileSync("git", args, {
+        cwd: workspace,
+        env,
+        encoding: "utf8",
+        stdio: ["ignore", "pipe", "pipe"],
+    }).trim();
+}
+export function getBaseCommit(repo) {
+    return git(["rev-parse", "HEAD"], repo);
+}
+function boundedGit(args, workspace, env, limit) {
+    const result = spawnSync("git", args, {
+        cwd: workspace,
+        env,
+        maxBuffer: limit + 1,
+    });
+    let truncated = result.stdout.length > limit || result.error?.message.includes("ENOBUFS") === true;
+    if (!truncated && (result.error || result.status !== 0)) {
+        throw result.error ?? new Error(result.stderr.toString().trim() || "git diff failed");
+    }
+    const text = result.stdout.subarray(0, limit).toString("utf8");
+    const encoded = Buffer.from(text);
+    truncated ||= encoded.length > limit;
+    return {
+        text: new TextDecoder().decode(encoded.subarray(0, limit), { stream: true }),
+        truncated,
+    };
+}
+export function collectWorkspaceDiff(input) {
+    const maxBytes = input.maxBytes ?? DEFAULT_DIFF_BYTES;
+    if (!Number.isSafeInteger(maxBytes) || maxBytes < 1) {
+        throw new Error("maxBytes must be a positive integer");
+    }
+    const temporary = mkdtempSync(join(tmpdir(), "outsrc-diff-"));
+    try {
+        const index = join(temporary, "index");
+        const currentIndex = resolve(input.workspace, git(["rev-parse", "--git-path", "index"], input.workspace));
+        const env = { ...process.env, GIT_INDEX_FILE: index };
+        if (existsSync(currentIndex))
+            copyFileSync(currentIndex, index);
+        else
+            git(["read-tree", "HEAD"], input.workspace, env);
+        git(["add", "-A", "--", "."], input.workspace, env);
+        const args = ["diff", "--cached", "--no-color"];
+        const patch = boundedGit([...args, input.baseCommit, "--"], input.workspace, env, maxBytes);
+        const stat = boundedGit([...args, "--stat", input.baseCommit, "--"], input.workspace, env, maxBytes);
+        return { patch: patch.text, stat: stat.text, truncated: patch.truncated || stat.truncated };
+    }
+    finally {
+        rmSync(temporary, { recursive: true, force: true });
+    }
+}
+export function commitWorkspace(input) {
+    git(["add", "-A", "--", "."], input.workspace);
+    const tree = git(["write-tree"], input.workspace);
+    const changed = tree !== git(["rev-parse", "HEAD^{tree}"], input.workspace);
+    if (changed)
+        git(["commit", "-m", input.message], input.workspace);
+    return { commit: getBaseCommit(input.workspace), changed };
+}

package/dist/wrapper.d.ts

@@ -0,0 +1,2 @@
+import { type RunResult, type RunSpec } from "./types.js";
+export declare function run(spec: RunSpec): Promise<RunResult>;

package/dist/wrapper.js

@@ -0,0 +1,246 @@
+import { spawn, spawnSync } from "node:child_process";
+import { appendFileSync, chmodSync, existsSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { writeHomeFile } from "./fs-home.js";
+import { dirname, join, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { parseArgs } from "node:util";
+import { z } from "zod";
+import { AGENT_OUTPUT_SCHEMA, buildInvocation, parseAgentOutput } from "./adapters.js";
+import { captureProcess } from "./job.js";
+import { LOG_TRUNCATED, MAX_LOG_BYTES, MAX_RUN_MS } from "./limits.js";
+import { engineDir, isPluginAdapter, teardownInvocation } from "./plugins.js";
+import { writeJson } from "./state.js";
+import { parseThreadId } from "./types.js";
+import { collectWorkspaceDiff, commitWorkspace } from "./workspace.js";
+const RunSpecSchema = z.object({
+    threadId: z.string().transform(parseThreadId),
+    runId: z.string(),
+    runDir: z.string(),
+    worktree: z.string(),
+    baseCommit: z.string(),
+    target: z.object({
+        adapter: z.enum(["claude", "codex", "grok", "custom", "codex-plugin", "grok-plugin"]),
+        command: z.string(),
+        args: z.array(z.string()),
+    }),
+    model: z.string().nullable(),
+    effort: z.string().nullable(),
+    permissions: z.enum(["auto", "ask"]),
+    sessionId: z.string().nullable(),
+    prompt: z.string(),
+    setup: z.array(z.array(z.string())),
+    autoCommit: z.boolean(),
+    kind: z.enum(["task", "review", "adversarial_review"]),
+    base: z.string().nullable(),
+});
+const DeadlineSchema = z.object({ deadlineMs: z.number().int().positive().nullable().optional() });
+function failure(message, sessionId) {
+    return { kind: "failed", message, sessionId, findings: [] };
+}
+function execute(input) {
+    return new Promise((resolveResult, reject) => {
+        const child = spawn(input.command, input.args, {
+            cwd: input.cwd,
+            env: { ...process.env, ...input.env },
+            stdio: ["ignore", "pipe", "pipe"],
+        });
+        const stdout = [];
+        let logError;
+        let logged = 0;
+        let truncated = false;
+        let settled = false;
+        let timedOut = false;
+        const marker = Buffer.from(LOG_TRUNCATED);
+        function append(chunk) {
+            try {
+                if (truncated)
+                    return;
+                const room = MAX_LOG_BYTES - logged;
+                if (room <= 0) {
+                    appendFileSync(input.logPath, marker);
+                    truncated = true;
+                    return;
+                }
+                const slice = chunk.subarray(0, room);
+                appendFileSync(input.logPath, slice);
+                logged += slice.length;
+                if (slice.length < chunk.length) {
+                    appendFileSync(input.logPath, marker);
+                    truncated = true;
+                }
+            }
+            catch (error) {
+                logError = error;
+            }
+        }
+        function finish(error, exitCode) {
+            if (settled)
+                return;
+            settled = true;
+            clearTimeout(timer);
+            if (error !== undefined)
+                reject(error);
+            else
+                resolveResult({ stdout: Buffer.concat(stdout).toString("utf8"), exitCode });
+        }
+        const timer = input.deadlineMs === null ? undefined : setTimeout(() => {
+            timedOut = true;
+            child.kill("SIGTERM");
+            const killTimer = setTimeout(() => child.kill("SIGKILL"), 500);
+            killTimer.unref();
+        }, input.deadlineMs);
+        timer?.unref();
+        child.once("error", (error) => finish(error, null));
+        child.stdout.on("data", (chunk) => {
+            stdout.push(chunk);
+            append(chunk);
+        });
+        child.stderr.on("data", append);
+        child.once("close", (exitCode) => {
+            if (timedOut)
+                finish(new Error(`Run exceeded the ${input.deadlineMs}ms deadline`), null);
+            else if (logError !== undefined)
+                finish(logError, null);
+            else
+                finish(undefined, exitCode);
+        });
+    });
+}
+export async function run(spec) {
+    let output = failure("Agent did not run", spec.sessionId);
+    let exitCode = null;
+    let commit = null;
+    let diffstat = "";
+    let phase = "Run preparation";
+    const logPath = join(spec.runDir, "run.log");
+    const deadlineMs = spec.deadlineMs === undefined ? MAX_RUN_MS : spec.deadlineMs;
+    const deadlineAt = deadlineMs === null ? null : Date.now() + deadlineMs;
+    function timeLeft() {
+        if (deadlineAt === null)
+            return null;
+        const left = deadlineAt - Date.now();
+        if (left <= 0)
+            throw new Error(`Run exceeded the ${deadlineMs}ms deadline`);
+        return left;
+    }
+    function publish(result) {
+        const temporary = join(spec.runDir, "result.json.tmp");
+        writeHomeFile(temporary, JSON.stringify(result));
+        renameSync(temporary, join(spec.runDir, "result.json"));
+        return result;
+    }
+    mkdirSync(spec.runDir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(spec.runDir, 0o700);
+    }
+    catch { }
+    if (existsSync(join(spec.runDir, "cancelled"))) {
+        return publish({
+            kind: "cancelled", message: "Task cancelled", sessionId: spec.sessionId, findings: [],
+            exitCode: null, finishedAt: new Date().toISOString(), diffstat: "", commit: null,
+        });
+    }
+    try {
+        writeFileSync(logPath, "");
+        const schemaPath = join(spec.runDir, "output-schema.json");
+        writeFileSync(schemaPath, JSON.stringify(AGENT_OUTPUT_SCHEMA));
+        for (const [index, command] of spec.setup.entries()) {
+            phase = `Setup command ${index + 1}`;
+            const [executable, ...args] = command;
+            if (!executable)
+                throw new Error("command is empty");
+            const setup = await execute({ command: executable, args, cwd: spec.worktree, logPath, deadlineMs: timeLeft() });
+            if (setup.exitCode !== 0) {
+                exitCode = setup.exitCode;
+                throw new Error(`exited with ${setup.exitCode ?? "a signal"}`);
+            }
+        }
+        phase = "Agent execution";
+        const dataDir = isPluginAdapter(spec.target.adapter) ? engineDir(dirname(dirname(spec.runDir)), spec.target.adapter) : "";
+        const invocation = buildInvocation({
+            target: spec.target,
+            worktree: spec.worktree,
+            prompt: spec.prompt,
+            model: spec.model,
+            effort: spec.effort,
+            sessionId: spec.sessionId,
+            schemaPath,
+            permissions: spec.permissions,
+            kind: spec.kind,
+            base: spec.base,
+            dataDir,
+            threadId: spec.threadId,
+        });
+        let executed;
+        try {
+            executed = await execute({ ...invocation, cwd: spec.worktree, logPath, deadlineMs: timeLeft() });
+        }
+        finally {
+            if (isPluginAdapter(spec.target.adapter)) {
+                const teardown = teardownInvocation(spec.target.adapter, spec.target.command, spec.worktree, dataDir);
+                if (teardown) {
+                    spawnSync(teardown.command, teardown.args, {
+                        cwd: spec.worktree, input: teardown.input, env: { ...process.env, ...teardown.env }, stdio: ["pipe", "ignore", "ignore"], timeout: 15_000,
+                    });
+                }
+            }
+        }
+        exitCode = executed.exitCode;
+        output = parseAgentOutput({ adapter: spec.target.adapter, stdout: executed.stdout, exitCode });
+        output.sessionId ??= spec.sessionId;
+        if (output.kind === "needs_input" && spec.target.adapter === "custom" &&
+            !spec.target.args.some((arg) => arg.includes("{session_id}"))) {
+            output = failure("Custom adapter requested input but has no {session_id} argument for resuming", output.sessionId);
+        }
+        if (output.kind === "completed" && spec.autoCommit) {
+            phase = "Automatic commit";
+            commit = commitWorkspace({
+                workspace: spec.worktree,
+                message: `outsrc: complete ${spec.threadId}`,
+            }).commit;
+        }
+    }
+    catch (error) {
+        output = failure(`${phase} failed: ${String(error)}`, output.sessionId);
+    }
+    try {
+        diffstat = collectWorkspaceDiff({ workspace: spec.worktree, baseCommit: spec.baseCommit }).stat;
+    }
+    catch (error) {
+        const context = output.kind === "failed" ? `${output.message}\n` : "";
+        output = failure(`${context}Result collection failed: ${String(error)}`, output.sessionId);
+    }
+    return publish({
+        ...output,
+        exitCode,
+        finishedAt: new Date().toISOString(),
+        diffstat,
+        commit,
+    });
+}
+async function main() {
+    const { values } = parseArgs({ options: { spec: { type: "string" } }, strict: true });
+    if (!values.spec)
+        throw new Error("wrapper: --spec is required");
+    const raw = JSON.parse(readFileSync(values.spec, "utf8"));
+    const parsed = RunSpecSchema.parse(raw);
+    const deadlineMs = DeadlineSchema.parse(raw).deadlineMs;
+    const spec = deadlineMs === undefined ? parsed : { ...parsed, deadlineMs };
+    mkdirSync(spec.runDir, { recursive: true, mode: 0o700 });
+    try {
+        chmodSync(spec.runDir, 0o700);
+    }
+    catch { }
+    const recorded = captureProcess(process.pid);
+    if (!recorded)
+        throw new Error("process start time is unavailable");
+    writeJson(join(spec.runDir, "process.json"), recorded);
+    const result = await run(spec);
+    process.exitCode = result.kind === "failed" ? 1 : 0;
+}
+if (process.argv[1] && resolve(process.argv[1]) === fileURLToPath(import.meta.url)) {
+    main().catch((error) => {
+        process.stderr.write(`${String(error)}\n`);
+        process.exitCode = 1;
+    });
+}

package/engines.lock.json

@@ -0,0 +1,14 @@
+{
+  "codex-plugin": {
+    "source": "https://github.com/openai/codex-plugin-cc.git",
+    "path": "plugins/codex",
+    "version": "1.0.5",
+    "commit": "80c31f99570876c3ef40327838b0a2ca1ae2cd9c"
+  },
+  "grok-plugin": {
+    "source": "https://github.com/xai-org/grok-build-plugin-cc.git",
+    "path": "plugins/grok-build",
+    "version": "0.2.0",
+    "commit": "5a9f924a8d1ca802b3e6dc0ce0e1a602fb35ec9e"
+  }
+}

package/package.json

@@ -0,0 +1,59 @@
+{
+  "name": "outsrc",
+  "version": "0.2.0",
+  "description": "Local MCP mailbox that lets any agent hand coding tasks to Claude Code, Codex and Grok Build in git worktrees.",
+  "homepage": "https://outsrc.ing",
+  "keywords": [
+    "mcp",
+    "claude-code",
+    "codex",
+    "grok",
+    "agents",
+    "worktree"
+  ],
+  "type": "module",
+  "bin": {
+    "outsrc-mcp": "dist/server.js",
+    "outsrc": "dist/cli.js"
+  },
+  "files": [
+    "dist",
+    "engines.lock.json",
+    "config.example.toml",
+    "README.md",
+    "LICENSE"
+  ],
+  "scripts": {
+    "build": "node scripts/build.mjs",
+    "test": "vitest run",
+    "mcp": "node --import tsx src/server.ts",
+    "verify": "node scripts/verify.mjs",
+    "typecheck": "tsc --project tsconfig.tests.json",
+    "smoke:native": "npm run build && node scripts/native-smoke.mjs",
+    "smoke:plugins": "npm run build && node scripts/plugin-smoke.mjs",
+    "prepublishOnly": "npm run build"
+  },
+  "engines": {
+    "node": "^22.12.0 || ^24.0.0 || >=26.0.0"
+  },
+  "dependencies": {
+    "@modelcontextprotocol/sdk": "^1.25.1",
+    "smol-toml": "^1.4.2",
+    "zod": "^4.6.5"
+  },
+  "devDependencies": {
+    "@types/node": "^22.15.0",
+    "tsx": "^4.20.0",
+    "typescript": "^7.0.2",
+    "vitest": "^5.0.1"
+  },
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/proticom/outsrc.ing.git"
+  },
+  "bugs": {
+    "url": "https://github.com/proticom/outsrc.ing/issues"
+  },
+  "author": "Proticom"
+}