@aragon-agent/cli 0.5.0 → 0.5.2

package/dist/logging/logger.js

@@ -0,0 +1,237 @@
+/**
+ * The logger: level filtering, record shape, redaction, and the module-level
+ * singleton every other file reaches through `getLogger()`.
+ *
+ * WIRE FORMAT — one `JSON.stringify(record)` per line, UTF-8, no BOM:
+ *
+ *   {"ts":"2026-07-27T12:11:02.913+08:00","lv":"info","sid":"7f3a91c2",
+ *    "pid":24188,"scope":"agent","msg":"turn_end",
+ *    "data":{"provider":"anthropic","in":1284,"out":377,"ms":4210}}
+ *
+ * THE SHORT KEYS ARE DELIBERATE AND MUST NOT BE "FIXED". The package's clean-code
+ * guide forbids names like `data`, and rightly so for TypeScript identifiers.
+ * These are not identifiers: they are the on-disk contract, repeated on every
+ * line of a file that reaches megabytes, and already parsed by whatever `jq`
+ * one-liner a user has written. Renaming them breaks every existing log and
+ * every existing script for a readability gain nobody experiences. Variable and
+ * function names in this file get no such exemption.
+ *
+ * `sid` and `pid` both exist because several `aragon` processes append to the
+ * same day's file: `sid` separates their interleaved lines, and `pid` is what
+ * still matches up with what the OS recorded after a crash.
+ */
+import { randomUUID } from 'node:crypto';
+import { join } from 'node:path';
+import process from 'node:process';
+import { getLogsDir } from '../config/app-paths.js';
+import { FileSink, currentLogFileName } from './file-sink.js';
+import { isLevelEnabled } from './levels.js';
+import { redactRecord } from './redact.js';
+import { getSecrets } from './secret-registry.js';
+const DISABLED_CONFIG = {
+    level: 'silent',
+    toFile: false,
+    dir: '',
+    maxFileBytes: 5 * 1024 * 1024,
+    maxFiles: 10,
+    redactSecrets: true,
+    previewChars: 512,
+};
+/**
+ * ISO 8601 with the LOCAL offset, matching the local date in the file name.
+ * `toISOString()` would put an evening record west of UTC into the next day
+ * while the file it lands in is named for the previous one.
+ */
+export function localIsoTimestamp(date = new Date()) {
+    const pad = (n, width = 2) => String(n).padStart(width, '0');
+    const offsetMinutes = -date.getTimezoneOffset();
+    const sign = offsetMinutes >= 0 ? '+' : '-';
+    const abs = Math.abs(offsetMinutes);
+    return (`${date.getFullYear()}-${pad(date.getMonth() + 1)}-${pad(date.getDate())}` +
+        `T${pad(date.getHours())}:${pad(date.getMinutes())}:${pad(date.getSeconds())}` +
+        `.${pad(date.getMilliseconds(), 3)}${sign}${pad(Math.floor(abs / 60))}:${pad(abs % 60)}`);
+}
+export class Logger {
+    config;
+    sink = null;
+    sid = randomUUID().slice(0, 8);
+    failureHandler = null;
+    constructor(config = DISABLED_CONFIG) {
+        this.config = { ...config };
+    }
+    error(scope, msg, data) {
+        this.emit('error', scope, msg, data);
+    }
+    warn(scope, msg, data) {
+        this.emit('warn', scope, msg, data);
+    }
+    info(scope, msg, data) {
+        this.emit('info', scope, msg, data);
+    }
+    debug(scope, msg, data) {
+        this.emit('debug', scope, msg, data);
+    }
+    trace(scope, msg, data) {
+        this.emit('trace', scope, msg, data);
+    }
+    child(scope) {
+        return {
+            error: (msg, data) => this.error(scope, msg, data),
+            warn: (msg, data) => this.warn(scope, msg, data),
+            info: (msg, data) => this.info(scope, msg, data),
+            debug: (msg, data) => this.debug(scope, msg, data),
+            trace: (msg, data) => this.trace(scope, msg, data),
+        };
+    }
+    /** Whether a record at `level` would be written — lets callers skip the work. */
+    isEnabled(level) {
+        return isLevelEnabled(level, this.config.level);
+    }
+    /** Truncation budget for user content at `debug`. `trace` ignores it. */
+    get previewChars() {
+        return this.config.previewChars;
+    }
+    get level() {
+        return this.config.level;
+    }
+    setLevel(level) {
+        this.config = { ...this.config, level };
+    }
+    /**
+     * THE authoritative-level hand-off (§4.4.5).
+     *
+     * `installLogging()` resolves a bootstrap level from `process.env`, the config
+     * file and a tiny argv scan, because it has to run before commander exists and
+     * before `loadDotenv()`. That bootstrap level covers migrations and early
+     * crashes and nothing else. Once `loadConfig()` has produced the real answer,
+     * every path calls this exactly once. Without it the fully-resolved level —
+     * including anything from `.env` — would simply never take effect.
+     *
+     * Idempotent, and safe after writing has already begun.
+     */
+    reconfigure(config) {
+        this.config = { ...config };
+        if (!this.sink)
+            return;
+        if (!config.toFile) {
+            this.sink.close();
+            this.sink = null;
+            return;
+        }
+        // `FileSink.reconfigure` handles a changed directory itself: it flushes and
+        // closes, and the next record lazily opens the new one.
+        this.sink.reconfigure(this.sinkOptions());
+    }
+    /** Registered by whoever owns a user-visible channel (toast, or stderr). */
+    onFailure(cb) {
+        this.failureHandler = cb;
+    }
+    /** Idempotent; `exit`, the signal hook and the crash hooks all call it. */
+    flushSync() {
+        this.sink?.flushSync();
+    }
+    /**
+     * Where records are going, for `aragon logs path`.
+     *
+     * Answers with a FILE path even before the sink has been created — the
+     * question is "where would I look?", and a bare directory is not that answer.
+     */
+    currentLogPath() {
+        if (this.sink)
+            return this.sink.currentPath;
+        return join(this.resolveDir(this.config), currentLogFileName());
+    }
+    get sinkError() {
+        return this.sink?.lastError;
+    }
+    get sinkDisabled() {
+        return this.sink?.disabled ?? false;
+    }
+    /** Closes the fd so a caller may delete the files (`aragon logs clear`). */
+    closeSink() {
+        this.sink?.close();
+        this.sink = null;
+    }
+    // -------------------------------------------------------------------------
+    // Internals
+    // -------------------------------------------------------------------------
+    emit(level, scope, msg, data) {
+        if (!isLevelEnabled(level, this.config.level))
+            return;
+        if (!this.config.toFile)
+            return;
+        const record = {
+            ts: localIsoTimestamp(),
+            lv: level,
+            sid: this.sid,
+            pid: process.pid,
+            scope,
+            msg,
+            // An empty `data` is omitted rather than written as `{}` — noise on every
+            // line of a file measured in megabytes.
+            ...(data && Object.keys(data).length > 0 ? { data } : {}),
+        };
+        const safe = this.config.redactSecrets ? redactRecord(record, getSecrets()) : record;
+        this.ensureSink()?.write(`${JSON.stringify(safe)}\n`);
+    }
+    resolveDir(config) {
+        return config.dir.trim().length > 0 ? config.dir : getLogsDir();
+    }
+    sinkOptions() {
+        return {
+            dir: this.resolveDir(this.config),
+            maxFileBytes: this.config.maxFileBytes,
+            maxFiles: this.config.maxFiles,
+            formatDropNotice: (count) => this.renderDropNotice(count),
+            onFailure: (reason) => this.failureHandler?.(reason),
+        };
+    }
+    /**
+     * Created on the FIRST record that actually passes the filters, never in
+     * `installLogging()`. `aragon --version`, `aragon config path` and anyone
+     * running with `--no-log-file` must not leave an empty directory behind.
+     */
+    ensureSink() {
+        if (!this.config.toFile)
+            return null;
+        if (!this.sink)
+            this.sink = new FileSink(this.sinkOptions());
+        return this.sink;
+    }
+    renderDropNotice(count) {
+        const record = {
+            ts: localIsoTimestamp(),
+            lv: 'warn',
+            sid: this.sid,
+            pid: process.pid,
+            scope: 'log',
+            msg: 'records_dropped',
+            data: { count },
+        };
+        return `${JSON.stringify(record)}\n`;
+    }
+}
+// ---------------------------------------------------------------------------
+// Module singleton
+// ---------------------------------------------------------------------------
+/**
+ * The pre-install logger: silent, file-less, allocates nothing.
+ *
+ * Its existence is what lets any module call `getLogger().info(...)`
+ * unconditionally — no null checks scattered across the codebase, and no import
+ * order that can accidentally create a log directory.
+ */
+const NOOP_LOGGER = new Logger(DISABLED_CONFIG);
+let active = null;
+export function getLogger() {
+    return active ?? NOOP_LOGGER;
+}
+/** Called by `installLogging()`; not part of the general API. */
+export function setActiveLogger(logger) {
+    active = logger;
+}
+/** Tests only — returns the singleton to its pre-install state. */
+export function resetLoggerForTest() {
+    active?.closeSink();
+    active = null;
+}

package/dist/logging/redact.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Secret redaction — two passes, both mandatory.
+ *
+ *   1. STRUCTURAL. Walk `data` and blank any value whose KEY looks like a
+ *      credential, whatever the value contains.
+ *   2. TEXTUAL. Scan `msg` and every string leaf for known key formats and for
+ *      every literal in the secret registry.
+ *
+ * Neither pass subsumes the other. Structure alone misses a key pasted into a
+ * URL or echoed back inside an error message. Text alone misses a
+ * custom-endpoint key that matches none of the vendor formats — which is
+ * exactly why the registry backstop exists, and exactly why it must be live
+ * rather than a startup snapshot (see `secret-registry.ts`).
+ *
+ * This module is pure: same input, same output, no I/O, no clock. It is the one
+ * part of the logging subsystem whose correctness can be established outright,
+ * and it guards the one failure that cannot be undone once it reaches disk.
+ */
+import type { LogRecord } from './logger.js';
+export declare const REDACTED = "\u00ABredacted\u00BB";
+export declare const TRUNCATED = "\u00ABtruncated\u00BB";
+export declare function redactText(text: string, secrets: readonly string[]): string;
+/**
+ * Redact a record in place of serialising it raw. Returns a new record; the
+ * caller's object is untouched so a failed write cannot leave a half-redacted
+ * value behind for a retry to publish.
+ */
+export declare function redactRecord(record: LogRecord, secrets: readonly string[]): LogRecord;

package/dist/logging/redact.js

@@ -0,0 +1,90 @@
+/**
+ * Secret redaction — two passes, both mandatory.
+ *
+ *   1. STRUCTURAL. Walk `data` and blank any value whose KEY looks like a
+ *      credential, whatever the value contains.
+ *   2. TEXTUAL. Scan `msg` and every string leaf for known key formats and for
+ *      every literal in the secret registry.
+ *
+ * Neither pass subsumes the other. Structure alone misses a key pasted into a
+ * URL or echoed back inside an error message. Text alone misses a
+ * custom-endpoint key that matches none of the vendor formats — which is
+ * exactly why the registry backstop exists, and exactly why it must be live
+ * rather than a startup snapshot (see `secret-registry.ts`).
+ *
+ * This module is pure: same input, same output, no I/O, no clock. It is the one
+ * part of the logging subsystem whose correctness can be established outright,
+ * and it guards the one failure that cannot be undone once it reaches disk.
+ */
+export const REDACTED = '«redacted»';
+export const TRUNCATED = '«truncated»';
+/** Value keys that are credentials regardless of what they hold. */
+const SECRET_KEY_PATTERN = /(api[-_]?key|token|secret|password|authorization|credential)/i;
+/**
+ * Known key shapes. Anthropic, OpenAI (and compatible endpoints), Google, plus
+ * any `Authorization: Bearer …` header value that survived pass 1.
+ */
+const SECRET_VALUE_PATTERNS = [
+    /sk-ant-[A-Za-z0-9_-]{16,}/g,
+    /sk-[A-Za-z0-9_-]{20,}/g,
+    /AIza[A-Za-z0-9_-]{28,}/g,
+    /Bearer\s+[A-Za-z0-9._~+/-]{16,}=*/g,
+];
+/**
+ * Bounds on the structural walk. A tool result can be an arbitrarily deep and
+ * wide object; without a ceiling, redacting one log record could stall the CLI.
+ * Exceeding either bound yields `«truncated»`, never the raw value.
+ */
+const MAX_DEPTH = 6;
+const MAX_NODES = 500;
+export function redactText(text, secrets) {
+    let out = text;
+    for (const pattern of SECRET_VALUE_PATTERNS) {
+        out = out.replace(pattern, REDACTED);
+    }
+    // `getSecrets()` returns longest-first, so a key that is a prefix of another
+    // cannot leave its tail behind. Split/join rather than a built regex: the
+    // literals are arbitrary and escaping them is one more thing to get wrong.
+    for (const secret of secrets) {
+        if (secret.length > 0 && out.includes(secret))
+            out = out.split(secret).join(REDACTED);
+    }
+    return out;
+}
+function redactValue(value, secrets, depth, budget) {
+    if (depth > MAX_DEPTH)
+        return TRUNCATED;
+    if (budget.nodes <= 0)
+        return TRUNCATED;
+    budget.nodes -= 1;
+    if (typeof value === 'string')
+        return redactText(value, secrets);
+    if (value === null || typeof value !== 'object')
+        return value;
+    if (Array.isArray(value)) {
+        return value.map((item) => redactValue(item, secrets, depth + 1, budget));
+    }
+    const out = {};
+    for (const [key, item] of Object.entries(value)) {
+        out[key] = SECRET_KEY_PATTERN.test(key)
+            ? REDACTED
+            : redactValue(item, secrets, depth + 1, budget);
+    }
+    return out;
+}
+/**
+ * Redact a record in place of serialising it raw. Returns a new record; the
+ * caller's object is untouched so a failed write cannot leave a half-redacted
+ * value behind for a retry to publish.
+ */
+export function redactRecord(record, secrets) {
+    const budget = { nodes: MAX_NODES };
+    const data = record.data
+        ? redactValue(record.data, secrets, 1, budget)
+        : undefined;
+    return {
+        ...record,
+        msg: redactText(record.msg, secrets),
+        ...(data ? { data } : {}),
+    };
+}

package/dist/logging/secret-registry.d.ts

@@ -0,0 +1,30 @@
+/**
+ * The live set of secret literals the redactor must never let reach disk.
+ *
+ * WHY A REGISTRY AND NOT A SNAPSHOT (aragon-home-config-and-logging P0-3):
+ *
+ * The format regexes in `redact.ts` catch the three vendors we know about. This
+ * registry is the backstop for everything else — a custom endpoint whose key
+ * looks like nothing in particular. That backstop only works if it holds the
+ * keys we ACTUALLY have, which is a moving target: `installLogging()` runs
+ * before commander has parsed `--api-key`, and a key the user types into the
+ * settings screen mid-session arrives later still. A set captured at startup
+ * would miss the single most common path by which a key enters the process, and
+ * would miss it silently, because the vendor regexes happen to cover the keys
+ * we test with.
+ *
+ * Process-lifetime, append-only, never serialised, never written anywhere.
+ */
+export declare function registerSecret(value: string | undefined | null): void;
+/** Convenience for the `apiKeys` maps every registration site happens to hold. */
+export declare function registerSecretsFrom(keys: Record<string, string | null | undefined> | undefined): void;
+/**
+ * Every known secret, LONGEST FIRST.
+ *
+ * Order matters: when one key is a prefix of another, replacing the short one
+ * first leaves the remainder of the long one in the file — a partial key is
+ * still a leak, and a more convincing one for being partial.
+ */
+export declare function getSecrets(): readonly string[];
+/** Tests only. Production code has no reason to forget a secret. */
+export declare function clearSecretsForTest(): void;

package/dist/logging/secret-registry.js

@@ -0,0 +1,55 @@
+/**
+ * The live set of secret literals the redactor must never let reach disk.
+ *
+ * WHY A REGISTRY AND NOT A SNAPSHOT (aragon-home-config-and-logging P0-3):
+ *
+ * The format regexes in `redact.ts` catch the three vendors we know about. This
+ * registry is the backstop for everything else — a custom endpoint whose key
+ * looks like nothing in particular. That backstop only works if it holds the
+ * keys we ACTUALLY have, which is a moving target: `installLogging()` runs
+ * before commander has parsed `--api-key`, and a key the user types into the
+ * settings screen mid-session arrives later still. A set captured at startup
+ * would miss the single most common path by which a key enters the process, and
+ * would miss it silently, because the vendor regexes happen to cover the keys
+ * we test with.
+ *
+ * Process-lifetime, append-only, never serialised, never written anywhere.
+ */
+const secrets = new Set();
+/**
+ * Minimum length for a value to count as a secret.
+ *
+ * Registering `"1"` or `"off"` would blank out every occurrence of that
+ * substring in ordinary log text, which destroys the log's usefulness while
+ * protecting nothing.
+ */
+const MIN_SECRET_LENGTH = 8;
+export function registerSecret(value) {
+    if (typeof value !== 'string')
+        return;
+    const trimmed = value.trim();
+    if (trimmed.length < MIN_SECRET_LENGTH)
+        return;
+    secrets.add(trimmed);
+}
+/** Convenience for the `apiKeys` maps every registration site happens to hold. */
+export function registerSecretsFrom(keys) {
+    if (!keys)
+        return;
+    for (const value of Object.values(keys))
+        registerSecret(value);
+}
+/**
+ * Every known secret, LONGEST FIRST.
+ *
+ * Order matters: when one key is a prefix of another, replacing the short one
+ * first leaves the remainder of the long one in the file — a partial key is
+ * still a leak, and a more convincing one for being partial.
+ */
+export function getSecrets() {
+    return [...secrets].sort((a, b) => b.length - a.length);
+}
+/** Tests only. Production code has no reason to forget a secret. */
+export function clearSecretsForTest() {
+    secrets.clear();
+}

package/dist/skills/paths.d.ts

@@ -10,16 +10,14 @@
  * flags), so there is no second mental model to learn.
  */
 import type { SkillScope } from '@aragon-agent/core';
+import { getUserDataDir, getUserSkillsDir } from '../config/app-paths.js';
 export interface SkillRoot {
     dir: string;
     scope: SkillScope;
     /** False for bundled / env / `.claude/skills` — install and remove refuse these. */
     writable: boolean;
 }
-/** `<data>` — the per-user data root. Parent of `skills/`, and where sidecar state lives. */
-export declare function getUserDataDir(): string;
-/** `<data>/skills` — the default install target. */
-export declare function getUserSkillsDir(): string;
+export { getUserDataDir, getUserSkillsDir };
 /** `<data>/skills/.staging` — scratch space for in-flight installs (§8.3). */
 export declare function getStagingDir(): string;
 /** `<data>/skills/.staging/.trash` — where a replaced skill is parked (P1-6). */

package/dist/skills/paths.js

@@ -13,15 +13,13 @@ import { existsSync, realpathSync, statSync } from 'node:fs';
 import { delimiter, dirname, join, resolve, sep } from 'node:path';
 import process from 'node:process';
 import { fileURLToPath } from 'node:url';
-import { appPaths as paths } from '../config/app-paths.js';
-/** `<data>` — the per-user data root. Parent of `skills/`, and where sidecar state lives. */
-export function getUserDataDir() {
-    return paths.data;
-}
-/** `<data>/skills` — the default install target. */
-export function getUserSkillsDir() {
-    return join(paths.data, 'skills');
-}
+import { getUserDataDir, getUserSkillsDir } from '../config/app-paths.js';
+// `<data>` is `~/.aragon-agent` and `<data>/skills` its `skills/` child. Both
+// are defined in `config/app-paths.ts` and only re-exported here: the skill
+// modules (and their test mocks) import them from this path, and two separate
+// definitions of the same directory is the drift this module's header warns
+// about.
+export { getUserDataDir, getUserSkillsDir };
 /** `<data>/skills/.staging` — scratch space for in-flight installs (§8.3). */
 export function getStagingDir() {
     return join(getUserSkillsDir(), '.staging');

package/dist/tools/human-input.d.ts

@@ -0,0 +1,179 @@
+/**
+ * The human-input channel (plan-mode §3.5 / §5.1) — types, the fail-closed
+ * default gate, and the two pure normalizers that repair whatever the model
+ * actually sent.
+ *
+ * Everything here is pure except the type declarations: no Ink, no React, no
+ * `node:*`. `tools/` is inside the glyph scanner's scope, so every literal is
+ * ASCII.
+ *
+ * WHY THE NORMALIZERS ARE THE ONLY AUTHORITY ON THE LIMITS (P0-4). The
+ * model-facing schemas in `plan-tools.ts` declare SHAPE only — `type`,
+ * `required`, `default` — and put every bound in the `description`. They used to
+ * carry `minItems` / `maxItems` / `maxLength`, and that had two failure modes at
+ * once: `ToolExecutor` rejected a six-question call outright with `Invalid
+ * parameters: ...` before any repair could run, wasting a full research turn on
+ * a cosmetic defect; and `ajv` is an OPTIONAL dependency of core, so without it
+ * the fallback validator checks `required` plus primitive types only and the
+ * same call sailed through. One design, two behaviours, selected by whether an
+ * optional install step succeeded. Bounds live here instead, where they are
+ * deterministic and unit-tested.
+ */
+export interface NormalizedOption {
+    label: string;
+    /** `''` when the model supplied none. */
+    description: string;
+    /** Exactly one per question is true after repair. */
+    recommended: boolean;
+    /** The synthetic free-text option. */
+    isOther: boolean;
+}
+export interface NormalizedQuestion {
+    id: string;
+    /** <= 12 chars, truncated. Rendered as a chip above the question. */
+    header: string;
+    question: string;
+    /** 3..5 entries: the 2..4 the model gave, plus the synthetic `Other`. */
+    options: NormalizedOption[];
+    allowMultiple: boolean;
+}
+export interface Answer {
+    id: string;
+    question: string;
+    /** Option labels. Length 1 unless `allowMultiple`. */
+    selected: string[];
+    /** Set only when `Other` was chosen. */
+    custom: string | null;
+}
+export interface NormalizedPlan {
+    title: string;
+    summary: string;
+    steps: {
+        title: string;
+        detail: string;
+    }[];
+    filesTouched: string[];
+    risks: string[];
+    openQuestions: string[];
+}
+export type HumanRequest = {
+    kind: 'questions';
+    questions: NormalizedQuestion[];
+} | {
+    kind: 'plan';
+    plan: NormalizedPlan;
+};
+export type HumanResponse = {
+    kind: 'answers';
+    answers: Answer[];
+    cancelled: boolean;
+} | {
+    kind: 'planDecision';
+    decision: 'approved' | 'revise' | 'dismissed';
+    feedback: string;
+};
+export interface HumanInputGate {
+    /**
+     * STATIC property of the channel: `true` only for a gate that can never
+     * acquire a human at all. Set on `DENY_ALL_HUMAN_INPUT` and nowhere else.
+     *
+     * This — not `canPrompt()` — is what `createPlanTools()` keys registration
+     * off. `canPrompt()` is a LIVE probe and is legitimately `false` for the whole
+     * window between `makeController()` and the App's first effect, because the
+     * App attaches the bridge handler later. A registration decision taken from it
+     * would be "no plan tools", forever, in every interactive session, with no
+     * error anywhere. The two predicates answer different questions and must not
+     * be merged.
+     */
+    readonly neverPrompts?: boolean;
+    /** True only while a TUI is mounted and able to render an overlay. */
+    canPrompt(): boolean;
+    /**
+     * Resolves with `null` when cancelled / unmounted / aborted. NEVER rejects.
+     *
+     * `signal` is the tool's `ctx.signal` and is REQUIRED in practice. It is the
+     * only ceiling the wait has: `ToolExecutor`'s timeout is cooperative — it
+     * aborts the context signal and keeps awaiting the tool's promise, with no
+     * `Promise.race` anywhere — and the idle watchdog is deliberately paused for
+     * the duration of the wait. Passing `undefined` therefore gives a wait with no
+     * ceiling of any kind, and the process wedges behind an overlay nobody is
+     * going to answer.
+     */
+    request(req: HumanRequest, signal?: AbortSignal): Promise<HumanResponse | null>;
+}
+export interface HumanInputBridge {
+    handler: ((req: HumanRequest, signal?: AbortSignal) => Promise<HumanResponse | null>) | null;
+    /**
+     * Resolve every outstanding request with `null`.
+     *
+     * Called on App unmount AND when a run ends. `ConfirmBridge` nulls its handler
+     * on unmount but leaves any in-flight promise dangling forever; with a
+     * three-second `y/N` that never mattered, but a question wizard the user
+     * abandons with `Ctrl+C` twice would hang the tool until its ceiling.
+     */
+    cancelPending(): void;
+}
+/**
+ * Fails CLOSED. The headless default — forgetting to pass a gate must refuse,
+ * never hang and never assume yes.
+ */
+export declare const DENY_ALL_HUMAN_INPUT: HumanInputGate;
+export declare const QUESTION_LIMITS: {
+    readonly maxQuestions: 5;
+    readonly minOptions: 2;
+    readonly maxOptions: 4;
+    readonly headerChars: 12;
+    readonly questionChars: 300;
+    readonly labelChars: 60;
+    readonly optionDescriptionChars: 120;
+};
+export declare const PLAN_LIMITS: {
+    readonly titleChars: 80;
+    readonly summaryChars: 600;
+    readonly maxSteps: 20;
+    readonly stepTitleChars: 100;
+    readonly stepDetailChars: 400;
+    readonly maxFiles: 30;
+    readonly maxRisks: 10;
+    readonly maxOpenQuestions: 10;
+};
+/**
+ * Trim to `max` characters, preferring a word boundary within the last
+ * `WORD_BOUNDARY_WINDOW` characters. Cutting a sentence mid-word reads as
+ * corruption; cutting it at a space reads as a summary.
+ */
+export declare function clampText(raw: unknown, max: number): string;
+/**
+ * Repair whatever the model sent into something renderable.
+ *
+ * Returns `[]` when nothing survives, which the tool turns into the one hard
+ * failure this path has. Every rule below is reachable precisely BECAUSE the
+ * schema stopped declaring the bounds (P0-4); with `minItems` / `maxItems` in
+ * the schema, `ajv` rejected the call first and rules 1 and 4 were dead code.
+ */
+export declare function normalizeQuestions(raw: unknown): NormalizedQuestion[];
+/**
+ * Repair a submitted plan. Returns `null` only when no step survives — the one
+ * hard failure, because there is then nothing left to review.
+ *
+ * A plan that is one step over the cap is still a plan, and rejecting it costs a
+ * full research turn to regain nothing. Truncation is silent to the model but
+ * VISIBLE to the user: the review overlay's position indicator counts the real
+ * rows, so a clipped plan cannot masquerade as complete.
+ */
+export declare function normalizePlan(raw: unknown): NormalizedPlan | null;
+export interface AnswersResultShape {
+    answers: Answer[];
+    cancelled: boolean;
+    roundsUsed: number;
+    roundsRemaining: number;
+}
+/**
+ * Render the `ask_user` result: one human-readable line so the transcript
+ * preview is legible without parsing, then the JSON the model reads.
+ *
+ * `asked` is passed separately rather than derived from `answers.length`
+ * because a cancelled wizard returns fewer answers than it asked for, and
+ * "answered 1 of 3" is the whole information content of that line.
+ */
+export declare function formatAnswersResult(shape: AnswersResultShape, asked: number): string;