@moretea-labs/forge 1.7.0 → 1.7.1

package/src/runtime/plugins/browser-native-session-service.ts

@@ -0,0 +1,222 @@
+import { AssistantPluginError } from './errors';
+import {
+  closeMacOsBrowserOwnedTab,
+  listMacOsBrowserTabs,
+  macOsBrowserPageHandleStale,
+  readMacOsBrowserOwnedTabMetadata,
+  type MacOsBrowserProduct,
+} from './browser-macos-bridge';
+import { listSavedBrowserSessions, removeBrowserSession } from './browser-session-store';
+import type { BrowserSessionInventoryItem, BrowserSessionState } from './browser-session-types';
+
+export interface NativeOwnedSessionInspection {
+  items: Map<string, BrowserSessionInventoryItem>;
+  liveCount: number;
+  deadCount: number;
+  unverifiedCount: number;
+  prunedCount: number;
+  closedInvalidCount: number;
+  failedCleanupCount: number;
+}
+
+export function nativeTabInventoryUnsupported(error: unknown): boolean {
+  if (error instanceof AssistantPluginError && error.code === 'BROWSER_AUTOMATION_ACTION_UNSUPPORTED') return true;
+  const message = error instanceof Error ? error.message : String(error ?? '');
+  return /\bBROWSER_AUTOMATION_ACTION_UNSUPPORTED\b/.test(message);
+}
+
+function isDiscardableNativeOwnedTabUrl(url: string): boolean {
+  const normalized = url.trim().toLowerCase();
+  return normalized === ''
+    || normalized === 'about:blank'
+    || normalized === 'chrome://newtab/'
+    || normalized === 'chrome://new-tab-page/'
+    || normalized === 'vivaldi://newtab/'
+    || normalized === 'vivaldi://startpage/';
+}
+
+/**
+ * Native tab liveness/cleanup belongs to one service so the Browser adapter does
+ * not reinterpret stable native identity or prune policy action-by-action.
+ */
+export async function inspectNativeOwnedSessions(input: {
+  repoRoot: string;
+  savedSessions: BrowserSessionState[];
+  timeoutMs: number;
+  pruneDead?: boolean;
+}): Promise<NativeOwnedSessionInspection> {
+  const { repoRoot, savedSessions, timeoutMs } = input;
+  const items = new Map<string, BrowserSessionInventoryItem>();
+  const inventories = new Map<MacOsBrowserProduct, Awaited<ReturnType<typeof listMacOsBrowserTabs>> | Error>();
+  const groups = new Map<string, BrowserSessionState[]>();
+  let liveCount = 0;
+  let deadCount = 0;
+  let unverifiedCount = 0;
+  let prunedCount = 0;
+  let closedInvalidCount = 0;
+  let failedCleanupCount = 0;
+
+  for (const session of savedSessions) {
+    const browser = session.browser;
+    const tab = browser?.tab;
+    const product = browser?.browserProduct;
+    if (browser?.provider !== 'macos-apple-events' || tab?.ownership !== 'plugin_owned' || !product || !tab.windowId || !tab.tabId) continue;
+    const key = `${product}:${tab.windowId}:${tab.tabId}`;
+    const group = groups.get(key) ?? [];
+    group.push(session);
+    groups.set(key, group);
+  }
+
+  for (const group of groups.values()) {
+    const canonical = group.reduce((latest, session) => session.updatedAt > latest.updatedAt ? session : latest);
+    const browser = canonical.browser!;
+    const tab = browser.tab!;
+    const product = browser.browserProduct!;
+    let inventory = inventories.get(product);
+    if (!inventory) {
+      try {
+        inventory = await listMacOsBrowserTabs(product, timeoutMs);
+      } catch (error) {
+        inventory = error instanceof Error ? error : new Error(String(error));
+      }
+      inventories.set(product, inventory);
+    }
+    if (inventory instanceof Error) {
+      if (!nativeTabInventoryUnsupported(inventory)) {
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'unverified', evidence: 'native_inventory_unavailable', cleanupError: inventory.message });
+        unverifiedCount += group.length;
+        continue;
+      }
+
+      const ref = { windowId: tab.windowId!, tabId: tab.tabId! };
+      let metadata: Awaited<ReturnType<typeof readMacOsBrowserOwnedTabMetadata>>;
+      try {
+        metadata = await readMacOsBrowserOwnedTabMetadata(product, ref, timeoutMs);
+      } catch (metadataError) {
+        if (macOsBrowserPageHandleStale(metadataError)) {
+          const pruned = input.pruneDead === true;
+          if (pruned) {
+            for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+            prunedCount += group.length;
+          }
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_missing', pruned });
+          deadCount += group.length;
+        } else {
+          const cleanupError = metadataError instanceof Error ? metadataError.message : String(metadataError);
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'unverified', evidence: 'native_inventory_unavailable', cleanupError });
+          unverifiedCount += group.length;
+        }
+        continue;
+      }
+
+      if (isDiscardableNativeOwnedTabUrl(metadata.url)) {
+        deadCount += group.length;
+        if (input.pruneDead === true) {
+          try {
+            await closeMacOsBrowserOwnedTab(product, ref, timeoutMs);
+            for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+            prunedCount += group.length;
+            closedInvalidCount += 1;
+            for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_closed', pruned: true });
+          } catch (error) {
+            failedCleanupCount += 1;
+            const cleanupError = error instanceof Error ? error.message : String(error);
+            for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_close_failed', cleanupError });
+          }
+        } else {
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid' });
+        }
+      } else {
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'live', evidence: 'native_tab_live' });
+        liveCount += group.length;
+      }
+      continue;
+    }
+
+    const live = inventory.tabs.find((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId);
+    if (!live) {
+      const pruned = input.pruneDead === true;
+      if (pruned) {
+        for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+        prunedCount += group.length;
+      }
+      for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_missing', pruned });
+      deadCount += group.length;
+      continue;
+    }
+
+    if (isDiscardableNativeOwnedTabUrl(live.url)) {
+      deadCount += group.length;
+      if (input.pruneDead === true) {
+        try {
+          await closeMacOsBrowserOwnedTab(product, { windowId: tab.windowId!, tabId: tab.tabId! }, timeoutMs);
+          for (const session of group) removeBrowserSession(repoRoot, session.sessionId);
+          prunedCount += group.length;
+          closedInvalidCount += 1;
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_closed', pruned: true });
+        } catch (error) {
+          failedCleanupCount += 1;
+          const cleanupError = error instanceof Error ? error.message : String(error);
+          for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid_close_failed', cleanupError });
+        }
+      } else {
+        for (const session of group) items.set(session.sessionId, { session, liveness: 'dead', evidence: 'native_tab_invalid' });
+      }
+      continue;
+    }
+
+    for (const session of group) items.set(session.sessionId, { session, liveness: 'live', evidence: 'native_tab_live' });
+    liveCount += group.length;
+  }
+
+  return { items, liveCount, deadCount, unverifiedCount, prunedCount, closedInvalidCount, failedCleanupCount };
+}
+
+export async function closeTrackedNativeOwnedSession(
+  session: BrowserSessionState,
+  timeoutMs: number,
+): Promise<{ resourceClosed: boolean; resourceAlreadyMissing: boolean }> {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || tab?.ownership !== 'plugin_owned') {
+    return { resourceClosed: false, resourceAlreadyMissing: false };
+  }
+  if (!browser.browserProduct || !tab.windowId || !tab.tabId) {
+    throw new AssistantPluginError('PLUGIN_BROWSER_NATIVE_OWNERSHIP_MISSING', 'Tracked plugin-owned native tab is missing stable browser identity; retaining session metadata instead of orphaning the tab.', {
+      retryable: false, details: { sessionId: session.sessionId, browserProduct: browser.browserProduct, windowId: tab.windowId, tabId: tab.tabId },
+    });
+  }
+  const ref = { windowId: tab.windowId, tabId: tab.tabId };
+  let inventory: Awaited<ReturnType<typeof listMacOsBrowserTabs>> | undefined;
+  try {
+    inventory = await listMacOsBrowserTabs(browser.browserProduct, timeoutMs);
+  } catch (error) {
+    if (!nativeTabInventoryUnsupported(error)) throw error;
+    try {
+      await readMacOsBrowserOwnedTabMetadata(browser.browserProduct, ref, timeoutMs);
+    } catch (metadataError) {
+      if (macOsBrowserPageHandleStale(metadataError)) return { resourceClosed: false, resourceAlreadyMissing: true };
+      throw metadataError;
+    }
+  }
+  if (inventory && !inventory.tabs.some((entry) => entry.windowId === tab.windowId && entry.tabId === tab.tabId)) {
+    return { resourceClosed: false, resourceAlreadyMissing: true };
+  }
+  await closeMacOsBrowserOwnedTab(browser.browserProduct, ref, timeoutMs);
+  return { resourceClosed: true, resourceAlreadyMissing: false };
+}
+
+export function nativeOwnedAliasSessionIds(repoRoot: string, session: BrowserSessionState): string[] {
+  const browser = session.browser;
+  const tab = browser?.tab;
+  if (browser?.provider !== 'macos-apple-events' || tab?.ownership !== 'plugin_owned' || !browser.browserProduct || !tab.windowId || !tab.tabId) {
+    return [session.sessionId];
+  }
+  return listSavedBrowserSessions(repoRoot)
+    .filter((candidate) => candidate.browser?.provider === 'macos-apple-events'
+      && candidate.browser.browserProduct === browser.browserProduct
+      && candidate.browser.tab?.ownership === 'plugin_owned'
+      && candidate.browser.tab.windowId === tab.windowId
+      && candidate.browser.tab.tabId === tab.tabId)
+    .map((candidate) => candidate.sessionId);
+}

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

@@ -1,3 +1,5 @@
+export const MAX_BROWSER_CDP_ENDPOINT_CANDIDATES = 5;
+
 export type BrowserProviderCapability =
   | 'dom.read'
   | 'dom.interact'

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

@@ -85,6 +85,16 @@ export function browserRuntimeActionPolicy(actionId: string): BrowserRuntimeActi
   };
 }
 
+
+/**
+ * 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;

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;
+}

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

@@ -0,0 +1,98 @@
+export type BrowserMode = 'attach_preferred' | 'managed_persistent' | 'isolated';
+export type BrowserProfileMode = 'repo_local' | 'custom';
+export type BrowserCdpAttachFallback = 'managed_persistent' | 'fail_closed';
+export type BrowserNativeProduct = 'chrome' | 'vivaldi';
+export type BrowserTabMatchReason = 'owned_token' | 'recovered_tab' | 'saved_url_title' | 'saved_url' | 'exact_url' | 'blank' | 'new_page';
+
+export interface CdpAttachAttempt {
+  endpoint: string;
+  discoveredEndpoint?: string;
+  probeUrl?: string;
+  browserVersion?: string;
+  error?: string;
+}
+
+export interface BrowserNativeAttachAttempt {
+  product: BrowserNativeProduct;
+  appName: string;
+  bundleId: string;
+  status: 'selected' | 'available' | 'not_installed' | 'not_running' | 'unavailable';
+  frontmost?: boolean;
+  error?: string;
+}
+
+export interface BrowserSessionResumeDiagnostic {
+  sessionId: string;
+  status: 'matched' | 'stale_tab' | 'no_saved_tab';
+  reason: string;
+  savedTab?: Pick<BrowserTabResumeState, 'key' | 'url' | 'title' | 'index'>;
+}
+
+export interface BrowserConnectionFallback {
+  policy: BrowserCdpAttachFallback;
+  from: 'attach_preferred';
+  to: 'managed_persistent';
+  reason: string;
+  attempts: CdpAttachAttempt[];
+  nativeAttempts?: BrowserNativeAttachAttempt[];
+}
+
+export interface BrowserTabResumeState {
+  key: string;
+  index: number;
+  url: string;
+  title?: string;
+  matchedBy: BrowserTabMatchReason;
+  inventoryCount: number;
+  capturedAt: string;
+  ownership?: 'plugin_owned' | 'user_owned';
+  ownerToken?: string;
+  windowId?: string;
+  tabId?: string;
+}
+
+export interface BrowserSessionConnectionState {
+  mode: BrowserMode;
+  activeMode: BrowserMode;
+  provider: 'playwright-cdp' | 'playwright-persistent-context' | 'macos-apple-events';
+  endpoint?: string;
+  browserVersion?: string;
+  browserProduct?: BrowserNativeProduct;
+  nativeBrowserCandidates?: BrowserNativeProduct[];
+  fallback?: BrowserConnectionFallback;
+  tab?: BrowserTabResumeState;
+  sessionResume?: BrowserSessionResumeDiagnostic;
+}
+
+export interface BrowserSessionState {
+  schemaVersion: 1;
+  sessionId: string;
+  url: string;
+  title?: string;
+  createdAt: string;
+  updatedAt: string;
+  browser?: BrowserSessionConnectionState;
+}
+
+export type BrowserSessionLiveness = 'live' | 'unverified' | 'dead';
+export type BrowserSessionLivenessEvidence =
+  | 'runtime_session_binding'
+  | 'runtime_owner_token'
+  | 'runtime_bound_page_missing'
+  | 'runtime_context_unavailable'
+  | 'runtime_owner_token_not_observed'
+  | 'provider_unverified'
+  | 'native_tab_live'
+  | 'native_tab_missing'
+  | 'native_tab_invalid'
+  | 'native_tab_invalid_closed'
+  | 'native_tab_invalid_close_failed'
+  | 'native_inventory_unavailable';
+
+export interface BrowserSessionInventoryItem {
+  session: BrowserSessionState;
+  liveness: BrowserSessionLiveness;
+  evidence: BrowserSessionLivenessEvidence;
+  pruned?: boolean;
+  cleanupError?: string;
+}

package/src/runtime/plugins/desktop-operator-registration.ts

@@ -119,7 +119,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_press',
       title: 'Press desktop element',
-      description: 'Press one Accessibility element semantically in the background; pointer/coordinate fallback is intentionally unavailable.',
+      description: 'Perform one bounded Accessibility semantic action in the background, including one-page list scrolling; pointer/coordinate and raw input fallback are intentionally unavailable.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',
@@ -135,8 +135,8 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
           selector: SELECTOR_SCHEMA,
           semantic_action: {
             type: 'string',
-            enum: ['press', 'show_menu', 'pick', 'open', 'confirm'],
-            description: 'Bounded Accessibility action supported by the trusted Desktop Operator provider; defaults to press when omitted.',
+            enum: ['press', 'show_menu', 'pick', 'open', 'confirm', 'scroll_down_page', 'scroll_up_page'],
+            description: 'Bounded Accessibility action supported by the trusted Desktop Operator provider; scroll actions move exactly one page and default to press when omitted.',
           },
         },
         required: ['interaction_id', 'selector'],
@@ -170,7 +170,7 @@ function desktopOperatorActions(): AssistantPluginActionDescriptor[] {
     {
       actionId: 'desktop_key',
       title: 'Press desktop keys',
-      description: 'Send one bounded key chord only when the explicit target session is already foreground; the operator never activates it.',
+      description: 'Send one bounded key chord to the exact target session after Forge independently re-establishes and verifies that application as system-frontmost at the action boundary.',
       readOnly: false,
       risk: 'workspace_write',
       confirmation: 'authorization',