@ashulab/carrier 0.0.0-stage → 0.1.1

package/dist/harnesses/agy.js

@@ -0,0 +1,131 @@
+import { tmpdir } from 'node:os';
+import { dirname, join } from 'node:path';
+import { buildPrompt } from '../prompts/build-prompt.js';
+import { childEnv, markerFor } from './common.js';
+import { boundOutput, caps, clean } from '../execution/events.js';
+/**
+ * Headless Antigravity as in docs/research/antigravity.md; stdin is closed by the runner.
+ * `agy` has no flag to name a run, so the marker rides in the path of its log file, which is part of argv.
+ * Permissions are skipped explicitly (ADR 0004) instead of relying on the operator's `toolPermission` setting, and
+ * there is no sandbox to turn off: `--sandbox` is opt-in. Resume restores context from any cwd, like Claude.
+ */
+export function buildAgyCommand(task, ctx) {
+    return {
+        bin: ctx.binary,
+        args: [
+            '-p',
+            buildPrompt(task, { forgeAgent: ctx.forgeAgent }),
+            // stream-json (not json) so the conversation id arrives while the run is going.
+            '--output-format',
+            'stream-json',
+            '--model',
+            task.model,
+            '--dangerously-skip-permissions',
+            '--add-dir',
+            dirname(task.resultPath),
+            '--log-file',
+            join(tmpdir(), `${markerFor(task.executionId)}.log`), // agy's own log, not ours to keep: the OS cleans the temp folder
+            ...(task.resumeSession ? ['--conversation', task.resumeSession] : []),
+        ],
+        cwd: task.workspace,
+        env: { ...childEnv(ctx), CARRIER_RESULT_PATH: task.resultPath },
+    };
+}
+const usageLimitTexts = ['AI credits balance is too low', 'individual quota reached', 'exhausted your quota'];
+// Shapes observed with agy 1.4.0: the first stdout line is `init` with the conversation id, written before the model is
+// called; a missing login prints "Authentication required" on stderr and ~60 s later ends with a `result` whose error is
+// "authentication failed or timed out"; resuming an unknown id does NOT fail: it exits 0 in a new conversation and only
+// says so on stderr. Both streams go through here.
+export function parseAgyLine(line) {
+    if (line.includes('Authentication required'))
+        return { authFailed: true };
+    if (/warning: conversation ".*" not found/.test(line))
+        return { sessionUnavailable: true };
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (event.event === 'init' && typeof event.conversation_id === 'string')
+        return { session: event.conversation_id };
+    if (event.event === 'result' && event.result?.status === 'ERROR') {
+        const error = str(event.result.error);
+        if (error === 'authentication failed or timed out')
+            return { authFailed: true };
+        // No reset time in the text (docs/research/agent-usage-limit-signals.md).
+        const usageLimit = error !== undefined && usageLimitTexts.some((text) => error.includes(text));
+        return { failure: { kind: usageLimit ? 'usage_limit' : 'api_error', detail: error ?? 'the run ended: ERROR' } };
+    }
+    return undefined;
+}
+const str = (value) => (typeof value === 'string' ? value : undefined);
+const obj = (value) => (typeof value === 'object' && value !== null ? value : {});
+// What the call acts on: the command or the path, else the first text parameter of a tool not seen before.
+function argOf(parameters) {
+    return str(parameters.CommandLine) ?? str(parameters.Path) ?? Object.values(parameters).find((value) => typeof value === 'string') ?? '';
+}
+const exitCode = (output) => /^Command exited with code (\d+)/.exec(output)?.[1];
+function agyEvents(line, state) {
+    const event = obj(JSON.parse(line));
+    if (event.event === 'result') {
+        // A turn left open (the run was cut short) still said what it said.
+        const pending = [...state.text.values()].join('').trim();
+        state.text.clear();
+        const { status, error } = obj(event.result);
+        const failed = str(error) ?? (str(status) !== undefined && status !== 'SUCCESS' ? `the run ended: ${status}` : undefined);
+        return [...(pending ? [{ kind: 'say', text: clean(pending, caps.text) }] : []), ...(failed === undefined ? [] : [{ kind: 'error', text: clean(failed, caps.text) }])];
+    }
+    if (event.event !== 'step_update')
+        return []; // init, and whatever a newer agy adds
+    const step = obj(event.step_update);
+    const key = `${str(step.conversation_id) ?? ''}:${String(step.step_index)}`;
+    const done = step.state === 'DONE';
+    const delta = str(step.text_delta) ?? '';
+    if (step.step_type === 'agent_response') {
+        const text = (state.text.get(key) ?? '') + delta;
+        if (!done) {
+            state.text.set(key, text);
+            return [];
+        }
+        state.text.delete(key);
+        return text.trim() === '' ? [] : [{ kind: 'say', text: clean(text.trim(), caps.text) }];
+    }
+    if (step.step_type !== 'tool')
+        return []; // user_input, and step types not seen yet: nothing to record
+    const info = obj(step.tool_info);
+    const tool = str(step.tool_name) ?? str(info.name) ?? 'tool';
+    if (!done) {
+        state.calls.set(key, { tool });
+        return [{ kind: 'tool_start', callId: key, tool, arg: clean(argOf(obj(info.parameters)), caps.arg) }];
+    }
+    state.calls.delete(key);
+    const output = str(info.output) ?? '';
+    const code = tool === 'run_command' ? exitCode(output) : undefined;
+    // A command's own output is what the design collapses; a read returns only a size, an edit nothing.
+    const body = code === undefined ? [] : boundOutput(output.slice(output.indexOf('Command output:') + 'Command output:'.length).replace(/\r\n/g, '\n').replace(/^\n/, ''));
+    const first = output.split('\n').find((l) => l.trim() !== '');
+    const summary = code === undefined ? first && clean(first, caps.summary) : `Exit code ${code}`;
+    return [
+        {
+            kind: 'tool_end',
+            callId: key,
+            tool,
+            status: code === undefined || code === '0' ? 'ok' : 'err',
+            ...(typeof step.duration_seconds === 'number' && { durationMs: Math.round(step.duration_seconds * 1000) }),
+            ...(summary && { summary }),
+            ...(body.length > 0 && { output: body }),
+        },
+    ];
+}
+/** Events of one stream-json line (docs/research/antigravity-stream.md). Never throws. */
+export function parseAgyEvents(line, state) {
+    try {
+        return agyEvents(line, state);
+    }
+    catch {
+        return []; // not JSON, or a shape this version of agy changed: the log keeps it, the events skip it
+    }
+}
+export const agyAdapter = { command: buildAgyCommand, parseLine: parseAgyLine, parseEvents: parseAgyEvents };

package/dist/harnesses/claude.js

@@ -0,0 +1,246 @@
+import { dirname } from 'node:path';
+import { buildPrompt } from '../prompts/build-prompt.js';
+import { claudeLocalEnv } from './local.js';
+import { childEnv, markerFor } from './common.js';
+import { boundOutput, caps, clean } from '../execution/events.js';
+/** Headless Claude as in docs/research/headless-agents.md; stdin is closed by the runner. */
+export function buildClaudeCommand(task, ctx) {
+    return {
+        bin: ctx.binary,
+        args: [
+            '-p',
+            buildPrompt(task, { forgeAgent: ctx.forgeAgent }),
+            '--permission-mode',
+            'bypassPermissions',
+            // stream-json (not json) so the session id arrives while the run is going.
+            '--output-format',
+            'stream-json',
+            '--verbose',
+            '--model',
+            task.model,
+            '--add-dir',
+            dirname(task.resultPath),
+            '--name',
+            markerFor(task.executionId),
+            ...(task.resumeSession ? ['--resume', task.resumeSession] : []),
+        ],
+        cwd: task.workspace,
+        env: { ...childEnv(ctx), ...(task.provider ? claudeLocalEnv(task.provider) : {}), ...(task.configDir && { CLAUDE_CONFIG_DIR: task.configDir }), CARRIER_RESULT_PATH: task.resultPath },
+    };
+}
+// Shapes observed with claude 2.1.301: init carries the session; a login or key error is an assistant
+// message with error "authentication_failed" and a result with api_error_status 401; a lost session is
+// a result "error_during_execution" saying "No conversation found"; an API error is a result with a numeric
+// api_error_status (429 with api_error "usage_limit_reached" is the session limit) and the message in result.
+export function parseClaudeLine(line) {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return undefined;
+    }
+    if (event.type === 'system' && event.subtype === 'init' && typeof event.session_id === 'string')
+        return { session: event.session_id };
+    if (event.type === 'assistant' && event.error === 'authentication_failed')
+        return { authFailed: true };
+    if (event.type === 'result') {
+        if (event.api_error_status === 401)
+            return { authFailed: true };
+        if (event.is_error === true && JSON.stringify(event.errors ?? '').includes('No conversation found'))
+            return { sessionUnavailable: true };
+        if (event.is_error === true && typeof event.api_error_status === 'number') {
+            const text = typeof event.result === 'string' ? event.result : '';
+            if (event.api_error_status === 429 && event.api_error === 'usage_limit_reached')
+                return { failure: { kind: 'usage_limit', detail: text } };
+            return { failure: { kind: 'api_error', detail: `HTTP ${event.api_error_status}${text ? `: ${text}` : ''}` } };
+        }
+    }
+    return undefined;
+}
+function blocksOf(line) {
+    const content = line.message?.content;
+    return Array.isArray(content) ? content : [];
+}
+const sliceIn = (description) => {
+    const slice = /slice #(\d+)/i.exec(description)?.[1];
+    return slice === undefined ? undefined : Number(slice);
+};
+const laneIn = (blocks) => {
+    const lane = /--lane-(\d+)/.exec(JSON.stringify(blocks.filter((block) => block.type === 'tool_use').map((block) => block.input)))?.[1];
+    return lane === undefined ? undefined : Number(lane);
+};
+/**
+ * Which subagent, lane and slice each parsed stream line belongs to (docs/research/claude-subagent-attribution.md).
+ * Exact: `agent_id` on a subagent's messages; `parent_tool_use_id` points back to its `Agent` call.
+ * Hints, from the model's own conventions: the slice is "slice #N" in that call's description, the lane is
+ * `--lane-N` in a path the subagent touched. Both stay undefined when the convention was not followed.
+ */
+export function attributeSubagentLines(lines) {
+    const callDescription = new Map();
+    const laneOfAgent = new Map();
+    for (const line of lines) {
+        const agent = line.agent_id;
+        if (typeof agent === 'string' && !laneOfAgent.has(agent)) {
+            const lane = laneIn(blocksOf(line));
+            if (lane !== undefined)
+                laneOfAgent.set(agent, lane);
+        }
+        for (const block of blocksOf(line)) {
+            if (block.type === 'tool_use' && block.name === 'Agent' && typeof block.id === 'string' && typeof block.input?.description === 'string') {
+                callDescription.set(block.id, block.input.description);
+            }
+        }
+    }
+    return lines.map((line) => {
+        const parent = typeof line.parent_tool_use_id === 'string' ? line.parent_tool_use_id : undefined;
+        const agentId = typeof line.agent_id === 'string' ? line.agent_id : null;
+        if (agentId === null)
+            return { agentId };
+        const description = (parent && callDescription.get(parent)) ?? (typeof line.task_description === 'string' ? line.task_description : '');
+        const slice = sliceIn(description);
+        const lane = laneOfAgent.get(agentId);
+        return { agentId, ...(lane === undefined ? {} : { lane }), ...(slice === undefined ? {} : { slice }) };
+    });
+}
+const str = (value) => (typeof value === 'string' ? value : undefined);
+// The one-line argument of a call: what it acts on.
+function argOf(input) {
+    if (!input)
+        return '';
+    for (const key of ['command', 'file_path', 'pattern', 'path', 'url', 'query', 'description']) {
+        const value = str(input[key]);
+        if (value !== undefined)
+            return value;
+    }
+    return Object.values(input).find((value) => typeof value === 'string') ?? '';
+}
+// A tool_result's content is a string, or a list of blocks of which the text ones count.
+function resultText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (!Array.isArray(content))
+        return '';
+    return content.map((part) => str(part?.text) ?? '').join('\n');
+}
+// `structuredPatch` of an Edit or Write result: hunks of lines that start with ' ', '-' or '+'.
+function diffOf(result) {
+    const hunks = result?.structuredPatch;
+    if (!Array.isArray(hunks))
+        return undefined;
+    const lines = hunks.flatMap((hunk) => hunk?.lines ?? []).filter((line) => typeof line === 'string');
+    if (lines.length === 0)
+        return undefined;
+    const diff = lines.slice(0, caps.diffLines).map((line) => ({ sign: line[0] === '+' ? '+' : line[0] === '-' ? '-' : ' ', text: clean(line.slice(1), caps.diffLine) }));
+    if (lines.length > caps.diffLines)
+        diff.push({ sign: ' ', text: `… ${lines.length - caps.diffLines} more lines` });
+    return { diff, added: lines.filter((line) => line[0] === '+').length, removed: lines.filter((line) => line[0] === '-').length };
+}
+function claudeEvents(line, state) {
+    const event = JSON.parse(line);
+    if (typeof event !== 'object' || event === null)
+        return [];
+    const time = typeof event.timestamp === 'string' ? Date.parse(event.timestamp) : NaN;
+    const at = Number.isNaN(time) ? undefined : time;
+    const agentId = str(event.agent_id);
+    const scope = { ...(at === undefined ? {} : { at }), ...(agentId === undefined ? {} : { agentId }) };
+    const blocks = blocksOf(event);
+    const events = [];
+    if (event.type === 'assistant') {
+        if (agentId !== undefined && !state.lanes.has(agentId)) {
+            const lane = laneIn(blocks);
+            if (lane !== undefined)
+                state.lanes.set(agentId, lane);
+        }
+        if (str(event.error) !== undefined) {
+            const text = blocks.map((block) => str(block.text)).find((t) => t) ?? String(event.error);
+            return [{ ...scope, kind: 'error', text: clean(text, caps.text) }];
+        }
+        for (const block of blocks) {
+            if (block.type === 'text') {
+                const text = str(block.text);
+                if (text)
+                    events.push({ ...scope, kind: 'say', text: clean(text, caps.text) });
+            }
+            else if (block.type === 'tool_use' && typeof block.id === 'string' && typeof block.name === 'string') {
+                state.calls.set(block.id, { at, tool: block.name });
+                const arg = clean(argOf(block.input), caps.arg);
+                const description = str(block.input?.description);
+                // Only when `arg` is something else: a call whose argument is its description (an Agent) would say it twice.
+                events.push({ ...scope, kind: 'tool_start', callId: block.id, tool: block.name, arg, ...(description && description !== arg && { description: clean(description, caps.summary) }) });
+            }
+        }
+    }
+    else if (event.type === 'user') {
+        for (const block of blocks) {
+            const result = block;
+            if (result.type !== 'tool_result' || typeof result.tool_use_id !== 'string')
+                continue;
+            const call = state.calls.get(result.tool_use_id);
+            state.calls.delete(result.tool_use_id);
+            const text = resultText(result.content);
+            const patch = diffOf(event.tool_use_result);
+            const firstLine = text.split('\n').find((l) => l.trim() !== '');
+            const summary = patch ? `+${patch.added} -${patch.removed}` : firstLine && clean(firstLine, caps.summary);
+            // Only a command's output is kept: it is what the design collapses; a Read would copy whole files.
+            const output = call?.tool === 'Bash' ? boundOutput(text) : [];
+            events.push({
+                ...scope,
+                kind: 'tool_end',
+                callId: result.tool_use_id,
+                ...(call && { tool: call.tool }),
+                status: result.is_error === true ? 'err' : 'ok',
+                ...(call?.at !== undefined && at !== undefined && { durationMs: Math.max(0, at - call.at) }),
+                ...(summary && { summary }),
+                ...(output.length > 0 && { output }),
+                ...(patch && { diff: patch.diff }),
+            });
+        }
+    }
+    else if (event.type === 'system') {
+        const taskId = str(event.task_id);
+        const callId = str(event.tool_use_id);
+        if (event.subtype === 'task_started' && event.task_type === 'local_agent' && taskId !== undefined) {
+            const description = str(event.description) ?? '';
+            const slice = sliceIn(description);
+            state.tasks.set(taskId, { description, slice });
+            events.push({ kind: 'task', agentId: taskId, ...(callId && { callId }), text: clean(description, caps.summary), ...(slice !== undefined && { slice }) });
+        }
+        else if (event.subtype === 'task_notification' && taskId !== undefined && state.tasks.has(taskId)) {
+            const { description, slice } = state.tasks.get(taskId);
+            state.tasks.delete(taskId);
+            const lane = state.lanes.get(taskId);
+            const summary = str(event.summary);
+            events.push({
+                kind: 'task',
+                agentId: taskId,
+                ...(callId && { callId }),
+                text: clean(description, caps.summary),
+                status: event.status === 'completed' ? 'ok' : 'err',
+                ...(summary && { summary: clean(summary, caps.summary) }),
+                ...(slice !== undefined && { slice }),
+                ...(lane !== undefined && { lane }),
+            });
+        }
+        else if (event.subtype === 'code_change_published') {
+            const branch = str(event.branch);
+            const text = [str(event.action) ?? 'published', str(event.identifier), branch && `(${branch})`].filter(Boolean).join(' ');
+            events.push({ kind: 'note', text: clean(text, caps.summary) });
+        }
+    }
+    else if (event.type === 'result' && event.is_error === true) {
+        events.push({ kind: 'error', text: clean(str(event.result) ?? JSON.stringify(event.errors ?? 'the run ended with an error'), caps.text) });
+    }
+    // Thinking, hooks, progress, rate limits and whatever else a newer CLI adds fall through: nothing to record.
+    return events;
+}
+/** Events of one stream-json line (docs/research/macos-app-data-engine.md, "Capturing events"). Never throws. */
+export function parseClaudeEvents(line, state) {
+    try {
+        return claudeEvents(line, state);
+    }
+    catch {
+        return []; // not JSON, or a shape this version of the CLI changed: the log keeps it, the events skip it
+    }
+}
+export const claudeAdapter = { command: buildClaudeCommand, parseLine: parseClaudeLine, parseEvents: parseClaudeEvents };

package/dist/harnesses/codex.js

@@ -0,0 +1,118 @@
+import { buildPrompt } from '../prompts/build-prompt.js';
+import { childEnv, markerFor } from './common.js';
+import { boundOutput, caps, clean } from '../execution/events.js';
+/**
+ * Headless Codex as in docs/research/headless-agents.md; stdin is closed by the runner.
+ * The unattended agent has to push and call `gh`, which Codex's sandbox blocks (no network), and nobody
+ * can answer an approval, so the command skips both: the same trade as Claude's bypassPermissions (ADR 0004).
+ * That one flag also covers `resume`, which takes neither --sandbox nor --add-dir, so the result path outside
+ * the workspace needs no --add-dir. Login, config, plugins and hooks stay those of the user's CLI.
+ */
+export function buildCodexCommand(task, ctx) {
+    return {
+        bin: ctx.binary,
+        args: [
+            'exec',
+            ...(task.resumeSession ? ['resume', task.resumeSession] : []),
+            buildPrompt(task, { forgeAgent: ctx.forgeAgent }),
+            // JSONL: thread.started carries the session id while the run is going.
+            '--json',
+            '--model',
+            task.model,
+            // `--oss --local-provider` is refused by `exec resume`; the config key both of them set is accepted by every form.
+            ...(task.provider ? ['-c', `model_provider="${task.provider}"`] : []),
+            '--dangerously-bypass-approvals-and-sandbox',
+            // Codex has no flag to name a run; a config key it ignores keeps the marker in argv for listActive/stop.
+            '-c',
+            `carrier_marker="${markerFor(task.executionId)}"`,
+        ],
+        cwd: task.workspace,
+        env: { ...childEnv(ctx), ...(task.configDir && { CODEX_HOME: task.configDir }), CARRIER_RESULT_PATH: task.resultPath },
+    };
+}
+const str = (value) => (typeof value === 'string' ? value : undefined);
+const usageLimitStarts = ["You've hit your usage limit", 'You hit your spend cap', 'Your workspace is out of credits', 'Quota exceeded.'];
+// Shapes observed with codex 0.153.4: thread.started carries the session; a missing login ends with
+// turn.failed "unexpected status 401 Unauthorized" (the "Reconnecting... n/5 (... 401" error events before it
+// are retries, not the end); resuming an unknown thread prints "no rollout found for thread id" on stderr, not JSON.
+export function parseCodexLine(line) {
+    let event;
+    try {
+        event = JSON.parse(line);
+    }
+    catch {
+        return line.includes('no rollout found for thread id') ? { sessionUnavailable: true } : undefined;
+    }
+    if (event.type === 'thread.started' && typeof event.thread_id === 'string')
+        return { session: event.thread_id };
+    if (event.type === 'turn.failed') {
+        const message = str(event.error?.message) ?? 'the turn failed';
+        if (message.includes('401 Unauthorized'))
+            return { authFailed: true };
+        // Text only (docs/research/agent-usage-limit-signals.md); the reset time stays in the detail, nothing computes on it.
+        return { failure: { kind: usageLimitStarts.some((start) => message.startsWith(start)) ? 'usage_limit' : 'api_error', detail: message } };
+    }
+    return undefined;
+}
+// Codex runs every command as `<shell> -lc '<the command>'`; the user's command is what is inside.
+const unwrap = (command) => {
+    const match = /^\S+ -lc (['"])([\s\S]*)\1$/.exec(command);
+    if (match === null)
+        return command;
+    return match[1] === '"' ? match[2].replace(/\\(["\\$`])/g, '$1') : match[2];
+};
+function codexEvents(line, state) {
+    const event = JSON.parse(line);
+    if (typeof event !== 'object' || event === null)
+        return [];
+    if (event.type === 'turn.failed')
+        return [{ kind: 'error', text: clean(str(event.error?.message) ?? 'the turn failed', caps.text) }];
+    const item = event.item;
+    if (typeof item !== 'object' || item === null)
+        return [];
+    const started = event.type === 'item.started';
+    if (!started && event.type !== 'item.completed')
+        return [];
+    const callId = str(item.id);
+    // The stream has no time: the engine stamps each event with the arrival of its line (and so no duration either).
+    if (item.type === 'agent_message') {
+        const text = str(item.text);
+        return text ? [{ kind: 'say', text: clean(text, caps.text) }] : [];
+    }
+    // Codex prints its own warnings as error items (a notice about a flag, not a failure of the run).
+    if (item.type === 'error') {
+        const text = str(item.message);
+        return text ? [{ kind: 'note', text: clean(text, caps.summary) }] : [];
+    }
+    if (callId === undefined || (item.type !== 'command_execution' && item.type !== 'file_change'))
+        return [];
+    const command = item.type === 'command_execution';
+    const tool = command ? 'shell' : 'Edit';
+    if (started) {
+        state.calls.set(callId, { tool });
+        const paths = Array.isArray(item.changes) ? item.changes.map((change) => str(change?.path)).filter((path) => path !== undefined) : [];
+        return [{ kind: 'tool_start', callId, tool, arg: clean(command ? unwrap(str(item.command) ?? '') : paths.join(', '), caps.arg) }];
+    }
+    state.calls.delete(callId);
+    if (!command) {
+        const files = Array.isArray(item.changes) ? item.changes.length : 0;
+        return [{ kind: 'tool_end', callId, tool, status: item.status === 'failed' ? 'err' : 'ok', summary: `${files} file${files === 1 ? '' : 's'}` }];
+    }
+    const code = typeof item.exit_code === 'number' ? item.exit_code : undefined;
+    const text = str(item.aggregated_output) ?? '';
+    const failed = code === undefined ? item.status === 'failed' : code !== 0;
+    const firstLine = text.split('\n').find((l) => l.trim() !== '');
+    const summary = failed && code !== undefined ? `Exit code ${code}` : firstLine && clean(firstLine, caps.summary);
+    const output = boundOutput(text);
+    return [{ kind: 'tool_end', callId, tool, status: failed ? 'err' : 'ok', ...(summary && { summary }), ...(output.length > 0 && { output }) }];
+}
+/** Events of one `exec --json` line (docs/research/codex-exec-stream.md). Never throws; reasoning, todo lists and whatever else a newer CLI adds give []. */
+export function parseCodexEvents(line, state) {
+    try {
+        return codexEvents(line, state);
+    }
+    catch {
+        return []; // not JSON, or a shape this version of the CLI changed: the log keeps it, the events skip it
+    }
+}
+export const codexAdapter = { command: buildCodexCommand, parseLine: parseCodexLine, parseEvents: parseCodexEvents };

package/dist/harnesses/common.js

@@ -0,0 +1,59 @@
+import { accessSync, constants } from 'node:fs';
+import { delimiter, join } from 'node:path';
+/** Marker in the child's argv, so a later process finds the executions an earlier one left running. */
+export const markerFor = (executionId) => `carrier-exec-${executionId}`;
+// git over HTTPS ignores GH_TOKEN: it asks the user's credential helpers (on macOS the keychain, i.e. the person's own login),
+// so without this every push and branch operation of a bot would be made as that person. The first entry empties the helper
+// list; the second answers with the execution's token, read from the environment when git asks (the token is not in the value).
+// For a Forge bot (CARRIER_FORGE_AGENT set; read as a variable, never pasted into this text) it asks `agent-forge` for a token
+// minted now, since the one the run started with expires after about an hour; if Forge prints nothing, fails or takes longer
+// than 10 seconds (a watchdog kills it; `timeout` is not on a stock macOS, and CARRIER_FORGE_TIMEOUT is only for the tests), the starting token.
+// Only `get` answers: git's `store` and `erase` must not mint tokens for nothing.
+const gitUsesToken = '!f() { [ "$1" = get ] || return 0; echo username=x-access-token; t=; ' +
+    'if [ -n "$CARRIER_FORGE_AGENT" ] && o=$(mktemp); then ' +
+    'agent-forge token --agent "$CARRIER_FORGE_AGENT" >"$o" 2>/dev/null & p=$!; ' +
+    '(sleep "${CARRIER_FORGE_TIMEOUT:-10}"; kill $p) >/dev/null 2>&1 & w=$!; ' +
+    '{ wait $p; kill $w; wait $w; } 2>/dev/null; t=$(cat "$o"); rm -f "$o"; fi; ' +
+    'echo "password=${t:-$GH_TOKEN}"; }; f';
+export function childEnv({ githubToken, gitIdentity, forgeAgent, baseEnv }) {
+    const identity = gitIdentity && {
+        GIT_AUTHOR_NAME: gitIdentity.name,
+        GIT_AUTHOR_EMAIL: gitIdentity.email,
+        GIT_COMMITTER_NAME: gitIdentity.name,
+        GIT_COMMITTER_EMAIL: gitIdentity.email,
+    };
+    const inherited = Object.entries(baseEnv).filter((e) => e[1] !== undefined);
+    const env = Object.fromEntries(inherited);
+    // Keeps the config entries the environment already had (GIT_CONFIG_COUNT) and adds ours after them.
+    const first = Number.isInteger(Number(env.GIT_CONFIG_COUNT)) ? Number(env.GIT_CONFIG_COUNT) : 0;
+    const credentialHelper = {
+        GIT_CONFIG_COUNT: String(first + 2),
+        [`GIT_CONFIG_KEY_${first}`]: 'credential.helper',
+        [`GIT_CONFIG_VALUE_${first}`]: '',
+        [`GIT_CONFIG_KEY_${first + 1}`]: 'credential.helper',
+        [`GIT_CONFIG_VALUE_${first + 1}`]: gitUsesToken,
+    };
+    return { ...env, GH_TOKEN: githubToken, GITHUB_TOKEN: githubToken, ...credentialHelper, ...identity, ...(forgeAgent && { CARRIER_FORGE_AGENT: forgeAgent }) };
+}
+const isExecutable = (path) => {
+    try {
+        accessSync(path, constants.X_OK);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+/**
+ * The real CLI binary, never a wrapper: Superset puts wrappers under ~/.superset/bin ahead of the real one
+ * on PATH (they add flags and trap signals), see docs/research/headless-agents.md.
+ */
+export function resolveBinary(name, path = process.env.PATH ?? '', executable = isExecutable) {
+    for (const dir of path.split(delimiter)) {
+        if (dir === '' || dir.includes('/.superset/'))
+            continue;
+        if (executable(join(dir, name)))
+            return join(dir, name);
+    }
+    throw new Error(`cannot find the real "${name}" binary on PATH`);
+}

package/dist/harnesses/credentials.js

@@ -0,0 +1,38 @@
+import { z } from 'zod';
+const botUser = z.object({ id: z.int().positive() });
+/** The id of a bot account from GitHub's public users endpoint (as Forge computes it), asked once per agent. */
+export function botIdFromGitHub(fetchImpl = fetch) {
+    const known = new Map();
+    return async (agent, token) => {
+        const cached = known.get(agent);
+        if (cached !== undefined)
+            return cached;
+        const response = await fetchImpl(`https://api.github.com/users/${encodeURIComponent(`${agent}[bot]`)}`, {
+            headers: { authorization: `Bearer ${token}`, accept: 'application/vnd.github+json' },
+            signal: AbortSignal.timeout(30_000),
+        });
+        if (!response.ok)
+            throw new Error(`GitHub answered HTTP ${response.status} for the user ${agent}[bot]`);
+        const { id } = botUser.parse(await response.json());
+        known.set(agent, id);
+        return id;
+    };
+}
+/**
+ * What each execution gets: the token of its profile (minted for this execution, handed to the child process
+ * only) and, for a Forge bot, the commit identity `<agent>[bot]`, which Forge exports only in its interactive
+ * mode. A `{kind:'gh'}` profile is the user's own login: `gh` as it is, no identity override.
+ * Any failure rejects; the runner reports that as `auth_failed`, since the run cannot start without a token.
+ */
+export function profileCredentials({ profiles, mint, botId = botIdFromGitHub() }) {
+    return async (task) => {
+        const profile = profiles[task.profile];
+        if (!profile)
+            throw new Error(`profile "${task.profile}" is not declared`);
+        const githubToken = await mint(profile, task.repo);
+        if (profile.kind === 'gh')
+            return { githubToken };
+        const name = `${profile.agent}[bot]`;
+        return { githubToken, forgeAgent: profile.agent, gitIdentity: { name, email: `${await botId(profile.agent, githubToken)}+${name}@users.noreply.github.com` } };
+    };
+}