@atomic-chat/core 0.5.1

package/dist/core/public-server.js

@@ -0,0 +1,143 @@
+/**
+ * The lifecycle of the public `/v1` listener owned by `AtomicCore`: start, stop and state, the option
+ * normalization that makes an identical start idempotent, and the published state files.
+ *
+ * It is a separate, optional listener whose stop must never take control down with it.
+ *
+ * It also keeps the remote-access tunnel honest about it: a public URL must never point at a port
+ * that has stopped, or at whatever binds that port next. So a stop ends the tunnel *first*, a
+ * genuine start ends any tunnel that survived (it pointed at the previous port), and a repeated
+ * start that changes nothing leaves the tunnel alone.
+ */
+import { writeFile } from 'node:fs/promises';
+import { AtomicCoreError } from '../contracts/index.js';
+import { DEFAULT_PROXY_TIMEOUT_SECS, DEFAULT_PUBLIC_HOST, DEFAULT_PUBLIC_PORT, DEFAULT_PUBLIC_PREFIX, PublicServer, markServerRunning, markServerStopped, normalizePrefix, stoppedState, } from '../server/index.js';
+import { dialOrigin } from '../remote-access/index.js';
+/** Owns the public listener and serializes its start/stop transitions. */
+export class PublicServerLifecycle {
+    deps;
+    publicServer;
+    lastPublicState = stoppedState();
+    publicConfig;
+    publicTransition = Promise.resolve();
+    stopping = false;
+    constructor(deps) {
+        this.deps = deps;
+    }
+    state() {
+        return this.publicServer ? this.publicServer.state() : { ...this.lastPublicState };
+    }
+    /**
+     * Where a tunnel would point: the *bound* port (a fallback can change it) and a host that really
+     * listens. `undefined` while there is no listener — and already while one is stopping, so nothing
+     * new is pointed at a port that is about to go.
+     */
+    endpoint() {
+        if (!this.publicServer || !this.publicConfig || this.stopping)
+            return undefined;
+        return {
+            origin: dialOrigin(this.publicServer.host, this.publicServer.port),
+            hasApiKey: this.publicConfig.apiKey !== '',
+        };
+    }
+    /** Start the public listener; an identical start is idempotent, an incompatible one is a conflict. */
+    start(options) {
+        return this.withPublicTransition(async () => {
+            this.deps.assertRunning();
+            const requested = normalizePublicOptions(options);
+            if (this.publicServer && this.publicConfig) {
+                if (publicOptionsCompatible(this.publicConfig, requested, options.port))
+                    return this.publicServer.state();
+                throw new AtomicCoreError('CORE_ALREADY_RUNNING', 'The public API server is already running with a different configuration.', `${this.publicServer.host}:${this.publicServer.port}${this.publicServer.prefix}`);
+            }
+            const server = await PublicServer.start(this.deps.serverDeps(), options).catch((e) => {
+                const error = e;
+                this.deps.events.emit('server:bind-failed', { port: options.port ?? 0, error: error.message });
+                throw error;
+            });
+            // A tunnel that survived until here pointed at the previous listener's port.
+            await this.deps.remoteAccess?.stop().catch(() => { });
+            this.publicServer = server;
+            this.publicConfig = { ...requested, port: server.port, requestedPort: requested.port };
+            this.lastPublicState = server.state();
+            await this.publishServerState(server.state());
+            if (requested.writeStateFile) {
+                await markServerRunning(this.deps.layout.serverStateFile, {
+                    host: server.host,
+                    port: server.port,
+                    prefix: server.prefix,
+                    requiresApiKey: requested.apiKey !== '',
+                }, (message) => this.deps.log('warn', message));
+            }
+            this.deps.events.emit('server:started', { host: server.host, port: server.port });
+            this.deps.log('info', `public API on ${server.url}`);
+            this.deps.remoteAccess?.announce();
+            return server.state();
+        });
+    }
+    /** Stop the listener after any transition in flight; a stopped listener reports its last state. */
+    stop() {
+        return this.withPublicTransition(() => this.stopPublicServerNow());
+    }
+    async stopPublicServerNow() {
+        if (!this.publicServer)
+            return this.state();
+        const wroteStateFile = this.publicConfig?.writeStateFile === true;
+        // The tunnel first: otherwise its public URL points at a dead port, or at whatever binds it next.
+        this.stopping = true;
+        try {
+            await this.deps.remoteAccess?.stop().catch(() => { });
+            this.lastPublicState = stoppedState(this.publicServer.state());
+            await this.publicServer.close();
+        }
+        finally {
+            this.stopping = false;
+        }
+        this.publicServer = undefined;
+        this.publicConfig = undefined;
+        await this.publishServerState(this.lastPublicState);
+        if (wroteStateFile)
+            await markServerStopped(this.deps.layout.serverStateFile, (message) => this.deps.log('warn', message));
+        this.deps.events.emit('server:stopped', {});
+        this.deps.remoteAccess?.announce();
+        return { ...this.lastPublicState };
+    }
+    /**
+     * Publish where the public API is, for clients that have no control token — `server status` and
+     * the app. This is the core's own copy; the app's `<data>/local-api-server.json` is written only
+     * when the app handed the server over (`writeStateFile`), so there is always one writer of it.
+     */
+    async publishServerState(state) {
+        await writeFile(this.deps.layout.core.publicServerState, `${JSON.stringify(state, null, 2)}\n`).catch((e) => this.deps.log('warn', `could not publish the public server state: ${e.message}`));
+    }
+    withPublicTransition(operation) {
+        const result = this.publicTransition.then(operation, operation);
+        this.publicTransition = result.then(() => { }, () => { });
+        return result;
+    }
+}
+function normalizePublicOptions(options) {
+    return {
+        host: options.host ?? DEFAULT_PUBLIC_HOST,
+        port: options.port ?? DEFAULT_PUBLIC_PORT,
+        prefix: normalizePrefix(options.prefix ?? DEFAULT_PUBLIC_PREFIX),
+        apiKey: options.apiKey ?? '',
+        trustedHosts: [...(options.trustedHosts ?? [])].sort(),
+        proxyTimeoutSecs: options.proxyTimeoutSecs ?? DEFAULT_PROXY_TIMEOUT_SECS,
+        writeStateFile: options.writeStateFile ?? false,
+        fallbackPort: options.fallbackPort ?? false,
+    };
+}
+function publicOptionsCompatible(current, requested, requestedPort) {
+    // A server that fell back to a free port still answers a repeat of the request that put it there.
+    const portMatches = requestedPort === 0 || current.port === requested.port || current.requestedPort === requested.port;
+    return (portMatches &&
+        current.host === requested.host &&
+        current.prefix === requested.prefix &&
+        current.apiKey === requested.apiKey &&
+        current.proxyTimeoutSecs === requested.proxyTimeoutSecs &&
+        current.writeStateFile === requested.writeStateFile &&
+        current.trustedHosts.length === requested.trustedHosts.length &&
+        current.trustedHosts.every((host, index) => host === requested.trustedHosts[index]));
+}
+//# sourceMappingURL=public-server.js.map

package/dist/core/public-server.js.map

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

package/dist/core/reap-orphans.d.ts

@@ -0,0 +1,7 @@
+import type { ProcessJournal } from '../lock/index.js';
+import type { CoreLogger } from './types.js';
+/**
+ * Terminate backend processes a previous owner left running. Only processes whose recorded start
+ * identity still matches are touched; anything unprovable is left alone and logged.
+ */
+export declare function reapOrphans(journal: ProcessJournal, instanceId: string, log: CoreLogger): Promise<void>;

package/dist/core/reap-orphans.js

@@ -0,0 +1,40 @@
+import { isProcessAlive, verifyProcessIdentity } from '../lock/index.js';
+/**
+ * Terminate backend processes a previous owner left running. Only processes whose recorded start
+ * identity still matches are touched; anything unprovable is left alone and logged.
+ */
+export async function reapOrphans(journal, instanceId, log) {
+    const scan = await journal.scanOrphans(instanceId, new Set());
+    for (const record of scan.confirmed) {
+        log('warn', `stopping orphaned backend pid ${record.pid} (${record.model_id}) from a previous core`);
+        await terminate(record);
+    }
+    await journal.forget([...scan.confirmed, ...scan.gone]);
+    for (const skipped of scan.skipped) {
+        if (skipped.reason === 'identity-unproven')
+            log('warn', `leaving pid ${skipped.record.pid} alone: cannot prove it is still our backend`);
+    }
+}
+async function terminate(record) {
+    const verdict = await verifyProcessIdentity(record.pid, record.process_start_id);
+    if (verdict !== 'match')
+        return;
+    try {
+        process.kill(record.pid, 'SIGTERM');
+    }
+    catch {
+        return;
+    }
+    const deadline = Date.now() + 5000;
+    while (isProcessAlive(record.pid) && Date.now() < deadline)
+        await new Promise((r) => setTimeout(r, 50));
+    if (isProcessAlive(record.pid)) {
+        try {
+            process.kill(record.pid, 'SIGKILL');
+        }
+        catch {
+            /* already gone */
+        }
+    }
+}
+//# sourceMappingURL=reap-orphans.js.map

package/dist/core/reap-orphans.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"reap-orphans.js","sourceRoot":"","sources":["../../src/core/reap-orphans.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,cAAc,EAAE,qBAAqB,EAAE,MAAM,kBAAkB,CAAA;AAIxE;;;GAGG;AACH,MAAM,CAAC,KAAK,UAAU,WAAW,CAC/B,OAAuB,EACvB,UAAkB,EAClB,GAAe;IAEf,MAAM,IAAI,GAAG,MAAM,OAAO,CAAC,WAAW,CAAC,UAAU,EAAE,IAAI,GAAG,EAAE,CAAC,CAAA;IAC7D,KAAK,MAAM,MAAM,IAAI,IAAI,CAAC,SAAS,EAAE,CAAC;QACpC,GAAG,CAAC,MAAM,EAAE,iCAAiC,MAAM,CAAC,GAAG,KAAK,MAAM,CAAC,QAAQ,wBAAwB,CAAC,CAAA;QACpG,MAAM,SAAS,CAAC,MAAM,CAAC,CAAA;IACzB,CAAC;IACD,MAAM,OAAO,CAAC,MAAM,CAAC,CAAC,GAAG,IAAI,CAAC,SAAS,EAAE,GAAG,IAAI,CAAC,IAAI,CAAC,CAAC,CAAA;IACvD,KAAK,MAAM,OAAO,IAAI,IAAI,CAAC,OAAO,EAAE,CAAC;QACnC,IAAI,OAAO,CAAC,MAAM,KAAK,mBAAmB;YACxC,GAAG,CAAC,MAAM,EAAE,eAAe,OAAO,CAAC,MAAM,CAAC,GAAG,8CAA8C,CAAC,CAAA;IAChG,CAAC;AACH,CAAC;AAED,KAAK,UAAU,SAAS,CAAC,MAA0B;IACjD,MAAM,OAAO,GAAG,MAAM,qBAAqB,CAAC,MAAM,CAAC,GAAG,EAAE,MAAM,CAAC,gBAAgB,CAAC,CAAA;IAChF,IAAI,OAAO,KAAK,OAAO;QAAE,OAAM;IAC/B,IAAI,CAAC;QACH,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;IACrC,CAAC;IAAC,MAAM,CAAC;QACP,OAAM;IACR,CAAC;IACD,MAAM,QAAQ,GAAG,IAAI,CAAC,GAAG,EAAE,GAAG,IAAI,CAAA;IAClC,OAAO,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,IAAI,IAAI,CAAC,GAAG,EAAE,GAAG,QAAQ;QAAE,MAAM,IAAI,OAAO,CAAC,CAAC,CAAC,EAAE,EAAE,CAAC,UAAU,CAAC,CAAC,EAAE,EAAE,CAAC,CAAC,CAAA;IACvG,IAAI,cAAc,CAAC,MAAM,CAAC,GAAG,CAAC,EAAE,CAAC;QAC/B,IAAI,CAAC;YACH,OAAO,CAAC,IAAI,CAAC,MAAM,CAAC,GAAG,EAAE,SAAS,CAAC,CAAA;QACrC,CAAC;QAAC,MAAM,CAAC;YACP,kBAAkB;QACpB,CAAC;IACH,CAAC;AACH,CAAC"}

package/dist/core/sessions.d.ts

@@ -0,0 +1,60 @@
+/**
+ * Local model sessions as `AtomicCore` owns them: the cross-process model claim taken before a load,
+ * per-model serialization of load/unload, cancelling a load that has not answered yet, and how the
+ * public server finds a session — one this core runs or one the desktop app registered as external.
+ */
+import { AtomicCoreError } from '../contracts/index.js';
+import type { LocalProviderId, SessionInfo, UnloadResult } from '../contracts/index.js';
+import type { DataLayout } from '../config/index.js';
+import type { CtxIncreaseResult, ExternalSessions, LocalRuntime, RecreateResult } from '../runtime/index.js';
+import type { CtxIncreaseOutcome, LocalTarget, SessionSummary } from '../server/index.js';
+import type { LocalProvider } from '../router/index.js';
+import type { CoreLoadOptions } from './types.js';
+export interface LocalSessionsDeps {
+    layout: DataLayout;
+    instanceId: string;
+    runtimes: Map<LocalProviderId, LocalRuntime>;
+    externalSessions: ExternalSessions;
+    /** The runtime for a provider; throws `PROVIDER_NOT_FOUND` for one this core does not offer. */
+    runtime: (provider: LocalProviderId) => LocalRuntime;
+    /** Throws once the owning core is stopping; checked again inside the serialized transition. */
+    assertRunning: () => void;
+    increaseCtx: (provider: LocalProviderId, modelId: string, reason?: string) => Promise<CtxIncreaseResult>;
+    recreateSession: (provider: LocalProviderId, modelId: string) => Promise<RecreateResult>;
+}
+/** Model claims and per-model transitions for the sessions this core loads. */
+export declare class LocalSessions {
+    private readonly deps;
+    private readonly modelClaims;
+    private readonly claimingModels;
+    private readonly modelTransitions;
+    /** One entry per model for every acquire still pending, so a cancel reaches the one that is loading. */
+    private readonly loadCancels;
+    constructor(deps: LocalSessionsDeps);
+    /** Load or attach without making an attaching client accidentally own the shared session. */
+    acquire(provider: LocalProviderId, modelId: string, options: CoreLoadOptions): Promise<{
+        session: SessionInfo;
+        created: boolean;
+    }>;
+    /**
+     * Cancel the load in flight for a model. Deliberately outside `withModelTransition`: queued there
+     * it would wait for the very load it is meant to stop. `false` means nothing is pending — the load
+     * has not reached the core yet or has already answered, and the caller unloads instead.
+     */
+    cancelLoad(provider: LocalProviderId, modelId: string): boolean;
+    private acquireNow;
+    unload(provider: LocalProviderId, modelId: string): Promise<UnloadResult>;
+    /** Wait for every model transition in flight, then release every claim this core still holds. */
+    releaseAll(): Promise<void>;
+    localTarget(provider: LocalProvider, modelId: string): LocalTarget | undefined;
+    /** Every session the public server can route to, owned here or registered as external. */
+    listLocalTargets(): LocalTarget[];
+    /**
+     * What the public server asks of a runtime when a request fails for lack of context or on a
+     * poisoned engine. Recovery reloads at the same context; everything else grows it one step.
+     */
+    serverCtxRequest(provider: LocalProvider, modelId: string, trigger: string): Promise<CtxIncreaseOutcome>;
+    private withModelTransition;
+}
+export declare function sessionsOf(runtimes: Map<LocalProviderId, LocalRuntime>): SessionSummary[];
+export declare function unknownProvider(provider: string, available: Iterable<string>): AtomicCoreError;

package/dist/core/sessions.js

@@ -0,0 +1,180 @@
+/**
+ * Local model sessions as `AtomicCore` owns them: the cross-process model claim taken before a load,
+ * per-model serialization of load/unload, cancelling a load that has not answered yet, and how the
+ * public server finds a session — one this core runs or one the desktop app registered as external.
+ */
+import { AtomicCoreError } from '../contracts/index.js';
+import { assertNotLoadedByLegacy, acquireModelClaim } from '../lock/index.js';
+import { LoadCancelRegistry, loadCancelledError, throwIfLoadCancelled } from '../runtime/index.js';
+import { LOCAL_SEARCH_ORDER, modelIdsMatch } from '../router/index.js';
+/** Model claims and per-model transitions for the sessions this core loads. */
+export class LocalSessions {
+    deps;
+    modelClaims = new Map();
+    claimingModels = new Map();
+    modelTransitions = new Map();
+    /** One entry per model for every acquire still pending, so a cancel reaches the one that is loading. */
+    loadCancels = new LoadCancelRegistry();
+    constructor(deps) {
+        this.deps = deps;
+    }
+    /** Load or attach without making an attaching client accidentally own the shared session. */
+    acquire(provider, modelId, options) {
+        const key = `${provider}\0${modelId}`;
+        // Registered before the transition queue, not inside it: an acquire waiting its turn behind
+        // another one of the same model has to be reachable by a cancel as well.
+        const cancel = this.loadCancels.register(key);
+        return this.withModelTransition(key, () => this.acquireNow(provider, modelId, options, cancel)).finally(() => cancel.release());
+    }
+    /**
+     * Cancel the load in flight for a model. Deliberately outside `withModelTransition`: queued there
+     * it would wait for the very load it is meant to stop. `false` means nothing is pending — the load
+     * has not reached the core yet or has already answered, and the caller unloads instead.
+     */
+    cancelLoad(provider, modelId) {
+        this.deps.runtime(provider);
+        return this.loadCancels.cancel(`${provider}\0${modelId}`);
+    }
+    async acquireNow(provider, modelId, options, cancel) {
+        this.deps.assertRunning();
+        throwIfLoadCancelled(cancel.signal);
+        // The desktop app can still own this data folder until it becomes a core client. A second copy
+        // of a model it already holds would double the VRAM and race for the GPU, so refuse before
+        // anything is spawned, and say where the app is already serving it.
+        const runtime = this.deps.runtime(provider);
+        const key = `${provider}\0${modelId}`;
+        let claim = this.modelClaims.get(key);
+        if (!claim) {
+            let pending = this.claimingModels.get(key);
+            if (!pending) {
+                pending = acquireModelClaim(this.deps.layout, provider, modelId, this.deps.instanceId);
+                this.claimingModels.set(key, pending);
+            }
+            try {
+                claim = await pending;
+                this.modelClaims.set(key, claim);
+            }
+            finally {
+                if (this.claimingModels.get(key) === pending)
+                    this.claimingModels.delete(key);
+            }
+        }
+        const created = !runtime.findSession(modelId) && !runtime.isLoading(modelId);
+        try {
+            throwIfLoadCancelled(cancel.signal);
+            await assertNotLoadedByLegacy(this.deps.layout, modelId);
+            // `options` came off the wire; the signal is the core's own and overrides whatever it carried.
+            const session = await runtime.load(modelId, { ...options, signal: cancel.signal });
+            await claim.update('ready');
+            if (created && cancel.signal.aborted) {
+                // A cancel that raced readiness still wins while the answer is undecided. Unload through the
+                // runtime: `this.unload` would queue behind this very transition.
+                await runtime.unload(modelId);
+                throw loadCancelledError();
+            }
+            // The answer is decided: from here a cancel finds nothing pending and the caller unloads.
+            cancel.release();
+            return { session, created };
+        }
+        catch (e) {
+            // Never release the claim over a live process: a joined reload, or an unload that failed.
+            if (created && !runtime.findSession(modelId)) {
+                await claim.release().catch(() => { });
+                this.modelClaims.delete(key);
+            }
+            throw e;
+        }
+    }
+    unload(provider, modelId) {
+        const key = `${provider}\0${modelId}`;
+        return this.withModelTransition(key, async () => {
+            this.deps.assertRunning();
+            const result = await this.deps.runtime(provider).unload(modelId);
+            if (result.success) {
+                await this.modelClaims
+                    .get(key)
+                    ?.release()
+                    .catch(() => { });
+                this.modelClaims.delete(key);
+            }
+            return result;
+        });
+    }
+    /** Wait for every model transition in flight, then release every claim this core still holds. */
+    async releaseAll() {
+        await Promise.all([...this.modelTransitions.values()]);
+        await Promise.all([...this.modelClaims.values()].map((claim) => claim.release().catch(() => { })));
+        this.modelClaims.clear();
+    }
+    localTarget(provider, modelId) {
+        const session = this.deps.runtimes
+            .get(provider)
+            ?.list()
+            .find((s) => modelIdsMatch(s.model_id, modelId)) ??
+            this.deps.externalSessions.find(provider, (id) => modelIdsMatch(id, modelId));
+        return session ? toLocalTarget(provider, session) : undefined;
+    }
+    /** Every session the public server can route to, owned here or registered as external. */
+    listLocalTargets() {
+        return LOCAL_SEARCH_ORDER.flatMap((provider) => [
+            ...(this.deps.runtimes.get(provider)?.list() ?? []).map((s) => toLocalTarget(provider, s)),
+            ...this.deps.externalSessions
+                .list()
+                .filter((s) => s.provider === provider)
+                .map((s) => toLocalTarget(provider, s)),
+        ]);
+    }
+    /**
+     * What the public server asks of a runtime when a request fails for lack of context or on a
+     * poisoned engine. Recovery reloads at the same context; everything else grows it one step.
+     */
+    async serverCtxRequest(provider, modelId, trigger) {
+        // A session another process owns is grown by that process; the core only asks.
+        const ownedHere = this.deps.runtimes
+            .get(provider)
+            ?.list()
+            .some((s) => modelIdsMatch(s.model_id, modelId));
+        const external = ownedHere
+            ? undefined
+            : this.deps.externalSessions.find(provider, (id) => modelIdsMatch(id, modelId));
+        if (external)
+            return this.deps.externalSessions.requestCtxIncrease(external.owner, provider, external.model_id, trigger);
+        if (trigger === 'compute_error_recovery') {
+            const result = await this.deps.recreateSession(provider, modelId);
+            return result.ok ? { ok: true } : { ok: false, reason: result.reason };
+        }
+        const result = await this.deps.increaseCtx(provider, modelId, trigger);
+        return result.ok ? { ok: true, new_ctx_len: result.new_ctx_len } : { ok: false, reason: result.reason };
+    }
+    withModelTransition(key, operation) {
+        const previous = this.modelTransitions.get(key) ?? Promise.resolve();
+        const result = previous.then(operation);
+        const settled = result.then(() => { }, () => { });
+        this.modelTransitions.set(key, settled);
+        void settled.then(() => {
+            if (this.modelTransitions.get(key) === settled)
+                this.modelTransitions.delete(key);
+        });
+        return result;
+    }
+}
+function toLocalTarget(provider, session) {
+    return {
+        provider,
+        modelId: session.model_id,
+        port: session.port,
+        apiKey: session.api_key,
+        isEmbedding: session.is_embedding,
+    };
+}
+export function sessionsOf(runtimes) {
+    const out = [];
+    for (const [provider, runtime] of runtimes)
+        for (const info of runtime.list())
+            out.push({ ...info, provider });
+    return out;
+}
+export function unknownProvider(provider, available) {
+    return new AtomicCoreError('PROVIDER_NOT_FOUND', `Unknown provider "${provider}".`, `available: ${[...available].join(', ')}`);
+}
+//# sourceMappingURL=sessions.js.map

package/dist/core/sessions.js.map

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

package/dist/core/types.d.ts

@@ -0,0 +1,61 @@
+import type { LocalProviderId } from '../contracts/index.js';
+import type { LoadOptions } from '../runtime/llamacpp/index.js';
+import type { LocalLoadOptions } from '../runtime/index.js';
+import type { WireDiffusionOptions } from '../diffusion/index.js';
+import type { Prober, TunnelSpawner, TunnelTimings } from '../remote-access/index.js';
+import type { TelemetryControl } from '../telemetry/index.js';
+export type CoreLogger = (level: 'info' | 'warn' | 'error', message: string) => void;
+export interface AtomicCoreOptions {
+    ownerScope?: 'app' | 'cli';
+    /** Explicit data folder; otherwise resolved like the app does (PLAN.md §8.2 "Data folder"). */
+    dataFolder?: string;
+    /** Where the app's bundled sidecar binaries live (`resources/bin`); needed for MLX and Foundation Models. */
+    resourcesDir?: string;
+    /**
+     * The `cloudflared` binary for remote access (`--cloudflared-bin`). The app bundles it next to its
+     * own executable and says where; without it `ATOMIC_CLOUDFLARED_BIN` and the resources folder are
+     * tried, and with none of them remote access reports `cloudflared_unavailable`.
+     */
+    cloudflaredPath?: string;
+    /** Test seams for the remote-access tunnel: a scripted process, a scripted probe, short timings. */
+    remoteAccess?: {
+        spawner?: TunnelSpawner;
+        prober?: Prober;
+        timings?: Partial<TunnelTimings>;
+    };
+    /** Test seams of the image-generation service (a fake engine, short timings). */
+    diffusion?: WireDiffusionOptions['overrides'];
+    /** The platform runtimes are offered for (macOS-only engines are not registered elsewhere). Test seam. */
+    platform?: NodeJS.Platform;
+    fetch?: typeof fetch;
+    env?: NodeJS.ProcessEnv;
+    /** 'owner' takes the instance lock; 'auto' is the same today — attaching is the CLI's job. */
+    role?: 'owner' | 'auto';
+    controlHost?: string;
+    /** 0 (the default) picks a free port and publishes it in the lock. */
+    controlPort?: number;
+    logger?: CoreLogger;
+    /**
+     * Where failures worth an issue go, and what `/atomic/v1/telemetry` drives. A host that owns its
+     * process (the app's daemon, the CLI) builds one with `createCoreReporter` so start-up failures are
+     * reported too; otherwise the core builds its own from `telemetry`.
+     */
+    errorReporter?: TelemetryControl;
+    /**
+     * Error reporting when no `errorReporter` is given: the core reports to its own Sentry project by
+     * itself, as `library` unless a `host` name is given. `enabled` is the host's consent; `false`
+     * turns reporting off for this core altogether. See docs/decisions/*-the-core-owns-its-error-reporting.md.
+     */
+    telemetry?: false | {
+        host?: string;
+        hostVersion?: string;
+        enabled?: boolean;
+    };
+}
+export declare const LOCAL_PROVIDER: LocalProviderId;
+/**
+ * Load options as the control API carries them: the shared ones plus llama.cpp's explicit paths.
+ * Without `signal`: a load is cancelled through `AtomicCore.cancelLoad`, and the control route casts
+ * a JSON body straight into these options, so a `signal` key arriving there must never be trusted.
+ */
+export type CoreLoadOptions = Omit<LocalLoadOptions, 'signal'> & Omit<LoadOptions, 'overrides' | 'signal'>;

package/dist/core/types.js

@@ -0,0 +1,2 @@
+export const LOCAL_PROVIDER = 'llamacpp-upstream';
+//# sourceMappingURL=types.js.map

package/dist/core/types.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.js","sourceRoot":"","sources":["../../src/core/types.ts"],"names":[],"mappings":"AAiDA,MAAM,CAAC,MAAM,cAAc,GAAoB,mBAAmB,CAAA"}

package/dist/credentials/api-keys.d.ts

@@ -0,0 +1,41 @@
+/**
+ * `<data>/atomic-core/credentials.json`: cloud provider API keys, kept out of `settings.json` so the
+ * settings file can be read, diffed and shown without exposing a secret (PLAN.md §3.4).
+ *
+ * `{version: 1, providers: {<id>: {api_key, updated_at, bound_to?}}}`, owner-readable only (0600 on Unix; on
+ * Windows the file inherits the per-user ACL of the data folder). Written through `.tmp` + rename,
+ * with the mode set when the temporary file is created, so the key is never on disk under a wider
+ * mode even for an instant.
+ */
+export declare const CREDENTIALS_VERSION = 1;
+export interface ApiKeyRecord {
+    api_key: string;
+    updated_at: string;
+    /** Hash of the non-secret provider configuration this key may be sent to. */
+    bound_to?: string;
+}
+export declare class ApiKeyStore {
+    readonly path: string;
+    private readonly now;
+    private doc;
+    private chain;
+    private constructor();
+    /**
+     * Read the file, or start empty when it is absent. A file that cannot be parsed is refused rather
+     * than silently replaced: overwriting it would throw away every key the user entered.
+     */
+    static open(path: string, options?: {
+        now?: () => number;
+    }): Promise<ApiKeyStore>;
+    get(provider: string): string | undefined;
+    has(provider: string): boolean;
+    record(provider: string): ApiKeyRecord | undefined;
+    /** Store a key; an empty or absent key removes the entry, the way the app's registration clears one. */
+    set(provider: string, apiKey: string | null | undefined): Promise<void>;
+    remove(provider: string): Promise<void>;
+    /** Persist a key and its destination binding as one credentials-file update. */
+    setBound(provider: string, apiKey: string | null | undefined, binding: string): Promise<void>;
+    /** Restore the exact previous record after a failed settings write. */
+    restore(provider: string, record: ApiKeyRecord | undefined): Promise<void>;
+    private mutate;
+}