pum-agent 0.2.13-beta.1 → 0.2.14-beta.1

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "pum-agent",
-  "version": "0.2.13-beta.1",
+  "version": "0.2.14-beta.1",
   "description": "A compact terminal coding agent powered by pi and OpenTUI.",
   "license": "MIT",
   "type": "module",

package/src/app.tsx

@@ -1209,7 +1209,6 @@ export function App({
                   : event.toolName.startsWith("message_cache_")
                     ? messageCacheDetail(event.result)
                     : undefined,
-            output: undefined,
             exitCode: bashResult.exitCode,
           });
           break;

package/src/subagents/fork-session.ts

@@ -0,0 +1,80 @@
+import { rmSync, writeFileSync } from "node:fs";
+import {
+  CURRENT_SESSION_VERSION,
+  SessionManager,
+  type SessionEntry,
+} from "@earendil-works/pi-coding-agent";
+import type { ForkOrigin, ForkSource } from "./types";
+
+type ForkSessionSource = Pick<
+  SessionManager,
+  "getSessionId" | "getSessionFile" | "getLeafId" | "getBranch" | "buildContextEntries"
+>;
+
+export function captureForkSource(
+  sessionManager: ForkSessionSource,
+  sourceAgentId: string | null,
+): ForkSource {
+  const cutoffEntryId = sessionManager.getLeafId();
+  const entries = cutoffEntryId === null ? [] : sessionManager.getBranch(cutoffEntryId);
+  if (cutoffEntryId !== null && entries.at(-1)?.id !== cutoffEntryId) {
+    throw new Error(`Cannot fork: cutoff entry ${cutoffEntryId} is not on the active branch`);
+  }
+  return {
+    origin: {
+      sourceSessionId: sessionManager.getSessionId(),
+      cutoffEntryId,
+      sourceAgentId,
+    },
+    sourceSessionFile: sessionManager.getSessionFile(),
+    entries: structuredClone(entries) as SessionEntry[],
+  };
+}
+
+export function createForkedSession(
+  source: ForkSource,
+  targetCwd: string,
+  sessionDir: string,
+): SessionManager {
+  const cutoff = source.origin.cutoffEntryId;
+  if ((cutoff === null && source.entries.length !== 0)
+    || (cutoff !== null && source.entries.at(-1)?.id !== cutoff)) {
+    throw new Error("Cannot fork: captured active branch does not match the cutoff entry");
+  }
+
+  const target = SessionManager.create(targetCwd, sessionDir, {
+    parentSession: source.sourceSessionFile,
+  });
+  const sessionFile = target.getSessionFile();
+  const header = target.getHeader();
+  if (!sessionFile || !header) throw new Error("Cannot fork: target session could not be allocated");
+
+  const forkHeader = {
+    ...header,
+    version: CURRENT_SESSION_VERSION,
+    cwd: targetCwd,
+    parentSession: source.sourceSessionFile,
+  };
+  const content = [forkHeader, ...source.entries]
+    .map((entry) => JSON.stringify(entry))
+    .join("\n") + "\n";
+  try {
+    writeFileSync(sessionFile, content, { flag: "wx" });
+    return SessionManager.open(sessionFile, sessionDir, targetCwd);
+  } catch (error) {
+    rmSync(sessionFile, { force: true });
+    throw error;
+  }
+}
+
+export function entriesAfterForkCutoff(
+  sessionManager: ForkSessionSource,
+  origin?: ForkOrigin,
+): SessionEntry[] {
+  if (!origin) return sessionManager.buildContextEntries();
+  const branch = sessionManager.getBranch();
+  if (origin.cutoffEntryId === null) return branch;
+  const cutoffIndex = branch.findIndex((entry) => entry.id === origin.cutoffEntryId);
+  if (cutoffIndex < 0) return [];
+  return branch.slice(cutoffIndex + 1);
+}

package/src/subagents/manager.ts

@@ -9,7 +9,7 @@ import {
   type ModelRuntime,
 } from "@earendil-works/pi-coding-agent";
 import { Type } from "typebox";
-import { existsSync } from "node:fs";
+import { existsSync, rmSync } from "node:fs";
 import { join } from "node:path";
 import { randomUUID } from "node:crypto";
 import {
@@ -80,6 +80,7 @@ import {
   type AgentMessageData,
   type TriggerEventData,
   type AgentTranscript,
+  type ForkSource,
   type SpawnSubagentOptions,
   type SubagentManagerEvent,
   type SubagentRegistryEvent,
@@ -90,6 +91,7 @@ import {
 import type { SpawnPreviewManager, SpawnPreviewRequester } from "./spawn-preview";
 import { readonlySubagentExtension } from "./readonly";
 import type { SessionStatsManager } from "../session-stats";
+import { captureForkSource, createForkedSession, entriesAfterForkCutoff } from "./fork-session";
 
 const MAX_RETAINED_AGENTS = 100;
 const MAX_MESSAGE_LENGTH = 12_000;
@@ -277,6 +279,12 @@ export function spawnSubagentParameters(readonlyAvailable: boolean) {
     task: Type.String({ description: "Complete task for the subagent" }),
     name: Type.Optional(Type.String({ description: "Optional worktree and agent name" })),
     preview: Type.Optional(Type.Boolean({ description: "Ask the user to approve before spawning" })),
+    context: Type.Optional(Type.Union([
+      Type.Literal("fresh"),
+      Type.Literal("fork"),
+    ], {
+      description: 'Conversation context mode. Defaults to "fresh". Use "fork" to inherit the immediate requester conversation before this assistant turn.',
+    })),
     ...(readonlyAvailable ? { readonly: readonlySpawnParameter() } : {}),
   }, { additionalProperties: false });
 }
@@ -443,7 +451,11 @@ export class SubagentManager {
           );
           restoredEntries.set(snapshot.id, childManager.getEntries());
           transcript = {
-            lines: replayEntries(childManager.buildContextEntries(), snapshot.worktree.path, true),
+            lines: replayEntries(
+              entriesAfterForkCutoff(childManager, snapshot.forkOrigin),
+              snapshot.worktree.path,
+              true,
+            ),
             stream: null,
             pending: [],
           };
@@ -845,7 +857,6 @@ export class SubagentManager {
                 : event.toolName.startsWith("message_cache_")
                   ? messageCacheDetail(event.result)
                   : undefined,
-          output: undefined,
           exitCode: bashResult.exitCode,
         });
         break;
@@ -1050,7 +1061,14 @@ export class SubagentManager {
               thinkingLevel: parent.snapshot.thinkingLevel,
               readonly: readonlyRequested,
               parentAgentId: agentId,
+              context: params.context ?? "fresh",
             };
+            if (options.context === "fork") {
+              options.forkSource = captureForkSource(
+                ctx.sessionManager,
+                agentId,
+              );
+            }
             if (params.preview) {
               const preview = await this.requestSpawnPreview({
                 sessionId: ctx.sessionManager.getSessionId(),
@@ -1269,7 +1287,11 @@ export class SubagentManager {
               modelId: `${ctx.model.provider}/${ctx.model.id}`,
               thinkingLevel: ctx.thinkingLevel ?? "off",
               readonly: readonlyRequested,
+              context: params.context ?? "fresh",
             };
+            if (options.context === "fork") {
+              options.forkSource = captureForkSource(ctx.sessionManager, null);
+            }
             if (params.preview) {
               const preview = await this.requestSpawnPreview({
                 sessionId: ctx.sessionManager.getSessionId(),
@@ -1421,6 +1443,11 @@ export class SubagentManager {
     if (options.readonly === true && this.sandboxModeSource() === "off") {
       throw new Error("Readonly subagents require the PUM Sandbox setting to be Auto or Require");
     }
+    const context = options.context ?? "fresh";
+    const forkSource = context === "fork"
+      ? options.forkSource ?? this.captureSpawnerForkSource(options.parentAgentId ?? null)
+      : undefined;
+    let allocatedSessionFile: string | undefined;
     const record = await this.withWorktreeLock(async () => {
       if (this.activeCount() >= this.maxActiveSubagents) throw activeLimitError(this.maxActiveSubagents);
       if (this.records.size >= MAX_RETAINED_AGENTS) throw new Error(`At most ${MAX_RETAINED_AGENTS} subagents can be retained`);
@@ -1431,33 +1458,48 @@ export class SubagentManager {
       }
 
       const worktree = await createWorktree(this.mainCwd, options.name);
-      const id = randomUUID().slice(0, 8);
-      const now = Date.now();
-      const snapshot: SubagentSnapshot = {
-        id,
-        name: worktree.name,
-        task: options.task,
-        status: "starting",
-        worktree,
-        parentAgentId: options.parentAgentId ?? null,
-        modelId: options.modelId,
-        thinkingLevel: options.thinkingLevel,
-        readonly: options.readonly === true,
-        transcript: emptyTranscript(),
-        startedAt: now,
-        updatedAt: now,
-        usage: emptyAgentUsage(),
-      };
-      const created: RuntimeRecord = {
-        snapshot,
-        userInstructionNotices: new Map(),
-        activityGeneration: 0,
-        idleNotifiedGeneration: 0,
-      };
-      this.records.set(id, created);
-      this.persist({ event: "spawned", id, at: now, snapshot: snapshotMetadata(snapshot) });
-      this.emit();
-      return created;
+      try {
+        const id = randomUUID().slice(0, 8);
+        const now = Date.now();
+        const snapshot: SubagentSnapshot = {
+          id,
+          name: worktree.name,
+          task: options.task,
+          status: "starting",
+          worktree,
+          parentAgentId: options.parentAgentId ?? null,
+          modelId: options.modelId,
+          thinkingLevel: options.thinkingLevel,
+          readonly: options.readonly === true,
+          forkOrigin: forkSource?.origin,
+          transcript: emptyTranscript(),
+          startedAt: now,
+          updatedAt: now,
+          usage: emptyAgentUsage(),
+        };
+        if (forkSource) {
+          const sessionDir = join(this.agentDir, "subagents", this.parentSessionId);
+          allocatedSessionFile = createForkedSession(
+            forkSource,
+            worktree.path,
+            sessionDir,
+          ).getSessionFile();
+          snapshot.sessionFile = allocatedSessionFile;
+        }
+        const created: RuntimeRecord = {
+          snapshot,
+          userInstructionNotices: new Map(),
+          activityGeneration: 0,
+          idleNotifiedGeneration: 0,
+        };
+        this.records.set(id, created);
+        this.emit();
+        return created;
+      } catch (error) {
+        if (allocatedSessionFile) rmSync(allocatedSessionFile, { force: true });
+        await removeWorktree(this.mainCwd, worktree).catch(() => {});
+        throw error;
+      }
     });
 
     try {
@@ -1470,11 +1512,30 @@ export class SubagentManager {
       });
       return cloneSnapshot(record);
     } catch (error) {
-      this.updateStatus(record, "failed", String(error));
+      if (context === "fork") {
+        await record.dispose?.();
+        this.records.delete(record.snapshot.id);
+        if (record.snapshot.sessionFile) rmSync(record.snapshot.sessionFile, { force: true });
+        await this.withWorktreeLock(() => removeWorktree(this.mainCwd, record.snapshot.worktree)).catch(() => {});
+        this.persist({ event: "removed", id: record.snapshot.id, at: Date.now() });
+        this.emit();
+      } else {
+        this.updateStatus(record, "failed", String(error));
+      }
       throw error;
     }
   }
 
+  private captureSpawnerForkSource(parentAgentId: string | null): ForkSource {
+    if (parentAgentId === null) {
+      if (!this.mainSessionManager) throw new Error("Cannot fork: the main source session is unavailable");
+      return captureForkSource(this.mainSessionManager, null);
+    }
+    const parent = this.records.get(parentAgentId);
+    if (!parent?.session) throw new Error("Cannot fork: the immediate parent session is unavailable");
+    return captureForkSource(parent.session.sessionManager, parentAgentId);
+  }
+
   private async ensureRuntime(record: RuntimeRecord, retrySettlements = true): Promise<void> {
     if (record.session) {
       if (retrySettlements) await this.retrySettlementsForParent(record.snapshot.id);
@@ -2247,9 +2308,17 @@ export class SubagentManager {
   private formatAgentList(): string {
     const agents = this.getAgents();
     if (!agents.length) return "No subagents.";
-    return agents.map((agent) =>
-      `${agent.id}  ${agent.name}  ${agent.status}${agent.readonly ? "  readonly" : ""}\n  ${agent.worktree.branch}\n  ${agent.worktree.path}`,
-    ).join("\n");
+    return agents.map((agent) => {
+      const origin = agent.forkOrigin;
+      const source = origin?.sourceAgentId
+        ? this.records.get(origin.sourceAgentId)?.snapshot.name ?? origin.sourceAgentId
+        : "main";
+      return `${agent.id}  ${agent.name}  ${agent.status}${agent.readonly ? "  readonly" : ""}`
+        + `\n  ${agent.worktree.branch}\n  ${agent.worktree.path}`
+        + (origin
+          ? `\n  fork source: ${source} · session ${origin.sourceSessionId} · cutoff ${origin.cutoffEntryId ?? "root"}`
+          : "");
+    }).join("\n");
   }
 
   async stop(id: string, status: SubagentStatus = "stopped", persist = true): Promise<void> {

package/src/subagents/spawn-preview-popup.tsx

@@ -38,7 +38,11 @@ export function SpawnPreviewPopup({
   const geometry = spawnPreviewPopupGeometry(terminalWidth, terminalHeight);
   const scrollRef = useRef<ScrollBoxRenderable>(null);
   const noteHeight = geometry.compact ? 1 : Math.min(4, Math.max(1, terminalHeight - 8));
-  const taskAreaHeight = Math.max(1, geometry.height - noteHeight - (geometry.compact ? 1 : 6));
+  const taskAreaHeight = Math.max(1, geometry.height - noteHeight - (geometry.compact ? 1 : 8));
+  const contextMode = request.options.context ?? "fresh";
+  const source = contextMode === "fork"
+    ? `${request.requester.name} · session ${request.requester.sessionId}`
+    : "none";
 
   useEffect(() => {
     inputRef.current?.setText("");
@@ -64,12 +68,15 @@ export function SpawnPreviewPopup({
       padding={geometry.compact ? 0 : 1}
     >
       {!geometry.compact ? (
-        <text
-          content={request.options.readonly ? "Child task · readonly" : "Child task"}
-          fg={theme.accent}
-          bg={theme.popupBg}
-          style={{ height: 1, flexShrink: 0 }}
-        />
+        <box style={{ flexDirection: "column", height: 3, flexShrink: 0 }}>
+          <text
+            content={request.options.readonly ? "Child task · readonly" : "Child task"}
+            fg={theme.accent}
+            bg={theme.popupBg}
+          />
+          <text content={`Context · ${contextMode}`} fg={theme.dim} bg={theme.popupBg} />
+          <text content={`Source · ${source}`} fg={theme.dim} bg={theme.popupBg} />
+        </box>
       ) : null}
       <scrollbox
         ref={scrollRef}

package/src/subagents/types.ts

@@ -2,6 +2,7 @@ import type { ImageContent } from "@earendil-works/pi-ai";
 import type { Line, PendingLine } from "../transcript";
 import type { WorktreeRecord } from "../worktree";
 import type { AgentUsage } from "../agent-usage";
+import type { SessionEntry } from "@earendil-works/pi-coding-agent";
 import {
   EXTERNAL_TRIGGER_CUSTOM_TYPE,
   type ExternalTriggerEventData,
@@ -32,6 +33,21 @@ export type AgentTranscript = {
   pending: PendingLine[];
 };
 
+export type SpawnContextMode = "fresh" | "fork";
+
+export type ForkOrigin = {
+  sourceSessionId: string;
+  cutoffEntryId: string | null;
+  sourceAgentId: string | null;
+};
+
+/** Immutable runtime capture. Only origin is persisted in the subagent snapshot. */
+export type ForkSource = {
+  origin: ForkOrigin;
+  sourceSessionFile?: string;
+  entries: readonly SessionEntry[];
+};
+
 export type SubagentSnapshot = {
   id: string;
   name: string;
@@ -45,6 +61,8 @@ export type SubagentSnapshot = {
   thinkingLevel: string;
   /** True when the child must not mutate files or delegate filesystem mutation. Missing legacy values mean false. */
   readonly?: boolean;
+  /** Present only when this child inherited an exact requester conversation branch. */
+  forkOrigin?: ForkOrigin;
   transcript: AgentTranscript;
   summary?: string;
   startedAt: number;
@@ -121,6 +139,9 @@ export type SpawnSubagentOptions = {
   readonly?: boolean;
   createWorktree?: boolean;
   parentAgentId?: string | null;
+  context?: SpawnContextMode;
+  /** Runtime-only immutable branch capture. This value is not persisted. */
+  forkSource?: ForkSource;
 };
 
 export type RoutedPrompt = {

package/src/tool-line.ts

@@ -9,7 +9,7 @@ export type ToolCall = {
   state: "running" | "ok" | "error" | "rejected";
   /** "+3 −1" for edits, or an error note. */
   detail?: string;
-  /** Cumulative live output, or the final displayed Bash output line. */
+  /** Cumulative live output retained until the Bash output display period ends. */
   output?: string;
   /** Start time used to delay live Bash output without delaying the tool row. */
   startedAt?: number;

package/src/transcript.tsx

@@ -6,7 +6,7 @@ import {
   type SyntaxStyle,
 } from "@opentui/core";
 import type { MarkdownProps } from "@opentui/react";
-import { useEffect, useState } from "react";
+import { useEffect, useRef, useState } from "react";
 import {
   useBlinkingText,
   useMarkdownCaret,
@@ -374,26 +374,62 @@ export function toolStateGlyph(state: ToolCall["state"]): string {
 
 const CHECK_MODE_HARD_BLOCK_PREFIX = "Check mode hard block:";
 const BASH_OUTPUT_DELAY_MS = 500;
+const BASH_OUTPUT_MIN_VISIBLE_MS = 2_000;
+
+function useBashOutputVisible(call: ToolCall): boolean {
+  const initiallyVisible = call.name === "bash"
+    && call.state === "running"
+    && Boolean(call.output)
+    && (call.startedAt === undefined || Date.now() - call.startedAt >= BASH_OUTPUT_DELAY_MS);
+  const [visible, setVisible] = useState(initiallyVisible);
+  const visibleSince = useRef<number | undefined>(initiallyVisible ? Date.now() : undefined);
 
-function useLiveBashOutputReady(call: ToolCall): boolean {
-  const [ready, setReady] = useState(() => (
-    call.startedAt === undefined || Date.now() - call.startedAt >= BASH_OUTPUT_DELAY_MS
-  ));
   useEffect(() => {
-    if (call.name !== "bash" || call.state !== "running" || call.startedAt === undefined) {
-      setReady(call.startedAt === undefined);
+    if (call.name !== "bash" || !call.output) {
+      visibleSince.current = undefined;
+      setVisible(false);
       return;
     }
-    const delay = BASH_OUTPUT_DELAY_MS - (Date.now() - call.startedAt);
-    if (delay <= 0) {
-      setReady(true);
+
+    const show = () => {
+      visibleSince.current ??= Date.now();
+      setVisible(true);
+    };
+
+    if (call.state === "running") {
+      if (call.startedAt === undefined) {
+        show();
+        return;
+      }
+      const delay = BASH_OUTPUT_DELAY_MS - (Date.now() - call.startedAt);
+      if (delay <= 0) {
+        show();
+        return;
+      }
+      visibleSince.current = undefined;
+      setVisible(false);
+      const timer = setTimeout(show, delay);
+      return () => clearTimeout(timer);
+    }
+
+    if (visibleSince.current === undefined) {
+      if (call.startedAt === undefined || Date.now() - call.startedAt < BASH_OUTPUT_DELAY_MS) {
+        setVisible(false);
+        return;
+      }
+      show();
+    }
+
+    const remaining = BASH_OUTPUT_MIN_VISIBLE_MS - (Date.now() - visibleSince.current!);
+    if (remaining <= 0) {
+      setVisible(false);
       return;
     }
-    setReady(false);
-    const timer = setTimeout(() => setReady(true), delay);
+    const timer = setTimeout(() => setVisible(false), remaining);
     return () => clearTimeout(timer);
-  }, [call.id, call.name, call.state, call.startedAt]);
-  return ready;
+  }, [call.id, call.name, call.output, call.startedAt, call.state]);
+
+  return visible;
 }
 
 function rejectedDetail(theme: Theme, detail: string): StyledText {
@@ -421,7 +457,7 @@ export function ToolLine({
   const spinner = useSpinner(call.state === "running");
   const failed = call.state === "error";
   const rejected = call.state === "rejected";
-  const liveBashOutputReady = useLiveBashOutputReady(call);
+  const bashOutputVisible = useBashOutputVisible(call);
   const toolColor = failed ? theme.error : rejected ? theme.rejection : theme.tool;
   const argColor = failed ? theme.error : rejected ? theme.rejection : theme.toolArg;
   const detailColor = failed ? theme.error : rejected ? theme.rejection : theme.dim;
@@ -443,7 +479,7 @@ export function ToolLine({
     caretColor: failed ? theme.error : rejected ? theme.rejection : theme.accent,
     active: workingCaret,
   });
-  const output = call.name === "bash" && call.state === "running" && call.output && liveBashOutputReady
+  const output = call.name === "bash" && call.output && bashOutputVisible
     ? bashOutputWindow(call.output)
     : null;
 

package/src/writing-style.ts

@@ -9,23 +9,26 @@ let currentStyle: WritingStyle = "none";
  * Practical ASD-STE100 guidance for model output. The controlled dictionary is
  * not embedded, so PUM does not claim that generated text is formally
  * certified or fully compliant with the standard.
+ *
+ * Kept deliberately concise: this text is part of the system prompt and is
+ * re-sent (cached) on every turn, so it costs tokens each turn. It states only
+ * the behavior-changing rules, not extra prose.
  */
 export const STE_SYSTEM_PROMPT = `## Writing style: Simplified Technical English (STE)
 
-Write your explanatory text with the principles of ASD-STE100 Simplified Technical English.
+Write explanatory text with the principles of ASD-STE100 Simplified Technical English.
 
 - Keep the technical meaning accurate. Accuracy has priority over simplification.
 - Use simple and unambiguous words. Use one word for one meaning when possible.
-- Use necessary project terms, code identifiers, commands, paths, API names, and other technical nouns and verbs unchanged.
-- Use the active voice. For instructions, use the imperative form.
+- Keep necessary project terms, code identifiers, commands, paths, API names, and other technical nouns and verbs unchanged.
+- Use the active voice. Use the imperative form for instructions.
 - Give only one instruction in each sentence.
-- Keep procedural sentences to 20 words or fewer.
-- Keep descriptive sentences to 25 words or fewer.
+- Keep procedural sentences to 20 words or fewer. Keep descriptive sentences to 25 words or fewer.
 - Use short paragraphs. Keep one topic in each paragraph.
 - Use vertical lists for complex information or multiple actions.
 - Do not use contractions. Do not omit necessary articles, subjects, or verbs.
 - Avoid ambiguous pronouns, idioms, slang, phrasal verbs, and unnecessary synonyms.
-- Repeat a noun when a pronoun could have more than one meaning.
+- Repeat a noun when a pronoun could mean more than one thing.
 - Keep terminology and wording consistent.
 - Do not modify quoted text, source code, tool output, or user-supplied text to make it follow STE.
 - Do not state or imply that the output has formal ASD approval or certified STE compliance.