pi-subagentura 2.0.0 → 2.0.2

package/artifact.ts

@@ -18,6 +18,7 @@
 
 import { appendFileSync, existsSync, mkdirSync, readdirSync, readFileSync, renameSync, statSync, writeFileSync } from "node:fs";
 import { join } from "node:path";
+import ndjson from "ndjson";
 
 // ── Types ───────────────────────────────────────────────────────────
 
@@ -87,6 +88,11 @@ export function writeOutput(art: SubagentArtifact, content: string): void {
  * ts >= since are returned. Malformed lines are silently skipped (the
  * sub-agent CLI is the only writer, but a partial write could in theory
  * leave a truncated line).
+ *
+ * Uses the `ndjson` library with `strict: false` so a single bad line does not abort the whole
+ * file — ndjson drops the bad row and continues with the rest. Any trailing partial line (file
+ * did not end with a newline) is buffered by the parser and dropped on `end()`; it is treated as a
+ * in-progress write that the next reader will pick up once completed.
  */
 export function readEvents(art: SubagentArtifact, since?: number): SubagentEvent[] {
 	if (!existsSync(art.statusFile)) return [];
@@ -96,16 +102,16 @@ export function readEvents(art: SubagentArtifact, since?: number): SubagentEvent
 	} catch {
 		return [];
 	}
+	const parser = ndjson.parse({ strict: false });
 	const events: SubagentEvent[] = [];
-	for (const line of content.split("\n")) {
-		if (!line.trim()) continue;
-		try {
-			const ev = JSON.parse(line) as SubagentEvent;
-			if (since === undefined || ev.ts >= since) events.push(ev);
-		} catch {
-			// Skip malformed lines (partial write, manual edit, etc.)
-		}
-	}
+	parser.on("data", (obj: unknown) => {
+		const ev = obj as SubagentEvent;
+		if (since === undefined || ev.ts >= since) events.push(ev);
+	});
+	// Non-strict mode never emits 'error' for bad JSON; attach a no-op so an unhandled error event
+	// can never crash the parent process.
+	parser.on("error", () => {});
+	parser.end(Buffer.from(content, "utf8"));
 	return events;
 }
 

package/helpers.ts

@@ -0,0 +1,660 @@
+/**
+ * Shared helpers for pi-subagentura
+ *
+ * Exported so both subagent.ts and test files can import them.
+ * Keeps helper logic in one place — single source of truth.
+ */
+
+import { randomBytes } from "node:crypto";
+import { appendFileSync, mkdirSync, existsSync } from "node:fs";
+import { resolve } from "node:path";
+import { getModel, getProviders } from "@earendil-works/pi-ai";
+import type { Model } from "@earendil-works/pi-ai";
+
+// Note: Model<TApi> and AgentToolResult<T> are SDK generics. We use `unknown` as
+// the type argument to avoid strict generic instantiation issues with tsc.
+import type { AgentToolResult } from "@earendil-works/pi-agent-core";
+
+import {
+  AuthStorage,
+  createAgentSession,
+  ModelRegistry,
+  SessionManager,
+  type AgentSession,
+} from "@earendil-works/pi-coding-agent";
+
+// ── Debug Logging ─────────────────────────────────────────────────
+
+const DEBUG_LOG_DIR = process.env.SUBAGENT_DEBUG_LOG_DIR
+  ? resolve(process.env.SUBAGENT_DEBUG_LOG_DIR)
+  : undefined;
+
+export function debugLog(level: string, event: string, data: Record<string, unknown> = {}) {
+  if (!DEBUG_LOG_DIR) return;
+  try {
+    if (!existsSync(DEBUG_LOG_DIR)) {
+      mkdirSync(DEBUG_LOG_DIR, { recursive: true });
+    }
+    const entry = JSON.stringify({
+      timestamp: new Date().toISOString(),
+      level,
+      event,
+      ...data,
+    }) + "\n";
+    const fileName = resolve(DEBUG_LOG_DIR, `debug-${new Date().toISOString().slice(0, 10)}.jsonl`);
+    appendFileSync(fileName, entry);
+  } catch {
+    // Silently fail to avoid polluting output
+  }
+}
+
+export function extractTextFromContent(content: unknown): string {
+  if (Array.isArray(content)) {
+    return content
+      .filter((c): c is { type: "text"; text: string } =>
+        typeof c === "object" && c !== null && c.type === "text" && typeof c.text === "string"
+      )
+      .map((c) => c.text)
+      .join("\n");
+  }
+  if (typeof content === "string") {
+    return content;
+  }
+  debugLog("warn", "unexpected_content_type", {
+    contentType: typeof content,
+    content: String(String(content).slice(0, 200)),
+  });
+  return "";
+}
+
+// ── Constants ────────────────────────────────────────────────────────
+
+/**
+ * Milliseconds to wait before showing activeTool in the live status preview.
+ * Prevents UI flicker for fast tool executions that start and end within this window.
+ *
+ * Note: If Pi adds new model providers, update KNOWN_PROVIDERS below.
+ */
+export const ACTIVE_TOOL_DEBOUNCE_MS = 150;
+
+// Note: If Pi adds new providers, getProviders() from @earendil-works/pi-ai will
+// return them automatically. We no longer maintain a hardcoded list.
+
+// ── Types ───────────────────────────────────────────────────────────
+
+export interface SubagentResult {
+  output: string;
+  usage: {
+    input: number;
+    output: number;
+    cacheRead: number;
+    cacheWrite: number;
+    cost: number;
+    turns: number;
+  };
+  model?: string;
+  isError: boolean;
+  errorMessage?: string;
+}
+
+export interface SubagentLiveStatus {
+  turn: number;
+  activeTool?: { name: string; args: Record<string, unknown> };
+  output: string;
+  usage: SubagentResult["usage"];
+}
+
+// ── Async Job Types ─────────────────────────────────────────────────
+
+export type JobStatus = "running" | "done" | "error" | "cancelled";
+
+/** Notification delivery mode for async subagent completion */
+export type NotifyOnComplete = "notify" | "inject";
+
+export interface JobState {
+  id: string;
+  status: JobStatus;
+  liveStatus: SubagentLiveStatus;
+  result?: SubagentResult;
+  session: AgentSession;
+  startedAt: number;
+  promise: Promise<SubagentResult>;
+  modelLabel?: string;
+  /** Notification mode requested by spawner's notifyOnComplete param */
+  notifyOnComplete?: NotifyOnComplete;
+  /** At-most-once delivery guard */
+  notificationDelivered?: boolean;
+  /** Set true by get_subagent_result to suppress redundant notification */
+  resultRetrieved?: boolean;
+  /** Optional TTL in ms for completed job retention */
+  maxAge?: number;
+}
+
+// ── Job Registry ────────────────────────────────────────────────────
+
+/**
+ * Persisted job registry using global to survive module reloads (jiti).
+ *
+ * Lifecycle:
+ *   - Jobs added on async subagent spawn
+ *   - Completed/error jobs persist indefinitely (no TTL)
+ *   - Cancelled jobs removed immediately
+ *   - All jobs lost on Pi restart (in-memory only)
+ */
+
+// Use 'global' for Node.js global, fall back to globalThis
+const g = typeof global !== "undefined" ? global : globalThis;
+
+// Create or reuse the registry on the global object
+if (!g.__piSubagenturaRegistry) {
+  g.__piSubagenturaRegistry = new Map<string, JobState>();
+}
+
+export const jobRegistry = g.__piSubagenturaRegistry as Map<string, JobState>;
+
+// Declare global piref for notification delivery (set by extension factory, read by delivery code)
+declare global {
+  var __piSubagenturaPiRef: unknown; // ExtensionAPI ref — set in subagent.ts factory
+}
+
+// Initialize the global pi ref
+if (!g.__piSubagenturaPiRef) {
+  g.__piSubagenturaPiRef = undefined;
+}
+
+/** Jobs persist indefinitely — no automatic expiration */
+export const JOB_CLEANUP_TTL_MS = 0;
+
+/** Maximum number of jobs to retain in the registry */
+export const MAX_REGISTRY_SIZE = 100;
+
+/** Remove the oldest completed or error job from the registry */
+export function pruneOldestJob(): boolean {
+  for (const [jobId, job] of jobRegistry) {
+    if (job.status === "done" || job.status === "error") {
+      jobRegistry.delete(jobId);
+      return true;
+    }
+  }
+  return false;
+}
+
+/** Remove all completed and error jobs from the registry. Returns count removed. */
+export function pruneCompletedJobs(): number {
+  let removed = 0;
+  for (const [jobId, job] of jobRegistry) {
+    if (job.status === "done" || job.status === "error") {
+      jobRegistry.delete(jobId);
+      removed++;
+    }
+  }
+  return removed;
+}
+
+export function scheduleJobCleanup(
+  jobId: string,
+  immediate = false,
+  maxAge?: number,
+): void {
+  if (!immediate) {
+    if (maxAge && maxAge > 0) {
+      setTimeout(() => {
+        jobRegistry.delete(jobId);
+      }, maxAge);
+    }
+    return; // persist indefinitely unless maxAge specified
+  }
+  setTimeout(() => {
+    jobRegistry.delete(jobId);
+  }, 0);
+}
+
+/** Generate a unique job ID (16 hex chars from crypto.randomBytes) */
+export function generateJobId(): string {
+  // Uses randomBytes for Node 18 compatibility (randomUUID needs Node 19+)
+  return randomBytes(8).toString("hex");
+}
+
+// ── Helpers ─────────────────────────────────────────────────────────
+
+/**
+ * Resolve a model from a string identifier and an optional default.
+ *
+ * The caller (LLM agent) is responsible for providing the correct model id.
+ * This function does NOT guess — it only does exact lookups:
+ *   1. undefined → defaultModel
+ *   2. Use parent modelRegistry (has extension-added models like minimax)
+ *   3. "provider/id" format → exact getModel lookup (global static registry)
+ *   4. Bare id → exact getModel scan across all providers (global static registry)
+ *   5. Falls back to defaultModel when nothing matches
+ */
+export function resolveModel(
+  modelId: string | undefined,
+  // @ts-expect-error — Model<TApi> requires type arg; unknown is a safe placeholder
+  defaultModel: Model | undefined,
+  parentModelRegistry?: ModelRegistry,
+) {
+  if (!modelId) return defaultModel;
+
+  // Only exact matching — no fuzzy/substring guessing.
+  // The AI should call list_available_models and pick from the list.
+  if (parentModelRegistry) {
+    if (modelId.includes("/")) {
+      const [provider, id] = modelId.split("/", 2);
+      const exact = parentModelRegistry.find(provider, id);
+      if (exact) return exact as any;
+    } else {
+      // Bare id — search all models in parent registry
+      for (const m of parentModelRegistry.getAll()) {
+        if (m.id === modelId) return m as any;
+      }
+    }
+  }
+
+  // Fall back to global static registry (built-in models only)
+  if (modelId.includes("/")) {
+    const [provider, id] = modelId.split("/", 2);
+    // @ts-expect-error — getModel requires KnownProvider union; we trust the caller
+    return getModel(provider, id) ?? defaultModel;
+  }
+
+  // Bare id — exact match across all providers
+  for (const provider of getProviders()) {
+    // @ts-expect-error — KnownProvider cast needed; string is assignable to it at runtime
+    const found = getModel(provider, modelId);
+    if (found) return found;
+  }
+
+  return defaultModel;
+}
+export function formatTokens(count: number): string {
+  if (count < 1000) return count.toString();
+  if (count < 10000) return `${(count / 1000).toFixed(1)}k`;
+  if (count < 1000000) return `${Math.round(count / 1000)}k`;
+  return `${(count / 1000000).toFixed(1)}M`;
+}
+
+export function formatUsage(
+  u: SubagentResult["usage"],
+  model?: string,
+): string {
+  const parts: string[] = [];
+  if (u.turns) parts.push(`${u.turns} turn${u.turns > 1 ? "s" : ""}`);
+  if (u.input) parts.push(`↑${formatTokens(u.input)}`);
+  if (u.output) parts.push(`↓${formatTokens(u.output)}`);
+  if (u.cacheRead) parts.push(`R${formatTokens(u.cacheRead)}`);
+  if (u.cacheWrite) parts.push(`W${formatTokens(u.cacheWrite)}`);
+  if (u.cost) parts.push(`$${u.cost.toFixed(4)}`);
+  if (model) parts.push(model);
+  return parts.join(" ");
+}
+
+export function buildLiveUpdate(
+  status: SubagentLiveStatus,
+  model?: string,
+  // @ts-expect-error — AgentToolResult<T> requires type arg; unknown is a safe placeholder
+): AgentToolResult {
+  return {
+    content: [{ type: "text", text: status.output }],
+    details: {
+      status: "running",
+      subagentStatus: status,
+      model,
+    },
+  };
+}
+
+// ── startSubagentJob ────────────────────────────────────────────────
+
+export interface StartSubagentJobParams {
+  task: string;
+  persona: string | undefined;
+  modelOverride: string | undefined;
+  cwd: string;
+  contextText: string | null;
+  signal: AbortSignal | undefined;
+  // @ts-expect-error — AgentToolResult<T> requires type arg
+  onUpdate: ((partial: AgentToolResult) => void) | undefined;
+  // @ts-expect-error — Model<TApi> requires type arg
+  defaultModel: Model | undefined;
+  maxAge?: number;
+  /** Parent session's model registry for resolving extension-added models (e.g. minimax) */
+  parentModelRegistry?: ModelRegistry;
+}
+
+export interface StartSubagentJobResult {
+  jobId: string;
+  jobPromise: Promise<SubagentResult>;
+  session: AgentSession;
+  liveStatus: SubagentLiveStatus;
+  modelLabel?: string;
+  /** Warning when modelOverride was specified but not found — lists available models */
+  modelWarning?: string;
+}
+
+/**
+ * Create a subagent session and start its prompt execution.
+ *
+ * Returns immediately with { jobId, jobPromise, session, liveStatus }.
+ * The jobPromise resolves to a SubagentResult when the subagent completes.
+ * The liveStatus object is mutated in real-time by the event subscriber.
+ *
+ * This is the shared core used by both sync (runSubagent) and async paths.
+ */
+export async function startSubagentJob(
+  params: StartSubagentJobParams,
+): Promise<StartSubagentJobResult> {
+  const {
+    task,
+    persona,
+    modelOverride,
+    cwd,
+    contextText,
+    signal,
+    onUpdate,
+    defaultModel,
+    parentModelRegistry,
+  } = params;
+
+  // Enforce registry size cap before adding a new job
+  while (jobRegistry.size >= MAX_REGISTRY_SIZE) {
+    if (!pruneOldestJob()) break; // no old jobs to evict, allow slight overcap
+  }
+
+  const jobId = generateJobId();
+  const authStorage = AuthStorage.create();
+  const modelRegistry = ModelRegistry.create(authStorage);
+
+  // Resolve model: exact match only, fallback to default
+  // Uses parent's modelRegistry to find extension-added models (e.g. minimax)
+  const targetModel = resolveModel(modelOverride, defaultModel, parentModelRegistry);
+  const modelLabel = targetModel
+    ? `${targetModel.provider}/${targetModel.id}`
+    : undefined;
+
+  // Build model warning when override was specified (helps AI discover valid models)
+  let modelWarning: string | undefined;
+  if (modelOverride && parentModelRegistry) {
+    const available = parentModelRegistry.getAvailable();
+    const modelList = available
+      .map((m) => `  ${m.provider}/${m.id}${m.name ? ` (${m.name})` : ""}`)
+      .join("\n");
+    modelWarning =
+      `Requested model "${modelOverride}" resolved to ${modelLabel ?? "none"}. ` +
+      `Available models:\n${modelList || "  (none)"}\n` +
+      `Use list_available_models to discover more.`;
+  }
+
+  let handleAbort: (() => void) | undefined;
+  let unsubscribe: (() => void) | undefined;
+
+  const liveStatus: SubagentLiveStatus = {
+    turn: 0,
+    output: "",
+    usage: {
+      input: 0,
+      output: 0,
+      cacheRead: 0,
+      cacheWrite: 0,
+      cost: 0,
+      turns: 0,
+    },
+  };
+
+  // Debounce activeTool updates to prevent flickering on fast tool calls.
+  // When onUpdate is undefined (async path), skip the debounce entirely —
+  // no rendering to flicker, and the timer overhead is wasted.
+  let activeToolTimer: ReturnType<typeof setTimeout> | undefined;
+  let pendingActiveTool: SubagentLiveStatus["activeTool"] = undefined;
+
+  function setActiveToolDebounced(tool: SubagentLiveStatus["activeTool"]) {
+    pendingActiveTool = tool;
+    if (activeToolTimer) {
+      clearTimeout(activeToolTimer);
+      activeToolTimer = undefined;
+    }
+    if (tool) {
+      if (!onUpdate) {
+        // Async path: no rendering, apply immediately
+        liveStatus.activeTool = tool;
+        return;
+      }
+      activeToolTimer = setTimeout(() => {
+        activeToolTimer = undefined;
+        liveStatus.activeTool = pendingActiveTool;
+        onUpdate?.(buildLiveUpdate(liveStatus, modelLabel));
+      }, ACTIVE_TOOL_DEBOUNCE_MS);
+    } else {
+      if (liveStatus.activeTool) {
+        liveStatus.activeTool = undefined;
+        onUpdate?.(buildLiveUpdate(liveStatus, modelLabel));
+      }
+    }
+  }
+
+  // Create session
+  debugLog("info", "session_creating", {
+    jobId,
+    model: modelLabel ?? "default",
+    cwd,
+  });
+  const session = (
+    await createAgentSession({
+      sessionManager: SessionManager.inMemory(),
+      authStorage,
+      modelRegistry,
+      model: targetModel,
+      cwd,
+    })
+  ).session;
+  debugLog("info", "session_created", {
+    jobId,
+    sessionModel: session.model ? `${session.model.provider}/${session.model.id}` : null,
+  });
+
+  // Wire abort signal
+  if (signal) {
+    handleAbort = () => {
+      debugLog("warn", "job_abort", { jobId });
+      session.abort().catch(() => {});
+    };
+    if (signal.aborted) {
+      handleAbort();
+    } else {
+      signal.addEventListener("abort", handleAbort);
+    }
+  }
+
+  // Wire session events
+  unsubscribe = session.subscribe((event) => {
+    switch (event.type) {
+      case "turn_start": {
+        liveStatus.turn++;
+        liveStatus.usage.turns = liveStatus.turn;
+        liveStatus.output = "";
+        debugLog("info", "turn_start", { jobId, turn: liveStatus.turn });
+        onUpdate?.(buildLiveUpdate(liveStatus, modelLabel));
+        break;
+      }
+      case "tool_execution_start": {
+        debugLog("info", "tool_start", {
+          jobId,
+          toolName: event.toolName,
+          args: event.args as Record<string, unknown>,
+        });
+        setActiveToolDebounced({
+          name: event.toolName,
+          args: event.args as Record<string, unknown>,
+        });
+        break;
+      }
+      case "tool_execution_end": {
+        debugLog("info", "tool_end", { jobId, toolName: liveStatus.activeTool?.name });
+        setActiveToolDebounced(undefined);
+        break;
+      }
+      case "turn_end": {
+        debugLog("info", "turn_end", {
+          jobId,
+          turn: liveStatus.turn,
+          outputLength: liveStatus.output.length,
+          activeTool: liveStatus.activeTool?.name ?? null,
+        });
+        if (activeToolTimer) {
+          clearTimeout(activeToolTimer);
+          activeToolTimer = undefined;
+        }
+        liveStatus.activeTool = undefined;
+        onUpdate?.(buildLiveUpdate(liveStatus, modelLabel));
+        break;
+      }
+      case "message_update": {
+        const evt = event.assistantMessageEvent;
+        debugLog("info", "message_update", {
+          jobId,
+          updateType: evt.type,
+          ...(evt.type === "text_delta" && {
+            delta: evt.delta.slice(0, 200),
+            outputLength: liveStatus.output.length,
+          }),
+          ...(evt.type === "thinking_delta" && { delta: evt.delta.slice(0, 200) }),
+          ...(evt.type === "toolcall_delta" && { partial: String(evt.partial).slice(0, 200) }),
+          ...(evt.type === "toolcall_end" && { toolCallId: evt.toolCall?.id }),
+        });
+        if (evt.type === "text_delta") {
+          liveStatus.output += evt.delta;
+          onUpdate?.(buildLiveUpdate(liveStatus, modelLabel));
+        }
+        break;
+      }
+    }
+  });
+
+  // Build prompt text
+  const personaPrefix = persona ? `${persona}\n\n` : "";
+  const finalPrompt = contextText
+    ? `${personaPrefix}You are a SEPARATE background sub-agent. Your ONLY job is the task below.\nThe conversation history above is CONTEXT ONLY — do NOT comment on it, do NOT role-play as the main assistant, do NOT describe the spawning process. Execute ONLY the task and return ONLY the result.\n\n## Conversation History (context only — do not respond to this)\n${contextText}\n\n## Your Task (respond ONLY to this)\n${task}`
+    : `${personaPrefix}Task: ${task}`;
+
+  debugLog("info", "prompt_built", {
+    jobId,
+    hasContext: !!contextText,
+    contextLength: contextText?.length ?? 0,
+    taskLength: task.length,
+    persona: persona ?? null,
+    promptPreview: finalPrompt.slice(0, 500),
+  });
+
+  // Launch the prompt in a promise chain (NOT awaited — returns immediately).
+  // The jobPromise represents the full lifecycle: prompt → extraction → cleanup.
+  const jobPromise = (async (): Promise<SubagentResult> => {
+    let result: SubagentResult;
+    try {
+      debugLog("info", "prompt_start", { jobId });
+      await session.prompt(finalPrompt);
+      debugLog("info", "prompt_complete", { jobId });
+
+      // Extract final assistant output
+      const messages = session.agent.state.messages;
+      debugLog("info", "messages_extracted", {
+        jobId,
+        messageCount: messages.length,
+        messageRoles: messages.map((m) => m.role),
+        lastMessageContentType: typeof (messages[messages.length - 1] as any)?.content,
+        lastMessageContentIsArray: Array.isArray((messages[messages.length - 1] as any)?.content),
+      });
+
+      let finalOutput = liveStatus.output;
+      for (let i = messages.length - 1; i >= 0; i--) {
+        const msg = messages[i];
+        debugLog("info", "message_check", {
+          jobId,
+          index: i,
+          role: msg.role,
+          contentType: typeof (msg as any).content,
+          contentIsArray: Array.isArray((msg as any).content),
+        });
+        if (msg.role === "assistant") {
+          const textParts = extractTextFromContent(msg.content);
+          if (textParts) {
+            finalOutput = textParts;
+            break;
+          }
+        }
+      }
+
+      const usage = {
+        input: 0,
+        output: 0,
+        cacheRead: 0,
+        cacheWrite: 0,
+        cost: 0,
+        turns: 0,
+      };
+      for (const msg of messages) {
+        if (msg.role === "assistant" && msg.usage) {
+          usage.turns++;
+          usage.input += msg.usage.input;
+          usage.output += msg.usage.output;
+          usage.cacheRead += msg.usage.cacheRead;
+          usage.cacheWrite += msg.usage.cacheWrite;
+          usage.cost += msg.usage.cost.total;
+        }
+      }
+
+      result = {
+        output: finalOutput || "(no output)",
+        usage,
+        model: session.model
+          ? `${session.model.provider}/${session.model.id}`
+          : undefined,
+        isError: !!session.agent.state.errorMessage,
+        errorMessage: session.agent.state.errorMessage,
+      };
+    } catch (err) {
+      const msg = err instanceof Error ? err.message : String(err);
+      const stack = err instanceof Error ? err.stack : undefined;
+      debugLog("error", "subagent_error", {
+        jobId,
+        error: msg,
+        stack: stack ?? null,
+        errorName: err instanceof Error ? err.name : typeof err,
+      });
+      result = {
+        output: `Sub-agent crashed: ${msg}`,
+        usage: {
+          input: 0,
+          output: 0,
+          cacheRead: 0,
+          cacheWrite: 0,
+          cost: 0,
+          turns: 0,
+        },
+        model: undefined,
+        isError: true,
+        errorMessage: msg,
+      };
+    } finally {
+      debugLog("info", "job_complete", {
+        jobId,
+        outputLength: result.output.length,
+        output: result.output.slice(0, 200),
+        isError: result.isError,
+        errorMessage: result.errorMessage ?? null,
+        usage: result.usage,
+      });
+      if (activeToolTimer) {
+        clearTimeout(activeToolTimer);
+        activeToolTimer = undefined;
+      }
+      if (signal && handleAbort)
+        signal.removeEventListener("abort", handleAbort);
+      if (unsubscribe) unsubscribe();
+      session?.dispose();
+      debugLog("info", "session_disposed", { jobId });
+    }
+    return result;
+  })();
+
+  return { jobId, jobPromise, session, liveStatus, modelLabel, modelWarning };
+}

package/package.json

@@ -1,7 +1,9 @@
 {
   "name": "pi-subagentura",
-  "version": "2.0.0",
+  "version": "2.0.2",
   "description": "Public Pi package that adds in-process sub-agents via the SDK",
+  "author": "lmn451",
+  "license": "MIT",
   "main": "subagent.ts",
   "type": "module",
   "keywords": [
@@ -13,7 +15,6 @@
     "swarm",
     "crew"
   ],
-  "license": "MIT",
   "repository": {
     "type": "git",
     "url": "https://github.com/lmn451/pi-subagentura"
@@ -27,7 +28,7 @@
     "interactive-tmux.ts",
     "artifact.ts",
     "subagent-artifact-cli.ts",
-    "README.md",
+    "helpers.ts",
     "LICENSE"
   ],
   "engines": {
@@ -58,5 +59,9 @@
     "prettier": "^3.8.3",
     "typescript": "^6.0.3",
     "vitest": "^3.0.0"
+  },
+  "dependencies": {
+    "is-path-inside": "^4.0.0",
+    "ndjson": "^2.0.0"
   }
 }

package/subagent.ts

@@ -59,12 +59,12 @@ import {
 } from "./interactive-tmux";
 import { appendEvent, artifactPath, lastEvent, readEvents, readOutput, type SubagentArtifact, type SubagentEvent } from "./artifact";
 
-import { openSync, readdirSync, readSync, statSync } from "node:fs";
+import { closeSync, openSync, readdirSync, readSync, realpathSync, statSync } from "node:fs";
 import { homedir } from "node:os";
 import { basename, dirname, join } from "node:path";
 import { Text, truncateToWidth } from "@earendil-works/pi-tui";
 import { Type } from "typebox";
-
+import ndjson from "ndjson";
 // ── Footer Status Key ─────────────────────────────────────────────────────────────────────
 const FOOTER_KEY = "subagentura-running";
 const WIDGET_KEY = "subagentura-activity";
@@ -544,9 +544,69 @@ export function pollArtifactChanges(pi: ExtensionAPI): void {
 	}
 }
 
+/**
+ * Per-state ndjson parser instance used to tail-read the child's session JSONL.
+ *
+ * The parser buffers partial trailing lines internally (via split2 underneath), so we can
+ * safely write raw bytes from the file on every poll and let the parser emit complete JSON
+ * objects as 'data' events. This replaces a hand-rolled partial-line + cursor scheme that had
+ * three latent bugs:
+ *   - A 1 MiB per-tick read cap combined with cursor-pinning on a missing newline caused a
+ *     permanent re-read loop on any single JSONL line larger than 1 MiB (e.g. a multi-MB tool
+ *     call result that the child pi runtime writes as a single line).
+ *   - File truncation left the cursor pointing past EOF, silently dropping any post-truncation
+ *     content.
+ *   - A `require("node:fs").closeSync(fd)` call in the finally block leaked file descriptors on
+ *     Node < 22.12 in some bundling paths.
+ *
+ * Keyed by sub-agent id; one parser per state lives for the lifetime of the process. The parser
+ * is destroyed and recreated on file truncation so the buffered partial state is cleared.
+ */
+const sessionParsers = new Map<string, ReturnType<typeof ndjson.parse>>();
+
+/** Defensive upper bound on the per-tick Buffer.alloc. With ndjson, a partial line is buffered
+ * internally across polls, so the cap is no longer required for correctness — it is kept purely
+ * to bound worst-case memory if the file explodes in a single tick. 1 MiB is plenty. */
+const MAX_SESSION_READ_BYTES = 1 * 1024 * 1024;
+
+/** Get-or-create the per-state session parser and wire its 'data' event to the entry handler. */
+function getOrCreateSessionParser(state: InteractiveSubagentState): ReturnType<typeof ndjson.parse> {
+	const existing = sessionParsers.get(state.id);
+	if (existing) return existing;
+	// strict: false → malformed lines are silently dropped instead of triggering an 'error' event
+	// that would force us to recreate the parser mid-stream. Same best-effort delivery semantics as
+	// the old hand-rolled try/catch around JSON.parse.
+	const parser = ndjson.parse({ strict: false });
+	parser.on("data", (entry: unknown) => {
+		const art = artifactPath(dirname(state.artifactDir), basename(state.artifactDir));
+		processSessionLogEntry(state, art, entry as any);
+	});
+	// In non-strict mode the parser does not emit 'error' for bad JSON, but we still attach a no-op
+	// handler so an unhandled error event can never crash the process.
+	parser.on("error", () => {
+		// Drop the broken parser so the next tick creates a fresh one. The cursor is reset in the
+		// truncation handler, so this only fires for pathological non-truncation errors.
+		sessionParsers.delete(state.id);
+	});
+	sessionParsers.set(state.id, parser);
+	return parser;
+}
+
+/** Destroy a state's parser (used on truncation and on state removal). */
+function destroySessionParser(state: InteractiveSubagentState): void {
+	const parser = sessionParsers.get(state.id);
+	if (!parser) return;
+	try {
+		parser.end();
+	} catch {
+		// ignore — we're tearing down
+	}
+	sessionParsers.delete(state.id);
+}
+
 /** Tail-read the child's session JSONL and append `tool_activity` events to events.ndjson.
  *  Updates `state.lastDeliveredSessionByte` so subsequent ticks re-read only new lines. */
-function tailReadSessionLog(state: InteractiveSubagentState, art: SubagentArtifact): void {
+function tailReadSessionLog(state: InteractiveSubagentState, _art: SubagentArtifact): void {
 	const sessionFile = state.sessionFile;
 	if (!sessionFile) return;
 
@@ -557,9 +617,25 @@ function tailReadSessionLog(state: InteractiveSubagentState, art: SubagentArtifa
 		return; // file not yet created by the child
 	}
 
+	const initialCursor = state.lastDeliveredSessionByte ?? 0;
+	if (size < initialCursor) {
+		// File shrunk under us (truncation, rotation, manual edit). Reset cursor and parser and fall
+		// through to the read below so any content already written after the truncation is processed in
+		// the same tick (e.g. test does truncateSync → writeFileSync → poll). The parser is recreated so the
+		// buffered partial state is cleared. Any duplicate tool_activity events are acceptable — the
+		// artifact log is best-effort and the LLM never sees these (TUI-widget only).
+		state.lastDeliveredSessionByte = 0;
+		destroySessionParser(state);
+	}
 	const cursor = state.lastDeliveredSessionByte ?? 0;
 	if (size <= cursor) return;
 
+	// Defensive cap on per-tick allocation. ndjson handles partial lines correctly across writes,
+	// so a single multi-MB line split across ticks works fine — no cursor pin.
+	const requested = size - cursor;
+	const toRead = Math.min(requested, MAX_SESSION_READ_BYTES);
+	if (toRead <= 0) return;
+
 	let fd: number;
 	try {
 		fd = openSync(sessionFile, "r");
@@ -567,59 +643,53 @@ function tailReadSessionLog(state: InteractiveSubagentState, art: SubagentArtifa
 		return;
 	}
 	try {
-		const len = size - cursor;
-		const buf = Buffer.alloc(len);
+		const buf = Buffer.alloc(toRead);
 		let bytesRead = 0;
-		while (bytesRead < len) {
-			const n = readSync(fd, buf, bytesRead, len - bytesRead, cursor + bytesRead);
+		while (bytesRead < toRead) {
+			const n = readSync(fd, buf, bytesRead, toRead - bytesRead, cursor + bytesRead);
 			if (n <= 0) break;
 			bytesRead += n;
 		}
-		const chunk = buf.subarray(0, bytesRead).toString("utf8");
-		processSessionLogChunk(state, art, chunk);
+		if (bytesRead === 0) return;
+		const parser = getOrCreateSessionParser(state);
+		parser.write(buf.subarray(0, bytesRead));
+		// Always advance the cursor by the bytes we fed the parser. The parser buffers any partial
+		// trailing line internally and will emit the completed object on a later write. We do NOT
+		// rewind to the last newline the way the old code did — doing so would re-feed the same bytes
+		// to the parser and double-emit on the next tick.
 		state.lastDeliveredSessionByte = cursor + bytesRead;
 	} finally {
-		try { require("node:fs").closeSync(fd); } catch {}
-	}
-}
-
-/** Parse a chunk of session JSONL, append a tool_activity event per tool call. */
-function processSessionLogChunk(state: InteractiveSubagentState, art: SubagentArtifact, chunk: string): void {
-	const lines = chunk.split("\n");
-	// Last entry may be a partial line (the child hasn't finished writing it yet).
-	// We still process complete lines; the partial line will be re-read on the next tick.
-	const completeLines = chunk.endsWith("\n") ? lines : lines.slice(0, -1);
-	for (const line of completeLines) {
-		if (!line.trim()) continue;
-		let entry: any;
 		try {
-			entry = JSON.parse(line);
+			closeSync(fd);
 		} catch {
-			// Skip malformed/partial — safer to drop than crash.
-			continue;
+			/* fd already closed or never opened — ignore */
 		}
-		if (entry.type !== "message") continue;
-		const msg = entry.message;
-		if (!msg) continue;
-
-		// Assistant message: extract toolCall blocks.
-		if (msg.role === "assistant" && Array.isArray(msg.content)) {
-			for (const block of msg.content) {
-				if (block.type !== "toolCall") continue;
-				const summary = summarizeToolCall(block.name, block.arguments);
-				if (!summary) continue;
-				const ev: SubagentEvent = {
-					ts: msg.timestamp ?? Date.now(),
-					type: "tool_activity",
-					status: "running",
-					tool: block.name,
-					summary,
-				};
-				appendEvent(art, ev);
-				state.lastToolName = block.name;
-				state.lastToolSummary = summary;
-				state.lastActivityAt = ev.ts;
-			}
+	}
+}
+
+/** Process a single parsed JSONL entry from the session log; append tool_activity events. */
+function processSessionLogEntry(state: InteractiveSubagentState, art: SubagentArtifact, entry: any): void {
+	if (entry.type !== "message") return;
+	const msg = entry.message;
+	if (!msg) return;
+
+	// Assistant message: extract toolCall blocks.
+	if (msg.role === "assistant" && Array.isArray(msg.content)) {
+		for (const block of msg.content) {
+			if (block.type !== "toolCall") continue;
+			const summary = summarizeToolCall(block.name, block.arguments);
+			if (!summary) continue;
+			const ev: SubagentEvent = {
+				ts: msg.timestamp ?? Date.now(),
+				type: "tool_activity",
+				status: "running",
+				tool: block.name,
+				summary,
+			};
+			appendEvent(art, ev);
+			state.lastToolName = block.name;
+			state.lastToolSummary = summary;
+			state.lastActivityAt = ev.ts;
 		}
 	}
 }
@@ -734,8 +804,27 @@ function labelFor(event: SubagentEvent): string {
  * default artifacts root (PI_CODING_AGENT_SESSION_DIR or ~/.pi/agent/sessions/subagentura).
  * For v1 this is a best-effort lookup; a future iteration can track all artifact roots.
  */
-function findArtifactById(id: string): SubagentArtifact | null {
+import isPathInside from "is-path-inside";
+
+export function findArtifactById(id: string): SubagentArtifact | null {
+	// Sub-agent ids are randomBytes(4).toString("hex") at spawn time, i.e. 8 hex
+	// chars. Validate the id before joining it into a path so that an
+	// LLM-supplied id like "../../../etc" can't escape the artifact root
+	// (path.join normalises "..", so a malicious id would otherwise resolve
+	// to a sibling directory and get exfiltrated to the parent LLM via
+	// read_subagent_artifact).
+	if (!/^[a-f0-9]{8}$/.test(id)) return null;
+
 	const root = process.env.PI_CODING_AGENT_SESSION_DIR ?? join(homedir(), ".pi", "agent", "sessions");
+	// Resolve the root once, with symlinks followed, so the containment check below
+	// is anchored on the real on-disk location. realpathSync throws if root doesn't
+	// exist; in that case there's nothing for us to find.
+	let realRoot: string;
+	try {
+		realRoot = realpathSync(root);
+	} catch {
+		return null;
+	}
 	let topLevel: string[];
 	try {
 		topLevel = readdirSync(root);
@@ -746,6 +835,19 @@ function findArtifactById(id: string): SubagentArtifact | null {
 		const candidate = join(root, entry, "artifacts", id);
 		try {
 			if (statSync(candidate).isDirectory()) {
+				// statSync follows symlinks, so a symlink at
+				// <root>/<cwd>/artifacts/<id> pointing outside the artifact root
+				// would otherwise be returned as a valid artifact. Resolve the
+				// candidate with realpath and verify it is still inside the
+				// resolved root. realpathSync is safe here because statSync
+				// above already confirmed candidate exists as a directory.
+				let realCandidate: string;
+				try {
+					realCandidate = realpathSync(candidate);
+				} catch {
+					continue;
+				}
+				if (!isPathInside(realCandidate, realRoot)) continue;
 				return artifactPath(join(root, entry, "artifacts"), id);
 			}
 		} catch {
@@ -830,10 +932,11 @@ export default function (pi: ExtensionAPI) {
 	// every running interactive sub-agent and fires pointer notifications for new events.
 	// The poller survives parent restarts (artifacts on disk + per-state lastDeliveredEventTs).
 	if (!g2.__piSubagenturaInteractivePollerHandle) {
-		g2.__piSubagenturaInteractivePollerHandle = setInterval(
-			() => pollArtifactChanges(pi),
-			5000,
-		);
+		const handle = setInterval(() => pollArtifactChanges(pi), 5000);
+		// Don't pin the event loop on a long-lived parent. unref() lets the process exit
+		// cleanly when nothing else is keeping it alive (no other ref'd handles).
+		handle.unref?.();
+		g2.__piSubagenturaInteractivePollerHandle = handle;
 	}
   // ── Tool 1: inherits conversation history ────────────────────────
   pi.registerTool({
@@ -1776,6 +1879,15 @@ export default function (pi: ExtensionAPI) {
     }),
 
     async execute(_toolCallId, params): Promise<any> {
+      // Validate the id shape FIRST so a malformed id gets a precise error
+      // instead of being collapsed into the generic "not found" message.
+      if (!/^[a-f0-9]{8}$/.test(params.id)) {
+        return {
+          content: [{ type: "text", text: `Invalid sub-agent id ${JSON.stringify(params.id)}; expected 8 lowercase hex chars.` }],
+          details: { id: params.id, status: "invalid_id" },
+          isError: true,
+        };
+      }
       const state = interactiveSubagentRegistry.get(params.id);
       const art = state
         ? artifactPath(dirname(state.artifactDir), basename(state.artifactDir))
@@ -1987,10 +2099,39 @@ export default function (pi: ExtensionAPI) {
     },
   });
 
-  // ── Session shutdown: abort all jobs and clear registry ──────────
+  // ── Session shutdown: abort all jobs, kill tmux panes, stop the poller ─
   (pi as any).on?.("session_shutdown", () => {
     const g2 = typeof global !== "undefined" ? global : globalThis;
 
+    // Stop the global poller so it doesn't fire after we're gone. Without
+    // clearInterval the handle would keep the event loop alive across restarts.
+    if (g2.__piSubagenturaInteractivePollerHandle) {
+      try {
+        clearInterval(g2.__piSubagenturaInteractivePollerHandle);
+      } catch { /* defensive */ }
+      g2.__piSubagenturaInteractivePollerHandle = undefined;
+    }
+
+    // Kill any tmux panes backing live interactive sub-agents. We can't leave them
+    // running — the parent process is shutting down. cancelInteractiveSubagent
+    // does the right thing (writes .cancelled, kills pane, lets trap record the event).
+    try {
+      for (const state of interactiveSubagentRegistry.values()) {
+        if (state.status === "running") {
+          try {
+            cancelInteractiveSubagent(state.id);
+          } catch { /* best effort */ }
+        }
+      }
+    } catch { /* best effort */ }
+
+    // Drop in-memory state for cancelled/exited interactive sub-agents. Without
+    // this, the Map grows unbounded across session_start/session_shutdown cycles
+    // and list_subagent_artifacts returns stale entries from previous sessions.
+    try {
+      interactiveSubagentRegistry.clear();
+    } catch { /* best effort */ }
+
     // Abort all running subagent sessions before clearing
     for (const job of jobRegistry.values()) {
       if (job.status === "running") {