feat(example): wire EIP-712 signing flow + tool-use loop for Day 5 milestone

Round 4.5 white-spot work from the bundle plan. Closes the 10 critical gaps
that would have blocked the Loom demo recording:

- /api/agent: full Anthropic tool-use loop. Parses tool_use content blocks,
  validates args via zod, calls buildPendleEnvelope, signs the EIP-712 digest
  via signEnvelope, attaches the signature into outer executeEnvelope call
  data, and returns both reply text + signed envelope.
- src/agent/signing.ts: signEnvelope() helper using viem signTypedData with
  the canonical AgentPolicyGate domain (name=AgentPolicyGate, version=1,
  chainId, verifyingContract) + ExecuteEnvelope type.
- envelope-builder.ts: canonical envelopeHash now includes per-call nonce +
  encodeAbiParameters for replay-resistance across Loom retakes. Added
  attachAgentSignature() to re-encode outer call data after signing.
- /api/decode: merges decoder-data/agent-policy-gate.json + mock-pendle-router.json
  with BUILTIN_REGISTRY. resolveDescriptors() patches placeholder addresses
  with real ones from contracts/deployed.json once deploy lands.
- src/agent/system-prompt.ts: known testnet token addresses (USDC, WETH, PT
  placeholders) + decimal-to-raw conversion rules.
- env.ts + .env.example: AGENT_SIGNER_PRIVATE_KEY for server-side signing.
- deployed.ts + deployed.json: getMockPendleRouterAddress() helper +
  PENDING placeholder entry mirroring the AgentPolicyGate pattern.
- PendleAgentChat.tsx: renders EnvelopePreview after tool-use response,
  auto-fetches decoded inner call via /api/decode, passes connected wagmi
  account as receiverAddress.

Blocked on Mike: forge deploy of AgentPolicyGate (Arb Sepolia + Robinhood
testnet) + MockPendleRouter (Arb Sepolia, contract not yet written) and
the cast send setAllowedRecipient follow-up so executeEnvelope passes the
allow-list check.

Author: mike-diamond

examples/arbitrum-london/.env.example

@@ -15,6 +15,9 @@ ROBINHOOD_TESTNET_RPC_URL=https://testnet.rpc.chain.robinhood.com
 # -- Deployer + agent signer (REQUIRED for forge scripts in contracts/) --
 DEPLOYER_PRIVATE_KEY=0x...
 AGENT_SIGNER_ADDRESS=0x...
+# Server-side EIP-712 signing key for /api/agent envelope binding.
+# Pair must match AGENT_SIGNER_ADDRESS above. TESTNET ONLY - rotate before mainnet.
+AGENT_SIGNER_PRIVATE_KEY=0x...
 
 # -- x402 facilitator (REQUIRED for /api/x402/* - lands Phase 2) --
 X402_FACILITATOR_PRIVATE_KEY=0x...

examples/arbitrum-london/app/api/agent/route.ts

@@ -1,29 +1,77 @@
 import { NextResponse, type NextRequest } from 'next/server'
+import type { Hex } from 'viem'
 
+import { ARBITRUM_SEPOLIA_CHAIN_ID } from '@/src/chains'
+import {
+  attachAgentSignature,
+  buildPendleEnvelope,
+  type DemoEnvelope,
+} from '@/src/agent/envelope-builder'
+import { signEnvelope } from '@/src/agent/signing'
+import {
+  PENDLE_SYSTEM_PROMPT,
+  RWA_SYSTEM_PROMPT,
+} from '@/src/agent/system-prompt'
+import {
+  PENDLE_TOOL_DEFINITION,
+  RWA_TOOL_DEFINITION,
+  preparePendleYieldSwapArgs,
+} from '@/src/agent/tools'
+import { getAgentPolicyGateAddress } from '@/src/config/deployed'
 import { getEnv } from '@/src/config/env'
 
 
 export const runtime = 'nodejs'
 
 /**
- * Phase 1 Day 3 milestone: minimum-viable Claude SDK echo.
+ * Phase 1 Day 5 milestone: tool-use loop + EIP-712 envelope signing.
  *
  * V1 contract:
- *   POST /api/agent { messages: [{ role, content }] }
- *   -> { reply: string, envelope?: DemoEnvelope }
+ *   POST /api/agent { messages, scenario?, receiverAddress? }
+ *   -> { reply, envelope?, scenario, milestone }
  *
- * For the Day 3 milestone we only echo the user message back through
- * Claude with no tools attached - confirms Node runtime + env loading +
- * Anthropic SDK plumbing works end to end. Tool calls + envelope return
- * land in Day 4 (Pendle) and Day 10 (RWA).
+ * Pendle flow:
+ *   1. Claude reads PENDLE_SYSTEM_PROMPT + receives PENDLE_TOOL_DEFINITION.
+ *   2. If args are clear: Claude calls prepare_pendle_yield_swap.
+ *   3. We validate via zod, buildPendleEnvelope, sign EIP-712 via signEnvelope,
+ *      attach signature, return both the assistant's text reply (if any) and
+ *      the signed envelope.
+ *   4. If Claude asks for clarification (text only): return reply, no envelope.
+ *
+ * RWA flow lands Phase 2 Day 10.
  *
  * The SDK is dynamically imported inside the handler so the route module
- * stays importable even when ANTHROPIC_API_KEY is unset (better DX for
- * the first contributor cloning the repo).
+ * stays loadable even when ANTHROPIC_API_KEY is unset (better DX for the
+ * first contributor cloning the repo).
  */
+const DEFAULT_RECEIVER = '0x000000000000000000000000000000000000dEaD' as const
+
 type AgentRequestBody = {
   messages: Array<{ role: 'user' | 'assistant', content: string }>,
   scenario?: 'pendle' | 'rwa',
+  receiverAddress?: `0x${string}`,
+}
+
+type ToolUseBlock = {
+  type: 'tool_use',
+  id: string,
+  name: string,
+  input: Record<string, unknown>,
+}
+
+type TextBlock = {
+  type: 'text',
+  text: string,
+}
+
+type ResponseContentBlock = ToolUseBlock | TextBlock | { type: string }
+
+const checkIsToolUseBlock = (block: ResponseContentBlock): block is ToolUseBlock => {
+  return block.type === 'tool_use'
+}
+
+const checkIsTextBlock = (block: ResponseContentBlock): block is TextBlock => {
+  return block.type === 'text'
 }
 
 export const POST = async (request: NextRequest) => {
@@ -38,6 +86,9 @@ export const POST = async (request: NextRequest) => {
     return NextResponse.json({ error: 'messages must be a non-empty array' }, { status: 400 })
   }
 
+  const scenario = body.scenario ?? 'pendle'
+  const receiverAddress = body.receiverAddress ?? DEFAULT_RECEIVER
+
   let env
   try {
     env = getEnv()
@@ -52,16 +103,13 @@ export const POST = async (request: NextRequest) => {
     return NextResponse.json(
       {
         error: 'ANTHROPIC_API_KEY not set',
-        hint: 'Add ANTHROPIC_API_KEY to .env.local - see .env.example for the full list',
+        hint: 'Add ANTHROPIC_API_KEY to .env.local - see .env.example',
       },
       { status: 503 },
     )
   }
 
-  // Dynamic import keeps the route module loadable without the SDK installed.
-  // Day 4 will replace this with the full Agent SDK + tool-use loop.
   const { default: Anthropic } = await import('@anthropic-ai/sdk').catch(() => ({ default: null }))
-
   if (Anthropic === null) {
     return NextResponse.json(
       {
@@ -74,32 +122,128 @@ export const POST = async (request: NextRequest) => {
 
   const anthropic = new Anthropic({ apiKey: env.ANTHROPIC_API_KEY })
 
+  const systemPrompt = scenario === 'rwa' ? RWA_SYSTEM_PROMPT : PENDLE_SYSTEM_PROMPT
+  const toolDefinition = scenario === 'rwa' ? RWA_TOOL_DEFINITION : PENDLE_TOOL_DEFINITION
+
+  let completion
   try {
-    const completion = await anthropic.messages.create({
+    completion = await anthropic.messages.create({
       model: 'claude-opus-4-5',
       max_tokens: 1024,
-      system:
-        'You are a placeholder echo agent. Day 4 replaces you with the full Pendle tool-use loop. Reply briefly to confirm the pipeline works.',
+      system: systemPrompt,
+      tools: [ toolDefinition ],
       messages: body.messages.map((message) => ({
         role: message.role,
         content: message.content,
       })),
     })
+  } catch (modelError) {
+    return NextResponse.json(
+      { error: 'Anthropic call failed', detail: String(modelError) },
+      { status: 502 },
+    )
+  }
 
-    const reply = completion.content
-      .filter((block: { type: string }) => block.type === 'text')
-      .map((block: { type: string, text?: string }) => block.text ?? '')
-      .join('\n')
+  const contentBlocks = completion.content as ResponseContentBlock[]
+  const textReply = contentBlocks
+    .filter(checkIsTextBlock)
+    .map((block) => block.text)
+    .join('\n')
+  const toolUseBlock = contentBlocks.find(checkIsToolUseBlock)
 
+  // No tool call - Claude is asking for clarification or refusing.
+  if (toolUseBlock === undefined) {
     return NextResponse.json({
-      reply,
-      scenario: body.scenario ?? 'pendle',
-      milestone: 'phase-1-day-3-echo',
+      reply: textReply,
+      scenario,
+      milestone: 'phase-1-day-5-tool-use-text-only',
     })
-  } catch (modelError) {
+  }
+
+  if (scenario !== 'pendle') {
     return NextResponse.json(
-      { error: 'Anthropic call failed', detail: String(modelError) },
+      {
+        error: 'RWA scenario not implemented yet',
+        detail: 'Phase 2 Day 10 wires the RWA envelope builder + Robinhood Chain deploy.',
+      },
+      { status: 501 },
+    )
+  }
+
+  if (toolUseBlock.name !== 'prepare_pendle_yield_swap') {
+    return NextResponse.json(
+      {
+        error: `Unexpected tool call: ${toolUseBlock.name}`,
+        detail: 'Only prepare_pendle_yield_swap is wired in the Pendle scenario.',
+      },
       { status: 502 },
     )
   }
+
+  const argsParse = preparePendleYieldSwapArgs.safeParse(toolUseBlock.input)
+  if (!argsParse.success) {
+    return NextResponse.json(
+      {
+        error: 'Invalid tool args from Claude',
+        detail: argsParse.error.flatten(),
+        rawInput: toolUseBlock.input,
+      },
+      { status: 422 },
+    )
+  }
+
+  let envelope: DemoEnvelope
+  try {
+    envelope = buildPendleEnvelope(argsParse.data, receiverAddress)
+  } catch (buildError) {
+    return NextResponse.json(
+      {
+        error: 'Envelope build failed',
+        detail: String(buildError),
+        hint:
+          'Most often this means MockPendleRouter or AgentPolicyGate is not deployed yet. ' +
+          'Run the forge scripts and update contracts/deployed.json.',
+      },
+      { status: 503 },
+    )
+  }
+
+  if (env.AGENT_SIGNER_PRIVATE_KEY === undefined) {
+    return NextResponse.json(
+      {
+        error: 'AGENT_SIGNER_PRIVATE_KEY not set',
+        hint:
+          'Required for EIP-712 envelope binding. Add a testnet key to .env.local ' +
+          'matching AGENT_SIGNER_ADDRESS.',
+      },
+      { status: 503 },
+    )
+  }
+
+  let signedEnvelope: DemoEnvelope
+  try {
+    const gateAddress = getAgentPolicyGateAddress(ARBITRUM_SEPOLIA_CHAIN_ID)
+    const signature = await signEnvelope({
+      envelopeHash: envelope.meta.envelopeHash,
+      to: envelope.inner.to,
+      data: envelope.inner.data,
+      value: BigInt(envelope.inner.value),
+      chainId: ARBITRUM_SEPOLIA_CHAIN_ID,
+      gateAddress,
+      signerPrivateKey: env.AGENT_SIGNER_PRIVATE_KEY as Hex,
+    })
+    signedEnvelope = attachAgentSignature(envelope, signature)
+  } catch (signError) {
+    return NextResponse.json(
+      { error: 'Signing failed', detail: String(signError) },
+      { status: 500 },
+    )
+  }
+
+  return NextResponse.json({
+    reply: textReply,
+    envelope: signedEnvelope,
+    scenario,
+    milestone: 'phase-1-day-5-tool-use-with-envelope',
+  })
 }

examples/arbitrum-london/app/api/decode/route.ts

@@ -1,6 +1,16 @@
-import { decodeCall, BUILTIN_REGISTRY } from '@txkit/tx-decoder'
+import {
+  decodeCall,
+  BUILTIN_REGISTRY,
+  buildRegistry,
+  type RegistryDescriptor,
+} from '@txkit/tx-decoder'
 import { NextResponse, type NextRequest } from 'next/server'
 
+import deployedJson from '@/contracts/deployed.json'
+import agentPolicyGateData from '@/decoder-data/agent-policy-gate.json'
+import mockPendleRouterData from '@/decoder-data/mock-pendle-router.json'
+
+
 export const runtime = 'nodejs'
 
 /**
@@ -10,14 +20,15 @@ export const runtime = 'nodejs'
  *   POST /api/decode { chain: "eip155:421614", call: { to, data, value? } }
  *   -> DecodedCall (per @txkit/tx-decoder shape)
  *
- * Day 5 client renders this through <EnvelopePreview/>.
- *
  * Registry composition:
  *   - BUILTIN_REGISTRY: ERC-20 / Permit2 / Uniswap V3 / Aave V3 / CoW Swap
  *     (5 mainstream protocols, 20 descriptors)
- *   - AgentPolicyGate registry data (Arbitrum Sepolia + Robinhood Chain
- *     testnet) is loaded from examples/arbitrum-london/decoder-data/ until
- *     Mike's deploy populates contracts/deployed.json - see TODO below.
+ *   - examples/arbitrum-london/decoder-data: AgentPolicyGate + MockPendleRouter
+ *     (Arbitrum Sepolia, Robinhood Chain testnet). Addresses are placeholder
+ *     0x0000...0000 in JSON; the merge step below patches them with real
+ *     addresses from contracts/deployed.json once Mike deploys.
+ *
+ * Day 5 client renders this through <EnvelopePreview/>.
  */
 type DecodeRequestBody = {
   chain: `eip155:${number}`,
@@ -28,6 +39,62 @@ type DecodeRequestBody = {
   },
 }
 
+type DeployedEntry = { address: string }
+type DeployedMap = Record<string, Record<string, DeployedEntry>>
+
+const deployedMap = deployedJson as DeployedMap
+
+/**
+ * Patch placeholder addresses (0x0000...0000) in the example decoder data
+ * with real addresses from contracts/deployed.json once a forge deploy
+ * script lands. Entries still in PENDING state stay as-is - the decoder
+ * misses them until the real contract is live, which surfaces the deploy
+ * gap rather than silently mis-decoding.
+ */
+const resolveDescriptors = (
+  data: ReadonlyArray<RegistryDescriptor>,
+  contractName: string,
+): ReadonlyArray<RegistryDescriptor> => {
+  const section = deployedMap[contractName]
+  if (section === undefined) {
+    return data
+  }
+  return data.map((descriptor) => {
+    const chainId = String(Number(descriptor.chain.split(':')[1]))
+    const entry = section[chainId]
+    if (entry === undefined) {
+      return descriptor
+    }
+    const isReal =
+      /^0x[a-fA-F0-9]{40}$/.test(entry.address) && !entry.address.includes('PENDING')
+    if (!isReal) {
+      return descriptor
+    }
+    return { ...descriptor, address: entry.address as `0x${string}` }
+  })
+}
+
+const exampleDescriptors: ReadonlyArray<RegistryDescriptor> = [
+  ...resolveDescriptors(
+    agentPolicyGateData as unknown as ReadonlyArray<RegistryDescriptor>,
+    'AgentPolicyGate',
+  ),
+  ...resolveDescriptors(
+    mockPendleRouterData as unknown as ReadonlyArray<RegistryDescriptor>,
+    'MockPendleRouter',
+  ),
+]
+
+const exampleRegistry = buildRegistry(exampleDescriptors)
+
+// Inferred shape matches @txkit/tx-decoder's Registry (Readonly<Record<string, RegistryDescriptor>>).
+// We avoid importing the Registry type because it is currently not exported
+// from the package barrel - shape-compatibility via spread is sufficient.
+const mergedRegistry = {
+  ...BUILTIN_REGISTRY,
+  ...exampleRegistry,
+}
+
 export const POST = async (request: NextRequest) => {
   let body: DecodeRequestBody
   try {
@@ -47,14 +114,10 @@ export const POST = async (request: NextRequest) => {
     return NextResponse.json({ error: 'call.to and call.data are required' }, { status: 400 })
   }
 
-  // TODO Phase 1 Day 5+: extend registry with examples/arbitrum-london/decoder-data/
-  //   const localRegistry = await loadExamplesRegistry()
-  //   const registry = mergeRegistries(BUILTIN_REGISTRY, localRegistry)
-
   try {
     const decoded = await decodeCall(
       { chain: body.chain, call: { to: body.call.to, data: body.call.data } },
-      { registry: BUILTIN_REGISTRY },
+      { registry: mergedRegistry },
     )
 
     // BigInt values (decoded args) do not serialise as JSON by default.