@runtimed/node 0.5.6 → 0.6.0-nightly.36654139751

package/src/binding.d.ts

@@ -40,8 +40,10 @@ export declare class Session {
    *
    * Callback receives the same JSON shape as `CellResult`, emitted whenever
    * the RuntimeStateDoc entry for the execution changes. The subscription
-   * ends after an authoritative terminal snapshot, including kernel
-   * failure/close.
+   * ends after a terminal execution snapshot, kernel failure after the
+   * execution has been observed, or connection close. An execution that
+   * never appears stays pending until the subscription is disposed or the
+   * connection closes.
    */
   onExecutionProgress(executionId: string, cellId: string | undefined | null, callback: (arg0: string) => void): EventSubscription
   /**
@@ -68,6 +70,13 @@ export declare class Session {
    * `NotebookDoc` + `RuntimeStateDoc` + `CommsDoc` snapshot triplet.
    */
   exportSnapshotPair(): Promise<SnapshotPair>
+  /**
+   * Acknowledge the current NotebookDoc frontier at the connected daemon.
+   * Returns the captured heads; later edits are not covered. Rejects on
+   * timeout, close, disconnect, unsupported peers, or daemon rejection.
+   * This does not save an .ipynb or acknowledge other document streams.
+   */
+  confirmNotebookSync(): Promise<Array<string>>
   /** Close the session and release the underlying connection. */
   close(): Promise<void>
   /**
@@ -154,6 +163,18 @@ export declare class Session {
   waitForExecution(executionId: string, options?: WaitExecutionOptions | undefined | null): Promise<CellResult>
 }
 
+/** One connection-owned permission registration. Keep it alive while the host is active. */
+export declare class TelemetryRegistration {
+  /** Await the daemon's permission acknowledgment. Disconnected handles reject, never reconnect. */
+  updatePermission(allowed: boolean): Promise<void>
+  /**
+   * Fence queued grants synchronously, then await revocation acknowledgment.
+   * Idempotent after success; disconnection rejects.
+   * Without acknowledgment, remote revocation can take up to the 120-second lease expiry.
+   */
+  close(): Promise<void>
+}
+
 /** An active notebook room reported by the daemon. */
 export interface ActiveNotebook {
   notebookId: string
@@ -273,6 +294,15 @@ export interface CreateRelayOptions {
 /** Daemon metadata needed by a Node host before it opens a notebook relay. */
 export interface DaemonInfo {
   version: string
+  /** Protocol support only; does not imply permission or enabled emission. */
+  hostTelemetry?: boolean
+  /** Daemon rollout/process emission gate, not user consent or host permission. */
+  hostTelemetryEnabled?: boolean
+  protocolVersion: number
+  /** Zero means the daemon predates semantic API version reporting. */
+  daemonApiVersion: number
+  /** Shared Rust compatibility diagnostic; absent when supported by this client. */
+  compatibilityError?: string
   socketPath: string
   isDevMode: boolean
   blobPort?: number
@@ -329,6 +359,29 @@ export interface GetExecutionResultOptions {
   socketPath?: string
 }
 
+/**
+ * Create environment.yml without overwriting an existing file or symlink.
+ *
+ * This uses the local Node process's filesystem authority. It does not contact
+ * the daemon, install packages, approve trust, or launch/change a kernel.
+ * Returns the absolute path of the newly created manifest.
+ */
+export declare function initializeEnvironmentYml(options: InitializeEnvironmentYmlOptions): Promise<string>
+
+/** Options for the local host's explicit manifest creation request. */
+export interface InitializeEnvironmentYmlOptions {
+  /** An existing absolute directory the host is authorized to write. */
+  directory: string
+  /** Optional environment name: letters, numbers, '.', '_' and '-'. */
+  name?: string
+  /** Conda match specs; pip subsections are not supported by this initializer. */
+  dependencies: Array<string>
+  /** Optional Python version constraint, e.g. "3.12" or ">=3.11,<3.13". */
+  python?: string
+  /** At least one channel, in priority order. No channels are inferred. */
+  channels: Array<string>
+}
+
 /** A notebook cell snapshot. */
 export interface JsCellSnapshot {
   id: string
@@ -397,6 +450,24 @@ export interface OpenRelayOptions {
 /** Open a notebook file and return its native typed-frame relay. */
 export declare function openRelayPath(path: string, options?: OpenRelayOptions | undefined | null): Promise<NativeRelaySession>
 
+/**
+ * Return null if host telemetry is unsupported or the capability probe is unavailable.
+ * Permission defaults to denied.
+ * The handle never reconnects; collecting an idle handle terminates its socket without awaiting revocation.
+ */
+export declare function openTelemetryRegistration(options: OpenTelemetryRegistrationOptions): Promise<TelemetryRegistration | null>
+
+export interface OpenTelemetryRegistrationOptions {
+  /** Explicit daemon endpoint. Opening a registration never starts a daemon. */
+  socketPath: string
+  /** Stable product slug, not a user, window, session, or installation identifier. */
+  hostId: string
+  /** Only "app" and "mcp" are accepted. */
+  source: 'app' | 'mcp'
+  /** Host permission only; daemon consent and emission gates still apply. Defaults to false. */
+  allowed?: boolean
+}
+
 /**
  * Package manager for Python notebook dependencies.
  *

package/src/execution-store.cjs

@@ -0,0 +1,397 @@
+// Generated by scripts/build-execution-store.mjs. Do not edit.
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.createNotebookExecutionStore = createNotebookExecutionStore;
+const EMPTY_NOTEBOOK_QUEUE = Object.freeze({
+    executing_cell_id: null,
+    queued_cell_ids: Object.freeze([]),
+});
+/** Independent synchronous notebook state. Construction performs no I/O. */
+function createNotebookExecutionStore() {
+    const _executionMap = new Map();
+    const _runtimeOwnedExecutionIds = new Set();
+    /** Per-cell reverse index: cell_id -> latest execution_id. */
+    const _cellToExecution = new Map();
+    const _executionToCell = new Map();
+    let _notebookQueueProjection = EMPTY_NOTEBOOK_QUEUE;
+    let _queue = null;
+    let _snapshot;
+    const _subscribers = new Map();
+    const _cellExecutionSubscribers = new Map();
+    const _queueProjectionSubscribers = new Set();
+    let _executionStructureVersion = 0;
+    const _executionStructureVersionSubscribers = new Set();
+    function emitExecutionChange(execution_id) {
+        const subs = _subscribers.get(execution_id);
+        if (!subs)
+            return;
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [...subs]) {
+            if (!subs.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch {
+                // subscriber errors must not break the dispatch loop
+            }
+        }
+    }
+    function emitCellExecutionPointerChange(cell_id) {
+        const subs = _cellExecutionSubscribers.get(cell_id);
+        if (!subs)
+            return;
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [...subs]) {
+            if (!subs.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch { }
+        }
+    }
+    function emitQueueProjectionChange() {
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [..._queueProjectionSubscribers]) {
+            if (!_queueProjectionSubscribers.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch { }
+        }
+    }
+    function emitExecutionStructureChange() {
+        _executionStructureVersion = (_executionStructureVersion + 1) | 0;
+        // Snapshot listeners so subscriptions added during delivery wait for the next notification.
+        // eslint-disable-next-line unicorn/no-useless-spread
+        for (const cb of [..._executionStructureVersionSubscribers]) {
+            if (!_executionStructureVersionSubscribers.has(cb))
+                continue;
+            try {
+                cb();
+            }
+            catch { }
+        }
+    }
+    // ── Subscription helpers ────────────────────────────────────────────────
+    function subscribeExecutionById(execution_id) {
+        return (callback) => {
+            let subs = _subscribers.get(execution_id);
+            if (!subs) {
+                subs = new Set();
+                _subscribers.set(execution_id, subs);
+            }
+            const set = subs;
+            set.add(callback);
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                set.delete(callback);
+                if (set.size === 0 && _subscribers.get(execution_id) === set)
+                    _subscribers.delete(execution_id);
+            };
+        };
+    }
+    function getExecutionSnapshotGetter(execution_id) {
+        return () => (execution_id ? _executionMap.get(execution_id) : undefined);
+    }
+    function subscribeCellExecutionPointer(cell_id) {
+        return (callback) => {
+            let subs = _cellExecutionSubscribers.get(cell_id);
+            if (!subs) {
+                subs = new Set();
+                _cellExecutionSubscribers.set(cell_id, subs);
+            }
+            const set = subs;
+            set.add(callback);
+            let active = true;
+            return () => {
+                if (!active)
+                    return;
+                active = false;
+                set.delete(callback);
+                if (set.size === 0 && _cellExecutionSubscribers.get(cell_id) === set)
+                    _cellExecutionSubscribers.delete(cell_id);
+            };
+        };
+    }
+    function getCellExecutionIdGetter(cell_id) {
+        return () => _cellToExecution.get(cell_id) ?? null;
+    }
+    function subscribeNotebookQueueProjection(callback) {
+        _queueProjectionSubscribers.add(callback);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            _queueProjectionSubscribers.delete(callback);
+        };
+    }
+    function getNotebookQueueProjection() {
+        return _notebookQueueProjection;
+    }
+    function subscribeExecutionStructureVersion(callback) {
+        _executionStructureVersionSubscribers.add(callback);
+        let active = true;
+        return () => {
+            if (!active)
+                return;
+            active = false;
+            _executionStructureVersionSubscribers.delete(callback);
+        };
+    }
+    function getExecutionStructureVersionSnapshot() {
+        return _executionStructureVersion;
+    }
+    // ── Write operations ────────────────────────────────────────────────────
+    /**
+     * Upsert an execution snapshot. Notifies only that execution's subscribers.
+     *
+     * Does NOT update the cell -> execution pointer. `RuntimeStateDoc` keeps
+     * historical executions per cell, so iterating it cannot reliably pick
+     * the current one. Callers set the cell pointer explicitly via
+     * `setCellExecutionPointer`, driven by the canonical `cells/{id}/execution_id`
+     * field in the notebook doc.
+     */
+    function setExecution(execution_id, snap) {
+        const prev = _executionMap.get(execution_id);
+        const sameOutputs = prev !== undefined && stringArraysEqual(prev.output_ids, snap.output_ids);
+        if (prev &&
+            sameOutputs &&
+            prev.execution_count === snap.execution_count &&
+            prev.status === snap.status &&
+            prev.success === snap.success &&
+            (prev.submitted_by_actor_label ?? null) === (snap.submitted_by_actor_label ?? null))
+            return;
+        const owned = Object.freeze({
+            ...snap,
+            output_ids: sameOutputs ? prev.output_ids : Object.freeze([...snap.output_ids]),
+        });
+        _executionMap.set(execution_id, owned);
+        _snapshot = undefined;
+        emitExecutionChange(execution_id);
+        if (!prev || prev.execution_count !== snap.execution_count || !sameOutputs)
+            emitExecutionStructureChange();
+    }
+    /**
+     * Mark execution snapshots whose authoritative source is RuntimeStateDoc.
+     *
+     * Projection placeholders can seed the same execution id before runtime sync
+     * catches up. Runtime upserts call this even when the snapshot is unchanged so
+     * projector cleanup can release ownership without deleting the runtime record.
+     */
+    function markExecutionsRuntimeOwned(execution_ids) {
+        for (const execution_id of execution_ids) {
+            _runtimeOwnedExecutionIds.add(execution_id);
+        }
+    }
+    function isExecutionRuntimeOwned(execution_id) {
+        return _runtimeOwnedExecutionIds.has(execution_id);
+    }
+    /**
+     * Explicitly set the active execution_id for a cell.
+     *
+     * Used on execution_started broadcasts and on clearOutputs (pass null).
+     */
+    function setCellExecutionPointer(cell_id, execution_id) {
+        const prev = _cellToExecution.get(cell_id) ?? null;
+        if (prev === execution_id)
+            return;
+        if (prev !== null && _executionToCell.get(prev) === cell_id) {
+            _executionToCell.delete(prev);
+        }
+        if (execution_id === null) {
+            _cellToExecution.delete(cell_id);
+        }
+        else {
+            _cellToExecution.set(cell_id, execution_id);
+            _executionToCell.set(execution_id, cell_id);
+        }
+        _snapshot = undefined;
+        emitCellExecutionPointerChange(cell_id);
+        emitExecutionStructureChange();
+    }
+    function setNotebookQueueProjection(projection) {
+        const next = notebookQueuesEqual(_notebookQueueProjection, projection)
+            ? _notebookQueueProjection
+            : Object.freeze({
+                executing_cell_id: projection.executing_cell_id,
+                queued_cell_ids: Object.freeze([...projection.queued_cell_ids]),
+            });
+        // A cell-only projection cannot invent execution queue membership, but it
+        // must keep an existing aggregate queue current before notifying readers.
+        if (_queue && !notebookQueuesEqual(_queue.notebook, next)) {
+            _queue = Object.freeze({ ..._queue, notebook: next });
+            _snapshot = undefined;
+        }
+        updateNotebookQueueProjection(next);
+    }
+    /** Accept an owned projection; wire updates preserve absent/null adapters. */
+    function updateNotebookQueueProjection(projection) {
+        if (notebookQueuesEqual(_notebookQueueProjection, projection))
+            return;
+        _notebookQueueProjection = projection;
+        emitQueueProjectionChange();
+    }
+    /**
+     * Drop a batch of executions from the store.
+     *
+     * Notifies per-execution subscribers with `undefined` and clears any cell
+     * pointer that referenced one of the removed ids. Used by the projection
+     * when the daemon trims an execution out of `RuntimeStateDoc` so the
+     * store doesn't drift monotonically larger.
+     */
+    function deleteExecutions(execution_ids) {
+        for (const eid of execution_ids) {
+            const existed = _executionMap.delete(eid);
+            _runtimeOwnedExecutionIds.delete(eid);
+            const cellId = _executionToCell.get(eid);
+            _executionToCell.delete(eid);
+            const cleared = cellId !== undefined && _cellToExecution.get(cellId) === eid;
+            if (cleared)
+                _cellToExecution.delete(cellId);
+            if (!existed && !cleared)
+                continue;
+            _snapshot = undefined;
+            if (existed)
+                emitExecutionChange(eid);
+            if (cleared)
+                emitCellExecutionPointerChange(cellId);
+            emitExecutionStructureChange();
+        }
+    }
+    /** Read a snapshot without subscribing. */
+    function getExecutionById(execution_id) {
+        return _executionMap.get(execution_id);
+    }
+    /** Read the cell's current execution_id without subscribing. */
+    function getCellExecutionId(cell_id) {
+        return _cellToExecution.get(cell_id) ?? null;
+    }
+    /** Read the current cell id for an execution pointer without subscribing. */
+    function getCellIdForExecutionId(execution_id) {
+        return _executionToCell.get(execution_id) ?? null;
+    }
+    /** Reset the entire store. Called on notebook switch or full reset. */
+    function resetNotebookExecutions() {
+        const eids = [..._executionMap.keys()];
+        const cells = [..._cellToExecution.keys()];
+        _executionMap.clear();
+        _runtimeOwnedExecutionIds.clear();
+        _cellToExecution.clear();
+        _executionToCell.clear();
+        _notebookQueueProjection = EMPTY_NOTEBOOK_QUEUE;
+        _queue = null;
+        _snapshot = undefined;
+        for (const eid of eids)
+            emitExecutionChange(eid);
+        for (const cid of cells)
+            emitCellExecutionPointerChange(cid);
+        emitQueueProjectionChange();
+        if (eids.length > 0 || cells.length > 0) {
+            emitExecutionStructureChange();
+        }
+    }
+    function stringArraysEqual(a, b) {
+        if (a.length !== b.length)
+            return false;
+        for (let i = 0; i < a.length; i++) {
+            if (a[i] !== b[i])
+                return false;
+        }
+        return true;
+    }
+    /** Lazily materialize a stable, immutable aggregate for headless consumers. */
+    function getSnapshot() {
+        return (_snapshot ??= Object.freeze({
+            cell_execution_ids: Object.freeze(Object.fromEntries(_cellToExecution)),
+            executions: Object.freeze(Object.fromEntries(_executionMap)),
+            queue: _queue,
+        }));
+    }
+    /**
+     * Apply Rust's projection in frontend order: upserts, removals, pointers, queue.
+     * Notifications are synchronous per write, not an atomic changeset batch.
+     * Reads inside notifications are current; retained snapshots never change.
+     */
+    function applyChangeset(changeset, options = {}) {
+        if (!changeset)
+            return;
+        for (const [id, snapshot] of changeset.execution_upserts ?? []) {
+            markExecutionsRuntimeOwned([id]);
+            setExecution(id, snapshot);
+            options.onExecutionSnapshot?.(id, getExecutionById(id));
+        }
+        deleteExecutions(changeset.removed_execution_ids ?? []);
+        for (const [cell, id] of changeset.cell_pointer_changes ?? [])
+            setCellExecutionPointer(cell, id);
+        if (Object.prototype.hasOwnProperty.call(changeset, "queue")) {
+            const queue = changeset.queue;
+            const next = queue == null
+                ? null
+                : Object.freeze({
+                    executing_execution_id: queue.executing_execution_id ?? null,
+                    queued_execution_ids: Object.freeze([...queue.queued_execution_ids]),
+                    notebook: queue.notebook == null
+                        ? queue.notebook
+                        : Object.freeze({
+                            executing_cell_id: queue.notebook.executing_cell_id ?? null,
+                            queued_cell_ids: Object.freeze([...queue.notebook.queued_cell_ids]),
+                        }),
+                });
+            if (!queuesEqual(_queue, next)) {
+                _queue = next;
+                _snapshot = undefined;
+            }
+            updateNotebookQueueProjection(next?.notebook ?? EMPTY_NOTEBOOK_QUEUE);
+        }
+    }
+    function queuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (!a || !b)
+            return false;
+        if (a.executing_execution_id !== b.executing_execution_id ||
+            !stringArraysEqual(a.queued_execution_ids, b.queued_execution_ids))
+            return false;
+        return notebookQueuesEqual(a.notebook, b.notebook);
+    }
+    function notebookQueuesEqual(a, b) {
+        if (a === b)
+            return true;
+        if (!a || !b)
+            return false;
+        return (a.executing_cell_id === b.executing_cell_id &&
+            stringArraysEqual(a.queued_cell_ids, b.queued_cell_ids));
+    }
+    return {
+        subscribeNotebookQueueProjection,
+        getNotebookQueueProjection,
+        setExecution,
+        markExecutionsRuntimeOwned,
+        isExecutionRuntimeOwned,
+        setCellExecutionPointer,
+        setNotebookQueueProjection,
+        deleteExecutions,
+        getExecutionById,
+        getCellExecutionId,
+        getCellIdForExecutionId,
+        resetNotebookExecutions,
+        subscribeExecutionById,
+        getExecutionSnapshotGetter,
+        subscribeCellExecutionPointer,
+        getCellExecutionIdGetter,
+        subscribeExecutionStructureVersion,
+        getExecutionStructureVersionSnapshot,
+        getSnapshot,
+        applyChangeset,
+    };
+}

package/src/execution-store.d.cts

@@ -0,0 +1,66 @@
+// Generated by scripts/build-execution-store.mjs. Do not edit.
+export interface ExecutionViewSnapshot {
+    execution_count: number | null;
+    status: "queued" | "running" | "done" | "error" | "cancelled" | (string & {});
+    success: boolean | null;
+    output_ids: string[];
+    submitted_by_actor_label?: string | null;
+}
+export interface ExecutionQueueProjection {
+    executing_execution_id?: string | null;
+    queued_execution_ids: string[];
+    notebook?: {
+        executing_cell_id?: string | null;
+        queued_cell_ids: string[];
+    } | null;
+}
+export interface ExecutionViewChangeset {
+    cell_pointer_changes?: Array<[cell_id: string, execution_id: string | null]>;
+    execution_upserts?: Array<[execution_id: string, snapshot: ExecutionViewSnapshot]>;
+    removed_execution_ids?: string[];
+    queue?: ExecutionQueueProjection | null;
+}
+/** Immutable consumer snapshots; wire payload types above remain mutable. */
+export type ExecutionSnapshot = Readonly<Omit<ExecutionViewSnapshot, "output_ids">> & {
+    readonly output_ids: readonly string[];
+};
+export interface NotebookQueueProjectionSnapshot {
+    readonly executing_cell_id: string | null;
+    readonly queued_cell_ids: readonly string[];
+}
+export interface ExecutionQueueSnapshot {
+    readonly executing_execution_id: string | null;
+    readonly queued_execution_ids: readonly string[];
+    readonly notebook?: NotebookQueueProjectionSnapshot | null;
+}
+export interface ExecutionView {
+    readonly cell_execution_ids: Readonly<Record<string, string>>;
+    readonly executions: Readonly<Record<string, ExecutionSnapshot>>;
+    readonly queue: ExecutionQueueSnapshot | null;
+}
+/** Independent synchronous notebook state. Construction performs no I/O. */
+export declare function createNotebookExecutionStore(): {
+    subscribeNotebookQueueProjection: (callback: () => void) => () => void;
+    getNotebookQueueProjection: () => NotebookQueueProjectionSnapshot;
+    setExecution: (execution_id: string, snap: ExecutionSnapshot) => void;
+    markExecutionsRuntimeOwned: (execution_ids: Iterable<string>) => void;
+    isExecutionRuntimeOwned: (execution_id: string) => boolean;
+    setCellExecutionPointer: (cell_id: string, execution_id: string | null) => void;
+    setNotebookQueueProjection: (projection: NotebookQueueProjectionSnapshot) => void;
+    deleteExecutions: (execution_ids: Iterable<string>) => void;
+    getExecutionById: (execution_id: string) => ExecutionSnapshot | undefined;
+    getCellExecutionId: (cell_id: string) => string | null;
+    getCellIdForExecutionId: (execution_id: string) => string | null;
+    resetNotebookExecutions: () => void;
+    subscribeExecutionById: (execution_id: string) => (cb: () => void) => () => void;
+    getExecutionSnapshotGetter: (execution_id: string) => () => ExecutionSnapshot | undefined;
+    subscribeCellExecutionPointer: (cell_id: string) => (cb: () => void) => () => void;
+    getCellExecutionIdGetter: (cell_id: string) => () => string | null;
+    subscribeExecutionStructureVersion: (callback: () => void) => () => void;
+    getExecutionStructureVersionSnapshot: () => number;
+    getSnapshot: () => ExecutionView;
+    applyChangeset: (changeset: ExecutionViewChangeset | null | undefined, options?: {
+        onExecutionSnapshot?: (id: string, snapshot: ExecutionSnapshot) => void;
+    }) => void;
+};
+export type NotebookExecutionStore = ReturnType<typeof createNotebookExecutionStore>;