shariq-pi-extensions 0.2.5 → 0.2.7

package/docs/EXTENSIONS.md

@@ -38,7 +38,7 @@ The goal extension adds persistent, branch-safe objectives, progress evidence, b
 
 The subagent extension runs flat Pi child agents with profiles, capability policies, continuation, result delivery, optional worktrees, and a dashboard. Configuration lives in `<agent-dir>/subagents.json`; trusted projects may override it through their Pi config directory. The configured concurrency ceiling is 50.
 
-The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement automatically sends a follow-up that starts the next parent turn; status tools are for explicit inspection, not waiting.
+The extension supplies tools including `spawn_agent`, `task`, `check_agent`, `list_agents`, `wait_agent`, `send_message`, `close_agent`, `reply_question`, and `apply_agent_changes`. Child settlement is handed to Pi immediately as an extension-originated user follow-up, so Pi queues it while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context; status tools are for explicit inspection, not waiting.
 
 ### [Orchestration](../extensions/orchestration/README.md)
 
@@ -50,7 +50,7 @@ The model-facing `create_orchestration` tool starts planning only after an expli
 
 Managed PTYs support servers, watchers, long builds, downloads, and interactive processes. The extension tracks up to eight concurrent terminals, retains bounded output, stores full logs in restrictive temporary directories, and stops process groups during shutdown or reload.
 
-Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal automatically sends a completion or failure follow-up and starts the next parent turn. Reading a terminal no longer suppresses that delivery; agents should inspect only for explicit progress requests or immediate interaction.
+Its tools are `start_terminal`, `read_terminal`, `write_terminal`, `list_terminals`, and `stop_terminal`. A model-started terminal immediately hands its completion or failure to Pi as an extension-originated user follow-up, which Pi queues while the parent is active or uses to start a new parent turn when idle with the bounded output guaranteed in model context. Reading a terminal does not suppress that delivery; agents should inspect only for explicit progress requests or immediate interaction.
 
 ## Web access
 

package/extensions/background-terminals/README.md

@@ -10,7 +10,7 @@ Session-scoped background pseudo-terminals for Pi. The extension combines Codex-
 - `list_terminals` — list running and settled terminals.
 - `stop_terminal` — stop complete process groups with TERM-to-KILL escalation.
 
-Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Completion wakes the parent automatically, so it can continue other work or end its turn rather than poll.
+Each output response carries a byte cursor. Pass it to the next read/write operation to avoid repeating output. Long or uncertain commands should use `start_terminal` instead of a large blocking `bash` timeout. Settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with bounded output guaranteed in model context, so the parent can continue other work or end its turn rather than poll.
 
 ## User interface
 
@@ -34,7 +34,7 @@ Each output response carries a byte cursor. Pass it to the next read/write opera
 - Output is sanitized before TUI or model rendering.
 - Processes run in their own PTY process group and are stopped on session shutdown, replacement, or reload.
 - Shutdown and stop operations are bounded and escalate from SIGTERM to SIGKILL.
-- Model-started terminals automatically deliver one completion/failure follow-up that starts the next parent turn.
+- Model-started terminals immediately hand one model-visible completion/failure follow-up to Pi; Pi queues it while the parent is active or starts the next parent turn when idle.
 - Reading settled output does not consume or suppress the automatic completion delivery.
 - Completion delivery is keyed by terminal id to prevent duplicate follow-ups.
 

package/extensions/background-terminals/index.ts

@@ -3,12 +3,12 @@ import * as path from "node:path";
 import type {
   ExtensionAPI,
   ExtensionCommandContext,
-  ExtensionContext,
   ExtensionUIContext,
 } from "@earendil-works/pi-coding-agent";
 import { getMarkdownTheme } from "@earendil-works/pi-coding-agent";
 import { Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { deliverSettlement } from "../shared/settlement-delivery.ts";
 import { oneLine, sanitizeTerminalText, stateLabel } from "../shared/tui-dashboard.ts";
 import { TerminalManager, MAX_RUNNING_TERMINALS } from "./src/manager.ts";
 import {
@@ -37,12 +37,12 @@ function resolveCwd(base: string, requested?: string): string {
 
 export default function backgroundTerminals(pi: ExtensionAPI) {
   let manager: TerminalManager | undefined;
-  let sessionContext: ExtensionContext | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubscribe: (() => void) | undefined;
   let lastStatus = "";
   const pendingResults = new Map<string, TerminalSnapshot>();
   const modelOwned = new Set<string>();
+  const starting = new Set<string>();
 
   const getManager = (): TerminalManager => {
     if (manager) return manager;
@@ -56,7 +56,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
         return;
       }
       pendingResults.set(snapshot.id, snapshot);
-      if (sessionContext?.isIdle()) flushResults();
+      if (!starting.has(snapshot.id)) flushResult(snapshot.id);
     });
     unsubscribe = manager.view.subscribe(updateStatus);
     updateStatus();
@@ -85,40 +85,31 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     }
   }
 
-  function deliver(snapshot: TerminalSnapshot): void {
-    pi.sendMessage(
-      {
-        customType: "background-terminal-result",
-        content: formatCompletion(snapshot),
-        display: true,
-        details: {
-          id: snapshot.id,
-          title: snapshot.title,
-          status: snapshot.status,
-          exitCode: snapshot.exitCode,
-        },
+  function flushResult(id: string): void {
+    const snapshot = pendingResults.get(id);
+    if (!snapshot) return;
+    pendingResults.delete(id);
+    deliverSettlement(pi, {
+      customType: "background-terminal-result",
+      content: formatCompletion(snapshot),
+      display: true,
+      details: {
+        id: snapshot.id,
+        title: snapshot.title,
+        status: snapshot.status,
+        exitCode: snapshot.exitCode,
       },
-      { deliverAs: "followUp", triggerTurn: true },
-    );
-  }
-
-  function flushResults(): void {
-    const results = [...pendingResults.values()];
-    pendingResults.clear();
-    for (const snapshot of results) deliver(snapshot);
+    });
   }
 
   pi.on("session_start", (_event, ctx) => {
-    sessionContext = ctx;
     if (ctx.hasUI) ui = ctx.ui;
   });
 
-  pi.on("agent_settled", flushResults);
-
   pi.on("session_shutdown", async () => {
-    sessionContext = undefined;
     pendingResults.clear();
     modelOwned.clear();
+    starting.clear();
     unsubscribe?.();
     unsubscribe = undefined;
     ui?.setStatus(STATUS_KEY, undefined);
@@ -140,7 +131,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
     promptSnippet: "Start an interactive or long-running command in a managed background PTY.",
     promptGuidelines: [
       "Use start_terminal by default for servers, watchers, downloads, long or uncertain builds and tests, interactive shells, and any command that should not occupy the main turn; reserve bash for short commands whose result is needed immediately. Never use a large bash timeout merely to wait for long work.",
-      "After start_terminal returns, continue only genuinely independent work. If none remains, end the turn immediately. The terminal completion automatically sends a follow-up and starts the next parent turn; do not call read_terminal, list_terminals, or start a timer merely to check whether it finished.",
+      "After start_terminal returns, continue only genuinely independent work. If none remains, end the turn immediately. Terminal settlement is handed to Pi immediately: it queues a follow-up while the parent is active or starts the next parent turn when idle. When that result invokes the parent, continue the original task immediately without waiting for the user or rereading the same terminal; do not call read_terminal, list_terminals, or start a timer merely to check whether it finished.",
       "Use stop_terminal when a managed process is no longer needed. Background terminals are session-scoped and are stopped during session shutdown or reload.",
     ],
     parameters: Type.Object({
@@ -158,6 +149,7 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
         cwd: resolveCwd(ctx.cwd, params.working_dir),
       });
       modelOwned.add(terminal.id);
+      starting.add(terminal.id);
       let result: TerminalReadResult;
       try {
         result = await getManager().read(terminal.id, {
@@ -166,12 +158,15 @@ export default function backgroundTerminals(pi: ExtensionAPI) {
           signal,
         });
       } catch (error) {
-        await getManager().kill([terminal.id]).catch(() => undefined);
+        starting.delete(terminal.id);
         modelOwned.delete(terminal.id);
+        await getManager().kill([terminal.id]).catch(() => undefined);
         consume(terminal.id);
         throw error;
       }
+      starting.delete(terminal.id);
       if (result.snapshot.status !== "running") consume(terminal.id);
+      else flushResult(terminal.id);
       let text = `Started background terminal ${terminal.id} "${oneLine(terminal.title)}" (pid ${terminal.pid}). Use cursor ${result.cursor} for incremental reads.`;
       if (result.text || result.snapshot.status !== "running") {
         text += `\n\n${formatReadResult(result)}`;

package/extensions/shared/README.md

@@ -8,6 +8,7 @@ Internal runtime utilities used by more than one extension. This directory is no
 - `child-session.ts` owns trust-aware child resources and bounded session shutdown.
 - `context-utilization.ts` formats model-context usage and capacity.
 - `dashboard-state.ts` keeps list selection stable as live rows change.
+- `settlement-delivery.ts` immediately hands asynchronous results to Pi as extension-originated user follow-ups, guaranteeing model-visible settlement context.
 - `tool-call-timeout.ts` applies cancellation-aware execution limits to registered tools.
 - `tui-dashboard.ts` provides bounded, sanitized terminal-dashboard rendering helpers.
 

package/extensions/shared/settlement-delivery.ts

@@ -0,0 +1,19 @@
+import type { ExtensionAPI } from "@earendil-works/pi-coding-agent";
+
+type SettlementMessage = Parameters<ExtensionAPI["sendMessage"]>[0];
+
+/**
+ * Hand settlement to Pi as an extension-originated user follow-up. A custom
+ * message can wake the parent yet fail to appear in the invoked model turn;
+ * sendUserMessage guarantees that the bounded result is model-visible. Pi
+ * starts a turn when idle and queues the same input while the parent is active.
+ */
+export function deliverSettlement(pi: ExtensionAPI, message: SettlementMessage): void {
+  const content = typeof message.content === "string"
+    ? message.content
+    : message.content
+      .filter((part) => part.type === "text")
+      .map((part) => part.text)
+      .join("\n");
+  pi.sendUserMessage(content, { deliverAs: "followUp" });
+}

package/extensions/subagents/README.md

@@ -19,7 +19,7 @@ The system is deliberately flat. Only the main Pi thread can spawn subagents. Ch
 - `reply_question` — answer a child’s blocking `ask_parent` request
 - `task` — atomically reserve capacity for up to the configured limit (maximum 50), start the fan-out in the background, and return child ids immediately
 
-Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Background completions wake the parent automatically, so the main turn can continue independent work or end and remain available to the user.
+Child sessions receive `message_parent`, `ask_parent`, `list_peers`, and `message_peer`. Peer messages are routed through the main-thread manager and can steer a running child or continue a settled one; they cannot create agents. Child settlement is handed to Pi immediately as an extension-originated user follow-up: it queues while the parent is active or starts a new parent turn when idle with the summary guaranteed in model context, so the main turn can continue independent work or end and remain available to the user.
 
 ## Profiles and capabilities
 
@@ -86,4 +86,3 @@ Children share the requested workspace by default. Use `isolation: "worktree"` o
 - `src/worktree.ts` — isolated worktree creation, inspection, conflict preflight, integration, and cleanup
 - `src/runtime.ts` — managed runtime and Pi backend registry
 - `src/ui/` — dashboard, transcript, and takeover components
-- `src/result-delivery.ts` — deferred automatic result delivery

package/extensions/subagents/index.ts

@@ -26,6 +26,7 @@ import {
 } from "@earendil-works/pi-coding-agent";
 import { Markdown, Text } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
+import { deliverSettlement } from "../shared/settlement-delivery.ts";
 import {
   formatElapsed,
   latestText,
@@ -56,7 +57,6 @@ import {
   SUBAGENT_WAIT_TOOL_DESCRIPTION,
   WORKTREE_ISOLATION_DESCRIPTION,
 } from "./src/prompt.ts";
-import { createDeferredResultDelivery } from "./src/result-delivery.ts";
 import {
   CAPABILITY_MODES,
   ISOLATION_MODES,
@@ -197,10 +197,8 @@ function resolveChildProjectTrust(options: {
 export default function (pi: ExtensionAPI) {
   let runtime: SubagentRuntime | undefined;
   let managerPromise: Promise<SubagentManagerShape> | undefined;
-  let sessionContext: ExtensionContext | undefined;
   let ui: ExtensionUIContext | undefined;
   let unsubStatus: (() => void) | undefined;
-  const resultDelivery = createDeferredResultDelivery<SubagentSnapshot>();
   const archived = new Map<string, ArchivedSubagent>();
   const peerHistory: PeerMessage[] = [];
   const pendingQuestions = new Map<
@@ -524,35 +522,24 @@ export default function (pi: ExtensionAPI) {
   };
 
   const deliverResult = (snap: SubagentSnapshot) => {
-    pi.sendMessage(
-      {
-        customType: "subagent-result",
-        content: buildSubagentResultMessage({
-          id: snap.id,
-          title: snap.title,
-          status: snap.status,
-          errorText: snap.errorText,
-          output: truncatedOutput(snap),
-        }),
-        display: true,
-        details: { id: snap.id, title: snap.title, status: snap.status },
-      },
-      { deliverAs: "followUp", triggerTurn: true },
-    );
-  };
-
-  const flushResults = () => {
-    for (const snap of resultDelivery.drain()) deliverResult(snap);
+    deliverSettlement(pi, {
+      customType: "subagent-result",
+      content: buildSubagentResultMessage({
+        id: snap.id,
+        title: snap.title,
+        status: snap.status,
+        errorText: snap.errorText,
+        output: truncatedOutput(snap),
+      }),
+      display: true,
+      details: { id: snap.id, title: snap.title, status: snap.status },
+    });
   };
 
   const onSettled = (snap: SubagentSnapshot, consumed: boolean) => {
     persistSnapshot(snap);
-    if (snap.meta.origin === "orchestration") {
-      resultDelivery.consume([snap.id]);
-      return;
-    }
+    if (snap.meta.origin === "orchestration") return;
     if (snap.meta.origin === "btw") {
-      resultDelivery.consume([snap.id]);
       pi.appendEntry<BtwEntryData>(BTW_ENTRY_TYPE, {
         id: snap.id,
         title: snap.title,
@@ -562,16 +549,10 @@ export default function (pi: ExtensionAPI) {
       });
       return;
     }
-    if (consumed) {
-      resultDelivery.consume([snap.id]);
-      return;
-    }
-    // Keep the result retractable while the parent is working. A later
-    // wait_agent can consume it before agent_settled flushes follow-ups.
-    // Defer a copy: the live snapshot keeps mutating if the subagent is
-    // restarted before the deferred result flushes.
-    resultDelivery.defer({ ...snap, meta: { ...snap.meta } });
-    if (sessionContext?.isIdle()) flushResults();
+    if (consumed) return;
+    // Hand the immutable settlement to Pi immediately. Pi queues it when the
+    // parent is active and starts a new parent turn when idle.
+    deliverResult({ ...snap, meta: { ...snap.meta } });
   };
 
   const coordinator: SubagentCoordinator = {
@@ -641,7 +622,6 @@ export default function (pi: ExtensionAPI) {
   );
 
   pi.on("session_start", (_event, ctx) => {
-    sessionContext = ctx;
     archived.clear();
     peerHistory.length = 0;
     for (const record of loadSubagentCatalog().values()) archived.set(record.id, record);
@@ -662,12 +642,8 @@ export default function (pi: ExtensionAPI) {
     if (ctx.hasUI) ui = ctx.ui;
   });
 
-  pi.on("agent_settled", flushResults);
-
   pi.on("session_shutdown", async () => {
-    sessionContext = undefined;
     unsubscribeCoordinator();
-    resultDelivery.clear();
     for (const pending of pendingQuestions.values()) {
       pending.reject(new Error("Parent Pi session shut down before replying."));
     }
@@ -692,7 +668,7 @@ export default function (pi: ExtensionAPI) {
     promptSnippet: SUBAGENT_SPAWN_PROMPT_SNIPPET,
     promptGuidelines: [
       ...SUBAGENT_SPAWN_PROMPT_GUIDELINES,
-      "After spawn_agent starts a child, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch it run; completion automatically starts the next parent turn.",
+      "After spawn_agent starts a child, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch it run. Settlement is handed to Pi immediately; when its attached summary invokes the parent, continue the original task without waiting for another user message.",
     ],
     parameters: Type.Object({
       message: Type.String({
@@ -832,7 +808,6 @@ export default function (pi: ExtensionAPI) {
       const snapshots = ids.map((id) => manager.view.get(id)!);
       const settled = snapshots.filter((snap) => snap.status !== "running");
       const pending = snapshots.filter((snap) => snap.status === "running");
-      resultDelivery.consume(settled.map((snap) => snap.id));
 
       const sections: string[] = [];
       let remainingBytes = WAIT_OUTPUT_MAX_BYTES;
@@ -1121,7 +1096,7 @@ export default function (pi: ExtensionAPI) {
     label: "Start Pi Subagent Tasks",
     description: "Start independent subagent tasks together in the background and return their ids immediately. Completion notices automatically start the next parent turn, so the parent should end its current turn when no independent work remains instead of checking status.",
     promptGuidelines: [
-      "After task starts children, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch them run; completion automatically starts the next parent turn.",
+      "After task starts children, continue only independent parent work or end the turn immediately. Do not call wait_agent, list_agents, or check_agent merely to watch them run. Settlements are handed to Pi immediately; when their attached summaries invoke the parent, continue the original task without waiting for another user message.",
     ],
     parameters: Type.Object({
       tasks: Type.Array(

package/extensions/subagents/src/prompt.ts

@@ -19,6 +19,7 @@ export const SUBAGENT_SPAWN_PROMPT_GUIDELINES = [
   "Use resume_from to continue a completed child's existing context instead of restating its original task.",
   "After spawn_agent or task starts background work, continue useful parent work; otherwise end the turn so Pi remains available to the user.",
   "Do not poll background agents. Completion notices arrive automatically and wake the parent; wait_agent only collects results already available and reports running agents without blocking.",
+  "When a completion notice invokes the parent, use its attached summary and continue the original task immediately; do not wait for another user message or call a status tool for the same result.",
 ];
 
 export const SUBAGENT_SPAWN_PARAMETER_DESCRIPTIONS = {
@@ -51,7 +52,7 @@ export function buildSubagentSpawnResult(options: {
   ].filter(Boolean);
   return (
     `Started Pi subagent ${options.id} "${options.title}" (${attributes.join(", ")}).\n` +
-    "It will report and wake the parent when finished. Continue useful work or end the turn instead of polling."
+    "It will report and wake the parent when finished. Continue useful work or end the turn instead of polling; when invoked by the result, continue the original task immediately."
   );
 }
 

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "shariq-pi-extensions",
-  "version": "0.2.5",
+  "version": "0.2.7",
   "description": "Cross-platform extension suite for the Pi coding agent.",
   "license": "MIT",
   "author": "Shariq Riaz",

package/skills/background-terminals/SKILL.md

@@ -24,7 +24,9 @@ Provide:
 - the working directory when it differs from the current directory;
 - an initial wait only when startup output is needed for the next decision.
 
-After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Terminal settlement automatically sends a follow-up and starts the next parent turn with the final status and bounded output. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
+After startup, continue only genuinely useful independent work. If none remains, end the turn immediately. Ending the turn is the waiting mechanism: terminal settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next parent turn with the final status and bounded output visible in model context. Do not keep the current turn alive to wait, invent monitoring work, or call terminal tools merely to see whether the process finished.
+
+When that completion follow-up invokes the next turn, treat its model-visible output as the terminal result and continue the original task immediately. Do not wait for another user message, announce that you are still waiting, or call `read_terminal` to retrieve the same result again. If `start_terminal` itself returns a settled result, the output is already synchronous and no second completion notice is needed.
 
 ## Inspect and interact only when necessary
 

package/skills/subagents/SKILL.md

@@ -24,14 +24,14 @@ This skill governs temporary Pi child agents. The `codex-thread-orchestrator` sk
 
 ## Wait by notification; inspect progress only when justified
 
-A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its completion notice automatically starts the next main-agent turn. The parent does not need to remain active or check once before ending its turn.
+A successful `spawn_agent` or `task` call starts asynchronous work and returns control to the parent. When a child finishes, its settlement is handed to Pi immediately as an extension-originated user follow-up, queued if the parent is still active, and otherwise starts the next main-agent turn with the summary visible in model context. The parent does not need to remain active or check once before ending its turn.
 
 After dispatch:
 
 1. Continue only parent work that is independently useful to the requested result.
 2. If no such work remains, end the turn immediately. A short progress note is enough when the user needs one.
 3. Do not call `wait_agent`, `list_agents`, or `check_agent` in the same turn merely because the child was just launched. Ending the turn is the waiting mechanism.
-4. Resume when a child completion notice invokes the main agent. Collect the completed result, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications.
+4. When a child completion notice invokes the main agent, treat its model-visible summary as the child result and continue the original task immediately. Reconcile completed results, launch any intentionally queued work if capacity requires waves, and otherwise keep waiting through notifications. Do not wait for the user to prompt you again or call a status tool to retrieve the same result.
 
 A progress check is reasonable when the user asks for status, a child has run materially longer than expected for its task and model, an interruption left its state unclear, or current status will change an immediate coordination decision. Prefer `check_agent` for one known child and `list_agents` for a batch overview. Use `wait_agent` to collect results already expected to be available, not as a running-status probe.
 

package/extensions/subagents/src/result-delivery.ts

@@ -1,20 +0,0 @@
-export function createDeferredResultDelivery<T extends { id: string }>() {
-  const pending = new Map<string, T>();
-
-  return {
-    defer(result: T) {
-      pending.set(result.id, result);
-    },
-    consume(ids: Iterable<string>) {
-      for (const id of ids) pending.delete(id);
-    },
-    drain() {
-      const results = [...pending.values()];
-      pending.clear();
-      return results;
-    },
-    clear() {
-      pending.clear();
-    },
-  };
-}