gsd-pi 2.76.0 → 2.77.0-dev.538325aea

package/packages/gsd-agent-core/dist/system-prompt.js

@@ -0,0 +1,201 @@
+/**
+ * System prompt construction and project context loading
+ */
+import { dirname, resolve } from "node:path";
+import { fileURLToPath } from "node:url";
+import { formatSkillsForPrompt } from "@gsd/pi-coding-agent";
+// toPosixPath removed from @gsd/pi-coding-agent 0.67.2 public API.
+// Phase 09: move to @gsd/agent-types.
+function toPosixPath(p) {
+    return p.replace(/\\/g, "/");
+}
+function getPiPackageDir() {
+    const piEntryPath = fileURLToPath(import.meta.resolve("@gsd/pi-coding-agent"));
+    return resolve(dirname(piEntryPath), "..");
+}
+function getReadmePath() {
+    return resolve(getPiPackageDir(), "README.md");
+}
+function getDocsPath() {
+    return resolve(getPiPackageDir(), "docs");
+}
+function getExamplesPath() {
+    return resolve(getPiPackageDir(), "examples");
+}
+/** Tool descriptions for system prompt */
+const toolDescriptions = {
+    read: "Read file contents",
+    bash: "Execute bash commands (ls, grep, find, etc.)",
+    edit: "Make surgical edits to files (find exact text and replace)",
+    write: "Create or overwrite files",
+    grep: "Search file contents for patterns (respects .gitignore)",
+    find: "Find files by glob pattern (respects .gitignore)",
+    ls: "List directory contents",
+    lsp: "Code intelligence via Language Server Protocol (go-to-definition, references, diagnostics, hover, rename, symbols)",
+};
+/** Build the system prompt with tools, guidelines, and context */
+export function buildSystemPrompt(options = {}) {
+    const { customPrompt, selectedTools, toolSnippets, promptGuidelines, appendSystemPrompt, cwd, contextFiles: providedContextFiles, skills: providedSkills, } = options;
+    const resolvedCwd = toPosixPath(cwd ?? process.cwd());
+    const now = new Date();
+    const dateTime = now.toLocaleString("en-US", {
+        weekday: "long",
+        year: "numeric",
+        month: "long",
+        day: "numeric",
+        hour: "2-digit",
+        minute: "2-digit",
+        second: "2-digit",
+        timeZoneName: "short",
+    });
+    const appendSection = appendSystemPrompt ? `\n\n${appendSystemPrompt}` : "";
+    const contextFiles = providedContextFiles ?? [];
+    const skills = providedSkills ?? [];
+    if (customPrompt) {
+        let prompt = customPrompt;
+        if (appendSection) {
+            prompt += appendSection;
+        }
+        // Append project context files
+        if (contextFiles.length > 0) {
+            prompt += "\n\n# Project Context\n\n";
+            prompt += "Project-specific instructions and guidelines:\n\n";
+            for (const { path: filePath, content } of contextFiles) {
+                prompt += `## ${filePath}\n\n${content}\n\n`;
+            }
+        }
+        // Append skills section (if read or Skill tool is available)
+        const customPromptHasSkillAccess = !selectedTools || selectedTools.includes("read") || selectedTools.includes("Skill");
+        if (customPromptHasSkillAccess && skills.length > 0) {
+            prompt += formatSkillsForPrompt(skills);
+        }
+        // Add date/time and working directory last
+        prompt += `\nCurrent date and time: ${dateTime}`;
+        prompt += `\nCurrent working directory: ${resolvedCwd}`;
+        // Append promptGuidelines from extension-registered tools.
+        // Without this, tools registered via pi.registerTool() with promptGuidelines
+        // have their definitions reach the API but the model has no guidance on when
+        // to use them (#1184).
+        if (promptGuidelines && promptGuidelines.length > 0) {
+            prompt += "\n\n";
+            for (const guideline of promptGuidelines) {
+                prompt += guideline + "\n";
+            }
+        }
+        return prompt;
+    }
+    // Get absolute paths to documentation and examples
+    const readmePath = getReadmePath();
+    const docsPath = getDocsPath();
+    const examplesPath = getExamplesPath();
+    // Build tools list based on selected tools.
+    // Built-ins use toolDescriptions. Custom tools can provide one-line snippets.
+    const tools = selectedTools || ["read", "bash", "edit", "write"];
+    const toolsList = tools.length > 0
+        ? tools
+            .map((name) => {
+            const snippet = toolSnippets?.[name] ?? toolDescriptions[name] ?? name;
+            return `- ${name}: ${snippet}`;
+        })
+            .join("\n")
+        : "(none)";
+    // Build guidelines based on which tools are actually available
+    const guidelinesList = [];
+    const guidelinesSet = new Set();
+    const addGuideline = (guideline) => {
+        if (guidelinesSet.has(guideline)) {
+            return;
+        }
+        guidelinesSet.add(guideline);
+        guidelinesList.push(guideline);
+    };
+    const hasBash = tools.includes("bash");
+    const hasEdit = tools.includes("edit");
+    const hasWrite = tools.includes("write");
+    const hasGrep = tools.includes("grep");
+    const hasFind = tools.includes("find");
+    const hasLs = tools.includes("ls");
+    const hasRead = tools.includes("read");
+    const hasLsp = tools.includes("lsp");
+    // File exploration guidelines
+    if (hasBash && !hasGrep && !hasFind && !hasLs) {
+        addGuideline("Use bash for file operations like ls, rg, find");
+    }
+    else if (hasBash && (hasGrep || hasFind || hasLs)) {
+        addGuideline("Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)");
+    }
+    // Read before edit guideline
+    if (hasRead && hasEdit) {
+        addGuideline("Use read to examine files before editing. You must use this tool instead of cat or sed.");
+    }
+    // Edit guideline
+    if (hasEdit) {
+        addGuideline("Use edit for precise changes (old text must match exactly)");
+    }
+    // Write guideline
+    if (hasWrite) {
+        addGuideline("Use write only for new files or complete rewrites");
+    }
+    // LSP guideline
+    if (hasLsp) {
+        addGuideline(`Use lsp as the primary tool for code navigation in typed codebases:
+- Navigation: definition, type_definition, implementation, references, incoming_calls, outgoing_calls
+- Understanding: hover (types + docs), signature (parameter info), symbols (file/workspace search)
+- Refactoring: rename (project-wide), code_actions (quick-fixes, imports, refactors), format (formatter)
+- Verification: diagnostics after edits to catch type errors immediately
+- Never grep for a symbol definition when lsp can resolve it semantically
+- Never shell out to a formatter when lsp format is available`);
+    }
+    // Output guideline (only when actually writing or executing)
+    if (hasEdit || hasWrite) {
+        addGuideline("When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did");
+    }
+    for (const guideline of promptGuidelines ?? []) {
+        const normalized = guideline.trim();
+        if (normalized.length > 0) {
+            addGuideline(normalized);
+        }
+    }
+    // Always include these
+    addGuideline("Be concise in your responses");
+    addGuideline("Show file paths clearly when working with files");
+    const guidelines = guidelinesList.map((g) => `- ${g}`).join("\n");
+    let prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.
+
+Available tools:
+${toolsList}
+
+In addition to the tools above, you may have access to other custom tools depending on the project.
+
+Guidelines:
+${guidelines}
+
+Pi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):
+- Main documentation: ${readmePath}
+- Additional docs: ${docsPath}
+- Examples: ${examplesPath} (extensions, custom tools, SDK)
+- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)
+- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing
+- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;
+    if (appendSection) {
+        prompt += appendSection;
+    }
+    // Append project context files
+    if (contextFiles.length > 0) {
+        prompt += "\n\n# Project Context\n\n";
+        prompt += "Project-specific instructions and guidelines:\n\n";
+        for (const { path: filePath, content } of contextFiles) {
+            prompt += `## ${filePath}\n\n${content}\n\n`;
+        }
+    }
+    // Append skills section (if read or Skill tool is available)
+    const hasSkill = tools.includes("Skill");
+    if ((hasRead || hasSkill) && skills.length > 0) {
+        prompt += formatSkillsForPrompt(skills);
+    }
+    // Add date/time and working directory last
+    prompt += `\nCurrent date and time: ${dateTime}`;
+    prompt += `\nCurrent working directory: ${resolvedCwd}`;
+    return prompt;
+}
+//# sourceMappingURL=system-prompt.js.map

package/packages/gsd-agent-core/dist/system-prompt.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"system-prompt.js","sourceRoot":"","sources":["../src/system-prompt.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * System prompt construction and project context loading\n */\n\nimport { dirname, resolve } from \"node:path\";\nimport { fileURLToPath } from \"node:url\";\nimport { formatSkillsForPrompt } from \"@gsd/pi-coding-agent\";\nimport type { Skill } from \"@gsd/agent-types\";\n\n// toPosixPath removed from @gsd/pi-coding-agent 0.67.2 public API.\n// Phase 09: move to @gsd/agent-types.\nfunction toPosixPath(p: string): string {\n\treturn p.replace(/\\\\/g, \"/\");\n}\n\nfunction getPiPackageDir(): string {\n\tconst piEntryPath = fileURLToPath(import.meta.resolve(\"@gsd/pi-coding-agent\"));\n\treturn resolve(dirname(piEntryPath), \"..\");\n}\n\nfunction getReadmePath(): string {\n\treturn resolve(getPiPackageDir(), \"README.md\");\n}\n\nfunction getDocsPath(): string {\n\treturn resolve(getPiPackageDir(), \"docs\");\n}\n\nfunction getExamplesPath(): string {\n\treturn resolve(getPiPackageDir(), \"examples\");\n}\n\n/** Tool descriptions for system prompt */\nconst toolDescriptions: Record<string, string> = {\n\tread: \"Read file contents\",\n\tbash: \"Execute bash commands (ls, grep, find, etc.)\",\n\tedit: \"Make surgical edits to files (find exact text and replace)\",\n\twrite: \"Create or overwrite files\",\n\tgrep: \"Search file contents for patterns (respects .gitignore)\",\n\tfind: \"Find files by glob pattern (respects .gitignore)\",\n\tls: \"List directory contents\",\n\tlsp: \"Code intelligence via Language Server Protocol (go-to-definition, references, diagnostics, hover, rename, symbols)\",\n};\n\nexport interface BuildSystemPromptOptions {\n\t/** Custom system prompt (replaces default). */\n\tcustomPrompt?: string;\n\t/** Tools to include in prompt. Default: [read, bash, edit, write] */\n\tselectedTools?: string[];\n\t/** Optional one-line tool snippets keyed by tool name. */\n\ttoolSnippets?: Record<string, string>;\n\t/** Additional guideline bullets appended to the default system prompt guidelines. */\n\tpromptGuidelines?: string[];\n\t/** Text to append to system prompt. */\n\tappendSystemPrompt?: string;\n\t/** Working directory. Default: process.cwd() */\n\tcwd?: string;\n\t/** Pre-loaded context files. */\n\tcontextFiles?: Array<{ path: string; content: string }>;\n\t/** Pre-loaded skills. */\n\tskills?: Skill[];\n}\n\n/** Build the system prompt with tools, guidelines, and context */\nexport function buildSystemPrompt(options: BuildSystemPromptOptions = {}): string {\n\tconst {\n\t\tcustomPrompt,\n\t\tselectedTools,\n\t\ttoolSnippets,\n\t\tpromptGuidelines,\n\t\tappendSystemPrompt,\n\t\tcwd,\n\t\tcontextFiles: providedContextFiles,\n\t\tskills: providedSkills,\n\t} = options;\n\tconst resolvedCwd = toPosixPath(cwd ?? process.cwd());\n\n\tconst now = new Date();\n\tconst dateTime = now.toLocaleString(\"en-US\", {\n\t\tweekday: \"long\",\n\t\tyear: \"numeric\",\n\t\tmonth: \"long\",\n\t\tday: \"numeric\",\n\t\thour: \"2-digit\",\n\t\tminute: \"2-digit\",\n\t\tsecond: \"2-digit\",\n\t\ttimeZoneName: \"short\",\n\t});\n\n\tconst appendSection = appendSystemPrompt ? `\\n\\n${appendSystemPrompt}` : \"\";\n\n\tconst contextFiles = providedContextFiles ?? [];\n\tconst skills = providedSkills ?? [];\n\n\tif (customPrompt) {\n\t\tlet prompt = customPrompt;\n\n\t\tif (appendSection) {\n\t\t\tprompt += appendSection;\n\t\t}\n\n\t\t// Append project context files\n\t\tif (contextFiles.length > 0) {\n\t\t\tprompt += \"\\n\\n# Project Context\\n\\n\";\n\t\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\t\tprompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n\t\t\t}\n\t\t}\n\n\t\t// Append skills section (if read or Skill tool is available)\n\t\tconst customPromptHasSkillAccess = !selectedTools || selectedTools.includes(\"read\") || selectedTools.includes(\"Skill\");\n\t\tif (customPromptHasSkillAccess && skills.length > 0) {\n\t\t\tprompt += formatSkillsForPrompt(skills);\n\t\t}\n\n\t\t// Add date/time and working directory last\n\t\tprompt += `\\nCurrent date and time: ${dateTime}`;\n\t\tprompt += `\\nCurrent working directory: ${resolvedCwd}`;\n\n\t\t// Append promptGuidelines from extension-registered tools.\n\t\t// Without this, tools registered via pi.registerTool() with promptGuidelines\n\t\t// have their definitions reach the API but the model has no guidance on when\n\t\t// to use them (#1184).\n\t\tif (promptGuidelines && promptGuidelines.length > 0) {\n\t\t\tprompt += \"\\n\\n\";\n\t\t\tfor (const guideline of promptGuidelines) {\n\t\t\t\tprompt += guideline + \"\\n\";\n\t\t\t}\n\t\t}\n\n\t\treturn prompt;\n\t}\n\n\t// Get absolute paths to documentation and examples\n\tconst readmePath = getReadmePath();\n\tconst docsPath = getDocsPath();\n\tconst examplesPath = getExamplesPath();\n\n\t// Build tools list based on selected tools.\n\t// Built-ins use toolDescriptions. Custom tools can provide one-line snippets.\n\tconst tools = selectedTools || [\"read\", \"bash\", \"edit\", \"write\"];\n\tconst toolsList =\n\t\ttools.length > 0\n\t\t\t? tools\n\t\t\t\t\t.map((name) => {\n\t\t\t\t\t\tconst snippet = toolSnippets?.[name] ?? toolDescriptions[name] ?? name;\n\t\t\t\t\t\treturn `- ${name}: ${snippet}`;\n\t\t\t\t\t})\n\t\t\t\t\t.join(\"\\n\")\n\t\t\t: \"(none)\";\n\n\t// Build guidelines based on which tools are actually available\n\tconst guidelinesList: string[] = [];\n\tconst guidelinesSet = new Set<string>();\n\tconst addGuideline = (guideline: string): void => {\n\t\tif (guidelinesSet.has(guideline)) {\n\t\t\treturn;\n\t\t}\n\t\tguidelinesSet.add(guideline);\n\t\tguidelinesList.push(guideline);\n\t};\n\n\tconst hasBash = tools.includes(\"bash\");\n\tconst hasEdit = tools.includes(\"edit\");\n\tconst hasWrite = tools.includes(\"write\");\n\tconst hasGrep = tools.includes(\"grep\");\n\tconst hasFind = tools.includes(\"find\");\n\tconst hasLs = tools.includes(\"ls\");\n\tconst hasRead = tools.includes(\"read\");\n\tconst hasLsp = tools.includes(\"lsp\");\n\n\t// File exploration guidelines\n\tif (hasBash && !hasGrep && !hasFind && !hasLs) {\n\t\taddGuideline(\"Use bash for file operations like ls, rg, find\");\n\t} else if (hasBash && (hasGrep || hasFind || hasLs)) {\n\t\taddGuideline(\"Prefer grep/find/ls tools over bash for file exploration (faster, respects .gitignore)\");\n\t}\n\n\t// Read before edit guideline\n\tif (hasRead && hasEdit) {\n\t\taddGuideline(\"Use read to examine files before editing. You must use this tool instead of cat or sed.\");\n\t}\n\n\t// Edit guideline\n\tif (hasEdit) {\n\t\taddGuideline(\"Use edit for precise changes (old text must match exactly)\");\n\t}\n\n\t// Write guideline\n\tif (hasWrite) {\n\t\taddGuideline(\"Use write only for new files or complete rewrites\");\n\t}\n\n\t// LSP guideline\n\tif (hasLsp) {\n\t\taddGuideline(\n\t\t\t`Use lsp as the primary tool for code navigation in typed codebases:\n- Navigation: definition, type_definition, implementation, references, incoming_calls, outgoing_calls\n- Understanding: hover (types + docs), signature (parameter info), symbols (file/workspace search)\n- Refactoring: rename (project-wide), code_actions (quick-fixes, imports, refactors), format (formatter)\n- Verification: diagnostics after edits to catch type errors immediately\n- Never grep for a symbol definition when lsp can resolve it semantically\n- Never shell out to a formatter when lsp format is available`,\n\t\t);\n\t}\n\n\t// Output guideline (only when actually writing or executing)\n\tif (hasEdit || hasWrite) {\n\t\taddGuideline(\n\t\t\t\"When summarizing your actions, output plain text directly - do NOT use cat or bash to display what you did\",\n\t\t);\n\t}\n\n\tfor (const guideline of promptGuidelines ?? []) {\n\t\tconst normalized = guideline.trim();\n\t\tif (normalized.length > 0) {\n\t\t\taddGuideline(normalized);\n\t\t}\n\t}\n\n\t// Always include these\n\taddGuideline(\"Be concise in your responses\");\n\taddGuideline(\"Show file paths clearly when working with files\");\n\n\tconst guidelines = guidelinesList.map((g) => `- ${g}`).join(\"\\n\");\n\n\tlet prompt = `You are an expert coding assistant operating inside pi, a coding agent harness. You help users by reading files, executing commands, editing code, and writing new files.\n\nAvailable tools:\n${toolsList}\n\nIn addition to the tools above, you may have access to other custom tools depending on the project.\n\nGuidelines:\n${guidelines}\n\nPi documentation (read only when the user asks about pi itself, its SDK, extensions, themes, skills, or TUI):\n- Main documentation: ${readmePath}\n- Additional docs: ${docsPath}\n- Examples: ${examplesPath} (extensions, custom tools, SDK)\n- When asked about: extensions (docs/extensions.md, examples/extensions/), themes (docs/themes.md), skills (docs/skills.md), prompt templates (docs/prompt-templates.md), TUI components (docs/tui.md), keybindings (docs/keybindings.md), SDK integrations (docs/sdk.md), custom providers (docs/custom-provider.md), adding models (docs/models.md), pi packages (docs/packages.md)\n- When working on pi topics, read the docs and examples, and follow .md cross-references before implementing\n- Always read pi .md files completely and follow links to related docs (e.g., tui.md for TUI API details)`;\n\n\tif (appendSection) {\n\t\tprompt += appendSection;\n\t}\n\n\t// Append project context files\n\tif (contextFiles.length > 0) {\n\t\tprompt += \"\\n\\n# Project Context\\n\\n\";\n\t\tprompt += \"Project-specific instructions and guidelines:\\n\\n\";\n\t\tfor (const { path: filePath, content } of contextFiles) {\n\t\t\tprompt += `## ${filePath}\\n\\n${content}\\n\\n`;\n\t\t}\n\t}\n\n\t// Append skills section (if read or Skill tool is available)\n\tconst hasSkill = tools.includes(\"Skill\");\n\tif ((hasRead || hasSkill) && skills.length > 0) {\n\t\tprompt += formatSkillsForPrompt(skills);\n\t}\n\n\t// Add date/time and working directory last\n\tprompt += `\\nCurrent date and time: ${dateTime}`;\n\tprompt += `\\nCurrent working directory: ${resolvedCwd}`;\n\n\treturn prompt;\n}\n"]}

package/packages/gsd-agent-core/package.json

@@ -0,0 +1,25 @@
+{
+  "name": "@gsd/agent-core",
+  "version": "1.0.0",
+  "description": "GSD session orchestration layer",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "scripts": {
+    "build": "tsc -p tsconfig.json && node scripts/copy-assets.cjs",
+    "copy-assets": "node scripts/copy-assets.cjs"
+  },
+  "dependencies": {
+    "@gsd/agent-types": "*",
+    "@gsd/pi-coding-agent": "*",
+    "@gsd/pi-agent-core": "*",
+    "@gsd/pi-ai": "*",
+    "@gsd/pi-tui": "*"
+  }
+}

package/packages/gsd-agent-core/scripts/copy-assets.cjs

@@ -0,0 +1,43 @@
+#!/usr/bin/env node
+const { mkdirSync, cpSync, copyFileSync, readdirSync } = require('fs');
+const { join } = require('path');
+
+/**
+ * Recursive directory copy using copyFileSync — workaround for cpSync failures
+ * on Windows paths containing non-ASCII characters.
+ */
+function safeCpSync(src, dest, options) {
+  try {
+    cpSync(src, dest, options);
+  } catch {
+    if (options && options.recursive) {
+      copyDirRecursive(src, dest, options && options.filter);
+    } else {
+      copyFileSync(src, dest);
+    }
+  }
+}
+
+function copyDirRecursive(src, dest, filter) {
+  mkdirSync(dest, { recursive: true });
+  for (const entry of readdirSync(src, { withFileTypes: true })) {
+    const srcPath = join(src, entry.name);
+    const destPath = join(dest, entry.name);
+    if (filter && !filter(srcPath)) continue;
+    if (entry.isDirectory()) {
+      copyDirRecursive(srcPath, destPath, filter);
+    } else {
+      copyFileSync(srcPath, destPath);
+    }
+  }
+}
+
+// Export HTML templates and vendor files (moved from pi-coding-agent in CORE-01)
+mkdirSync('dist/export-html/vendor', { recursive: true });
+safeCpSync('src/export-html/template.html', 'dist/export-html/template.html');
+safeCpSync('src/export-html/template.css', 'dist/export-html/template.css');
+safeCpSync('src/export-html/template.js', 'dist/export-html/template.js');
+safeCpSync('src/export-html/vendor', 'dist/export-html/vendor', {
+  recursive: true,
+  filter: (s) => !s.endsWith('.ts'),
+});

package/packages/gsd-agent-core/src/agent-session.test.ts

@@ -0,0 +1,169 @@
+/**
+ * Session-replacement tests for AgentSession (Plan 08-04, D-15).
+ *
+ * These tests verify that event listeners, steering messages, and pending
+ * messages survive session transitions (switch-new, switch-resume, fork)
+ * via the _snapshotState / _restoreState mechanism.
+ *
+ * Direct bracket-notation access to private methods is intentional:
+ * _snapshotState and _restoreState are the core behaviour units, and
+ * testing them directly avoids the heavy dependency graph required to
+ * construct a real AgentSession.
+ */
+
+import assert from "node:assert/strict";
+import { test } from "node:test";
+
+// ---------------------------------------------------------------------------
+// Minimal AgentSession stub
+//
+// Mirrors the private fields and methods that _snapshotState / _restoreState
+// operate on. Only the fields touched by those two helpers are present.
+// ---------------------------------------------------------------------------
+
+/**
+ * Create a minimal stub that exposes the same private fields and methods
+ * as AgentSession for snapshot/restore testing.
+ */
+function makeSessionStub() {
+	const stub = {
+		_eventListeners: [] as Array<(event: unknown) => void>,
+		_steeringMessages: [] as string[],
+		_followUpMessages: [] as string[],
+		_pendingNextTurnMessages: [] as unknown[],
+
+		/** Mirrors AgentSession._snapshotState */
+		_snapshotState(this: typeof stub) {
+			return {
+				listeners: [...this._eventListeners],
+				steering: [...this._steeringMessages],
+				followUp: [...this._followUpMessages],
+				pending: [...this._pendingNextTurnMessages],
+			};
+		},
+
+		/** Mirrors AgentSession._restoreState */
+		_restoreState(
+			this: typeof stub,
+			snapshot: ReturnType<typeof stub._snapshotState>,
+		) {
+			this._eventListeners = snapshot.listeners;
+			this._steeringMessages = snapshot.steering;
+			this._followUpMessages = snapshot.followUp;
+			this._pendingNextTurnMessages = snapshot.pending;
+		},
+	};
+
+	return stub;
+}
+
+// ---------------------------------------------------------------------------
+// Test 1 — switch-new: event listener survives newSession transition
+// ---------------------------------------------------------------------------
+
+test("switch-new: event listener registered before newSession() survives the transition", () => {
+	const session = makeSessionStub();
+
+	// Register a listener BEFORE the transition.
+	const received: unknown[] = [];
+	const listener = (event: unknown) => received.push(event);
+	session._eventListeners.push(listener);
+
+	// Simulate what AgentSession.newSession() does:
+	//   1. snapshot state
+	//   2. perform transition (clears _eventListeners, etc.)
+	//   3. restore state
+	const snapshot = session._snapshotState();
+
+	// Simulate the transition clearing the listener array (as dispose() does).
+	session._eventListeners = [];
+	session._steeringMessages = [];
+	session._followUpMessages = [];
+	session._pendingNextTurnMessages = [];
+
+	// Restore state.
+	session._restoreState(snapshot);
+
+	// Listener must still be present.
+	assert.equal(session._eventListeners.length, 1, "listener array should have 1 entry after restore");
+	assert.equal(session._eventListeners[0], listener, "restored listener must be the same reference");
+
+	// Calling the listener via the restored array works.
+	session._eventListeners[0]({ type: "session_state_changed", reason: "new_session" });
+	assert.equal(received.length, 1, "listener must have received the event");
+});
+
+// ---------------------------------------------------------------------------
+// Test 2 — switch-resume: steering messages survive switchSession transition
+// ---------------------------------------------------------------------------
+
+test("switch-resume: steering messages set before switchSession() survive the transition", () => {
+	const session = makeSessionStub();
+
+	// Set steering messages BEFORE the transition.
+	session._steeringMessages = ["tell me about the weather", "and the stars"];
+
+	// Simulate what AgentSession.switchSession() does:
+	//   1. snapshot state
+	//   2. runtime clears steering/followUp/pending (teardown)
+	//   3. restore state
+	const snapshot = session._snapshotState();
+
+	// Simulate teardown clearing the arrays.
+	session._steeringMessages = [];
+	session._followUpMessages = [];
+	session._pendingNextTurnMessages = [];
+
+	// Restore state.
+	session._restoreState(snapshot);
+
+	// Steering messages must survive.
+	assert.deepEqual(
+		session._steeringMessages,
+		["tell me about the weather", "and the stars"],
+		"steering messages must be preserved after switchSession restore",
+	);
+});
+
+// ---------------------------------------------------------------------------
+// Test 3 — fork: listener + pending messages both survive fork transition
+// ---------------------------------------------------------------------------
+
+test("fork: event listener and pending messages registered before fork() survive the transition", () => {
+	const session = makeSessionStub();
+
+	// Register a listener AND set pending messages BEFORE the transition.
+	const fired: string[] = [];
+	const forkListener = (event: unknown) => fired.push(String((event as { type: string }).type));
+	session._eventListeners.push(forkListener);
+	session._pendingNextTurnMessages.push({ type: "custom", content: "pending context" });
+
+	// Simulate what AgentSession.fork() does:
+	//   1. snapshot state
+	//   2. perform fork (clears pendingNextTurnMessages, dispose clears listeners)
+	//   3. restore state
+	const snapshot = session._snapshotState();
+
+	// Simulate fork teardown.
+	session._eventListeners = [];
+	session._pendingNextTurnMessages = [];
+
+	// Restore state.
+	session._restoreState(snapshot);
+
+	// Listener must survive.
+	assert.equal(session._eventListeners.length, 1, "listener must be present after fork restore");
+	assert.equal(session._eventListeners[0], forkListener, "restored listener must be the same reference");
+
+	// Pending messages must survive.
+	assert.equal(session._pendingNextTurnMessages.length, 1, "pending message must survive fork");
+	assert.deepEqual(
+		session._pendingNextTurnMessages[0],
+		{ type: "custom", content: "pending context" },
+		"pending message content must be intact after fork",
+	);
+
+	// Listener fires correctly after restore.
+	session._eventListeners[0]({ type: "fork" });
+	assert.deepEqual(fired, ["fork"], "listener must fire after fork restore");
+});