@atomic-chat/core 0.5.1

package/dist/server/control/routes/telemetry.js

@@ -0,0 +1,46 @@
+/** The app's error-reporting consent, anonymous user and hardware tags (`set_telemetry_*` in the app). */
+import { AtomicCoreError } from '../../../contracts/index.js';
+import { readJsonBody, sendError, sendJson } from '../../http.js';
+/** What a core whose host turned reporting off (`telemetry: false`) says, whatever it is asked. */
+const NOT_REPORTING = {
+    enabled: false,
+    reporting: false,
+    has_user: false,
+    tags: {},
+    source: 'host',
+    host: 'library',
+};
+/** The body of `PUT /telemetry`, or a message saying what is wrong with it. */
+export function parseTelemetryUpdate(body) {
+    if (!body || typeof body !== 'object' || Array.isArray(body))
+        return 'telemetry needs a JSON object';
+    const { enabled, user_id: userId, tags } = body;
+    if (enabled !== undefined && typeof enabled !== 'boolean')
+        return '"enabled" must be true or false';
+    if (userId !== undefined && userId !== null && typeof userId !== 'string')
+        return '"user_id" must be a string or null';
+    if (tags !== undefined &&
+        (!tags ||
+            typeof tags !== 'object' ||
+            Array.isArray(tags) ||
+            Object.values(tags).some((value) => typeof value !== 'string')))
+        return '"tags" must map names to strings';
+    return {
+        ...(enabled !== undefined ? { enabled } : {}),
+        ...(userId !== undefined ? { user_id: userId } : {}),
+        ...(tags !== undefined ? { tags: tags } : {}),
+    };
+}
+export function registerTelemetryRoutes(router, deps, ctx) {
+    const { p } = ctx;
+    const state = () => deps.telemetry?.state() ?? NOT_REPORTING;
+    router.get(p('/telemetry'), (_req, res) => sendJson(res, 200, state()));
+    router.put(p('/telemetry'), async (req, res) => {
+        const update = parseTelemetryUpdate(await readJsonBody(req));
+        if (typeof update === 'string')
+            return sendError(res, new AtomicCoreError('INVALID_ARGUMENT', update));
+        deps.telemetry?.update(update);
+        sendJson(res, 200, state());
+    });
+}
+//# sourceMappingURL=telemetry.js.map

package/dist/server/control/routes/telemetry.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"telemetry.js","sourceRoot":"","sources":["../../../../src/server/control/routes/telemetry.ts"],"names":[],"mappings":"AAAA,0GAA0G;AAE1G,OAAO,EAAE,eAAe,EAAE,MAAM,6BAA6B,CAAA;AAE7D,OAAO,EAAE,YAAY,EAAE,SAAS,EAAE,QAAQ,EAAE,MAAM,eAAe,CAAA;AAIjE,mGAAmG;AACnG,MAAM,aAAa,GAAmB;IACpC,OAAO,EAAE,KAAK;IACd,SAAS,EAAE,KAAK;IAChB,QAAQ,EAAE,KAAK;IACf,IAAI,EAAE,EAAE;IACR,MAAM,EAAE,MAAM;IACd,IAAI,EAAE,SAAS;CAChB,CAAA;AAED,+EAA+E;AAC/E,MAAM,UAAU,oBAAoB,CAAC,IAAa;IAChD,IAAI,CAAC,IAAI,IAAI,OAAO,IAAI,KAAK,QAAQ,IAAI,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;QAAE,OAAO,+BAA+B,CAAA;IACpG,MAAM,EAAE,OAAO,EAAE,OAAO,EAAE,MAAM,EAAE,IAAI,EAAE,GAAG,IAA+B,CAAA;IAC1E,IAAI,OAAO,KAAK,SAAS,IAAI,OAAO,OAAO,KAAK,SAAS;QAAE,OAAO,iCAAiC,CAAA;IACnG,IAAI,MAAM,KAAK,SAAS,IAAI,MAAM,KAAK,IAAI,IAAI,OAAO,MAAM,KAAK,QAAQ;QACvE,OAAO,oCAAoC,CAAA;IAC7C,IACE,IAAI,KAAK,SAAS;QAClB,CAAC,CAAC,IAAI;YACJ,OAAO,IAAI,KAAK,QAAQ;YACxB,KAAK,CAAC,OAAO,CAAC,IAAI,CAAC;YACnB,MAAM,CAAC,MAAM,CAAC,IAAI,CAAC,CAAC,IAAI,CAAC,CAAC,KAAK,EAAE,EAAE,CAAC,OAAO,KAAK,KAAK,QAAQ,CAAC,CAAC;QAEjE,OAAO,kCAAkC,CAAA;IAC3C,OAAO;QACL,GAAG,CAAC,OAAO,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QAC7C,GAAG,CAAC,MAAM,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,OAAO,EAAE,MAAM,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;QACpD,GAAG,CAAC,IAAI,KAAK,SAAS,CAAC,CAAC,CAAC,EAAE,IAAI,EAAE,IAA8B,EAAE,CAAC,CAAC,CAAC,EAAE,CAAC;KACxE,CAAA;AACH,CAAC;AAED,MAAM,UAAU,uBAAuB,CACrC,MAAc,EACd,IAAuB,EACvB,GAAwB;IAExB,MAAM,EAAE,CAAC,EAAE,GAAG,GAAG,CAAA;IACjB,MAAM,KAAK,GAAG,GAAG,EAAE,CAAC,IAAI,CAAC,SAAS,EAAE,KAAK,EAAE,IAAI,aAAa,CAAA;IAE5D,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,CAAC,IAAI,EAAE,GAAG,EAAE,EAAE,CAAC,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAC,CAAA;IAEvE,MAAM,CAAC,GAAG,CAAC,CAAC,CAAC,YAAY,CAAC,EAAE,KAAK,EAAE,GAAG,EAAE,GAAG,EAAE,EAAE;QAC7C,MAAM,MAAM,GAAG,oBAAoB,CAAC,MAAM,YAAY,CAAC,GAAG,CAAC,CAAC,CAAA;QAC5D,IAAI,OAAO,MAAM,KAAK,QAAQ;YAAE,OAAO,SAAS,CAAC,GAAG,EAAE,IAAI,eAAe,CAAC,kBAAkB,EAAE,MAAM,CAAC,CAAC,CAAA;QACtG,IAAI,CAAC,SAAS,EAAE,MAAM,CAAC,MAAM,CAAC,CAAA;QAC9B,QAAQ,CAAC,GAAG,EAAE,GAAG,EAAE,KAAK,EAAE,CAAC,CAAA;IAC7B,CAAC,CAAC,CAAA;AACJ,CAAC"}

package/dist/server/control/server.d.ts

@@ -0,0 +1,26 @@
+/**
+ * The control listener: binds loopback, gates every request (loopback peer, loopback `Host`, control
+ * token), dispatches through the router, and fans core events out to attached SSE clients.
+ */
+import type { ServerResponse } from 'node:http';
+import type { ControlServerDeps } from './types.js';
+export declare class ControlServer {
+    private readonly server;
+    private readonly deps;
+    readonly host: string;
+    readonly port: number;
+    private readonly detachEmitter;
+    private readonly sseClients;
+    private heartbeat;
+    private constructor();
+    get url(): string;
+    static start(deps: ControlServerDeps, options?: {
+        host?: string;
+        port?: number;
+    }): Promise<ControlServer>;
+    private broadcast;
+    private ping;
+    /** Registered by the events route; kept private to the module through the holder. */
+    attachSse(res: ServerResponse): void;
+    close(): Promise<void>;
+}

package/dist/server/control/server.js

@@ -0,0 +1,111 @@
+/**
+ * The control listener: binds loopback, gates every request (loopback peer, loopback `Host`, control
+ * token), dispatches through the router, and fans core events out to attached SSE clients.
+ */
+import { createServer } from 'node:http';
+import { AtomicCoreError } from '../../contracts/index.js';
+import { bearerToken, controlTokenMatches } from '../../lock/index.js';
+import { captureReport, internalErrorReport } from '../../telemetry/index.js';
+import { hostHeaderIsLoopback, isLoopbackAddress, pathOf, sendError, statusForCode, toCoreError, } from '../http.js';
+import { buildRouter } from './router.js';
+import { sseFrame } from './routes/lifecycle.js';
+import { SSE_HEARTBEAT_MS } from './types.js';
+export class ControlServer {
+    server;
+    deps;
+    host;
+    port;
+    detachEmitter;
+    sseClients = new Set();
+    heartbeat;
+    constructor(server, deps, host, port, detachEmitter) {
+        this.server = server;
+        this.deps = deps;
+        this.host = host;
+        this.port = port;
+        this.detachEmitter = detachEmitter;
+    }
+    get url() {
+        return `http://${this.host}:${this.port}`;
+    }
+    static async start(deps, options = {}) {
+        const host = options.host ?? '127.0.0.1';
+        // The events route needs the instance that is being constructed, so it reads it through a holder.
+        const holder = {};
+        const router = buildRouter(deps, () => holder.instance);
+        const server = createServer((req, res) => {
+            void handle(req, res, router, deps).catch((e) => sendError(res, e));
+        });
+        // A control connection must never keep the process alive on its own; shutdown is explicit.
+        server.on('connection', (socket) => socket.unref?.());
+        await new Promise((resolve, reject) => {
+            server.once('error', reject);
+            server.listen(options.port ?? 0, host, () => {
+                server.off('error', reject);
+                resolve();
+            });
+        });
+        const address = server.address();
+        const port = typeof address === 'object' && address ? address.port : 0;
+        const detach = deps.emitter.onAny((record) => holder.instance?.broadcast(record));
+        const instance = new ControlServer(server, deps, host, port, detach);
+        holder.instance = instance;
+        instance.heartbeat = setInterval(() => instance.ping(), SSE_HEARTBEAT_MS);
+        instance.heartbeat.unref?.();
+        return instance;
+    }
+    broadcast(record) {
+        const frame = sseFrame(this.deps.emitter.cursor(record.seq), record.name, record.payload);
+        for (const res of this.sseClients)
+            res.write(frame);
+    }
+    ping() {
+        for (const res of this.sseClients)
+            res.write(': ping\n\n');
+    }
+    /** Registered by the events route; kept private to the module through the holder. */
+    attachSse(res) {
+        this.sseClients.add(res);
+        res.on('close', () => this.sseClients.delete(res));
+    }
+    async close() {
+        if (this.heartbeat)
+            clearInterval(this.heartbeat);
+        this.detachEmitter();
+        for (const res of this.sseClients)
+            res.end();
+        this.sseClients.clear();
+        this.server.closeAllConnections?.();
+        await new Promise((resolve) => this.server.close(() => resolve()));
+    }
+}
+async function handle(req, res, router, deps) {
+    if (!isLoopbackAddress(req.socket.remoteAddress)) {
+        return sendError(res, new AtomicCoreError('FORBIDDEN_HOST', 'The control API answers only on loopback.', req.socket.remoteAddress ?? ''));
+    }
+    if (!hostHeaderIsLoopback(req.headers.host)) {
+        return sendError(res, new AtomicCoreError('FORBIDDEN_HOST', 'Unexpected Host header on the control API.', req.headers.host ?? ''));
+    }
+    if (!controlTokenMatches(bearerToken(req.headers.authorization), deps.token)) {
+        return sendError(res, new AtomicCoreError('UNAUTHORIZED', 'A valid control token is required.'));
+    }
+    const path = pathOf(req);
+    const found = router.find(req.method ?? 'GET', path);
+    if (!found) {
+        return sendError(res, new AtomicCoreError('INVALID_ARGUMENT', `No such control route: ${path}`), 404);
+    }
+    if ('methodMismatch' in found) {
+        return sendError(res, new AtomicCoreError('INVALID_ARGUMENT', `${req.method} is not allowed on ${path}`), 405);
+    }
+    try {
+        await found.route.handler(req, res, found.match);
+    }
+    catch (error) {
+        // Reported here, where the route's pattern is known; the path itself may name a model or a file.
+        const status = statusForCode(toCoreError(error).code);
+        const route = `${found.route.method} ${found.route.pattern}`;
+        captureReport(deps.telemetry, internalErrorReport({ source: 'control_route', error, status, route }));
+        throw error;
+    }
+}
+//# sourceMappingURL=server.js.map

package/dist/server/control/server.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"server.js","sourceRoot":"","sources":["../../../src/server/control/server.ts"],"names":[],"mappings":"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"}

package/dist/server/control/types.d.ts

@@ -0,0 +1,271 @@
+/**
+ * The control API's dependency surface: what the owner injects into the control server, and the
+ * snapshot shape it answers with. Types and shared constants only.
+ */
+import type { CloudProviderInput, CloudProviderView, SubscriptionModel } from '../../cloud/index.js';
+import type { ChatGptStatus } from '../../credentials/index.js';
+import type { DeviceInfo, DiffusionBackendInstallRecord, DiffusionCancelResult, DiffusionConfig, DiffusionModelFile, DiffusionStatus, FinalizeBackendInstallArgs, GalleryFlags, GalleryImageItem, GalleryListOptions, GalleryPage, ImageCapabilities, ImageGenerateRequest, ImageJob, LoadDiffusionModelRequest, LoadedDiffusionModel, VideoCapabilities, VideoGalleryPage, VideoGenerateRequest, VideoJob, GalleryVideoItem, LocalApiServerState, LocalProviderId, RemoteAccessStatus, SessionInfo, UnloadResult } from '../../contracts/index.js';
+import type { CoreEmitter } from '../../events/index.js';
+import type { CtxIncreaseResult } from '../../runtime/llamacpp/runtime.js';
+import type { GgufValidation, ModelCapabilities } from '../../models/index.js';
+import type { EmbeddingResponse } from '../../models/index.js';
+import type { ProxyConfig } from '../../downloads/index.js';
+import type { HardwareOverrideStore } from '../../hardware/index.js';
+import type { TelemetryControl } from '../../telemetry/index.js';
+import type { InstallBackendResult, InstalledBackendPack, OptimalBackendCacheRecord } from '../../backend/index.js';
+import type { OptimalState, OptimalUpdate } from '../../backend/index.js';
+import type { ImportOptions, ImportResult, MigrationRecord, ProviderValues, UpdateResult } from '../../settings/index.js';
+import type { ClientRegistry } from '../clients.js';
+import type { ControlServer } from './server.js';
+export declare const SSE_HEARTBEAT_MS = 15000;
+export interface SessionSummary extends SessionInfo {
+    provider: LocalProviderId;
+}
+export interface PublicServerControl {
+    status: () => LocalApiServerState;
+    start: (options: {
+        host?: string;
+        port?: number;
+        prefix?: string;
+        apiKey?: string;
+        trustedHosts?: string[];
+        proxyTimeoutSecs?: number;
+        writeStateFile?: boolean;
+        fallbackPort?: boolean;
+    }) => Promise<LocalApiServerState>;
+    stop: () => Promise<LocalApiServerState>;
+    /**
+     * Whether the app's API screen is watching the public server. Previews of prompts and replies are
+     * collected only while it is (ATO-113). Survives a server restart, like the app's own inspector.
+     */
+    setInspecting: (enabled: boolean) => void;
+}
+/**
+ * The settings surface the control API exposes. Narrower than `SettingsStore` on purpose: the app
+ * reads a provider's values, patches them with a revision, and migrates its own copy across — it has
+ * no business writing the migration bookkeeping directly.
+ */
+export interface SettingsControl {
+    get: (provider: LocalProviderId) => ProviderValues;
+    revision: () => number;
+    migration: (scope: string) => MigrationRecord | null;
+    update: (provider: LocalProviderId, patch: ProviderValues, options: {
+        expectedRevision?: number;
+    }) => Promise<UpdateResult>;
+    importProvider: (provider: LocalProviderId, values: ProviderValues, options: ImportOptions) => Promise<ImportResult>;
+    acknowledge: (scope: string, revision: number) => Promise<UpdateResult>;
+}
+/**
+ * The backend surface the app drives. Narrow on purpose: the updater screen installs, removes and
+ * lists, and everything else it shows it computes from those three answers.
+ */
+export interface BackendControl {
+    list: (provider: string, currentVersionBackend?: string) => Promise<InstalledBackendPack[]>;
+    install: (provider: string, version: string, backend: string, options: {
+        taskId: string;
+        force?: boolean;
+        proxy?: ProxyConfig | null;
+        assetName?: string;
+    }) => Promise<InstallBackendResult>;
+    remove: (provider: string, version: string, backend: string) => Promise<boolean>;
+    cancel: (taskId: string) => boolean;
+    getOptimal: (provider: string) => Promise<OptimalState>;
+    setOptimal: (provider: string, record: OptimalBackendCacheRecord | null, expectedRevision: number) => Promise<OptimalUpdate>;
+    optimalSnapshot: () => Record<string, OptimalState>;
+}
+/**
+ * The questions the app asks about models it has not loaded. Each answers rather than throws: the
+ * caller is usually deciding what to show in a list, and one unreadable file must not empty it.
+ */
+export interface ModelControl {
+    capabilities: (provider: string, modelId: string) => Promise<ModelCapabilities>;
+    validateGguf: (path: string) => Promise<GgufValidation>;
+    /** Devices the installed backend reports, which needs a backend to ask. */
+    devices: (provider: string) => Promise<DeviceInfo[]>;
+    embed: (provider: string, modelId: string, input: string[], ubatchSize: number) => Promise<EmbeddingResponse>;
+}
+/** Room left for a download. Answers for the data folder only; `null` when the platform cannot say. */
+export interface DiskControl {
+    available: (path: unknown) => Promise<number | null>;
+}
+/** Reaching the public listener from outside this machine (stage 7c–7d). */
+export interface RemoteAccessControl {
+    /** IPv4 literals a device on the network can dial, default-route address first. Display only. */
+    lanAddresses: () => Promise<string[]>;
+    status: () => RemoteAccessStatus;
+    /** Answers `starting` at once; throws a `REMOTE_ACCESS_*` refusal with the app's reason in `details`. */
+    start: () => RemoteAccessStatus;
+    /** Answers once the tunnel's process is gone. */
+    stop: () => Promise<RemoteAccessStatus>;
+}
+/**
+ * Image generation (stage 7h): the app's twenty `DiffusionService` operations, one route each. The
+ * routes parse and validate the bodies; what arrives here is already typed.
+ */
+export interface DiffusionControl {
+    configure: (config: DiffusionConfig) => Promise<DiffusionStatus>;
+    getStatus: () => Promise<DiffusionStatus>;
+    setOutputDir: (path: string) => Promise<DiffusionStatus>;
+    finalizeBackendInstall: (args: FinalizeBackendInstallArgs) => Promise<DiffusionBackendInstallRecord>;
+    listInstalledBackends: () => Promise<DiffusionBackendInstallRecord[]>;
+    removeBackend: (dir: string) => Promise<void>;
+    listModelFiles: () => Promise<DiffusionModelFile[]>;
+    deleteModelFile: (path: string) => Promise<void>;
+    /** Answers once the server serves the model, which can take minutes. */
+    loadModel: (request: LoadDiffusionModelRequest) => Promise<LoadedDiffusionModel>;
+    unloadModel: () => Promise<void>;
+    getCapabilities: () => ImageCapabilities;
+    touchIdle: () => void;
+    generate: (request: ImageGenerateRequest) => Promise<{
+        jobId: string;
+    }>;
+    getJob: (jobId: string) => ImageJob | null;
+    cancelJob: (jobId: string) => Promise<DiffusionCancelResult>;
+    listGallery: (options: GalleryListOptions) => Promise<GalleryPage>;
+    getGalleryItem: (id: string) => Promise<GalleryImageItem | null>;
+    deleteGalleryItems: (ids: string[]) => Promise<void>;
+    setGalleryFlags: (id: string, flags: GalleryFlags) => Promise<GalleryImageItem>;
+    exportGalleryItem: (id: string, targetPath: string) => Promise<void>;
+    getVideoCapabilities: () => VideoCapabilities;
+    generateVideo: (request: VideoGenerateRequest) => Promise<{
+        jobId: string;
+    }>;
+    getVideoJob: (jobId: string) => VideoJob | null;
+    cancelVideoJob: (jobId: string) => Promise<DiffusionCancelResult>;
+    listVideoGallery: (options: GalleryListOptions) => Promise<VideoGalleryPage>;
+    getVideoGalleryItem: (id: string) => Promise<GalleryVideoItem | null>;
+    deleteVideoGalleryItems: (ids: string[]) => Promise<void>;
+    setVideoGalleryFlags: (id: string, flags: GalleryFlags) => Promise<GalleryVideoItem>;
+    exportVideoGalleryItem: (id: string, targetPath: string) => Promise<void>;
+    /** The poster the app rendered from the clip's first frame; the bare base64 of a PNG. */
+    setVideoPoster: (id: string, pngBase64: string) => Promise<GalleryVideoItem>;
+}
+/** Engines another process owns, registered so the public server can route to them (stage 4d). */
+export interface ExternalSessionControl {
+    publish: (owner: string, generation: number, sessions: unknown) => {
+        generation: number;
+        sessions: number;
+    };
+    heartbeat: (owner: string, generation: number) => {
+        alive: boolean;
+    };
+    unregister: (owner: string, generation?: number) => boolean;
+    list: () => unknown[];
+    answerCtx: (owner: string, requestId: string, outcome: unknown) => boolean;
+}
+/** Cloud providers the public server routes to (PLAN.md §4, stage 4c). Keys are never read back. */
+export interface CloudControl {
+    list: () => CloudProviderView[];
+    upsert: (input: CloudProviderInput) => Promise<CloudProviderView>;
+    remove: (provider: string) => Promise<void>;
+}
+/** The ChatGPT subscription session. Nothing here ever returns a token. */
+export interface ChatGptControl {
+    status: () => Promise<ChatGptStatus>;
+    reload?: () => Promise<ChatGptStatus>;
+    startLogin: () => Promise<{
+        authorize_url: string;
+    }>;
+    waitLogin: () => Promise<ChatGptStatus>;
+    cancelLogin: () => void;
+    logout: () => Promise<ChatGptStatus>;
+    models: () => Promise<SubscriptionModel[]>;
+}
+export interface ControlServerDeps {
+    token: string;
+    instanceId: string;
+    version: string;
+    ownerScope?: 'app' | 'cli';
+    dataFolder: string;
+    emitter: CoreEmitter;
+    clients: ClientRegistry;
+    sessions: () => SessionSummary[];
+    loadModel: (provider: string, modelId: string, body: Record<string, unknown>) => Promise<SessionInfo | {
+        session: SessionInfo;
+        created: boolean;
+    }>;
+    /**
+     * Cancel a load that has not answered yet. Answers rather than throws when there is nothing to
+     * cancel: the app retries while its load request is still travelling, and unloads once it lands.
+     */
+    cancelModelLoad: (provider: string, modelId: string) => boolean;
+    unloadModel: (provider: string, modelId: string) => Promise<UnloadResult>;
+    /**
+     * Reload a model one context step larger because a request overflowed. Answers rather than
+     * throws when it declines: "the ladder is at its top" is an outcome the caller acts on, not an
+     * error, and the proxy has to tell it apart from a failed reload.
+     */
+    increaseCtx: (provider: string, modelId: string, reason?: string) => Promise<CtxIncreaseResult>;
+    /**
+     * Restart a model at the context it already has, because its engine is poisoned (a compute
+     * failure). The app's extension asks for this when the core owns the runtime but the app's own
+     * proxy saw the failure.
+     */
+    recreateSession: (provider: string, modelId: string) => Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    publicServer: PublicServerControl;
+    /** The settings store, for the routes that read and migrate provider settings (PLAN.md §3.4). */
+    settings: SettingsControl;
+    /** Hardware facts the app injects, which outrank the core's own probe (PLAN.md §2 decision 10). */
+    hardware: HardwareOverrideStore;
+    /** Installing and removing llama.cpp backends (PLAN.md §4, stage 3c). */
+    backends: BackendControl;
+    /** Free space inside the data folder, which the app asks before a download (stage 7b). */
+    disk: DiskControl;
+    remoteAccess: RemoteAccessControl;
+    diffusion: DiffusionControl;
+    /** What a model is and can do, without loading it (PLAN.md §4, stage 3d). */
+    models: ModelControl;
+    /**
+     * Whether Apple's on-device model can run here: the server's own `--check` token (`available`,
+     * `notEligible`, `appleIntelligenceNotEnabled`, `modelNotReady`, `unavailable`, `binaryNotFound`).
+     * Answers `unavailable` on a platform without the runtime.
+     */
+    foundationModelsAvailability?: (force: boolean) => Promise<string>;
+    cloud: CloudControl;
+    chatgpt: ChatGptControl;
+    externalSessions: ExternalSessionControl;
+    /** Stop the whole core. The server has already answered by the time this runs. */
+    shutdown: (options: {
+        force: boolean;
+        requestedBy?: string | undefined;
+    }) => Promise<void>;
+    /**
+     * Error reporting: where a route that failed on our side is reported, and the app's consent,
+     * user and tags behind `/telemetry`. Absent in a CLI owner, which reports nothing.
+     */
+    telemetry?: TelemetryControl;
+    startedAt?: number;
+    now?: () => number;
+}
+export interface ControlSnapshot {
+    instance_id: string;
+    owner_scope?: 'app' | 'cli' | undefined;
+    protocol: number;
+    version: string;
+    pid: number;
+    data_folder: string;
+    started_at: number;
+    uptime_ms: number;
+    cursor: string;
+    sessions: SessionSummary[];
+    server: LocalApiServerState;
+    clients: ReturnType<ClientRegistry['list']>;
+    downloads: unknown[];
+    optimal_backends: Record<string, OptimalState>;
+}
+/**
+ * What every route family shares, built once per router: the prefixed path helper, the clock the
+ * uptime is measured with, the snapshot builder, and the server instance the events route attaches to.
+ * Internal to this module; not re-exported.
+ */
+export interface ControlRouteContext {
+    p: (suffix: string) => string;
+    now: () => number;
+    startedAt: number;
+    snapshot: () => ControlSnapshot;
+    /** The server being constructed; `undefined` until `ControlServer.start` has built it. */
+    self: () => ControlServer | undefined;
+}

package/dist/server/control/types.js

@@ -0,0 +1,6 @@
+/**
+ * The control API's dependency surface: what the owner injects into the control server, and the
+ * snapshot shape it answers with. Types and shared constants only.
+ */
+export const SSE_HEARTBEAT_MS = 15_000;
+//# sourceMappingURL=types.js.map

package/dist/server/control/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../../src/server/control/types.ts"],"names":[],"mappings":"AAAA;;;GAGG;AAuDH,MAAM,CAAC,MAAM,gBAAgB,GAAG,MAAM,CAAA"}

package/dist/server/http.d.ts

@@ -0,0 +1,62 @@
+/**
+ * The little bit of HTTP the core needs: a path router, JSON body reading with a cap, the shared
+ * error envelope `{error:{code,message,details?}}` that the app already parses, and the loopback
+ * checks the control listener relies on (PLAN.md §3.6).
+ *
+ * Deliberately not a framework: the control surface is a dozen routes, and a dependency here would
+ * have to be audited for the signed binary.
+ */
+import type { IncomingMessage, ServerResponse } from 'node:http';
+import { AtomicCoreError } from '../contracts/index.js';
+import type { ErrorCode } from '../contracts/index.js';
+export declare const MAX_JSON_BODY_BYTES: number;
+export interface RouteMatch {
+    params: Record<string, string>;
+}
+export type Handler = (req: IncomingMessage, res: ServerResponse, match: RouteMatch) => void | Promise<void>;
+export interface Route {
+    method: string;
+    /** `/atomic/v1/models/:provider/*rest/load` — `:name` matches one segment, `*name` the rest. */
+    pattern: string;
+    handler: Handler;
+}
+export declare class Router {
+    private readonly routes;
+    add(method: string, pattern: string, handler: Handler): this;
+    get(pattern: string, handler: Handler): this;
+    post(pattern: string, handler: Handler): this;
+    put(pattern: string, handler: Handler): this;
+    patch(pattern: string, handler: Handler): this;
+    delete(pattern: string, handler: Handler): this;
+    /** The matching route, or `undefined`; `methodMismatch` distinguishes 404 from 405. */
+    find(method: string, path: string): {
+        route: Route;
+        match: RouteMatch;
+    } | {
+        methodMismatch: true;
+    } | undefined;
+}
+export declare function sendJson(res: ServerResponse, status: number, body: unknown): void;
+/** HTTP status for a core error code. Anything unmapped is a 500: an unknown failure is not the caller's fault. */
+export declare function statusForCode(code: ErrorCode): number;
+export declare function toCoreError(error: unknown): AtomicCoreError;
+export declare function sendError(res: ServerResponse, error: unknown, status?: number): void;
+/**
+ * Past the limit the rest of the body is read and discarded, up to this many times the limit, before
+ * the refusal is written: Bun's `node:http` (1.3.10) delivers an answer written while the request
+ * body is still arriving as an empty 200, Node delivers the refusal either way (ADR
+ * 2026-09-22-detect-a-client-that-hangs-up-before-the-answer-under-bun). Beyond the ceiling the
+ * connection is dropped instead of read on.
+ */
+export declare const OVERSIZE_DRAIN_FACTOR = 8;
+export declare function readJsonBody<T = unknown>(req: IncomingMessage, limit?: number): Promise<T>;
+/** Peer address check: the control listener answers only to processes on this machine. */
+export declare function isLoopbackAddress(address: string | undefined | null): boolean;
+/**
+ * Host-header check, which is what stops a browser page from posting to the control port through
+ * DNS rebinding: the name must itself be loopback, not merely resolve to it today.
+ */
+export declare function hostHeaderIsLoopback(host: string | undefined | null): boolean;
+/** `?name=value` for a request path. */
+export declare function queryOf(req: IncomingMessage): URLSearchParams;
+export declare function pathOf(req: IncomingMessage): string;