lyra-core 0.1.0

package/src/tools/escalation.test.ts

@@ -0,0 +1,348 @@
+import { expect, test } from 'bun:test'
+import {
+  type EscalationDeps,
+  type FetchEscalation,
+  detectFetchEscalation,
+  mergeEscalationResult,
+  runEscalation,
+} from './escalation'
+import type { ToolCall, ToolResult } from './types'
+
+const fetchCall = (id: string, url: string): ToolCall => ({
+  id,
+  name: 'web.fetch',
+  args: { url },
+})
+
+const blockedResult = (final_url: string, reason: string): ToolResult => ({
+  ok: true,
+  data: {
+    status: 200,
+    content_type: 'text/html',
+    body: '# unusual traffic from your computer network\n\nplease show you are not a robot',
+    truncated: false,
+    final_url,
+    blocked: true,
+    block_reason: reason,
+  },
+})
+
+const escalationFor = (call: ToolCall, reason: string, url: string): FetchEscalation => ({
+  needed: true,
+  escalatedCall: { id: `auto-escalate-${call.id}`, name: 'browser.navigate', args: { url } },
+  reason,
+  url,
+})
+
+test('detect: web.fetch + blocked + final_url returns needed with escalated call', () => {
+  const call = fetchCall('c1', 'https://www.google.com/search?q=test')
+  const result = blockedResult('https://www.google.com/search?q=test', 'google-bot-block')
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.escalatedCall?.id).toBe('auto-escalate-c1')
+  expect(out.escalatedCall?.name).toBe('browser.navigate')
+  expect(out.escalatedCall?.args).toEqual({ url: 'https://www.google.com/search?q=test' })
+  expect(out.reason).toBe('google-bot-block')
+  expect(out.url).toBe('https://www.google.com/search?q=test')
+})
+
+test('detect: blocked + no final_url falls back to call.args.url', () => {
+  const call = fetchCall('c2', 'https://example.com/blocked')
+  const result: ToolResult = {
+    ok: true,
+    data: { blocked: true, block_reason: 'cloudflare', body: 'Just a moment...' },
+  }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.escalatedCall?.args).toEqual({ url: 'https://example.com/blocked' })
+})
+
+test('detect: blocked + neither final_url nor args.url returns not needed', () => {
+  const call: ToolCall = { id: 'c3', name: 'web.fetch', args: {} }
+  const result: ToolResult = { ok: true, data: { blocked: true, block_reason: 'captcha' } }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: v0.21.3 — timeout failure DOES escalate (transient)', () => {
+  const call = fetchCall('c4', 'https://arxiv.org/search/?query=test')
+  const result: ToolResult = { ok: false, error: 'timeout after 15000ms' }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('timeout')
+  expect(out.escalatedCall?.args).toEqual({ url: 'https://arxiv.org/search/?query=test' })
+})
+
+test('detect: v0.21.3 — http 503 failure DOES escalate', () => {
+  const call = fetchCall('c4b', 'https://flaky.example.com')
+  const result: ToolResult = { ok: false, error: 'http 503' }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('http-503')
+})
+
+test('detect: v0.21.3 — http 429 failure DOES escalate', () => {
+  const call = fetchCall('c4c', 'https://api.example.com')
+  const result: ToolResult = { ok: false, error: 'http 429' }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('http-429')
+})
+
+test('detect: v0.21.3 — DNS failure DOES escalate', () => {
+  const call = fetchCall('c4d', 'https://dns-broken.example')
+  const result: ToolResult = {
+    ok: false,
+    error: 'getaddrinfo ENOTFOUND dns-broken.example',
+  }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('dns')
+})
+
+test('detect: v0.21.3 — connection refused DOES escalate', () => {
+  const call = fetchCall('c4e', 'https://refused.example.com')
+  const result: ToolResult = { ok: false, error: 'connect ECONNREFUSED' }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('connection')
+})
+
+test('detect: v0.21.3 — generic fetch failure DOES escalate', () => {
+  const call = fetchCall('c4f', 'https://example.com')
+  const result: ToolResult = { ok: false, error: 'fetch failed' }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('fetch-error')
+})
+
+test('detect: v0.21.3 — invalid URL is permanent, does NOT escalate', () => {
+  const call: ToolCall = { id: 'c4g', name: 'web.fetch', args: { url: 'not a url' } }
+  const result: ToolResult = { ok: false, error: 'invalid URL' }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: v0.21.3 — unsupported protocol is permanent, does NOT escalate', () => {
+  const call = fetchCall('c4h', 'file:///etc/passwd')
+  const result: ToolResult = { ok: false, error: 'unsupported protocol: file:' }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: v0.21.3 — host blocked (private IP) is permanent, does NOT escalate', () => {
+  const call = fetchCall('c4i', 'http://169.254.169.254/latest/meta-data')
+  const result: ToolResult = {
+    ok: false,
+    error: 'host blocked (private/loopback/metadata): 169.254.169.254',
+  }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: web.fetch ok with no blocked field returns not needed', () => {
+  const call = fetchCall('c5', 'https://news.ycombinator.com')
+  const result: ToolResult = {
+    ok: true,
+    data: { status: 200, body: '# Hacker News', final_url: 'https://news.ycombinator.com' },
+  }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: non-web.fetch tool with blocked:true returns not needed', () => {
+  const call: ToolCall = { id: 'c6', name: 'shell.run', args: { command: 'ls' } }
+  const result: ToolResult = { ok: true, data: { blocked: true, block_reason: 'spurious' } }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: web.fetch with missing data field + ok=true returns not needed', () => {
+  const call = fetchCall('c7', 'https://x.com')
+  const result: ToolResult = { ok: true }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: web.fetch missing block_reason still escalates with reason "unknown"', () => {
+  const call = fetchCall('c8', 'https://x.com')
+  const result: ToolResult = {
+    ok: true,
+    data: { blocked: true, final_url: 'https://x.com' },
+  }
+  const out = detectFetchEscalation(call, result)
+  expect(out.needed).toBe(true)
+  expect(out.reason).toBe('unknown')
+})
+
+test('detect: tail-recursion guard refuses to escalate already-escalated calls', () => {
+  const call: ToolCall = {
+    id: 'auto-escalate-original',
+    name: 'web.fetch',
+    args: { url: 'https://x.com' },
+  }
+  const result = blockedResult('https://x.com', 'cloudflare')
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('detect: v0.21.3 — failure with no URL anywhere does NOT escalate', () => {
+  const call: ToolCall = { id: 'c9', name: 'web.fetch', args: {} }
+  const result: ToolResult = { ok: false, error: 'timeout after 15000ms' }
+  expect(detectFetchEscalation(call, result).needed).toBe(false)
+})
+
+test('merge: ok escalation produces ok=true result with both blobs', () => {
+  const original = blockedResult('https://www.google.com', 'google-bot-block')
+  const escalated: ToolResult = {
+    ok: true,
+    data: { currentUrl: 'https://www.google.com', title: 'Google' },
+  }
+  const escalation = escalationFor(
+    fetchCall('c9', 'https://www.google.com'),
+    'google-bot-block',
+    'https://www.google.com',
+  )
+  const merged = mergeEscalationResult(original, escalated, escalation)
+  expect(merged.ok).toBe(true)
+  const data = merged.data as Record<string, unknown>
+  expect(data.blocked).toBe(true)
+  expect(data.body).toContain('unusual traffic')
+  const ae = data.auto_escalation as Record<string, unknown>
+  expect(ae.triggered).toBe(true)
+  expect(ae.from).toBe('web.fetch')
+  expect(ae.to).toBe('browser.navigate')
+  expect(ae.reason).toBe('google-bot-block')
+  expect(ae.url).toBe('https://www.google.com')
+  const aeResult = ae.result as ToolResult
+  expect(aeResult.ok).toBe(true)
+  expect((aeResult.data as Record<string, unknown>).title).toBe('Google')
+})
+
+test('merge: v0.21.3 — timeout escalation preserves original error', () => {
+  const original: ToolResult = { ok: false, error: 'timeout after 15000ms' }
+  const escalated: ToolResult = { ok: true, data: { currentUrl: 'https://arxiv.org/search' } }
+  const escalation = escalationFor(
+    fetchCall('cT', 'https://arxiv.org/search'),
+    'timeout',
+    'https://arxiv.org/search',
+  )
+  const merged = mergeEscalationResult(original, escalated, escalation)
+  expect(merged.ok).toBe(true)
+  const data = merged.data as Record<string, unknown>
+  const ae = data.auto_escalation as Record<string, unknown>
+  expect(ae.reason).toBe('timeout')
+  expect(ae.original_error).toBe('timeout after 15000ms')
+})
+
+test('merge: failed escalation sets ok=false with descriptive error, preserves original data', () => {
+  const original = blockedResult('https://www.google.com', 'google-bot-block')
+  const escalated: ToolResult = {
+    ok: false,
+    error: 'Unknown tool: browser.navigate',
+  }
+  const escalation = escalationFor(
+    fetchCall('c10', 'https://www.google.com'),
+    'google-bot-block',
+    'https://www.google.com',
+  )
+  const merged = mergeEscalationResult(original, escalated, escalation)
+  expect(merged.ok).toBe(false)
+  expect(merged.error).toContain('auto-escalation failed')
+  expect(merged.error).toContain('Unknown tool: browser.navigate')
+  const data = merged.data as Record<string, unknown>
+  expect(data.blocked).toBe(true)
+  expect(data.body).toContain('unusual traffic')
+  const ae = data.auto_escalation as Record<string, unknown>
+  expect((ae.result as ToolResult).ok).toBe(false)
+})
+
+test('merge: failed escalation with no error field still produces fallback message', () => {
+  const original = blockedResult('https://x.com', 'cloudflare')
+  const escalated: ToolResult = { ok: false }
+  const escalation = escalationFor(fetchCall('c11', 'https://x.com'), 'cloudflare', 'https://x.com')
+  const merged = mergeEscalationResult(original, escalated, escalation)
+  expect(merged.error).toBe('auto-escalation failed: unknown')
+})
+
+test('merge: missing original.data handled defensively (no throw, escalation block still set)', () => {
+  const original: ToolResult = { ok: true }
+  const escalated: ToolResult = { ok: true, data: { currentUrl: 'https://x.com' } }
+  const escalation = escalationFor(fetchCall('c12', 'https://x.com'), 'rate-limit', 'https://x.com')
+  const merged = mergeEscalationResult(original, escalated, escalation)
+  expect(merged.ok).toBe(true)
+  const data = merged.data as Record<string, unknown>
+  expect(data.auto_escalation).toBeDefined()
+  const ae = data.auto_escalation as Record<string, unknown>
+  expect(ae.reason).toBe('rate-limit')
+})
+
+interface CallLog {
+  pre: ToolCall[]
+  post: Array<{ call: ToolCall; result: ToolResult }>
+  dispatch: ToolCall[]
+  activity: Array<{ call: ToolCall; result: ToolResult }>
+  starts: ToolCall[]
+  ends: Array<{ call: ToolCall; result: ToolResult; durationMs: number }>
+}
+
+const captureDeps = (
+  log: CallLog,
+  dispatchResult: ToolResult,
+  preShort?: ToolResult,
+): EscalationDeps => ({
+  runPreCall: async call => {
+    log.pre.push(call)
+    return preShort ? { short: preShort } : {}
+  },
+  runPostCall: async (call, result) => {
+    log.post.push({ call, result })
+  },
+  dispatch: async call => {
+    log.dispatch.push(call)
+    return dispatchResult
+  },
+  appendActivity: async (call, result) => {
+    log.activity.push({ call, result })
+  },
+  onStart: call => {
+    log.starts.push(call)
+  },
+  onEnd: (call, result, durationMs) => {
+    log.ends.push({ call, result, durationMs })
+  },
+})
+
+test('runEscalation: passes through original when escalation not needed', async () => {
+  const log: CallLog = { pre: [], post: [], dispatch: [], activity: [], starts: [], ends: [] }
+  const original: ToolResult = { ok: true, data: { body: 'fine' } }
+  const out = await runEscalation({ needed: false }, original, captureDeps(log, { ok: true }))
+  expect(out).toBe(original)
+  expect(log.starts.length).toBe(0)
+  expect(log.dispatch.length).toBe(0)
+})
+
+test('runEscalation: ok escalation runs full pipeline + emits start/end + merges', async () => {
+  const log: CallLog = { pre: [], post: [], dispatch: [], activity: [], starts: [], ends: [] }
+  const original = blockedResult('https://x.com', 'cloudflare')
+  const escalation = escalationFor(fetchCall('c13', 'https://x.com'), 'cloudflare', 'https://x.com')
+  const escalated: ToolResult = { ok: true, data: { currentUrl: 'https://x.com' } }
+  const merged = await runEscalation(escalation, original, captureDeps(log, escalated))
+  expect(log.starts.length).toBe(1)
+  expect(log.starts[0]?.name).toBe('browser.navigate')
+  expect(log.pre.length).toBe(1)
+  expect(log.dispatch.length).toBe(1)
+  expect(log.post.length).toBe(1)
+  expect(log.activity.length).toBe(1)
+  expect(log.ends.length).toBe(1)
+  expect(typeof log.ends[0]?.durationMs).toBe('number')
+  expect(merged.ok).toBe(true)
+  const ae = (merged.data as Record<string, unknown>).auto_escalation as Record<string, unknown>
+  expect(ae.triggered).toBe(true)
+})
+
+test('runEscalation: pre-hook short-circuit skips dispatch + post-hook', async () => {
+  const log: CallLog = { pre: [], post: [], dispatch: [], activity: [], starts: [], ends: [] }
+  const original = blockedResult('https://x.com', 'cloudflare')
+  const escalation = escalationFor(fetchCall('c14', 'https://x.com'), 'cloudflare', 'https://x.com')
+  const denied: ToolResult = { ok: false, error: 'denied by approval' }
+  const merged = await runEscalation(escalation, original, captureDeps(log, { ok: true }, denied))
+  expect(log.dispatch.length).toBe(0)
+  expect(log.post.length).toBe(0)
+  expect(log.activity.length).toBe(1)
+  expect(log.activity[0]?.result.ok).toBe(false)
+  expect(merged.ok).toBe(false)
+  expect(merged.error).toContain('auto-escalation failed')
+})

package/src/tools/escalation.ts

@@ -0,0 +1,200 @@
+import type { ToolCall, ToolResult } from './types'
+
+/**
+ * v0.21.2/v0.21.3: web.fetch can fail in many ways. Some failures are transient
+ * (Cloudflare interstitial, Google bot block, captcha, rate-limit, HTTP 5xx,
+ * timeout, network error) and the browser primitive often recovers because it
+ * runs a real headless Chromium that handles cookies, JS challenges, and uses
+ * different DNS / network stack. Other failures are permanent (invalid URL,
+ * unsupported protocol, private/loopback host) and re-trying via browser would
+ * not help.
+ *
+ * The dispatcher (chat.tsx onToolCall + build-runtime.ts onToolCall) calls
+ * `runEscalation`. Both wrappers share orchestration (pre/post hooks, dispatch,
+ * activity append, merge) here; only the UX side effects (state.pushRow vs
+ * events.publish) are passed as callbacks. Brain sees one merged tool message
+ * regardless of how many wrapper-level retries happened.
+ *
+ * Live drives showed Qwen3.6 ignores conditional escalation rules in long
+ * contexts: pre-fix, the brain ended turn with toolCalls=0 on a blocked fetch
+ * and replied "(no reply)" / memory disclaimer. v0.21.2 escalated on the
+ * structured `blocked:true` signal. v0.21.3 extends to ANY transient web.fetch
+ * failure ("ensure browser routing is active so agent proactively go with
+ * browser every time it gets any hiccup or issues").
+ */
+
+const ESCALATED_ID_PREFIX = 'auto-escalate-'
+
+/**
+ * Errors web.fetch returns for input it must refuse outright. Browser would
+ * not fix them and we don't want to drive it to file:// / private IPs / etc.
+ * Match-prefix on the error string.
+ */
+const PERMANENT_FAILURE_PATTERNS: readonly RegExp[] = [
+  /^invalid URL$/i,
+  /^unsupported protocol/i,
+  /^host blocked/i,
+]
+
+export interface FetchEscalation {
+  needed: boolean
+  escalatedCall?: ToolCall
+  reason?: string
+  url?: string
+}
+
+/**
+ * Decide whether a web.fetch result warrants an automatic browser.navigate
+ * retry. Fires on:
+ *   - bot-block / captcha / rate-limit interstitial (data.blocked === true)
+ *   - any web.fetch failure (result.ok === false) UNLESS the error is one of
+ *     the permanent-failure patterns above (invalid URL, unsupported
+ *     protocol, host blocked for security)
+ *
+ * URL preference order: `result.data.final_url` (post-redirect canonical URL),
+ * then `call.args.url` (original request). If neither is present we cannot
+ * synthesize a browser.navigate call, so escalation is skipped. Recursion
+ * guard refuses to re-escalate calls that are themselves synthetic
+ * escalations.
+ */
+export function detectFetchEscalation(call: ToolCall, result: ToolResult): FetchEscalation {
+  if (call.name !== 'web.fetch') return { needed: false }
+  if (typeof call.id === 'string' && call.id.startsWith(ESCALATED_ID_PREFIX))
+    return { needed: false }
+
+  const data = result.data as Record<string, unknown> | undefined
+  const finalUrl = data && typeof data.final_url === 'string' ? data.final_url : null
+  const argUrl = extractUrlFromCallArgs(call)
+  const url = finalUrl && finalUrl.length > 0 ? finalUrl : argUrl
+  if (!url) return { needed: false }
+
+  if (result.ok && data?.blocked === true) {
+    const reason = typeof data.block_reason === 'string' ? data.block_reason : 'unknown'
+    return synthesize(call, url, reason)
+  }
+  if (!result.ok) {
+    const error = typeof result.error === 'string' ? result.error : 'unknown'
+    if (PERMANENT_FAILURE_PATTERNS.some(re => re.test(error))) return { needed: false }
+    return synthesize(call, url, classifyError(error))
+  }
+  return { needed: false }
+}
+
+function synthesize(call: ToolCall, url: string, reason: string): FetchEscalation {
+  return {
+    needed: true,
+    escalatedCall: {
+      id: `${ESCALATED_ID_PREFIX}${call.id}`,
+      name: 'browser.navigate',
+      args: { url },
+    },
+    reason,
+    url,
+  }
+}
+
+function extractUrlFromCallArgs(call: ToolCall): string | null {
+  if (!call.args || typeof call.args !== 'object') return null
+  const args = call.args as Record<string, unknown>
+  return typeof args.url === 'string' && args.url.length > 0 ? args.url : null
+}
+
+/**
+ * Classify a non-block web.fetch error into a short symbolic reason. Keeps
+ * the merged auto_escalation.reason field readable for the brain instead of
+ * pasting raw stack traces.
+ */
+function classifyError(error: string): string {
+  if (/^timeout/i.test(error)) return 'timeout'
+  const httpMatch = error.match(/^http\s+(\d{3})/i)
+  if (httpMatch) return `http-${httpMatch[1]}`
+  if (/dns|enotfound|getaddrinfo/i.test(error)) return 'dns'
+  if (/connection|econnrefused|econnreset|socket/i.test(error)) return 'connection'
+  if (/aborted|abortError/i.test(error)) return 'aborted'
+  return 'fetch-error'
+}
+
+/**
+ * Merge a failed/blocked web.fetch result with an escalated browser.navigate
+ * result into the single tool message the brain receives. Original `data.body`
+ * (the bot-block markdown, if any) is preserved alongside `data.auto_escalation`
+ * so the brain has full context to call `browser.snapshot` next.
+ *
+ * `mergedResult.ok` reflects the ESCALATED call's success: if browser.navigate
+ * also failed (no agent-browser binary, headless Chrome flake, etc.), the
+ * brain sees ok:false and can degrade gracefully.
+ */
+export function mergeEscalationResult(
+  original: ToolResult,
+  escalated: ToolResult,
+  escalation: FetchEscalation,
+): ToolResult {
+  const originalData =
+    original.data && typeof original.data === 'object'
+      ? (original.data as Record<string, unknown>)
+      : {}
+  const merged: ToolResult = {
+    ok: escalated.ok,
+    data: {
+      ...originalData,
+      auto_escalation: {
+        triggered: true,
+        from: 'web.fetch',
+        to: 'browser.navigate',
+        reason: escalation.reason ?? 'unknown',
+        url: escalation.url ?? '',
+        original_error: original.error,
+        result: escalated,
+      },
+    },
+  }
+  if (!escalated.ok) {
+    merged.error = `auto-escalation failed: ${escalated.error ?? 'unknown'}`
+  }
+  return merged
+}
+
+export interface EscalationDeps {
+  /** Run pre-tool hooks (permission, sandbox bridge). Mirrors HookBus shape. */
+  runPreCall: (call: ToolCall) => Promise<{ short?: ToolResult; call?: ToolCall }>
+  /** Run post-tool hooks (audit, telemetry). */
+  runPostCall: (call: ToolCall, result: ToolResult) => Promise<void>
+  /** Dispatch the (possibly hook-replaced) call to the tool registry. */
+  dispatch: (call: ToolCall) => Promise<ToolResult>
+  /** Append a `kind:'tool-call'` activity entry tagged `autoEscalated:true`. */
+  appendActivity: (call: ToolCall, result: ToolResult) => Promise<void>
+  /** UX sink: notify the operator a follow-up call is starting. */
+  onStart: (call: ToolCall) => void
+  /** UX sink: notify the operator the follow-up call finished. */
+  onEnd: (call: ToolCall, result: ToolResult, durationMs: number) => void
+}
+
+/**
+ * Orchestrate the escalated browser.navigate dispatch on behalf of the brain
+ * wrapper. Owns: UX start → pre-hook → dispatch (or short-circuit) → post-hook →
+ * activity append → UX end → merge. Both `chat.tsx` and `build-runtime.ts` call
+ * this so any future change (extra hook, retry policy, telemetry) lands in one
+ * place instead of drifting between TUI and gateway paths.
+ */
+export async function runEscalation(
+  escalation: FetchEscalation,
+  originalResult: ToolResult,
+  deps: EscalationDeps,
+): Promise<ToolResult> {
+  if (!escalation.needed || !escalation.escalatedCall) return originalResult
+  const synthCall = escalation.escalatedCall
+  const startedAt = Date.now()
+  deps.onStart(synthCall)
+  const pre = await deps.runPreCall(synthCall)
+  const effective = pre.call ?? synthCall
+  let result: ToolResult
+  if (pre.short) {
+    result = pre.short
+  } else {
+    result = await deps.dispatch(effective)
+    await deps.runPostCall(effective, result)
+  }
+  await deps.appendActivity(effective, result)
+  deps.onEnd(effective, result, Date.now() - startedAt)
+  return mergeEscalationResult(originalResult, result, escalation)
+}

package/src/tools/index.ts

@@ -0,0 +1,11 @@
+export type { ToolCall, ToolDef, ToolResult, ToolSchema, JSONSchema } from './types'
+export { ToolRegistry } from './registry'
+export { zodToJsonSchema } from './zod-schema'
+export { coerceBool, coerceInt } from './zod-helpers'
+export {
+  detectFetchEscalation,
+  mergeEscalationResult,
+  runEscalation,
+  type EscalationDeps,
+  type FetchEscalation,
+} from './escalation'

package/src/tools/registry.test.ts

@@ -0,0 +1,70 @@
+import { expect, test } from 'bun:test'
+import { z } from 'zod'
+import { ToolRegistry } from './registry'
+
+test('register + find + dispatch a tool', async () => {
+  const reg = new ToolRegistry()
+  let captured: unknown = null
+  reg.register({
+    name: 'echo',
+    description: 'Echo back a message',
+    schema: z.object({ message: z.string() }),
+    handler: async args => {
+      captured = args
+      return { ok: true, data: args }
+    },
+  })
+
+  const r = await reg.dispatch({ id: 'c1', name: 'echo', args: { message: 'hi' } })
+  expect(r.ok).toBe(true)
+  expect(captured).toEqual({ message: 'hi' })
+})
+
+test('dispatch fails on unknown tool', async () => {
+  const reg = new ToolRegistry()
+  const r = await reg.dispatch({ id: 'c1', name: 'nope', args: {} })
+  expect(r.ok).toBe(false)
+})
+
+test('dispatch fails on schema-invalid args', async () => {
+  const reg = new ToolRegistry()
+  reg.register({
+    name: 'echo',
+    description: 'Echo',
+    schema: z.object({ message: z.string() }),
+    handler: async () => ({ ok: true }),
+  })
+  const r = await reg.dispatch({ id: 'c1', name: 'echo', args: { message: 123 } })
+  expect(r.ok).toBe(false)
+  expect(r.error).toContain('Invalid args')
+})
+
+test('glob disable prevents dispatch', async () => {
+  const reg = new ToolRegistry({ 'defi.*': false })
+  reg.register({
+    name: 'defi.swap',
+    description: 'Swap',
+    schema: z.object({}),
+    handler: async () => ({ ok: true }),
+  })
+  expect(reg.find('defi.swap')).toBeUndefined()
+  const r = await reg.dispatch({ id: 'c1', name: 'defi.swap', args: {} })
+  expect(r.ok).toBe(false)
+  expect(r.error).toContain('Unknown tool')
+})
+
+test('schemas() emits OpenAI-compat shape', () => {
+  const reg = new ToolRegistry()
+  reg.register({
+    name: 'memory.save',
+    description: 'Save memory',
+    schema: z.object({ name: z.string(), type: z.enum(['feedback', 'user']) }),
+    handler: async () => ({ ok: true }),
+  })
+  const schemas = reg.schemas()
+  expect(schemas[0]!.type).toBe('function')
+  expect(schemas[0]!.function.name).toBe('memory.save')
+  const props = schemas[0]!.function.parameters.properties as Record<string, { type: string }>
+  expect(props.name).toEqual({ type: 'string' })
+  expect(schemas[0]!.function.parameters.required).toEqual(['name', 'type'])
+})