@agentage/cli 0.0.3 → 0.25.0

package/dist/daemon/lifecycle.js

@@ -0,0 +1,151 @@
+import { randomBytes } from 'node:crypto';
+import { existsSync, readFileSync, unlinkSync, writeFileSync } from 'node:fs';
+import { join } from 'node:path';
+import chalk from 'chalk';
+import { getConfigDir } from '../lib/fs/config.js';
+// The daemon's on-disk state lives beside the config so an isolated AGENTAGE_CONFIG_DIR fully
+// isolates a daemon (pid, port, token) from any other - tests never collide with a real one.
+export const DEFAULT_DAEMON_PORT = 4243;
+// The daemon entry exits with this code on EADDRINUSE so a spawning CLI can short-circuit fast.
+export const EADDRINUSE_EXIT_CODE = 3;
+const pidPath = () => join(getConfigDir(), 'daemon.pid');
+const portPath = () => join(getConfigDir(), 'daemon.port');
+const tokenPath = () => join(getConfigDir(), 'daemon.token');
+export const writePidFile = (pid) => writeFileSync(pidPath(), String(pid), 'utf-8');
+export const writePortFile = (port) => writeFileSync(portPath(), String(port), 'utf-8');
+// A 256-bit per-daemon secret gating /api/*; only a same-machine client that can read the 0600
+// file (so, the same user) can call it, closing the loopback socket to any other local process.
+export const generateDaemonToken = () => randomBytes(32).toString('hex');
+export const writeTokenFile = (token) => writeFileSync(tokenPath(), token, { encoding: 'utf-8', mode: 0o600 });
+export const readDaemonToken = () => {
+    if (!existsSync(tokenPath()))
+        return null;
+    const token = readFileSync(tokenPath(), 'utf-8').trim();
+    return token.length > 0 ? token : null;
+};
+export const removePidFile = () => {
+    if (existsSync(pidPath()))
+        unlinkSync(pidPath());
+};
+export const removePortFile = () => {
+    if (existsSync(portPath()))
+        unlinkSync(portPath());
+};
+export const removeTokenFile = () => {
+    if (existsSync(tokenPath()))
+        unlinkSync(tokenPath());
+};
+const readNumberFile = (path) => {
+    if (!existsSync(path))
+        return null;
+    const n = Number.parseInt(readFileSync(path, 'utf-8').trim(), 10);
+    return Number.isNaN(n) ? null : n;
+};
+// Env override wins (test isolation); else the running daemon's recorded port; else the default.
+export const resolvePort = () => {
+    const env = process.env['AGENTAGE_DAEMON_PORT'];
+    if (env) {
+        const n = Number.parseInt(env, 10);
+        if (!Number.isNaN(n))
+            return n;
+    }
+    return readNumberFile(portPath()) ?? DEFAULT_DAEMON_PORT;
+};
+const readPid = () => readNumberFile(pidPath());
+export const isProcessAlive = (pid) => {
+    try {
+        process.kill(pid, 0);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+// SIGTERM a known-live pid (a legacy daemon we learned about via /health, not our pidfile).
+// Returns whether the signal was delivered; false when the pid is already gone or unsignalable.
+export const signalPid = (pid) => {
+    if (!isProcessAlive(pid))
+        return false;
+    try {
+        process.kill(pid, 'SIGTERM');
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+export const isDaemonRunning = () => {
+    const pid = readPid();
+    if (pid === null)
+        return false;
+    if (!isProcessAlive(pid)) {
+        removePidFile();
+        removePortFile();
+        removeTokenFile();
+        return false;
+    }
+    return true;
+};
+// SIGTERM the running daemon and clear its on-disk state; the daemon also self-cleans on exit.
+// Returns whether a live process was actually signalled.
+export const stopDaemon = () => {
+    const pid = readPid();
+    if (pid === null)
+        return false;
+    const alive = isProcessAlive(pid);
+    if (alive)
+        process.kill(pid, 'SIGTERM');
+    removePidFile();
+    removePortFile();
+    removeTokenFile();
+    return alive;
+};
+// Lightweight, cycle-free /health probe (daemon-client imports this module) returning the reported
+// pid; null when the port holds no reachable agentage daemon.
+const probeDaemonPid = async (port) => {
+    try {
+        const res = await fetch(`http://127.0.0.1:${port}/api/health`, {
+            signal: AbortSignal.timeout(500),
+        });
+        if (!res.ok)
+            return null;
+        const h = (await res.json());
+        return typeof h.pid === 'number' ? h.pid : null;
+    }
+    catch {
+        return null;
+    }
+};
+// stopDaemon signals a bare recorded pid, which the OS may have recycled onto an unrelated process.
+// Guard it: signal only when /health confirms the pid is our daemon, or - if no port was recorded -
+// fall back to the blind signal with a printed caveat. Refuse otherwise rather than kill a stranger.
+export const stopDaemonSafely = async (probe = probeDaemonPid) => {
+    const pid = readPid();
+    if (pid === null || !isProcessAlive(pid))
+        return stopDaemon();
+    const port = readNumberFile(portPath());
+    const confirmed = port !== null && (await probe(port)) === pid;
+    if (confirmed)
+        return stopDaemon();
+    if (port === null) {
+        console.error(chalk.yellow(`No recorded port; signalling pid ${pid} without confirmation.`));
+        return stopDaemon();
+    }
+    console.error(chalk.yellow(`Daemon on port ${port} did not confirm pid ${pid}; not signalling. Delete the pid file to force.`));
+    return false;
+};
+// Stop, then wait (bounded) for the old process to actually exit so a restart can rebind the
+// port without an EADDRINUSE window. Returns whether the process is confirmed gone.
+export const stopDaemonAndWait = async (timeoutMs = 2000) => {
+    const pid = readPid();
+    const signalled = stopDaemon();
+    if (!signalled || pid === null)
+        return true;
+    const deadline = Date.now() + timeoutMs;
+    while (isProcessAlive(pid)) {
+        if (Date.now() >= deadline)
+            return false;
+        await new Promise((r) => setTimeout(r, 50));
+    }
+    return true;
+};

package/dist/daemon/mcp-http.d.ts

@@ -0,0 +1,3 @@
+import { type IncomingMessage, type ServerResponse } from 'node:http';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+export declare const handleMcp: (req: IncomingMessage, res: ServerResponse, buildServer: () => Promise<McpServer>, allowedHosts: string[]) => Promise<void>;

package/dist/daemon/mcp-http.js

@@ -0,0 +1,34 @@
+import { StreamableHTTPServerTransport } from '@modelcontextprotocol/sdk/server/streamableHttp.js';
+const jsonRpcError = (res, status, message) => {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify({ jsonrpc: '2.0', error: { code: -32000, message }, id: null }));
+};
+// Stateless Streamable HTTP (JSON, no session), mirroring the cloud memory endpoint: a fresh MCP
+// server + transport per POST, torn down when the response closes. GET/DELETE are 405 - stateless
+// exposes no server-initiated SSE stream or session teardown. Tokenless (editor clients stay
+// simple) but DNS-rebinding-protected: allowedHosts pins the Host to the bound loopback port.
+export const handleMcp = async (req, res, buildServer, allowedHosts) => {
+    if (req.method !== 'POST') {
+        jsonRpcError(res, 405, 'Method not allowed: this endpoint is stateless (POST only).');
+        return;
+    }
+    const server = await buildServer();
+    const transport = new StreamableHTTPServerTransport({
+        sessionIdGenerator: undefined,
+        enableJsonResponse: true,
+        enableDnsRebindingProtection: true,
+        allowedHosts,
+    });
+    res.on('close', () => {
+        void transport.close();
+        void server.close();
+    });
+    try {
+        await server.connect(transport);
+        await transport.handleRequest(req, res);
+    }
+    catch {
+        if (!res.headersSent)
+            jsonRpcError(res, 500, 'Internal server error');
+    }
+};

package/dist/daemon/server.d.ts

@@ -0,0 +1,26 @@
+import { type Server } from 'node:http';
+import { type McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import { type MemoryClient } from '../lib/memory/memory-client.js';
+import { type SyncResult } from '../sync/git/cycle.js';
+import { type CouchSyncResult } from '../sync/couch/manager.js';
+import { type SyncStatus } from '../sync/git/manager.js';
+import { type MemoryVerb } from './actions.js';
+export interface DaemonSyncApi {
+    status: () => SyncStatus;
+    runNow: (vault: string) => Promise<SyncResult | CouchSyncResult>;
+}
+export interface DaemonServerOptions {
+    getClient: () => MemoryClient | Promise<MemoryClient>;
+    buildMcpServer?: () => Promise<McpServer>;
+    sync?: DaemonSyncApi;
+    onMutation?: (verb: MemoryVerb, body: unknown) => void;
+    authToken: string;
+    version: string;
+    startedAt?: number;
+}
+export interface DaemonServer {
+    server: Server;
+    start: (port: number, host?: string) => Promise<void>;
+    stop: () => Promise<void>;
+}
+export declare const createDaemonServer: (opts: DaemonServerOptions) => DaemonServer;

package/dist/daemon/server.js

@@ -0,0 +1,136 @@
+import { createServer } from 'node:http';
+import { dispatchMemory, isMemoryVerb } from './actions.js';
+import { isAllowedHost, isAllowedOrigin, loopbackHosts } from './guards.js';
+import { handleMcp } from './mcp-http.js';
+const LOOPBACK = '127.0.0.1';
+const AUTH_HEADER = 'x-agentage-token';
+const readBody = (req) => new Promise((resolve, reject) => {
+    const chunks = [];
+    req.on('data', (c) => chunks.push(c));
+    req.on('end', () => {
+        const raw = Buffer.concat(chunks).toString('utf-8');
+        if (raw.length === 0)
+            return resolve({});
+        try {
+            resolve(JSON.parse(raw));
+        }
+        catch {
+            reject(new Error('invalid JSON body'));
+        }
+    });
+    req.on('error', reject);
+});
+const send = (res, status, body) => {
+    res.writeHead(status, { 'Content-Type': 'application/json' });
+    res.end(JSON.stringify(body));
+};
+const isJsonContentType = (req) => (req.headers['content-type'] ?? '').split(';')[0]?.trim() === 'application/json';
+const header = (req, name) => {
+    const v = req.headers[name];
+    return Array.isArray(v) ? v[0] : v;
+};
+// Loopback-only JSON HTTP: GET /api/health + POST /api/memory/<verb> (the CLI verbs) + POST /mcp
+// (the frozen 6 tools for on-machine AI clients, stateless Streamable HTTP). Web-origin defense on
+// EVERY request (Host + Origin allow-lists + DNS-rebinding protection on /mcp); /api/* additionally
+// needs the per-daemon token, while /health and /mcp stay tokenless for probes and editor clients.
+export const createDaemonServer = (opts) => {
+    const startedAt = opts.startedAt ?? Date.now();
+    let served = 0;
+    let boundPort = 0;
+    // 403 unless the request looks like it came from a genuine same-machine loopback client.
+    const originGuard = (req) => isAllowedHost(header(req, 'host'), boundPort) && isAllowedOrigin(header(req, 'origin'));
+    const handle = async (req, res) => {
+        const url = req.url ?? '/';
+        if (!originGuard(req))
+            return send(res, 403, { error: 'forbidden' });
+        const path = url.split('?')[0] ?? url;
+        const isApi = path.startsWith('/api/') && path !== '/api/health';
+        if (isApi && header(req, AUTH_HEADER) !== opts.authToken) {
+            return send(res, 401, { error: 'unauthorized' });
+        }
+        if (isApi && req.method === 'POST' && !isJsonContentType(req)) {
+            return send(res, 415, { error: 'unsupported media type' });
+        }
+        if (req.method === 'GET' && url === '/api/health') {
+            return send(res, 200, {
+                ok: true,
+                version: opts.version,
+                pid: process.pid,
+                uptime: Math.floor((Date.now() - startedAt) / 1000),
+                served,
+                mcp: !!opts.buildMcpServer,
+            });
+        }
+        if (path === '/mcp') {
+            if (!opts.buildMcpServer)
+                return send(res, 404, { error: 'not found' });
+            return handleMcp(req, res, opts.buildMcpServer, loopbackHosts(boundPort));
+        }
+        if (req.method === 'GET' && url === '/api/sync/status') {
+            if (!opts.sync)
+                return send(res, 404, { error: 'not found' });
+            return send(res, 200, opts.sync.status());
+        }
+        if (req.method === 'POST' && url === '/api/sync/run') {
+            if (!opts.sync)
+                return send(res, 404, { error: 'not found' });
+            const body = (await readBody(req));
+            if (!body.vault)
+                return send(res, 400, { error: 'vault is required' });
+            try {
+                return send(res, 200, await opts.sync.runNow(body.vault));
+            }
+            catch (err) {
+                return send(res, 400, { error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        const match = url.match(/^\/api\/memory\/([a-z]+)$/);
+        if (req.method === 'POST' && match) {
+            const verb = match[1];
+            if (!isMemoryVerb(verb))
+                return send(res, 404, { error: `unknown verb: ${verb}` });
+            try {
+                const body = await readBody(req);
+                const result = await dispatchMemory(await opts.getClient(), verb, body);
+                served += 1;
+                opts.onMutation?.(verb, body); // fire-and-forget account push-on-save
+                return send(res, 200, result);
+            }
+            catch (err) {
+                return send(res, 400, { error: err instanceof Error ? err.message : String(err) });
+            }
+        }
+        send(res, 404, { error: 'not found' });
+    };
+    const server = createServer((req, res) => {
+        handle(req, res).catch((err) => send(res, 500, { error: err instanceof Error ? err.message : String(err) }));
+    });
+    const start = (port, host = LOOPBACK) => new Promise((resolve, reject) => {
+        const onError = (err) => {
+            if (err.code !== 'EADDRINUSE')
+                return reject(err);
+            // Preserve the code so the entry point can exit distinctly on a busy port.
+            const busy = new Error(`port ${port} already in use`);
+            busy.code = 'EADDRINUSE';
+            reject(busy);
+        };
+        server.once('error', onError);
+        server.listen(port, host, () => {
+            const addr = server.address();
+            boundPort = typeof addr === 'object' && addr ? addr.port : port;
+            server.removeListener('error', onError);
+            resolve();
+        });
+    });
+    // close() alone hangs on idle keep-alive sockets; drop idle ones now, force the rest after a grace.
+    const stop = () => new Promise((resolve) => {
+        server.closeIdleConnections();
+        const grace = setTimeout(() => server.closeAllConnections(), 500);
+        grace.unref();
+        server.close(() => {
+            clearTimeout(grace);
+            resolve();
+        });
+    });
+    return { server, start, stop };
+};

package/dist/daemon-entry.d.ts

@@ -0,0 +1,7 @@
+export declare const isEaddrinuse: (err: unknown) => boolean;
+export declare const createStateCleanup: (remove: () => void) => {
+    markOwned: () => void;
+    cleanup: () => void;
+};
+export declare const safeReschedule: (steps: Array<() => void>, onError: (msg: string) => void) => void;
+export declare const mcpEnabled: (env?: NodeJS.ProcessEnv) => boolean;

package/dist/daemon-entry.js

@@ -0,0 +1,128 @@
+import { unwatchFile, watchFile } from 'node:fs';
+import { fileURLToPath } from 'node:url';
+import { isAccountVault } from '@agentage/memory-core';
+import { createClientProvider } from './daemon/client-provider.js';
+import { EADDRINUSE_EXIT_CODE, generateDaemonToken, removePidFile, removePortFile, removeTokenFile, resolvePort, writePidFile, writePortFile, writeTokenFile, } from './daemon/lifecycle.js';
+import { createDaemonServer } from './daemon/server.js';
+import { loadLocalMemoryServer } from './mcp/local-server.js';
+import { loadVaultsConfig, vaultsJsonPath } from './lib/vault/vaults.js';
+import { createCouchSyncManager } from './sync/couch/manager.js';
+import { createDiscoverWatcher } from './sync/discover/watcher.js';
+import { createSyncManager } from './sync/git/manager.js';
+import { VERSION } from './utils/version.js';
+export const isEaddrinuse = (err) => typeof err === 'object' && err !== null && err.code === 'EADDRINUSE';
+// Gate state-file cleanup on ownership: a loser of an autostart race must never wipe the winner's
+// pid/port/token files. Only the process that actually wrote them may remove them.
+export const createStateCleanup = (remove) => {
+    let owned = false;
+    return {
+        markOwned: () => {
+            owned = true;
+        },
+        cleanup: () => {
+            if (owned)
+                remove();
+        },
+    };
+};
+// Run each reschedule independently: a transiently-invalid config edit must not crash the daemon or
+// stop the other channels rescheduling; the throwing one keeps its last-good schedule.
+export const safeReschedule = (steps, onError) => {
+    for (const step of steps) {
+        try {
+            step();
+        }
+        catch (err) {
+            onError(err instanceof Error ? err.message : String(err));
+        }
+    }
+};
+// MCP is served at /mcp by default; AGENTAGE_DAEMON_NO_MCP=1 leaves buildMcpServer unset so the
+// endpoint 404s (the `daemon start --no-mcp` flag sets this on the spawned process).
+export const mcpEnabled = (env = process.env) => env['AGENTAGE_DAEMON_NO_MCP'] !== '1';
+// Unset/empty/invalid -> undefined (the watcher's defaults apply); the watcher floors low values.
+const envInt = (name) => {
+    const raw = process.env[name];
+    if (!raw)
+        return undefined;
+    const v = Number(raw);
+    return Number.isFinite(v) && v >= 0 ? v : undefined;
+};
+const state = createStateCleanup(() => {
+    removePidFile();
+    removePortFile();
+    removeTokenFile();
+});
+// The detached, long-lived engine host: one loopback HTTP server that owns a single in-process
+// engine and serialises every vault mutation, avoiding concurrent git index.lock collisions. It
+// runs both sync loops (git origins + the account/couch channel) and reschedules on config change.
+const main = async () => {
+    const port = resolvePort();
+    const authToken = generateDaemonToken();
+    const git = createSyncManager();
+    const couch = createCouchSyncManager();
+    const discover = createDiscoverWatcher({
+        log: (msg) => console.log(`[discover] ${msg}`),
+        debounceMs: envInt('AGENTAGE_DISCOVER_DEBOUNCE_MS'),
+        pollMs: envInt('AGENTAGE_DISCOVER_POLL_MS'),
+    });
+    // A vault is on exactly one channel: an account (agentage) vault syncs over couch, else git.
+    const runNow = (vault) => {
+        const entry = loadVaultsConfig().config.vaults?.[vault];
+        return entry && isAccountVault(entry) ? couch.runNow(vault) : git.runNow(vault);
+    };
+    const server = createDaemonServer({
+        getClient: createClientProvider(),
+        buildMcpServer: mcpEnabled() ? loadLocalMemoryServer : undefined,
+        sync: {
+            status: () => ({ ...git.status(), couch: couch.status(), discover: discover.status() }),
+            runNow,
+        },
+        onMutation: (verb, body) => couch.onWrite(verb, body),
+        authToken,
+        version: VERSION,
+    });
+    await server.start(port);
+    writePidFile(process.pid);
+    writePortFile(port);
+    writeTokenFile(authToken);
+    state.markOwned();
+    const reschedule = () => safeReschedule([() => git.reschedule(), () => couch.reschedule(), () => discover.reschedule()], (msg) => console.error(`[daemon] reschedule failed: ${msg}`));
+    reschedule();
+    const configPath = vaultsJsonPath();
+    watchFile(configPath, { interval: 2000 }, reschedule);
+    const shutdown = () => {
+        unwatchFile(configPath);
+        git.stop();
+        couch.stop();
+        discover.stop();
+        server.stop().finally(() => {
+            state.cleanup();
+            process.exit(0);
+        });
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+};
+// Only self-invoke when run directly (spawnDaemon's `node daemon-entry.js`); importing for tests
+// must not boot a daemon.
+const invokedDirectly = () => {
+    const entry = process.argv[1];
+    return !!entry && fileURLToPath(import.meta.url) === entry;
+};
+if (invokedDirectly()) {
+    process.on('uncaughtException', (err) => {
+        console.error(`[daemon] uncaught: ${err instanceof Error ? err.message : String(err)}`);
+        state.cleanup();
+        process.exit(1);
+    });
+    main().catch((err) => {
+        if (isEaddrinuse(err)) {
+            // Another daemon owns the port + our state files: exit distinctly, touch nothing.
+            process.exit(EADDRINUSE_EXIT_CODE);
+        }
+        console.error(err instanceof Error ? err.message : String(err));
+        state.cleanup();
+        process.exit(1);
+    });
+}

package/dist/index.d.ts

@@ -1,2 +1 @@
 export { VERSION } from './utils/version.js';
-//# sourceMappingURL=index.d.ts.map

package/dist/index.js

@@ -1,2 +1 @@
 export { VERSION } from './utils/version.js';
-//# sourceMappingURL=index.js.map

package/dist/lib/auth/api.d.ts

@@ -0,0 +1,8 @@
+import { type AuthState } from '../fs/config.js';
+import { type Links } from '../net/origins.js';
+export { AuthRequiredError, TransientAuthError } from './auth-errors.js';
+export declare const refreshOrThrow: (auth: AuthState, links: Links) => Promise<void>;
+export declare const currentBearer: (readAuth: () => AuthState | null, links: Links) => Promise<string | null>;
+export declare const authedGet: <T>(auth: AuthState, links: Links, url: string) => Promise<T>;
+export declare const authedPost: (auth: AuthState, links: Links, url: string, body: unknown) => Promise<Response>;
+export { introspectToken, type TokenSession } from './introspect.js';

package/dist/lib/auth/api.js

@@ -0,0 +1,99 @@
+import { mutateAuth } from '../fs/config.js';
+import { refreshTokens, TokenRequestError } from './oauth.js';
+import { requestHeaders } from '../net/user-agent.js';
+import { AuthRequiredError, isTerminalRefresh, TransientAuthError } from './auth-errors.js';
+export { AuthRequiredError, TransientAuthError } from './auth-errors.js';
+// Every authed call is CLI-originated; identify the caller alongside the bearer.
+const cliHeaders = () => requestHeaders({ component: 'cli' });
+// Refresh the stored token in place. On success mutates auth + persists and returns. On failure it
+// throws: AuthRequiredError when the grant is dead (401/invalid_grant/invalid_client), else
+// TransientAuthError (429/5xx/network/timeout) - a blip that must not be read as a dead session.
+export const refreshOrThrow = async (auth, links) => {
+    if (auth.kind === 'pat')
+        throw new AuthRequiredError('personal access token expired or revoked - mint a new one in the dashboard (Settings -> API tokens)');
+    if (!auth.tokens.refreshToken)
+        throw new AuthRequiredError('no refresh token');
+    let fresh;
+    try {
+        fresh = await refreshTokens(links.auth, auth.clientId, auth.tokens.refreshToken);
+    }
+    catch (err) {
+        if (err instanceof TokenRequestError && isTerminalRefresh(err.status, err.oauthError))
+            throw new AuthRequiredError('session expired');
+        throw new TransientAuthError('refresh temporarily failed');
+    }
+    const tokens = {
+        accessToken: fresh.access_token,
+        refreshToken: fresh.refresh_token ?? auth.tokens.refreshToken,
+        expiresAt: fresh.expires_in ? Date.now() + fresh.expires_in * 1000 : undefined,
+    };
+    auth.tokens = tokens; // the caller retries its request with this in-memory copy
+    // Persist under the lock, folding the new tokens onto the freshly-read state so a concurrent
+    // writer's other fields (clientId, siteFqdn) are not clobbered by a stale in-memory copy.
+    await mutateAuth((current) => {
+        const base = current ?? auth;
+        base.tokens = tokens;
+        return base;
+    });
+};
+// Boolean shim for the request paths that just want "refresh once, then retry": any failure
+// (terminal or transient) collapses to false so they fall through to their own status handling.
+const tryRefresh = async (auth, links) => {
+    try {
+        await refreshOrThrow(auth, links);
+        return true;
+    }
+    catch {
+        return false;
+    }
+};
+// The current OAuth bearer for background (couch) sync. Reads auth.json fresh on every call - the
+// user may sign in or out between ticks - and refreshes once when the stored token is past its
+// stated expiry. Returns null when signed out so a caller pauses with zero network, never throws.
+export const currentBearer = async (readAuth, links) => {
+    const auth = readAuth();
+    if (!auth?.tokens.accessToken)
+        return null;
+    const expired = auth.tokens.expiresAt !== undefined && auth.tokens.expiresAt <= Date.now();
+    if (expired && !(await tryRefresh(auth, links)))
+        return null;
+    return auth.tokens.accessToken;
+};
+// redirect: 'manual' so the bearer is never replayed to a redirect target; any 3xx is an error.
+const isRedirect = (res) => res.type === 'opaqueredirect' || (res.status >= 300 && res.status < 400);
+export const authedGet = async (auth, links, url) => {
+    const call = () => fetch(url, {
+        headers: { authorization: `Bearer ${auth.tokens.accessToken}`, ...cliHeaders() },
+        redirect: 'manual',
+    });
+    let res = await call();
+    if (res.status === 401 && (await tryRefresh(auth, links)))
+        res = await call();
+    if (res.status === 401)
+        throw new AuthRequiredError('session expired');
+    if (isRedirect(res))
+        throw new Error(`GET ${url} refused redirect (${res.status})`);
+    if (!res.ok)
+        throw new Error(`GET ${url} failed (${res.status})`);
+    return (await res.json());
+};
+// A bearer POST with the same refresh-once dance as authedGet. Unlike authedGet it returns the
+// raw Response (never throws on a non-2xx): callers branch on the status codes themselves.
+export const authedPost = async (auth, links, url, body) => {
+    const call = () => fetch(url, {
+        method: 'POST',
+        headers: {
+            authorization: `Bearer ${auth.tokens.accessToken}`,
+            'content-type': 'application/json',
+            ...cliHeaders(),
+        },
+        body: JSON.stringify(body),
+        redirect: 'manual',
+    });
+    let res = await call();
+    if (res.status === 401 && (await tryRefresh(auth, links)))
+        res = await call();
+    return res;
+};
+// Re-export the introspection surface so existing callers keep importing from './api.js'.
+export { introspectToken } from './introspect.js';

package/dist/lib/auth/auth-errors.d.ts

@@ -0,0 +1,7 @@
+export declare class AuthRequiredError extends Error {
+    constructor(message?: string);
+}
+export declare class TransientAuthError extends Error {
+    constructor(message?: string);
+}
+export declare const isTerminalRefresh: (status: number, oauthError?: string) => boolean;

package/dist/lib/auth/auth-errors.js

@@ -0,0 +1,22 @@
+// Auth failures split two ways: TERMINAL means the session truly needs re-auth (401,
+// invalid_grant/invalid_client on the refresh grant); TRANSIENT means a blip we must not report as
+// expired (429, 5xx, network, timeout, unexpected redirect). Mirrors web#219's get-session taxonomy.
+// The session is genuinely gone: user must sign in again.
+export class AuthRequiredError extends Error {
+    constructor(message = 'not signed in') {
+        super(message);
+        this.name = 'AuthRequiredError';
+    }
+}
+// A temporary failure (rate limit / server hiccup / network) - the session may still be valid.
+export class TransientAuthError extends Error {
+    constructor(message = 'could not verify session') {
+        super(message);
+        this.name = 'TransientAuthError';
+    }
+}
+// OAuth token-endpoint error codes that mean the refresh grant is dead, not merely throttled.
+const TERMINAL_GRANT_ERRORS = new Set(['invalid_grant', 'invalid_client']);
+// Classify a failed refresh POST: 401 or an explicit invalid_grant/invalid_client is terminal;
+// everything else (429, 5xx, network, redirect, unknown) is transient.
+export const isTerminalRefresh = (status, oauthError) => status === 401 || (oauthError !== undefined && TERMINAL_GRANT_ERRORS.has(oauthError));

package/dist/lib/{callback-server.d.ts → auth/callback-server.d.ts}

@@ -4,4 +4,3 @@ export interface CallbackServer {
     close: () => void;
 }
 export declare const startCallbackServer: (expectedState: string) => Promise<CallbackServer>;
-//# sourceMappingURL=callback-server.d.ts.map

package/dist/lib/{callback-server.js → auth/callback-server.js}

@@ -39,7 +39,8 @@ export const startCallbackServer = (expectedState) => new Promise((resolveServer
             .end(page(true, 'You can return to the terminal.'));
         finish(code);
     });
-    server.listen(0, () => {
+    // Bind loopback only so the one-shot sign-in callback is never LAN-reachable.
+    server.listen(0, '127.0.0.1', () => {
         const address = server.address();
         const port = typeof address === 'object' && address ? address.port : 0;
         resolveServer({
@@ -69,4 +70,3 @@ export const startCallbackServer = (expectedState) => new Promise((resolveServer
         });
     });
 });
-//# sourceMappingURL=callback-server.js.map