@agentic-kit/cli 0.8.1 → 0.9.0

package/README.md

@@ -37,6 +37,9 @@ The merged tree is materialized into the appstash-owned agent dir, so the sessio
 | `agent [options...]` | Start an interactive session with the harness skills |
 | `agent -p "prompt"` | One-shot print mode |
 | `agent init` | Configure the skills source (repo + pin) interactively |
+| `agent login` | Sign in to the Constructive platform (interactive) |
+| `agent logout` | Revoke the API key and clear the stored session |
+| `agent whoami` | Show the signed-in account, backend, and masked API key |
 | `agent skills list` | Resolve and list the effective skill set per layer |
 | `agent skills update` | Re-fetch the base release and re-materialize |
 | `agent help` | Usage |
@@ -60,12 +63,22 @@ The merged tree is materialized into the appstash-owned agent dir, so the sessio
 
 Env overrides: `AGENT_SKILLS_REPO`, `AGENT_SKILLS_PIN`, `AGENT_HOME` (appstash base dir), `GITHUB_TOKEN` (private skills repos).
 
-Db-tool credentials (read per tool call; without them the tools respond "not signed in"):
+## Authentication
+
+`agent login` signs in to the Constructive platform with email and password. The flow asks for a backend first: `localnet` (a local backend on `*.localhost:3000`), `devnet` (`*.launchql.dev`), or a custom API URL. After sign-in, the CLI mints a 5-year API key for the db tools and checks it on each startup. `agent logout` revokes the key and deletes the session.
+
+Credential files (mode `0600`, plaintext):
+
+- `~/.constructive/config/agent/account.json` — the signed-in session (user, access token, API key)
+- `~/.constructive/config/agent/backend-config.json` — the selected backend endpoints
+
+The db tools read these files on each tool call, so a login mid-session is picked up without a restart. Tokens never enter the environment of child processes.
+
+Env overrides for CI and headless use (these win over the stored session; read per tool call):
 `CONSTRUCTIVE_USER_ID`, `CONSTRUCTIVE_ACCESS_TOKEN`, `CONSTRUCTIVE_API_KEY` (optional), `CONSTRUCTIVE_API_ENDPOINT`, `CONSTRUCTIVE_MODULES_ENDPOINT` (default to the local backend).
 
 ## Roadmap
 
-- `agent login` — sign in to a Constructive backend and persist credentials in appstash instead of env vars.
 - Harness system-prompt section + templates/prompts materialization, shared with constructive-desktop via a common adapter package.
 
 ## Credits

package/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/account-store.js

@@ -0,0 +1,59 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.loadSession = loadSession;
+exports.saveSession = saveSession;
+exports.clearSession = clearSession;
+const backend_store_1 = require("./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) ?? (0, backend_store_1.saveBackendConfig)(store, backend_store_1.BACKEND_PRESETS.localnet);
+}
+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.
+ */
+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
+    });
+}
+function clearSession(store, context) {
+    const contextName = context ?? currentContextName(store);
+    if (contextName)
+        store.removeCredentials(contextName);
+}

package/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/api-key.js

@@ -0,0 +1,96 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.REMINT_THRESHOLD_MS = exports.API_KEY_YEARS = exports.API_KEY_MFA_LEVEL = exports.API_KEY_ACCESS_LEVEL = exports.API_KEY_NAME = void 0;
+exports.buildCreateApiKeyInput = buildCreateApiKeyInput;
+exports.parseMintedKey = parseMintedKey;
+exports.classifyApiKeyError = classifyApiKeyError;
+exports.needsRemint = needsRemint;
+exports.remintApiKey = remintApiKey;
+exports.API_KEY_NAME = 'agentic-cli';
+exports.API_KEY_ACCESS_LEVEL = 'full_access';
+exports.API_KEY_MFA_LEVEL = 'none';
+exports.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.
+ */
+exports.REMINT_THRESHOLD_MS = 1000 * 60 * 60 * 24 * 7;
+function buildCreateApiKeyInput({ years }) {
+    return {
+        keyName: exports.API_KEY_NAME,
+        accessLevel: exports.API_KEY_ACCESS_LEVEL,
+        mfaLevel: exports.API_KEY_MFA_LEVEL,
+        expiresIn: { years }
+    };
+}
+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'
+};
+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';
+}
+function needsRemint({ apiKeyExpiresAt, now, thresholdMs = exports.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.
+ */
+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/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>;

package/auth-error.js

@@ -0,0 +1,114 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.AUTH_TIMEOUT_MS = void 0;
+exports.isNetworkError = isNetworkError;
+exports.describeAuthError = describeAuthError;
+exports.withAuthTimeout = withAuthTimeout;
+const NETWORK_ERROR_CODES = new Set([
+    'ECONNREFUSED',
+    'ECONNRESET',
+    'ENOTFOUND',
+    'EAI_AGAIN',
+    'EHOSTUNREACH',
+    'ENETUNREACH',
+    'ETIMEDOUT',
+    'UND_ERR_CONNECT_TIMEOUT',
+    'UND_ERR_SOCKET'
+]);
+function errorCode(err) {
+    if (!err || typeof err !== 'object')
+        return undefined;
+    const { code, cause } = err;
+    if (typeof code === 'string')
+        return code;
+    if (cause && typeof cause === 'object') {
+        const causeCode = cause.code;
+        if (typeof causeCode === 'string')
+            return causeCode;
+    }
+    return undefined;
+}
+function isNetworkError(err) {
+    const code = errorCode(err);
+    if (code !== undefined)
+        return NETWORK_ERROR_CODES.has(code);
+    if (err instanceof AggregateError)
+        return true;
+    return err instanceof TypeError && /fetch failed/i.test(err.message);
+}
+function extractGraphqlMessages(err) {
+    const messages = [];
+    const codes = [];
+    const visited = new Set();
+    const visit = (value) => {
+        if (!value || typeof value !== 'object' || visited.has(value))
+            return;
+        visited.add(value);
+        const record = value;
+        if (typeof record.message === 'string' && record.message.trim() !== '') {
+            const message = record.message.trim().replace(/^GraphQL Error:\s*/u, '');
+            if (message.length > 0)
+                messages.push(message);
+        }
+        const extensions = record.extensions && typeof record.extensions === 'object'
+            ? record.extensions
+            : undefined;
+        if (typeof extensions?.code === 'string')
+            codes.push(extensions.code);
+        if (Array.isArray(record.errors))
+            record.errors.forEach(visit);
+        if (record.cause)
+            visit(record.cause);
+        if (record.extensions)
+            visit(record.extensions);
+        if (record.detail)
+            visit(record.detail);
+        if (record.data)
+            visit(record.data);
+        if (record.response)
+            visit(record.response);
+        if (record.result)
+            visit(record.result);
+        if (record.payload)
+            visit(record.payload);
+    };
+    visit(err);
+    if (messages.length === 0) {
+        for (const code of codes) {
+            if (code === 'UNAUTHENTICATED')
+                messages.push('Your session has expired. Sign in again.');
+            if (code === 'FORBIDDEN') {
+                messages.push('The server rejected this request. Check your account permissions.');
+            }
+        }
+    }
+    return [...new Set(messages)];
+}
+function describeAuthError(err, endpoint) {
+    if (isNetworkError(err)) {
+        return `Could not reach the server at ${endpoint}. Check that it is running, or pick a different backend.`;
+    }
+    const graphqlMessages = extractGraphqlMessages(err);
+    if (graphqlMessages.length > 0)
+        return graphqlMessages.join('; ');
+    const message = err instanceof Error ? err.message : String(err);
+    if (message.trim() !== '' && message !== '[object Object]')
+        return message;
+    const name = err instanceof Error ? err.name : typeof err;
+    return `Authentication failed unexpectedly (${name}).`;
+}
+exports.AUTH_TIMEOUT_MS = 10_000;
+function withAuthTimeout(promise, endpoint, ms = exports.AUTH_TIMEOUT_MS) {
+    return new Promise((resolve, reject) => {
+        const timer = setTimeout(() => {
+            reject(new Error(`The server at ${endpoint} did not respond within ${Math.round(ms / 1000)}s. Check the backend settings and try again.`));
+        }, ms);
+        promise.then(value => {
+            clearTimeout(timer);
+            resolve(value);
+        }, (err) => {
+            clearTimeout(timer);
+            reject(err instanceof Error ? err : new Error(String(err)));
+        });
+    });
+}

package/auth.d.ts

@@ -0,0 +1,28 @@
+import { ConfigStore } from 'appstash';
+import { AccountSession } from './account-store';
+export type ApiKeyRefreshStatus = 'ok' | 'reminted' | 'reauth-required' | 'unavailable' | 'signed-out';
+/**
+ * Ensure the stored session carries a usable, not-about-to-expire API key.
+ * Never throws: returns a status the caller can surface. A mint/re-mint needs
+ * the fresh-password step-up window, so it succeeds right after a sign-in and
+ * degrades to 'reauth-required' when attempted cold.
+ */
+export declare function refreshApiKeyIfNeeded({ store, context, authEndpoint }: {
+    store: ConfigStore;
+    /** Backend context the session is filed under; defaults to the active one. */
+    context?: string;
+    authEndpoint: string;
+}): Promise<ApiKeyRefreshStatus>;
+export declare function signIn({ store, context, authEndpoint, email, password }: {
+    store: ConfigStore;
+    context?: string;
+    authEndpoint: string;
+    email: string;
+    password: string;
+}): Promise<AccountSession>;
+export declare function signOut({ store, context, authEndpoint }: {
+    store: ConfigStore;
+    /** Backend context the session is filed under; defaults to the active one. */
+    context?: string;
+    authEndpoint: string;
+}): Promise<boolean>;

package/auth.js

@@ -0,0 +1,119 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.refreshApiKeyIfNeeded = refreshApiKeyIfNeeded;
+exports.signIn = signIn;
+exports.signOut = signOut;
+const sdk_1 = require("@constructive-io/sdk");
+const account_store_1 = require("./account-store");
+const api_key_1 = require("./api-key");
+const auth_error_1 = require("./auth-error");
+const SELECT = {
+    result: {
+        select: { userId: true, accessToken: true, accessTokenExpiresAt: true }
+    }
+};
+const CREATE_KEY_SELECT = {
+    result: { select: { apiKey: true, keyId: true, expiresAt: true } }
+};
+const REVOKE_KEY_SELECT = { result: true };
+function authedClient(endpoint, bearer) {
+    return sdk_1.auth.createClient({
+        endpoint,
+        headers: { Authorization: `Bearer ${bearer}` }
+    });
+}
+async function mint(client) {
+    const data = (await client.mutation
+        .createApiKey({ input: (0, api_key_1.buildCreateApiKeyInput)({ years: api_key_1.API_KEY_YEARS }) }, { select: CREATE_KEY_SELECT })
+        .unwrap());
+    return (0, api_key_1.parseMintedKey)(data?.createApiKey?.result);
+}
+async function revoke(client, keyId) {
+    await client.mutation.revokeApiKey({ input: { keyId } }, { select: REVOKE_KEY_SELECT }).unwrap();
+}
+/**
+ * Ensure the stored session carries a usable, not-about-to-expire API key.
+ * Never throws: returns a status the caller can surface. A mint/re-mint needs
+ * the fresh-password step-up window, so it succeeds right after a sign-in and
+ * degrades to 'reauth-required' when attempted cold.
+ */
+async function refreshApiKeyIfNeeded({ store, context, authEndpoint }) {
+    const session = (0, account_store_1.loadSession)(store, context);
+    if (!session)
+        return 'signed-out';
+    const hasKey = !!session.apiKey;
+    const due = (0, api_key_1.needsRemint)({
+        apiKeyExpiresAt: session.apiKeyExpiresAt,
+        now: Date.now()
+    });
+    if (hasKey && !due)
+        return 'ok';
+    const client = authedClient(authEndpoint, session.accessToken);
+    try {
+        const minted = await (0, api_key_1.remintApiKey)({
+            currentKeyId: session.keyId,
+            revoke: (keyId) => revoke(client, keyId),
+            mint: () => mint(client)
+        });
+        (0, account_store_1.saveSession)(store, {
+            ...session,
+            apiKey: minted.apiKey,
+            keyId: minted.keyId,
+            apiKeyExpiresAt: minted.apiKeyExpiresAt
+        }, context);
+        return 'reminted';
+    }
+    catch (err) {
+        const kind = (0, api_key_1.classifyApiKeyError)(err);
+        if (kind === 'step-up-required' || kind === 'not-authenticated')
+            return 'reauth-required';
+        console.warn(`[agent] API key refresh failed (${kind}): ${(0, auth_error_1.describeAuthError)(err, authEndpoint)}`);
+        return 'unavailable';
+    }
+}
+async function signIn({ store, context, authEndpoint, email, password }) {
+    const trimmedEmail = email.trim();
+    if (!trimmedEmail || !password)
+        throw new Error('Email and password are required.');
+    const client = sdk_1.auth.createClient({ endpoint: authEndpoint });
+    const request = client.mutation
+        .signIn({ input: { email: trimmedEmail, password } }, { select: SELECT })
+        .unwrap();
+    let data;
+    try {
+        data = (await (0, auth_error_1.withAuthTimeout)(request, authEndpoint));
+    }
+    catch (err) {
+        throw new Error((0, auth_error_1.describeAuthError)(err, authEndpoint));
+    }
+    const record = data?.signIn?.result;
+    if (!record?.accessToken || !record.userId) {
+        throw new Error('Authentication returned no access token (MFA may be required).');
+    }
+    (0, account_store_1.saveSession)(store, {
+        userId: record.userId,
+        email: trimmedEmail,
+        accessToken: record.accessToken,
+        ...(record.accessTokenExpiresAt ? { accessTokenExpiresAt: record.accessTokenExpiresAt } : {}),
+        signedInAt: Date.now()
+    }, context);
+    // Mint the long-lived API key inside the fresh step-up window. Best-effort: a
+    // mint failure leaves a valid signed-in session that lacks a key until re-auth.
+    await refreshApiKeyIfNeeded({ store, context, authEndpoint });
+    return (0, account_store_1.loadSession)(store, context);
+}
+async function signOut({ store, context, authEndpoint }) {
+    const session = (0, account_store_1.loadSession)(store, context);
+    if (!session)
+        return false;
+    if (session.keyId) {
+        try {
+            await revoke(authedClient(authEndpoint, session.accessToken), session.keyId);
+        }
+        catch (err) {
+            console.warn(`[agent] API key revoke on sign-out failed: ${(0, auth_error_1.describeAuthError)(err, authEndpoint)}`);
+        }
+    }
+    (0, account_store_1.clearSession)(store, context);
+    return true;
+}

package/backend-store.d.ts

@@ -0,0 +1,19 @@
+import { ConfigStore } from 'appstash';
+export interface BackendConfig {
+    apiEndpoint: string;
+    authEndpoint: string;
+    modulesEndpoint: string;
+}
+export declare const BACKEND_PRESETS: Record<string, BackendConfig>;
+/** Context name used for endpoints that match no preset. */
+export declare const CUSTOM_CONTEXT = "custom";
+/**
+ * A chosen backend is a named context in the shared store: the preset name when
+ * the endpoints match one, `custom` otherwise. Credentials hang off the context,
+ * so signing in against localnet and devnet keeps two independent sessions.
+ */
+export declare function contextNameFor(config: BackendConfig): string;
+/** Endpoints of the active context, or null when no backend has been chosen. */
+export declare function loadBackendConfig(store: ConfigStore): BackendConfig | null;
+/** Persist the endpoints as a context and make it active. */
+export declare function saveBackendConfig(store: ConfigStore, config: BackendConfig): string;

package/backend-store.js

@@ -0,0 +1,64 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.CUSTOM_CONTEXT = exports.BACKEND_PRESETS = void 0;
+exports.contextNameFor = contextNameFor;
+exports.loadBackendConfig = loadBackendConfig;
+exports.saveBackendConfig = saveBackendConfig;
+exports.BACKEND_PRESETS = {
+    localnet: {
+        apiEndpoint: 'http://api.localhost:3000/graphql',
+        authEndpoint: 'http://auth.localhost:3000/graphql',
+        modulesEndpoint: 'http://modules.localhost:3000/graphql'
+    },
+    devnet: {
+        apiEndpoint: 'https://api.launchql.dev/graphql',
+        authEndpoint: 'https://auth.launchql.dev/graphql',
+        modulesEndpoint: 'https://modules.launchql.dev/graphql'
+    }
+};
+/** Context name used for endpoints that match no preset. */
+exports.CUSTOM_CONTEXT = 'custom';
+/**
+ * A chosen backend is a named context in the shared store: the preset name when
+ * the endpoints match one, `custom` otherwise. Credentials hang off the context,
+ * so signing in against localnet and devnet keeps two independent sessions.
+ */
+function contextNameFor(config) {
+    for (const [name, preset] of Object.entries(exports.BACKEND_PRESETS)) {
+        if (preset.apiEndpoint === config.apiEndpoint &&
+            preset.authEndpoint === config.authEndpoint &&
+            preset.modulesEndpoint === config.modulesEndpoint) {
+            return name;
+        }
+    }
+    return exports.CUSTOM_CONTEXT;
+}
+function toBackendConfig(targets) {
+    const apiEndpoint = targets?.api?.endpoint;
+    const authEndpoint = targets?.auth?.endpoint;
+    const modulesEndpoint = targets?.modules?.endpoint;
+    if (!apiEndpoint || !authEndpoint || !modulesEndpoint)
+        return null;
+    return { apiEndpoint, authEndpoint, modulesEndpoint };
+}
+/** Endpoints of the active context, or null when no backend has been chosen. */
+function loadBackendConfig(store) {
+    const ctx = store.getCurrentContext();
+    if (!ctx)
+        return null;
+    return toBackendConfig(ctx.targets);
+}
+/** Persist the endpoints as a context and make it active. */
+function saveBackendConfig(store, config) {
+    const name = contextNameFor(config);
+    store.createContext(name, {
+        endpoint: config.apiEndpoint,
+        targets: {
+            api: { endpoint: config.apiEndpoint },
+            auth: { endpoint: config.authEndpoint },
+            modules: { endpoint: config.modulesEndpoint }
+        }
+    });
+    store.setCurrentContext(name);
+    return name;
+}

package/commands.d.ts

@@ -2,4 +2,7 @@ import { AgentCliConfig } from './config';
 export declare function skillsList(config: AgentCliConfig): Promise<void>;
 export declare function skillsUpdate(config: AgentCliConfig): Promise<void>;
 export declare function init(config: AgentCliConfig, argv: Record<string, unknown>): Promise<void>;
+export declare function login(config: AgentCliConfig, argv: Record<string, unknown>): Promise<void>;
+export declare function logout(config: AgentCliConfig): Promise<void>;
+export declare function whoami(config: AgentCliConfig): void;
 export declare function usage(): void;