@agentic-kit/cli 0.8.2 → 0.9.1

package/commands.js

@@ -3,8 +3,15 @@ Object.defineProperty(exports, "__esModule", { value: true });
 exports.skillsList = skillsList;
 exports.skillsUpdate = skillsUpdate;
 exports.init = init;
+exports.login = login;
+exports.logout = logout;
+exports.whoami = whoami;
 exports.usage = usage;
+const pi_1 = require("@agentic-kit/pi");
 const inquirerer_1 = require("inquirerer");
+const account_store_1 = require("./account-store");
+const auth_1 = require("./auth");
+const backend_store_1 = require("./backend-store");
 const config_1 = require("./config");
 const skills_1 = require("./skills");
 const log = (msg) => console.log(`[agent] ${msg}`);
@@ -45,6 +52,108 @@ async function init(config, argv) {
     log(`wrote ${config.manifestFile}`);
     log(`local overlay dir (highest precedence): ${config.overlayDir}`);
 }
+function maskKey(token) {
+    if (token.length <= 10)
+        return '****';
+    return `${token.slice(0, 6)}...${token.slice(-4)}`;
+}
+async function login(config, argv) {
+    if (!process.stdin.isTTY && !(argv.email && argv.password)) {
+        throw new Error('agent login is interactive and needs a terminal. For headless use, set CONSTRUCTIVE_USER_ID, CONSTRUCTIVE_ACCESS_TOKEN, and CONSTRUCTIVE_API_KEY.');
+    }
+    const saved = (0, backend_store_1.loadBackendConfig)(config.store);
+    const prompter = new inquirerer_1.Inquirerer({ noTty: !process.stdin.isTTY });
+    try {
+        const answers = await prompter.prompt(argv, [
+            {
+                type: 'list',
+                name: 'backend',
+                message: 'Backend',
+                options: [...Object.keys(backend_store_1.BACKEND_PRESETS), 'custom'],
+                default: saved ? (0, backend_store_1.contextNameFor)(saved) : 'localnet'
+            },
+            {
+                type: 'text',
+                name: 'apiUrl',
+                message: 'API GraphQL endpoint (e.g. https://api.example.com/graphql)',
+                default: saved?.apiEndpoint,
+                when: (a) => a.backend === 'custom'
+            },
+            { type: 'text', name: 'email', message: 'Email' },
+            { type: 'password', name: 'password', message: 'Password' }
+        ]);
+        let backend;
+        if (answers.backend === 'custom') {
+            const apiUrl = String(answers.apiUrl ?? '').trim();
+            const authEndpoint = (0, pi_1.deriveSubdomainEndpoint)(apiUrl, 'auth');
+            const modulesEndpoint = (0, pi_1.deriveSubdomainEndpoint)(apiUrl, 'modules');
+            if (!apiUrl || !authEndpoint || !modulesEndpoint) {
+                throw new Error(`Invalid API endpoint URL: ${apiUrl || '(empty)'}`);
+            }
+            backend = { apiEndpoint: apiUrl, authEndpoint, modulesEndpoint };
+        }
+        else {
+            backend = backend_store_1.BACKEND_PRESETS[String(answers.backend)];
+            if (!backend)
+                throw new Error(`Unknown backend preset: ${answers.backend}`);
+        }
+        // File the session under the backend's context name, then commit the backend
+        // itself: a failed sign-in must leave neither behind.
+        const contextName = (0, backend_store_1.contextNameFor)(backend);
+        const session = await (0, auth_1.signIn)({
+            store: config.store,
+            context: contextName,
+            authEndpoint: backend.authEndpoint,
+            email: String(answers.email ?? ''),
+            password: String(answers.password ?? '')
+        });
+        (0, backend_store_1.saveBackendConfig)(config.store, backend);
+        log(`signed in as ${session.email}`);
+        log(`backend: ${backend.apiEndpoint}`);
+        if (session.apiKey) {
+            log(`API key ${maskKey(session.apiKey)} (expires ${session.apiKeyExpiresAt ?? 'unknown'})`);
+        }
+        else {
+            log('warning: API key mint failed — db tools stay signed out. Run `agent login` again to retry.');
+        }
+        log(`session stored in context ${contextName}`);
+    }
+    finally {
+        prompter.close();
+    }
+}
+async function logout(config) {
+    const backend = (0, backend_store_1.loadBackendConfig)(config.store) ?? backend_store_1.BACKEND_PRESETS.localnet;
+    const wasSignedIn = await (0, auth_1.signOut)({
+        store: config.store,
+        authEndpoint: backend.authEndpoint
+    });
+    if (wasSignedIn)
+        log('signed out — API key revoked and session cleared.');
+    else
+        log('not signed in.');
+}
+function whoami(config) {
+    const session = (0, account_store_1.loadSession)(config.store);
+    if (!session) {
+        log('not signed in — run `agent login`');
+        process.exitCode = 1;
+        return;
+    }
+    const backend = (0, backend_store_1.loadBackendConfig)(config.store);
+    log(`signed in as ${session.email}`);
+    log(`user id: ${session.userId}`);
+    log(`backend: ${backend?.apiEndpoint ?? 'unknown'}`);
+    if (session.apiKey) {
+        log(`API key: ${maskKey(session.apiKey)} (expires ${session.apiKeyExpiresAt ?? 'unknown'})`);
+    }
+    else {
+        log('API key: none — db tools stay signed out. Run `agent login` to mint one.');
+    }
+    if (session.accessTokenExpiresAt)
+        log(`access token expires: ${session.accessTokenExpiresAt}`);
+    log(`context: ${config.store.getCurrentContext()?.name ?? 'none'}`);
+}
 function usage() {
     console.log(`agent — the pi coding agent with the Constructive harness baked in
 
@@ -52,6 +161,9 @@ Usage:
   agent [pi options...]        start an interactive session (pi TUI)
   agent -p "prompt"            one-shot print mode (pi)
   agent init                   configure the skills source (repo + pin)
+  agent login                  sign in to the Constructive platform
+  agent logout                 revoke the API key and clear the session
+  agent whoami                 show the signed-in account
   agent skills list            resolve + list the effective skill set
   agent skills update          re-fetch the base release and re-materialize
   agent help                   show this help

package/config.d.ts

@@ -1,5 +1,13 @@
 import { HarnessDirs, SkillsManifest } from '@agentic-kit/harness';
+import { ConfigStore } from 'appstash';
 export declare const DEFAULT_SKILLS_REPO = "constructive-io/constructive-skills";
+/**
+ * Directory identity shared with the csdk CLI and the desktop app, so a sign-in
+ * here is a sign-in there. `agent` is only the tool's own name (env prefixes,
+ * help text).
+ */
+export declare const STASH_NAME = "constructive";
+export declare const TOOL_NAME = "agent";
 export declare const DEFAULT_SKILLS_PIN = "main";
 /** Layer names understood by the assembler. */
 export declare const BASE_LAYER = "constructive-skills";
@@ -12,6 +20,8 @@ export interface AgentCliConfig {
     overlayDir: string;
     /** Path of the user-editable manifest: `<config>/skills-manifest.json`. */
     manifestFile: string;
+    /** Shared contexts + credentials store (endpoints and signed-in session). */
+    store: ConfigStore;
     manifest: SkillsManifest;
     skillsRepo: string;
     skillsPin: string;
@@ -22,6 +32,12 @@ interface ManifestFile {
     manifest?: SkillsManifest;
 }
 export declare function defaultManifest(): SkillsManifest;
+/**
+ * Move a pre-shared-store sign-in (`agent/account.json` +
+ * `agent/backend-config.json`) into the store, once. The originals are renamed
+ * rather than deleted, so a downgrade still finds them.
+ */
+export declare function importLegacyAgentFiles(store: ConfigStore, legacyDir: string): void;
 export declare function loadConfig(baseDir?: string): AgentCliConfig;
 export declare function saveManifestFile(config: AgentCliConfig, file: ManifestFile): void;
 export {};

package/config.js

@@ -33,14 +33,25 @@ var __importStar = (this && this.__importStar) || (function () {
     };
 })();
 Object.defineProperty(exports, "__esModule", { value: true });
-exports.OVERLAY_LAYER = exports.BASE_LAYER = exports.DEFAULT_SKILLS_PIN = exports.DEFAULT_SKILLS_REPO = void 0;
+exports.OVERLAY_LAYER = exports.BASE_LAYER = exports.DEFAULT_SKILLS_PIN = exports.TOOL_NAME = exports.STASH_NAME = exports.DEFAULT_SKILLS_REPO = void 0;
 exports.defaultManifest = defaultManifest;
+exports.importLegacyAgentFiles = importLegacyAgentFiles;
 exports.loadConfig = loadConfig;
 exports.saveManifestFile = saveManifestFile;
 const harness_1 = require("@agentic-kit/harness");
+const appstash_1 = require("appstash");
 const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
+const account_store_1 = require("./account-store");
+const backend_store_1 = require("./backend-store");
 exports.DEFAULT_SKILLS_REPO = 'constructive-io/constructive-skills';
+/**
+ * Directory identity shared with the csdk CLI and the desktop app, so a sign-in
+ * here is a sign-in there. `agent` is only the tool's own name (env prefixes,
+ * help text).
+ */
+exports.STASH_NAME = 'constructive';
+exports.TOOL_NAME = 'agent';
 exports.DEFAULT_SKILLS_PIN = 'main';
 /** Layer names understood by the assembler. */
 exports.BASE_LAYER = 'constructive-skills';
@@ -50,13 +61,53 @@ function defaultManifest() {
         sources: [{ name: exports.BASE_LAYER }, { name: exports.OVERLAY_LAYER }]
     };
 }
+function readLegacyFile(file) {
+    if (!fs.existsSync(file))
+        return null;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+}
+/**
+ * Move a pre-shared-store sign-in (`agent/account.json` +
+ * `agent/backend-config.json`) into the store, once. The originals are renamed
+ * rather than deleted, so a downgrade still finds them.
+ */
+function importLegacyAgentFiles(store, legacyDir) {
+    const accountFile = path.join(legacyDir, 'account.json');
+    const backendFile = path.join(legacyDir, 'backend-config.json');
+    if (!fs.existsSync(accountFile) && !fs.existsSync(backendFile))
+        return;
+    const backend = readLegacyFile(backendFile);
+    if (backend?.apiEndpoint && backend.authEndpoint && backend.modulesEndpoint) {
+        (0, backend_store_1.saveBackendConfig)(store, backend);
+    }
+    const legacy = readLegacyFile(accountFile);
+    if (legacy?.token && legacy.userId) {
+        const session = {
+            userId: legacy.userId,
+            email: legacy.email ?? '',
+            accessToken: legacy.token,
+            accessTokenExpiresAt: legacy.accessTokenExpiresAt,
+            apiKey: legacy.apiKey,
+            keyId: legacy.keyId,
+            apiKeyExpiresAt: legacy.apiKeyExpiresAt,
+            signedInAt: legacy.signedInAt ?? Date.now()
+        };
+        (0, account_store_1.saveSession)(store, session);
+    }
+    for (const file of [accountFile, backendFile]) {
+        if (fs.existsSync(file))
+            fs.renameSync(file, `${file}.migrated`);
+    }
+}
 function loadConfig(baseDir) {
     const dirs = (0, harness_1.harnessDirs)('constructive', baseDir);
     const agentDir = path.join(dirs.stash.data, 'agent');
     const overlayDir = path.join(dirs.stash.config, 'skills-overlay');
     const manifestFile = path.join(dirs.stash.config, 'skills-manifest.json');
+    const store = (0, appstash_1.createConfigStore)(exports.TOOL_NAME, { stashName: exports.STASH_NAME, baseDir });
     fs.mkdirSync(agentDir, { recursive: true });
     fs.mkdirSync(overlayDir, { recursive: true });
+    importLegacyAgentFiles(store, path.join(dirs.stash.config, 'agent'));
     let file = {};
     if (fs.existsSync(manifestFile)) {
         file = JSON.parse(fs.readFileSync(manifestFile, 'utf8'));
@@ -66,6 +117,7 @@ function loadConfig(baseDir) {
         agentDir,
         overlayDir,
         manifestFile,
+        store,
         manifest: file.manifest ?? defaultManifest(),
         skillsRepo: process.env.AGENT_SKILLS_REPO ?? file.repo ?? exports.DEFAULT_SKILLS_REPO,
         skillsPin: process.env.AGENT_SKILLS_PIN ?? file.pin ?? exports.DEFAULT_SKILLS_PIN

package/credentials.d.ts

@@ -0,0 +1,11 @@
+export type ResolvedAccount = {
+    userId: string;
+    accessToken: string;
+    apiKey?: string;
+};
+export type ResolvedBackendConfig = {
+    apiEndpoint?: string;
+    modulesEndpoint?: string;
+};
+export declare function resolveAccount(): ResolvedAccount | null;
+export declare function resolveBackendConfig(): ResolvedBackendConfig | undefined;

package/credentials.js

@@ -0,0 +1,32 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.resolveAccount = resolveAccount;
+exports.resolveBackendConfig = resolveBackendConfig;
+const account_store_1 = require("./account-store");
+const backend_store_1 = require("./backend-store");
+const config_1 = require("./config");
+// Both resolvers run on every tool call and re-read the store, so a login or
+// logout mid-session is picked up without a restart. CONSTRUCTIVE_* env vars
+// win over the store (the CI/headless path); tokens never enter process.env
+// from here.
+function resolveAccount() {
+    const userId = process.env.CONSTRUCTIVE_USER_ID;
+    const accessToken = process.env.CONSTRUCTIVE_ACCESS_TOKEN;
+    if (userId && accessToken) {
+        return { userId, accessToken, apiKey: process.env.CONSTRUCTIVE_API_KEY };
+    }
+    const session = (0, account_store_1.loadSession)((0, config_1.loadConfig)(process.env.AGENT_HOME).store);
+    if (!session)
+        return null;
+    return { userId: session.userId, accessToken: session.accessToken, apiKey: session.apiKey };
+}
+function resolveBackendConfig() {
+    const apiEndpoint = process.env.CONSTRUCTIVE_API_ENDPOINT;
+    const modulesEndpoint = process.env.CONSTRUCTIVE_MODULES_ENDPOINT;
+    if (apiEndpoint || modulesEndpoint)
+        return { apiEndpoint, modulesEndpoint };
+    const stored = (0, backend_store_1.loadBackendConfig)((0, config_1.loadConfig)(process.env.AGENT_HOME).store);
+    if (!stored)
+        return undefined;
+    return { apiEndpoint: stored.apiEndpoint, modulesEndpoint: stored.modulesEndpoint };
+}

package/db-tools.d.ts

@@ -1,7 +1,7 @@
 import { AgentCliConfig } from './config';
 /**
- * Environment variables the generated extension reads at tool-call time.
- * Without CONSTRUCTIVE_ACCESS_TOKEN the tools load but report "not signed in".
+ * Environment variables that override the stored session at tool-call time.
+ * Without env vars or a stored session the tools load but report "not signed in".
  */
 export declare const HOST_ENV_VARS: readonly ["CONSTRUCTIVE_USER_ID", "CONSTRUCTIVE_ACCESS_TOKEN", "CONSTRUCTIVE_API_KEY", "CONSTRUCTIVE_API_ENDPOINT", "CONSTRUCTIVE_MODULES_ENDPOINT"];
 /**

package/db-tools.js

@@ -39,8 +39,8 @@ const fs = __importStar(require("fs"));
 const path = __importStar(require("path"));
 const EXTENSION_FILE = 'constructive-db-tools.js';
 /**
- * Environment variables the generated extension reads at tool-call time.
- * Without CONSTRUCTIVE_ACCESS_TOKEN the tools load but report "not signed in".
+ * Environment variables that override the stored session at tool-call time.
+ * Without env vars or a stored session the tools load but report "not signed in".
  */
 exports.HOST_ENV_VARS = [
     'CONSTRUCTIVE_USER_ID',
@@ -51,26 +51,21 @@ exports.HOST_ENV_VARS = [
 ];
 // pi's TUI loads extensions from files under <agentDir>/extensions (via jiti),
 // not from factories, so the db tools are wired by materializing a small
-// generated entry there. The @agentic-kit/pi entry path is resolved from THIS
-// package at assembly time and baked in, because node resolution from the
-// appstash agent dir would not find it.
-function extensionSource(pkgEntry) {
+// generated entry there. Both entry paths are resolved from THIS package at
+// assembly time and baked in, because node resolution from the appstash agent
+// dir would not find them.
+function extensionSource(pkgEntry, credentialsEntry) {
     return `// Generated by @agentic-kit/cli — do not edit (rewritten on every \`agent\` run).
 // Registers the Constructive typed db tools + confirm gate (@agentic-kit/pi)
-// with credentials read from the environment on each call.
+// with credentials resolved on each call: CONSTRUCTIVE_* env vars first, then
+// the \`agent login\` session store.
 const { createDbTools } = require(${JSON.stringify(pkgEntry)});
+const { resolveAccount, resolveBackendConfig } = require(${JSON.stringify(credentialsEntry)});
 
 module.exports = createDbTools({
-  account: () => {
-    const userId = process.env.CONSTRUCTIVE_USER_ID;
-    const accessToken = process.env.CONSTRUCTIVE_ACCESS_TOKEN;
-    if (!userId || !accessToken) return null;
-    return { userId, accessToken, apiKey: process.env.CONSTRUCTIVE_API_KEY };
-  },
-  backendConfig: () => ({
-    apiEndpoint: process.env.CONSTRUCTIVE_API_ENDPOINT,
-    modulesEndpoint: process.env.CONSTRUCTIVE_MODULES_ENDPOINT
-  })
+  account: resolveAccount,
+  backendConfig: resolveBackendConfig,
+  signInHint: 'Run \`agent login\` to sign in.'
 });
 `;
 }
@@ -87,9 +82,10 @@ function materializeDbTools(config, log) {
         log('db tools unavailable (@agentic-kit/pi not installed) — continuing without them');
         return null;
     }
+    const credentialsEntry = require.resolve('./credentials');
     const dir = path.join(config.agentDir, 'extensions');
     fs.mkdirSync(dir, { recursive: true });
     const file = path.join(dir, EXTENSION_FILE);
-    fs.writeFileSync(file, extensionSource(pkgEntry));
+    fs.writeFileSync(file, extensionSource(pkgEntry, credentialsEntry));
     return file;
 }

package/esm/account-store.d.ts

@@ -0,0 +1,19 @@
+import { ConfigStore } from 'appstash';
+export interface AccountSession {
+    userId: string;
+    email: string;
+    accessToken: string;
+    accessTokenExpiresAt?: string;
+    apiKey?: string;
+    keyId?: string;
+    apiKeyExpiresAt?: string;
+    signedInAt: number;
+}
+export declare function loadSession(store: ConfigStore, context?: string): AccountSession | null;
+/**
+ * `context` names the backend the session belongs to; it does not have to exist
+ * as a context yet, so a sign-in can be filed before the backend is committed
+ * and a failed sign-in leaves nothing behind.
+ */
+export declare function saveSession(store: ConfigStore, session: AccountSession, context?: string): void;
+export declare function clearSession(store: ConfigStore, context?: string): void;

package/esm/account-store.js

@@ -0,0 +1,54 @@
+import { BACKEND_PRESETS, saveBackendConfig } from './backend-store';
+/**
+ * Sessions live in the shared Constructive stash, as the credentials of the
+ * active context (the chosen backend). The store owns the file layout, the
+ * atomic 0600 writes and the at-rest encoding; this module only maps between
+ * its `ContextCredentials` and the session shape the CLI passes around.
+ */
+function currentContextName(store) {
+    return store.getCurrentContext()?.name ?? null;
+}
+/** The active context, defaulting to localnet the first time one is needed. */
+function ensureContextName(store) {
+    return currentContextName(store) ?? saveBackendConfig(store, BACKEND_PRESETS.localnet);
+}
+export function loadSession(store, context) {
+    const contextName = context ?? currentContextName(store);
+    if (!contextName)
+        return null;
+    const creds = store.getCredentials(contextName);
+    if (!creds?.token || !creds.userId)
+        return null;
+    return {
+        userId: creds.userId,
+        email: creds.email ?? '',
+        accessToken: creds.token,
+        accessTokenExpiresAt: creds.expiresAt,
+        apiKey: creds.apiKey,
+        keyId: creds.keyId,
+        apiKeyExpiresAt: creds.apiKeyExpiresAt,
+        signedInAt: creds.signedInAt ?? 0
+    };
+}
+/**
+ * `context` names the backend the session belongs to; it does not have to exist
+ * as a context yet, so a sign-in can be filed before the backend is committed
+ * and a failed sign-in leaves nothing behind.
+ */
+export function saveSession(store, session, context) {
+    store.setCredentials(context ?? ensureContextName(store), {
+        token: session.accessToken,
+        expiresAt: session.accessTokenExpiresAt,
+        userId: session.userId,
+        email: session.email,
+        apiKey: session.apiKey,
+        keyId: session.keyId,
+        apiKeyExpiresAt: session.apiKeyExpiresAt,
+        signedInAt: session.signedInAt
+    });
+}
+export function clearSession(store, context) {
+    const contextName = context ?? currentContextName(store);
+    if (contextName)
+        store.removeCredentials(contextName);
+}

package/esm/api-key.d.ts

@@ -0,0 +1,51 @@
+export declare const API_KEY_NAME = "agentic-cli";
+export declare const API_KEY_ACCESS_LEVEL = "full_access";
+export declare const API_KEY_MFA_LEVEL = "none";
+export declare const API_KEY_YEARS = 5;
+/**
+ * Re-mint once the key is within a week of expiry. The mint needs a
+ * fresh-password step-up window, so in practice the refresh succeeds only right
+ * after a sign-in; otherwise it surfaces as a re-auth prompt.
+ */
+export declare const REMINT_THRESHOLD_MS: number;
+export interface MintedApiKey {
+    apiKey: string;
+    keyId: string;
+    apiKeyExpiresAt?: string;
+}
+export interface CreateApiKeyInputShape {
+    keyName: string;
+    accessLevel: string;
+    mfaLevel: string;
+    expiresIn: {
+        years: number;
+    };
+}
+export declare function buildCreateApiKeyInput({ years }: {
+    years: number;
+}): CreateApiKeyInputShape;
+interface RawApiKeyRecord {
+    apiKey?: string | null;
+    keyId?: string | null;
+    expiresAt?: string | null;
+}
+export declare function parseMintedKey(record: RawApiKeyRecord | null | undefined): MintedApiKey;
+export type ApiKeyErrorKind = 'step-up-required' | 'disabled' | 'limit-reached' | 'not-authenticated' | 'invalid-access-level' | 'unknown';
+export declare function classifyApiKeyError(err: unknown): ApiKeyErrorKind;
+export declare function needsRemint({ apiKeyExpiresAt, now, thresholdMs }: {
+    apiKeyExpiresAt: string | undefined;
+    now: number;
+    thresholdMs?: number;
+}): boolean;
+/**
+ * Mint-first, revoke-on-success: revoking before minting would destroy a
+ * still-valid key whenever the mint then fails, leaving no credential at all.
+ * The one case that needs the old key gone first is the live-key cap
+ * (API_KEY_LIMIT_REACHED): there we revoke, then retry the mint once.
+ */
+export declare function remintApiKey({ currentKeyId, revoke, mint }: {
+    currentKeyId: string | undefined;
+    revoke: (keyId: string) => Promise<void>;
+    mint: () => Promise<MintedApiKey>;
+}): Promise<MintedApiKey>;
+export {};

package/esm/api-key.js

@@ -0,0 +1,88 @@
+export const API_KEY_NAME = 'agentic-cli';
+export const API_KEY_ACCESS_LEVEL = 'full_access';
+export const API_KEY_MFA_LEVEL = 'none';
+export const API_KEY_YEARS = 5;
+/**
+ * Re-mint once the key is within a week of expiry. The mint needs a
+ * fresh-password step-up window, so in practice the refresh succeeds only right
+ * after a sign-in; otherwise it surfaces as a re-auth prompt.
+ */
+export const REMINT_THRESHOLD_MS = 1000 * 60 * 60 * 24 * 7;
+export function buildCreateApiKeyInput({ years }) {
+    return {
+        keyName: API_KEY_NAME,
+        accessLevel: API_KEY_ACCESS_LEVEL,
+        mfaLevel: API_KEY_MFA_LEVEL,
+        expiresIn: { years }
+    };
+}
+export function parseMintedKey(record) {
+    if (!record?.apiKey || !record.keyId) {
+        throw new Error('createApiKey returned no API key.');
+    }
+    return {
+        apiKey: record.apiKey,
+        keyId: record.keyId,
+        ...(record.expiresAt ? { apiKeyExpiresAt: record.expiresAt } : {})
+    };
+}
+const ERROR_CODE_MAP = {
+    STEP_UP_REQUIRED: 'step-up-required',
+    API_KEYS_DISABLED: 'disabled',
+    API_KEY_LIMIT_REACHED: 'limit-reached',
+    NOT_AUTHENTICATED: 'not-authenticated',
+    INVALID_ACCESS_LEVEL: 'invalid-access-level'
+};
+export function classifyApiKeyError(err) {
+    const errors = err?.errors;
+    if (Array.isArray(errors)) {
+        for (const e of errors) {
+            const code = e.extensions?.code;
+            if (code && ERROR_CODE_MAP[code])
+                return ERROR_CODE_MAP[code];
+        }
+    }
+    const message = err instanceof Error ? err.message : typeof err === 'string' ? err : '';
+    for (const code of Object.keys(ERROR_CODE_MAP)) {
+        if (message.includes(code))
+            return ERROR_CODE_MAP[code];
+    }
+    return 'unknown';
+}
+export function needsRemint({ apiKeyExpiresAt, now, thresholdMs = REMINT_THRESHOLD_MS }) {
+    if (!apiKeyExpiresAt)
+        return false;
+    const expires = Date.parse(apiKeyExpiresAt);
+    if (Number.isNaN(expires))
+        return false;
+    return expires - now <= thresholdMs;
+}
+/**
+ * Mint-first, revoke-on-success: revoking before minting would destroy a
+ * still-valid key whenever the mint then fails, leaving no credential at all.
+ * The one case that needs the old key gone first is the live-key cap
+ * (API_KEY_LIMIT_REACHED): there we revoke, then retry the mint once.
+ */
+export async function remintApiKey({ currentKeyId, revoke, mint }) {
+    const revokeOld = async () => {
+        if (!currentKeyId)
+            return;
+        try {
+            await revoke(currentKeyId);
+        }
+        catch (err) {
+            console.warn(`[agent] failed to revoke superseded API key ${currentKeyId}: ${err instanceof Error ? err.message : String(err)}`);
+        }
+    };
+    try {
+        const minted = await mint();
+        await revokeOld();
+        return minted;
+    }
+    catch (err) {
+        if (classifyApiKeyError(err) !== 'limit-reached')
+            throw err;
+        await revokeOld();
+        return mint();
+    }
+}

package/esm/auth-error.d.ts

@@ -0,0 +1,4 @@
+export declare function isNetworkError(err: unknown): boolean;
+export declare function describeAuthError(err: unknown, endpoint: string): string;
+export declare const AUTH_TIMEOUT_MS = 10000;
+export declare function withAuthTimeout<T>(promise: Promise<T>, endpoint: string, ms?: number): Promise<T>;