@thirdfy/agent-cli 0.1.4 → 0.1.6

package/README.md

@@ -16,6 +16,9 @@ If you want the full developer docs, start here:
 - [API Reference home](https://docs.thirdfy.com/api)
 - [LLM docs map (llms.txt)](https://docs.thirdfy.com/llms.txt)
 - [LLM full API snapshot (llms-full.txt)](https://docs.thirdfy.com/llms-full.txt)
+- [DogeOS quickstart (repo)](./docs/dogeos-quickstart.md)
+- [Action onboarding standard](./docs/action-onboarding-standard.md)
+- [Skill integration RFC](./docs/skill-integration-rfc.md)
 
 ## Install
 
@@ -33,18 +36,19 @@ npx @thirdfy/agent-cli --help
 ## Quick start
 
 ```bash
-export THIRDFY_API_BASE="https://api.thirdfy.com"
 export AGENT_API_KEY="..."
 export THIRDFY_AUTH_TOKEN="..."
 export THIRDFY_OWNER_SESSION_TOKEN="..."
 
-thirdfy-agent actions --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --json
+thirdfy-agent actions --agent-api-key "$AGENT_API_KEY" --json
 thirdfy-agent profile init --profile personal --json
-thirdfy-agent preflight --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
-thirdfy-agent run --api-base "$THIRDFY_API_BASE" --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
-thirdfy-agent intent-status --api-base "$THIRDFY_API_BASE" --intent-id "<intentId>" --json
+thirdfy-agent preflight --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
+thirdfy-agent run --agent-api-key "$AGENT_API_KEY" --action swap --params '{"tokenIn":"0x...","tokenOut":"0x...","amountIn":"1000000"}' --estimated-amount-usd 25 --json
+thirdfy-agent intent-status --intent-id "<intentId>" --json
 ```
 
+By default, the CLI targets production (`https://api.thirdfy.com`). Use `--api-base` (or `THIRDFY_API_BASE`) only for staging/dev/custom deployments.
+
 ## Auth model
 
 - `AGENT_API_KEY`: execution identity and policy-aware action access (`actions --agent-api-key`, `preflight`, `run`)
@@ -56,15 +60,15 @@ Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is c
 ### Wallet-sign onboarding path
 
 ```bash
-thirdfy-agent agent auth challenge --api-base "$THIRDFY_API_BASE" --agent-key "0xYOUR_AGENT_KEY" --json
+thirdfy-agent agent auth challenge --agent-key "0xYOUR_AGENT_KEY" --json
 # Sign challenge.message with your wallet, then:
-thirdfy-agent agent auth verify --api-base "$THIRDFY_API_BASE" --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
+thirdfy-agent agent auth verify --challenge-id "<challengeId>" --signature "0x..." --agent-key "0xYOUR_AGENT_KEY" --json
 ```
 
 Use the returned session token:
 
 ```bash
-thirdfy-agent agent register --api-base "$THIRDFY_API_BASE" --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json
+thirdfy-agent agent register --owner-session-token "$THIRDFY_OWNER_SESSION_TOKEN" --agent-key "0xYOUR_AGENT_KEY" --name "my-agent" --json
 ```
 
 ### Idempotency behavior (`run`)
@@ -113,9 +117,40 @@ Jeff-friendly aliases map directly to core commands:
 - Execution: `preflight`, `run`, `intent-status`, `jeff preflight`, `jeff trade`, `jeff status`
 - Profiles: `profile init`, `profile use`, `profile show`, `whoami`
 - Onboarding: `agent auth challenge`, `agent auth verify`, `agent register`, `agent key rotate`, `agent key revoke`
-- Governance readiness: `delegation upsert`, `delegation status`, `credentials upsert`, `credentials status`
+- Governance readiness: `delegation create`, `delegation activate`, `delegation status`, `credentials upsert`, `credentials status`
 - Account: `credits balance`
 
+## Delegation lifecycle (canonical)
+
+Use `create` + `activate` as the default delegated execution lifecycle:
+
+```bash
+thirdfy-agent delegation create \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --owner-address "0xOWNER_WALLET" \
+  --token-address "0x833589fCD6eDb6E08f4c7C32D4f71b54bdA02913" \
+  --max-usd-per-day 250 \
+  --json
+
+# Sign the returned `data.delegation` payload in your wallet, then:
+thirdfy-agent delegation activate \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --wallet-address "0xOWNER_WALLET" \
+  --session-account-address "0xSESSION_ACCOUNT" \
+  --delegation-manager "0xDELEGATION_MANAGER" \
+  --delegation '{"delegator":"0x...","delegate":"0x...","authority":"0x...","caveats":[],"salt":"0x...","signature":"0x"}' \
+  --signature "0xSIGNED_DELEGATION" \
+  --json
+
+thirdfy-agent delegation status \
+  --auth-token "$THIRDFY_AUTH_TOKEN" \
+  --agent-key "0xYOUR_AGENT_KEY" \
+  --verify \
+  --json
+```
+
 ## More docs
 
 - OpenClaw CLI onboarding flow:

package/bin/thirdfy-agent.mjs

@@ -130,8 +130,11 @@ async function main() {
     case 'credits balance':
       await commandCreditsBalance(context, subFlags, capabilities);
       return;
-    case 'delegation upsert':
-      await commandDelegationUpsert(context, subFlags, capabilities);
+    case 'delegation create':
+      await commandDelegationCreate(context, subFlags, capabilities);
+      return;
+    case 'delegation activate':
+      await commandDelegationActivate(context, subFlags, capabilities);
       return;
     case 'delegation status':
       await commandDelegationStatus(context, subFlags, capabilities);
@@ -388,32 +391,76 @@ async function commandCreditsBalance(ctx, flags, capabilities) {
   });
 }
 
-async function commandDelegationUpsert(ctx, flags, capabilities) {
+async function commandDelegationCreate(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for delegation create');
+  let sessionAccountAddress = String(flags.sessionAccountAddress || '').trim();
+  if (!sessionAccountAddress) {
+    try {
+      const executorAddressResponse = await apiGet(ctx, '/api/v1/agent/delegation/executor-address', {
+        Authorization: `Bearer ${authToken}`,
+      });
+      sessionAccountAddress = String(executorAddressResponse?.data?.executorAddress || '').trim();
+    } catch (error) {
+      if (ctx.verbose) {
+        process.stderr.write(
+          `delegation create: executor-address discovery failed, falling back to --session-account-address (${error?.message || 'unknown error'})\n`
+        );
+      }
+    }
+  }
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    ownerAddress: String(flags.ownerAddress || flags.walletAddress || '').trim() || requireFlag(flags, 'ownerAddress', 'Missing --owner-address'),
+    sessionAccountAddress: sessionAccountAddress || requireFlag(flags, 'sessionAccountAddress', 'Missing --session-account-address'),
+    chainId: Number(flags.chainId || 8453),
+    tokenAddress: requireFlag(flags, 'tokenAddress', 'Missing --token-address'),
+    maxUsdPerDay: Number(requireFlag(flags, 'maxUsdPerDay', 'Missing --max-usd-per-day')),
+    periodDuration: Number(flags.periodDuration || 86_400),
+    expirySeconds: Number(flags.expirySeconds || 86_400),
+  };
+  const response = await apiPost(ctx, '/api/v1/agent/delegation/create', payload, {
+    Authorization: `Bearer ${authToken}`,
+  });
+  const success = Boolean(response?.success !== false);
+  printEnvelope({
+    success,
+    code: success ? 'DELEGATION_CREATED' : 'DELEGATION_CREATE_FAILED',
+    message: response?.message || (success ? 'Delegation payload created' : 'Delegation create failed'),
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandDelegationActivate(ctx, flags, capabilities) {
+  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for delegation activate');
   const payload = {
-    userDid: requireFlag(flags, 'userDid', 'Missing --user-did'),
     agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
     walletAddress: requireFlag(flags, 'walletAddress', 'Missing --wallet-address'),
+    sessionAccountAddress: requireFlag(flags, 'sessionAccountAddress', 'Missing --session-account-address'),
+    sessionAccountType: String(flags.sessionAccountType || 'smart').trim(),
     chainId: Number(flags.chainId || 8453),
-    executionMode: String(flags.executionMode || 'delegated_execution_user'),
+    delegationManager: requireFlag(flags, 'delegationManager', 'Missing --delegation-manager'),
+    signature: requireFlag(flags, 'signature', 'Missing --signature'),
   };
-  if (flags.sessionAccountAddress) payload.sessionAccountAddress = String(flags.sessionAccountAddress).trim();
-  if (flags.sessionAccountType) payload.sessionAccountType = String(flags.sessionAccountType).trim();
-  if (flags.permissionsContext) payload.permissionsContext = String(flags.permissionsContext).trim();
-  if (flags.delegationManager) payload.delegationManager = String(flags.delegationManager).trim();
+  const delegation = parseJsonFlag(flags, 'delegation');
+  payload.delegation = delegation;
   if (flags.permissionsExpiry) payload.permissionsExpiry = String(flags.permissionsExpiry).trim();
-  if (flags.strategyManifestVersion) payload.strategyManifestVersion = String(flags.strategyManifestVersion).trim();
-  if (flags.strategyManifestHash) payload.strategyManifestHash = String(flags.strategyManifestHash).trim();
+  if (flags.permissionsContext) payload.permissionsContext = String(flags.permissionsContext).trim();
+  if (flags.permission) payload.permission = parseJsonFlag(flags, 'permission');
+  if (flags.permissionType) payload.permissionType = String(flags.permissionType).trim();
+  if (flags.permissionData) payload.permissionData = parseJsonFlag(flags, 'permissionData');
   if (flags.modelAConstraints) payload.modelAConstraints = parseJsonFlag(flags, 'modelAConstraints');
-
-  const response = await requestWithRouteFallback(ctx, {
-    method: 'POST',
-    routes: ['/api/v1/agent/delegation/upsert', '/api/v1/agent/agent/delegation/upsert'],
-    body: payload,
+  const response = await apiPost(ctx, '/api/v1/agent/delegation/activate', payload, {
+    Authorization: `Bearer ${authToken}`,
   });
+  const success = Boolean(response?.success !== false);
   printEnvelope({
-    success: Boolean(response?.success !== false),
-    code: response?.updated ? 'DELEGATION_UPDATED' : 'DELEGATION_UPSERTED',
-    message: response?.message || 'Delegation upsert completed',
+    success,
+    code: success ? 'DELEGATION_ACTIVATED' : 'DELEGATION_ACTIVATE_FAILED',
+    message: response?.message || (success ? 'Delegation activated' : 'Delegation activate failed'),
     data: response,
     meta: {
       apiBase: ctx.apiBase,
@@ -1094,15 +1141,29 @@ async function resolveActionSelection(ctx, flags) {
     return { requestedAction, resolvedAction: requestedAction };
   }
 
-  const exact = keyed.filter(
-    (entry) => entry.key.toLowerCase() === requestedLower || entry.aliases.some((a) => a.toLowerCase() === requestedLower)
-  );
-  if (exact.length === 1) {
-    return { requestedAction, resolvedAction: exact[0].key };
+  // Prefer direct action id matches over alias matches.
+  // This keeps UX simple for commands like `--action swap` when another action aliases to "swap".
+  const exactKey = keyed.filter((entry) => entry.key.toLowerCase() === requestedLower);
+  if (exactKey.length === 1) {
+    return { requestedAction, resolvedAction: exactKey[0].key };
+  }
+  if (exactKey.length > 1) {
+    throw new Error(
+      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(
+        exactKey.map((v) => v.key)
+      )}.`
+    );
+  }
+
+  const exactAlias = keyed.filter((entry) => entry.aliases.some((a) => a.toLowerCase() === requestedLower));
+  if (exactAlias.length === 1) {
+    return { requestedAction, resolvedAction: exactAlias[0].key };
   }
-  if (exact.length > 1) {
+  if (exactAlias.length > 1) {
     throw new Error(
-      `Ambiguous --action "${requestedAction}". Multiple exact matches found: ${formatActionList(exact.map((v) => v.key))}.`
+      `Ambiguous --action "${requestedAction}". Alias matches multiple actions: ${formatActionList(
+        exactAlias.map((v) => v.key)
+      )}.`
     );
   }
 
@@ -1250,7 +1311,8 @@ Core commands:
   thirdfy-agent whoami [--json]
   thirdfy-agent catalogs list [--json]
   thirdfy-agent actions [--catalog <id>] [--provider <id>] [--agent-api-key <key>] [--chain-id <id>] [--run-mode <mode>] [--json]
-  thirdfy-agent delegation upsert --user-did <did> --agent-key <key> --wallet-address <addr> [--json]
+  thirdfy-agent delegation create --auth-token <token> --agent-key <key> --owner-address <addr> --token-address <addr> --max-usd-per-day <usd> [--session-account-address <addr>] [--json]
+  thirdfy-agent delegation activate --auth-token <token> --agent-key <key> --wallet-address <addr> --session-account-address <addr> --delegation-manager <addr> --delegation <json> --signature <hex> [--json]
   thirdfy-agent delegation status --auth-token <token> --agent-key <key> [--verify] [--json]
   thirdfy-agent credentials upsert --auth-token <token> --venue <id> --api-key <key> --api-secret <secret> [--json]
   thirdfy-agent credentials status --auth-token <token> [--venue <id>] [--json]

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.4",
+  "version": "0.1.6",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {
@@ -18,6 +18,13 @@
     "test": "node --test \"test/**/*.test.cjs\"",
     "lint": "node --check ./bin/thirdfy-agent.mjs",
     "validate:cli-contract-schemas": "node ./scripts/validate-cli-contract-schemas.mjs",
+    "validate:actions": "node ./scripts/e2e/validate-actions.mjs",
+    "e2e:base:simulate": "node ./scripts/e2e/base-simulate.mjs",
+    "e2e:base:real": "node ./scripts/e2e/base-realtx.mjs",
+    "e2e:delegation:discovery": "node ./scripts/e2e/delegation-discovery.mjs",
+    "e2e:delegation:lifecycle": "node ./scripts/e2e/delegation-lifecycle.mjs",
+    "e2e:delegation:prod:certify": "node ./scripts/e2e/prod-delegation-certify.mjs",
+    "e2e:report:last": "node ./scripts/e2e/report-last.mjs",
     "smoke:cli": "node ./bin/thirdfy-agent.mjs --help && node ./bin/thirdfy-agent.mjs --version --json",
     "prepublishOnly": "npm run validate:cli-contract-schemas && npm run test && npm run smoke:cli"
   },

package/src/utils/cli/intentNormalization.cjs

@@ -19,6 +19,20 @@ function normalizeIntentResponse(response) {
   const executed = Number(response?.executed || 0);
   const total = Number(response?.total || results.length || 0);
   const success = Boolean(response?.success);
+  const topLevelBlockedReason = String(response?.blockedReason || '').trim() || null;
+  const topLevelBlockedStage = String(response?.blockedStage || '').trim() || null;
+  const blockedByReasonFromResponse =
+    response?.blockedByReason && typeof response.blockedByReason === 'object' ? response.blockedByReason : null;
+  const groupedBlocked = summarizeBlockedReasons(results);
+  if (topLevelBlockedReason && !groupedBlocked[topLevelBlockedReason]) {
+    groupedBlocked[topLevelBlockedReason] = 1;
+  }
+  const mergedBlockedByReason = blockedByReasonFromResponse
+    ? { ...groupedBlocked, ...blockedByReasonFromResponse }
+    : groupedBlocked;
+  const topLevelGovernanceSignal = String(response?.governanceSignal || '').trim() || null;
+  const topLevelDelegationSignal = String(response?.delegationSignal || '').trim() || null;
+  const policyEvaluated = response?.policyEvaluated === true;
   return {
     success,
     status: response?.status || (success ? 'queued' : 'failed'),
@@ -28,7 +42,12 @@ function normalizeIntentResponse(response) {
     blocked,
     failed,
     results,
-    blockedByReason: summarizeBlockedReasons(results),
+    blockedByReason: mergedBlockedByReason,
+    blockedReason: topLevelBlockedReason,
+    blockedStage: topLevelBlockedStage,
+    governanceSignal: topLevelGovernanceSignal,
+    delegationSignal: topLevelDelegationSignal,
+    policyEvaluated,
     error: response?.error || null,
     mode: response?.mode || null,
     unsignedTx: response?.unsignedTx || null,