@agentic-kit/cli 0.8.2 → 0.9.0

package/esm/auth-error.js

@@ -0,0 +1,108 @@
+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;
+}
+export 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)];
+}
+export 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}).`;
+}
+export const AUTH_TIMEOUT_MS = 10_000;
+export function withAuthTimeout(promise, endpoint, ms = 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/esm/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/esm/auth.js

@@ -0,0 +1,114 @@
+import { auth } from '@constructive-io/sdk';
+import { clearSession, loadSession, saveSession } from './account-store';
+import { API_KEY_YEARS, buildCreateApiKeyInput, classifyApiKeyError, needsRemint, parseMintedKey, remintApiKey } from './api-key';
+import { describeAuthError, withAuthTimeout } from './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 auth.createClient({
+        endpoint,
+        headers: { Authorization: `Bearer ${bearer}` }
+    });
+}
+async function mint(client) {
+    const data = (await client.mutation
+        .createApiKey({ input: buildCreateApiKeyInput({ years: API_KEY_YEARS }) }, { select: CREATE_KEY_SELECT })
+        .unwrap());
+    return 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.
+ */
+export async function refreshApiKeyIfNeeded({ store, context, authEndpoint }) {
+    const session = loadSession(store, context);
+    if (!session)
+        return 'signed-out';
+    const hasKey = !!session.apiKey;
+    const due = needsRemint({
+        apiKeyExpiresAt: session.apiKeyExpiresAt,
+        now: Date.now()
+    });
+    if (hasKey && !due)
+        return 'ok';
+    const client = authedClient(authEndpoint, session.accessToken);
+    try {
+        const minted = await remintApiKey({
+            currentKeyId: session.keyId,
+            revoke: (keyId) => revoke(client, keyId),
+            mint: () => mint(client)
+        });
+        saveSession(store, {
+            ...session,
+            apiKey: minted.apiKey,
+            keyId: minted.keyId,
+            apiKeyExpiresAt: minted.apiKeyExpiresAt
+        }, context);
+        return 'reminted';
+    }
+    catch (err) {
+        const kind = classifyApiKeyError(err);
+        if (kind === 'step-up-required' || kind === 'not-authenticated')
+            return 'reauth-required';
+        console.warn(`[agent] API key refresh failed (${kind}): ${describeAuthError(err, authEndpoint)}`);
+        return 'unavailable';
+    }
+}
+export 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 = auth.createClient({ endpoint: authEndpoint });
+    const request = client.mutation
+        .signIn({ input: { email: trimmedEmail, password } }, { select: SELECT })
+        .unwrap();
+    let data;
+    try {
+        data = (await withAuthTimeout(request, authEndpoint));
+    }
+    catch (err) {
+        throw new Error(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).');
+    }
+    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 loadSession(store, context);
+}
+export async function signOut({ store, context, authEndpoint }) {
+    const session = 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: ${describeAuthError(err, authEndpoint)}`);
+        }
+    }
+    clearSession(store, context);
+    return true;
+}

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

@@ -0,0 +1,58 @@
+export const 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. */
+export 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 function contextNameFor(config) {
+    for (const [name, preset] of Object.entries(BACKEND_PRESETS)) {
+        if (preset.apiEndpoint === config.apiEndpoint &&
+            preset.authEndpoint === config.authEndpoint &&
+            preset.modulesEndpoint === config.modulesEndpoint) {
+            return name;
+        }
+    }
+    return 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. */
+export 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. */
+export 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/esm/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;

package/esm/commands.js

@@ -1,4 +1,8 @@
+import { deriveSubdomainEndpoint } from '@agentic-kit/pi';
 import { Inquirerer } from 'inquirerer';
+import { loadSession } from './account-store';
+import { signIn, signOut } from './auth';
+import { BACKEND_PRESETS, contextNameFor, loadBackendConfig, saveBackendConfig } from './backend-store';
 import { defaultManifest, saveManifestFile } from './config';
 import { assembleSkills } from './skills';
 const log = (msg) => console.log(`[agent] ${msg}`);
@@ -39,6 +43,108 @@ export 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)}`;
+}
+export 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 = loadBackendConfig(config.store);
+    const prompter = new Inquirerer({ noTty: !process.stdin.isTTY });
+    try {
+        const answers = await prompter.prompt(argv, [
+            {
+                type: 'list',
+                name: 'backend',
+                message: 'Backend',
+                options: [...Object.keys(BACKEND_PRESETS), 'custom'],
+                default: saved ? 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 = deriveSubdomainEndpoint(apiUrl, 'auth');
+            const modulesEndpoint = deriveSubdomainEndpoint(apiUrl, 'modules');
+            if (!apiUrl || !authEndpoint || !modulesEndpoint) {
+                throw new Error(`Invalid API endpoint URL: ${apiUrl || '(empty)'}`);
+            }
+            backend = { apiEndpoint: apiUrl, authEndpoint, modulesEndpoint };
+        }
+        else {
+            backend = 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 = contextNameFor(backend);
+        const session = await signIn({
+            store: config.store,
+            context: contextName,
+            authEndpoint: backend.authEndpoint,
+            email: String(answers.email ?? ''),
+            password: String(answers.password ?? '')
+        });
+        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();
+    }
+}
+export async function logout(config) {
+    const backend = loadBackendConfig(config.store) ?? BACKEND_PRESETS.localnet;
+    const wasSignedIn = await signOut({
+        store: config.store,
+        authEndpoint: backend.authEndpoint
+    });
+    if (wasSignedIn)
+        log('signed out — API key revoked and session cleared.');
+    else
+        log('not signed in.');
+}
+export function whoami(config) {
+    const session = loadSession(config.store);
+    if (!session) {
+        log('not signed in — run `agent login`');
+        process.exitCode = 1;
+        return;
+    }
+    const backend = 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'}`);
+}
 export function usage() {
     console.log(`agent — the pi coding agent with the Constructive harness baked in
 
@@ -46,6 +152,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/esm/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/esm/config.js

@@ -1,7 +1,17 @@
 import { harnessDirs } from '@agentic-kit/harness';
+import { createConfigStore } from 'appstash';
 import * as fs from 'fs';
 import * as path from 'path';
+import { saveSession } from './account-store';
+import { saveBackendConfig } from './backend-store';
 export 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 const STASH_NAME = 'constructive';
+export const TOOL_NAME = 'agent';
 export const DEFAULT_SKILLS_PIN = 'main';
 /** Layer names understood by the assembler. */
 export const BASE_LAYER = 'constructive-skills';
@@ -11,13 +21,53 @@ export function defaultManifest() {
         sources: [{ name: BASE_LAYER }, { name: 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.
+ */
+export 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) {
+        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()
+        };
+        saveSession(store, session);
+    }
+    for (const file of [accountFile, backendFile]) {
+        if (fs.existsSync(file))
+            fs.renameSync(file, `${file}.migrated`);
+    }
+}
 export function loadConfig(baseDir) {
     const dirs = 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 = createConfigStore(TOOL_NAME, { stashName: 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'));
@@ -27,6 +77,7 @@ export function loadConfig(baseDir) {
         agentDir,
         overlayDir,
         manifestFile,
+        store,
         manifest: file.manifest ?? defaultManifest(),
         skillsRepo: process.env.AGENT_SKILLS_REPO ?? file.repo ?? DEFAULT_SKILLS_REPO,
         skillsPin: process.env.AGENT_SKILLS_PIN ?? file.pin ?? DEFAULT_SKILLS_PIN

package/esm/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/esm/credentials.js

@@ -0,0 +1,28 @@
+import { loadSession } from './account-store';
+import { loadBackendConfig } from './backend-store';
+import { loadConfig } from './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.
+export 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 = loadSession(loadConfig(process.env.AGENT_HOME).store);
+    if (!session)
+        return null;
+    return { userId: session.userId, accessToken: session.accessToken, apiKey: session.apiKey };
+}
+export function resolveBackendConfig() {
+    const apiEndpoint = process.env.CONSTRUCTIVE_API_ENDPOINT;
+    const modulesEndpoint = process.env.CONSTRUCTIVE_MODULES_ENDPOINT;
+    if (apiEndpoint || modulesEndpoint)
+        return { apiEndpoint, modulesEndpoint };
+    const stored = loadBackendConfig(loadConfig(process.env.AGENT_HOME).store);
+    if (!stored)
+        return undefined;
+    return { apiEndpoint: stored.apiEndpoint, modulesEndpoint: stored.modulesEndpoint };
+}

package/esm/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"];
 /**