@jopqior/pi-subagents 1.0.0

package/src/service/service-adapter.ts

@@ -0,0 +1,201 @@
+/**
+ * service-adapter.ts — Adapter that wraps SubagentManager to satisfy SubagentsService.
+ *
+ * Handles model resolution at the API boundary, record serialization
+ * (stripping non-serializable fields), and session gating.
+ */
+
+import type { Model } from "@earendil-works/pi-ai";
+import { parseThinkingLevel, thinkingLevelError } from "#src/config/thinking-level";
+import type { ParentSnapshot } from "#src/lifecycle/parent-snapshot";
+import type { AgentSpawnConfig, ResumeCallOptions, ResumeOutcome } from "#src/lifecycle/subagent-manager";
+import type { WorkspaceProvider } from "#src/lifecycle/workspace";
+import type {
+  ResumeOptions,
+  ResumeResult,
+  SpawnOptions,
+  SpawnSelectionProvider,
+  SpawnSelectionRegistration,
+  SubagentRecord,
+  SubagentsService,
+} from "#src/service/service";
+import type { ModelRegistry } from "#src/session/model-resolver";
+import type { SessionContext, Subagent, ThinkingLevel } from "#src/types";
+
+/** Narrow interface for the SubagentManager — avoids coupling to the concrete class. */
+export interface SubagentManagerLike {
+  spawn(snapshot: ParentSnapshot, type: string, prompt: string, options: AgentSpawnConfig): string;
+  getRecord(id: string): Subagent | undefined;
+  listAgents(): Subagent[];
+  abort(id: string): boolean;
+  waitForAll(): Promise<void>;
+  hasRunning(): boolean;
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+  resume(id: string, prompt: string, options: ResumeCallOptions): Promise<ResumeOutcome>;
+}
+
+/**
+ * Narrow runtime interface consumed by the service adapter.
+ * `SubagentRuntime` satisfies this structurally; tests use plain stubs.
+ */
+export interface ServiceRuntimeLike {
+  readonly currentCtx: SessionContext | undefined;
+  buildSnapshot(inheritContext: boolean): ParentSnapshot;
+  /** Parent session identity, so an SDK-spawned child nests under its parent. */
+  getSessionInfo(): { parentSessionFile: string; parentSessionId: string };
+  /** Selection-provider registration, delegated to the runtime-owned scope. */
+  registerSpawnSelectionProvider(provider: SpawnSelectionProvider): SpawnSelectionRegistration;
+}
+
+/** Adapter that wraps SubagentManager to satisfy SubagentsService. */
+export class SubagentsServiceAdapter implements SubagentsService {
+  constructor(
+    private readonly manager: SubagentManagerLike,
+    private readonly resolveModel: (input: string, registry: ModelRegistry) => Model<any> | string,
+    private readonly runtime: ServiceRuntimeLike,
+  ) {}
+
+  spawn(type: string, prompt: string, options?: SpawnOptions): string {
+    if (!this.runtime.currentCtx) {
+      throw new Error("No active session — cannot spawn agents outside a session.");
+    }
+
+    const model = this.resolveModelOption(options?.model);
+    const description = options?.description ?? prompt.slice(0, 80);
+
+    const snapshot = this.runtime.buildSnapshot(options?.inheritContext ?? false);
+    const { parentSessionFile, parentSessionId } = this.runtime.getSessionInfo();
+    return this.manager.spawn(snapshot, type, prompt, {
+      description,
+      model,
+      // No toolCallId — an SDK spawn has no originating tool call, and
+      // Subagent.toolCallId reporting undefined there is the truth.
+      parentSession: { parentSessionFile, parentSessionId },
+      maxTurns: options?.maxTurns,
+      thinkingLevel: this.resolveThinkingLevel(options?.thinkingLevel),
+      inheritContext: options?.inheritContext,
+      bypassQueue: options?.bypassQueue,
+      // A caller that names `foreground` has committed; one that omits it has
+      // not, so the agent's own frontmatter decides and background is the
+      // SDK-door default.
+      background:
+        options?.foreground === undefined
+          ? { kind: "default", isBackground: true }
+          : { kind: "explicit", isBackground: !options.foreground },
+    });
+  }
+
+  getRecord(id: string): SubagentRecord | undefined {
+    const record = this.manager.getRecord(id);
+    return record ? toSubagentRecord(record) : undefined;
+  }
+
+  listAgents(): SubagentRecord[] {
+    return this.manager.listAgents().map(toSubagentRecord);
+  }
+
+  abort(id: string): boolean {
+    return this.manager.abort(id);
+  }
+
+  async steer(id: string, message: string): Promise<boolean> {
+    const record = this.manager.getRecord(id);
+    if (!record) {
+      return false;
+    }
+    const outcome = await record.steer(message);
+    return outcome.kind !== "rejected";
+  }
+
+  async resume(id: string, prompt: string, options?: ResumeOptions): Promise<ResumeResult> {
+    const outcome = await this.manager.resume(id, prompt, {
+      claimOutcome: options?.claimOutcome,
+      signal: options?.signal,
+    });
+    // A refusal is the same value on both sides; only the resumed arm crosses
+    // the by-value boundary the snapshot draws.
+    return outcome.kind === "refused"
+      ? outcome
+      : { kind: "resumed", record: toSubagentRecord(outcome.record) };
+  }
+
+  async waitForAll(): Promise<void> {
+    return this.manager.waitForAll();
+  }
+
+  hasRunning(): boolean {
+    return this.manager.hasRunning();
+  }
+
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void {
+    return this.manager.registerWorkspaceProvider(provider);
+  }
+
+  registerSpawnSelectionProvider(provider: SpawnSelectionProvider): SpawnSelectionRegistration {
+    return this.runtime.registerSpawnSelectionProvider(provider);
+  }
+
+  /**
+   * Narrow an optional thinking-level override, rejecting one the SDK does not know.
+   *
+   * `SpawnOptions` widens the field to `string` for the public surface, and Pi clamps an
+   * unrecognized level down to `off` rather than reporting it — so a typo would silently
+   * disable thinking in the child. Throwing matches the adapter's other input failures.
+   */
+  private resolveThinkingLevel(input: string | undefined): ThinkingLevel | undefined {
+    if (input == null) return undefined;
+    const level = parseThinkingLevel(input);
+    if (level === undefined) throw new Error(thinkingLevelError(input));
+    return level;
+  }
+
+  /** Resolve an optional model-string override against the current session's registry. */
+  private resolveModelOption(modelInput: string | undefined): Model<any> | undefined {
+    if (!modelInput) return undefined;
+    const registry = this.runtime.currentCtx?.modelRegistry;
+    if (!registry) {
+      throw new Error("No model registry available.");
+    }
+    const resolved = this.resolveModel(modelInput, registry);
+    if (typeof resolved === "string") {
+      throw new Error(resolved);
+    }
+    return resolved;
+  }
+}
+
+/**
+ * Convert an internal Subagent to a serializable SubagentRecord.
+ *
+ * The allowlist is explicit because the snapshot admits only discrete facts —
+ * identity, resolved spawn decisions, cumulative metrics, and pointers to
+ * durable artifacts. Live objects, momentary activity, and package-internal
+ * bookkeeping stay out; see
+ * `docs/decisions/0005-subagent-record-admission-policy.md`.
+ */
+export function toSubagentRecord(record: Subagent): SubagentRecord {
+  const out: SubagentRecord = {
+    id: record.id,
+    type: record.type,
+    description: record.description,
+    status: record.status,
+    isBackground: record.isBackground,
+    toolUses: record.toolUses,
+    turnCount: record.turnCount,
+    startedAt: record.startedAt,
+    // Copy: the agent accumulates into its own object on every message_end, so
+    // an aliased snapshot would drift, and a consumer could write into the
+    // agent's totals.
+    lifetimeUsage: { ...record.lifetimeUsage },
+    compactionCount: record.compactionCount,
+  };
+
+  if (record.result !== undefined) out.result = record.result;
+  if (record.pendingQuestion !== undefined) out.pendingQuestion = record.pendingQuestion;
+  if (record.error !== undefined) out.error = record.error;
+  if (record.completedAt !== undefined) out.completedAt = record.completedAt;
+  if (record.maxTurns !== undefined) out.maxTurns = record.maxTurns;
+  if (record.outputFile !== undefined) out.outputFile = record.outputFile;
+
+  return out;
+}

package/src/service/service.ts

@@ -0,0 +1,246 @@
+/**
+ * service.ts — Public API surface for cross-extension access to subagents.
+ *
+ * Consumers declare this package as an optional peer dependency and use
+ * dynamic import to access the accessor functions:
+ *
+ *   const { getSubagentsService } = await import("@jopqior/pi-subagents");
+ *   const svc = getSubagentsService();
+ *   svc?.spawn("Explore", "Check for stale TODOs");
+ */
+
+import type { Api, Model } from "@earendil-works/pi-ai";
+import type { SubagentThinkingLevel } from "#src/config/thinking-level";
+import type { ResumeRefusal, SubagentStatus } from "#src/lifecycle/subagent";
+import type { ResumeRefusalReason } from "#src/lifecycle/subagent-manager";
+import type { LifetimeUsage } from "#src/lifecycle/usage";
+import type {
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+} from "#src/lifecycle/workspace";
+
+
+// SubagentStatus is defined in the lifecycle layer (single home) and re-exported
+// here for the public API surface — mirrors the LifetimeUsage / workspace pattern.
+export type { SubagentStatus } from "#src/lifecycle/subagent";
+// The resume vocabulary is re-exported for the same reason: the record owns the
+// reasons a resume is refused, and the manager adds the one that is not a fact
+// about a record.
+// Generative extension seam (ADR 0002, Phase 16 Step 2). The provider type
+// and all four collaborator types it references are re-exported by name so
+// consumers can import them directly rather than recovering them via
+// indexed-access inference (e.g. `Parameters<WorkspaceProvider["prepare"]>[0]`).
+export type {
+  LifetimeUsage,
+  ResumeRefusal,
+  ResumeRefusalReason,
+  Workspace,
+  WorkspaceDisposeOutcome,
+  WorkspaceDisposeResult,
+  WorkspacePrepareContext,
+  WorkspaceProvider,
+};
+
+/**
+ * Serializable by-value snapshot of an agent's state.
+ *
+ * Produced by this package and read by consumers — not a contract third
+ * parties implement, so a new field is a minor release. What earns a field a
+ * place here (and what the snapshot deliberately withholds) is decided in
+ * `docs/decisions/0005-subagent-record-admission-policy.md`.
+ */
+export interface SubagentRecord {
+  id: string;
+  type: string;
+  description: string;
+  status: SubagentStatus;
+  /** Scheduling and announcement mode, resolved once at the manager choke point. */
+  isBackground: boolean;
+  result?: string;
+  /** The question the agent ended its turn with, when it declared one. */
+  pendingQuestion?: string;
+  error?: string;
+  toolUses: number;
+  /** Turns consumed so far; starts at 1. */
+  turnCount: number;
+  /** Turn ceiling for this run, when one was set. */
+  maxTurns?: number;
+  startedAt: number;
+  completedAt?: number;
+  lifetimeUsage: LifetimeUsage;
+  compactionCount: number;
+  /** Path to the agent's session JSONL, once the session exists. */
+  outputFile?: string;
+}
+
+/** Options for resuming an agent via the service. */
+export interface ResumeOptions {
+  /**
+   * Declare that the caller will deliver the resumed outcome to the parent,
+   * suppressing the completion nudge for it. Omitted, the resumed outcome is
+   * announced exactly as a background completion is.
+   */
+  claimOutcome?: boolean;
+  /**
+   * Cancels the resumed turn loop. `abort(id)` does not reach it: a resume does
+   * not run under the record's own abort controller.
+   */
+  signal?: AbortSignal;
+}
+
+/**
+ * What a resume attempt produced.
+ *
+ * A resumed run that *failed* is still `resumed` — the snapshot carries
+ * `status: "error"` and the message. `refused` means no turn loop ran.
+ */
+export type ResumeResult =
+  | { kind: "resumed"; record: SubagentRecord }
+  | { kind: "refused"; reason: ResumeRefusalReason };
+
+/** Options for spawning an agent via the service. */
+export interface SpawnOptions {
+  description?: string;
+  model?: string;
+  maxTurns?: number;
+  thinkingLevel?: string;
+  inheritContext?: boolean;
+  foreground?: boolean;
+  bypassQueue?: boolean;
+}
+
+/** The pair a human selected for one new run — the authority for model and thinking. */
+export interface SpawnSelection {
+  readonly model: Model<Api>;
+  /** Mandatory and never `undefined`: `off` through `max`, including `off`. */
+  readonly thinkingLevel: SubagentThinkingLevel;
+}
+
+/** What a provider is asked, for one admitted new run about to create a child session. */
+export interface SpawnSelectionRequest {
+  /** Identifies the request in the root UI. */
+  readonly agentId: string;
+  readonly agentType: string;
+  readonly description: string;
+  /** The authenticated available models of the session whose manager is spawning — the actual choices. */
+  readonly availableModels: readonly Model<Api>[];
+}
+
+/**
+ * Asks for the model and thinking level a new run should use.
+ *
+ * Resolves with the selected pair, or `undefined` for user cancellation —
+ * never an approval that silently keeps inherited values. Infrastructure
+ * failures (no UI, unavailable catalogue) reject rather than resolve.
+ */
+export interface SpawnSelectionProvider {
+  select(
+    request: SpawnSelectionRequest,
+    signal: AbortSignal,
+  ): Promise<SpawnSelection | undefined>;
+}
+
+/**
+ * The outcome of registering a selection provider.
+ *
+ * `owned` — this session is the root of its subagent tree and now holds the
+ * lease; `dispose()` revokes it (idempotent) and a new session is required to
+ * register again.
+ *
+ * `inherited` — this session is a descendant: the supplied provider is NOT
+ * installed and the root's ownership is untouched (including when the
+ * inherited lease is already closed); `dispose()` is a no-op.
+ */
+export type SpawnSelectionRegistration =
+  | { readonly kind: "owned"; dispose(): void }
+  | { readonly kind: "inherited"; dispose(): void };
+
+/** The public service contract for cross-extension subagent access. */
+export interface SubagentsService {
+  /** Spawn an agent. Returns the agent ID immediately. */
+  spawn(type: string, prompt: string, options?: SpawnOptions): string;
+
+  /** Get a snapshot of an agent's current state. */
+  getRecord(id: string): SubagentRecord | undefined;
+
+  /** List all tracked agents, most recent first. */
+  listAgents(): SubagentRecord[];
+
+  /** Abort a running or queued agent. Returns false if not found. */
+  abort(id: string): boolean;
+
+  /** Send a steering message to a running agent. */
+  steer(id: string, message: string): Promise<boolean>;
+
+  /**
+   * Resume a settled agent with a new prompt, continuing its session.
+   *
+   * Resolves when the resumed run reaches a terminal state, carrying the
+   * terminal snapshot — a caller that does not need the outcome can ignore the
+   * promise. A refusal resolves promptly instead: the checks are synchronous
+   * and no turn loop is started.
+   */
+  resume(id: string, prompt: string, options?: ResumeOptions): Promise<ResumeResult>;
+
+  /** Wait for all running and queued agents to complete. */
+  waitForAll(): Promise<void>;
+
+  /** Whether any agents are running or queued. */
+  hasRunning(): boolean;
+
+  /**
+   * Register the single workspace provider that supplies a child's working
+   * directory plus bracketed setup/teardown. Throws if one is already
+   * registered. Returns a disposer that unregisters the provider.
+   */
+  registerWorkspaceProvider(provider: WorkspaceProvider): () => void;
+
+  /**
+   * Register the per-spawn selection provider this session's subagent tree
+   * will consult before creating any new child session.
+   *
+   * On the tree's root session: installs the provider (throws if one is
+   * already registered, or once this session's scope is closed) and returns an
+   * `owned` registration whose disposer revokes it. On a descendant session:
+   * installs nothing and returns `inherited` — the root's chooser serves the
+   * whole tree.
+   */
+  registerSpawnSelectionProvider(provider: SpawnSelectionProvider): SpawnSelectionRegistration;
+}
+
+/** Event channel constants for pi.events subscriptions. */
+export const SUBAGENT_EVENTS = {
+  STARTED: "subagents:started",
+  COMPLETED: "subagents:completed",
+  FAILED: "subagents:failed",
+  RESUMING: "subagents:resuming",
+  RESUMED: "subagents:resumed",
+  COMPACTED: "subagents:compacted",
+  CREATED: "subagents:created",
+  STEERED: "subagents:steered",
+} as const;
+
+// ---- Accessor functions ----
+
+const SERVICE_KEY = Symbol.for("@gotgenes/pi-subagents:service");
+
+/** Publish the SubagentsService on globalThis for cross-extension access. */
+export function publishSubagentsService(service: SubagentsService): void {
+  (globalThis as Record<symbol, unknown>)[SERVICE_KEY] = service;
+}
+
+/** Retrieve the published SubagentsService, or undefined if not yet published. */
+export function getSubagentsService(): SubagentsService | undefined {
+  return (globalThis as Record<symbol, unknown>)[SERVICE_KEY] as
+    | SubagentsService
+    | undefined;
+}
+
+/** Remove the SubagentsService from globalThis (call on shutdown/reload). */
+export function unpublishSubagentsService(): void {
+  // eslint-disable-next-line @typescript-eslint/no-dynamic-delete -- Symbol-keyed global property; Map.delete() is not applicable
+  delete (globalThis as Record<symbol, unknown>)[SERVICE_KEY];
+}

package/src/session/ask-parent-tool.ts

@@ -0,0 +1,69 @@
+/**
+ * ask-parent-tool.ts — The tool a child asks its delegating agent a question with.
+ *
+ * A child that cannot finish without information only its parent has records
+ * the question here and ends its turn. The parent answers by resuming the
+ * child, which continues with its context intact.
+ *
+ * The tool records; it does not announce. Every result carrier already renders
+ * a pending question — with the exact resume call while the record is still
+ * resumable, and why it is not once `Subagent.resumeRefusal` says otherwise —
+ * so announcing here would tell the parent the same thing twice.
+ *
+ * Lives in `session/` rather than `tools/` because it is installed on the
+ * child's session by the assembly factory, where every `tools/` module is
+ * registered on the parent's.
+ */
+
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "@sinclair/typebox";
+
+export const ASK_PARENT_TOOL_NAME = "ask_parent";
+
+const RESULT_TEXT =
+	"Question recorded for the delegating agent. End your turn now — it will answer by resuming you, and you will continue with your context intact.";
+
+/** Records a child's question against its own subagent record. */
+export type QuestionRecorder = (question: string) => void;
+
+export class AskParentTool {
+	constructor(private readonly record: QuestionRecorder) {}
+
+	execute(
+		_toolCallId: string,
+		params: { question: string },
+		_signal: AbortSignal,
+		_onUpdate: unknown,
+		_ctx: unknown,
+	) {
+		this.record(params.question);
+		// `details` is required by the SDK's result type; this tool renders none.
+		return { content: [{ type: "text" as const, text: RESULT_TEXT }], details: undefined };
+	}
+
+	toToolDefinition() {
+		return defineTool({
+			name: ASK_PARENT_TOOL_NAME,
+			label: "Ask Parent",
+			promptSnippet: "Ask the delegating agent a question, then end your turn.",
+			description:
+				"Record a question for the agent that delegated this task. Use it when you cannot finish " +
+				"without information only the delegating agent has, and the answer changes what you would do; " +
+				"otherwise state your assumption and continue. After calling this, end your turn immediately — " +
+				"the delegating agent answers by resuming you, and you continue with your context intact.",
+			parameters: Type.Object({
+				question: Type.String({
+					description: "The question the delegating agent must answer before you can continue.",
+				}),
+			}),
+			// The tool's own work is synchronous; the SDK's execute contract is not.
+			execute: (
+				toolCallId: string,
+				params: { question: string },
+				signal: AbortSignal,
+				onUpdate: unknown,
+				ctx: unknown,
+			) => Promise.resolve(this.execute(toolCallId, params, signal, onUpdate, ctx)),
+		});
+	}
+}

package/src/session/content-items.ts

@@ -0,0 +1,53 @@
+/**
+ * content-items.ts — Shared parsing utilities for Pi SDK message content items.
+ *
+ * Provides type-safe extraction of text parts and tool-call names from
+ * assistant message content arrays. Pure functions — no IO.
+ */
+
+import type { TextContent, ToolCall } from "@earendil-works/pi-ai";
+
+// ── Types ─────────────────────────────────────────────────────────────────────
+
+/** Extracted text parts and tool names from assistant message content. */
+export interface AssistantContentParts {
+  textParts: string[];
+  toolNames: string[];
+}
+
+// ── Functions ─────────────────────────────────────────────────────────────────
+
+/**
+ * Extracts the display name from a tool-call content item.
+ *
+ * Returns 'unknown' for non-toolCall items.
+ * The Pi SDK's ToolCall.name is always present — no fallback chain needed.
+ */
+export function getToolCallName(c: { type: string }): string {
+  if (c.type !== "toolCall") return "unknown";
+  return (c as ToolCall).name;
+}
+
+/**
+ * Extract text parts and tool-call names from assistant message content items.
+ *
+ * Accepts any array whose elements carry a `type` discriminant — all Pi SDK
+ * content types (TextContent, ThinkingContent, ToolCall) satisfy this constraint.
+ * Pure data extraction — consumers apply their own presentation formatting.
+ * Skips items of unknown types (e.g. thinking blocks, images) and empty text.
+ */
+export function extractAssistantContent(
+  content: ReadonlyArray<{ type: string }>,
+): AssistantContentParts {
+  const textParts: string[] = [];
+  const toolNames: string[] = [];
+  for (const c of content) {
+    if (c.type === "text") {
+      const text = (c as TextContent).text;
+      if (text) textParts.push(text);
+    } else if (c.type === "toolCall") {
+      toolNames.push(getToolCallName(c));
+    }
+  }
+  return { textParts, toolNames };
+}

package/src/session/context.ts

@@ -0,0 +1,80 @@
+/**
+ * context.ts — Extract parent conversation context for subagent inheritance.
+ */
+
+import type { TextContent } from "@earendil-works/pi-ai";
+import type { SessionContext } from "#src/types";
+
+/**
+ * Minimal structural types for session branch entries consumed by buildParentContext.
+ * `getBranch()` returns `unknown[]` in SessionContext (ISP), so we cast to these
+ * local shapes instead of coupling to the SDK's SessionEntry type.
+ */
+type MessageEntry = {
+  type: "message";
+  message: { role: string; content: string | { type: string }[] };
+};
+type CompactionEntry = { type: "compaction"; summary?: string };
+type BranchEntry = MessageEntry | CompactionEntry | { type: string };
+
+/** Type predicate: narrow an unknown content block to TextContent. */
+function isTextContent(c: unknown): c is TextContent {
+  return typeof c === "object" && c !== null && (c as { type: string }).type === "text";
+}
+
+/** Extract text from a message content block array. */
+export function extractText(content: unknown[]): string {
+  return content
+    .filter(isTextContent)
+    .map((c) => c.text)
+    .join("\n");
+}
+
+/** Format a message entry (user/assistant); returns undefined for roles to skip. */
+function formatMessageEntry(entry: MessageEntry): string | undefined {
+  const msg = entry.message;
+  const text = typeof msg.content === "string" ? msg.content : extractText(msg.content);
+  if (!text.trim()) return undefined;
+  if (msg.role === "user") return `[User]: ${text.trim()}`;
+  if (msg.role === "assistant") return `[Assistant]: ${text.trim()}`;
+  return undefined; // skip toolResult and other roles
+}
+
+/** Format a compaction entry; returns undefined when no summary is present. */
+function formatCompactionEntry(entry: CompactionEntry): string | undefined {
+  return entry.summary ? `[Summary]: ${entry.summary}` : undefined;
+}
+
+/** Dispatch a branch entry to the appropriate formatter. */
+function formatBranchEntry(entry: BranchEntry): string | undefined {
+  if (entry.type === "message") return formatMessageEntry(entry as MessageEntry);
+  if (entry.type === "compaction") return formatCompactionEntry(entry as CompactionEntry);
+  return undefined;
+}
+
+/**
+ * Build a text representation of the parent conversation context.
+ * Used when inherit_context is true to give the subagent visibility
+ * into what has been discussed/done so far.
+ */
+export function buildParentContext(ctx: SessionContext): string {
+  const entries = ctx.sessionManager.getBranch();
+  // eslint-disable-next-line @typescript-eslint/no-unnecessary-condition -- getBranch() may return undefined at runtime despite its type
+  if (!entries || entries.length === 0) return "";
+
+  const parts = (entries as BranchEntry[])
+    .map(formatBranchEntry)
+    .filter((p): p is string => p !== undefined);
+
+  if (parts.length === 0) return "";
+
+  return `# Parent Conversation Context
+The following is the conversation history from the parent session that spawned you.
+Use this context to understand what has been discussed and decided so far.
+
+${parts.join("\n\n")}
+
+---
+# Your Task (below)
+`;
+}