agents 0.26.0 → 0.28.0

package/dist/browser-tool-4iomavs_.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"browser-tool-4iomavs_.js","names":[],"sources":["../src/browser/session-connector.ts","../src/browser/browser-tool.ts"],"sourcesContent":["import {\n  CodemodeConnector,\n  MAX_DURABLE_VALUE_BYTES,\n  type ConnectorTool,\n  type ConnectorTools,\n  type ToolExecuteContext\n} from \"@cloudflare/codemode\";\nimport { validateConnectorArgs } from \"./connector-validation\";\nimport {\n  CDP_METHOD_NOT_FOUND,\n  CdpProtocolError,\n  type CdpConnection\n} from \"./cdp-connection\";\nimport type { BrowserConnection, BrowserConnectOptions } from \"./browser\";\nimport type { SearchableCdpSpec } from \"./spec\";\n\n/**\n * Where a {@link BrowserSessionConnector} gets its browser. Usually a\n * `Browser` installed on the host's Lifecycle.\n */\nexport interface BrowserSource {\n  /** The browser's name, for log messages. */\n  readonly name: string;\n  /**\n   * Reattach to the browser (or replace it) and open a CDP connection for\n   * a scope. A source that ignores `scope` shares one active tab between\n   * every caller.\n   */\n  connect(options?: BrowserConnectOptions): Promise<BrowserConnection>;\n}\n\nexport interface BrowserSessionConnectorOptions {\n  /** The persistent browser this connector drives. */\n  browser: BrowserSource;\n  /**\n   * The scope this connector's executions work in: they share one active\n   * tab, kept apart from other scopes'. Defaults to the browser's default\n   * scope.\n   */\n  scope?: string;\n}\n\n/** A tab a page opened on its own during an execution. */\nexport interface BrowserNewTab {\n  targetId: string;\n  url?: string;\n  title?: string;\n}\n\n/**\n * What happened to the browser during one execution, beyond the code's own\n * result — read by the tool after the run via\n * {@link BrowserSessionConnector.takeReport}.\n */\nexport interface BrowserExecutionReport {\n  /** The browser was replaced before this run; earlier page state is gone. */\n  restarted: boolean;\n  /** Tabs the page opened itself (popups, `target=_blank`). */\n  newTabs: BrowserNewTab[];\n  /**\n   * The tab this scope was working in was closed by someone else (another\n   * scope, or a person in Live View), so `\"active\"` will be a new blank tab.\n   */\n  tabClosed: boolean;\n  /** Another scope is working in this scope's active tab too. */\n  tabShared: boolean;\n}\n\n/** `sessionId` value that addresses the tab the agent is working in. */\nexport const ACTIVE_PAGE_SESSION = \"active\";\n\n/**\n * `cdp.attachToTarget` returns `{ sessionId: \"target:<targetId>\" }` — a\n * stable handle rather than a connection-scoped CDP session id, so replayed\n * code computes identical arguments. `send` resolves it on the live socket.\n */\nconst ATTACH_HANDLE_PREFIX = \"target:\";\n\n/** Chrome's JSON-RPC code for a CDP session id it doesn't know. */\nconst CDP_SESSION_NOT_FOUND = -32001;\n\n/**\n * Codemode records every `send` result for replay and fails the run when one\n * is over {@link MAX_DURABLE_VALUE_BYTES}, telling the model to write to a\n * file, which this sandbox can't. A full-page screenshot is the usual\n * culprit, so say how to take a smaller one instead.\n */\nfunction assertScreenshotFits(result: unknown): void {\n  // Measure the result as codemode stores it (JSON), not just the data, so a\n  // screenshot just under the limit can't slip past with its JSON framing.\n  const size = JSON.stringify(result ?? null).length;\n  if (size <= MAX_DURABLE_VALUE_BYTES) return;\n  const megabytes = (size / 1_000_000).toFixed(1);\n  throw new Error(\n    `The screenshot result is ${megabytes} MB, over the 1 MB limit on a ` +\n      `cdp.send result. Capture just the viewport (no captureBeyondViewport ` +\n      `or clip larger than the window), or pass format: \"jpeg\" with ` +\n      `quality: 60.`\n  );\n}\n\n/** {@link BrowserSessionConnector} `#liveParams`: nothing to detach. */\nconst DETACHED = Symbol(\"detached\");\n\n/** Reports awaiting their tool call; bounded in case a caller never reads. */\nconst MAX_PENDING_REPORTS = 100;\n\n/**\n * Commands that would end the browser. The host owns its lifetime, so the\n * model can't close it out from under the agent (and lose its logins).\n */\nconst BROWSER_LIFETIME_COMMANDS = new Set([\n  \"Browser.close\",\n  \"Browser.crash\",\n  \"Browser.crashGpuProcess\"\n]);\n\n/** A CDP target id — for this connector, a tab. */\ntype TargetId = string & { readonly __brand: \"TargetId\" };\n\n/** A CDP session id from `Target.attachToTarget`, valid on one socket only. */\ntype LiveSessionId = string & { readonly __brand: \"LiveSessionId\" };\n\n/** The stable `sessionId` handle `cdp.attachToTarget` gives the model. */\ntype AttachHandle = `${typeof ATTACH_HANDLE_PREFIX}${string}`;\n\ninterface TargetInfo {\n  targetId: TargetId;\n  type: string;\n  url?: string;\n  title?: string;\n  /** The tab that opened this one (popups, `target=_blank` links). */\n  openerId?: TargetId;\n}\n\n/** Per-execution state for one pass. Dropped when the pass ends. */\ninterface ExecutionState {\n  executionId: string;\n  connected: BrowserConnection;\n  /** Live CDP session per target, valid on this socket only. */\n  attached: Map<TargetId, LiveSessionId>;\n  /**\n   * Tabs this pass attached to, through the connector or a raw\n   * `Target.attachToTarget`. Their popups are this pass's new tabs.\n   */\n  workedIn: Set<TargetId>;\n  /** Page targets open when the pass connected. */\n  initialPages: Set<TargetId>;\n  /** The tab `\"active\"` resolves to — decided lazily on first use. */\n  activeTargetId?: TargetId;\n  /** Whether {@link activeTargetId} was decided (vs. never needed). */\n  activeResolved: boolean;\n  /** Tabs this pass closed with `Target.closeTarget`. */\n  closed: Set<TargetId>;\n}\n\n/**\n * How to use the `cdp` connector, one rule per line. `codemode.describe(\"cdp\")`\n * returns these, and `browserTool` puts them in its description. Each rule\n * fixes a mistake models make with CDP, or states something about this\n * browser they can't know; leave out what a model knows already.\n */\nexport const BROWSER_INSTRUCTIONS = [\n  \"The browser persists between runs: tabs, cookies, and logins are still there next time. You never start or close it.\",\n  \"If the browser was replaced (idle timeout, crash), the result says restarted: true and earlier tabs and logins are gone. Before an action that matters (submitting a form, a purchase), check you're on the page you expect.\",\n  'Page-scoped commands (Page.*, Runtime.*, DOM.*, Input.*, Network.*, Emulation.*) need sessionId: \"active\", your tab, which is remembered between runs. Browser.* and Target.* commands take no sessionId.',\n  \"Other open tabs (Target.getTargets) may belong to other conversations using this browser: don't close, navigate, or attach to a tab you didn't open unless the user asks.\",\n  \"Target.createTarget opens a tab and makes it active. To switch to another open tab, call cdp.attachToTarget({ targetId }); the sessionId it returns keeps working in later runs, while one from a raw Target.attachToTarget only works in the current run.\",\n  \"Tabs a page opens itself (popups, target=_blank links) don't become active; the result lists them as newTabs.\",\n  \"Runtime.evaluate: pass returnByValue: true, or objects come back as a remote reference with no value, and awaitPromise: true for async expressions. The value is at result.value. A thrown error doesn't reject: check exceptionDetails.\",\n  \"Page.navigate returns before the page loads and doesn't throw when it fails: check errorText, then poll document.readyState with Runtime.evaluate until it is 'complete'.\",\n  \"Pick out what you need inside Runtime.evaluate and return only that. Results over about 24,000 characters are cut short, and a single cdp.send result over 1 MB (a full-page screenshot, say) fails the run.\"\n].join(\"\\n\");\n\n/**\n * Codemode connector exposing one host-named, persistent browser over the\n * Chrome DevTools Protocol as the `cdp` global.\n *\n * The model never manages sessions: every execution reattaches to the\n * browser (or gets a replacement, reported as `restarted`), and\n * `sessionId: \"active\"` addresses the tab it last worked in. The active tab\n * is stored per scope (see {@link BrowserSessionConnectorOptions.scope}), so\n * it survives between executions for as long as the tab does, and one\n * scope's executions never land in another scope's tab unless the model\n * attaches to it.\n *\n * The CDP socket is per pass: opened on the first call, closed when the pass\n * ends. The browser itself outlives the execution.\n */\nexport class BrowserSessionConnector extends CodemodeConnector {\n  readonly #browser: BrowserSource;\n  readonly #scope: string | undefined;\n  #states = new Map<string, ExecutionState>();\n  #connecting = new Map<string, Promise<ExecutionState>>();\n  /**\n   * In memory, on this instance. An execution resumed after an approval\n   * pause may run on a fresh connector, whose report starts over. Nothing\n   * pauses today — the browser tool wires no approval tools — so reporting\n   * across a resume is left for when approvals are added.\n   *\n   * The same goes for raw CDP session ids from `Target.attachToTarget` sent\n   * through `send`: they belong to one pass's socket, so a replay after a\n   * pause would reuse a dead id. The stable handles from `attachToTarget`\n   * are the replay-safe path.\n   */\n  #reports = new Map<string, BrowserExecutionReport>();\n\n  constructor(\n    ctx: DurableObjectState | ExecutionContext,\n    options: BrowserSessionConnectorOptions\n  ) {\n    super(ctx, {});\n    this.#browser = options.browser;\n    this.#scope = options.scope;\n  }\n\n  name(): string {\n    return \"cdp\";\n  }\n\n  protected instructions(): string {\n    return BROWSER_INSTRUCTIONS;\n  }\n\n  protected override tool(name: string, tool: ConnectorTool): ConnectorTool {\n    return validateConnectorArgs(this.name(), name, tool);\n  }\n\n  protected tools(): ConnectorTools {\n    return {\n      send: {\n        description:\n          'Send a CDP command and return its method result directly. Pass sessionId: \"active\" for page-scoped commands; omit it for Browser/Target commands.',\n        inputSchema: {\n          type: \"object\",\n          properties: {\n            method: {\n              type: \"string\",\n              description: 'CDP method, e.g. \"Page.navigate\"'\n            },\n            params: {\n              type: \"object\",\n              description: \"CDP command parameters\"\n            },\n            sessionId: {\n              type: \"string\",\n              description:\n                '\"active\" for the current tab, or a handle from attachToTarget. Omit for Browser/Target commands.'\n            },\n            timeoutMs: {\n              type: \"number\",\n              description: \"Per-command timeout override in milliseconds\"\n            }\n          },\n          required: [\"method\"]\n        },\n        execute: async (args, ctx) => {\n          const { method, params, sessionId, timeoutMs } = args as {\n            method: string;\n            params?: Record<string, unknown>;\n            sessionId?: string;\n            timeoutMs?: number;\n          };\n          if (BROWSER_LIFETIME_COMMANDS.has(method)) {\n            throw new Error(\n              `${method} is not available: this browser is managed for you ` +\n                `and persists between runs. To close a tab, send ` +\n                `Target.closeTarget with its targetId.`\n            );\n          }\n          const state = await this.#state(this.#executionId(ctx));\n          const live = await this.#resolveSessionId(state, sessionId);\n          const liveParams = this.#liveParams(state, method, params);\n          if (liveParams === DETACHED) return {};\n          let result: unknown;\n          try {\n            result = await state.connected.cdp.send(method, liveParams, {\n              sessionId: live,\n              timeoutMs\n            });\n          } catch (error) {\n            throw await this.#teach(state, error, method, sessionId);\n          }\n          this.#observe(state, method, liveParams, result);\n          if (method === \"Page.captureScreenshot\") {\n            assertScreenshotFits(result);\n          }\n          return result;\n        }\n      },\n\n      attachToTarget: {\n        description:\n          \"Switch to an open tab: make it the active tab and return { sessionId } — a handle you can pass to page-scoped send calls for that tab.\",\n        inputSchema: {\n          type: \"object\",\n          properties: {\n            targetId: {\n              type: \"string\",\n              description: \"Target id from Target.getTargets/createTarget\"\n            },\n            timeoutMs: { type: \"number\" }\n          },\n          required: [\"targetId\"]\n        },\n        outputSchema: {\n          type: \"object\",\n          properties: {\n            sessionId: {\n              type: \"string\",\n              description: \"Session handle for page-scoped send calls\"\n            }\n          },\n          required: [\"sessionId\"]\n        },\n        execute: async (args, ctx) => {\n          const { targetId, timeoutMs } = args as {\n            targetId: TargetId;\n            timeoutMs?: number;\n          };\n          const state = await this.#state(this.#executionId(ctx));\n          await this.#attach(state, targetId, timeoutMs);\n          this.#setActive(state, targetId);\n          return { sessionId: attachHandle(targetId) };\n        }\n      },\n\n      spec: {\n        description:\n          \"Return the searchable Chrome DevTools Protocol spec: domains with their commands, events, and types.\",\n        replay: \"reexecute\",\n        inputSchema: { type: \"object\", properties: {} },\n        execute: async (_args, ctx): Promise<SearchableCdpSpec> => {\n          const state = await this.#state(this.#executionId(ctx));\n          return state.connected.spec();\n        }\n      },\n\n      getDebugLog: {\n        description:\n          \"Return recent CDP protocol traffic (sends, receives, warnings) for this execution — useful to diagnose failures and timeouts.\",\n        replay: \"reexecute\",\n        inputSchema: {\n          type: \"object\",\n          properties: {\n            limit: {\n              type: \"number\",\n              minimum: 1,\n              description:\n                \"Max entries to return, newest last (default 50; only the last 400 are kept)\"\n            }\n          }\n        },\n        execute: async (args, ctx) => {\n          const { limit } = (args ?? {}) as { limit?: number };\n          const state = await this.#state(this.#executionId(ctx));\n          return state.connected.cdp.getDebugLog(limit);\n        }\n      },\n\n      clearDebugLog: {\n        description: \"Clear the CDP debug log for this execution.\",\n        inputSchema: { type: \"object\", properties: {} },\n        execute: async (_args, ctx) => {\n          const state = await this.#state(this.#executionId(ctx));\n          state.connected.cdp.clearDebugLog();\n          return null;\n        }\n      }\n    };\n  }\n\n  // ── Codemode execution hooks ─────────────────────────────────────────────\n\n  /**\n   * The pass is over: note tabs the page opened, save the scope's active\n   * tab, note whether another scope shares it, and drop the socket. The\n   * browser stays alive.\n   */\n  override async onPassEnd(executionId: string): Promise<void> {\n    const state = this.#states.get(executionId);\n    if (!state) return;\n    this.#states.delete(executionId);\n    try {\n      const open = await this.#recordNewTabs(executionId, state);\n      const active = await this.#saveActiveTarget(state, open);\n      if (active && state.activeResolved) {\n        await this.#recordSharedTab(state, active);\n      }\n    } finally {\n      state.connected.cdp.disconnect();\n    }\n  }\n\n  /** Nothing per execution outlives the pass; the named browser persists. */\n  override async disposeExecution(executionId: string): Promise<void> {\n    const state = this.#states.get(executionId);\n    if (!state) return;\n    this.#states.delete(executionId);\n    state.connected.cdp.disconnect();\n  }\n\n  /**\n   * Take (and forget) what happened to the browser during an execution.\n   * `undefined` when the execution never touched the browser. Covers the\n   * passes this instance ran; see the note on `#reports`.\n   */\n  takeReport(executionId: string): BrowserExecutionReport | undefined {\n    const report = this.#reports.get(executionId);\n    this.#reports.delete(executionId);\n    return report;\n  }\n\n  // ── Internals ────────────────────────────────────────────────────────────\n\n  #executionId(ctx: ToolExecuteContext | undefined): string {\n    if (!ctx?.executionId) {\n      throw new Error(\"Browser tools must run inside a codemode execution\");\n    }\n    return ctx.executionId;\n  }\n\n  /**\n   * Connect once per pass. Concurrent first calls (model code that uses\n   * Promise.all despite the instructions) share one connect.\n   */\n  #state(executionId: string): Promise<ExecutionState> {\n    const existing = this.#states.get(executionId);\n    if (existing) return Promise.resolve(existing);\n    const inFlight = this.#connecting.get(executionId);\n    if (inFlight) return inFlight;\n    const promise = this.#connect(executionId).finally(() => {\n      this.#connecting.delete(executionId);\n    });\n    this.#connecting.set(executionId, promise);\n    return promise;\n  }\n\n  async #connect(executionId: string): Promise<ExecutionState> {\n    const connected = await this.#browser.connect(\n      this.#scope === undefined ? undefined : { scope: this.#scope }\n    );\n    let initialPages: TargetInfo[];\n    try {\n      initialPages = await this.#pages(connected.cdp);\n    } catch (error) {\n      connected.cdp.disconnect();\n      throw error;\n    }\n    const state: ExecutionState = {\n      executionId,\n      connected,\n      attached: new Map(),\n      workedIn: new Set(),\n      initialPages: new Set(initialPages.map((page) => page.targetId)),\n      activeResolved: false,\n      closed: new Set()\n    };\n    this.#states.set(executionId, state);\n    this.#report(executionId, connected.restarted);\n    return state;\n  }\n\n  #report(executionId: string, restarted: boolean): BrowserExecutionReport {\n    let report = this.#reports.get(executionId);\n    if (!report) {\n      report = { restarted, newTabs: [], tabClosed: false, tabShared: false };\n      this.#reports.set(executionId, report);\n      if (this.#reports.size > MAX_PENDING_REPORTS) {\n        const oldest = this.#reports.keys().next().value;\n        if (oldest !== undefined) this.#reports.delete(oldest);\n      }\n    }\n    // A replacement on any pass means earlier page state is gone.\n    report.restarted ||= restarted;\n    return report;\n  }\n\n  /**\n   * Add tabs the page opened this pass to the execution's report, and drop\n   * earlier ones that have since closed: `newTabs` lists page-opened tabs\n   * still open when the execution ends, across every pass. Returns the open\n   * tabs, or `undefined` when the browser couldn't be asked.\n   */\n  async #recordNewTabs(\n    executionId: string,\n    state: ExecutionState\n  ): Promise<Set<TargetId> | undefined> {\n    let pages: TargetInfo[];\n    try {\n      pages = await this.#pages(state.connected.cdp);\n    } catch (error) {\n      this.#warn(\"list the open tabs\", error);\n      return undefined;\n    }\n    const report = this.#report(executionId, state.connected.restarted);\n    const opened = new Set<string>(report.newTabs.map((tab) => tab.targetId));\n    // A new tab is this execution's when its opener is a tab this pass\n    // worked in, or another of its new tabs (a popup's popup). Chrome sets\n    // openerId only on tabs a page opened, never on Target.createTarget\n    // tabs, and a popup another scope's page opened meanwhile has that\n    // scope's tab as its opener.\n    let grew = true;\n    while (grew) {\n      grew = false;\n      for (const page of pages) {\n        const opener = page.openerId;\n        if (\n          !opener ||\n          opened.has(page.targetId) ||\n          state.initialPages.has(page.targetId)\n        ) {\n          continue;\n        }\n        if (state.workedIn.has(opener) || opened.has(opener)) {\n          opened.add(page.targetId);\n          grew = true;\n        }\n      }\n    }\n    report.newTabs = pages\n      .filter((page) => opened.has(page.targetId))\n      .map(({ targetId, url, title }) => ({ targetId, url, title }));\n    return new Set(pages.map((page) => page.targetId));\n  }\n\n  /**\n   * Save the tab this pass settled on, forgetting one that has since closed,\n   * and return it. Without the list of open tabs, save the choice\n   * unchecked: the next execution checks the stored tab is still open\n   * before using it.\n   */\n  async #saveActiveTarget(\n    state: ExecutionState,\n    open: Set<TargetId> | undefined\n  ): Promise<TargetId | undefined> {\n    const stored = state.connected.activeTargetId as TargetId | undefined;\n    // A pass that never used \"active\" still sees the stored tab is gone;\n    // say so now, since the next pass won't know there was one.\n    if (\n      !state.activeResolved &&\n      stored &&\n      open &&\n      !open.has(stored) &&\n      !state.closed.has(stored)\n    ) {\n      this.#report(state.executionId, state.connected.restarted).tabClosed =\n        true;\n    }\n    const candidate = state.activeResolved ? state.activeTargetId : stored;\n    const active =\n      candidate && (!open || open.has(candidate)) ? candidate : undefined;\n    if (active === stored) return active;\n    try {\n      await state.connected.setActiveTarget(active);\n    } catch (error) {\n      this.#warn(\"save the active tab\", error);\n    }\n    return active;\n  }\n\n  /** Report when another scope is working in this pass's tab too. */\n  async #recordSharedTab(\n    state: ExecutionState,\n    active: TargetId\n  ): Promise<void> {\n    try {\n      const others = await state.connected.targetsInOtherScopes();\n      if (others.has(active)) {\n        this.#report(state.executionId, state.connected.restarted).tabShared =\n          true;\n      }\n    } catch (error) {\n      this.#warn(\"check whether the active tab is shared\", error);\n    }\n  }\n\n  #warn(action: string, error: unknown): void {\n    console.warn(\n      `[agents/browser] Failed to ${action} for browser \"${this.#browser.name}\"`,\n      error\n    );\n  }\n\n  async #pages(cdp: CdpConnection): Promise<TargetInfo[]> {\n    const result = (await cdp.send(\"Target.getTargets\")) as {\n      targetInfos?: TargetInfo[];\n    };\n    return (result?.targetInfos ?? []).filter((info) => info.type === \"page\");\n  }\n\n  async #resolveSessionId(\n    state: ExecutionState,\n    sessionId: string | undefined\n  ): Promise<LiveSessionId | undefined> {\n    if (sessionId === ACTIVE_PAGE_SESSION) {\n      return this.#attach(state, await this.#activeTarget(state));\n    }\n    if (isAttachHandle(sessionId)) {\n      return this.#attach(state, targetOfHandle(sessionId));\n    }\n    // Omitted, or a raw CDP session id the model got from send().\n    return sessionId as LiveSessionId | undefined;\n  }\n\n  /**\n   * Decide which tab `\"active\"` means, once per pass: the scope's stored tab\n   * if it is still open, else a new blank tab. Never a tab the scope didn't\n   * open, even a blank one: it may be another scope's, or a popup.\n   */\n  async #activeTarget(state: ExecutionState): Promise<TargetId> {\n    if (state.activeTargetId) return state.activeTargetId;\n    const { connected } = state;\n    const pages = await this.#pages(connected.cdp);\n    const stored = connected.activeTargetId as TargetId | undefined;\n    let targetId = pages.find((page) => page.targetId === stored)?.targetId;\n    if (!targetId && stored && !state.closed.has(stored)) {\n      this.#report(state.executionId, connected.restarted).tabClosed = true;\n    }\n    if (!targetId) {\n      const created = (await connected.cdp.send(\"Target.createTarget\", {\n        url: \"about:blank\"\n      })) as { targetId: TargetId };\n      targetId = created.targetId;\n    }\n    this.#setActive(state, targetId);\n    return targetId;\n  }\n\n  #setActive(state: ExecutionState, targetId: TargetId | undefined): void {\n    state.activeTargetId = targetId;\n    state.activeResolved = true;\n  }\n\n  async #attach(\n    state: ExecutionState,\n    targetId: TargetId,\n    timeoutMs?: number\n  ): Promise<LiveSessionId> {\n    const existing = state.attached.get(targetId);\n    if (existing) return existing;\n    const live = (await state.connected.cdp.attachToTarget(targetId, {\n      timeoutMs\n    })) as LiveSessionId;\n    state.attached.set(targetId, live);\n    state.workedIn.add(targetId);\n    return live;\n  }\n\n  /** Track tab changes the model makes through raw Target commands. */\n  #observe(\n    state: ExecutionState,\n    method: string,\n    params: Record<string, unknown> | undefined,\n    result: unknown\n  ): void {\n    const targetId =\n      typeof params?.targetId === \"string\"\n        ? (params.targetId as TargetId)\n        : undefined;\n    if (method === \"Target.createTarget\") {\n      const created = (result as { targetId?: unknown } | undefined)?.targetId;\n      if (typeof created === \"string\") {\n        this.#setActive(state, created as TargetId);\n      }\n    } else if (method === \"Target.attachToTarget\" && targetId) {\n      this.#setActive(state, targetId);\n      state.workedIn.add(targetId);\n    } else if (method === \"Target.closeTarget\" && targetId) {\n      state.attached.delete(targetId);\n      state.closed.add(targetId);\n      // The next \"active\" use picks a tab afresh.\n      if (state.activeTargetId === targetId) state.activeTargetId = undefined;\n    } else if (method === \"Target.detachFromTarget\") {\n      // Forget a session the model detached, so the next use reattaches.\n      for (const [target, live] of state.attached) {\n        if (target === targetId || live === params?.sessionId) {\n          state.attached.delete(target);\n        }\n      }\n    }\n  }\n\n  /**\n   * Swap a handle in `Target.detachFromTarget`'s `sessionId` param for the\n   * live CDP session id. Returns {@link DETACHED} when the handle's tab isn't\n   * attached on this socket, so there is nothing to detach.\n   */\n  #liveParams(\n    state: ExecutionState,\n    method: string,\n    params: Record<string, unknown> | undefined\n  ): Record<string, unknown> | undefined | typeof DETACHED {\n    const handle = params?.sessionId;\n    if (method !== \"Target.detachFromTarget\" || typeof handle !== \"string\") {\n      return params;\n    }\n    if (!isAttachHandle(handle)) return params;\n    const live = state.attached.get(targetOfHandle(handle));\n    return live ? { ...params, sessionId: live } : DETACHED;\n  }\n\n  /**\n   * Turn the common protocol mistakes into instructions: sending an\n   * event as a command, and a page-scoped command without a session.\n   */\n  async #teach(\n    state: ExecutionState,\n    error: unknown,\n    method: string,\n    sessionId: string | undefined\n  ): Promise<unknown> {\n    if (!(error instanceof CdpProtocolError)) return error;\n    if (\n      error.code === CDP_SESSION_NOT_FOUND &&\n      sessionId &&\n      sessionId !== ACTIVE_PAGE_SESSION &&\n      !isAttachHandle(sessionId)\n    ) {\n      return new Error(\n        `${error.message}. CDP session ids don't carry over between runs. ` +\n          `Use sessionId: \"active\" for the current tab, or the handle from ` +\n          `cdp.attachToTarget({ targetId }) for another tab.`\n      );\n    }\n    if (error.code !== CDP_METHOD_NOT_FOUND) return error;\n    if (await this.#isEvent(state, method)) {\n      return new Error(\n        `${error.message}. '${method}' is a CDP *event*, not a command — it ` +\n          `cannot be sent. To wait for page state, poll instead (e.g. ` +\n          `Runtime.evaluate of document.readyState until \"complete\").`\n      );\n    }\n    if (!sessionId) {\n      return new Error(\n        `${error.message}. '${method}' is page-scoped: pass sessionId: ` +\n          `\"active\" to run it in the current tab — ` +\n          `cdp.send({ method: \"${method}\", params, sessionId: \"active\" }).`\n      );\n    }\n    return error;\n  }\n\n  async #isEvent(state: ExecutionState, method: string): Promise<boolean> {\n    try {\n      const spec = await state.connected.spec();\n      const domain = method.split(\".\")[0];\n      return spec.domains.some(\n        (d) => d.name === domain && d.events.some((e) => e.event === method)\n      );\n    } catch {\n      return false;\n    }\n  }\n}\n\nfunction attachHandle(targetId: TargetId): AttachHandle {\n  return `${ATTACH_HANDLE_PREFIX}${targetId}`;\n}\n\nfunction isAttachHandle(\n  sessionId: string | undefined\n): sessionId is AttachHandle {\n  return sessionId?.startsWith(ATTACH_HANDLE_PREFIX) ?? false;\n}\n\nfunction targetOfHandle(handle: AttachHandle): TargetId {\n  return handle.slice(ATTACH_HANDLE_PREFIX.length) as TargetId;\n}\n","/**\n * The harness-neutral core of `browserTool`, shared by the adapters in\n * `tools/` (`agents/browser/ai-sdk`, `agents/browser/tanstack-ai`,\n * `agents/browser/pi`).\n * Internal — not an entry point.\n */\nimport {\n  createCodemodeRuntime,\n  DynamicWorkerExecutor,\n  type ProxyToolOutput\n} from \"@cloudflare/codemode\";\nimport { DEFAULT_BROWSER_SCOPE } from \"./browser\";\nimport {\n  BROWSER_INSTRUCTIONS,\n  BrowserSessionConnector,\n  type BrowserExecutionReport,\n  type BrowserNewTab,\n  type BrowserSource\n} from \"./session-connector\";\nimport { resolveCtx, transformBrowserResult } from \"./tool-helpers\";\n\nexport interface BrowserToolOptions {\n  /**\n   * The browser the tool drives — usually a `Browser` installed on the\n   * host's Lifecycle. Tools built from the same `Browser` share it.\n   */\n  browser: BrowserSource;\n\n  /**\n   * WorkerLoader binding for sandboxed code execution.\n   *\n   * Requires `\"worker_loaders\": [{ \"binding\": \"LOADER\" }]` in wrangler.jsonc.\n   */\n  loader: WorkerLoader;\n\n  /** Sandbox execution timeout in milliseconds. Defaults to 60000 (60s). */\n  timeoutMs?: number;\n\n  /**\n   * Who is driving, when several chats or users share one `Browser`: runs\n   * with the same scope share an active tab, and each scope keeps its own.\n   * Cookies and logins are shared by every scope. Defaults to `\"shared\"`,\n   * one active tab for every tool that leaves it out.\n   */\n  scope?: string;\n\n  /**\n   * Durable Object state for the codemode runtime facet. Optional inside an\n   * Agent (resolved via `getCurrentAgent()`); pass it explicitly elsewhere.\n   *\n   * The worker must export the `CodemodeRuntime` class (the\n   * `@cloudflare/codemode/vite` plugin does this automatically, or add\n   * `export { CodemodeRuntime } from \"@cloudflare/codemode\"` to your entry).\n   */\n  ctx?: DurableObjectState;\n}\n\n/** The model's input to `browserTool`: JavaScript to run. */\nexport interface BrowserToolInput {\n  code: string;\n}\n\n/**\n * The result of one `browserTool` run: the codemode execution result,\n * plus what happened to the browser.\n */\nexport type BrowserToolOutput = ProxyToolOutput & {\n  /** The browser was replaced before this run; earlier tabs are gone. */\n  restarted?: true;\n  /**\n   * Sentences telling the model what happened to its browser: it was\n   * restarted, its tab was closed by someone else, or another scope is\n   * working in its tab too.\n   */\n  notice?: string;\n  /** Tabs the page opened itself (popups, `target=_blank` links). */\n  newTabs?: BrowserNewTab[];\n};\n\nconst DEFAULT_TIMEOUT_MS = 60_000;\n\nconst RESTARTED_NOTICE =\n  \"The browser was restarted before this run (it expired or was closed): earlier tabs, logins, and page state are gone. Your code ran in a fresh browser — navigate again before relying on page state.\";\n\nconst TAB_CLOSED_NOTICE =\n  'The tab you were working in was closed (by another conversation using this browser, or a person). `sessionId: \"active\"` now opens a blank tab — navigate again before relying on page state.';\n\nconst TAB_SHARED_NOTICE =\n  \"Another conversation using this browser is also working in your tab, so its page may change between your runs. Open a tab of your own with Target.createTarget if you need one.\";\n\n/** Scopes whose runtime and connector stay built; older ones are rebuilt. */\nconst MAX_CACHED_SCOPES = 32;\n\n/**\n * A codemode runtime name per browser. Browser names are host-chosen and\n * unrestricted; runtime names allow only `[a-zA-Z0-9_.-]`, so anything else\n * (including `.`, the escape) is hex-escaped.\n */\nfunction browserRuntimeName(name: string): string {\n  const escaped = name.replace(\n    /[^a-zA-Z0-9_-]/g,\n    (char) => `.${char.codePointAt(0)?.toString(16)}.`\n  );\n  return `browser-tool_${escaped}`;\n}\n\n/**\n * The latest run queued per browser and scope, so runs in one scope go one\n * at a time, even from tools built separately (one per turn, say). Per\n * isolate, which is per Durable Object.\n */\nconst runQueues = new WeakMap<BrowserSource, Map<string, Promise<unknown>>>();\n\nfunction queued<T>(\n  browser: BrowserSource,\n  scope: string,\n  run: () => Promise<T>\n): Promise<T> {\n  let queues = runQueues.get(browser);\n  if (!queues) runQueues.set(browser, (queues = new Map()));\n  const previous = queues.get(scope) ?? Promise.resolve();\n  const next = previous.then(run, run);\n  const settled = next.catch(() => undefined);\n  queues.set(scope, settled);\n  void settled.then(() => {\n    if (queues.get(scope) === settled) queues.delete(scope);\n  });\n  return next;\n}\n\n/** Add what happened to the browser to the codemode result. */\nfunction withBrowserReport(\n  output: ProxyToolOutput,\n  report: BrowserExecutionReport | undefined\n): BrowserToolOutput {\n  if (!report) return output;\n  const notices = [\n    report.restarted && RESTARTED_NOTICE,\n    report.tabClosed && !report.restarted && TAB_CLOSED_NOTICE,\n    report.tabShared && TAB_SHARED_NOTICE\n  ].filter((notice) => typeof notice === \"string\");\n  return {\n    ...output,\n    ...(report.restarted ? { restarted: true as const } : {}),\n    ...(notices.length > 0 ? { notice: notices.join(\" \") } : {}),\n    ...(report.newTabs.length > 0 ? { newTabs: report.newTabs } : {})\n  };\n}\n\n/** Report sentences that must survive a screenshot's text summary. */\nexport function browserReportNotes(output: BrowserToolOutput): string[] {\n  const notes: string[] = [];\n  if (output.notice) notes.push(output.notice);\n  if (output.newTabs?.length) {\n    notes.push(\n      `New tabs opened by the page: ${JSON.stringify(output.newTabs)}`\n    );\n  }\n  return notes;\n}\n\n/**\n * Build the codemode runtime and connector for one `browserTool`, and wrap\n * `execute` so each result carries the browser report.\n *\n * Each scope gets its own connector (which knows its scope) on the same\n * codemode runtime, built on first use. Runs in one scope wait for each\n * other, since they drive one tab; runs in different scopes go in parallel.\n */\nexport function createBrowserToolCore(\n  options: BrowserToolOptions,\n  adapter: {\n    /** What the adapter does with screenshots, told to the model. */\n    screenshotHint: string;\n  }\n) {\n  const ctx = resolveCtx(options);\n  if (!ctx) {\n    throw new Error(\n      \"browserTool requires a Durable Object 'ctx' — pass it explicitly, or call from within an Agent so it can be resolved via getCurrentAgent()\"\n    );\n  }\n\n  const timeout = options.timeoutMs ?? DEFAULT_TIMEOUT_MS;\n  const executor = new DynamicWorkerExecutor({\n    loader: options.loader,\n    timeout\n  });\n\n  // Our own description, not codemode's generic one: that one tells the\n  // model to search before every new connector (search doesn't cover CDP\n  // commands), and describes approvals, snippets, and replay, which this\n  // tool doesn't use.\n  const rules = [\n    BROWSER_INSTRUCTIONS,\n    `Each run times out after ${Math.round(timeout / 1000)}s, so split long jobs (crawling a site, say) across runs.`,\n    adapter.screenshotHint\n  ]\n    .join(\"\\n\")\n    .split(\"\\n\")\n    .map((rule) => `- ${rule}`)\n    .join(\"\\n\");\n  const description = [\n    \"Run JavaScript that drives a persistent Chrome browser over the Chrome DevTools Protocol (CDP).\",\n    \"\",\n    \"Write an async arrow function, `async () => { ... }`, and return a small JSON value. Use the `cdp` global to reach the browser. `fetch` is blocked and there is no file system or Node.js API.\",\n    \"\",\n    \"## cdp\",\n    \"\",\n    \"- `cdp.send({ method, params?, sessionId?, timeoutMs? })` sends a CDP command and returns its result without the JSON-RPC envelope: `Page.navigate` returns `{ frameId, errorText? }`, `Runtime.evaluate` returns `{ result: { value }, exceptionDetails? }`.\",\n    \"- `cdp.attachToTarget({ targetId })` makes an open tab active and returns `{ sessionId }`.\",\n    '- `cdp.spec()` returns the whole protocol (about 650 KB) as `{ domains: [{ name, commands, events, types }] }`. Filter it in code, for example `spec.domains.find((d) => d.name === \"Page\").commands.find((c) => c.name === \"navigate\")`.',\n    \"- `cdp.getDebugLog()` returns recent protocol traffic, for when a command fails or times out.\",\n    \"\",\n    \"## Rules\",\n    \"\",\n    rules,\n    '- A `SyntaxError` from \"Failed to start Worker\" means your code didn\\'t parse; its line number points into wrapper code, not yours. Check regex literals and escapes.'\n  ].join(\"\\n\");\n  type CodemodeTool = ReturnType<\n    ReturnType<typeof createCodemodeRuntime>[\"tool\"]\n  >;\n  interface ScopedTool {\n    connector: BrowserSessionConnector;\n    tool: CodemodeTool;\n  }\n  const durableCtx: DurableObjectState = ctx;\n  const scopes = new Map<string, ScopedTool>();\n  function scoped(scope: string): ScopedTool {\n    const cached = scopes.get(scope);\n    if (cached) {\n      // Most recently used last, so the first entry is the one to drop.\n      scopes.delete(scope);\n      scopes.set(scope, cached);\n      return cached;\n    }\n    const connector = new BrowserSessionConnector(durableCtx, {\n      browser: options.browser,\n      scope\n    });\n    const runtime = createCodemodeRuntime({\n      ctx: durableCtx,\n      executor,\n      connectors: [connector],\n      name: browserRuntimeName(options.browser.name),\n      transformResult: transformBrowserResult\n    });\n    const built = { connector, tool: runtime.tool({ description }) };\n    scopes.set(scope, built);\n    if (scopes.size > MAX_CACHED_SCOPES) {\n      const oldest = scopes.keys().next().value;\n      if (oldest !== undefined) scopes.delete(oldest);\n    }\n    return built;\n  }\n\n  const defaultScope = options.scope ?? DEFAULT_BROWSER_SCOPE;\n  const { inputSchema } = scoped(defaultScope).tool;\n\n  return {\n    description,\n    inputSchema,\n    /** Run `input` in `scope`, which defaults to the tool's `scope`. */\n    execute: (\n      input: BrowserToolInput,\n      scope: string = defaultScope\n    ): Promise<BrowserToolOutput> =>\n      queued(options.browser, scope, async () => {\n        const { connector, tool } = scoped(scope);\n        const output = await tool.execute(input, undefined);\n        return withBrowserReport(\n          output,\n          connector.takeReport(output.executionId)\n        );\n      })\n  };\n}\n"],"mappings":"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"}

package/dist/{browser-tool-DuNdlwZ9.d.ts → browser-tool-vtrPOV8e.d.ts}

@@ -1,4 +1,7 @@
-import { n as BrowserConnection } from "./browser-DE3d-RLk.js";
+import {
+  n as BrowserConnectOptions,
+  r as BrowserConnection
+} from "./browser-D30VlpcA.js";
 import {
   CodemodeConnector,
   ConnectorTool,
@@ -14,8 +17,12 @@ import {
 interface BrowserSource {
   /** The browser's name, for log messages. */
   readonly name: string;
-  /** Reattach to the browser (or replace it) and open a CDP connection. */
-  connect(): Promise<BrowserConnection>;
+  /**
+   * Reattach to the browser (or replace it) and open a CDP connection for
+   * a scope. A source that ignores `scope` shares one active tab between
+   * every caller.
+   */
+  connect(options?: BrowserConnectOptions): Promise<BrowserConnection>;
 }
 /** A tab a page opened on its own during an execution. */
 interface BrowserNewTab {
@@ -37,8 +44,15 @@ interface BrowserToolOptions {
    * Requires `"worker_loaders": [{ "binding": "LOADER" }]` in wrangler.jsonc.
    */
   loader: WorkerLoader;
-  /** Sandbox execution timeout in milliseconds. Defaults to 30000 (30s). */
+  /** Sandbox execution timeout in milliseconds. Defaults to 60000 (60s). */
   timeoutMs?: number;
+  /**
+   * Who is driving, when several chats or users share one `Browser`: runs
+   * with the same scope share an active tab, and each scope keeps its own.
+   * Cookies and logins are shared by every scope. Defaults to `"shared"`,
+   * one active tab for every tool that leaves it out.
+   */
+  scope?: string;
   /**
    * Durable Object state for the codemode runtime facet. Optional inside an
    * Agent (resolved via `getCurrentAgent()`); pass it explicitly elsewhere.
@@ -58,7 +72,12 @@ interface BrowserToolInput {
  * plus what happened to the browser.
  */
 type BrowserToolOutput = ProxyToolOutput & {
-  /** The browser was replaced before this run; earlier tabs are gone. */ restarted?: true /** A sentence telling the model what `restarted` means for it. */;
+  /** The browser was replaced before this run; earlier tabs are gone. */ restarted?: true;
+  /**
+   * Sentences telling the model what happened to its browser: it was
+   * restarted, its tab was closed by someone else, or another scope is
+   * working in its tab too.
+   */
   notice?: string /** Tabs the page opened itself (popups, `target=_blank` links). */;
   newTabs?: BrowserNewTab[];
 };
@@ -70,4 +89,4 @@ export {
   BrowserToolOutput as r,
   BrowserToolInput as t
 };
-//# sourceMappingURL=browser-tool-DuNdlwZ9.d.ts.map
+//# sourceMappingURL=browser-tool-vtrPOV8e.d.ts.map

package/dist/{capability-B4WbF81e.js → capability-DBAKc6UZ.js}

@@ -2,8 +2,6 @@
 const installedServices = /* @__PURE__ */ new WeakMap();
 /**
 * Base class for capabilities that consume standard Lifecycle services.
-*
-* @experimental The API surface may change before stabilizing.
 */
 var LifecycleCapability = class {
 	constructor(capabilityId) {
@@ -40,4 +38,4 @@ function lifecycleCapabilityId(capability) {
 //#endregion
 export { bindLifecycleCapability as n, lifecycleCapabilityId as r, LifecycleCapability as t };
 
-//# sourceMappingURL=capability-B4WbF81e.js.map
+//# sourceMappingURL=capability-DBAKc6UZ.js.map

package/dist/capability-DBAKc6UZ.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"capability-DBAKc6UZ.js","names":[],"sources":["../src/lifecycle/capability.ts"],"sourcesContent":["import type {\n  CapabilityStartContext,\n  DurableObjectCapability\n} from \"./capability-runner\";\nimport type { Connection } from \"./types\";\nimport type { LifecycleJobs } from \"./job-queue\";\n\n/** Opaque address understood by a Lifecycle routing transport. */\nexport type LifecycleRouteAddress = {\n  /** Stable equality and storage key. */\n  readonly key: string;\n  /** Transport-owned serialized address. */\n  readonly data: string;\n};\n\n/** Context supplied with a routed capability message. */\nexport type LifecycleRouteContext = {\n  /** Address of the sending Lifecycle, or undefined for an unrouted root. */\n  readonly source: LifecycleRouteAddress | undefined;\n  /** Capability-owned message payload. */\n  readonly payload: unknown;\n};\n\n/** Startup state of a Lifecycle. */\nexport type LifecycleStatus = \"zero\" | \"starting\" | \"started\";\n\n/** Best-effort telemetry available to every Lifecycle capability. */\nexport type LifecycleEvents = {\n  /** Publish an event under this capability's stable identity. */\n  readonly emit: (type: string, payload: unknown) => void;\n};\n\n/** Routing available to every Lifecycle capability. */\nexport type LifecycleRoutes = {\n  /** This Lifecycle's transport address, or undefined at the route root. */\n  readonly source: LifecycleRouteAddress | undefined;\n  /** Route a capability-owned message to the root Lifecycle. */\n  readonly toRoot: (payload: unknown) => Promise<unknown>;\n  /** Route a capability-owned message to another Lifecycle. */\n  readonly to: (\n    target: LifecycleRouteAddress,\n    payload: unknown\n  ) => Promise<unknown>;\n};\n\n/**\n * Ambient scope a capability supplies when entering host context on\n * behalf of a live connection or request.\n */\nexport type LifecycleHostContextScope = {\n  /** The connection the callback runs on behalf of, when there is one. */\n  readonly connection?: Connection;\n  /** The request the callback runs on behalf of, when there is one. */\n  readonly request?: Request;\n};\n\n/**\n * The platform's hibernatable-socket surface, exposed narrowly so a\n * capability that owns connections (e.g. WebSockets) can accept and\n * enumerate them without holding the whole `DurableObjectState`.\n * These are workerd API names, not Lifecycle modeling sockets.\n */\nexport type LifecycleSockets = {\n  /** Accept a socket into hibernation under the given tags. */\n  readonly accept: (ws: WebSocket, tags: string[]) => void;\n  /** Every hibernated socket on the object, optionally by tag. */\n  readonly get: (tag?: string) => WebSocket[];\n};\n\n/**\n * Standard services granted to every installed Lifecycle capability.\n */\nexport type LifecycleServices = {\n  /** The host's Durable Object name; see `Lifecycle.name`. */\n  readonly name: string;\n  /** The host class name, as exported from the Worker. */\n  readonly className: string;\n  readonly storage: DurableObjectStorage;\n  readonly sockets: LifecycleSockets;\n  /**\n   * Resolve once Lifecycle startup has finished, starting it if needed, and\n   * reject if that startup fails. Calls made from inside startup resolve\n   * immediately.\n   *\n   * Await it first in any operation that can run before startup and starts\n   * work `onStart` also awaits, such as lazily opening a store. Native RPC\n   * bypasses the automatic startup on fetch, alarm and WebSocket events, so\n   * such an operation can begin that work outside startup. `onStart` then\n   * awaits it while startup holds the input gate (`blockConcurrencyWhile`),\n   * which holds back the work's timers and I/O, and startup times out after\n   * 30 seconds and resets the object.\n   */\n  readonly ready: () => Promise<void>;\n  /**\n   * Startup state: `\"zero\"` before startup, `\"starting\"` while capability\n   * and host startup hooks run, `\"started\"` once `ready()` resolves without\n   * waiting.\n   */\n  readonly status: () => LifecycleStatus;\n  /**\n   * This capability's scoped access to the Lifecycle-owned work queue.\n   * Pushed items are dispatched to `onJob` when due; every queue mutation\n   * re-arms the physical alarm automatically.\n   */\n  readonly jobs: LifecycleJobs;\n  /**\n   * Keep work this capability hands off at a bounded `onJob` return inside\n   * the current alarm's memory-limit breaker domain (#1825). Returns false,\n   * tracking nothing, outside an alarm invocation.\n   */\n  readonly trackAlarmWork: (work: Promise<unknown>) => boolean;\n  /**\n   * Run a capability-held user callback inside the host invocation context.\n   * Capability hooks run outside host context; this is the one boundary for\n   * entering it, and a host composition root may substitute its own wrapper\n   * (Agent adds tracing span scope). Pass `scope` to make a live\n   * connection or request ambient for the callback.\n   */\n  readonly runInHostContext: (\n    fn: () => unknown,\n    scope?: LifecycleHostContextScope\n  ) => Promise<unknown>;\n  readonly events: LifecycleEvents;\n  readonly routes: LifecycleRoutes;\n};\n\nconst installedServices = new WeakMap<object, LifecycleServices>();\n\n/**\n * Base class for capabilities that consume standard Lifecycle services.\n */\nexport abstract class LifecycleCapability<Props extends object = object> {\n  readonly capabilityId: string;\n\n  /** How this capability claims traffic; see {@link DurableObjectCapability.claims}. */\n  readonly claims: \"selective\" | \"catch-all\" = \"selective\";\n\n  protected constructor(capabilityId: string) {\n    if (capabilityId.trim() === \"\") {\n      throw new Error(\"Lifecycle capability IDs must be non-empty\");\n    }\n    this.capabilityId = capabilityId;\n  }\n\n  /** Default startup hook; capabilities override when they own startup work. */\n  onStart(_context: CapabilityStartContext<Props>): void {}\n\n  /** Standard services when installed, or undefined in isolated unit tests. */\n  protected get lifecycleServices(): LifecycleServices | undefined {\n    return installedServices.get(this);\n  }\n\n  /** Standard services supplied when Lifecycle installs this capability. */\n  protected get lifecycle(): LifecycleServices {\n    const services = this.lifecycleServices;\n    if (!services) {\n      throw new Error(\n        `${this.constructor.name} must be installed with Lifecycle.use() before use`\n      );\n    }\n    return services;\n  }\n}\n\n/**\n * @internal Bind the standard service surface to one capability instance.\n * `Lifecycle.use()` calls this during installation. Test a capability by\n * installing it on a minimal Durable Object with a real Lifecycle rather\n * than binding fake services.\n */\nexport function bindLifecycleCapability(\n  capability: LifecycleCapability,\n  services: LifecycleServices\n): void {\n  installedServices.set(capability, services);\n}\n\n/** @internal Read a capability ID without exposing installation internals. */\nexport function lifecycleCapabilityId(\n  capability: DurableObjectCapability\n): string | undefined {\n  return capability instanceof LifecycleCapability\n    ? capability.capabilityId\n    : undefined;\n}\n"],"mappings":";AA8HA,MAAM,oCAAoB,IAAI,QAAmC;;;;AAKjE,IAAsB,sBAAtB,MAAyE;CAMvE,YAAsB,cAAsB;EAF5C,KAAS,SAAoC;EAG3C,IAAI,aAAa,KAAK,MAAM,IAC1B,MAAM,IAAI,MAAM,4CAA4C;EAE9D,KAAK,eAAe;CACtB;;CAGA,QAAQ,UAA+C,CAAC;;CAGxD,IAAc,oBAAmD;EAC/D,OAAO,kBAAkB,IAAI,IAAI;CACnC;;CAGA,IAAc,YAA+B;EAC3C,MAAM,WAAW,KAAK;EACtB,IAAI,CAAC,UACH,MAAM,IAAI,MACR,GAAG,KAAK,YAAY,KAAK,mDAC3B;EAEF,OAAO;CACT;AACF;;;;;;;AAQA,SAAgB,wBACd,YACA,UACM;CACN,kBAAkB,IAAI,YAAY,QAAQ;AAC5C;;AAGA,SAAgB,sBACd,YACoB;CACpB,OAAO,sBAAsB,sBACzB,WAAW,eACX,KAAA;AACN"}

package/dist/{capability-runner-DBAnGr6L.d.ts → capability-runner-BiVUtjqC.d.ts}

@@ -219,8 +219,6 @@ type LifecycleSockets = {
 };
 /**
  * Standard services granted to every installed Lifecycle capability.
- *
- * @experimental The API surface may change before stabilizing.
  */
 type LifecycleServices = {
   /** The host's Durable Object name; see `Lifecycle.name`. */ readonly name: string /** The host class name, as exported from the Worker. */;
@@ -231,6 +229,14 @@ type LifecycleServices = {
    * Resolve once Lifecycle startup has finished, starting it if needed, and
    * reject if that startup fails. Calls made from inside startup resolve
    * immediately.
+   *
+   * Await it first in any operation that can run before startup and starts
+   * work `onStart` also awaits, such as lazily opening a store. Native RPC
+   * bypasses the automatic startup on fetch, alarm and WebSocket events, so
+   * such an operation can begin that work outside startup. `onStart` then
+   * awaits it while startup holds the input gate (`blockConcurrencyWhile`),
+   * which holds back the work's timers and I/O, and startup times out after
+   * 30 seconds and resets the object.
    */
   readonly ready: () => Promise<void>;
   /**
@@ -267,8 +273,6 @@ type LifecycleServices = {
 };
 /**
  * Base class for capabilities that consume standard Lifecycle services.
- *
- * @experimental The API surface may change before stabilizing.
  */
 declare abstract class LifecycleCapability<Props extends object = object> {
   readonly capabilityId: string;
@@ -361,8 +365,6 @@ type MemoryLimitContext = {
  * - `onRoute` is addressed to one capability by its id; `onJob` is
  *   addressed by the due job's owning capability, with Lifecycle owning
  *   the queue and the one physical alarm.
- *
- * @experimental The API surface may change before stabilizing.
  */
 interface DurableObjectCapability<Props extends object = object> {
   /**
@@ -486,4 +488,4 @@ export {
   Connection as x,
   LifecycleJobPushOptions as y
 };
-//# sourceMappingURL=capability-runner-DBAnGr6L.d.ts.map
+//# sourceMappingURL=capability-runner-BiVUtjqC.d.ts.map

package/dist/channel-Bak_6zDP.d.ts

@@ -0,0 +1,333 @@
+import {
+  b as ChannelMessageSurface,
+  m as ResponseChunk,
+  p as Participant,
+  x as ChannelMessageSurfaceInput
+} from "./protocol-CukuI73M.js";
+
+//#region src/experimental/channels/identity.d.ts
+type ChannelIdentity = Readonly<{
+  /** Configured Channel that observed this identity. */ channelKey: string /** Stable Channel namespace in which `subject` is unique. @default "default" */;
+  scope?: string /** Stable Channel subject within `scope`. */;
+  subject: string;
+}>;
+/** A Channel-produced identity before its Host stamps the configured key. */
+type ChannelIdentityInput = Readonly<{
+  scope?: string;
+  subject: string;
+}>;
+/** Build a stable key for comparing or indexing a Channel identity. */
+declare function identityKey(identity: ChannelIdentity): string;
+//#endregion
+//#region src/experimental/channels/ingress.d.ts
+/** Serializable provider attachment facts available after ingress returns. */
+type ChannelAttachment = {
+  id?: string;
+  mediaType?: string;
+  name?: string;
+  size?: number;
+  text?: string;
+  url?: string;
+};
+type ChannelActor = {
+  readonly id: string /** Stable Channel identity suitable for explicit application linking. */;
+  readonly identity?: ChannelIdentity;
+  readonly username?: string;
+  readonly fullName?: string;
+  readonly isBot?: boolean | "unknown";
+  readonly isSelf?: boolean;
+};
+/** An actor before the Host stamps its configured Channel key. */
+type ChannelActorInput = Omit<ChannelActor, "identity"> & {
+  readonly identity?: ChannelIdentityInput;
+};
+type ChannelEventContext = {
+  /** Immutable Channel-scoped identity, independent of application routing. */ readonly eventId: string;
+  readonly thread: {
+    readonly id: string;
+    readonly isDirectMessage: boolean | "unknown";
+  } /** Exact provider destination for responding to this inbound event. */;
+  readonly replySurface?: ChannelMessageSurface;
+  readonly actor?: ChannelActor;
+};
+/** A normalized inbound message from a Channel. */
+type ChannelInboundMessage = ChannelEventContext & {
+  readonly type: "message";
+  readonly message: {
+    readonly id: string;
+    readonly text: string;
+    readonly title?: string;
+    readonly markdown?: string;
+    readonly attachments?: readonly ChannelAttachment[];
+    readonly isMention?: boolean;
+    readonly reply?: {
+      readonly id: string;
+      readonly text?: string;
+    };
+    readonly metadata?: {
+      /** ISO 8601 timestamp supplied by the provider. */ readonly sentAt?: string;
+      readonly edited?: boolean /** ISO 8601 timestamp supplied by the provider. */;
+      readonly editedAt?: string;
+      readonly autoReply?: boolean;
+    };
+  };
+};
+/** A provider-normalized response to an external approval request. */
+type ChannelApprovalResponse = ChannelEventContext & {
+  readonly type: "approval-response";
+  readonly approvalId: string;
+  readonly decision:
+    | "approve"
+    | "reject" /** Provider reference for this inbound response. */;
+  readonly reference: string;
+};
+type ChannelIngressEvent = ChannelInboundMessage | ChannelApprovalResponse;
+/** A normalized message before the Host stamps its configured Channel key. */
+type ChannelEventContextInput = Omit<
+  ChannelEventContext,
+  "replySurface" | "actor"
+> & {
+  readonly replySurface?: ChannelMessageSurfaceInput;
+  readonly actor?: ChannelActorInput;
+};
+type ChannelInboundMessageInput = Omit<
+  ChannelInboundMessage,
+  "replySurface" | "actor"
+> & {
+  readonly replySurface?: ChannelMessageSurfaceInput;
+  readonly actor?: ChannelActorInput;
+};
+/** A normalized approval before the Host stamps its configured Channel key. */
+type ChannelApprovalResponseInput = Omit<
+  ChannelApprovalResponse,
+  "replySurface" | "actor"
+> & {
+  readonly replySurface?: ChannelMessageSurfaceInput;
+  readonly actor?: ChannelActorInput;
+};
+/** Authenticated event produced by a Channel before Host dispatch. */
+type ChannelIngressEventInput =
+  | ChannelInboundMessageInput
+  | ChannelApprovalResponseInput;
+/** Authenticated Channel output retained only until Host routing completes. */
+type ChannelIngressEnvelope<TRaw = unknown> = {
+  event: ChannelIngressEventInput;
+  raw: TRaw;
+};
+/** The normalized envelopes and provider acknowledgement produced by ingress. */
+type ChannelIngressResult<TRaw = unknown> = {
+  events: readonly ChannelIngressEnvelope<TRaw>[];
+  response: Response;
+};
+/** Match an HTTP request to one exact URL pathname. */
+declare function matchesPath(request: Request, path: string): boolean;
+/** Webhook-shaped inbound support owned by a Channel. */
+interface ChannelIngress<TRaw = unknown> {
+  /** Return null when this Channel does not own the request. */
+  receive(request: Request): Promise<ChannelIngressResult<TRaw> | null>;
+}
+/** Structural input supported by Workers Email and Agent email handlers. */
+type ChannelEmailInput = {
+  from: string;
+  to: string;
+  headers: Headers;
+  raw?: ReadableStream<Uint8Array>;
+  getRaw?: () => Promise<Uint8Array>;
+};
+type ChannelEmailIngressResult<TRaw = unknown> = {
+  events: readonly ChannelIngressEnvelope<TRaw>[];
+};
+/** Non-HTTP ingress for a Workers Email event. */
+interface ChannelEmailIngress<TRaw = unknown> {
+  /** Return null when this Channel does not own the email. */
+  receive(
+    email: ChannelEmailInput
+  ): Promise<ChannelEmailIngressResult<TRaw> | null>;
+}
+//#endregion
+//#region src/experimental/channels/channel.d.ts
+type Awaitable<T> = T | Promise<T>;
+/** A transport-neutral outbound message whose canonical content is Markdown. */
+type ChannelMessage = {
+  /** Optional topic. Each transport decides how to represent it. */ title?: string /** Canonical Markdown content. */;
+  markdown: string;
+};
+/** A transport failure safe to expose to an AI model. */
+type DeliveryFailure = {
+  code: string;
+  message: string;
+};
+/**
+ * The result of a direct delivery attempt, defined by what reached the reader.
+ *
+ * `delivered` means the whole message reached the reader, not that a person
+ * read it. `failed` means none of it did; its `retryable` field says whether
+ * the same route can be attempted again. `uncertain` means an unknown amount
+ * of the message reached the reader, so another attempt or route could
+ * duplicate content. A stream that ends before its answer is complete is
+ * `uncertain`, and carries a `reference` when the Channel created something
+ * the caller can point at.
+ */
+type DeliveryResult =
+  | {
+      status: "delivered";
+      reference?: string;
+    }
+  | {
+      status: "failed";
+      retryable: boolean;
+      error: DeliveryFailure;
+    }
+  | {
+      status: "uncertain";
+      reference?: string;
+      error: DeliveryFailure;
+    };
+/** A response's chunks, as `ChannelGateway.stream` takes them. */
+type ChannelChunkSource = ReadableStream<ResponseChunk>;
+/** Caller options for one finished delivery. */
+type ChannelDeliveryOptions = {
+  /** Caller-owned correlation an Adapter may use where the provider supports it. */ delivery?: ChannelDeliveryContext;
+};
+/** Caller options for one streamed answer. */
+type ChannelStreamOptions = {
+  /**
+   * Optional topic. It is an option rather than a chunk because it is known
+   * before the first token, and a Channel usually needs it in its opening
+   * provider call.
+   */
+  title?: string /** Caller-owned correlation an Adapter may use where the provider supports it. */;
+  delivery?: ChannelDeliveryContext;
+};
+/**
+ * Caller-owned correlation supplied to one provider delivery attempt.
+ *
+ * This is not an idempotency guarantee. An Adapter may map it to a provider
+ * idempotency primitive when one exists, or otherwise use it for observability.
+ */
+type ChannelDeliveryContext = {
+  deliveryId: string;
+};
+/**
+ * Who a sender is, as the application decides it. A string is shorthand
+ * for `{ id }`; `null` refuses the sender. Participants that share an id
+ * are the same participant.
+ */
+type ParticipantResult = Participant | string | null;
+/**
+ * Resolve who sent an authenticated event. Channels has no opinion on
+ * identity: this is the only place a webhook sender becomes a participant.
+ */
+type ChannelParticipant<TRaw = unknown> = (
+  event: ChannelIngressEvent,
+  raw: TRaw
+) => Awaitable<ParticipantResult>;
+/**
+ * Pick the agent object an event reaches, or return null to ignore it.
+ *
+ * The agent object is the authorization boundary: anyone who reaches one
+ * may use every conversation in it. Default: an agent object of the
+ * participant's own (`routes.perParticipant`).
+ */
+type ChannelRoute<TRaw = unknown> = (
+  event: ChannelIngressEvent,
+  raw: TRaw,
+  participant: Participant
+) => Awaitable<string | null>;
+/** A WebSocket upgrade's conversation, once it is known to be for Channels. */
+type ChannelUpgradeMatch = {
+  /** The conversation to follow. Default: the agent's default conversation. */ conversationId?: string;
+};
+/** How a Channel takes WebSocket upgrades in the gateway. */
+interface ChannelUpgrade {
+  /** Return undefined for an upgrade that is not for this Channel. */
+  match(request: Request): ChannelUpgradeMatch | undefined;
+  /** Who is connecting. Return null to refuse the upgrade. */
+  participant(request: Request): Awaitable<ParticipantResult>;
+  /** The agent object the upgrade reaches, or null to refuse it. */
+  route(request: Request, participant: Participant): Awaitable<string | null>;
+}
+/** A configured delivery route with optional ingress support. */
+interface Channel<TRaw = unknown> {
+  /**
+   * Who sent an ingress event. Required when the Channel has `ingress` or
+   * `emailIngress`; the gateway refuses to start without it.
+   */
+  participant?(
+    event: ChannelIngressEvent,
+    raw: TRaw
+  ): Awaitable<ParticipantResult>;
+  /** Pick the agent object an event reaches. See `ChannelRoute`. */
+  route?(
+    event: ChannelIngressEvent,
+    raw: TRaw,
+    participant: Participant
+  ): Awaitable<string | null>;
+  /** Derive a direct destination from this configured Channel's identity. */
+  contactSurface?(identity: ChannelIdentity): ChannelMessageSurfaceInput | null;
+  /**
+   * Deliver one finished message. Only for Channels that cannot stream:
+   * the gateway delivers to a Channel that can by streaming the message.
+   */
+  deliver?(
+    surface: ChannelMessageSurface,
+    message: ChannelMessage,
+    options?: ChannelDeliveryOptions
+  ): Promise<DeliveryResult>;
+  /**
+   * Deliver one progressively generated answer. Absent for Channels that
+   * cannot stream, which the Host serves by collecting and calling `deliver`.
+   *
+   * The Channel owns the consumption loop. It must finalize whether the
+   * stream closed or errored, because a model can fail mid-generation, and it
+   * must not abandon a terminal provider call on error.
+   */
+  stream?(
+    surface: ChannelMessageSurface,
+    chunks: ChannelChunkSource,
+    options: ChannelStreamOptions
+  ): Promise<DeliveryResult>;
+  readonly ingress?: ChannelIngress<TRaw>;
+  readonly emailIngress?: ChannelEmailIngress<TRaw>;
+  /** WebSocket upgrades this Channel takes, such as the Web Channel's. */
+  readonly upgrade?: ChannelUpgrade;
+}
+//#endregion
+export {
+  ChannelIngressEventInput as A,
+  ChannelEventContext as C,
+  ChannelIngress as D,
+  ChannelInboundMessageInput as E,
+  identityKey as F,
+  matchesPath as M,
+  ChannelIdentity as N,
+  ChannelIngressEnvelope as O,
+  ChannelIdentityInput as P,
+  ChannelEmailInput as S,
+  ChannelInboundMessage as T,
+  ChannelApprovalResponse as _,
+  ChannelDeliveryOptions as a,
+  ChannelEmailIngress as b,
+  ChannelRoute as c,
+  ChannelUpgradeMatch as d,
+  DeliveryFailure as f,
+  ChannelActorInput as g,
+  ChannelActor as h,
+  ChannelDeliveryContext as i,
+  ChannelIngressResult as j,
+  ChannelIngressEvent as k,
+  ChannelStreamOptions as l,
+  ParticipantResult as m,
+  Channel as n,
+  ChannelMessage as o,
+  DeliveryResult as p,
+  ChannelChunkSource as r,
+  ChannelParticipant as s,
+  Awaitable as t,
+  ChannelUpgrade as u,
+  ChannelApprovalResponseInput as v,
+  ChannelEventContextInput as w,
+  ChannelEmailIngressResult as x,
+  ChannelAttachment as y
+};
+//# sourceMappingURL=channel-Bak_6zDP.d.ts.map

package/dist/chat/index.d.ts

@@ -9,21 +9,23 @@ import {
   _ as FiberRecoveryContext$1,
   at as isPositionlessAgentToolChunk,
   z as AgentToolEventState
-} from "../agent-routing-0DR0Tk2v.js";
-import { _ as TaskStep, m as TaskRunOptions } from "../tasks-9YxYtByh.js";
+} from "../agent-routing-QDcchcQP.js";
+import { _ as TaskStep, m as TaskRunOptions } from "../tasks-E89KdwkS.js";
+import {
+  n as ClientToolSchema,
+  r as createToolsFromClientSchemas,
+  t as ClientToolExecutor
+} from "../client-tools-aIBO0Fk7.js";
+import { n as Streams } from "../streams-vrCtbUIn.js";
 import {
   a as CHAT_MESSAGE_TYPES,
-  c as ClientToolExecutor,
   i as OutgoingMessage,
-  l as ClientToolSchema,
   n as IncomingMessage,
   o as STREAM_RESUME_NONE_REASONS,
   r as MessageType,
   s as StreamResumeNoneReason,
-  t as ChatTurnOutcome,
-  u as createToolsFromClientSchemas
-} from "../wire-types-CrjKvDyi.js";
-import { n as Streams } from "../streams-Cmkj9QfW.js";
+  t as ChatTurnOutcome
+} from "../wire-types-Cv0iwjk5.js";
 import {
   a as applyAgentToolEvent,
   i as AgentToolProgressEmitter,
@@ -32,7 +34,7 @@ import {
   r as AgentToolProgressEmitResult,
   s as interceptAgentToolBroadcast,
   t as AgentToolBroadcastHooks
-} from "../agent-tools-YrATZJu2.js";
+} from "../agent-tools-DHL2XI7u.js";
 import { l as SessionMessage } from "../types-B7LojTe4.js";
 import { ModelMessage, UIMessage } from "ai";
 import { Connection, FiberRecoveryContext } from "agents";