Multi-Agent Collaboration for Team and Friends
TypeScript agent-automationagent-orchestrationagent-workflowai-agentsai-collaborationai-memoryai-workforceautonomous-agentsclaude-codeclaude-code-skillscodexcoding-agentmulti-agentmultiple-agentone-person-businessone-person-companyone-person-teamopencodesolopreneur
feat(agent-driver): discover recent contexts (#705)
Gustavo Ye334203eb27c3
diff --git a/src/daemon/agent-driver/README.md b/src/daemon/agent-driver/README.mdindex 76c41c04e..cb0f71dca 100644--- a/src/daemon/agent-driver/README.md+++ b/src/daemon/agent-driver/README.md@@ -55,6 +55,49 @@ await eventsDone;void { result, observedText };```+## Recent context discovery++The SDK can discover bounded global history for Onboard without opening or+resuming an agent session. The two Top-K values are independent, non-negative+safe integers. A zero value skips that collection.++```ts+const recent = await sdk.discoverRecentContext({+ backend: "codex",+ recentSessionFilesTopK: 5,+ recentProjectsTopK: 3,+});++if (!recent.ok) throw new Error(recent.error.message);+// {+// ok: true,+// sessionFiles: {+// capability: "supported",+// items: [{ sessionFilePath, projectPath, modifiedAt }],+// },+// recentProjects: [{ projectPath, modifiedAt }],+// }+```++Discovery covers root sessions across the machine, not only the current+working directory or sessions created by Alook. Results are newest-first;+projects are deduplicated by normalized absolute path and retain the newest+root-session timestamp. No titles, previews, messages, session ids, or vendor+payloads cross the public boundary.++| Backend | Session files | Recent projects | Source |+|---|---|---|---|+| Claude | supported | supported | direct root JSONL scan |+| Codex | supported | supported | read-only rollout-header scan, child threads excluded |+| Cursor | unavailable | supported | ACP `session/list` |+| OpenCode | unavailable | supported | async, adaptively bounded `session list --format json` prefixes |+| Pi | supported | supported | JSONL metadata and first-line header only |++Cursor and OpenCode return `sessionFiles.capability: "unavailable"` with an+empty item list. This is distinct from a supported backend with no saved+sessions. Discovery is read-only: it does not export, materialize, migrate,+repair, resume, or create provider artifacts.+## Built-in execution matrixAll built-ins keep one physical lane for the lifetime of a logical session.@@ -96,6 +139,10 @@ For contract v1:derive completion from output text or a generic idle/exit signal;- report an unavailable required protocol/capability as incompatible orunhealthy. Do not silently fall back to a one-shot runtime.+- optionally implement `discoverRecentContext()` for bounded, global,+ read-only history discovery. All built-in adapters implement it; extension+ adapters that omit it receive `recent_context_discovery_unsupported` from the+ SDK without changing adapter-author contract version 1.Package semver and the numeric adapter-author contract version are independent.Only an incompatible `/adapter-author` change increments the latter.diff --git a/src/daemon/agent-driver/RELEASE_NOTES.md b/src/daemon/agent-driver/RELEASE_NOTES.mdindex 89f46cd5a..808729420 100644--- a/src/daemon/agent-driver/RELEASE_NOTES.md+++ b/src/daemon/agent-driver/RELEASE_NOTES.md@@ -1,5 +1,27 @@# Release notes+## Bounded recent-context discovery++- Added `AgentDriverSdk.discoverRecentContext()` with independent+ `recentSessionFilesTopK` and `recentProjectsTopK` bounds.+- Claude, Codex, and Pi return root session files plus deduplicated projects.+ Cursor and OpenCode explicitly mark per-session files unavailable while still+ returning recent projects.+- Discovery is global across projects and read-only. Public results contain only+ absolute paths and ISO-8601 modification times; provider titles, previews,+ messages, ids, and payloads stay inside adapters.+- Codex reads only rollout headers and filters subagent sources; Claude ignores nested+ subagent JSONL; Pi reads only each candidate's first-line header and excludes+ `parentSession` children instead of calling the body-reading `listAll()` API.++### Compatibility++The consumer SDK gains an additive method and result vocabulary. The optional+adapter-author discovery method does not change numeric contract version 1.+Extension adapters that omit it fail that call with+`recent_context_discovery_unsupported`; their existing probe/open behavior is+unchanged.+## Complete semantic output and payload-free liveness- Replaced public text/reasoning delta events withdiff --git a/src/daemon/agent-driver/src/adapter-author.ts b/src/daemon/agent-driver/src/adapter-author.tsindex 65c557086..2b5f29452 100644--- a/src/daemon/agent-driver/src/adapter-author.ts+++ b/src/daemon/agent-driver/src/adapter-author.ts@@ -15,6 +15,8 @@ export type {TerminalOwnership, WellKnownTransportKind,SpawnedProcess, SpawnedProcessHandle, VendorSessionHandle,} from "./internal/adapter.js";+export { RecentContextCollector, isValidRecentContextTopK } from "./internal/recent-context.js";+export type { RecentContextCandidate } from "./internal/recent-context.js";export type {AgentDriverHost, CreateAgentDriverSdkOptions, DefaultAgentDriverHostOptions,PrepareExecutionInput, PrepareExecutionResult, PreparedExecutionResource, RawOutputEvent,diff --git a/src/daemon/agent-driver/src/adapters/claude/index.ts b/src/daemon/agent-driver/src/adapters/claude/index.tsindex 49d84e2f0..b10244262 100644--- a/src/daemon/agent-driver/src/adapters/claude/index.ts+++ b/src/daemon/agent-driver/src/adapters/claude/index.ts@@ -21,6 +21,7 @@ import { probeClaude, probeCommandVersion, resolveSpawnSpec, resolveClaudeCommanimport { resolveLaunchFieldsOrDefault } from "../../internal/config.js";import { spawnAgentProcess } from "../../internal/killTree.js";import { ClaudeTurnProtocol } from "./turnProtocol.js";+import { discoverClaudeRecentContext } from "./recent-context.js";const CLAUDE_MODEL_CATALOG = {updateMode: "unsupported" as const,@@ -44,6 +45,10 @@ export class ClaudeDriver implements BackendAdapter {private readonly eventNormalizer = new ClaudeEventNormalizer(this.turnProtocol);private pendingInterrupt?: { input: LaneInterruptInput; process: SpawnedProcessHandle };+ discoverRecentContext(request: Parameters<typeof discoverClaudeRecentContext>[0]) {+ return discoverClaudeRecentContext(request);+ }+beginTurn(): string {this.pendingInterrupt = undefined;const receipt = this.turnProtocol.beginTurn();diff --git a/src/daemon/agent-driver/src/adapters/claude/recent-context.test.ts b/src/daemon/agent-driver/src/adapters/claude/recent-context.test.tsnew file mode 100644index 000000000..1ef1adca7--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/claude/recent-context.test.ts@@ -0,0 +1,186 @@+import { mkdirSync, mkdtempSync, readdirSync, rmSync, symlinkSync, utimesSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import path from "node:path";+import { describe, expect, it } from "vitest";+import { discoverClaudeRecentContext, readClaudeProjectPath } from "./recent-context.js";++const projectPath = (...segments: string[]) => path.join(path.parse(process.cwd()).root, "projects", ...segments);++function fsError(code: string): NodeJS.ErrnoException {+ const error = new Error(code) as NodeJS.ErrnoException;+ error.code = code;+ return error;+}++function writeSession(filePath: string, cwd: string, modifiedAt: string): void {+ writeFileSync(filePath, `{\"type\":\"queue-operation\"}\n{\"cwd\":${JSON.stringify(cwd)}}\n`);+ const date = new Date(modifiedAt);+ utimesSync(filePath, date, date);+}++describe("Claude recent-context discovery", () => {+ it("uses CLAUDE_CONFIG_DIR when the projects root is not injected", async () => {+ const configRoot = mkdtempSync(path.join(tmpdir(), "claude-config-root-"));+ const original = process.env.CLAUDE_CONFIG_DIR;+ process.env.CLAUDE_CONFIG_DIR = configRoot;+ try {+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ } finally {+ if (original == null) delete process.env.CLAUDE_CONFIG_DIR;+ else process.env.CLAUDE_CONFIG_DIR = original;+ rmSync(configRoot, { recursive: true, force: true });+ }+ });++ it("treats a missing projects root as empty", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "claude-missing-root-"));+ try {+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { projectsRoot: path.join(parent, "missing") })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("rejects when the projects root cannot be read as a directory", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "claude-invalid-root-"));+ const projectsRoot = path.join(parent, "projects.jsonl");+ writeFileSync(projectsRoot, "not a directory\n");+ try {+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { projectsRoot })).rejects.toBeInstanceOf(Error);+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("distinguishes a vanished session file from another read failure", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "claude-read-error-"));+ try {+ await expect(readClaudeProjectPath(path.join(parent, "missing.jsonl"))).resolves.toBeNull();+ await expect(readClaudeProjectPath(parent)).rejects.toBeInstanceOf(Error);+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("skips a vanished project directory and rejects other nested directory errors", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "claude-nested-errors-"));+ const project = path.join(root, "encoded-project");+ mkdirSync(project);+ const rootEntries = readdirSync(root, { withFileTypes: true });+ try {+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, {+ projectsRoot: root,+ readDirectory: async (directory) => {+ if (directory === root) return rootEntries;+ throw fsError("ENOENT");+ },+ })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, {+ projectsRoot: root,+ readDirectory: async (directory) => {+ if (directory === root) return rootEntries;+ throw fsError("EACCES");+ },+ })).rejects.toMatchObject({ code: "EACCES" });+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("handles candidate stat disappearance without hiding other stat errors", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "claude-stat-errors-"));+ const project = path.join(root, "encoded-project");+ mkdirSync(project);+ writeFileSync(path.join(project, "session.jsonl"), "{}\n");+ const readDirectory = async (directory: string) => readdirSync(directory, { withFileTypes: true });+ try {+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { projectsRoot: root, readDirectory, statPath: async () => { throw fsError("ENOENT"); } }))+ .resolves.toEqual({ sessionFiles: { capability: "supported", items: [] }, recentProjects: [] });+ await expect(discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { projectsRoot: root, readDirectory, statPath: async () => { throw fsError("EIO"); } }))+ .rejects.toMatchObject({ code: "EIO" });+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("scans root JSONL only and applies separate session/project Top-K values", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "claude-discovery-"));+ const projectA = path.join(root, "encoded-a");+ const projectB = path.join(root, "encoded-b");+ mkdirSync(path.join(projectA, "subagents"), { recursive: true });+ mkdirSync(projectB, { recursive: true });+ const sessionA = path.join(projectA, "a.jsonl");+ const sessionB = path.join(projectB, "b.jsonl");+ writeSession(sessionA, projectPath("a"), "2026-01-03T00:00:00Z");+ writeSession(sessionB, projectPath("b"), "2026-01-01T00:00:00Z");+ writeSession(path.join(projectA, "subagents", "child.jsonl"), projectPath("child"), "2026-01-04T00:00:00Z");+ try {+ const result = await discoverClaudeRecentContext({+ recentSessionFilesTopK: 2,+ recentProjectsTopK: 1,+ }, { projectsRoot: root });+ expect(result.sessionFiles.items.map((item) => item.sessionFilePath)).toEqual([sessionA, sessionB]);+ expect(result.recentProjects).toEqual([{+ projectPath: projectPath("a"),+ modifiedAt: "2026-01-03T00:00:00.000Z",+ }]);+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("skips malformed and symlink entries while retaining a deleted project path", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "claude-discovery-invalid-"));+ const project = path.join(root, "encoded-project");+ mkdirSync(project);+ const malformed = path.join(project, "malformed.jsonl");+ const session = path.join(project, "root.jsonl");+ const linked = path.join(project, "linked.jsonl");+ const deletedProject = projectPath("deleted", "project");+ writeFileSync(malformed, "not-json\n");+ const newest = new Date("2026-01-04T00:00:00Z");+ utimesSync(malformed, newest, newest);+ writeSession(session, deletedProject, "2026-01-03T00:00:00Z");+ symlinkSync(session, linked);+ try {+ const result = await discoverClaudeRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { projectsRoot: root });+ expect(result.sessionFiles.items[0]?.sessionFilePath).toBe(session);+ expect(result.recentProjects[0]?.projectPath).toBe(deletedProject);+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });+});diff --git a/src/daemon/agent-driver/src/adapters/claude/recent-context.ts b/src/daemon/agent-driver/src/adapters/claude/recent-context.tsnew file mode 100644index 000000000..d4ff5897d--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/claude/recent-context.ts@@ -0,0 +1,73 @@+import { createReadStream } from "node:fs";+import { homedir } from "node:os";+import path from "node:path";+import { createInterface } from "node:readline";+import type { RecentContextDiscoveryData, RecentContextDiscoveryRequest } from "../../contract.js";+import {+ collectJsonlFileCandidates,+ isMissingPathError,+ type JsonlScanOptions,+ RecentContextCollector,+} from "../../internal/recent-context.js";++interface ClaudeRecentContextDependencies {+ readonly projectsRoot?: string;+ readonly readProjectPath?: (filePath: string) => Promise<string | null>;+ readonly readDirectory?: JsonlScanOptions["readDirectory"];+ readonly statPath?: JsonlScanOptions["statPath"];+}++export async function readClaudeProjectPath(filePath: string): Promise<string | null> {+ const input = createReadStream(filePath);+ const lines = createInterface({ input, crlfDelay: Infinity });+ try {+ for await (const line of lines) {+ let record: unknown;+ try {+ record = JSON.parse(line);+ } catch {+ continue;+ }+ if (!record || typeof record !== "object") continue;+ const cwd = (record as Record<string, unknown>).cwd;+ if (typeof cwd === "string" && path.isAbsolute(cwd)) return cwd;+ }+ return null;+ } catch (error) {+ if (isMissingPathError(error)) return null;+ throw error;+ } finally {+ lines.close();+ input.destroy();+ }+}++export async function discoverClaudeRecentContext(+ request: RecentContextDiscoveryRequest,+ dependencies: ClaudeRecentContextDependencies = {},+): Promise<RecentContextDiscoveryData> {+ const collector = new RecentContextCollector(request, "supported");+ if (collector.satisfied) return collector.result();+ const projectsRoot = path.resolve(dependencies.projectsRoot+ ?? path.join(process.env.CLAUDE_CONFIG_DIR || path.join(homedir(), ".claude"), "projects"));+ const readProjectPath = dependencies.readProjectPath ?? readClaudeProjectPath;+ const candidates = await collectJsonlFileCandidates(projectsRoot, {+ includeRootFiles: false,+ maxDepth: 1,+ readDirectory: dependencies.readDirectory,+ statPath: dependencies.statPath,+ });++ candidates.sort((left, right) => right.modifiedAt.getTime() - left.modifiedAt.getTime());+ for (const candidate of candidates) {+ const projectPath = await readProjectPath(candidate.filePath);+ if (!projectPath) continue;+ collector.add({+ sessionFilePath: candidate.filePath,+ projectPath,+ modifiedAt: candidate.modifiedAt,+ });+ if (collector.satisfied) break;+ }+ return collector.result();+}diff --git a/src/daemon/agent-driver/src/adapters/codex/index.ts b/src/daemon/agent-driver/src/adapters/codex/index.tsindex 318c87c84..9c918eefa 100644--- a/src/daemon/agent-driver/src/adapters/codex/index.ts+++ b/src/daemon/agent-driver/src/adapters/codex/index.ts@@ -36,6 +36,7 @@ import {normalizeRuntimeModelId,RUNTIME_MODEL_CATALOG_MAX,} from "../../internal/modelCatalog.js";+import { discoverCodexRecentContext } from "./recent-context.js";const SETTINGS_UPDATE_TIMEOUT_MS = 5_000;const MODEL_LIST_TIMEOUT_MS = 5_000;@@ -72,6 +73,9 @@ export class CodexDriver implements BackendAdapter {private readonly eventNormalizer = new CodexEventNormalizer();private readonly pendingAccountReadRequestIds = new Set<number>();private requestId = 0;+ discoverRecentContext(request: Parameters<typeof discoverCodexRecentContext>[0]) {+ return discoverCodexRecentContext(request);+ }/** Resolved Codex home root (CODEX_HOME or ~/.codex); set on spawn. */private codexHomeRoot: string | null = null;/**diff --git a/src/daemon/agent-driver/src/adapters/codex/recent-context.test.ts b/src/daemon/agent-driver/src/adapters/codex/recent-context.test.tsnew file mode 100644index 000000000..5e2bf8f82--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/codex/recent-context.test.ts@@ -0,0 +1,153 @@+import { mkdirSync, mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import path from "node:path";+import { describe, expect, it, vi } from "vitest";+import { readFirstLine } from "../../internal/recent-context.js";+import { resolveCodexHomeRootFromEnv } from "./home.js";+import { discoverCodexRecentContext } from "./recent-context.js";++const projectPath = (...segments: string[]) => path.join(path.parse(process.cwd()).root, "projects", ...segments);++function fsError(code: string): NodeJS.ErrnoException {+ const error = new Error(code) as NodeJS.ErrnoException;+ error.code = code;+ return error;+}++function writeRollout(filePath: string, payload: Record<string, unknown>, modifiedAt: string): void {+ writeFileSync(filePath, `${JSON.stringify({ type: "session_meta", payload })}\n{"type":"event_msg","secret":"not-read"}\n`);+ const date = new Date(modifiedAt);+ utimesSync(filePath, date, date);+}++describe("Codex recent-context discovery", () => {+ it("uses the canonical Codex home fallback for an empty CODEX_HOME", () => {+ expect(resolveCodexHomeRootFromEnv(+ { CODEX_HOME: "" },+ { defaultHomeDir: "/users/tester" },+ )).toBe(path.join("/users/tester", ".codex"));+ });++ it("uses CODEX_HOME when the sessions root is not injected", async () => {+ const codexRoot = mkdtempSync(path.join(tmpdir(), "codex-home-root-"));+ const original = process.env.CODEX_HOME;+ process.env.CODEX_HOME = codexRoot;+ try {+ await expect(discoverCodexRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ } finally {+ if (original == null) delete process.env.CODEX_HOME;+ else process.env.CODEX_HOME = original;+ rmSync(codexRoot, { recursive: true, force: true });+ }+ });++ it("treats a missing sessions root as empty", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "codex-missing-root-"));+ try {+ await expect(discoverCodexRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { sessionsRoot: path.join(parent, "missing") })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("rejects when the sessions root cannot be read as a directory", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "codex-invalid-root-"));+ const sessionsRoot = path.join(parent, "sessions.jsonl");+ writeFileSync(sessionsRoot, "not a directory\n");+ try {+ await expect(discoverCodexRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { sessionsRoot })).rejects.toBeInstanceOf(Error);+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("does not hide a candidate stat failure", async () => {+ const sessionsRoot = mkdtempSync(path.join(tmpdir(), "codex-stat-error-"));+ writeFileSync(path.join(sessionsRoot, "session.jsonl"), "{}\n");+ try {+ await expect(discoverCodexRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, {+ sessionsRoot,+ readDirectory: async (directory) => readdirSync(directory, { withFileTypes: true }),+ statPath: async () => { throw fsError("EIO"); },+ })).rejects.toMatchObject({ code: "EIO" });+ } finally {+ rmSync(sessionsRoot, { recursive: true, force: true });+ }+ });++ it("scans rollouts newest-first, excludes subagents, and stops at both bounds", async () => {+ const sessionsRoot = mkdtempSync(path.join(tmpdir(), "codex-discovery-"));+ const day = path.join(sessionsRoot, "2026", "01", "03");+ mkdirSync(day, { recursive: true });+ const malformed = path.join(day, "malformed.jsonl");+ const child = path.join(day, "child.jsonl");+ const newestRoot = path.join(day, "root-new.jsonl");+ const oldRoot = path.join(day, "root-old.jsonl");+ const oldestRoot = path.join(day, "root-oldest.jsonl");+ writeFileSync(malformed, "not-json\n");+ const malformedDate = new Date("2026-01-05T00:00:00Z");+ utimesSync(malformed, malformedDate, malformedDate);+ writeRollout(child, { cwd: projectPath("child"), source: { subagent: "review" } }, "2026-01-04T00:00:00Z");+ writeRollout(newestRoot, { cwd: projectPath("a"), source: "vscode" }, "2026-01-03T00:00:00Z");+ writeRollout(oldRoot, { cwd: projectPath("b"), source: "cli" }, "2026-01-01T00:00:00Z");+ writeRollout(oldestRoot, { cwd: projectPath("c"), source: "cli" }, "2025-12-31T00:00:00Z");+ const reads: string[] = [];+ const readHeader = vi.fn(async (filePath: string) => {+ reads.push(filePath);+ return readFirstLine(filePath);+ });+ try {+ const result = await discoverCodexRecentContext({+ recentSessionFilesTopK: 2,+ recentProjectsTopK: 1,+ }, { sessionsRoot, readHeader });+ expect(result.sessionFiles.items.map((item) => item.sessionFilePath)).toEqual([newestRoot, oldRoot]);+ expect(result.recentProjects).toEqual([{+ projectPath: projectPath("a"),+ modifiedAt: "2026-01-03T00:00:00.000Z",+ }]);+ expect(reads).toEqual([malformed, child, newestRoot, oldRoot]);+ expect(reads).not.toContain(oldestRoot);+ } finally {+ rmSync(sessionsRoot, { recursive: true, force: true });+ }+ });++ it("recognizes current and compatibility child markers", async () => {+ const sessionsRoot = mkdtempSync(path.join(tmpdir(), "codex-child-markers-"));+ const current = path.join(sessionsRoot, "current.jsonl");+ const compatibility = path.join(sessionsRoot, "compatibility.jsonl");+ const root = path.join(sessionsRoot, "root.jsonl");+ writeRollout(current, { cwd: projectPath("child-a"), source: { subAgent: "review" } }, "2026-01-04T00:00:00Z");+ writeRollout(compatibility, { cwd: projectPath("child-b"), parent_thread_id: "parent" }, "2026-01-03T00:00:00Z");+ writeRollout(root, { cwd: projectPath("root"), source: "cli" }, "2026-01-02T00:00:00Z");+ try {+ const result = await discoverCodexRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { sessionsRoot });+ expect(result.sessionFiles.items[0]?.sessionFilePath).toBe(root);+ expect(result.recentProjects[0]?.projectPath).toBe(projectPath("root"));+ } finally {+ rmSync(sessionsRoot, { recursive: true, force: true });+ }+ });+});diff --git a/src/daemon/agent-driver/src/adapters/codex/recent-context.ts b/src/daemon/agent-driver/src/adapters/codex/recent-context.tsnew file mode 100644index 000000000..be9d456ce--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/codex/recent-context.ts@@ -0,0 +1,57 @@+import path from "node:path";+import type { RecentContextDiscoveryData, RecentContextDiscoveryRequest } from "../../contract.js";+import {+ collectJsonlFileCandidates,+ type JsonlScanOptions,+ readFirstLine,+ RecentContextCollector,+} from "../../internal/recent-context.js";+import { asRecord, tryParseJsonRecord } from "../../internal/utils.js";+import { resolveCodexHomeRootFromEnv } from "./home.js";++interface CodexRecentContextDependencies {+ readonly sessionsRoot?: string;+ readonly readHeader?: (filePath: string) => Promise<string | null>;+ readonly readDirectory?: JsonlScanOptions["readDirectory"];+ readonly statPath?: JsonlScanOptions["statPath"];+}++function isChildSession(payload: Record<string, unknown>): boolean {+ if (payload.parentThreadId != null || payload.parent_thread_id != null) return true;+ const source = payload.source;+ if (typeof source === "string") return source.toLowerCase().startsWith("subagent");+ const sourceRecord = asRecord(source);+ return sourceRecord != null && ("subagent" in sourceRecord || "subAgent" in sourceRecord);+}++export async function discoverCodexRecentContext(+ request: RecentContextDiscoveryRequest,+ dependencies: CodexRecentContextDependencies = {},+): Promise<RecentContextDiscoveryData> {+ const collector = new RecentContextCollector(request, "supported");+ if (collector.satisfied) return collector.result();+ const sessionsRoot = path.resolve(dependencies.sessionsRoot+ ?? path.join(resolveCodexHomeRootFromEnv(), "sessions"));+ const readHeader = dependencies.readHeader ?? readFirstLine;+ const candidates = await collectJsonlFileCandidates(sessionsRoot, {+ readDirectory: dependencies.readDirectory,+ statPath: dependencies.statPath,+ });+ candidates.sort((left, right) => right.modifiedAt.getTime() - left.modifiedAt.getTime());++ for (const candidate of candidates) {+ const line = await readHeader(candidate.filePath);+ if (!line) continue;+ const header = tryParseJsonRecord(line);+ if (!header) continue;+ const payload = asRecord(header.payload);+ if (header.type !== "session_meta" || !payload || isChildSession(payload)) continue;+ collector.add({+ sessionFilePath: candidate.filePath,+ projectPath: payload.cwd,+ modifiedAt: candidate.modifiedAt,+ });+ if (collector.satisfied) break;+ }+ return collector.result();+}diff --git a/src/daemon/agent-driver/src/adapters/cursor/index.ts b/src/daemon/agent-driver/src/adapters/cursor/index.tsindex bc4279617..6c5d5b80c 100644--- a/src/daemon/agent-driver/src/adapters/cursor/index.ts+++ b/src/daemon/agent-driver/src/adapters/cursor/index.ts@@ -24,6 +24,7 @@ import {import { CursorAcpLane, type CursorAcpProcessFactory } from "./acp-lane.js";import { probeCursorAcpCatalog } from "./catalog-probe.js";import type { RuntimeReasoningCatalog } from "../../contract.js";+import { discoverCursorRecentContext } from "./recent-context.js";export class CursorDriver implements BackendAdapter, CursorAcpProcessFactory {readonly id = "cursor";@@ -35,6 +36,10 @@ export class CursorDriver implements BackendAdapter, CursorAcpProcessFactory {terminalOwnership: "transport_request",} as const;+ discoverRecentContext(request: Parameters<typeof discoverCursorRecentContext>[0]) {+ return discoverCursorRecentContext(request);+ }+constructor(private readonly catalogProbe: (command?: string) => Promise<RuntimeReasoningCatalog | undefined> = probeCursorAcpCatalog,) {}diff --git a/src/daemon/agent-driver/src/adapters/cursor/recent-context.test.ts b/src/daemon/agent-driver/src/adapters/cursor/recent-context.test.tsnew file mode 100644index 000000000..f6825b242--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/cursor/recent-context.test.ts@@ -0,0 +1,376 @@+import { EventEmitter } from "node:events";+import { PassThrough } from "node:stream";+import { beforeEach, describe, expect, it, vi } from "vitest";+import type { SpawnedProcessHandle } from "../../internal/adapter.js";+import { discoverCursorRecentContext } from "./recent-context.js";+import path from "node:path";++const projectPath = (...segments: string[]) => path.join(path.parse(process.cwd()).root, "projects", ...segments);+const killTreeMocks = vi.hoisted(() => ({ killProcessTree: vi.fn(async () => {}) }));++vi.mock("../../internal/killTree.js", async () => {+ const actual = await vi.importActual<typeof import("../../internal/killTree.js")>("../../internal/killTree.js");+ return { ...actual, killProcessTree: killTreeMocks.killProcessTree };+});++type RpcRequest = { id: number; method: string; params: Record<string, unknown> };++function fakeRpcProcess(+ onRequest: (request: RpcRequest, respond: (result: unknown) => void) => void,+ writeResponse: (stdout: PassThrough, payload: Buffer) => void = (stdout, payload) => { stdout.write(payload); },+) {+ const stdout = new PassThrough();+ const stderr = new PassThrough();+ const stdin = new PassThrough();+ const requests: RpcRequest[] = [];+ let buffer = "";+ const process = Object.assign(new EventEmitter(), {+ stdout,+ stderr,+ stdin,+ pid: undefined,+ exitCode: null,+ signalCode: null,+ kill: vi.fn(() => true),+ }) as unknown as SpawnedProcessHandle;+ stdin.on("data", (chunk) => {+ buffer += chunk.toString();+ const lines = buffer.split("\n");+ buffer = lines.pop() ?? "";+ for (const line of lines) {+ if (!line.trim()) continue;+ const request = JSON.parse(line) as RpcRequest;+ requests.push(request);+ onRequest(request, (result) => queueMicrotask(() => {+ writeResponse(stdout, Buffer.from(`${JSON.stringify({ jsonrpc: "2.0", id: request.id, result })}\n`));+ }));+ }+ });+ return { process, requests };+}++describe("Cursor recent-context discovery", () => {+ beforeEach(() => killTreeMocks.killProcessTree.mockClear());++ it("decodes string and Uint8Array stdout chunks", async () => {+ let responseIndex = 0;+ const expectedProjectPath = projectPath("mixed-chunks");+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({ sessions: [{ cwd: expectedProjectPath, updatedAt: "2026-01-01T00:00:00Z" }] });+ }, (stdout, payload) => {+ responseIndex += 1;+ if (responseIndex === 1) stdout.emit("data", payload.toString("utf8"));+ else if (responseIndex === 2) stdout.emit("data", new Uint8Array(payload));+ else stdout.write(payload);+ });++ const result = await discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup: async () => {} });+ expect(result.recentProjects[0]?.projectPath).toBe(expectedProjectPath);+ });++ it("preserves a UTF-8 project path split across stdout chunks", async () => {+ const unicodeProjectPath = projectPath("中文-🚀");+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({ sessions: [{ cwd: unicodeProjectPath, updatedAt: "2026-01-01T00:00:00Z" }] });+ }, (stdout, payload) => {+ const marker = Buffer.from("中");+ const markerAt = payload.indexOf(marker);+ if (markerAt < 0) {+ stdout.write(payload);+ return;+ }+ stdout.write(payload.subarray(0, markerAt + 1));+ stdout.write(payload.subarray(markerAt + 1));+ });++ const result = await discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup: async () => {} });+ expect(result.recentProjects[0]?.projectPath).toBe(unicodeProjectPath);+ });++ it("accepts the compatibility data field from session/list", async () => {+ const expectedProjectPath = projectPath("compatibility-data");+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({ data: [{ cwd: expectedProjectPath, updatedAt: "2026-01-01T00:00:00Z" }] });+ });++ const result = await discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup: async () => {} });+ expect(result.recentProjects[0]?.projectPath).toBe(expectedProjectPath);+ });++ it("treats a session/list result without an array as empty", async () => {+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({});+ });++ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup: async () => {} })).resolves.toEqual({+ sessionFiles: { capability: "unavailable", items: [] },+ recentProjects: [],+ });+ });++ it("authenticates, paginates, and returns deduplicated projects with unavailable files", async () => {+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: {} } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ if (request.params.cursor === "next") {+ return respond({+ sessions: [{ sessionId: "b", cwd: projectPath("b"), updatedAt: "2026-01-01T00:00:00Z" }],+ });+ }+ return respond({+ sessions: [+ { sessionId: "relative", cwd: "relative", updatedAt: "2026-01-05T00:00:00Z" },+ { sessionId: "invalid-time", cwd: projectPath("invalid"), updatedAt: "not-a-time" },+ { sessionId: "a1", cwd: projectPath("a"), updatedAt: "2026-01-03T00:00:00Z" },+ { sessionId: "a2", cwd: projectPath("a"), updatedAt: "2026-01-02T00:00:00Z" },+ ],+ nextCursor: "next",+ });+ });+ const cleanup = vi.fn(async () => {});+ const result = await discoverCursorRecentContext({+ recentSessionFilesTopK: 9,+ recentProjectsTopK: 2,+ }, { spawn: () => rpc.process, cleanup });++ expect(result.sessionFiles).toEqual({ capability: "unavailable", items: [] });+ expect(result.recentProjects.map((item) => item.projectPath)).toEqual([projectPath("a"), projectPath("b")]);+ expect(rpc.requests.map((request) => request.method)).toEqual([+ "initialize", "authenticate", "session/list", "session/list",+ ]);+ expect(cleanup).toHaveBeenCalledOnce();+ });++ it("rejects a successful listing when process cleanup fails", async () => {+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({ sessions: [] });+ });+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, {+ spawn: () => rpc.process,+ cleanup: async () => { throw new Error("private cleanup detail"); },+ })).rejects.toThrow("Cursor discovery cleanup failed");+ });++ it("uses complete default cleanup for pid and pid-less processes", async () => {+ const respondWithEmptyList = (request: RpcRequest, respond: (result: unknown) => void) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({ sessions: [] });+ };+ const withPid = fakeRpcProcess(respondWithEmptyList);+ (withPid.process as { pid?: number }).pid = 4242;+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => withPid.process })).resolves.toMatchObject({ recentProjects: [] });+ expect(killTreeMocks.killProcessTree).toHaveBeenCalledWith(4242, { graceMs: 250 });++ const withoutPid = fakeRpcProcess(respondWithEmptyList);+ (withoutPid.process.kill as ReturnType<typeof vi.fn>).mockReturnValue(false);+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => withoutPid.process })).rejects.toThrow("cleanup failed");+ });++ it("fails closed for unavailable transport, write failure, session listing, and authentication", async () => {+ const unavailable = fakeRpcProcess(() => {});+ (unavailable.process as { stdin: null }).stdin = null;+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => unavailable.process, cleanup: async () => {} }))+ .rejects.toThrow("transport is unavailable");++ const writeFailure = fakeRpcProcess(() => {});+ (writeFailure.process.stdin as unknown as { write: () => never }).write = () => { throw new Error("EPIPE"); };+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => writeFailure.process, cleanup: async () => {} }))+ .rejects.toThrow("transport write failed");++ const noListing = fakeRpcProcess((_request, respond) => respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: {} },+ authMethods: [{ id: "cursor_login" }],+ }));+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => noListing.process, cleanup: async () => {} }))+ .rejects.toThrow("session listing is unavailable");++ const noAuthentication = fakeRpcProcess((_request, respond) => respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [],+ }));+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => noAuthentication.process, cleanup: async () => {} }))+ .rejects.toThrow("authentication is unavailable");+ });++ it("flushes a final response without a newline", async () => {+ const expectedProjectPath = projectPath("flushed");+ const rpc = fakeRpcProcess((request, respond) => {+ if (request.method === "initialize") {+ return respond({+ protocolVersion: 1,+ agentCapabilities: { sessionCapabilities: { list: true } },+ authMethods: [{ id: "cursor_login" }],+ });+ }+ if (request.method === "authenticate") return respond({});+ return respond({ sessions: [{ cwd: expectedProjectPath, updatedAt: "2026-01-01T00:00:00Z" }] });+ }, (stdout, payload) => {+ if (!payload.includes(Buffer.from(expectedProjectPath))) {+ stdout.write(payload);+ return;+ }+ stdout.end(payload.subarray(0, -1));+ });+ const result = await discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup: async () => {} });+ expect(result.recentProjects[0]?.projectPath).toBe(expectedProjectPath);+ });++ it("turns stdin stream errors into a discovery failure", async () => {+ const rpc = fakeRpcProcess(() => {});+ const discovery = discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup: async () => {} });+ (rpc.process.stdin as unknown as { emit(event: string, error: Error): boolean })+ .emit("error", new Error("private EPIPE detail"));+ await expect(discovery).rejects.toThrow("Cursor discovery transport failed");++ const exited = fakeRpcProcess(() => {});+ const exitedDiscovery = discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => exited.process, cleanup: async () => {} });+ (exited.process as unknown as EventEmitter).emit("exit", 1, null);+ await expect(exitedDiscovery).rejects.toThrow("process exited early");+ });++ it("rejects an incompatible ACP protocol after cleanup", async () => {+ const rpc = fakeRpcProcess((_request, respond) => respond({ protocolVersion: 2 }));+ const cleanup = vi.fn(async () => {});+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => rpc.process, cleanup })).rejects.toThrow("protocol is incompatible");+ expect(cleanup).toHaveBeenCalledOnce();+ });++ it("does not spawn when the project bound is zero", async () => {+ const spawn = vi.fn();+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 5,+ recentProjectsTopK: 0,+ }, { spawn })).resolves.toEqual({+ sessionFiles: { capability: "unavailable", items: [] },+ recentProjects: [],+ });+ expect(spawn).not.toHaveBeenCalled();+ });++ it("enforces timeout and output bounds", async () => {+ const pending = fakeRpcProcess(() => {});+ await expect(discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => pending.process, cleanup: async () => {}, timeoutMs: 5 }))+ .rejects.toThrow("timed out");++ const noisy = fakeRpcProcess(() => {});+ const bounded = discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => noisy.process, cleanup: async () => {}, outputMaxBytes: 1 });+ (noisy.process.stdout as unknown as { emit(event: string, chunk: Buffer): boolean })+ .emit("data", Buffer.from("too much"));+ await expect(bounded).rejects.toThrow("output exceeded its bound");++ const noisyStderr = fakeRpcProcess(() => {});+ const stderrBounded = discoverCursorRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => noisyStderr.process, cleanup: async () => {}, outputMaxBytes: 1 });+ (noisyStderr.process.stderr as unknown as { emit(event: string, chunk: Buffer): boolean })+ .emit("data", Buffer.from("too much"));+ await expect(stderrBounded).rejects.toThrow("output exceeded its bound");+ });+});diff --git a/src/daemon/agent-driver/src/adapters/cursor/recent-context.ts b/src/daemon/agent-driver/src/adapters/cursor/recent-context.tsnew file mode 100644index 000000000..789e20b26--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/cursor/recent-context.ts@@ -0,0 +1,123 @@+import type { RecentContextDiscoveryData, RecentContextDiscoveryRequest } from "../../contract.js";+import {+ type DiscoveryProcessControl,+ type DiscoveryProcessDependencies,+ runBoundedDiscoveryProcess,+} from "../../internal/discovery-process.js";+import { spawnAgentProcess } from "../../internal/killTree.js";+import { resolveSpawnSpec } from "../../internal/probe.js";+import { RecentContextCollector } from "../../internal/recent-context.js";+import { asRecord, jsonRpcRequest, tryParseJsonLine } from "../../internal/utils.js";++const ACP_PROTOCOL_VERSION = 1;+const AUTH_METHOD_ID = "cursor_login";+const CURSOR_DISCOVERY_TIMEOUT_MS = 30_000;+const CURSOR_DISCOVERY_OUTPUT_MAX_BYTES = 4 * 1024 * 1024;++type CursorRecentContextDependencies = DiscoveryProcessDependencies;++export async function discoverCursorRecentContext(+ request: RecentContextDiscoveryRequest,+ dependencies: CursorRecentContextDependencies = {},+): Promise<RecentContextDiscoveryData> {+ const collector = new RecentContextCollector(request, "unavailable");+ if (collector.satisfied) return collector.result();+ const spec = resolveSpawnSpec("cursor-agent", ["acp"], request.command);+ const processHandle = (dependencies.spawn ?? spawnAgentProcess)(spec.command, spec.args, {+ cwd: dependencies.cwd ?? process.cwd(),+ env: { ...process.env, CI: "1" },+ shell: spec.shell,+ });++ let buffer = "";+ let requestId = 0;+ let expectedId = 0;+ let expectedMethod = "";+ const seenCursors = new Set<string>();+ const requestRpc = (+ method: string,+ params: Record<string, unknown>,+ control: DiscoveryProcessControl<RecentContextDiscoveryData>,+ ) => {+ expectedId = ++requestId;+ expectedMethod = method;+ control.write(`${jsonRpcRequest(method, params, expectedId)}\n`);+ };+ const requestPage = (control: DiscoveryProcessControl<RecentContextDiscoveryData>, cursor?: string) =>+ requestRpc("session/list", cursor ? { cursor } : {}, control);+ const onLine = (line: string, control: DiscoveryProcessControl<RecentContextDiscoveryData>) => {+ const message = asRecord(tryParseJsonLine(line));+ if (!message || message.id !== expectedId) return;+ if (message.error !== undefined) return control.fail("Cursor discovery request failed");+ const result = asRecord(message.result);+ if (!result) return control.fail("Cursor discovery returned an invalid response");+ if (expectedMethod === "initialize") {+ if (result.protocolVersion !== ACP_PROTOCOL_VERSION) {+ return control.fail("Cursor discovery protocol is incompatible");+ }+ const capabilities = asRecord(result.agentCapabilities);+ const sessionCapabilities = asRecord(capabilities?.sessionCapabilities);+ if (sessionCapabilities?.list !== true && !asRecord(sessionCapabilities?.list)) {+ return control.fail("Cursor session listing is unavailable");+ }+ const authMethods = Array.isArray(result.authMethods) ? result.authMethods : [];+ if (!authMethods.some((method) => asRecord(method)?.id === AUTH_METHOD_ID)) {+ return control.fail("Cursor discovery authentication is unavailable");+ }+ requestRpc("authenticate", { methodId: AUTH_METHOD_ID }, control);+ return;+ }+ if (expectedMethod === "authenticate") {+ requestPage(control);+ return;+ }+ if (expectedMethod !== "session/list") return control.fail("Cursor discovery state is invalid");+ const sessions = Array.isArray(result.sessions)+ ? result.sessions+ : Array.isArray(result.data)+ ? result.data+ : [];+ for (const value of sessions) {+ const session = asRecord(value);+ if (!session) continue;+ collector.add({ projectPath: session.cwd, modifiedAt: session.updatedAt });+ if (collector.satisfied) return control.finish(collector.result());+ }+ const nextCursor = typeof result.nextCursor === "string" && result.nextCursor+ ? result.nextCursor+ : undefined;+ if (!nextCursor) return control.finish(collector.result());+ if (seenCursors.has(nextCursor)) return control.fail("Cursor discovery cursor repeated");+ seenCursors.add(nextCursor);+ requestPage(control, nextCursor);+ };++ return runBoundedDiscoveryProcess({+ process: processHandle,+ label: "Cursor",+ timeoutMs: dependencies.timeoutMs ?? CURSOR_DISCOVERY_TIMEOUT_MS,+ outputMaxBytes: dependencies.outputMaxBytes ?? CURSOR_DISCOVERY_OUTPUT_MAX_BYTES,+ cleanup: dependencies.cleanup,+ exitEvent: "exit",+ onStdout: (text, final, control) => {+ buffer += text;+ const lines = buffer.split("\n");+ buffer = lines.pop() ?? "";+ for (const line of lines) if (line.trim()) onLine(line, control);+ if (final && buffer.trim()) {+ const line = buffer;+ buffer = "";+ onLine(line, control);+ }+ },+ onExit: (_code, _signal, control) => control.fail("Cursor discovery process exited early"),+ onStart: (control) => requestRpc("initialize", {+ protocolVersion: ACP_PROTOCOL_VERSION,+ clientCapabilities: {+ fs: { readTextFile: false, writeTextFile: false },+ terminal: false,+ },+ clientInfo: { name: "alook-agent-driver-discovery", version: "0.1.31" },+ }, control),+ });+}diff --git a/src/daemon/agent-driver/src/adapters/opencode/index.ts b/src/daemon/agent-driver/src/adapters/opencode/index.tsindex b9b310429..e938a268e 100644--- a/src/daemon/agent-driver/src/adapters/opencode/index.ts+++ b/src/daemon/agent-driver/src/adapters/opencode/index.ts@@ -27,6 +27,7 @@ import {OpenCodeServiceLane,type OpenCodeServiceProcessFactory,} from "./service-lane.js";+import { discoverOpenCodeRecentContext } from "./recent-context.js";function createOpenCodeMessageId(): string {return `msg_${randomBytes(16).toString("hex")}`;@@ -46,6 +47,10 @@ export class OpenCodeDriver implements BackendAdapter, OpenCodeServiceProcessFacprivate readonly outputProbe: (command: string, args: string[]) => CommandOutputProbeResult = probeCommandOutput,) {}+ discoverRecentContext(request: Parameters<typeof discoverOpenCodeRecentContext>[0]) {+ return discoverOpenCodeRecentContext(request);+ }+probe(command?: string) {const result = probeCliRuntime("opencode", {}, command);if (result.status !== "healthy") return result;diff --git a/src/daemon/agent-driver/src/adapters/opencode/recent-context.test.ts b/src/daemon/agent-driver/src/adapters/opencode/recent-context.test.tsnew file mode 100644index 000000000..d064eb8ce--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/opencode/recent-context.test.ts@@ -0,0 +1,221 @@+import { EventEmitter } from "node:events";+import { PassThrough } from "node:stream";+import { beforeEach, describe, expect, it, vi } from "vitest";+import type { SpawnedProcessHandle } from "../../internal/adapter.js";+import { discoverOpenCodeRecentContext } from "./recent-context.js";+import path from "node:path";++const projectPath = (...segments: string[]) => path.join(path.parse(process.cwd()).root, "projects", ...segments);+const killTreeMocks = vi.hoisted(() => ({ killProcessTree: vi.fn(async () => {}) }));++vi.mock("../../internal/killTree.js", async () => {+ const actual = await vi.importActual<typeof import("../../internal/killTree.js")>("../../internal/killTree.js");+ return { ...actual, killProcessTree: killTreeMocks.killProcessTree };+});++function fakeCommandProcess(output?: string | readonly Buffer[], delayMs = 0): SpawnedProcessHandle {+ const stdout = new PassThrough();+ const stderr = new PassThrough();+ const process = Object.assign(new EventEmitter(), {+ stdout,+ stderr,+ stdin: null,+ pid: undefined,+ exitCode: null as number | null,+ signalCode: null,+ kill: vi.fn(() => true),+ }) as unknown as SpawnedProcessHandle;+ if (output !== undefined) {+ setTimeout(() => {+ const chunks = typeof output === "string" ? [output] : output;+ for (const chunk of chunks) stdout.write(chunk);+ (process as { exitCode: number | null }).exitCode = 0;+ (process as unknown as EventEmitter).emit("close", 0, null);+ }, delayMs);+ }+ return process;+}++describe("OpenCode recent-context discovery", () => {+ beforeEach(() => killTreeMocks.killProcessTree.mockClear());++ it("decodes string and Uint8Array stdout chunks and flushes stream end", async () => {+ const expectedProjectPath = projectPath("mixed-chunks");+ const payload = JSON.stringify([{+ directory: expectedProjectPath,+ updated: Date.parse("2026-01-01T00:00:00Z"),+ }]);+ const process = fakeCommandProcess();+ setTimeout(() => {+ const stdout = process.stdout as unknown as EventEmitter;+ stdout.emit("data", payload.slice(0, 1));+ stdout.emit("data", new Uint8Array(Buffer.from(payload.slice(1))));+ stdout.emit("end");+ (process as unknown as EventEmitter).emit("close", 0, null);+ }, 0);+ const result = await discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => process, cleanup: async () => {} });+ expect(result.recentProjects[0]?.projectPath).toBe(expectedProjectPath);+ });++ it("preserves a UTF-8 project path split across stdout chunks", async () => {+ const unicodeProjectPath = projectPath("中文-🚀");+ const payload = Buffer.from(JSON.stringify([+ { directory: unicodeProjectPath, updated: Date.parse("2026-01-01T00:00:00Z") },+ ]));+ const markerAt = payload.indexOf(Buffer.from("中"));+ expect(markerAt).toBeGreaterThanOrEqual(0);+ const result = await discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, {+ spawn: () => fakeCommandProcess([+ payload.subarray(0, markerAt + 1),+ payload.subarray(markerAt + 1),+ ]),+ cleanup: async () => {},+ });+ expect(result.recentProjects[0]?.projectPath).toBe(unicodeProjectPath);+ });++ it("uses an async bounded global list and returns deduplicated projects only", async () => {+ const spawn = vi.fn((_command: string, _args: string[]) => fakeCommandProcess(JSON.stringify([+ { id: "one", directory: projectPath("a"), updated: Date.parse("2026-01-03T00:00:00Z") },+ { id: "two", directory: projectPath("a"), updated: Date.parse("2026-01-02T00:00:00Z") },+ { id: "three", directory: projectPath("b"), updated: Date.parse("2026-01-01T00:00:00Z") },+ ])));+ const cleanup = vi.fn(async () => {});+ const result = await discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 9,+ recentProjectsTopK: 2,+ command: "/bin/opencode-test",+ }, { spawn, cleanup });+ expect(spawn).toHaveBeenCalledWith("/bin/opencode-test", [+ "session", "list", "--format", "json", "--max-count", "20", "--pure",+ ], expect.objectContaining({ stdin: "ignore" }));+ expect(result.sessionFiles).toEqual({ capability: "unavailable", items: [] });+ expect(result.recentProjects).toEqual([+ { projectPath: projectPath("a"), modifiedAt: "2026-01-03T00:00:00.000Z" },+ { projectPath: projectPath("b"), modifiedAt: "2026-01-01T00:00:00.000Z" },+ ]);+ expect(cleanup).toHaveBeenCalledOnce();+ });++ it("fails closed on invalid JSON", async () => {+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => fakeCommandProcess("not-json"), cleanup: async () => {} }))+ .rejects.toThrow("invalid JSON");+ });++ it("fails closed on a non-array response", async () => {+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => fakeCommandProcess("{}"), cleanup: async () => {} }))+ .rejects.toThrow("invalid response");+ });++ it("expands the bounded prefix when more than 10K recent sessions share one project", async () => {+ const sessions = [+ ...Array.from({ length: 21 }, (_, index) => ({+ id: `a-${index}`,+ directory: projectPath("a"),+ updated: Date.parse("2026-01-03T00:00:00Z") - index,+ })),+ { id: "b", directory: projectPath("b"), updated: Date.parse("2026-01-01T00:00:00Z") },+ ];+ const requestedPrefixes: number[] = [];+ const spawn = vi.fn((_command: string, args: string[]) => {+ const maxCount = Number(args[args.indexOf("--max-count") + 1]);+ requestedPrefixes.push(maxCount);+ return fakeCommandProcess(JSON.stringify(sessions.slice(0, maxCount)));+ });++ const result = await discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 2,+ }, { spawn, cleanup: async () => {} });+ expect(requestedPrefixes).toEqual([20, 40]);+ expect(result.recentProjects.map((item) => item.projectPath)).toEqual([projectPath("a"), projectPath("b")]);+ });++ it("keeps the event loop live while a listing is pending", async () => {+ let timerAdvanced = false;+ const discovery = discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, {+ spawn: () => fakeCommandProcess(JSON.stringify([+ { directory: projectPath("a"), updated: Date.parse("2026-01-01T00:00:00Z") },+ ]), 10),+ cleanup: async () => {},+ });+ setTimeout(() => { timerAdvanced = true; }, 0);+ await discovery;+ expect(timerAdvanced).toBe(true);+ });++ it("times out a pending process and still cleans it up", async () => {+ const cleanup = vi.fn(async () => {});+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => fakeCommandProcess(), cleanup, timeoutMs: 5 }))+ .rejects.toThrow("timed out");+ expect(cleanup).toHaveBeenCalledOnce();+ });++ it("rejects successful output when cleanup fails", async () => {+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, {+ spawn: () => fakeCommandProcess(JSON.stringify([])),+ cleanup: async () => { throw new Error("private cleanup detail"); },+ })).rejects.toThrow("OpenCode discovery cleanup failed");+ });++ it("uses complete default cleanup for pid and pid-less processes", async () => {+ const withPid = fakeCommandProcess("[]");+ (withPid as { pid?: number }).pid = 4242;+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => withPid })).resolves.toMatchObject({ recentProjects: [] });+ expect(killTreeMocks.killProcessTree).toHaveBeenCalledWith(4242, { graceMs: 250 });++ const withoutPid = fakeCommandProcess();+ (withoutPid.kill as ReturnType<typeof vi.fn>).mockReturnValue(false);+ setTimeout(() => {+ (withoutPid.stdout as PassThrough).write("[]");+ (withoutPid as unknown as EventEmitter).emit("close", 0, null);+ }, 0);+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => withoutPid })).rejects.toThrow("cleanup failed");+ });++ it("bounds combined process output", async () => {+ await expect(discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, {+ spawn: () => fakeCommandProcess("[]"),+ cleanup: async () => {},+ outputMaxBytes: 1,+ })).rejects.toThrow("output exceeded its bound");++ const noisyStderr = fakeCommandProcess();+ const bounded = discoverOpenCodeRecentContext({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, { spawn: () => noisyStderr, cleanup: async () => {}, outputMaxBytes: 1 });+ (noisyStderr.stderr as unknown as EventEmitter).emit("data", Buffer.from("too much"));+ await expect(bounded).rejects.toThrow("output exceeded its bound");+ });+});diff --git a/src/daemon/agent-driver/src/adapters/opencode/recent-context.ts b/src/daemon/agent-driver/src/adapters/opencode/recent-context.tsnew file mode 100644index 000000000..2bde01be7--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/opencode/recent-context.ts@@ -0,0 +1,99 @@+import type { RecentContextDiscoveryData, RecentContextDiscoveryRequest } from "../../contract.js";+import {+ type DiscoveryProcessDependencies,+ runBoundedDiscoveryProcess,+} from "../../internal/discovery-process.js";+import { spawnAgentProcess } from "../../internal/killTree.js";+import { resolveSpawnSpec } from "../../internal/probe.js";+import { RecentContextCollector } from "../../internal/recent-context.js";+import { asRecord } from "../../internal/utils.js";++const OPENCODE_DISCOVERY_TIMEOUT_MS = 15_000;+const OPENCODE_DISCOVERY_OUTPUT_MAX_BYTES = 4 * 1024 * 1024;++type OpenCodeRecentContextDependencies = DiscoveryProcessDependencies;++interface CommandOutput {+ readonly output: string;+ readonly outputBytes: number;+}++function collectCommandOutput(+ command: string,+ args: string[],+ shell: boolean,+ dependencies: OpenCodeRecentContextDependencies,+ timeoutMs: number,+ outputMaxBytes: number,+): Promise<CommandOutput> {+ const processHandle = (dependencies.spawn ?? spawnAgentProcess)(command, args, {+ cwd: dependencies.cwd ?? process.cwd(),+ env: { ...process.env, CI: "1" },+ shell,+ stdin: "ignore",+ });++ let output = "";+ return runBoundedDiscoveryProcess({+ process: processHandle,+ label: "OpenCode",+ timeoutMs,+ outputMaxBytes,+ cleanup: dependencies.cleanup,+ exitEvent: "close",+ onStdout: (text) => { output += text; },+ onExit: (code, _signal, control) => {+ if (code !== 0) return control.fail("OpenCode session listing failed");+ control.flushStdout();+ control.finish({ output, outputBytes: control.outputBytes });+ },+ });+}++export async function discoverOpenCodeRecentContext(+ request: RecentContextDiscoveryRequest,+ dependencies: OpenCodeRecentContextDependencies = {},+): Promise<RecentContextDiscoveryData> {+ const collector = new RecentContextCollector(request, "unavailable");+ if (collector.satisfied) return collector.result();+ const startedAt = Date.now();+ const timeoutMs = dependencies.timeoutMs ?? OPENCODE_DISCOVERY_TIMEOUT_MS;+ let remainingOutputBytes = dependencies.outputMaxBytes ?? OPENCODE_DISCOVERY_OUTPUT_MAX_BYTES;+ let maxCount = Math.max(1, Math.min(Number.MAX_SAFE_INTEGER, request.recentProjectsTopK * 10));+ while (!collector.satisfied) {+ const remainingTimeoutMs = timeoutMs - (Date.now() - startedAt);+ if (remainingTimeoutMs <= 0) throw new Error("OpenCode discovery timed out");+ const spec = resolveSpawnSpec(+ "opencode",+ ["session", "list", "--format", "json", "--max-count", String(maxCount), "--pure"],+ request.command,+ );+ const commandOutput = await collectCommandOutput(+ spec.command,+ spec.args,+ spec.shell,+ dependencies,+ remainingTimeoutMs,+ remainingOutputBytes,+ );+ remainingOutputBytes -= commandOutput.outputBytes;+ let parsed: unknown;+ try {+ parsed = JSON.parse(commandOutput.output);+ } catch {+ throw new Error("OpenCode session listing returned invalid JSON");+ }+ if (!Array.isArray(parsed)) throw new Error("OpenCode session listing returned an invalid response");+ for (const value of parsed) {+ const session = asRecord(value);+ if (!session) continue;+ const modifiedAt = session.updated ?? session.updatedAt;+ collector.add({ projectPath: session.directory, modifiedAt });+ }+ if (collector.satisfied || parsed.length < maxCount) break;+ const nextMaxCount = Math.min(Number.MAX_SAFE_INTEGER, maxCount * 2);+ if (nextMaxCount === maxCount) throw new Error("OpenCode session listing could not prove the requested Top-K");+ maxCount = nextMaxCount;+ }+ return collector.result();+}diff --git a/src/daemon/agent-driver/src/adapters/pi/index.ts b/src/daemon/agent-driver/src/adapters/pi/index.tsindex 5fc1d4c2b..11276fec0 100644--- a/src/daemon/agent-driver/src/adapters/pi/index.ts+++ b/src/daemon/agent-driver/src/adapters/pi/index.ts@@ -17,6 +17,7 @@ import {type PiSdkLoader,type PiSessionDependencies,} from "./sessionDeps.js";+import { discoverPiRecentContext } from "./recent-context.js";const PI_SDK_PACKAGE_NAME = "@earendil-works/pi-coding-agent";const PI_MODEL_PROBE_TIMEOUT_MS = 5_000;@@ -260,6 +261,10 @@ export class PiDriver implements BackendAdapter {private sessionId: string | null = null;private terminalSequence = 0;+ discoverRecentContext(request: Parameters<typeof discoverPiRecentContext>[0]) {+ return discoverPiRecentContext(request);+ }+constructor(private readonly dependenciesFor: (ctx: AdapterLaunchContext) => PiSessionDependencies = createPiSessionDependencies,private readonly loadSdk: PiSdkLoader = loadPiSdkModule,diff --git a/src/daemon/agent-driver/src/adapters/pi/recent-context.test.ts b/src/daemon/agent-driver/src/adapters/pi/recent-context.test.tsnew file mode 100644index 000000000..224984713--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/pi/recent-context.test.ts@@ -0,0 +1,207 @@+import { mkdirSync, mkdtempSync, readdirSync, rmSync, utimesSync, writeFileSync } from "node:fs";+import { homedir, tmpdir } from "node:os";+import path from "node:path";+import { describe, expect, it, vi } from "vitest";+import { readFirstLine } from "../../internal/recent-context.js";+import { discoverPiRecentContext } from "./recent-context.js";++const projectPath = (...segments: string[]) => path.join(path.parse(process.cwd()).root, "projects", ...segments);++function fsError(code: string): NodeJS.ErrnoException {+ const error = new Error(code) as NodeJS.ErrnoException;+ error.code = code;+ return error;+}++function writeSession(filePath: string, header: Record<string, unknown>, modifiedAt: string): void {+ writeFileSync(filePath, `${JSON.stringify(header)}\n{\"type\":\"message\",\"secret\":\"not-read\"}\n`);+ const date = new Date(modifiedAt);+ utimesSync(filePath, date, date);+}++describe("Pi recent-context discovery", () => {+ it("uses PI_CODING_AGENT_DIR when the sessions root is not injected", async () => {+ const piRoot = mkdtempSync(path.join(tmpdir(), "pi-agent-root-"));+ const originalAgentRoot = process.env.PI_CODING_AGENT_DIR;+ const originalSessionRoot = process.env.PI_CODING_AGENT_SESSION_DIR;+ process.env.PI_CODING_AGENT_DIR = piRoot;+ delete process.env.PI_CODING_AGENT_SESSION_DIR;+ try {+ await expect(discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ } finally {+ if (originalAgentRoot == null) delete process.env.PI_CODING_AGENT_DIR;+ else process.env.PI_CODING_AGENT_DIR = originalAgentRoot;+ if (originalSessionRoot == null) delete process.env.PI_CODING_AGENT_SESSION_DIR;+ else process.env.PI_CODING_AGENT_SESSION_DIR = originalSessionRoot;+ rmSync(piRoot, { recursive: true, force: true });+ }+ });++ it("treats a missing sessions root as empty", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "pi-missing-root-"));+ try {+ await expect(discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { sessionsRoot: path.join(parent, "missing") })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("rejects when the sessions root cannot be read as a directory", async () => {+ const parent = mkdtempSync(path.join(tmpdir(), "pi-invalid-root-"));+ const sessionsRoot = path.join(parent, "sessions.jsonl");+ writeFileSync(sessionsRoot, "not a directory\n");+ try {+ await expect(discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, { sessionsRoot })).rejects.toBeInstanceOf(Error);+ } finally {+ rmSync(parent, { recursive: true, force: true });+ }+ });++ it("skips a vanished project directory and rejects other nested directory errors", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "pi-nested-errors-"));+ const project = path.join(root, "encoded-project");+ mkdirSync(project);+ const rootEntries = readdirSync(root, { withFileTypes: true });+ try {+ await expect(discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, {+ sessionsRoot: root,+ readDirectory: async (directory) => {+ if (directory === root) return rootEntries;+ throw fsError("ENOENT");+ },+ })).resolves.toEqual({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [],+ });+ await expect(discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, {+ sessionsRoot: root,+ readDirectory: async (directory) => {+ if (directory === root) return rootEntries;+ throw fsError("EACCES");+ },+ })).rejects.toMatchObject({ code: "EACCES" });+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("does not hide a candidate stat failure", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "pi-stat-error-"));+ const project = path.join(root, "encoded-project");+ mkdirSync(project);+ writeFileSync(path.join(project, "session.jsonl"), "{}\n");+ try {+ await expect(discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ }, {+ sessionsRoot: root,+ readDirectory: async (directory) => readdirSync(directory, { withFileTypes: true }),+ statPath: async () => { throw fsError("EIO"); },+ })).rejects.toMatchObject({ code: "EIO" });+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("reads headers newest-first, skips children, and stops once both bounds are filled", async () => {+ const root = mkdtempSync(path.join(tmpdir(), "pi-discovery-"));+ const project = path.join(root, "encoded-project");+ mkdirSync(project);+ const malformed = path.join(project, "malformed.jsonl");+ const child = path.join(project, "child.jsonl");+ const newestRoot = path.join(project, "root-new.jsonl");+ const oldRoot = path.join(project, "root-old.jsonl");+ writeFileSync(malformed, "not-json\n");+ const malformedDate = new Date("2026-01-05T00:00:00Z");+ utimesSync(malformed, malformedDate, malformedDate);+ writeSession(child, { type: "session", cwd: projectPath("child"), parentSession: "parent.jsonl" }, "2026-01-04T00:00:00Z");+ writeSession(newestRoot, { type: "session", cwd: projectPath("a") }, "2026-01-03T00:00:00Z");+ writeSession(oldRoot, { type: "session", cwd: projectPath("b") }, "2026-01-01T00:00:00Z");+ const reads: string[] = [];+ const readHeader = vi.fn(async (filePath: string) => {+ reads.push(filePath);+ return readFirstLine(filePath);+ });+ try {+ const result = await discoverPiRecentContext({+ recentSessionFilesTopK: 2,+ recentProjectsTopK: 1,+ }, { sessionsRoot: root, readHeader });+ expect(result.sessionFiles.items.map((item) => item.sessionFilePath)).toEqual([newestRoot, oldRoot]);+ expect(result.recentProjects).toHaveLength(1);+ expect(reads).toEqual([malformed, child, newestRoot, oldRoot]);+ } finally {+ rmSync(root, { recursive: true, force: true });+ }+ });++ it("treats PI_CODING_AGENT_SESSION_DIR as a direct session directory", async () => {+ const directory = mkdtempSync(path.join(tmpdir(), "pi-custom-session-dir-"));+ const child = path.join(directory, "child.jsonl");+ const root = path.join(directory, "root.jsonl");+ writeSession(child, { type: "session", cwd: projectPath("child"), parentSession: "parent.jsonl" }, "2026-01-04T00:00:00Z");+ writeSession(root, { type: "session", cwd: projectPath("root") }, "2026-01-03T00:00:00Z");+ const original = process.env.PI_CODING_AGENT_SESSION_DIR;+ process.env.PI_CODING_AGENT_SESSION_DIR = directory;+ try {+ const result = await discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ });+ expect(result.sessionFiles.items).toEqual([{+ sessionFilePath: root,+ projectPath: projectPath("root"),+ modifiedAt: "2026-01-03T00:00:00.000Z",+ }]);+ expect(result.recentProjects).toEqual([{+ projectPath: projectPath("root"),+ modifiedAt: "2026-01-03T00:00:00.000Z",+ }]);+ } finally {+ if (original == null) delete process.env.PI_CODING_AGENT_SESSION_DIR;+ else process.env.PI_CODING_AGENT_SESSION_DIR = original;+ rmSync(directory, { recursive: true, force: true });+ }+ });++ it("expands a tilde in PI_CODING_AGENT_SESSION_DIR", async () => {+ const directory = mkdtempSync(path.join(homedir(), ".pi-custom-session-dir-"));+ const root = path.join(directory, "root.jsonl");+ writeSession(root, { type: "session", cwd: projectPath("root") }, "2026-01-03T00:00:00Z");+ const original = process.env.PI_CODING_AGENT_SESSION_DIR;+ process.env.PI_CODING_AGENT_SESSION_DIR = `~/${path.basename(directory)}`;+ try {+ const result = await discoverPiRecentContext({+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ });+ expect(result.sessionFiles.items[0]?.sessionFilePath).toBe(root);+ } finally {+ if (original == null) delete process.env.PI_CODING_AGENT_SESSION_DIR;+ else process.env.PI_CODING_AGENT_SESSION_DIR = original;+ rmSync(directory, { recursive: true, force: true });+ }+ });+});diff --git a/src/daemon/agent-driver/src/adapters/pi/recent-context.ts b/src/daemon/agent-driver/src/adapters/pi/recent-context.tsnew file mode 100644index 000000000..b5a161627--- /dev/null+++ b/src/daemon/agent-driver/src/adapters/pi/recent-context.ts@@ -0,0 +1,59 @@+import { homedir } from "node:os";+import path from "node:path";+import type { RecentContextDiscoveryData, RecentContextDiscoveryRequest } from "../../contract.js";+import {+ collectJsonlFileCandidates,+ type JsonlScanOptions,+ readFirstLine,+ RecentContextCollector,+} from "../../internal/recent-context.js";+import { tryParseJsonRecord } from "../../internal/utils.js";++interface PiRecentContextDependencies {+ readonly sessionsRoot?: string;+ readonly readHeader?: (filePath: string) => Promise<string | null>;+ readonly readDirectory?: JsonlScanOptions["readDirectory"];+ readonly statPath?: JsonlScanOptions["statPath"];+}++function expandTildePath(value: string): string {+ if (value === "~") return homedir();+ if (value.startsWith("~/")) return path.join(homedir(), value.slice(2));+ return value;+}++export async function discoverPiRecentContext(+ request: RecentContextDiscoveryRequest,+ dependencies: PiRecentContextDependencies = {},+): Promise<RecentContextDiscoveryData> {+ const collector = new RecentContextCollector(request, "supported");+ if (collector.satisfied) return collector.result();+ const customSessionDirectory = process.env.PI_CODING_AGENT_SESSION_DIR;+ const sessionsRoot = path.resolve(expandTildePath(dependencies.sessionsRoot+ ?? customSessionDirectory+ ?? path.join(process.env.PI_CODING_AGENT_DIR || path.join(homedir(), ".pi", "agent"), "sessions")));+ const scanDirectSessions = dependencies.sessionsRoot == null && customSessionDirectory != null;+ const readHeader = dependencies.readHeader ?? readFirstLine;+ const candidates = await collectJsonlFileCandidates(sessionsRoot, {+ includeRootFiles: scanDirectSessions,+ maxDepth: 1,+ readDirectory: dependencies.readDirectory,+ statPath: dependencies.statPath,+ });++ candidates.sort((left, right) => right.modifiedAt.getTime() - left.modifiedAt.getTime());+ for (const candidate of candidates) {+ const line = await readHeader(candidate.filePath);+ if (!line) continue;+ const header = tryParseJsonRecord(line);+ if (!header) continue;+ if (header.type !== "session" || header.parentSession != null) continue;+ collector.add({+ sessionFilePath: candidate.filePath,+ projectPath: header.cwd,+ modifiedAt: candidate.modifiedAt,+ });+ if (collector.satisfied) break;+ }+ return collector.result();+}diff --git a/src/daemon/agent-driver/src/contract.ts b/src/daemon/agent-driver/src/contract.tsindex 98a3cea76..9464a4d13 100644--- a/src/daemon/agent-driver/src/contract.ts+++ b/src/daemon/agent-driver/src/contract.ts@@ -555,6 +555,44 @@ export interface ProbeInput<Specs, Id extends BackendId<Specs>> {readonly command?: string;}+export interface DiscoveredSessionFile {+ readonly sessionFilePath: string;+ readonly projectPath: string;+ readonly modifiedAt: string;+}++export interface DiscoveredProject {+ readonly projectPath: string;+ readonly modifiedAt: string;+}++export const SESSION_FILE_DISCOVERY_CAPABILITIES = ["supported", "unavailable"] as const;++export type SessionFileDiscoveryCapability = (typeof SESSION_FILE_DISCOVERY_CAPABILITIES)[number];++export interface RecentContextDiscoveryRequest {+ readonly recentSessionFilesTopK: number;+ readonly recentProjectsTopK: number;+ readonly command?: string;+}++export interface RecentContextDiscoveryInput<Specs, Id extends BackendId<Specs>>+ extends RecentContextDiscoveryRequest {+ readonly backend: Id;+}++export interface RecentContextDiscoveryData {+ readonly sessionFiles: {+ readonly capability: SessionFileDiscoveryCapability;+ readonly items: readonly DiscoveredSessionFile[];+ };+ readonly recentProjects: readonly DiscoveredProject[];+}++export type RecentContextDiscoveryResult =+ | ({ readonly ok: true } & RecentContextDiscoveryData)+ | { readonly ok: false; readonly error: AgentDriverError };+export type BackendProbe<Capabilities> =| {readonly status: "healthy";@@ -580,6 +618,9 @@ export interface AgentDriverSdk<Specs = BuiltinBackendSpecs> {probe<Id extends BackendId<Specs>>(input: ProbeInput<Specs, Id>,): Promise<BackendProbe<CapabilitiesOf<Specs, Id>>>;+ discoverRecentContext<Id extends BackendId<Specs>>(+ input: RecentContextDiscoveryInput<Specs, Id>,+ ): Promise<RecentContextDiscoveryResult>;open<Id extends BackendId<Specs>>(input: OpenSessionInput<Specs, Id>,): Promise<OpenSessionResult<Specs, Id>>;diff --git a/src/daemon/agent-driver/src/controller/logical-session.test.ts b/src/daemon/agent-driver/src/controller/logical-session.test.tsindex c61fb3b6e..7ac35857e 100644--- a/src/daemon/agent-driver/src/controller/logical-session.test.ts+++ b/src/daemon/agent-driver/src/controller/logical-session.test.ts@@ -69,6 +69,9 @@ class FakeDriver implements BackendAdapter {constructor(readonly id: BuiltinBackendId, readonly execution: BackendExecution) {}probe() { return { status: "healthy" as const }; }+ async discoverRecentContext() {+ return { sessionFiles: { capability: "unavailable" as const, items: [] }, recentProjects: [] };+ }async openLane(ctx: AdapterLaunchContext, options?: RuntimeLaneOpenOptions): Promise<RuntimeLane> {if (this.laneOverride) return this.laneOverride;if (this.execution.transport.kind === "in_process_sdk") return this.createSdkLane(ctx);diff --git a/src/daemon/agent-driver/src/internal/adapter.ts b/src/daemon/agent-driver/src/internal/adapter.tsindex 5d0366e78..0856fd71f 100644--- a/src/daemon/agent-driver/src/internal/adapter.ts+++ b/src/daemon/agent-driver/src/internal/adapter.ts@@ -10,6 +10,8 @@ import type {RuntimeReasoningCatalog,RuntimeSettingsUpdate,RuntimeSettingsUpdateResult,+ RecentContextDiscoveryData,+ RecentContextDiscoveryRequest,} from "../contract.js";import type { ProviderQuotaObservation, TokenUsageDelta } from "../contract.js";@@ -205,6 +207,7 @@ export interface BackendAdapter<Id extends string = BuiltinBackendId, Config = B| { readonly kind: "workspace_file"; readonly canonical: string; readonly aliases: readonly string[] };readonly execution: BackendExecution;probe(command?: string): ProbeResult | Promise<ProbeResult>;+ discoverRecentContext?(input: RecentContextDiscoveryRequest): Promise<RecentContextDiscoveryData>;openLane(ctx: AdapterLaunchContext<Id, Config>,options?: RuntimeLaneOpenOptions,diff --git a/src/daemon/agent-driver/src/internal/discovery-process.ts b/src/daemon/agent-driver/src/internal/discovery-process.tsnew file mode 100644index 000000000..e4fc21567--- /dev/null+++ b/src/daemon/agent-driver/src/internal/discovery-process.ts@@ -0,0 +1,114 @@+import { StringDecoder } from "node:string_decoder";+import type { SpawnedProcessHandle } from "./adapter.js";+import { killProcessTree } from "./killTree.js";++export type DiscoverySpawn = (+ command: string,+ args: string[],+ options: { cwd: string; env: NodeJS.ProcessEnv; shell: boolean; stdin?: "ignore" },+) => SpawnedProcessHandle;++export interface DiscoveryProcessDependencies {+ readonly spawn?: DiscoverySpawn;+ readonly cleanup?: (process: SpawnedProcessHandle) => Promise<void>;+ readonly timeoutMs?: number;+ readonly outputMaxBytes?: number;+ readonly cwd?: string;+}++export interface DiscoveryProcessControl<Result> {+ readonly outputBytes: number;+ finish(result: Result): void;+ fail(message: string): void;+ flushStdout(): void;+ write(line: string): void;+}++interface DiscoveryProcessOptions<Result> {+ readonly process: SpawnedProcessHandle;+ readonly label: string;+ readonly timeoutMs: number;+ readonly outputMaxBytes: number;+ readonly cleanup?: DiscoveryProcessDependencies["cleanup"];+ readonly exitEvent: "exit" | "close";+ readonly onStdout: (text: string, final: boolean, control: DiscoveryProcessControl<Result>) => void;+ readonly onExit: (code: number | null, signal: string | null, control: DiscoveryProcessControl<Result>) => void;+ readonly onStart?: (control: DiscoveryProcessControl<Result>) => void;+}++function toBuffer(chunk: unknown): Buffer {+ if (Buffer.isBuffer(chunk)) return chunk;+ if (chunk instanceof Uint8Array) return Buffer.from(chunk.buffer, chunk.byteOffset, chunk.byteLength);+ return Buffer.from(String(chunk));+}++async function cleanupProcess(process: SpawnedProcessHandle, label: string): Promise<void> {+ if (process.pid) await killProcessTree(process.pid, { graceMs: 250 });+ else if (process.exitCode === null && process.signalCode === null && !process.kill("SIGTERM")) {+ throw new Error(`${label} discovery cleanup failed`);+ }+}++function onStream(stream: unknown, event: "error" | "end", listener: () => void): void {+ (stream as { on?: (event: string, listener: () => void) => unknown } | undefined)?.on?.(event, listener);+}++export function runBoundedDiscoveryProcess<Result>(options: DiscoveryProcessOptions<Result>): Promise<Result> {+ return new Promise((resolve, reject) => {+ const decoder = new StringDecoder("utf8");+ let settled = false;+ let decoderEnded = false;+ let outputBytes = 0;+ const settle = (result?: Result, error?: Error) => {+ if (settled) return;+ settled = true;+ clearTimeout(timer);+ if (!decoderEnded) decoder.end();+ void Promise.resolve().then(+ () => options.cleanup?.(options.process) ?? cleanupProcess(options.process, options.label),+ ).then(+ () => error ? reject(error) : resolve(result as Result),+ () => reject(error ?? new Error(`${options.label} discovery cleanup failed`)),+ );+ };+ const control: DiscoveryProcessControl<Result> = {+ get outputBytes() { return outputBytes; },+ finish: (result) => settle(result),+ fail: (message) => settle(undefined, new Error(message)),+ flushStdout: () => {+ if (settled || decoderEnded) return;+ decoderEnded = true;+ options.onStdout(decoder.end(), true, control);+ },+ write: (line) => {+ const stdin = options.process.stdin;+ if (!stdin || stdin.destroyed || stdin.writableEnded || stdin.writable === false) {+ return control.fail(`${options.label} discovery transport is unavailable`);+ }+ try { stdin.write(line); } catch { control.fail(`${options.label} discovery transport write failed`); }+ },+ };+ const addBytes = (chunk: unknown, decode: boolean) => {+ if (settled) return;+ const bytes = toBuffer(chunk);+ outputBytes += bytes.byteLength;+ if (outputBytes > options.outputMaxBytes) {+ control.fail(`${options.label} discovery output exceeded its bound`);+ } else if (decode) options.onStdout(decoder.write(bytes), false, control);+ };+ const timer = setTimeout(+ () => control.fail(`${options.label} discovery timed out`),+ Math.max(1, options.timeoutMs),+ );+ timer.unref?.();+ options.process.stdout?.on("data", (chunk) => addBytes(chunk, true));+ options.process.stderr?.on("data", (chunk) => addBytes(chunk, false));+ onStream(options.process.stdout, "end", control.flushStdout);+ for (const stream of [options.process.stdin, options.process.stdout, options.process.stderr]) {+ onStream(stream, "error", () => control.fail(`${options.label} discovery transport failed`));+ }+ options.process.on("error", () => control.fail(`${options.label} discovery process failed`));+ options.process.on(options.exitEvent, (code, signal) => options.onExit(code, signal, control));+ options.onStart?.(control);+ });+}diff --git a/src/daemon/agent-driver/src/internal/recent-context.test.ts b/src/daemon/agent-driver/src/internal/recent-context.test.tsnew file mode 100644index 000000000..540dbe33d--- /dev/null+++ b/src/daemon/agent-driver/src/internal/recent-context.test.ts@@ -0,0 +1,164 @@+import { mkdtempSync, rmSync, writeFileSync } from "node:fs";+import { tmpdir } from "node:os";+import path from "node:path";+import { describe, expect, it } from "vitest";+import {+ isValidRecentContextTopK,+ readFirstLine,+ RecentContextCollector,+ sanitizeRecentContextData,+} from "./recent-context.js";++const absolutePath = (...segments: string[]) => path.join(path.parse(process.cwd()).root, ...segments);++describe("recent context normalization", () => {+ it("validates bounded counts without coercion", () => {+ expect(isValidRecentContextTopK(0)).toBe(true);+ expect(isValidRecentContextTopK(3)).toBe(true);+ for (const value of [-1, 1.5, Number.NaN, Number.POSITIVE_INFINITY, Number.MAX_SAFE_INTEGER + 1]) {+ expect(isValidRecentContextTopK(value)).toBe(false);+ }+ });++ it("applies independent limits and deduplicates projects at their newest time", () => {+ const sessionOne = absolutePath("sessions", "one");+ const sessionTwo = absolutePath("sessions", "two");+ const projectA = absolutePath("projects", "a");+ const collector = new RecentContextCollector({+ recentSessionFilesTopK: 2,+ recentProjectsTopK: 1,+ }, "supported");+ collector.add({ sessionFilePath: sessionOne, projectPath: projectA, modifiedAt: "2026-01-02T00:00:00Z" });+ collector.add({ sessionFilePath: sessionTwo, projectPath: projectA, modifiedAt: "2026-01-01T00:00:00Z" });+ collector.add({ sessionFilePath: "relative", projectPath: absolutePath("projects", "b"), modifiedAt: "invalid" });++ expect(collector.satisfied).toBe(true);+ expect(collector.result()).toEqual({+ sessionFiles: {+ capability: "supported",+ items: [+ { sessionFilePath: sessionOne, projectPath: projectA, modifiedAt: "2026-01-02T00:00:00.000Z" },+ { sessionFilePath: sessionTwo, projectPath: projectA, modifiedAt: "2026-01-01T00:00:00.000Z" },+ ],+ },+ recentProjects: [+ { projectPath: projectA, modifiedAt: "2026-01-02T00:00:00.000Z" },+ ],+ });+ });++ it("normalizes numeric timestamps", () => {+ const project = absolutePath("projects", "numeric-time");+ const collector = new RecentContextCollector({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, "supported");+ collector.add({ projectPath: project, modifiedAt: Date.parse("2026-01-02T00:00:00Z") });++ expect(collector.result().recentProjects).toEqual([{+ projectPath: project,+ modifiedAt: "2026-01-02T00:00:00.000Z",+ }]);+ });++ it("ignores timestamps with unsupported value types", () => {+ const collector = new RecentContextCollector({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ }, "supported");+ collector.add({+ projectPath: absolutePath("projects", "invalid-time-type"),+ modifiedAt: true,+ });++ expect(collector.result().recentProjects).toEqual([]);+ });++ it("reads only the first JSONL line", async () => {+ const directory = mkdtempSync(path.join(tmpdir(), "recent-context-line-"));+ const filePath = path.join(directory, "session.jsonl");+ try {+ writeFileSync(filePath, "{\"type\":\"session\"}\nthis line must not be parsed\n");+ await expect(readFirstLine(filePath)).resolves.toBe("{\"type\":\"session\"}");+ } finally {+ rmSync(directory, { recursive: true, force: true });+ }+ });++ it("treats a concurrently missing file as absent and propagates other read errors", async () => {+ const directory = mkdtempSync(path.join(tmpdir(), "recent-context-read-errors-"));+ try {+ await expect(readFirstLine(path.join(directory, "missing.jsonl"))).resolves.toBeNull();+ await expect(readFirstLine(directory)).rejects.toBeInstanceOf(Error);+ } finally {+ rmSync(directory, { recursive: true, force: true });+ }+ });++ it("strips adapter-only fields and reapplies both public bounds", () => {+ const sessionOne = absolutePath("sessions", "one");+ const sessionTwo = absolutePath("sessions", "two");+ const projectOne = absolutePath("projects", "one");+ const projectTwo = absolutePath("projects", "two");+ const sanitized = sanitizeRecentContextData({+ secret: "drop",+ sessionFiles: {+ capability: "supported",+ items: [+ { sessionFilePath: sessionOne, projectPath: projectOne, modifiedAt: "2026-01-02", preview: "drop" },+ { sessionFilePath: sessionTwo, projectPath: projectTwo, modifiedAt: "2026-01-01" },+ ],+ },+ recentProjects: [+ { projectPath: projectOne, modifiedAt: "2026-01-02", title: "drop" },+ { projectPath: projectTwo, modifiedAt: "2026-01-01" },+ ],+ }, { recentSessionFilesTopK: 1, recentProjectsTopK: 1 });+ expect(sanitized).toEqual({+ sessionFiles: {+ capability: "supported",+ items: [{ sessionFilePath: sessionOne, projectPath: projectOne, modifiedAt: "2026-01-02T00:00:00.000Z" }],+ },+ recentProjects: [{ projectPath: projectOne, modifiedAt: "2026-01-02T00:00:00.000Z" }],+ });+ });++ it("takes the true newest items from an unordered extension adapter result", () => {+ const oldSession = absolutePath("sessions", "old");+ const newSession = absolutePath("sessions", "new");+ const oldProject = absolutePath("projects", "old");+ const newProject = absolutePath("projects", "new");+ const sanitized = sanitizeRecentContextData({+ sessionFiles: {+ capability: "supported",+ items: [+ { sessionFilePath: oldSession, projectPath: oldProject, modifiedAt: "2026-01-01" },+ { sessionFilePath: newSession, projectPath: newProject, modifiedAt: "2026-01-03" },+ ],+ },+ recentProjects: [+ { projectPath: oldProject, modifiedAt: "2026-01-01" },+ { projectPath: newProject, modifiedAt: "2026-01-03" },+ { projectPath: newProject, modifiedAt: "2026-01-02" },+ ],+ }, { recentSessionFilesTopK: 1, recentProjectsTopK: 1 });+ expect(sanitized).toEqual({+ sessionFiles: {+ capability: "supported",+ items: [{ sessionFilePath: newSession, projectPath: newProject, modifiedAt: "2026-01-03T00:00:00.000Z" }],+ },+ recentProjects: [{ projectPath: newProject, modifiedAt: "2026-01-03T00:00:00.000Z" }],+ });+ });++ it("rejects malformed session-file containers", () => {+ expect(sanitizeRecentContextData({+ sessionFiles: null,+ recentProjects: [],+ }, { recentSessionFilesTopK: 1, recentProjectsTopK: 1 })).toBeNull();+ expect(sanitizeRecentContextData({+ sessionFiles: { capability: "invalid", items: [] },+ recentProjects: [],+ }, { recentSessionFilesTopK: 1, recentProjectsTopK: 1 })).toBeNull();+ });+});diff --git a/src/daemon/agent-driver/src/internal/recent-context.ts b/src/daemon/agent-driver/src/internal/recent-context.tsnew file mode 100644index 000000000..145d7749b--- /dev/null+++ b/src/daemon/agent-driver/src/internal/recent-context.ts@@ -0,0 +1,227 @@+import path from "node:path";+import { createReadStream, type Dirent } from "node:fs";+import { readdir, stat } from "node:fs/promises";+import type {+ RecentContextDiscoveryData,+ RecentContextDiscoveryRequest,+ SessionFileDiscoveryCapability,+} from "../contract.js";++export interface RecentContextCandidate {+ readonly projectPath: unknown;+ readonly modifiedAt: unknown;+ readonly sessionFilePath?: unknown;+}++interface JsonlFileCandidate {+ readonly filePath: string;+ readonly modifiedAt: Date;+}++export interface JsonlScanOptions {+ readonly includeRootFiles?: boolean;+ readonly maxDepth?: number;+ readonly readDirectory?: (directory: string) => Promise<readonly Dirent<string>[]>;+ readonly statPath?: typeof stat;+}++function normalizeAbsolutePath(value: unknown): string | null {+ if (typeof value !== "string" || !path.isAbsolute(value)) return null;+ return path.normalize(value);+}++function normalizeModifiedAt(value: unknown): string | null {+ const date = value instanceof Date+ ? value+ : typeof value === "string" || typeof value === "number"+ ? new Date(value)+ : null;+ if (!date || !Number.isFinite(date.getTime())) return null;+ return date.toISOString();+}++export function isValidRecentContextTopK(value: number): boolean {+ return Number.isSafeInteger(value) && value >= 0;+}++export function isMissingPathError(error: unknown): boolean {+ return (error as NodeJS.ErrnoException | undefined)?.code === "ENOENT";+}++export async function readFirstLine(filePath: string, maxBytes = 65_536): Promise<string | null> {+ const stream = createReadStream(filePath, { highWaterMark: 1 });+ const bytes: Buffer[] = [];+ let length = 0;+ try {+ for await (const chunk of stream) {+ const byte = Buffer.isBuffer(chunk) ? chunk : Buffer.from(chunk);+ if (byte[0] === 0x0a) break;+ if (length >= maxBytes) return null;+ bytes.push(byte);+ length += byte.length;+ }+ return length === 0 ? null : Buffer.concat(bytes, length).toString("utf8").replace(/\r$/, "");+ } catch (error) {+ if (isMissingPathError(error)) return null;+ throw error;+ } finally {+ stream.destroy();+ }+}++export async function collectJsonlFileCandidates(+ root: string,+ options: JsonlScanOptions = {},+): Promise<JsonlFileCandidate[]> {+ const candidates: JsonlFileCandidate[] = [];+ const readDirectory = options.readDirectory+ ?? ((directory: string) => readdir(directory, { withFileTypes: true }));+ const statPath = options.statPath ?? stat;++ const visit = async (directory: string, remainingDepth: number, includeFiles: boolean): Promise<void> => {+ let entries: readonly Dirent<string>[];+ try {+ entries = await readDirectory(directory);+ } catch (error) {+ if (isMissingPathError(error)) return;+ throw error;+ }+ await Promise.all(entries.map(async (entry) => {+ const entryPath = path.join(directory, entry.name);+ if (entry.isDirectory() && remainingDepth > 0) {+ await visit(entryPath, remainingDepth - 1, true);+ } else if (includeFiles && entry.isFile() && entry.name.endsWith(".jsonl")) {+ try {+ const metadata = await statPath(entryPath);+ if (metadata.isFile()) candidates.push({ filePath: entryPath, modifiedAt: metadata.mtime });+ } catch (error) {+ if (!isMissingPathError(error)) throw error;+ }+ }+ }));+ };++ await visit(root, options.maxDepth ?? Number.POSITIVE_INFINITY, options.includeRootFiles ?? true);+ return candidates;+}++function retainNewest<K, V extends { readonly modifiedAt: string }>(+ values: Map<K, V>,+ key: K,+ value: V,+ topK: number,+): void {+ const existing = values.get(key);+ if (existing) {+ if (value.modifiedAt > existing.modifiedAt) values.set(key, value);+ return;+ }+ if (values.size < topK) {+ values.set(key, value);+ return;+ }+ let oldest: [K, V] | undefined;+ for (const entry of values) {+ if (!oldest || entry[1].modifiedAt < oldest[1].modifiedAt) oldest = entry;+ }+ if (oldest && value.modifiedAt > oldest[1].modifiedAt) {+ values.delete(oldest[0]);+ values.set(key, value);+ }+}++export class RecentContextCollector {+ private readonly sessions = new Map<string, {+ sessionFilePath: string;+ projectPath: string;+ modifiedAt: string;+ }>();+ private readonly projects = new Map<string, { projectPath: string; modifiedAt: string }>();++ constructor(+ private readonly request: RecentContextDiscoveryRequest,+ private readonly sessionFileCapability: SessionFileDiscoveryCapability,+ ) {}++ add(candidate: RecentContextCandidate, target: "both" | "session" | "project" = "both"): void {+ const projectPath = normalizeAbsolutePath(candidate.projectPath);+ const modifiedAt = normalizeModifiedAt(candidate.modifiedAt);+ if (!projectPath || !modifiedAt) return;++ if (target !== "session") {+ retainNewest(this.projects, projectPath, { projectPath, modifiedAt }, this.request.recentProjectsTopK);+ }++ if (+ target === "project"+ || this.sessionFileCapability !== "supported"+ ) return;+ const sessionFilePath = normalizeAbsolutePath(candidate.sessionFilePath);+ if (!sessionFilePath) return;+ retainNewest(+ this.sessions,+ sessionFilePath,+ { sessionFilePath, projectPath, modifiedAt },+ this.request.recentSessionFilesTopK,+ );+ }++ get satisfied(): boolean {+ const sessionsSatisfied = this.sessionFileCapability === "unavailable"+ || this.sessions.size >= this.request.recentSessionFilesTopK;+ return sessionsSatisfied && this.projects.size >= this.request.recentProjectsTopK;+ }++ result(): RecentContextDiscoveryData {+ const newestFirst = <T extends { readonly modifiedAt: string }>(left: T, right: T) =>+ right.modifiedAt.localeCompare(left.modifiedAt);+ return {+ sessionFiles: {+ capability: this.sessionFileCapability,+ items: [...this.sessions.values()]+ .sort(newestFirst)+ .slice(0, this.request.recentSessionFilesTopK),+ },+ recentProjects: [...this.projects.values()]+ .sort(newestFirst)+ .slice(0, this.request.recentProjectsTopK),+ };+ }+}++export function sanitizeRecentContextData(+ value: unknown,+ request: RecentContextDiscoveryRequest,+): RecentContextDiscoveryData | null {+ if (!value || typeof value !== "object" || Array.isArray(value)) return null;+ const candidate = value as Record<string, unknown>;+ if (!candidate.sessionFiles || typeof candidate.sessionFiles !== "object" || Array.isArray(candidate.sessionFiles)) {+ return null;+ }+ const sessionFiles = candidate.sessionFiles as Record<string, unknown>;+ const capability = sessionFiles.capability;+ if ((capability !== "supported" && capability !== "unavailable") || !Array.isArray(sessionFiles.items)) {+ return null;+ }+ if (!Array.isArray(candidate.recentProjects)) return null;++ const collector = new RecentContextCollector(request, capability);+ if (capability === "supported") {+ for (const item of sessionFiles.items) {+ if (!item || typeof item !== "object" || Array.isArray(item)) continue;+ const record = item as Record<string, unknown>;+ collector.add({+ sessionFilePath: record.sessionFilePath,+ projectPath: record.projectPath,+ modifiedAt: record.modifiedAt,+ }, "session");+ }+ }++ for (const item of candidate.recentProjects) {+ if (!item || typeof item !== "object" || Array.isArray(item)) continue;+ const record = item as Record<string, unknown>;+ collector.add({ projectPath: record.projectPath, modifiedAt: record.modifiedAt }, "project");+ }+ return collector.result();+}diff --git a/src/daemon/agent-driver/src/internal/utils.ts b/src/daemon/agent-driver/src/internal/utils.tsindex 42caf8d04..5c359b86d 100644--- a/src/daemon/agent-driver/src/internal/utils.ts+++ b/src/daemon/agent-driver/src/internal/utils.ts@@ -26,3 +26,13 @@ export function tryParseJsonLine(line: string): unknown | null {return null;}}++export function asRecord(value: unknown): Record<string, unknown> | null {+ return value && typeof value === "object" && !Array.isArray(value)+ ? value as Record<string, unknown>+ : null;+}++export function tryParseJsonRecord(line: string): Record<string, unknown> | null {+ return asRecord(tryParseJsonLine(line));+}diff --git a/src/daemon/agent-driver/src/public-contract.ts b/src/daemon/agent-driver/src/public-contract.tsindex 885f9bfba..f54a8af38 100644--- a/src/daemon/agent-driver/src/public-contract.ts+++ b/src/daemon/agent-driver/src/public-contract.ts@@ -1,4 +1,8 @@/** Consumer contract: logical SDK/session/event/result vocabulary only. */+import { SESSION_FILE_DISCOVERY_CAPABILITIES as sessionFileDiscoveryCapabilities } from "./contract.js";++export const SESSION_FILE_DISCOVERY_CAPABILITIES = sessionFileDiscoveryCapabilities;+export type {JsonPrimitive, JsonValue, JsonObject, BuiltinBackendId, ReasoningEffort, RuntimeReasoningCatalog,RuntimeSettingsUpdate, RuntimeSettingsUpdateResult, ModelSelection, DefaultProvider,@@ -11,6 +15,8 @@ export type {QuotaProductIdentity, QuotaModelIdentity, QuotaWindowIdentity, QuotaLimit,ProviderQuotaObservation, CoreAgentEventPayload, AgentEventEnvelope, AgentEvent,AgentSessionSnapshot, AgentEventStream, ExtensionNames, ExtensionInput, ExtensionOutput, ExtensionResult,- AgentSession, ProbeInput, BackendProbe, OpenSessionInput,+ AgentSession, ProbeInput, BackendProbe, OpenSessionInput, DiscoveredSessionFile,+ DiscoveredProject, SessionFileDiscoveryCapability, RecentContextDiscoveryRequest,+ RecentContextDiscoveryInput, RecentContextDiscoveryData, RecentContextDiscoveryResult,AgentDriverSdk,} from "./contract.js";diff --git a/src/daemon/agent-driver/src/registry.test.ts b/src/daemon/agent-driver/src/registry.test.tsindex 7d719aad5..f1b60ddd3 100644--- a/src/daemon/agent-driver/src/registry.test.ts+++ b/src/daemon/agent-driver/src/registry.test.ts@@ -117,6 +117,9 @@ describe("adapter registration runtime boundary", () => {} as const;currentSessionId = null;probe() { return { status: "healthy" as const }; }+ async discoverRecentContext() {+ return { sessionFiles: { capability: "unavailable" as const, items: [] }, recentProjects: [] };+ }normalizeLine() { return []; }encodeMessage() { return ""; }async openLane() { throw new Error("not opened by registration tests"); }@@ -153,6 +156,7 @@ describe("adapter registration runtime boundary", () => {terminalOwnership: "lane_generation",},probe() {},+ discoverRecentContext() {},openLane() {},};expect(() => assertAdapterCompatibility(@@ -162,6 +166,27 @@ describe("adapter registration runtime boundary", () => {)).toThrow("delivery conflicts with its execution lifetime");});+ it("accepts a missing recent-context hook but rejects a malformed optional hook", () => {+ const adapter = {+ id: "sixth",+ instructionDelivery: { kind: "native" },+ execution: {+ lifetime: "session",+ transport: { kind: "stdio_stream", protocol: "sixth.test.v1" },+ wakeStart: "immediate",+ terminalOwnership: "vendor_message",+ },+ probe() {},+ openLane() {},+ };+ expect(() => assertAdapterCompatibility("sixth", EXPECTED.claude, adapter)).not.toThrow();+ expect(() => assertAdapterCompatibility(+ "sixth",+ EXPECTED.claude,+ { ...adapter, discoverRecentContext: "not-a-function" },+ )).toThrow("invalid discoverRecentContext");+ });+it("rejects malformed turn-silence policies instead of disabling stall detection", () => {const adapter = {id: "sixth",@@ -179,6 +204,7 @@ describe("adapter registration runtime boundary", () => {},},probe() {},+ discoverRecentContext() {},openLane() {},};const invalidPolicies = [diff --git a/src/daemon/agent-driver/src/registry.ts b/src/daemon/agent-driver/src/registry.tsindex 7897c41fc..15c099c1c 100644--- a/src/daemon/agent-driver/src/registry.ts+++ b/src/daemon/agent-driver/src/registry.ts@@ -103,6 +103,9 @@ export function assertAdapterCompatibility(for (const method of ["probe", "openLane"] as const) {if (typeof candidate[method] !== "function") throw new Error(`Adapter ${registrationId} is missing ${method}()`);}+ if (candidate.discoverRecentContext !== undefined && typeof candidate.discoverRecentContext !== "function") {+ throw new Error(`Adapter ${registrationId} has an invalid discoverRecentContext()`);+ }const instruction = candidate.instructionDelivery as Record<string, unknown> | undefined;if (!instruction || (instruction.kind !== "native" && instruction.kind !== "workspace_file")) {throw new Error(`Adapter ${registrationId} has an invalid instructionDelivery declaration`);diff --git a/src/daemon/agent-driver/src/sdk.test.ts b/src/daemon/agent-driver/src/sdk.test.tsindex 54085dae1..b4ecbad18 100644--- a/src/daemon/agent-driver/src/sdk.test.ts+++ b/src/daemon/agent-driver/src/sdk.test.ts@@ -14,6 +14,7 @@ import { createFakeAgentDriverHost } from "./testing/fake-host.js";import { createAgentDriverSdk, createAgentDriverSdkWithRegistry } from "./sdk.js";import { createAgentDriverRegistry, type AgentDriverRegistry } from "./registry.js";import { createAgentDriverSdk as createPublicAgentDriverSdk } from "./public-sdk.js";+import { SESSION_FILE_DISCOVERY_CAPABILITIES } from "./index.js";const claudeInput = {backend: "claude" as const,@@ -58,6 +59,7 @@ function sdkTestLane(receipt = "fresh-receipt") {describe("createAgentDriverSdk", () => {it("exposes the built-ins with default options", () => {expect(createAgentDriverSdk().backendIds).toEqual(["claude", "codex", "cursor", "opencode", "pi"]);+ expect(SESSION_FILE_DISCOVERY_CAPABILITIES).toEqual(["supported", "unavailable"]);});it("maps healthy, unhealthy, and thrown adapter probes", async () => {@@ -95,6 +97,74 @@ describe("createAgentDriverSdk", () => {expect(createPublicAgentDriverSdk().backendIds).toEqual(["claude", "codex", "cursor", "opencode", "pi"]);});+ it.each(["claude", "codex", "cursor", "opencode", "pi"] as const)(+ "dispatches zero-bound discovery through the built-in %s adapter",+ async (backend) => {+ await expect(createAgentDriverSdk().discoverRecentContext({+ backend,+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 0,+ })).resolves.toEqual({+ ok: true,+ sessionFiles: {+ capability: backend === "cursor" || backend === "opencode" ? "unavailable" : "supported",+ items: [],+ },+ recentProjects: [],+ });+ },+ );++ it("validates independent Top-K values and dispatches discovery without leaking thrown details", async () => {+ const sdk = createAgentDriverSdk();+ const discover = vi.spyOn(ClaudeDriver.prototype, "discoverRecentContext");+ const projectPath = join(process.cwd(), "projects", "a");+ await expect(sdk.discoverRecentContext({+ backend: "claude",+ recentSessionFilesTopK: -1,+ recentProjectsTopK: 2,+ })).resolves.toMatchObject({+ ok: false,+ error: { code: "invalid_recent_context_top_k", retryable: false },+ });+ expect(discover).not.toHaveBeenCalled();++ discover.mockResolvedValueOnce({+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [{ projectPath, modifiedAt: "2026-01-01T00:00:00.000Z" }],+ });+ await expect(sdk.discoverRecentContext({+ backend: "claude",+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ command: "claude-test",+ })).resolves.toEqual({+ ok: true,+ sessionFiles: { capability: "supported", items: [] },+ recentProjects: [{ projectPath, modifiedAt: "2026-01-01T00:00:00.000Z" }],+ });+ expect(discover).toHaveBeenCalledWith({+ recentSessionFilesTopK: 0,+ recentProjectsTopK: 1,+ command: "claude-test",+ });++ discover.mockRejectedValueOnce(new Error("private /Users/person/session.jsonl"));+ await expect(sdk.discoverRecentContext({+ backend: "claude",+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ })).resolves.toEqual({+ ok: false,+ error: {+ category: "runtime_unavailable",+ code: "recent_context_discovery_failed",+ message: "Backend claude recent-context discovery failed",+ retryable: true,+ },+ });+ });+it("returns host preparation failures without constructing a session", async () => {const error: AgentDriverError = {category: "configuration",@@ -325,6 +395,14 @@ describe("createAgentDriverSdk", () => {version: "6.0.0",capabilities,});+ await expect(sdk.discoverRecentContext({+ backend: "sixth",+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ })).resolves.toMatchObject({+ ok: false,+ error: { code: "recent_context_discovery_unsupported", retryable: false },+ });const opened = await sdk.open({backend: "sixth",launch: {@@ -366,6 +444,35 @@ describe("createAgentDriverSdk", () => {expect(prepare).not.toHaveBeenCalled();});+ it("reports a malformed optional recent-context hook as an adapter contract error", async () => {+ const adapter = new ClaudeDriver();+ Object.defineProperty(adapter, "discoverRecentContext", {+ configurable: true,+ value: "not-a-function",+ });+ const registry = createAgentDriverRegistry<BuiltinBackendSpecs>([{+ id: "claude",+ contractVersion: 1,+ capabilities: claudeCapabilities,+ createAdapter: () => adapter,+ }]);+ const sdk = createAgentDriverSdkWithRegistry({ registry, host: createFakeAgentDriverHost() });++ await expect(sdk.discoverRecentContext({+ backend: "claude",+ recentSessionFilesTopK: 1,+ recentProjectsTopK: 1,+ })).resolves.toEqual({+ ok: false,+ error: {+ category: "internal",+ code: "adapter_contract_invalid",+ message: "Backend claude adapter contract is invalid",+ retryable: false,+ },+ });+ });+it.each([["missing", undefined],["old", 0],diff --git a/src/daemon/agent-driver/src/sdk.ts b/src/daemon/agent-driver/src/sdk.tsindex 230ebb6bf..49311aa8b 100644--- a/src/daemon/agent-driver/src/sdk.ts+++ b/src/daemon/agent-driver/src/sdk.ts@@ -8,6 +8,8 @@ import type {OpenSessionInput,OpenSessionResult,ProbeInput,+ RecentContextDiscoveryInput,+ RecentContextDiscoveryResult,} from "./contract.js";import { createDefaultAgentDriverHost } from "./host/default-host.js";import {@@ -18,6 +20,7 @@ import {} from "./registry.js";import { LogicalAgentSession } from "./controller/logical-session.js";import { scrubDriverError, stableErrorCode } from "./internal/errors.js";+import { isValidRecentContextTopK, sanitizeRecentContextData } from "./internal/recent-context.js";export function createAgentDriverSdk(options: CreateAgentDriverSdkOptions = {},@@ -33,6 +36,68 @@ export function createAgentDriverSdkWithRegistry<Specs>(const registry = options.registry;return {backendIds: registry.backendIds,+ async discoverRecentContext<Id extends BackendId<Specs>>(+ input: RecentContextDiscoveryInput<Specs, Id>,+ ): Promise<RecentContextDiscoveryResult> {+ if (+ !isValidRecentContextTopK(input.recentSessionFilesTopK)+ || !isValidRecentContextTopK(input.recentProjectsTopK)+ ) {+ return {+ ok: false,+ error: {+ category: "configuration",+ code: "invalid_recent_context_top_k",+ message: "Recent-context Top-K values must be non-negative safe integers",+ retryable: false,+ },+ };+ }+ const registration = registry.get(input.backend);+ try {+ assertRegistrationShape(registration);+ const adapter = registration.createAdapter();+ assertAdapterCompatibility(String(registration.id), registration.capabilities, adapter);+ if (!adapter.discoverRecentContext) {+ return {+ ok: false,+ error: {+ category: "configuration",+ code: "recent_context_discovery_unsupported",+ message: `Backend ${input.backend} does not support recent-context discovery`,+ retryable: false,+ },+ };+ }+ const command = (registration.capabilities as { readonly commandOverride: boolean }).commandOverride+ ? input.command+ : undefined;+ const discovered = await adapter.discoverRecentContext({+ recentSessionFilesTopK: input.recentSessionFilesTopK,+ recentProjectsTopK: input.recentProjectsTopK,+ ...(command ? { command } : {}),+ });+ const sanitized = sanitizeRecentContextData(discovered, input);+ if (!sanitized) throw new Error(`Adapter ${input.backend} returned invalid recent-context data`);+ return { ok: true, ...sanitized };+ } catch (error) {+ const contractInvalid = error instanceof Error && (+ error.message.startsWith("Adapter ")+ || error.message.startsWith("Agent backend registration ")+ );+ return {+ ok: false,+ error: {+ category: contractInvalid ? "internal" : "runtime_unavailable",+ code: contractInvalid ? "adapter_contract_invalid" : "recent_context_discovery_failed",+ message: contractInvalid+ ? `Backend ${input.backend} adapter contract is invalid`+ : `Backend ${input.backend} recent-context discovery failed`,+ retryable: !contractInvalid,+ },+ };+ }+ },async probe<Id extends BackendId<Specs>>(input: ProbeInput<Specs, Id>,): Promise<BackendProbe<CapabilitiesOf<Specs, Id>>> {