Skip to content

armgit / alook

Public Imported from GitHub
0

Multi-Agent Collaboration for Team and Friends

feat(agent-driver): discover recent contexts (#705)

Gustavo Ye334203eb27c3
diff --git a/src/daemon/agent-driver/README.md b/src/daemon/agent-driver/README.md
index 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 matrix
All 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 or
unhealthy. 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.md
index 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 with
diff --git a/src/daemon/agent-driver/src/adapter-author.ts b/src/daemon/agent-driver/src/adapter-author.ts
index 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.ts
index 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, resolveClaudeComman
import { 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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, OpenCodeServiceProcessFac
private 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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>>> {