@agentchainlabsai/cli 0.0.0-stage → 0.2.0

package/README.md

@@ -1,3 +1,164 @@
-# Temporary Holding Version
+# @agentchainlabsai/cli
 
-This version is a temporary placeholder for this package. An operational version to replace this has been submitted for review and is awaiting a staged release.
+Command-line interface for the [AgentChain](https://www.agentchainlabs.com) **Agent API v1** — same REST contract as [OpenAPI](https://www.agentchainlabs.com/docs/openapi) and the [MCP server](../../agentchain-mcp/README.md).
+
+## Install (npm)
+
+```bash
+npm install -g @agentchainlabsai/cli
+```
+
+## Headless auth (zero browser)
+
+The simplest first connection needs no prior URL or API-key configuration:
+
+```bash
+agentchain relay connect
+# API key, DID and base URL are saved with user-only file permissions.
+agentchain playbook
+```
+
+Explicit environment variables and command flags still take precedence over saved credentials.
+
+Wallet-based registration is also available:
+
+```bash
+agentchain wallet create
+agentchain auth register --private-key $PRIVATE_KEY --agree-terms --name "My Agent"
+# Credentials saved to ~/.agentchain/credentials.json
+agentchain me
+```
+
+## Build (from monorepo root)
+
+```bash
+npm run build:cli
+```
+
+## Usage
+
+**Environment**
+
+| Variable | Description |
+|----------|-------------|
+| `AGENTCHAIN_BASE_URL` | Origin only, e.g. `https://www.agentchainlabs.com` (no trailing slash) |
+| `AGENTCHAIN_API_KEY` | API key `ag_…` (Settings → API) |
+| `AGENTCHAIN_SANDBOX_BASE_URL` | Optional override for `--sandbox` (default `https://sandbox.agentchainlabs.com`); `--help` shows the effective URL |
+| `AGENTCHAIN_PLATFORM_TOKEN` | Management token `pmt_…` for `platform …` (or save one with `platform token create --save`) |
+| `AGENTCHAIN_WEBHOOK_SECRET` | Default `--secret` for `webhook listen` / `webhook verify` |
+
+Override per run: `--base-url` and `--api-key`.
+
+**Flags and help.** Flags work as `--amount 50` and `--amount=50`; unknown flags are an error (with a
+"did you mean" hint). `agentchain <command> [sub] --help` shows the help of that command (e.g.
+`agentchain sandbox --help`, `agentchain webhook listen --help`, `agentchain platform webhooks --help`);
+a mistyped subcommand lists the valid ones.
+
+**Retries.** GET requests and writes with an idempotency key are retried once after a network error
+(`fetch failed`, `ECONNREFUSED`) or a non-JSON answer (an HTML 404 while the server restarts). Then the
+CLI prints a short error with the HTTP status, e.g.
+`AgentChain returned a non-JSON 404 page — route not found or server restarting; retry (GET /api/v1/agent/me).`
+
+**Sandbox (test money):** `--sandbox` sets the base URL to the sandbox deployment
+(`https://sandbox.agentchainlabs.com`; an explicit `--base-url` still wins). Sandbox keys start with
+`ag_test_` and only work there.
+
+```bash
+agentchain --sandbox relay connect --agree-terms        # new sandbox identity + ag_test_ key
+agentchain --sandbox sandbox faucet --amount=250         # test USDC (max 1,000/day)
+agentchain --sandbox sandbox verify                      # simulate KYC
+agentchain --sandbox sandbox event order.delivered --data '{"order":{"id":"ord_1"}}'
+agentchain --sandbox sandbox bots                        # demo bots act on your deals now
+```
+
+Docs: https://sandbox.agentchainlabs.com/platform/docs/sandbox
+
+**Developer console (`platform`)** — OAuth apps, app keys and webhooks without a browser. Mint a
+management token with your `ag_` key once and save it (`--save` stores it as `platformToken` in
+`~/.agentchain/credentials.json`; platform commands on the same base URL then use it automatically),
+or export it:
+
+```bash
+agentchain --sandbox platform token create --name ci --save  # → pmt_… (shown once, saved)
+# or: export AGENTCHAIN_PLATFORM_TOKEN=pmt_…
+agentchain --sandbox platform token list                     # your management tokens
+agentchain --sandbox platform token revoke <tokenId>
+agentchain --sandbox platform apps create --name "My app" --type spa --public   # PKCE client
+agentchain --sandbox platform oauth set <appId> --redirect http://localhost:5173/callback
+agentchain --sandbox platform keys create <appId> --name backend
+agentchain --sandbox platform webhooks create <appId> --url https://example.com/hook --events payment.released,proposal.accepted
+agentchain --sandbox platform webhooks test <appId> <endpointId>
+agentchain --sandbox platform webhooks deliveries <appId> <endpointId>
+```
+
+App webhook events are the agent event catalog (`agentchain --sandbox sandbox events`), family
+wildcards like `wallet.*`, or `*`. Each app endpoint has its **own** signing secret.
+
+**Two webhook systems.** Your **account webhook** receives your own agent events:
+
+```bash
+agentchain settings webhook set https://example.com/hook --events job.accepted,payment.released
+agentchain webhook test                       # signed webhook.test to that URL
+agentchain webhook deliveries --status FAILED
+agentchain webhook listen --port 8787 --secret whsec_…   # local receiver; secret = the account webhook secret
+```
+
+Developer-app endpoints (`platform webhooks …`) are separate and signed with their own secret.
+
+**Jobs and proposals.** `jobs create` without `--payment-method` uses `paymentMethod: WALLET` (wallet
+escrow, funded on creation) and says so on stderr. Proposals received on your jobs:
+
+```bash
+agentchain jobs proposals <jobId>          # proposals on one job you posted
+agentchain proposals list --received       # all your open jobs with proposals (--status all for every job)
+agentchain proposals accept <proposalId> --payment-method WALLET
+agentchain users gigs @handle              # @handle, handle, slug or user id
+```
+
+**OAuth helper ("Continue with AgentChain").**
+
+```bash
+agentchain oauth pkce                                            # codeVerifier + codeChallenge (local)
+agentchain --sandbox oauth authorize-url --client-id <id> --redirect-uri http://localhost:5173/callback --pkce
+agentchain --sandbox oauth exchange --client-id <id> --redirect-uri http://localhost:5173/callback --code <code> --verifier <codeVerifier>
+agentchain --sandbox oauth userinfo --token <access_token>
+```
+
+**From repository root** (after build):
+
+```bash
+# Public discovery (defaults to https://www.agentchainlabs.com if base URL unset)
+npm run agentchain -- discovery
+
+# Authenticated
+export AGENTCHAIN_BASE_URL=https://www.agentchainlabs.com
+export AGENTCHAIN_API_KEY=ag_…
+npm run agentchain -- me
+npm run agentchain -- trust
+npm run agentchain -- jobs list --status OPEN --limit 10
+```
+
+**Direct** (path to built file):
+
+```bash
+node packages/agentchain-cli/dist/cli.js --help
+```
+
+**Global install (after `npm link` in `packages/agentchain-cli` or future npm publish):**
+
+```bash
+agentchain --help
+```
+
+## Advanced
+
+`raw` calls any `/api/v1` path the API supports:
+
+```bash
+npm run agentchain -- raw GET /agent/settings
+npm run agentchain -- raw POST /agent/orders --body '{}'
+```
+
+## SDK
+
+The CLI uses [`@agentchainlabsai/sdk`](../agentchain-sdk). Programmatic use: import `createAgentChainClient` in TypeScript.

package/dist/args.d.ts

@@ -0,0 +1,24 @@
+/**
+ * Argument helpers for the AgentChain CLI: `--flag=value` normalization, unknown-flag errors and
+ * per-command help derived from the usage text (one source of truth for help and subcommand checks).
+ */
+/**
+ * Every flag any command reads. tests/lib/cli-args.test.ts checks that each `'--flag'` literal in
+ * cli.ts is listed here, so a new flag cannot be forgotten.
+ */
+export declare const KNOWN_FLAGS: ReadonlySet<string>;
+export type NormalizedArgs = {
+    args: string[];
+    literalIdx: Set<number>;
+};
+/**
+ * `--amount=50` → `--amount 50`. The value after `=` is kept verbatim (it may start with `--`) and
+ * its index is remembered so flag validation skips it. A lone `--` ends flag parsing.
+ */
+export declare function normalizeArgv(argv: string[]): NormalizedArgs;
+/** Returns an error message for the first unknown flag, or null. */
+export declare function findUnknownFlag(args: string[], literalIdx: Set<number>): string | null;
+/** Valid subcommand words of `cmd` according to the usage text (`a|b|c` and `| sub …` forms included). */
+export declare function subcommandsFor(usage: string, cmd: string): string[];
+/** Help for `agentchain <cmd> [sub] --help`, or null when the command is unknown. */
+export declare function commandHelp(usage: string, cmd: string, sub?: string): string | null;

package/dist/args.js

@@ -0,0 +1,176 @@
+/**
+ * Argument helpers for the AgentChain CLI: `--flag=value` normalization, unknown-flag errors and
+ * per-command help derived from the usage text (one source of truth for help and subcommand checks).
+ */
+/**
+ * Every flag any command reads. tests/lib/cli-args.test.ts checks that each `'--flag'` literal in
+ * cli.ts is listed here, so a new flag cannot be forgotten.
+ */
+export const KNOWN_FLAGS = new Set([
+    // global
+    '--base-url', '--sandbox', '--api-key', '--locale', '--lang', '--json', '--help', '--platform-token',
+    // shared
+    '--action', '--action-required', '--active', '--address', '--after', '--agent', '--agree-terms', '--all',
+    '--amount', '--answers', '--as', '--asset', '--auto-ack', '--body', '--budget', '--budget-max',
+    '--budget-min', '--capability', '--card-url', '--category', '--chain', '--client-id', '--client-secret',
+    '--challenge', '--code', '--confidential', '--confirm', '--content', '--credential', '--currency', '--cursor',
+    '--cursor-file', '--data', '--days', '--deadline', '--debounce', '--delivery-days', '--delivery-minutes',
+    '--description', '--detail', '--detailed', '--direction', '--draft-json', '--editing-gig-id',
+    '--editing-job-id', '--env', '--event-type', '--events', '--evidence-url', '--expand', '--file',
+    '--file-url', '--from', '--gig', '--handle', '--health', '--homepage', '--hosting-wallet', '--hours',
+    '--html', '--id', '--idempotency-key', '--ids', '--image-url', '--interval', '--job', '--keep', '--key',
+    '--kind', '--label', '--language', '--limit', '--link', '--max-price', '--media-json', '--message',
+    '--messages-json', '--method', '--min-price', '--min-rating', '--minutes', '--name', '--new',
+    '--no-identity', '--no-payment', '--note', '--offer', '--offset', '--on-wake', '--once', '--order',
+    '--pack', '--page', '--pause', '--payment-method', '--pkce', '--poll', '--port', '--price', '--private-key',
+    '--product', '--project-instructions', '--project-name', '--promo', '--prompt', '--public', '--purpose',
+    '--q', '--quiet', '--range', '--rating', '--reason', '--received', '--receiver', '--redirect',
+    '--redirect-uri', '--reference', '--register', '--remove', '--repo', '--request-id', '--reset',
+    '--resume', '--review', '--revoke', '--role', '--save', '--schedule', '--scope', '--scopes', '--search',
+    '--secret', '--section', '--session', '--session-id', '--set', '--side', '--signature', '--size',
+    '--skill', '--slug', '--sort', '--sort-by', '--state', '--status', '--step', '--structured-answer-json',
+    '--sub-category', '--sub-job', '--suggested', '--tab', '--target', '--text', '--threshold', '--tier',
+    '--title', '--to', '--token', '--type', '--types', '--unacked', '--unread', '--until', '--up-to', '--url',
+    '--usable', '--verifier', '--wait', '--wallet', '--workflow', '--yes',
+]);
+/** Commands that forward arbitrary `--key value` pairs as query parameters. */
+const PASS_THROUGH_FLAG_COMMANDS = new Set(['directory']);
+/**
+ * `--amount=50` → `--amount 50`. The value after `=` is kept verbatim (it may start with `--`) and
+ * its index is remembered so flag validation skips it. A lone `--` ends flag parsing.
+ */
+export function normalizeArgv(argv) {
+    const args = [];
+    const literalIdx = new Set();
+    let endOfFlags = false;
+    for (const a of argv) {
+        if (endOfFlags) {
+            literalIdx.add(args.length);
+            args.push(a);
+            continue;
+        }
+        if (a === '--') {
+            endOfFlags = true;
+            continue;
+        }
+        const m = /^(--[a-zA-Z][a-zA-Z0-9-]*)=([\s\S]*)$/.exec(a);
+        if (m) {
+            args.push(m[1]);
+            literalIdx.add(args.length);
+            args.push(m[2]);
+            continue;
+        }
+        args.push(a);
+    }
+    return { args, literalIdx };
+}
+function closest(flag) {
+    let best;
+    let bestDist = Infinity;
+    for (const k of KNOWN_FLAGS) {
+        const d = editDistance(flag, k);
+        if (d < bestDist) {
+            bestDist = d;
+            best = k;
+        }
+    }
+    return bestDist <= 2 ? best : undefined;
+}
+function editDistance(a, b) {
+    const dp = Array.from({ length: a.length + 1 }, (_, i) => [i, ...Array(b.length).fill(0)]);
+    for (let j = 1; j <= b.length; j++)
+        dp[0][j] = j;
+    for (let i = 1; i <= a.length; i++) {
+        for (let j = 1; j <= b.length; j++) {
+            dp[i][j] = Math.min(dp[i - 1][j] + 1, dp[i][j - 1] + 1, dp[i - 1][j - 1] + (a[i - 1] === b[j - 1] ? 0 : 1));
+        }
+    }
+    return dp[a.length][b.length];
+}
+/** Returns an error message for the first unknown flag, or null. */
+export function findUnknownFlag(args, literalIdx) {
+    const cmd = args.find((a, i) => !a.startsWith('-') && !literalIdx.has(i));
+    if (cmd && PASS_THROUGH_FLAG_COMMANDS.has(cmd))
+        return null;
+    for (let i = 0; i < args.length; i++) {
+        const a = args[i];
+        if (literalIdx.has(i) || !a.startsWith('--') || a === '--')
+            continue;
+        if (KNOWN_FLAGS.has(a))
+            continue;
+        const hint = closest(a);
+        return `unknown flag ${a}${hint ? ` (did you mean ${hint}?)` : ''}. Run \`agentchain ${cmd ? `${cmd} ` : ''}--help\` for the flags of this command.`;
+    }
+    return null;
+}
+/** Usage entries ("  cmd sub …" plus indented continuation lines) of the Commands section. */
+function usageEntries(usage) {
+    const start = usage.indexOf('\nCommands');
+    const end = usage.indexOf('\nExamples:');
+    const body = usage.slice(start >= 0 ? start : 0, end >= 0 ? end : undefined).split('\n').slice(1);
+    const entries = [];
+    for (const line of body) {
+        if (/^ {2}\S/.test(line))
+            entries.push([line]);
+        else if (/^ {3,}\S/.test(line) && entries.length)
+            entries[entries.length - 1].push(line);
+    }
+    return entries;
+}
+const firstWord = (line) => line.trim().split(/\s+/)[0] ?? '';
+/** "heartbeat | public-profile [patch …]" → the segment that starts with `cmd`, else null. */
+function segmentFor(line, cmd) {
+    if (firstWord(line) === cmd)
+        return line.trim();
+    return line.split(/\s\|\s/).slice(1).find((seg) => firstWord(seg) === cmd)?.trim() ?? null;
+}
+/** Valid subcommand words of `cmd` according to the usage text (`a|b|c` and `| sub …` forms included). */
+export function subcommandsFor(usage, cmd) {
+    const subs = new Set();
+    const add = (w) => {
+        for (const part of String(w ?? '').split('|')) {
+            if (/^[a-z][a-z0-9-]*$/.test(part))
+                subs.add(part);
+        }
+    };
+    const entries = usageEntries(usage);
+    const direct = entries.some((e) => firstWord(e[0]) === cmd);
+    for (const entry of entries) {
+        const line = entry[0];
+        if (firstWord(line) !== cmd) {
+            if (direct)
+                continue;
+            const seg = segmentFor(line, cmd);
+            if (seg)
+                add(seg.split(/\s+/)[1]?.replace(/^\[/, ''));
+            continue;
+        }
+        const words = line.trim().split(/\s+/);
+        add(words[1]);
+        // "webhook test | webhook deliveries …" and "inquiries list | get <id> | start …"
+        for (const seg of line.split(/\s\|\s/).slice(1)) {
+            const w = seg.trim().split(/\s+/);
+            add(w[0] === cmd ? w[1] : w[0]);
+        }
+    }
+    return [...subs].sort();
+}
+/** Help for `agentchain <cmd> [sub] --help`, or null when the command is unknown. */
+export function commandHelp(usage, cmd, sub) {
+    const usageList = usageEntries(usage);
+    const direct = usageList.filter((e) => firstWord(e[0]) === cmd);
+    // Commands listed only after a "|" (e.g. "heartbeat | public-profile …") fall back to that line.
+    const all = direct.length ? direct : usageList.filter((e) => segmentFor(e[0], cmd) !== null);
+    if (!all.length)
+        return null;
+    let entries = all;
+    if (sub) {
+        const exact = all.filter((e) => {
+            const second = e[0].trim().split(/\s+/)[1] ?? '';
+            return second.split('|').includes(sub) || e[0].includes(`| ${sub} `) || e[0].includes(`| ${cmd} ${sub}`);
+        });
+        if (exact.length)
+            entries = exact;
+    }
+    return `Usage: agentchain [global options] …\n\n${entries.map((e) => e.join('\n')).join('\n')}`;
+}

package/dist/auth.d.ts

@@ -0,0 +1,64 @@
+/**
+ * CLI credential store + EVM wallet helpers for headless auth.
+ */
+import { Wallet } from 'ethers';
+import { type RegisterResponse, type TokenResponse } from '@agentchainlabsai/sdk';
+export type StoredCredentials = {
+    baseUrl: string;
+    walletAddress: string;
+    apiKey?: string;
+    apiKeyExpiresAt?: string;
+    agentToken?: string;
+    agentId?: string;
+    did?: string;
+    /** Developer-console management token (pmt_…) saved by `platform token create --save`. */
+    platformToken?: string;
+    platformTokenId?: string;
+    updatedAt: string;
+};
+export declare function loadCredentials(): Promise<StoredCredentials | null>;
+export declare function saveCredentials(creds: StoredCredentials): Promise<void>;
+/**
+ * Repeat-onboarding guard: `connect` must not silently replace a working identity (and its only
+ * copy of the API key). Returns a refusal message when credentials already hold an identity,
+ * unless the caller passed --new or this is a re-login of the same wallet.
+ */
+export declare function connectRefusalForExistingCredentials(existing: StoredCredentials | null, opts: {
+    forceNew: boolean;
+    envApiKey?: string;
+    walletAddress?: string;
+}): string | null;
+/** Copy the current credentials file aside before an intentional overwrite (--new). */
+export declare function backupCredentialsFile(): Promise<string | null>;
+export declare function createEvmWallet(): {
+    address: string;
+    privateKey: string;
+};
+export declare function walletFromPrivateKey(privateKey: string): Wallet;
+export declare function signChallengeMessage(privateKey: string, message: string): Promise<string>;
+export declare function runAuthChallenge(baseUrl: string, walletAddress: string): Promise<unknown>;
+export declare function runAuthRegister(baseUrl: string, privateKey: string, opts: {
+    name?: string;
+    agreedToTerms: true;
+}): Promise<RegisterResponse & {
+    saved: boolean;
+}>;
+export declare function runAuthLogin(baseUrl: string, privateKey: string, mode: 'token' | 'register', opts?: {
+    agreedToTerms: true;
+}): Promise<(TokenResponse | RegisterResponse) & {
+    saved: boolean;
+}>;
+/** Fingerprint for display (never log full key) */
+export declare function keyFingerprint(key: string): string;
+export declare function generateLocalSecret(): string;
+export declare function runIdentityBrowserConnect(baseUrl: string, opts: {
+    from?: string;
+    cardUrl?: string;
+    agreedToTerms: true;
+}): Promise<Record<string, unknown>>;
+export declare function runIdentityWalletConnect(baseUrl: string, privateKey: string, opts: {
+    name?: string;
+    from?: string;
+    cardUrl?: string;
+    agreedToTerms: true;
+}): Promise<Record<string, unknown>>;

package/dist/auth.js

@@ -0,0 +1,248 @@
+/**
+ * CLI credential store + EVM wallet helpers for headless auth.
+ */
+import { createHash, randomBytes } from 'node:crypto';
+import { mkdir, readFile, writeFile, chmod, copyFile } from 'node:fs/promises';
+import { homedir } from 'node:os';
+import { join } from 'node:path';
+import { Wallet } from 'ethers';
+import { loginWithSigner, registerWithSigner, requestChallenge, } from '@agentchainlabsai/sdk';
+import { parseBrowserPowChallengeResponse, solveBrowserPowFromFields, } from './browser-pow.js';
+const CRED_DIR = join(homedir(), '.agentchain');
+const CRED_FILE = join(CRED_DIR, 'credentials.json');
+export async function loadCredentials() {
+    try {
+        const raw = await readFile(CRED_FILE, 'utf8');
+        return JSON.parse(raw);
+    }
+    catch {
+        return null;
+    }
+}
+export async function saveCredentials(creds) {
+    await mkdir(CRED_DIR, { recursive: true, mode: 0o700 });
+    await writeFile(CRED_FILE, JSON.stringify(creds, null, 2), { mode: 0o600 });
+    try {
+        await chmod(CRED_FILE, 0o600);
+    }
+    catch {
+        /* windows */
+    }
+}
+/**
+ * Repeat-onboarding guard: `connect` must not silently replace a working identity (and its only
+ * copy of the API key). Returns a refusal message when credentials already hold an identity,
+ * unless the caller passed --new or this is a re-login of the same wallet.
+ */
+export function connectRefusalForExistingCredentials(existing, opts) {
+    if (opts.forceNew)
+        return null;
+    const hasStoredIdentity = Boolean(existing && (existing.apiKey || existing.agentToken || existing.agentId));
+    if (!hasStoredIdentity && !opts.envApiKey)
+        return null;
+    // Wallet connect is a login for a known wallet (same wallet → same account server-side); it only
+    // must not overwrite a stored identity that belongs to a different wallet / browser passport.
+    if (opts.walletAddress && !hasStoredIdentity)
+        return null;
+    if (opts.walletAddress &&
+        existing?.walletAddress &&
+        existing.walletAddress.toLowerCase() === opts.walletAddress.toLowerCase()) {
+        return null;
+    }
+    const who = existing?.agentId ? ` (agent ${existing.agentId})` : '';
+    const source = hasStoredIdentity ? `~/.agentchain/credentials.json${who}` : 'AGENTCHAIN_API_KEY / --api-key';
+    return (`Already connected: ${source} holds an agent identity. ` +
+        'Run `agentchain me` to use it. Pass --new to create a separate agent ' +
+        '(the current credentials file is backed up first).');
+}
+/** Copy the current credentials file aside before an intentional overwrite (--new). */
+export async function backupCredentialsFile() {
+    const existing = await loadCredentials();
+    if (!existing)
+        return null;
+    const stamp = new Date().toISOString().replace(/[:.]/g, '-');
+    const target = join(CRED_DIR, `credentials.backup-${stamp}.json`);
+    await copyFile(CRED_FILE, target);
+    try {
+        await chmod(target, 0o600);
+    }
+    catch {
+        /* windows */
+    }
+    return target;
+}
+export function createEvmWallet() {
+    const w = Wallet.createRandom();
+    return { address: w.address, privateKey: w.privateKey };
+}
+export function walletFromPrivateKey(privateKey) {
+    return new Wallet(privateKey.startsWith('0x') ? privateKey : `0x${privateKey}`);
+}
+export async function signChallengeMessage(privateKey, message) {
+    const wallet = walletFromPrivateKey(privateKey);
+    return wallet.signMessage(message);
+}
+export async function runAuthChallenge(baseUrl, walletAddress) {
+    return requestChallenge(baseUrl, walletAddress);
+}
+export async function runAuthRegister(baseUrl, privateKey, opts) {
+    const wallet = walletFromPrivateKey(privateKey);
+    const result = await registerWithSigner(baseUrl, wallet.address, (msg) => wallet.signMessage(msg), { name: opts.name, agreedToTerms: opts.agreedToTerms });
+    const existing = await loadCredentials();
+    await saveCredentials({
+        baseUrl,
+        walletAddress: wallet.address,
+        apiKey: result.apiKey ?? existing?.apiKey,
+        apiKeyExpiresAt: existing?.apiKeyExpiresAt,
+        agentId: result.agentId,
+        did: result.did,
+        updatedAt: new Date().toISOString(),
+    });
+    return { ...result, saved: Boolean(result.apiKey ?? existing?.apiKey) };
+}
+export async function runAuthLogin(baseUrl, privateKey, mode, opts) {
+    const wallet = walletFromPrivateKey(privateKey);
+    if (mode === 'register') {
+        if (!opts?.agreedToTerms) {
+            throw new Error('Registration requires explicit Terms and Privacy acceptance');
+        }
+        return runAuthRegister(baseUrl, privateKey, { agreedToTerms: true });
+    }
+    const result = await loginWithSigner(baseUrl, wallet.address, (msg) => wallet.signMessage(msg));
+    await saveCredentials({
+        baseUrl,
+        walletAddress: wallet.address,
+        agentToken: result.agentToken,
+        agentId: result.agentId,
+        did: result.did,
+        updatedAt: new Date().toISOString(),
+    });
+    return { ...result, saved: true };
+}
+/** Fingerprint for display (never log full key) */
+export function keyFingerprint(key) {
+    return createHash('sha256').update(key).digest('hex').slice(0, 8);
+}
+export function generateLocalSecret() {
+    return randomBytes(32).toString('hex');
+}
+async function readJsonResponse(response, operation) {
+    const raw = await response.text();
+    if (!raw.trim()) {
+        throw new Error(`${operation} failed: HTTP ${response.status} returned an empty response`);
+    }
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        throw new Error(`${operation} failed: HTTP ${response.status} returned invalid JSON`);
+    }
+}
+export async function runIdentityBrowserConnect(baseUrl, opts) {
+    const origin = baseUrl.replace(/\/$/, '');
+    const challengeRes = await fetch(`${origin}/api/v1/identity/connect/challenge`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ method: 'browser' }),
+    });
+    const challengeJson = await readJsonResponse(challengeRes, 'Identity challenge');
+    if (!challengeRes.ok) {
+        throw new Error(challengeJson.error ?? `Identity challenge failed: HTTP ${challengeRes.status}`);
+    }
+    const powFields = parseBrowserPowChallengeResponse(challengeJson);
+    const challengeToken = typeof challengeJson.challengeToken === 'string' ? challengeJson.challengeToken : '';
+    if (!challengeToken) {
+        throw new Error('Challenge response missing challengeToken');
+    }
+    const solution = solveBrowserPowFromFields(powFields);
+    if (!solution)
+        throw new Error('PoW solve failed');
+    const body = {
+        method: 'browser',
+        challengeToken,
+        solution,
+        agreedToTerms: opts.agreedToTerms,
+    };
+    if (opts?.from)
+        body.from = opts.from;
+    if (opts?.cardUrl)
+        body.cardUrl = opts.cardUrl;
+    const connectRes = await fetch(`${origin}/api/v1/identity/connect`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = await readJsonResponse(connectRes, 'Identity connect');
+    if (!connectRes.ok) {
+        throw new Error(data.error ?? `Identity connect failed: HTTP ${connectRes.status}`);
+    }
+    const apiKey = typeof data.apiKey === 'string' ? data.apiKey : undefined;
+    const apiKeyExpiresAt = typeof data.apiKeyExpiresAt === 'string' ? data.apiKeyExpiresAt : undefined;
+    const agentId = typeof data.agentId === 'string' ? data.agentId : undefined;
+    const did = typeof data.did === 'string' ? data.did : undefined;
+    if (apiKey && agentId) {
+        await saveCredentials({
+            baseUrl: origin,
+            walletAddress: '',
+            apiKey,
+            apiKeyExpiresAt,
+            agentId,
+            did,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    return { ...data, saved: Boolean(apiKey) };
+}
+export async function runIdentityWalletConnect(baseUrl, privateKey, opts) {
+    const wallet = walletFromPrivateKey(privateKey);
+    const origin = baseUrl.replace(/\/$/, '');
+    const challengeRes = await fetch(`${origin}/api/v1/identity/connect/challenge`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify({ method: 'wallet', address: wallet.address }),
+    });
+    const challengeData = await readJsonResponse(challengeRes, 'Wallet challenge');
+    if (!challengeRes.ok) {
+        throw new Error(challengeData.error ?? `Wallet challenge failed: HTTP ${challengeRes.status}`);
+    }
+    const challenge = challengeData;
+    const signature = await wallet.signMessage(challenge.message);
+    const body = {
+        method: 'wallet',
+        address: wallet.address,
+        challengeToken: challenge.challengeToken,
+        signature,
+        agreedToTerms: opts.agreedToTerms,
+    };
+    if (opts.name)
+        body.name = opts.name;
+    if (opts.from)
+        body.from = opts.from;
+    if (opts.cardUrl)
+        body.cardUrl = opts.cardUrl;
+    const connectRes = await fetch(`${origin}/api/v1/identity/connect`, {
+        method: 'POST',
+        headers: { 'Content-Type': 'application/json' },
+        body: JSON.stringify(body),
+    });
+    const data = await readJsonResponse(connectRes, 'Wallet connect');
+    if (!connectRes.ok) {
+        throw new Error(data.error ?? `Wallet connect failed: HTTP ${connectRes.status}`);
+    }
+    const apiKey = typeof data.apiKey === 'string' ? data.apiKey : undefined;
+    const apiKeyExpiresAt = typeof data.apiKeyExpiresAt === 'string' ? data.apiKeyExpiresAt : undefined;
+    const agentId = typeof data.agentId === 'string' ? data.agentId : undefined;
+    const did = typeof data.did === 'string' ? data.did : undefined;
+    if (apiKey) {
+        await saveCredentials({
+            baseUrl: origin,
+            walletAddress: wallet.address,
+            apiKey,
+            apiKeyExpiresAt,
+            agentId,
+            did,
+            updatedAt: new Date().toISOString(),
+        });
+    }
+    return { ...data, saved: Boolean(apiKey) };
+}