@blockrun/franklin 3.20.1 → 3.21.0

package/dist/agent/context.js

@@ -296,6 +296,14 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - \`/v1/modal/{...path}\` — Modal GPU sandbox passthrough (create/exec/etc.).
 - \`/v1/pm/{...path}\` — prediction-market data passthrough.
 
+**Phone & Voice (typed tools — prefer these over raw primitive calls)**
+- \`ListPhoneNumbers\` (\$0.001) / \`BuyPhoneNumber\` (\$5, 30-day lease) / \`RenewPhoneNumber\` (\$5) / \`ReleasePhoneNumber\` (free) — lifecycle of wallet-owned BlockRun numbers.
+- \`PhoneLookup\` (\$0.01) / \`PhoneFraudCheck\` (\$0.05) — carrier + risk lookup.
+- \`VoiceCall\` (\$0.54, POST /v1/voice/call) — place an outbound AI-driven call. Async — returns \`call_id\` immediately.
+- \`VoiceStatus\` (free, GET /v1/voice/call/{id}) — poll a previously-initiated call for status / transcript / recording / disposition.
+- For end-to-end voice workflows including auto-poll, confirmation gates, and compliance reminders, prefer the bundled **\`/phone-call\`** skill — it walks through intent capture, caller-ID selection, task scripting, confirmation, and the polling loop. Calls auto-journal to ~/.blockrun/calls.jsonl (visible in the panel "Calls" tab).
+- US/CA destinations only. Marketing/sales calls require prior express consent (TCPA).
+
 **Surf — crypto data + chat (x402-paid)** via the generic \`BlockRun\` capability. ~55 curated endpoints. Tier-1 $0.001, Tier-2 $0.005, Tier-3 / chat $0.02.
 - \`/v1/surf/exchange/*\` — CEX trading pairs, prices, perps, depth, klines, funding history, long/short ratio.
 - \`/v1/surf/market/*\` — token rankings, fear/greed, futures, ETF flows, options skew, liquidations, on-chain indicators (NUPL/SOPR/MVRV), price indicators (RSI/MACD/BBANDS).
@@ -307,7 +315,7 @@ On-chain affiliate (20 bps in sell-token, force-set server-side) flows to BlockR
 - \`/v1/surf/fund/{detail,portfolio,ranking}\` — VC fund profiles, portfolios, ranking.
 - \`/v1/surf/project/{detail,defi/metrics,defi/ranking}\` — project profiles + DeFi protocol metrics.
 
-For Surf workflows, prefer the bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`) — they document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`). \`/v1/surf/chat/completions\` (surf-1.5) is temporarily disabled in v3.20.1 — the BlockRun gateway's upstream path returns 404 from Surf; will be re-enabled in a follow-up release once the gateway side is fixed.
+For Surf workflows, prefer the bundled skills (\`/surf-market\`, \`/surf-chain\`, \`/surf-social\`) — they document which endpoint to pick for which question and the cost trade-off. Skipped (use the dedicated tools instead): \`/v1/surf/prediction-market/*\` (use \`PredictionMarket\`), \`/v1/surf/search/*\` (use \`ExaSearch\`), \`/v1/surf/web/*\` (use \`BrowserX\`). The Surf chat surface (\`/v1/surf/chat/completions\`, surf-1.5) is **not currently exposed** by the BlockRun gateway — removed from the registry pending an upstream redesign around per-token billing. Do not attempt to call it; use the data endpoints above for crypto context, or any of the standard LLMs on \`/v1/chat/completions\` for general chat.
 
 **Generic gateway primitive**: \`BlockRun({ path, method, params, body })\` is a single capability that signs x402 and forwards to ANY path under \`/api\`. Use it for Surf endpoints (above) and any future BlockRun partner that doesn't have a dedicated capability yet. Always specify the exact path; the primitive will not guess.
 

package/dist/panel/html.js

@@ -517,6 +517,10 @@ a:hover { text-decoration:underline; }
       Phone
       <span class="nav-badge" id="phone-nav-badge" style="display:none"></span>
     </button>
+    <button class="nav-item" data-tab="calls">
+      <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M3 10v4"/><path d="M7 8v8"/><path d="M11 5v14"/><path d="M15 8v8"/><path d="M19 10v4"/></svg>
+      Calls
+    </button>
     <button class="nav-item" data-tab="sessions">
       <svg viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round"><path d="M21 15a2 2 0 0 1-2 2H7l-4 4V5a2 2 0 0 1 2-2h14a2 2 0 0 1 2 2z"/></svg>
       Sessions
@@ -779,6 +783,27 @@ a:hover { text-decoration:underline; }
     </div>
   </div>
 
+  <!-- Calls -->
+  <div class="tab" id="tab-calls">
+    <div class="content-header">
+      <h2>Calls</h2>
+      <p>Recent outbound voice calls fired through VoiceCall. Reads from ~/.blockrun/calls.jsonl &mdash; the journal Franklin keeps locally as it polls call status.</p>
+    </div>
+
+    <div class="card">
+      <div style="display:flex;align-items:center;justify-content:space-between;gap:12px;flex-wrap:wrap;">
+        <h3 style="margin:0">Recent calls</h3>
+        <div style="display:flex;gap:8px;align-items:center">
+          <span class="phone-status" id="calls-list-status"></span>
+          <button class="btn btn-ghost" id="calls-refresh-btn" title="Reload from journal">Refresh</button>
+        </div>
+      </div>
+      <div id="calls-list" style="margin-top:12px">
+        <div class="phone-empty">Loading&hellip;</div>
+      </div>
+    </div>
+  </div>
+
   <!-- Learnings -->
   <div class="tab" id="tab-learnings">
     <div class="content-header">
@@ -1947,6 +1972,96 @@ document.getElementById('phone-buy-btn')?.addEventListener('click', buyPhoneNumb
 // clicks into the Phone tab. Cached read — no network cost.
 loadPhone({});
 
+// ─── Calls tab ──────────────────────────────────────────────────────────
+// Read-only view of ~/.blockrun/calls.jsonl. VoiceCall and VoiceStatus tools
+// write to that journal; this tab just reads.
+
+function formatCallStatus(status) {
+  const s = String(status || '').toLowerCase();
+  if (s === 'completed') return { label: 'completed', cls: 'green' };
+  if (s === 'queued' || s === 'in_progress' || s === 'in-progress') return { label: s.replace('_',' '), cls: 'amber' };
+  return { label: s || 'unknown', cls: 'red' };
+}
+
+function formatDuration(sec) {
+  if (!sec || typeof sec !== 'number') return '—';
+  const m = Math.floor(sec / 60);
+  const s = sec % 60;
+  return m > 0 ? m + 'm ' + s + 's' : s + 's';
+}
+
+function renderCallsList(calls) {
+  const list = document.getElementById('calls-list');
+  if (!list) return;
+  if (!calls || calls.length === 0) {
+    list.innerHTML = '<div class="phone-empty">' +
+      '<strong>No calls yet</strong>' +
+      'Outbound voice calls fired via the <code>VoiceCall</code> tool or the <code>/phone-call</code> skill ' +
+      'will appear here. Each call costs $0.54 and requires a wallet-owned BlockRun phone number as caller ID.' +
+      '</div>';
+    return;
+  }
+  const html = calls.map(c => {
+    const st = formatCallStatus(c.status);
+    const human = formatPhoneNumber(c.to);
+    const fromHuman = formatPhoneNumber(c.from);
+    const when = new Date(c.timestamp).toLocaleString();
+    const cost = c.paid_usd ? '$' + c.paid_usd.toFixed(2) : '—';
+    const safeTask = (c.task || '').replace(/[<>&]/g, ch => ({'<':'&lt;','>':'&gt;','&':'&amp;'}[ch]));
+    const transcriptHtml = c.transcript
+      ? '<details style="margin-top:8px"><summary style="cursor:pointer;color:var(--text-dim);font-size:12px">Transcript</summary><pre style="white-space:pre-wrap;background:oklch(0 0 0 / 25%);padding:10px;border-radius:8px;font-size:12px;margin-top:6px;max-height:400px;overflow:auto">' +
+        c.transcript.replace(/[<>&]/g, ch => ({'<':'&lt;','>':'&gt;','&':'&amp;'}[ch])) + '</pre></details>'
+      : '';
+    const recordingHtml = c.recording_url
+      ? '<a href="' + c.recording_url + '" target="_blank" rel="noopener" style="font-size:11px;color:var(--brand);text-decoration:none;margin-left:8px">▶ recording</a>'
+      : '';
+    return ''
+      + '<div class="phone-row" style="grid-template-columns:auto 1fr auto;align-items:start">'
+      + '  <div class="phone-icon-bubble">'
+      + '    <svg width="20" height="20" viewBox="0 0 24 24" fill="none" stroke="currentColor" stroke-width="1.8" stroke-linecap="round" stroke-linejoin="round">'
+      + '      <path d="M3 10v4"/><path d="M7 8v8"/><path d="M11 5v14"/><path d="M15 8v8"/><path d="M19 10v4"/>'
+      + '    </svg>'
+      + '  </div>'
+      + '  <div class="phone-main">'
+      + '    <div class="phone-num">' + human + ' <span style="font-size:11px;color:var(--text-dim);font-weight:400">from ' + fromHuman + '</span></div>'
+      + '    <div class="phone-meta">'
+      + '      <span class="chip ' + st.cls + '">' + st.label + '</span>'
+      + '      <span class="chip">' + formatDuration(c.duration_sec) + '</span>'
+      + '      <span class="chip">' + cost + '</span>'
+      + '      <span style="font-size:11px;color:var(--text-dim)">' + when + '</span>'
+      + recordingHtml
+      + '    </div>'
+      + '    <div style="font-size:12px;color:var(--text-muted);margin-top:4px;line-height:1.5">' + (safeTask.slice(0, 200) + (safeTask.length > 200 ? '…' : '')) + '</div>'
+      + transcriptHtml
+      + '  </div>'
+      + '</div>';
+  }).join('');
+  list.innerHTML = html;
+}
+
+async function loadCalls() {
+  const statusEl = document.getElementById('calls-list-status');
+  if (statusEl) { statusEl.textContent = 'Loading…'; statusEl.className = 'phone-status'; }
+  try {
+    const r = await fetch('/api/calls?limit=50');
+    const data = await r.json();
+    if (!r.ok) {
+      if (statusEl) { statusEl.textContent = data.error || 'Failed to load'; statusEl.className = 'phone-status err'; }
+      return;
+    }
+    renderCallsList(data.calls || []);
+    if (statusEl) {
+      statusEl.className = 'phone-status';
+      statusEl.textContent = data.count + ' call' + (data.count === 1 ? '' : 's');
+    }
+  } catch (err) {
+    if (statusEl) { statusEl.textContent = 'Network error'; statusEl.className = 'phone-status err'; }
+  }
+}
+
+document.querySelector('[data-tab="calls"]')?.addEventListener('click', loadCalls);
+document.getElementById('calls-refresh-btn')?.addEventListener('click', loadCalls);
+
 loadOverview();
 loadSessions();
 loadMarkets();

package/dist/panel/server.js

@@ -575,6 +575,54 @@ export function createPanelServer(port) {
                     }
                     return;
                 }
+                // ─── Calls (voice call journal) ─────────────────────────────────────
+                // Read-only views of ~/.blockrun/calls.jsonl. VoiceCall and VoiceStatus
+                // tools write to that journal; this endpoint just summarizes it for the
+                // panel "Calls" tab. No x402, no wallet-mutating action — same loopback
+                // posture as the rest of the panel anyway since the journal can contain
+                // call transcripts and recipient numbers.
+                if (p === '/api/calls' && (!req.method || req.method === 'GET')) {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden', calls: [] }, 403);
+                        return;
+                    }
+                    try {
+                        const { CallLog } = await import('../phone/call-log.js');
+                        const log = new CallLog();
+                        const limit = Math.min(parseInt(url.searchParams.get('limit') || '50', 10), 200);
+                        const calls = log.summary(limit);
+                        json(res, { calls, count: calls.length });
+                    }
+                    catch (err) {
+                        json(res, { error: err.message, calls: [] }, 500);
+                    }
+                    return;
+                }
+                if (p.startsWith('/api/calls/') && (!req.method || req.method === 'GET')) {
+                    if (!isLocalPanelRequest(req)) {
+                        json(res, { error: 'forbidden' }, 403);
+                        return;
+                    }
+                    try {
+                        const callId = decodeURIComponent(p.slice('/api/calls/'.length));
+                        if (!callId) {
+                            json(res, { error: 'call_id required' }, 400);
+                            return;
+                        }
+                        const { CallLog } = await import('../phone/call-log.js');
+                        const log = new CallLog();
+                        const entry = log.byCallId(callId);
+                        if (!entry) {
+                            json(res, { error: 'not found', call_id: callId }, 404);
+                            return;
+                        }
+                        json(res, entry);
+                    }
+                    catch (err) {
+                        json(res, { error: err.message }, 500);
+                    }
+                    return;
+                }
                 if (p === '/api/markets') {
                     // Snapshot of every active data provider for the Markets panel:
                     // pipeline wiring (which endpoint serves which asset class), live

package/dist/phone/call-log.d.ts

@@ -0,0 +1,62 @@
+/**
+ * CallLog — JSONL persistent record of every outbound voice call the agent
+ * initiates through VoiceCall (and updates as VoiceStatus polls for status).
+ *
+ * Why a journal: BlockRun's gateway doesn't expose a "list my calls" endpoint —
+ * /v1/voice/call/{id} works but you need to remember the id. Without local
+ * persistence, the panel can't show a "recent calls" view and cross-session
+ * memory ("did I already leave a voicemail at this number this week?") is
+ * impossible.
+ *
+ * Why append-only with multiple rows per call_id: calls are async, status
+ * mutates over time (queued → in_progress → completed). Append-only avoids
+ * the JSONL-rewrite-race that an in-place update would introduce — readers
+ * pick the latest row by call_id when summarizing. Same approach trade-log
+ * uses for fills vs corrections.
+ *
+ * Schema (additive over time; readers tolerate missing optional fields):
+ *   timestamp:    ms epoch of THIS log row (not the call start)
+ *   call_id:      Bland.ai call identifier (stable across rows)
+ *   to / from:    E.164 numbers
+ *   task:         the natural-language instructions the AI followed
+ *   voice / max_duration_min / language:  caller-side preferences (queue row only)
+ *   status:       queued | in_progress | completed | failed | cancelled |
+ *                 busy | no-answer | voicemail
+ *   duration_sec: actual call length once known
+ *   transcript:   full conversation text once completed
+ *   recording_url: Bland-hosted MP3/WAV link
+ *   paid_usd:     0.54 charged on the initial POST; later rows carry 0
+ *   tx_hash:      x402 settlement hash for the initial POST
+ */
+export type CallStatus = 'queued' | 'in_progress' | 'completed' | 'failed' | 'cancelled' | 'busy' | 'no-answer' | 'voicemail';
+export interface CallLogEntry {
+    timestamp: number;
+    call_id: string;
+    to: string;
+    from: string;
+    task: string;
+    voice?: string;
+    max_duration_min?: number;
+    language?: string;
+    status: CallStatus;
+    duration_sec?: number;
+    transcript?: string;
+    recording_url?: string;
+    paid_usd: number;
+    tx_hash?: string;
+}
+export declare function isTerminalStatus(s: unknown): s is CallStatus;
+export declare function defaultCallLogPath(): string;
+export declare class CallLog {
+    private filePath;
+    constructor(filePath?: string);
+    append(entry: CallLogEntry): void;
+    /** Read every entry on disk in chronological (append) order. */
+    all(): CallLogEntry[];
+    /**
+     * Latest row for each call_id, newest first by initial-row timestamp.
+     * This is the canonical "list of calls" view for the panel.
+     */
+    summary(limit?: number): CallLogEntry[];
+    byCallId(callId: string): CallLogEntry | null;
+}

package/dist/phone/call-log.js

@@ -0,0 +1,123 @@
+/**
+ * CallLog — JSONL persistent record of every outbound voice call the agent
+ * initiates through VoiceCall (and updates as VoiceStatus polls for status).
+ *
+ * Why a journal: BlockRun's gateway doesn't expose a "list my calls" endpoint —
+ * /v1/voice/call/{id} works but you need to remember the id. Without local
+ * persistence, the panel can't show a "recent calls" view and cross-session
+ * memory ("did I already leave a voicemail at this number this week?") is
+ * impossible.
+ *
+ * Why append-only with multiple rows per call_id: calls are async, status
+ * mutates over time (queued → in_progress → completed). Append-only avoids
+ * the JSONL-rewrite-race that an in-place update would introduce — readers
+ * pick the latest row by call_id when summarizing. Same approach trade-log
+ * uses for fills vs corrections.
+ *
+ * Schema (additive over time; readers tolerate missing optional fields):
+ *   timestamp:    ms epoch of THIS log row (not the call start)
+ *   call_id:      Bland.ai call identifier (stable across rows)
+ *   to / from:    E.164 numbers
+ *   task:         the natural-language instructions the AI followed
+ *   voice / max_duration_min / language:  caller-side preferences (queue row only)
+ *   status:       queued | in_progress | completed | failed | cancelled |
+ *                 busy | no-answer | voicemail
+ *   duration_sec: actual call length once known
+ *   transcript:   full conversation text once completed
+ *   recording_url: Bland-hosted MP3/WAV link
+ *   paid_usd:     0.54 charged on the initial POST; later rows carry 0
+ *   tx_hash:      x402 settlement hash for the initial POST
+ */
+import { appendFileSync, existsSync, mkdirSync, readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { homedir } from 'node:os';
+/** Set of statuses that mean "no further polling needed". */
+const TERMINAL_STATUSES = new Set([
+    'completed',
+    'failed',
+    'cancelled',
+    'busy',
+    'no-answer',
+    'voicemail',
+]);
+export function isTerminalStatus(s) {
+    return typeof s === 'string' && TERMINAL_STATUSES.has(s);
+}
+export function defaultCallLogPath() {
+    return join(homedir(), '.blockrun', 'calls.jsonl');
+}
+export class CallLog {
+    filePath;
+    constructor(filePath = defaultCallLogPath()) {
+        this.filePath = filePath;
+    }
+    append(entry) {
+        try {
+            mkdirSync(dirname(this.filePath), { recursive: true });
+            appendFileSync(this.filePath, JSON.stringify(entry) + '\n', 'utf-8');
+        }
+        catch {
+            /* best-effort persistence; never block a call on disk failure */
+        }
+    }
+    /** Read every entry on disk in chronological (append) order. */
+    all() {
+        if (!existsSync(this.filePath))
+            return [];
+        let raw;
+        try {
+            raw = readFileSync(this.filePath, 'utf-8');
+        }
+        catch {
+            return [];
+        }
+        const out = [];
+        for (const line of raw.split('\n')) {
+            if (!line.trim())
+                continue;
+            try {
+                const obj = JSON.parse(line);
+                if (typeof obj?.timestamp === 'number' &&
+                    typeof obj?.call_id === 'string' &&
+                    typeof obj?.to === 'string' &&
+                    typeof obj?.from === 'string' &&
+                    typeof obj?.task === 'string' &&
+                    typeof obj?.status === 'string' &&
+                    typeof obj?.paid_usd === 'number') {
+                    out.push(obj);
+                }
+            }
+            catch {
+                /* corrupt line — skip */
+            }
+        }
+        return out;
+    }
+    /**
+     * Latest row for each call_id, newest first by initial-row timestamp.
+     * This is the canonical "list of calls" view for the panel.
+     */
+    summary(limit = 50) {
+        const all = this.all();
+        const latest = new Map();
+        for (const e of all) {
+            const cur = latest.get(e.call_id);
+            // Keep the row with the FRESHEST timestamp per call_id (status updates).
+            if (!cur || e.timestamp >= cur.timestamp)
+                latest.set(e.call_id, e);
+        }
+        // Sort newest-first by the latest-row timestamp.
+        const list = Array.from(latest.values()).sort((a, b) => b.timestamp - a.timestamp);
+        return list.slice(0, limit);
+    }
+    byCallId(callId) {
+        let best = null;
+        for (const e of this.all()) {
+            if (e.call_id !== callId)
+                continue;
+            if (!best || e.timestamp >= best.timestamp)
+                best = e;
+        }
+        return best;
+    }
+}

package/dist/skills-bundled/phone-call/SKILL.md

@@ -0,0 +1,115 @@
+---
+name: phone-call
+description: Place an outbound AI-driven voice call (Bland.ai via BlockRun). Walks through intent capture, caller-ID selection, task scripting, and confirmation; fires VoiceCall, then auto-polls VoiceStatus until completion and surfaces the transcript. $0.54 per call, US/CA destinations only, charged from your wallet. Real-world action — use with prior consent.
+triggers:
+  - "make a phone call"
+  - "call this number"
+  - "call them"
+  - "place a call"
+  - "outbound call"
+  - "phone call"
+  - "leave a voicemail"
+argument-hint: <recipient + what to say>
+cost-receipt: true
+---
+
+You are running inside Franklin on **{{wallet_chain}}**. This skill is Franklin's real-world action surface — it picks up a real phone, charges a real $0.54 from the user's wallet, and the recipient is a real human (or their voicemail). Be deliberate.
+
+## Workflow
+
+### 1 · Capture intent
+
+Read what the user said below under "The user said". Extract two things:
+
+- **Recipient phone number** in E.164 (e.g. `+14155552671`). US/CA only — if the country code isn't `+1`, stop and tell the user the surface is US/CA only today.
+- **Task** — what should the AI say / do on the call? Concrete enough that a stranger reading it cold could execute. 10–4000 chars.
+
+If either is vague, ask **one** clarifying question. Do not fan out into multi-question interviews — phone calls aren't worth a 5-turn interrogation.
+
+### 2 · Pick the caller-ID
+
+Call `ListPhoneNumbers` ($0.001) to see what the wallet owns.
+
+- **0 active numbers** → tell the user they need to provision one first via `BuyPhoneNumber` ($5, 30-day lease). Stop. Do not auto-buy a number unless the user explicitly says so — $5 is a meaningful spend.
+- **1 active number** → use it as `from`. Mention which number you're using.
+- **>1 active number** → list them with expiry dates; ask the user which to use as caller-ID.
+
+### 3 · Craft the task script
+
+Reasonable template — adapt to the user's intent:
+
+```
+Greet the recipient briefly. Identify yourself as <"calling on behalf of <user>" or
+similar>. State the purpose in one sentence: <purpose>. <Key facts the AI needs to
+convey or ask>. If you reach voicemail, leave a short message: <voicemail script>.
+Stay polite and end the call once the objective is met.
+```
+
+The task is verbatim instructions to the AI — every phrase you write WILL be spoken by the AI on the call. Don't include placeholders the AI can't resolve. Don't include private data the recipient shouldn't hear ("the user is buying a $40,000 car" is between Franklin and the user, not the recipient).
+
+### 4 · Confirm before firing
+
+Show the user, in plain text:
+
+- **To:** \`<recipient E.164>\`
+- **From:** \`<caller-ID E.164>\` (\<days-left\> days on lease)
+- **Cost:** $0.54 from wallet
+- **Voice:** \`<preset>\` (default \`maya\`)
+- **Max duration:** \<N\> minutes (default 5)
+- **Task summary:** first 1–2 sentences
+
+Ask: "Place the call? Reply \`yes\` to proceed." Wait for explicit confirmation. Anything other than yes → stop.
+
+### 5 · Place the call
+
+```
+VoiceCall({
+  to: "<E.164>",
+  from: "<E.164 wallet-owned>",
+  task: "<full task script>",
+  voice: "<preset>",      // optional, default maya
+  max_duration: <N>,      // optional, default 5
+  language: "<code>"      // optional, default en-US
+})
+```
+
+Tool returns a `call_id` immediately. Surface it to the user along with "polling now."
+
+### 6 · Auto-poll status
+
+Loop, every ~30 seconds, calling `VoiceStatus({ call_id })`:
+
+- If status is `queued` or `in_progress` → continue.
+- If status is one of `completed` / `failed` / `cancelled` / `busy` / `no-answer` / `voicemail` → stop polling.
+- Cap the loop at ~10 minutes total (20 polls). If you hit the cap, tell the user the call is still running and they can rerun `VoiceStatus call_id="…"` later.
+
+VoiceStatus is **free** — poll as often as needed.
+
+### 7 · Surface the result
+
+When polling ends:
+
+- One-line outcome: status, duration (sec → MM:SS), disposition.
+- Full transcript (or first 2000 chars + a note if longer).
+- Recording URL if returned.
+- Total cost ($0.54 — the polls were free).
+
+If the call failed before connecting (busy, no-answer, voicemail without leaving a message), tell the user clearly. Don't dress up a failed call as a partial success.
+
+## Compliance — non-negotiable
+
+- **US/CA destinations only.** Anything else, refuse.
+- **Daytime preference.** Estimate the recipient's local time from the area code; if it's outside 9 am – 9 pm local, raise the question in the confirmation step (not after firing). User can override.
+- **Marketing / sales calls require prior express consent.** If the task script reads like outbound marketing (selling something, soliciting sign-ups, promotional offers), refuse unless the user explicitly attests in their message that the recipient has prior consent. TCPA in the US is not a guideline; it's a statute with private right of action.
+- **Don't auto-fire follow-ups.** If a call fails or ends in voicemail, ask the user whether to retry, don't loop automatically.
+
+## Anti-patterns
+
+- Placing a call to a number the user didn't explicitly type. If they said "call them about Y", clarify who "them" is — don't grep history for the most-recent-looking number.
+- Writing a task script that pressures the recipient (false urgency, fake authority, manipulation). The AI on the call WILL execute whatever's in the script.
+- Sequential cold calls without consent. One call per skill invocation; if the user wants a sequence, ask them to confirm each one.
+- Calling 911 or any emergency line. Both Franklin and BlockRun block this; don't try to test it.
+
+## The user said
+
+$ARGUMENTS

package/dist/tools/blockrun.js

@@ -174,10 +174,10 @@ export const blockrunCapability = {
     spec: {
         name: 'BlockRun',
         description: 'Call any BlockRun gateway endpoint. Signs an x402 USDC payment from the user wallet, retries on HTTP 402, and returns the response. ' +
-            'Use this for crypto data (Surf — markets, on-chain, social, chat), AI inference (chat / image / video / music), phone numbers and voice calls, ' +
-            'prediction markets, DeFi data, and any other API exposed under https://blockrun.ai/marketplace. ' +
+            'Use this for crypto data (Surf — markets, on-chain, social), AI inference (chat / image / video / music), prediction markets, DeFi data, and any other API exposed under https://blockrun.ai/marketplace. ' +
+            'For phone and voice, prefer the typed tools (ListPhoneNumbers, BuyPhoneNumber, RenewPhoneNumber, ReleasePhoneNumber, PhoneLookup, PhoneFraudCheck, VoiceCall, VoiceStatus) — they spell out cost, required fields, and the buy-number-first requirement. ' +
             'The path must start with "/v1/" or "/.well-known/". ' +
-            'Bundled skills like /surf-market, /surf-chain, /surf-social, /surf-chat document which endpoints to call for common workflows — read those when you are unsure which path serves the user\'s question. ' +
+            'Bundled skills like /surf-market, /surf-chain, /surf-social document which endpoints to call for common workflows — read those when you are unsure which path serves the user\'s question. ' +
             'Cost is wallet-charged automatically; the response includes the actual USD paid.',
         input_schema: {
             type: 'object',

package/dist/tools/index.js

@@ -33,6 +33,8 @@ import { defiLlamaProtocolsCapability, defiLlamaProtocolCapability, defiLlamaCha
 import { predictionMarketCapability } from './prediction.js';
 import { modalCapabilities } from './modal.js';
 import { blockrunCapability } from './blockrun.js';
+import { listPhoneNumbersCapability, buyPhoneNumberCapability, renewPhoneNumberCapability, releasePhoneNumberCapability, phoneLookupCapability, phoneFraudCheckCapability, } from './phone.js';
+import { voiceCallCapability, voiceStatusCapability } from './voice.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -164,7 +166,19 @@ export const allCapabilities = [
     defiLlamaYieldsCapability,
     defiLlamaPriceCapability,
     predictionMarketCapability, // Polymarket / Kalshi / matching / smart money via Predexon
-    blockrunCapability, // Generic x402-paid gateway primitive — Surf, Phone, future partners (see /surf-* skills)
+    blockrunCapability, // Generic x402-paid gateway primitive — Surf, future partners (see /surf-* skills)
+    // Phone & Voice — typed surface so the agent pattern-matches on the user
+    // intent ("buy a number", "make a call") without needing to consult the
+    // BlockRun primitive or the .well-known/x402 manifest. All wrap the same
+    // /v1/phone/* and /v1/voice/* endpoints under the hood.
+    listPhoneNumbersCapability, // ListPhoneNumbers — $0.001
+    buyPhoneNumberCapability, // BuyPhoneNumber   — $5 / 30 days
+    renewPhoneNumberCapability, // RenewPhoneNumber — $5 / 30 days
+    releasePhoneNumberCapability, // ReleasePhoneNumber — free
+    phoneLookupCapability, // PhoneLookup      — $0.01
+    phoneFraudCheckCapability, // PhoneFraudCheck  — $0.05
+    voiceCallCapability, // VoiceCall        — $0.54 / call (Bland.ai)
+    voiceStatusCapability, // VoiceStatus      — free (poll)
     // Modal GPU sandbox tools — registered but hidden by default (not in
     // CORE_TOOL_NAMES). Agent must `ActivateTool({names:["ModalCreate",...]})`
     // before they appear in its tool inventory. High-cost ($0.40/H100 create)

package/dist/tools/phone.d.ts

@@ -0,0 +1,20 @@
+/**
+ * Phone number management — buy / list / renew / release / lookup wallet-
+ * owned phone numbers via the BlockRun gateway `/v1/phone/*` endpoints.
+ *
+ * Each lifecycle action is its own typed tool (rather than a single generic
+ * "phone manager") so the agent's tool-list pattern-matches naturally on the
+ * user's intent — "buy me a number" → BuyPhoneNumber, "list my numbers" →
+ * ListPhoneNumbers — without needing to consult the BlockRun primitive or
+ * the `.well-known/x402` manifest.
+ *
+ * x402 payment flow mirrors src/tools/exa.ts: a 402 from the gateway triggers
+ * a signed USDC transfer (Base or Solana), retry succeeds.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const listPhoneNumbersCapability: CapabilityHandler;
+export declare const buyPhoneNumberCapability: CapabilityHandler;
+export declare const renewPhoneNumberCapability: CapabilityHandler;
+export declare const releasePhoneNumberCapability: CapabilityHandler;
+export declare const phoneLookupCapability: CapabilityHandler;
+export declare const phoneFraudCheckCapability: CapabilityHandler;

package/dist/tools/phone.js

@@ -0,0 +1,284 @@
+/**
+ * Phone number management — buy / list / renew / release / lookup wallet-
+ * owned phone numbers via the BlockRun gateway `/v1/phone/*` endpoints.
+ *
+ * Each lifecycle action is its own typed tool (rather than a single generic
+ * "phone manager") so the agent's tool-list pattern-matches naturally on the
+ * user's intent — "buy me a number" → BuyPhoneNumber, "list my numbers" →
+ * ListPhoneNumbers — without needing to consult the BlockRun primitive or
+ * the `.well-known/x402` manifest.
+ *
+ * x402 payment flow mirrors src/tools/exa.ts: a 402 from the gateway triggers
+ * a signed USDC transfer (Base or Solana), retry succeeds.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
+const PHONE_TIMEOUT_MS = 30_000;
+// ─── Shared payment flow (POST) ───────────────────────────────────────────
+async function postWithPayment(path, body, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${path}`;
+    const bodyStr = JSON.stringify(body);
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), PHONE_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        let response = await fetch(endpoint, {
+            method: 'POST',
+            signal: controller.signal,
+            headers,
+            body: bodyStr,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint, 'Franklin phone');
+            if (!paymentHeaders)
+                throw new Error('Payment signing failed — check wallet balance');
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body: bodyStr,
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(`Phone ${path} failed (${response.status}): ${errText.slice(0, 300)}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function signPayment(response, chain, endpoint, description) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || description,
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired);
+        const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || description,
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        logger.warn(`[franklin] Phone payment error: ${err.message}`);
+        return null;
+    }
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* not JSON */ }
+    }
+    return header;
+}
+// ─── Tools ─────────────────────────────────────────────────────────────────
+export const listPhoneNumbersCapability = {
+    spec: {
+        name: 'ListPhoneNumbers',
+        description: 'List the phone numbers your wallet currently owns (US/CA, leased 30 days at a time). ' +
+            'Use this before any phone-related action to remind the agent what numbers are available. ' +
+            'Costs $0.001 USDC. Returns each number with country, area code, expiration timestamp, ' +
+            'and current status (active/expiring/expired).',
+        input_schema: { type: 'object', properties: {} },
+    },
+    execute: async (_input, ctx) => {
+        try {
+            const res = await postWithPayment('/v1/phone/numbers/list', {}, ctx);
+            return {
+                output: `## Phone numbers (wallet-owned)\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Phone list failed: ${err.message}`, isError: true };
+        }
+    },
+};
+export const buyPhoneNumberCapability = {
+    spec: {
+        name: 'BuyPhoneNumber',
+        description: 'Provision a new US or CA phone number for the wallet for 30 days. Costs $5 USDC. ' +
+            'Optionally pin a 3-digit area code (best effort). The provisioned number is auto-registered ' +
+            'as a valid caller ID for outbound VoiceCall. A wallet can hold multiple numbers; this adds ' +
+            'one, never replaces. To pick the country: country="US" (default) or country="CA".',
+        input_schema: {
+            type: 'object',
+            properties: {
+                country: { type: 'string', enum: ['US', 'CA'], description: 'Country code (default: US)' },
+                area_code: { type: 'string', description: 'Preferred 3-digit area code (best effort)' },
+            },
+        },
+    },
+    execute: async (input, ctx) => {
+        const body = {};
+        if (typeof input.country === 'string')
+            body.country = input.country;
+        if (typeof input.area_code === 'string')
+            body.areaCode = input.area_code;
+        try {
+            const res = await postWithPayment('/v1/phone/numbers/buy', body, ctx);
+            return {
+                output: `## Number provisioned ($5 USDC charged)\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Buy failed: ${err.message}`, isError: true };
+        }
+    },
+};
+export const renewPhoneNumberCapability = {
+    spec: {
+        name: 'RenewPhoneNumber',
+        description: 'Extend the 30-day lease on a wallet-owned phone number. Costs $5 USDC. Use ListPhoneNumbers ' +
+            'first to confirm the number is yours. Released or expired numbers cannot be renewed — buy a ' +
+            'new one with BuyPhoneNumber instead.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                phone_number: { type: 'string', description: 'E.164 format, e.g. +14155552671' },
+            },
+            required: ['phone_number'],
+        },
+    },
+    execute: async (input, ctx) => {
+        if (typeof input.phone_number !== 'string') {
+            return { output: 'phone_number (E.164) required', isError: true };
+        }
+        try {
+            const res = await postWithPayment('/v1/phone/numbers/renew', { phoneNumber: input.phone_number }, ctx);
+            return {
+                output: `## Lease renewed (+30 days, $5 USDC charged)\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Renew failed: ${err.message}`, isError: true };
+        }
+    },
+};
+export const releasePhoneNumberCapability = {
+    spec: {
+        name: 'ReleasePhoneNumber',
+        description: 'Release a wallet-owned phone number back to the BlockRun pool before its lease expires. ' +
+            'Free. The number is gone after this — it may be picked up by another wallet. Use when you ' +
+            "no longer need a test number and want it out of your ListPhoneNumbers result.",
+        input_schema: {
+            type: 'object',
+            properties: {
+                phone_number: { type: 'string', description: 'E.164 format, e.g. +14155552671' },
+            },
+            required: ['phone_number'],
+        },
+    },
+    execute: async (input, ctx) => {
+        if (typeof input.phone_number !== 'string') {
+            return { output: 'phone_number (E.164) required', isError: true };
+        }
+        try {
+            const res = await postWithPayment('/v1/phone/numbers/release', { phoneNumber: input.phone_number }, ctx);
+            return {
+                output: `## Number released (free)\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Release failed: ${err.message}`, isError: true };
+        }
+    },
+};
+export const phoneLookupCapability = {
+    spec: {
+        name: 'PhoneLookup',
+        description: 'Look up carrier and line type information for ANY phone number (does not need to be ' +
+            'wallet-owned). Returns carrier name, line type (mobile/landline/voip), country, and ' +
+            'portability info. Costs $0.01 USDC. Use to validate a number before texting/calling or ' +
+            'to figure out whether a contact number is a real mobile.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                phone_number: { type: 'string', description: 'E.164 format, e.g. +14155552671' },
+            },
+            required: ['phone_number'],
+        },
+    },
+    execute: async (input, ctx) => {
+        if (typeof input.phone_number !== 'string') {
+            return { output: 'phone_number (E.164) required', isError: true };
+        }
+        try {
+            const res = await postWithPayment('/v1/phone/lookup', { phoneNumber: input.phone_number }, ctx);
+            return {
+                output: `## Phone lookup ($0.01 USDC charged)\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Lookup failed: ${err.message}`, isError: true };
+        }
+    },
+};
+export const phoneFraudCheckCapability = {
+    spec: {
+        name: 'PhoneFraudCheck',
+        description: 'Run a fraud / risk assessment on a phone number — checks SIM swap signals, call forwarding ' +
+            'status, and known-spam reputation. Returns a risk score and signal breakdown. Costs $0.05 ' +
+            'USDC. Use before sending OTPs or trusting a phone for account recovery.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                phone_number: { type: 'string', description: 'E.164 format, e.g. +14155552671' },
+            },
+            required: ['phone_number'],
+        },
+    },
+    execute: async (input, ctx) => {
+        if (typeof input.phone_number !== 'string') {
+            return { output: 'phone_number (E.164) required', isError: true };
+        }
+        try {
+            const res = await postWithPayment('/v1/phone/lookup/fraud', { phoneNumber: input.phone_number }, ctx);
+            return {
+                output: `## Fraud check ($0.05 USDC charged)\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Fraud check failed: ${err.message}`, isError: true };
+        }
+    },
+};

package/dist/tools/voice.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Outbound AI voice calls via Bland.ai through the BlockRun `/v1/voice/*`
+ * gateway. Two tools:
+ *
+ *  - VoiceCall   — POST /v1/voice/call ($0.54 flat, up to 5 min default).
+ *                  Returns call_id immediately; the call runs async upstream.
+ *  - VoiceStatus — GET  /v1/voice/call/{call_id} (free). Polls for transcript
+ *                  + recording + final disposition.
+ *
+ * Voice calls require a wallet-owned BlockRun phone number as caller ID —
+ * use BuyPhoneNumber (or ListPhoneNumbers if one already exists) before
+ * calling VoiceCall, otherwise the gateway returns 400 with the buy
+ * instructions inline.
+ *
+ * x402 payment flow mirrors src/tools/exa.ts.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export declare const voiceCallCapability: CapabilityHandler;
+export declare const voiceStatusCapability: CapabilityHandler;

package/dist/tools/voice.js

@@ -0,0 +1,352 @@
+/**
+ * Outbound AI voice calls via Bland.ai through the BlockRun `/v1/voice/*`
+ * gateway. Two tools:
+ *
+ *  - VoiceCall   — POST /v1/voice/call ($0.54 flat, up to 5 min default).
+ *                  Returns call_id immediately; the call runs async upstream.
+ *  - VoiceStatus — GET  /v1/voice/call/{call_id} (free). Polls for transcript
+ *                  + recording + final disposition.
+ *
+ * Voice calls require a wallet-owned BlockRun phone number as caller ID —
+ * use BuyPhoneNumber (or ListPhoneNumbers if one already exists) before
+ * calling VoiceCall, otherwise the gateway returns 400 with the buy
+ * instructions inline.
+ *
+ * x402 payment flow mirrors src/tools/exa.ts.
+ */
+import { getOrCreateWallet, getOrCreateSolanaWallet, createPaymentPayload, createSolanaPaymentPayload, parsePaymentRequired, extractPaymentDetails, solanaKeyToBytes, SOLANA_NETWORK, } from '@blockrun/llm';
+import { loadChain, API_URLS, VERSION } from '../config.js';
+import { logger } from '../logger.js';
+import { CallLog } from '../phone/call-log.js';
+/** Singleton, lazy — paths are computed at first use so tests can stub homedir. */
+let _callLog = null;
+function callLog() {
+    if (!_callLog)
+        _callLog = new CallLog();
+    return _callLog;
+}
+/**
+ * Normalize whatever string Bland.ai returns as `status` (or `disposition` /
+ * `call_state` — the field name has drifted across upstream versions) into
+ * the CallStatus union our journal stores. Unknown / missing → 'queued' so
+ * the row still gets written and a later poll can refine it.
+ */
+function normalizeStatus(raw) {
+    if (typeof raw !== 'string')
+        return 'queued';
+    const s = raw.toLowerCase().trim();
+    if (s === 'completed')
+        return 'completed';
+    if (s === 'failed' || s === 'error')
+        return 'failed';
+    if (s === 'cancelled' || s === 'canceled')
+        return 'cancelled';
+    if (s === 'busy')
+        return 'busy';
+    if (s === 'no-answer' || s === 'no_answer' || s === 'noanswer')
+        return 'no-answer';
+    if (s === 'voicemail')
+        return 'voicemail';
+    if (s === 'in-progress' || s === 'in_progress' || s === 'inprogress' || s === 'ringing')
+        return 'in_progress';
+    return 'queued';
+}
+const VOICE_TIMEOUT_MS = 30_000;
+// ─── Shared x402 helpers (paid POST + free GET) ───────────────────────────
+async function postWithPayment(path, body, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${path}`;
+    const bodyStr = JSON.stringify(body);
+    const headers = {
+        'Content-Type': 'application/json',
+        'User-Agent': `franklin/${VERSION}`,
+    };
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), VOICE_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        let response = await fetch(endpoint, {
+            method: 'POST',
+            signal: controller.signal,
+            headers,
+            body: bodyStr,
+        });
+        if (response.status === 402) {
+            const paymentHeaders = await signPayment(response, chain, endpoint);
+            if (!paymentHeaders)
+                throw new Error('Payment signing failed — check wallet balance');
+            response = await fetch(endpoint, {
+                method: 'POST',
+                signal: controller.signal,
+                headers: { ...headers, ...paymentHeaders },
+                body: bodyStr,
+            });
+        }
+        if (!response.ok) {
+            const errText = await response.text().catch(() => '');
+            throw new Error(`Voice ${path} failed (${response.status}): ${errText.slice(0, 400)}`);
+        }
+        return (await response.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function getNoPayment(path, ctx) {
+    const chain = loadChain();
+    const apiUrl = API_URLS[chain];
+    const endpoint = `${apiUrl}${path}`;
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), VOICE_TIMEOUT_MS);
+    const onAbort = () => controller.abort();
+    ctx.abortSignal.addEventListener('abort', onAbort, { once: true });
+    try {
+        const resp = await fetch(endpoint, {
+            method: 'GET',
+            signal: controller.signal,
+            headers: { 'User-Agent': `franklin/${VERSION}` },
+        });
+        if (!resp.ok) {
+            const errText = await resp.text().catch(() => '');
+            throw new Error(`Voice ${path} failed (${resp.status}): ${errText.slice(0, 300)}`);
+        }
+        return (await resp.json());
+    }
+    finally {
+        clearTimeout(timeout);
+        ctx.abortSignal.removeEventListener('abort', onAbort);
+    }
+}
+async function signPayment(response, chain, endpoint) {
+    try {
+        const paymentHeader = await extractPaymentReq(response);
+        if (!paymentHeader)
+            return null;
+        if (chain === 'solana') {
+            const wallet = await getOrCreateSolanaWallet();
+            const paymentRequired = parsePaymentRequired(paymentHeader);
+            const details = extractPaymentDetails(paymentRequired, SOLANA_NETWORK);
+            const secretBytes = await solanaKeyToBytes(wallet.privateKey);
+            const feePayer = details.extra?.feePayer || details.recipient;
+            const payload = await createSolanaPaymentPayload(secretBytes, wallet.address, details.recipient, details.amount, feePayer, {
+                resourceUrl: details.resource?.url || endpoint,
+                resourceDescription: details.resource?.description || 'Franklin voice call',
+                maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+                extra: details.extra,
+            });
+            return { 'PAYMENT-SIGNATURE': payload };
+        }
+        const wallet = getOrCreateWallet();
+        const paymentRequired = parsePaymentRequired(paymentHeader);
+        const details = extractPaymentDetails(paymentRequired);
+        const payload = await createPaymentPayload(wallet.privateKey, wallet.address, details.recipient, details.amount, details.network || 'eip155:8453', {
+            resourceUrl: details.resource?.url || endpoint,
+            resourceDescription: details.resource?.description || 'Franklin voice call',
+            maxTimeoutSeconds: details.maxTimeoutSeconds || 60,
+            extra: details.extra,
+        });
+        return { 'PAYMENT-SIGNATURE': payload };
+    }
+    catch (err) {
+        logger.warn(`[franklin] Voice payment error: ${err.message}`);
+        return null;
+    }
+}
+async function extractPaymentReq(response) {
+    let header = response.headers.get('payment-required');
+    if (!header) {
+        try {
+            const body = (await response.json());
+            if (body.x402 || body.accepts)
+                header = btoa(JSON.stringify(body));
+        }
+        catch { /* not JSON */ }
+    }
+    return header;
+}
+// ─── Tools ─────────────────────────────────────────────────────────────────
+export const voiceCallCapability = {
+    spec: {
+        name: 'VoiceCall',
+        description: 'Make an outbound AI-powered phone call via Bland.ai. The AI agent on the other end ' +
+            'follows the `task` description in natural language. Cost: $0.54 flat per call (up to 5 min ' +
+            'default, 30 min max). Returns a call_id immediately; the call runs asynchronously. Use ' +
+            'VoiceStatus with the same call_id to poll transcript / recording / disposition.\n\n' +
+            'Common use cases: appointment reminders, verification callbacks, voice surveys, customer ' +
+            'outreach, OTP retrieval, two-party verification calls.\n\n' +
+            'Requirements:\n' +
+            '  - `from` MUST be a wallet-owned BlockRun phone number — use ListPhoneNumbers to find ' +
+            'one or BuyPhoneNumber to provision one ($5, 30-day lease).\n' +
+            '  - `to` and `from` must be E.164 format (+ country code prefix, e.g. +14155552671).\n' +
+            '  - `task` must be ≥10 chars, ≤4000 chars.\n' +
+            '  - US/CA destinations only.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                to: {
+                    type: 'string',
+                    description: 'Recipient phone number in E.164 format, e.g. +14155552671.',
+                },
+                from: {
+                    type: 'string',
+                    description: 'Caller ID — must be a phone number your wallet owns via BlockRun (provision with ' +
+                        'BuyPhoneNumber). E.164 format.',
+                },
+                task: {
+                    type: 'string',
+                    description: 'Natural-language description of what the AI should do on the call. Min 10 chars, ' +
+                        'max 4000. Example: "Greet the person, confirm their 3 pm appointment for Thursday, ' +
+                        'and ask if they need to reschedule. Speak warmly and end the call after confirmation."',
+                },
+                voice: {
+                    type: 'string',
+                    enum: ['nat', 'josh', 'maya', 'june', 'paige', 'derek', 'florian'],
+                    description: 'Voice preset (default: maya). Try josh/derek for male voices, maya/june/paige for ' +
+                        'female, nat for neutral.',
+                },
+                max_duration: {
+                    type: 'integer',
+                    minimum: 1,
+                    maximum: 30,
+                    description: 'Maximum call length in minutes (1–30, default: 5).',
+                },
+                language: {
+                    type: 'string',
+                    description: 'Language code for STT/TTS (default: en-US). Bland supports zh-CN, es-ES, etc.',
+                },
+                first_sentence: {
+                    type: 'string',
+                    description: 'Optional fixed opening line spoken before the AI takes over (≤500 chars).',
+                },
+                wait_for_greeting: {
+                    type: 'boolean',
+                    description: 'If true, AI waits for the recipient to speak first before talking.',
+                },
+            },
+            required: ['to', 'from', 'task'],
+        },
+    },
+    execute: async (input, ctx) => {
+        if (typeof input.to !== 'string')
+            return { output: 'to (E.164) required', isError: true };
+        if (typeof input.from !== 'string')
+            return { output: 'from (wallet-owned E.164) required — use ListPhoneNumbers / BuyPhoneNumber', isError: true };
+        if (typeof input.task !== 'string' || input.task.length < 10) {
+            return { output: 'task required (10–4000 chars natural-language description)', isError: true };
+        }
+        const body = {
+            to: input.to,
+            from: input.from,
+            task: input.task,
+        };
+        // The gateway validates additionalProperties: false — only forward known
+        // optional fields, don't echo back whatever the caller passed.
+        if (typeof input.voice === 'string')
+            body.voice = input.voice;
+        if (typeof input.max_duration === 'number')
+            body.max_duration = input.max_duration;
+        if (typeof input.language === 'string')
+            body.language = input.language;
+        if (typeof input.first_sentence === 'string')
+            body.first_sentence = input.first_sentence;
+        if (typeof input.wait_for_greeting === 'boolean')
+            body.wait_for_greeting = input.wait_for_greeting;
+        try {
+            const res = await postWithPayment('/v1/voice/call', body, ctx);
+            const callId = (res.call_id || res.id);
+            // Persist a "queued" row so the panel sees the call before VoiceStatus polls.
+            // Best-effort — if disk write fails we still surface the call_id to the agent.
+            if (callId) {
+                try {
+                    callLog().append({
+                        timestamp: Date.now(),
+                        call_id: callId,
+                        to: String(input.to),
+                        from: String(input.from),
+                        task: String(input.task),
+                        voice: typeof input.voice === 'string' ? input.voice : undefined,
+                        max_duration_min: typeof input.max_duration === 'number' ? input.max_duration : undefined,
+                        language: typeof input.language === 'string' ? input.language : undefined,
+                        status: normalizeStatus(res.status),
+                        paid_usd: 0.54,
+                        tx_hash: typeof res.tx_hash === 'string' ? res.tx_hash : undefined,
+                    });
+                }
+                catch { /* best-effort */ }
+            }
+            return {
+                output: `## Voice call initiated ($0.54 USDC charged)\n\n` +
+                    (callId
+                        ? `**call_id:** \`${callId}\`\n\nPoll with VoiceStatus call_id="${callId}" to get the ` +
+                            `transcript and disposition. The call typically completes in 1–6 minutes.\n\n`
+                        : '') +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `Voice call failed: ${err.message}`, isError: true };
+        }
+    },
+};
+export const voiceStatusCapability = {
+    spec: {
+        name: 'VoiceStatus',
+        description: 'Poll a previously-initiated voice call for its current status, transcript, recording URL, ' +
+            'and final disposition (completed / failed / no-answer / busy / voicemail). Free — no USDC ' +
+            'charged. Use the call_id returned by VoiceCall. Call this every 30–60 s until status is ' +
+            'a terminal state.',
+        input_schema: {
+            type: 'object',
+            properties: {
+                call_id: {
+                    type: 'string',
+                    description: 'The call_id returned by a prior VoiceCall.',
+                },
+            },
+            required: ['call_id'],
+        },
+    },
+    execute: async (input, ctx) => {
+        if (typeof input.call_id !== 'string') {
+            return { output: 'call_id required', isError: true };
+        }
+        try {
+            const res = await getNoPayment(`/v1/voice/call/${encodeURIComponent(input.call_id)}`, ctx);
+            // Patch the local journal with whatever fields the gateway returned —
+            // transcript / recording / duration / disposition. Append-only schema
+            // means we just write a new row; CallLog.summary() picks the latest.
+            try {
+                const prior = callLog().byCallId(input.call_id);
+                if (prior) {
+                    const recording = typeof res.recording_url === 'string' ? res.recording_url :
+                        typeof res.recording === 'string' ? res.recording : undefined;
+                    const duration = typeof res.call_length === 'number' ? Math.round(res.call_length) :
+                        typeof res.duration === 'number' ? Math.round(res.duration) :
+                            typeof res.duration_sec === 'number' ? Math.round(res.duration_sec) : undefined;
+                    const transcript = typeof res.concatenated_transcript === 'string' ? res.concatenated_transcript :
+                        typeof res.transcript === 'string' ? res.transcript : undefined;
+                    callLog().append({
+                        ...prior,
+                        timestamp: Date.now(),
+                        paid_usd: 0, // status polls are free; only the initial POST charges
+                        status: normalizeStatus(res.status ?? res.queue_status ?? res.disposition),
+                        duration_sec: duration ?? prior.duration_sec,
+                        transcript: transcript ?? prior.transcript,
+                        recording_url: recording ?? prior.recording_url,
+                    });
+                }
+            }
+            catch { /* best-effort */ }
+            return {
+                output: `## Voice call status\n\n` +
+                    '```json\n' + JSON.stringify(res, null, 2) + '\n```',
+            };
+        }
+        catch (err) {
+            return { output: `VoiceStatus failed: ${err.message}`, isError: true };
+        }
+    },
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@blockrun/franklin",
-  "version": "3.20.1",
+  "version": "3.21.0",
   "description": "Franklin Agent — The AI agent with a wallet. Spends USDC autonomously to get real work done. Pay per action, no subscriptions.",
   "type": "module",
   "exports": {