@aragon-agent/cli 0.5.11 → 0.6.1

package/dist/diagnostics/info.js

@@ -0,0 +1,99 @@
+/**
+ * `aragon info` - capability discovery (cli-integration-surface section 5.4).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * "INSTALL AND CALL" ACROSS VERSIONS IS ONLY ROBUST IF THE CALLER CAN ASK WHAT
+ * IT JUST INSTALLED (G6). Everything a wrapper might branch on is here, and
+ * `features` is a FLAT STRING LIST on purpose: a wrapper testing
+ * `info.features.includes('sessions')` keeps working across versions that add
+ * capabilities, which a nested shape with renamed keys would not.
+ */
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+import { readFileSync } from 'node:fs';
+import process from 'node:process';
+import { getConfigPath, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
+import { loadConfig, makeGetApiKey } from '../config/load.js';
+import { HOST_TOOL_NAMES } from '../tools/index.js';
+import { EXEC_SCHEMA_VERSION } from '../exec/events.js';
+/**
+ * Everything this build can do, as names a wrapper can test for.
+ *
+ * ADD, NEVER RENAME. A removed name is a breaking change for every consumer that
+ * guarded on it, and the whole value of the list is that guarding is cheap.
+ */
+const FEATURES = [
+    'exec',
+    'sessions',
+    'permissions',
+    'budgets',
+    'team',
+    'todo',
+    'skills',
+    'fast',
+];
+export function buildInfo(flags, version) {
+    const config = loadConfig(flags);
+    const getKey = makeGetApiKey(config);
+    return {
+        cli: version,
+        core: readCoreVersion(),
+        node: process.version,
+        schemaVersion: EXEC_SCHEMA_VERSION,
+        home: getUserDataDir(),
+        configPath: getConfigPath(),
+        sessionsDir: getSessionsDir(),
+        provider: config.provider,
+        model: config.model,
+        hasApiKey: Boolean(getKey(config.provider)),
+        // THE SUPERSET, not "what a run would register right now". This answers
+        // "which names can `--allow-tool` take?", which is exactly what
+        // `HOST_TOOL_NAMES` means and exactly what `--allow-tool` validates against.
+        tools: [...HOST_TOOL_NAMES],
+        outputFormats: ['text', 'json', 'stream-json'],
+        inputFormats: ['text', 'stream-json'],
+        permissionModes: ['auto', 'plan', 'strict'],
+        features: [...FEATURES],
+    };
+}
+/**
+ * The installed `@aragon-agent/core` version, or `'unknown'`.
+ *
+ * RESOLVED, NOT READ OFF THE DEPENDENCY RANGE. `"^0.2.12"` in this package's
+ * own `package.json` is what was ASKED FOR; a consumer asking `aragon info`
+ * wants what is actually loaded, and the two differ on every machine that
+ * installed a patch release.
+ *
+ * A DIRECTORY WALK, AND NEITHER `createRequire().resolve()` NOR
+ * `import.meta.resolve()` (implementation finding IF-2). Core's `exports` map
+ * declares only an `import` condition, so `createRequire(...).resolve()` fails
+ * with `ERR_PACKAGE_PATH_NOT_EXPORTED` - and it fails on the DEVELOPER's machine
+ * as readily as on a user's, which is how this was caught. `import.meta.resolve`
+ * is not synchronously available on Node 18, and `engines` says `>=18`.
+ *
+ * The walk covers all three real layouts: the monorepo (a symlink in the root
+ * `node_modules`), a flat npm install (core beside cli under the project's
+ * `node_modules`), and a nested one (core under the cli package's own
+ * `node_modules`).
+ */
+function readCoreVersion() {
+    let dir = dirname(fileURLToPath(import.meta.url));
+    for (let depth = 0; depth < 10; depth += 1) {
+        try {
+            const pkg = JSON.parse(readFileSync(join(dir, 'node_modules', '@aragon-agent', 'core', 'package.json'), 'utf-8'));
+            if (pkg.version)
+                return pkg.version;
+        }
+        catch {
+            // Not this level. Keep walking.
+        }
+        const parent = dirname(dir);
+        if (parent === dir)
+            break;
+        dir = parent;
+    }
+    // A bundled or unusual layout. A missing version is worth reporting honestly;
+    // it is not worth failing a discovery command over.
+    return 'unknown';
+}

package/dist/exec/cli-commands.d.ts

@@ -0,0 +1,31 @@
+/**
+ * `aragon exec` commander wiring (cli-integration-surface section 3.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE DECLARATIONS LIVE HERE, NOT IN `cli.tsx`, AND THAT IS A DELIBERATE
+ * DEPARTURE FROM THE EXISTING CONVENTION. `logs` / `history` / `skills` /
+ * `update` declare their options in `cli.tsx` and delegate to a `run*Command`.
+ * `cli.tsx` is already 1600 lines against this repository's 1000-line guideline,
+ * and four new subcommands carrying about twenty declarations between them is
+ * another 120 lines on a file that is 60% over budget. So `cli.tsx` gains four
+ * imports and four `register*Command(...)` call sites instead. This is a rule
+ * for the NEW code, not a refactor of the old (which is out of scope).
+ *
+ * NOT `src/commands/` EITHER: that directory is the SLASH-command tree
+ * (`/help`, `/model`, `/save`, `/resume`), and it already owns the two names
+ * exec's session work sits closest to.
+ */
+import { type Command } from 'commander';
+import type { CliFlags } from '../config/load.js';
+import { type ExecControllerFactory } from './index.js';
+export interface ExecCommandDeps {
+    version: string;
+    /**
+     * Supplied by `cli.tsx`. It cannot be imported: `cli.tsx` imports this module,
+     * so reaching back for `makeController` would be a cycle, and re-deriving it
+     * here would give the headless approval gates a second definition.
+     */
+    makeController: ExecControllerFactory;
+}
+export declare function registerExecCommand(program: Command, toFlags: (opts: Record<string, unknown>) => CliFlags, deps: ExecCommandDeps): void;

package/dist/exec/cli-commands.js

@@ -0,0 +1,63 @@
+/**
+ * `aragon exec` commander wiring (cli-integration-surface section 3.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE DECLARATIONS LIVE HERE, NOT IN `cli.tsx`, AND THAT IS A DELIBERATE
+ * DEPARTURE FROM THE EXISTING CONVENTION. `logs` / `history` / `skills` /
+ * `update` declare their options in `cli.tsx` and delegate to a `run*Command`.
+ * `cli.tsx` is already 1600 lines against this repository's 1000-line guideline,
+ * and four new subcommands carrying about twenty declarations between them is
+ * another 120 lines on a file that is 60% over budget. So `cli.tsx` gains four
+ * imports and four `register*Command(...)` call sites instead. This is a rule
+ * for the NEW code, not a refactor of the old (which is out of scope).
+ *
+ * NOT `src/commands/` EITHER: that directory is the SLASH-command tree
+ * (`/help`, `/model`, `/save`, `/resume`), and it already owns the two names
+ * exec's session work sits closest to.
+ */
+import { Option } from 'commander';
+import { runExec } from './index.js';
+export function registerExecCommand(program, toFlags, deps) {
+    const exec = program
+        .command('exec')
+        .description('Headless, machine-facing run: JSON events, sessions, tool permissions, budgets')
+        .argument('[prompt]', 'The prompt (or use --prompt-file, or pipe it on stdin)')
+        .option('--output-format <fmt>', 'text | json | stream-json (default: text)')
+        .option('--input-format <fmt>', 'text | stream-json (needs --output-format stream-json)')
+        .option('--partial-messages', 'Emit text_delta events (stream-json only)')
+        .option('--include-thinking', 'Emit thinking events (stream-json only)')
+        .option('--prompt-file <path>', 'Read the prompt from a file')
+        .option('--session-id <id>', 'Create or resume a session by id')
+        .option('--resume <id|path>', 'Resume an existing session; fail if it is absent')
+        .option('-c, --continue', 'Resume the newest session for this working directory')
+        .option('--no-save-session', 'Run statelessly: write nothing to the sessions directory')
+        .option('--max-turns <n>', 'Stop after n assistant turns (exit 3)')
+        .option('--max-duration <ms>', 'Stop after ms of wall clock (exit 3). --idle-timeout still applies to a silent ' +
+        'stretch inside the run, and --tool-timeout to a single tool call')
+        .option('--permission-mode <m>', 'auto | plan | strict (default: auto)')
+        .option('--allow-tool <names>', 'Add tools to the baseline (repeatable; comma-separated accepted)', collect)
+        .option('--deny-tool <names>', 'Remove tools; wins over --allow-tool (repeatable; comma-separated accepted)', collect)
+        .option('--append-system-prompt <text>', 'Append text to the builtin system prompt')
+        .option('--append-system-prompt-file <path>', 'Append the contents of a file')
+        // HIDDEN, AND KEPT ONLY SO A GUESS IS NOT PUNISHED (P2-1 / D-16). The root
+        // command already carries `--tool-timeout` (a single tool call) and
+        // `--idle-timeout` (the engine watchdog); a third option called plainly
+        // `--timeout` would be the most generic of the three names attached to the
+        // newest and least familiar of them.
+        .addOption(new Option('--timeout <ms>', 'Alias of --max-duration').hideHelp());
+    exec.action(async (prompt, opts) => {
+        const rootOpts = program.opts();
+        process.exitCode = await runExec(toFlags(program.opts()), {
+            ...opts,
+            // Hoisted from the root by commander, and read here because `exec` does
+            // not redeclare them. `--print` is REFUSED rather than ignored (P2-5).
+            ...(rootOpts.quiet !== undefined ? { quiet: rootOpts.quiet } : {}),
+            ...(rootOpts.print !== undefined ? { print: rootOpts.print } : {}),
+        }, prompt, { version: deps.version, makeController: deps.makeController });
+    });
+}
+/** Repeatable option accumulator. Comma splitting happens in `options.ts`. */
+function collect(value, previous = []) {
+    return [...previous, value];
+}

package/dist/exec/emitter.d.ts

@@ -0,0 +1,80 @@
+/**
+ * The three output faces of `aragon exec` (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE EMITTER IS THE ONLY OBJECT HANDED A STDOUT STREAM (R-2). Everything else
+ * on the exec path writes to stderr: migration notices, config-parse warnings,
+ * untrusted-skill notices, retry lines, `[usage]`, `[team]`, `[todo]` and every
+ * log record. One stray `process.stdout.write` corrupts every consumer, silently
+ * and only in the field, so the containment is structural rather than a rule
+ * anyone has to remember.
+ *
+ * `result()` IS IDEMPOTENT ON ALL THREE (AC-6). A `finally` and an error handler
+ * racing must not produce two `result` lines, and the second call being a no-op
+ * is what makes "exactly one, always last" true on every exit path including
+ * error, budget and signal - rather than true for the paths someone remembered.
+ */
+import type { ExecEvent, ExecInitParams, ExecResultEvent, ExecResultParams } from './events.js';
+export interface ExecEmitter {
+    init(params: ExecInitParams): void;
+    /** Every non-`result` event. Ignored wholesale by `text` and `json`. */
+    emit(event: ExecEvent): void;
+    /** Exactly once per run; the second call is a no-op. */
+    result(params: ExecResultParams): void;
+    /** What `result()` actually wrote, or `null`. For tests and for `runExec`. */
+    emitted(): ExecResultEvent | null;
+}
+/**
+ * `--output-format text`: WRITES NOTHING (D-1).
+ *
+ * Text mode delegates to `runHeadless` VERBATIM - same controller, same
+ * `quiet`, same `followThrough` - and this object exists only so `runExec` has
+ * one shape to talk to. Reimplementing text rendering here would make "the human
+ * CLI is unchanged" an argument someone has to trust instead of a fact anyone
+ * can check, and the two implementations would drift the first time a retry line
+ * changed. AC-1 asserts byte equality on BOTH streams; this class is what makes
+ * it true by construction.
+ */
+export declare class TextEmitter implements ExecEmitter {
+    private done;
+    init(_params: ExecInitParams): void;
+    emit(_event: ExecEvent): void;
+    result(params: ExecResultParams): void;
+    emitted(): ExecResultEvent | null;
+}
+/**
+ * `--output-format json`: the `result` object alone, pretty-printed, on stdout.
+ *
+ * `aragon exec --output-format json "..." | jq -r .result` is the intended
+ * one-liner, which is why the intermediate events are dropped rather than
+ * buffered into an array: a wrapper that wants the stream asks for the stream.
+ */
+export declare class JsonEmitter implements ExecEmitter {
+    private readonly out;
+    private done;
+    constructor(out: NodeJS.WritableStream);
+    init(_params: ExecInitParams): void;
+    emit(_event: ExecEvent): void;
+    result(params: ExecResultParams): void;
+    emitted(): ExecResultEvent | null;
+}
+/**
+ * `--output-format stream-json`: one JSON object per line, `\n`-terminated, no
+ * pretty-printing, UTF-8.
+ *
+ * EVENTS AFTER `result` ARE DROPPED, not appended. "Exactly one `result`, always
+ * last" is the property consumers build their read loop around, and a late
+ * `tool_result` arriving from a torn-down subscription would break it in the
+ * rarest and least reproducible circumstances there are.
+ */
+export declare class StreamJsonEmitter implements ExecEmitter {
+    private readonly out;
+    private done;
+    constructor(out: NodeJS.WritableStream);
+    init(params: ExecInitParams): void;
+    emit(event: ExecEvent): void;
+    result(params: ExecResultParams): void;
+    emitted(): ExecResultEvent | null;
+}
+export declare function createEmitter(format: 'text' | 'json' | 'stream-json', out: NodeJS.WritableStream): ExecEmitter;

package/dist/exec/emitter.js

@@ -0,0 +1,127 @@
+/**
+ * The three output faces of `aragon exec` (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * THE EMITTER IS THE ONLY OBJECT HANDED A STDOUT STREAM (R-2). Everything else
+ * on the exec path writes to stderr: migration notices, config-parse warnings,
+ * untrusted-skill notices, retry lines, `[usage]`, `[team]`, `[todo]` and every
+ * log record. One stray `process.stdout.write` corrupts every consumer, silently
+ * and only in the field, so the containment is structural rather than a rule
+ * anyone has to remember.
+ *
+ * `result()` IS IDEMPOTENT ON ALL THREE (AC-6). A `finally` and an error handler
+ * racing must not produce two `result` lines, and the second call being a no-op
+ * is what makes "exactly one, always last" true on every exit path including
+ * error, budget and signal - rather than true for the paths someone remembered.
+ */
+import { buildInitEvent, buildResultEvent, toNdjsonLine } from './events.js';
+/**
+ * `--output-format text`: WRITES NOTHING (D-1).
+ *
+ * Text mode delegates to `runHeadless` VERBATIM - same controller, same
+ * `quiet`, same `followThrough` - and this object exists only so `runExec` has
+ * one shape to talk to. Reimplementing text rendering here would make "the human
+ * CLI is unchanged" an argument someone has to trust instead of a fact anyone
+ * can check, and the two implementations would drift the first time a retry line
+ * changed. AC-1 asserts byte equality on BOTH streams; this class is what makes
+ * it true by construction.
+ */
+export class TextEmitter {
+    done = null;
+    // The parameters are DECLARED even though they are unused, so a caller
+    // holding a concrete `TextEmitter` can call it exactly as it calls the other
+    // two. A zero-arity method satisfies the interface and then makes the class
+    // unusable through its own type, which is the sort of asymmetry that turns
+    // into a cast at the call site.
+    init(_params) {
+        // Deliberately empty. `runHeadless` owns every byte of the text stream.
+    }
+    emit(_event) {
+        // Deliberately empty, same reason.
+    }
+    result(params) {
+        if (this.done)
+            return;
+        // RECORDED BUT NOT WRITTEN. `runExec` reads it for the exit code and the
+        // session bookkeeping; writing it would append a JSON line to prose that
+        // `aragon -p` does not produce.
+        this.done = buildResultEvent(params);
+    }
+    emitted() {
+        return this.done;
+    }
+}
+/**
+ * `--output-format json`: the `result` object alone, pretty-printed, on stdout.
+ *
+ * `aragon exec --output-format json "..." | jq -r .result` is the intended
+ * one-liner, which is why the intermediate events are dropped rather than
+ * buffered into an array: a wrapper that wants the stream asks for the stream.
+ */
+export class JsonEmitter {
+    out;
+    done = null;
+    constructor(out) {
+        this.out = out;
+    }
+    init(_params) {
+        // The init event is carried by `result.sessionId` / `result.model` for this
+        // format. Writing it here would put two objects on a stream documented to
+        // carry one.
+    }
+    emit(_event) {
+        // Dropped by design; see the class comment.
+    }
+    result(params) {
+        if (this.done)
+            return;
+        this.done = buildResultEvent(params);
+        this.out.write(`${JSON.stringify(this.done, null, 2)}\n`);
+    }
+    emitted() {
+        return this.done;
+    }
+}
+/**
+ * `--output-format stream-json`: one JSON object per line, `\n`-terminated, no
+ * pretty-printing, UTF-8.
+ *
+ * EVENTS AFTER `result` ARE DROPPED, not appended. "Exactly one `result`, always
+ * last" is the property consumers build their read loop around, and a late
+ * `tool_result` arriving from a torn-down subscription would break it in the
+ * rarest and least reproducible circumstances there are.
+ */
+export class StreamJsonEmitter {
+    out;
+    done = null;
+    constructor(out) {
+        this.out = out;
+    }
+    init(params) {
+        if (this.done)
+            return;
+        this.out.write(toNdjsonLine(buildInitEvent(params)));
+    }
+    emit(event) {
+        if (this.done)
+            return;
+        this.out.write(toNdjsonLine(event));
+    }
+    result(params) {
+        if (this.done)
+            return;
+        this.done = buildResultEvent(params);
+        this.out.write(toNdjsonLine(this.done));
+    }
+    emitted() {
+        return this.done;
+    }
+}
+export function createEmitter(format, out) {
+    if (format === 'json')
+        return new JsonEmitter(out);
+    if (format === 'stream-json')
+        return new StreamJsonEmitter(out);
+    return new TextEmitter();
+}

package/dist/exec/events.d.ts

@@ -0,0 +1,226 @@
+/**
+ * THE CONTRACT (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`, R-3 / AC-25). Every string here can reach a
+ * consumer's terminal through `--output-format text` fallbacks or a stderr
+ * warning, and the whole point of the scanner is that a legacy `cmd.exe` shows
+ * mojibake for anything else.
+ *
+ * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
+ * `node:`-free type space, so a consumer of this module cannot accidentally
+ * evaluate the runner.
+ *
+ * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
+ * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
+ * That rule only holds if consumers keep their side of it, so the README states
+ * it in the same words: ignore event types you do not know, ignore fields you do
+ * not know. Without that contract the version would have to move for every
+ * additive change and every wrapper would pin an exact number forever.
+ */
+export declare const EXEC_SCHEMA_VERSION = 1;
+/** The three baselines of section 4.2. `plan` is a MODE, never a filter. */
+export type ExecPermissionMode = 'auto' | 'plan' | 'strict';
+export type ExecOutputFormat = 'text' | 'json' | 'stream-json';
+export type ExecInputFormat = 'text' | 'stream-json';
+/**
+ * Why the run ended.
+ *
+ * `interrupted` covers ALL THREE signals (section 3.6): which one arrived is an
+ * operating-system fact, not an agent outcome, and a wrapper that wants to know
+ * reads `exitCode` - which follows the CLI's existing `128 + signo` convention.
+ */
+export type ExecStopReason = 'end_turn' | 'max_turns' | 'timeout' | 'interrupted' | 'error';
+export interface ExecUsage {
+    inputTokens: number;
+    outputTokens: number;
+    totalTokens: number;
+}
+export interface ExecCost {
+    amount: number;
+    currency: 'USD';
+    /**
+     * `controller.isPricedModel(...)` (P2-3) - the method the CLI already uses for
+     * this question, not a second price table. When it is `false`, `amount` is `0`:
+     * a feature that looks free while it is spending money is worse than one that
+     * admits it does not know.
+     */
+    known: boolean;
+}
+export interface ExecTodoCounts {
+    total: number;
+    done: number;
+}
+export interface ExecErrorInfo {
+    code: string;
+    message: string;
+}
+export interface ExecSystemInitEvent {
+    type: 'system';
+    subtype: 'init';
+    schemaVersion: number;
+    sessionId: string;
+    cli: string;
+    cwd: string;
+    startedAt: number;
+    model: {
+        provider: string;
+        id: string;
+        baseUrl: string | null;
+    };
+    permissionMode: ExecPermissionMode;
+    tools: string[];
+    resumed: boolean;
+}
+export interface ExecUserEvent {
+    type: 'user';
+    sessionId: string;
+    turn: number;
+    text: string;
+    /**
+     * `todo_continue` marks a message the CLI generated on the caller's behalf
+     * through the follow-through loop. A wrapper replaying a transcript has to be
+     * able to tell those apart from what it actually sent.
+     */
+    source: 'caller' | 'todo_continue';
+}
+export interface ExecTextDeltaEvent {
+    type: 'text_delta';
+    sessionId: string;
+    turn: number;
+    delta: string;
+}
+export interface ExecThinkingEvent {
+    type: 'thinking';
+    sessionId: string;
+    turn: number;
+    text: string;
+}
+export interface ExecAssistantEvent {
+    type: 'assistant';
+    sessionId: string;
+    turn: number;
+    text: string;
+}
+export interface ExecToolCallEvent {
+    type: 'tool_call';
+    sessionId: string;
+    turn: number;
+    id: string;
+    name: string;
+    input: Record<string, unknown>;
+}
+export interface ExecToolResultEvent {
+    type: 'tool_result';
+    sessionId: string;
+    turn: number;
+    id: string;
+    name: string;
+    isError: boolean;
+    durationMs: number;
+    /**
+     * NOT TRUNCATED A SECOND TIME (AC-26). The core executor already clips at
+     * roughly 100 KB, and this event carries what the MODEL saw - the only
+     * faithful choice. A consumer therefore needs a line reader without a small
+     * buffer cap, and the README says so.
+     */
+    output: string;
+}
+export interface ExecTodoEvent {
+    type: 'todo';
+    sessionId: string;
+    total: number;
+    done: number;
+    activeIndex: number;
+    items: {
+        content: string;
+        status: 'pending' | 'in_progress' | 'completed';
+    }[];
+}
+export interface ExecTeamEvent {
+    type: 'team';
+    sessionId: string;
+    subtype: 'dispatch_start' | 'agent_update' | 'dispatch_end';
+    label?: string;
+    phase?: string;
+    description?: string;
+    durationMs?: number;
+    toolCalls?: number;
+    ok?: number;
+    total?: number;
+    aborted?: boolean;
+}
+export interface ExecFastReviewEvent {
+    type: 'fast_review';
+    sessionId: string;
+    turn: number;
+    model: string;
+    text: string;
+}
+export interface ExecRetryEvent {
+    type: 'retry';
+    sessionId: string;
+    attempt: number;
+    maxRetries: number;
+    errorType: string;
+    delayMs: number;
+}
+export interface ExecErrorEvent {
+    type: 'error';
+    sessionId: string;
+    /** `false` for a line the run recovered from (a malformed stdin line, say). */
+    fatal: boolean;
+    code: string;
+    message: string;
+}
+export interface ExecResultEvent {
+    type: 'result';
+    schemaVersion: number;
+    sessionId: string;
+    isError: boolean;
+    stopReason: ExecStopReason;
+    /**
+     * `0` success | `1` agent error | `2` usage/config | `3` budget |
+     * `128 + signo` for a signal (130 SIGINT, 143 SIGTERM, 129 SIGHUP).
+     *
+     * DELIBERATELY `number`, NOT A UNION (P1-11): `logging/install.ts` holds
+     * `SIGNAL_NUMBERS = { SIGINT: 2, SIGTERM: 15, SIGHUP: 1 }` and exits
+     * `128 + signo`, so the signal values are open-ended and a union that omitted
+     * 143 would make the honest value unrepresentable.
+     */
+    exitCode: number;
+    /** The final assistant text; `''` when there was none. */
+    result: string;
+    turns: number;
+    durationMs: number;
+    usage: ExecUsage;
+    cost: ExecCost;
+    model: {
+        provider: string;
+        id: string;
+    };
+    todos: ExecTodoCounts | null;
+    error: ExecErrorInfo | null;
+}
+export type ExecEvent = ExecSystemInitEvent | ExecUserEvent | ExecTextDeltaEvent | ExecThinkingEvent | ExecAssistantEvent | ExecToolCallEvent | ExecToolResultEvent | ExecTodoEvent | ExecTeamEvent | ExecFastReviewEvent | ExecRetryEvent | ExecErrorEvent | ExecResultEvent;
+/** Everything `system/init` needs that the runner cannot derive for itself. */
+export interface ExecInitParams {
+    sessionId: string;
+    cli: string;
+    cwd: string;
+    startedAt: number;
+    model: {
+        provider: string;
+        id: string;
+        baseUrl: string | null;
+    };
+    permissionMode: ExecPermissionMode;
+    tools: string[];
+    resumed: boolean;
+}
+export declare function buildInitEvent(params: ExecInitParams): ExecSystemInitEvent;
+/** Everything `result` needs. `schemaVersion` is stamped here, never by a caller. */
+export type ExecResultParams = Omit<ExecResultEvent, 'type' | 'schemaVersion'>;
+export declare function buildResultEvent(params: ExecResultParams): ExecResultEvent;
+/** Serialize one event as an NDJSON line, terminator included. */
+export declare function toNdjsonLine(event: ExecEvent): string;

package/dist/exec/events.js

@@ -0,0 +1,43 @@
+/**
+ * THE CONTRACT (cli-integration-surface section 5.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope
+ * (`glyphs.test.ts::inScope`, R-3 / AC-25). Every string here can reach a
+ * consumer's terminal through `--output-format text` fallbacks or a stderr
+ * warning, and the whole point of the scanner is that a legacy `cmd.exe` shows
+ * mojibake for anything else.
+ *
+ * PURE TYPES AND BUILDERS. No I/O, no process access, no imports outside
+ * `node:`-free type space, so a consumer of this module cannot accidentally
+ * evaluate the runner.
+ *
+ * `EXEC_SCHEMA_VERSION` appears on `system` and on `result` and NOWHERE ELSE.
+ * ADDING A FIELD OR AN EVENT TYPE NEVER BUMPS IT; renaming or removing one does.
+ * That rule only holds if consumers keep their side of it, so the README states
+ * it in the same words: ignore event types you do not know, ignore fields you do
+ * not know. Without that contract the version would have to move for every
+ * additive change and every wrapper would pin an exact number forever.
+ */
+export const EXEC_SCHEMA_VERSION = 1;
+export function buildInitEvent(params) {
+    return {
+        type: 'system',
+        subtype: 'init',
+        schemaVersion: EXEC_SCHEMA_VERSION,
+        sessionId: params.sessionId,
+        cli: params.cli,
+        cwd: params.cwd,
+        startedAt: params.startedAt,
+        model: params.model,
+        permissionMode: params.permissionMode,
+        tools: params.tools,
+        resumed: params.resumed,
+    };
+}
+export function buildResultEvent(params) {
+    return { type: 'result', schemaVersion: EXEC_SCHEMA_VERSION, ...params };
+}
+/** Serialize one event as an NDJSON line, terminator included. */
+export function toNdjsonLine(event) {
+    return `${JSON.stringify(event)}\n`;
+}