@blockrun/franklin 3.8.44 → 3.9.1

package/dist/skills/bootstrap.d.ts

@@ -0,0 +1,27 @@
+/**
+ * Boot-time helpers that wire the skills library into the running process:
+ *
+ * - `loadBundledSkills()` discovers `dist/skills-bundled/<name>/SKILL.md`
+ *   relative to this module's location and returns a populated Registry.
+ *   User-global and project-local discovery are deferred to Phase 2 of the
+ *   skills MVP plan; today we only ship the bundled set.
+ *
+ * - `getSkillVars()` returns the synchronously-known runtime variables
+ *   that `substituteVariables` injects into a skill body before
+ *   `$ARGUMENTS` expansion. Async values (wallet balance, on-chain reads)
+ *   are deferred to a later phase: those vars stay literal in the rendered
+ *   prompt and `substituteVariables` leaves unknown vars intact.
+ */
+import { Registry } from './registry.js';
+import type { LoadError } from './types.js';
+export interface BundledLoad {
+    registry: Registry;
+    errors: LoadError[];
+}
+export declare function loadBundledSkills(): BundledLoad;
+export interface SkillVarSource {
+    chain?: 'base' | 'solana';
+    /** Per-turn spend cap in USD; mirrors the `max-turn-spend-usd` config key. */
+    perTurnCapUsd?: number;
+}
+export declare function getSkillVars(src: SkillVarSource): Record<string, string>;

package/dist/skills/bootstrap.js

@@ -0,0 +1,40 @@
+/**
+ * Boot-time helpers that wire the skills library into the running process:
+ *
+ * - `loadBundledSkills()` discovers `dist/skills-bundled/<name>/SKILL.md`
+ *   relative to this module's location and returns a populated Registry.
+ *   User-global and project-local discovery are deferred to Phase 2 of the
+ *   skills MVP plan; today we only ship the bundled set.
+ *
+ * - `getSkillVars()` returns the synchronously-known runtime variables
+ *   that `substituteVariables` injects into a skill body before
+ *   `$ARGUMENTS` expansion. Async values (wallet balance, on-chain reads)
+ *   are deferred to a later phase: those vars stay literal in the rendered
+ *   prompt and `substituteVariables` leaves unknown vars intact.
+ */
+import { fileURLToPath } from 'node:url';
+import { dirname, join } from 'node:path';
+import { loadSkillsFromDir } from './loader.js';
+import { Registry } from './registry.js';
+const HERE = dirname(fileURLToPath(import.meta.url));
+// Built form lives at dist/skills/bootstrap.js, so dist/skills-bundled/
+// is one level up + sibling.
+const BUNDLED_DIR = join(HERE, '..', 'skills-bundled');
+export function loadBundledSkills() {
+    const result = loadSkillsFromDir(BUNDLED_DIR, 'bundled');
+    return { registry: Registry.fromLoaded(result.skills), errors: result.errors };
+}
+export function getSkillVars(src) {
+    const out = {};
+    if (src.chain)
+        out.wallet_chain = src.chain;
+    if (typeof src.perTurnCapUsd === 'number' && Number.isFinite(src.perTurnCapUsd)) {
+        const cap = src.perTurnCapUsd.toFixed(2);
+        out.per_turn_cap = cap;
+        // Skills run at turn boundary, so spent-this-turn is always zero at
+        // substitution time and remaining equals the cap.
+        out.spent_this_turn = '0.00';
+        out.turn_budget_remaining = cap;
+    }
+    return out;
+}

package/dist/skills/invoke.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Skill invocation helpers.
+ *
+ * `substituteVariables` is the only piece of the invocation path that runs
+ * for every skill: it inlines `{{wallet_balance}}` and similar runtime
+ * context, then expands `$ARGUMENTS` to the trailing slash-command argument.
+ *
+ * Both substitutions use function-form replacement so that values containing
+ * `$` or other replacement-pattern meta-characters (like a user task that
+ * mentions "find $5 of value") are inserted verbatim.
+ */
+export declare function substituteVariables(body: string, vars: Record<string, string>, args: string): string;
+import type { Registry } from './registry.js';
+export interface SkillMatch {
+    rewritten: string;
+}
+/**
+ * Pure dispatch: given a slash-command input line, look up the skill in the
+ * registry, render its body against runtime variables and arguments, and
+ * return the prompt the agent should run. Returns null when the input is
+ * not a slash command, the slash is bare, or no skill of that name exists.
+ */
+export declare function matchSkill(input: string, registry: Registry, vars: Record<string, string>): SkillMatch | null;

package/dist/skills/invoke.js

@@ -0,0 +1,38 @@
+/**
+ * Skill invocation helpers.
+ *
+ * `substituteVariables` is the only piece of the invocation path that runs
+ * for every skill: it inlines `{{wallet_balance}}` and similar runtime
+ * context, then expands `$ARGUMENTS` to the trailing slash-command argument.
+ *
+ * Both substitutions use function-form replacement so that values containing
+ * `$` or other replacement-pattern meta-characters (like a user task that
+ * mentions "find $5 of value") are inserted verbatim.
+ */
+const VAR_PATTERN = /\{\{(\w+)\}\}/g;
+export function substituteVariables(body, vars, args) {
+    const withVars = body.replace(VAR_PATTERN, (match, key) => {
+        return Object.prototype.hasOwnProperty.call(vars, key) ? vars[key] : match;
+    });
+    return withVars.replaceAll('$ARGUMENTS', () => args);
+}
+/**
+ * Pure dispatch: given a slash-command input line, look up the skill in the
+ * registry, render its body against runtime variables and arguments, and
+ * return the prompt the agent should run. Returns null when the input is
+ * not a slash command, the slash is bare, or no skill of that name exists.
+ */
+export function matchSkill(input, registry, vars) {
+    if (!input.startsWith('/'))
+        return null;
+    const space = input.indexOf(' ');
+    const name = (space < 0 ? input : input.slice(0, space)).slice(1);
+    if (name.length === 0)
+        return null;
+    const skill = registry.lookup(name);
+    if (!skill)
+        return null;
+    const args = space < 0 ? '' : input.slice(space + 1).trim();
+    const rewritten = substituteVariables(skill.skill.body, vars, args);
+    return { rewritten };
+}

package/dist/skills/loader.d.ts

@@ -0,0 +1,21 @@
+/**
+ * SKILL.md loader — parses Anthropic-spec frontmatter + markdown body.
+ *
+ * The frontmatter parser is intentionally minimal: flat `key: value` lines
+ * with scalar values (string, boolean, number). Quoted strings, nested
+ * objects, and arrays are out of scope for MVP — Anthropic's SKILL.md spec
+ * never needs them and adding a YAML dependency would be heavier than the
+ * spec warrants.
+ */
+import type { LoadResult, ParseResult, SkillSource } from './types.js';
+export declare function parseSkill(content: string): ParseResult;
+/**
+ * Discover and parse every `<dir>/<name>/SKILL.md` under `root`.
+ *
+ * Missing root → empty result, no error (callers happily union project +
+ * user + bundled, and absent dirs are normal).
+ *
+ * Parse failures on individual skills do not abort the load; they are
+ * surfaced via `LoadResult.errors` so the caller can warn the user.
+ */
+export declare function loadSkillsFromDir(root: string, source: SkillSource): LoadResult;

package/dist/skills/loader.js

@@ -0,0 +1,149 @@
+/**
+ * SKILL.md loader — parses Anthropic-spec frontmatter + markdown body.
+ *
+ * The frontmatter parser is intentionally minimal: flat `key: value` lines
+ * with scalar values (string, boolean, number). Quoted strings, nested
+ * objects, and arrays are out of scope for MVP — Anthropic's SKILL.md spec
+ * never needs them and adding a YAML dependency would be heavier than the
+ * spec warrants.
+ */
+import { readdirSync, readFileSync, statSync } from 'node:fs';
+import { join } from 'node:path';
+const FRONTMATTER_FENCE = '---';
+export function parseSkill(content) {
+    const fmMatch = extractFrontmatter(content);
+    if (!fmMatch) {
+        return { error: 'missing frontmatter (file must start with --- fence)' };
+    }
+    const { frontmatter, body } = fmMatch;
+    const parsedFrontmatter = parseFrontmatter(frontmatter);
+    if ('error' in parsedFrontmatter)
+        return { error: parsedFrontmatter.error };
+    const { fields, warnings } = parsedFrontmatter;
+    if (typeof fields.name !== 'string' || fields.name.length === 0) {
+        return { error: 'frontmatter missing required field: name' };
+    }
+    if (typeof fields.description !== 'string' || fields.description.length === 0) {
+        return { error: 'frontmatter missing required field: description' };
+    }
+    const skill = {
+        name: fields.name,
+        description: fields.description,
+        body,
+    };
+    if (typeof fields['argument-hint'] === 'string') {
+        skill.argumentHint = fields['argument-hint'];
+    }
+    if (typeof fields['disable-model-invocation'] === 'boolean') {
+        skill.disableModelInvocation = fields['disable-model-invocation'];
+    }
+    if (typeof fields['budget-cap-usd'] === 'number') {
+        skill.budgetCapUsd = fields['budget-cap-usd'];
+    }
+    if (typeof fields['cost-receipt'] === 'boolean') {
+        skill.costReceipt = fields['cost-receipt'];
+    }
+    return { skill, warnings };
+}
+function extractFrontmatter(content) {
+    const normalized = content.replace(/\r\n/g, '\n');
+    if (!normalized.startsWith(FRONTMATTER_FENCE + '\n'))
+        return null;
+    const rest = normalized.slice(FRONTMATTER_FENCE.length + 1);
+    const closeIdx = rest.indexOf('\n' + FRONTMATTER_FENCE + '\n');
+    if (closeIdx < 0)
+        return null;
+    const frontmatter = rest.slice(0, closeIdx);
+    const body = rest.slice(closeIdx + 1 + FRONTMATTER_FENCE.length + 1);
+    return { frontmatter, body };
+}
+function parseFrontmatter(text) {
+    const fields = {};
+    const warnings = [];
+    const lines = text.split('\n');
+    for (let i = 0; i < lines.length; i++) {
+        const line = lines[i];
+        if (line.trim() === '' || line.trim().startsWith('#'))
+            continue;
+        const colon = line.indexOf(':');
+        if (colon < 0) {
+            return { error: `frontmatter line ${i + 1} is not key: value — got "${line}"` };
+        }
+        const key = line.slice(0, colon).trim();
+        const rawValue = line.slice(colon + 1).trim();
+        if (key.length === 0) {
+            return { error: `frontmatter line ${i + 1} has empty key` };
+        }
+        fields[key] = parseScalar(rawValue);
+    }
+    return { fields, warnings };
+}
+/**
+ * Discover and parse every `<dir>/<name>/SKILL.md` under `root`.
+ *
+ * Missing root → empty result, no error (callers happily union project +
+ * user + bundled, and absent dirs are normal).
+ *
+ * Parse failures on individual skills do not abort the load; they are
+ * surfaced via `LoadResult.errors` so the caller can warn the user.
+ */
+export function loadSkillsFromDir(root, source) {
+    const result = { skills: [], errors: [] };
+    let entries;
+    try {
+        entries = readdirSync(root);
+    }
+    catch {
+        return result;
+    }
+    for (const entry of entries) {
+        const dirPath = join(root, entry);
+        let entryStat;
+        try {
+            entryStat = statSync(dirPath);
+        }
+        catch {
+            continue;
+        }
+        if (!entryStat.isDirectory())
+            continue;
+        const skillPath = join(dirPath, 'SKILL.md');
+        let content;
+        try {
+            content = readFileSync(skillPath, 'utf8');
+        }
+        catch {
+            continue;
+        }
+        const parsed = parseSkill(content);
+        if ('error' in parsed) {
+            result.errors.push({ path: skillPath, error: parsed.error });
+            continue;
+        }
+        const warnings = [...parsed.warnings];
+        let skill = parsed.skill;
+        if (skill.name !== entry) {
+            warnings.push(`frontmatter name "${skill.name}" disagrees with directory "${entry}"; using directory name`);
+            skill = { ...skill, name: entry };
+        }
+        const loaded = { skill, source, path: skillPath, warnings };
+        result.skills.push(loaded);
+    }
+    return result;
+}
+function parseScalar(raw) {
+    if (raw === 'true')
+        return true;
+    if (raw === 'false')
+        return false;
+    if (/^-?\d+$/.test(raw))
+        return Number.parseInt(raw, 10);
+    if (/^-?\d+\.\d+$/.test(raw))
+        return Number.parseFloat(raw);
+    // Strip surrounding quotes if present.
+    if ((raw.startsWith('"') && raw.endsWith('"') && raw.length >= 2) ||
+        (raw.startsWith("'") && raw.endsWith("'") && raw.length >= 2)) {
+        return raw.slice(1, -1);
+    }
+    return raw;
+}

package/dist/skills/registry.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Skill registry — resolves name conflicts across sources and exposes
+ * lookup, list, and shadow-set queries for `/help` and
+ * `franklin skills list`.
+ *
+ * Precedence: project > user > bundled. Within the same source, the first
+ * loaded skill wins so that the order returned by the loader (which is
+ * filesystem-ordered) is the deterministic tiebreaker the user can rely on.
+ *
+ * Built-in slash commands (e.g. `/security`) take precedence over skills
+ * with the same name, but that check happens at the dispatch layer in
+ * `src/agent/commands.ts`. The registry never sees the built-in list.
+ */
+import type { LoadedSkill } from './types.js';
+export interface ShadowEntry {
+    winner: LoadedSkill;
+    loser: LoadedSkill;
+}
+export declare class Registry {
+    private readonly byName;
+    private readonly shadows;
+    static fromLoaded(loaded: LoadedSkill[]): Registry;
+    lookup(name: string): LoadedSkill | undefined;
+    list(): LoadedSkill[];
+    shadowed(): ShadowEntry[];
+}

package/dist/skills/registry.js

@@ -0,0 +1,54 @@
+/**
+ * Skill registry — resolves name conflicts across sources and exposes
+ * lookup, list, and shadow-set queries for `/help` and
+ * `franklin skills list`.
+ *
+ * Precedence: project > user > bundled. Within the same source, the first
+ * loaded skill wins so that the order returned by the loader (which is
+ * filesystem-ordered) is the deterministic tiebreaker the user can rely on.
+ *
+ * Built-in slash commands (e.g. `/security`) take precedence over skills
+ * with the same name, but that check happens at the dispatch layer in
+ * `src/agent/commands.ts`. The registry never sees the built-in list.
+ */
+const SOURCE_PRIORITY = {
+    project: 3,
+    user: 2,
+    bundled: 1,
+};
+export class Registry {
+    byName = new Map();
+    shadows = [];
+    static fromLoaded(loaded) {
+        const reg = new Registry();
+        // Stable sort by source priority (desc); ties broken by original order
+        // so that within a single source, the first-loaded skill wins.
+        const indexed = loaded.map((l, i) => ({ l, i }));
+        indexed.sort((a, b) => {
+            const pa = SOURCE_PRIORITY[a.l.source];
+            const pb = SOURCE_PRIORITY[b.l.source];
+            if (pa !== pb)
+                return pb - pa;
+            return a.i - b.i;
+        });
+        for (const { l } of indexed) {
+            const existing = reg.byName.get(l.skill.name);
+            if (!existing) {
+                reg.byName.set(l.skill.name, l);
+            }
+            else {
+                reg.shadows.push({ winner: existing, loser: l });
+            }
+        }
+        return reg;
+    }
+    lookup(name) {
+        return this.byName.get(name);
+    }
+    list() {
+        return [...this.byName.values()].sort((a, b) => a.skill.name.localeCompare(b.skill.name));
+    }
+    shadowed() {
+        return [...this.shadows];
+    }
+}

package/dist/skills/types.d.ts

@@ -0,0 +1,47 @@
+/**
+ * Public types for Franklin's skills layer.
+ *
+ * A "skill" is an Anthropic-spec SKILL.md file: YAML frontmatter + a markdown
+ * body that becomes the prompt-rewrite for a slash command. See
+ * docs/plans/2026-04-29-franklin-skills-mvp-design.md.
+ */
+export type SkillSource = 'bundled' | 'user' | 'project';
+export interface ParsedSkill {
+    /** Kebab-case skill identifier; matches the parent directory name. */
+    name: string;
+    /** Short description shown in /help and franklin skills list. */
+    description: string;
+    /** Raw markdown body (not yet variable-substituted). */
+    body: string;
+    /** Anthropic spec: hint shown after the slash command. */
+    argumentHint?: string;
+    /** Anthropic spec: when true, the model must not auto-invoke this skill. */
+    disableModelInvocation?: boolean;
+    /** Franklin extension: hard cap (USD) for the turn this skill kicks off. */
+    budgetCapUsd?: number;
+    /** Franklin extension: append a paid-call receipt under the agent reply. */
+    costReceipt?: boolean;
+}
+export type ParseResult = {
+    skill: ParsedSkill;
+    warnings: string[];
+} | {
+    error: string;
+};
+export interface LoadedSkill {
+    skill: ParsedSkill;
+    source: SkillSource;
+    /** Absolute path to the SKILL.md file. */
+    path: string;
+    /** Non-fatal warnings raised while loading this skill. */
+    warnings: string[];
+}
+export interface LoadError {
+    /** Absolute path to the file that failed. */
+    path: string;
+    error: string;
+}
+export interface LoadResult {
+    skills: LoadedSkill[];
+    errors: LoadError[];
+}

package/dist/skills/types.js

@@ -0,0 +1,8 @@
+/**
+ * Public types for Franklin's skills layer.
+ *
+ * A "skill" is an Anthropic-spec SKILL.md file: YAML frontmatter + a markdown
+ * body that becomes the prompt-rewrite for a slash command. See
+ * docs/plans/2026-04-29-franklin-skills-mvp-design.md.
+ */
+export {};

package/dist/skills-bundled/budget-grill/SKILL.md

@@ -0,0 +1,24 @@
+---
+name: budget-grill
+description: Wallet-aware grilling — interview me about a plan one question at a time, with each branch of the decision tree framed as a USDC cost impact
+argument-hint: <plan or topic to grill on>
+cost-receipt: true
+---
+
+You are running inside Franklin, an Economic Agent powered by an x402 USDC wallet on {{wallet_chain}}. The user has set a per-turn spend cap of {{per_turn_cap}} USDC, of which {{spent_this_turn}} has been spent so far ({{turn_budget_remaining}} remaining).
+
+Your job: interview the user relentlessly about the plan below, **one question at a time**, until you reach a shared understanding of every branch of the decision tree. For every question, also propose your recommended answer and the reasoning behind it.
+
+The thing that makes this skill different from a generic grilling session: **frame every option in cost terms**. For each branch, estimate the USDC spend per call/run/cycle, the model tier it would land on, and the worst-case wallet drain over the lifetime of the feature. If the option spends $0 because it's free-tier, say so explicitly. If it depends on a paid tool (`ExaSearch`, `ImageGen`, `VideoGen`, `MusicGen`, `TradingMarket` paid actions), name the tool and estimate the per-call cost.
+
+Rules of engagement:
+
+1. **One question per response.** Do not stack questions.
+2. **Walk down the decision tree.** Resolve dependencies between decisions one by one — a question that depends on the answer to another comes later.
+3. **Recommend an answer.** Every question carries your recommendation + the cost-impact reasoning behind it.
+4. **Cross-reference the codebase.** If a question can be answered by reading the code, read the code instead of asking. Use `Read`, `Grep`, `Glob`. The user's time is more expensive than tool calls.
+5. **Stop at saturation, not exhaustion.** When the marginal next question stops uncovering new cost trade-offs or design decisions, propose the agreed plan back to the user as a numbered summary, with each step's projected cost and the running total.
+
+The plan or topic to grill on:
+
+$ARGUMENTS

package/dist/tools/index.js

@@ -23,6 +23,7 @@ import { searchXCapability } from './searchx.js';
 import { postToXCapability } from './posttox.js';
 import { moaCapability } from './moa.js';
 import { webhookPostCapability } from './webhook.js';
+import { walletCapability } from './wallet.js';
 import { createTradingCapabilities } from './trading-execute.js';
 import { Portfolio } from '../trading/portfolio.js';
 import { RiskEngine } from '../trading/risk.js';
@@ -140,6 +141,7 @@ export const allCapabilities = [
     postToXCapability,
     moaCapability,
     webhookPostCapability,
+    walletCapability,
 ];
 export { readCapability, writeCapability, editCapability, bashCapability, globCapability, grepCapability, webFetchCapability, webSearchCapability, taskCapability, };
 export { createSubAgentCapability } from './subagent.js';

package/dist/tools/moa.js

@@ -14,14 +14,14 @@ import { ModelClient } from '../agent/llm.js';
 // ─── Configuration ────────────────────────────────────────────────────────
 /** Reference models — diverse, cheap/free models for parallel queries. */
 const REFERENCE_MODELS = [
-    'nvidia/glm-4.7', // Free, strong reasoning + coding
-    'nvidia/qwen3-next-80b-a3b-thinking', // Free, explicit reasoning model
-    'nvidia/qwen3-coder-480b', // Free, strong coding
+    'nvidia/qwen3-coder-480b', // Free, agent-tested coding
+    'nvidia/llama-4-maverick', // Free, agent-tested general chat
+    'nvidia/glm-4.7', // Free chat fallback
     'google/gemini-2.5-flash', // Fast, cheap
     'deepseek/deepseek-chat', // Cheap, good reasoning
 ];
 /** Aggregator model — free by default. Users explicitly pass `aggregator` to upgrade. */
-const AGGREGATOR_MODEL = 'nvidia/glm-4.7';
+const AGGREGATOR_MODEL = 'nvidia/qwen3-coder-480b';
 /** Max tokens per reference response. */
 const REFERENCE_MAX_TOKENS = 4096;
 /** Max tokens for aggregator. */

package/dist/tools/subagent.js

@@ -18,7 +18,7 @@ async function execute(input, ctx) {
         return { output: 'Error: prompt is required', isError: true };
     }
     // Resolve which model the sub-agent will actually run on
-    const subModel = model || registeredParentModel || 'nvidia/glm-4.7';
+    const subModel = model || registeredParentModel || 'nvidia/qwen3-coder-480b';
     // Cost gate: if parent is free but sub-agent wants paid, ask user first.
     // Prevents silent charges when the agent decides to spawn a more capable sub-agent.
     if (isFreeModel(registeredParentModel) && !isFreeModel(subModel)) {
@@ -27,14 +27,14 @@ async function execute(input, ctx) {
             // No way to prompt the user (daemon/panel/non-interactive mode).
             // Fail closed — refuse the paid spawn rather than silently charging.
             return {
-                output: `Sub-agent declined: parent is on a free model but sub-agent requested a paid model (${shortLabel}). No interactive prompt available. Retry with model='nemotron' or run interactively to approve.`,
+                output: `Sub-agent declined: parent is on a free model but sub-agent requested a paid model (${shortLabel}). No interactive prompt available. Retry with model='free' or run interactively to approve.`,
                 isError: true,
             };
         }
         const answer = await ctx.onAskUser(`Sub-agent wants to use ${shortLabel} (paid). Approve?`, ['y', 'n']);
         if (answer.toLowerCase() !== 'y' && answer.toLowerCase() !== 'yes') {
             return {
-                output: `Sub-agent skipped — user declined paid model (${shortLabel}). Retry with a free model like nemotron.`,
+                output: `Sub-agent skipped — user declined paid model (${shortLabel}). Retry with a free model like free.`,
                 isError: true,
             };
         }

package/dist/tools/tool-categories.js

@@ -50,6 +50,9 @@ export const CORE_TOOL_NAMES = new Set([
     // enough that every model tends to pick it correctly.
     'WebFetch',
     'WebSearch',
+    // Wallet read — Franklin is the agent with a wallet, so balance + chain
+    // + address must be a one-call answer rather than a Bash shell-out.
+    'Wallet',
 ]);
 /** True if this tool is always available without activation. */
 export function isCoreTool(name) {

package/dist/tools/wallet.d.ts

@@ -0,0 +1,23 @@
+/**
+ * Wallet capability — direct read of Franklin's wallet status.
+ *
+ * Why this exists as a first-class tool: without it, "what's my balance"
+ * routes through Bash (`franklin balance`) plus parsing, which costs both
+ * extra tool turns and ~1KB of bash-tool framing in the model's input
+ * window every turn. With Wallet as a dedicated zero-arg tool, the agent
+ * can answer balance questions in one cheap call. It also preserves the
+ * Economic-Agent positioning: the wallet is a first-class concept, not a
+ * shell command.
+ *
+ * Bash is still available for non-trivial wallet operations (sending,
+ * signing arbitrary tx) — Wallet is read-only by design.
+ */
+import type { CapabilityHandler } from '../agent/types.js';
+export interface WalletReportInput {
+    chain: 'base' | 'solana';
+    address: string;
+    balanceUsd: number;
+}
+/** Pure formatter — small, deterministic, easy to unit-test. */
+export declare function formatWalletReport(input: WalletReportInput): string;
+export declare const walletCapability: CapabilityHandler;

package/dist/tools/wallet.js

@@ -0,0 +1,63 @@
+/**
+ * Wallet capability — direct read of Franklin's wallet status.
+ *
+ * Why this exists as a first-class tool: without it, "what's my balance"
+ * routes through Bash (`franklin balance`) plus parsing, which costs both
+ * extra tool turns and ~1KB of bash-tool framing in the model's input
+ * window every turn. With Wallet as a dedicated zero-arg tool, the agent
+ * can answer balance questions in one cheap call. It also preserves the
+ * Economic-Agent positioning: the wallet is a first-class concept, not a
+ * shell command.
+ *
+ * Bash is still available for non-trivial wallet operations (sending,
+ * signing arbitrary tx) — Wallet is read-only by design.
+ */
+import { loadChain } from '../config.js';
+/** Pure formatter — small, deterministic, easy to unit-test. */
+export function formatWalletReport(input) {
+    return [
+        `Chain: ${input.chain}`,
+        `Address: ${input.address}`,
+        `USDC Balance: $${input.balanceUsd.toFixed(2)}`,
+    ].join('\n');
+}
+async function execute() {
+    const chain = loadChain();
+    try {
+        if (chain === 'solana') {
+            const { setupAgentSolanaWallet } = await import('@blockrun/llm');
+            const c = await setupAgentSolanaWallet({ silent: true });
+            const address = await c.getWalletAddress();
+            const balance = await c.getBalance();
+            return { output: formatWalletReport({ chain, address, balanceUsd: balance }) };
+        }
+        const { setupAgentWallet } = await import('@blockrun/llm');
+        const c = setupAgentWallet({ silent: true });
+        const address = c.getWalletAddress();
+        const balance = await c.getBalance();
+        return { output: formatWalletReport({ chain, address, balanceUsd: balance }) };
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        return {
+            output: `Wallet read failed (${msg}). The user may not have run \`franklin setup\` yet, ` +
+                `or the chain RPC is temporarily unreachable. Surface this to the user as-is.`,
+            isError: true,
+        };
+    }
+}
+export const walletCapability = {
+    spec: {
+        name: 'Wallet',
+        description: 'Read Franklin\'s wallet status — chain, address, and USDC balance. ' +
+            'Use this for any "what\'s my balance / how much money / 钱包余额 / wallet status" question. ' +
+            'Cheaper and more direct than running `franklin balance` via Bash, and never costs USDC.',
+        input_schema: {
+            type: 'object',
+            properties: {},
+            additionalProperties: false,
+        },
+    },
+    execute,
+    concurrent: true,
+};