pi-better-subagents 0.4.2 → 0.5.0

package/shared-task-sandbox.ts

@@ -160,6 +160,8 @@ export function installTaskTools(pi: ExtensionAPI, options: {
     shellPath?: () => string | undefined;
     trustedSources: readonly string[];
     admitExtensionTool?: (name: string, input: unknown, sourcePath: string | undefined) => boolean;
+    /** Build the admitted bash definition from the confined operations (default: the SDK bash tool). */
+    bashDefinition?: (cwd: string, operations: BashOperations) => ReturnType<typeof createBashToolDefinition>;
 }) {
     const { controller } = options;
     const sourceKey = (path: string) => path.startsWith("<") ? path : canonicalizePath(path);
@@ -180,7 +182,7 @@ export function installTaskTools(pi: ExtensionAPI, options: {
         pi.registerTool(own(createReadToolDefinition(cwd, { operations: files.read })));
         pi.registerTool(own(createWriteToolDefinition(cwd, { operations: files.write })));
         pi.registerTool(own(createEditToolDefinition(cwd, { operations: files.edit })));
-        pi.registerTool(own(createBashToolDefinition(cwd, { operations: bash })));
+        pi.registerTool(own(options.bashDefinition ? options.bashDefinition(cwd, bash) : createBashToolDefinition(cwd, { operations: bash })));
     };
     register(options.cwd);
     pi.on("user_bash", () => ({ operations: bash }));

package/task-guard.ts

@@ -4,6 +4,10 @@ import { describeSandboxSupport } from "./shared-sandbox-core.ts";
 import { installTaskTools, TASK_BUILTINS } from "./shared-task-sandbox.ts";
 import { parseTaskPolicy } from "./task-policy.ts";
 import { SANDBOX_POLICY_CHANNEL, SANDBOX_POLICY_REQUEST_CHANNEL } from "./permission-policy.ts";
+import { failureDispositionTool, intentBashDefinition } from "./child-incidents.ts";
+import { DISPOSITION_TOOL } from "./incident-model.ts";
+
+const TRUSTED_INLINE_SOURCE = "<inline:task-sandbox>";
 
 export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (error: unknown) => never): void {
     const policy = parseTaskPolicy(input);
@@ -16,9 +20,15 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
     });
     const controller = Object.freeze({ requireLaunchPlan: () => plan });
     let shellPath: string | undefined;
+    let currentCwd = process.cwd();
     const boundary = installTaskTools(pi, { controller, cwd: process.cwd(), shellPath: () => shellPath,
-        trustedSources: ["<inline:task-sandbox>"],
+        trustedSources: [TRUSTED_INLINE_SOURCE],
+        // Structured command intent (#315): validated before the confined command runs.
+        bashDefinition: (cwd, operations) => intentBashDefinition(cwd, operations) as any,
+        // The disposition tool performs no file or command I/O; only this inline registration is admitted.
+        admitExtensionTool: (name, _input, sourcePath) => name === DISPOSITION_TOOL && sourcePath === TRUSTED_INLINE_SOURCE,
     });
+    pi.registerTool(failureDispositionTool(() => currentCwd) as any);
     const profile = Object.freeze({ enabled: true, ...policy.permissions });
     const status = Object.freeze({
         state: "enabled", projectRoot: policy.root, writableRoot: policy.root,
@@ -31,12 +41,14 @@ export default function taskGuard(pi: ExtensionAPI, input: unknown, fatal: (erro
     pi.on("session_start", (_event, ctx) => {
         try {
             shellPath = SettingsManager.create(ctx.cwd, policy.agentDir, { projectTrusted: false }).getShellPath();
+            currentCwd = ctx.cwd;
             boundary.register(ctx.cwd);
             const selected = policy.tools.filter((name) => (TASK_BUILTINS as readonly string[]).includes(name));
             boundary.assertInstalled(selected);
-            pi.setActiveTools(selected);
+            const activated = selected.length ? [...selected, DISPOSITION_TOOL] : selected;
+            pi.setActiveTools(activated);
             const active = new Set(pi.getActiveTools());
-            if (active.size !== selected.length || selected.some((name) => !active.has(name))) {
+            if (active.size !== activated.length || activated.some((name) => !active.has(name))) {
                 throw new Error("SDK did not activate the guarded tool set; refusing to start the task.");
             }
             pi.events.emit(SANDBOX_POLICY_CHANNEL, status);

package/tools.ts

@@ -15,19 +15,33 @@
  */
 
 import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
-import { readMeta, listMetas, effectiveStatus, isFinalResultStatus, type RunMeta, type RunStatus } from "./registry.ts";
-import { parseRun, tailLog, formatSubagentOutputBody } from "./parse.ts";
-import { buildSubagentResultText } from "./finalization.ts";
-import { failureSummary, prependFailureSummary } from "./failures.ts";
-import { formatOrphanedResult } from "./lifecycle.ts";
+import { readMeta, listRunRecords, effectiveStatus, isFinalResultStatus, type RunMeta, type RunStatus } from "./registry.ts";
+import { buildSubagentResultPayload } from "./finalization.ts";
 import { stopRun } from "./stop.ts";
-import { fmtElapsed, fmtSpend } from "./widget.ts";
 import {
     SUBAGENT_LIST_DEFAULT_LIMIT,
     SUBAGENT_LIST_MAX_LIMIT,
     SUBAGENT_LIST_STATUSES,
-    buildSubagentList,
+    collectSubagentList,
+    formatSubagentListRow,
 } from "./list.ts";
+import {
+    assembleOrphanedResult,
+    assembleRunningResult,
+    assembleSubagentListPayload,
+    assembleSubagentOutput,
+    assembleUnreadableMetadata,
+    listIncidentCount,
+    formatIncidentLabel,
+    listRevisions,
+    listScopeKey,
+    requestScopeKey,
+    resolveActiveOrigin,
+    resolveRunAccess,
+    runInListScope,
+    unknownRunError,
+    type SubagentToolSession,
+} from "./output-payload.ts";
 import {
     extractChildEventFactsFromLog,
     loadHealthThresholdsFromConfig,
@@ -35,7 +49,6 @@ import {
     type HealthObservation,
 } from "./health-observation.ts";
 import {
-    appendHealthDiagnostic,
     formatHealthDiagnosticLine,
     statusThemeColor,
     truncateToVisibleWidth,
@@ -222,25 +235,49 @@ function displayThemeColor(status: string): string {
 type ToolDefinition = Parameters<ExtensionAPI["registerTool"]>[0];
 
 // ---- subagent_list --------------------------------------------------------
-export function subagentListTool(Type: TypeModule): ToolDefinition {
+export type { SubagentToolSession };
+
+/** The session provider bound to this tool call's host context. */
+function forCall(session: SubagentToolSession, ctx: unknown): SubagentToolSession {
+    const provider = session.getActiveOrigin;
+    if (typeof provider !== "function") return session;
+    return { getActiveOrigin: () => provider(ctx) };
+}
+
+export function subagentListTool(Type: TypeModule, baseSession: SubagentToolSession = {}): ToolDefinition {
     return {
         name: "subagent_list",
         label: "List Subagents",
         description:
-            `List background subagent runs with status and metadata. Non-blocking. ` +
-            `Default: this parent process only, newest first, limit ${SUBAGENT_LIST_DEFAULT_LIMIT}. ` +
-            `Pass all:true for machine-global; limit is clamped to max ${SUBAGENT_LIST_MAX_LIMIT}.`,
+            `List background subagent runs with compact status rows. Non-blocking. ` +
+            `Default: current session, newest first, limit ${SUBAGENT_LIST_DEFAULT_LIMIT} (1 KiB page). ` +
+            `Pass all:true for machine-global; limit is clamped to max ${SUBAGENT_LIST_MAX_LIMIT}. ` +
+            `Pass cursor to continue. Incident counts are compact; full failure text lives on subagent_result/output.`,
         promptSnippet: "List background subagent runs and their status",
         parameters: Type.Object({
-            all: Type.Optional(Type.Boolean({ description: "If true, list every run on this machine. Default false = only runs spawned by this pi process." })),
+            all: Type.Optional(Type.Boolean({ description: "If true, list every run on this machine. Default false = current session only." })),
             limit: Type.Optional(Type.Number({ description: `Maximum rows to display (default ${SUBAGENT_LIST_DEFAULT_LIMIT}, max ${SUBAGENT_LIST_MAX_LIMIT}; larger values are clamped).` })),
             status: Type.Optional(Type.Array(Type.String(), { description: `Effective statuses to include: ${SUBAGENT_LIST_STATUSES.join(", ")}.` })),
+            cursor: Type.Optional(Type.String({ description: "Caller-owned page or status cursor from a previous list response." })),
+            maxBytes: Type.Optional(Type.Number({ description: "UTF-8 byte budget for this page (default 1 KiB, max 4 KiB)." })),
         }),
-        async execute(_toolCallId: string, params: unknown) {
-            const p = (params ?? {}) as { all?: boolean; limit?: number; status?: string[] | string };
+        async execute(_toolCallId: string, params: unknown, _signal?: unknown, _onUpdate?: unknown, ctx?: unknown) {
+            const session = forCall(baseSession, ctx);
+            const p = (params ?? {}) as {
+                all?: boolean; limit?: number; status?: string[] | string; cursor?: string; maxBytes?: number;
+            };
             const now = Date.now();
-            const metas = listMetas();
-            // Cache observations per id so usage + health share one parse where needed.
+            const index = listRunRecords();
+            const metas = index.metas;
+            const parentPid = process.pid;
+            const resolved = resolveActiveOrigin(session);
+            const origin = resolved.origin;
+            const sessionAvailable = !(resolved.wired && !resolved.available);
+            const scopeKey = listScopeKey(p.all === true, origin, parentPid, sessionAvailable);
+            let sessionWarning: string | undefined;
+            if (p.all !== true && !sessionAvailable) {
+                sessionWarning = `Session identity unavailable; ownership of ${metas.length} run(s) cannot be verified, so none are listed. Pass all:true for machine-global.`;
+            }
             const healthCache = new Map<string, HealthObservation>();
             const healthById = (id: string) => {
                 const hit = healthCache.get(id);
@@ -251,117 +288,145 @@ export function subagentListTool(Type: TypeModule): ToolDefinition {
                 healthCache.set(id, obs);
                 return obs;
             };
-            return text(buildSubagentList({
+            const inScope = (meta: RunMeta) => runInListScope(
+                meta,
+                { all: p.all === true },
+                origin,
+                parentPid,
+                sessionAvailable,
+            );
+            const collected = collectSubagentList({
                 metas,
                 params: p,
-                parentPid: process.pid,
+                parentPid,
                 now,
                 statusOf: effectiveStatus,
-                usageById: (id: string) => parseRun(id).usage,
                 healthById,
-                failureById: (id: string) => {
-                    const meta = metas.find((m) => m.id === id);
-                    return meta ? failureSummary(id, meta.cwd, meta.status !== "running" && meta.status !== "orphaned") : "";
+                inScope,
+            });
+            const items = collected.items as Array<{ meta: RunMeta; status: string }>;
+            const incidents = new Map(items.map((row) => [row.meta.id, listIncidentCount(
+                row.meta.id,
+                row.meta.cwd,
+                row.meta.status !== "running" && row.meta.status !== "orphaned",
+            )] as const));
+            const revisions = listRevisions(
+                items.map((row) => ({ id: row.meta.id, status: String(row.status), meta: row.meta })),
+                items.map((row) => incidents.get(row.meta.id)?.revision ?? ""),
+            );
+            const statusesKey = Array.isArray(p.status) ? [...p.status].map(String).sort().join(",") : String(p.status ?? "");
+            const incidentRuns = items.filter((row) => (incidents.get(row.meta.id)?.count ?? 0) > 0).length;
+            return text(assembleSubagentListPayload({
+                warnings: collected.warnings,
+                items,
+                render: (row) => {
+                    const incident = incidents.get(row.meta.id);
+                    return formatSubagentListRow(row.meta, {
+                        status: row.status,
+                        now,
+                        health: healthById(row.meta.id),
+                        failure: formatIncidentLabel(incident?.count ?? 0, incident?.actionRequired ?? 0),
+                    });
                 },
+                limit: Math.max(1, collected.limit),
+                cursor: p.cursor,
+                maxBytes: p.maxBytes,
+                contentRevision: revisions.contentRevision,
+                failureRevision: revisions.failureRevision,
+                scopeKey,
+                statusesKey,
+                sessionWarning,
+                unreadable: index.unreadable,
+                indexError: index.indexError,
+                incidentRuns,
             }));
         },
     } as ToolDefinition;
 }
 
 // ---- subagent_output ------------------------------------------------------
-export function subagentOutputTool(Type: TypeModule): ToolDefinition {
+export function subagentOutputTool(Type: TypeModule, baseSession: SubagentToolSession = {}): ToolDefinition {
     return {
         name: "subagent_output",
         label: "Subagent Output",
         description:
-            "Tail the live output of a subagent run. Non-blocking: returns whatever exists right now and " +
-            "returns immediately whether or not the run has finished. Never waits.",
+            "Read a subagent run's current output without waiting. Default is a 1 KiB / 10-line excerpt of the current session. " +
+            "Pass all:true to read a foreign-session id. Pass mode=raw for retained-log pages (16 KiB default, 64 KiB cap). " +
+            "Pass cursor to continue or to poll for failure-only changes. Missing or unreadable logs are reported as gaps, not as empty healthy output.",
         promptSnippet: "Peek at a subagent's current output without waiting",
         promptGuidelines: [
             "Use subagent_output only when the user explicitly asks how a run is progressing. It never waits — do not call it in a loop.",
+            "Do not poll unchanged output. If the response says no new evidence since a cursor, stop.",
         ],
         parameters: Type.Object({
             id: Type.String({ description: "Run id from subagent_spawn." }),
-            tail_lines: Type.Optional(Type.Number({ description: "How many trailing lines to show (default 40)." })),
+            tail_lines: Type.Optional(Type.Number({ description: "Deprecated alias for lines." })),
+            lines: Type.Optional(Type.Number({ description: "Max lines in the default excerpt (default 10)." })),
+            cursor: Type.Optional(Type.String({ description: "Caller-owned page or status cursor from a previous response." })),
+            maxBytes: Type.Optional(Type.Number({ description: "UTF-8 byte budget for this page (default 1 KiB, max 4 KiB; raw default 16 KiB, max 64 KiB)." })),
+            mode: Type.Optional(Type.String({ description: "raw = page retained log bytes. Default is the bounded assembled excerpt." })),
+            all: Type.Optional(Type.Boolean({ description: "If true, allow a foreign-session id. Default is current session only." })),
         }),
-        async execute(_id: string, params: unknown) {
-            const p = params as { id: string; tail_lines?: number };
-            const meta = readMeta(p.id);
-            if (!meta) throw new Error(`Unknown run id: ${p.id}`);
-            const st = effectiveStatus(meta);
-            const r = parseRun(p.id);
-            const el = fmtElapsed((meta.endedAt ?? Date.now()) - meta.startedAt);
-            const spend = fmtSpend(r.usage);
-            const head = `[${p.id} · ${st} · ${el}${spend ? ` · ${spend}` : ""}]`;
-            const tools = r.toolCalls.length ? `\ntools used: ${r.toolCalls.join(", ")}` : "";
-            const raw = tailLog(p.id, p.tail_lines ?? 40);
-            const body = formatSubagentOutputBody(
-                head,
-                tools,
-                r.finalText || r.lastActivity || undefined,
-                raw,
-                r.diagnostics,
-            );
-            // Health diagnostics for orphaned/lost/degraded only (#67). Healthy/quiet
-            // stays on today's body. Independent of meta.callback.
-            const healthLine = formatHealthDiagnosticLine(observeMetaHealth(meta));
-            return text(prependFailureSummary(appendHealthDiagnostic(body, healthLine), failureSummary(p.id, meta.cwd, st !== "running" && st !== "orphaned")));
+        async execute(_id: string, params: unknown, _signal?: unknown, _onUpdate?: unknown, ctx?: unknown) {
+            const session = forCall(baseSession, ctx);
+            const p = params as { id: string; cursor?: string; maxBytes?: number; mode?: string; all?: boolean; lines?: number; tail_lines?: number };
+            const access = resolveRunAccess(p.id, p, session);
+            if (access.kind === "missing") throw unknownRunError(p.id);
+            if (access.kind === "unreadable") return text(assembleUnreadableMetadata(p.id, access.detail, p));
+            if (access.kind === "denied") return text(access.payload);
+            const scopeKey = requestScopeKey(p, session);
+            const healthLine = formatHealthDiagnosticLine(observeMetaHealth(access.meta));
+            return text(assembleSubagentOutput(p.id, access.meta, p, healthLine, scopeKey));
         },
     } as ToolDefinition;
 }
 
 // ---- subagent_result ------------------------------------------------------
-export function subagentResultTool(Type: TypeModule): ToolDefinition {
+export function subagentResultTool(Type: TypeModule, baseSession: SubagentToolSession = {}): ToolDefinition {
     return {
         name: "subagent_result",
         label: "Subagent Result",
         description:
-            "Read a subagent's final output if it has finished. NEVER waits: if the run is still going it " +
-            "says so and returns immediately.",
+            "Read a subagent's final output if it has finished. NEVER waits. Default current session. Ordinary answers are preserved verbatim in a 2 KiB UTF-8 page (max 8 KiB); pass cursor to reconstruct the rest. Pass all:true for a foreign-session id. mode=raw pages retained log bytes (16 KiB default, 64 KiB cap). Failures and exceptional lifecycle facts come before progress. No tool-name histories or default cost lines.",
         promptSnippet: "Read a finished subagent's final result (never waits)",
         promptGuidelines: [
             "Use subagent_result to collect a finished run's output. If it reports the run is still going, stop — do not poll; you'll be notified when it finishes.",
+            "If the response includes nextCursor, call again with that cursor to read the rest of the answer. Do not summarize away unread pages.",
         ],
         parameters: Type.Object({
             id: Type.String({ description: "Run id from subagent_spawn." }),
+            cursor: Type.Optional(Type.String({ description: "Caller-owned answer page or status cursor from a previous response." })),
+            maxBytes: Type.Optional(Type.Number({ description: "UTF-8 byte budget for this page (default 2 KiB, max 8 KiB)." })),
+            mode: Type.Optional(Type.String({ description: "raw = page retained log bytes (16 KiB default, 64 KiB cap). Default is the bounded assembled result." })),
+            all: Type.Optional(Type.Boolean({ description: "If true, allow a foreign-session id. Default is current session only." })),
         }),
         renderResult(result: unknown, options: unknown, theme: unknown) {
             return renderSubagentResultDisplay(result, options, theme);
         },
-        async execute(_id: string, params: unknown) {
-            const p = params as { id: string };
-            const meta = readMeta(p.id);
-            if (!meta) throw new Error(`Unknown run id: ${p.id}`);
+        async execute(_id: string, params: unknown, _signal?: unknown, _onUpdate?: unknown, ctx?: unknown) {
+            const session = forCall(baseSession, ctx);
+            const p = params as { id: string; cursor?: string; maxBytes?: number; mode?: string; all?: boolean };
+            const access = resolveRunAccess(p.id, p, session);
+            if (access.kind === "missing") throw unknownRunError(p.id);
+            if (access.kind === "unreadable") {
+                return subagentResultText(assembleUnreadableMetadata(p.id, access.detail, p));
+            }
+            if (access.kind === "denied") return subagentResultText(access.payload);
+            const meta = access.meta;
+            const scopeKey = requestScopeKey(p, session);
             const st = effectiveStatus(meta);
+            const healthLine = formatHealthDiagnosticLine(observeMetaHealth(meta));
             if (!isFinalResultStatus(st)) {
                 if (st === "orphaned") {
-                    // Non-terminal: supervision is broken but related process-
-                    // group work may still be alive — never present this as a
-                    // final result. Surface best-CURRENT artifacts (#65) plus
-                    // health diagnostic (#67).
-                    const r = parseRun(p.id);
-                    const el = fmtElapsed((meta.endedAt ?? Date.now()) - meta.startedAt);
-                    const spend = fmtSpend(r.usage);
-                    const tools = r.toolCalls.length ? ` · tools: ${r.toolCalls.join(", ")}` : "";
-                    const head = `[${p.id} · orphaned · ${el}${spend ? ` · ${spend}` : ""}${tools}]`;
-                    const rawTail = tailLog(p.id, 40);
-                    const body = `${head}\n${formatOrphanedResult(r, rawTail)}`;
-                    const healthLine = formatHealthDiagnosticLine(observeMetaHealth(meta));
-                    return subagentResultText(prependFailureSummary(appendHealthDiagnostic(body, healthLine), failureSummary(p.id, meta.cwd)));
+                    return subagentResultText(assembleOrphanedResult(p.id, meta, healthLine, p, scopeKey));
                 }
-                return subagentResultText(prependFailureSummary(`Run ${p.id} is still running — no result yet. You'll be notified when it finishes; don't poll.`, failureSummary(p.id, meta.cwd)));
+                return subagentResultText(assembleRunningResult(p.id, meta, p, scopeKey));
             }
-            // Lifecycle-aware body (complete-stream authority + diagnostics).
-            // Lost runs go through formatLostResult inside formatSubagentResult (#65).
-            const body = buildSubagentResultText(p.id);
+            const body = buildSubagentResultPayload(p.id, p, healthLine, scopeKey);
             if (body === null) {
-                // Defensive: status race between effectiveStatus and body assembly.
-                return subagentResultText(`Run ${p.id} is still running — no result yet. You'll be notified when it finishes; don't poll.`);
+                return subagentResultText(assembleRunningResult(p.id, meta, p, scopeKey));
             }
-            // Append degraded/lost health facts when present; completed/failed
-            // happy paths stay quiet when observation is non-actionable.
-            const healthLine = formatHealthDiagnosticLine(observeMetaHealth(meta));
-            return subagentResultText(prependFailureSummary(appendHealthDiagnostic(body, healthLine), failureSummary(p.id, meta.cwd, true)));
+            return subagentResultText(body);
         },
     } as ToolDefinition;
 }