agents/dist/browser/tools/pi.d.ts

A home for your AI agents

import {
  T as BrowserSource,
  b as BrowserNewTab
} from "../../browser-CI97khiJ.js";
import {
  n as BrowserToolOptions,
  r as BrowserToolOutput,
  t as BrowserToolInput
} from "../../browser-tool-Cxtiwfua.js";
import { ToolExecutionApi, ToolRegistration } from "@earendil-works/pi-durable";

//#region src/browser/tools/pi.d.ts
interface PiBrowserToolOptions<TName extends string = "browser"> extends Omit<
  BrowserToolOptions,
  "scope"
> {
  /** The tool's name. Default `"browser"`. */
  name?: TName;
  /**
   * Which calls share an active tab: a string for every call, or a function
   * of the call. Defaults to `conversation:<id>` for the calling
   * conversation (`conversationScope` from `agents/browser`), so each
   * conversation (and each fork or subagent) on the Durable Object keeps its
   * own tab, while cookies and logins stay shared.
   */
  scope?: string | ((api: ToolExecutionApi) => string);
}
declare const browserToolParameters: import("@earendil-works/pi-schema").Schema<{
  code: string;
}>;
/**
 * What a UI can show about a run without reading the content: its id and
 * outcome.
 */
type PiBrowserToolDetails = {
  executionId: string;
  status: BrowserToolOutput["status"];
};
type PiBrowserTool<TName extends string = "browser"> = ToolRegistration<
  typeof browserToolParameters,
  PiBrowserToolDetails
> & {
  readonly name: TName;
};
/**
 * Create a pi-durable tool that lets the model drive a persistent browser
 * with JavaScript and the Chrome DevTools Protocol.
 *
 * Works like `browserTool` in `agents/browser/ai-sdk`: tabs, cookies, and
 * logins carry over between runs, `sessionId: "active"` addresses the tab the
 * model last worked in, and a replaced browser is reported in the
 * result's `notice`. A returned screenshot comes back as an image part that
 * the model sees, when its model accepts images.
 *
 * Scripts in pi's code mode call it as `tools.browser({ code })`, which
 * resolves to the run as an object (`status`, `result`, `error`, `notice`),
 * on errors too. A screenshot's `result` is an image block, for `image()`.
 *
 * Each conversation gets its own active tab (see
 * {@link PiBrowserToolOptions.scope}). A conversation's calls run one at a
 * time, since they share its tab, and the tool doesn't rerun after an
 * eviction (its code may have clicked or
 * submitted something): pi gives the model an interrupted result instead.
 *
 * @example
 * ```ts
 * import { Browser, browserRun } from "agents/browser";
 * import { browserTool } from "agents/browser/pi";
 *
 * export class MyAgent extends DurableObject<Env> {
 *   readonly browser = new Browser({ provider: browserRun(this.env.BROWSER) });
 *   readonly registry = createRegistry();
 *   readonly harness = new PiHarness({
 *     harness: ({ storage, context, onWake }) => {
 *       this.registry.install({
 *         name: "browser",
 *         tools: [
 *           browserTool({
 *             browser: this.browser,
 *             loader: this.env.LOADER
 *           })
 *         ]
 *       });
 *       return Harness.open(
 *         storage,
 *         { models, registry: this.registry, onWake },
 *         context
 *       );
 *     }
 *   });
 *   readonly lifecycle = Lifecycle.install(this)
 *     .use(this.browser)
 *     .use(this.harness);
 * }
 * ```
 */
declare function browserTool<TName extends string = "browser">(
  options: PiBrowserToolOptions<TName>
): PiBrowserTool<TName>;
//#endregion
export {
  type BrowserNewTab,
  type BrowserSource,
  type BrowserToolInput,
  type BrowserToolOptions,
  type BrowserToolOutput,
  PiBrowserTool,
  PiBrowserToolDetails,
  PiBrowserToolOptions,
  browserTool
};
//# sourceMappingURL=pi.d.ts.map