digital-tools 2.1.1 → 2.3.0

package/src/worker.ts

@@ -0,0 +1,370 @@
+/**
+ * Tool Worker - provides tool service via RPC
+ *
+ * This worker can be deployed to Cloudflare Workers or run locally via Miniflare.
+ * It exposes tool registration, discovery, execution, and MCP conversion via Workers RPC.
+ *
+ * Uses Cloudflare Workers RPC (WorkerEntrypoint, RpcTarget) for communication.
+ */
+
+import { WorkerEntrypoint, RpcTarget } from 'cloudflare:workers'
+import type { AnyTool, ToolCategory, ToolQuery, MCPTool, ToolSubcategory } from './types.js'
+
+/**
+ * Core tool service - extends RpcTarget so it can be passed over RPC
+ *
+ * Contains all tool functionality: registration, discovery, execution, and MCP conversion
+ */
+export class ToolServiceCore extends RpcTarget {
+  private tools: Map<string, AnyTool> = new Map()
+
+  constructor() {
+    super()
+    // Register built-in tools
+    this.registerBuiltins()
+  }
+
+  /**
+   * Register built-in tools
+   */
+  private registerBuiltins(): void {
+    // data.json.parse
+    this.register({
+      id: 'data.json.parse',
+      name: 'Parse JSON',
+      description: 'Parse a JSON string into an object',
+      category: 'data',
+      subcategory: 'transform',
+      parameters: [
+        {
+          name: 'text',
+          description: 'JSON string to parse',
+          schema: { type: 'string' },
+          required: true,
+        },
+      ],
+      handler: async (input: { text: string }) => {
+        try {
+          const data = JSON.parse(input.text)
+          return { data, valid: true }
+        } catch (e) {
+          return {
+            data: null,
+            valid: false,
+            error: e instanceof Error ? e.message : 'Invalid JSON',
+          }
+        }
+      },
+      tags: ['json', 'parse', 'transform'],
+    })
+
+    // data.csv.parse
+    this.register({
+      id: 'data.csv.parse',
+      name: 'Parse CSV',
+      description: 'Parse CSV text into an array of objects',
+      category: 'data',
+      subcategory: 'transform',
+      parameters: [
+        {
+          name: 'text',
+          description: 'CSV text to parse',
+          schema: { type: 'string' },
+          required: true,
+        },
+        {
+          name: 'delimiter',
+          description: 'Column delimiter (default: comma)',
+          schema: { type: 'string' },
+          required: false,
+        },
+        {
+          name: 'hasHeaders',
+          description: 'First row is headers (default: true)',
+          schema: { type: 'boolean' },
+          required: false,
+        },
+      ],
+      handler: async (input: { text: string; delimiter?: string; hasHeaders?: boolean }) => {
+        const delimiter = input.delimiter || ','
+        const hasHeaders = input.hasHeaders !== false
+        const lines = input.text.split('\n').filter((line) => line.trim())
+
+        if (lines.length === 0) {
+          return { rows: [], headers: [], rowCount: 0 }
+        }
+
+        const firstLine = lines[0]!
+        const headers = hasHeaders
+          ? firstLine.split(delimiter).map((h) => h.trim())
+          : firstLine.split(delimiter).map((_, i) => `column${i + 1}`)
+
+        const dataLines = hasHeaders ? lines.slice(1) : lines
+
+        const rows = dataLines.map((line) => {
+          const values = line.split(delimiter).map((v) => v.trim())
+          const row: Record<string, string> = {}
+          headers.forEach((header, i) => {
+            row[header] = values[i] || ''
+          })
+          return row
+        })
+
+        return { rows, headers, rowCount: rows.length }
+      },
+      tags: ['csv', 'parse', 'transform'],
+    })
+
+    // data.transform
+    this.register({
+      id: 'data.transform',
+      name: 'Transform Data',
+      description: 'Transform data by mapping fields to new structure',
+      category: 'data',
+      subcategory: 'transform',
+      parameters: [
+        {
+          name: 'data',
+          description: 'Source data to transform',
+          schema: {},
+          required: true,
+        },
+        {
+          name: 'transform',
+          description: 'Mapping of output fields to input paths',
+          schema: { type: 'object' },
+          required: true,
+        },
+      ],
+      handler: async (input: { data: unknown; transform: Record<string, string> }) => {
+        const result: Record<string, unknown> = {}
+
+        for (const [outputKey, inputPath] of Object.entries(input.transform)) {
+          const pathParts = inputPath.split('.')
+          let value: unknown = input.data
+
+          for (const part of pathParts) {
+            if (value && typeof value === 'object' && part in (value as Record<string, unknown>)) {
+              value = (value as Record<string, unknown>)[part]
+            } else {
+              value = undefined
+              break
+            }
+          }
+
+          result[outputKey] = value
+        }
+
+        return { result }
+      },
+      tags: ['transform', 'map', 'extract'],
+    })
+  }
+
+  /**
+   * Register a tool in the service registry
+   */
+  register(tool: AnyTool): void {
+    this.tools.set(tool.id, tool)
+  }
+
+  /**
+   * Unregister a tool
+   */
+  unregister(id: string): boolean {
+    return this.tools.delete(id)
+  }
+
+  /**
+   * Get a tool by ID
+   */
+  get(id: string): AnyTool | undefined {
+    return this.tools.get(id)
+  }
+
+  /**
+   * Check if a tool exists
+   */
+  has(id: string): boolean {
+    return this.tools.has(id)
+  }
+
+  /**
+   * List all tool IDs
+   */
+  list(): string[] {
+    return Array.from(this.tools.keys())
+  }
+
+  /**
+   * Query tools with filtering
+   */
+  query(options: ToolQuery): AnyTool[] {
+    let results = Array.from(this.tools.values())
+
+    // Filter by category
+    if (options.category) {
+      results = results.filter((t) => t.category === options.category)
+    }
+
+    // Filter by subcategory
+    if (options.subcategory) {
+      results = results.filter((t) => t.subcategory === options.subcategory)
+    }
+
+    // Filter by tags
+    if (options.tags && options.tags.length > 0) {
+      results = results.filter((t) => t.tags && options.tags!.some((tag) => t.tags!.includes(tag)))
+    }
+
+    // Filter by audience
+    if (options.audience) {
+      results = results.filter(
+        (t) => t.audience === options.audience || t.audience === 'both' || !t.audience
+      )
+    }
+
+    // Text search
+    if (options.search) {
+      const search = options.search.toLowerCase()
+      results = results.filter(
+        (t) =>
+          t.name.toLowerCase().includes(search) ||
+          t.description.toLowerCase().includes(search) ||
+          t.id.toLowerCase().includes(search)
+      )
+    }
+
+    // Pagination
+    const offset = options.offset ?? 0
+    const limit = options.limit ?? results.length
+    results = results.slice(offset, offset + limit)
+
+    return results
+  }
+
+  /**
+   * Get tools by category
+   */
+  byCategory(category: ToolCategory): AnyTool[] {
+    return this.query({ category })
+  }
+
+  /**
+   * Execute a tool by ID
+   */
+  async executeTool<TInput = unknown, TOutput = unknown>(
+    id: string,
+    input: TInput
+  ): Promise<TOutput> {
+    const tool = this.tools.get(id)
+    if (!tool) {
+      throw new Error(`Tool "${id}" not found`)
+    }
+    return tool.handler(input) as Promise<TOutput>
+  }
+
+  /**
+   * Convert a Tool to MCP format
+   */
+  toMCP(tool: AnyTool): MCPTool {
+    return {
+      name: tool.id,
+      description: tool.description,
+      inputSchema: {
+        type: 'object',
+        properties: Object.fromEntries(
+          tool.parameters.map((p) => [
+            p.name,
+            typeof p.schema === 'object' && 'type' in p.schema
+              ? { ...p.schema, description: p.description }
+              : { description: p.description },
+          ])
+        ),
+        required: tool.parameters.filter((p) => p.required).map((p) => p.name),
+      },
+    }
+  }
+
+  /**
+   * Convert all registered tools to MCP format
+   */
+  listMCPTools(): MCPTool[] {
+    return this.list().map((id) => this.toMCP(this.get(id)!))
+  }
+
+  /**
+   * Import a tool from MCP format
+   */
+  fromMCP(
+    mcpTool: MCPTool,
+    handler: (input: unknown) => unknown | Promise<unknown>,
+    options?: {
+      category?: ToolCategory
+      subcategory?: ToolSubcategory
+      tags?: string[]
+    }
+  ): AnyTool {
+    const inputSchema = mcpTool.inputSchema
+    const properties = inputSchema.properties || {}
+    const required = inputSchema.required || []
+
+    const parameters = Object.entries(properties).map(([name, schema]) => ({
+      name,
+      description: (schema as { description?: string }).description || `Parameter: ${name}`,
+      schema: schema as { type?: string },
+      required: required.includes(name),
+    }))
+
+    const tool: AnyTool = {
+      id: mcpTool.name,
+      name: mcpTool.name,
+      description: mcpTool.description,
+      category: options?.category || 'integration',
+      ...(options?.subcategory !== undefined && { subcategory: options.subcategory }),
+      ...(options?.tags !== undefined && { tags: options.tags }),
+      parameters,
+      handler,
+    }
+
+    return tool
+  }
+
+  /**
+   * Clear all tools (except built-ins if keepBuiltins is true)
+   */
+  clear(keepBuiltins: boolean = false): void {
+    if (keepBuiltins) {
+      const builtinIds = ['data.json.parse', 'data.csv.parse', 'data.transform']
+      const builtins = builtinIds.map((id) => this.tools.get(id)).filter(Boolean) as AnyTool[]
+      this.tools.clear()
+      builtins.forEach((tool) => this.tools.set(tool.id, tool))
+    } else {
+      this.tools.clear()
+    }
+  }
+}
+
+/**
+ * Main tool service exposed via RPC as WorkerEntrypoint
+ *
+ * Usage:
+ *   const tools = await env.TOOLS.connect()
+ *   tools.register({ id: 'my.tool', ... })
+ *   tools.list()
+ *   const result = await tools.executeTool('data.json.parse', { text: '{}' })
+ */
+export class ToolService extends WorkerEntrypoint {
+  /**
+   * Get a tool service instance - returns an RpcTarget that can be used directly
+   */
+  connect(): ToolServiceCore {
+    return new ToolServiceCore()
+  }
+}
+
+// Export as default for WorkerEntrypoint pattern
+export default ToolService
+
+// Export aliases
+export { ToolService as ToolWorker }

package/src/wrap.ts

@@ -0,0 +1,260 @@
+/**
+ * `wrapTool()` — bridge from a `Tool` definition to an HTTP-shaped handler
+ * gated by `id.org.ai` brokers.
+ *
+ * Mirrors id.org.ai's `wrap()` shape but is specific to digital-tools:
+ *
+ *   1. Calls `AuthBroker.gate(req, need)` to authenticate the caller.
+ *      `need` is derived from the tool's `auth` declaration.
+ *      On rejection, returns the broker's pre-baked `denialResponse(...)`.
+ *
+ *   2. When the tool declares `pricing`, calls
+ *      `PaymentBroker.settle(req, identity, required)`. On rejection,
+ *      returns the broker's pre-baked 402 (`PaymentRejection.response`).
+ *      `required` is translated from our local MDXLD `PaymentRequired`
+ *      shape into id.org.ai's discriminated `PaymentRequired` (`charge`
+ *      intent — `session` intent is not yet supported in 0.3.0 and we
+ *      throw a clear error if a tool requests it).
+ *
+ *   3. Reads `application/json` body, calls `tool.handler(input, ctx)`
+ *      with `ctx.identity = Identity` and (when paid) `ctx.paymentReceipt
+ *      = PaymentReceipt`. The receipt's `responseHeader` (e.g.
+ *      `PAYMENT-RESPONSE` for x402 or `Payment-Receipt` for MPP) is
+ *      stamped onto the success response.
+ *
+ *   4. Tools without `auth` and without `pricing` pass through directly;
+ *      the handler is invoked with `ctx.identity` undefined-cast (we set
+ *      it to a synthetic anonymous ref) so the handler signature stays
+ *      consistent.
+ *
+ * Tests should pass structural fakes for `AuthBroker` and `PaymentBroker`
+ * — both are interfaces in id.org.ai. We intentionally do NOT depend on
+ * `AuthBrokerImpl` / `PaymentBrokerImpl` so this module is portable into
+ * Workers without pulling concrete adapters.
+ *
+ * @packageDocumentation
+ */
+
+import type {
+  AuthBroker,
+  AuthRequirement as IdAuthRequirement,
+  Identity,
+  PaymentBroker,
+  PaymentRequired as IdPaymentRequired,
+  PaymentReceipt,
+  RailQuote,
+} from 'id.org.ai'
+import { denialResponse } from 'id.org.ai'
+import type { AuthRequirement, PaymentRequired, Tool, ToolHandlerContext } from './types.js'
+
+/**
+ * Translate the local MDXLD-shaped `AuthRequirement` (scopes + required
+ * mechanism) into id.org.ai's typed `AuthRequirement`. We always emit
+ * `minLevel: 1` for `oauth`/`apiKey` (a credential must be presented) and
+ * `minLevel: 0` for `none` (anonymous OK). Scopes flow through unchanged.
+ */
+function toIdAuthRequirement(req: AuthRequirement): IdAuthRequirement {
+  const minLevel = req.required === 'none' ? 0 : 1
+  return {
+    minLevel,
+    ...(req.scopes.length > 0 && { scopes: req.scopes }),
+  }
+}
+
+/**
+ * Translate the local MDXLD-shaped `PaymentRequired` (single amount +
+ * accepted protocols) into id.org.ai's discriminated `PaymentRequired`
+ * (`charge` intent with explicit `RailQuote[]`). Each `accepts` entry
+ * fans out into `(method)` quotes — we use `exact` for x402 and `tempo`
+ * for MPP per phase-1 of `PaymentBrokerImpl`.
+ *
+ * Throws on `intent: 'session'` style requests — our local
+ * `PaymentRequired` doesn't currently model session intent, but if a
+ * caller mutates it to add one we surface the limitation early.
+ */
+function toIdPaymentRequired(pricing: PaymentRequired): IdPaymentRequired {
+  // Local `PaymentRequired` doesn't carry an `intent` discriminator;
+  // any future widening that does should fail fast here.
+  if ((pricing as unknown as { intent?: string }).intent === 'session') {
+    throw new Error(
+      "wrapTool: 'session' intent pricing is not yet supported (id.org.ai PaymentBroker.session() is not implemented in 0.3.0). " +
+        "Use 'charge' intent or wait for the next id.org.ai release."
+    )
+  }
+
+  const accepts: RailQuote[] = pricing.accepts.map((protocol): RailQuote => {
+    if (protocol === 'x402') {
+      return {
+        rail: { protocol: 'x402', method: 'exact', asset: pricing.currency },
+        amount: pricing.amount,
+        asset: pricing.currency,
+        payTo: pricing.recipient,
+      }
+    }
+    // protocol === 'mpp'
+    return {
+      rail: { protocol: 'mpp', method: 'tempo', asset: pricing.currency },
+      amount: pricing.amount,
+      asset: pricing.currency,
+      payTo: pricing.recipient,
+    }
+  })
+
+  return {
+    intent: 'charge',
+    accepts,
+  }
+}
+
+/**
+ * Read the request body as JSON. Returns `undefined` for empty bodies
+ * and non-JSON content types so tools with no input still work.
+ */
+async function readJsonBody(req: Request): Promise<unknown> {
+  const ct = req.headers.get('content-type') ?? ''
+  if (!ct.toLowerCase().includes('application/json')) return undefined
+  const text = await req.text()
+  if (!text) return undefined
+  try {
+    return JSON.parse(text)
+  } catch {
+    return undefined
+  }
+}
+
+/**
+ * Build a JSON `Response` for a successful tool invocation. Stamps the
+ * payment receipt's `responseHeader` (e.g. `PAYMENT-RESPONSE` for x402
+ * or `Payment-Receipt` for MPP) when present.
+ */
+function jsonOk(body: unknown, receipt?: PaymentReceipt): Response {
+  const headers: Record<string, string> = { 'content-type': 'application/json' }
+  if (receipt?.responseHeader) {
+    const [name, value] = receipt.responseHeader
+    headers[name] = value
+  }
+  return new Response(JSON.stringify(body), { status: 200, headers })
+}
+
+/**
+ * Build a JSON error `Response`.
+ */
+function jsonError(status: number, code: string, message: string): Response {
+  return new Response(JSON.stringify({ error: code, error_description: message }), {
+    status,
+    headers: { 'content-type': 'application/json' },
+  })
+}
+
+/**
+ * Wrap a Tool with broker-aware HTTP handling.
+ *
+ * @param broker         AuthBroker (id.org.ai). Required when the tool has `auth`.
+ * @param paymentBroker  PaymentBroker (id.org.ai). Required when the tool has `pricing`.
+ * @param tool           The tool definition.
+ * @returns A function `(req: Request) => Promise<Response>` honoring the
+ *          tool's `auth` and `pricing` declarations.
+ *
+ * @example
+ * ```ts
+ * const handler = wrapTool(authBroker, paymentBroker, sendEmailTool)
+ * // Use as a Worker fetch handler:
+ * export default { fetch: handler }
+ * ```
+ *
+ * Tools without `auth` / `pricing` pass through with no broker calls.
+ * In that case the broker arguments may still be provided but are unused.
+ */
+export function wrapTool<TInput, TOutput>(
+  broker: AuthBroker | undefined,
+  paymentBroker: PaymentBroker | undefined,
+  tool: Tool<TInput, TOutput>
+): (req: Request) => Promise<Response> {
+  // Pre-translate auth/pricing once so per-request work stays minimal,
+  // and so a `session`-intent pricing fails at wrap-time rather than at
+  // first request — easier to debug.
+  const idAuth = tool.auth ? toIdAuthRequirement(tool.auth) : null
+  const idPricing = tool.pricing ? toIdPaymentRequired(tool.pricing) : null
+
+  return async function wrappedTool(req: Request): Promise<Response> {
+    let identity: Identity | undefined
+    let receipt: PaymentReceipt | undefined
+
+    // --- Auth gate ----------------------------------------------------
+    if (idAuth) {
+      if (!broker) {
+        return jsonError(
+          500,
+          'configuration_error',
+          `Tool "${tool.id}" declares auth but no AuthBroker was provided to wrapTool()`
+        )
+      }
+      const decision = await broker.gate(req, idAuth)
+      if (!decision.ok) {
+        return denialResponse(decision)
+      }
+      identity = decision.identity
+    }
+
+    // --- Payment settle ----------------------------------------------
+    if (idPricing) {
+      if (!paymentBroker) {
+        return jsonError(
+          500,
+          'configuration_error',
+          `Tool "${tool.id}" declares pricing but no PaymentBroker was provided to wrapTool()`
+        )
+      }
+      // Auth is required for paid tools so we have an Identity to settle
+      // against. If a tool has pricing without auth we fall back to a
+      // synthetic anonymous identity — the broker still accepts it but
+      // rail negotiation will fail unless the request carries proof.
+      const settleIdentity: Identity = identity ?? {
+        id: 'anonymous',
+        type: 'agent',
+        name: 'anonymous',
+        verified: false,
+        level: 0,
+        claimStatus: 'unclaimed',
+      }
+      const outcome = await paymentBroker.settle(req, settleIdentity, idPricing)
+      if (!outcome.ok) {
+        return outcome.response
+      }
+      receipt = outcome
+    }
+
+    // --- Invoke handler -----------------------------------------------
+    let input: TInput
+    try {
+      input = (await readJsonBody(req)) as TInput
+    } catch {
+      return jsonError(400, 'invalid_request', 'Could not parse request body as JSON')
+    }
+
+    const ctx: ToolHandlerContext = {
+      identity: identity ?? 'anonymous',
+      ...(receipt && { paymentReceipt: receipt }),
+    }
+
+    try {
+      const result = await tool.handler(input, ctx)
+      return jsonOk(result, receipt)
+    } catch (err) {
+      const message = err instanceof Error ? err.message : String(err)
+      return jsonError(500, 'execution_error', message)
+    }
+  }
+}
+
+/**
+ * Internal: exported only for tests. Turn a local MDXLD `PaymentRequired`
+ * into id.org.ai's `PaymentRequired`. Throws on session intent.
+ */
+export const __toIdPaymentRequired = toIdPaymentRequired
+
+/**
+ * Internal: exported only for tests. Turn a local `AuthRequirement`
+ * into id.org.ai's `AuthRequirement`.
+ */
+export const __toIdAuthRequirement = toIdAuthRequirement