@thirdfy/agent-cli 0.1.1 → 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

@@ -4,16 +4,15 @@ import { randomUUID } from 'crypto';
 import fs from 'fs';
 import path from 'path';
 import { createRequire } from 'module';
-import { pathToFileURL } from 'url';
 
 const require = createRequire(import.meta.url);
 const { normalizeIntentResponse } = require('../src/utils/cli/intentNormalization.cjs');
+const { version: CLI_VERSION } = require('../package.json');
 const {
   normalizeDelegationStatus,
   normalizeCredentialStatus,
 } = require('../src/utils/cli/delegationNormalization.cjs');
 
-const CLI_VERSION = '0.1.0';
 const DEFAULT_API_BASE = 'https://api.thirdfy.com';
 const DEFAULT_TIMEOUT_MS = 30000;
 const DEFAULT_CATALOG_CACHE_TTL_MS = 60_000;
@@ -39,37 +38,25 @@ const context = {
   verbose,
 };
 
-const isEntrypoint = (() => {
-  try {
-    if (!process.argv[1]) return false;
-    const resolvedArgvPath = fs.realpathSync(process.argv[1]);
-    return import.meta.url === pathToFileURL(resolvedArgvPath).href;
-  } catch {
-    return false;
-  }
-})();
-
-if (isEntrypoint) {
-  main().catch((error) => {
-    const statusCode = Number(error?.statusCode || 0) || undefined;
-    const payload = error?.payload && typeof error.payload === 'object' ? error.payload : {};
-    const blockedReason = String(payload.blockedReason || payload.error || '').trim() || undefined;
-    const blockedStage = String(payload.blockedStage || '').trim() || undefined;
-    printEnvelope({
-      success: false,
-      code: statusCode ? 'API_REQUEST_FAILED' : 'CLI_UNHANDLED_ERROR',
-      message: error?.message || 'Unhandled CLI error',
-      data: {
-        statusCode,
-        blockedReason,
-        blockedStage,
-        payload,
-      },
-      meta: { version: CLI_VERSION, apiBase: context.apiBase },
-    });
-    process.exit(1);
+main().catch((error) => {
+  const statusCode = Number(error?.statusCode || 0) || undefined;
+  const payload = error?.payload && typeof error.payload === 'object' ? error.payload : {};
+  const blockedReason = String(payload.blockedReason || payload.error || '').trim() || undefined;
+  const blockedStage = String(payload.blockedStage || '').trim() || undefined;
+  printEnvelope({
+    success: false,
+    code: statusCode ? 'API_REQUEST_FAILED' : 'CLI_UNHANDLED_ERROR',
+    message: error?.message || 'Unhandled CLI error',
+    data: {
+      statusCode,
+      blockedReason,
+      blockedStage,
+      payload,
+    },
+    meta: { version: CLI_VERSION, apiBase: context.apiBase },
   });
-}
+  process.exit(1);
+});
 
 async function main() {
   if (globalFlags.version) {
@@ -126,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) {
@@ -496,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'),
@@ -514,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',
@@ -530,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',
@@ -549,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',
@@ -567,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'),
@@ -700,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;
@@ -806,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]
@@ -818,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.1",
+  "version": "0.1.3",
   "description": "Thirdfy Agent CLI for onboarding, governance preflight, execute-intent, and status polling.",
   "type": "module",
   "bin": {