@ai-devkit/agent-manager 0.33.1 → 0.35.0

package/src/__tests__/providers/grok/GrokSessionLocator.test.ts

@@ -0,0 +1,106 @@
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+
+import type { ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { GrokSessionLocator } from "../../../providers/grok/GrokSessionLocator.js";
+
+describe("GrokSessionLocator", () => {
+  let baseDir: string;
+  let locator: GrokSessionLocator;
+
+  beforeEach(() => {
+    baseDir = fs.mkdtempSync(path.join(os.tmpdir(), "grok-locator-test-"));
+    locator = new GrokSessionLocator({ baseDir });
+  });
+
+  afterEach(() => {
+    fs.rmSync(baseDir, { recursive: true, force: true });
+  });
+
+  function writeSession(cwd: string, id: string, mtime?: Date): string {
+    const sessionDir = path.join(baseDir, "sessions", encodeURIComponent(cwd), id);
+    fs.mkdirSync(sessionDir, { recursive: true });
+    const chatPath = path.join(sessionDir, "chat_history.jsonl");
+    fs.writeFileSync(chatPath, "");
+    if (mtime) fs.utimesSync(chatPath, mtime, mtime);
+    return sessionDir;
+  }
+
+  function proc(overrides: Partial<ProcessInfo> = {}): ProcessInfo {
+    return { pid: 4242, command: "grok", cwd: "/repo/app", tty: "ttys001", ...overrides };
+  }
+
+  describe("matchRunningProcesses", () => {
+    it("prefers the active_sessions.json cwd over the process cwd", () => {
+      const sessionDir = writeSession("/repo/real", "s1");
+      fs.writeFileSync(
+        path.join(baseDir, "active_sessions.json"),
+        JSON.stringify([{ pid: 4242, cwd: "/repo/real" }]),
+      );
+
+      expect(locator.matchRunningProcesses([proc({ cwd: "/wrong" })])).toEqual([
+        { process: expect.objectContaining({ pid: 4242 }), cwd: "/repo/real", sessionDir },
+      ]);
+    });
+
+    it("ignores a malformed active_sessions.json and falls back to the process cwd", () => {
+      const sessionDir = writeSession("/repo/app", "s1");
+      fs.writeFileSync(path.join(baseDir, "active_sessions.json"), "{not json");
+
+      expect(locator.matchRunningProcesses([proc()])[0]).toMatchObject({
+        cwd: "/repo/app",
+        sessionDir,
+      });
+    });
+
+    it("picks the session with the newest chat_history.jsonl", () => {
+      writeSession("/repo/app", "old", new Date(Date.now() - 60_000));
+      const newest = writeSession("/repo/app", "new");
+
+      expect(locator.matchRunningProcesses([proc()])[0].sessionDir).toBe(newest);
+    });
+
+    it("returns a null sessionDir when no cwd is known", () => {
+      expect(locator.matchRunningProcesses([proc({ cwd: "" })])[0]).toMatchObject({
+        cwd: "",
+        sessionDir: null,
+      });
+    });
+  });
+
+  describe("historical sessions", () => {
+    it("discovers session dirs with the decoded group cwd", () => {
+      const a = writeSession("/repo/a", "s1");
+      const b = writeSession("/repo/b", "s2");
+
+      expect(locator.discoverHistoricalSessionDirs()).toEqual(
+        expect.arrayContaining([
+          { sessionDir: a, defaultCwd: "/repo/a" },
+          { sessionDir: b, defaultCwd: "/repo/b" },
+        ]),
+      );
+    });
+
+    it("prefers the .cwd file over the encoded group name", () => {
+      const groupDir = path.join(baseDir, "sessions", "slug-abc123");
+      fs.mkdirSync(path.join(groupDir, "s1"), { recursive: true });
+      fs.writeFileSync(path.join(groupDir, ".cwd"), "/very/long/path\n");
+
+      expect(locator.discoverHistoricalSessionDirs()).toEqual([
+        { sessionDir: path.join(groupDir, "s1"), defaultCwd: "/very/long/path" },
+      ]);
+    });
+
+    it("finds session dirs by id and rejects unsafe ids", () => {
+      const dir = writeSession("/repo/a", "s1");
+      writeSession("/repo/b", "s2");
+
+      expect(locator.findHistoricalSessionDirsById("s1")).toEqual([
+        { sessionDir: dir, defaultCwd: "/repo/a" },
+      ]);
+      expect(locator.findHistoricalSessionDirsById("../s1")).toEqual([]);
+    });
+  });
+});

package/src/__tests__/providers/opencode/OpenCodeAdapter.test.ts

@@ -0,0 +1,215 @@
+import Database from "better-sqlite3";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { AgentStatus, type ProcessInfo } from "../../../adapters/AgentAdapter.js";
+import { OpenCodeAdapter } from "../../../providers/opencode/OpenCodeAdapter.js";
+
+describe("OpenCodeAdapter", () => {
+  let adapter: OpenCodeAdapter;
+  let tmpDir: string;
+  let dbPath: string;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "opencode-adapter-test-"));
+    dbPath = path.join(tmpDir, "opencode.db");
+    adapter = new OpenCodeAdapter(dbPath);
+  });
+
+  afterEach(() => {
+    adapter.close();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("detects opencode executables", () => {
+    expect(adapter.canHandle({ pid: 1, command: "opencode", cwd: "/repo" })).toBe(true);
+    expect(adapter.canHandle({ pid: 2, command: "/usr/bin/opencode.exe", cwd: "/repo" })).toBe(
+      true,
+    );
+    expect(adapter.canHandle({ pid: 3, command: "node /repo/opencode-plugin.js" })).toBe(false);
+  });
+
+  it("returns process-only agents when the database is unavailable", async () => {
+    const agents = await adapter.detectAgents({
+      processes: [{ pid: 100, command: "opencode", cwd: "/repo", tty: "ttys001" }],
+    });
+
+    expect(agents).toEqual([
+      expect.objectContaining({
+        type: "opencode",
+        status: AgentStatus.RUNNING,
+        pid: 100,
+        projectPath: "/repo",
+        sessionId: "pid-100",
+        summary: "OpenCode process running",
+      }),
+    ]);
+  });
+
+  it("maps matching OpenCode sessions to agents", async () => {
+    const now = Date.now();
+    writeDatabase(dbPath, {
+      sessions: [{ id: "sess-001", directory: "/repo", timeCreated: now - 60_000 }],
+      messages: [
+        {
+          id: "msg-user",
+          sessionId: "sess-001",
+          role: "user",
+          timeCreated: now - 50_000,
+          timeUpdated: now - 50_000,
+        },
+        {
+          id: "msg-assistant",
+          sessionId: "sess-001",
+          role: "assistant",
+          timeCreated: now - 30_000,
+          timeUpdated: now - 30_000,
+          completed: now - 20_000,
+        },
+      ],
+      parts: [
+        {
+          messageId: "msg-user",
+          sessionId: "sess-001",
+          type: "text",
+          text: "Refactor this module",
+          timeCreated: now - 50_000,
+        },
+      ],
+    });
+
+    const process: ProcessInfo = { pid: 200, command: "opencode", cwd: "/repo", tty: "ttys002" };
+    const [agent] = await adapter.detectAgents({ processes: [process] });
+
+    expect(agent).toMatchObject({
+      type: "opencode",
+      status: AgentStatus.WAITING,
+      pid: 200,
+      projectPath: "/repo",
+      sessionId: "sess-001",
+      summary: "Refactor this module",
+      sessionFilePath: `${dbPath}::sess-001`,
+    });
+  });
+
+  it("returns conversation messages for encoded OpenCode session refs", () => {
+    writeDatabase(dbPath, {
+      sessions: [{ id: "sess-abc", directory: "/repo", timeCreated: Date.now() }],
+      messages: [
+        {
+          id: "msg-user",
+          sessionId: "sess-abc",
+          role: "user",
+          timeCreated: 1000,
+          timeUpdated: 1000,
+        },
+      ],
+      parts: [
+        {
+          messageId: "msg-user",
+          sessionId: "sess-abc",
+          type: "text",
+          text: "Hello agent",
+          timeCreated: 1000,
+        },
+      ],
+    });
+
+    expect(adapter.getConversation(`${dbPath}::sess-abc`)).toEqual([
+      { role: "user", content: "Hello agent" },
+    ]);
+    expect(adapter.getConversation("/not-an-opencode-ref")).toEqual([]);
+  });
+
+  it("finds an exact session ID with a targeted database query", async () => {
+    const now = Date.now();
+    writeDatabase(dbPath, {
+      sessions: [
+        { id: "wanted", directory: "/repo", timeCreated: now },
+        { id: "other", directory: "/other", timeCreated: now - 1_000 },
+      ],
+    });
+
+    await expect(adapter.findSessionsById("wanted")).resolves.toEqual([
+      expect.objectContaining({
+        type: "opencode",
+        sessionId: "wanted",
+        sessionFilePath: `${dbPath}::wanted`,
+      }),
+    ]);
+  });
+});
+
+function writeDatabase(
+  filePath: string,
+  data: {
+    sessions: Array<{ id: string; directory: string; timeCreated: number }>;
+    messages?: Array<{
+      id: string;
+      sessionId: string;
+      role: string;
+      timeCreated: number;
+      timeUpdated: number;
+      completed?: number;
+    }>;
+    parts?: Array<{
+      messageId: string;
+      sessionId: string;
+      type: string;
+      text?: string;
+      reasoning?: string;
+      tool?: string;
+      timeCreated: number;
+    }>;
+  },
+): void {
+  const db = new Database(filePath);
+  db.exec(`
+    CREATE TABLE session (id TEXT, directory TEXT, time_created INTEGER);
+    CREATE TABLE message (id TEXT, session_id TEXT, data TEXT, time_created INTEGER, time_updated INTEGER);
+    CREATE TABLE part (message_id TEXT, session_id TEXT, data TEXT, time_created INTEGER);
+  `);
+
+  const insertSession = db.prepare(
+    "INSERT INTO session (id, directory, time_created) VALUES (?, ?, ?)",
+  );
+  for (const session of data.sessions) {
+    insertSession.run(session.id, session.directory, session.timeCreated);
+  }
+
+  const insertMessage = db.prepare(
+    "INSERT INTO message (id, session_id, data, time_created, time_updated) VALUES (?, ?, ?, ?, ?)",
+  );
+  for (const message of data.messages ?? []) {
+    insertMessage.run(
+      message.id,
+      message.sessionId,
+      JSON.stringify({
+        role: message.role,
+        time: message.completed === undefined ? {} : { completed: message.completed },
+      }),
+      message.timeCreated,
+      message.timeUpdated,
+    );
+  }
+
+  const insertPart = db.prepare(
+    "INSERT INTO part (message_id, session_id, data, time_created) VALUES (?, ?, ?, ?)",
+  );
+  for (const part of data.parts ?? []) {
+    insertPart.run(
+      part.messageId,
+      part.sessionId,
+      JSON.stringify({
+        type: part.type,
+        text: part.text,
+        reasoning: part.reasoning,
+        tool: part.tool,
+      }),
+      part.timeCreated,
+    );
+  }
+
+  db.close();
+}

package/src/__tests__/providers/opencode/OpenCodeAgentMapper.test.ts

@@ -0,0 +1,83 @@
+import { describe, expect, it } from "vitest";
+import { AgentStatus } from "../../../adapters/AgentAdapter.js";
+import { OpenCodeAgentMapper } from "../../../providers/opencode/OpenCodeAgentMapper.js";
+
+describe("OpenCodeAgentMapper", () => {
+  const mapper = new OpenCodeAgentMapper("/tmp/opencode.db");
+
+  it("maps completed assistant sessions as waiting", () => {
+    const now = Date.now();
+
+    const agent = mapper.mapSessionToAgent(
+      { sessionId: "sess-1", directory: "/repo", timeCreated: now - 60_000 },
+      {
+        lastRole: "assistant",
+        lastTimeUpdated: now - 30_000,
+        lastAssistantCompleted: true,
+        lastAssistantErrored: false,
+        summary: "Ship the feature",
+      },
+      { pid: 123, command: "opencode", cwd: "/repo" },
+    );
+
+    expect(agent).toMatchObject({
+      type: "opencode",
+      status: AgentStatus.WAITING,
+      summary: "Ship the feature",
+      pid: 123,
+      projectPath: "/repo",
+      sessionId: "sess-1",
+      sessionFilePath: "/tmp/opencode.db::sess-1",
+    });
+  });
+
+  it("keeps incomplete assistant sessions running even when they are quiet briefly", () => {
+    const now = Date.now();
+
+    const agent = mapper.mapSessionToAgent(
+      { sessionId: "sess-2", directory: "/repo", timeCreated: now - 120_000 },
+      {
+        lastRole: "assistant",
+        lastTimeUpdated: now - 120_000,
+        lastAssistantCompleted: false,
+        lastAssistantErrored: false,
+        summary: "",
+      },
+      { pid: 124, command: "opencode", cwd: "/repo" },
+    );
+
+    expect(agent.status).toBe(AgentStatus.RUNNING);
+    expect(agent.summary).toBe("OpenCode session active");
+  });
+
+  it("marks stale sessions idle", () => {
+    const staleTime = Date.now() - 10 * 60 * 1000;
+
+    const agent = mapper.mapSessionToAgent(
+      { sessionId: "sess-3", directory: "/old", timeCreated: staleTime },
+      {
+        lastRole: "assistant",
+        lastTimeUpdated: staleTime,
+        lastAssistantCompleted: true,
+        lastAssistantErrored: false,
+        summary: "",
+      },
+      { pid: 125, command: "opencode", cwd: "/old" },
+    );
+
+    expect(agent.status).toBe(AgentStatus.IDLE);
+  });
+
+  it("maps unmatched processes as running process-only agents", () => {
+    const agent = mapper.mapProcessOnlyAgent({ pid: 500, command: "opencode", cwd: "/repo" });
+
+    expect(agent).toMatchObject({
+      type: "opencode",
+      status: AgentStatus.RUNNING,
+      summary: "OpenCode process running",
+      pid: 500,
+      projectPath: "/repo",
+      sessionId: "pid-500",
+    });
+  });
+});

package/src/__tests__/providers/opencode/OpenCodeSessionLocator.test.ts

@@ -0,0 +1,84 @@
+import Database from "better-sqlite3";
+import * as fs from "fs";
+import * as os from "os";
+import * as path from "path";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { OpenCodeSessionLocator } from "../../../providers/opencode/OpenCodeSessionLocator.js";
+import { OpenCodeSessionParser } from "../../../providers/opencode/OpenCodeSessionParser.js";
+
+describe("OpenCodeSessionLocator", () => {
+  let tmpDir: string;
+  let dbPath: string;
+  let locator: OpenCodeSessionLocator;
+
+  beforeEach(() => {
+    tmpDir = fs.mkdtempSync(path.join(os.tmpdir(), "opencode-locator-test-"));
+    dbPath = path.join(tmpDir, "opencode.db");
+    locator = new OpenCodeSessionLocator(dbPath, new OpenCodeSessionParser());
+  });
+
+  afterEach(() => {
+    locator.close();
+    fs.rmSync(tmpDir, { recursive: true, force: true });
+  });
+
+  it("returns null when the database file does not exist", () => {
+    expect(locator.openDb()).toBeNull();
+    expect(locator.listSessions()).toEqual([]);
+  });
+
+  it("finds the newest session for a directory", () => {
+    writeDatabase(dbPath, [
+      { id: "old", directory: "/repo", timeCreated: 1000 },
+      { id: "new", directory: "/repo", timeCreated: 2000 },
+      { id: "other", directory: "/other", timeCreated: 3000 },
+    ]);
+
+    const db = locator.openDb();
+    expect(db).not.toBeNull();
+    expect(locator.findSessionForDirectory(db!, "/repo")).toEqual({
+      sessionId: "new",
+      directory: "/repo",
+      timeCreated: 2000,
+    });
+  });
+
+  it("lists sessions and filters by cwd", () => {
+    writeDatabase(dbPath, [
+      { id: "sess-a", directory: "/repo-a", timeCreated: 1000 },
+      { id: "sess-b", directory: "/repo-b", timeCreated: 2000 },
+    ]);
+
+    const sessions = locator.listSessions({ cwd: "/repo-a" });
+
+    expect(sessions).toEqual([
+      expect.objectContaining({
+        type: "opencode",
+        sessionId: "sess-a",
+        cwd: "/repo-a",
+        sessionFilePath: `${dbPath}::sess-a`,
+      }),
+    ]);
+  });
+});
+
+function writeDatabase(
+  filePath: string,
+  sessions: Array<{ id: string; directory: string; timeCreated: number }>,
+): void {
+  const db = new Database(filePath);
+  db.exec(`
+    CREATE TABLE session (id TEXT, directory TEXT, time_created INTEGER);
+    CREATE TABLE message (id TEXT, session_id TEXT, data TEXT, time_created INTEGER, time_updated INTEGER);
+    CREATE TABLE part (message_id TEXT, session_id TEXT, data TEXT, time_created INTEGER);
+  `);
+
+  const insertSession = db.prepare(
+    "INSERT INTO session (id, directory, time_created) VALUES (?, ?, ?)",
+  );
+  for (const session of sessions) {
+    insertSession.run(session.id, session.directory, session.timeCreated);
+  }
+
+  db.close();
+}

package/src/__tests__/providers/opencode/OpenCodeSessionParser.test.ts

@@ -0,0 +1,148 @@
+import Database from "better-sqlite3";
+import { afterEach, beforeEach, describe, expect, it } from "vitest";
+import { OpenCodeSessionParser } from "../../../providers/opencode/OpenCodeSessionParser.js";
+
+describe("OpenCodeSessionParser", () => {
+  let db: Database.Database;
+  let parser: OpenCodeSessionParser;
+
+  beforeEach(() => {
+    db = new Database(":memory:");
+    db.exec(`
+      CREATE TABLE message (id TEXT, session_id TEXT, data TEXT, time_created INTEGER, time_updated INTEGER);
+      CREATE TABLE part (message_id TEXT, session_id TEXT, data TEXT, time_created INTEGER);
+    `);
+    parser = new OpenCodeSessionParser();
+  });
+
+  afterEach(() => {
+    db.close();
+  });
+
+  it("extracts session stats from OpenCode messages and parts", () => {
+    insertMessage(db, {
+      id: "msg-user",
+      sessionId: "sess-1",
+      role: "user",
+      timeCreated: 1000,
+      timeUpdated: 1000,
+    });
+    insertMessage(db, {
+      id: "msg-assistant",
+      sessionId: "sess-1",
+      role: "assistant",
+      timeCreated: 2000,
+      timeUpdated: 2500,
+      completed: 2400,
+    });
+    insertPart(db, {
+      messageId: "msg-user",
+      sessionId: "sess-1",
+      data: { type: "text", text: "Plan the migration" },
+      timeCreated: 1000,
+    });
+
+    expect(parser.getSessionStats(db, "sess-1")).toEqual({
+      lastRole: "assistant",
+      lastTimeUpdated: 2500,
+      lastAssistantCompleted: true,
+      lastAssistantErrored: false,
+      summary: "Plan the migration",
+    });
+  });
+
+  it("orders stats by message creation time, not metadata update time", () => {
+    insertMessage(db, {
+      id: "msg-user",
+      sessionId: "sess-1",
+      role: "user",
+      timeCreated: 1000,
+      timeUpdated: 3000,
+    });
+    insertMessage(db, {
+      id: "msg-assistant",
+      sessionId: "sess-1",
+      role: "assistant",
+      timeCreated: 2000,
+      timeUpdated: 2100,
+      completed: 2200,
+    });
+
+    expect(parser.getSessionStats(db, "sess-1").lastRole).toBe("assistant");
+  });
+
+  it("reads visible conversation text and hides verbose-only parts by default", () => {
+    insertMessage(db, {
+      id: "msg-user",
+      sessionId: "sess-1",
+      role: "user",
+      timeCreated: 1000,
+      timeUpdated: 1000,
+    });
+    insertMessage(db, {
+      id: "msg-assistant",
+      sessionId: "sess-1",
+      role: "assistant",
+      timeCreated: 2000,
+      timeUpdated: 2000,
+    });
+    insertPart(db, {
+      messageId: "msg-user",
+      sessionId: "sess-1",
+      data: { type: "text", text: "Hello" },
+      timeCreated: 1000,
+    });
+    insertPart(db, {
+      messageId: "msg-assistant",
+      sessionId: "sess-1",
+      data: { type: "reasoning", reasoning: "private thought" },
+      timeCreated: 2000,
+    });
+    insertPart(db, {
+      messageId: "msg-assistant",
+      sessionId: "sess-1",
+      data: { type: "tool", tool: "read_file" },
+      timeCreated: 3000,
+    });
+
+    expect(parser.getConversation(db, "sess-1")).toEqual([{ role: "user", content: "Hello" }]);
+    expect(parser.getConversation(db, "sess-1", { verbose: true })).toEqual([
+      { role: "user", content: "Hello" },
+      { role: "assistant", content: "[thinking] private thought" },
+      { role: "assistant", content: "[tool: read_file]" },
+    ]);
+  });
+});
+
+function insertMessage(
+  db: Database.Database,
+  input: {
+    id: string;
+    sessionId: string;
+    role: string;
+    timeCreated: number;
+    timeUpdated: number;
+    completed?: number;
+  },
+): void {
+  db.prepare(
+    "INSERT INTO message (id, session_id, data, time_created, time_updated) VALUES (?, ?, ?, ?, ?)",
+  ).run(
+    input.id,
+    input.sessionId,
+    JSON.stringify({
+      role: input.role,
+      time: input.completed === undefined ? {} : { completed: input.completed },
+    }),
+    input.timeCreated,
+    input.timeUpdated,
+  );
+}
+
+function insertPart(
+  db: Database.Database,
+  input: { messageId: string; sessionId: string; data: unknown; timeCreated: number },
+): void {
+  db.prepare("INSERT INTO part (message_id, session_id, data, time_created) VALUES (?, ?, ?, ?)")
+    .run(input.messageId, input.sessionId, JSON.stringify(input.data), input.timeCreated);
+}

package/src/__tests__/providers/pi/PiAdapter.test.ts

@@ -260,6 +260,21 @@ describe("PiAdapter", () => {
     ]);
   });
 
+  it("finds an exact session ID from the filename suffix", async () => {
+    const wanted = writePiSession("/repo/wanted", [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-wanted", cwd: "/repo/wanted" },
+      { role: "user", content: "wanted" },
+    ]);
+    writePiSession("/repo/other", [
+      { timestamp: "2026-06-10T08:58:20.754Z", sessionId: "sess-other", cwd: "/repo/other" },
+      { role: "user", content: "other" },
+    ]);
+
+    await expect(adapter.findSessionsById("sess-wanted")).resolves.toEqual([
+      expect.objectContaining({ sessionId: "sess-wanted", sessionFilePath: wanted }),
+    ]);
+  });
+
   function makeProcess(overrides: Partial<ProcessInfo>): ProcessInfo {
     return {
       pid: 1,

package/src/__tests__/utils/session.test.ts

@@ -5,7 +5,7 @@
 import type { MockedFunction } from "vitest";
 
 import * as fs from "fs";
-import { batchGetSessionFileBirthtimes } from "../../utils/session.js";
+import { batchGetSessionFileBirthtimes, isSafePathSegment } from "../../utils/session.js";
 
 vi.mock("fs", () => ({
   readdirSync: vi.fn(),
@@ -15,6 +15,16 @@ vi.mock("fs", () => ({
 const mockedReaddirSync = fs.readdirSync as MockedFunction<typeof fs.readdirSync>;
 const mockedStatSync = fs.statSync as MockedFunction<typeof fs.statSync>;
 
+describe("isSafePathSegment", () => {
+  it.each(["", ".", "..", "nested/session", "bad\0id"])("rejects unsafe segment %j", (value) => {
+    expect(isSafePathSegment(value)).toBe(false);
+  });
+
+  it.each(["session-id", ".hidden-session"])("accepts safe segment %j", (value) => {
+    expect(isSafePathSegment(value)).toBe(true);
+  });
+});
+
 describe("batchGetSessionFileBirthtimes", () => {
   beforeEach(() => {
     mockedReaddirSync.mockReset();

package/src/adapters/AgentAdapter.ts

@@ -208,4 +208,13 @@ export interface AgentAdapter {
    * @returns Array of sessions discovered on disk
    */
   listSessions(opts?: ListSessionsOptions): Promise<SessionSummary[]>;
+
+  /**
+   * Resolve exact historical session matches without enumerating every summary.
+   *
+   * Built-in adapters implement this using their provider-native storage shape.
+   * The method remains optional so external adapters can fall back to
+   * {@link listSessions} until they adopt direct lookup.
+   */
+  findSessionsById?(sessionId: string): Promise<SessionSummary[]>;
 }