@thirdfy/agent-cli 0.3.0 → 0.4.0

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);
   }
 }