@aragon-agent/cli 0.6.38 → 0.6.40

package/dist/agent/controller.d.ts

@@ -19,6 +19,8 @@ import type { CliConfig, CompactionConfig, FastConfig, RetryConfig, TeamConfig,
 import type { ModelRole } from '../config/model-profiles.js';
 import { ModelWindows } from '../config/model-windows.js';
 import { type ConfirmRequest } from '../tools/index.js';
+import type { ToolGate } from '../tools/tool-gate.js';
+import type { ToolHookRunner } from '../exec/hooks/tool-wrapper.js';
 import type { ToolPermission } from '../exec/permission.js';
 import { type ToolOutputListener } from '../tools/tool-output-store.js';
 import type { FilePatch } from '../tools/patch.js';
@@ -28,11 +30,13 @@ import { ProcSupervisor } from '../proc/supervisor.js';
 import type { ProcEventListener, ServiceSnapshot } from '../proc/types.js';
 import { type FastStatus } from '../fast/wiring.js';
 import type { FastEventListener, FastSnapshot } from '../fast/types.js';
+import type { TaskSummaryOutcome } from '../fast/task-summary-types.js';
 import { ContextMeter, type ContextUsageListener } from '../compaction/meter.js';
 import type { CompactionEventListener, CompactionSnapshot, ContextUsageSnapshot } from '../compaction/types.js';
 import type { AcceptanceItem, TodoEventListener, TodoSnapshot } from '../todo/types.js';
 import { type HumanInputGate } from '../tools/human-input.js';
 import { SkillService, type ApprovalGate } from '../skills/service.js';
+import type { SkillRoutingReport } from '../skills/triage.js';
 import { type ConversationResetOptions, type ConversationResetResult } from './conversation-reset.js';
 import type { AgentMode } from './agent-mode.js';
 import type { NoticeLevel } from './reducer.js';
@@ -100,6 +104,36 @@ export interface ControllerDeps {
      * `tools/index.ts`.
      */
     permission?: ToolPermission;
+    /**
+     * The caller's per-call approval gate (headless-host-bridge §2.3.3).
+     *
+     * FORWARDED INTO `createBuiltinTools` AND NOWHERE ELSE. Unlike `permission` it
+     * does NOT reach subagents in this round: every child builds its own tool array
+     * through `team/runtime.ts`, and a fan-out that asked "may I run bash?" once per
+     * child for one decision is an approval waterfall, not a control. Absent on
+     * every existing path, which is what keeps the tool array identical there.
+     */
+    toolGate?: ToolGate;
+    /**
+     * How long a decision may wait, added to the tool's own budget.
+     *
+     * SEE THE TWO-PHASE FORMULA AT `toolTimeoutOverrides`. The executor arms its
+     * timer BEFORE the approval wrapper runs, so a ceiling of `toolTimeoutMs` alone
+     * would give the tool less than its configured time by exactly however long the
+     * caller took to answer.
+     */
+    decisionBudgetMs?: number;
+    /**
+     * The gate each SUBAGENT gets, keyed by its label (headless-host-bridge
+     * section 2.3.7).
+     *
+     * A SEPARATE FIELD BECAUSE THE SCOPE DIFFERS, NOT BECAUSE THE GATE DOES: every
+     * child reports `{id, label, depth: 1}` so the caller can render "subagent A
+     * wants to run bash", while the lead reports `depth: 0`. One shared instance
+     * would attribute every child's request to the lead. Absent outside bridge mode,
+     * which keeps a child's tool array identical today.
+     */
+    toolGateForChild?: (label: string) => ToolGate;
     /**
      * `--append-system-prompt` text, appended verbatim to the composed prompt
      * (§4.1). Threaded through `composeSystemPrompt` so it survives every rebuild
@@ -107,6 +141,41 @@ export interface ControllerDeps {
      * once at construction and lost at the first `rebuildSystemPrompt()`.
      */
     appendSystemPrompt?: string;
+    /**
+     * `submit_result`, registered with the lead's toolset when the caller supplied
+     * `--result-schema` (headless-request-scope-and-typed-result section 2.3.9).
+     *
+     * FORWARDED INTO `createBuiltinTools` AND NOWHERE ELSE. It must NOT reach a
+     * subagent: a child's product is a report that goes back through `task`, and a
+     * second submitter inside one request would compete with the lead's schema for the
+     * one accepted value. The child's `createBuiltinTools` call site is
+     * `team/subagent.ts`, and it deliberately passes nothing here.
+     *
+     * Absent on every existing path (the TUI, `-p`, every subcommand), which is what
+     * keeps their tool arrays byte-identical (I-S2).
+     */
+    resultTool?: AgentTool;
+    /**
+     * The rendered `<structured_result>` block, or absent.
+     *
+     * SEE THE FIELD'S OWN COMMENT for why this is threaded through the controller
+     * rather than spliced once: the prompt is rebuilt, and a block that vanished on a
+     * rebuild would leave the model unaware of the contract it is being graded against.
+     */
+    structuredResultBlock?: string;
+    /**
+     * The caller's lifecycle hooks (headless-threads-and-lifecycle-hooks section 2.4.9).
+     *
+     * FORWARDED INTO `createBuiltinTools` AND NOWHERE ELSE, in the same shape `resultTool`
+     * is: absent on every existing path (the TUI, `-p`, every subcommand and every
+     * subagent), which is what keeps their tool arrays byte-identical.
+     *
+     * THE CHILD'S CALL SITE IS DELIBERATELY SILENT ABOUT IT. Hooks see the LEAD's tool calls;
+     * a subagent builds its own array in `team/subagent.ts` and a hook installed for tenant
+     * isolation on the lead must not silently become a hook on every child's identical
+     * `read_file` - that is a different security decision with its own design (section 9.5).
+     */
+    hookRunner?: ToolHookRunner;
     /**
      * The per-model window table from ~/.aragon-agent/model-windows.json.
      * Injectable so tests can hand the controller a table without writing into
@@ -115,22 +184,36 @@ export interface ControllerDeps {
      */
     modelWindows?: ModelWindows;
 }
-/** What `setAgentMode` actually adopted — see `AgentController.setAgentMode`. */
+/**
+ * What `setAgentMode` actually adopted — see `AgentController.setAgentMode`.
+ *
+ * THIS IS ALSO WHAT `/plan status` REPORTS. A `PlanStatus extends AgentModeState`
+ * with `askRoundsUsed` / `maxAskRounds` existed until the round cap was deleted;
+ * keeping an empty sub-interface around would only leave a comment that every
+ * later reader has to work through to learn that nothing is missing.
+ */
 export interface AgentModeState {
     effective: AgentMode;
     /** Non-null only while a `plan -> build` switch is waiting for `agent_end`. */
     pending: AgentMode | null;
 }
-export interface PlanStatus extends AgentModeState {
-    askRoundsUsed: number;
-    maxAskRounds: number;
-}
 export interface PreflightResult {
     ok: boolean;
     message?: string;
     /** 'config' for a missing/invalid key or unusable provider. */
     kind?: 'config';
 }
+/** Inputs for one task-label attempt (`AgentController.summarizeTask`). */
+export interface SummarizeTaskOptions {
+    /**
+     * Cancels the call. The CALLER also owns the epoch guard
+     * (tui-shortcut-drawer-and-task-summary D-10): aborting frees the connection,
+     * the epoch decides correctness, and neither substitutes for the other.
+     */
+    signal?: AbortSignal;
+    /** The glyph a cut label ends with. ASCII by default so a headless caller is safe. */
+    ellipsis?: string;
+}
 export declare class AgentController {
     private config;
     private readonly agent;
@@ -143,9 +226,34 @@ export declare class AgentController {
     private modelMetadataAbort;
     private disposed;
     private readonly tools;
+    /**
+     * Tools the CALLER serves, replaced on every `tool_register` (I-13).
+     *
+     * A SECOND ARRAY, NOT ONE GROWN ONE. `this.tools` is read by `listTools()`,
+     * `toolNames()`, `composeSystemPrompt()` and three "fixed at construction" flags
+     * (bash_output/bash_kill, task, todo_write). Growing it would silently change
+     * what those flags mean; keeping the caller's tools beside it gives one honest
+     * rule - the REGISTRY is the union, `this.tools` stays the host's own set.
+     */
+    private callerTools;
     private readonly skills;
     private readonly skillsEnabled;
     private onSkillsChanged?;
+    /**
+     * This turn's routing result, or `null` when triage is off or nothing scored.
+     *
+     * It also carries the task it was computed for (`SkillRoutingReport.task`), so
+     * there is no separate copy of the turn's text to keep in step with it.
+     */
+    private turnRouting;
+    /** The previous turn's routing, for `/skills route` with no argument. */
+    private lastSkillRouting;
+    /** Did this turn call `skill(name)` successfully? The only proof of adoption. */
+    private skillLoadedThisTurn;
+    /** Tool calls this turn, EXCLUDING `skill` / `skill_find` (see §4.2.7). */
+    private toolCallsThisTurn;
+    /** Skills already reported as "not loaded" — a session says it once (I-T5). */
+    private readonly skillTriageNoticed;
     /** Mutable session cwd — tools resolve relative paths against this. */
     private cwd;
     /**
@@ -157,9 +265,33 @@ export declare class AgentController {
      * Empty on every path but `aragon exec`.
      */
     private readonly appendSystemPrompt;
+    /**
+     * The `<structured_result>` block (headless-request-scope-and-typed-result
+     * section 2.3.8), or `''`.
+     *
+     * A FIELD FOR THE SAME REASON `appendSystemPrompt` IS ONE: `composeSystemPrompt()`
+     * runs again on every rebuild, so a value spliced once at construction would vanish
+     * at the first `/cwd` change, skills rescan or mode flip - and the model would then
+     * be asked to submit a result it had never been told about. Empty on every path but
+     * `aragon exec --result-schema`.
+     */
+    private readonly structuredResultBlock;
     private effectiveMode;
     private pendingMode;
-    private askRounds;
+    /**
+     * Fingerprints of the question SETS the user ANSWERED in this turn. Bounded,
+     * and the bound is storage hygiene rather than a refusal rule — see
+     * `ASK_GUARD_LIMITS`.
+     *
+     * Replaces a numeric round counter that capped `ask_user` at four calls. There
+     * is no cap now; the only thing this prevents is the same batch of questions
+     * being put to the user twice, which is noise rather than information.
+     *
+     * Cleared in `prepareUserTurn` for a NEW turn only. A steer continuation is the
+     * same turn — clearing there would disable the guard exactly when a long turn
+     * most needs it (§4.1.6).
+     */
+    private readonly askedFingerprints;
     /** Static: whether this session could ever render a question overlay. */
     private readonly planInteractive;
     private readonly teamRegistered;
@@ -345,6 +477,24 @@ export declare class AgentController {
      * semantics depend on whether a notice happened to be pending.
      */
     private flushPendingNotices;
+    /**
+     * THE BOUNDARY OF ONE TURN — and there are TWO call sites, which is the reason
+     * this takes an explicit flag instead of resetting everything unconditionally.
+     *
+     * `startPrompt` passes `{ steering: false }`: the user typed something new, so
+     * this really is a new turn. `continue()` passes `{ steering: true }` with the
+     * CONCATENATED queued steering text, which resumes the SAME turn.
+     *
+     * A steer continuation must not re-triage (the candidates would change mid-turn,
+     * and rebuilding the prompt aborts an idle compaction for no gain) and must not
+     * clear the answered-question guard (a long turn interrupted by one steer is
+     * exactly when a repeat question is most likely). Hence per-turn state is
+     * initialised in ONE branch.
+     *
+     * `steering` is REQUIRED and positional-second so each call site states which
+     * kind of turn it is starting, rather than letting a default make "new turn" the
+     * thoughtless option.
+     */
     private prepareUserTurn;
     /** Cancel pending startup as well as any engine run already in progress. */
     abort(): void;
@@ -483,9 +633,53 @@ export declare class AgentController {
      */
     applyPendingMode(): AgentModeState | null;
     /** Named read surface for `/plan status`, so no command reaches into internals. */
-    getPlanStatus(): PlanStatus;
-    /** Spend one `ask_user` round. Called from the tool, never from the UI. */
-    private takeAskRound;
+    getPlanStatus(): AgentModeState;
+    /**
+     * READ-ONLY guard probe, called by `ask_user` BEFORE it opens the overlay.
+     *
+     * No side effect of any kind: a check that also writes cannot be placed before
+     * the question without recording an answer that has not happened yet, and the
+     * "a cancelled round stays askable" rule would then be unimplementable.
+     */
+    private hasAnswered;
+    /**
+     * Record an ANSWERED question set, called by `ask_user` after a real answer.
+     *
+     * Evicts the oldest entry past `ASK_GUARD_LIMITS.maxRemembered`. That eviction
+     * is memory hygiene and NOT a refusal rule — a bounded rejection would be the
+     * deleted round cap wearing a bigger number.
+     */
+    private noteAnswered;
+    /** `/skills route` with no argument: the LAST turn's real routing result. */
+    getSkillRouting(): SkillRoutingReport | null;
+    /**
+     * One line when a confidently-matched skill was NOT loaded — and silence every
+     * other time (D-8).
+     *
+     * THE DISCIPLINE IS "SILENT ON SUCCESS, VISIBLE ON FAILURE". Announcing the
+     * candidates every turn would be ignored by the third day; announcing nothing
+     * ever would make the whole feature unfalsifiable. "A skill covered this task,
+     * you did the work anyway, and you never opened it" is precisely the failure this
+     * feature exists to fix, so it is the one case that speaks — and it names the
+     * command that explains it.
+     *
+     * SEVEN CONDITIONS, and the first one is the one that is easy to get wrong.
+     *
+     * 0. This turn was NOT aborted and NOT ended by an error.
+     *    `agent_end` is emitted unconditionally from a `finally` block in
+     *    `core/src/engine/agent.ts` and its payload carries no reason, no `aborted`
+     *    and no `error` field — so "did this turn finish normally?" has to be read
+     *    from this class's own state. `stopEngine()` sets `abortRequested` before it
+     *    calls `agent.abort()` and `agent_start` clears it, which makes it an exact
+     *    answer. Without this condition an Esc mis-touch would produce a line
+     *    criticising the model for not loading a skill: commentary in response to an
+     *    interruption.
+     *
+     * Conditions 5 and 0 are not redundant: 0 decides what counts as the end of a
+     * turn, 5 decides whether the turn did any work. With only 5, a tool call made
+     * before an abort would still trigger the notice.
+     */
+    private maybeReportSkillTriage;
     /**
      * Run `fn` with the idle watchdog paused.
      *
@@ -870,6 +1064,24 @@ export declare class AgentController {
      * consumed by `App` too, and this round promised to be purely additive.
      */
     fastSnapshot(): FastSnapshot | null;
+    /**
+     * Summarise one user prompt into a header label, using the FAST tier only.
+     *
+     * NEVER REJECTS - the same contract `prompt()` has, and the reason `App` needs
+     * no `.catch`. Every failure is folded into a discriminated
+     * `TaskSummaryOutcome`, because a header label must not be able to produce an
+     * unhandled rejection in a TUI that has nowhere to show one.
+     *
+     * THE CONTROLLER OWNS THE `AbortController` AND ABORTS IT UNCONDITIONALLY on the
+     * way out: `runTaskSummaryCall` may return a `timeout` outcome while the request
+     * is still open (it is forbidden to abort its own call - see that file's
+     * header), so this `finally` is what actually releases the connection.
+     *
+     * EVERY `this.fast` READ IS BEHIND THE CLOSURE, exactly as the reviewer and the
+     * overseer wiring do it: `complete` is only reached from inside the call, which
+     * runs long after construction, so there is no use-before-assign.
+     */
+    summarizeTask(anchor: string, opts?: SummarizeTaskOptions): Promise<TaskSummaryOutcome>;
     /**
      * Subscribe to occupancy publications. Returns an unsubscribe function.
      *
@@ -970,6 +1182,29 @@ export declare class AgentController {
      * `subscribeTodos` and `subscribeFast` already set.
      */
     subscribeCompaction(listener: CompactionEventListener): () => void;
-    /** List usable tools (name + description) for the /tools command. */
+    /**
+     * List usable tools (name + description) for the /tools command.
+     *
+     * THE UNION, SO THE VIEW AND THE REGISTRY CANNOT DISAGREE (I-13). `system/init`
+     * builds `init.tools` from here, as do `/tools` and `/skills`; reporting only the
+     * host's own set while the model is calling `db_query` is the exact failure that
+     * invariant names - a caller reading "the model has no such tool" about a tool it
+     * is watching run.
+     */
     listTools(): AgentTool[];
+    /**
+     * Replace the caller-served tool set. Called ONLY at a turn boundary.
+     *
+     * `Agent.setTools()` unregisters and re-registers entries in the LIVE registry.
+     * This class already learned the lesson once: `submit_plan` mutates the mode from
+     * INSIDE a tool execution, so rebuilding the array at that moment would mutate
+     * the registry mid-iteration (see the comment on the plan tools). Hence the
+     * refusal rather than a silently deferred write: a caller that registers
+     * mid-turn gets an error it can act on, and the bridge defers the frame instead.
+     *
+     * `[]` is meaningful and not an omission: it means "restore the factory set".
+     */
+    applyCallerTools(tools: AgentTool[]): void;
+    /** The names the caller currently serves, for `ack.tools`. */
+    callerToolNames(): string[];
 }