@tonyclaw/agent-inspector 3.1.20 → 3.1.21

package/src/proxy/ecosystemTasks.ts

@@ -14,6 +14,7 @@ import {
   signalProcessTree,
   type CommandSpec,
 } from "./platformCommands";
+import { DEFAULT_RUNTIME_BUDGET_POLICY } from "../lib/resourceLimits";
 
 const MAX_TASKS = 50;
 const OUTPUT_LIMIT = 40_000;
@@ -34,6 +35,12 @@ const activeTasks = new Map<string, ActiveTask>();
 let acceptingTasks = true;
 let shutdownForceTimer: ReturnType<typeof setTimeout> | null = null;
 
+function activeTaskLimit(): number {
+  const configured = Number(process.env["ECOSYSTEM_TASK_ACTIVE_LIMIT"]);
+  if (Number.isSafeInteger(configured) && configured > 0) return configured;
+  return DEFAULT_RUNTIME_BUDGET_POLICY.queues.backgroundWorkers;
+}
+
 function nowIso(): string {
   return new Date().toISOString();
 }
@@ -258,6 +265,7 @@ export function startEcosystemTask(
   action: EcosystemTaskAction,
 ): EcosystemTask | null {
   if (!acceptingTasks) return null;
+  if (activeTasks.size >= activeTaskLimit()) return null;
   if (action === "recipe") return null;
   const definition =
     action === "runner-presets"
@@ -291,6 +299,7 @@ export function startEcosystemTask(
 
 export function startEcosystemRecipeTask(recipeId: string): EcosystemTask | null {
   if (!acceptingTasks) return null;
+  if (activeTasks.size >= activeTaskLimit()) return null;
   const recipe = findEcosystemRecipe(recipeId);
   if (recipe === null) return null;
   if (!recipe.runnable) return null;
@@ -367,6 +376,7 @@ export function _startEcosystemTaskForTests(
   timeoutMs = RECIPE_TIMEOUT_MS,
 ): EcosystemTask | null {
   if (!acceptingTasks) return null;
+  if (activeTasks.size >= activeTaskLimit()) return null;
   const task: EcosystemTask = {
     id: randomUUID(),
     packageId: "test-package",
@@ -393,3 +403,13 @@ export function _resetEcosystemTasksForTests(): void {
   activeTasks.clear();
   acceptingTasks = true;
 }
+
+export function _getEcosystemTaskAdmissionHealthForTests(): {
+  activeTasks: number;
+  activeTaskLimit: number;
+} {
+  return {
+    activeTasks: activeTasks.size,
+    activeTaskLimit: activeTaskLimit(),
+  };
+}

package/src/proxy/handler.ts

@@ -40,7 +40,7 @@ import {
   getRuntimeAdmissionState,
   type RuntimeRequestLease,
 } from "./runtimeAdmission";
-import { resourceLimitResponse } from "../lib/resourceLimits";
+import { DEFAULT_RUNTIME_BUDGET_POLICY, resourceLimitResponse } from "../lib/resourceLimits";
 import {
   buildUpstreamUrl,
   describeApiRoute,
@@ -592,10 +592,19 @@ async function handleAdmittedProxy(req: Request): Promise<Response> {
         body: bodyToForward,
         signal: req.signal,
       },
-      { allowLoopback: ALLOW_LOOPBACK },
+      {
+        allowLoopback: ALLOW_LOOPBACK,
+        deadlineMs: DEFAULT_RUNTIME_BUDGET_POLICY.upstream.fetchDeadlineMs,
+        responseBytes: DEFAULT_RUNTIME_BUDGET_POLICY.upstream.fetchResponseBytes,
+      },
     );
     if (!fetchResult.ok) {
-      const status = fetchResult.kind === "network-policy" ? STATUS_FORBIDDEN : STATUS_BAD_GATEWAY;
+      const status =
+        fetchResult.kind === "network-policy"
+          ? STATUS_FORBIDDEN
+          : fetchResult.kind === "resource-limit"
+            ? STATUS_PAYLOAD_TOO_LARGE
+            : STATUS_BAD_GATEWAY;
       logger.warn(`[handler] Safe fetch blocked ${upstreamUrl}: ${fetchResult.reason}`);
       log.elapsedMs = Date.now() - startTime;
       log.responseStatus = status;
@@ -605,7 +614,11 @@ async function handleAdmittedProxy(req: Request): Promise<Response> {
       return new Response(
         fetchResult.kind === "network-policy"
           ? "Forbidden: upstream URL is not permitted"
-          : "Proxy error: upstream redirects are not permitted",
+          : fetchResult.kind === "resource-limit"
+            ? "Proxy error: upstream response exceeded configured limits"
+            : fetchResult.kind === "timeout"
+              ? "Proxy error: upstream request timed out"
+              : "Proxy error: upstream redirects are not permitted",
         { status },
       );
     }

package/src/proxy/identityProxy.ts

@@ -585,9 +585,10 @@ function normalizedHostname(value: string): string | null {
 }
 
 function isLoopbackHostname(hostname: string): boolean {
-  if (hostname === "localhost" || hostname === "::1") return true;
-  if (isIP(hostname) !== 4) return false;
-  return hostname.split(".", 1)[0] === "127";
+  const normalized = hostname.toLowerCase().replace(/^\[|]$/g, "");
+  if (normalized === "localhost" || normalized === "::1") return true;
+  if (isIP(normalized) !== 4) return false;
+  return normalized.split(".", 1)[0] === "127";
 }
 
 export type UiOriginAllowlist = {
@@ -669,15 +670,31 @@ function normalizedRequestOrigin(origin: string): string | null {
   }
 }
 
+function parsedRequestOrigin(origin: string): URL | null {
+  const normalized = normalizedRequestOrigin(origin);
+  if (normalized === null) return null;
+  return new URL(normalized);
+}
+
+function isSameOrLoopbackAliasOrigin(left: URL, right: URL): boolean {
+  if (left.origin === right.origin) return true;
+  return (
+    left.protocol === right.protocol &&
+    left.port === right.port &&
+    isLoopbackHostname(left.hostname) &&
+    isLoopbackHostname(right.hostname)
+  );
+}
+
 function isSameRequestOrigin(
   origin: string,
   host: string | undefined,
   publicOrigin?: string,
 ): boolean {
-  const parsedOrigin = normalizedRequestOrigin(origin);
+  const parsedOrigin = parsedRequestOrigin(origin);
   if (parsedOrigin === null) return false;
-  const expected = normalizedRequestOrigin(publicOrigin ?? `http://${host ?? "localhost"}`);
-  return expected !== null && parsedOrigin === expected;
+  const expected = parsedRequestOrigin(publicOrigin ?? `http://${host ?? "localhost"}`);
+  return expected !== null && isSameOrLoopbackAliasOrigin(parsedOrigin, expected);
 }
 
 function matchedUiOrigin(
@@ -797,24 +814,27 @@ export function isBrowserMutationAllowed(input: {
   const fetchSite = input.secFetchSite?.toLowerCase();
   const browserRequest = input.origin !== undefined || fetchSite !== undefined;
   if (!browserRequest) return true;
+  const sameOrigin =
+    input.origin !== undefined
+      ? isSameRequestOrigin(input.origin, input.host, input.publicOrigin)
+      : false;
   if (isModelProxyPath(pathname)) {
-    if (fetchSite !== undefined && fetchSite !== "same-origin") return false;
-    if (
-      input.origin !== undefined &&
-      !isSameRequestOrigin(input.origin, input.host, input.publicOrigin)
-    ) {
+    if (fetchSite !== undefined && fetchSite !== "same-origin" && !sameOrigin) return false;
+    if (input.origin !== undefined && !sameOrigin) {
       return false;
     }
     return input.csrfToken === "1";
   }
   const allowedOrigin = matchedUiOrigin(input.origin, input.allowedUiOrigins);
-  if (fetchSite !== undefined && fetchSite !== "same-origin" && allowedOrigin === null)
+  if (
+    fetchSite !== undefined &&
+    fetchSite !== "same-origin" &&
+    !sameOrigin &&
+    allowedOrigin === null
+  )
     return false;
   if (input.origin !== undefined) {
-    if (
-      !isSameRequestOrigin(input.origin, input.host, input.publicOrigin) &&
-      allowedOrigin === null
-    ) {
+    if (!sameOrigin && allowedOrigin === null) {
       return false;
     }
   }

package/src/proxy/logIndex.ts

@@ -17,6 +17,7 @@ import { extractToolTraceEvents } from "../lib/toolTrace";
 import { extractStopReason } from "../lib/stopReason";
 import {
   getSqliteLogIndexMaxId,
+  listSqliteLogCursorEntries,
   replaceSqliteLogIndexEntries,
   syncSqliteLogIndexEntries,
   upsertSqliteLogIndexEntry,
@@ -159,9 +160,36 @@ function createEmptyIndex(): LogIndex {
   };
 }
 
+function createIndexFromEntries(entries: readonly LogIndexEntry[]): LogIndex {
+  const index = createEmptyIndex();
+  for (const entry of entries) {
+    index.entries[entry.id] = entry;
+    index.maxId = Math.max(index.maxId, entry.id);
+  }
+  return index;
+}
+
+function sqliteProjectionReferencesExistingLedgers(entries: readonly LogIndexEntry[]): boolean {
+  const logDir = resolveLogDir();
+  for (const entry of entries) {
+    if (!entry.file.endsWith(".jsonl")) return false;
+    if (!existsSync(join(logDir, entry.file))) return false;
+  }
+  return true;
+}
+
 export async function loadIndex(): Promise<LogIndex> {
   if (cachedIndex !== null) return cachedIndex;
-  // logs.idx and inspector.sqlite are projections only. A cold process always rebuilds from
+  const sqliteEntries = await listSqliteLogCursorEntries({});
+  if (sqliteEntries !== null) {
+    if (sqliteProjectionReferencesExistingLedgers(sqliteEntries)) {
+      cachedIndex = createIndexFromEntries(sqliteEntries);
+      allocatedMaxId = Math.max(allocatedMaxId, cachedIndex.maxId);
+      return cachedIndex;
+    }
+    logger.warn("[logIndex] SQLite projection references missing ledgers; rebuilding from JSONL");
+  }
+  // logs.idx remains a legacy fallback projection only. If SQLite is unavailable, rebuild from
   // authoritative JSONL rather than allowing a stale, conflicting, or higher derived row to win.
   return await rebuildIndex();
 }
@@ -212,9 +240,11 @@ export async function addToIndex(
   if (id > index.maxId) {
     index.maxId = id;
   }
-  void upsertSqliteLogIndexEntry(entry);
-  // Defer disk writes to reduce I/O - flush after a batch of updates
-  scheduleIndexFlush();
+  const sqliteUpdated = await upsertSqliteLogIndexEntry(entry);
+  if (!sqliteUpdated) {
+    // Legacy fallback only: defer disk writes to reduce I/O when SQLite is unavailable.
+    scheduleIndexFlush();
+  }
 }
 
 /**
@@ -232,8 +262,8 @@ export async function updateLogIndexEntryMetadata(log: CapturedLog): Promise<voi
     ...createLogIndexEntryMetadata(log),
   };
   index.entries[log.id] = updated;
-  await upsertSqliteLogIndexEntry(updated);
-  scheduleIndexFlush();
+  const sqliteUpdated = await upsertSqliteLogIndexEntry(updated);
+  if (!sqliteUpdated) scheduleIndexFlush();
 }
 
 // Batch writes: collect pending flushes and write once
@@ -243,6 +273,7 @@ let indexFlushTimeout: ReturnType<typeof setTimeout> | null = null;
 async function flushIndexAsync(): Promise<void> {
   indexFlushScheduled = false;
   indexFlushTimeout = null;
+  if ((await listSqliteLogCursorEntries({})) !== null) return;
   const index = await loadIndex();
   await saveIndex(index);
 }
@@ -261,6 +292,7 @@ export async function flushIndex(): Promise<void> {
     indexFlushTimeout = null;
   }
   indexFlushScheduled = false;
+  if ((await listSqliteLogCursorEntries({})) !== null) return;
   const index = await loadIndex();
   await saveIndex(index);
 }

package/src/proxy/logger.ts

@@ -61,6 +61,10 @@ function getInspectorLogPath(): string {
   return path.join(getDataDir(), "logs", "inspector.log");
 }
 
+export function resolveApplicationLogPath(): string {
+  return getInspectorLogPath();
+}
+
 function readBoundedInteger(
   name: string,
   fallback: number,

package/src/proxy/rawStreamCapture.ts

@@ -4,6 +4,11 @@ import { randomUUID } from "node:crypto";
 import { open, unlink, type FileHandle } from "node:fs/promises";
 import { join } from "node:path";
 import { getDataDir } from "./dataDir";
+import {
+  DEFAULT_RUNTIME_BUDGET_POLICY,
+  type RuntimeBudgetPolicy,
+  runtimeBudgetPolicySnapshot,
+} from "~/lib/resourceLimits";
 import {
   ensurePrivateDirectorySync,
   PRIVATE_FILE_MODE,
@@ -34,6 +39,16 @@ export type RawStreamCaptureOptions = {
   globalBudget?: RawStreamObservationBudget;
 };
 
+export function rawStreamCaptureOptionsFromBudgetPolicy(
+  policy: RuntimeBudgetPolicy = DEFAULT_RUNTIME_BUDGET_POLICY,
+): Pick<RawStreamCaptureOptions, "queueMaxMessages" | "queueMaxBytes"> {
+  const snapshot = runtimeBudgetPolicySnapshot(policy);
+  return {
+    queueMaxMessages: snapshot.queues.rawStreamMessages,
+    queueMaxBytes: snapshot.queues.rawStreamBytes,
+  };
+}
+
 export type RawStreamSource =
   | {
       type: "memory";
@@ -108,7 +123,7 @@ const globalObservationBudget = new RawStreamObservationBudget(
   ),
 );
 
-function getRawStreamDir(): string {
+export function getRawStreamDir(): string {
   return join(getDataDir(), "raw-streams");
 }
 

package/src/proxy/runtimeHealth.ts

@@ -8,6 +8,7 @@ import { isSqliteLogIndexReady } from "./sqliteLogIndex";
 import { recoverCapturedLogStorage } from "./jsonlRecovery";
 import { resolveLogDir } from "./logger";
 import { loadIndex } from "./logIndex";
+import { getSessionRuntimeQueueHealth } from "./sessionRuntime";
 
 const DEFAULT_CACHE_MS = 2_000;
 const DEFAULT_MIN_DISK_HEADROOM_BYTES = 256 * 1024 * 1024;
@@ -86,6 +87,7 @@ function finalizerChecks(): {
   queue: ReadinessCheckLevel;
 } {
   const health = getFinalizerRuntimeHealth();
+  const sessionQueue = getSessionRuntimeQueueHealth();
   const runtimeArtifactMissing = health.runtime !== "inline" && !health.artifactAvailable;
   const initializedWorkerMissing =
     health.runtime === "worker" &&
@@ -104,9 +106,9 @@ function finalizerChecks(): {
   );
   const warningThreshold = Math.max(1, Math.floor(queueLimit * 0.8));
   const queue =
-    health.pendingJobs >= queueLimit
+    health.pendingJobs + sessionQueue.queuedTasks >= queueLimit
       ? "unavailable"
-      : health.pendingJobs >= warningThreshold
+      : health.pendingJobs + sessionQueue.queuedTasks >= warningThreshold
         ? "degraded"
         : "ok";
   return { workers, queue };

package/src/proxy/runtimeMetrics.ts

@@ -0,0 +1,149 @@
+import { DEFAULT_RUNTIME_BUDGET_POLICY } from "../lib/resourceLimits";
+import { getFinalizerRuntimeHealth } from "./logFinalizer";
+import { getRuntimeAdmissionState } from "./runtimeAdmission";
+import { getRuntimeReadiness } from "./runtimeHealth";
+import { getSessionRuntimeQueueHealth } from "./sessionRuntime";
+import { listSqliteLogCursorEntries } from "./sqliteLogIndex";
+import { getStorageLifecycleInventory, getLastStorageLifecycleGcResult } from "./storageLifecycle";
+
+export const PERFORMANCE_METRICS_SCHEMA = "agent-inspector.performance-metrics/v1";
+export const OPERATIONAL_METRICS_SCHEMA = "agent-inspector.operational-metrics/v1";
+
+export type SseRuntimeMetrics = {
+  activeClients: number;
+  capacity: number;
+};
+
+export type SafeOperationalMetrics = {
+  schema: typeof PERFORMANCE_METRICS_SCHEMA;
+  activeUpstream: number;
+  queueDepth: number;
+  queueBytes: number;
+  incompleteCaptures: number;
+  finalizerLagMs: number;
+  persistenceLagMs: number;
+  activeLeases: number;
+  runtime: {
+    schema: typeof OPERATIONAL_METRICS_SCHEMA;
+    collectedAt: string;
+    readiness: Awaited<ReturnType<typeof getRuntimeReadiness>>;
+    requests: {
+      activeProxyRequests: number;
+      proxyCapacity: number;
+      acceptingRequests: boolean;
+    };
+    limits: typeof DEFAULT_RUNTIME_BUDGET_POLICY;
+    queues: {
+      finalizerPendingJobs: number;
+      sessionQueuedTasks: number;
+      sessionActiveQueues: number;
+      sessionQueueLimit: number;
+    };
+    workers: ReturnType<typeof getFinalizerRuntimeHealth>;
+    storage: {
+      totalFiles: number;
+      totalBytes: number;
+      reclaimableBytes: number;
+      lastGc: {
+        checkedAt: string;
+        filesDeleted: number;
+        bytesDeleted: number;
+        errors: number;
+      } | null;
+    };
+    sse: SseRuntimeMetrics;
+    truncation: {
+      captureIncompleteLogs: number;
+      droppedChunks: number;
+      droppedBytes: number;
+      source: "sqlite" | "unavailable";
+    };
+  };
+};
+
+async function getTruncationMetrics(): Promise<SafeOperationalMetrics["runtime"]["truncation"]> {
+  const entries = await listSqliteLogCursorEntries({});
+  if (entries === null) {
+    return {
+      captureIncompleteLogs: 0,
+      droppedChunks: 0,
+      droppedBytes: 0,
+      source: "unavailable",
+    };
+  }
+
+  return {
+    captureIncompleteLogs: entries.filter((entry) => entry.summary?.captureIncomplete === true)
+      .length,
+    droppedChunks: entries.reduce((sum, entry) => sum + (entry.summary?.droppedChunks ?? 0), 0),
+    droppedBytes: entries.reduce((sum, entry) => sum + (entry.summary?.droppedBytes ?? 0), 0),
+    source: "sqlite",
+  };
+}
+
+export async function getSafeOperationalMetrics(
+  sse: SseRuntimeMetrics,
+): Promise<SafeOperationalMetrics> {
+  const [readiness, truncation] = await Promise.all([
+    getRuntimeReadiness(),
+    getTruncationMetrics(),
+  ]);
+  const admission = getRuntimeAdmissionState();
+  const workers = getFinalizerRuntimeHealth();
+  const sessionQueue = getSessionRuntimeQueueHealth();
+  const storageInventory = getStorageLifecycleInventory();
+  const lastGc = getLastStorageLifecycleGcResult();
+  const reclaimableBytes = storageInventory.artifacts
+    .filter(
+      (artifact) =>
+        artifact.cleanupBehavior === "retention-gc" ||
+        artifact.cleanupBehavior === "orphan-reclaim",
+    )
+    .reduce((sum, artifact) => sum + artifact.bytes, 0);
+  const queueDepth = workers.pendingJobs + sessionQueue.queuedTasks;
+
+  return {
+    schema: PERFORMANCE_METRICS_SCHEMA,
+    activeUpstream: admission.activeRequests,
+    queueDepth,
+    queueBytes: 0,
+    incompleteCaptures: truncation.captureIncompleteLogs,
+    finalizerLagMs: 0,
+    persistenceLagMs: 0,
+    activeLeases: sse.activeClients,
+    runtime: {
+      schema: OPERATIONAL_METRICS_SCHEMA,
+      collectedAt: new Date().toISOString(),
+      readiness,
+      requests: {
+        activeProxyRequests: admission.activeRequests,
+        proxyCapacity: admission.capacity,
+        acceptingRequests: admission.acceptingRequests,
+      },
+      limits: DEFAULT_RUNTIME_BUDGET_POLICY,
+      queues: {
+        finalizerPendingJobs: workers.pendingJobs,
+        sessionQueuedTasks: sessionQueue.queuedTasks,
+        sessionActiveQueues: sessionQueue.activeQueues,
+        sessionQueueLimit: sessionQueue.queueLimit,
+      },
+      workers,
+      storage: {
+        totalFiles: storageInventory.totalFiles,
+        totalBytes: storageInventory.totalBytes,
+        reclaimableBytes,
+        lastGc:
+          lastGc === null
+            ? null
+            : {
+                checkedAt: lastGc.checkedAt,
+                filesDeleted: lastGc.filesDeleted,
+                bytesDeleted: lastGc.bytesDeleted,
+                errors: lastGc.errors.length,
+              },
+      },
+      sse,
+      truncation,
+    },
+  };
+}

package/src/proxy/sessionRuntime.ts

@@ -1,5 +1,6 @@
 import { logger } from "./logger";
 import { executeFinalizeLogJob, type FinalizeLogJob } from "./logFinalizer";
+import { DEFAULT_RUNTIME_BUDGET_POLICY } from "../lib/resourceLimits";
 import {
   getLogSessionId,
   markSessionTaskFinished,
@@ -14,11 +15,25 @@ export type SessionTaskName = "finalize-log";
 type SessionTask<T> = () => Promise<T> | T;
 
 const queues = new Map<string, Promise<void>>();
+let queuedTaskCount = 0;
+
+export class SessionTaskQueueRejectedError extends Error {
+  constructor(limit: number) {
+    super(`Session task queue is full; limit=${String(limit)}`);
+    this.name = "SessionTaskQueueRejectedError";
+  }
+}
 
 function queueKeyForSession(sessionId: string | null): string {
   return sessionId ?? UNASSIGNED_SESSION_QUEUE;
 }
 
+function resolveSessionTaskQueueLimit(): number {
+  const configured = Number(process.env["SESSION_TASK_QUEUE_LIMIT"]);
+  if (Number.isSafeInteger(configured) && configured > 0) return configured;
+  return DEFAULT_RUNTIME_BUDGET_POLICY.queues.finalizerJobs;
+}
+
 function errorMessage(err: unknown): string {
   return err instanceof Error ? err.message : String(err);
 }
@@ -46,9 +61,19 @@ export function enqueueSessionTask<T>(
   taskName: SessionTaskName,
   task: SessionTask<T>,
 ): Promise<T> {
+  const queueLimit = resolveSessionTaskQueueLimit();
+  if (queuedTaskCount >= queueLimit) {
+    logger.warn(
+      `[sessionRuntime] Rejecting ${taskName} for session ${sessionId ?? "unassigned"}: ` +
+        `queue full (${String(queuedTaskCount)}/${String(queueLimit)})`,
+    );
+    return Promise.reject(new SessionTaskQueueRejectedError(queueLimit));
+  }
+
   const queueKey = queueKeyForSession(sessionId);
   const previous = queues.get(queueKey) ?? Promise.resolve();
 
+  queuedTaskCount += 1;
   markSessionTaskQueued(sessionId);
 
   const current = previous
@@ -61,6 +86,7 @@ export function enqueueSessionTask<T>(
 
   queues.set(queueKey, settled);
   void settled.then(() => {
+    queuedTaskCount = Math.max(0, queuedTaskCount - 1);
     if (queues.get(queueKey) === settled) {
       queues.delete(queueKey);
     }
@@ -81,3 +107,15 @@ export async function flushSessionTasks(): Promise<void> {
     await Promise.all([...queues.values()]);
   }
 }
+
+export function getSessionRuntimeQueueHealth(): {
+  activeQueues: number;
+  queuedTasks: number;
+  queueLimit: number;
+} {
+  return {
+    activeQueues: queues.size,
+    queuedTasks: queuedTaskCount,
+    queueLimit: resolveSessionTaskQueueLimit(),
+  };
+}

package/src/proxy/sqliteLogIndex.ts

@@ -627,6 +627,57 @@ export async function upsertSqliteLogIndexEntry(entry: LogIndexEntry): Promise<b
   return runPrepared(state.db, UPSERT_SQL, entryParams(entry));
 }
 
+export type SqliteLogCursorEntryFilters = {
+  sessionId?: string;
+  model?: string;
+  clientPid?: number;
+};
+
+function sqliteCursorWhereClause(filters: SqliteLogCursorEntryFilters): {
+  sql: string;
+  params: unknown[];
+} {
+  const clauses: string[] = [];
+  const params: unknown[] = [];
+  if (filters.sessionId !== undefined) {
+    clauses.push("session_id = ?");
+    params.push(filters.sessionId);
+  }
+  if (filters.model !== undefined) {
+    clauses.push("model = ?");
+    params.push(filters.model);
+  }
+  if (filters.clientPid !== undefined) {
+    clauses.push("client_pid = ?");
+    params.push(filters.clientPid);
+  }
+  return {
+    sql: clauses.length === 0 ? "" : ` WHERE ${clauses.join(" AND ")}`,
+    params,
+  };
+}
+
+export async function listSqliteLogCursorEntries(
+  filters: SqliteLogCursorEntryFilters,
+): Promise<LogIndexEntry[] | null> {
+  const state = await getSqliteState();
+  if (state.status !== "ready") return null;
+  const where = sqliteCursorWhereClause(filters);
+  const rows = allPrepared(
+    state.db,
+    `SELECT * FROM log_index${where.sql} ORDER BY id ASC`,
+    where.params,
+  );
+  if (rows === null) return null;
+  const entries: LogIndexEntry[] = [];
+  for (const row of rows) {
+    const entry = entryFromRow(row);
+    if (entry === null || entry.summary === undefined) return null;
+    entries.push(entry);
+  }
+  return entries;
+}
+
 export async function syncSqliteLogIndexEntries(
   entries: readonly LogIndexEntry[],
 ): Promise<boolean> {