@2kw/ai 5.2.0-dev.8 → 5.3.0-dev.5

package/dist/lib/client.d.ts

@@ -1,12 +1,69 @@
+import { type Middleware } from "openapi-fetch";
 import type { paths } from "../generated/openapi.js";
+import { type ResolvedConfig } from "./config.js";
+import { ensureJwt } from "./auth-session.js";
 import type { Command } from "commander";
+/**
+ * Marks a request that has already been replayed once after a 401, so a
+ * server that keeps rejecting a freshly minted JWT cannot spin the retry.
+ */
+export declare const RETRY_MARKER = "x-2kw-auth-retried";
+type SessionConfig = Extract<ResolvedConfig, {
+    kind: "session";
+}>;
+type ApiKeyConfig = Extract<ResolvedConfig, {
+    kind: "apiKey";
+}>;
+/** Test seams for the session middleware; both default to the real thing. */
+export interface SessionAuthDeps {
+    /** Session-to-JWT resolution; defaults to {@link ensureJwt}. */
+    ensureJwtFn?: typeof ensureJwt;
+    /** Used only for the 401 replay; defaults to global `fetch`. */
+    fetchFn?: typeof fetch;
+}
+/**
+ * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
+ */
+export declare const errorMiddleware: Middleware;
+/**
+ * API-key contexts carry a long-lived credential, so the header is static and
+ * a 401 is final — there is nothing to refresh.
+ */
+export declare function apiKeyAuthMiddleware(config: ApiKeyConfig): Middleware;
+/**
+ * Session contexts authenticate with a short-lived org JWT minted from the
+ * stored session token. On a 401 we force one re-mint and retry — but only
+ * for GET requests: mutation bodies are consumed by the time onResponse
+ * fires and cannot be replayed safely.
+ */
+export declare function sessionAuthMiddleware(config: SessionConfig, deps?: SessionAuthDeps): Middleware;
+/**
+ * The middleware stack for a resolved config, in registration order.
+ *
+ * Order is load-bearing: openapi-fetch runs `onRequest` forwards but
+ * `onResponse` in reverse, so the error middleware is registered FIRST to make
+ * its throw happen LAST. Registered last it would raise on a 401 before the
+ * auth middleware ever saw the response, and the retry would be dead code.
+ */
+export declare function buildMiddleware(config: ResolvedConfig, deps?: SessionAuthDeps): Middleware[];
+/**
+ * Resolve the Authorization header value for code that performs raw fetch
+ * calls outside the openapi-fetch client (multipart uploads, downloads).
+ * API-key contexts are synchronous passthrough; session contexts mint/reuse
+ * a JWT. No 401 retry here — raw-fetch callers surface errors directly.
+ */
+export declare function resolveAuthHeader(config: ResolvedConfig, deps?: Pick<SessionAuthDeps, "ensureJwtFn">): Promise<string>;
 /**
  * Create a typed openapi-fetch client from the resolved config.
  * Attaches Bearer auth and error middleware automatically.
+ *
+ * Stays synchronous — a JWT is minted lazily inside the request middleware, so
+ * none of the ~90 call sites has to await client construction.
  */
 export declare function getClient(command: Command): import("openapi-fetch").Client<paths, `${string}/${string}`>;
 /**
  * Convenience: run an async action with consistent error handling.
  */
 export declare function runAction(command: Command, action: () => Promise<void>): Promise<void>;
+export {};
 //# sourceMappingURL=client.d.ts.map

package/dist/lib/client.js

@@ -1,10 +1,16 @@
 import createClient from "openapi-fetch";
 import { resolveConfig, isJsonOutput } from "./config.js";
+import { ensureJwt } from "./auth-session.js";
 import { BackboneApiError, handleError } from "./errors.js";
+/**
+ * Marks a request that has already been replayed once after a 401, so a
+ * server that keeps rejecting a freshly minted JWT cannot spin the retry.
+ */
+export const RETRY_MARKER = "x-2kw-auth-retried";
 /**
  * Error-handling middleware: intercepts non-ok responses and throws BackboneApiError.
  */
-const errorMiddleware = {
+export const errorMiddleware = {
     async onResponse({ response }) {
         if (response.ok)
             return undefined;
@@ -23,19 +29,89 @@ const errorMiddleware = {
         });
     },
 };
+/**
+ * API-key contexts carry a long-lived credential, so the header is static and
+ * a 401 is final — there is nothing to refresh.
+ */
+export function apiKeyAuthMiddleware(config) {
+    return {
+        onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${config.apiKey}`);
+            return request;
+        },
+    };
+}
+/**
+ * Session contexts authenticate with a short-lived org JWT minted from the
+ * stored session token. On a 401 we force one re-mint and retry — but only
+ * for GET requests: mutation bodies are consumed by the time onResponse
+ * fires and cannot be replayed safely.
+ */
+export function sessionAuthMiddleware(config, deps = {}) {
+    const doEnsure = deps.ensureJwtFn ?? ensureJwt;
+    const doFetch = deps.fetchFn ?? fetch;
+    return {
+        async onRequest({ request }) {
+            request.headers.set("Authorization", `Bearer ${await doEnsure(config)}`);
+            return request;
+        },
+        async onResponse({ request, response }) {
+            if (response.status !== 401 ||
+                request.method !== "GET" ||
+                request.headers.has(RETRY_MARKER)) {
+                return undefined;
+            }
+            const jwt = await doEnsure(config, { force: true });
+            const retry = new Request(request.url, {
+                method: "GET",
+                headers: new Headers(request.headers),
+            });
+            retry.headers.set("Authorization", `Bearer ${jwt}`);
+            retry.headers.set(RETRY_MARKER, "1");
+            return doFetch(retry);
+        },
+    };
+}
+/**
+ * The middleware stack for a resolved config, in registration order.
+ *
+ * Order is load-bearing: openapi-fetch runs `onRequest` forwards but
+ * `onResponse` in reverse, so the error middleware is registered FIRST to make
+ * its throw happen LAST. Registered last it would raise on a 401 before the
+ * auth middleware ever saw the response, and the retry would be dead code.
+ */
+export function buildMiddleware(config, deps = {}) {
+    return [
+        errorMiddleware, // MUST stay first — see docblock
+        config.kind === "apiKey"
+            ? apiKeyAuthMiddleware(config)
+            : sessionAuthMiddleware(config, deps),
+    ];
+}
+/**
+ * Resolve the Authorization header value for code that performs raw fetch
+ * calls outside the openapi-fetch client (multipart uploads, downloads).
+ * API-key contexts are synchronous passthrough; session contexts mint/reuse
+ * a JWT. No 401 retry here — raw-fetch callers surface errors directly.
+ */
+export async function resolveAuthHeader(config, deps = {}) {
+    if (config.kind === "apiKey")
+        return `Bearer ${config.apiKey}`;
+    return `Bearer ${await (deps.ensureJwtFn ?? ensureJwt)(config)}`;
+}
 /**
  * Create a typed openapi-fetch client from the resolved config.
  * Attaches Bearer auth and error middleware automatically.
+ *
+ * Stays synchronous — a JWT is minted lazily inside the request middleware, so
+ * none of the ~90 call sites has to await client construction.
  */
 export function getClient(command) {
     const config = resolveConfig(command);
     const client = createClient({
         baseUrl: config.baseUrl.replace(/\/+$/, ""),
-        headers: {
-            Authorization: `Bearer ${config.apiKey}`,
-        },
     });
-    client.use(errorMiddleware);
+    client.use(...buildMiddleware(config));
     return client;
 }
 /**

package/dist/lib/config.d.ts

@@ -2,16 +2,41 @@ import Conf from "conf";
 import type { Command } from "commander";
 export interface ContextEntry {
     baseUrl: string;
-    apiKey: string;
+    /** Present on API-key contexts (CI/scripts and manual logins). */
+    apiKey?: string;
+    /** Present on session contexts created by the browser device-flow login. */
+    sessionToken?: string;
+    /** Auth service base URL for this context (e.g. https://auth.2kw.ai). */
+    authUrl?: string;
+    /** Active organization chosen at login / via set-org. */
+    organizationId?: string;
+    /** Short-lived org JWT cache — avoids one auth round-trip between rapid commands. */
+    cachedJwt?: string;
+    /** Epoch millis when cachedJwt expires. */
+    cachedJwtExp?: number;
 }
 export interface BackboneConfigStore {
     activeContext: string;
     contexts: Record<string, ContextEntry>;
 }
-export interface BackboneConfig {
+/**
+ * What a command actually authenticates with. Either a raw API key, or a
+ * browser session that a later step exchanges for a short-lived org JWT.
+ */
+export type ResolvedConfig = {
+    kind: "apiKey";
     apiKey: string;
     baseUrl: string;
-}
+} | {
+    kind: "session";
+    contextName: string;
+    sessionToken: string;
+    authUrl: string;
+    baseUrl: string;
+    organizationId?: string;
+    cachedJwt?: string;
+    cachedJwtExp?: number;
+};
 /**
  * Fallback base URL when the user has no context, env var, or local config.
  * Override at runtime by setting AI_2KW_DEFAULT_BASE_URL (or the legacy
@@ -19,6 +44,12 @@ export interface BackboneConfig {
  * deployment.
  */
 export declare const DEFAULT_BASE_URL: string;
+/**
+ * Fallback auth-service URL used when the API host is not one we recognise.
+ * Override at runtime with AI_2KW_DEFAULT_AUTH_URL.
+ */
+export declare const DEFAULT_AUTH_URL: string;
+export declare function defaultAuthUrlFor(baseUrl: string): string;
 declare const store: Conf<BackboneConfigStore>;
 export { store };
 export declare function validateContextName(name: string): void;
@@ -27,18 +58,46 @@ export declare function getActiveContext(): ContextEntry | undefined;
 export declare function getAllContexts(): Record<string, ContextEntry>;
 export declare function getContextCount(): number;
 export declare function setContext(name: string, entry: ContextEntry): void;
+/**
+ * Merge a partial update into an existing context, leaving unmentioned fields
+ * intact.
+ *
+ * Note the spread semantics: a key present in `patch` with the value
+ * `undefined` CLEARS that field rather than being ignored. That is deliberate
+ * and relied upon — e.g. `updateContext(name, { cachedJwt: undefined,
+ * cachedJwtExp: undefined })` drops a stale cached JWT.
+ */
+export declare function updateContext(name: string, patch: Partial<ContextEntry>): void;
 export declare function deleteContext(name: string): void;
 export declare function renameContext(oldName: string, newName: string): void;
 export declare function setActiveContext(name: string): void;
+/**
+ * Every input resolution considers, made explicit so the precedence rules can
+ * be exercised without touching the store, the environment, or the cwd.
+ *
+ * Flags, env vars, and the local file are API-key-only by design: session
+ * credentials are issued by the browser login and only ever live in the store.
+ */
+export interface ConfigSources {
+    flagApiKey?: string;
+    flagBaseUrl?: string;
+    envApiKey?: string;
+    envBaseUrl?: string;
+    localApiKey?: string;
+    localBaseUrl?: string;
+    activeContextName: string;
+    activeContext?: ContextEntry;
+}
+export declare function resolveConfigFromSources(s: ConfigSources): ResolvedConfig;
 /**
  * Resolve configuration with priority:
  *   1. CLI flags (--api-key, --base-url)
  *   2. Environment variables (AI_2KW_API_KEY then legacy BACKBONE_API_KEY,
  *      same for AI_2KW_BASE_URL / BACKBONE_BASE_URL)
  *   3. Local .2kw file (or legacy .backbone)
- *   4. Active context from config store
+ *   4. Active context from config store (API key or browser session)
  */
-export declare function resolveConfig(command: Command): BackboneConfig;
+export declare function resolveConfig(command: Command): ResolvedConfig;
 /** Check if --json flag is set on root command */
 export declare function isJsonOutput(command: Command): boolean;
 //# sourceMappingURL=config.d.ts.map

package/dist/lib/config.js

@@ -10,6 +10,32 @@ import { resolve } from "node:path";
 export const DEFAULT_BASE_URL = process.env.AI_2KW_DEFAULT_BASE_URL ??
     process.env.BACKBONE_DEFAULT_BASE_URL ??
     "https://backbone.manfred-kunze.dev/api";
+/**
+ * Fallback auth-service URL used when the API host is not one we recognise.
+ * Override at runtime with AI_2KW_DEFAULT_AUTH_URL.
+ */
+export const DEFAULT_AUTH_URL = process.env.AI_2KW_DEFAULT_AUTH_URL ?? "https://auth.2kw.ai";
+/** Known API-host → auth-service mappings for interactive login defaults. */
+const AUTH_URL_BY_API_HOST = {
+    "api.2kw.ai": "https://auth.2kw.ai",
+    "api-dev.2kw.ai": "https://auth-dev.2kw.ai",
+    "backbone.manfred-kunze.dev": "https://auth.2kw.ai",
+    "localhost:8080": "http://localhost:3001",
+    "127.0.0.1:8080": "http://localhost:3001",
+};
+export function defaultAuthUrlFor(baseUrl) {
+    try {
+        const host = new URL(baseUrl).host;
+        // hasOwn, not a bare index: a host like "constructor" or "toString" would
+        // otherwise resolve through Object.prototype and yield a bogus auth URL.
+        return Object.hasOwn(AUTH_URL_BY_API_HOST, host)
+            ? AUTH_URL_BY_API_HOST[host]
+            : DEFAULT_AUTH_URL;
+    }
+    catch {
+        return DEFAULT_AUTH_URL;
+    }
+}
 // One-shot flag so we only print the deprecation warning once per process,
 // even if resolveConfig is called multiple times across commands.
 let legacyEnvWarned = false;
@@ -30,9 +56,17 @@ function warnLegacyEnv(legacyName, canonicalName) {
  * fully self-contained.
  */
 const CONFIG_DIR_OVERRIDE = process.env.AI_2KW_CONFIG_DIR;
+/**
+ * Owner-only, like an ssh private key: this file holds live credentials — an
+ * API key, or a session token and the org JWT minted from it. conf defaults to
+ * 0o666, which on any shared POSIX box makes every account on it a reader.
+ * Windows largely ignores mode bits, where this is simply inert.
+ */
+const CONFIG_FILE_MODE = 0o600;
 const store = new Conf({
     projectName: "2kw",
     projectSuffix: "",
+    configFileMode: CONFIG_FILE_MODE,
     defaults: {
         activeContext: "default",
         contexts: {},
@@ -56,6 +90,9 @@ const store = new Conf({
     const legacy = new Conf({
         projectName: "backbone",
         projectSuffix: "",
+        // Same credentials, same restriction — this instance only computes a path
+        // today, but it must not be the one that widens a file if it ever writes.
+        configFileMode: CONFIG_FILE_MODE,
         defaults: { activeContext: "default", contexts: {} },
         ...(CONFIG_DIR_OVERRIDE ? { cwd: CONFIG_DIR_OVERRIDE } : {}),
     });
@@ -117,6 +154,24 @@ export function setContext(name, entry) {
     contexts[name] = entry;
     store.set("contexts", contexts);
 }
+/**
+ * Merge a partial update into an existing context, leaving unmentioned fields
+ * intact.
+ *
+ * Note the spread semantics: a key present in `patch` with the value
+ * `undefined` CLEARS that field rather than being ignored. That is deliberate
+ * and relied upon — e.g. `updateContext(name, { cachedJwt: undefined,
+ * cachedJwtExp: undefined })` drops a stale cached JWT.
+ */
+export function updateContext(name, patch) {
+    const contexts = getAllContexts();
+    const existing = contexts[name];
+    if (!existing) {
+        throw new Error(`Context "${name}" does not exist.`);
+    }
+    contexts[name] = { ...existing, ...patch };
+    store.set("contexts", contexts);
+}
 export function deleteContext(name) {
     const contexts = getAllContexts();
     if (!contexts[name]) {
@@ -186,32 +241,67 @@ function readEnv(canonical, legacy) {
     }
     return undefined;
 }
+const NO_AUTH_ERROR = 'No credentials configured. Run "2kw auth login" (browser sign-in), ' +
+    '"2kw auth login --api-key <key>", or set AI_2KW_API_KEY.';
+export function resolveConfigFromSources(s) {
+    const baseUrl = s.flagBaseUrl ??
+        s.envBaseUrl ??
+        s.localBaseUrl ??
+        s.activeContext?.baseUrl ??
+        DEFAULT_BASE_URL;
+    // Explicit API keys (flag > env > local file) always win — they are the
+    // CI/script escape hatch and must never be shadowed by a stored session.
+    const explicitApiKey = s.flagApiKey ?? s.envApiKey ?? s.localApiKey;
+    if (explicitApiKey) {
+        return { kind: "apiKey", apiKey: explicitApiKey, baseUrl };
+    }
+    const ctx = s.activeContext;
+    if (ctx?.sessionToken) {
+        // A session without an auth URL cannot be exchanged for a JWT — treat it
+        // as unusable rather than failing later with an opaque request error.
+        if (!ctx.authUrl)
+            throw new Error(NO_AUTH_ERROR);
+        return {
+            kind: "session",
+            contextName: s.activeContextName,
+            sessionToken: ctx.sessionToken,
+            authUrl: ctx.authUrl,
+            baseUrl,
+            organizationId: ctx.organizationId,
+            cachedJwt: ctx.cachedJwt,
+            cachedJwtExp: ctx.cachedJwtExp,
+        };
+    }
+    if (ctx?.apiKey) {
+        return { kind: "apiKey", apiKey: ctx.apiKey, baseUrl };
+    }
+    throw new Error(NO_AUTH_ERROR);
+}
 /**
  * Resolve configuration with priority:
  *   1. CLI flags (--api-key, --base-url)
  *   2. Environment variables (AI_2KW_API_KEY then legacy BACKBONE_API_KEY,
  *      same for AI_2KW_BASE_URL / BACKBONE_BASE_URL)
  *   3. Local .2kw file (or legacy .backbone)
- *   4. Active context from config store
+ *   4. Active context from config store (API key or browser session)
  */
 export function resolveConfig(command) {
     const root = getRootCommand(command);
     const opts = root.opts();
     const local = readLocalFile();
-    const activeCtx = getActiveContext();
-    const apiKey = opts.apiKey ??
-        readEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY") ??
-        local.apiKey ??
-        activeCtx?.apiKey;
-    const baseUrl = opts.baseUrl ??
-        readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL") ??
-        local.baseUrl ??
-        activeCtx?.baseUrl ??
-        DEFAULT_BASE_URL;
-    if (!apiKey) {
-        throw new Error('No API key configured. Run "2kw auth login" (or "backbone auth login") or set AI_2KW_API_KEY.');
-    }
-    return { apiKey, baseUrl };
+    // readEnv now runs even when a flag overrides it, so the BACKBONE_* legacy
+    // deprecation warning can fire in cases the old short-circuit chain silenced.
+    // Accepted: the variable IS set and IS deprecated, flag or no flag.
+    return resolveConfigFromSources({
+        flagApiKey: opts.apiKey,
+        flagBaseUrl: opts.baseUrl,
+        envApiKey: readEnv("AI_2KW_API_KEY", "BACKBONE_API_KEY"),
+        envBaseUrl: readEnv("AI_2KW_BASE_URL", "BACKBONE_BASE_URL"),
+        localApiKey: local.apiKey,
+        localBaseUrl: local.baseUrl,
+        activeContextName: getActiveContextName(),
+        activeContext: getActiveContext(),
+    });
 }
 /** Walk up Commander's parent chain to find root program */
 function getRootCommand(cmd) {

package/dist/lib/errors.d.ts

@@ -19,7 +19,8 @@ export type AuthFailureKind = "UNAUTHORIZED" | "FORBIDDEN" | "UNREACHABLE" | "UN
 /**
  * Classify why a credential check failed, from the thrown error alone.
  *
- * - An HTTP rejection arrives as {@link BackboneApiError}: 401 → UNAUTHORIZED,
+ * - An HTTP rejection arrives as {@link BackboneApiError} (the API) or
+ *   {@link AuthServiceError} (the auth service): 401 → UNAUTHORIZED,
  *   403 → FORBIDDEN, anything else → UNKNOWN.
  * - A network fault (fetch throws before any response) → UNREACHABLE, detected
  *   by undici's `fetch failed` TypeError or a known network error code on the

package/dist/lib/errors.js

@@ -1,4 +1,7 @@
 import chalk from "chalk";
+import { AuthServiceError } from "./auth-service.js";
+import { SessionExpiredError } from "./auth-session.js";
+import { getActiveContext, getActiveContextName, updateContext } from "./config.js";
 export class BackboneApiError extends Error {
     status;
     errorType;
@@ -23,10 +26,20 @@ const NETWORK_ERROR_CODES = new Set([
     "ENETUNREACH",
     "EHOSTUNREACH",
 ]);
+/** Shared status → kind mapping: the two rejection types agree on what a 401
+ *  and a 403 mean, and differ only in who sent them. */
+function classifyStatus(status) {
+    if (status === 401)
+        return "UNAUTHORIZED";
+    if (status === 403)
+        return "FORBIDDEN";
+    return "UNKNOWN";
+}
 /**
  * Classify why a credential check failed, from the thrown error alone.
  *
- * - An HTTP rejection arrives as {@link BackboneApiError}: 401 → UNAUTHORIZED,
+ * - An HTTP rejection arrives as {@link BackboneApiError} (the API) or
+ *   {@link AuthServiceError} (the auth service): 401 → UNAUTHORIZED,
  *   403 → FORBIDDEN, anything else → UNKNOWN.
  * - A network fault (fetch throws before any response) → UNREACHABLE, detected
  *   by undici's `fetch failed` TypeError or a known network error code on the
@@ -34,13 +47,10 @@ const NETWORK_ERROR_CODES = new Set([
  * - Everything else → UNKNOWN.
  */
 export function classifyAuthFailure(err) {
-    if (err instanceof BackboneApiError) {
-        if (err.status === 401)
-            return "UNAUTHORIZED";
-        if (err.status === 403)
-            return "FORBIDDEN";
-        return "UNKNOWN";
-    }
+    if (err instanceof BackboneApiError)
+        return classifyStatus(err.status);
+    if (err instanceof AuthServiceError)
+        return classifyStatus(err.status);
     if (isNetworkError(err))
         return "UNREACHABLE";
     return "UNKNOWN";
@@ -59,7 +69,7 @@ function isNetworkError(err) {
     return typeof causeCode === "string" && NETWORK_ERROR_CODES.has(causeCode);
 }
 const HINTS = {
-    401: 'Invalid or missing API key. Run "backbone auth login" to configure credentials.',
+    401: 'Invalid or missing API key. Run "2kw auth login" to configure credentials.',
     402: "Billing limit reached. Check your plan limits or upgrade at the dashboard.",
     403: "You don't have permission for this action. Check your organization role.",
     404: "Resource not found. Verify the ID is correct.",
@@ -67,8 +77,39 @@ const HINTS = {
     422: "Validation error. Check the input values.",
     429: "Rate limit exceeded. Wait a moment and try again.",
 };
+/**
+ * Drop the cached org JWT of the active session context.
+ *
+ * Called when the session behind that JWT turns out to be dead: keeping the
+ * token would only make the next command spend a request discovering the same
+ * 401. Best-effort by design — a read-only store is not worth a second error on
+ * top of the one being reported.
+ */
+function clearCachedJwt() {
+    try {
+        const ctx = getActiveContext();
+        // API-key contexts have no session and no cache to clear.
+        if (!ctx?.sessionToken)
+            return;
+        updateContext(getActiveContextName(), { cachedJwt: undefined, cachedJwtExp: undefined });
+    }
+    catch {
+        // Nothing actionable: the message below is still the one the user needs.
+    }
+}
 export function handleError(err, json) {
-    if (err instanceof BackboneApiError) {
+    if (err instanceof SessionExpiredError) {
+        clearCachedJwt();
+        // Reached by every command once the stored session dies, so it gets the
+        // one line that names the fix — never a stack trace.
+        if (json) {
+            console.error(JSON.stringify({ error: "session_expired", message: err.message }));
+        }
+        else {
+            console.error(chalk.yellow(err.message));
+        }
+    }
+    else if (err instanceof BackboneApiError) {
         if (json) {
             console.error(JSON.stringify({
                 error: err.errorType,
@@ -87,7 +128,21 @@ export function handleError(err, json) {
     }
     else if (err instanceof Error) {
         if (json) {
-            console.error(JSON.stringify({ error: err.name, message: err.message }));
+            // Errors from outside the typed client (AuthServiceError, undici network
+            // faults) carry their own status/code. Passing them through is what lets
+            // a scripted caller tell an "invalid_client" apart from a dead DNS name
+            // instead of string-matching the message.
+            const status = err.status;
+            // undici hangs the real code off `cause`, so read both — same pair
+            // isNetworkError checks above.
+            const code = err.code ??
+                err.cause?.code;
+            console.error(JSON.stringify({
+                error: err.name,
+                message: err.message,
+                ...(typeof status === "number" ? { status } : {}),
+                ...(typeof code === "string" ? { code } : {}),
+            }));
         }
         else {
             console.error(chalk.red(`Error: ${err.message}`));

package/dist/lib/redact.d.ts

@@ -0,0 +1,35 @@
+/**
+ * The one place that decides how a stored credential is allowed to appear —
+ * on screen, and in `--json` output.
+ *
+ * Every surface that prints a {@link ContextEntry} goes through here (`context
+ * list`, `context current`, `config list`), because a secret that reaches a
+ * terminal also reaches scrollback, CI logs, and pasted bug reports. Keeping
+ * the rules next to the shape they redact is what stops the next surface from
+ * re-deriving them and forgetting a field.
+ */
+import type { ContextEntry } from "./config.js";
+/**
+ * Enough of an API key to recognise which one it is, never enough to use it.
+ * A key too short to keep both ends of is blanked outright rather than
+ * printed with its middle "hidden".
+ */
+export declare function maskApiKey(key: string | undefined): string;
+/**
+ * Session tokens are opaque and long; the leading characters are enough to
+ * tell two apart in a bug report, and are useless on their own.
+ */
+export declare function maskSessionToken(token: string): string;
+/** The credential column of `context list` / `context current`, either kind. */
+export declare function credentialSummary(ctx: ContextEntry): string;
+/**
+ * A {@link ContextEntry} safe to serialize.
+ *
+ * The shape is otherwise the stored one so scripts reading `context list
+ * --json` keep working: `apiKey` and `sessionToken` are masked in place,
+ * `cachedJwt` is dropped entirely (it is a bearer token for the API and has no
+ * identifying value at all), and `cachedJwtExp` stays — knowing when the cache
+ * turns over is useful and expiries are not secret.
+ */
+export declare function redactContext(ctx: ContextEntry): Record<string, unknown>;
+//# sourceMappingURL=redact.d.ts.map

package/dist/lib/redact.js

@@ -0,0 +1,54 @@
+/**
+ * The one place that decides how a stored credential is allowed to appear —
+ * on screen, and in `--json` output.
+ *
+ * Every surface that prints a {@link ContextEntry} goes through here (`context
+ * list`, `context current`, `config list`), because a secret that reaches a
+ * terminal also reaches scrollback, CI logs, and pasted bug reports. Keeping
+ * the rules next to the shape they redact is what stops the next surface from
+ * re-deriving them and forgetting a field.
+ */
+/**
+ * Enough of an API key to recognise which one it is, never enough to use it.
+ * A key too short to keep both ends of is blanked outright rather than
+ * printed with its middle "hidden".
+ */
+export function maskApiKey(key) {
+    if (!key)
+        return "-";
+    if (key.length <= 11)
+        return "****";
+    return key.slice(0, 7) + "..." + key.slice(-4);
+}
+/**
+ * Session tokens are opaque and long; the leading characters are enough to
+ * tell two apart in a bug report, and are useless on their own.
+ */
+export function maskSessionToken(token) {
+    return token.length <= 8 ? "****" : token.slice(0, 8) + "...";
+}
+/** The credential column of `context list` / `context current`, either kind. */
+export function credentialSummary(ctx) {
+    if (ctx.sessionToken)
+        return `session ${maskSessionToken(ctx.sessionToken)}`;
+    return maskApiKey(ctx.apiKey);
+}
+/**
+ * A {@link ContextEntry} safe to serialize.
+ *
+ * The shape is otherwise the stored one so scripts reading `context list
+ * --json` keep working: `apiKey` and `sessionToken` are masked in place,
+ * `cachedJwt` is dropped entirely (it is a bearer token for the API and has no
+ * identifying value at all), and `cachedJwtExp` stays — knowing when the cache
+ * turns over is useful and expiries are not secret.
+ */
+export function redactContext(ctx) {
+    const { apiKey, sessionToken, cachedJwt, ...rest } = ctx;
+    void cachedJwt; // destructured only to keep it out of `rest`.
+    return {
+        ...rest,
+        ...(apiKey !== undefined ? { apiKey: maskApiKey(apiKey) } : {}),
+        ...(sessionToken !== undefined ? { sessionToken: maskSessionToken(sessionToken) } : {}),
+    };
+}
+//# sourceMappingURL=redact.js.map