@zeroxyz/cli 1.15.0 → 1.17.0

package/dist/index.js

@@ -78449,7 +78449,7 @@ init_esm_shims();
 // ../sdk/dist/index.js
 init_esm_shims();
 
-// ../sdk/dist/chunk-EIQP6VGZ.js
+// ../sdk/dist/chunk-T77VVLOM.js
 init_esm_shims();
 
 // ../../node_modules/.pnpm/viem@2.52.2_bufferutil@4.1.0_typescript@5.9.3_utf-8-validate@6.0.6_zod@4.3.6/node_modules/viem/_esm/index.js
@@ -143831,7 +143831,7 @@ config(en_default2());
 // ../../node_modules/.pnpm/zod@4.3.6/node_modules/zod/index.js
 var zod_default = external_exports3;
 
-// ../sdk/dist/chunk-EIQP6VGZ.js
+// ../sdk/dist/chunk-T77VVLOM.js
 var createManagedAccount = (client, address2) => toAccount({
   address: address2,
   async signMessage({ message: message2 }) {
@@ -143910,6 +143910,25 @@ var ZeroAuthError = class extends ZeroError {
     this.name = "ZeroAuthError";
   }
 };
+var ZeroAgentAuthError = class extends ZeroError {
+  status;
+  body;
+  constructor(message2, init) {
+    super("auth_error", message2, { cause: init.cause });
+    this.name = "ZeroAgentAuthError";
+    this.status = init.status;
+    this.body = init.body;
+  }
+  // The error code the SERVER sent, distinct from ZeroError's `code`
+  // discriminator. WorkOS error bodies carry {code, message}; OAuth-style
+  // ones carry {error}.
+  get serverCode() {
+    const body = this.body;
+    if (typeof body?.code === "string") return body.code;
+    if (typeof body?.error === "string") return body.error;
+    return null;
+  }
+};
 var ZeroPaymentError = class extends ZeroError {
   constructor(message2, options) {
     super("payment_error", message2, options);
@@ -145267,16 +145286,89 @@ var extractUpstreamErrorMessage = (body) => {
   }
   return void 0;
 };
+var extractFieldName = (message2) => {
+  const patterns = [
+    /(?:field|param(?:eter)?|property|key)[:\s]+["'`]?([a-z0-9_.[\]-]+)["'`]?/i,
+    /["'`]([a-z0-9_.[\]-]+)["'`]\s*(?:is\s+)?(?:required|missing|expected)/i,
+    // Quotes REQUIRED here — an unquoted token after "required"/"missing"
+    // is usually a generic noun ("required parameters", "missing fields"),
+    // not a field name. Only trust it when the seller quoted it.
+    /(?:required|missing|expected)[:\s]+["'`]([a-z0-9_.[\]-]+)["'`]/i
+  ];
+  for (const p of patterns) {
+    const match = message2.match(p);
+    if (match?.[1]) return match[1];
+  }
+  return void 0;
+};
+var extractAllowedMethod = (text) => {
+  const listed = text.match(
+    /allowed[^[]*\[\s*["'`]?(GET|POST|PUT|PATCH|DELETE|HEAD)/i
+  );
+  if (listed?.[1]) return listed[1].toUpperCase();
+  const useVerb = text.match(/\buse\s+(GET|POST|PUT|PATCH|DELETE|HEAD)\b/i);
+  if (useVerb?.[1]) return useVerb[1].toUpperCase();
+  return void 0;
+};
+var extractUnrecognizedKeys = (bodyRaw) => {
+  if (!bodyRaw) return [];
+  const parsed = tryParseJson(bodyRaw);
+  if (parsed === null || typeof parsed !== "object") return [];
+  const out = [];
+  const visit = (node) => {
+    if (!node || typeof node !== "object") return;
+    const o = node;
+    if (Array.isArray(o.keys)) {
+      for (const k of o.keys) if (typeof k === "string") out.push(k);
+    }
+    for (const v of Object.values(o)) {
+      if (Array.isArray(v)) v.forEach(visit);
+      else if (v && typeof v === "object") visit(v);
+    }
+  };
+  visit(parsed);
+  return [...new Set(out)].slice(0, 8);
+};
+var computeFixHint = (status, message2, bodyRaw) => {
+  if (status < 400 || status >= 500) return void 0;
+  const hay = `${message2 ?? ""} ${bodyRaw ?? ""}`.toLowerCase();
+  if (status === 405 || /method not allowed|method_not_allowed/.test(hay)) {
+    const allowed = extractAllowedMethod(`${bodyRaw ?? ""} ${message2 ?? ""}`);
+    return allowed ? `the endpoint expects ${allowed}, not the method you used \u2014 retry with -X ${allowed}` : "the endpoint rejected this HTTP method \u2014 check the capability's method (`zero get <slug>`) and retry with the right -X";
+  }
+  if (/invalid json|not valid json|malformed|unexpected token|json ?parse|could not parse|failed to parse|jsondecode/.test(
+    hay
+  )) {
+    return "the request body isn't valid JSON \u2014 check quoting/escaping (single-quote the -d value or use @file), then retry";
+  }
+  if (/unrecognized[_ ]?key|unexpected key|unknown (field|key|propert)|additional (?:propert|field)|not allowed in object/.test(
+    hay
+  )) {
+    const keys = extractUnrecognizedKeys(bodyRaw ?? null);
+    return keys.length ? `remove the unexpected field(s) ${keys.map((k) => `'${k}'`).join(", ")} from the request body, then retry` : "the request body has fields the capability doesn't accept \u2014 send only the documented fields, then retry";
+  }
+  if (status === 415 || /content-?type|unsupported media|media type/.test(hay)) {
+    return "set the Content-Type header to what the capability expects (usually application/json), then retry";
+  }
+  if (/required|missing|must (include|provide|have|contain)|is expected/.test(hay)) {
+    const field = extractFieldName(message2 ?? "");
+    return field ? `add the required field '${field}' to the request body, then retry` : "the request is missing one or more required fields \u2014 check the capability schema (`zero get <slug>`), then retry";
+  }
+  return void 0;
+};
 var buildUpstreamError = (status, bodyRaw, bodyEncoding) => {
   if (status >= 200 && status < 300) return void 0;
   if (bodyRaw === null || bodyRaw.length === 0) return void 0;
   if (bodyEncoding === "base64") return void 0;
   const snippet = bodyRaw.slice(0, ERROR_SNIPPET_BYTES);
+  const message2 = extractUpstreamErrorMessage(bodyRaw);
+  const fixHint = computeFixHint(status, message2, bodyRaw);
   return {
     status,
-    message: extractUpstreamErrorMessage(bodyRaw),
+    message: message2,
     snippetHash: createHash("sha256").update(snippet).digest("hex"),
-    snippetLength: snippet.length
+    snippetLength: snippet.length,
+    ...fixHint && { fixHint }
   };
 };
 var computeOutcome = (status, payment, warnings) => {
@@ -145665,74 +145757,63 @@ var clientFetch = async (client, url4, opts = {}) => {
   return result;
 };
 var package_default = {
-  version: "0.9.0"
+  version: "0.11.0"
 };
 var SDK_VERSION2 = package_default.version;
-var userWalletDtoSchema = external_exports3.object({
-  walletAddress: external_exports3.string(),
-  source: external_exports3.enum(["self_custody", "privy_embedded"]),
-  isPrimary: external_exports3.boolean(),
-  linkedAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).nullable().optional(),
-  delegationGranted: external_exports3.boolean(),
-  signerQuorumId: external_exports3.string().nullable(),
-  // Per-transaction USDC cap in base units (6 dp). null = unlimited, 0 = free-only.
-  maxTransactionUsdcBaseUnits: external_exports3.number().int().nullable()
-});
-var welcomeBonusSummarySchema = external_exports3.object({
-  status: external_exports3.string(),
-  amountUsd: external_exports3.number()
-});
-var internalUserDtoSchema = external_exports3.object({
+var agentAuthMetadataSchema = external_exports3.object({
+  token_endpoint: external_exports3.string().optional(),
+  agent_auth: external_exports3.object({
+    identity_endpoint: external_exports3.string(),
+    claim_endpoint: external_exports3.string().optional()
+  }).loose()
+}).loose();
+var identityEnvelopeSchema = external_exports3.object({
   id: external_exports3.string(),
-  email: external_exports3.string().nullable(),
-  createdAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).optional(),
-  lastLoginAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).nullable().optional(),
-  onboardingCompleted: external_exports3.boolean().optional(),
-  delegationGranted: external_exports3.boolean().optional(),
-  wallets: external_exports3.array(userWalletDtoSchema).optional(),
-  balance: external_exports3.object({ amount: external_exports3.string(), asset: external_exports3.string() }).nullable().optional(),
-  welcomeBonus: welcomeBonusSummarySchema.nullable().optional()
-});
-var publicUserDtoSchema = external_exports3.object({
-  user: external_exports3.object({
-    id: external_exports3.string(),
-    email: external_exports3.string().nullable()
-  }),
-  walletAddress: external_exports3.string().nullable(),
-  balance: external_exports3.object({ amount: external_exports3.string(), asset: external_exports3.string() }).nullable(),
-  welcomeBonus: welcomeBonusSummarySchema.nullable()
-});
-var signResponseSchema = external_exports3.object({
-  signature: external_exports3.string().regex(/^0x[0-9a-fA-F]+$/, "must be 0x-prefixed hex"),
-  walletAddress: external_exports3.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be 0x-prefixed 40-char hex address")
-});
-var deviceStartResponseSchema = external_exports3.object({
-  deviceCode: external_exports3.string(),
-  userCode: external_exports3.string(),
-  verificationUri: external_exports3.string(),
-  pollInterval: external_exports3.number(),
-  expiresAt: external_exports3.number()
-});
-var devicePollResponseSchema = external_exports3.union([
-  // userCode + verificationUri are optional: older API deployments don't
-  // echo them on pending.
-  external_exports3.object({
-    error: external_exports3.literal("authorization_pending"),
-    userCode: external_exports3.string().optional(),
-    verificationUri: external_exports3.string().optional()
-  }),
-  external_exports3.object({ error: external_exports3.literal("expired_token") }),
-  external_exports3.object({
-    accessToken: external_exports3.string(),
-    refreshToken: external_exports3.string(),
-    expiresIn: external_exports3.number(),
-    user: internalUserDtoSchema
-  })
-]);
-var sessionExchangeResponseSchema = external_exports3.object({
-  token: external_exports3.string(),
-  expiresAt: external_exports3.number()
-});
+  identity: external_exports3.object({
+    assertion: external_exports3.string(),
+    expires_at: external_exports3.string().optional(),
+    refresh_token: external_exports3.object({ value: external_exports3.string() }).loose().optional()
+  }).loose(),
+  claim: external_exports3.object({
+    token: external_exports3.string().optional(),
+    expires_at: external_exports3.string().optional()
+  }).loose().optional()
+}).loose().transform((raw) => ({
+  registrationId: raw.id,
+  identityAssertion: raw.identity.assertion,
+  assertionExpires: raw.identity.expires_at ?? null,
+  refreshToken: raw.identity.refresh_token?.value ?? null,
+  claimToken: raw.claim?.token ?? null,
+  claimTokenExpires: raw.claim?.expires_at ?? null
+}));
+var agentTokenResponseSchema = external_exports3.object({ access_token: external_exports3.string() }).loose().transform((raw) => ({ accessToken: raw.access_token }));
+var startClaimResponseSchema = external_exports3.object({
+  attempt: external_exports3.object({
+    verification_uri: external_exports3.string(),
+    expires_at: external_exports3.string().optional()
+  }).loose()
+}).loose().transform((raw) => ({
+  verificationUri: raw.attempt.verification_uri,
+  expiresAt: raw.attempt.expires_at ?? null
+}));
+var completeClaimResponseSchema = external_exports3.object({
+  identity: external_exports3.object({
+    assertion: external_exports3.string(),
+    expires_at: external_exports3.string().optional(),
+    refresh_token: external_exports3.object({ value: external_exports3.string() }).loose().optional()
+  }).loose()
+}).loose().transform((raw) => ({
+  identityAssertion: raw.identity.assertion,
+  assertionExpires: raw.identity.expires_at ?? null,
+  refreshToken: raw.identity.refresh_token?.value ?? null
+}));
+var agentZeroSessionSchema = external_exports3.object({
+  accessToken: external_exports3.string(),
+  refreshToken: external_exports3.string(),
+  expiresIn: external_exports3.number(),
+  user: external_exports3.object({ id: external_exports3.string() }).loose(),
+  walletAddress: external_exports3.string().optional()
+}).loose();
 var refreshResponseSchema = external_exports3.object({
   accessToken: external_exports3.string(),
   refreshToken: external_exports3.string()
@@ -145965,6 +146046,264 @@ var request2 = async (client, opts, schema) => {
     cause: lastNetworkError
   });
 };
+var JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer";
+var trimSlash = (value) => value.replace(/\/$/, "");
+var wrapNetworkError = (url4, err) => {
+  const cause = err?.cause;
+  const causeMessage = cause instanceof Error ? cause.code ?? cause.message : err instanceof Error ? err.message : String(err);
+  return new ZeroAgentAuthError(`Could not reach ${url4} (${causeMessage})`, {
+    status: 0,
+    cause: err
+  });
+};
+var AuthAgent = class {
+  constructor(client) {
+    this.client = client;
+  }
+  endpointsPromise = null;
+  // Fully autonomous signup: register anonymously at the AuthKit domain,
+  // exchange the identity assertion for a WorkOS access token, exchange that
+  // for a Zero session. The claim token and identity assertion are returned
+  // exactly once — the caller persists them.
+  signup = async () => {
+    const registration = await this.register();
+    const token = await this.exchangeAssertion(registration.identityAssertion);
+    const session4 = await this.exchangeAtZero(token.accessToken);
+    return { registration, session: session4 };
+  };
+  register = async () => {
+    const endpoints = await this.endpoints();
+    return this.postJson(
+      endpoints.identityEndpoint,
+      { type: "anonymous" },
+      identityEnvelopeSchema
+    );
+  };
+  exchangeAssertion = async (identityAssertion) => {
+    const endpoints = await this.endpoints();
+    return this.postForm(
+      endpoints.tokenEndpoint,
+      { grant_type: JWT_BEARER_GRANT_TYPE, assertion: identityAssertion },
+      agentTokenResponseSchema
+    );
+  };
+  // POST /v1/auth/agent/exchange — WorkOS agent access token → Zero session
+  // pair (+ the implicitly provisioned wallet address). The post-claim token
+  // goes through here too: the server binds the claiming human.
+  exchangeAtZero = (accessToken, opts = {}) => request2(
+    this.client,
+    {
+      method: "POST",
+      path: "/v1/auth/agent/exchange",
+      body: { accessToken },
+      signal: opts.signal
+    },
+    agentZeroSessionSchema
+  );
+  // Mint a claim attempt. The human opens the returned verification URI,
+  // signs in as `email`, and the page shows THEM a pairing code to read back
+  // to the agent — completeClaim() submits it.
+  startClaim = async (input) => {
+    const endpoints = await this.endpoints();
+    if (!endpoints.claimEndpoint) {
+      throw new ZeroAgentAuthError(
+        "The authorization server advertises no claim endpoint.",
+        { status: 0 }
+      );
+    }
+    return this.postJson(
+      endpoints.claimEndpoint,
+      {
+        type: "service_auth",
+        claim_token: input.claimToken,
+        login_hint: input.email
+      },
+      startClaimResponseSchema
+    );
+  };
+  // Submit the pairing code the human read off the hosted page. Terminal
+  // states map to a typed result; anything unexpected throws.
+  completeClaim = async (input) => {
+    const endpoints = await this.endpoints();
+    if (!endpoints.claimEndpoint) {
+      throw new ZeroAgentAuthError(
+        "The authorization server advertises no claim endpoint.",
+        { status: 0 }
+      );
+    }
+    try {
+      const identity = await this.postJson(
+        `${endpoints.claimEndpoint}/complete`,
+        { claim_token: input.claimToken, user_code: input.userCode },
+        completeClaimResponseSchema
+      );
+      return { status: "ok", ...identity };
+    } catch (err) {
+      if (err instanceof ZeroAgentAuthError && err.serverCode) {
+        if (err.serverCode === "claim_not_confirmed") {
+          return { status: "not_confirmed" };
+        }
+        if (err.serverCode === "invalid_user_code") {
+          return { status: "invalid_code" };
+        }
+        if ([
+          "user_code_expired",
+          "claim_expired",
+          "claim_revoked",
+          "already_claimed",
+          "claim_denied"
+        ].includes(err.serverCode)) {
+          return { status: "expired", code: err.serverCode };
+        }
+      }
+      throw err;
+    }
+  };
+  // Resolve (and cache) the agent-auth endpoints via discovery.
+  endpoints = () => {
+    if (!this.endpointsPromise) {
+      this.endpointsPromise = this.discover().catch((err) => {
+        this.endpointsPromise = null;
+        throw err;
+      });
+    }
+    return this.endpointsPromise;
+  };
+  discover = async () => {
+    const resource = await this.getJson(
+      `${trimSlash(this.client.baseUrl)}/.well-known/oauth-protected-resource`
+    );
+    let lastError = null;
+    for (const server of resource.authorization_servers ?? []) {
+      try {
+        const raw = await this.getJson(
+          `${trimSlash(server)}/.well-known/oauth-authorization-server`
+        );
+        const metadata = agentAuthMetadataSchema.parse(raw);
+        return {
+          authorizationServer: trimSlash(server),
+          identityEndpoint: metadata.agent_auth.identity_endpoint,
+          claimEndpoint: metadata.agent_auth.claim_endpoint ?? null,
+          tokenEndpoint: metadata.token_endpoint ?? `${trimSlash(server)}/oauth2/token`
+        };
+      } catch (err) {
+        lastError = err;
+      }
+    }
+    throw new ZeroAgentAuthError(
+      "No authorization server with an agent_auth block found \u2014 agent registration is not enabled for this service.",
+      { status: 0, cause: lastError }
+    );
+  };
+  getJson = async (url4) => {
+    const response = await this.client.fetchImpl(url4).catch((err) => {
+      throw wrapNetworkError(url4, err);
+    });
+    if (!response.ok) {
+      throw new ZeroAgentAuthError(`GET ${url4} failed (${response.status})`, {
+        status: response.status
+      });
+    }
+    return await response.json();
+  };
+  postJson = (url4, body, schema) => this.post(url4, "application/json", JSON.stringify(body), schema);
+  postForm = (url4, fields, schema) => this.post(
+    url4,
+    "application/x-www-form-urlencoded",
+    new URLSearchParams(fields).toString(),
+    schema
+  );
+  post = async (url4, contentType, body, schema) => {
+    const response = await this.client.fetchImpl(url4, {
+      method: "POST",
+      headers: { "content-type": contentType },
+      body
+    }).catch((err) => {
+      throw wrapNetworkError(url4, err);
+    });
+    const text = await response.text();
+    let parsed = null;
+    try {
+      parsed = text ? JSON.parse(text) : null;
+    } catch {
+    }
+    if (!response.ok) {
+      const errBody = parsed;
+      const code = errBody?.code ?? errBody?.error;
+      throw new ZeroAgentAuthError(
+        `Agent auth request to ${url4} failed (${response.status}${typeof code === "string" ? `: ${code}` : ""})`,
+        { status: response.status, body: parsed ?? text }
+      );
+    }
+    return schema.parse(parsed);
+  };
+};
+var userWalletDtoSchema = external_exports3.object({
+  walletAddress: external_exports3.string(),
+  source: external_exports3.enum(["self_custody", "privy_embedded"]),
+  isPrimary: external_exports3.boolean(),
+  linkedAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).nullable().optional(),
+  importedAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).nullable().optional(),
+  delegationGranted: external_exports3.boolean(),
+  signerQuorumId: external_exports3.string().nullable(),
+  // Per-transaction USDC cap in base units (6 dp). null = unlimited, 0 = free-only.
+  maxTransactionUsdcBaseUnits: external_exports3.number().int().nullable()
+});
+var welcomeBonusSummarySchema = external_exports3.object({
+  status: external_exports3.string(),
+  amountUsd: external_exports3.number()
+});
+var internalUserDtoSchema = external_exports3.object({
+  id: external_exports3.string(),
+  email: external_exports3.string().nullable(),
+  createdAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).optional(),
+  lastLoginAt: external_exports3.union([external_exports3.string(), external_exports3.date()]).nullable().optional(),
+  onboardingCompleted: external_exports3.boolean().optional(),
+  delegationGranted: external_exports3.boolean().optional(),
+  wallets: external_exports3.array(userWalletDtoSchema).optional(),
+  balance: external_exports3.object({ amount: external_exports3.string(), asset: external_exports3.string() }).nullable().optional(),
+  welcomeBonus: welcomeBonusSummarySchema.nullable().optional()
+});
+var publicUserDtoSchema = external_exports3.object({
+  user: external_exports3.object({
+    id: external_exports3.string(),
+    email: external_exports3.string().nullable()
+  }),
+  walletAddress: external_exports3.string().nullable(),
+  balance: external_exports3.object({ amount: external_exports3.string(), asset: external_exports3.string() }).nullable(),
+  welcomeBonus: welcomeBonusSummarySchema.nullable()
+});
+var signResponseSchema = external_exports3.object({
+  signature: external_exports3.string().regex(/^0x[0-9a-fA-F]+$/, "must be 0x-prefixed hex"),
+  walletAddress: external_exports3.string().regex(/^0x[0-9a-fA-F]{40}$/, "must be 0x-prefixed 40-char hex address")
+});
+var deviceStartResponseSchema = external_exports3.object({
+  deviceCode: external_exports3.string(),
+  userCode: external_exports3.string(),
+  verificationUri: external_exports3.string(),
+  pollInterval: external_exports3.number(),
+  expiresAt: external_exports3.number()
+});
+var devicePollResponseSchema = external_exports3.union([
+  // userCode + verificationUri are optional: older API deployments don't
+  // echo them on pending.
+  external_exports3.object({
+    error: external_exports3.literal("authorization_pending"),
+    userCode: external_exports3.string().optional(),
+    verificationUri: external_exports3.string().optional()
+  }),
+  external_exports3.object({ error: external_exports3.literal("expired_token") }),
+  external_exports3.object({
+    accessToken: external_exports3.string(),
+    refreshToken: external_exports3.string(),
+    expiresIn: external_exports3.number(),
+    user: internalUserDtoSchema
+  })
+]);
+var sessionExchangeResponseSchema = external_exports3.object({
+  token: external_exports3.string(),
+  expiresAt: external_exports3.number()
+});
 var AuthDevice = class {
   constructor(client) {
     this.client = client;
@@ -146025,8 +146364,10 @@ var repackageSignFailure = (err, op) => {
 var Auth = class {
   constructor(client) {
     this.client = client;
+    this.agent = new AuthAgent(client);
     this.device = new AuthDevice(client);
   }
+  agent;
   device;
   // The internal (web-app facing) user profile. Richer than profile(): full
   // wallet list with per-wallet delegation/signer/limit metadata.
@@ -146323,6 +146664,9 @@ var capabilityResponseSchema = external_exports3.object({
     "unknown_unparsed",
     "unprobed"
   ]).optional(),
+  // ZERO-147 — provenance of displayCostAmount (settled | probe | registry |
+  // unknown). `settled` means the shown price is reconciled from real charges.
+  priceSource: external_exports3.string().nullable().optional(),
   requiresHandshake: external_exports3.boolean().optional(),
   reviewCount: external_exports3.number(),
   rating: ratingSchema,
@@ -146675,6 +147019,48 @@ var Wallet = class {
     },
     userWalletDtoSchema
   );
+  // Link an existing self-custody wallet to the session user by private key.
+  // Session-only. 409s when the wallet is already linked (to this or another
+  // profile — the error message says which).
+  import = (opts) => request2(
+    this.client,
+    {
+      method: "POST",
+      path: "/v1/users/me/wallets/import",
+      body: {
+        privateKey: opts.privateKey,
+        ...opts.makePrimary !== void 0 ? { makePrimary: opts.makePrimary } : {}
+      },
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Make one of the session user's linked wallets the primary payer.
+  // Session-only. 404s when the address isn't linked to the user.
+  setPrimary = (opts) => request2(
+    this.client,
+    {
+      method: "PATCH",
+      path: "/v1/users/me/wallets/primary",
+      body: { walletAddress: opts.walletAddress },
+      signal: opts.signal
+    },
+    userWalletDtoSchema
+  );
+  // Unlink a wallet from the session user. Session-only. 409s on the primary
+  // wallet or a non-zero balance (the error message says which); 404s when
+  // the address isn't linked. Responds 204 — resolves to void.
+  remove = async (opts) => {
+    await request2(
+      this.client,
+      {
+        method: "DELETE",
+        path: `/v1/users/me/wallets/${opts.walletAddress}`,
+        signal: opts.signal
+      },
+      external_exports3.undefined()
+    );
+  };
   // Routes by identity: account mode signs EIP-191 against /v1/wallet/fund-url,
   // session mode hits /v1/users/me/fund-url (Bearer-authed, wallet resolved
   // server-side). Both honor `provider` (coinbase | stripe).
@@ -147399,7 +147785,7 @@ var placeholderFor = (fieldName, propSchema) => String(sampleValueFor(fieldName,
 
 // package.json
 var package_default2 = {
-  version: "1.15.0"};
+  version: "1.17.0"};
 
 // src/app.ts
 init_esm_shims();
@@ -148030,272 +148416,6 @@ defineLazyProperty(apps, "safari", () => detectPlatformBinary({
 }));
 var open_default = open2;
 
-// src/services/agent-auth.ts
-init_esm_shims();
-var JWT_BEARER_GRANT_TYPE = "urn:ietf:params:oauth:grant-type:jwt-bearer";
-var trimSlash = (value) => value.replace(/\/$/, "");
-var AgentAuthHttpError = class extends Error {
-  constructor(message2, status, body) {
-    super(message2);
-    this.status = status;
-    this.body = body;
-    this.name = "AgentAuthHttpError";
-  }
-  // WorkOS error bodies carry {code, message}; OAuth-style ones carry {error}.
-  get code() {
-    const body = this.body;
-    if (typeof body?.code === "string") return body.code;
-    if (typeof body?.error === "string") return body.error;
-    return null;
-  }
-};
-var agentAuthMetadataSchema = external_exports3.object({
-  token_endpoint: external_exports3.string().optional(),
-  agent_auth: external_exports3.object({
-    identity_endpoint: external_exports3.string(),
-    claim_endpoint: external_exports3.string().optional()
-  }).loose()
-}).loose();
-var identityEnvelopeSchema = external_exports3.object({
-  id: external_exports3.string(),
-  identity: external_exports3.object({
-    assertion: external_exports3.string(),
-    expires_at: external_exports3.string().optional(),
-    refresh_token: external_exports3.object({ value: external_exports3.string() }).loose().optional()
-  }).loose(),
-  claim: external_exports3.object({
-    token: external_exports3.string().optional(),
-    expires_at: external_exports3.string().optional()
-  }).loose().optional()
-}).loose().transform((raw) => ({
-  registrationId: raw.id,
-  identityAssertion: raw.identity.assertion,
-  assertionExpires: raw.identity.expires_at ?? null,
-  refreshToken: raw.identity.refresh_token?.value ?? null,
-  claimToken: raw.claim?.token ?? null,
-  claimTokenExpires: raw.claim?.expires_at ?? null
-}));
-var tokenResponseSchema = external_exports3.object({ access_token: external_exports3.string() }).loose().transform((raw) => ({ accessToken: raw.access_token }));
-var startClaimResponseSchema = external_exports3.object({
-  attempt: external_exports3.object({
-    verification_uri: external_exports3.string(),
-    expires_at: external_exports3.string().optional()
-  }).loose()
-}).loose().transform((raw) => ({
-  verificationUri: raw.attempt.verification_uri,
-  expiresAt: raw.attempt.expires_at ?? null
-}));
-var completeClaimResponseSchema = external_exports3.object({
-  identity: external_exports3.object({
-    assertion: external_exports3.string(),
-    expires_at: external_exports3.string().optional(),
-    refresh_token: external_exports3.object({ value: external_exports3.string() }).loose().optional()
-  }).loose()
-}).loose().transform((raw) => ({
-  identityAssertion: raw.identity.assertion,
-  assertionExpires: raw.identity.expires_at ?? null,
-  refreshToken: raw.identity.refresh_token?.value ?? null
-}));
-var zeroExchangeResponseSchema = external_exports3.object({
-  accessToken: external_exports3.string(),
-  refreshToken: external_exports3.string(),
-  expiresIn: external_exports3.number(),
-  user: external_exports3.object({ id: external_exports3.string() }).loose(),
-  walletAddress: external_exports3.string().optional()
-}).loose();
-var AgentAuthClient = class {
-  constructor(apiBaseUrl, fetchImpl = (...args) => globalThis.fetch(...args)) {
-    this.fetchImpl = fetchImpl;
-    this.apiBaseUrl = trimSlash(apiBaseUrl);
-  }
-  apiBaseUrl;
-  endpointsPromise = null;
-  // Fully autonomous signup: register anonymously at the AuthKit domain,
-  // exchange the identity assertion for a WorkOS access token, exchange that
-  // for a Zero session. The claim token and identity assertion are returned
-  // exactly once — the caller persists them.
-  signup = async () => {
-    const registration = await this.register();
-    const token = await this.exchangeAssertion(registration.identityAssertion);
-    const session4 = await this.exchangeAtZero(token.accessToken);
-    return { registration, session: session4 };
-  };
-  register = async () => {
-    const endpoints = await this.endpoints();
-    return this.postJson(
-      endpoints.identityEndpoint,
-      { type: "anonymous" },
-      identityEnvelopeSchema
-    );
-  };
-  exchangeAssertion = async (identityAssertion) => {
-    const endpoints = await this.endpoints();
-    return this.postForm(
-      endpoints.tokenEndpoint,
-      { grant_type: JWT_BEARER_GRANT_TYPE, assertion: identityAssertion },
-      tokenResponseSchema
-    );
-  };
-  // POST /v1/auth/agent/exchange — WorkOS agent access token → Zero session
-  // pair (+ the implicitly provisioned wallet address). The post-claim token
-  // goes through here too: the server binds the claiming human.
-  exchangeAtZero = (accessToken) => this.postJson(
-    `${this.apiBaseUrl}/v1/auth/agent/exchange`,
-    { accessToken },
-    zeroExchangeResponseSchema
-  );
-  // Mint a claim attempt. The human opens the returned verification URI,
-  // signs in as `email`, and the page shows THEM a pairing code to read back
-  // to the agent — completeClaim() submits it.
-  startClaim = async (input) => {
-    const endpoints = await this.endpoints();
-    if (!endpoints.claimEndpoint) {
-      throw new AgentAuthHttpError(
-        "The authorization server advertises no claim endpoint.",
-        0,
-        null
-      );
-    }
-    return this.postJson(
-      endpoints.claimEndpoint,
-      {
-        type: "service_auth",
-        claim_token: input.claimToken,
-        login_hint: input.email
-      },
-      startClaimResponseSchema
-    );
-  };
-  // Submit the pairing code the human read off the hosted page. Terminal
-  // states map to a typed result; anything unexpected throws.
-  completeClaim = async (input) => {
-    const endpoints = await this.endpoints();
-    if (!endpoints.claimEndpoint) {
-      throw new AgentAuthHttpError(
-        "The authorization server advertises no claim endpoint.",
-        0,
-        null
-      );
-    }
-    try {
-      const identity = await this.postJson(
-        `${endpoints.claimEndpoint}/complete`,
-        { claim_token: input.claimToken, user_code: input.userCode },
-        completeClaimResponseSchema
-      );
-      return { status: "ok", ...identity };
-    } catch (err) {
-      if (err instanceof AgentAuthHttpError && err.code) {
-        if (err.code === "claim_not_confirmed") {
-          return { status: "not_confirmed" };
-        }
-        if (err.code === "invalid_user_code") {
-          return { status: "invalid_code" };
-        }
-        if ([
-          "user_code_expired",
-          "claim_expired",
-          "claim_revoked",
-          "already_claimed",
-          "claim_denied"
-        ].includes(err.code)) {
-          return { status: "expired", code: err.code };
-        }
-      }
-      throw err;
-    }
-  };
-  // Resolve (and cache) the agent-auth endpoints via discovery.
-  endpoints = () => {
-    if (!this.endpointsPromise) {
-      this.endpointsPromise = this.discover().catch((err) => {
-        this.endpointsPromise = null;
-        throw err;
-      });
-    }
-    return this.endpointsPromise;
-  };
-  discover = async () => {
-    const resource = await this.getJson(`${this.apiBaseUrl}/.well-known/oauth-protected-resource`);
-    let lastError = null;
-    for (const server of resource.authorization_servers ?? []) {
-      try {
-        const raw = await this.getJson(
-          `${trimSlash(server)}/.well-known/oauth-authorization-server`
-        );
-        const metadata = agentAuthMetadataSchema.parse(raw);
-        return {
-          authorizationServer: trimSlash(server),
-          identityEndpoint: metadata.agent_auth.identity_endpoint,
-          claimEndpoint: metadata.agent_auth.claim_endpoint ?? null,
-          tokenEndpoint: metadata.token_endpoint ?? `${trimSlash(server)}/oauth2/token`
-        };
-      } catch (err) {
-        lastError = err;
-      }
-    }
-    throw new AgentAuthHttpError(
-      "No authorization server with an agent_auth block found \u2014 agent registration is not enabled for this service.",
-      0,
-      lastError
-    );
-  };
-  getJson = async (url4) => {
-    const response = await this.fetchImpl(url4).catch((err) => {
-      throw wrapNetworkError(url4, err);
-    });
-    if (!response.ok) {
-      throw new AgentAuthHttpError(
-        `GET ${url4} failed (${response.status})`,
-        response.status,
-        null
-      );
-    }
-    return await response.json();
-  };
-  postJson = (url4, body, schema) => this.post(url4, "application/json", JSON.stringify(body), schema);
-  postForm = (url4, fields, schema) => this.post(
-    url4,
-    "application/x-www-form-urlencoded",
-    new URLSearchParams(fields).toString(),
-    schema
-  );
-  post = async (url4, contentType, body, schema) => {
-    const response = await this.fetchImpl(url4, {
-      method: "POST",
-      headers: { "content-type": contentType },
-      body
-    }).catch((err) => {
-      throw wrapNetworkError(url4, err);
-    });
-    const text = await response.text();
-    let parsed = null;
-    try {
-      parsed = text ? JSON.parse(text) : null;
-    } catch {
-    }
-    if (!response.ok) {
-      const body2 = parsed;
-      const code = body2?.code ?? body2?.error;
-      throw new AgentAuthHttpError(
-        `Agent auth request to ${url4} failed (${response.status}${typeof code === "string" ? `: ${code}` : ""})`,
-        response.status,
-        parsed ?? text
-      );
-    }
-    return schema.parse(parsed);
-  };
-};
-var wrapNetworkError = (url4, err) => {
-  const cause = err?.cause;
-  const causeMessage = cause instanceof Error ? cause.code ?? cause.message : err instanceof Error ? err.message : String(err);
-  return new AgentAuthHttpError(
-    `Could not reach ${url4} (${causeMessage})`,
-    0,
-    null
-  );
-};
-
 // src/util/secure-config.ts
 init_esm_shims();
 var SECURE_DIR_MODE = 448;
@@ -148642,7 +148762,7 @@ var authAgentRegisterCommand = (appContext) => new Command("register").descripti
     process.exitCode = 1;
     return;
   }
-  const agentAuth = new AgentAuthClient(client.baseUrl);
+  const agentAuth = client.auth.agent;
   let result;
   try {
     result = await agentAuth.signup();
@@ -148809,7 +148929,7 @@ var authAgentClaimCommand = (appContext) => new Command("claim").description(
     return;
   }
   const claimToken = registration.claimToken;
-  const agentAuth = new AgentAuthClient(client.baseUrl);
+  const agentAuth = client.auth.agent;
   if (opts.code) {
     const ok2 = await completeClaimAndExchange(
       agentAuth,
@@ -148822,7 +148942,7 @@ var authAgentClaimCommand = (appContext) => new Command("claim").description(
     return;
   }
   const started = await agentAuth.startClaim({ claimToken, email: email4 }).catch((err) => {
-    const code = err instanceof AgentAuthHttpError && err.code ? err.code : truncateError(err instanceof Error ? err.message : String(err));
+    const code = err instanceof ZeroAgentAuthError && err.serverCode ? err.serverCode : truncateError(err instanceof Error ? err.message : String(err));
     process.stderr.write(
       `Could not start the claim (${code}). The claim token may be expired \u2014 check \`claimTokenExpires\` in ~/.zero/config.json.
 `
@@ -149225,7 +149345,11 @@ var OUTCOMES = {
     errorClass: "insufficient_funds",
     reviewable: false
   },
-  server_error: { exitCode: 0, errorClass: "upstream_4xx", reviewable: true }
+  // A capability returned a non-2xx (4xx/5xx). Exit 2 — distinct from a
+  // transport failure (1) — so `zero fetch … && next` stops instead of
+  // feeding an error body downstream as if it were a result. The body is
+  // still printed and the run is reviewable; only the success signal changes.
+  server_error: { exitCode: 2, errorClass: "upstream_4xx", reviewable: true }
 };
 var cliErrorClassFor = (outcome, status, walletAddress) => {
   const info = OUTCOMES[outcome];
@@ -149657,6 +149781,9 @@ var fetchCommand = (appContext) => new Command("fetch").description(
           );
         } else if (outcome === "server_error" && typeof status === "number") {
           console.error(`  Upstream returned ${status}${messageSuffix}`);
+          if (upstreamError?.fixHint) {
+            console.error(`  \u21B3 Fix: ${upstreamError.fixHint}`);
+          }
         }
       }
       if (options.json) {
@@ -149686,6 +149813,11 @@ var fetchCommand = (appContext) => new Command("fetch").description(
             bodyRaw: status === null ? null : bodyRaw,
             ...isBinary && { bodyEncoding: "base64" },
             ...resultError && { error: resultError },
+            // A non-2xx from the capability: surface the structured
+            // upstream detail (status, message, and the caller-
+            // fixable `fixHint`) in the envelope too. Agents run
+            // `--json`, so without this the fixHint is invisible.
+            ...upstreamError && { upstreamError },
             ...legacyMigrateHint && { hint: legacyMigrateHint },
             ...combinedSkipReasons.length > 0 && {
               runTrackingSkipped: combinedSkipReasons
@@ -149695,9 +149827,10 @@ var fetchCommand = (appContext) => new Command("fetch").description(
         );
       } else if (runId && outcomeInfo.reviewable) {
         const isTTY = process.stderr.isTTY;
+        const responded2xx = status !== null && status >= 200 && status < 300;
         console.error(`
   Run ID: ${runId}`);
-        if (isTTY) {
+        if (isTTY && responded2xx) {
           console.error(
             `  Leave a review to help other agents discover great capabilities:`
           );
@@ -149718,10 +149851,19 @@ var fetchCommand = (appContext) => new Command("fetch").description(
               ``
             ].join("\n")
           );
-        } else {
+        } else if (responded2xx) {
           console.error(
             `  zero review ${runId} --success --accuracy 5 --value 4 --reliability 5`
           );
+        } else if (isTTY) {
+          console.error(
+            `  The call did not return a usable result. If the capability itself was at fault, record it:`
+          );
+          console.error(
+            `  zero review ${runId} --no-success --content "what went wrong"`
+          );
+        } else {
+          console.error(`  zero review ${runId} --no-success`);
         }
       } else if (!runId && cliSkipReasons.length > 0) {
         console.error(
@@ -151696,17 +151838,20 @@ init_esm_shims();
 
 // src/util/migrate-config.ts
 init_esm_shims();
-var backupAndStripPrivateKey = (zeroDir) => {
+var backupAndStripConfigKeys = (zeroDir, keys) => {
   const configPath = join$1(zeroDir, "config.json");
   const backupPath = join$1(zeroDir, "config.backup.json");
   const raw = readFileSync(configPath, "utf8");
   ensureSecureDir(zeroDir);
   writeSecureFile(backupPath, raw);
   const parsed = JSON.parse(raw);
-  delete parsed.privateKey;
+  for (const key of keys) {
+    delete parsed[key];
+  }
   writeSecureFile(configPath, JSON.stringify(parsed, null, 2));
   return { backupPath, configPath };
 };
+var backupAndStripPrivateKey = (zeroDir) => backupAndStripConfigKeys(zeroDir, ["privateKey"]);
 
 // src/util/stdin.ts
 init_esm_shims();
@@ -151935,6 +152080,148 @@ var walletSetCommand = (appContext) => new Command("set").description("Set walle
     force: options.force ?? false
   });
 });
+var normalizeImportKey = (raw) => {
+  const trimmed = raw.trim();
+  const prefixed = trimmed.startsWith("0x") ? trimmed : `0x${trimmed}`;
+  return PRIVATE_KEY_PATTERN.test(prefixed) ? prefixed : null;
+};
+var SIGN_IN_FIRST_MESSAGE = "This command requires a signed-in session. Run `zero auth login` first.";
+var walletImportCommand = (appContext) => new Command("import").description(
+  "Link an existing self-custody wallet to your Zero profile by private key"
+).argument("[privateKey]", "Hex-encoded private key (0x prefix optional)").option(
+  "--key-stdin",
+  "Read the private key from stdin instead of an argument"
+).option("--primary", "Make the imported wallet your primary payer wallet").action(
+  async (privateKeyArg, options) => {
+    const { analyticsService, client } = appContext.services;
+    if (privateKeyArg && options.keyStdin) {
+      console.error(
+        "Pass the key as an argument OR via --key-stdin, not both."
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (!privateKeyArg && !options.keyStdin) {
+      console.error(
+        "Missing private key. Pass it as an argument or pipe it with --key-stdin."
+      );
+      process.exitCode = 1;
+      return;
+    }
+    let rawKey;
+    if (options.keyStdin) {
+      if (process.stdin.isTTY) {
+        console.error(
+          "Expected a private key on stdin. Example:\n  zero wallet generate --json | jq -r .privateKey | zero wallet import --key-stdin"
+        );
+        process.exitCode = 1;
+        return;
+      }
+      rawKey = await readStdin();
+    } else {
+      rawKey = privateKeyArg;
+    }
+    const privateKey = normalizeImportKey(rawKey);
+    if (!privateKey) {
+      console.error(
+        "Invalid private key (expected 64 hex chars, 0x prefix optional)."
+      );
+      process.exitCode = 1;
+      return;
+    }
+    if (client.getCredentials().kind !== "session") {
+      console.error(SIGN_IN_FIRST_MESSAGE);
+      process.exitCode = 1;
+      return;
+    }
+    let wallet;
+    try {
+      wallet = await client.wallet.import({
+        privateKey,
+        ...options.primary ? { makePrimary: true } : {}
+      });
+    } catch (err) {
+      if (err instanceof ZeroApiError) {
+        if (err.status === 401) {
+          console.error(
+            "Session expired. Run `zero auth login` and try again."
+          );
+        } else {
+          console.error(`Could not import wallet: ${err.message}`);
+        }
+      } else {
+        console.error("Could not import wallet: network error.");
+      }
+      process.exitCode = 1;
+      return;
+    }
+    analyticsService.setWalletAddress(wallet.walletAddress);
+    console.log(
+      `Wallet imported: ${wallet.walletAddress}${wallet.isPrimary ? " (primary)" : ""}`
+    );
+    let localKeyStripped = false;
+    const zeroDir = join$1(homedir(), ".zero");
+    const configPath = join$1(zeroDir, "config.json");
+    const config2 = existsSync(configPath) ? readConfig(configPath) : {};
+    const localByoKey = config2.byoPrivateKey ? normalizeImportKey(config2.byoPrivateKey) : null;
+    if (localByoKey && localByoKey.toLowerCase() === privateKey.toLowerCase()) {
+      try {
+        const { backupPath } = backupAndStripConfigKeys(zeroDir, [
+          "byoPrivateKey"
+        ]);
+        localKeyStripped = true;
+        console.log(
+          `Local key backed up to ${backupPath} and removed from config \u2014 managed signing now applies.`
+        );
+      } catch {
+        console.error(
+          "Could not back up the local key; it was left in place in ~/.zero/config.json."
+        );
+      }
+    }
+    analyticsService.capture("wallet_imported", {
+      primary: wallet.isPrimary,
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      key_source: options.keyStdin ? "stdin" : "arg",
+      // biome-ignore lint/style/useNamingConvention: snake_case for analytics
+      local_key_stripped: localKeyStripped
+    });
+  }
+);
+var walletListCommand = (appContext) => new Command("list").description("List the wallets linked to your Zero profile").action(async () => {
+  const { analyticsService, client } = appContext.services;
+  if (client.getCredentials().kind !== "session") {
+    console.error(SIGN_IN_FIRST_MESSAGE);
+    process.exitCode = 1;
+    return;
+  }
+  let wallets;
+  try {
+    wallets = await client.wallet.list();
+  } catch (err) {
+    const message2 = err instanceof ZeroApiError && err.status === 401 ? "Session expired. Run `zero auth login` and try again." : "Failed to list wallets.";
+    console.error(message2);
+    process.exitCode = 1;
+    return;
+  }
+  if (wallets.length === 0) {
+    console.log(
+      "No wallets linked. One is provisioned automatically on your first paid call, or run `zero wallet import <key>`."
+    );
+  } else {
+    for (const wallet of wallets) {
+      const source = wallet.importedAt ? "imported" : wallet.source === "privy_embedded" ? "managed" : "byo";
+      const columns = [
+        wallet.walletAddress,
+        source.padEnd(8),
+        (wallet.isPrimary ? "PRIMARY" : "").padEnd(7),
+        wallet.delegationGranted ? "delegated" : "not delegated"
+      ];
+      console.log(columns.join("  ").trimEnd());
+    }
+  }
+  analyticsService.capture("wallet_listed", { count: wallets.length });
+});
 var walletGenerateCommand = (appContext) => new Command("generate").description(
   "Generate a fresh wallet (address + private key) without touching your configured wallet"
 ).option("--json", "Emit { address, privateKey } as JSON").option(
@@ -152022,6 +152309,8 @@ var walletCommand = (appContext) => {
   cmd.addCommand(walletAddressCommand(appContext));
   cmd.addCommand(walletSetCommand(appContext));
   cmd.addCommand(walletGenerateCommand(appContext));
+  cmd.addCommand(walletImportCommand(appContext));
+  cmd.addCommand(walletListCommand(appContext));
   return cmd;
 };
 

package/package.json

@@ -1,6 +1,6 @@
 {
 	"name": "@zeroxyz/cli",
-	"version": "1.15.0",
+	"version": "1.17.0",
 	"type": "module",
 	"bin": {
 		"zero": "dist/index.js",