@moretea-labs/forge 1.6.0 → 1.7.1

package/src/runtime/plugins/browser-runtime.ts

@@ -0,0 +1,193 @@
+import { AssistantPluginError } from './errors';
+import type { AssistantPluginActionExecutionInput } from './types';
+import {
+  validateBrowserTransaction,
+  type BrowserActionReplaySafety,
+  type BrowserForegroundRequirement,
+  type BrowserProviderCapability,
+  type BrowserTargetIdentity,
+  type BrowserTransaction,
+} from './browser-runtime-contract';
+import {
+  BrowserProviderRegistry,
+  BrowserProviderUnavailableBeforeActionError,
+  type BrowserRuntimeProvider,
+} from './browser-provider-registry';
+
+export const ALL_BROWSER_PROVIDER_CAPABILITIES = [
+  'dom.read',
+  'dom.interact',
+  'browser.internal_resources',
+  'browser.screenshot',
+  'browser.trusted_input',
+  'browser.foreground',
+  'browser.transaction',
+  'browser.persistent_handle',
+] as const satisfies readonly BrowserProviderCapability[];
+
+const READ_ACTIONS = new Set([
+  'list_sessions', 'reconcile_sessions', 'get_handoff_status',
+  'get_text', 'get_html', 'query_selector', 'query_all', 'get_attribute', 'list_frames', 'verify_state',
+  'extract_links', 'extract_tables', 'extract_forms', 'snapshot_interactive', 'get_console_errors', 'get_failed_requests',
+  'wait_for_load_state', 'wait_for_selector', 'await_file_transfer',
+]);
+const SCREENSHOT_ACTIONS = new Set(['screenshot']);
+const TRUSTED_INPUT_ACTIONS = new Set(['trusted_input', 'activate_page']);
+const DOM_INTERACTION_ACTIONS = new Set([
+  'create_session', 'open_page', 'navigate', 'reload', 'go_back',
+  'click', 'click_text', 'double_click', 'hover', 'focus', 'type', 'fill', 'select_option', 'check', 'uncheck',
+  'press', 'keyboard_shortcut', 'dispatch_event', 'attach_local_file', 'close_page',
+]);
+const IDEMPOTENT_ACTIONS = new Set(['configure', 'close_session', 'clear_session', 'request_human_handoff', 'resolve_handoff']);
+
+interface BrowserRuntimeActionPolicy {
+  requiredCapabilities: readonly BrowserProviderCapability[];
+  foreground: BrowserForegroundRequirement;
+  replaySafety: BrowserActionReplaySafety;
+}
+
+const registries = new Map<string, BrowserProviderRegistry<AssistantPluginActionExecutionInput, Record<string, unknown>>>();
+
+function registryFor(runtimeKey: string): BrowserProviderRegistry<AssistantPluginActionExecutionInput, Record<string, unknown>> {
+  let registry = registries.get(runtimeKey);
+  if (!registry) {
+    registry = new BrowserProviderRegistry();
+    registries.set(runtimeKey, registry);
+  }
+  return registry;
+}
+
+export function invalidateBrowserRuntime(runtimeKey: string, reason: string): void {
+  registries.get(runtimeKey)?.invalidateAll(reason);
+}
+
+export function browserRuntimeActionPolicy(actionId: string): BrowserRuntimeActionPolicy {
+  if (SCREENSHOT_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['browser.screenshot', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
+  }
+  if (TRUSTED_INPUT_ACTIONS.has(actionId)) {
+    return {
+      requiredCapabilities: ['browser.trusted_input', 'browser.foreground', 'browser.transaction'],
+      foreground: 'explicit_required',
+      replaySafety: 'non_idempotent',
+    };
+  }
+  if (READ_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['dom.read', 'browser.transaction'], foreground: 'none', replaySafety: 'read_only' };
+  }
+  if (DOM_INTERACTION_ACTIONS.has(actionId)) {
+    return { requiredCapabilities: ['dom.interact', 'browser.transaction'], foreground: 'none', replaySafety: 'non_idempotent' };
+  }
+  return {
+    requiredCapabilities: ['browser.transaction'],
+    foreground: 'none',
+    replaySafety: IDEMPOTENT_ACTIONS.has(actionId) ? 'idempotent' : 'non_idempotent',
+  };
+}
+
+
+/**
+ * Post-dispatch replay is a semantic BrowserRuntime decision. Only read-only
+ * actions fenced to an already-existing resource may be replayed after a
+ * transient provider failure; mutations retain unknown-outcome semantics.
+ */
+export function browserActionCanReplayAfterDispatch(actionId: string, requireExistingResource = true): boolean {
+  return requireExistingResource && browserRuntimeActionPolicy(actionId).replaySafety === 'read_only';
+}
+
+function stringArgument(args: Record<string, unknown>, key: string): string | undefined {
+  const value = args[key];
+  return typeof value === 'string' && value.trim() ? value.trim() : undefined;
+}
+
+function stableTargetFor(input: AssistantPluginActionExecutionInput, providerId: string): BrowserTargetIdentity {
+  const sessionId = stringArgument(input.args, 'session_id');
+  const nativeProduct = stringArgument(input.args, 'native_browser_product');
+  const nativeWindowId = stringArgument(input.args, 'native_window_id');
+  const nativeTabId = stringArgument(input.args, 'native_tab_id');
+  if (nativeWindowId && nativeTabId) {
+    return {
+      providerId,
+      resourceKind: 'tab',
+      resourceId: `window:${nativeWindowId}/tab:${nativeTabId}`,
+      ...(nativeProduct ? { browserProduct: nativeProduct } : {}),
+      ownership: 'user_owned',
+    };
+  }
+  if (sessionId) {
+    return {
+      providerId,
+      resourceKind: 'page',
+      resourceId: `session:${sessionId}`,
+      ownership: 'provider_owned',
+    };
+  }
+  return {
+    providerId,
+    resourceKind: 'page',
+    resourceId: `request:${input.requestId}:${input.actionId}`,
+    ownership: 'plugin_owned',
+  };
+}
+
+function transactionFor(
+  input: AssistantPluginActionExecutionInput,
+  providerId: string,
+  policy: BrowserRuntimeActionPolicy,
+): BrowserTransaction {
+  return {
+    transactionId: input.requestId,
+    target: stableTargetFor(input, providerId),
+    requiredCapabilities: policy.requiredCapabilities,
+    foreground: policy.foreground,
+    replaySafety: policy.replaySafety,
+    action: {
+      kind: policy.replaySafety === 'read_only' ? 'read' : policy.foreground === 'explicit_required' ? 'trusted_input' : 'dom',
+      operation: input.actionId,
+      arguments: input.args,
+    },
+    ...(policy.replaySafety === 'read_only'
+      ? {}
+      : { postconditions: [{ kind: 'provider_assertion', assertion: 'semantic_action_result', expected: true }] as const }),
+    timeoutMs: typeof input.args.timeout_ms === 'number' && Number.isFinite(input.args.timeout_ms)
+      ? Math.max(1, Math.trunc(input.args.timeout_ms))
+      : 60_000,
+  };
+}
+
+export async function executeBrowserRuntimeAction(options: {
+  runtimeKey: string;
+  input: AssistantPluginActionExecutionInput;
+  providers: readonly BrowserRuntimeProvider<AssistantPluginActionExecutionInput, Record<string, unknown>>[];
+}): Promise<Record<string, unknown>> {
+  const registry = registryFor(options.runtimeKey);
+  for (const provider of options.providers) registry.register(provider);
+
+  const policy = browserRuntimeActionPolicy(options.input.actionId);
+  const excluded = new Set<string>();
+  while (true) {
+    const selection = await registry.select({
+      input: options.input,
+      requiredCapabilities: policy.requiredCapabilities,
+      foreground: policy.foreground,
+      excludedProviderIds: excluded,
+    });
+    const transaction = transactionFor(options.input, selection.provider.providerId, policy);
+    const validationErrors = validateBrowserTransaction(transaction);
+    if (validationErrors.length > 0) {
+      throw new AssistantPluginError('PLUGIN_BROWSER_TRANSACTION_INVALID', validationErrors[0]!, {
+        retryable: false,
+        details: { transactionId: transaction.transactionId, errors: validationErrors },
+      });
+    }
+
+    try {
+      return await selection.provider.execute(options.input);
+    } catch (error) {
+      if (!(error instanceof BrowserProviderUnavailableBeforeActionError)) throw error;
+      excluded.add(selection.provider.providerId);
+      // This is provider reselection, not action replay: the typed error proves the rejected provider
+      // never attempted the action. Unknown outcomes from non-idempotent actions always propagate.
+    }
+  }
+}

package/src/runtime/plugins/browser-session-authority.ts

@@ -0,0 +1,332 @@
+import { AsyncLocalStorage } from 'node:async_hooks';
+import { createHash } from 'crypto';
+import { readdirSync, readFileSync } from 'fs';
+import { join, resolve } from 'path';
+import {
+  listControlPlaneRecords,
+  readControlPlaneRecord,
+  readControlPlaneRecordWithinTransaction,
+  withControlPlaneTransaction,
+  writeControlPlaneRecordWithinTransaction,
+} from '../control-plane/persistence/sqlite-store';
+
+const SESSION_NAMESPACE = 'browser_session';
+const SESSION_SCOPE = 'controller';
+const IMPORT_NAMESPACE = 'browser_session_legacy_import';
+const MAX_AUTHORITY_RECORDS = 5_000;
+export const DEFAULT_BROWSER_SESSION_LIST_LIMIT = 50;
+export const MAX_BROWSER_SESSION_LIST_LIMIT = 200;
+
+export interface BrowserSessionAuthorityContext {
+  controllerHome: string;
+  repoId: string;
+}
+
+export interface BrowserSessionAuthoritySession {
+  schemaVersion: 1;
+  sessionId: string;
+  url: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  browser?: {
+    provider?: string;
+    browserProduct?: string;
+    tab?: {
+      windowId?: string;
+      tabId?: string;
+      ownership?: string;
+    };
+  };
+}
+
+interface BrowserSessionAuthorityEntry<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
+  schemaVersion: 1;
+  status: 'active' | 'tombstoned';
+  session: T;
+  aliases: string[];
+  repositoryIds: string[];
+  nativeIdentity?: string;
+  tombstonedAt?: string;
+  importedFromLegacy?: boolean;
+}
+
+interface LegacyImportMarker {
+  schemaVersion: 1;
+  repoId: string;
+  repoRootFingerprint: string;
+  importedAt: string;
+  importedRecordCount: number;
+}
+
+export interface BrowserSessionAuthorityPage<T extends BrowserSessionAuthoritySession = BrowserSessionAuthoritySession> {
+  sessions: T[];
+  limit: number;
+  totalCount: number;
+  nextCursor?: string;
+}
+
+const authorityContextStorage = new AsyncLocalStorage<BrowserSessionAuthorityContext>();
+
+export function withBrowserSessionAuthorityContext<T>(
+  context: BrowserSessionAuthorityContext,
+  operation: () => T,
+): T {
+  return authorityContextStorage.run(context, operation);
+}
+
+export function currentBrowserSessionAuthorityContext(): BrowserSessionAuthorityContext | undefined {
+  return authorityContextStorage.getStore();
+}
+
+function digest(value: string): string {
+  return createHash('sha256').update(value).digest('hex');
+}
+
+function nativeIdentity(session: BrowserSessionAuthoritySession): string | undefined {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || !browser.browserProduct || !tab?.windowId || !tab.tabId) return undefined;
+  return `${browser.provider}:${browser.browserProduct}:${tab.windowId}:${tab.tabId}`;
+}
+
+function recordKey(repoId: string, session: BrowserSessionAuthoritySession): string {
+  const native = nativeIdentity(session);
+  return native ? `native-${digest(native).slice(0, 40)}` : `session-${digest(`${repoId}:${session.sessionId}`).slice(0, 40)}`;
+}
+
+function importMarkerKey(repoRoot: string): string {
+  return digest(resolve(repoRoot)).slice(0, 40);
+}
+
+function unique(values: string[]): string[] {
+  return [...new Set(values.filter(Boolean))].sort();
+}
+
+function parseLegacySession(path: string): BrowserSessionAuthoritySession {
+  let parsed: unknown;
+  try {
+    parsed = JSON.parse(readFileSync(path, 'utf8'));
+  } catch (error) {
+    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: ${error instanceof Error ? error.message : String(error)}`);
+  }
+  if (!parsed || typeof parsed !== 'object' || Array.isArray(parsed)) {
+    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: expected object`);
+  }
+  const session = parsed as Partial<BrowserSessionAuthoritySession>;
+  if (session.schemaVersion !== 1 || typeof session.sessionId !== 'string' || typeof session.url !== 'string'
+    || typeof session.createdAt !== 'string' || typeof session.updatedAt !== 'string') {
+    throw new Error(`PLUGIN_BROWSER_SESSION_STATE_CORRUPT: ${path}: required session fields are missing`);
+  }
+  return session as BrowserSessionAuthoritySession;
+}
+
+function legacySessions(repoRoot: string): BrowserSessionAuthoritySession[] {
+  const root = join(repoRoot, '.forge', 'browser', 'sessions');
+  let names: string[];
+  try {
+    names = readdirSync(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return [];
+    throw error;
+  }
+  return names.filter((name) => name.endsWith('.json')).sort().map((name) => parseLegacySession(join(root, name)));
+}
+
+function mergeEntry<T extends BrowserSessionAuthoritySession>(
+  existing: BrowserSessionAuthorityEntry<T> | undefined,
+  repoId: string,
+  session: T,
+  options: { importedFromLegacy?: boolean } = {},
+): BrowserSessionAuthorityEntry<T> {
+  const canonicalSessionId = existing?.session.sessionId ?? session.sessionId;
+  const canonicalCreatedAt = existing?.session.createdAt ?? session.createdAt;
+  const normalizedSession = {
+    ...session,
+    sessionId: canonicalSessionId,
+    createdAt: canonicalCreatedAt,
+  } as T;
+  return {
+    schemaVersion: 1,
+    status: 'active',
+    session: normalizedSession,
+    aliases: unique([...(existing?.aliases ?? []), existing?.session.sessionId ?? '', session.sessionId, canonicalSessionId]),
+    repositoryIds: unique([...(existing?.repositoryIds ?? []), repoId]),
+    nativeIdentity: nativeIdentity(session) ?? existing?.nativeIdentity,
+    importedFromLegacy: options.importedFromLegacy === true || existing?.importedFromLegacy === true,
+  };
+}
+
+export function ensureLegacyBrowserSessionsImported(controllerHome: string, repoId: string, repoRoot: string): number {
+  const markerKey = importMarkerKey(repoRoot);
+  if (readControlPlaneRecord<LegacyImportMarker>(controllerHome, IMPORT_NAMESPACE, repoId, markerKey)) return 0;
+  const sessions = legacySessions(repoRoot);
+  return withControlPlaneTransaction(controllerHome, (database) => {
+    const marker = readControlPlaneRecordWithinTransaction<LegacyImportMarker>(database, IMPORT_NAMESPACE, repoId, markerKey);
+    if (marker) return 0;
+    let imported = 0;
+    for (const session of sessions) {
+      const key = recordKey(repoId, session);
+      const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry>(database, SESSION_NAMESPACE, SESSION_SCOPE, key);
+      const next = mergeEntry(current?.value, repoId, session, { importedFromLegacy: true });
+      writeControlPlaneRecordWithinTransaction(database, {
+        namespace: SESSION_NAMESPACE,
+        scope: SESSION_SCOPE,
+        key,
+        schemaVersion: 1,
+        value: next,
+        expectedRevision: current?.revision ?? null,
+        action: current ? 'legacy_merge' : 'legacy_import',
+      });
+      imported += 1;
+    }
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: IMPORT_NAMESPACE,
+      scope: repoId,
+      key: markerKey,
+      schemaVersion: 1,
+      value: {
+        schemaVersion: 1,
+        repoId,
+        repoRootFingerprint: markerKey,
+        importedAt: new Date().toISOString(),
+        importedRecordCount: imported,
+      } satisfies LegacyImportMarker,
+      expectedRevision: null,
+      action: 'legacy_import_complete',
+    });
+    return imported;
+  });
+}
+
+function authorityEntries(controllerHome: string): BrowserSessionAuthorityEntry[] {
+  return listControlPlaneRecords<BrowserSessionAuthorityEntry>(controllerHome, {
+    namespace: SESSION_NAMESPACE,
+    scope: SESSION_SCOPE,
+    limit: MAX_AUTHORITY_RECORDS,
+  }).map((record) => record.value);
+}
+
+function visibleToRepository(entry: BrowserSessionAuthorityEntry, repoId: string): boolean {
+  return Boolean(entry.nativeIdentity) || entry.repositoryIds.includes(repoId);
+}
+
+function activeEntries(controllerHome: string, repoId: string, repoRoot: string): BrowserSessionAuthorityEntry[] {
+  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
+  return authorityEntries(controllerHome)
+    .filter((entry) => entry.status === 'active' && visibleToRepository(entry, repoId))
+    .sort((left, right) => {
+      const updated = right.session.updatedAt.localeCompare(left.session.updatedAt);
+      return updated !== 0 ? updated : left.session.sessionId.localeCompare(right.session.sessionId);
+    });
+}
+
+export function saveBrowserSession<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  session: T,
+): T {
+  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
+  const key = recordKey(repoId, session);
+  return withControlPlaneTransaction(controllerHome, (database) => {
+    const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry<T>>(database, SESSION_NAMESPACE, SESSION_SCOPE, key);
+    const next = mergeEntry(current?.value, repoId, session);
+    const written = writeControlPlaneRecordWithinTransaction(database, {
+      namespace: SESSION_NAMESPACE,
+      scope: SESSION_SCOPE,
+      key,
+      schemaVersion: 1,
+      value: next,
+      expectedRevision: current?.revision ?? null,
+      action: current ? 'save' : 'create',
+    });
+    return written.value.session;
+  });
+}
+
+export function findBrowserSession<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  sessionId: string,
+): T | undefined {
+  return activeEntries(controllerHome, repoId, repoRoot)
+    .find((entry) => entry.session.sessionId === sessionId || entry.aliases.includes(sessionId))?.session as T | undefined;
+}
+
+export function listBrowserSessions<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  options: { limit?: number; cursor?: string } = {},
+): BrowserSessionAuthorityPage<T> {
+  const entries = activeEntries(controllerHome, repoId, repoRoot);
+  const limit = Math.max(1, Math.min(Math.trunc(options.limit ?? DEFAULT_BROWSER_SESSION_LIST_LIMIT), MAX_BROWSER_SESSION_LIST_LIMIT));
+  let offset = 0;
+  if (options.cursor) {
+    try {
+      const parsed = JSON.parse(Buffer.from(options.cursor, 'base64url').toString('utf8')) as { offset?: unknown };
+      if (!Number.isInteger(parsed.offset) || Number(parsed.offset) < 0) throw new Error('invalid offset');
+      offset = Number(parsed.offset);
+    } catch {
+      throw new Error('PLUGIN_BROWSER_SESSION_CURSOR_INVALID: cursor is invalid or expired');
+    }
+  }
+  const page = entries.slice(offset, offset + limit);
+  const nextOffset = offset + page.length;
+  const nextCursor = nextOffset < entries.length
+    ? Buffer.from(JSON.stringify({ offset: nextOffset }), 'utf8').toString('base64url')
+    : undefined;
+  return {
+    sessions: page.map((entry) => entry.session as T),
+    limit,
+    totalCount: entries.length,
+    nextCursor,
+  };
+}
+
+export function listAllBrowserSessionsForRepository<T extends BrowserSessionAuthoritySession>(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+): T[] {
+  return activeEntries(controllerHome, repoId, repoRoot).map((entry) => entry.session as T);
+}
+
+export function tombstoneBrowserSession(
+  controllerHome: string,
+  repoId: string,
+  repoRoot: string,
+  sessionId: string,
+): boolean {
+  ensureLegacyBrowserSessionsImported(controllerHome, repoId, repoRoot);
+  const record = listControlPlaneRecords<BrowserSessionAuthorityEntry>(controllerHome, {
+    namespace: SESSION_NAMESPACE,
+    scope: SESSION_SCOPE,
+    limit: MAX_AUTHORITY_RECORDS,
+  }).find((candidate) => {
+    const entry = candidate.value;
+    return entry.status === 'active' && visibleToRepository(entry, repoId)
+      && (entry.session.sessionId === sessionId || entry.aliases.includes(sessionId));
+  });
+  if (!record) return false;
+  return withControlPlaneTransaction(controllerHome, (database) => {
+    const current = readControlPlaneRecordWithinTransaction<BrowserSessionAuthorityEntry>(database, SESSION_NAMESPACE, SESSION_SCOPE, record.key);
+    if (!current || current.value.status !== 'active') return false;
+    writeControlPlaneRecordWithinTransaction(database, {
+      namespace: SESSION_NAMESPACE,
+      scope: SESSION_SCOPE,
+      key: record.key,
+      schemaVersion: 1,
+      value: {
+        ...current.value,
+        status: 'tombstoned',
+        tombstonedAt: new Date().toISOString(),
+      },
+      expectedRevision: current.revision,
+      action: 'tombstone',
+    });
+    return true;
+  });
+}

package/src/runtime/plugins/browser-session-store.ts

@@ -0,0 +1,121 @@
+import { readdirSync, readFileSync, rmSync } from 'fs';
+import { basename, join } from 'path';
+import { writeJsonAtomic } from '../shared/json-files';
+import { AssistantPluginError } from './errors';
+import {
+  currentBrowserSessionAuthorityContext,
+  findBrowserSession as findBrowserSessionAuthority,
+  listAllBrowserSessionsForRepository,
+  saveBrowserSession as saveBrowserSessionAuthority,
+  tombstoneBrowserSession,
+} from './browser-session-authority';
+
+const BROWSER_STATE_ROOT = '.forge/browser';
+
+import type { BrowserSessionState } from './browser-session-types';
+
+/**
+ * Repository-local browser paths remain compatibility storage only. During
+ * Runtime/plugin execution, BrowserSessionAuthority (SQLite) is the sole writer;
+ * the JSON files are read/written only when no Controller authority context is
+ * present (for legacy migration/tests/standalone helpers).
+ */
+export function browserStateDir(
+  repoRoot: string,
+  name: 'sessions' | 'screenshots' | 'profiles' | 'downloads' | 'diagnostics',
+): string {
+  return join(repoRoot, BROWSER_STATE_ROOT, name);
+}
+
+function sessionPath(repoRoot: string, sessionId: string): string {
+  return join(browserStateDir(repoRoot, 'sessions'), `${sessionId.replace(/[^a-zA-Z0-9_-]/g, '_')}.json`);
+}
+
+function readLegacyBrowserSessionJson(path: string): BrowserSessionState | undefined {
+  let raw: string;
+  try {
+    raw = readFileSync(path, 'utf-8');
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return undefined;
+    throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_READ_FAILED', 'Saved browser session metadata could not be read.', {
+      retryable: true,
+      details: { fileName: basename(path), cause: error instanceof Error ? error.message : String(error) },
+    });
+  }
+  try {
+    return JSON.parse(raw) as BrowserSessionState;
+  } catch (error) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_CORRUPT', 'Saved browser session metadata is malformed; refusing to treat corrupt state as a missing session.', {
+      retryable: false,
+      details: { fileName: basename(path), cause: error instanceof Error ? error.message : String(error) },
+    });
+  }
+}
+
+export function saveBrowserSession(repoRoot: string, session: BrowserSessionState): BrowserSessionState {
+  const authority = currentBrowserSessionAuthorityContext();
+  if (!authority) {
+    writeJsonAtomic(sessionPath(repoRoot, session.sessionId), session);
+    return session;
+  }
+  const saved = saveBrowserSessionAuthority<BrowserSessionState>(authority.controllerHome, authority.repoId, repoRoot, session);
+  if (saved.sessionId === session.sessionId || !saved.browser?.sessionResume) return saved;
+  return {
+    ...saved,
+    browser: {
+      ...saved.browser,
+      sessionResume: { ...saved.browser.sessionResume, sessionId: saved.sessionId },
+    },
+  };
+}
+
+export function findBrowserSession(repoRoot: string, sessionId?: string): BrowserSessionState | undefined {
+  if (!sessionId) return undefined;
+  const authority = currentBrowserSessionAuthorityContext();
+  return authority
+    ? findBrowserSessionAuthority<BrowserSessionState>(authority.controllerHome, authority.repoId, repoRoot, sessionId)
+    : readLegacyBrowserSessionJson(sessionPath(repoRoot, sessionId));
+}
+
+export function listSavedBrowserSessions(repoRoot: string): BrowserSessionState[] {
+  const authority = currentBrowserSessionAuthorityContext();
+  if (authority) {
+    return listAllBrowserSessionsForRepository<BrowserSessionState>(authority.controllerHome, authority.repoId, repoRoot);
+  }
+  const root = browserStateDir(repoRoot, 'sessions');
+  let names: string[];
+  try {
+    names = readdirSync(root);
+  } catch (error) {
+    if ((error as NodeJS.ErrnoException)?.code === 'ENOENT') return [];
+    throw new AssistantPluginError('PLUGIN_BROWSER_SESSION_STATE_READ_FAILED', 'Saved browser session directory could not be read.', {
+      retryable: true,
+      details: { cause: error instanceof Error ? error.message : String(error) },
+    });
+  }
+  return names
+    .filter((name) => name.endsWith('.json'))
+    .map((name) => readLegacyBrowserSessionJson(join(root, name)))
+    .filter((session): session is BrowserSessionState => Boolean(session));
+}
+
+export function removeBrowserSession(repoRoot: string, sessionId: string): void {
+  const authority = currentBrowserSessionAuthorityContext();
+  if (authority) {
+    tombstoneBrowserSession(authority.controllerHome, authority.repoId, repoRoot, sessionId);
+    return;
+  }
+  rmSync(sessionPath(repoRoot, sessionId), { force: true });
+}
+
+export function loadBrowserSession(repoRoot: string, sessionId?: string): BrowserSessionState | undefined {
+  return sessionId ? findBrowserSession(repoRoot, sessionId) : undefined;
+}
+
+export function requireBrowserSession(repoRoot: string, sessionId: string): BrowserSessionState {
+  const session = findBrowserSession(repoRoot, sessionId);
+  if (!session) {
+    throw new AssistantPluginError('PLUGIN_SESSION_NOT_FOUND', `Browser session not found: ${sessionId}`, { retryable: false });
+  }
+  return session;
+}