@thirdfy/agent-cli 0.1.2 → 0.1.3

package/README.md

@@ -34,25 +34,47 @@ npx @thirdfy/agent-cli --help
 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 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 --idempotency-key "swap-001" --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
 ```
 
 ## Auth model
 
 - `AGENT_API_KEY`: execution identity and policy-aware action access (`actions --agent-api-key`, `preflight`, `run`)
-- `THIRDFY_AUTH_TOKEN`: user-scoped onboarding and account/governance operations (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
+- `THIRDFY_AUTH_TOKEN`: Privy-native owner/account auth (`agent register`, `agent key *`, `delegation *`, `credentials *`, `credits balance`)
+- `THIRDFY_OWNER_SESSION_TOKEN`: wallet-sign owner auth session (`agent register`, `agent key *`)
 
 Execution-only workflows can run with only `AGENT_API_KEY` after onboarding is complete.
 
+### Wallet-sign onboarding path
+
+```bash
+thirdfy-agent agent auth challenge --api-base "$THIRDFY_API_BASE" --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
+```
+
+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
+```
+
+### Idempotency behavior (`run`)
+
+- `run` auto-generates `idempotencyKey` by default when not provided.
+- For deterministic retries across workers/restarts, pass your own stable `--idempotency-key`.
+- `preflight` does not force idempotency keys.
+
 ## Command groups
 
 - Discovery: `catalogs list`, `actions`
 - Execution: `preflight`, `run`, `intent-status`
-- Onboarding: `agent register`, `agent key rotate`, `agent key revoke`
+- 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`
 - Account: `credits balance`
 

package/bin/thirdfy-agent.mjs

@@ -113,6 +113,14 @@ async function main() {
     await commandAgentKeyRevoke(context, subFlags, capabilities);
     return;
   }
+  if (commandKey3 === 'agent auth challenge') {
+    await commandAgentAuthChallenge(context, subFlags, capabilities);
+    return;
+  }
+  if (commandKey3 === 'agent auth verify') {
+    await commandAgentAuthVerify(context, subFlags, capabilities);
+    return;
+  }
 
   const rootCommand = parsed.positionals[0];
   switch (rootCommand) {
@@ -483,7 +491,10 @@ async function commandCredentialsStatus(ctx, flags, capabilities) {
 }
 
 async function commandAgentRegister(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent register');
+  const ownerHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing owner auth for agent register: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token'
+  );
   const payload = {
     agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
     name: requireFlag(flags, 'name', 'Missing --name'),
@@ -501,9 +512,10 @@ async function commandAgentRegister(ctx, flags, capabilities) {
   if (flags.strategy) payload.strategy = parseJsonFlag(flags, 'strategy');
   if (flags.apiKeyEnvelopePublicKey) payload.apiKeyEnvelopePublicKey = String(flags.apiKeyEnvelopePublicKey);
 
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/register-with-privy', payload, {
-    Authorization: `Bearer ${authToken}`,
-  });
+  const route = ownerHeaders['x-owner-session-token']
+    ? '/api/v1/agent/onboarding/register-with-wallet'
+    : '/api/v1/agent/onboarding/register-with-privy';
+  const response = await apiPost(ctx, route, payload, ownerHeaders);
   printEnvelope({
     success: true,
     code: 'AGENT_REGISTERED',
@@ -517,12 +529,13 @@ async function commandAgentRegister(ctx, flags, capabilities) {
 }
 
 async function commandAgentKeyRotate(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent key rotate');
+  const ownerHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing owner auth for agent key rotate: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token'
+  );
   const payload = {};
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/rotate', payload, {
-    Authorization: `Bearer ${authToken}`,
-  });
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/rotate', payload, ownerHeaders);
   printEnvelope({
     success: true,
     code: 'AGENT_KEY_ROTATED',
@@ -536,12 +549,13 @@ async function commandAgentKeyRotate(ctx, flags, capabilities) {
 }
 
 async function commandAgentKeyRevoke(ctx, flags, capabilities) {
-  const authToken = getAuthToken(flags, 'Missing --auth-token (or THIRDFY_AUTH_TOKEN) for agent key revoke');
+  const ownerHeaders = buildOwnerAuthHeaders(
+    flags,
+    'Missing owner auth for agent key revoke: provide --auth-token (THIRDFY_AUTH_TOKEN) or --owner-session-token'
+  );
   const payload = {};
   if (flags.agentKey) payload.agentKey = String(flags.agentKey).trim();
-  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/revoke', payload, {
-    Authorization: `Bearer ${authToken}`,
-  });
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/me/api-key/revoke', payload, ownerHeaders);
   printEnvelope({
     success: true,
     code: 'AGENT_KEY_REVOKED',
@@ -554,6 +568,47 @@ async function commandAgentKeyRevoke(ctx, flags, capabilities) {
   });
 }
 
+async function commandAgentAuthChallenge(ctx, flags, capabilities) {
+  const payload = {
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+    chainId: Number(flags.chainId || 8453),
+  };
+  if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/challenge', payload);
+  printEnvelope({
+    success: true,
+    code: 'OWNER_CHALLENGE_CREATED',
+    message: 'Wallet challenge created',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
+async function commandAgentAuthVerify(ctx, flags, capabilities) {
+  const payload = {
+    challengeId: requireFlag(flags, 'challengeId', 'Missing --challenge-id'),
+    signature: requireFlag(flags, 'signature', 'Missing --signature'),
+    agentKey: requireFlag(flags, 'agentKey', 'Missing --agent-key'),
+  };
+  if (flags.walletAddress) payload.walletAddress = String(flags.walletAddress).trim();
+
+  const response = await apiPost(ctx, '/api/v1/agent/onboarding/wallet/verify', payload);
+  printEnvelope({
+    success: true,
+    code: 'OWNER_VERIFIED',
+    message: 'Wallet challenge verified',
+    data: response,
+    meta: {
+      apiBase: ctx.apiBase,
+      capabilitiesVersion: capabilities?.contractVersion || null,
+    },
+  });
+}
+
 function buildIntentPayload(flags, options) {
   const payload = {
     agentApiKey: requireFlag(flags, 'agentApiKey', 'Missing --agent-api-key'),
@@ -687,6 +742,18 @@ function getAuthToken(flags, missingMessage) {
   return authToken;
 }
 
+function buildOwnerAuthHeaders(flags, missingMessage) {
+  const authToken = String(flags.authToken || process.env.THIRDFY_AUTH_TOKEN || '').trim();
+  const ownerSessionToken = String(flags.ownerSessionToken || process.env.THIRDFY_OWNER_SESSION_TOKEN || '').trim();
+  if (!authToken && !ownerSessionToken) {
+    throw new Error(missingMessage);
+  }
+  if (authToken) {
+    return { Authorization: `Bearer ${authToken}` };
+  }
+  return { 'x-owner-session-token': ownerSessionToken };
+}
+
 function extractActions(response) {
   if (Array.isArray(response)) return response;
   if (Array.isArray(response.actions)) return response.actions;
@@ -793,9 +860,11 @@ Core commands:
   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]
-  thirdfy-agent agent register --auth-token <token> --agent-key <key> --name <name> [--json]
-  thirdfy-agent agent key rotate --auth-token <token> [--agent-key <key>] [--json]
-  thirdfy-agent agent key revoke --auth-token <token> [--agent-key <key>] [--json]
+  thirdfy-agent agent auth challenge --agent-key <key> [--wallet-address <addr>] [--chain-id <id>] [--json]
+  thirdfy-agent agent auth verify --challenge-id <id> --signature <hex> --agent-key <key> [--wallet-address <addr>] [--json]
+  thirdfy-agent agent register --agent-key <key> --name <name> [--auth-token <token> | --owner-session-token <token>] [--json]
+  thirdfy-agent agent key rotate [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
+  thirdfy-agent agent key revoke [--agent-key <key>] [--auth-token <token> | --owner-session-token <token>] [--json]
   thirdfy-agent preflight --agent-api-key <key> --action <id> --params <json> [--json]
   thirdfy-agent run --agent-api-key <key> --action <id> --params <json> [--idempotency-key <key>] [--json]
   thirdfy-agent intent-status --intent-id <id> [--json]
@@ -805,6 +874,7 @@ Global flags:
   --api-base <url>   default: https://api.thirdfy.com
   --env <file>       load env vars from file
   --timeout <ms>     request timeout
+  --owner-session-token <token>  owner session token (or THIRDFY_OWNER_SESSION_TOKEN)
   --json             stable machine-readable output
   --verbose          print adapter diagnostics
   --version          print version

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@thirdfy/agent-cli",
-  "version": "0.1.2",
+  "version": "0.1.3",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {