@kaleidorg/mind 0.0.1 → 0.1.0

package/dist/skills/types.d.ts

@@ -0,0 +1,53 @@
+/**
+ * Skills — Claude-style Agent Skills the brain can "enter".
+ *
+ * A skill is the top layer of tool use: a folder with a `SKILL.md` (YAML
+ * frontmatter + a markdown playbook) and optional `references/*.md` files that
+ * are loaded on demand. Entering a skill injects its playbook into the system
+ * prompt and (optionally) scopes the agent to a subset of tools. The tools are
+ * still invoked via function calling and may be backed by in-process handlers
+ * or MCP servers — skills don't replace those, they *direct* them.
+ *
+ * This is progressive disclosure, the core idea behind Anthropic's Agent Skills:
+ * a small local model never sees every tool or instruction at once — only the
+ * selected skill's playbook, and it can pull a reference file in when it needs
+ * the detail. The format is compatible with skills published for Claude (e.g.
+ * `bitrefill/agents`), so the same SKILL.md runs the QVAC brain unchanged.
+ */
+/** A reference file (references/*.md) the agent can read on demand. */
+export interface SkillReference {
+    /** Filename, e.g. "mcp.md". */
+    name: string;
+    /** Markdown contents. */
+    content: string;
+}
+export interface Skill {
+    /** Stable id, e.g. "bitrefill" / "portfolio-manager". */
+    name: string;
+    /**
+     * "When to use this" — the spec's selection signal. May be long and embed the
+     * trigger phrases ("…Triggers when the user mentions gift cards, eSIM…").
+     */
+    description: string;
+    /** The playbook: markdown instructions injected into the system prompt. */
+    instructions: string;
+    /**
+     * Tool names this skill is allowed to use. When set, the engine exposes only
+     * these tools while the skill is active (progressive disclosure). Omit to
+     * allow all registered tools (the default for capability-routing skills).
+     */
+    tools?: string[];
+    /** Optional trigger keywords to boost selection (in addition to description). */
+    triggers?: string[];
+    /** Remaining frontmatter (compatibility, author, version, homepage, …). */
+    metadata?: Record<string, string>;
+    /** Reference files (references/*.md) for progressive disclosure. */
+    references?: SkillReference[];
+    /** Source folder, when loaded from disk (Node). */
+    dir?: string;
+}
+/** Picks the most relevant skill for a query (or null for none). */
+export interface SkillSelector {
+    select(query: string, skills: Skill[]): Skill | null;
+}
+//# sourceMappingURL=types.d.ts.map

package/dist/skills/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAEH,uEAAuE;AACvE,MAAM,WAAW,cAAc;IAC7B,+BAA+B;IAC/B,IAAI,EAAE,MAAM,CAAC;IACb,yBAAyB;IACzB,OAAO,EAAE,MAAM,CAAC;CACjB;AAED,MAAM,WAAW,KAAK;IACpB,yDAAyD;IACzD,IAAI,EAAE,MAAM,CAAC;IACb;;;OAGG;IACH,WAAW,EAAE,MAAM,CAAC;IACpB,2EAA2E;IAC3E,YAAY,EAAE,MAAM,CAAC;IACrB;;;;OAIG;IACH,KAAK,CAAC,EAAE,MAAM,EAAE,CAAC;IACjB,iFAAiF;IACjF,QAAQ,CAAC,EAAE,MAAM,EAAE,CAAC;IACpB,2EAA2E;IAC3E,QAAQ,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;IAClC,oEAAoE;IACpE,UAAU,CAAC,EAAE,cAAc,EAAE,CAAC;IAC9B,mDAAmD;IACnD,GAAG,CAAC,EAAE,MAAM,CAAC;CACd;AAED,oEAAoE;AACpE,MAAM,WAAW,aAAa;IAC5B,MAAM,CAAC,KAAK,EAAE,MAAM,EAAE,MAAM,EAAE,KAAK,EAAE,GAAG,KAAK,GAAG,IAAI,CAAC;CACtD"}

package/dist/skills/types.js

@@ -0,0 +1,18 @@
+/**
+ * Skills — Claude-style Agent Skills the brain can "enter".
+ *
+ * A skill is the top layer of tool use: a folder with a `SKILL.md` (YAML
+ * frontmatter + a markdown playbook) and optional `references/*.md` files that
+ * are loaded on demand. Entering a skill injects its playbook into the system
+ * prompt and (optionally) scopes the agent to a subset of tools. The tools are
+ * still invoked via function calling and may be backed by in-process handlers
+ * or MCP servers — skills don't replace those, they *direct* them.
+ *
+ * This is progressive disclosure, the core idea behind Anthropic's Agent Skills:
+ * a small local model never sees every tool or instruction at once — only the
+ * selected skill's playbook, and it can pull a reference file in when it needs
+ * the detail. The format is compatible with skills published for Claude (e.g.
+ * `bitrefill/agents`), so the same SKILL.md runs the QVAC brain unchanged.
+ */
+export {};
+//# sourceMappingURL=types.js.map

package/dist/skills/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/skills/types.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG"}

package/dist/tools/l402.d.ts

@@ -0,0 +1,47 @@
+/**
+ * L402 tool source — lets the agent pay for paywalled HTTP resources in sats.
+ *
+ * Exposes one tool, `fetch_paid_resource(url)`, that runs the L402 flow:
+ *   GET url → 402 with an L402 challenge (macaroon + Lightning invoice)
+ *   → pay the invoice (via the injected `payInvoice`, e.g. the on-device wallet)
+ *   → re-GET with `Authorization: L402 <macaroon>:<preimage>` → return the body.
+ *
+ * This is the "agent pays for a tool in sats" capability: any KaleidoMind agent
+ * (mobile or desktop) can buy premium data / inference autonomously. Payment
+ * runs through the host's wallet, so it stays on-device; the engine's
+ * confirmation gate can wrap the spend if desired.
+ *
+ * No dependencies — uses global fetch (Node ≥18, React Native). The fetch impl
+ * is injectable for testing.
+ */
+import type { ToolSource } from './source.js';
+export interface L402PayResult {
+    /** Payment preimage (hex) — proves the invoice was paid. */
+    preimage: string;
+}
+export interface L402Options {
+    /** Pay a BOLT11 invoice, resolve with the preimage. Wallet on device; mock in tests. */
+    payInvoice: (invoice: string, amountSats: number) => Promise<L402PayResult>;
+    /** Override fetch (tests). Defaults to global fetch. */
+    fetchImpl?: typeof fetch;
+    /** Optional progress logging. */
+    log?: (msg: string) => void;
+    /**
+     * Gate the tool behind the engine's confirmation (default true). The catch:
+     * the invoice amount is only known DURING execution (the 402 challenge), so a
+     * pre-execution confirmation can't show it. On hosts without a dedicated L402
+     * confirmation UX, set this false and bound spending with `maxAutoPaySats`.
+     */
+    requiresConfirmation?: boolean;
+    /** Auto-pay only invoices up to this many sats; reject larger ones. */
+    maxAutoPaySats?: number;
+}
+/** Parse an L402 (or legacy LSAT) WWW-Authenticate challenge. */
+export declare function parseL402Challenge(header: string): {
+    macaroon: string;
+    invoice: string;
+} | null;
+/** Rough BOLT11 amount → sats (for logging / spend caps). 0 if unparseable. */
+export declare function bolt11AmountSats(invoice: string): number;
+export declare function createL402ToolSource(opts: L402Options): ToolSource;
+//# sourceMappingURL=l402.d.ts.map

package/dist/tools/l402.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"l402.d.ts","sourceRoot":"","sources":["../../src/tools/l402.ts"],"names":[],"mappings":"AAAA;;;;;;;;;;;;;;;GAeG;AAGH,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,aAAa,CAAC;AAE9C,MAAM,WAAW,aAAa;IAC5B,4DAA4D;IAC5D,QAAQ,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,WAAW;IAC1B,wFAAwF;IACxF,UAAU,EAAE,CAAC,OAAO,EAAE,MAAM,EAAE,UAAU,EAAE,MAAM,KAAK,OAAO,CAAC,aAAa,CAAC,CAAC;IAC5E,wDAAwD;IACxD,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;IACzB,iCAAiC;IACjC,GAAG,CAAC,EAAE,CAAC,GAAG,EAAE,MAAM,KAAK,IAAI,CAAC;IAC5B;;;;;OAKG;IACH,oBAAoB,CAAC,EAAE,OAAO,CAAC;IAC/B,uEAAuE;IACvE,cAAc,CAAC,EAAE,MAAM,CAAC;CACzB;AAED,iEAAiE;AACjE,wBAAgB,kBAAkB,CAAC,MAAM,EAAE,MAAM,GAAG;IAAE,QAAQ,EAAE,MAAM,CAAC;IAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAAG,IAAI,CAI/F;AAED,+EAA+E;AAC/E,wBAAgB,gBAAgB,CAAC,OAAO,EAAE,MAAM,GAAG,MAAM,CAOxD;AAED,wBAAgB,oBAAoB,CAAC,IAAI,EAAE,WAAW,GAAG,UAAU,CA6DlE"}

package/dist/tools/l402.js

@@ -0,0 +1,84 @@
+/**
+ * L402 tool source — lets the agent pay for paywalled HTTP resources in sats.
+ *
+ * Exposes one tool, `fetch_paid_resource(url)`, that runs the L402 flow:
+ *   GET url → 402 with an L402 challenge (macaroon + Lightning invoice)
+ *   → pay the invoice (via the injected `payInvoice`, e.g. the on-device wallet)
+ *   → re-GET with `Authorization: L402 <macaroon>:<preimage>` → return the body.
+ *
+ * This is the "agent pays for a tool in sats" capability: any KaleidoMind agent
+ * (mobile or desktop) can buy premium data / inference autonomously. Payment
+ * runs through the host's wallet, so it stays on-device; the engine's
+ * confirmation gate can wrap the spend if desired.
+ *
+ * No dependencies — uses global fetch (Node ≥18, React Native). The fetch impl
+ * is injectable for testing.
+ */
+/** Parse an L402 (or legacy LSAT) WWW-Authenticate challenge. */
+export function parseL402Challenge(header) {
+    const macaroon = header.match(/macaroon="([^"]+)"/i)?.[1];
+    const invoice = header.match(/invoice="([^"]+)"/i)?.[1];
+    return macaroon && invoice ? { macaroon, invoice } : null;
+}
+/** Rough BOLT11 amount → sats (for logging / spend caps). 0 if unparseable. */
+export function bolt11AmountSats(invoice) {
+    const m = invoice.match(/^ln(?:bc|tb|bcrt)(\d+)([munp]?)/i);
+    if (!m)
+        return 0;
+    const n = Number(m[1]);
+    const mult = (m[2] || '').toLowerCase();
+    const btc = mult === 'm' ? n / 1e3 : mult === 'u' ? n / 1e6 : mult === 'n' ? n / 1e9 : mult === 'p' ? n / 1e12 : n;
+    return Math.round(btc * 1e8);
+}
+export function createL402ToolSource(opts) {
+    const doFetch = opts.fetchImpl ?? fetch;
+    const tool = {
+        name: 'fetch_paid_resource',
+        description: 'Fetch a paywalled (L402) HTTP resource, automatically paying the required ' +
+            'Lightning invoice in sats. Use this for premium or paid APIs (market data, ' +
+            'inference, etc.). Pass the resource URL.',
+        parameters: {
+            type: 'object',
+            properties: { url: { type: 'string', description: 'The resource URL to fetch' } },
+            required: ['url'],
+        },
+        requiresConfirmation: opts.requiresConfirmation ?? true,
+    };
+    async function execute(_name, args) {
+        const url = String(args.url ?? '');
+        if (!url)
+            throw new Error('fetch_paid_resource: url is required');
+        let res = await doFetch(url);
+        if (res.status === 402) {
+            const challenge = parseL402Challenge(res.headers.get('www-authenticate') ?? '');
+            if (!challenge)
+                throw new Error('402 Payment Required but no L402 challenge present');
+            const amountSats = bolt11AmountSats(challenge.invoice) || Number(res.headers.get('x-amount-sats') ?? 0);
+            if (opts.maxAutoPaySats != null && amountSats > opts.maxAutoPaySats) {
+                throw new Error(`L402 invoice is ${amountSats} sats, above the ${opts.maxAutoPaySats} sat auto-pay cap — declined`);
+            }
+            opts.log?.(`L402: ${url} requires ${amountSats} sats — paying…`);
+            const { preimage } = await opts.payInvoice(challenge.invoice, amountSats);
+            res = await doFetch(url, {
+                headers: { Authorization: `L402 ${challenge.macaroon}:${preimage}` },
+            });
+            opts.log?.(`L402: paid ${amountSats} sats → ${res.status}`);
+        }
+        if (!res.ok)
+            throw new Error(`fetch_paid_resource: ${res.status} ${res.statusText}`);
+        const body = await res.text();
+        try {
+            return JSON.parse(body);
+        }
+        catch {
+            return body;
+        }
+    }
+    return {
+        id: 'l402',
+        listTools: () => [tool],
+        has: (name) => name === tool.name,
+        execute,
+    };
+}
+//# sourceMappingURL=l402.js.map

package/dist/tools/l402.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"l402.js","sourceRoot":"","sources":["../../src/tools/l402.ts"],"names":[],"mappings":"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"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@kaleidorg/mind",
-  "version": "0.0.1",
+  "version": "0.1.0",
   "description": "Local-first reasoning + function-calling engine for KaleidoSwap. QVAC-powered.",
   "license": "Apache-2.0",
   "type": "module",
@@ -23,6 +23,10 @@
       "import": "./dist/tools/mcp.js",
       "types": "./dist/tools/mcp.d.ts"
     },
+    "./skills": {
+      "import": "./dist/skills/loader.js",
+      "types": "./dist/skills/loader.d.ts"
+    },
     "./logger": {
       "import": "./dist/logger.js",
       "types": "./dist/logger.d.ts"
@@ -31,6 +35,8 @@
   "files": [
     "dist",
     "src",
+    "skills",
+    "scripts",
     "README.md",
     "LICENSE"
   ],
@@ -38,7 +44,8 @@
     "build": "tsc",
     "typecheck": "tsc --noEmit",
     "test": "vitest run",
-    "lint": "eslint src"
+    "lint": "eslint src",
+    "bundle-skills": "node scripts/bundle-skills.mjs"
   },
   "devDependencies": {
     "vitest": "^1.6.0"

package/scripts/bundle-skills.mjs

@@ -0,0 +1,84 @@
+#!/usr/bin/env node
+/**
+ * bundle-skills — serialise one or more skill directories into a SkillBundle
+ * JSON file, so hosts without a filesystem (React Native) can load the same
+ * SKILL.md skills the Node fs loader reads.
+ *
+ * Usage:
+ *   node bundle-skills.mjs --out <file.json> <skills-dir> [<more-dirs>...]
+ *
+ * Example (mobile: ship the packaged bitrefill skill + the app's own skills):
+ *   node bundle-skills.mjs --out ./skills.bundle.json \
+ *     node_modules/@kaleidorg/mind/skills/bitrefill ./skills
+ *
+ * Each positional arg may be either a single skill folder (contains SKILL.md)
+ * or a parent folder of skill folders. References under <skill>/references/*.md
+ * are inlined. The output matches the `SkillBundle` type in src/skills/bundle.ts.
+ */
+
+import { readdirSync, readFileSync, existsSync, writeFileSync, statSync } from 'node:fs';
+import { join, basename } from 'node:path';
+
+function parseArgs(argv) {
+  const dirs = [];
+  let out = null;
+  for (let i = 0; i < argv.length; i++) {
+    if (argv[i] === '--out') out = argv[++i];
+    else dirs.push(argv[i]);
+  }
+  if (!out || dirs.length === 0) {
+    console.error('usage: bundle-skills.mjs --out <file.json> <skills-dir> [<more-dirs>...]');
+    process.exit(2);
+  }
+  return { out, dirs };
+}
+
+function readSkillFolder(dir) {
+  const md = join(dir, 'SKILL.md');
+  if (!existsSync(md)) return null;
+  const refDir = join(dir, 'references');
+  const references = existsSync(refDir)
+    ? readdirSync(refDir)
+        .filter((f) => f.endsWith('.md'))
+        .sort()
+        .map((name) => ({ name, content: readFileSync(join(refDir, name), 'utf8') }))
+    : [];
+  return {
+    dir: basename(dir),
+    markdown: readFileSync(md, 'utf8'),
+    ...(references.length ? { references } : {}),
+  };
+}
+
+/** Expand a path into skill folders: itself if it has a SKILL.md, else its children. */
+function collectSkillDirs(path) {
+  if (!existsSync(path)) {
+    console.error(`bundle-skills: path not found: ${path}`);
+    return [];
+  }
+  if (existsSync(join(path, 'SKILL.md'))) return [path];
+  return readdirSync(path)
+    .map((e) => join(path, e))
+    .filter((p) => statSync(p).isDirectory() && existsSync(join(p, 'SKILL.md')))
+    .sort();
+}
+
+const { out, dirs } = parseArgs(process.argv.slice(2));
+const seen = new Set();
+const skills = [];
+for (const arg of dirs) {
+  for (const skillDir of collectSkillDirs(arg)) {
+    const s = readSkillFolder(skillDir);
+    if (!s) continue;
+    if (seen.has(s.dir)) {
+      console.error(`bundle-skills: duplicate skill folder "${s.dir}" — skipping ${skillDir}`);
+      continue;
+    }
+    seen.add(s.dir);
+    skills.push(s);
+  }
+}
+
+const bundle = { version: 1, skills };
+writeFileSync(out, JSON.stringify(bundle, null, 2));
+console.error(`bundle-skills: wrote ${skills.length} skill(s) → ${out} [${skills.map((s) => s.dir).join(', ')}]`);

package/skills/README.md

@@ -0,0 +1,74 @@
+# Skills
+
+Claude-style **Agent Skills** the KaleidoMind brain (QVAC) loads at runtime.
+Skills are the top layer of tool use: entering one injects a focused playbook
+into the system prompt and (optionally) scopes the model to a subset of tools —
+*progressive disclosure*, so a small local model never sees every tool or
+instruction at once.
+
+Each subfolder is a skill: a `SKILL.md` (YAML frontmatter + playbook) plus
+optional `references/*.md` files loaded on demand. The format is the Anthropic
+Agent Skills spec, so skills published for Claude (e.g. `bitrefill/agents`) run
+the QVAC brain unchanged.
+
+## Frontmatter
+
+```yaml
+---
+name: my-skill                 # required — stable id
+description: When to use this…  # required — selection signal (embed triggers here)
+tools: tool_a, tool_b          # optional — scope the model to these tools
+triggers: foo, bar             # optional — keywords that boost selection
+metadata:                      # optional — anything else (author, version, …)
+  author: kaleidoswap
+---
+# Playbook
+Markdown instructions injected into the system prompt when this skill is active.
+```
+
+## Loading (same skills, every surface)
+
+**Node** (desktop sidecar, kaleidoagent) — read folders from disk:
+
+```ts
+import { loadSkillsDir, packagedSkillsDir } from '@kaleidorg/mind/skills';
+import { SkillRegistry, createSkillReferenceToolSource } from '@kaleidorg/mind';
+
+const skills = loadSkillsDir(packagedSkillsDir());   // these shipped skills
+const registry = new SkillRegistry(skills);
+const refSource = createSkillReferenceToolSource(registry); // read_skill_reference
+```
+
+**React Native** (rate) — no filesystem, so bundle the folders to JSON at build
+time and rehydrate:
+
+```bash
+node node_modules/@kaleidorg/mind/scripts/bundle-skills.mjs \
+  --out skills.bundle.json ./skills
+```
+```ts
+import { SkillRegistry, skillsFromBundle } from '@kaleidorg/mind';
+import bundle from './skills.bundle.json';
+const registry = new SkillRegistry(skillsFromBundle(bundle));
+```
+
+Then per query: `const skill = registry.select(query)` →
+`registry.compose(systemPrompt, skill)` → pass `{ system, allowedTools }` to
+`engine.runAgentic(...)`.
+
+## Adding a skill
+
+1. Create `skills/<name>/SKILL.md` (and `references/*.md` if needed).
+2. Node hosts pick it up automatically. For mobile, re-run the bundler.
+3. That's it — no code changes. The selector routes to it by description/triggers.
+
+## Shipped skills
+
+- **bitrefill/** — official Bitrefill agent skill (gift cards, mobile top-ups,
+  eSIMs; pay in crypto / Lightning / USDC-x402 / balance). Capability-routes to
+  the best channel; preferred purchase path is the Bitrefill remote MCP at
+  `https://api.bitrefill.com/mcp` (needs `BITREFILL_API_KEY` — anonymous = 401).
+  Source: https://github.com/bitrefill/agents (MIT). Update with
+  `npx skills add bitrefill/agents` or re-vendor the folder.
+- **kaleido-wallet/** — balances, receive, pay, channels over `kaleido-mcp`.
+- **kaleido-trading/** — prices, quotes, atomic swaps, LSP channels.

package/skills/bitrefill/SKILL.md

@@ -0,0 +1,66 @@
+---
+name: bitrefill
+description: "Buy or browse Bitrefill — 1,500+ gift cards, mobile top-ups, and eSIMs across 180+ countries, payable in crypto, Lightning, USDC via x402, or pre-funded account balance. Routes the host agent to its highest-fidelity channel (residential browser, MCP server, npm CLI, or REST API) based on detected runtime capabilities, with a dedicated OpenClaw integration guide for chat-channel scenarios. Triggers when the user mentions Bitrefill, gift cards, mobile top-up, eSIM data plan, refilling a phone, or asks to pay or check out with crypto, Lightning, USDC, or x402."
+compatibility: "Detects host capabilities at runtime. Paths require: browse — residential-IP browser; MCP — MCP-capable client + Bitrefill OAuth/API key; CLI — Node.js >=18 + shell + npm + @bitrefill/cli >=0.3.0 (headless login/verify via magic link); API — outbound HTTP + Bitrefill API key (Personal) or API ID/Secret (Business/Affiliate). OpenClaw host gets a dedicated guide."
+metadata:
+  author: bitrefill
+  version: "2.1.5"
+  homepage: "https://www.bitrefill.com"
+  docs: "https://docs.bitrefill.com"
+  repository: "https://github.com/bitrefill/cli"
+---
+
+# Bitrefill
+
+Bitrefill sells digital goods (gift cards, mobile top-ups, eSIMs) across 180+ countries and 1,500+ brands. Pay with crypto, Lightning, USDC via x402, or pre-funded account balance. Codes deliver instantly after payment confirms.
+
+This skill **routes by capability, not by use case**. Same intent ("buy a Steam card") plays out differently across hosts. Pick a path below based on what your runtime can do.
+
+## Pick a path
+
+Walk these checks **in order**. First match wins.
+
+1. **Inside OpenClaw?** Check for `~/.openclaw/openclaw.json`, `~/.openclaw/skills/`, or `openclaw` on PATH. If yes → read [host-openclaw.md](references/host-openclaw.md) first. **Default purchase path: guest CLI via `exec`** (no auth). Sign in for `balance`/cashback. OpenClaw also supports MCP, API, Browse, chat-channel scenarios (Telegram, cron, mobile camera).
+
+2. **Browse-only intent (no purchase)?** If the user only wants to explore, compare prices, or learn how products work:
+   - Have a residential-IP browser (ChatGPT Atlas, Cursor browser tool, Claude/Playwright Chrome extension, OpenClaw on user host)? → [browse.md](references/browse.md).
+   - Datacenter egress only (ChatGPT web/Agent, Gemini consumer, Jules)? `www.bitrefill.com` returns **403 Cloudflare** to datacenter IPs. Use [mcp.md](references/mcp.md) `search-products` / `product-details` instead — they return the same catalog without scraping.
+
+3. **MCP supported?** Bitrefill ships a remote HTTP/SSE MCP at `https://api.bitrefill.com/mcp`. Works on Claude.ai (Pro+), Cowork, Claude Desktop, Claude Code, ChatGPT (Plus+), Atlas, Codex CLI, Gemini CLI, Cursor, OpenCode, OpenClaw. **Highest-fidelity purchase channel — typed tool calls, OAuth or API key, no shell needed.** → [mcp.md](references/mcp.md).
+
+4. **Shell + `npm install` available?** CLI ≥ 0.3.0: **guest checkout first** (no auth — `buy-products --email` + crypto). Sign in for `balance`, cashback, order history. → [cli.md](references/cli.md). Headless sign-in → [cli-headless-auth.md](references/cli-headless-auth.md).
+
+5. **Outbound HTTP from agent loop?** Anywhere shell exists, plus Claude Code `WebFetch`. Last resort — verbose, no typed validation. → [api.md](references/api.md).
+
+6. **None of the above** (e.g. Gemini consumer free tier): give the user a `bitrefill.com` link and stop.
+
+Don't know which host you're in? Read [capability-matrix.md](references/capability-matrix.md) — per-client cheat sheet maps every leading agent product to its viable paths.
+
+## Top spending safeguards (read full list before any purchase)
+
+This skill enables **real-money transactions**. Codes deliver instantly and digital goods are non-refundable per EU consumer rights.
+
+- **Confirm before buying.** Present product, denomination, price, payment method. Wait for explicit user approval. Autonomous purchasing only when user opts in for the current session.
+- **Treat codes as cash.** Never paste in group chats or public channels. Prefer in-memory storage over plain-text logs. Advise user to redeem ASAP.
+- **Use a dedicated, low-balance account.** Never give the agent access to high-balance accounts or crypto wallet seeds. This skill is **not a wallet**.
+- **Log every purchase.** `invoice_id`, product, amount, payment method.
+
+Full safeguards + per-host hardening (OpenClaw exec-approvals, Cursor auto-approve, Codex sandbox, Claude Code allowlist) → [safeguards.md](references/safeguards.md).
+
+## References
+
+| File | Use when |
+|------|----------|
+| [browse.md](references/browse.md) | Agent has residential-IP browser; user wants to explore |
+| [mcp.md](references/mcp.md) | MCP-capable host; preferred purchase path |
+| [cli.md](references/cli.md) | Shell + npm; guest checkout or signed-in CLI ≥ 0.3.0 |
+| [cli-headless-auth.md](references/cli-headless-auth.md) | AgentMail or equivalent inbox + magic-link auth for headless agents |
+| [api.md](references/api.md) | HTTP-only runtime; Personal / Business / Affiliate REST tiers |
+| [host-openclaw.md](references/host-openclaw.md) | OpenClaw Gateway — guest CLI via `exec` preferred |
+| [capability-matrix.md](references/capability-matrix.md) | Per-client viable paths cheat sheet |
+| [safeguards.md](references/safeguards.md) | Spending policy + per-host hardening |
+| [troubleshooting.md](references/troubleshooting.md) | Common errors across all paths |
+
+## Source of truth
+
+Skill summarizes and routes. For exhaustive enums (countries, payment methods, full endpoint list), follow link-outs to <https://docs.bitrefill.com>.

package/skills/bitrefill/references/api.md

@@ -0,0 +1,99 @@
+# Path: REST API
+
+Use when: outbound HTTP available but no MCP and no shell. Last resort — verbose, no typed validation. Examples below use `curl` but any HTTP client works.
+
+Base URL: `https://api.bitrefill.com/v2`
+
+## Three tiers
+
+| Tier | Auth | Use case |
+|------|------|----------|
+| Personal | Bearer token | Personal projects, agent automation |
+| Business | Basic auth (`API_ID:API_SECRET`) | Platforms, resellers, BRGC batches, deposits, test products |
+| Affiliate | Basic auth | Same as Business + commission tracking, results filtered by `referrer_id` |
+
+## Personal API (agent default)
+
+Get key: <https://www.bitrefill.com/account/developers>.
+
+```bash
+export BITREFILL_API_KEY=YOUR_API_KEY
+H="Authorization: Bearer $BITREFILL_API_KEY"
+
+# 1. Ping
+curl -H "$H" https://api.bitrefill.com/v2/ping
+# → {"data":{"message":"pong"}}
+
+# 2. Balance
+curl -H "$H" https://api.bitrefill.com/v2/accounts/balance
+
+# 3. Search
+curl -H "$H" "https://api.bitrefill.com/v2/products/search?q=amazon"
+
+# 4. Product details
+curl -H "$H" https://api.bitrefill.com/v2/products/amazon-us
+
+# 5. Buy (balance, instant)
+curl -X POST -H "$H" -H "Content-Type: application/json" \
+  -d '{
+    "products": [{"product_id":"amazon-us","package_id":"amazon-us<&>50","quantity":1}],
+    "payment_method": "balance",
+    "auto_pay": true
+  }' \
+  https://api.bitrefill.com/v2/invoices
+
+# 6. Order / redemption
+curl -H "$H" https://api.bitrefill.com/v2/orders/{order_id}
+# → data.redemption_info.code, .link, .pin, .instructions
+```
+
+For crypto: omit `auto_pay`, set `payment_method: "bitcoin"|"lightning"|"usdc_base"|...`, include `refund_address` for crypto methods, then poll `GET /invoices/{id}` until `status: "complete"`.
+
+## Business API
+
+Apply: <https://www.bitrefill.com/integrate>.
+
+```bash
+TOKEN=$(printf "%s:%s" "$BITREFILL_API_ID" "$BITREFILL_API_SECRET" | base64)
+H="Authorization: Basic $TOKEN"
+
+curl -H "$H" https://api.bitrefill.com/v2/ping
+```
+
+Adds: BRGC (Bitrefill Reusable Gift Card) batches, account deposits via crypto, full product catalog including test products. Same endpoints + `POST /brgc-batches`, `POST /accounts/deposit`.
+
+## Affiliate API
+
+Apply: <https://www.bitrefill.com/affiliate>. Same auth as Business. Adds `GET /commissions` with `after`/`before` date filters. Order/invoice queries return data filtered by `referrer_id` instead of `user_id`.
+
+## Key endpoints
+
+- `GET /ping` — health check (1 req / 3 s)
+- `GET /accounts/balance` — current balance
+- `GET /products` — paginated catalog (cache locally, refresh daily; 1000 product req/hr quota shared with search)
+- `GET /products/search?q=...` — keyword search
+- `GET /products/{id}` — product details with `packages` array
+- `POST /invoices` — create invoice (max 20 products)
+- `POST /invoices/{id}/pay` — pay unpaid balance invoice
+- `GET /invoices/{id}` — status
+- `GET /orders/{id}` — redemption info
+- `POST /esims` — create eSIM invoice (or top-up existing via `esim_id`)
+- `GET /esims` / `GET /esims/{id}` — list / get user eSIMs
+
+Webhooks: `webhook_url` field on invoice creation → notification when delivered.
+
+## Test products
+
+Business/Affiliate only. No money charged. Examples: `test-gift-card-code`, etc. Full list: <https://docs.bitrefill.com/docs/test-products>.
+
+## Rate limits
+
+Most endpoints 60 req / 10 min. `/products` and `/products/search` 60 req/min + 1000 product req/hr quota. `/ping` 1 req / 3 s. Full table: <https://docs.bitrefill.com/docs/rate-limits>.
+
+## Source of truth
+
+- <https://docs.bitrefill.com/docs/api-overview> — tier comparison + auth
+- <https://docs.bitrefill.com/docs/quickstart-2> — 6-step purchase flow
+- <https://docs.bitrefill.com/reference> — full endpoint catalog
+- <https://docs.bitrefill.com/docs/error-codes> — error codes
+- <https://docs.bitrefill.com/docs/webhooks> — webhook payload spec