@verevoir/review 0.3.0 → 0.3.2

package/node_modules/@anthropic-ai/sdk/src/lib/internal/toolsets/core.ts

@@ -0,0 +1,428 @@
+/**
+ * Shared building blocks for each toolset family's class.
+ */
+import { APIUserAbortError } from '../../../core/error';
+import type { Promisable } from '../../tools/BetaRunnableTool';
+import type { ToolsetFamily } from './family';
+import { throwIfPropagates } from './run';
+import { ToolError } from '../../tools/ToolError';
+import {
+  ConfirmDeclinedError,
+  ConfirmFailedError,
+  DisabledMemberError,
+  ToolsetConfigError,
+  UnavailableMemberError,
+  UnknownMemberError,
+} from './errors';
+import type { BetaToolConfigs, BetaToolsetCallContext } from './hooks';
+import { FIELD_MAX, cutPoints, errorTextContent } from './sanitize';
+import type { BetaBase64ImageSource, BetaTextBlockParam } from '../../../resources/beta';
+
+// --- results ---------------------------------------------------------------------------------------------
+
+/** A screenshot or zoom image from either toolset, rendered as one image block. */
+export interface BetaScreenshotResult {
+  /** Base64 image bytes, without a `data:` prefix. */
+  data: string;
+  /** Defaults to `'image/png'`. */
+  mediaType?: BetaBase64ImageSource['media_type'] | undefined;
+}
+
+// --- the member registry ---------------------------------------------------------------------------------
+
+/**
+ * The kinds of value a member hands back, each rendered by `render.ts`. `point` is a cursor position. `none` is a
+ * pure action, rendered from its confirmation template and then the line it returned, if any.
+ */
+export type ResultKind = 'navigate' | 'screenshot' | 'text' | 'tab' | 'tabs' | 'point' | 'none';
+
+/**
+ * One member of a toolset: what the generated types do not carry about it, kept by hand in the family's registry.
+ * `Kind` is the result kinds the family's rows use.
+ */
+export interface ToolsetMember<Name extends string = string, Kind extends ResultKind = ResultKind> {
+  readonly name: Name;
+  readonly result: Kind;
+  /**
+   * The confirmation the model reads after a pure action, with the placeholders `render.ts` knows (`{text}`,
+   * `{duration}`, …; `{ref}` reads `target.ref`) filled from the input. A line the action returned follows it.
+   */
+  readonly text?: string;
+  readonly enabledByDefault: boolean;
+}
+
+/**
+ * A registry row as a family writes it: result kind, confirmation template, default-enabled flag. A family writes its
+ * rows `as const`, so each member's result kind is a literal the result types below can read.
+ */
+export type MemberRow = readonly [ResultKind, string | null, boolean];
+
+/** The declared result type (`Results[K]`) of every member whose row in `Rows` gives result kind `R`. */
+export type KindResultOf<
+  Name extends string,
+  Rows extends { readonly [K in Name]: MemberRow },
+  Results extends { readonly [K in Name]: unknown },
+  R extends ResultKind,
+> = { [K in Name]: Rows[K][0] extends R ? Results[K] : never }[Name];
+
+/**
+ * A member's result with its result kind, which says how to read it: for each kind `R` the family uses, `value` is
+ * what that family's members of that kind declare. A family exports its own instantiation and a `typedResult` that
+ * builds one, the one place the driver's declared result type is taken at its word.
+ */
+export type TypedResultOf<
+  Name extends string,
+  Rows extends { readonly [K in Name]: MemberRow },
+  Results extends { readonly [K in Name]: unknown },
+  R extends ResultKind = Rows[Name][0],
+> = { [P in R]: { readonly kind: P; readonly value: KindResultOf<Name, Rows, Results, P> } }[R];
+
+/** The member table from a family's rows, in the order of `names`. */
+export function buildMembers<Name extends string, Rows extends { readonly [K in Name]: MemberRow }>(
+  names: readonly Name[],
+  rows: Rows,
+): ReadonlyMap<Name, ToolsetMember<Name, Rows[Name][0]>> {
+  return new Map(
+    names.map((name) => {
+      const [result, text, enabledByDefault] = rows[name];
+      return [name, { name, result, ...(text !== null ? { text } : {}), enabledByDefault }];
+    }),
+  );
+}
+
+/** A family's member registry, as the parts of a toolset class shared by every family read it. */
+export interface Registry<Name extends string, M extends ToolsetMember<Name> = ToolsetMember<Name>> {
+  /** The family stamped on member blocks, matched against `tool_use.toolset_name`. */
+  readonly family: ToolsetFamily;
+  /** Every member name, in canonical order. */
+  readonly names: readonly Name[];
+  readonly members: ReadonlyMap<Name, M>;
+  /** Members the API withholds unless `configs` enables them. */
+  readonly defaultDisabled: ReadonlySet<string>;
+}
+
+/** The registry row for a model-supplied name, or undefined when it names no member. */
+export function memberOf<Name extends string, M extends ToolsetMember<Name>>(
+  registry: Registry<Name, M>,
+  name: string,
+): M | undefined {
+  return registry.members.get(name as Name);
+}
+
+/** A wire entry's `configs` (any generated `*ToolsetConfigs`), read as `{ [member]: { enabled? } }`. */
+export type MemberConfigs = object | undefined;
+
+/**
+ * Whether `configs` leave `name` enabled, failing closed when the answer is unclear.
+ *
+ * Only a real boolean `enabled` turns a member on or off. Any other value fails closed, so a malformed
+ * entry (a `"false"` string that came through JSON or an environment variable) can never turn on a
+ * member that is off by default.
+ */
+export function isEnabled(
+  name: string,
+  configs: MemberConfigs,
+  defaultDisabled: ReadonlySet<string>,
+): boolean {
+  // Own properties only: `in` would walk the prototype chain, so a member named `constructor` would find an entry.
+  const entry =
+    configs != null && Object.prototype.hasOwnProperty.call(configs, name) ?
+      (configs as Record<string, { enabled?: boolean | null } | null | undefined>)[name]
+    : undefined;
+
+  // an entry that is neither an object nor null (`{ navigate: false }`) reads as off, not as the member's default
+  if (entry != null && typeof entry !== 'object') return false;
+
+  const enabled = entry?.enabled;
+  if (enabled === true) return true;
+  if (enabled !== undefined && enabled !== null) return false;
+  return !defaultDisabled.has(name);
+}
+
+// --- constructor options -----------------------------------------------------------------------------------
+
+/** The constructor options every family takes; a family's own options type adds to them. */
+export interface ToolsetOptions<Configs extends object, Confirm> {
+  configs?: Configs | undefined;
+  confirm?: Confirm | undefined;
+  toolConfigs?: BetaToolConfigs | undefined;
+}
+
+/** What the dispatch gate reads: the wire configs, and which members the class serves and the caller configured. */
+export interface ServedMembers {
+  /** What `toJSON` sends: the caller's `configs` plus `enabled: false` for every member the subclass does not serve. */
+  readonly wireConfigs: MemberConfigs;
+  /** The members a sampled call may reach: the implemented ones, or all of them for an execute-only subclass. */
+  readonly served: ReadonlySet<string>;
+  /** Members the caller's own `configs` mention. */
+  readonly configured: ReadonlySet<string>;
+}
+
+/** The shared constructor options, validated and resolved once at construction. */
+export interface ResolvedToolsetOptions<Configs extends object, Confirm> extends ServedMembers {
+  readonly wireConfigs: Configs | undefined;
+  readonly confirm: Confirm | undefined;
+  /** Spread onto the `tools[]` entry `toJSON` returns: your `toolConfigs`, copied and frozen at construction. */
+  readonly toolConfigs: BetaToolConfigs | undefined;
+}
+
+function deepFreeze<T>(value: T): T {
+  if (value !== null && typeof value === 'object' && !Object.isFrozen(value)) {
+    for (const v of Object.values(value)) deepFreeze(v);
+    Object.freeze(value);
+  }
+  return value;
+}
+
+/** The prototype property a member's method is defined under (`type` is `type_`). */
+function methodKey(name: string): string {
+  return name === 'type' ? 'type_' : name;
+}
+
+/** Whether `instance`'s class chain overrides `key` before reaching `base`, by own-property lookup. Nothing is called. */
+export function overrides(instance: object, base: object, key: string): boolean {
+  let proto: object | null = Object.getPrototypeOf(instance);
+  while (proto !== null && proto !== base) {
+    if (Object.prototype.hasOwnProperty.call(proto, key)) return true;
+    proto = Object.getPrototypeOf(proto);
+  }
+  return false;
+}
+
+function wireConfigs<Configs extends object>(
+  names: readonly string[],
+  configs: Configs | undefined,
+  served: ReadonlySet<string>,
+): Configs | undefined {
+  // The copy is what is both checked and sent, so whatever `configs` holds that JSON drops (an entry on a
+  // prototype, a non-enumerable one) can neither pass the check nor reach the wire: the member stays at its default.
+  const wire: Record<string, Record<string, unknown>> = JSON.parse(JSON.stringify(configs ?? {}));
+
+  const unserved = names.filter((name) => !served.has(name) && wire[name]?.['enabled'] === true);
+  if (unserved.length) {
+    // Offering the model a member that can only ever answer "not available" is a configuration mistake:
+    // implement the method (a subclass that overrides execute alone serves every member).
+    throw new ToolsetConfigError(
+      `configs enables member(s) this toolset does not implement: ${JSON.stringify(unserved.sort())} ` +
+        '(override the member method; a subclass that overrides only execute() serves every member)',
+    );
+  }
+
+  for (const name of names) {
+    if (served.has(name)) continue;
+    wire[name] = { ...wire[name], enabled: false };
+  }
+
+  // Frozen: this object is what the dispatch gate reads and what toJSON() copies, and the runner snapshots the wire
+  // entry when it is created. A later mutation would let the gate accept a member the API was told is off.
+  return Object.keys(wire).length ? (deepFreeze(wire) as Configs) : undefined;
+}
+
+/**
+ * Check and resolve the options every family shares, once, at construction. A family checks its own options in its
+ * own class.
+ */
+export function resolveToolsetOptions<
+  Configs extends object,
+  Confirm extends (ctx: never) => Promisable<boolean>,
+>(
+  registry: Registry<string>,
+  instance: object,
+  base: object,
+  options: ToolsetOptions<Configs, Confirm>,
+): ResolvedToolsetOptions<Configs, Confirm> {
+  // a class that overrides execute serves every member, whether or not it also implements member methods
+  const served = new Set<string>(
+    overrides(instance, base, 'execute') ?
+      registry.names
+    : registry.names.filter((name) => overrides(instance, base, methodKey(name))),
+  );
+  const wire = wireConfigs(registry.names, options.configs, served);
+  const confirm = options.confirm;
+  // Copied once and frozen, like the wire configs: a later change to the object you passed never reaches a request.
+  const toolConfigs: BetaToolConfigs | undefined =
+    options.toolConfigs === undefined ?
+      undefined
+    : deepFreeze(JSON.parse(JSON.stringify(options.toolConfigs)));
+  if (toolConfigs != null && 'configs' in toolConfigs) {
+    // refused rather than left to silently replace, or be replaced by, what the `configs` option writes there
+    throw new ToolsetConfigError(
+      'toolConfigs sets "configs", which the toolset writes itself: pass member settings as the configs option',
+    );
+  }
+  return {
+    wireConfigs: wire,
+    served,
+    configured: new Set(Object.keys(options.configs ?? {})),
+    confirm,
+    toolConfigs,
+  };
+}
+
+// --- a call's stages ---------------------------------------------------------------------------------------
+
+/** One member call in flight: what each stage produced, for the stages after it. `Result` is the family's typed result. */
+export class MemberCall<M extends ToolsetMember = ToolsetMember, Input = unknown, Result = unknown> {
+  member: M | undefined = undefined;
+  input: Input | undefined = undefined;
+  result: Result | undefined = undefined;
+  error: ToolError | undefined = undefined;
+
+  constructor(
+    readonly ctx: BetaToolsetCallContext,
+    readonly name: string,
+    readonly rawInput: unknown,
+  ) {}
+
+  get toolUseId(): string | undefined {
+    return this.ctx.toolUse?.id;
+  }
+}
+
+/**
+ * Stage one of a call: the registry row for `name`, or the refusal the model reads (an unknown name, a
+ * member this application disabled, or one the driver does not implement).
+ */
+export function resolveMember<Name extends string, M extends ToolsetMember<Name>>(
+  registry: Registry<Name, M>,
+  options: ServedMembers,
+  name: string,
+): M {
+  const member = memberOf(registry, name);
+  if (member === undefined) throw new UnknownMemberError(name, registry.family);
+  if (!isEnabled(member.name, options.wireConfigs, registry.defaultDisabled)) {
+    if (!options.served.has(member.name) && !options.configured.has(member.name)) {
+      throw new UnavailableMemberError(member.name, registry.family);
+    }
+    throw new DisabledMemberError(member.name);
+  }
+  return member;
+}
+
+/**
+ * `execute`'s default body: the member's method on `instance`, resolved through the registry rather than by property
+ * name, since `instance[name]` on raw model output would reach `constructor`, `toString` or any other property.
+ */
+export async function dispatchMember<Name extends string>(
+  registry: Registry<Name>,
+  instance: object,
+  ctx: BetaToolsetCallContext,
+  name: Name,
+  input: unknown,
+): Promise<unknown> {
+  if (registry.members.get(name) === undefined) throw new UnknownMemberError(name, registry.family);
+  const method = (instance as unknown as Record<string, (c: BetaToolsetCallContext, i: unknown) => unknown>)[
+    methodKey(name)
+  ]!;
+  return await method.call(instance, ctx, input);
+}
+
+/**
+ * The text blocks of a `ToolError`'s content: an is_error result may hold text only (`errorTextContent`). An empty one
+ * still signals that the call failed.
+ */
+export function errorContent(error: ToolError): BetaTextBlockParam[] {
+  const content = errorTextContent(error.content);
+  if (typeof content === 'string') return content === '' ? [] : [{ type: 'text', text: content }];
+  return content;
+}
+
+/**
+ * `error` with each text block run through `check` and then bounded to the field limit. The same object when nothing
+ * changed. The bound comes after the check: a driver's exception can embed a page-sized payload, and cutting first
+ * would let a page place a path across the cut where the check reads a shorter one.
+ */
+export async function checkedError(
+  error: ToolError,
+  check: (text: string) => Promisable<string> = (text) => text,
+): Promise<ToolError> {
+  const content = errorContent(error);
+  const checked = await Promise.all(
+    content.map(async (block) => ({ ...block, text: cutPoints(await check(block.text), FIELD_MAX) })),
+  );
+  if (checked.every((block, i) => block.text === content[i]!.text)) return error;
+  return new ToolError(checked);
+}
+
+/**
+ * Ask `confirm` about the call awaiting approval: returns when it approved, throws the refusal the model reads
+ * otherwise. A `ToolError` it throws is relayed as-is. Any other exception means the prompt failed, and refuses the
+ * call rather than ending the run. Anything but `true` declines the call.
+ */
+export async function confirmOrThrow<Context>(
+  confirm: (ctx: Context) => Promisable<boolean>,
+  ctx: Context,
+  call: MemberCall,
+): Promise<void> {
+  const name = call.member!.name;
+
+  let returned: unknown;
+  try {
+    returned = await confirm(ctx);
+  } catch (error) {
+    throwIfPropagates(error, call.ctx);
+    if (error instanceof ToolError) throw error;
+    throw new ConfirmFailedError(name);
+  }
+
+  if (returned !== true) throw new ConfirmDeclinedError(name);
+}
+
+// --- one call at a time ------------------------------------------------------------------------------------
+
+/** The queue every top-level call of one toolset chains behind: calls run one at a time, in arrival order. */
+export class CallQueue {
+  #chain: Promise<void> = Promise.resolve();
+
+  /** Run `turn` once the calls ahead of it have settled; a call whose `signal` aborts meanwhile leaves the queue at once. */
+  enqueue<T>(signal: AbortSignal | null | undefined, turn: () => Promise<T>): Promise<T> {
+    const previous = this.#chain;
+    let ready: Promise<unknown> = previous;
+    let onAbort = (): void => undefined;
+
+    if (signal) {
+      // A queued call whose run is aborted leaves the queue at once rather than when its turn comes.
+      const aborted = new Promise<never>((_, reject) => {
+        onAbort = () => reject(new APIUserAbortError());
+        if (signal.aborted) onAbort();
+        else signal.addEventListener('abort', onAbort, { once: true });
+      });
+      aborted.catch(() => undefined);
+      ready = Promise.race([previous, aborted]);
+    }
+
+    const run = ready.then(turn);
+    if (signal) {
+      // The listener goes when the call settles, so a long-lived signal shared by many calls does not collect one each.
+      run.finally(() => signal.removeEventListener('abort', onAbort)).catch(() => undefined);
+    }
+
+    // The queue still waits for the call ahead even when this one gave up waiting for it, and a failed call does not
+    // break it.
+    this.#chain = Promise.allSettled([previous, run]).then(() => undefined);
+    return run;
+  }
+
+  /** Settles once every call accepted so far has settled, failed ones included. */
+  drain(): Promise<void> {
+    return this.#chain;
+  }
+}
+
+/**
+ * Wire `Symbol.asyncDispose` on a toolset class's prototype to its `close()`, where the engine provides the symbol.
+ * The tsconfig targets ES2020, so there is no typed `AsyncDisposable` member: `await using` works from JavaScript on
+ * those engines, and TypeScript callers use `close()`.
+ */
+export function wireAsyncDispose(prototype: { close(): Promise<void> }): void {
+  const asyncDispose = (Symbol as { asyncDispose?: symbol }).asyncDispose;
+  if (!asyncDispose || Object.prototype.hasOwnProperty.call(prototype, asyncDispose)) return;
+  Object.defineProperty(prototype, asyncDispose, {
+    // Through `this`, so a subclass's `close()` override is what runs.
+    value: function (this: { close(): Promise<void> }) {
+      return this.close();
+    },
+    configurable: true,
+    writable: true,
+  });
+}

package/node_modules/@anthropic-ai/sdk/src/lib/internal/toolsets/errors.ts

@@ -0,0 +1,130 @@
+import { AnthropicError } from '../../../core/error';
+import type { ToolsetFamily } from './family';
+import { ToolError } from '../../tools/ToolError';
+import { logSafe, quotedName } from './sanitize';
+
+/**
+ * Thrown when your code uses a toolset's API incorrectly. Catch it to catch all three kinds below.
+ *
+ * The only exception the tool runner propagates from a member call: anything else a member throws becomes an
+ * `is_error` result the model can react to, and the loop continues.
+ */
+export class ToolsetUsageError extends AnthropicError {
+  /** The wrapped error, when there is one (a driver's `browserState` that threw). Its stack is the driver's own. */
+  override readonly cause?: unknown;
+
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message);
+    this.name = 'ToolsetUsageError';
+    if (options && 'cause' in options) this.cause = options.cause;
+  }
+}
+
+/** A construction-time mistake: an option combination the toolset cannot honour. */
+export class ToolsetConfigError extends ToolsetUsageError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'ToolsetConfigError';
+  }
+}
+
+/** Misuse of the SDK's own API detected at call time (a `browserState` that threw, a misrouted `tool_use`). */
+export class ToolsetContractError extends ToolsetUsageError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'ToolsetContractError';
+  }
+}
+
+/** A member run on a toolset you already closed. */
+export class ToolsetClosedError extends ToolsetUsageError {
+  constructor(message: string, options?: { cause?: unknown }) {
+    super(message, options);
+    this.name = 'ToolsetClosedError';
+  }
+}
+
+// --- the SDK's own refusals ---------------------------------------------------------------------------
+// Each is a `ToolError`, so the model reads it as an `is_error` result and the loop continues. The subclass lets
+// your code (an `execute` override, a test) identify the refusal without comparing text.
+
+/** The refusal the model reads for a member name the toolset does not have. */
+export class UnknownMemberError extends ToolError {
+  constructor(name: string, family: ToolsetFamily) {
+    super(`Error: unknown ${family} toolset member '${quotedName(name)}'`);
+    this.name = 'UnknownMemberError';
+  }
+}
+
+/** The refusal the model reads for a member your application's `configs` disabled. */
+export class DisabledMemberError extends ToolError {
+  constructor(name: string) {
+    super(
+      `The '${name}' action is not permitted by this application's permissions and cannot be used in this session.`,
+    );
+    this.name = 'DisabledMemberError';
+  }
+}
+
+/** The refusal the model reads for a member the driver does not implement. */
+export class UnavailableMemberError extends ToolError {
+  constructor(name: string, family: ToolsetFamily) {
+    super(`The ${family} toolset member '${name}' is not available in this environment.`);
+    this.name = 'UnavailableMemberError';
+  }
+}
+
+/**
+ * The refusal the model reads when its `tool_use.input` does not fit the member: `problem` is the field and what was
+ * expected.
+ */
+export class InvalidMemberInputError extends ToolError {
+  constructor(name: string, family: ToolsetFamily, problem: string) {
+    super(`invalid input for ${family} member '${name}': ${problem}`);
+    this.name = 'InvalidMemberInputError';
+  }
+}
+
+/**
+ * The refusal the model reads when your `urlPolicy` threw something other than a `ToolError` (a `ToolError` it throws
+ * reaches the model as thrown). `reason` is the line it reads.
+ */
+export class URLRefusedError extends ToolError {
+  constructor(reason: string) {
+    // one bounded line: a reason may echo a model-written address of any length
+    super(logSafe(reason));
+    this.name = 'URLRefusedError';
+  }
+}
+
+/** The refusal the model reads when your `confirm` callable answered anything but `true` for the member `name`. */
+export class ConfirmDeclinedError extends ToolError {
+  constructor(name: string) {
+    super(`The user did not grant permission to run '${name}'. Do not retry it unless the user asks you to.`);
+    this.name = 'ConfirmDeclinedError';
+  }
+}
+
+/** The refusal the model reads when your `confirm` callable threw, so no answer could be obtained for `name`. */
+export class ConfirmFailedError extends ToolError {
+  constructor(name: string) {
+    super(
+      `Permission to run '${name}' could not be obtained (the confirmation prompt failed). Do not retry it unless the user asks you to.`,
+    );
+    this.name = 'ConfirmFailedError';
+  }
+}
+
+/**
+ * The refusal the model reads for a `file_upload` the file policy (or its absence) does not admit. `reason` is the line
+ * it reads.
+ */
+export class UploadRefusedError extends ToolError {
+  constructor(reason: string) {
+    super(reason);
+    this.name = 'UploadRefusedError';
+  }
+}
+
+/** The refusal for a `file_upload` by path when no upload root is configured (no file policy, or one without roots). */
+export const NO_UPLOAD_ROOTS = 'file_upload has no configured upload roots';

package/node_modules/@anthropic-ai/sdk/src/lib/internal/toolsets/family.ts

@@ -0,0 +1,23 @@
+/**
+ * The toolset families the SDK runs, and how a `tools[]` entry maps to one.
+ */
+import type { BetaRunnableToolset, BetaToolsetParam } from '../../tools/BetaRunnableToolset';
+import type { BetaToolRunnerParams } from '../../tools/BetaToolRunner';
+
+export type ToolsetFamily = 'browser' | 'computer';
+
+/** Dated `tools[]` entry `type` → the family stamped on member blocks. */
+export const TOOLSET_TYPE_TO_FAMILY = {
+  browser_toolset_20260801: 'browser',
+  computer_toolset_20260801: 'computer',
+} as const satisfies Record<string, ToolsetFamily>;
+
+export function toolsetFamily(toolset: BetaToolsetParam): ToolsetFamily {
+  return TOOLSET_TYPE_TO_FAMILY[toolset.type];
+}
+
+/** Whether a `tools` entry is a toolset the runner can execute locally. */
+export function isRunnableToolset(t: BetaToolRunnerParams['tools'][number]): t is BetaRunnableToolset {
+  // `in` alone would accept inherited keys such as `toString`
+  return 'run' in t && t.type != null && Object.prototype.hasOwnProperty.call(TOOLSET_TYPE_TO_FAMILY, t.type);
+}

package/node_modules/@anthropic-ai/sdk/src/lib/internal/toolsets/hooks.ts

@@ -0,0 +1,98 @@
+/**
+ * The types of the toolset constructor hooks. `BetaToolsetCallContext`, `MemberConfirmContext` and `BetaToolConfigs` serve
+ * every family, `BetaComputerConfirmContext` and `BetaComputerConfirmCallable` serve the computer toolset, and the rest
+ * serve the browser toolset.
+ */
+import type { BetaToolUse, Promisable } from '../../tools/BetaRunnableTool';
+import type { BetaComputerMemberInput, BetaComputerMemberName } from './computer-members';
+import type { BetaBrowserMemberName } from './inputs';
+import type { BetaBrowserState } from './results';
+import type { BetaBrowserMemberInput, BetaCacheControlEphemeral } from '../../../resources/beta';
+
+/**
+ * What a member receives alongside its input, and what `confirm` (and the browser toolset's `browserState`) receive
+ * about the call: the model call being served (`toolUse`, absent only when your own code calls `run()` without one)
+ * and the run's abort signal. The tool runner's `BetaToolRunContext` is one.
+ */
+export interface BetaToolsetCallContext {
+  toolUse?: BetaToolUse | undefined;
+  /** Aborted when the run is. The runner still waits for the member to return, so check it in long-running work. */
+  signal?: AbortSignal | null | undefined;
+}
+
+/**
+ * What a hook receives about the call it serves: the first argument of `urlPolicy(context, url)` and of the file
+ * policy's `resolveUploadPaths(context, paths)` / `resolveUploadDocuments(context, documentIds)`.
+ */
+export interface BetaURLContext {
+  /** The member being called: `navigate` for the URL policy, `file_upload` for the file policy. */
+  member?: BetaBrowserMemberName | undefined;
+  /** The tab the call named, if any, as the model sent it and not checked. */
+  tabId?: string | undefined;
+  /** The model call being served. Absent when a hook is invoked outside one. */
+  toolUseId?: string | undefined;
+}
+
+/**
+ * `(context, url)`, called once for each `navigate` with `url` exactly as the model wrote it, before the driver
+ * receives it. Return (or resolve) nothing to allow, throw `ToolError` to refuse. May be async.
+ */
+export type BetaURLPolicy = (context: BetaURLContext, url: string) => void | Promise<void>;
+
+/**
+ * Decides which upload paths and document ids a `file_upload` may use and which download paths the model may see.
+ * With no file policy configured, an upload input that contains a path or a document id is refused and download
+ * paths are never shown to the model.
+ */
+export interface BetaFilePolicy {
+  /**
+   * Resolve each path the model asked to upload, or throw `ToolError` to refuse. The driver receives the returned paths
+   * in `input.paths`.
+   */
+  resolveUploadPaths(ctx: BetaURLContext, paths: string[]): Promisable<string[]>;
+  /**
+   * Vet each document id (a file staged with the Files API) the model asked to upload, or throw `ToolError` to refuse.
+   * The driver receives the returned ids in `input.document_ids`.
+   */
+  resolveUploadDocuments(ctx: BetaURLContext, documentIds: string[]): Promisable<string[]>;
+  /** Whether a `download_completed` path may reach the model. `false` forwards the event without it. May be async. */
+  isPathVisible(path: string): Promisable<boolean>;
+}
+
+/** What every family's `confirm` callable receives about the call awaiting approval: the member and its input. */
+export interface MemberConfirmContext<Name extends string, Input> extends BetaToolsetCallContext {
+  readonly member: Name;
+  readonly input: Input;
+}
+
+/**
+ * Passed to the browser toolset's `confirm` for each call awaiting approval. `tabId` and `tabURL` describe the tab
+ * the call targets (else the active tab) in the last report the SDK collected, which the model saw unless that call
+ * failed or was refused; the page may have changed since. When that report has no such tab (anything before the
+ * first), `tabURL` is undefined and `tabId` is the model's `tab_id` as sent, not checked.
+ */
+export interface BetaConfirmContext
+  extends MemberConfirmContext<BetaBrowserMemberName, BetaBrowserMemberInput> {
+  /** The driver's URL string, folded to one line. One longer than 4,096 characters is cut and begins with `…`. */
+  readonly tabURL?: string | undefined;
+  readonly tabId?: string | undefined;
+}
+
+/** Fields set on the toolset's `tools[]` entry itself rather than on a member. `toJSON()` copies them onto it. */
+export interface BetaToolConfigs {
+  cache_control?: BetaCacheControlEphemeral | null;
+}
+
+/** true runs the call, false declines it. The context contains the member and its input. */
+export type BetaConfirmCallable = (ctx: BetaConfirmContext) => Promisable<boolean>;
+
+/** What the computer toolset's `confirm` callable is told about the call awaiting approval: the member and its input. */
+export type BetaComputerConfirmContext = MemberConfirmContext<
+  BetaComputerMemberName,
+  BetaComputerMemberInput
+>;
+
+/** true runs the call, false declines it; the context carries the member and its input. */
+export type BetaComputerConfirmCallable = (ctx: BetaComputerConfirmContext) => Promisable<boolean>;
+
+export type BetaBrowserStateCallable = (ctx: BetaToolsetCallContext) => Promisable<BetaBrowserState>;