Skip to content

armgit / cindy

Public Imported from GitHub
0

Consider it done. The open-source AI agent that works out of the box · 想到,就能做到。开源、开箱即用的 AI Agent。

21.4 KB
Raw Blame
/**
 * HTTP client for communicating with the opencli daemon.
 *
 * Provides a typed send() function that posts a Command and returns a Result.
 */

import { sleep } from '../utils.js';
import type { SlotGrantData, SlotPolicy } from '../site-slots.js';
import { BrowserConnectError, SessionBusyError } from '../errors.js';
import { COMMAND_RESULT_UNKNOWN_CODE, COMMAND_RESULT_UNKNOWN_HINT } from '../daemon-utils.js';
import { classifyBrowserError } from './errors.js';
import { profileRouteParams, resolveProfileSelection } from './profile.js';
import { DEFAULT_BROWSER_CONNECT_TIMEOUT } from './config.js';
import { ensureBrowserBridgeReady } from './daemon-lifecycle.js';
import { isPreDispatchError } from './bridge-readiness.js';
import {
  fetchDaemonStatus,
  getDaemonHealth,
  requestDaemon,
  requestDaemonShutdown,
  type BrowserProfileStatus,
  type DaemonHealth,
  type DaemonStatus,
} from './daemon-transport.js';

let _idCounter = 0;

function generateId(): string {
  return `cmd_${process.pid}_${Date.now()}_${++_idCounter}`;
}

/**
 * Id for a whole logical CLI command run. Encodes the CLI pid so the daemon can
 * name/kill the holder in a busy error (see parsePidFromRunId in session-lease.ts).
 */
export function generateRunId(): string {
  return `run_${process.pid}_${Date.now()}_${++_idCounter}`;
}

/**
 * Identity of the CLI command run currently driving the browser, attached to
 * every command so the daemon can arbitrate the write lease. Module-level and
 * one-per-invocation, matching `setDaemonCommandTimeoutSeconds`. Null for read
 * and ephemeral commands, which are never lease-arbitrated.
 */
export interface DaemonRunContext {
  runId: string;
  command: string;
  access: 'read' | 'write';
}

let _runContext: DaemonRunContext | null = null;

export function setDaemonRunContext(ctx: DaemonRunContext | null): void {
  _runContext = ctx;
}

/**
 * Clear the run context only if it still belongs to `runId`. Used by deferred
 * cleanup (an adapter that outlived its CLI timeout settles later): by then a
 * newer run may own the context, and unconditionally nulling it would strip
 * that run's lease heartbeats mid-flight.
 */
export function clearDaemonRunContext(runId: string): void {
  if (_runContext?.runId === runId) _runContext = null;
}

/**
 * Best-effort release of a persistent site-session lease on command completion.
 * A direct one-shot POST (no bridge ensure / retry): if it never lands, the
 * daemon's TTL reclaims the lease anyway, so this must never block the caller.
 */
export async function releaseSiteSessionLease(params: {
  runId: string;
  session: string;
  surface: 'adapter';
}): Promise<void> {
  try {
    await requestDaemon('/command', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({
        id: generateId(),
        action: 'lease-release',
        runId: params.runId,
        session: params.session,
        surface: params.surface,
      }),
      timeout: 2000,
    });
  } catch {
    // Best-effort: TTL expiry reclaims the lease if the daemon is unreachable.
  }
}

/**
 * Borrow one slot of a pooled site for this run. Resolves to the slot's
 * persistent session name once the daemon's admission queue grants it. The
 * caller must have set the run context so later execs heartbeat the slot.
 */
export async function acquireSiteSlot(params: SlotPolicy & {
  site: string;
  waitMs: number;
  contextId?: string;
  preferredContextId?: string;
}): Promise<SlotGrantData> {
  // timeoutMs lifts the client HTTP deadline past the daemon's own wait timer.
  return await sendCommand('slot-acquire', { ...params, timeoutMs: params.waitMs }) as SlotGrantData;
}

/**
 * Transport-level deadlines share one source of truth: `body.timeout` (seconds).
 * The daemon arms its per-command timer from it, the extension derives its CDP
 * deadline from the same value, and the client HTTP abort fires only after the
 * daemon's structured timeout response should have arrived — so failures
 * surface innermost-first (extension < daemon < client) with a real error
 * instead of an opaque client-side AbortError.
 */
const DEFAULT_COMMAND_TIMEOUT_SECONDS = 120;
/** Headroom past an extension-side operation's own timer (e.g. wait-download). */
const EXTENSION_OP_TIMEOUT_MARGIN_MS = 15_000;
/** Client aborts only this long after the daemon timer should have fired. */
const HTTP_TIMEOUT_MARGIN_MS = 10_000;

let _userCommandTimeoutSeconds: number | null = null;

/**
 * Propagate the user's `--timeout` down to the transport layer. Without this
 * the daemon/HTTP deadlines stay at their defaults and a long-running command
 * gets aborted mid-flight even though the user explicitly allowed more time.
 */
export function setDaemonCommandTimeoutSeconds(seconds: number | null): void {
  _userCommandTimeoutSeconds = typeof seconds === 'number' && seconds > 0 ? Math.ceil(seconds) : null;
}

function effectiveCommandTimeoutSeconds(params: Omit<DaemonCommand, 'id' | 'action'>): number {
  const base = _userCommandTimeoutSeconds ?? DEFAULT_COMMAND_TIMEOUT_SECONDS;
  if (typeof params.timeoutMs === 'number' && params.timeoutMs > 0) {
    return Math.max(base, Math.ceil((params.timeoutMs + EXTENSION_OP_TIMEOUT_MARGIN_MS) / 1000));
  }
  return base;
}

/**
 * First extension version with the command journal (see extension/src/
 * journal.ts). From this version on, re-sending the SAME command id is safe:
 * the executor replays the recorded result instead of re-executing.
 */
export const MIN_JOURNAL_EXTENSION_VERSION = '1.0.22';

function versionAtLeast(version: string | null | undefined, min: string): boolean {
  if (!version) return false;
  const a = version.replace(/^v/, '').split('-')[0].split('.').map(Number);
  const b = min.split('.').map(Number);
  if (a.length < 3 || a.some(Number.isNaN)) return false;
  for (let i = 0; i < 3; i++) {
    const d = a[i] - (b[i] ?? 0);
    if (d !== 0) return d > 0;
  }
  return true;
}

export function supportsCommandJournal(version: string | null | undefined, compatRange: string | null | undefined): boolean {
  // compatRange marks the independently versioned extension line.
  return !!compatRange && versionAtLeast(version, MIN_JOURNAL_EXTENSION_VERSION);
}

/** Error codes meaning the executor's outcome is genuinely unknown — never auto-retry. */
const UNKNOWN_OUTCOME_CODES = new Set(['command_result_unknown', 'command_lost', 'result_evicted']);

/**
 * True when a thrown error carries an unknown-outcome code — the browser-side
 * command may still be running even though the client gave up. Callers use this
 * to decide whether it is safe to release a persistent site-session lease: it is
 * not, because the still-running command keeps mutating the tab. Walks the cause
 * chain so a wrapped `BrowserCommandError` is still recognized.
 */
export function isUnknownOutcomeError(err: unknown): boolean {
  const seen = new Set<unknown>();
  let current: unknown = err;
  while (current && typeof current === 'object' && !seen.has(current)) {
    seen.add(current);
    const code = (current as { code?: unknown }).code;
    if (typeof code === 'string' && UNKNOWN_OUTCOME_CODES.has(code)) return true;
    current = (current as { cause?: unknown }).cause;
  }
  return false;
}

/** Max transport attempts for one logical command (same id throughout). */
const TRANSPORT_MAX_ATTEMPTS = 4;

/**
 * undici surfaces network failures as `TypeError: fetch failed` with the real
 * error in `.cause` (possibly an AggregateError). Only failures that happen
 * before the request could reach the daemon are safe to auto-retry — a reset
 * or hang-up after connect means the daemon may have already dispatched the
 * command to the browser.
 */
const PRE_CONNECT_ERROR_CODES = new Set([
  'ECONNREFUSED',
  'UND_ERR_CONNECT_TIMEOUT',
  'EHOSTUNREACH',
  'ENETUNREACH',
  'ENOTFOUND',
]);

function isPreConnectFetchError(err: unknown): boolean {
  const queue: unknown[] = [err];
  const seen = new Set<unknown>();
  while (queue.length) {
    const current = queue.pop();
    if (!current || typeof current !== 'object' || seen.has(current)) continue;
    seen.add(current);
    const { code, cause, errors } = current as { code?: unknown; cause?: unknown; errors?: unknown };
    if (typeof code === 'string' && PRE_CONNECT_ERROR_CODES.has(code)) return true;
    if (cause) queue.push(cause);
    if (Array.isArray(errors)) queue.push(...errors);
  }
  return false;
}

export interface DaemonCommand extends Partial<SlotPolicy> {
  id: string;
  action: 'chrome-call' | 'chrome-describe' | 'exec' | 'navigate' | 'tabs' | 'cookies' | 'screenshot' | 'close-window' | 'close-owned-tab' | 'set-file-input' | 'insert-text' | 'bind' | 'network-capture-start' | 'network-capture-read' | 'wait-download' | 'cdp' | 'frames' | 'lease-release' | 'slot-acquire';
  retainIncomplete?: boolean;
  /** slot-acquire: pooled site and queue wait budget (policy fields via SlotPolicy). */
  site?: string;
  waitMs?: number;
  /** Target page identity (targetId). Cross-layer contract with the extension. */
  page?: string;
  code?: string;
  chromeMethod?: string;
  chromeArgs?: unknown[];
  session?: string;
  surface?: 'browser' | 'adapter';
  /** Adapter site session lifecycle. Persistent site sessions do not idle-expire. */
  siteSession?: 'ephemeral' | 'persistent';
  url?: string;
  op?: string;
  index?: number;
  domain?: string;
  format?: 'png' | 'jpeg';
  quality?: number;
  fullPage?: boolean;
  /** Override viewport width in CSS pixels for screenshot (0 / undefined = use current) */
  width?: number;
  /** Override viewport height in CSS pixels for screenshot (0 / undefined = use current; ignored when fullPage) */
  height?: number;

  /** Local file paths for set-file-input action */
  files?: string[];
  /** CSS selector for file input element (set-file-input action) */
  selector?: string;
  /** Raw text payload for insert-text action */
  text?: string;
  /** URL substring filter pattern for network capture */
  pattern?: string;
  /** Download wait timeout in milliseconds */
  timeoutMs?: number;
  cdpMethod?: string;
  cdpParams?: Record<string, unknown>;
  /** Window foreground/background policy for owned Browser Bridge containers. */
  windowMode?: 'foreground' | 'background';
  /** Custom idle timeout in seconds for this session. Overrides the default. */
  idleTimeout?: number;
  /** Frame index for cross-frame operations (0-based, from 'frames' action) */
  frameIndex?: number;
  /** Browser profile/context REQUIRED for this command (--profile / OPENCLI_PROFILE). Fails loud when offline. */
  contextId?: string;
  /**
   * Browser profile/context PREFERRED for this command (persisted config
   * default). The daemon uses it when connected, and falls back to the only
   * connected profile when it is not — a stale default must never veto live
   * reality. Mutually exclusive with `contextId`.
   */
  preferredContextId?: string;
  /**
   * Daemon-side command timeout in seconds. Set by the transport layer from
   * the effective command deadline; kept for older daemons — new code prefers
   * `deadlineAt`.
   */
  timeout?: number;
  /**
   * Absolute command deadline (epoch ms). All hops run on one machine, so
   * every layer derives its remaining budget as `deadlineAt - Date.now()`,
   * absorbing queueing and service-worker wake latency.
   */
  deadlineAt?: number;
  /**
   * Stable id for the whole logical CLI command run (NOT the per-exec `id`).
   * The daemon uses it to arbitrate a write lease on the persistent site
   * session: the first command acquires, same-runId execs refresh it as a
   * heartbeat, a concurrent different-runId write fails fast. See session-lease.ts.
   */
  runId?: string;
  /** Human command name (e.g. `chatgpt ask`) surfaced in the busy error. */
  command?: string;
  /** Command access level; only 'write' commands take/hold a session lease. */
  access?: 'read' | 'write';
}

export interface DaemonResult {
  id: string;
  ok: boolean;
  data?: unknown;
  error?: string;
  errorCode?: string;
  errorHint?: string;
  /** Page identity (targetId) — present on page-scoped command responses */
  page?: string;
}

export class BrowserCommandError extends Error {
  constructor(message: string, readonly code?: string, readonly hint?: string) {
    super(message);
    this.name = 'BrowserCommandError';
  }
}

export {
  fetchDaemonStatus,
  getDaemonHealth,
  requestDaemonShutdown,
  type BrowserProfileStatus,
  type DaemonHealth,
  type DaemonStatus,
};

/**
 * Internal: send a command to the daemon and return the raw `DaemonResult`.
 *
 * There are exactly two retry classes, with different id semantics:
 *
 * TRANSPORT retries — the SAME command id, so the executor's journal replays
 * an already-executed command instead of re-running it:
 * - fetch failures (daemon down/replaced/crashed): run the ensure path (which
 *   also spawns the daemon and tells us the extension version), then resend.
 *   Requires a journaling extension unless the failure was pre-connect;
 * - pre-dispatch bridge/profile errors and `daemon_shutting_down`;
 * - a duplicate id landing on a still-pending command attaches to it in the
 *   daemon (no re-dispatch), so same-id resends never double-execute.
 *
 * SEMANTIC retry — ONE new logical attempt with a NEW id, only for executor
 * errors that happened before any page code ran (`attach_failed`/`tab_gone`).
 * `target_navigated` is the page layer's decision, not ours.
 *
 * Never retried: `command_result_unknown` / `command_lost` / `result_evicted`
 * (the outcome is genuinely unknown) and client-side AbortError (the shared
 * deadline is already exhausted).
 */
async function sendCommandRaw(
  action: DaemonCommand['action'],
  params: Omit<DaemonCommand, 'id' | 'action'>,
): Promise<DaemonResult> {
  const timeoutSeconds = effectiveCommandTimeoutSeconds(params);
  const deadlineAt = Date.now() + timeoutSeconds * 1000;
  const rawWindowMode = process.env.OPENCLI_WINDOW;
  const envWindowMode = rawWindowMode === 'foreground' || rawWindowMode === 'background'
    ? rawWindowMode
    : undefined;
  // Requirement vs preference: an explicit contextId routes strictly; a
  // preferred one is arbitrated by the daemon against live connections.
  const routing = params.contextId || params.preferredContextId
    ? { contextId: params.contextId, preferredContextId: params.preferredContextId }
    : profileRouteParams(resolveProfileSelection());
  const contextId = routing.contextId;
  const preferredContextId = routing.preferredContextId;
  const windowMode = params.windowMode ?? envWindowMode;
  // Override the owned session idle timeout, not the container window lifetime.
  // Explicit close still releases ephemeral sessions; persistent adapter sessions
  // and borrowed bound tabs ignore idle timeouts. Per-command values take priority.
  // The extension ignores 0, so only positive integers are forwarded.
  const rawIdleTimeout = process.env.OPENCLI_BROWSER_IDLE_TIMEOUT;
  const envIdleTimeout = rawIdleTimeout && /^\d+$/.test(rawIdleTimeout) && Number(rawIdleTimeout) > 0
    ? Number(rawIdleTimeout)
    : undefined;
  const idleTimeout = params.idleTimeout ?? envIdleTimeout;

  let id = generateId();
  let ensureUsed = false;
  let semanticRetryUsed = false;
  let executorJournaled: boolean | null = null;

  const ensureBridge = async (): Promise<void> => {
    // Bound the connect wait by the command's remaining budget so repeated
    // daemon failures cannot stretch the total wall time far past --timeout.
    const remainingSeconds = Math.ceil((deadlineAt - Date.now()) / 1000);
    const health = await ensureBrowserBridgeReady({
      timeoutSeconds: Math.max(1, Math.min(DEFAULT_BROWSER_CONNECT_TIMEOUT, remainingSeconds)),
      // Only an explicit requirement pins readiness to a specific profile; a
      // preferred one is arbitrated against live connections on every poll,
      // so a stale default still cannot hang the ensure path while a valid
      // one avoids the multi-profile ambiguity error (#2259).
      contextId,
      preferredContextId,
      verbose: false,
    });
    executorJournaled = supportsCommandJournal(health.status?.extensionVersion, health.status?.extensionCompatRange);
  };

  for (let attempt = 1; attempt <= TRANSPORT_MAX_ATTEMPTS; attempt++) {
    if (attempt > 1 && Date.now() >= deadlineAt) {
      throw new BrowserCommandError(
        'Browser command deadline exhausted across transport retries.',
        COMMAND_RESULT_UNKNOWN_CODE,
        COMMAND_RESULT_UNKNOWN_HINT,
      );
    }
    const remainingMs = Math.max(1000, deadlineAt - Date.now());
    const command: DaemonCommand = {
      id,
      action,
      ...params,
      timeout: timeoutSeconds,
      deadlineAt,
      ...(contextId && { contextId }),
      ...(preferredContextId && { preferredContextId }),
      ...(windowMode && { windowMode }),
      ...(idleTimeout !== undefined && { idleTimeout }),
      // Carry the run identity so the daemon can acquire/refresh the write
      // lease on the persistent site session. The same runId across every exec
      // of one command is the heartbeat that keeps a long-running holder alive.
      ...(_runContext && {
        runId: _runContext.runId,
        command: _runContext.command,
        access: _runContext.access,
      }),
    };
    try {
      const res = await requestDaemon('/command', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify(command),
        timeout: remainingMs + HTTP_TIMEOUT_MARGIN_MS,
      });

      const result = (await res.json()) as DaemonResult;

      if (result.ok) return result;

      // A second concurrent write on the same persistent site session is
      // rejected before the daemon dispatches anything — terminal, never
      // retried, and surfaced as a CliError so the busy message is the output.
      if (result.errorCode === 'session_busy' || result.errorCode === 'slot_wait_timeout' || result.errorCode === 'slot_conflict') {
        throw new SessionBusyError(result.error ?? 'The site session is busy.', result.errorHint);
      }

      if (result.errorCode && UNKNOWN_OUTCOME_CODES.has(result.errorCode)) {
        throw new BrowserCommandError(result.error ?? 'Browser command result is unknown', result.errorCode, result.errorHint);
      }

      if (isPreDispatchError(result.errorCode) && !ensureUsed) {
        // Never dispatched — resending the same id is safe on any extension.
        ensureUsed = true;
        await ensureBridge();
        continue;
      }

      if (result.errorCode === 'daemon_shutting_down' && !ensureUsed) {
        // The command WAS dispatched and the daemon died before the result
        // came back. Resending the same id is only safe when the extension
        // journals ids; otherwise the outcome is genuinely unknown.
        ensureUsed = true;
        await ensureBridge();
        if (executorJournaled) continue;
        throw new BrowserCommandError(
          result.error ?? 'Daemon shut down mid-command; the command may have already been applied.',
          COMMAND_RESULT_UNKNOWN_CODE,
          COMMAND_RESULT_UNKNOWN_HINT,
        );
      }

      const advice = classifyBrowserError(new BrowserCommandError(result.error ?? '', result.errorCode));
      if (advice.kind === 'extension-transient' && !semanticRetryUsed) {
        semanticRetryUsed = true;
        id = generateId();
        await sleep(advice.delayMs);
        continue;
      }

      throw new BrowserCommandError(result.error ?? 'Daemon command failed', result.errorCode, result.errorHint);
    } catch (err) {
      if (err instanceof BrowserCommandError || err instanceof BrowserConnectError || err instanceof SessionBusyError) throw err;

      if (err instanceof Error && err.name === 'AbortError') {
        throw new BrowserCommandError(
          'Browser command timed out client-side; the page may still have applied it.',
          COMMAND_RESULT_UNKNOWN_CODE,
          COMMAND_RESULT_UNKNOWN_HINT,
        );
      }

      if (err instanceof TypeError) {
        // Transport failure — the request may or may not have reached the
        // daemon. Bring the bridge back up (spawns a daemon if none is
        // running) and learn whether the extension journals command ids.
        await ensureBridge();
        // Same-id resend is safe when the request never connected, or when
        // the executor dedupes ids. Otherwise the outcome is unknown.
        if (executorJournaled || isPreConnectFetchError(err)) continue;
        throw new BrowserCommandError(
          'Connection to the daemon was lost mid-command; it may have already been applied.',
          COMMAND_RESULT_UNKNOWN_CODE,
          COMMAND_RESULT_UNKNOWN_HINT,
        );
      }

      throw err;
    }
  }

  throw new BrowserCommandError('sendCommand: max attempts exhausted', 'max_attempts_exhausted');
}

/**
 * Send a command to the daemon and return the result data.
 */
export async function sendCommand(
  action: DaemonCommand['action'],
  params: Omit<DaemonCommand, 'id' | 'action'> = {},
): Promise<unknown> {
  const result = await sendCommandRaw(action, params);
  return result.data;
}

/**
 * Like sendCommand, but returns both data and page identity (targetId).
 * Use this for page-scoped commands where the caller needs the page identity.
 */
export async function sendCommandFull(
  action: DaemonCommand['action'],
  params: Omit<DaemonCommand, 'id' | 'action'> = {},
): Promise<{ data: unknown; page?: string }> {
  const result = await sendCommandRaw(action, params);
  return { data: result.data, page: result.page };
}

export async function bindTab(session: string, opts: { contextId?: string } = {}): Promise<unknown> {
  return sendCommand('bind', { session, surface: 'browser', ...opts });
}