@aragon-agent/cli 0.6.3 → 0.6.4

package/dist/tools/index.d.ts

@@ -12,6 +12,7 @@ import { type AgentTool, type ToolPolicyDecision, type ToolPolicyVerdict } from
 import type { AgentMode } from '../agent/agent-mode.js';
 import type { ToolPermission } from '../exec/permission.js';
 import type { FilePatch } from './patch.js';
+import type { ProcSupervisorPort } from '../proc/types.js';
 export interface ConfirmRequest {
     tool: string;
     summary: string;
@@ -151,6 +152,58 @@ export interface BuiltinToolsOptions {
      * `--no-skills` is.
      */
     teamTools?: AgentTool[];
+    /**
+     * The process supervisor (background-service-supervision §3.5).
+     *
+     * THE TWO-INTERFACE RULE: it is declared on `ToolDeps` as well, and adding it
+     * to only one of the two type-checks and forwards nothing — `bash` never sees
+     * a supervisor and every long-running command keeps hanging, with nothing
+     * anywhere erroring. Both, or neither.
+     *
+     * The conditional spread below is what makes I-2 true at this layer: with
+     * background services off the controller passes no key, so no property is
+     * added and `deps` is the object it is today.
+     */
+    procs?: ProcSupervisorPort;
+    /**
+     * `bash_output` / `bash_kill`, appended verbatim.
+     *
+     * THROUGH THE FACTORY FOR THE REASON `teamTools` AND `todoTools` EACH RECORD
+     * IN CAPITALS (P0-2): `tools.test.ts::C7` asserts `HOST_TOOL_NAMES` equals
+     * what this factory PRODUCES, so appending these two in `AgentController`
+     * after the factory returned would turn C7 red with a message about two lists
+     * of names that says nothing about background services.
+     *
+     * An empty array (`bash.background: false`) leaves the tool list
+     * byte-identical to the pre-feature build — I-2, provable by object identity
+     * exactly as `--no-skills` and `--no-team` are.
+     */
+    procTools?: AgentTool[];
+    /**
+     * `cfg.bash.autoBackground`, READ AT CALL TIME.
+     *
+     * Never cached: `aragon config set bash.autoBackground false` takes effect in
+     * the running session, and a cached `true` would go on backgrounding commands
+     * the user just told it not to.
+     */
+    autoBackground?: () => boolean;
+    /** `cfg.bash.startupSettleMs`, read at call time for the same reason. */
+    startupSettleMs?: () => number;
+    /**
+     * Whether this session can render a service card and keep a service alive
+     * (D-15 / P1-8).
+     *
+     * FALSE UNDER `aragon exec` AND `-p`. It suppresses only the CLASSIFIER: an
+     * explicit `background: true` is still honoured, and its result then says the
+     * service dies with the run. Without it `aragon -p "npm run dev"` would
+     * background a server, return in `startupSettleMs`, and reap it at process
+     * exit with nothing anywhere saying so.
+     *
+     * It is the SAME SIGNAL `planTools` already uses to decide that no overlay can
+     * be rendered, so this costs one boolean rather than a new capability probe.
+     * Absent means interactive, which is what every existing caller is.
+     */
+    interactive?: boolean;
     /**
      * Tool names that skip the CEILING wrapper only (never the plan gate, never
      * confirmation).
@@ -199,7 +252,7 @@ export interface BuiltinToolsOptions {
  * is the whole of what this mechanism is worth, and saying so plainly beats
  * implying it covers more.
  */
-export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write"];
+export declare const SKILL_TOOL_FLOOR: readonly ["read_file", "list_dir", "glob", "grep", "skill", "skill_find", "ask_user", "submit_plan", "task", "todo_write", "bash_output"];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
  * within `HOST_TOOL_NAMES` — "the five that change something", the set this file
@@ -232,5 +285,5 @@ export declare const PLAN_MODE_BLOCKED_TOOLS: ReadonlySet<string>;
  * declaration MEANS, and that reading must not change with how the CLI was
  * started.
  */
-export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "task"];
+export declare const HOST_TOOL_NAMES: readonly ["read_file", "write_file", "edit_file", "list_dir", "glob", "grep", "bash", "skill", "skill_find", "skill_install", "skill_create", "ask_user", "submit_plan", "todo_write", "bash_output", "bash_kill", "task"];
 export declare function createBuiltinTools(options: BuiltinToolsOptions): AgentTool[];

package/dist/tools/index.js

@@ -59,6 +59,12 @@ export const SKILL_TOOL_FLOOR = [
     // inside that skill's frame — the identical dead end that put `ask_user` /
     // `submit_plan` / `task` here.
     'todo_write',
+    // `bash_output` joins the FLOOR rather than the blocked set (D-12), and the
+    // partition test below is what forces that choice to be conscious. It READS A
+    // BUFFER: it cannot write to disk or run a shell, which is the floor's stated
+    // membership test. Blocking it in plan mode would also let the agent start a
+    // service it then could not read — the dead end the floor exists to prevent.
+    'bash_output',
 ];
 /**
  * The five tools plan mode refuses: exactly the complement of `SKILL_TOOL_FLOOR`
@@ -77,6 +83,11 @@ export const PLAN_MODE_BLOCKED_TOOLS = new Set([
     'bash',
     'skill_install',
     'skill_create',
+    // `bash_kill` joins the BLOCKED set (D-12). It TERMINATES A PROCESS, which is
+    // a mutation of the world and the complement's stated membership test. Nothing
+    // is dead-ended by it: `Ctrl+C` and `/bg stop` both remain available to the
+    // USER in plan mode, so the person can always stop what the agent started.
+    'bash_kill',
 ]);
 /**
  * Every tool name this host CAN register (7 built-ins + 4 skill tools).
@@ -113,6 +124,13 @@ export const HOST_TOOL_NAMES = [
     'ask_user',
     'submit_plan',
     'todo_write',
+    // Both names are here even though `bash.background: false` registers NEITHER,
+    // and that is the constant's documented meaning rather than an inconsistency:
+    // it is the SUPERSET of what this host CAN register, answering "can a skill's
+    // `allowed-tools` declaration ever take effect?" — the same relationship
+    // `skills doctor` already has with `--no-skills`.
+    'bash_output',
+    'bash_kill',
     // `team_send` / `team_wait` are DELIBERATELY ABSENT (P2-5). This constant
     // answers "can a skill's `allowed-tools` declaration ever take effect?", and
     // those two are never registered on a lead — so a skill naming them genuinely
@@ -221,6 +239,10 @@ export function createBuiltinTools(options) {
         ...(options.recordChange ? { recordChange: options.recordChange } : {}),
         // Added in the same shape and for the same reason (P1-1).
         ...(options.recordOutput ? { recordOutput: options.recordOutput } : {}),
+        // And the third, in the same shape and for the same reason. The FORWARD half
+        // of the two-interface note on `procs` above: without this line the field is
+        // on both interfaces, nothing errors, and `bash` still hangs.
+        ...(options.procs ? { procs: options.procs } : {}),
     };
     let tools = [
         makeReadFile(deps),
@@ -229,7 +251,18 @@ export function createBuiltinTools(options) {
         makeListDir(deps),
         makeGlob(deps),
         makeGrep(deps),
-        makeBash(deps),
+        // The second argument is spread CONDITIONALLY on the supervisor being
+        // present, so with background services off `makeBash` receives its default
+        // `{}` and produces the pre-feature tool: no `background` property in the
+        // schema, the pre-feature description string, no supervisor call (I-2).
+        makeBash(deps, options.procs
+            ? {
+                supervisor: options.procs,
+                ...(options.autoBackground ? { autoBackground: options.autoBackground } : {}),
+                ...(options.startupSettleMs ? { startupSettleMs: options.startupSettleMs } : {}),
+                ...(options.interactive !== undefined ? { interactive: options.interactive } : {}),
+            }
+            : {}),
     ];
     if (options.confirmTools && options.confirm) {
         const confirm = options.confirm;
@@ -246,6 +279,11 @@ export function createBuiltinTools(options) {
     if (options.todoTools && options.todoTools.length > 0) {
         tools = [...tools, ...options.todoTools];
     }
+    // AFTER `todoTools`, BEFORE `teamTools`, so a lead's `task` stays last and
+    // `HOST_TOOL_NAMES` changes by two insertions rather than a reshuffle.
+    if (options.procTools && options.procTools.length > 0) {
+        tools = [...tools, ...options.procTools];
+    }
     // BEFORE both wrappers, so the lead's `task` is covered by the plan gate and
     // the ceiling like everything else, and a child's comm tools are covered by
     // everything except the ceiling (see `policyExempt`).

package/dist/tools/proc-tools.d.ts

@@ -0,0 +1,25 @@
+/**
+ * `bash_output` and `bash_kill` — the model's two handles on a supervised
+ * service (background-service-supervision §5.1).
+ *
+ * REGISTERED THROUGH A FACTORY OPTION, NEVER APPENDED AFTER THE FACT
+ * (`tools/index.ts::procTools`). `tools.test.ts::C7` asserts `HOST_TOOL_NAMES`
+ * equals what `createBuiltinTools` PRODUCES, so appending these in
+ * `AgentController` after the factory returned would turn that test red with a
+ * message about two lists of names that says nothing about background services —
+ * the trap `teamTools` and `todoTools` each record in capitals.
+ *
+ * NEITHER JOINS `MUTATING_TOOLS` (P2-5). `bash_output` is a read. `bash_kill`
+ * stops something THIS SESSION STARTED and is showing on screen, and the plan
+ * gate already refuses it in plan mode; putting a `--confirm` modal between the
+ * user and stopping their own runaway server is the wrong trade. `bash` itself
+ * stays in `MUTATING_TOOLS` unchanged, including when `background: true` — the
+ * command is still arbitrary.
+ */
+import { type AgentTool } from '@aragon-agent/core';
+import type { ProcSupervisorPort } from '../proc/types.js';
+export interface ProcToolDeps {
+    supervisor: ProcSupervisorPort;
+}
+export declare function makeBashOutput(deps: ProcToolDeps): AgentTool;
+export declare function makeBashKill(deps: ProcToolDeps): AgentTool;

package/dist/tools/proc-tools.js

@@ -0,0 +1,102 @@
+/**
+ * `bash_output` and `bash_kill` — the model's two handles on a supervised
+ * service (background-service-supervision §5.1).
+ *
+ * REGISTERED THROUGH A FACTORY OPTION, NEVER APPENDED AFTER THE FACT
+ * (`tools/index.ts::procTools`). `tools.test.ts::C7` asserts `HOST_TOOL_NAMES`
+ * equals what `createBuiltinTools` PRODUCES, so appending these in
+ * `AgentController` after the factory returned would turn that test red with a
+ * message about two lists of names that says nothing about background services —
+ * the trap `teamTools` and `todoTools` each record in capitals.
+ *
+ * NEITHER JOINS `MUTATING_TOOLS` (P2-5). `bash_output` is a read. `bash_kill`
+ * stops something THIS SESSION STARTED and is showing on screen, and the plan
+ * gate already refuses it in plan mode; putting a `--confirm` modal between the
+ * user and stopping their own runaway server is the wrong trade. `bash` itself
+ * stays in `MUTATING_TOOLS` unchanged, including when `background: true` — the
+ * command is still arbitrary.
+ */
+import { defineTool, errorResult, textResult } from '@aragon-agent/core';
+import { PROC_LIMITS } from '../proc/limits.js';
+/** One line of status, shared by both tools so the two can never disagree. */
+function statusLine(service) {
+    const bits = [`service ${service.id}  ${service.status}`];
+    if (service.url)
+        bits.push(service.url);
+    if (service.exitCode !== null)
+        bits.push(`exit code ${service.exitCode}`);
+    else if (service.signal)
+        bits.push(`signal ${service.signal}`);
+    if (service.killIncomplete)
+        bits.push('(may have left a detached child)');
+    return `${bits.join('  ')}\n$ ${service.command}`;
+}
+export function makeBashOutput(deps) {
+    return defineTool({
+        name: 'bash_output',
+        label: 'Service log',
+        description: 'Read a background service log tail and its current status. Pass the ' +
+            '`since` cursor returned by a previous call to read only what is new. ' +
+            'Use this to verify a service actually started, and to read a build or ' +
+            'test watcher as it runs.',
+        parameters: {
+            type: 'object',
+            properties: {
+                service: { type: 'string', description: 'The service id, e.g. "s1".' },
+                since: {
+                    type: 'number',
+                    description: 'Cursor from a previous call; omit to read the whole tail.',
+                },
+            },
+            required: ['service'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            const service = deps.supervisor.get(params.service);
+            if (!service) {
+                return errorResult(`No service "${params.service}". Start one with bash({ command, background: true }).`);
+            }
+            const page = deps.supervisor.read(params.service, params.since);
+            const lines = [statusLine(service)];
+            if (page?.truncated) {
+                lines.push(`[note] older rows were dropped - the tail keeps the last ` +
+                    `${PROC_LIMITS.serviceTailRows} rows.`);
+            }
+            if (!page || page.rows.length === 0) {
+                lines.push('(no new output)');
+            }
+            else {
+                lines.push(...page.rows);
+            }
+            lines.push(`[cursor ${page?.cursor ?? service.rowsSeen}]`);
+            return textResult(lines.join('\n'));
+        },
+    });
+}
+export function makeBashKill(deps) {
+    return defineTool({
+        name: 'bash_kill',
+        label: 'Stop service',
+        description: 'Stop a background service by id, or every service with "all". Stop the ' +
+            'services you started once you are finished with them, unless the user ' +
+            'asked for them to stay up.',
+        parameters: {
+            type: 'object',
+            properties: {
+                service: { type: 'string', description: 'The service id, or "all".' },
+            },
+            required: ['service'],
+        },
+        async execute(_id, rawParams) {
+            const params = rawParams;
+            if (params.service !== 'all' && !deps.supervisor.get(params.service)) {
+                return errorResult(`No service "${params.service}".`);
+            }
+            const stopped = await deps.supervisor.stop(params.service);
+            if (stopped.length === 0)
+                return textResult('Nothing to stop.');
+            const lines = stopped.map((s) => statusLine(s));
+            return textResult(`Stopped ${stopped.length} service${stopped.length === 1 ? '' : 's'}.\n${lines.join('\n')}`);
+        },
+    });
+}

package/dist/ui/App.d.ts

@@ -10,7 +10,8 @@ import type { ConfirmRequest } from '../tools/index.js';
 import { type Overlay, type ToastLevel } from '../agent/reducer.js';
 import type { UpdateBridge } from '../update/types.js';
 import { type RenderMode } from './layout/frame.js';
-import type { MouseSource } from '../input/stdin-mouse-filter.js';
+import type { MouseSource } from '../input/stdin-filter.js';
+import type { PasteBridge } from '../input/limits.js';
 import type { SelectionBridge } from './selection/selection-controller.js';
 import type { HumanInputBridge } from '../tools/human-input.js';
 export interface ConfirmBridge {
@@ -73,6 +74,18 @@ export interface AppProps {
      * 'off'`, on a non-TTY, in CI, and in every test that does not exercise it.
      */
     updateBridge?: UpdateBridge;
+    /**
+     * The stdin filter's channel for a refused paste (tui-paste-handling section
+     * 5.1.2 / I-15).
+     *
+     * A BRIDGE for the reason `updateBridge` above is one: the filter is built in
+     * `cli.tsx` BEFORE `render()`, so it has no `dispatch`. Its only other outlet
+     * is the logger, and a limit that writes only to a log file is
+     * indistinguishable — from the user's chair — from a paste that silently did
+     * nothing, which is what D-11 exists to rule out. Absent under `--no-paste`,
+     * on a non-TTY, and in every test that does not exercise it.
+     */
+    pasteBridge?: PasteBridge;
     /**
      * The terminal-facing services `cli.tsx` owns and this component cannot build
      * (tui-selection-and-scroll-follow §4.4).
@@ -120,4 +133,4 @@ export interface TerminalBridge {
     writeForeign?: (text: string) => void;
     selection?: SelectionBridge;
 }
-export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, terminal, }: AppProps): React.ReactElement;
+export declare function App({ controller, version, mode, initialOverlay, initialPrompt, confirmBridge, humanInputBridge, mouseSource, vtInputWarning, updateBridge, pasteBridge, terminal, }: AppProps): React.ReactElement;