@atomic-chat/core 0.5.1

package/dist/cli/owner.js

@@ -0,0 +1,179 @@
+/**
+ * Finding — or starting — the core that owns a data folder (PLAN.md §3.6).
+ *
+ * Every command that needs a running core goes through here: read the lock, attach to a live owner,
+ * and only when there is none, launch `daemon` as an independent process and wait for it to publish
+ * its control port. The launched core does *not* die with us: that is the whole point of the owner
+ * model, and it is why `serve` can be Ctrl+C'd without unloading the model.
+ */
+import { spawn } from 'node:child_process';
+import { AtomicCoreError } from '../contracts/index.js';
+import { CoreClient } from '../client/index.js';
+import { inspectLock, readControlToken, waitForPublishedOwner } from '../lock/index.js';
+import { CORE_VERSION } from '../version.js';
+export const DAEMON_START_TIMEOUT_MS = 20_000;
+/**
+ * How to re-invoke ourselves. Always through `process.execPath`: inside a compiled Bun binary
+ * `argv[0]` is the literal string `bun`, which is not a program on the user's machine — spawning it
+ * gave `Script not found "daemon"`. Running from source needs the script path as well.
+ */
+export function selfCommand(argv = process.argv, execPath = process.execPath) {
+    const script = argv[1];
+    return script && /\.(c|m)?[jt]s$/.test(script) ? [execPath, script] : [execPath];
+}
+export async function attachToOwner(options) {
+    const state = await inspectLock(options.layout);
+    if (state.kind === 'owned' && state.record.state === 'ready') {
+        if (state.record.owner_scope !== 'cli' || state.record.version !== CORE_VERSION) {
+            if (state.record.owner_scope === 'app')
+                throw new AtomicCoreError('CORE_PROTOCOL_MISMATCH', 'The desktop application owns this folder.');
+            if (!options.launch)
+                throw new AtomicCoreError('CORE_PROTOCOL_MISMATCH', 'The running CLI core needs an upgrade; run a command that starts it.');
+            await replaceIdleDaemon(options, state.record);
+            return attachToOwner(options);
+        }
+        return { client: await connect(options, state.record), record: state.record, launched: false };
+    }
+    if (!options.launch) {
+        throw new AtomicCoreError('CORE_NOT_RUNNING', 'No Atomic Chat core is running for this data folder.', options.layout.root);
+    }
+    if (state.kind === 'owned') {
+        const record = await waitForPublishedOwner(options.layout, {
+            timeoutMs: options.timeoutMs ?? DAEMON_START_TIMEOUT_MS,
+        });
+        if (record.owner_scope !== 'cli' || record.version !== CORE_VERSION)
+            return attachToOwner(options);
+        return { client: await connect(options, record), record, launched: false };
+    }
+    const owner = await launchDaemon(options);
+    return { client: await connect(options, owner.record), ...owner };
+}
+/** A CLI command owns a renewable registration only while it is doing work. */
+export async function withAttachedOwner(options, work) {
+    const owner = await attachToOwner(options);
+    const registration = await owner.client.register(process.pid);
+    const clientId = registration.client.id;
+    let heartbeat;
+    const timer = setInterval(() => {
+        if (heartbeat)
+            return;
+        heartbeat = owner.client
+            .heartbeat(clientId)
+            .catch((error) => options.log?.(`client heartbeat failed: ${String(error)}`))
+            .finally(() => {
+            heartbeat = undefined;
+        });
+    }, options.heartbeatIntervalMs ?? registration.heartbeat_interval_ms);
+    timer.unref?.();
+    try {
+        return await work(owner, clientId);
+    }
+    finally {
+        clearInterval(timer);
+        await heartbeat;
+        try {
+            await owner.client.unregister(clientId);
+        }
+        catch {
+            // A shutdown command or a crashed daemon cannot acknowledge unregister.
+            // The registration also has a bounded TTL.
+        }
+    }
+}
+async function replaceIdleDaemon(options, record) {
+    const token = await readControlToken(options.layout);
+    const client = new CoreClient({
+        baseUrl: `http://${record.control_host}:${record.control_port}`,
+        token,
+        name: options.clientName,
+    });
+    const snapshot = await client.snapshot();
+    if (snapshot.instance_id !== record.instance_id)
+        throw new AtomicCoreError('CORE_PROTOCOL_MISMATCH', 'The CLI core changed during upgrade; retry the command.');
+    if (snapshot.clients.length)
+        throw new AtomicCoreError('CORE_ALREADY_RUNNING', 'The old CLI core still has active clients. End their commands before updating.', snapshot.clients.map((c) => c.name).join(', '));
+    await client.shutdown();
+    const deadline = Date.now() + (options.timeoutMs ?? DAEMON_START_TIMEOUT_MS);
+    while (Date.now() < deadline) {
+        const state = await inspectLock(options.layout);
+        if (state.kind === 'free' ||
+            state.kind === 'stale' ||
+            (state.kind === 'owned' && state.record.instance_id !== record.instance_id))
+            return;
+        await new Promise((resolve) => setTimeout(resolve, 100));
+    }
+    throw new AtomicCoreError('CORE_ALREADY_RUNNING', 'The old CLI core did not release its lock.');
+}
+async function connect(options, record) {
+    const token = await readControlToken(options.layout);
+    const client = new CoreClient({
+        baseUrl: `http://${record.control_host}:${record.control_port}`,
+        token,
+        name: options.clientName,
+    });
+    await client.handshake('cli');
+    return client;
+}
+/**
+ * Start the daemon detached, with its stdio closed after the handshake. The ready line is read from
+ * the lock rather than the pipe, so a core that was started by someone else in the same moment is
+ * just as good as the one we spawned.
+ */
+async function launchDaemon(options) {
+    const command = options.selfCommand ?? selfCommand();
+    const [exe, ...prefix] = command;
+    const args = [...prefix, 'daemon', '--data-folder', options.layout.root, '--control-port', '0'];
+    options.log?.(`starting a core: ${[exe, ...args].join(' ')}`);
+    const child = spawn(exe, args, {
+        detached: true,
+        windowsHide: true,
+        stdio: ['ignore', 'pipe', 'pipe'],
+    });
+    let stderr = '';
+    child.stderr?.on('data', (chunk) => {
+        stderr = `${stderr}${chunk.toString()}`.slice(-4000);
+    });
+    child.stdout?.resume();
+    const failed = new Promise((_resolve, reject) => {
+        child.once('error', (e) => reject(new AtomicCoreError('CORE_START_FAILED', 'Could not start the Atomic Chat core.', e.message)));
+        child.once('exit', (code, signal) => reject(new AtomicCoreError('CORE_START_FAILED', 'The Atomic Chat core exited before it was ready.', `exit ${code ?? signal ?? '?'}${stderr ? `\n${stderr.trim()}` : ''}`)));
+    });
+    try {
+        const record = await Promise.race([
+            waitForPublishedOwner(options.layout, { timeoutMs: options.timeoutMs ?? DAEMON_START_TIMEOUT_MS }),
+            failed,
+        ]);
+        // Detach: the core outlives this process, and we stop holding its pipes open.
+        detachChild(child);
+        return { record, launched: record.pid === child.pid };
+    }
+    catch (e) {
+        child.removeAllListeners();
+        // Two `serve` commands may both observe a free folder. One daemon wins the atomic lock and the
+        // other exits; that loser is not a startup failure for its caller when the winner is already
+        // publishing the same folder. Wait for that owner instead of rejecting one of the commands.
+        const state = await inspectLock(options.layout);
+        if (state.kind === 'owned') {
+            try {
+                const record = await waitForPublishedOwner(options.layout, {
+                    timeoutMs: options.timeoutMs ?? DAEMON_START_TIMEOUT_MS,
+                });
+                return { record, launched: record.pid === child.pid };
+            }
+            finally {
+                detachChild(child);
+            }
+        }
+        if (child.exitCode === null && child.signalCode === null)
+            child.kill();
+        detachChild(child);
+        throw e;
+    }
+}
+function detachChild(child) {
+    child.stdout?.destroy();
+    child.stderr?.destroy();
+    child.unref();
+    child.removeAllListeners();
+}
+//# sourceMappingURL=owner.js.map

package/dist/cli/owner.js.map

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

package/dist/client/control-client.d.ts

@@ -0,0 +1,213 @@
+/**
+ * Browser-safe client of the control API (`/atomic/v1`). The CLI uses it over plain `fetch`; the
+ * Tauri adapter will hand it an `invoke`-backed transport so the control token never enters the
+ * webview (PLAN.md §3.6). No `node:*` may appear in this folder.
+ *
+ * Every failure comes back as `AtomicCoreError` with the code the core sent, so callers branch on
+ * the same strings whether the core is in-process or across a socket.
+ */
+import type { CloudProviderInput, CloudProviderView, SubscriptionModel } from '../cloud/index.js';
+import type { ChatGptStatus } from '../credentials/index.js';
+import type { CoreEventName, DiffusionBackendInstallRecord, DiffusionCancelResult, DiffusionConfig, DiffusionModelFile, DiffusionStatus, FinalizeBackendInstallArgs, GalleryFlags, GalleryImageItem, GalleryListOptions, GalleryPage, ImageCapabilities, ImageGenerateRequest, ImageJob, LoadDiffusionModelRequest, VideoCapabilities, VideoGalleryPage, VideoGenerateRequest, VideoJob, GalleryVideoItem, LoadedDiffusionModel, LocalApiServerState, RemoteAccessStatus, SessionInfo, UnloadResult } from '../contracts/index.js';
+export interface CoreClientOptions {
+    baseUrl: string;
+    token: string;
+    fetch?: typeof fetch;
+    /** Identify this client in `clients` and in the core's logs. */
+    name?: string;
+}
+export interface ClientRegistration {
+    client: {
+        id: string;
+        name: string;
+        pid: number | null;
+    };
+    heartbeat_interval_ms: number;
+    snapshot: CoreSnapshot;
+}
+export interface CoreSnapshot {
+    instance_id: string;
+    owner_scope?: 'app' | 'cli';
+    protocol: number;
+    version: string;
+    pid: number;
+    data_folder: string;
+    cursor: string;
+    sessions: Array<SessionInfo & {
+        provider: string;
+    }>;
+    server: LocalApiServerState;
+    clients: Array<{
+        id: string;
+        name: string;
+        pid: number | null;
+    }>;
+    downloads: unknown[];
+    optimal_backends?: Record<string, {
+        revision: number;
+        optimal: unknown | null;
+    }>;
+}
+export interface CoreEventMessage {
+    id: string;
+    event: CoreEventName | 'resync';
+    data: unknown;
+}
+export declare class CoreClient {
+    private readonly options;
+    private readonly fetchImpl;
+    readonly baseUrl: string;
+    constructor(options: CoreClientOptions);
+    private url;
+    private call;
+    /**
+     * A typed call to any control route, for a host that needs a route family this client does not
+     * wrap yet (hardware, backends, settings, environments). Same transport and error mapping as the
+     * named methods; `path` is relative to `/atomic/v1`.
+     */
+    request<T>(method: 'GET' | 'POST' | 'PUT' | 'PATCH' | 'DELETE', path: string, body?: unknown): Promise<T>;
+    health(): Promise<{
+        ok: true;
+        pid: number;
+        version: string;
+        instance_id: string;
+        protocol: number;
+    }>;
+    snapshot(): Promise<CoreSnapshot>;
+    /** Refuse a binary or ownership scope we cannot safely share. */
+    handshake(expectedScope?: 'app' | 'cli'): Promise<CoreSnapshot>;
+    register(pid?: number): Promise<ClientRegistration>;
+    heartbeat(clientId: string): Promise<{
+        ok: true;
+    }>;
+    unregister(clientId: string): Promise<{
+        ok: true;
+    }>;
+    sessions(): Promise<{
+        sessions: Array<SessionInfo & {
+            provider: string;
+        }>;
+    }>;
+    loadModel(provider: string, modelId: string, body?: Record<string, unknown>): Promise<SessionInfo>;
+    /** Load or attach, while preserving whether this request created the session. */
+    acquireModel(provider: string, modelId: string, body?: Record<string, unknown>): Promise<{
+        session: SessionInfo;
+        created: boolean;
+    }>;
+    /**
+     * Cancel a load that has not answered yet. `false` means nothing was pending for the model: the
+     * load request has not arrived, or it has already answered and the model is to be unloaded.
+     */
+    cancelModelLoad(provider: string, modelId: string): Promise<boolean>;
+    /**
+     * Free bytes where a download would land, or `null` when the platform cannot say. `path` must be
+     * inside the data folder; without one the answer is for the data folder itself.
+     */
+    availableDiskSpace(path?: string): Promise<number | null>;
+    /** The Cloudflare quick tunnel in front of the public server. */
+    remoteAccessStatus(): Promise<RemoteAccessStatus>;
+    /** Answers `starting` at once; a refusal carries the app's reason (`server_stopped`, …) in `details`. */
+    startRemoteAccess(): Promise<RemoteAccessStatus>;
+    /** Answers once the tunnel's process is gone. */
+    stopRemoteAccess(): Promise<RemoteAccessStatus>;
+    /** IPv4 literals a device on the network can dial, default-route address first. Display only. */
+    lanAddresses(): Promise<string[]>;
+    /** Once per core generation, before anything else; `dataFolder` must be the core's own. */
+    configureDiffusion(config: DiffusionConfig): Promise<DiffusionStatus>;
+    diffusionStatus(): Promise<DiffusionStatus>;
+    /** An empty path restores `<data>/images`. */
+    setDiffusionOutputDir(path: string): Promise<DiffusionStatus>;
+    finalizeDiffusionBackend(args: FinalizeBackendInstallArgs): Promise<DiffusionBackendInstallRecord>;
+    listDiffusionBackends(): Promise<DiffusionBackendInstallRecord[]>;
+    /** Refuses (`BACKEND_IN_USE`) while a model runs from that tree. */
+    removeDiffusionBackend(dir: string): Promise<void>;
+    listDiffusionModelFiles(): Promise<DiffusionModelFile[]>;
+    deleteDiffusionModelFile(path: string): Promise<void>;
+    /** Answers once the server serves the model: minutes for a large one. */
+    loadDiffusionModel(request: LoadDiffusionModelRequest): Promise<LoadedDiffusionModel>;
+    unloadDiffusionModel(): Promise<void>;
+    diffusionCapabilities(): Promise<ImageCapabilities>;
+    /** Reset the idle-unload deadline without generating. */
+    touchDiffusionIdle(): Promise<void>;
+    /** Answers with the job id at once; progress and the outcome arrive as `diffusion:*` events. */
+    generateImage(request: ImageGenerateRequest): Promise<{
+        jobId: string;
+    }>;
+    diffusionJob(jobId: string): Promise<ImageJob | null>;
+    cancelImageJob(jobId: string): Promise<DiffusionCancelResult>;
+    listGallery(options: GalleryListOptions): Promise<GalleryPage>;
+    galleryItem(id: string): Promise<GalleryImageItem | null>;
+    deleteGalleryItems(ids: string[]): Promise<void>;
+    setGalleryFlags(id: string, flags: GalleryFlags): Promise<GalleryImageItem>;
+    exportGalleryItem(id: string, targetPath: string): Promise<void>;
+    diffusionVideoCapabilities(): Promise<VideoCapabilities>;
+    /** Answers with the job id at once; progress and the outcome arrive as `diffusion:video-*` events. */
+    generateVideo(request: VideoGenerateRequest): Promise<{
+        jobId: string;
+    }>;
+    videoJob(jobId: string): Promise<VideoJob | null>;
+    cancelVideoJob(jobId: string): Promise<DiffusionCancelResult>;
+    listVideoGallery(options: GalleryListOptions): Promise<VideoGalleryPage>;
+    videoGalleryItem(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, as base64 PNG (a data-URL prefix accepted). */
+    setVideoPoster(id: string, pngBase64: string): Promise<GalleryVideoItem>;
+    /** Restart a poisoned engine at the context it already has. */
+    recreateSession(provider: string, modelId: string): Promise<{
+        ok: boolean;
+        reason?: string;
+    }>;
+    unloadModel(provider: string, modelId: string): Promise<UnloadResult>;
+    cloudProviders(): Promise<{
+        providers: CloudProviderView[];
+    }>;
+    setCloudProvider(provider: string, input: Omit<CloudProviderInput, 'provider'>): Promise<CloudProviderView>;
+    removeCloudProvider(provider: string): Promise<{
+        removed: true;
+    }>;
+    chatgptStatus(): Promise<ChatGptStatus>;
+    chatgptStartLogin(): Promise<{
+        authorize_url: string;
+    }>;
+    chatgptWaitLogin(): Promise<ChatGptStatus>;
+    chatgptCancelLogin(): Promise<{
+        cancelled: true;
+    }>;
+    chatgptLogout(): Promise<ChatGptStatus>;
+    chatgptModels(): Promise<{
+        models: SubscriptionModel[];
+    }>;
+    serverStatus(): Promise<LocalApiServerState>;
+    startServer(options: {
+        host?: string;
+        port?: number;
+        prefix?: string;
+        api_key?: string;
+        trusted_hosts?: string[];
+        proxy_timeout_secs?: number;
+        state_file?: boolean;
+        fallback_port?: boolean;
+    }): Promise<LocalApiServerState>;
+    /** Tell the core whether the app's API screen is watching, which gates prompt previews. */
+    setInspecting(enabled: boolean): Promise<{
+        enabled: boolean;
+    }>;
+    stopServer(): Promise<LocalApiServerState>;
+    shutdown(options?: {
+        force?: boolean;
+        client_id?: string;
+    }): Promise<{
+        ok: true;
+    }>;
+    /**
+     * Subscribe to the event stream. Resolves when the stream ends; `onEvent` sees each frame,
+     * including the `resync` the core sends when a cursor is too old to replay.
+     */
+    events(onEvent: (message: CoreEventMessage) => void, options?: {
+        cursor?: string;
+        signal?: AbortSignal;
+        onOpen?: () => void;
+    }): Promise<void>;
+}