@usenaive-sdk/cli 0.12.2 → 0.13.0

package/README.md

@@ -14,7 +14,7 @@ Command-line interface for the Naive API v2. Register, manage identity, and use
 - **Video** — Generate via fal.ai (dynamic pricing)
 - **Social** — Connect accounts, create posts, schedule, analytics (via bundle.social)
 - **Verification** — Identity verification (KYC) for company founders/members via Footprint
-- **Formation** — Company formation (LLC incorporation) via Doola ($249 fee via Stripe Checkout)
+- **Formation** — Company formation (LLC incorporation) via Doola ($349 fee via Stripe Checkout)
 - **Cards** — Virtual cards — create, fund, assign agents, track transactions (Stripe Issuing + Reloadly)
 - **Jobs** — List, inspect, and cancel async jobs
 - **Status** — Credit balance and usage history
@@ -74,7 +74,7 @@ The CLI stores config at `~/.naive/config.json`:
 Set via registration or environment:
 
 ```bash
-# Auto-saved on register/login/link
+# Auto-saved on register/login/browser auth
 naive register --name "My Agent" --email owner@example.com --password yourpassword
 
 # Or set manually
@@ -82,13 +82,61 @@ export NAIVE_API_KEY=nv_sk_live_...
 export NAIVE_BASE_URL=http://localhost:3100  # for local dev
 ```
 
+### The durable runtime — `naive teams`
+
+The addressing tuple is `(company, tenant, team)` and it is in the path, not
+inferred, so `--tenant` is required on every subcommand except `list`. There is
+no default: `--tenant @self` is the only shorthand.
+
+```bash
+naive teams list
+naive teams show support --tenant tu_8f21
+naive teams submit support "refund the duplicate charge" --tenant tu_8f21
+naive teams board support --tenant tu_8f21
+naive teams watch support --tenant tu_8f21 --run run_01J8 --follow   # NDJSON
+naive teams approvals support --tenant tu_8f21
+naive teams decide support apr_01J --allow --because "verified with the customer"
+```
+
+All 27 subcommands, their flags, their REST paths and their ActionIds are
+declared once in `src/lib/teams-catalog.ts`; `src/commands/teams.ts` builds the
+commander tree by walking it and declares no subcommand of its own.
+
+`--because` is a required *flag* (never a positional) on every op that widens
+authority or destroys state: `unblock decide settle model stop migrate rollback`.
+
+Exit codes: `0` success · `1` error · `2` success with a diff
+(`plan --detailed-exitcode`) · `3` success where the terminal state is not
+success (`tasks|task --fail-on-unverified`, `watch --fail-on-terminal`).
+`unverified` is a third terminal state, and a CI script that reads `0` as "the
+work is done" would otherwise count an unattested task as a pass.
+
+**Not yet served.** There is no `/v1/teams` mount on `packages/api` in this
+repository. Every `naive teams` subcommand therefore reaches the API's catch-all
+today, and the CLI says exactly that — it reports the missing *route*, not a
+missing team.
+
+### Deprecation
+
+`ceo · tasks · objectives · employees · cron · loops · memory` drive the legacy
+orchestration runtime, which is frozen. **They all keep working**, unchanged.
+Each prints a one-line banner on stderr carrying a greppable `[dep.<group>]` id
+and its replacement, and attaches a `deprecation` object to the JSON envelope on
+stdout, so stdout stays `JSON.parse`-able. Nothing is disabled and no route is
+removed.
+
+Where a capability genuinely has no successor (`tasks complete`, `cron pause`,
+the provisioning verbs) the notice says so and gives the reason, rather than
+inventing a replacement — the record's `replacement` is a closed union, so a
+missing one cannot render as an empty string.
+
 ### Commands
 
 ```bash
 # Auth
 naive register --name "Agent" --email user@example.com --password mypassword --company "Acme"
 naive login --email user@example.com --password mypassword
-naive link --email existing@example.com
+naive auth email existing@example.com
 naive whoami
 naive companies
 naive keys list
@@ -165,6 +213,7 @@ naive email create --local-part hello     # Create new inbox on active domain
 naive email delete <inbox-id>             # Delete an inbox
 naive email send --from-inbox <uuid> --to user@example.com --subject "Hi" --body "Hello"
 naive email inbox --inbox <uuid> --limit 20
+naive email sent --limit 20
 naive email read <email-id>
 
 # Search
@@ -196,13 +245,13 @@ naive social sync                                            # Sync from bundle.
 naive social upload --url https://example.com/video.mp4      # Upload media
 naive social posts                                           # List posts
 naive social posts --status draft                            # Filter by status
-naive social post "Hello world!" --platforms twitter,linkedin --publish  # Create + publish (1 credit)
+naive social post "Hello world!" --platforms twitter,linkedin --publish  # Create + publish (2.5 credits; 3 for X)
 naive social post "Draft" --platforms twitter                 # Create draft (free)
 naive social post "Demo" --platforms youtube --media-url https://example.com/video.mp4 --youtube-type SHORT --publish
 naive social get <post-id>                                   # Get post details
 naive social edit <post-id> --content "Updated"              # Edit draft
 naive social delete <post-id>                                # Delete post
-naive social publish <post-id>                               # Publish draft (1 credit)
+naive social publish <post-id>                               # Publish draft (2.5 credits; 3 for X)
 naive social analytics <post-id>                             # Post analytics
 naive social comments <post-id>                              # Post comments
 naive social account-analytics <account-id>                  # Account analytics
@@ -301,3 +350,25 @@ src/
     ├── cards.ts      # naive cards (list/cardholder/create-cardholder/create/details/check-payment/retry-issue/top-up/refund/cancel/assignments/assign/unassign/log-transaction/transactions)
     └── jobs.ts       # naive jobs (list/get/cancel)
 ```
+
+
+## Purpose
+
+Naïve CLI — provision and govern a real-world agent profile per agent (identity, card, comms, runtime). Formerly @usenaive/cli.
+
+## Consumers
+
+Part of the Naive monorepo. See the [root README](../../README.md) for how components fit together and which packages depend on this one.
+
+## Run standalone
+
+```bash
+pnpm --filter @usenaive-sdk/cli dev
+pnpm --filter @usenaive-sdk/cli build
+pnpm --filter @usenaive-sdk/cli test
+pnpm --filter @usenaive-sdk/cli typecheck
+```
+
+## Place in the topology
+
+One node in the Naive monorepo (open plumbing). The [root README](../../README.md) has the full architecture diagram.

package/dist/client.d.ts

@@ -1,6 +1,45 @@
+/** True when `data` is our synthetic non-JSON marker (so handleApiError fires even
+ *  on the rare non-JSON body carrying a 2xx status). */
+export declare function isUpstreamError(data: unknown): boolean;
+/**
+ * Read a fetch Response body as JSON without ever throwing. Real API bodies are
+ * always JSON (the fast path). A non-JSON body (HTML gateway page, proxy text,
+ * empty body) is turned into a synthetic `{ error: { code: "upstream_error", … } }`
+ * envelope — the same shape formatApiError already understands — carrying the HTTP
+ * status and a bounded snippet, so the caller emits a clean error instead of crashing.
+ */
+export declare function parseJsonOrUpstreamError(resp: Response): Promise<unknown>;
 export declare function setActiveUserOverride(userId?: string): void;
-/** Resolve the active subject user id (override > config). */
+/**
+ * Resolve the active subject user id (override > env > config).
+ *
+ * NAIVE_ACTIVE_USER_ID is how a containerized agent gets a subject: its Hermes
+ * profile's .env carries its own sealed key plus its tenant_user id, so the CLI
+ * it runs scopes calls to /v1/users/<that id>/... and the agent's AccountKit
+ * (its declared `can:` / `limits:`) is actually enforced. There is no
+ * ~/.naive/config.json in a profile's home to hold `active_user_id`.
+ */
 export declare function activeUserId(): string | undefined;
+export declare function setActiveProjectOverride(projectId?: string): void;
+/**
+ * The `--project` flag as parsed off the ROOT program, if it was given.
+ *
+ * `naive use <child> --project <id>` writes the flag after the subcommand, but
+ * commander binds it to the root program's identically-named option, leaving the
+ * subcommand's own `opts.project` undefined. `use` reads it back through here.
+ */
+export declare function activeProjectOverride(): string | undefined;
+/**
+ * Resolve the active project id (override > env > config).
+ *
+ * Undefined is a MEANINGFUL answer, not a missing one: the server resolves the
+ * organization's default project, which is where `naive` acted before projects
+ * existed and where migration 059 backfilled every row. So the header is sent
+ * only when a project was actually chosen, and a CLI that never mentions one
+ * keeps producing byte-identical requests.
+ */
+export declare function activeProjectId(): string | undefined;
+export declare function scopePathToUser(path: string, subject: string | undefined): string;
 export declare function apiRequest(method: string, rawPath: string, body?: Record<string, unknown>, opts?: {
     noAuth?: boolean;
     userId?: string;
@@ -9,6 +48,23 @@ export declare function apiRequest(method: string, rawPath: string, body?: Recor
     status: number;
     data: unknown;
 }>;
+/**
+ * Like {@link apiRequest} but for endpoints that return a BINARY body (e.g.
+ * synthesized speech). Sends the same JSON request and auth/subject handling,
+ * and on success returns the raw bytes plus the response headers, so callers
+ * can read ids like `x-audio-request-id` off the response.
+ *
+ * An error response is still JSON, so it is parsed into the usual `{ status,
+ * data }` shape — `handleApiError` works unchanged.
+ */
+export declare function apiRequestBinary(method: string, rawPath: string, body?: Record<string, unknown>, opts?: {
+    userId?: string;
+    headers?: Record<string, string>;
+}): Promise<{
+    status: number;
+    data: unknown;
+    headers?: Record<string, string>;
+}>;
 /**
  * Upload a raw gzipped payload (e.g. a project tarball for direct app deploys).
  * Same auth + subject handling as apiRequest, but with a binary body.
@@ -23,6 +79,23 @@ export declare function handleApiError(action: string, resp: {
     status: number;
     data: unknown;
 }): void;
+/** Exchange email+password for a session token, captured from Set-Cookie (the token is
+ *  not in the response body). Returns the token + the login payload. Exits on API error. */
+export declare function sessionLogin(email: string, password: string): Promise<{
+    token: string;
+    data: Record<string, unknown>;
+}>;
+/** HTTP for human-only routes. Sends the session cookie, NEVER the agent api_key.
+ *  Supports JSON and multipart (native FormData) bodies, with an upload timeout. */
+export declare function sessionRequest(method: string, path: string, opts?: {
+    body?: Record<string, unknown>;
+    multipart?: FormData;
+    headers?: Record<string, string>;
+    timeoutMs?: number;
+}): Promise<{
+    status: number;
+    data: unknown;
+}>;
 /**
  * Governance: a sensitive action may be deferred for human approval (HTTP 202
  * with `status: "pending_approval"`). When that happens, emit a structured

package/dist/client.js

@@ -1,14 +1,144 @@
-import { loadConfig, getApiKey } from "./config.js";
-import { formatApiError, agentOutput } from "./output.js";
+import { loadConfig, getApiKey, getSessionToken } from "./config.js";
+import { randomUUID } from "node:crypto";
+import { formatApiError, agentOutput, agentError, setPendingUpdate } from "./output.js";
+import { readVersion } from "./version.js";
+import { evaluateCliVersion } from "./lib/version-check.js";
+import { networkErrorResponse, parseHttpResponse } from "./lib/http-response.js";
+const UPDATE_COMMAND = "npm i -g @usenaive-sdk/cli@latest";
+/**
+ * Server-driven version handshake. The API stamps `x-naive-cli-latest` and
+ * `x-naive-cli-min` on every response; we compare them against this CLI's own
+ * version. Below-minimum is a hard block (exits via agentError); below-latest
+ * queues a non-fatal update notice for the next agentOutput. Missing/unparseable
+ * headers are a no-op (evaluateCliVersion returns "ok").
+ */
+function checkCliVersion(resp) {
+    const latest = resp.headers.get("x-naive-cli-latest") ?? undefined;
+    const min = resp.headers.get("x-naive-cli-min") ?? undefined;
+    if (!latest && !min)
+        return;
+    // Best-effort: the version check must never break the user's command. The only
+    // intended non-return exit is the `cli_outdated` hard block; any unexpected
+    // throw is swallowed to a no-op.
+    try {
+        const current = readVersion();
+        const decision = evaluateCliVersion(current, min, latest);
+        if (decision.kind === "block") {
+            agentError({
+                action: "version_check",
+                error: {
+                    code: "cli_outdated",
+                    message: `Your naive CLI (v${decision.current}) is older than the minimum supported version (v${decision.min}). Update to continue.`,
+                },
+                recovery_steps: [
+                    { command: UPDATE_COMMAND, description: "Update to the latest naive CLI, then re-run your command" },
+                ],
+            });
+            return; // unreachable — agentError calls process.exit(1)
+        }
+        if (decision.kind === "notice") {
+            setPendingUpdate({
+                current: decision.current,
+                latest: decision.latest,
+                update_command: UPDATE_COMMAND,
+                note: `A newer naive CLI is available (v${decision.current} → v${decision.latest}). Update with: ${UPDATE_COMMAND}`,
+            });
+        }
+    }
+    catch {
+        // Version check is advisory; on any unexpected failure, do nothing.
+    }
+}
+// ── Non-JSON body handling (standalone helper) ──────────────────────────────
+//
+// The main request paths (apiRequest / apiUploadGzip / sessionLogin /
+// sessionRequest) go through requestResponse() + lib/http-response.ts, which is
+// content-type-aware, redacts secrets, and does the idempotent GET/HEAD retry.
+// Callers that run their OWN fetch for a media/binary path (commands/media.ts,
+// commands/clone.ts) use parseJsonOrUpstreamError() below to read a JSON body
+// without ever throwing on a non-JSON gateway page.
+const BODY_SNIPPET_MAX = 200;
+/** Collapse whitespace and hard-truncate a response body so we never dump a full
+ *  HTML page into the error envelope. */
+function bodySnippet(text) {
+    return text.replace(/\s+/g, " ").trim().slice(0, BODY_SNIPPET_MAX);
+}
+/** True when `data` is our synthetic non-JSON marker (so handleApiError fires even
+ *  on the rare non-JSON body carrying a 2xx status). */
+export function isUpstreamError(data) {
+    return (typeof data === "object" &&
+        data !== null &&
+        data.error?.code === "upstream_error");
+}
+/**
+ * Read a fetch Response body as JSON without ever throwing. Real API bodies are
+ * always JSON (the fast path). A non-JSON body (HTML gateway page, proxy text,
+ * empty body) is turned into a synthetic `{ error: { code: "upstream_error", … } }`
+ * envelope — the same shape formatApiError already understands — carrying the HTTP
+ * status and a bounded snippet, so the caller emits a clean error instead of crashing.
+ */
+export async function parseJsonOrUpstreamError(resp) {
+    const raw = await resp.text();
+    try {
+        return JSON.parse(raw);
+    }
+    catch {
+        return {
+            error: {
+                code: "upstream_error",
+                message: `The API returned a non-JSON response (HTTP ${resp.status}). This is usually a transient gateway timeout — retry in a moment.`,
+                http_status: resp.status,
+                body_snippet: bodySnippet(raw),
+            },
+        };
+    }
+}
 // Per-invocation override for the active subject user (set by a global --user
 // flag). Falls back to config.active_user_id, then the api key's default.
 let _userOverride;
 export function setActiveUserOverride(userId) {
     _userOverride = userId;
 }
-/** Resolve the active subject user id (override > config). */
+/**
+ * Resolve the active subject user id (override > env > config).
+ *
+ * NAIVE_ACTIVE_USER_ID is how a containerized agent gets a subject: its Hermes
+ * profile's .env carries its own sealed key plus its tenant_user id, so the CLI
+ * it runs scopes calls to /v1/users/<that id>/... and the agent's AccountKit
+ * (its declared `can:` / `limits:`) is actually enforced. There is no
+ * ~/.naive/config.json in a profile's home to hold `active_user_id`.
+ */
 export function activeUserId() {
-    return _userOverride ?? loadConfig().active_user_id;
+    const fromEnv = process.env.NAIVE_ACTIVE_USER_ID?.trim();
+    return _userOverride ?? (fromEnv || undefined) ?? loadConfig().active_user_id;
+}
+// Per-invocation override for the active project (set by a global --project flag).
+let _projectOverride;
+export function setActiveProjectOverride(projectId) {
+    _projectOverride = projectId;
+}
+/**
+ * The `--project` flag as parsed off the ROOT program, if it was given.
+ *
+ * `naive use <child> --project <id>` writes the flag after the subcommand, but
+ * commander binds it to the root program's identically-named option, leaving the
+ * subcommand's own `opts.project` undefined. `use` reads it back through here.
+ */
+export function activeProjectOverride() {
+    return _projectOverride;
+}
+/**
+ * Resolve the active project id (override > env > config).
+ *
+ * Undefined is a MEANINGFUL answer, not a missing one: the server resolves the
+ * organization's default project, which is where `naive` acted before projects
+ * existed and where migration 059 backfilled every row. So the header is sent
+ * only when a project was actually chosen, and a CLI that never mentions one
+ * keeps producing byte-identical requests.
+ */
+export function activeProjectId() {
+    const fromEnv = process.env.NAIVE_ACTIVE_PROJECT_ID?.trim();
+    return _projectOverride ?? (fromEnv || undefined) ?? loadConfig().active_project_id;
 }
 /**
  * Native primitives that have per-user path routes (/v1/users/:id/<prim>).
@@ -18,10 +148,23 @@ export function activeUserId() {
  * AccountKit — matching the SDK and dashboard. The legacy routes don't run
  * the subject middleware, so without this the header was silently ignored.
  */
-const PER_USER_PRIMITIVES = new Set(["cards", "phone", "trading", "email", "domains", "verification", "formation", "social", "compute", "queue"]);
-function scopePathToUser(path, subject) {
-    if (!subject)
-        return path; // solo flow (no active user) keeps legacy behavior
+// NOTE: unlike the others, `wallet` and `payments` have NO legacy company-level
+// mount. The default subject sentinel below is therefore required even when the
+// caller has not explicitly selected a tenant user.
+const PER_USER_PRIMITIVES = new Set(["cards", "phone", "trading", "email", "domains", "verification", "formation", "social", "compute", "queue", "mobile", "wallet", "payments"]);
+const USER_PATH_ONLY_PRIMITIVES = new Set(["wallet", "payments"]);
+/**
+ * The wallet's OPERATOR verbs: fund / sweep / setPolicy, plus POST /wallet
+ * (create) and /transfer, which are operator verbs too since they
+ * provision the float and move it out respectively. All of them move or
+ * re-govern the float. Reads (GET /wallet, /wallet/balances) and the agent's own
+ * /payments surface are NOT admin.
+ */
+const WALLET_ADMIN_PATH = /^\/v1\/(?:users\/[^/]+\/)?wallet(?:\/(?:fund|transfer|policy|sweep))?(?:\?|$)/;
+function isWalletAdminCall(method, rawPath) {
+    return method.toUpperCase() === "POST" && WALLET_ADMIN_PATH.test(rawPath);
+}
+export function scopePathToUser(path, subject) {
     if (path.startsWith("/v1/users/"))
         return path; // already user-scoped
     const m = path.match(/^\/v1\/([^/?]+)(.*)$/);
@@ -29,12 +172,58 @@ function scopePathToUser(path, subject) {
         return path;
     if (!PER_USER_PRIMITIVES.has(m[1]))
         return path;
-    return `/v1/users/${subject}/${m[1]}${m[2]}`;
+    const resolvedSubject = subject ?? (USER_PATH_ONLY_PRIMITIVES.has(m[1]) ? "default" : undefined);
+    if (!resolvedSubject)
+        return path;
+    return `/v1/users/${resolvedSubject}/${m[1]}${m[2]}`;
+}
+const TRANSIENT_READ_STATUSES = new Set([500, 502, 503, 504]);
+async function requestResponse(url, init) {
+    const method = String(init.method ?? "GET").toUpperCase();
+    const mayRetry = method === "GET" || method === "HEAD";
+    for (let attempt = 0; attempt < 2; attempt++) {
+        let response;
+        try {
+            response = await fetch(url, init);
+        }
+        catch (error) {
+            if (mayRetry && attempt === 0) {
+                await new Promise((resolve) => setTimeout(resolve, 100));
+                continue;
+            }
+            return networkErrorResponse(error);
+        }
+        if (mayRetry && attempt === 0 && TRANSIENT_READ_STATUSES.has(response.status)) {
+            await response.body?.cancel().catch(() => { });
+            await new Promise((resolve) => setTimeout(resolve, 100));
+            continue;
+        }
+        try {
+            return { ...(await parseHttpResponse(response)), response };
+        }
+        catch (error) {
+            return { ...networkErrorResponse(error), response };
+        }
+    }
+    return networkErrorResponse(new Error("Request failed after retry"));
 }
 export async function apiRequest(method, rawPath, body, opts) {
+    // Invariant guard: the human-only admin surface must NEVER be reached with an agent
+    // key. apiRequest sends the agent bearer, so it must refuse these paths outright.
+    if (rawPath.startsWith("/v1/voice-admin")) {
+        throw new Error("Internal error: /v1/voice-admin is human-only and must be called via sessionRequest, not apiRequest.");
+    }
+    // Same invariant for the wallet's operator verbs: an agent must
+    // never be able to fund, transfer, sweep or re-policy the float it spends
+    // from. The server enforces this too (enforceWalletAdmin); this is the
+    // client-side half, so a mistake surfaces at the call site, not as a 403.
+    if (isWalletAdminCall(method, rawPath)) {
+        throw new Error(`Internal error: ${rawPath} is an operator-only wallet verb and must be called via sessionRequest, not apiRequest.`);
+    }
     const config = loadConfig();
     const headers = {
         "Content-Type": "application/json",
+        "X-Request-Id": randomUUID(),
         ...(opts?.headers ?? {}),
     };
     let path = rawPath;
@@ -45,18 +234,78 @@ export async function apiRequest(method, rawPath, body, opts) {
         const subject = opts?.userId ?? activeUserId();
         if (subject)
             headers["X-Naive-User-Id"] = subject;
+        // Select the project the same way: a header, so no route has to change.
+        const project = activeProjectId();
+        if (project)
+            headers["X-Naive-Project-Id"] = project;
         // Native primitives only isolate via their per-user path routes, so rewrite
-        // legacy paths to the path-scoped form when a subject is active.
+        // legacy paths to the path-scoped form. "default" asks the API to resolve
+        // the key/company default when the CLI has no explicit `naive use` value.
         path = scopePathToUser(path, subject);
     }
     const url = `${config.base_url}${path}`;
-    const resp = await fetch(url, {
+    const parsed = await requestResponse(url, {
         method,
         headers,
         ...(body && { body: JSON.stringify(body) }),
     });
-    const data = await resp.json();
-    return { status: resp.status, data };
+    if (parsed.response)
+        checkCliVersion(parsed.response);
+    return { status: parsed.status, data: parsed.data };
+}
+/**
+ * Like {@link apiRequest} but for endpoints that return a BINARY body (e.g.
+ * synthesized speech). Sends the same JSON request and auth/subject handling,
+ * and on success returns the raw bytes plus the response headers, so callers
+ * can read ids like `x-audio-request-id` off the response.
+ *
+ * An error response is still JSON, so it is parsed into the usual `{ status,
+ * data }` shape — `handleApiError` works unchanged.
+ */
+export async function apiRequestBinary(method, rawPath, body, opts) {
+    const config = loadConfig();
+    const headers = {
+        "Content-Type": "application/json",
+        "X-Request-Id": randomUUID(),
+        ...(opts?.headers ?? {}),
+        Authorization: `Bearer ${getApiKey()}`,
+    };
+    const subject = opts?.userId ?? activeUserId();
+    if (subject)
+        headers["X-Naive-User-Id"] = subject;
+    const binaryProject = activeProjectId();
+    if (binaryProject)
+        headers["X-Naive-Project-Id"] = binaryProject;
+    const path = scopePathToUser(rawPath, subject);
+    let response;
+    try {
+        response = await fetch(`${config.base_url}${path}`, {
+            method,
+            headers,
+            ...(body && { body: JSON.stringify(body) }),
+        });
+    }
+    catch (error) {
+        return networkErrorResponse(error);
+    }
+    checkCliVersion(response);
+    if (!response.ok) {
+        // Errors come back as the standard JSON envelope even on a binary route.
+        const text = await response.text().catch(() => "");
+        let data = {};
+        try {
+            data = text ? JSON.parse(text) : {};
+        }
+        catch {
+            data = { error: { code: "upstream_error", message: text.slice(0, 500) || response.statusText } };
+        }
+        return { status: response.status, data };
+    }
+    const flatHeaders = {};
+    response.headers.forEach((value, key) => {
+        flatHeaders[key.toLowerCase()] = value;
+    });
+    return { status: response.status, data: await response.arrayBuffer(), headers: flatHeaders };
 }
 /**
  * Upload a raw gzipped payload (e.g. a project tarball for direct app deploys).
@@ -66,25 +315,110 @@ export async function apiUploadGzip(rawPath, payload, opts) {
     const config = loadConfig();
     const headers = {
         "Content-Type": "application/gzip",
+        "X-Request-Id": randomUUID(),
         Authorization: `Bearer ${getApiKey()}`,
     };
     const subject = opts?.userId ?? activeUserId();
     if (subject)
         headers["X-Naive-User-Id"] = subject;
+    const uploadProject = activeProjectId();
+    if (uploadProject)
+        headers["X-Naive-Project-Id"] = uploadProject;
     const path = scopePathToUser(rawPath, subject);
-    const resp = await fetch(`${config.base_url}${path}`, {
+    const parsed = await requestResponse(`${config.base_url}${path}`, {
         method: "POST",
         headers,
         body: new Uint8Array(payload),
     });
-    const data = await resp.json().catch(() => ({}));
-    return { status: resp.status, data };
+    if (parsed.response)
+        checkCliVersion(parsed.response);
+    return { status: parsed.status, data: parsed.data };
 }
 export function handleApiError(action, resp) {
-    if (resp.status >= 400) {
+    // Fires on any 4xx/5xx, and also on a synthetic upstream_error carrying a 2xx
+    // status (a non-JSON body from a proxy) so a malformed success never slips through.
+    if (resp.status >= 400 || isUpstreamError(resp.data)) {
         formatApiError(action, resp.data);
     }
 }
+// ── Human session auth (for human-only operations: voice clone/revoke) ──────────────
+//
+// A session cookie is materially more powerful than the agent key on the voice surface
+// (it can clone AND revoke), so it gets stricter handling: never sent over plaintext to a
+// remote host, and the agent api_key is never read in this path.
+/** Refuse to put a session cookie on the wire over plaintext http to a non-local host —
+ *  the server only marks the cookie `secure` in prod, so we protect it client-side. */
+function assertSecureBaseUrl(baseUrl) {
+    let u;
+    try {
+        u = new URL(baseUrl);
+    }
+    catch {
+        throw new Error(`Invalid base_url: ${baseUrl}`);
+    }
+    const isLocal = u.hostname === "localhost" || u.hostname === "127.0.0.1" || u.hostname === "::1";
+    if (u.protocol === "http:" && !isLocal) {
+        throw new Error(`Refusing to send a session cookie over plaintext http to ${u.hostname}. Use https, or a localhost base_url for dev.`);
+    }
+}
+/** Exchange email+password for a session token, captured from Set-Cookie (the token is
+ *  not in the response body). Returns the token + the login payload. Exits on API error. */
+export async function sessionLogin(email, password) {
+    const config = loadConfig();
+    assertSecureBaseUrl(config.base_url);
+    const parsed = await requestResponse(`${config.base_url}/v1/auth/session/login`, {
+        method: "POST",
+        headers: { "Content-Type": "application/json", "X-Request-Id": randomUUID() },
+        body: JSON.stringify({ email, password }),
+    });
+    const data = parsed.data;
+    if (parsed.status >= 400 || isUpstreamError(data)) {
+        formatApiError("auth.session-login", data); // exits the process
+    }
+    // Parse by name, not by index — the server may set more than one cookie.
+    const cookie = parsed.response?.headers.getSetCookie().find((c) => c.startsWith("naive_session="));
+    if (!cookie) {
+        throw new Error("Login succeeded but no naive_session cookie was returned.");
+    }
+    const token = cookie.slice("naive_session=".length).split(";")[0];
+    return { token, data };
+}
+/** HTTP for human-only routes. Sends the session cookie, NEVER the agent api_key.
+ *  Supports JSON and multipart (native FormData) bodies, with an upload timeout. */
+export async function sessionRequest(method, path, opts) {
+    const config = loadConfig();
+    assertSecureBaseUrl(config.base_url);
+    const url = `${config.base_url}${path}`;
+    const headers = {
+        // getSessionToken() never falls back to the agent key.
+        Cookie: `naive_session=${getSessionToken()}`,
+        "X-Request-Id": randomUUID(),
+        ...(opts?.headers ?? {}),
+    };
+    let payload;
+    if (opts?.multipart) {
+        payload = opts.multipart; // fetch sets the multipart Content-Type + boundary
+    }
+    else if (opts?.body) {
+        headers["Content-Type"] = "application/json";
+        payload = JSON.stringify(opts.body);
+    }
+    // Bound the request so a stalled (large) upload can't hang the CLI forever.
+    const controller = new AbortController();
+    const timeout = setTimeout(() => controller.abort(), opts?.timeoutMs ?? 120_000);
+    try {
+        const parsed = await requestResponse(url, {
+            method,
+            headers,
+            ...(payload !== undefined && { body: payload }),
+            signal: controller.signal,
+        });
+        return { status: parsed.status, data: parsed.data };
+    }
+    finally {
+        clearTimeout(timeout);
+    }
+}
 /**
  * Governance: a sensitive action may be deferred for human approval (HTTP 202
  * with `status: "pending_approval"`). When that happens, emit a structured