@mnemom/mnemom 0.7.2 → 0.9.0

package/dist/lib/api.d.ts

@@ -1,4 +1,14 @@
 export declare const API_BASE: string;
+/**
+ * Generate a fresh Idempotency-Key for a mutation request.
+ *
+ * The server's beginIdempotentMutation contract (mnemom-api/src/idempotency.ts)
+ * requires this header on every PUT/POST/DELETE to a mutation endpoint;
+ * without it the server short-circuits with a 400 "Idempotency-Key header is
+ * required". Callers may pass an explicit key (for retries that must hit the
+ * cached reservation) — when omitted, we mint a UUIDv4.
+ */
+export declare function newIdempotencyKey(): string;
 export interface Agent {
     id: string;
     gateway: string;
@@ -7,13 +17,33 @@ export interface Agent {
     email?: string;
     created_at: string;
 }
+/**
+ * Per docs.mnemom.ai/api-reference/openapi.json#components/schemas/IntegrityScore:
+ *
+ *   { agent_id, total_traces, verified_traces, violation_count, integrity_score }
+ *
+ * `integrity_score` is a value in [0, 1].
+ *
+ * Pre-this-fix the CLI's interface declared `score` / `verified` /
+ * `violations` / `last_updated` — none of which exist on the wire. The
+ * `mnemom integrity` command rendered every field as `undefined` (and the
+ * score as `NaN%`) against any agent. Field names now match the docs
+ * verbatim.
+ *
+ * NOTE — API shape divergence (flagged for a follow-up mnemom-api PR):
+ * the RPC path in handleGetIntegrity returns an *array* of one object
+ * (Supabase wraps TABLE-returning RPCs as arrays) without `agent_id`;
+ * the manual fallback returns the *object* with `agent_id`. The docs
+ * canonical is the object shape. We accept both shapes defensively in
+ * getIntegrity below so this CLI works against today's prod API and
+ * keeps working when the API normalizes to a single shape.
+ */
 export interface IntegrityScore {
-    agent_id: string;
-    score: number;
+    agent_id?: string;
     total_traces: number;
-    verified: number;
-    violations: number;
-    last_updated: string;
+    verified_traces: number;
+    violation_count: number;
+    integrity_score: number;
 }
 export interface Trace {
     id: string;
@@ -29,7 +59,9 @@ export interface ApiError {
     error: string;
     message: string;
 }
-export declare function postApi<T>(endpoint: string, body: unknown): Promise<T>;
+export declare function postApi<T>(endpoint: string, body: unknown, opts?: {
+    idempotencyKey?: string;
+}): Promise<T>;
 export declare function verifyBinding(agentId: string, keyHash: string): Promise<{
     bound: boolean;
     key_prefix: string | null;
@@ -53,7 +85,30 @@ export declare function listAgents(): Promise<AgentListItem[]>;
  * Note: capped at 100 agents by listAgents().
  */
 export declare function getAgentByName(name: string): Promise<AgentListItem | null>;
+/**
+ * Fetch the integrity score for an agent.
+ *
+ * `/v1/integrity/:id` is the public-when-agent-is-public, owner-otherwise
+ * data route. The CLI must send the owner's auth header so private claimed
+ * agents (the common case for customers and internal users) return 200
+ * instead of 401. fetchWithAuthRetry inherits the 401-retry-with-refresh
+ * path from PR #200 so a stale local expiresAt heals transparently.
+ */
 export declare function getIntegrity(id: string): Promise<IntegrityScore>;
+/**
+ * Fetch recent traces for an agent.
+ *
+ * The API returns an envelope `{ traces, limit, offset }` (see
+ * mnemom-api/src/index.ts:handleGetTraces). Pre-this-fix the CLI typed
+ * the response as `Trace[]` and downstream code crashed with "traces is
+ * not iterable" because the envelope is not iterable. We unwrap the
+ * envelope here and return the bare array so callers (logs.ts) can keep
+ * the simpler shape.
+ *
+ * Sends auth headers — same reasoning as getIntegrity. The pre-PR-A
+ * `{ traces: [], private: true }` leaky envelope branch is gone, so we
+ * don't need a special case for it.
+ */
 export declare function getTraces(id: string, limit?: number): Promise<Trace[]>;
 export interface AlignmentCard {
     card_id?: string;
@@ -93,11 +148,15 @@ export interface CardResponse {
     updated_at: string;
 }
 export declare function getCard(agentId: string): Promise<CardResponse | null>;
-export declare function updateCard(agentId: string, cardJson: AlignmentCard): Promise<{
+export declare function updateCard(agentId: string, cardJson: AlignmentCard, opts?: {
+    idempotencyKey?: string;
+}): Promise<{
     updated: boolean;
     card_id: string;
 }>;
-export declare function reverifyAgent(agentId: string): Promise<{
+export declare function reverifyAgent(agentId: string, opts?: {
+    idempotencyKey?: string;
+}): Promise<{
     reverified: number;
 }>;
 export interface PolicyResponse {
@@ -114,7 +173,9 @@ export interface PolicyListResponse {
     policy: PolicyResponse | null;
 }
 export declare function getPolicy(agentId: string): Promise<PolicyListResponse | null>;
-export declare function publishPolicy(agentId: string, policyJson: Record<string, unknown>): Promise<{
+export declare function publishPolicy(agentId: string, policyJson: Record<string, unknown>, opts?: {
+    idempotencyKey?: string;
+}): Promise<{
     id: string;
     version: number;
     created: boolean;
@@ -131,3 +192,64 @@ export declare function testPolicyHistorical(agentId: string, policyJson: Record
         skipped: number;
     };
 }>;
+/**
+ * Fetch the canonical alignment card as YAML (or JSON fallback).
+ * Returns the raw response body as a string.
+ */
+export declare function getAlignmentCard(agentId: string, format?: "yaml" | "json"): Promise<{
+    body: string;
+    contentType: string;
+}>;
+/** Hard cap enforced by the API on inbound alignment-card bodies (413 otherwise). */
+export declare const ALIGNMENT_CARD_MAX_BYTES: number;
+/**
+ * Shape of a successful PUT response — the canonical card the composer
+ * just wrote, serialized as JSON via mnemom-api/src/composition/response.ts:
+ * respondCard with `_composition` stripped. We type the fields we display;
+ * the rest of the canonical card is allowed (and ignored at this layer).
+ *
+ * Pre-this-fix the typed return was `{ card_id, composed: boolean }` —
+ * a fictional wrapper. The API never returned a `composed` field; the CLI
+ * was rendering "Canonical card recomposed" gated on a value that, on the
+ * real wire, is always undefined. Drop the lie; reflect the actual shape.
+ */
+export interface PublishedCardResponse {
+    card_id?: string;
+    agent_id?: string;
+    card_version?: string;
+    issued_at?: string;
+    [key: string]: unknown;
+}
+/**
+ * Publish (create or update) an alignment card.
+ * Accepts YAML or JSON body; set contentType accordingly.
+ */
+export declare function putAlignmentCard(agentId: string, body: string, contentType?: "text/yaml" | "application/json", opts?: {
+    idempotencyKey?: string;
+}): Promise<PublishedCardResponse>;
+/**
+ * Fetch the canonical protection card as YAML (or JSON fallback).
+ */
+export declare function getProtectionCard(agentId: string, format?: "yaml" | "json"): Promise<{
+    body: string;
+    contentType: string;
+}>;
+/** Hard cap enforced by the API on inbound protection-card bodies (413 otherwise). */
+export declare const PROTECTION_CARD_MAX_BYTES: number;
+/**
+ * Publish (create or update) a protection card.
+ */
+export declare function putProtectionCard(agentId: string, body: string, contentType?: "text/yaml" | "application/json", opts?: {
+    idempotencyKey?: string;
+}): Promise<PublishedCardResponse>;
+/**
+ * Resolve an agent name or ID to a server agent ID.
+ *
+ * Resolution order:
+ *  1. Explicit agentName parameter (--agent flag)
+ *  2. MNEMOM_AGENT environment variable
+ *
+ * If the value looks like an agent ID (smolt-* or mnm-*), uses it directly.
+ * Otherwise resolves the name from the authenticated user's agent list.
+ */
+export declare function resolveAgentId(agentName?: string): Promise<string>;

package/dist/lib/api.js

@@ -1,5 +1,6 @@
+import { randomUUID } from "node:crypto";
 import { getApiUrl } from "./config.js";
-import { resolveAuth } from "./auth.js";
+import { forceRefreshAccessToken, resolveAuth } from "./auth.js";
 export const API_BASE = getApiUrl();
 /** Sanitize file-sourced data before use in outbound HTTP requests. */
 function sanitizeForHttp(data) {
@@ -13,6 +14,18 @@ function validateUrl(url) {
     }
     return parsed.href;
 }
+/**
+ * Generate a fresh Idempotency-Key for a mutation request.
+ *
+ * The server's beginIdempotentMutation contract (mnemom-api/src/idempotency.ts)
+ * requires this header on every PUT/POST/DELETE to a mutation endpoint;
+ * without it the server short-circuits with a 400 "Idempotency-Key header is
+ * required". Callers may pass an explicit key (for retries that must hit the
+ * cached reservation) — when omitted, we mint a UUIDv4.
+ */
+export function newIdempotencyKey() {
+    return randomUUID();
+}
 async function fetchApi(endpoint) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
     const response = await fetch(url);
@@ -25,11 +38,12 @@ async function fetchApi(endpoint) {
     }
     return response.json();
 }
-export async function postApi(endpoint, body) {
+export async function postApi(endpoint, body, opts = {}) {
     const url = validateUrl(`${API_BASE}${endpoint}`);
     const cred = await resolveAuth();
     const headers = {
         "Content-Type": "application/json",
+        "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
     };
     if (cred.type === "jwt") {
         headers["Authorization"] = `Bearer ${cred.token}`;
@@ -74,15 +88,44 @@ async function authHeaders() {
             return {};
     }
 }
+/**
+ * Issue an authenticated fetch, and on a 401 response transparently force a
+ * token refresh and retry once.
+ *
+ * We hit this in the wild when the locally-stored expiresAt diverges from
+ * the JWT's actual exp claim (e.g. Supabase has been observed reporting
+ * expires_in values longer than the JWT's exp). Without this retry,
+ * `whoami` cheerfully reports a "valid" token while every authenticated
+ * call gets 401 — and the user has no path forward besides
+ * `mnemom logout && mnemom login`. The retry heals stale auth files
+ * transparently for users who haven't re-logged-in since the
+ * computeExpiresAt fix landed.
+ *
+ * `buildInit` is invoked fresh for each attempt so the retry picks up the
+ * new Authorization header from the refreshed token. We do NOT mint a new
+ * Idempotency-Key on the retry — the same key keys back into the same
+ * server-side reservation by design.
+ */
+async function fetchWithAuthRetry(url, buildInit) {
+    const first = await fetch(url, await buildInit());
+    if (first.status !== 401)
+        return first;
+    const refreshed = await forceRefreshAccessToken();
+    if (!refreshed)
+        return first;
+    return fetch(url, await buildInit());
+}
 export async function getAgent(id) {
     return fetchApi(`/v1/agents/${id}`);
 }
 export async function listAgents() {
     const url = validateUrl(`${API_BASE}/v1/agents?limit=100`);
-    const response = await fetch(url, { headers: await authHeaders() });
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: await authHeaders(),
+    }));
     if (!response.ok) {
         if (response.status === 401) {
-            throw new Error("Not authenticated. Run `smoltbot login` or set MNEMOM_API_KEY.");
+            throw new Error("Not authenticated. Run `mnemom login` or set MNEMOM_API_KEY.");
         }
         const err = await response.json().catch(() => ({ error: "unknown" }));
         throw new Error(err.message || `Failed to list agents: ${response.status}`);
@@ -112,11 +155,79 @@ export async function getAgentByName(name) {
     }
     return null;
 }
+/**
+ * Fetch the integrity score for an agent.
+ *
+ * `/v1/integrity/:id` is the public-when-agent-is-public, owner-otherwise
+ * data route. The CLI must send the owner's auth header so private claimed
+ * agents (the common case for customers and internal users) return 200
+ * instead of 401. fetchWithAuthRetry inherits the 401-retry-with-refresh
+ * path from PR #200 so a stale local expiresAt heals transparently.
+ */
 export async function getIntegrity(id) {
-    return fetchApi(`/v1/integrity/${id}`);
+    const url = validateUrl(`${API_BASE}/v1/integrity/${id}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `API request failed: ${response.status}`);
+    }
+    // Accept both the canonical docs shape (object) and the RPC-wrapped shape
+    // (array of one row). The latter is what prod actually returns today on
+    // the RPC path; flagged for a follow-up API normalization.
+    const body = (await response.json());
+    const row = Array.isArray(body) ? (body[0] ?? emptyIntegrityRow(id)) : body;
+    // Fill in agent_id when the API didn't (RPC path) so the field is always
+    // populated for consumers regardless of which API path served the request.
+    if (!row.agent_id)
+        row.agent_id = id;
+    return row;
+}
+function emptyIntegrityRow(agentId) {
+    return {
+        agent_id: agentId,
+        total_traces: 0,
+        verified_traces: 0,
+        violation_count: 0,
+        integrity_score: 1,
+    };
 }
+/**
+ * Fetch recent traces for an agent.
+ *
+ * The API returns an envelope `{ traces, limit, offset }` (see
+ * mnemom-api/src/index.ts:handleGetTraces). Pre-this-fix the CLI typed
+ * the response as `Trace[]` and downstream code crashed with "traces is
+ * not iterable" because the envelope is not iterable. We unwrap the
+ * envelope here and return the bare array so callers (logs.ts) can keep
+ * the simpler shape.
+ *
+ * Sends auth headers — same reasoning as getIntegrity. The pre-PR-A
+ * `{ traces: [], private: true }` leaky envelope branch is gone, so we
+ * don't need a special case for it.
+ */
 export async function getTraces(id, limit = 10) {
-    return fetchApi(`/v1/traces?agent_id=${id}&limit=${limit}`);
+    const url = validateUrl(`${API_BASE}/v1/traces?agent_id=${id}&limit=${limit}`);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        headers: await authHeaders(),
+    }));
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `API request failed: ${response.status}`);
+    }
+    const data = (await response.json());
+    // Accept both the envelope shape (current API) and a bare array (defensive
+    // — staging is mid-deploy when a CLI smoke runs against an older API).
+    if (Array.isArray(data))
+        return data;
+    return data.traces ?? [];
 }
 export async function getCard(agentId) {
     try {
@@ -130,11 +241,15 @@ export async function getCard(agentId) {
         throw error;
     }
 }
-export async function updateCard(agentId, cardJson) {
+export async function updateCard(agentId, cardJson, opts = {}) {
     const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/card`);
     const response = await fetch(url, {
         method: "PATCH",
-        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+        headers: {
+            "Content-Type": "application/json",
+            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
+            ...(await authHeaders()),
+        },
         body: sanitizeForHttp(JSON.stringify({ card_json: cardJson })),
     });
     if (!response.ok) {
@@ -146,11 +261,15 @@ export async function updateCard(agentId, cardJson) {
     }
     return response.json();
 }
-export async function reverifyAgent(agentId) {
+export async function reverifyAgent(agentId, opts = {}) {
     const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/reverify`);
     const response = await fetch(url, {
         method: "POST",
-        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+        headers: {
+            "Content-Type": "application/json",
+            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
+            ...(await authHeaders()),
+        },
     });
     if (!response.ok) {
         const error = (await response.json().catch(() => ({
@@ -173,11 +292,15 @@ export async function getPolicy(agentId) {
         throw error;
     }
 }
-export async function publishPolicy(agentId, policyJson) {
+export async function publishPolicy(agentId, policyJson, opts = {}) {
     const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/policy`);
     const response = await fetch(url, {
         method: "PUT",
-        headers: { "Content-Type": "application/json", ...(await authHeaders()) },
+        headers: {
+            "Content-Type": "application/json",
+            "Idempotency-Key": opts.idempotencyKey ?? newIdempotencyKey(),
+            ...(await authHeaders()),
+        },
         body: sanitizeForHttp(JSON.stringify({ policy_json: policyJson })),
     });
     if (!response.ok) {
@@ -205,3 +328,166 @@ export async function testPolicyHistorical(agentId, policyJson, limit = 50) {
     }
     return response.json();
 }
+// ============================================================================
+// Unified Card API (UC-4+)
+// ============================================================================
+/**
+ * Fetch the canonical alignment card as YAML (or JSON fallback).
+ * Returns the raw response body as a string.
+ */
+export async function getAlignmentCard(agentId, format = "yaml") {
+    const accept = format === "yaml" ? "text/yaml" : "application/json";
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/alignment-card`);
+    const response = await fetch(url, {
+        headers: { Accept: accept, ...(await authHeaders()) },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            return { body: "", contentType: "" };
+        }
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Failed to fetch alignment card: ${response.status}`);
+    }
+    const ct = response.headers.get("content-type") ?? "";
+    const body = await response.text();
+    return { body, contentType: ct };
+}
+/** Hard cap enforced by the API on inbound alignment-card bodies (413 otherwise). */
+export const ALIGNMENT_CARD_MAX_BYTES = 128 * 1024;
+/**
+ * Publish (create or update) an alignment card.
+ * Accepts YAML or JSON body; set contentType accordingly.
+ */
+export async function putAlignmentCard(agentId, body, contentType = "text/yaml", opts = {}) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/alignment-card`);
+    // Lock in a single Idempotency-Key for this logical mutation. If the auth
+    // token is stale and the first attempt returns 401, fetchWithAuthRetry
+    // refreshes the token and retries — but the Idempotency-Key must be the
+    // same key on both attempts so the server's reservation table sees them as
+    // a single mutation, not two competing PUTs.
+    const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();
+    const sanitizedBody = sanitizeForHttp(body);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "PUT",
+        headers: {
+            "Content-Type": contentType,
+            // The API content-negotiates the response body via Accept (see
+            // mnemom-api/src/composition/response.ts:respondYamlJson). We parse the
+            // response as JSON below, so we have to ask for JSON explicitly —
+            // Node's default Accept: */* would otherwise yield a YAML body and
+            // response.json() would crash with "Unexpected token 'a' is not valid
+            // JSON" against the canonical card we just wrote.
+            Accept: "application/json",
+            "Idempotency-Key": idempotencyKey,
+            ...(await authHeaders()),
+        },
+        body: sanitizedBody,
+    }));
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Failed to publish alignment card: ${response.status}`);
+    }
+    return response.json();
+}
+/**
+ * Fetch the canonical protection card as YAML (or JSON fallback).
+ */
+export async function getProtectionCard(agentId, format = "yaml") {
+    const accept = format === "yaml" ? "text/yaml" : "application/json";
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/protection-card`);
+    const response = await fetch(url, {
+        headers: { Accept: accept, ...(await authHeaders()) },
+    });
+    if (!response.ok) {
+        if (response.status === 404) {
+            return { body: "", contentType: "" };
+        }
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Failed to fetch protection card: ${response.status}`);
+    }
+    const ct = response.headers.get("content-type") ?? "";
+    const body = await response.text();
+    return { body, contentType: ct };
+}
+/** Hard cap enforced by the API on inbound protection-card bodies (413 otherwise). */
+export const PROTECTION_CARD_MAX_BYTES = 64 * 1024;
+/**
+ * Publish (create or update) a protection card.
+ */
+export async function putProtectionCard(agentId, body, contentType = "text/yaml", opts = {}) {
+    const url = validateUrl(`${API_BASE}/v1/agents/${agentId}/protection-card`);
+    // See putAlignmentCard for why the Idempotency-Key is computed once outside
+    // the retry closure.
+    const idempotencyKey = opts.idempotencyKey ?? newIdempotencyKey();
+    const sanitizedBody = sanitizeForHttp(body);
+    const response = await fetchWithAuthRetry(url, async () => ({
+        method: "PUT",
+        headers: {
+            "Content-Type": contentType,
+            // See putAlignmentCard for the rationale — the API negotiates response
+            // body format via Accept and we parse the response as JSON below.
+            Accept: "application/json",
+            "Idempotency-Key": idempotencyKey,
+            ...(await authHeaders()),
+        },
+        body: sanitizedBody,
+    }));
+    if (!response.ok) {
+        const error = (await response.json().catch(() => ({
+            error: "unknown",
+            message: response.statusText,
+        })));
+        throw new Error(error.message || `Failed to publish protection card: ${response.status}`);
+    }
+    return response.json();
+}
+// ============================================================================
+// Agent Resolution (server-side, no local config)
+// ============================================================================
+/**
+ * Resolve an agent name or ID to a server agent ID.
+ *
+ * Resolution order:
+ *  1. Explicit agentName parameter (--agent flag)
+ *  2. MNEMOM_AGENT environment variable
+ *
+ * If the value looks like an agent ID (smolt-* or mnm-*), uses it directly.
+ * Otherwise resolves the name from the authenticated user's agent list.
+ */
+export async function resolveAgentId(agentName) {
+    const name = agentName ?? process.env.MNEMOM_AGENT;
+    if (!name) {
+        console.error("\nAgent required. Use --agent <name> or set MNEMOM_AGENT.\n");
+        console.error("List your agents with: mnemom agents\n");
+        process.exit(1);
+    }
+    // If it looks like an agent ID, use directly (no server call needed)
+    if (/^(smolt-[0-9a-f]{8}|mnm-[0-9a-f-]{36})$/.test(name)) {
+        return name;
+    }
+    // Resolve name from server (requires auth)
+    try {
+        const agent = await getAgentByName(name);
+        if (agent)
+            return agent.id;
+    }
+    catch (err) {
+        const msg = err instanceof Error ? err.message : String(err);
+        if (msg.includes("Not authenticated")) {
+            console.error(`\nNot authenticated. Run \`mnemom login\` first.\n`);
+            process.exit(1);
+        }
+    }
+    console.error(`\nAgent not found: ${name}`);
+    console.error("List your agents with: mnemom agents\n");
+    process.exit(1);
+}

package/dist/lib/auth.d.ts

@@ -1,4 +1,26 @@
-import { type AuthTokens } from "./config.js";
+/**
+ * Auth credential management.
+ *
+ * Stores auth tokens in ~/.mnemom/auth.json (UC-9: no more config.json).
+ * License JWTs are stored alongside auth tokens.
+ */
+export interface AuthTokens {
+    accessToken: string;
+    refreshToken: string;
+    expiresAt: number;
+    userId: string;
+    email: string;
+}
+export interface AuthStore {
+    auth?: AuthTokens;
+    licenseJwt?: string;
+}
+export declare function saveAuthTokens(tokens: AuthTokens): void;
+export declare function clearAuthTokens(): void;
+export declare function getAuthInfo(): AuthTokens | null;
+export declare function saveLicenseJwt(jwt: string): void;
+export declare function clearLicenseJwt(): void;
+export declare function getLicenseJwt(): string | null;
 export type AuthCredential = {
     type: "jwt";
     token: string;
@@ -8,32 +30,44 @@ export type AuthCredential = {
 } | {
     type: "none";
 };
+/**
+ * Compute the effective expiresAt for a freshly issued access token.
+ * Prefers the JWT's own `exp` claim; falls back to `now + expires_in` if the
+ * token can't be parsed (e.g. an opaque token).
+ */
+export declare function computeExpiresAt(accessToken: string, expiresInSeconds: number): number;
 /**
  * Get a valid access token, or null if not authenticated.
  *
  * Resolution order:
- *  1. SMOLTBOT_TOKEN environment variable (CI / non-interactive)
- *  2. Stored token from config (auto-refreshes if expired)
+ *  1. MNEMOM_TOKEN environment variable (CI / non-interactive)
+ *  2. Stored token from auth store (auto-refreshes if expired)
  */
 export declare function getAccessToken(): Promise<string | null>;
+/**
+ * Force a refresh of the stored access token regardless of local expiry, and
+ * return the new access token (or null if refresh failed).
+ *
+ * Intended as a 401-recovery hook for callers: if an authenticated request
+ * comes back unauthorized despite the local cache claiming a valid token, the
+ * cache is stale (clock skew, divergence between expires_in and the JWT's
+ * actual exp, or server-side revocation). Force a refresh and retry once.
+ */
+export declare function forceRefreshAccessToken(): Promise<string | null>;
 /**
  * Get a valid access token or exit with a helpful message.
  */
 export declare function requireAccessToken(): Promise<string>;
 /**
- * Get the Mnemom API key from env var or config.
- *
- * Resolution order:
- *  1. MNEMOM_API_KEY environment variable
- *  2. Stored mnemomApiKey from config
+ * Get the Mnemom API key from env var.
  */
 export declare function getMnemomApiKey(): string | null;
 /**
  * Resolve the best available auth credential.
  *
  * Resolution order:
- *  1. JWT (SMOLTBOT_TOKEN env or stored token with auto-refresh)
- *  2. API key (MNEMOM_API_KEY env or config mnemomApiKey)
+ *  1. JWT (MNEMOM_TOKEN env or stored token with auto-refresh)
+ *  2. API key (MNEMOM_API_KEY env)
  *  3. None
  */
 export declare function resolveAuth(): Promise<AuthCredential>;
@@ -44,17 +78,8 @@ export declare function requireAuth(): Promise<AuthCredential & {
     type: "jwt" | "api-key";
 }>;
 /**
- * Authenticate via browser-based login flow.
- *
- * 1. Start a local HTTP server on a random port
- * 2. Generate a random `state` nonce for CSRF protection
- * 3. Open the browser to the API's CLI login page
- * 4. Wait for the login page to POST tokens back to localhost
- * 5. Verify state, store tokens, and close the server
+ * Check if the user is logged in (has any credential).
  */
+export declare function isLoggedIn(): Promise<boolean>;
 export declare function loginWithBrowser(): Promise<AuthTokens>;
-/**
- * Authenticate with email + password via the API auth proxy.
- * Used by --no-browser fallback.
- */
 export declare function loginWithPassword(email: string, password: string): Promise<AuthTokens>;