@tt-a1i/openpi 0.1.1 → 0.3.0

package/extensions/subagents/index.ts

@@ -31,9 +31,9 @@ import type {
   ExtensionCommandContext,
   ExtensionContext,
   ExtensionUIContext,
+  MessageRenderer,
 } from "@earendil-works/pi-coding-agent";
 import {
-  CustomEditor,
   DEFAULT_MAX_BYTES,
   DEFAULT_MAX_LINES,
   defineTool,
@@ -65,6 +65,14 @@ import {
   hasActivity,
   unreadActivityCounts,
 } from "../shared/activity-status.ts";
+import {
+  OPENPI_TOOL_SURFACE,
+  patchOwnedTools,
+} from "../shared/tool-surface.ts";
+import {
+  registerEditorLayer,
+  removeEditorLayer,
+} from "../shared/editor-layers.ts";
 import { formatContextUtilization } from "./src/format.ts";
 import { SubagentManager, type SubagentManagerShape } from "./src/manager.ts";
 import {
@@ -121,6 +129,7 @@ import {
 } from "./navigation.ts";
 import { openSubagentPicker, openSubagentTakeover } from "./src/ui/takeover.ts";
 import {
+  buildWaitResultPreview,
   renderWaitResult,
   type WaitResultDetails,
 } from "./src/ui/wait-result.ts";
@@ -144,6 +153,23 @@ interface SubagentFinishedData {
   readonly elapsed: string;
 }
 
+interface SubagentResultDetails {
+  readonly id?: string;
+  readonly title?: string;
+  readonly status?: SubagentSnapshot["status"];
+  readonly count?: number;
+  readonly results?: ReadonlyArray<{
+    readonly id: string;
+    readonly title: string;
+    readonly status: SubagentSnapshot["status"];
+  }>;
+}
+
+interface SubagentResultEntryData {
+  readonly content: string;
+  readonly details: SubagentResultDetails;
+}
+
 interface BtwResultData {
   readonly id: string;
   readonly title: string;
@@ -180,6 +206,104 @@ function truncatedOutput(
   return text;
 }
 
+export function createSubagentResultDispatcher(
+  pi: ExtensionAPI,
+  outputFor: (snap: SubagentSnapshot) => string = truncatedOutput,
+) {
+  return (snaps: readonly SubagentSnapshot[], wake: boolean) => {
+    if (snaps.length === 0) return;
+    const content = snaps
+      .map((snap) =>
+        buildSubagentResultMessage({
+          id: snap.id,
+          title: snap.title,
+          status: snap.status,
+          errorText: snap.errorText,
+          output: outputFor(snap),
+        }),
+      )
+      .join("\n\n");
+    const details: SubagentResultDetails =
+      snaps.length === 1
+        ? {
+            id: snaps[0]!.id,
+            title: snaps[0]!.title,
+            status: snaps[0]!.status,
+          }
+        : {
+            count: snaps.length,
+            results: snaps.map((snap) => ({
+              id: snap.id,
+              title: snap.title,
+              status: snap.status,
+            })),
+          };
+    pi.appendEntry<SubagentResultEntryData>("subagent-result", {
+      content,
+      details,
+    });
+    pi.sendMessage(
+      {
+        customType: "subagent-result",
+        content,
+        display: false,
+        details,
+      },
+      resultDeliveryOptions(wake),
+    );
+  };
+}
+
+type SubagentResultTheme = Parameters<MessageRenderer>[2];
+
+function renderSubagentResult(
+  content: string,
+  details: SubagentResultDetails,
+  expanded: boolean,
+  theme: SubagentResultTheme,
+) {
+  if (!expanded && loadSetupConfig().ui.subagentResultDisplay === "compact") {
+    const results = details.results?.length
+      ? details.results
+      : details.id
+        ? [
+            {
+              id: details.id,
+              title: details.title,
+              status: details.status,
+            },
+          ]
+        : [];
+    return new Text(buildWaitResultPreview(content, { results }, theme), 0, 0);
+  }
+
+  const failed = details.status === "error";
+  const icon = failed ? theme.fg("error", "x") : theme.fg("success", "■");
+  const header =
+    `${icon} ` +
+    theme.fg("accent", theme.bold(`subagent ${details.id ?? "?"}`)) +
+    theme.fg(
+      "muted",
+      ` · ${details.title ?? ""} · ${failed ? "failed" : "finished"}`,
+    );
+
+  // Remove only the summary line. The following Error line (when present)
+  // is part of the actual result and must remain visible.
+  const body = content.split("\n").slice(1).join("\n").trim();
+  const md = new Markdown(body, 0, 0, getMarkdownTheme());
+  const container = new Text(header, 0, 0);
+  return {
+    render: (width: number) => [
+      ...container.render(width),
+      ...md.render(width),
+    ],
+    invalidate: () => {
+      container.invalidate();
+      md.invalidate();
+    },
+  };
+}
+
 export default function (pi: ExtensionAPI) {
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
@@ -196,8 +320,18 @@ export default function (pi: ExtensionAPI) {
   let navigationManager: SubagentManagerShape | undefined;
   let widgetVisible = false;
   let requestWidgetRender: (() => void) | undefined;
+  let navigationLayerRegistered = false;
   let dashboardOpen = false;
   const resultDelivery = createDeferredResultDelivery<SubagentSnapshot>();
+  const dispatchResults = createSubagentResultDispatcher(pi);
+  const hideLifecycleTools = () =>
+    patchOwnedTools(pi, "subagents", {
+      disable: OPENPI_TOOL_SURFACE.subagents.deferred,
+    });
+  const showLifecycleTools = () =>
+    patchOwnedTools(pi, "subagents", {
+      enable: OPENPI_TOOL_SURFACE.subagents.deferred,
+    });
 
   const getRuntime = () => (runtime ??= createSubagentRuntime());
 
@@ -280,26 +414,26 @@ export default function (pi: ExtensionAPI) {
 
   const installSubagentNavigation = (ctx: ExtensionContext) => {
     if (ctx.mode !== "tui") return;
-    const previous = ctx.ui.getEditorComponent();
-    ctx.ui.setEditorComponent((tui, theme, keybindings) => {
-      const base =
-        previous?.(tui, theme, keybindings) ??
-        new CustomEditor(tui, theme, keybindings);
-      return new BelowEditorNavigationEditor(
-        base,
-        keybindings,
-        stripState,
-        () => Boolean(stripEntry()),
-        () => {
-          const entry = stripEntry();
-          if (entry) void openDashboard(ctx, entry.snapshot.id);
-        },
-        () => {
-          requestWidgetRender?.();
-          tui.requestRender();
-        },
-      );
+    registerEditorLayer(pi, ctx, {
+      id: "subagents",
+      order: 100,
+      wrap: (base, tui, _theme, keybindings) =>
+        new BelowEditorNavigationEditor(
+          base,
+          keybindings,
+          stripState,
+          () => Boolean(stripEntry()),
+          () => {
+            const entry = stripEntry();
+            if (entry) void openDashboard(ctx, entry.snapshot.id);
+          },
+          () => {
+            requestWidgetRender?.();
+            tui.requestRender();
+          },
+        ),
     });
+    navigationLayerRegistered = true;
   };
 
   /**
@@ -314,41 +448,7 @@ export default function (pi: ExtensionAPI) {
     snaps: readonly SubagentSnapshot[],
     wake: boolean,
   ) => {
-    if (snaps.length === 0) return;
-    pi.sendMessage(
-      {
-        customType: "subagent-result",
-        // One message per flush, not per subagent.
-        content: snaps
-          .map((snap) =>
-            buildSubagentResultMessage({
-              id: snap.id,
-              title: snap.title,
-              status: snap.status,
-              errorText: snap.errorText,
-              output: truncatedOutput(snap),
-            }),
-          )
-          .join("\n\n"),
-        display: true,
-        details:
-          snaps.length === 1
-            ? {
-                id: snaps[0]!.id,
-                title: snaps[0]!.title,
-                status: snaps[0]!.status,
-              }
-            : {
-                count: snaps.length,
-                results: snaps.map((snap) => ({
-                  id: snap.id,
-                  title: snap.title,
-                  status: snap.status,
-                })),
-              },
-      },
-      resultDeliveryOptions(wake),
-    );
+    dispatchResults(snaps, wake);
   };
 
   const flushResults = (wake: boolean) => {
@@ -408,6 +508,7 @@ export default function (pi: ExtensionAPI) {
 
   pi.on("session_start", (_event, ctx) => {
     refreshAgentTypes(ctx.cwd, ctx.isProjectTrusted());
+    hideLifecycleTools();
     sessionContext = ctx;
     settledAcknowledgedAt = 0;
     if (ctx.hasUI) ui = ctx.ui;
@@ -434,6 +535,10 @@ export default function (pi: ExtensionAPI) {
   pi.on("agent_settled", () => flushResults(false));
 
   pi.on("session_shutdown", async () => {
+    if (navigationLayerRegistered) {
+      removeEditorLayer(pi, "subagents");
+      navigationLayerRegistered = false;
+    }
     resultDelivery.clear();
     unsubStatus?.();
     unsubStatus = undefined;
@@ -681,6 +786,8 @@ export default function (pi: ExtensionAPI) {
         throw error;
       }
 
+      showLifecycleTools();
+
       return {
         content: [
           {
@@ -1036,52 +1143,28 @@ export default function (pi: ExtensionAPI) {
   pi.registerMessageRenderer(
     "subagent-result",
     (message, { expanded }, theme) => {
-      const details = (message.details ?? {}) as {
-        id?: string;
-        title?: string;
-        status?: string;
-      };
-      const failed = details.status === "error";
-      const icon = failed ? theme.fg("error", "x") : theme.fg("success", "■");
-      const header =
-        `${icon} ` +
-        theme.fg("accent", theme.bold(`subagent ${details.id ?? "?"}`)) +
-        theme.fg(
-          "muted",
-          ` · ${details.title ?? ""} · ${failed ? "failed" : "finished"}`,
-        );
-
       const content =
         typeof message.content === "string" ? message.content : "";
-      // Remove only the summary line. The following Error line (when present)
-      // is part of the actual result and must remain visible.
-      const body = content.split("\n").slice(1).join("\n").trim();
-
-      if (expanded || loadSetupConfig().ui.subagentResultDisplay === "full") {
-        const md = new Markdown(`${body}`, 0, 0, getMarkdownTheme());
-        const container = new Text(header, 0, 0);
-        return {
-          render: (width: number) => [
-            ...container.render(width),
-            ...md.render(width),
-          ],
-          invalidate: () => {
-            container.invalidate();
-            md.invalidate();
-          },
-        };
-      }
-
-      const previewLines = body.split("\n").slice(0, 8);
-      let text = header;
-      for (const line of previewLines)
-        text += `\n${theme.fg("toolOutput", line)}`;
-      if (body.split("\n").length > 8)
-        text += `\n${theme.fg("dim", `... (${keyHint("app.tools.expand", "to expand")})`)}`;
-      return new Text(text, 0, 0);
+      return renderSubagentResult(
+        content,
+        (message.details ?? {}) as SubagentResultDetails,
+        expanded,
+        theme,
+      );
     },
   );
 
+  pi.registerEntryRenderer<SubagentResultEntryData>(
+    "subagent-result",
+    (entry, { expanded }, theme) =>
+      renderSubagentResult(
+        entry.data?.content ?? "",
+        entry.data?.details ?? {},
+        expanded,
+        theme,
+      ),
+  );
+
   pi.registerEntryRenderer<SubagentFinishedData>(
     "subagent-finished",
     (entry, _options, theme) => {

package/extensions/subagents/src/manager.ts

@@ -205,7 +205,8 @@ const makeManager = Effect.gen(function* () {
   let reservedBtw = 0;
   let disposed = false;
   let onSettled:
-    ((snap: SubagentSnapshot, consumed: boolean) => void) | undefined;
+    | ((snap: SubagentSnapshot, consumed: boolean) => void)
+    | undefined;
 
   const notify = (id?: string) => {
     const waiters = changeWaiters;
@@ -636,16 +637,17 @@ const makeManager = Effect.gen(function* () {
             pruneSettled();
           }),
         ),
-        Effect.map((): ReadonlyArray<CancelResult> =>
-          unique.map((id) => {
-            const snapshot = entries.get(id)?.snapshot;
-            return {
-              id,
-              title: snapshot?.title ?? "?",
-              status: snapshot?.status ?? "error",
-              cancelled: runningIds.includes(id),
-            };
-          }),
+        Effect.map(
+          (): ReadonlyArray<CancelResult> =>
+            unique.map((id) => {
+              const snapshot = entries.get(id)?.snapshot;
+              return {
+                id,
+                title: snapshot?.title ?? "?",
+                status: snapshot?.status ?? "error",
+                cancelled: runningIds.includes(id),
+              };
+            }),
         ),
       );
     });

package/extensions/subagents/src/prompt.ts

@@ -8,7 +8,7 @@ import { MAX_RUNNING } from "./manager.ts";
 
 /** Describes subagent_spawn, including the fixed concurrency cap. */
 export const SUBAGENT_SPAWN_TOOL_DESCRIPTION =
-  "Spawn a background subagent: a fully autonomous, headless pi session with its own context window, this environment's tools and config, and normal host permissions. Fire-and-forget: this returns immediately with an id. The subagent's final output is queued back to you as a message when it settles, or collect it explicitly with subagent_wait. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. " +
+  "Spawn a background subagent: a fully autonomous, headless pi session with its own context window, this environment's tools and config, and normal host permissions. Fire-and-forget: this returns immediately with an id, and the subagent's final output is automatically queued back to you as a message when it settles. In an interactive session, keep working or end your turn so the user remains able to interact; do not block merely because a later step depends on the result. Children cannot orchestrate more agents/workflows or ask the user, and cannot see this conversation, so the prompt must be self-contained. Only use trusted working directories. " +
   `Max ${MAX_RUNNING} subagents can be running at once.`;
 
 /**
@@ -62,7 +62,7 @@ export const SUBAGENT_SPAWN_PROMPT_SNIPPET =
 /** Guides the parent model to delegate standalone tasks and avoid unnecessary blocking waits. */
 export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
   "Reserve subagent_spawn for substantial, self-contained work; give it a complete, standalone prompt. For a single lookup or edit you can do inline, just do it — each subagent spends a fresh context window and cannot see this conversation.",
-  "After subagent_spawn, keep working on other things; results arrive automatically and you are re-invoked when a subagent settles. Do not poll with subagent_check and do not subagent_wait just to sit idle — wait only when your next step genuinely cannot proceed without the result, and never answer from a guessed result before it arrives.",
+  "After subagent_spawn, keep working on independent work. If none remains in an interactive session, briefly tell the user the subagent is running in the background and end your turn; its result arrives automatically and you are re-invoked when it settles. Do not poll with subagent_check. Do not call subagent_wait merely because your next step depends on the result or because you have nothing else to do. Block only when the user explicitly asks you to keep the current response open for these results, or when a non-interactive automation must return them in the same invocation. Never answer from a guessed result before it arrives.",
 ];
 
 /** Model-facing schema descriptions for subagent_spawn task and execution options. */
@@ -75,7 +75,7 @@ export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
   workingDir:
     "Trusted working directory for the autonomous child (default: current working directory)",
   isolation:
-    'Set to "worktree" to run this child in its own git worktree on its own branch, branched from HEAD. Use it whenever children may edit the same files or stage changes concurrently — without it, parallel children share one checkout and one git index, so their edits and `git add`s overwrite each other. The child should COMMIT its work. A direct child can receive later subagent_send turns, so its checkout lives with that child Session. On retirement it is reclaimed only when a bounded inspection proves it empty; commits, dirty/untracked/ignored files, detached HEAD, timeout, or Git failure preserve it. Requires a git repository, and the checkout starts clean, so anything gitignored (build output, .env) will not be there.',
+    'Set to "worktree" for concurrent writers and tell the child to commit. Requires Git and a clean checkout. Read the subagents Skill for lifecycle, merge location, and costs.',
   model:
     'Optional model override, as "provider/model-id" or a bare id resolved against the current provider. Precedence: explicit spawn model > selected type file model > configured built-in role model > parent model. Never guess a model name.',
   reasoningEffort:
@@ -113,14 +113,14 @@ export function buildSubagentSpawnResult(options: {
     : "";
   return (
     `Spawned subagent ${options.id} "${options.title}" (${options.harness}: ${options.modelLabel}, ${options.cwd}).${typeNote}${toolNote}${worktreeNote}\n` +
-    `It runs in the background — keep working on other things; its result is delivered to you automatically when it finishes, so do not poll or wait for it. ` +
-    `Only if your next step truly cannot proceed without it, subagent_wait(ids: ["${options.id}"]) blocks for it; subagent_cancel stops it, subagent_check peeks at a running one, subagent_list shows all.`
+    `It runs in the background — keep working on independent work. If none remains in an interactive session, briefly tell the user it is still running and end your turn; its result is delivered automatically and you are automatically re-invoked when it finishes. Do not poll or call subagent_wait merely because a later step depends on it. ` +
+    `Use subagent_wait(ids: ["${options.id}"]) only if the user explicitly asked you to keep the current response open for this result, or a non-interactive automation must return it in the same invocation; subagent_cancel stops it, subagent_check peeks at a running one, subagent_list shows all.`
   );
 }
 
 /** Describes explicit blocking collection of one or more subagent results. */
 export const SUBAGENT_WAIT_TOOL_DESCRIPTION =
-  "Block until all listed subagents have settled, then return their final outputs. This is the EXCEPTION, not the default: after spawning, keep doing other useful work — each subagent's result is delivered to you automatically when it settles, and you'll be re-invoked then. Call subagent_wait only when your very next step cannot proceed without the result (e.g. you must synthesize several children's outputs and have nothing else to do first). Never poll for completion and never answer from a guessed result before it arrives.";
+  "Block until all listed subagents have settled, then return their final outputs. This is an explicit synchronous barrier, not the default. In an interactive session, call it only when the user explicitly asks you to keep the current response open for these results. A dependent next step or having nothing else to do is not sufficient: end your turn and let automatic result delivery re-invoke you while the user remains free to interact. In a non-interactive automation, use it only when the same invocation must return the completed results. Never poll for completion and never answer from a guessed result before it arrives.";
 
 /** Model-facing schema description for the subagent ids to await. */
 export const SUBAGENT_WAIT_PARAMETER_DESCRIPTIONS = {
@@ -154,7 +154,7 @@ export function buildSubagentSendResult(options: {
 }) {
   return options.wasRunning
     ? `Steered ${options.id} "${options.title}". It is queued into the active run; the result is delivered when it settles.`
-    : `Restarted ${options.id} "${options.title}" for another turn on its existing transcript. The result is delivered when it settles, or use subagent_wait(ids: ["${options.id}"]) to block for it.`;
+    : `Restarted ${options.id} "${options.title}" for another turn on its existing transcript. The result is delivered automatically when it settles.`;
 }
 
 /** Describes nonblocking inspection of a subagent without consuming its result. */