@dfm-fi/agent 0.2.1942 → 0.2.1958

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/mcp-server.js

@@ -889,27 +889,19 @@ async function keylessWrite(tool, args) {
 // ─── WRITE TOOL: launch_vault (create DTF) ────────────────────────────────
 server.registerTool('launch_vault', {
     title: 'Launch a fund',
-    description: 'REAL-MONEY (gated). Create a new fund. WHO PAYS: your APP WALLET ' +
-        '(the Privy operating wallet) signs and funds this whenever you have an ' +
-        'active one — that is where your money is, and it becomes the vault admin. ' +
-        'An app wallet is REQUIRED here: with no active one this tool refuses ' +
-        'instead of signing with a local keypair, because the creator is fixed ' +
-        'onchain forever and is what registers the fund to you — a launch signed ' +
-        'by any other wallet is a fund nobody can claim. Anyone can get an app ' +
-        'wallet (no allowlist); this is an identity rule, not a permission one. Check ' +
-        '`app_wallet` first if a write is refused for funds. `assets` is the basket — each ' +
-        '{ mint, symbol, allocationBps }; allocationBps MUST sum to exactly 10000, ' +
-        '≤10 assets (mainnet cap). Live factory/fund-tier rules decide mint eligibility; ' +
-        'a freezable mint is accepted in production v1 but carries issuer-lock risk. Fees are factory-global ' +
-        'and read live by DFM — the creator cannot set them. After the vault is recorded, ' +
-        'the share mint automatically gets ' +
-        'Metaplex token metadata (name/symbol/uri) so explorers + wallets show the ' +
-        'Fund instead of "Unknown Token" (#47, best-effort + non-fatal); pass `metadata:false` ' +
-        'to skip its unrecoverable rent; the API preflight reports the current SOL requirement ' +
-        'and attach it later from the vault page. ' +
-        'Names and symbols must be unique among active DFM funds; closed funds release them. ' +
-        'Name matching ignores case and repeated whitespace; symbol matching ignores case. ' +
-        'Returns the vault address — fund the first deposit ≥ ~$12.',
+    description: 'REAL-MONEY (gated). Create a new fund. Your APP WALLET signs, pays and ' +
+        'becomes the vault admin; with no active app wallet this tool refuses rather ' +
+        'than sign with a local keypair (the creator is fixed onchain forever and is ' +
+        'what registers the fund to you). Any wallet can get one — an identity rule, ' +
+        'not a permission. Check `app_wallet` if a write is refused for funds. ' +
+        '`assets` = [{ mint, symbol, allocationBps }], allocationBps summing to exactly ' +
+        '10000, 2–10 assets. Live factory rules decide mint eligibility; freezable ' +
+        'mints are accepted but carry issuer-lock risk. Fees are factory-global, read ' +
+        'live; the creator cannot set them. The share mint gets Metaplex metadata so ' +
+        'wallets show the fund (#47, non-fatal); `metadata:false` skips its ' +
+        'unrecoverable rent (attach it later from the vault page). Names and symbols ' +
+        'must be unique among active funds (case-insensitive). Returns the vault ' +
+        'address — fund the first deposit ≥ ~$12.',
     inputSchema: {
         name: z.string().min(1).max(32),
         symbol: z
@@ -931,19 +923,27 @@ server.registerTool('launch_vault', {
         // never comes back, and the SOL floor drops from ~0.045 to ~0.03 without
         // it. The vault page can attach it later (creator-signed).
         metadata: z.boolean().optional(),
+        announceOptIn: z
+            .boolean()
+            .optional()
+            .describe('Let DFM announce this fund publicly on X/Telegram/Moltbook. Default false (no announcement).'),
         confirmPhrase: confirmPhraseField,
     },
     annotations: { title: 'DFM launch vault', readOnlyHint: false, destructiveHint: true, idempotentHint: false, openWorldHint: true },
 }, 
 // REVIEW: real-money path — parent must review before enabling.
-async ({ name, symbol, assets, category, description, metadata, confirmPhrase }) => {
+async ({ name, symbol, assets, category, description, metadata, announceOptIn, confirmPhrase }) => {
     const gate = confirmGate('launch_vault', confirmPhrase);
     if (!gate.ok)
         return gate.result;
     const write = writeGate();
     if (!write.ok)
         return write.result;
-    return keylessWrite('launch_vault', { name, symbol, assets, category, description, ...(metadata === false && { metadata }) });
+    return keylessWrite('launch_vault', {
+        name, symbol, assets, category, description,
+        ...(metadata === false && { metadata }),
+        ...(announceOptIn === true && { announceOptIn }),
+    });
 });
 // ─── WRITE TOOL: deposit (zap-in) ─────────────────────────────────────────
 server.registerTool('deposit', {
@@ -1530,26 +1530,18 @@ server.registerTool('init_rebalancer', {
 // `/execute/prepare`, just off the agent surface.)
 server.registerTool('rebalance_to_targets', {
     title: 'Rebalance a vault to its configured target weights',
-    description: 'THE MANAGER\'S RECURRING DUTY, not a convenience: a fund\'s config is the promise, its holdings are the ' +
-        'reality, and prices pull them apart every day. A drifted fund no longer holds what its depositors bought, ' +
-        'and share price settles onchain from the ACTUAL basket, so every new deposit mints against the drift. ' +
-        'DFM has NO automatic rebalancing (manual by design, #35) — nothing converges by itself, so an agent that ' +
-        'reads a managed vault and stays quiet about drift IS the failure. Report it with the number even when ' +
-        'nobody asked, then let the ' +
-        'manager decide; never fire this unasked. ' +
-        'REAL-MONEY (gated). MANAGER action — only works on a vault your app wallet ' +
-        'ADMINS whose rebalancer is initialized (bundled into launch_vault, or run ' +
-        'init_rebalancer first). CONVERGES the vault\'s live holdings toward its ' +
-        'CURRENT onchain CONFIG target weights — you supply NO inputMint/outputMint/' +
-        'amount. The API derives the converging swap legs from the drift between live ' +
-        'balances and the registered targets (sell-overweight → buy-underweight), ' +
-        'returns them as ordered admin-signed execute_rebalance txs, and this tool ' +
-        'signs + submits them IN ORDER (honoring the 5s onchain cooldown). To CHANGE ' +
-        'the targets first, use update_vault_assets (reconfigure). Onchain guards are ' +
-        'ORACLE-FREE: a measured min_out floor + hardcoded velocity ceilings + an ' +
-        'output-mint allowlist (a value-leaking route REVERTS). If already balanced, it ' +
-        'returns `converged:true` with no swaps. The vault must HOLD assets (i.e. after ' +
-        'a deposit) — converging an empty vault does nothing.',
+    description: 'REAL-MONEY (gated). MANAGER duty: prices pull holdings away from the config ' +
+        'every day and DFM has NO automatic rebalancing (#35), so report drift with ' +
+        'the number even unasked — but never fire this unasked; the manager decides. ' +
+        'Works only on a vault your app wallet ADMINS with an initialized rebalancer ' +
+        '(bundled into launch_vault, else init_rebalancer). CONVERGES live holdings ' +
+        'toward the CURRENT onchain target weights — you supply no mints or amounts. ' +
+        'The API derives the legs from drift (sell overweight → buy underweight) as ' +
+        'ordered admin-signed execute_rebalance txs; this tool signs + submits them in ' +
+        'order (5s onchain cooldown). To CHANGE targets first, use update_vault_assets. ' +
+        'Onchain guards are oracle-free: measured min_out + velocity ceilings + an ' +
+        'output-mint allowlist (a value-leaking route reverts). Already balanced → ' +
+        '`converged:true`, no swaps. An empty vault (no deposit yet) does nothing.',
     inputSchema: {
         vault: z.string().regex(BASE58, 'Invalid base58 vault address'),
         slippageBps: z.number().int().min(1).max(300).optional(),

package/dist/signing.js

@@ -20,7 +20,8 @@
  * The keypair is loaded lazily (first WRITE call), so the read-only tools and
  * `npx tsx` smoke runs never touch key material.
  */
-import { readFileSync } from 'node:fs';
+import { lstatSync, readFileSync } from 'node:fs';
+import { dirname, resolve } from 'node:path';
 import { Keypair, Transaction, VersionedTransaction } from '@solana/web3.js';
 import nacl from 'tweetnacl';
 import bs58 from 'bs58';
@@ -32,6 +33,54 @@ import bs58 from 'bs58';
  */
 const PROTOCOL_WALLET = '9GjEBsZ1Cos2J6inmgwhBKv9pXGNtLSJ7xQ9xZb29bET';
 let cachedKeypair = null;
+const lstatOrNull = (p) => {
+    try {
+        return lstatSync(p);
+    }
+    catch (e) {
+        if (e.code === 'ENOENT')
+            return null;
+        throw e;
+    }
+};
+const myUid = () => (typeof process.getuid === 'function' ? process.getuid() : undefined);
+/**
+ * Harden the on-disk keypair path before reading it.
+ *
+ * Mirrors the owner-key checks in `app-wallet-owner.ts`: symlinks (file or
+ * directory), files owned by another uid, and any group/other access are
+ * refused outright. The env-JSON escape hatch bypasses the filesystem entirely.
+ */
+function assertSafeKeypairPath(filePath) {
+    const path = resolve(filePath);
+    const dir = dirname(path);
+    const dirSt = lstatOrNull(dir);
+    if (!dirSt)
+        throw new Error(`Keypair directory ${dir} does not exist.`);
+    if (dirSt.isSymbolicLink())
+        throw new Error(`${dir} is a symlink — refusing to keep a keypair behind it`);
+    if (!dirSt.isDirectory())
+        throw new Error(`${dir} is not a directory`);
+    const uid = myUid();
+    if (uid !== undefined && dirSt.uid !== uid)
+        throw new Error(`${dir} is not owned by the current user`);
+    if ((dirSt.mode & 0o022) !== 0)
+        throw new Error(`${dir} is writable by other users`);
+    const st = lstatOrNull(path);
+    if (!st) {
+        throw new Error(`Could not read test keypair file at DFM_AGENT_KEYPAIR_PATH (ENOENT). ` +
+            `Set it to a Solana secret-key JSON file the operator controls locally.`);
+    }
+    if (st.isSymbolicLink())
+        throw new Error(`${path} is a symlink — refusing to use it as a keypair file`);
+    if (!st.isFile())
+        throw new Error(`${path} exists and is not a regular file`);
+    if (uid !== undefined && st.uid !== uid)
+        throw new Error(`${path} is not owned by the current user`);
+    if ((st.mode & 0o077) !== 0) {
+        throw new Error(`${path} is readable by other users (mode ${(st.mode & 0o777).toString(8)}); run chmod 600 on it first`);
+    }
+}
 /** Parse a Solana 64-byte secret-key JSON array into a Keypair. */
 function keypairFromJsonArray(json, source) {
     let arr;
@@ -70,6 +119,7 @@ export function loadTestKeypair(config) {
         return cachedKeypair;
     let kp;
     if (config.keypairPath) {
+        assertSafeKeypairPath(config.keypairPath);
         let raw;
         try {
             raw = readFileSync(config.keypairPath, 'utf8');

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@dfm-fi/agent",
-  "version": "0.2.1942",
+  "version": "0.2.1958",
   "description": "DFM v2 MCP server — drive the full fund launch → deposit → redeem (+ manage) lifecycle from an AI agent against the live API.",
   "homepage": "https://app.dfm.finance/docs/agent",
   "mcpName": "io.github.DFM-Finance/dfm-agent",
@@ -55,10 +55,10 @@
     "lint": "eslint .",
     "example:read": "tsx src/examples/list-and-status.ts",
     "example:lifecycle": "tsx src/examples/launch-deposit-redeem.ts",
-    "test": "npm run build && node scripts/smoke-signing.mjs && node scripts/smoke-signing-v1.mjs &&node scripts/smoke-cli.mjs && node scripts/smoke-keyless.mjs && node scripts/smoke-zap-options.mjs && tsx src/who-pays.test.ts && tsx src/wallet-identity.test.ts && tsx src/money-path.test.ts && tsx src/control-flow.test.ts && tsx src/create-flow.metadata.test.ts && tsx src/manager-flow.reconfigure.test.ts && tsx src/recovery-flow.deadleg.test.ts && tsx src/zap-v2-flow.pending.test.ts && tsx src/mcp-server.confirm-gate.test.ts && tsx src/app-wallet-owner.test.ts && tsx src/onboarding.test.ts"
+    "test": "npm run build && node scripts/smoke-signing.mjs && node scripts/smoke-signing-v1.mjs &&node scripts/smoke-cli.mjs && node scripts/smoke-keyless.mjs && node scripts/smoke-zap-options.mjs && tsx src/who-pays.test.ts && tsx src/wallet-identity.test.ts && tsx src/money-path.test.ts && tsx src/control-flow.test.ts && tsx src/create-flow.metadata.test.ts && tsx src/manager-flow.reconfigure.test.ts && tsx src/recovery-flow.deadleg.test.ts && tsx src/zap-v2-flow.pending.test.ts && tsx src/mcp-server.confirm-gate.test.ts && tsx src/app-wallet-owner.test.ts && tsx src/onboarding.test.ts && tsx src/client-header.test.ts"
   },
   "dependencies": {
-    "@modelcontextprotocol/sdk": "^1.26.0",
+    "@modelcontextprotocol/sdk": "^1.32.1",
     "@solana/web3.js": "^1.99.0",
     "bs58": "^4.0.1",
     "tweetnacl": "^1.0.3",