@thirdfy/agent-cli 0.2.86 → 0.4.0

package/src/commands/walletControl.mjs

@@ -0,0 +1,66 @@
+import { loadProfileConfig } from '../core/context.mjs';
+import { parseJsonFlag, requireFlag } from '../core/args.mjs';
+import { apiGet, apiPost } from '../core/http.mjs';
+
+/**
+ * The owner's side of API 4.0 wallet control (`/api/v1/agent/:agentKey/wallet-control/*`), for a
+ * user-owned agent wallet. Owner auth only (`--owner-session-token` or a Privy `--auth-token`); the
+ * API refuses agent API keys. Thirdfy never signs these: `request` returns the unsigned Privy
+ * request(s), the owner signs `signatureInput` with their own key, and `submit` relays it. This is
+ * how an owner answers AGENT_POLICY_UPDATE_REQUIRED (`--action update_policy`) from the CLI.
+ * Same routes as Console and thirdfy-mcp `walletControlRequest` / `walletControlSubmit`.
+ */
+export function createWalletControlCommands({ printEnvelope, buildOwnerAuthHeaders }) {
+  const ownerHeaders = (flags, command) =>
+    buildOwnerAuthHeaders(flags, `Missing owner auth for wallet-control ${command}: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token`);
+
+  function agentKeyOf(flags) {
+    const key = String(flags.agentKey || loadProfileConfig()?.agent?.agentKey || '').trim();
+    if (!key) throw new Error('Missing --agent-key (or a configured agent)');
+    return key;
+  }
+
+  const base = (agentKey) => `/api/v1/agent/${encodeURIComponent(agentKey)}/wallet-control`;
+  const meta = (ctx, capabilities) => ({ apiBase: ctx.apiBase, capabilitiesVersion: capabilities?.contractVersion || null });
+
+  async function commandWalletControlState(ctx, flags, capabilities) {
+    const headers = ownerHeaders(flags, 'state');
+    const agentKey = agentKeyOf(flags);
+    const query = flags.walletAddress ? `?walletAddress=${encodeURIComponent(String(flags.walletAddress).trim())}` : '';
+    const response = await apiGet(ctx, `${base(agentKey)}/state${query}`, headers);
+    printEnvelope({ success: true, code: 'WALLET_CONTROL_STATE', message: 'Owner wallet state', data: response?.data ?? response, meta: meta(ctx, capabilities) });
+  }
+
+  async function commandWalletControlRequest(ctx, flags, capabilities) {
+    const headers = ownerHeaders(flags, 'request');
+    const action = requireFlag(flags, 'action', 'Missing --action (update_policy, stop_agent, resume_agent, change_payout, export)');
+    const agentKey = agentKeyOf(flags);
+    const payload = { action: String(action).trim() };
+    if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+    if (flags.payoutAddress) payload.payoutAddress = String(flags.payoutAddress).trim();
+    if (flags.recipientPublicKey) payload.recipientPublicKey = String(flags.recipientPublicKey).trim();
+    const response = await apiPost(ctx, `${base(agentKey)}/requests`, payload, headers);
+    printEnvelope({
+      success: true,
+      code: 'WALLET_CONTROL_REQUESTS',
+      message: 'Unsigned owner request(s): sign each signatureInput with the owner key, then run wallet-control submit',
+      data: response?.data ?? response,
+      meta: meta(ctx, capabilities),
+    });
+  }
+
+  async function commandWalletControlSubmit(ctx, flags, capabilities) {
+    const headers = ownerHeaders(flags, 'submit');
+    const action = requireFlag(flags, 'action', 'Missing --action');
+    const signatureInput = parseJsonFlag(flags, 'signatureInput');
+    if (!signatureInput || typeof signatureInput !== 'object') throw new Error('Missing --signature-input (the signatureInput JSON of the request the owner signed)');
+    const signature = requireFlag(flags, 'signature', 'Missing --signature (the owner signature of signatureInput)');
+    const agentKey = agentKeyOf(flags);
+    const payload = { action: String(action).trim(), signatureInput, signature: String(signature).trim() };
+    if (flags.payoutAddress) payload.payoutAddress = String(flags.payoutAddress).trim();
+    const response = await apiPost(ctx, `${base(agentKey)}/submit`, payload, headers);
+    printEnvelope({ success: true, code: 'WALLET_CONTROL_SUBMITTED', message: 'Owner action relayed', data: response?.data ?? response, meta: meta(ctx, capabilities) });
+  }
+
+  return { commandWalletControlState, commandWalletControlRequest, commandWalletControlSubmit };
+}

package/src/contracts/cli/schemas/actions.response.schema.json

@@ -44,6 +44,51 @@
         },
         "additionalProperties": true
       }
+    },
+    "pagination": {
+      "type": "object",
+      "description": "Present with --search, --limit, --offset or --view (thirdfy-mcp getAgentActions paging).",
+      "required": [
+        "total",
+        "matched",
+        "offset",
+        "limit",
+        "returned",
+        "hasMore"
+      ],
+      "properties": {
+        "total": {
+          "type": "integer"
+        },
+        "matched": {
+          "type": "integer"
+        },
+        "offset": {
+          "type": "integer"
+        },
+        "limit": {
+          "type": "integer"
+        },
+        "returned": {
+          "type": "integer"
+        },
+        "hasMore": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": true
+    },
+    "view": {
+      "enum": [
+        "concise",
+        "detailed"
+      ]
+    },
+    "hint": {
+      "type": "string"
+    },
+    "providerHint": {
+      "type": "object"
     }
   },
   "additionalProperties": true

package/src/contracts/cli/schemas/chains-non-evm.response.schema.json

@@ -0,0 +1,76 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI response data: chains --non-evm (thirdfy-mcp getNonEvmCapabilities parity)",
+  "type": "object",
+  "required": [
+    "supportedChains",
+    "executionEnabled",
+    "contractVersion",
+    "solana",
+    "notes"
+  ],
+  "properties": {
+    "supportedChains": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "executionEnabled": {
+      "type": "boolean"
+    },
+    "contractVersion": {
+      "type": "string"
+    },
+    "chainRegistrySource": {
+      "enum": [
+        "api",
+        "default"
+      ]
+    },
+    "solana": {
+      "type": "object",
+      "required": [
+        "enabled",
+        "chainFamily",
+        "chainIds",
+        "requiredRunMode"
+      ],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "chainFamily": {
+          "enum": [
+            "svm"
+          ]
+        },
+        "chainIds": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          }
+        },
+        "caip2": {
+          "type": "object"
+        },
+        "requiredRunMode": {
+          "enum": [
+            "agent_wallet"
+          ]
+        },
+        "providers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "notes": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

package/src/contracts/cli/schemas/chains.response.schema.json

@@ -0,0 +1,151 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI response data: chains (thirdfy-mcp getChainCapabilities parity)",
+  "type": "object",
+  "required": [
+    "supportedEvmChainIds",
+    "configuredEvmChainIds",
+    "catalogEvmChainIds",
+    "supportedNonEvmChains",
+    "supportedSvmChainIds",
+    "chainRegistrySource",
+    "caip2",
+    "supportedExecutionLanes",
+    "defaultChainId",
+    "nonEvmExecutionContract"
+  ],
+  "properties": {
+    "supportedEvmChainIds": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      }
+    },
+    "configuredEvmChainIds": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      }
+    },
+    "catalogEvmChainIds": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      }
+    },
+    "catalogSource": {
+      "enum": [
+        "live",
+        "unavailable"
+      ]
+    },
+    "catalogError": {
+      "type": "string"
+    },
+    "supportedNonEvmChains": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "supportedSvmChainIds": {
+      "type": "array",
+      "items": {
+        "type": "integer"
+      }
+    },
+    "chainRegistrySource": {
+      "enum": [
+        "api",
+        "default"
+      ]
+    },
+    "caip2": {
+      "type": "object"
+    },
+    "supportedExecutionLanes": {
+      "type": "array",
+      "items": {
+        "type": "string"
+      }
+    },
+    "defaultChainId": {
+      "type": "integer"
+    },
+    "defaultExecutionLane": {
+      "type": "string"
+    },
+    "nonEvmExecutionContract": {
+      "type": "object",
+      "required": [
+        "enabled",
+        "chainFamily",
+        "chainIds",
+        "requiredRunMode"
+      ],
+      "properties": {
+        "enabled": {
+          "type": "boolean"
+        },
+        "chainFamily": {
+          "enum": [
+            "svm"
+          ]
+        },
+        "chainIds": {
+          "type": "array",
+          "items": {
+            "type": "integer"
+          }
+        },
+        "caip2": {
+          "type": "object"
+        },
+        "requiredRunMode": {
+          "enum": [
+            "agent_wallet"
+          ]
+        },
+        "providers": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": true
+    },
+    "chains": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "chainId",
+          "chainFamily"
+        ],
+        "properties": {
+          "chainId": {
+            "type": "integer"
+          },
+          "chainFamily": {
+            "enum": [
+              "evm",
+              "svm"
+            ]
+          },
+          "caip2": {
+            "type": "string"
+          },
+          "supportedExecutionLanes": {
+            "type": "array",
+            "items": {
+              "type": "string"
+            }
+          }
+        },
+        "additionalProperties": true
+      }
+    }
+  },
+  "additionalProperties": true
+}

package/src/contracts/cli/schemas/error.response.schema.json

@@ -0,0 +1,61 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI response data on any failure: the error fields (thirdfy-mcp tool error envelope parity)",
+  "type": "object",
+  "required": [
+    "errorCode",
+    "retryable",
+    "nextAction"
+  ],
+  "properties": {
+    "errorCode": {
+      "type": "string"
+    },
+    "retryable": {
+      "type": "boolean"
+    },
+    "retryAfterSeconds": {
+      "type": "integer"
+    },
+    "nextAction": {
+      "type": "string"
+    },
+    "hint": {
+      "type": "string"
+    },
+    "blockedReason": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "blockedStage": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "statusCode": {
+      "type": [
+        "integer",
+        "null"
+      ]
+    },
+    "riskRefusal": {
+      "type": "object",
+      "required": [
+        "code"
+      ],
+      "properties": {
+        "code": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "message": {
+      "type": "string"
+    }
+  },
+  "additionalProperties": true
+}

package/src/contracts/cli/schemas/preview.response.schema.json

@@ -0,0 +1,179 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI response data: preview (thirdfy-mcp previewOrder parity)",
+  "type": "object",
+  "required": [
+    "action",
+    "chainId",
+    "success",
+    "wouldSign"
+  ],
+  "properties": {
+    "action": {
+      "type": "string"
+    },
+    "chainId": {
+      "type": "integer"
+    },
+    "success": {
+      "type": "boolean"
+    },
+    "wouldSign": {
+      "type": "boolean"
+    },
+    "blockedReason": {
+      "type": "string"
+    },
+    "blockedStage": {
+      "type": "string"
+    },
+    "reason": {
+      "type": "string"
+    },
+    "nextAction": {
+      "type": "string"
+    },
+    "riskRefusal": {
+      "type": "object",
+      "required": [
+        "code"
+      ],
+      "properties": {
+        "code": {
+          "type": "string"
+        },
+        "field": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "message": {
+      "type": "string"
+    },
+    "gas": {
+      "type": "object",
+      "required": [
+        "sponsored",
+        "note"
+      ],
+      "properties": {
+        "sponsored": {
+          "type": "boolean"
+        },
+        "payer": {
+          "type": "string"
+        },
+        "nativeToken": {
+          "type": "string"
+        },
+        "faucet": {
+          "type": "string"
+        },
+        "rentPayer": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "amountUsd": {
+      "type": "number"
+    },
+    "orderPreview": {
+      "type": "object",
+      "properties": {
+        "previewKind": {
+          "type": "string"
+        },
+        "wouldSign": {
+          "type": "boolean"
+        },
+        "notionalUsd": {
+          "type": "number"
+        }
+      },
+      "additionalProperties": true
+    },
+    "warnings": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "required": [
+          "message"
+        ],
+        "properties": {
+          "code": {
+            "type": [
+              "string",
+              "null"
+            ]
+          },
+          "message": {
+            "type": "string"
+          }
+        }
+      }
+    },
+    "note": {
+      "type": "string"
+    },
+    "venueSetup": {
+      "type": "object",
+      "properties": {
+        "runsWithOrder": {
+          "type": "boolean"
+        }
+      },
+      "additionalProperties": true
+    },
+    "order": {
+      "type": "object",
+      "required": [
+        "action",
+        "params",
+        "chainId",
+        "runMode",
+        "executionIdempotencyKey",
+        "command"
+      ],
+      "properties": {
+        "action": {
+          "type": "string"
+        },
+        "params": {
+          "type": "object"
+        },
+        "chainId": {
+          "type": "integer"
+        },
+        "runMode": {
+          "enum": [
+            "agent_wallet"
+          ]
+        },
+        "estimatedAmountUsd": {
+          "type": "number"
+        },
+        "confirmWrites": {
+          "enum": [
+            true
+          ]
+        },
+        "executionIdempotencyKey": {
+          "type": "string"
+        },
+        "command": {
+          "type": "array",
+          "items": {
+            "type": "string"
+          }
+        }
+      },
+      "additionalProperties": false
+    }
+  },
+  "additionalProperties": true
+}

package/src/contracts/cli/schemas/readiness.response.schema.json

@@ -0,0 +1,94 @@
+{
+  "$schema": "https://json-schema.org/draft/2020-12/schema",
+  "title": "CLI response data: readiness (thirdfy-mcp getSelfReadiness parity)",
+  "type": "object",
+  "required": [
+    "runMode",
+    "chainId",
+    "source",
+    "readiness"
+  ],
+  "properties": {
+    "runMode": {
+      "enum": [
+        "agent_wallet",
+        "self",
+        "hybrid",
+        "thirdfy"
+      ]
+    },
+    "custodyMode": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "chainId": {
+      "type": "integer"
+    },
+    "chainIdAssumed": {
+      "enum": [
+        true
+      ]
+    },
+    "chainIdNote": {
+      "type": "string"
+    },
+    "walletAddress": {
+      "type": [
+        "string",
+        "null"
+      ]
+    },
+    "gas": {
+      "type": "object",
+      "required": [
+        "sponsored",
+        "note"
+      ],
+      "properties": {
+        "sponsored": {
+          "type": "boolean"
+        },
+        "payer": {
+          "type": "string"
+        },
+        "nativeToken": {
+          "type": "string"
+        },
+        "faucet": {
+          "type": "string"
+        },
+        "rentPayer": {
+          "type": "string"
+        },
+        "note": {
+          "type": "string"
+        }
+      },
+      "additionalProperties": true
+    },
+    "source": {
+      "enum": [
+        "/api/v1/agent/execution-wallet",
+        "/api/v1/agent/delegation/check"
+      ]
+    },
+    "ready": {
+      "type": "boolean"
+    },
+    "walletControl": {
+      "type": "object"
+    },
+    "nextAction": {
+      "type": "string"
+    },
+    "userMessage": {
+      "type": "string"
+    },
+    "readiness": {
+      "type": "object"
+    }
+  },
+  "additionalProperties": true
+}

package/src/core/args.mjs

@@ -50,9 +50,17 @@ export function loadEnvFile(filePath) {
   }
 }
 
+/** An error in how the command was called; describeCliError reports it as INVALID_ARGUMENTS. */
+export function usageError(message, field) {
+  const error = new Error(message);
+  error.usage = true;
+  error.field = field;
+  return error;
+}
+
 export function requireFlag(flags, key, message) {
   if (flags[key] === undefined || flags[key] === null || String(flags[key]).trim() === '') {
-    throw new Error(message || `Missing required flag --${key}`);
+    throw usageError(message || `Missing required flag --${key}`, key);
   }
   return flags[key];
 }
@@ -63,6 +71,6 @@ export function parseJsonFlag(flags, key) {
   try {
     return JSON.parse(String(raw));
   } catch {
-    throw new Error(`Invalid JSON for --${key}`);
+    throw usageError(`Invalid JSON for --${key}`, key);
   }
 }