@tintinweb/pi-subagents 0.9.1 → 0.10.0

package/dist/index.js

@@ -15,7 +15,7 @@ import { defineTool, getAgentDir, getSettingsListTheme } from "@earendil-works/p
 import { Container, Key, matchesKey, SettingsList, Spacer, Text } from "@earendil-works/pi-tui";
 import { Type } from "@sinclair/typebox";
 import { AgentManager } from "./agent-manager.js";
-import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
+import { getAgentConversation, getDefaultMaxTurns, getGraceTurns, normalizeMaxTurns, SUBAGENT_TOOL_NAMES, setDefaultMaxTurns, setGraceTurns, steerAgent } from "./agent-runner.js";
 import { BUILTIN_TOOL_NAMES, getAgentConfig, getAllTypes, getAvailableTypes, getDefaultAgentNames, getUserAgentNames, registerAgents, resolveType } from "./agent-types.js";
 import { registerRpcHandlers } from "./cross-extension-rpc.js";
 import { loadCustomAgents } from "./custom-agents.js";
@@ -27,6 +27,7 @@ import { createOutputFilePath, streamToOutputFile, writeInitialEntry } from "./o
 import { SubagentScheduler } from "./schedule.js";
 import { resolveStorePath, ScheduleStore } from "./schedule-store.js";
 import { applyAndEmitLoaded, saveAndEmitChanged } from "./settings.js";
+import { getStatusNote } from "./status-note.js";
 import { AgentWidget, buildInvocationTags, describeActivity, formatDuration, formatMs, formatTokens, formatTurns, getDisplayName, getPromptModeLabel, SPINNER, } from "./ui/agent-widget.js";
 import { showSchedulesMenu } from "./ui/schedule-menu.js";
 import { addUsage, getLifetimeTotal, getSessionContextPercent } from "./usage.js";
@@ -98,15 +99,6 @@ function getStatusLabel(status, error) {
         default: return "Done";
     }
 }
-/** Parenthetical status note for completed agent result text. */
-function getStatusNote(status) {
-    switch (status) {
-        case "aborted": return " (aborted — max turns exceeded, output may be incomplete)";
-        case "steered": return " (wrapped up — reached turn limit)";
-        case "stopped": return " (stopped by user)";
-        default: return "";
-    }
-}
 /** Escape XML special characters to prevent injection in structured notifications. */
 function escapeXml(s) {
     return s.replace(/&/g, "&amp;").replace(/</g, "&lt;").replace(/>/g, "&gt;");
@@ -130,7 +122,7 @@ function formatTaskNotification(record, resultMaxLen) {
         record.toolCallId ? `<tool-use-id>${escapeXml(record.toolCallId)}</tool-use-id>` : null,
         record.outputFile ? `<output-file>${escapeXml(record.outputFile)}</output-file>` : null,
         `<status>${escapeXml(status)}</status>`,
-        `<summary>Agent "${escapeXml(record.description)}" ${record.status}</summary>`,
+        `<summary>Agent "${escapeXml(record.description)}" ${record.status}${getStatusNote(record.status)}</summary>`,
         `<result>${escapeXml(resultPreview)}</result>`,
         `<usage><total_tokens>${totalTokens}</total_tokens><tool_uses>${record.toolUses}</tool_uses>${ctxXml}${compactXml}<duration_ms>${durationMs}</duration_ms></usage>`,
         `</task-notification>`,
@@ -573,7 +565,7 @@ export default function (pi) {
         ? `\n- Use \`schedule\` only when the user explicitly asked for scheduled / recurring / delayed execution (e.g. "every Monday", "in an hour"). Don't auto-schedule from vague intent like "monitor X" — run once now or ask.`
         : "";
     pi.registerTool(defineTool({
-        name: "Agent",
+        name: SUBAGENT_TOOL_NAMES.AGENT,
         label: "Agent",
         description: `Launch a new agent to handle complex, multi-step tasks autonomously. Each agent type has specific capabilities and tools available to it.
 
@@ -673,7 +665,7 @@ Terse command-style prompts produce shallow, generic work.
                 const text = result.content[0]?.type === "text" ? result.content[0].text : "";
                 return new Text(text, 0, 0);
             }
-            // Helper: build "haiku · thinking: high · ⟳5≤30 · 3 tool uses · 33.8k tokens" stats string
+            // Helper: build "haiku · thinking: high · ↻5≤30 · 3 tool uses · 33.8k tokens" stats string
             const stats = (d) => {
                 const parts = [];
                 if (d.modelName)
@@ -1042,7 +1034,7 @@ Terse command-style prompts produce shallow, generic work.
     }));
     // ---- get_subagent_result tool ----
     pi.registerTool(defineTool({
-        name: "get_subagent_result",
+        name: SUBAGENT_TOOL_NAMES.GET_RESULT,
         label: "Get Agent Result",
         description: "Check status and retrieve results from a background agent. Use the agent ID returned by Agent with run_in_background.",
         promptSnippet: "Check status and retrieve results from a background agent",
@@ -1084,7 +1076,7 @@ Terse command-style prompts produce shallow, generic work.
                 statsParts.push(`Compactions: ${record.compactionCount}`);
             statsParts.push(`Duration: ${duration}`);
             let output = `Agent: ${record.id}\n` +
-                `Type: ${displayName} | Status: ${record.status} | ${statsParts.join(" | ")}\n` +
+                `Type: ${displayName} | Status: ${record.status}${getStatusNote(record.status)} | ${statsParts.join(" | ")}\n` +
                 `Description: ${record.description}\n\n`;
             if (record.status === "running") {
                 output += "Agent is still running. Use wait: true or check back later.";
@@ -1112,7 +1104,7 @@ Terse command-style prompts produce shallow, generic work.
     }));
     // ---- steer_subagent tool ----
     pi.registerTool(defineTool({
-        name: "steer_subagent",
+        name: SUBAGENT_TOOL_NAMES.STEER,
         label: "Steer Agent",
         description: "Send a steering message to a running agent. The message will interrupt the agent after its current tool execution " +
             "and be injected into its conversation, allowing you to redirect its work mid-run. Only works on running agents.",
@@ -1322,7 +1314,11 @@ Terse command-style prompts produce shallow, generic work.
         const session = record.session;
         const activity = agentActivity.get(record.id);
         await ctx.ui.custom((tui, theme, _keybindings, done) => {
-            return new ConversationViewer(tui, session, record, activity, theme, done);
+            return new ConversationViewer(tui, session, record, activity, theme, done, () => {
+                if (manager.abort(record.id)) {
+                    ctx.ui.notify(`Stopped "${record.description}".`, "info");
+                }
+            });
         }, {
             overlay: true,
             overlayOptions: { anchor: "center", width: "90%", maxHeight: `${VIEWPORT_HEIGHT_PCT}%` },

package/dist/prompts.d.ts

@@ -16,12 +16,15 @@ export interface PromptExtras {
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
  * extensions (e.g. permission/policy systems) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).

package/dist/prompts.js

@@ -5,12 +5,15 @@
  * Build the system prompt for an agent from its config.
  *
  * - "replace" mode: env header + config.systemPrompt (full control, no parent identity)
- * - "append" mode: env header + parent system prompt + sub-agent context + config.systemPrompt
+ * - "append" mode: parent system prompt + sub-agent context + env header + config.systemPrompt
  * - "append" with empty systemPrompt: pure parent clone
  *
- * Both modes prepend an `<active_agent name="${config.name}"/>` tag so downstream
+ * Both modes include an `<active_agent name="${config.name}"/>` tag so downstream
  * extensions (e.g. permission/policy systems) can resolve per-agent policy
- * inside the child session by parsing the system prompt.
+ * inside the child session by parsing the system prompt. In replace mode the tag
+ * is prepended; in append mode it follows the shared inherited content so the
+ * parent prompt forms an identical, cacheable byte prefix with the parent
+ * session (the LLM's KV cache can then reuse those tokens across every spawn).
  *
  * @param parentSystemPrompt  The parent agent's effective system prompt (for append mode).
  * @param extras  Optional extra sections to inject (memory, preloaded skills).
@@ -49,7 +52,12 @@ You are operating as a sub-agent invoked to handle a specific task.
         const customSection = config.systemPrompt?.trim()
             ? `\n\n<agent_instructions>\n${config.systemPrompt}\n</agent_instructions>`
             : "";
-        return activeAgentTag + envBlock + "\n\n<inherited_system_prompt>\n" + identity + "\n</inherited_system_prompt>\n\n" + bridge + customSection + extrasSuffix;
+        // Place shared/stable content first so the LLM's KV cache can reuse the
+        // inherited prefix across all subagent invocations. The parent prompt is
+        // placed verbatim (no wrapper tag) so it forms an identical byte prefix
+        // with the parent session, maximising KV cache hits. The <active_agent>
+        // tag and env block vary per call and are placed after the cached prefix.
+        return identity + "\n\n" + bridge + "\n\n" + activeAgentTag + envBlock + customSection + extrasSuffix;
     }
     // "replace" mode — env header + the config's full system prompt
     const replaceHeader = `You are a pi coding agent sub-agent.

package/dist/status-note.d.ts

@@ -0,0 +1,13 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export declare function getStatusNote(status: string): string;

package/dist/status-note.js

@@ -0,0 +1,24 @@
+/**
+ * status-note.ts — Parenthetical status note appended to agent result text.
+ */
+/**
+ * Explicit parenthetical note for a non-normal terminal outcome, so the parent
+ * agent can't mistake partial output for a completed result. Empty string for a
+ * clean completion (and any unknown/non-terminal status).
+ *
+ * `stopped` (a human aborted it) is deliberately distinct from `aborted` (the
+ * turn limit was hit) — the parent should treat human intervention differently
+ * from a budget cutoff.
+ */
+export function getStatusNote(status) {
+    switch (status) {
+        case "stopped":
+            return " (STOPPED BY THE USER before completion — output is partial; the task was NOT finished)";
+        case "aborted":
+            return " (aborted — hit the turn limit before completion; output may be incomplete)";
+        case "steered":
+            return " (wrapped up at the turn limit — output may be partial)";
+        default:
+            return "";
+    }
+}

package/dist/types.d.ts

@@ -19,6 +19,9 @@ export interface AgentConfig {
     displayName?: string;
     description: string;
     builtinToolNames?: string[];
+    /** Raw `ext:` selector entries from the `tools:` CSV, e.g. ["ext:foo", "ext:bar/x"].
+     * Presence of any entry flips extension tools to an explicit allowlist. */
+    extSelectors?: string[];
     /** Tool denylist — these tools are removed even if `builtinToolNames` or extensions include them. */
     disallowedTools?: string[];
     /** true = inherit all, string[] = only listed, false = none */

package/dist/ui/agent-widget.d.ts

@@ -66,15 +66,15 @@ export declare function formatTokens(count: number): string;
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
+ * Compaction count rendered as `⇊N` in dim.
  *
  *   "12.3k token"               — no annotations
  *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
+ *   "12.3k token (⇊2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ⇊2)"    — both
  */
 export declare function formatSessionTokens(tokens: number, percent: number | null, theme: Theme, compactions?: number): string;
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
 export declare function formatTurns(turnCount: number, maxTurns?: number | null): string;
 /** Format milliseconds as human-readable duration. */
 export declare function formatMs(ms: number): string;

package/dist/ui/agent-widget.js

@@ -36,12 +36,12 @@ export function formatTokens(count) {
 /**
  * Token count with optional context-fill % and compaction-count annotations.
  * Thresholds for percent: <70% dim, 70–85% warning, ≥85% error.
- * Compaction count rendered as `↻N` in dim.
+ * Compaction count rendered as `⇊N` in dim.
  *
  *   "12.3k token"               — no annotations
  *   "12.3k token (45%)"         — percent only
- *   "12.3k token (↻2)"          — compactions only (e.g. right after compact)
- *   "12.3k token (45% · ↻2)"    — both
+ *   "12.3k token (⇊2)"          — compactions only (e.g. right after compact)
+ *   "12.3k token (45% · ⇊2)"    — both
  */
 export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
     const tokenStr = formatTokens(tokens);
@@ -51,15 +51,15 @@ export function formatSessionTokens(tokens, percent, theme, compactions = 0) {
         annot.push(theme.fg(color, `${Math.round(percent)}%`));
     }
     if (compactions > 0) {
-        annot.push(theme.fg("dim", `↻${compactions}`));
+        annot.push(theme.fg("dim", `⇊${compactions}`));
     }
     if (annot.length === 0)
         return tokenStr;
     return `${tokenStr} (${annot.join(" · ")})`;
 }
-/** Format turn count with optional max limit: "⟳5≤30" or "⟳5". */
+/** Format turn count with optional max limit: "↻5≤30" or "↻5". */
 export function formatTurns(turnCount, maxTurns) {
-    return maxTurns != null ? `⟳${turnCount}≤${maxTurns}` : `⟳${turnCount}`;
+    return maxTurns != null ? `↻${turnCount}≤${maxTurns}` : `↻${turnCount}`;
 }
 /** Format milliseconds as human-readable duration. */
 export function formatMs(ms) {

package/dist/ui/conversation-viewer.d.ts

@@ -18,14 +18,22 @@ export declare class ConversationViewer implements Component {
     private activity;
     private theme;
     private done;
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    private onStop?;
     private scrollOffset;
     private autoScroll;
     private unsubscribe;
     private lastInnerW;
     private closed;
-    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void);
+    /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+    private stopArmed;
+    constructor(tui: TUI, session: AgentSession, record: AgentRecord, activity: AgentActivity | undefined, theme: Theme, done: (result: undefined) => void, 
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    onStop?: (() => void) | undefined);
     handleInput(data: string): void;
     render(width: number): string[];
+    /** Stoppable only when a stop handler exists and the agent is still active. */
+    private isStoppable;
     invalidate(): void;
     dispose(): void;
     private viewportHeight;

package/dist/ui/conversation-viewer.js

@@ -20,18 +20,24 @@ export class ConversationViewer {
     activity;
     theme;
     done;
+    onStop;
     scrollOffset = 0;
     autoScroll = true;
     unsubscribe;
     lastInnerW = 0;
     closed = false;
-    constructor(tui, session, record, activity, theme, done) {
+    /** Two-press confirm guard for the stop key, so a stray key can't kill the agent. */
+    stopArmed = false;
+    constructor(tui, session, record, activity, theme, done, 
+    /** Abort the agent shown here. Omitted → no stop affordance (e.g. read-only history). */
+    onStop) {
         this.tui = tui;
         this.session = session;
         this.record = record;
         this.activity = activity;
         this.theme = theme;
         this.done = done;
+        this.onStop = onStop;
         this.unsubscribe = session.subscribe(() => {
             if (this.closed)
                 return;
@@ -44,6 +50,23 @@ export class ConversationViewer {
             this.done(undefined);
             return;
         }
+        // Stop/abort the agent (only while it can still be stopped). Two-press:
+        // first "x" arms, second confirms — any other key disarms.
+        if (matchesKey(data, "x")) {
+            if (this.isStoppable()) {
+                if (this.stopArmed) {
+                    this.stopArmed = false;
+                    this.onStop?.();
+                }
+                else {
+                    this.stopArmed = true;
+                }
+                this.tui.requestRender();
+            }
+            return;
+        }
+        if (this.stopArmed)
+            this.stopArmed = false;
         const totalLines = this.buildContentLines(this.lastInnerW).length;
         const viewportHeight = this.viewportHeight();
         const maxScroll = Math.max(0, totalLines - viewportHeight);
@@ -132,12 +155,22 @@ export class ConversationViewer {
             ? "100%"
             : `${Math.round(((visibleStart + viewportHeight) / contentLines.length) * 100)}%`;
         const footerLeft = th.fg("dim", `${contentLines.length} lines · ${scrollPct}`);
-        const footerRight = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+        const scrollHint = th.fg("dim", "↑↓ scroll · PgUp/PgDn or Shift+↑↓ · Esc close");
+        // Stop hint goes first in the right group so it survives right-edge
+        // truncation on narrow terminals (the scroll hint is the expendable part).
+        const footerRight = this.isStoppable()
+            ? (this.stopArmed ? th.fg("error", "x again to STOP") : th.fg("dim", "x stop")) +
+                th.fg("dim", " · ") + scrollHint
+            : scrollHint;
         const footerGap = Math.max(1, innerW - visibleWidth(footerLeft) - visibleWidth(footerRight));
         lines.push(row(footerLeft + " ".repeat(footerGap) + footerRight));
         lines.push(hrBot);
         return lines;
     }
+    /** Stoppable only when a stop handler exists and the agent is still active. */
+    isStoppable() {
+        return !!this.onStop && (this.record.status === "running" || this.record.status === "queued");
+    }
     invalidate() { }
     dispose() {
         this.closed = true;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@tintinweb/pi-subagents",
-  "version": "0.9.1",
+  "version": "0.10.0",
   "description": "A pi extension extension that brings smart Claude Code-style autonomous sub-agents to pi.",
   "author": "tintinweb",
   "license": "MIT",
@@ -35,6 +35,7 @@
     "prepublishOnly": "npm run lint && npm run typecheck && npm run test && npm run build",
     "test": "vitest run",
     "test:watch": "vitest",
+    "test:e2e": "vitest run e2e --reporter=verbose",
     "typecheck": "tsc --noEmit",
     "lint": "biome check src/ test/",
     "lint:fix": "biome check --fix src/ test/"