nebula-ai-core 0.1.0

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.ts

@@ -0,0 +1,152 @@
+import type { ToolCall, ToolDef, ToolResult, ToolSchema } from './types'
+import { zodToJsonSchema } from './zod-schema'
+
+interface EnablementRule {
+  pattern: string
+  regex: RegExp | null
+  enabled: boolean
+}
+
+/**
+ * Symbol-based tool registry. Tools self-register at import time (plugins
+ * contribute by importing their entry module, which triggers the registry
+ * call). Glob-style enable/disable via `config.tools` is applied at `list()`.
+ *
+ * Deferred-tool model (Claude Code-compatible): tools default to alwaysLoad
+ * (eager). A tool with `shouldDefer: true` (and not `alwaysLoad: true`) is
+ * hidden from `schemas()` until `unlock(name)` is called. The brain hydrates
+ * deferred schemas via the `tool.search` meta-tool.
+ */
+export class ToolRegistry {
+  private readonly tools = new Map<string, ToolDef>()
+  private readonly rules: EnablementRule[]
+  private readonly unlocked = new Set<string>()
+
+  constructor(enabled: Record<string, boolean> = {}) {
+    this.rules = Object.entries(enabled).map(([pattern, on]) => ({
+      pattern,
+      regex: pattern.includes('*') ? new RegExp(`^${pattern.replace(/\*/g, '.*')}$`) : null,
+      enabled: on,
+    }))
+  }
+
+  register(def: ToolDef): void {
+    if (this.tools.has(def.name)) {
+      throw new Error(`Tool already registered: ${def.name}`)
+    }
+    this.tools.set(def.name, def as ToolDef<unknown>)
+  }
+
+  find(name: string): ToolDef | undefined {
+    const tool = this.tools.get(name)
+    if (!tool) return undefined
+    if (!this.isEnabled(name)) return undefined
+    return tool
+  }
+
+  /** All registered + enabled tools, regardless of defer state. */
+  list(): ToolDef[] {
+    return [...this.tools.values()].filter(t => this.isEnabled(t.name))
+  }
+
+  /** Tools whose schemas the brain should see this turn. */
+  loadedList(): ToolDef[] {
+    return this.list().filter(t => this.isLoaded(t))
+  }
+
+  /** OpenAI-format schemas for the eager (loaded) set; sent to Mantle Compute. */
+  schemas(): ToolSchema[] {
+    return this.loadedList().map(t => ({
+      type: 'function',
+      function: {
+        name: t.name,
+        description: t.description,
+        parameters: t.parametersOverride ?? zodToJsonSchema(t.schema),
+      },
+    }))
+  }
+
+  /**
+   * Mark a deferred tool as loaded so its schema appears in the next
+   * `schemas()` call. Idempotent.
+   */
+  unlock(name: string): boolean {
+    const tool = this.tools.get(name)
+    if (!tool) return false
+    this.unlocked.add(name)
+    return true
+  }
+
+  /** Whether the brain currently sees the tool's schema. */
+  isLoaded(tool: ToolDef): boolean {
+    if (tool.shouldDefer && tool.alwaysLoad !== true) {
+      return this.unlocked.has(tool.name)
+    }
+    return true
+  }
+
+  /**
+   * Search the registry for tools matching either an exact-name select query
+   * (`select:fs.read,fs.write`) or a free-text keyword query that matches
+   * names, descriptions, and searchHints.
+   */
+  search(query: string, maxResults = 5): ToolDef[] {
+    const trimmed = query.trim()
+    if (trimmed.startsWith('select:')) {
+      const names = trimmed
+        .slice('select:'.length)
+        .split(',')
+        .map(s => s.trim())
+        .filter(Boolean)
+      return names
+        .map(n => this.tools.get(n))
+        .filter((t): t is ToolDef => !!t && this.isEnabled(t.name))
+        .slice(0, maxResults)
+    }
+    const required: string[] = []
+    const keywords: string[] = []
+    for (const part of trimmed.toLowerCase().split(/\s+/).filter(Boolean)) {
+      if (part.startsWith('+')) required.push(part.slice(1))
+      else keywords.push(part)
+    }
+    const scored: { tool: ToolDef; score: number }[] = []
+    for (const tool of this.list()) {
+      const haystack = [tool.name, tool.description, tool.searchHint ?? ''].join(' ').toLowerCase()
+      if (!required.every(r => haystack.includes(r))) continue
+      let score = required.length > 0 ? 1 : 0
+      for (const kw of keywords) {
+        if (haystack.includes(kw)) score++
+      }
+      if (score > 0) scored.push({ tool, score })
+    }
+    return scored
+      .sort((a, b) => b.score - a.score)
+      .slice(0, maxResults)
+      .map(c => c.tool)
+  }
+
+  async dispatch(call: ToolCall): Promise<ToolResult> {
+    const tool = this.find(call.name)
+    if (!tool) return { ok: false, error: `Unknown tool: ${call.name}` }
+    const parsed = tool.schema.safeParse(call.args)
+    if (!parsed.success) {
+      return { ok: false, error: `Invalid args: ${parsed.error.message}` }
+    }
+    try {
+      return await tool.handler(parsed.data)
+    } catch (e) {
+      const msg = e instanceof Error ? e.message : String(e)
+      return { ok: false, error: msg }
+    }
+  }
+
+  private isEnabled(name: string): boolean {
+    // Right-most matching rule wins. No explicit rule = enabled by default.
+    let decision: boolean | null = null
+    for (const rule of this.rules) {
+      const matches = rule.regex ? rule.regex.test(name) : rule.pattern === name
+      if (matches) decision = rule.enabled
+    }
+    return decision ?? true
+  }
+}

package/src/tools/types.ts

@@ -0,0 +1,65 @@
+import type { z } from 'zod'
+
+/** OpenAI-compatible JSON Schema for a function parameter spec. */
+export interface JSONSchema {
+  type: 'object'
+  properties: Record<string, unknown>
+  required?: string[]
+  additionalProperties?: boolean
+  description?: string
+}
+
+/** Shape we hand to the brain when asking it to plan with tools. */
+export interface ToolSchema {
+  type: 'function'
+  function: {
+    name: string
+    description: string
+    parameters: JSONSchema
+  }
+}
+
+export interface ToolCall {
+  id: string
+  name: string
+  args: unknown
+}
+
+export interface ToolDef<TArgs = unknown> {
+  name: string
+  description: string
+  /** zod schema the runtime uses to both validate AND build JSONSchema for the brain. */
+  schema: z.ZodType<TArgs>
+  handler: (args: TArgs) => Promise<ToolResult> | ToolResult
+  /**
+   * When set with `shouldDefer`, overrides the deferral so the tool's schema
+   * still ships every turn. Has no effect when `shouldDefer` is false/unset.
+   */
+  alwaysLoad?: boolean
+  /**
+   * Hide this tool's schema by default; the brain only sees it after
+   * `tool.search` matches it (mirrors Claude Code's shouldDefer). Combine with
+   * `alwaysLoad: true` to force eager loading even though the tool is meant
+   * to be searchable.
+   */
+  shouldDefer?: boolean
+  /**
+   * 3-10 word hint used by `tool.search` keyword matching when this tool is
+   * deferred. Should describe domain ("filesystem read text"), not phrasing.
+   */
+  searchHint?: string
+  /**
+   * Optional JSON Schema override for tools whose param shape isn't expressed
+   * as a top-level `z.object({})` (MCP tools, dynamically-discovered remote
+   * tools). When set, `registry.schemas()` and `tool.search` use this verbatim
+   * instead of running `zodToJsonSchema(schema)`. The `schema.safeParse()`
+   * still gates dispatch.
+   */
+  parametersOverride?: JSONSchema
+}
+
+export interface ToolResult {
+  ok: boolean
+  data?: unknown
+  error?: string
+}

package/src/tools/zod-helpers.ts

@@ -0,0 +1,36 @@
+import { z } from 'zod'
+
+/**
+ * Some Mantle Compute providers (qwen3.6-plus among them) serialize tool-call
+ * boolean args as the strings "true"/"false" instead of JSON booleans. This
+ * accepts either form and falls back to actual booleans + 0/1 numbers.
+ */
+export const coerceBool: z.ZodType<boolean> = z.preprocess(v => {
+  if (typeof v === 'boolean') return v
+  if (typeof v === 'number') return v !== 0
+  if (typeof v === 'string') {
+    const lower = v.trim().toLowerCase()
+    if (lower === 'true' || lower === '1' || lower === 'yes') return true
+    if (lower === 'false' || lower === '0' || lower === 'no') return false
+  }
+  return v
+}, z.boolean()) as unknown as z.ZodType<boolean>
+
+/**
+ * Same shape as coerceBool but for integers. qwen3.6-plus and other Mantle
+ * Compute providers sometimes serialize numeric tool-call args as strings
+ * ("400" instead of 400). zod's z.number() rejects them with
+ * "Expected number, received string". Wrap any numeric tool arg with
+ * `coerceInt` (or `coerceInt.refine(n => n > 0, 'must be positive')`) so the
+ * validation passes regardless of how the brain stringifies it.
+ */
+export const coerceInt: z.ZodType<number> = z.preprocess(v => {
+  if (typeof v === 'number') return v
+  if (typeof v === 'string') {
+    const trimmed = v.trim()
+    if (trimmed === '') return v
+    const n = Number(trimmed)
+    if (Number.isFinite(n) && Math.trunc(n) === n) return n
+  }
+  return v
+}, z.number().int()) as unknown as z.ZodType<number>

package/src/tools/zod-schema.ts

@@ -0,0 +1,99 @@
+import type { z } from 'zod'
+import type { JSONSchema } from './types'
+
+/**
+ * Convert a zod object schema to the minimal JSON Schema dialect Mantle Compute
+ * (and the OpenAI tool-calling format) expects. Handles: string, number,
+ * boolean, enum, optional, array, nested object. Good enough for phase 1-3
+ * MVP tools; revisit when we need deeper schema features.
+ */
+export function zodToJsonSchema(schema: z.ZodType, description?: string): JSONSchema {
+  const shape = unwrapObjectShape(schema)
+  if (!shape) throw new Error('Top-level tool schema must be a z.object({ ... })')
+  return objectShapeToJson(shape, description) as unknown as JSONSchema
+}
+
+type ZodObjectLike = { _def: { typeName: string; shape: () => Record<string, z.ZodType> } }
+
+function unwrapObjectShape(schema: z.ZodType): Record<string, z.ZodType> | null {
+  const s = schema as unknown as ZodObjectLike
+  if (s._def?.typeName === 'ZodObject') return s._def.shape()
+  return null
+}
+
+function unwrapOptional(schema: z.ZodType): { schema: z.ZodType; optional: boolean } {
+  const s = schema as unknown as {
+    _def: { typeName: string; innerType?: z.ZodType; schema?: z.ZodType }
+  }
+  if (s._def?.typeName === 'ZodOptional' || s._def?.typeName === 'ZodDefault') {
+    return { schema: s._def.innerType!, optional: true }
+  }
+  if (s._def?.typeName === 'ZodEffects') {
+    const inner = unwrapOptional(s._def.schema!)
+    return inner
+  }
+  return { schema, optional: false }
+}
+
+function objectShapeToJson(
+  shape: Record<string, z.ZodType>,
+  description?: string,
+): Record<string, unknown> {
+  const properties: Record<string, unknown> = {}
+  const required: string[] = []
+  for (const [key, value] of Object.entries(shape)) {
+    const { schema: prop, optional } = unwrapOptional(value)
+    properties[key] = zodTypeToJson(prop)
+    if (!optional) required.push(key)
+  }
+  return {
+    type: 'object',
+    properties,
+    ...(required.length ? { required } : {}),
+    additionalProperties: false,
+    ...(description ? { description } : {}),
+  }
+}
+
+function zodTypeToJson(schema: z.ZodType): unknown {
+  const s = schema as unknown as {
+    _def: {
+      typeName: string
+      description?: string
+      values?: string[]
+      type?: z.ZodType
+      shape?: () => Record<string, z.ZodType>
+    }
+  }
+  const t = s._def.typeName
+  const description = s._def.description
+
+  switch (t) {
+    case 'ZodString':
+      return { type: 'string', ...(description ? { description } : {}) }
+    case 'ZodNumber':
+      return { type: 'number', ...(description ? { description } : {}) }
+    case 'ZodBoolean':
+      return { type: 'boolean', ...(description ? { description } : {}) }
+    case 'ZodEnum':
+      return {
+        type: 'string',
+        enum: s._def.values,
+        ...(description ? { description } : {}),
+      }
+    case 'ZodArray':
+      return {
+        type: 'array',
+        items: zodTypeToJson(s._def.type!),
+        ...(description ? { description } : {}),
+      }
+    case 'ZodObject':
+      return objectShapeToJson(s._def.shape?.() ?? {}, description)
+    case 'ZodEffects': {
+      const inner = (s._def as unknown as { schema: z.ZodType }).schema
+      return zodTypeToJson(inner)
+    }
+    default:
+      return { description: description ?? 'unspecified' }
+  }
+}

package/src/wallet/drain.ts

@@ -0,0 +1,79 @@
+import { type Address, type Hex, formatEther } from 'viem'
+import { getGasPriceWithFloor, makeViemClients } from '../chain'
+import type { NebulaNetwork } from '../config'
+import { waitForReceiptResilient } from '../identity/receipt'
+
+/**
+ * Sweep an agent EOA's native balance to a target address. Reserves enough
+ * for the sweep tx itself (21000 gas at the live max-fee), so the resulting
+ * balance is "as close to 0 as the gas reserve allows" without underpaying.
+ *
+ * Used by `nebula drain` for fund recovery on a retiring agent. Does not
+ * touch the compute ledger; that's `nebula ledger refund`.
+ */
+
+export interface DrainAgentResult {
+  txHash: Hex
+  amountSent: bigint
+  gasReserved: bigint
+}
+
+export const SWEEP_GAS_LIMIT = 21_000n
+
+/**
+ * Pure helper: given balance + gasPrice + optional override, return the value
+ * to send, the gas reserve, and an error message if the balance can't cover
+ * the sweep. Lifted out of drainAgentEOA so it can be unit-tested without a
+ * live RPC.
+ */
+export function computeSweepAmount(opts: {
+  balance: bigint
+  gasPrice: bigint
+  agentAddress: Address
+  gasReserveOverride?: bigint
+}): { value: bigint; gasReserve: bigint; error?: string } {
+  const gasReserve = opts.gasReserveOverride ?? SWEEP_GAS_LIMIT * opts.gasPrice
+  if (opts.balance <= gasReserve) {
+    return {
+      value: 0n,
+      gasReserve,
+      error: `agent EOA ${opts.agentAddress} has ${formatEther(opts.balance)} Mantle; below gas reserve ${formatEther(gasReserve)} Mantle`,
+    }
+  }
+  return { value: opts.balance - gasReserve, gasReserve }
+}
+
+export async function drainAgentEOA(opts: {
+  network: NebulaNetwork
+  privkeyHex: Hex
+  to: Address
+  /** Override the gas reserve (in wei). Default = 21000 * live max-fee. */
+  gasReserveWei?: bigint
+}): Promise<DrainAgentResult> {
+  const { account, publicClient, walletClient, chain } = makeViemClients({
+    network: opts.network,
+    privkeyHex: opts.privkeyHex,
+  })
+
+  const balance = await publicClient.getBalance({ address: account.address })
+  const gasPrice = await getGasPriceWithFloor(publicClient)
+  const sweep = computeSweepAmount({
+    balance,
+    gasPrice,
+    agentAddress: account.address,
+    gasReserveOverride: opts.gasReserveWei,
+  })
+  if (sweep.error) throw new Error(sweep.error)
+
+  const txHash = await walletClient.sendTransaction({
+    account,
+    chain,
+    to: opts.to,
+    value: sweep.value,
+    gas: SWEEP_GAS_LIMIT,
+    maxFeePerGas: gasPrice,
+    maxPriorityFeePerGas: gasPrice,
+  })
+  await waitForReceiptResilient(publicClient, txHash)
+  return { txHash, amountSent: sweep.value, gasReserved: sweep.gasReserve }
+}

package/src/wallet/eoa.ts

@@ -0,0 +1,51 @@
+import { mkdir, readFile, writeFile } from 'node:fs/promises'
+import { dirname } from 'node:path'
+import { bytesToHex, hexToBytes } from 'viem'
+import { generatePrivateKey, privateKeyToAccount } from 'viem/accounts'
+import { type EncryptedKeystore, decryptKey, encryptKey } from './keystore'
+
+/**
+ * Library-agnostic agent wallet material. Callers instantiate the right
+ * chain library (viem `privateKeyToAccount`, ethers `new Wallet(hex)`, etc.)
+ * at point of use.
+ */
+export interface AgentWalletMaterial {
+  /** 0x-prefixed hex private key. */
+  privkeyHex: `0x${string}`
+  /** EIP-55 address derived from the key. */
+  address: `0x${string}`
+}
+
+export function generateAgentWallet(): AgentWalletMaterial {
+  const privkeyHex = generatePrivateKey()
+  const account = privateKeyToAccount(privkeyHex)
+  return { privkeyHex, address: account.address }
+}
+
+export async function saveKeystore(
+  path: string,
+  privkeyHex: string,
+  passphrase: string,
+): Promise<void> {
+  const privkey = hexToBytes(privkeyHex as `0x${string}`)
+  const encrypted = encryptKey(privkey, passphrase)
+  await mkdir(dirname(path), { recursive: true })
+  await writeFile(path, JSON.stringify(encrypted, null, 2), 'utf8')
+}
+
+export async function loadKeystore(path: string, passphrase: string): Promise<AgentWalletMaterial> {
+  let raw: string
+  try {
+    raw = await readFile(path, 'utf8')
+  } catch (e) {
+    if ((e as NodeJS.ErrnoException).code === 'ENOENT') {
+      throw new Error(`Keystore not found at ${path}`)
+    }
+    throw e
+  }
+  const encrypted = JSON.parse(raw) as EncryptedKeystore
+  const privkey = decryptKey(encrypted, passphrase)
+  const privkeyHex = bytesToHex(privkey)
+  const account = privateKeyToAccount(privkeyHex)
+  return { privkeyHex, address: account.address }
+}