@hheei/pi-subagents 0.5.3 → 0.7.0

package/README.md

@@ -16,7 +16,7 @@ children and `/subagents stop [id]` to stop one without conflicting with other e
 | Tool | Purpose |
 | --- | --- |
 | `agent_spawn({ task, agent, cwd?, title? })` | Spawn an independent background subagent task. Runs in a new Herdr tab (or cmux surface) targeting the parent's workspace when a host is available, and headless in the background otherwise. **Prefer reusing existing subagents** via `agent_send` for related/follow-up work to maintain context and maximize prompt cache and memory efficiency. Tool description lists available agent names and roles, excluding disabled or hidden definitions. Deferred by default; discover via `tool_search({ query: "agent" })`. Do not poll for completion; results return automatically. |
-| `agent_send({ id, message, mode? })` | Send `steer`, `follow_up`, or `auto` input to a specific child. **Primary tool for assigning follow-up or functionally related tasks** to existing subagents: idle, blocked, done, or errored children resume their existing session automatically with historical context intact. A child whose runtime has ended is resumed the same way; spawn a new child only for new work. Stop first only when send says the previous process is still running. Deferred by default; discover via `tool_search({ query: "agent" })`. |
+| `agent_send({ id, message, mode? })` | Send input to a specific child. `mode: "steer"` (the default) enters the current turn once its tool calls are in, before the next model request; `mode: "follow_up"` waits until the child has no tool calls or steering left, then continues as a new turn. **Primary tool for assigning follow-up or functionally related tasks** to existing subagents: idle, blocked, done, or errored children resume their existing session automatically with historical context intact. A child whose runtime has ended is resumed the same way; spawn a new child only for new work. Stop first only when send says the previous process is still running. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 | `agent_get({ id, keys? })` | Inspect one subagent by id. `keys` is a comma-separated selection of `status` (default), `progress` (default), and `diagnostic`; unknown keys fail. The view never returns the child's task parameters or terminal result, which arrive automatically as reports. From the second successful inspection of the same child in this parent runtime, the result adds a short reminder that results return automatically and must not be polled. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 | `agent_stop({ id })` | Stop one subagent's runtime by id. The child keeps its session, so a later `agent_send` can resume it. Deferred by default; discover via `tool_search({ query: "agent" })`. |
 
@@ -37,6 +37,8 @@ Subagents communicate with the parent through the `commands` table in `state.sql
 - **Completion by Direct Output**: Subagents do **not** need to call any reporting tool upon successful completion. The subagent simply outputs its final answer as normal assistant text.
 - **Settlement Batching**: When a subagent settles, the harness captures the trailing assistant text and delivers it to the parent conversation as a `subagent-report`. Reports flush within 500ms when no other child is working, and are batched for up to 10 seconds while another child is still running.
 - **Blockers & Decisions**: The child registers `contact_parent({ message, reason? })` strictly for reporting when it is blocked or urgently requires a parent decision midway (`reason` defaults to `'blocked'`). Blocked reports wake the parent immediately.
+- **Direct `/compact` Command**: Sending `"/compact"` (or `"/compact [instructions]"`) via `agent_send` intercepts the command on the child side without passing it as prompt text to the LLM. The child executes native context compaction and reports completion status back to the parent via `contact_parent`. Duplicate `/compact` requests while a compaction is already in flight are safely acknowledged and ignored.
+- **Context Trim Hint**: When a subagent completes a task with context usage exceeding 100,000 tokens, its report includes a hint advising the parent to trim memory via `agent_send({ id, message: "/compact" })` if the child session will be retained for future work.
 - **Automatic Retry**: Pi's own auto-retry is observed, not invented: reports are suppressed while a retry is in flight, and a retry that succeeds clears the previous error instead of reporting it.
 - **Panel Failure Auto-Close**: When a subagent running in a panel encounters a fatal error or reports a blocker, the manager starts a 15-second countdown after notifying the parent, automatically closing the panel tab to avoid workspace clutter unless new instructions are dispatched.
 ## Compact status and reports
@@ -50,7 +52,7 @@ Use `/subagents` for complete status and management. `agent_send` can resume a d
 ## Host Integration and Isolation
 
 - **Herdr Workspace Affinity**: When spawning in Herdr, tabs are explicitly created in the parent process's current workspace (`--workspace <WORKSPACE_ID>`), preventing child tabs from jumping to whichever workspace happens to have user focus.
-- **Hindsight Memory Isolation**: `PI_HINDSIGHT_DISABLE=1` is set in the child environment and memory auto-registration/recall/writeback are disabled. The child bridge blocks all `mcp__hindsight__*` calls (including nested codemode calls and future server tools), even if that server is configured in a file. Memory recall prompt blocks are stripped. This boundary applies to the reserved `hindsight` server name, not arbitrary external servers registered under other names.
+- **Memory Isolation**: Both `PI_HINDSIGHT_DISABLE=1` and `PI_OBSERVATIONAL_MEMORY_DISABLE=1` are injected into child processes. Hindsight memory auto-registration, recall, and writeback are disabled, and the child bridge blocks all `mcp__hindsight__*` calls. Background Observational Memory workers (observation, reflection, compaction triggers) are suppressed in passive mode.
 
 ## Agent definitions
 

package/dist/child-control.js

@@ -198,6 +198,20 @@ export function registerChildControl(pi, options) {
         }
         return ctx;
     };
+    const reportCompaction = (reason, message) => {
+        void client
+            .report("contact_parent", {
+            type: "pi_subagent_report",
+            parentSessionId: options.identity.parentSessionId,
+            childId: options.identity.subagentId,
+            runtimeIdentity: options.identity.runtimeIdentity,
+            reason,
+            message,
+        })
+            .catch((err) => {
+            options.diagnose?.(`failed to report compaction ${reason}: ${errorMessage(err)}`);
+        });
+    };
     const deliverPrompt = (payload, deliverAs) => {
         const message = promptMessage(payload);
         // A message needs a session to land in: while the process is between sessions the parent
@@ -206,6 +220,23 @@ export function registerChildControl(pi, options) {
         if (path === undefined) {
             throw new BridgeError("session_not_ready", "This child has no session file path");
         }
+        const trimmed = message.trim();
+        if (trimmed === "/compact" || trimmed.startsWith("/compact ")) {
+            if (isCompacting) {
+                return { accepted: true, path, compacting: true };
+            }
+            const customInstructions = trimmed.slice(8).trim() || undefined;
+            requireContext().compact({
+                ...(customInstructions ? { customInstructions } : {}),
+                onComplete: (result) => {
+                    reportCompaction("success", `Context compacted (${result.tokensBefore} -> ${result.estimatedTokensAfter} tokens).`);
+                },
+                onError: (err) => {
+                    reportCompaction("blocked", `Compaction failed: ${err.message}`);
+                },
+            });
+            return { accepted: true, path, compacting: true };
+        }
         if (isCompacting) {
             pendingCompactionDeliveries.push({ message, deliverAs });
             return { accepted: true, path, queuedForCompaction: true };

package/dist/domain.d.ts

@@ -8,7 +8,16 @@ export declare function normalizeSubagentState(value: unknown): SubagentState |
  * is created, because it decides who holds the process for the rest of the child's life.
  */
 export type Presentation = "panel" | "background";
-export type SendMode = "steer" | "follow_up" | "auto";
+/**
+ * How `agent_send` hands its message to a child.
+ *
+ * `steer` enters the current assistant turn once its tool calls are in, before the next model
+ * request, so it redirects work already in flight. `follow_up` waits until the child's run has no
+ * tool calls or steering left, then continues as a new turn in the same run. There is no "auto":
+ * the two queues already are the two situations, so the caller picks instead of guessing from the
+ * child's state.
+ */
+export type SendMode = "steer" | "follow_up";
 export type VisualSubagentState = SubagentState;
 export declare function toVisualSubagentState(state: SubagentState, interrupted?: string): VisualSubagentState;
 export declare const VISUAL_SUBAGENT_GLYPH: Record<VisualSubagentState, string>;

package/dist/launch-spec.js

@@ -192,6 +192,7 @@ export function buildLaunchSpec(options) {
         // Empty is the defined "derive the title in the child" case, mirroring the task channel below.
         [CHILD_TITLE_ENV_KEY]: config.title ?? "",
         PI_HINDSIGHT_DISABLE: "1",
+        PI_OBSERVATIONAL_MEMORY_DISABLE: "1",
         ...(config.codemodeOnly ? { PI_CODEMODE_MODE: "only" } : {}),
         ...(mcpExcluded && mcpExcluded.length > 0
             ? { PI_SUBAGENT_MCP_EXCLUDE: mcpExcluded.join(",") }

package/dist/manager.js

@@ -570,13 +570,19 @@ export class SubagentManager {
             else {
                 message = text ?? "";
             }
+            const reason = isError ? "error" : isBlocked ? "blocked" : "success";
+            if (reason === "success" &&
+                facts?.contextTokens !== undefined &&
+                facts.contextTokens >= 100_000) {
+                const kTokens = `${Math.round(facts.contextTokens / 1000)}k`;
+                message = `${message}\n\n[Context: ~${kTokens} tokens. If retaining this subagent for future tasks, send "/compact" via agent_send to trim memory.]`;
+            }
             const lastDelivered = this.#lastDeliveredTurn.get(id);
             if (lastDelivered !== undefined &&
                 lastDelivered.workVersion === workVersion &&
                 lastDelivered.message === message) {
                 return;
             }
-            const reason = isError ? "error" : isBlocked ? "blocked" : "success";
             const projector = this.#projectors.get(id);
             const updatedRecord = !failed
                 ? await this.#update(id, (current) => {
@@ -923,7 +929,7 @@ export class SubagentManager {
             return failed;
         }
     }
-    send(id, rawMessage, mode = "auto", signal) {
+    send(id, rawMessage, mode = "steer", signal) {
         const message = stripHindsightContent(rawMessage);
         this.#bumpActivity(id);
         this.#clearSettledPanelClose(id);
@@ -994,15 +1000,10 @@ export class SubagentManager {
                 }
             }
             const state = isResumed ? "running" : record.state;
-            const operation = isResumed
-                ? "prompt"
-                : mode === "auto"
-                    ? state === "running"
-                        ? "steer"
-                        : "follow_up"
-                    : mode;
-            if (operation === undefined)
-                return failure("send", "Cannot infer send mode from unknown state", id, state);
+            // A resume already starts a fresh run, so the mode has nothing to decide: the message is
+            // that run's prompt. Otherwise the caller's mode is the request, with no state guessing:
+            // a running child steers at its next model step, an idle one simply starts a run.
+            const operation = isResumed ? "prompt" : mode;
             if (signal?.aborted)
                 return failure("send", "Send was cancelled", id, state);
             this.#clearSettledPanelClose(id);
@@ -1182,25 +1183,20 @@ export class SubagentManager {
             const delivered = await this.contactParent(childId, reason, payload.message, record);
             if ("reason" in delivered)
                 throw new BridgeError("delivery_failed", delivered.reason);
-            if (reason === "success") {
-                const projector = this.#projectors.get(childId);
-                if (projector !== undefined) {
-                    projector.syncState("done");
-                }
-                await this.#update(childId, (current) => ({
-                    ...current,
-                    state: "done",
-                }));
-            }
-            else if (reason === "blocked") {
+            if (reason === "success" || reason === "blocked") {
+                const terminalState = reason === "success" ? "done" : "blocked";
                 const projector = this.#projectors.get(childId);
                 if (projector !== undefined) {
-                    projector.syncState("blocked");
+                    projector.syncState(terminalState);
                 }
-                await this.#update(childId, (current) => ({
-                    ...current,
-                    state: "blocked",
-                }));
+                await this.#update(childId, (current) => {
+                    const { unacknowledgedInput: _input, ...clean } = current;
+                    return {
+                        ...clean,
+                        state: terminalState,
+                    };
+                });
+                this.#scheduleSettledPanelClose(childId);
             }
             else {
                 const projector = this.#projectors.get(childId);

package/dist/state.d.ts

@@ -12,6 +12,7 @@ export interface TranscriptFacts {
     readonly stopReason?: string;
     readonly interrupted?: string;
     readonly containsInput: boolean;
+    readonly contextTokens?: number;
 }
 export interface StateProjector {
     applyEvent(event: unknown): StateSnapshot;

package/dist/state.js

@@ -123,12 +123,26 @@ function lastCompletedAssistant(entries) {
     }
     return last;
 }
+function lastAssistantContextTokens(message) {
+    if (message === undefined)
+        return undefined;
+    const usage = record(message.usage);
+    if (usage === undefined)
+        return undefined;
+    const input = finite(usage.input) ?? 0;
+    const output = finite(usage.output) ?? 0;
+    const cacheRead = finite(usage.cacheRead) ?? 0;
+    const cacheWrite = finite(usage.cacheWrite) ?? 0;
+    const total = input + output + cacheRead + cacheWrite;
+    return total > 0 ? total : undefined;
+}
 /** What the parent projects from a session. The transcript itself never crosses the bridge. */
 export function transcriptFacts(entries, expectedInput) {
     const last = lastCompletedAssistant(entries);
     const summary = summarizeCurrentBranch(entries);
     const stopReason = typeof last?.stopReason === "string" ? last.stopReason : undefined;
     const interrupted = last === undefined ? undefined : diagnostic(last);
+    const contextTokens = lastAssistantContextTokens(last);
     const containsInput = expectedInput !== undefined &&
         entries.some((entry) => {
             const value = record(entry);
@@ -140,6 +154,7 @@ export function transcriptFacts(entries, expectedInput) {
         ...(summary === undefined ? {} : { summary }),
         ...(stopReason === undefined ? {} : { stopReason }),
         ...(interrupted === undefined ? {} : { interrupted }),
+        ...(contextTokens === undefined ? {} : { contextTokens }),
         containsInput,
     };
 }
@@ -169,6 +184,7 @@ export function parseTranscriptFacts(value) {
     const summary = typeof value.summary === "string" ? value.summary : undefined;
     const stopReason = typeof value.stopReason === "string" ? value.stopReason : undefined;
     const interrupted = typeof value.interrupted === "string" ? value.interrupted : undefined;
+    const contextTokens = usageNumber(value.contextTokens);
     return {
         usage: {
             inputTokens,
@@ -181,6 +197,7 @@ export function parseTranscriptFacts(value) {
         ...(summary === undefined ? {} : { summary }),
         ...(stopReason === undefined ? {} : { stopReason }),
         ...(interrupted === undefined ? {} : { interrupted }),
+        ...(contextTokens === undefined ? {} : { contextTokens }),
         containsInput: value.containsInput,
     };
 }

package/dist/tool-presentation.js

@@ -55,7 +55,7 @@ function spawnPresentation(args, result) {
 function sendPresentation(args, result) {
     const record = isRecord(args) ? args : undefined;
     const id = stringField(record, "id") ?? "agent";
-    const mode = stringField(record, "mode") ?? "auto";
+    const mode = stringField(record, "mode") ?? "steer";
     const message = stringField(record, "message");
     const confirmation = result === undefined ? undefined : agentResultText(result);
     const copy = message === undefined

package/dist/tools.js

@@ -18,7 +18,9 @@ const spawnSchema = Type.Object({
 const sendSchema = Type.Object({
     id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
     message: Type.String({ minLength: 1 }),
-    mode: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("follow_up"), Type.Literal("auto")])),
+    mode: Type.Optional(Type.Union([Type.Literal("steer"), Type.Literal("follow_up")], {
+        description: "steer (the default) enters the child's current turn once its tool calls are in, before the next model request, so it redirects work already in flight; an idle child just starts a run. follow_up waits until the child has no tool calls or steering left, then continues as a new turn. Use follow_up for work that must not interrupt what the child is doing now.",
+    })),
 });
 const idSchema = Type.Object({
     id: Type.String({ minLength: 1, description: "Subagent id, e.g. agent-1" }),
@@ -66,7 +68,7 @@ function getSpawnDescription(agents) {
         formatAvailableAgents(agents),
     ].join("\n");
 }
-const SEND_DESCRIPTION = "Send input, steer, or follow-up instructions to an existing subagent (e.g. 'agent-1'), resuming its session when it is idle, blocked, done, or errored. A child whose runtime has ended is resumed the same way: send to that id, do not spawn a replacement. Stop it first only when send reports the previous process is still running. Results are returned automatically when the task finishes; do not poll agent_get. Related subagent tools: agent_spawn, agent_get, agent_stop.";
+const SEND_DESCRIPTION = "Send input to an existing subagent (e.g. 'agent-1'), resuming its session when it is idle, blocked, done, or errored. A child whose runtime has ended is resumed the same way: send to that id, do not spawn a replacement. Stop it first only when send reports the previous process is still running. Results are returned automatically when the task finishes; do not poll agent_get. Related subagent tools: agent_spawn, agent_get, agent_stop.";
 const GET_DESCRIPTION = "Inspect one subagent's status, progress, or diagnostic details by id (e.g. 'agent-1'). Use keys to choose fields; defaults to 'status,progress'. Results are returned automatically; use this for inspection, not completion polling. Related subagent tools: agent_spawn, agent_send, agent_stop.";
 const STOP_DESCRIPTION = "Stop a subagent's runtime by id (e.g. 'agent-1'). The child keeps its session, so a later agent_send can resume it. Related subagent tools: agent_spawn, agent_send, agent_get.";
 const CONTACT_DESCRIPTION = "Notify the parent session when you are BLOCKED and cannot continue without parent decision or intervention. Do NOT call this on success or task completion: simply output your final answer directly as normal text in your response, and the harness will automatically capture and report your result to the parent.";

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-subagents",
-  "version": "0.5.3",
+  "version": "0.7.0",
   "description": "Independent background Pi subagent sessions with durable identity and RPC control.",
   "type": "module",
   "main": "dist/index.js",
@@ -35,7 +35,7 @@
     "access": "public"
   },
   "dependencies": {
-    "@hheei/pi-ext-core": "^0.6.2"
+    "@hheei/pi-ext-core": "^0.6.4"
   },
   "peerDependencies": {
     "@earendil-works/pi-coding-agent": ">=1.3.0",