@aragon-agent/cli 0.6.37 → 0.6.39

package/dist/exec/hooks/validate.js

@@ -0,0 +1,310 @@
+/**
+ * Validating untrusted hook frames (headless-threads-and-lifecycle-hooks section 2.4.3).
+ *
+ * ASCII ONLY - `src/exec/**` is inside the glyph scanner's scope.
+ *
+ * PURE, AND THAT IS THE POINT. `hook_register` and `hook_answer` arrive from a pipe, so
+ * every field is `unknown` until something says otherwise. This module is that
+ * something, and it is the ONLY reader (I-H7): a second validator somewhere else would
+ * mean an answer that is legal in one path and illegal in another, which is worse than
+ * having no validator at all.
+ *
+ * EVERY REFUSAL IS A STABLE CODE, NEVER A SILENT CORRECTION. The two exceptions are
+ * deliberate and both are documented where they happen: an out-of-range `timeoutMs` is
+ * clamped (with a warning on the ack) because the caller asked for a bounded round trip
+ * and got a smaller one, and a missing `tools` defaults to `['*']` because "every tool"
+ * is the only sensible reading of an absent filter.
+ */
+import { HOOK_LIMITS, HOOK_POINTS, isHookPoint, } from './limits.js';
+const CODE_UNKNOWN_POINT = 'unknown_hook_point';
+const CODE_UNKNOWN_TOOL = 'unknown_tool';
+const CODE_INVALID = 'hook_invalid_answer';
+/**
+ * Whole-frame validation: ALL specs are accepted or the frame is refused.
+ *
+ * PARTIAL SUCCESS IS UNIMPOSSIBLE TO DEBUG. A caller that sent six hooks and got
+ * `accepted:true` with two of them silently dropped has no way to tell which two, and
+ * the failure it causes later ("the redactor did not run for read_file") looks exactly
+ * like a bug in the caller's own matcher.
+ */
+export function validateHookSpecs(raw, options) {
+    const specs = [];
+    const warnings = [];
+    for (let index = 0; index < raw.length; index += 1) {
+        const entry = raw[index];
+        if (!entry || typeof entry !== 'object' || Array.isArray(entry)) {
+            return {
+                ok: false,
+                code: CODE_INVALID,
+                message: `hooks[${index}] must be an object with a "point".`,
+            };
+        }
+        const record = entry;
+        if (!isHookPoint(record.point)) {
+            return {
+                ok: false,
+                code: CODE_UNKNOWN_POINT,
+                message: `hooks[${index}].point must be one of ${HOOK_POINTS.join(', ')}; ` +
+                    `got ${JSON.stringify(record.point)}.`,
+            };
+        }
+        const tools = normaliseTools(record.tools, index);
+        if ('code' in tools)
+            return { ok: false, code: tools.code, message: tools.message };
+        for (const tool of tools.tools) {
+            if (tool === '*')
+                continue;
+            if (options.knownTools.has(tool))
+                continue;
+            return {
+                ok: false,
+                code: CODE_UNKNOWN_TOOL,
+                message: `hooks[${index}].tools names "${tool}", which is not a tool this run can call. ` +
+                    'Use "*" to match every tool.',
+            };
+        }
+        const timeout = normaliseTimeout(record.timeoutMs, index, warnings);
+        specs.push({
+            point: record.point,
+            ...(typeof record.name === 'string' && record.name.trim().length > 0
+                ? { name: record.name.trim() }
+                : {}),
+            tools: tools.tools,
+            timeoutMs: timeout,
+        });
+    }
+    return { ok: true, specs, warnings };
+}
+function normaliseTools(value, index) {
+    if (value === undefined)
+        return { tools: ['*'] };
+    if (!Array.isArray(value)) {
+        return { code: CODE_INVALID, message: `hooks[${index}].tools must be an array of names.` };
+    }
+    const names = [];
+    for (const item of value) {
+        if (typeof item !== 'string' || item.trim().length === 0) {
+            return { code: CODE_INVALID, message: `hooks[${index}].tools must hold non-empty strings.` };
+        }
+        const name = item.trim();
+        if (!names.includes(name))
+            names.push(name);
+    }
+    return { tools: names.length > 0 ? names : ['*'] };
+}
+/**
+ * CLAMP, DO NOT REFUSE, and say so.
+ *
+ * A timeout outside the window describes a round trip the caller wants bounded, so the
+ * nearest legal bound is what they asked for; refusing the whole registration would
+ * leave the run with no hook at all over a number that only shapes a wait. The warning
+ * on the ack is what keeps the clamping honest.
+ */
+function normaliseTimeout(value, index, warnings) {
+    if (value === undefined)
+        return HOOK_LIMITS.defaultTimeoutMs;
+    if (typeof value !== 'number' || !Number.isFinite(value)) {
+        warnings.push(`hooks[${index}].timeoutMs was not a number; using ${HOOK_LIMITS.defaultTimeoutMs}.`);
+        return HOOK_LIMITS.defaultTimeoutMs;
+    }
+    const ms = Math.round(value);
+    if (ms < HOOK_LIMITS.minTimeoutMs) {
+        warnings.push(`hooks[${index}].timeoutMs raised to ${HOOK_LIMITS.minTimeoutMs}.`);
+        return HOOK_LIMITS.minTimeoutMs;
+    }
+    if (ms > HOOK_LIMITS.maxTimeoutMs) {
+        warnings.push(`hooks[${index}].timeoutMs lowered to ${HOOK_LIMITS.maxTimeoutMs}.`);
+        return HOOK_LIMITS.maxTimeoutMs;
+    }
+    return ms;
+}
+/**
+ * THE FOUR POINTS' LEGAL ACTIONS, ENFORCED HERE AND NOWHERE ELSE.
+ *
+ * A single `validateHookAnswer(point, raw)` rather than four validators, because the
+ * frame is one shape and the point is a property of the request the CLI made - so the
+ * caller never has to restate which point it is answering.
+ */
+export function validateHookAnswer(point, raw) {
+    if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+        return { ok: false, code: CODE_INVALID, message: 'A hook answer must be an object.' };
+    }
+    const record = raw;
+    const action = typeof record.action === 'string' ? record.action : '';
+    switch (point) {
+        case 'prompt_pre':
+            return validatePromptPre(action, record);
+        case 'turn_start':
+            return validateTurnStart(action, record);
+        case 'tool_pre':
+            return validateToolPre(action, record);
+        case 'tool_post':
+            return validateToolPost(action, record);
+        default:
+            return { ok: false, code: CODE_INVALID, message: `Unknown hook point "${String(point)}".` };
+    }
+}
+function denyAnswer(record) {
+    const reason = clipReason(record.reason);
+    const message = clipReason(record.message);
+    return {
+        ok: true,
+        answer: {
+            action: 'deny',
+            ...(reason ? { reason } : {}),
+            ...(message ? { message } : {}),
+        },
+    };
+}
+function validatePromptPre(action, record) {
+    if (action === 'allow')
+        return { ok: true, answer: { action: 'allow' } };
+    if (action === 'deny')
+        return denyAnswer(record);
+    if (action !== 'rewrite')
+        return wrongAction('prompt_pre', 'allow, rewrite, deny', action);
+    const text = typeof record.text === 'string' ? record.text : '';
+    // AN EMPTY REWRITE IS INVALID, NOT AN EMPTY PROMPT: Core rejects an empty user message
+    // with a provider 400, which is the hardest class of failure to attribute after the
+    // fact (section 2.4.7).
+    if (text.trim().length === 0) {
+        return { ok: false, code: CODE_INVALID, message: 'A prompt_pre rewrite needs non-empty text.' };
+    }
+    if (text.length > HOOK_LIMITS.maxInjectChars) {
+        return {
+            ok: false,
+            code: CODE_INVALID,
+            message: `A prompt_pre rewrite may carry at most ${HOOK_LIMITS.maxInjectChars} characters.`,
+        };
+    }
+    return { ok: true, answer: { action: 'rewrite', text } };
+}
+function validateTurnStart(action, record) {
+    if (action === 'allow')
+        return { ok: true, answer: { action: 'allow' } };
+    if (action !== 'inject')
+        return wrongAction('turn_start', 'allow, inject', action);
+    const text = typeof record.text === 'string' ? record.text.trim() : '';
+    if (text.length === 0) {
+        return { ok: false, code: CODE_INVALID, message: 'A turn_start inject needs non-empty text.' };
+    }
+    if (text.length > HOOK_LIMITS.maxInjectChars) {
+        return {
+            ok: false,
+            code: CODE_INVALID,
+            message: `A turn_start inject may carry at most ${HOOK_LIMITS.maxInjectChars} characters.`,
+        };
+    }
+    return { ok: true, answer: { action: 'inject', text } };
+}
+function validateToolPre(action, record) {
+    if (action === 'allow')
+        return { ok: true, answer: { action: 'allow' } };
+    if (action === 'deny')
+        return denyAnswer(record);
+    if (action !== 'rewrite')
+        return wrongAction('tool_pre', 'allow, rewrite, deny', action);
+    const input = record.input;
+    if (!input || typeof input !== 'object' || Array.isArray(input)) {
+        return {
+            ok: false,
+            code: CODE_INVALID,
+            message: 'A tool_pre rewrite needs a JSON object "input".',
+        };
+    }
+    // THE TOOL'S OWN SCHEMA IS NOT CHECKED HERE. `wrapWithToolHooks` re-validates against
+    // `tool.parameters` at the point of use, because that is the only place the tool object
+    // exists - and an edit that passes this check and fails that one must be reported as
+    // `invalid`, which the wrapper does (I-H3).
+    return { ok: true, answer: { action: 'rewrite', input: input } };
+}
+function validateToolPost(action, record) {
+    if (action === 'keep')
+        return { ok: true, answer: { action: 'keep' } };
+    if (action === 'deny')
+        return denyAnswer(record);
+    if (action !== 'replace')
+        return wrongAction('tool_post', 'keep, replace, deny', action);
+    if (record.content === undefined) {
+        return { ok: false, code: CODE_INVALID, message: 'A tool_post replace needs "content".' };
+    }
+    // A PART LIST IS HISTORY, SO ITS SHAPE IS PART OF THE ANSWER'S VALIDITY.
+    //
+    // `content` becomes the `tool_result` the model reads, and it is persisted with the
+    // session: a part without a `type` produces a provider 400 on the NEXT request, and a
+    // resumed session keeps producing it. Attributing that to the model - which is what an
+    // unchecked answer does - is the one hole I-H7 cannot afford, so the shape is checked
+    // here, once, with the same `hook_invalid_answer` code as every other illegal answer.
+    if (Array.isArray(record.content)) {
+        for (const part of record.content) {
+            if (!part || typeof part !== 'object' || Array.isArray(part)) {
+                return {
+                    ok: false,
+                    code: CODE_INVALID,
+                    message: 'A tool_post replace content array must hold content-block objects.',
+                };
+            }
+            const type = part.type;
+            if (typeof type !== 'string' || type.trim().length === 0) {
+                return {
+                    ok: false,
+                    code: CODE_INVALID,
+                    message: 'Every content block in a tool_post replace needs a non-empty "type".',
+                };
+            }
+        }
+    }
+    const chars = contentChars(record.content);
+    if (chars > HOOK_LIMITS.maxContentChars) {
+        return {
+            ok: false,
+            code: CODE_INVALID,
+            message: `A tool_post replace may carry at most ${HOOK_LIMITS.maxContentChars} characters.`,
+        };
+    }
+    return {
+        ok: true,
+        answer: {
+            action: 'replace',
+            content: record.content,
+            ...(record.isError === true ? { isError: true } : {}),
+        },
+    };
+}
+function wrongAction(point, allowed, action) {
+    return {
+        ok: false,
+        code: CODE_INVALID,
+        message: `${point} accepts ${allowed}; got ${JSON.stringify(action)}.`,
+    };
+}
+/** Total characters in a content value, whether it is a string or a part list. */
+function contentChars(content) {
+    if (typeof content === 'string')
+        return content.length;
+    if (Array.isArray(content)) {
+        let total = 0;
+        for (const part of content) {
+            const text = part?.text;
+            if (part && typeof part === 'object' && typeof text === 'string') {
+                total += (part.text).length;
+            }
+            else {
+                total += JSON.stringify(part ?? null).length;
+            }
+        }
+        return total;
+    }
+    return JSON.stringify(content ?? null).length;
+}
+/** Bound the one caller-supplied string that becomes MODEL-VISIBLE (I-H2's sibling). */
+export function clipReason(value) {
+    if (typeof value !== 'string')
+        return undefined;
+    const trimmed = value.trim();
+    if (trimmed.length === 0)
+        return undefined;
+    return trimmed.length <= HOOK_LIMITS.maxReasonChars
+        ? trimmed
+        : trimmed.slice(0, HOOK_LIMITS.maxReasonChars);
+}

package/dist/exec/index.d.ts

@@ -20,6 +20,75 @@ 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';
+import type { AgentTool } from '@aragon-agent/core';
+import type { ApprovalGate } from '../skills/service.js';
+import type { HumanInputGate } from '../tools/human-input.js';
+import type { ToolGate } from '../tools/tool-gate.js';
+import type { ToolHookRunner } from './hooks/tool-wrapper.js';
+/**
+ * Everything `aragon exec` may hand the controller factory.
+ *
+ * THE THREE GATES ARE OPTIONAL AND ABSENT IN EVERY MODE BUT BRIDGE, which is the
+ * rule that keeps the tool array identical by object identity for `-p`, the TUI
+ * and every subagent (I-1). `cli.tsx` decides nothing here; it spreads what it is
+ * given.
+ */
+export interface ExecControllerDeps {
+    permission?: ToolPermission;
+    appendSystemPrompt?: string;
+    /** The per-call approval gate; bridge only. */
+    toolGate?: ToolGate;
+    /** `skill_install` approval; bridge only. */
+    approval?: ApprovalGate;
+    /** `ask_user` / `submit_plan`; bridge only. */
+    humanInput?: HumanInputGate;
+    /** Added to each gated tool's executor timeout; bridge only. */
+    decisionBudgetMs?: number;
+    /** The gate each subagent gets, keyed by label; bridge only (section 2.3.7). */
+    toolGateForChild?: (label: string) => ToolGate;
+    /** Caller-served tools registered at construction; bridge only. */
+    callerTools?: AgentTool[];
+    /**
+     * `submit_result`, or absent (headless-request-scope-and-typed-result section 2.6
+     * row 11). Decided by `--result-schema` alone, NOT by bridge mode: a `json` run can
+     * carry a schema too, and there is no second request to scope it to.
+     */
+    resultTool?: AgentTool;
+    /** The `<structured_result>` block that tells the model the contract exists. */
+    structuredResultBlock?: string;
+    /**
+     * The caller's lifecycle hooks (headless-threads-and-lifecycle-hooks section 2.4.9).
+     *
+     * BRIDGE ONLY, and always present there even before `hook_register` arrives: the tool
+     * array is built once, at controller construction, while hooks are registered later.
+     */
+    hookRunner?: ToolHookRunner;
+    /**
+     * Set by the thread runtime, and read by `makeExecController` alone
+     * (section 2.3.4): non-`undefined` means "this controller is one of N".
+     */
+    threadId?: string;
+    /**
+     * WHETHER THIS CONSTRUCTION OWNS THE PROCESS-LEVEL LOG MOUNTS (review P1-8).
+     *
+     * `threadId` is the WRONG signal for that decision, because the default thread has an id
+     * too (`main`) - a guard on "is there a thread id" therefore skipped the mount for every
+     * thread, leaving a thread-mode run with no `run_exec` line, no `onFailure` handler (a
+     * failing log write becomes silent) and no untrusted-skill warning. Exactly ONE caller
+     * sets this: the runtime that opens the default thread. `undefined` means "single-run
+     * invocation", which owns them by definition.
+     */
+    processLevelMounts?: boolean;
+    /**
+     * Receives the two disposers `makeExecController` got back from
+     * `attachAgentEvents` / `attachTeamEvents`.
+     *
+     * A CALLBACK RATHER THAN A RETURN VALUE because the factory's signature is a port
+     * (`cli.tsx` implements it) and this round must not change that signature. Interactive
+     * callers pass nothing, which leaves their behaviour byte-identical.
+     */
+    onAttach?: (disposers: Array<() => void>) => void;
+}
 /**
  * How `runExec` obtains a controller.
  *
@@ -29,10 +98,34 @@ import { type ToolPermission } from './permission.js';
  * 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;
+/**
+ * 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.
+ */
+/**
+ * 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.
+ */
+/**
+ * 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: ExecControllerDeps) => AgentController;
 export interface RunExecContext {
     version: string;
     makeController: ExecControllerFactory;
@@ -54,3 +147,36 @@ export interface RunExecContext {
  * 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>;
+/**
+ * What thread mode needs, and why it is not an `ExecPromptSource`
+ * (headless-threads-and-lifecycle-hooks section 4.3, review P1-3).
+ *
+ * A PRE-BUILT SOURCE HAS ALREADY ATTACHED ITS STDIN LISTENERS. Handing one to a thread run
+ * would put two splitters on the same bytes and the frames after the first newline would
+ * land in whichever was registered first, so `execute()` refuses the combination and this
+ * type carries the STREAM instead.
+ */
+export interface ThreadsInput {
+    /** The raw stdin. The thread dispatcher is its only parser. */
+    stdin: NodeJS.ReadableStream;
+}
+/**
+ * Persist one thread's session, for thread mode.
+ *
+ * A THIN WRAPPER OVER `persist()`, and deliberately not a second implementation: the file
+ * shape, the cumulative counters and the "a failed write is not a failed run" rule are one
+ * set of decisions. Threads never resume (section 1.4), so there is no previous metadata to
+ * accumulate onto; `--resume` stays a process-level, default-thread feature.
+ */
+export declare function persistThreadSession(input: {
+    sessionId: string;
+    controller: AgentController;
+    turns: number;
+    usage: {
+        inputTokens: number;
+        outputTokens: number;
+    };
+    at: number;
+    cli: string;
+    cwd: string;
+}): void;