@dfm-fi/agent 0.2.1942 → 0.2.1960

package/README.md

@@ -45,6 +45,17 @@ Claude Desktop (`claude_desktop_config.json`):
 }
 ```
 
+## Headless agent (no human account)
+
+```bash
+claude mcp add dfm --env DFM_AGENT_WRITE_ENABLED=true -- npx -y @dfm-fi/agent@latest
+```
+
+Then ask the agent to `onboard`: it creates its identity keypair, signs in, sets a profile (a default
+avatar is generated when there is no image), creates an app wallet owned by a local P-256 key, and
+prints the funding step — send USDC and SOL to the identity public key, then `app_wallet_fund {usdc, sol}`.
+`whoami` prints the same funding step while the app wallet is short. No API key is needed for writes.
+
 ## How money moves
 
 Fund operations run from your **app wallet**, not from your own wallet. New app wallets are owned
@@ -71,17 +82,27 @@ running. Write tools also require `DFM_AGENT_WRITE_ENABLED=true`.
 | `trader_profile` | read | A trader's public profile by wallet or @username. |
 | `xp_status` | read | Your XP and the top of the leaderboard. |
 | `follow_trader` / `unfollow_trader` | social | Follow or unfollow a trader. Moves no funds. |
+| `report_bug` | support | Send a bug report to the DFM team. Moves no funds. |
+| `onboard` | onboarding | Headless agent: runs the steps below in order, stops at the first missing one and prints the funding step. |
+| `create_identity_wallet` | onboarding | The agent's own Solana identity keypair (SIWS sign-in); reused if present, never a second. |
+| `set_profile` | onboarding | Display name, @username, bio, avatar. No image file? A deterministic default avatar is generated. |
+| `create_app_wallet` | onboarding | An app wallet owned by the agent's local P-256 key. |
+| `create_api_key` | onboarding | Mint a `dfm_` key (read-only unless `DFM_ALLOW_WRITE_KEY_MINT=1`), stored 0600, never shown in chat. |
 | `launch_vault` | write | Launch a fund (2–10 assets, weights sum to 10,000 bps). |
 | `deposit` | write | USDC → fund shares (full zap-in; resumes an open escrow). |
 | `redeem` | write | Fund shares → USDC (full zap-out; resumes an open escrow). |
 | `swap` | write | Swap one token for another in the app wallet (Jupiter). |
 | `update_vault_assets` | write | Manager: replace a fund's target basket. |
 | `rebalance_to_targets` | write | Manager: swap holdings back to the target weights. |
-| `init_rebalancer` | write | Manager: enable rebalancing (normally done by `launch_vault`). |
+| `init_rebalancer` | write | Manager: enable rebalancing (normally done by `launch_vault`). Rebalancing is manual: there are no auto-rebalance tools. |
+| `attach_metadata` | write | Retry a fund's share-token metadata (name, symbol, logo) when the launch skipped it or it failed. |
 | `zap_v2_cancel` / `zap_v2_update_envelope` | write | Recover or unstick a stalled escrow. |
 | `update_vault_policy` | write | Manager: constitutional limits (explicit human instruction only). |
-| `transfer_admin` / `accept_admin_transfer` | write | Hand over / accept fund control (explicit human instruction only). |
-| `app_wallet_fund` / `app_wallet_withdraw` / `withdraw_asset` / `app_wallet_rearm` | write | Fund, sweep or re-arm the app wallet; withdraw one token. |
+| `transfer_admin` / `accept_admin_transfer` | write | **Not available yet in this MCP**: `transfer_admin` always refuses; `accept_admin_transfer` only reconciles an acceptance that already landed. |
+| `app_wallet_fund` / `app_wallet_withdraw` / `withdraw_asset` / `app_wallet_rearm` | write | Fund (from the local identity wallet; not in key-only mode), sweep or re-arm the app wallet; withdraw one token. |
+| `close_empty_accounts` | write | Agent-owned app wallet: close empty token accounts and reclaim the rent. |
+
+The authoritative list is the server's `tools/list`.
 
 There is no fee tool: fees are set by the protocol, not per fund.
 
@@ -89,12 +110,14 @@ There is no fee tool: fees are set by the protocol, not per fund.
 
 | Variable | Default | Description |
 |----------|---------|-------------|
-| `DFM_API_KEY` | — | Recommended auth. A `dfm_` key minted in the app (write access needed for write tools). |
+| `DFM_API_KEY` | — | Auth for an agent operating a human's account: a `dfm_` key the human mints in the app (write access needed for write tools). Not needed by a headless agent. |
 | `DFM_AGENT_WRITE_ENABLED` | `false` | Master switch for every write tool. |
 | `DFM_API_URL` | `https://app.dfm.finance` | API base (`/api/v2` is appended). |
 | `DFM_MCP_CONFIRM_REQUIRED` | unset | `1` = every write needs `confirmPhrase:"<tool_name>"` typed by the human (prompt-injection guard). |
 | `DFM_MCP_NONINTERACTIVE_WRITES` | unset | `1` = skip the phrase even when required. Only for unattended machines. |
-| `DFM_AGENT_KEYPAIR_PATH` / `DFM_AGENT_KEYPAIR_JSON` | — | Legacy: sign in with a local Solana keypair instead of an API key. A leaked keypair is the wallet; prefer a key. |
+| `DFM_ALLOW_WRITE_KEY_MINT` | unset | `1` = `create_api_key` may mint write keys / write caps. Otherwise it mints read-only keys only. |
+| `DFM_AGENT_AVATAR_PATH` | `~/.config/dfm/avatar.{png,jpg,jpeg,webp,gif}` | Operator avatar for `set_profile` (≤ 2 MB). Absent → a generated default. |
+| `DFM_AGENT_KEYPAIR_PATH` / `DFM_AGENT_KEYPAIR_JSON` | `~/.config/dfm/agent-wallet.json` | Identity of a headless agent (SIWS sign-in; `create_identity_wallet` creates it once). It only signs in and funds the app wallet (`app_wallet_fund`); fund operations are signed by the app wallet. Keep it 0600 and backed up. |
 | `HELIUS_RPC_URL` / `DFM_RPC_URL` | — | Optional: submit through your own RPC instead of the backend. |
 | `SOLANA_CLUSTER` | `mainnet-beta` | Cluster name. |
 

package/dist/api-client.d.ts

@@ -163,9 +163,10 @@ export declare class DfmApiClient {
     /**
      * `POST /agent/operating/float/withdraw` — sweep the float back to its OWNER.
      *
-     * The destination is pinned server-side to the authenticated wallet, so this
-     * cannot send anywhere else. Works past a stale rebalancer stamp and a user
-     * expiry (the sweep carve-outs) — the float must never be trapped.
+     * The agent never names a destination: the API resolves the owner's SAVED
+     * withdrawal wallet first and falls back to the authenticated wallet, so
+     * this cannot send anywhere else. Works past a stale rebalancer stamp and a
+     * user expiry (the sweep carve-outs) — the float must never be trapped.
      */
     /**
      * `GET /agent/operating/assets` — every token the app wallet holds.
@@ -187,9 +188,10 @@ export declare class DfmApiClient {
     /**
      * `POST /agent/operating/assets/withdraw` — move ONE mint back to the owner.
      *
-     * `destination` is deliberately NOT exposed here: the API defaults it to the
-     * authenticated wallet, and an agent that could name a destination would be
-     * a drain vector for anything that can put words in its input.
+     * `destination` is deliberately NOT exposed here: the API resolves the
+     * owner's saved withdrawal wallet first, falling back to the authenticated
+     * wallet — an agent that could name a destination would be a drain vector
+     * for anything that can put words in its input.
      */
     withdrawAppWalletAsset(mint: string, amount?: number | string): Promise<{
         signature: string;
@@ -251,6 +253,12 @@ export declare class DfmApiClient {
      * and signs it behind both cap layers plus the tx-assert simulation. Used
      * when the MCP has an API key but no keypair; see `keyless.ts` for when that
      * applies and why it never falls back to local signing.
+     *
+     * The idempotency key is PINNED to the operation itself (tool + canonical
+     * args, hashed) rather than a fresh UUID: when the response is lost — a 504
+     * the server outlived, a dropped socket — the agent's retry carries the SAME
+     * key, and the server returns the already-running/finished job instead of
+     * executing a second time (the two-vaults-two-fees bug, A7).
      */
     executeViaOperatingWallet(tool: string, args: Record<string, unknown>): Promise<{
         signature?: string;
@@ -323,6 +331,8 @@ export declare class DfmApiClient {
         assets: CreateAssetInput[];
         description?: string;
         tags?: number[];
+        /** Let DFM announce this fund publicly on X/Telegram/Moltbook (default false). */
+        announceOptIn?: boolean;
     }): Promise<CreatePrepareResponse>;
     /**
      * `POST /vaults/create/confirm` — record the vault doc after the create tx

package/dist/api-client.js

@@ -13,13 +13,42 @@
  * NEVER sees the secret key — signing is delegated to `signing.ts` via the
  * write methods, and auth is delegated to `SiwsSession`.
  */
-import { randomUUID } from 'node:crypto';
+import { createHash, randomUUID } from 'node:crypto';
+import { dfmClientHeaders } from './client-header.js';
 const BASE58_RE = /^[1-9A-HJ-NP-Za-km-z]{32,44}$/;
 function requireBase58(addr, label) {
     if (!BASE58_RE.test(addr)) {
         throw new Error(`Invalid base58 ${label}: ${addr}`);
     }
 }
+/**
+ * Canonical JSON for an operation id: object keys sorted recursively, so two
+ * calls that MEAN the same write hash identically regardless of key order.
+ * Money fields travel as strings server-side, so no number-precision games.
+ */
+function stableStringify(value) {
+    if (value === null || typeof value !== 'object')
+        return JSON.stringify(value) ?? 'null';
+    if (Array.isArray(value))
+        return `[${value.map(stableStringify).join(',')}]`;
+    const entries = Object.keys(value)
+        .sort()
+        .map((k) => `${JSON.stringify(k)}:${stableStringify(value[k])}`);
+    return `{${entries.join(',')}}`;
+}
+/**
+ * The deterministic operation id for ONE keyless write (A7): same tool + same
+ * args → same id, so a retry after a LOST response names the first attempt
+ * instead of executing twice. This is what "the same logical operation" means
+ * here — a genuinely NEW write with byte-identical args is deliberately
+ * treated as a retry; change an argument to make a new operation.
+ */
+function operatingOperationKey(tool, args) {
+    const digest = createHash('sha256').update(`${tool}\n${stableStringify(args)}`).digest('hex');
+    return `opexec-${digest}`;
+}
+/** Launch-surface label (`launchedVia: 'mcp'` on the API side) — never a credential. */
+const CLIENT_HEADERS = dfmClientHeaders();
 export class DfmApiClient {
     session;
     baseUrl;
@@ -31,7 +60,7 @@ export class DfmApiClient {
     async publicRequest(path, init) {
         const res = await fetch(`${this.baseUrl}${path}`, {
             ...init,
-            headers: { 'Content-Type': 'application/json', ...(init?.headers ?? {}) },
+            headers: { 'Content-Type': 'application/json', ...CLIENT_HEADERS, ...(init?.headers ?? {}) },
         });
         if (!res.ok) {
             const body = await res.text().catch(() => '');
@@ -49,6 +78,7 @@ export class DfmApiClient {
         const idempotencyKey = mutating ? (pinnedKey ?? randomUUID()) : undefined;
         const common = (extra) => ({
             'Content-Type': 'application/json',
+            ...CLIENT_HEADERS,
             ...extra,
             ...(idempotencyKey ? { 'X-Idempotency-Key': idempotencyKey } : {}),
             ...(reqInit.headers ?? {}),
@@ -58,8 +88,10 @@ export class DfmApiClient {
         // resolves server-side to its owner wallet plus the credential's caps.
         // That matters because a leaked keypair IS the wallet, whereas a leaked API
         // key is revocable and capped (read-only unless explicitly widened).
-        // There is no re-auth loop here — a key does not expire; a 401 means it was
-        // revoked, and silently retrying a revoked credential would be wrong.
+        // There is no re-auth loop here — a key cannot be refreshed from the MCP
+        // side. A 401 means the key was revoked OR expired (the server enforces
+        // `expiresAt`); silently retrying a dead credential would be wrong either
+        // way, so the caller is told to mint a new one.
         const apiKey = sessionOnly ? undefined : process.env.DFM_API_KEY?.trim();
         if (apiKey) {
             const res = await fetch(`${this.baseUrl}${path}`, {
@@ -288,9 +320,10 @@ export class DfmApiClient {
     /**
      * `POST /agent/operating/float/withdraw` — sweep the float back to its OWNER.
      *
-     * The destination is pinned server-side to the authenticated wallet, so this
-     * cannot send anywhere else. Works past a stale rebalancer stamp and a user
-     * expiry (the sweep carve-outs) — the float must never be trapped.
+     * The agent never names a destination: the API resolves the owner's SAVED
+     * withdrawal wallet first and falls back to the authenticated wallet, so
+     * this cannot send anywhere else. Works past a stale rebalancer stamp and a
+     * user expiry (the sweep carve-outs) — the float must never be trapped.
      */
     /**
      * `GET /agent/operating/assets` — every token the app wallet holds.
@@ -304,9 +337,10 @@ export class DfmApiClient {
     /**
      * `POST /agent/operating/assets/withdraw` — move ONE mint back to the owner.
      *
-     * `destination` is deliberately NOT exposed here: the API defaults it to the
-     * authenticated wallet, and an agent that could name a destination would be
-     * a drain vector for anything that can put words in its input.
+     * `destination` is deliberately NOT exposed here: the API resolves the
+     * owner's saved withdrawal wallet first, falling back to the authenticated
+     * wallet — an agent that could name a destination would be a drain vector
+     * for anything that can put words in its input.
      */
     async withdrawAppWalletAsset(mint, amount) {
         return this.authRequest('/agent/operating/assets/withdraw', {
@@ -361,11 +395,18 @@ export class DfmApiClient {
      * and signs it behind both cap layers plus the tx-assert simulation. Used
      * when the MCP has an API key but no keypair; see `keyless.ts` for when that
      * applies and why it never falls back to local signing.
+     *
+     * The idempotency key is PINNED to the operation itself (tool + canonical
+     * args, hashed) rather than a fresh UUID: when the response is lost — a 504
+     * the server outlived, a dropped socket — the agent's retry carries the SAME
+     * key, and the server returns the already-running/finished job instead of
+     * executing a second time (the two-vaults-two-fees bug, A7).
      */
     async executeViaOperatingWallet(tool, args) {
         const first = await this.authRequest('/agent/operating/execute', {
             method: 'POST',
             body: JSON.stringify({ tool, args }),
+            idempotencyKey: operatingOperationKey(tool, args),
         });
         // Finished inside the server's inline window — the shape this method has
         // always returned.

package/dist/client-header.d.ts

@@ -0,0 +1,11 @@
+/**
+ * `x-dfm-client: mcp/<version>` on every DFM API call this package makes.
+ *
+ * The API stamps it onto a launched fund as `launchedVia: 'mcp'` (marketing:
+ * how many funds AI agents launch through the MCP). It is a LABEL only — the
+ * server never grants, widens or skips anything because of it.
+ */
+export declare const DFM_CLIENT_HEADER = "x-dfm-client";
+export declare function readPackageVersion(): string;
+export declare function dfmClientHeaders(version?: string): Record<string, string>;
+//# sourceMappingURL=client-header.d.ts.map

package/dist/client-header.js

@@ -0,0 +1,25 @@
+import { readFileSync } from 'node:fs';
+import { dirname, join } from 'node:path';
+import { fileURLToPath } from 'node:url';
+/**
+ * `x-dfm-client: mcp/<version>` on every DFM API call this package makes.
+ *
+ * The API stamps it onto a launched fund as `launchedVia: 'mcp'` (marketing:
+ * how many funds AI agents launch through the MCP). It is a LABEL only — the
+ * server never grants, widens or skips anything because of it.
+ */
+export const DFM_CLIENT_HEADER = 'x-dfm-client';
+export function readPackageVersion() {
+    try {
+        // dist/client-header.js → ../package.json (same layout in the published tarball).
+        const pkgPath = join(dirname(fileURLToPath(import.meta.url)), '..', 'package.json');
+        return JSON.parse(readFileSync(pkgPath, 'utf8')).version ?? '0.0.0';
+    }
+    catch {
+        return '0.0.0';
+    }
+}
+export function dfmClientHeaders(version = readPackageVersion()) {
+    return { [DFM_CLIENT_HEADER]: `mcp/${version}` };
+}
+//# sourceMappingURL=client-header.js.map

package/dist/create-flow.d.ts

@@ -38,6 +38,8 @@ export interface LaunchVaultParams {
     /** Category enum (0-7, 255). Defaults to 255 (uncategorized/other). */
     category?: number;
     description?: string;
+    /** Let DFM announce this fund publicly on X/Telegram/Moltbook (default false). */
+    announceOptIn?: boolean;
 }
 export interface LaunchVaultResult {
     ok: boolean;

package/dist/create-flow.js

@@ -93,6 +93,7 @@ export async function runLaunchVault(config, api, params) {
         category: params.category ?? 255,
         assets: params.assets,
         description: params.description,
+        ...(params.announceOptIn === true && { announceOptIn: true }),
     });
     // 2. SIGN locally + 3. SUBMIT.
     const signed = signBase64Transaction(config, prepared.transaction);

package/dist/default-avatar.d.ts

@@ -0,0 +1,6 @@
+export declare const DEFAULT_AVATAR_SIZE: number;
+/** Which cells are filled: 15 bits for the left 3 columns, mirrored to 5. */
+export declare function identiconCells(seed: string): boolean[][];
+/** A deterministic PNG identicon for `seed` (the identity public key). */
+export declare function defaultAvatarPng(seed: string): Buffer;
+//# sourceMappingURL=default-avatar.d.ts.map

package/dist/default-avatar.js

@@ -0,0 +1,101 @@
+/**
+ * DEFAULT AVATAR for headless agents (2026-10-20). The API's onboarding gate
+ * wants a chosen name AND an avatar before an app wallet can be created; a
+ * vanilla headless agent has no operator image, so `set_profile` used to stop
+ * dead. This draws a deterministic 5×5 mirrored identicon from the identity
+ * public key and encodes it as a PNG with no dependency beyond node:zlib — the
+ * API accepts PNG (magic-byte check in profile.controller.ts) and re-encodes it
+ * to WebP. Same pubkey → same bytes, so re-running set_profile is idempotent.
+ * An operator-provided image always wins (see `avatarPath`).
+ */
+import { createHash } from 'node:crypto';
+import { deflateSync } from 'node:zlib';
+const GRID = 5;
+const CELL = 40;
+const MARGIN = 20;
+export const DEFAULT_AVATAR_SIZE = GRID * CELL + 2 * MARGIN; // 240 px
+const CRC_TABLE = (() => {
+    const t = new Uint32Array(256);
+    for (let n = 0; n < 256; n++) {
+        let c = n;
+        for (let k = 0; k < 8; k++)
+            c = c & 1 ? 0xedb88320 ^ (c >>> 1) : c >>> 1;
+        t[n] = c >>> 0;
+    }
+    return t;
+})();
+function crc32(buf) {
+    let c = 0xffffffff;
+    for (const b of buf)
+        c = CRC_TABLE[(c ^ b) & 0xff] ^ (c >>> 8);
+    return (c ^ 0xffffffff) >>> 0;
+}
+function chunk(type, data) {
+    const len = Buffer.alloc(4);
+    len.writeUInt32BE(data.length);
+    const td = Buffer.concat([Buffer.from(type, 'latin1'), data]);
+    const crc = Buffer.alloc(4);
+    crc.writeUInt32BE(crc32(td));
+    return Buffer.concat([len, td, crc]);
+}
+/** HSL (h 0-360, s/l 0-1) → 8-bit RGB. */
+function hsl(h, s, l) {
+    const a = s * Math.min(l, 1 - l);
+    const f = (n) => {
+        const k = (n + h / 30) % 12;
+        return Math.round(255 * (l - a * Math.max(-1, Math.min(k - 3, 9 - k, 1))));
+    };
+    return [f(0), f(8), f(4)];
+}
+/** Which cells are filled: 15 bits for the left 3 columns, mirrored to 5. */
+export function identiconCells(seed) {
+    const h = createHash('sha256').update(seed, 'utf8').digest();
+    const cells = [];
+    for (let y = 0; y < GRID; y++) {
+        const row = [];
+        for (let x = 0; x < GRID; x++) {
+            const col = x < 3 ? x : GRID - 1 - x;
+            row.push((h[y * 3 + col] & 1) === 1);
+        }
+        cells.push(row);
+    }
+    return cells;
+}
+/** A deterministic PNG identicon for `seed` (the identity public key). */
+export function defaultAvatarPng(seed) {
+    const h = createHash('sha256').update(seed, 'utf8').digest();
+    const fg = hsl(((h[20] << 8) | h[21]) % 360, 0.55, 0.5);
+    const bg = [242, 242, 242];
+    const cells = identiconCells(seed);
+    const size = DEFAULT_AVATAR_SIZE;
+    const raw = Buffer.alloc(size * (1 + size * 3));
+    for (let py = 0; py < size; py++) {
+        const rowOff = py * (1 + size * 3);
+        raw[rowOff] = 0; // filter: none
+        for (let px = 0; px < size; px++) {
+            const cx = Math.floor((px - MARGIN) / CELL);
+            const cy = Math.floor((py - MARGIN) / CELL);
+            const on = px >= MARGIN && py >= MARGIN && cx < GRID && cy < GRID && cells[cy][cx];
+            const [r, g, b] = on ? fg : bg;
+            const o = rowOff + 1 + px * 3;
+            raw[o] = r;
+            raw[o + 1] = g;
+            raw[o + 2] = b;
+        }
+    }
+    const ihdr = Buffer.alloc(13);
+    ihdr.writeUInt32BE(size, 0);
+    ihdr.writeUInt32BE(size, 4);
+    ihdr[8] = 8; // bit depth
+    ihdr[9] = 2; // colour type: truecolour RGB
+    ihdr[10] = 0;
+    ihdr[11] = 0;
+    ihdr[12] = 0;
+    return Buffer.concat([
+        Buffer.from([0x89, 0x50, 0x4e, 0x47, 0x0d, 0x0a, 0x1a, 0x0a]),
+        chunk('IHDR', ihdr),
+        chunk('IDAT', deflateSync(raw)),
+        chunk('IEND', Buffer.alloc(0)),
+    ]);
+}
+//# sourceMappingURL=default-avatar.js.map

package/dist/mcp-server.d.ts

@@ -22,8 +22,8 @@
  *     • zap_v2_cancel       — recover a stalled escrow's holdings as-is
  *     • zap_v2_update_envelope — loosen pinned floors to unstick a mid-crank escrow
  *     • update_vault_assets — MANAGER: RECONFIGURE — set new target weights + converge (own vault)
- *     • transfer_admin   — MANAGER, HIGH-SENSITIVITY: hand vault control to a new key
- *     • accept_admin_transfer — HIGH-SENSITIVITY: complete a pending control handoff
+ *     • transfer_admin   — NOT available yet: always refuses (no app-wallet executor)
+ *     • accept_admin_transfer — reconcile-only: new acceptances are refused
  *     • update_vault_policy — HIGH-SENSITIVITY: create/amend constitutional limits
  *     • init_rebalancer  — MANAGER: enable rebalancing (create RebalancerConfig) for own vault
  *     • rebalance_to_targets — MANAGER: converge holdings to the vault's CONFIG targets (own vault)