@astrasyncai/verification-gateway 2.3.10 → 2.4.1

package/README.md

@@ -1,18 +1,26 @@
 # @astrasyncai/verification-gateway
 
-Universal Verification Gateway for AstraSync KYA Platform - verify AI agents across any counterparty type.
+The AstraSync KYA Platform SDK. One package, two roles: register agents with the KYA backend, and verify agents at any counterparty type (API / MCP / website / agent-to-agent).
 
-## Which package do I install?
+## What's in this package?
 
-AstraSync ships two npm packages with deliberately distinct roles. Pick by who you are, not by what you're building:
+As of v2.4.0 this is the only npm package you need for AstraSync integration. Pick the subpath that matches what you're doing:
 
-| You are…                                                                                      | Install                                                       | Use it for                                                                                                               |
-| --------------------------------------------------------------------------------------------- | ------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
-| **A merchant / counterparty** running an API, MCP server, or website that AI agents call into | `@astrasyncai/verification-gateway` (this package)            | Verifying inbound agents before they hit your endpoint. Express + Next.js middleware, Commerce Shield, webhook verifier. |
-| **An agent author** building an AI agent that calls out to other people's services            | `@astrasyncai/sdk` (the agent-side SDK on npm, separate repo) | Registering your agent with AstraSync, attaching credentials to outbound HTTP / MCP / A2A calls, KYD onboarding.         |
-| **A platform / orchestrator** doing both ends in one place                                    | Both                                                          | The two roles compose: each side's flow is independent.                                                                  |
+| If you're…                                                                                | Import from                                      | Get                                                                                           |
+| ----------------------------------------------------------------------------------------- | ------------------------------------------------ | --------------------------------------------------------------------------------------------- |
+| **Registering an agent with the KYA backend**                                             | `@astrasyncai/verification-gateway/registration` | `AstraSync` class — `register()`, `verify()`, `health()`. The `astrasync` CLI is bundled too. |
+| **Building an agent that calls out to other services** (per-request credential injection) | `@astrasyncai/verification-gateway/agent`        | `AgentClient`, `ChallengeHandler`, ownership validation, runtime PDLSS shape.                 |
+| **Running an Express API that AI agents call into**                                       | `@astrasyncai/verification-gateway/express`      | `createMiddleware()` — protect routes, attach verification context.                           |
+| **Running a Next.js app that AI agents call into**                                        | `@astrasyncai/verification-gateway/nextjs`       | `createMiddleware()`, Commerce Shield wiring.                                                 |
+| **Running an MCP server that AI agents call into**                                        | `@astrasyncai/verification-gateway/mcp`          | MCP tool gates + inner-hop dedupe headers.                                                    |
+| **Doing direct verification (no framework)**                                              | `@astrasyncai/verification-gateway/sdk`          | `VerificationGatewayClient` with retry / backoff / timeout.                                   |
+| **Parsing protocol-level credentials** (HTTP / A2A / MCP / x402 / AP2 / MPP)              | `@astrasyncai/verification-gateway/transport`    | Cross-protocol credential extraction + injection.                                             |
+| **Evaluating PDLSS offline** (local / hybrid mode)                                        | `@astrasyncai/verification-gateway/gateway`      | `AstraSyncGateway` (online / local / hybrid).                                                 |
+| **Receiving webhook callbacks**                                                           | `@astrasyncai/verification-gateway/webhooks`     | `verifyAstraSyncWebhook()`, `signAstraSyncWebhook()`.                                         |
 
-> Both packages talk to the same backend — `POST /agents/verify-access`. The contract is shared; the role is just which side you're sitting on.
+> All subpaths talk to the same backend — `POST /agents/verify-access` for verification, `POST /agents/register` for registration. The contract is shared; the role is just which side of the handshake you're sitting on.
+
+Before v2.4.0 the agent-registration half shipped as a separate package (`@astrasyncai/agent-registration`, briefly; `@astrasyncai/sdk` before that). It was merged in to stop the two-package version drift and to give partners one install instead of two. The legacy `@astrasyncai/sdk` package on npm is deprecated with a pointer to this package; `@astrasyncai/agent-registration` was never published.
 
 ## Overview
 
@@ -95,6 +103,130 @@ if (result.verified && result.accessLevel !== 'none') {
 }
 ```
 
+### Agent Registration
+
+**Use the SDK for all agent registration**, whether you're a developer firing off a one-shot CLI call or an autonomous agent self-registering on first run. The SDK handles auth-mode routing for you: signature-authenticated callers get synchronous registration; API-key-only callers get an owner-approval handshake (server-side rule, not negotiable).
+
+#### `apiEndpoint` — runtime-challenge URL
+
+`apiEndpoint` is the URL where your agent's verification-gateway SDK is mounted to receive runtime challenges from counterparties. Optional but recommended — if you omit it, your agent declares no runtime-challenge support, which is included in the verification payload and may cause some counterparties to decline access requests.
+
+#### Two registration response modes
+
+The same `register()` call returns one of two shapes depending on auth context:
+
+- **201 active** — synchronous: returned when the request is signed with a crypto keypair (`privateKey` configured) or when authenticated via email+password. Result: `{ status: 'active', agent }`.
+- **202 pending_approval** — API-key only: the SDK was authenticated with an API key but the request was not signed. The backend emails the account owner a "Sign In to Accept" link, fires a dashboard alert, and returns a tracking token. Result: `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The agent becomes active only after the owner approves.
+
+This split enforces the platform rule that **API-key registrations always require owner step-up** — registering an agent autonomously with just an API key is not a sufficient authority signal on its own.
+
+#### Pattern A — developer / long-running agent (block until approved)
+
+Best for CLI tools, dev-machine first-run, and long-running services:
+
+```typescript
+import {
+  AstraSync,
+  RegistrationDeniedError,
+  RegistrationTimeoutError,
+} from '@astrasyncai/verification-gateway/registration';
+
+const sdk = new AstraSync({
+  apiKey: process.env.ASTRASYNC_API_KEY,
+  privateKey: process.env.ASTRASYNC_PRIVATE_KEY, // optional — when set, 201 sync path
+});
+
+try {
+  const agent = await sdk.register({
+    name: 'invoice-bot',
+    description: 'Reconciles AP/AR across accounting systems.',
+    agentType: 'autonomous',
+    apiEndpoint: 'https://invoice-bot.example.com', // runtime-challenge URL
+    model: { modelProvider: 'anthropic', modelName: 'claude-sonnet-4-5' },
+    framework: { frameworkName: 'langchain', frameworkVersion: '0.3.0' },
+    protocols: ['a2a', 'mcp'],
+    pdlss: {
+      purpose: {
+        categories: ['accounting'],
+        allowedActions: ['accounting.read', 'accounting.write'],
+      },
+      limits: { stepUpThreshold: 1_000, approvalThreshold: 10_000, currency: 'USD' },
+      scope: { resources: ['xero.invoices', 'quickbooks.bills'] },
+      selfInstantiation: { allowed: false },
+    },
+    // Blocking mode: poll until the request resolves.
+    waitForApproval: true,
+    timeoutMs: 10 * 60 * 1000, // 10 minutes default
+    onPending: ({ ageMs }) =>
+      console.log(`Awaiting owner approval (${(ageMs / 1000).toFixed(0)}s)…`),
+  });
+  console.log(`Agent registered: ${agent.astrasyncIdLevel1}`);
+} catch (err) {
+  if (err instanceof RegistrationDeniedError) {
+    console.error('Owner denied:', err.reason);
+  } else if (err instanceof RegistrationTimeoutError) {
+    console.error(
+      'Timed out — request is still active server-side; poll later via sdk.waitForApproval(requestId)'
+    );
+  } else {
+    throw err;
+  }
+}
+```
+
+#### Pattern B — serverless / scheduled agent (non-blocking, exit and resume)
+
+Best for Lambda / Cloud Functions / cron-driven self-registration where you can't hold the runtime open for minutes:
+
+```typescript
+const sdk = new AstraSync({ apiKey: process.env.ASTRASYNC_API_KEY });
+
+const result = await sdk.register({
+  name: 'invoice-bot',
+  apiEndpoint: 'https://invoice-bot.example.com',
+  pdlss: { purpose: { categories: ['accounting'], allowedActions: ['accounting.read'] } },
+});
+
+if (result.status === 'pending_approval') {
+  // Store the requestId in your durable storage (DynamoDB, KV, etc.)
+  await store.set('astrasync.pendingRequestId', result.requestId);
+  console.log(`Awaiting owner approval at ${result.pollUrl}; will resume on next scheduled run.`);
+  return; // function exits — owner has time to approve
+}
+
+console.log(`Agent registered as ${result.agent.astrasyncIdLevel1}`);
+```
+
+On the next scheduled run, resume by polling:
+
+```typescript
+const requestId = await store.get('astrasync.pendingRequestId');
+const status = await sdk.pollRegistration(requestId);
+if (status.state === 'approved') {
+  await store.set('astrasync.agentId', status.agent.kyaAgentId);
+  await store.delete('astrasync.pendingRequestId');
+} else if (status.state === 'denied' || status.state === 'expired') {
+  console.error(`Registration terminated: ${status.state}`);
+}
+```
+
+CLI equivalent — same surface from a shell, also via `npx`:
+
+```bash
+npx astrasync register --name invoice-bot --agent-type autonomous \
+  --model-provider anthropic --model-name claude-sonnet-4-5 \
+  --framework-name langchain --framework-version 0.3.0 \
+  --protocols a2a,mcp \
+  --api-endpoint https://invoice-bot.example.com \
+  --pdlss '{"purpose":{"categories":["accounting"],"allowedActions":["accounting.read"]}}'
+```
+
+The CLI uses the same response logic — it will print a "Sign in to approve" message and a poll URL when the response is 202 pending, and exit non-zero on deny/expire.
+
+> `/registration` is for **one-shot onboarding** — register an agent, look up its public profile, check API health. For **per-request credential injection** (attaching ASTRA-id, sessionId, PDLSS to outgoing HTTP / A2A / MCP calls from an already-registered agent), use `/agent` (`AgentClient`). The two roles are deliberately separate concerns: registration is identity, `/agent` is runtime.
+
+> A `PDLSSConfig` type exists in both `/registration` and `/agent`, with **different shapes**. `/registration`'s `PDLSSConfig` is the boundary declaration submitted at register time; `/agent`'s `PDLSSConfig` is the per-request runtime request shape. Disambiguate via the import path — the root export deliberately does not re-export either.
+
 ### Inner-hop verification (MCP → REST dedupe with X-Astra-Verified-Hop)
 
 When an MCP tool calls an inner REST endpoint that ALSO runs the

package/dist/bin/astrasync.js

@@ -0,0 +1,498 @@
+#!/usr/bin/env node
+"use strict";
+var __create = Object.create;
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __getProtoOf = Object.getPrototypeOf;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toESM = (mod, isNodeMode, target) => (target = mod != null ? __create(__getProtoOf(mod)) : {}, __copyProps(
+  // If the importer is in node compatibility mode or this is not an ESM
+  // file that has been converted to a CommonJS file using a Babel-
+  // compatible transform (i.e. "__esModule" has not been set), then set
+  // "default" to the CommonJS "module.exports" for node compatibility.
+  isNodeMode || !mod || !mod.__esModule ? __defProp(target, "default", { value: mod, enumerable: true }) : target,
+  mod
+));
+
+// src/registration/errors.ts
+var AstraSyncError = class extends Error {
+  constructor(message, statusCode, code) {
+    super(message);
+    this.name = "AstraSyncError";
+    this.statusCode = statusCode;
+    this.code = code;
+  }
+};
+var KYDRequiredError = class extends AstraSyncError {
+  constructor(response) {
+    const kydUrl = response.kydUrl || "https://astrasync.ai/developer-profile";
+    super(
+      `KYD verification required before registering agents.
+Complete your KYD profile at: ${kydUrl}`,
+      403,
+      "KYD_REQUIRED"
+    );
+    this.name = "KYDRequiredError";
+    this.kydUrl = kydUrl;
+    this.ownerNotified = response.ownerNotified || false;
+  }
+};
+var AuthenticationError = class extends AstraSyncError {
+  constructor(message) {
+    super(message, 401, "AUTH_FAILED");
+    this.name = "AuthenticationError";
+  }
+};
+var RegistrationDeniedError = class extends AstraSyncError {
+  constructor(requestId, reason) {
+    super(
+      `Registration request ${requestId} was denied by the account owner.${reason ? ` Reason: ${reason}` : ""}`,
+      403,
+      "REGISTRATION_DENIED"
+    );
+    this.name = "RegistrationDeniedError";
+    this.requestId = requestId;
+    this.reason = reason;
+  }
+};
+var RegistrationExpiredError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Registration request ${requestId} expired before the owner approved it. Submit a new registration request.`,
+      410,
+      "REGISTRATION_EXPIRED"
+    );
+    this.name = "RegistrationExpiredError";
+    this.requestId = requestId;
+  }
+};
+var RegistrationTimeoutError = class extends AstraSyncError {
+  constructor(requestId) {
+    super(
+      `Timed out waiting for owner approval of registration request ${requestId}. The request is still active server-side; poll the request to resume waiting.`,
+      408,
+      "REGISTRATION_TIMEOUT"
+    );
+    this.name = "RegistrationTimeoutError";
+    this.requestId = requestId;
+  }
+};
+
+// src/registration/api.ts
+var DEFAULT_BASE_URL = "https://astrasync.ai";
+var sleep = (ms) => new Promise((r) => setTimeout(r, ms));
+var AstraSync = class {
+  constructor(config = {}) {
+    this.baseUrl = (config.baseUrl || process.env.ASTRASYNC_API_URL || DEFAULT_BASE_URL).replace(
+      /\/+$/,
+      ""
+    );
+    this.apiKey = config.apiKey || process.env.ASTRASYNC_API_KEY;
+    this.email = config.email;
+    this.password = config.password;
+    this.privateKey = config.privateKey;
+    if (!this.apiKey && !this.email) {
+      throw new AuthenticationError(
+        "Authentication required. Provide apiKey, or email+password. Set ASTRASYNC_API_KEY env var or pass config to constructor."
+      );
+    }
+    if (this.email && !this.password) {
+      throw new AuthenticationError("Password is required when using email authentication.");
+    }
+  }
+  /**
+   * Register a new AI agent on the AstraSync KYA Platform.
+   *
+   * The backend response depends on auth context:
+   * - **Crypto-keypair signed** (`privateKey` configured): synchronous 201,
+   *   returns `{ status: 'active', agent }`.
+   * - **API-key only** (no signature): 202 pending, returns
+   *   `{ status: 'pending_approval', requestId, pollUrl, expiresAt }`. The
+   *   owner is notified by email and a dashboard alert is emitted; the agent
+   *   becomes active only after the owner approves.
+   *
+   * Blocking mode: pass `{ waitForApproval: true }` to have the SDK poll the
+   * request until it resolves, then return the live agent record. The promise
+   * rejects with `RegistrationDeniedError`, `RegistrationExpiredError`, or
+   * `RegistrationTimeoutError` on the corresponding terminal states.
+   *
+   * @example Non-blocking (default — best for serverless / scheduled agents):
+   * ```typescript
+   * const result = await sdk.register({ name, pdlss });
+   * if (result.status === 'pending_approval') {
+   *   storeRequestId(result.requestId);
+   *   return; // function exits; resume later via pollRegistration()
+   * }
+   * ```
+   *
+   * @example Blocking (best for long-running services + CLI):
+   * ```typescript
+   * const agent = await sdk.register({
+   *   name, pdlss, waitForApproval: true, timeoutMs: 600_000,
+   *   onPending: ({ ageMs }) => console.log(`waiting ${ageMs}ms`),
+   * });
+   * ```
+   */
+  async register(options) {
+    const body = {
+      name: options.name,
+      ...options.description && { description: options.description },
+      ...options.agentType && { agentType: options.agentType },
+      ...options.apiEndpoint && { apiEndpoint: options.apiEndpoint },
+      ...options.model && { model: options.model },
+      ...options.framework && { framework: options.framework },
+      ...options.protocols && { protocols: options.protocols },
+      ...options.metadata && { metadata: options.metadata },
+      ...options.pdlss && { pdlss: options.pdlss }
+    };
+    const { status, body: raw } = await this.requestWithStatus("POST", "/api/agents/register", body);
+    if (status === 201) {
+      const active = {
+        status: "active",
+        agent: raw.data.agent
+      };
+      return active;
+    }
+    const pendingBody = raw;
+    const pending = {
+      status: "pending_approval",
+      requestId: pendingBody.requestId,
+      expiresAt: pendingBody.expiresAt,
+      pollUrl: pendingBody.pollUrl,
+      message: pendingBody.message
+    };
+    if (!options.waitForApproval) return pending;
+    return this.waitForApproval(pendingBody.requestId, options);
+  }
+  /**
+   * Poll the current state of a pending-approval registration request.
+   *
+   * Useful for caller-driven polling when `waitForApproval: false` (the
+   * default). The endpoint is unauthenticated — pass the `requestId` that
+   * was returned from the 202 response.
+   *
+   * @returns `state: 'pending'` while awaiting; `'approved'` carries the
+   *          minted agent in `agent`; `'denied'` may carry the owner's
+   *          `reason`; `'expired'` is terminal after 14 days.
+   */
+  async pollRegistration(requestId) {
+    const url = `${this.baseUrl}/api/agents/request-registration/${requestId}`;
+    const res = await fetch(url, { headers: { Accept: "application/json" } });
+    if (!res.ok) {
+      const errBody = await res.json().catch(() => ({}));
+      throw new AstraSyncError(
+        errBody.error || `pollRegistration failed: ${res.status}`,
+        res.status,
+        errBody.code
+      );
+    }
+    return await res.json();
+  }
+  /**
+   * Block until a pending registration request resolves to a terminal state.
+   * Resolves to the live `AgentRecord` on approval; rejects with the matching
+   * Registration*Error on deny/expire/timeout. Usually called via
+   * `register({ waitForApproval: true })`, but exposed for callers that want
+   * to fire-and-forget the initial register call and resume waiting later
+   * (e.g. after restoring a stored `requestId` on cold start).
+   */
+  async waitForApproval(requestId, options = {}) {
+    const timeoutMs = options.timeoutMs ?? 10 * 60 * 1e3;
+    const pollIntervalMs = options.pollIntervalMs ?? 5e3;
+    const start = Date.now();
+    const deadline = start + timeoutMs;
+    while (Date.now() < deadline) {
+      const result = await this.pollRegistration(requestId);
+      const ageMs = Date.now() - start;
+      options.onPending?.({ requestId, ageMs });
+      if (result.state === "approved") {
+        if (!result.agent) {
+          throw new AstraSyncError(
+            `Registration ${requestId} reported approved but no agent payload returned.`,
+            500
+          );
+        }
+        return result.agent;
+      }
+      if (result.state === "denied") {
+        throw new RegistrationDeniedError(requestId, result.reason);
+      }
+      if (result.state === "expired") {
+        throw new RegistrationExpiredError(requestId);
+      }
+      await sleep(pollIntervalMs);
+    }
+    throw new RegistrationTimeoutError(requestId);
+  }
+  /**
+   * Look up an agent's public profile by ASTRA ID or UUID.
+   */
+  async verify(agentId) {
+    return this.request("GET", `/api/agents/verify/${agentId}`);
+  }
+  /**
+   * Check API health.
+   */
+  async health() {
+    const res = await fetch(`${this.baseUrl}/api/health/`);
+    if (!res.ok) {
+      throw new AstraSyncError(`Health check failed: ${res.status}`, res.status);
+    }
+    return res.json();
+  }
+  // ── Private helpers ──────────────────────────────────────────────
+  async request(method, endpoint, body) {
+    const { body: parsed } = await this.requestWithStatus(method, endpoint, body);
+    return parsed;
+  }
+  /**
+   * Variant of {@link request} that also returns the HTTP status code, so
+   * callers can branch on 201 vs 202 (or other success codes) without losing
+   * type information about the response body.
+   */
+  async requestWithStatus(method, endpoint, body) {
+    const url = `${this.baseUrl}${endpoint}`;
+    const headers = {
+      "Content-Type": "application/json"
+    };
+    const token = await this.getAuthToken();
+    headers["Authorization"] = `Bearer ${token}`;
+    if (this.privateKey) {
+      const signature = await this.signRequest(method, endpoint, body || {});
+      headers["X-AstraSync-Signature"] = signature;
+    }
+    const res = await fetch(url, {
+      method,
+      headers,
+      ...body ? { body: JSON.stringify(body) } : {}
+    });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({ error: res.statusText }));
+      if (res.status === 403 && errorBody.code === "KYD_REQUIRED") {
+        throw new KYDRequiredError(errorBody);
+      }
+      throw new AstraSyncError(
+        errorBody.error || `Request failed: ${res.status}`,
+        res.status,
+        errorBody.code
+      );
+    }
+    return { status: res.status, body: await res.json() };
+  }
+  async getAuthToken() {
+    if (this.apiKey) {
+      return this.apiKey;
+    }
+    if (this.cachedJwt && this.jwtExpiresAt && Date.now() < this.jwtExpiresAt) {
+      return this.cachedJwt;
+    }
+    const res = await fetch(`${this.baseUrl}/api/auth/login`, {
+      method: "POST",
+      headers: { "Content-Type": "application/json" },
+      body: JSON.stringify({ email: this.email, password: this.password })
+    });
+    if (!res.ok) {
+      const errorBody = await res.json().catch(() => ({}));
+      throw new AuthenticationError(
+        errorBody.message || errorBody.error || "Login failed"
+      );
+    }
+    const data = await res.json();
+    this.cachedJwt = data.data.token;
+    this.jwtExpiresAt = Date.now() + 6 * 24 * 60 * 60 * 1e3;
+    return this.cachedJwt;
+  }
+  /**
+   * Sign a request using secp256k1 (ethers.js).
+   * Canonical message format: METHOD:ENDPOINT:SORTED_JSON_BODY
+   * Must match apps/backend/src/services/signature-verify.service.ts exactly.
+   */
+  async signRequest(method, endpoint, body) {
+    const { Wallet } = await import("ethers");
+    const sorted = this.sortObjectKeys(body);
+    const canonical = `${method}:${endpoint}:${JSON.stringify(sorted)}`;
+    const wallet = new Wallet(this.privateKey);
+    return wallet.signMessage(canonical);
+  }
+  /** Recursively sort object keys for canonical JSON representation. */
+  sortObjectKeys(obj) {
+    if (obj === null || typeof obj !== "object") {
+      return obj;
+    }
+    if (Array.isArray(obj)) {
+      return obj.map((item) => this.sortObjectKeys(item));
+    }
+    const sorted = {};
+    for (const key of Object.keys(obj).sort()) {
+      sorted[key] = this.sortObjectKeys(obj[key]);
+    }
+    return sorted;
+  }
+};
+
+// src/bin/astrasync.ts
+function usage() {
+  console.log(`
+astrasync - AstraSync KYA Platform CLI
+
+USAGE:
+  astrasync [options] <command> [args]
+
+GLOBAL OPTIONS:
+  --api-key <key>       API key (kya_ prefixed). Also reads ASTRASYNC_API_KEY env.
+  --email <email>       Email for login auth
+  --password <pass>     Password for login auth
+  --private-key <key>   secp256k1 private key for crypto signing
+  --base-url <url>      API base URL (default: https://astrasync.ai; use https://staging.astrasync.ai for staging)
+  --help                Show this help message
+
+COMMANDS:
+  register              Register a new AI agent
+  verify <id>           Look up an agent by ASTRA ID or UUID
+  health                Check API health
+
+REGISTER OPTIONS:
+  --name <name>                 Agent name (required)
+  --description <desc>          Agent description
+  --agent-type <type>           Agent type (default: general)
+  --api-endpoint <url>          Agent API endpoint URL
+  --model-name <name>           LLM model name (e.g. claude-opus-4.6)
+  --model-provider <provider>   Model provider (e.g. anthropic, openai)
+  --model-type <type>           Model type (default: llm)
+  --framework-name <name>       Framework name (e.g. langchain, crewai)
+  --framework-version <ver>     Framework version
+
+EXAMPLES:
+  astrasync --api-key kya_xxx register --name "My Agent"
+  astrasync register --name "My Agent" --model-name gpt-4o --model-provider openai
+  astrasync verify ASTRA-abc123
+  astrasync health
+`);
+}
+function parseArgs(args) {
+  const globals = {};
+  const commandArgs = {};
+  let command = "";
+  let inCommand = false;
+  for (let i = 0; i < args.length; i++) {
+    const arg = args[i];
+    if (!inCommand && !arg.startsWith("--")) {
+      command = arg;
+      inCommand = true;
+      continue;
+    }
+    if (arg === "--help" || arg === "-h") {
+      globals["help"] = "true";
+      continue;
+    }
+    if (arg.startsWith("--")) {
+      const key = arg.slice(2);
+      const value = args[++i] || "";
+      if (inCommand) {
+        commandArgs[key] = value;
+      } else {
+        globals[key] = value;
+      }
+    }
+  }
+  return { globals, command, commandArgs };
+}
+async function main() {
+  const { globals, command, commandArgs } = parseArgs(process.argv.slice(2));
+  if (globals["help"] || !command) {
+    usage();
+    process.exit(command ? 0 : 1);
+  }
+  const config = {
+    apiKey: globals["api-key"],
+    email: globals["email"],
+    password: globals["password"],
+    privateKey: globals["private-key"],
+    baseUrl: globals["base-url"]
+  };
+  try {
+    if (command === "health") {
+      const client2 = new AstraSync({
+        apiKey: config.apiKey || "health-check",
+        baseUrl: config.baseUrl
+      });
+      const result = await client2.health();
+      console.log(JSON.stringify(result, null, 2));
+      return;
+    }
+    const client = new AstraSync({
+      apiKey: config.apiKey,
+      email: config.email,
+      password: config.password,
+      privateKey: config.privateKey,
+      baseUrl: config.baseUrl
+    });
+    if (command === "register") {
+      const name = commandArgs["name"];
+      if (!name) {
+        console.error("Error: --name is required for register command");
+        process.exit(1);
+      }
+      const options = {
+        name,
+        ...commandArgs["description"] && { description: commandArgs["description"] },
+        ...commandArgs["agent-type"] && { agentType: commandArgs["agent-type"] },
+        ...commandArgs["api-endpoint"] && { apiEndpoint: commandArgs["api-endpoint"] }
+      };
+      if (commandArgs["model-name"] && commandArgs["model-provider"]) {
+        options.model = {
+          modelName: commandArgs["model-name"],
+          modelProvider: commandArgs["model-provider"],
+          ...commandArgs["model-type"] && {
+            modelType: commandArgs["model-type"]
+          }
+        };
+      }
+      if (commandArgs["framework-name"] && commandArgs["framework-version"]) {
+        options.framework = {
+          frameworkName: commandArgs["framework-name"],
+          frameworkVersion: commandArgs["framework-version"]
+        };
+      }
+      const result = await client.register(options);
+      console.log(JSON.stringify(result, null, 2));
+    } else if (command === "verify") {
+      const agentId = commandArgs["id"] || process.argv[process.argv.length - 1];
+      if (!agentId || agentId.startsWith("--")) {
+        console.error("Error: agent ID is required for verify command");
+        process.exit(1);
+      }
+      const result = await client.verify(agentId);
+      console.log(JSON.stringify(result, null, 2));
+    } else {
+      console.error(`Unknown command: ${command}`);
+      usage();
+      process.exit(1);
+    }
+  } catch (error) {
+    if (error instanceof KYDRequiredError) {
+      console.error(`
+Error: ${error.message}`);
+      if (error.ownerNotified) {
+        console.error("A reminder email has been sent to your registered email address.");
+      }
+      process.exit(1);
+    }
+    if (error instanceof AstraSyncError) {
+      console.error(`
+Error [${error.code || error.statusCode}]: ${error.message}`);
+      process.exit(1);
+    }
+    throw error;
+  }
+}
+main();