@aragon-agent/cli 0.5.12 → 0.6.2

package/dist/diagnostics/doctor.js

@@ -0,0 +1,207 @@
+/**
+ * `aragon doctor` - "is this machine configured to run me?", in one exit code
+ * (cli-integration-surface section 4.3).
+ *
+ * ASCII ONLY - `src/diagnostics/**` is inside the glyph scanner's scope.
+ *
+ * EVERY CHECK CARRIES A ONE-LINE REMEDY, and only `fail` affects the exit code.
+ * A `warn` that failed the command would make the command useless on the many
+ * machines where something is unusual but working; a `fail` with no remedy makes
+ * the caller guess, which is the state this command exists to end.
+ */
+import { existsSync, mkdirSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import process from 'node:process';
+import { initProviders, ModelRegistry } from '@aragon-agent/core';
+import { getHomeResolutionWarning, getSessionsDir, getUserDataDir } from '../config/app-paths.js';
+import { readConfigFile } from '../config/store.js';
+import { loadConfig, makeGetApiKey } from '../config/load.js';
+import { isAdapterProvider, toRetryPolicy } from '../config/schema.js';
+import { MODE_TOGGLE_KEYS } from '../agent/agent-mode.js';
+import { supportsWindowsVtInput } from '../ui/win-vt-input.js';
+const MIN_NODE_MAJOR = 18;
+export async function runDoctorChecks(flags, opts = {}) {
+    const checks = [checkNode(), ...checkVtInput(), checkHome(), checkConfigFile()];
+    const config = loadConfig(flags);
+    checks.push(checkProviderKey(config));
+    checks.push(checkModel(config));
+    checks.push(checkSessionsDir());
+    if (opts.probe)
+        checks.push(await probeProvider(config));
+    return { ok: checks.every((c) => c.verdict !== 'fail'), checks };
+}
+function pass(name, detail) {
+    return { name, verdict: 'pass', detail, remedy: '' };
+}
+function checkNode() {
+    const major = Number.parseInt(process.versions.node.split('.')[0] ?? '0', 10);
+    if (major >= MIN_NODE_MAJOR)
+        return pass('node', `v${process.versions.node}`);
+    return {
+        name: 'node',
+        verdict: 'fail',
+        detail: `v${process.versions.node} is below the supported floor`,
+        remedy: `Install Node ${MIN_NODE_MAJOR} or newer.`,
+    };
+}
+/**
+ * Whether this console can deliver `Shift+Tab`
+ * (shift-tab-mode-toggle-still-dead-on-windows, C3-2).
+ *
+ * `MIN_NODE_MAJOR` STAYS AT 18 and this is a separate check on purpose. The
+ * install floor is about whether aragon runs; this is about one key, and raising
+ * the floor to 22.17 would lock out a large, otherwise perfectly healthy Node 20
+ * population over it.
+ *
+ * `warn`, never `fail`: aragon turns the console bit on itself at startup, and
+ * `MODE_TOGGLE_KEYS.fallback` works whether or not that succeeded, so nothing
+ * here is actually broken - the exit code must not say it is.
+ *
+ * WHY IT EXISTS AT ALL: `checkNode` passes every version this bug affects, so a
+ * user whose mode toggle is dead ran the tool built to explain their machine and
+ * was told it was fine (analysis section 3.7). A diagnostic that is confidently
+ * wrong is worse than one that is silent - it ends the investigation.
+ *
+ * Returned as a list so the row simply does not exist off Windows, where there
+ * is no such thing as a console input mode to report on.
+ */
+function checkVtInput() {
+    if (process.platform !== 'win32')
+        return [];
+    if (supportsWindowsVtInput(process.platform, process.versions.node)) {
+        return [pass('vt-input', `v${process.versions.node} delivers Shift+Tab and mouse reports`)];
+    }
+    return [
+        {
+            name: 'vt-input',
+            verdict: 'warn',
+            detail: `Node v${process.versions.node} never enables ENABLE_VIRTUAL_TERMINAL_INPUT, so this ` +
+                'console reports Shift+Tab as a plain Tab and sends no mouse events',
+            remedy: `aragon turns that bit on at startup; if a policy blocks it, ${MODE_TOGGLE_KEYS.fallback} ` +
+                'and /plan toggle the mode too. Node 22.17+ (or 24.2+) removes the problem.',
+        },
+    ];
+}
+function checkHome() {
+    const home = getUserDataDir();
+    const warning = getHomeResolutionWarning();
+    try {
+        if (!existsSync(home))
+            mkdirSync(home, { recursive: true });
+        const probe = join(home, '.doctor-write-probe');
+        writeFileSync(probe, 'ok', 'utf-8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        return {
+            name: 'home',
+            verdict: 'fail',
+            detail: `${home} is not writable (${err.message})`,
+            remedy: 'Fix the permissions, or point ARAGON_HOME at a directory you own.',
+        };
+    }
+    if (warning) {
+        return {
+            name: 'home',
+            verdict: 'warn',
+            detail: `${home} (${warning})`,
+            remedy: 'Set ARAGON_HOME to an absolute path if this is not where you want state kept.',
+        };
+    }
+    return pass('home', home);
+}
+function checkConfigFile() {
+    const { parseError } = readConfigFile();
+    if (!parseError)
+        return pass('config', 'parses');
+    return {
+        name: 'config',
+        verdict: 'warn',
+        detail: `using defaults, could not parse ${parseError}`,
+        remedy: 'Run `aragon config edit` and fix the JSON, or delete the file to start over.',
+    };
+}
+function checkProviderKey(config) {
+    const key = makeGetApiKey(config)(config.provider);
+    if (key)
+        return pass('api-key', `resolved for ${config.provider}`);
+    return {
+        name: 'api-key',
+        verdict: 'fail',
+        detail: `no API key for provider "${config.provider}"`,
+        remedy: `Run \`aragon config\` and add one, or set the provider's key in the environment.`,
+    };
+}
+function checkModel(config) {
+    if (!isAdapterProvider(config.provider)) {
+        return {
+            name: 'model',
+            verdict: 'fail',
+            detail: `unknown provider "${config.provider}"`,
+            remedy: 'Run `aragon models` to see the providers this build supports.',
+        };
+    }
+    const registry = new ModelRegistry(initProviders({ retryPolicy: toRetryPolicy(config.retry) }));
+    const known = registry.getModels(config.provider).some((m) => m.id === config.model);
+    if (known)
+        return pass('model', `${config.provider}/${config.model}`);
+    // WARN, NOT FAIL. The registry is a builtin list plus whatever an account can
+    // discover, so a model it does not know is frequently one this account has and
+    // the shipped table does not - the cost table is unknown, the run is fine.
+    return {
+        name: 'model',
+        verdict: 'warn',
+        detail: `${config.provider}/${config.model} is not in the builtin registry`,
+        remedy: 'Run `aragon models` to list what this key can reach; cost reporting will be off.',
+    };
+}
+function checkSessionsDir() {
+    const dir = getSessionsDir();
+    try {
+        if (!existsSync(dir))
+            mkdirSync(dir, { recursive: true });
+        const probe = join(dir, '.doctor-write-probe');
+        writeFileSync(probe, 'ok', 'utf-8');
+        unlinkSync(probe);
+    }
+    catch (err) {
+        return {
+            name: 'sessions',
+            verdict: 'fail',
+            detail: `${dir} is not writable (${err.message})`,
+            remedy: 'Fix the permissions, or run `aragon exec --no-save-session`.',
+        };
+    }
+    return pass('sessions', dir);
+}
+/**
+ * `--probe`: one minimal API call.
+ *
+ * MODEL DISCOVERY IS THE CHEAPEST HONEST PROBE. It exercises the base URL, the
+ * key and the TLS chain - which is the whole of what "can this machine reach the
+ * provider" means - without spending a single completion token.
+ */
+async function probeProvider(config) {
+    const key = makeGetApiKey(config)(config.provider);
+    if (!key || !isAdapterProvider(config.provider)) {
+        return {
+            name: 'probe',
+            verdict: 'warn',
+            detail: 'skipped: no key or unknown provider',
+            remedy: 'Fix the api-key check above, then run `aragon doctor --probe` again.',
+        };
+    }
+    const registry = new ModelRegistry(initProviders({ retryPolicy: toRetryPolicy(config.retry) }));
+    try {
+        const models = await registry.discoverModels(config.provider, key, config.baseUrl);
+        return pass('probe', `${config.provider} answered with ${models.length} model(s)`);
+    }
+    catch (err) {
+        return {
+            name: 'probe',
+            verdict: 'fail',
+            detail: `${config.provider} did not answer (${err.message})`,
+            remedy: 'Check the key, the base URL and any proxy between this machine and the provider.',
+        };
+    }
+}

package/dist/diagnostics/info.d.ts

@@ -0,0 +1,30 @@
+/**
+ * `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 { type CliFlags } from '../config/load.js';
+export interface ExecInfo {
+    cli: string;
+    core: string;
+    node: string;
+    schemaVersion: number;
+    home: string;
+    configPath: string;
+    sessionsDir: string;
+    provider: string;
+    model: string;
+    hasApiKey: boolean;
+    tools: string[];
+    outputFormats: string[];
+    inputFormats: string[];
+    permissionModes: string[];
+    features: string[];
+}
+export declare function buildInfo(flags: CliFlags, version: string): ExecInfo;

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();
+}