@aragon-agent/cli 0.5.12 → 0.6.2

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`;
+}

package/dist/exec/index.d.ts

@@ -0,0 +1,56 @@
+/**
+ * `aragon exec` - wiring only (cli-integration-surface section 3.3 / 6.1).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * NO PROCESS-GLOBAL STATE, AND THAT IS A RULE RATHER THAN A HABIT (section 2.2).
+ * A programmatic Node API is the deferral most likely to be asked for first, and
+ * the only thing that makes it cheap later is `runExec()` holding nothing the
+ * process owns: the controller arrives through a factory, both streams are
+ * parameters, and the exit code is RETURNED rather than assigned.
+ *
+ * THE CONTROLLER COMES FROM A FACTORY BECAUSE `makeController` LIVES IN
+ * `cli.tsx` (see the note on `ExecControllerFactory`). Reaching for it directly
+ * would make `cli.tsx -> exec/cli-commands.ts -> exec/index.ts -> cli.tsx` a
+ * cycle, and duplicating it here would give the headless approval gates a second
+ * definition - the one thing `makeController`'s own comment says must not
+ * happen.
+ */
+import type { AgentController } from '../agent/controller.js';
+import { type CliFlags } from '../config/load.js';
+import { type RawExecOptions } from './options.js';
+import { type ToolPermission } from './permission.js';
+/**
+ * How `runExec` obtains a controller.
+ *
+ * `cli.tsx` supplies `(flags, deps) => makeController(flags, { interactive:
+ * false, ...deps }).controller`, already wired for headless: the deny-all
+ * approval gate, the deny-all human-input gate, the log attachments and the
+ * untrusted-skill notices. Everything this module needs and nothing it should
+ * decide for itself.
+ */
+export type ExecControllerFactory = (flags: CliFlags, deps: {
+    permission?: ToolPermission;
+    appendSystemPrompt?: string;
+}) => AgentController;
+export interface RunExecContext {
+    version: string;
+    makeController: ExecControllerFactory;
+    stdout?: NodeJS.WritableStream;
+    stderr?: NodeJS.WritableStream;
+    stdin?: NodeJS.ReadableStream;
+    /** Injected by tests so a run never touches the real clock. */
+    now?: () => number;
+}
+/**
+ * Run one `aragon exec` invocation and resolve with the process exit code.
+ *
+ * EXIT 2 MEANS THE RUN NEVER STARTED, AND STDOUT CARRIES NOTHING ON THAT PATH.
+ * Option errors, prompt errors and session errors are all reported on stderr
+ * alone: emitting a lone `result` line for them would break the guarantee
+ * `system/init` is the FIRST stream-json line (AC-5), and a wrapper that got a
+ * `result` without an `init` could not tell a run that failed to start from one
+ * that failed. A preflight failure is different - the format is settled and the
+ * schema has begun - so that one DOES emit a `result` with `exitCode: 2`.
+ */
+export declare function runExec(flags: CliFlags, raw: RawExecOptions, promptArg: string | undefined, ctx: RunExecContext): Promise<number>;