digital-tools 2.1.1 → 2.3.0

package/src/tools/web.ts

@@ -23,7 +23,11 @@ export const fetchUrl = defineTool<
     type: 'object',
     properties: {
       url: { type: 'string', description: 'URL to fetch' },
-      method: { type: 'string', description: 'HTTP method (default: GET)', enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'] },
+      method: {
+        type: 'string',
+        description: 'HTTP method (default: GET)',
+        enum: ['GET', 'POST', 'PUT', 'DELETE', 'PATCH'],
+      },
       headers: { type: 'object', description: 'Request headers' },
       body: { type: 'string', description: 'Request body (for POST/PUT/PATCH)' },
     },
@@ -32,8 +36,8 @@ export const fetchUrl = defineTool<
   handler: async (input) => {
     const response = await fetch(input.url, {
       method: input.method || 'GET',
-      headers: input.headers,
-      body: input.body,
+      ...(input.headers !== undefined && { headers: input.headers }),
+      ...(input.body !== undefined && { body: input.body }),
     })
 
     const headers: Record<string, string> = {}
@@ -75,21 +79,26 @@ export const parseHtml = defineTool<
   },
   handler: async (input) => {
     // Basic HTML parsing without DOM (would use cheerio or jsdom in production)
-    const text = input.html.replace(/<[^>]*>/g, ' ').replace(/\s+/g, ' ').trim()
+    const text = input.html
+      .replace(/<[^>]*>/g, ' ')
+      .replace(/\s+/g, ' ')
+      .trim()
 
     // Extract links
     const linkRegex = /href="([^"]+)"/g
     const links: string[] = []
     let match
     while ((match = linkRegex.exec(input.html)) !== null) {
-      links.push(match[1])
+      if (match[1] !== undefined) {
+        links.push(match[1])
+      }
     }
 
     // Extract images
     const imgRegex = /src="([^"]+)"/g
     const images: string[] = []
     while ((match = imgRegex.exec(input.html)) !== null) {
-      if (match[1].match(/\.(jpg|jpeg|png|gif|webp|svg)/i)) {
+      if (match[1] !== undefined && match[1].match(/\.(jpg|jpeg|png|gif|webp|svg)/i)) {
         images.push(match[1])
       }
     }
@@ -127,12 +136,13 @@ export const readUrl = defineTool<
 
     // Extract title
     const titleMatch = html.match(/<title[^>]*>([^<]+)<\/title>/i)
-    const title = titleMatch ? titleMatch[1].trim() : ''
+    const title = titleMatch && titleMatch[1] ? titleMatch[1].trim() : ''
 
     // Extract body text
     const bodyMatch = html.match(/<body[^>]*>([\s\S]*)<\/body>/i)
-    const body = bodyMatch ? bodyMatch[1] : html
-    const text = body.replace(/<script[\s\S]*?<\/script>/gi, '')
+    const body = bodyMatch && bodyMatch[1] ? bodyMatch[1] : html
+    const text = body
+      .replace(/<script[\s\S]*?<\/script>/gi, '')
       .replace(/<style[\s\S]*?<\/style>/gi, '')
       .replace(/<[^>]*>/g, ' ')
       .replace(/\s+/g, ' ')
@@ -143,7 +153,9 @@ export const readUrl = defineTool<
     const links: string[] = []
     let match
     while ((match = linkRegex.exec(html)) !== null) {
-      links.push(match[1])
+      if (match[1] !== undefined) {
+        links.push(match[1])
+      }
     }
 
     return { title, text: text.slice(0, 10000), links: [...new Set(links)] }

package/src/track-record.ts

@@ -0,0 +1,106 @@
+/**
+ * Track Record + Agent Mode + Promotion Policy (v3 §6 — Function-as-typed-primitive)
+ *
+ * Earned-autonomy primitives shared across `digital-tools` Function refs and
+ * (later) `digital-workers`. A Function or Worker accumulates a {@link TrackRecord}
+ * over time; a {@link PromotionPolicy} declares the threshold rules that move a
+ * Function up or down the {@link AgentMode} ladder (manual → supervised →
+ * autonomous, and back).
+ *
+ * These types live in `digital-tools` because the Function discriminated union
+ * is the first consumer; `digital-workers` re-exports the same types when it
+ * lands so per-Worker autonomy and per-Function autonomy use one vocabulary.
+ *
+ * @packageDocumentation
+ */
+
+import type { Money } from 'autonomous-finance'
+
+/**
+ * Operating mode of an agentic Function (or Worker).
+ *
+ * - `manual`     — every invocation requires a human to initiate.
+ * - `supervised` — runs autonomously but every output is reviewed before
+ *                  being released downstream (gated on human sign-off).
+ * - `autonomous` — runs and releases without per-invocation review;
+ *                  oversight is post-hoc and sample-based.
+ */
+export type AgentMode = 'manual' | 'supervised' | 'autonomous'
+
+/**
+ * Direction of the most recent measured trend in a {@link TrackRecord}.
+ */
+export type TrendDirection = 'improving' | 'stable' | 'declining'
+
+/**
+ * Quality + cost + oversight signal accumulated over a Function or Worker's
+ * recent invocations. Drives {@link PromotionPolicy} thresholds.
+ *
+ * All fields are present for any Function that has been invoked at least once;
+ * the registry materialises a zero-sample record on first registration so
+ * thresholds always have a value to compare against.
+ */
+export interface TrackRecord {
+  /** Fraction of invocations that met the OutcomeContract (0–1). */
+  accuracy: number
+  /** Number of invocations the record summarises. */
+  samples: number
+  /** Direction of the most recent measured trend. */
+  trend: TrendDirection
+  /** ISO-8601 timestamp of the most recent sample. */
+  lastUpdated: string
+  /** Average cost per successful invocation; absent until at least one success. */
+  costPerSuccess?: Money
+  /**
+   * Fraction of supervised invocations whose human reviewer overrode the
+   * Function's output (0–1). High values indicate the Function is not ready
+   * for promotion to `autonomous`.
+   */
+  reviewerOverrideRate?: number
+  /**
+   * Composite 0–100 score combining accuracy / cost / override rate. Used by
+   * downstream catalog UI when ranking Functions; the precise formula lives
+   * in `ai-evaluate` so it can evolve without a type change here.
+   */
+  digitalScore?: number
+}
+
+/**
+ * Threshold-gated rule that promotes or demotes a Function between
+ * {@link AgentMode} values based on its accumulated {@link TrackRecord}.
+ *
+ * Predicates are expressed as strings so they can be persisted alongside the
+ * Function definition and re-evaluated against fresh records without a code
+ * change. The evaluator (lives in `ai-evaluate`) parses them against a
+ * `TrackRecord` plus invocation context.
+ */
+export interface PromotionRule {
+  /**
+   * String predicate evaluated against the {@link TrackRecord} (and optionally
+   * elapsed time / sample size). Examples:
+   *   - `'accuracy >= 0.95 && samples >= 100'`
+   *   - `'reviewerOverrideRate < 0.05 && trend === "improving"'`
+   */
+  when: string
+  /** Mode to move the Function to when {@link when} holds. */
+  to: AgentMode
+  /** Optional human-readable description of the rule's intent. */
+  rationale?: string
+}
+
+/**
+ * Declarative ladder describing when a Function may climb to a more
+ * autonomous {@link AgentMode} and when it must step back down.
+ *
+ * `evaluate` sets the cadence at which the policy is re-checked against the
+ * latest {@link TrackRecord}; `'continuous'` re-evaluates after every
+ * invocation, `'daily'` / `'weekly'` use a scheduled job.
+ */
+export interface PromotionPolicy {
+  /** Rules that move the Function up the autonomy ladder. */
+  promote: PromotionRule[]
+  /** Rules that move the Function down the autonomy ladder. */
+  demote: PromotionRule[]
+  /** Cadence at which the policy is re-evaluated. */
+  evaluate: 'continuous' | 'daily' | 'weekly'
+}

package/src/types.ts

@@ -9,8 +9,17 @@
  */
 
 import type { JSONSchema } from 'ai-functions'
+import type { Frame, ActionRef } from 'digital-objects'
+import type { Identity, PaymentReceipt } from 'id.org.ai'
 import type { z } from 'zod'
 
+// Re-export for downstream consumers (digital-tasks/digital-workers can use the same Frame)
+export type { Frame, ActionRef } from 'digital-objects'
+
+// Re-export id.org.ai canonical types so consumers don't need a separate import.
+// `wrapTool()` populates these on `ToolHandlerContext` after broker gating.
+export type { Identity, PaymentReceipt } from 'id.org.ai'
+
 // ============================================================================
 // Tool Category Ontology
 // ============================================================================
@@ -38,10 +47,10 @@ export type ToolCategory =
 export type CommunicationSubcategory =
   | 'email'
   | 'sms'
-  | 'channel'        // Brand-agnostic team messaging (Slack/Teams/Discord)
-  | 'workspace'      // Team messaging workspace/organization
+  | 'channel' // Brand-agnostic team messaging (Slack/Teams/Discord)
+  | 'workspace' // Team messaging workspace/organization
   | 'direct-message' // Private/DM conversations
-  | 'chat'           // Generic chat
+  | 'chat' // Generic chat
   | 'notification'
   | 'voice'
   | 'video-call'
@@ -283,15 +292,166 @@ export interface ToolOutput {
   streaming?: boolean
 }
 
+// ============================================================================
+// SVO Co-Design Types (aip-oejp): verb / frame / auth / pricing / handler ctx
+// ============================================================================
+
+/**
+ * Reference to an Identity in `id.org.ai`.
+ *
+ * Currently a string ID; the canonical type will move to `id.org.ai`
+ * once that package is published. Until then, treat as opaque.
+ */
+export type IdentityRef = string
+
+/**
+ * Payment rail used to satisfy a tool's `pricing` requirement.
+ *
+ * Minimal local definition — the canonical type will come from
+ * `id.org.ai` (PaymentBroker) once that package is published.
+ */
+export interface PaymentRail {
+  /** Rail used to settle the payment */
+  rail: 'x402' | 'mpp'
+  /** Optional receipt / proof of payment from the broker */
+  receipt?: string
+}
+
+/**
+ * Authentication requirement for invoking a tool.
+ *
+ * Declares which auth scheme and scopes the caller must present
+ * before the handler is executed.
+ */
+export interface AuthRequirement {
+  /** OAuth scopes / API key scopes required */
+  scopes: string[]
+  /** Auth mechanism the tool requires; `none` means public */
+  required: 'oauth' | 'apiKey' | 'none'
+}
+
+/**
+ * Payment requirement attached to a tool, MDXLD-shaped and
+ * compatible with x402 / MPP payment rails.
+ *
+ * When present, callers must satisfy this before the handler runs;
+ * the broker (id.org.ai) negotiates an acceptable rail and injects
+ * a `PaymentRail` into the handler context.
+ */
+export interface PaymentRequired {
+  /** MDXLD type discriminator */
+  $type: 'PaymentRequired'
+  /** Amount as a string (preserves precision for crypto/fiat) */
+  amount: string
+  /** ISO 4217 currency code or asset symbol (e.g. 'USD', 'USDC') */
+  currency: string
+  /** Payment rails this tool will accept */
+  accepts: ('x402' | 'mpp')[]
+  /** Wallet address or stripeAccountId of the recipient */
+  recipient: string
+  /** Optional facilitator URL/identifier */
+  facilitator?: string
+}
+
+/**
+ * Context object passed to a tool handler when invoked through
+ * an SVO-aware dispatcher.
+ *
+ * This is distinct from the registry-level `ToolContext` (executor
+ * metadata for tracing/audit) — `ToolHandlerContext` carries
+ * runtime resources the handler needs to perform the action:
+ * the caller's identity, an injected payment rail (if `pricing`
+ * was satisfied), and the parent Action that caused the call.
+ *
+ * Handlers that don't need any of this can keep the arity-1
+ * `(args) => result` signature; arity-2 `(args, ctx) => result`
+ * is opt-in.
+ *
+ * `wrapTool()` (the broker-aware HTTP wrapper) populates `identity`
+ * with a full id.org.ai `Identity` record and, when `pricing` is
+ * satisfied, populates `paymentReceipt` with the canonical receipt
+ * from `PaymentBroker.settle()`. Older dispatchers that pass an
+ * opaque `IdentityRef` string and/or the local `PaymentRail` shape
+ * remain supported (the handler signature widens, not narrows).
+ */
+export interface ToolHandlerContext {
+  /**
+   * Identity of the caller. Either:
+   *   - the canonical {@link Identity} record from `id.org.ai`
+   *     (populated by `wrapTool()` after `AuthBroker.gate()`), or
+   *   - an opaque {@link IdentityRef} string for legacy dispatchers.
+   */
+  identity: Identity | IdentityRef
+  /**
+   * Backwards-compatible local `PaymentRail` shape. Older dispatchers
+   * may set this; new code should prefer {@link paymentReceipt} which
+   * carries the full id.org.ai receipt (txRef, settledAt, response
+   * header, …).
+   */
+  payment?: PaymentRail
+  /**
+   * Canonical {@link PaymentReceipt} from `PaymentBroker.settle()`.
+   * Populated by `wrapTool()` when the tool's `pricing` is satisfied.
+   */
+  paymentReceipt?: PaymentReceipt
+  /** Parent Action that caused this tool invocation, if any */
+  parentAction?: ActionRef
+}
+
 // ============================================================================
 // Core Tool Interface
 // ============================================================================
 
 /**
- * Core Tool definition - the foundational type
+ * Core Tool definition - the foundational type for digital tools.
+ *
+ * Tools can be used by both humans and AI agents. They provide a standardized
+ * interface for performing actions across various categories including
+ * communication, data, development, documents, finance, and more.
+ *
+ * @typeParam TInput - The type of input the tool handler accepts
+ * @typeParam TOutput - The type of output the tool handler returns
+ *
+ * @example Basic tool definition
+ * ```typescript
+ * import { Tool, defineTool } from 'digital-tools'
  *
- * Tools can be used by both humans and AI agents. They provide
- * a standardized interface for performing actions.
+ * const greetTool: Tool<{ name: string }, string> = {
+ *   id: 'communication.greeting.hello',
+ *   name: 'Greet User',
+ *   description: 'Generates a greeting message for the specified user',
+ *   category: 'communication',
+ *   parameters: [{
+ *     name: 'name',
+ *     description: 'Name of the person to greet',
+ *     schema: { type: 'string' },
+ *     required: true,
+ *   }],
+ *   handler: ({ name }) => `Hello, ${name}!`,
+ * }
+ * ```
+ *
+ * @example Using defineTool helper with Zod schema
+ * ```typescript
+ * import { defineTool } from 'digital-tools'
+ * import { z } from 'zod'
+ *
+ * const fetchTool = defineTool({
+ *   id: 'web.fetch.url',
+ *   name: 'Fetch URL',
+ *   description: 'Fetches content from a URL',
+ *   category: 'web',
+ *   input: z.object({ url: z.string().url() }),
+ *   handler: async ({ url }) => {
+ *     const response = await fetch(url)
+ *     return response.text()
+ *   },
+ * })
+ * ```
+ *
+ * @see {@link ToolCategory} for available categories
+ * @see {@link ToolRegistry} for tool registration and discovery
+ * @see {@link defineTool} for the recommended way to create tools
  */
 export interface Tool<TInput = unknown, TOutput = unknown> {
   /** Unique tool identifier (e.g., 'communication.email.send') */
@@ -329,6 +489,31 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
   /** Rate limiting */
   rateLimit?: RateLimit
 
+  // SVO Co-Design (aip-oejp) — all optional, additive over existing tools
+  /**
+   * Canonical Verb name this tool implements (e.g. 'send', 'transcribe').
+   *
+   * Used by SVO-aware dispatchers to resolve a Verb in `digital-objects`
+   * and pick a Tool registered for it. Cross-package Verb auto-registration
+   * is intentionally NOT performed here — see follow-up bead.
+   */
+  verb?: string
+
+  /**
+   * Frame declaring the complement-role types this tool accepts.
+   *
+   * Reuses the canonical {@link Frame} type from `digital-objects` so
+   * Tool frames and Verb frames stay in lockstep. When absent, the tool
+   * is treated as permissive (frame inferred from input shape).
+   */
+  frame?: Frame
+
+  /** Auth requirement gate; absent means no auth required */
+  auth?: AuthRequirement
+
+  /** Pricing requirement (x402/MPP); absent means free */
+  pricing?: PaymentRequired
+
   // Input/Output
   /** Input parameters */
   parameters: ToolParameter[]
@@ -336,8 +521,16 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
   /** Output definition */
   output?: ToolOutput
 
-  /** The tool implementation */
-  handler: (input: TInput) => TOutput | Promise<TOutput>
+  /**
+   * The tool implementation.
+   *
+   * Backward-compatible: handlers may take just `(input)` (arity-1) or
+   * opt into the SVO handler context with `(input, ctx)` (arity-2).
+   * Dispatchers that don't have a {@link ToolHandlerContext} should
+   * call the handler with the input only — TypeScript permits this
+   * because the second parameter is optional.
+   */
+  handler: (input: TInput, ctx?: ToolHandlerContext) => TOutput | Promise<TOutput>
 
   // Metadata
   /** Tool author/owner */
@@ -360,8 +553,22 @@ export interface Tool<TInput = unknown, TOutput = unknown> {
 }
 
 /**
- * Any tool type - used for arrays and collections of tools
- * with different input/output types
+ * Any tool type - used for arrays and collections of tools with different
+ * input/output types.
+ *
+ * Use this type when you need to work with heterogeneous collections of tools,
+ * such as in registries, tool lists, or when the specific input/output types
+ * are not known at compile time.
+ *
+ * @example Tool collection
+ * ```typescript
+ * import { AnyTool } from 'digital-tools'
+ *
+ * const tools: AnyTool[] = [emailTool, slackTool, fetchTool]
+ * tools.forEach(tool => console.log(tool.name))
+ * ```
+ *
+ * @see {@link Tool} for the base tool type with specific type parameters
  */
 // eslint-disable-next-line @typescript-eslint/no-explicit-any
 export type AnyTool = Tool<any, any>
@@ -388,10 +595,31 @@ export interface DefineToolOptions<TInput, TOutput> {
   input: Schema
   /** Output schema (optional) */
   output?: Schema
-  /** The handler function */
-  handler: (input: TInput) => TOutput | Promise<TOutput>
+
+  // SVO Co-Design (aip-oejp) — all optional, additive
+  /** Canonical Verb name this tool implements */
+  verb?: string
+  /** Frame from `digital-objects` declaring complement-role types */
+  frame?: Frame
+  /** Auth requirement; absent means no auth required */
+  auth?: AuthRequirement
+  /** Pricing requirement (x402/MPP); absent means free */
+  pricing?: PaymentRequired
+
+  /**
+   * The handler function.
+   *
+   * Backward-compatible: arity-1 `(input)` handlers continue to work;
+   * arity-2 `(input, ctx)` handlers receive the SVO {@link ToolHandlerContext}.
+   */
+  handler: (input: TInput, ctx?: ToolHandlerContext) => TOutput | Promise<TOutput>
   /** Additional options */
-  options?: Partial<Omit<Tool<TInput, TOutput>, 'id' | 'name' | 'description' | 'category' | 'parameters' | 'handler'>>
+  options?: Partial<
+    Omit<
+      Tool<TInput, TOutput>,
+      'id' | 'name' | 'description' | 'category' | 'parameters' | 'handler'
+    >
+  >
 }
 
 /**

package/src/verb-registration.ts

@@ -0,0 +1,197 @@
+/**
+ * Verb Auto-Registration (aip-47tm)
+ *
+ * Bridges `defineTool()` (synchronous, side-effect-free builder) to
+ * `digital-objects`' provider-mediated `defineVerb()` (async, I/O-bound).
+ *
+ * ## Design choice — Option B: explicit bootstrap
+ *
+ * `defineTool({ verb, frame })` records the metadata on the Tool but does
+ * NOT call `provider.defineVerb()` itself. Cross-package side effects
+ * from a pure builder are surprising; the provider is also caller-supplied,
+ * so eager registration would force `defineTool` to know about a provider
+ * it doesn't currently take.
+ *
+ * Instead, registration is an explicit, idempotent helper:
+ *
+ *   - `registerToolVerb(provider, tool)`     — single-tool, used from
+ *                                                custom dispatchers that
+ *                                                want lazy-on-first-call.
+ *   - `registerToolVerbs(provider, tools)`   — bootstrap list, used at
+ *                                                startup once per provider.
+ *
+ * Both are idempotent: re-registering a Verb with the same name and same
+ * frame is a no-op. Re-registering with a different frame throws —
+ * silent overwrite would mask an ontology drift bug.
+ *
+ * ## Why not Option A (lazy in `wrapTool`)
+ *
+ * `wrapTool()` takes auth + payment brokers, not a `DigitalObjectsProvider`.
+ * Wiring a provider into `wrapTool()` would couple HTTP wrapping to the
+ * digital-objects ontology — a layering inversion. Callers that want
+ * lazy-on-first-call can compose `registerToolVerb()` into their own
+ * dispatcher; the helper is fast enough to call per-request because the
+ * idempotency check short-circuits to a single `getVerb()` lookup.
+ *
+ * ## Why not Option C (eager-with-deferred-provider queue)
+ *
+ * A module-level queue is global state in `digital-tools` — exactly what
+ * the bead forbids. It also can't flush deterministically across
+ * concurrent test workers, and ordering becomes load-dependent.
+ *
+ * @packageDocumentation
+ */
+
+import type { Frame, Verb, VerbDefinition } from 'digital-objects'
+import type { AnyTool, Tool } from './types.js'
+
+/**
+ * Subset of `DigitalObjectsProvider` that this module requires.
+ *
+ * We deliberately accept only `getVerb` + `defineVerb` (rather than the
+ * full provider interface) so callers can pass any object with these
+ * two methods — including HTTP/RPC clients, test doubles, and the
+ * canonical `MemoryProvider`.
+ */
+export interface VerbRegistrationProvider {
+  defineVerb(def: VerbDefinition): Promise<Verb>
+  getVerb(name: string): Promise<Verb | null>
+}
+
+/**
+ * Compare two optional Frames structurally. Returns true when both are
+ * undefined, or both define the same set of role -> NounRef mappings.
+ *
+ * `manner` (string[]) is compared as an unordered set since the role
+ * order is not semantically meaningful.
+ */
+function framesEqual(a: Frame | undefined, b: Frame | undefined): boolean {
+  if (a === b) return true
+  if (!a || !b) return false
+
+  const keys = new Set<keyof Frame>([
+    ...(Object.keys(a) as (keyof Frame)[]),
+    ...(Object.keys(b) as (keyof Frame)[]),
+  ])
+
+  for (const k of keys) {
+    const av = a[k]
+    const bv = b[k]
+    if (k === 'manner') {
+      const aArr = (av as string[] | undefined) ?? []
+      const bArr = (bv as string[] | undefined) ?? []
+      if (aArr.length !== bArr.length) return false
+      const aSet = new Set(aArr)
+      for (const v of bArr) if (!aSet.has(v)) return false
+    } else {
+      if (av !== bv) return false
+    }
+  }
+  return true
+}
+
+/**
+ * Mismatch error raised when a Tool tries to register a Verb whose name
+ * already exists with a different frame. We do not silently overwrite —
+ * conflicting ontology shapes are almost always a bug (two tools claiming
+ * the same verb with different role expectations).
+ */
+export class VerbRegistrationConflictError extends Error {
+  constructor(
+    public readonly verbName: string,
+    public readonly existing: Frame | undefined,
+    public readonly incoming: Frame | undefined
+  ) {
+    super(
+      `Verb "${verbName}" is already registered with a different frame. ` +
+        `Tools that share a verb name must declare the same frame. ` +
+        `Re-registering a verb with the same frame is a no-op (idempotent), ` +
+        `but the incoming frame does not match the existing one.`
+    )
+    this.name = 'VerbRegistrationConflictError'
+  }
+}
+
+/**
+ * Register the Verb declared by a single Tool against `provider`.
+ *
+ * - Tools without a `verb` field are skipped (they are not SVO-aware).
+ * - If the verb already exists with the same frame, the call is a no-op
+ *   and the existing Verb is returned (idempotent).
+ * - If the verb already exists with a different frame, throws
+ *   {@link VerbRegistrationConflictError}.
+ *
+ * Suitable for both eager bootstrap and lazy-per-request use:
+ * the idempotency check is a single `getVerb()` lookup, so it is safe
+ * to call from a hot dispatch path.
+ *
+ * @returns The registered Verb, or `null` if the tool has no `verb` field.
+ *
+ * @example Lazy registration in a custom dispatcher
+ * ```ts
+ * async function dispatch(provider: DigitalObjectsProvider, tool: Tool, args: unknown) {
+ *   await registerToolVerb(provider, tool)   // idempotent, cheap on subsequent calls
+ *   return tool.handler(args)
+ * }
+ * ```
+ */
+export async function registerToolVerb(
+  provider: VerbRegistrationProvider,
+  tool: Tool<unknown, unknown> | AnyTool
+): Promise<Verb | null> {
+  if (!tool.verb) return null
+
+  const existing = await provider.getVerb(tool.verb)
+  if (existing) {
+    if (framesEqual(existing.frame, tool.frame)) {
+      return existing
+    }
+    throw new VerbRegistrationConflictError(tool.verb, existing.frame, tool.frame)
+  }
+
+  return provider.defineVerb({
+    name: tool.verb,
+    ...(tool.frame !== undefined && { frame: tool.frame }),
+    ...(tool.description !== undefined && { description: tool.description }),
+  })
+}
+
+/**
+ * Bootstrap helper: register the Verbs for every SVO-aware tool in
+ * `tools` against `provider`.
+ *
+ * Tools without a `verb` field are skipped silently (legacy / non-SVO
+ * tools coexist with SVO-aware tools in the same registry).
+ *
+ * Conflicts (same verb name, different frame) throw on the first
+ * conflicting tool — the caller can decide whether to retry without
+ * the conflicting tool or surface the error.
+ *
+ * @returns The list of Verbs that were registered (or already existed,
+ *          for idempotent calls). Tools with no verb are not included.
+ *
+ * @example Startup
+ * ```ts
+ * import { MemoryProvider, registerToolVerbs, getBuiltinTools } from 'digital-tools'
+ *
+ * const provider = new MemoryProvider()
+ * await registerToolVerbs(provider, getBuiltinTools())
+ * ```
+ */
+export async function registerToolVerbs(
+  provider: VerbRegistrationProvider,
+  tools: ReadonlyArray<Tool<unknown, unknown> | AnyTool>
+): Promise<Verb[]> {
+  const registered: Verb[] = []
+  for (const tool of tools) {
+    const verb = await registerToolVerb(provider, tool)
+    if (verb) registered.push(verb)
+  }
+  return registered
+}
+
+/**
+ * Alias for {@link registerToolVerbs}. The "bootstrap" name reads better
+ * at startup sites where a list of tools is wired against a provider once.
+ */
+export const bootstrapTools = registerToolVerbs