@ai-devkit/agent-manager 0.34.0 → 0.36.0

package/src/capacity/openai.ts

@@ -0,0 +1,361 @@
+import { readFile } from "node:fs/promises";
+import { homedir } from "node:os";
+import { join } from "node:path";
+import { parseWhamUsage } from "./wham.js";
+import type { CapacityReport, CapacityWindow } from "./types.js";
+
+const OPENAI_USAGE_BASE_URL = "https://api.openai.com/v1/organization/usage";
+const OPENAI_MODELS_URL = "https://api.openai.com/v1/models";
+const WHAM_USAGE_URL = "https://chatgpt.com/backend-api/wham/usage";
+const OPENAI_USAGE_ENDPOINTS = ["completions", "responses"] as const;
+const USAGE_WINDOW_DAYS = 7;
+const DAY_MS = 24 * 60 * 60 * 1000;
+const MISSING_API_KEY_MESSAGE =
+  "OpenAI credentials not found; set OPENAI_API_KEY, configure the Pi openai provider, or log in to OpenAI via Pi";
+const EPOCH_MS_FLOOR = 1e12;
+
+export type OpenAiUsageBucket = { startMs: number; tokens: number };
+type UnknownRecord = Record<string, unknown>;
+
+/**
+ * Resolved OpenAI credential: a platform API key (env or Pi `openai` entry)
+ * or the OAuth login Pi stores as `openai-codex` for ChatGPT-backed access.
+ */
+export type OpenAiCredential =
+  | { kind: "platform"; key: string }
+  | { kind: "oauth"; access: string; accountId: string; expiresMs: number | null };
+
+export type OpenAiCredentialOptions = {
+  env?: NodeJS.ProcessEnv;
+  readFile?: (path: string, encoding: BufferEncoding) => Promise<string>;
+};
+
+export type OpenAiProbeOptions = OpenAiCredentialOptions & {
+  checkedAt: string;
+  fetch?: typeof globalThis.fetch;
+  timeoutMs?: number;
+};
+type OpenAiRequestContext = OpenAiProbeOptions & { key: string };
+type OAuthCredential = Extract<OpenAiCredential, { kind: "oauth" }>;
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.trim() ? value.trim() : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+/** Pi stores `expires` in epoch milliseconds, codex-style tokens use seconds. */
+function toEpochMs(value: unknown): number | null {
+  const raw = finiteNumber(value);
+  if (raw === null || raw <= 0) return null;
+  return raw > EPOCH_MS_FLOOR ? raw : raw * 1000;
+}
+
+async function readPiAuthRoot(options: OpenAiCredentialOptions): Promise<UnknownRecord> {
+  const env = options.env ?? process.env;
+  const authPath = join(env.HOME || homedir(), ".pi", "agent", "auth.json");
+  let parsed: UnknownRecord;
+  try {
+    const contents = await (options.readFile ?? readFile)(authPath, "utf8");
+    const root = record(JSON.parse(contents));
+    if (!root) throw new Error("invalid");
+    parsed = root;
+  } catch (error) {
+    if (record(error)?.code === "ENOENT") {
+      throw new Error(MISSING_API_KEY_MESSAGE);
+    }
+    throw new Error("OpenAI Pi auth file is malformed");
+  }
+  return parsed;
+}
+
+/**
+ * Resolves the OpenAI credential in priority order: `OPENAI_API_KEY` env,
+ * then the Pi `openai` platform-key entry, then the Pi `openai-codex` OAuth
+ * login written by `pi login` (no manual setup required).
+ */
+export async function resolveOpenAiCredential(
+  options: OpenAiCredentialOptions = {},
+): Promise<OpenAiCredential> {
+  const env = options.env ?? process.env;
+  const environmentKey = nonEmptyText(env.OPENAI_API_KEY);
+  if (environmentKey) return { kind: "platform", key: environmentKey };
+
+  const parsed = await readPiAuthRoot(options);
+
+  const platform = record(parsed.openai);
+  if (platform) {
+    const key = platform.type === "api_key" ? nonEmptyText(platform.key) : null;
+    if (!key) {
+      throw new Error("OpenAI Pi auth file has a malformed openai credential");
+    }
+    return { kind: "platform", key };
+  }
+
+  const oauth = record(parsed["openai-codex"]);
+  const access = oauth?.type === "oauth" ? nonEmptyText(oauth.access) : null;
+  const accountId = nonEmptyText(oauth?.accountId);
+  if (oauth && access && accountId) {
+    return { kind: "oauth", access, accountId, expiresMs: toEpochMs(oauth.expires) };
+  }
+  throw new Error(MISSING_API_KEY_MESSAGE);
+}
+
+export async function resolveOpenAiApiKey(options: OpenAiCredentialOptions = {}): Promise<string> {
+  const credential = await resolveOpenAiCredential(options);
+  if (credential.kind === "platform") return credential.key;
+  throw new Error(MISSING_API_KEY_MESSAGE);
+}
+
+function bucketTokens(value: unknown): number {
+  const results = Array.isArray(value) ? value : [];
+  return results.reduce(
+    (total, entry) =>
+      total +
+      (finiteNumber(record(entry)?.input_tokens) ?? 0) +
+      (finiteNumber(record(entry)?.output_tokens) ?? 0),
+    0,
+  );
+}
+
+/**
+ * Maps one OpenAI Usage API payload (day buckets of per-model token counts)
+ * into summed UTC-day buckets. Entries without a numeric
+ * aggregation_timestamp are skipped because they cannot be placed in time.
+ */
+export function parseOpenAiUsage(raw: unknown): OpenAiUsageBucket[] {
+  const data = record(raw)?.data;
+  if (!Array.isArray(data)) throw new Error("Invalid OpenAI usage response");
+  const buckets: OpenAiUsageBucket[] = [];
+  for (const entry of data) {
+    const seconds = finiteNumber(record(entry)?.aggregation_timestamp);
+    if (seconds === null) continue;
+    buckets.push({ startMs: seconds * 1000, tokens: bucketTokens(record(entry)?.results) });
+  }
+  return buckets;
+}
+
+function openAiCapacityReport(
+  windows: CapacityWindow[],
+  checkedAt: string,
+  authenticated: boolean,
+): CapacityReport {
+  return {
+    harness: "pi",
+    provider: "openai",
+    generatedAt: checkedAt,
+    authenticated,
+    available: windows.length > 0 ? "yes" : "unknown",
+    windows,
+    creditsRemaining: null,
+  };
+}
+
+/**
+ * Builds the capacity report from merged day buckets: trailing-7-day and
+ * current-UTC-day token usage. The platform is pay-as-you-go and exposes no
+ * queryable limit, so windows report consumption only — no faked percentages.
+ */
+export function buildOpenAiReport(buckets: OpenAiUsageBucket[], checkedAt: string): CapacityReport {
+  const nowMs = Date.parse(checkedAt);
+  const todayStartMs = Math.floor(nowMs / DAY_MS) * DAY_MS;
+  const weekStartMs = todayStartMs - (USAGE_WINDOW_DAYS - 1) * DAY_MS;
+  let todayTokens = 0;
+  let weekTokens = 0;
+  for (const bucket of buckets) {
+    if (bucket.startMs === todayStartMs) todayTokens += bucket.tokens;
+    if (bucket.startMs >= weekStartMs) weekTokens += bucket.tokens;
+  }
+  const windows: CapacityWindow[] = [
+    {
+      id: "openai:tokens:today",
+      label: "Tokens · today (UTC)",
+      limitType: "TOKENS_LIMIT",
+      durationMinutes: 24 * 60,
+      usedPercent: null,
+      resetsAt: new Date(todayStartMs + DAY_MS).toISOString(),
+      total: null,
+      current: todayTokens,
+      remaining: null,
+    },
+    {
+      id: "openai:tokens:week",
+      label: "Tokens · 7 days",
+      limitType: "TOKENS_LIMIT",
+      durationMinutes: USAGE_WINDOW_DAYS * 24 * 60,
+      usedPercent: null,
+      resetsAt: null,
+      total: null,
+      current: weekTokens,
+      remaining: null,
+    },
+  ];
+  return openAiCapacityReport(windows, checkedAt, true);
+}
+
+async function fetchUsage(context: OpenAiRequestContext): Promise<unknown[] | number | null> {
+  const fetcher = context.fetch ?? globalThis.fetch;
+  const endSeconds = Math.floor(Date.parse(context.checkedAt) / 1000);
+  const startSeconds = endSeconds - USAGE_WINDOW_DAYS * 24 * 60 * 60;
+  const query = `start_time=${startSeconds}&end_time=${endSeconds}`;
+  const payloads: unknown[] = [];
+  for (const endpoint of OPENAI_USAGE_ENDPOINTS) {
+    const controller = new AbortController();
+    const timer = setTimeout(() => controller.abort(), context.timeoutMs ?? 5000);
+    let response: Response;
+    try {
+      response = await fetcher(`${OPENAI_USAGE_BASE_URL}/${endpoint}?${query}`, {
+        method: "GET",
+        headers: {
+          Authorization: `Bearer ${context.key}`,
+        },
+        signal: controller.signal,
+      });
+    } catch {
+      throw new Error("OpenAI usage request failed");
+    } finally {
+      clearTimeout(timer);
+    }
+    if (response.status === 401) return null;
+    if (response.status === 403) return response.status;
+    if (response.status !== 200) {
+      throw new Error(`OpenAI usage request failed: HTTP ${response.status}`);
+    }
+    try {
+      payloads.push(await response.json());
+    } catch {
+      throw new Error("OpenAI usage response is not valid JSON");
+    }
+  }
+  return payloads;
+}
+
+async function verifyKey(context: OpenAiRequestContext): Promise<boolean> {
+  const fetcher = context.fetch ?? globalThis.fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), context.timeoutMs ?? 5000);
+  try {
+    const response = await fetcher(OPENAI_MODELS_URL, {
+      method: "GET",
+      headers: { Authorization: `Bearer ${context.key}` },
+      signal: controller.signal,
+    });
+    return response.status !== 401;
+  } catch {
+    throw new Error("OpenAI usage request failed");
+  } finally {
+    clearTimeout(timer);
+  }
+}
+
+export async function probeOpenAiCapacity(options: OpenAiProbeOptions): Promise<CapacityReport> {
+  const credential = await resolveOpenAiCredential(options);
+  if (credential.kind === "oauth") {
+    return probeOpenAiOauthCapacity(credential, options);
+  }
+  const probe: OpenAiProbeOptions & { key: string } = { ...options, key: credential.key };
+  const result = await fetchUsage(probe);
+  if (result === null) {
+    return openAiCapacityReport([], options.checkedAt, false);
+  }
+  if (typeof result === "number") {
+    const authenticated = await verifyKey(probe);
+    return openAiCapacityReport([], options.checkedAt, authenticated);
+  }
+  const buckets = result.flatMap(parseOpenAiUsage);
+  return buildOpenAiReport(buckets, options.checkedAt);
+}
+
+/** Mirrors codex.ts: JWT `exp` (epoch seconds) as expiry fallback. */
+function jwtExpiryMs(token: string): number | null {
+  const part = token.split(".")[1];
+  if (!part) return null;
+  try {
+    const exp = finiteNumber(
+      record(JSON.parse(Buffer.from(part, "base64url").toString("utf8")))?.exp,
+    );
+    return exp === null ? null : exp * 1000;
+  } catch {
+    return null;
+  }
+}
+
+function oauthExpired(credential: OAuthCredential, nowMs: number): boolean {
+  const expiryMs = credential.expiresMs ?? jwtExpiryMs(credential.access);
+  return expiryMs !== null && expiryMs <= nowMs;
+}
+
+async function fetchWhamUsage(
+  credential: OAuthCredential,
+  options: OpenAiProbeOptions,
+): Promise<unknown | null> {
+  const fetcher = options.fetch ?? globalThis.fetch;
+  const controller = new AbortController();
+  const timer = setTimeout(() => controller.abort(), options.timeoutMs ?? 5000);
+  let response: Response;
+  try {
+    response = await fetcher(WHAM_USAGE_URL, {
+      method: "GET",
+      headers: {
+        Authorization: `Bearer ${credential.access}`,
+        "ChatGPT-Account-Id": credential.accountId,
+      },
+      signal: controller.signal,
+    });
+  } catch {
+    throw new Error("OpenAI usage request failed");
+  } finally {
+    clearTimeout(timer);
+  }
+  if (response.status === 401 || response.status === 403) return null;
+  if (response.status !== 200) {
+    throw new Error(`OpenAI usage request failed: HTTP ${response.status}`);
+  }
+  try {
+    return await response.json();
+  } catch {
+    throw new Error("OpenAI usage response is not valid JSON");
+  }
+}
+
+/**
+ * OAuth path for Pi's OpenAI login: consumes the same wham/usage endpoint as
+ * the codex harness. Stale logins are never fetched (no refresh, matching
+ * codex.ts); they render as authenticated-but-stale instead.
+ */
+async function probeOpenAiOauthCapacity(
+  credential: OAuthCredential,
+  options: OpenAiProbeOptions,
+): Promise<CapacityReport> {
+  const staleReport: CapacityReport = {
+    harness: "pi",
+    provider: "openai",
+    generatedAt: options.checkedAt,
+    authenticated: true,
+    available: "unknown",
+    windows: [],
+    creditsRemaining: null,
+  };
+  const nowMs = Date.parse(options.checkedAt);
+  if (Number.isNaN(nowMs) || oauthExpired(credential, nowMs)) return staleReport;
+  const raw = await fetchWhamUsage(credential, options);
+  if (raw === null) {
+    return { ...staleReport, authenticated: false };
+  }
+  const snapshot = parseWhamUsage(raw);
+  const hasUsage = snapshot.windows.some((window) => window.usedPercent !== null);
+  return {
+    ...staleReport,
+    available: hasUsage ? "yes" : "unknown",
+    windows: snapshot.windows,
+    creditsRemaining: snapshot.creditsRemaining,
+  };
+}

package/src/capacity/wham.ts

@@ -0,0 +1,84 @@
+import type { CapacityWindow } from "./types.js";
+
+type WhamUsageSnapshot = {
+  windows: CapacityWindow[];
+  creditsRemaining: number | null;
+};
+
+type UnknownRecord = Record<string, unknown>;
+
+function record(value: unknown): UnknownRecord | null {
+  return value !== null && typeof value === "object" && !Array.isArray(value)
+    ? (value as UnknownRecord)
+    : null;
+}
+
+function finiteNumber(value: unknown): number | null {
+  return typeof value === "number" && Number.isFinite(value) ? value : null;
+}
+
+function nonEmptyText(value: unknown): string | null {
+  return typeof value === "string" && value.length > 0 ? value : null;
+}
+
+export function resetTime(value: unknown): string | null {
+  const seconds = finiteNumber(value);
+  if (seconds !== null) return new Date(seconds * 1000).toISOString();
+  if (typeof value === "string" && !Number.isNaN(Date.parse(value)))
+    return new Date(value).toISOString();
+  return null;
+}
+
+export function safeIdentifier(value: unknown): string | null {
+  const candidate = nonEmptyText(value);
+  if (!candidate || !/^[a-z][a-z0-9_-]{0,63}$/i.test(candidate)) return null;
+  if (/(?:account|token|secret|key)[_-]?\d{6,}/i.test(candidate)) return null;
+  return candidate;
+}
+
+export function toRateWindow(value: unknown, id: string, label: string): CapacityWindow | null {
+  const input = record(value);
+  if (!input) return null;
+  const used = finiteNumber(input.used_percent);
+  const seconds = finiteNumber(input.limit_window_seconds);
+  return {
+    id,
+    label,
+    durationMinutes: seconds === null ? null : seconds / 60,
+    usedPercent: used,
+    resetsAt: resetTime(input.reset_at),
+  };
+}
+
+function extraWindows(value: unknown): CapacityWindow[] {
+  if (!Array.isArray(value)) return [];
+  return value.flatMap((entry, index) => {
+    const limit = record(entry);
+    if (!limit) return [];
+    const scope = safeIdentifier(limit.limit_name) ?? `extra-${index + 1}`;
+    const windows = record(limit.rate_limit) ?? limit;
+    return [
+      toRateWindow(windows.primary_window, `${scope}:primary`, `${scope} primary`),
+      toRateWindow(windows.secondary_window, `${scope}:secondary`, `${scope} secondary`),
+    ].filter((window): window is CapacityWindow => window !== null);
+  });
+}
+
+/**
+ * Parses the chatgpt.com backend wham/usage payload shared by every
+ * OAuth-backed OpenAI consumer (codex harness and pi login) into generic
+ * capacity windows plus the credit balance.
+ */
+export function parseWhamUsage(raw: unknown): WhamUsageSnapshot {
+  const response = record(raw) ?? {};
+  const limits = record(response.rate_limit) ?? {};
+  const credits = record(response.credits) ?? {};
+  return {
+    windows: [
+      toRateWindow(limits.primary_window, "session", "Session"),
+      toRateWindow(limits.secondary_window, "weekly", "Weekly"),
+      ...extraWindows(response.additional_rate_limits),
+    ].filter((window): window is CapacityWindow => window !== null),
+    creditsRemaining: finiteNumber(credits.balance),
+  };
+}

package/src/index.ts

@@ -1,9 +1,16 @@
 export { AgentManager, AgentNotRunningError } from "./AgentManager.js";
-export { getCodexCapacityReport, getZaiCapacityReport } from "./capacity/index.js";
+export {
+  getClaudeCapacityReport,
+  getCodexCapacityReport,
+  getOpenAiCapacityReport,
+  getZaiCapacityReport,
+} from "./capacity/index.js";
 export type {
+  ClaudeCapacityOptions,
   CapacityProbeOptions,
   CapacityReport,
   CapacityWindow,
+  OpenAiCapacityOptions,
   ZaiCapacityOptions,
 } from "./capacity/index.js";
 export {
@@ -29,7 +36,9 @@ export { ClaudeCodeAdapter } from "./providers/claude/ClaudeCodeAdapter.js";
 export { CodexAdapter } from "./providers/codex/CodexAdapter.js";
 export { CopilotAdapter } from "./providers/copilot/CopilotAdapter.js";
 export { GeminiCliAdapter } from "./providers/gemini/GeminiCliAdapter.js";
-export { GrokCliAdapter } from "./adapters/GrokCliAdapter.js";
+export { GrokCliAdapter } from "./providers/grok/GrokCliAdapter.js";
+export { AntigravityCliAdapter } from "./adapters/AntigravityCliAdapter.js";
+export { KiroAdapter } from "./adapters/KiroAdapter.js";
 export { OpenCodeAdapter } from "./providers/opencode/OpenCodeAdapter.js";
 export { PiAdapter } from "./providers/pi/PiAdapter.js";
 export { AgentStatus } from "./adapters/AgentAdapter.js";

package/src/providers/claude/ClaudeCodeAdapter.ts

@@ -138,31 +138,36 @@ export class ClaudeCodeAdapter implements AgentAdapter {
     const summaries: SessionSummary[] = [];
 
     for (const { filePath, defaultCwd } of candidates) {
-      const session = this.parser.readSession(filePath, defaultCwd);
-      if (!session) continue;
-
-      // Drop sessions whose JSONL had no parseable conversation entries.
-      // readSession is permissive (returns a shell record even when every
-      // line fails to parse); listSessions needs at least one real entry
-      // so we don't surface garbage files.
-      if (!session.lastEntryType) continue;
-
-      const recordedCwd = session.lastCwd || defaultCwd;
-      if (filterCwd !== undefined && recordedCwd !== filterCwd) continue;
-
-      const stat = safeStat(filePath);
-
-      summaries.push({
-        type: "claude",
-        sessionId: session.sessionId,
-        cwd: recordedCwd,
-        firstUserMessage: session.firstUserMessage || "",
-        lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
-        startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
-        sessionFilePath: filePath,
-      });
+      const summary = this.toSessionSummary(filePath, defaultCwd);
+      if (!summary) continue;
+      if (filterCwd !== undefined && summary.cwd !== filterCwd) continue;
+      summaries.push(summary);
     }
 
     return summaries;
   }
+
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    return this.createLocator()
+      .findHistoricalSessionFilesById(sessionId)
+      .map(({ filePath, defaultCwd }) => this.toSessionSummary(filePath, defaultCwd))
+      .filter((summary): summary is SessionSummary => summary?.sessionId === sessionId);
+  }
+
+  private toSessionSummary(filePath: string, defaultCwd: string): SessionSummary | null {
+    const session = this.parser.readSession(filePath, defaultCwd);
+    if (!session?.lastEntryType) return null;
+
+    const recordedCwd = session.lastCwd || defaultCwd;
+    const stat = safeStat(filePath);
+    return {
+      type: "claude",
+      sessionId: session.sessionId,
+      cwd: recordedCwd,
+      firstUserMessage: session.firstUserMessage || "",
+      lastActive: session.lastActive ?? stat?.mtime ?? new Date(),
+      startedAt: session.sessionStart ?? stat?.birthtime ?? stat?.mtime ?? new Date(),
+      sessionFilePath: filePath,
+    };
+  }
 }

package/src/providers/claude/ClaudeSessionLocator.ts

@@ -6,6 +6,7 @@ import { matchProcessesToSessions, type MatchResult } from "../../utils/matching
 import {
   batchGetSessionFileBirthtimes,
   isDirectory,
+  isSafePathSegment,
   listJsonl,
   safeReaddir,
   safeStat,
@@ -130,6 +131,25 @@ export class ClaudeSessionLocator {
     return out;
   }
 
+  findHistoricalSessionFilesById(
+    sessionId: string,
+  ): Array<{ filePath: string; defaultCwd: string }> {
+    if (!isSafePathSegment(sessionId) || !isDirectory(this.projectsDir)) {
+      return [];
+    }
+
+    const matches: Array<{ filePath: string; defaultCwd: string }> = [];
+    for (const dirName of safeReaddir(this.projectsDir)) {
+      const projectDir = path.join(this.projectsDir, dirName);
+      if (!isDirectory(projectDir)) continue;
+
+      const filePath = path.join(projectDir, `${sessionId}.jsonl`);
+      if (!safeStat(filePath)?.isFile()) continue;
+      matches.push({ filePath, defaultCwd: dirName.replace(/-/g, "/") });
+    }
+    return matches;
+  }
+
   /**
    * Derive the Claude Code project directory for a given CWD.
    *

package/src/providers/codex/CodexAdapter.ts

@@ -95,6 +95,14 @@ export class CodexAdapter implements AgentAdapter {
     return summaries;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    const sessionFile = this.createLocator().findSessionFileById(sessionId);
+    if (!sessionFile) return [];
+
+    const summary = this.parser.fileToSessionSummary(sessionFile.filePath);
+    return summary?.sessionId === sessionId ? [summary] : [];
+  }
+
   private async getCodexProcesses(context?: AgentDetectionContext): Promise<ProcessInfo[]> {
     const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
     const relevant = filterByProcessNames(snapshot, this.processNames);

package/src/providers/copilot/CopilotAdapter.ts

@@ -29,7 +29,7 @@ import {
 import { AgentRegistry, type RegistryEntry } from "../../utils/AgentRegistry.js";
 import { CopilotAgentMapper } from "./CopilotAgentMapper.js";
 import { CopilotSessionLocator } from "./CopilotSessionLocator.js";
-import { CopilotSessionParser } from "./CopilotSessionParser.js";
+import { CopilotSessionParser, type CopilotSession } from "./CopilotSessionParser.js";
 
 export interface CopilotAdapterOptions {
   sessionStateDir?: string;
@@ -111,20 +111,36 @@ export class CopilotAdapter implements AgentAdapter {
       if (!session) continue;
       if (opts?.cwd !== undefined && session.projectPath !== opts.cwd) continue;
 
-      summaries.push({
-        type: this.type,
-        sessionId: session.sessionId,
-        cwd: session.projectPath,
-        firstUserMessage: session.firstUserMessage,
-        lastActive: session.lastActive,
-        startedAt: session.sessionStart,
-        sessionFilePath: session.eventsFilePath,
-      });
+      summaries.push(this.toSessionSummary(session));
     }
 
     return summaries;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    const match = this.locator.findSessionDirById(sessionId);
+    if (match) {
+      const session = this.parser.readSessionDir(match.sessionDir, match.sessionId);
+      if (session?.sessionId === sessionId) {
+        return [this.toSessionSummary(session)];
+      }
+    }
+
+    return (await this.listSessions()).filter((session) => session.sessionId === sessionId);
+  }
+
+  private toSessionSummary(session: CopilotSession): SessionSummary {
+    return {
+      type: this.type,
+      sessionId: session.sessionId,
+      cwd: session.projectPath,
+      firstUserMessage: session.firstUserMessage,
+      lastActive: session.lastActive,
+      startedAt: session.sessionStart,
+      sessionFilePath: session.eventsFilePath,
+    };
+  }
+
   private applyWrapperRegistryName(
     agent: AgentInfo,
     processInfo: ProcessInfo,

package/src/providers/copilot/CopilotSessionLocator.ts

@@ -1,5 +1,5 @@
 import * as path from "path";
-import { isDirectory, safeReaddir } from "../../utils/session.js";
+import { isDirectory, isSafePathSegment, safeReaddir } from "../../utils/session.js";
 
 export interface CopilotLock {
   sessionDir: string;
@@ -39,6 +39,12 @@ export class CopilotSessionLocator {
     return sessionDirs;
   }
 
+  findSessionDirById(sessionId: string): CopilotSessionDir | null {
+    if (!isSafePathSegment(sessionId)) return null;
+    const sessionDir = path.join(this.sessionStateDir, sessionId);
+    return isDirectory(sessionDir) ? { sessionDir, sessionId } : null;
+  }
+
   discoverActiveLocks(): CopilotLock[] {
     const locks: CopilotLock[] = [];
     for (const { sessionDir, sessionId } of this.listSessionDirs()) {

package/src/providers/gemini/GeminiCliAdapter.ts

@@ -108,6 +108,14 @@ export class GeminiCliAdapter implements AgentAdapter {
     return summaries;
   }
 
+  async findSessionsById(sessionId: string): Promise<SessionSummary[]> {
+    for (const filePath of this.locator.discoverHistoricalSessionFiles()) {
+      const summary = this.parser.fileToSessionSummary(filePath);
+      if (summary?.sessionId === sessionId) return [summary];
+    }
+    return [];
+  }
+
   private async getGeminiProcesses(context?: AgentDetectionContext): Promise<ProcessInfo[]> {
     const snapshot = context?.processes ?? (await captureProcessSnapshot(this.processNames));
     const relevant = filterByProcessNames(snapshot, this.processNames);