@hheei/pi-subagents 0.6.0 → 0.7.0

package/README.md

@@ -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/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) => {
@@ -1177,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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@hheei/pi-subagents",
-  "version": "0.6.0",
+  "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",