@runtimed/node 0.5.6 → 0.6.0-nightly.36693858508

package/src/index.d.ts

@@ -1,6 +1,6 @@
 import type { Observable } from "rxjs";
 
-export { RelaySession, connectRelay, createRelay, openRelayPath } from "./relay";
+export { RelaySession, connectRelay, createRelay, openRelayPath, queryDaemonInfo } from "./relay";
 export type {
   CommentsNotebookRef,
   CreateRelayOptions,
@@ -11,16 +11,14 @@ export type {
   RelayInfo,
 } from "./relay";
 
-export type NotebookDocPhase = "pending" | "syncing" | "interactive";
-export type RuntimeStatePhase = "pending" | "syncing" | "ready";
+export type ConnectionState = "Connected" | "Disconnected";
+export type NotebookDocPhase = "Pending" | "Syncing" | "Interactive";
+export type RuntimeStatePhase = "Pending" | "Syncing" | "Ready";
 
-export type InitialLoadPhase =
-  | { phase: "not_needed" }
-  | { phase: "streaming" }
-  | { phase: "ready" }
-  | { phase: "failed"; reason: string };
+export type InitialLoadPhase = "NotNeeded" | "Streaming" | "Ready" | { Failed: { reason: string } };
 
 export interface SessionStatus {
+  connection: ConnectionState;
   notebook_doc: NotebookDocPhase;
   runtime_state: RuntimeStatePhase;
   initial_load: InitialLoadPhase;
@@ -32,45 +30,57 @@ export interface ExecutionTransition {
   execution_count: number | null;
 }
 
-export interface ExecutionViewSnapshot {
-  execution_count: number | null;
-  status: "queued" | "running" | "done" | "error" | (string & {});
-  success: boolean | null;
-  output_ids: string[];
-  submitted_by_actor_label?: string | null;
-}
+import type {
+  ExecutionViewChangeset,
+  ExecutionView,
+  NotebookExecutionStore,
+} from "./execution-store.cjs";
+export type {
+  ExecutionViewSnapshot,
+  ExecutionQueueProjection,
+  ExecutionViewChangeset,
+  ExecutionSnapshot,
+  ExecutionQueueSnapshot,
+  ExecutionView,
+  NotebookExecutionStore,
+} from "./execution-store.cjs";
 
-export interface ExecutionQueueProjection {
-  executing_execution_id?: string | null;
-  queued_execution_ids: string[];
-  notebook?: {
-    executing_cell_id?: string | null;
-    queued_cell_ids: string[];
-  } | null;
-}
+export type RuntimeState = Record<string, unknown>;
 
-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;
+export type RuntimeKind = "python" | "deno" | (string & {});
+
+export interface OpenTelemetryRegistrationOptions {
+  /** Explicit daemon endpoint. This API never starts a daemon. */
+  socketPath: string;
+  /** Stable product slug, not a user, window, session, or installation identifier. */
+  hostId: string;
+  source: "app" | "mcp";
+  /** Host permission only; daemon consent and emission gates still apply. Defaults to false. */
+  allowed?: boolean;
 }
 
-export interface ExecutionView {
+/** One host-lifetime owner. Aggregate active windows before granting permission. */
+export class TelemetryRegistration {
+  private constructor();
+  /** Await the daemon acknowledgment. Disconnected handles reject, never reconnect. */
+  updatePermission(allowed: boolean): Promise<void>;
   /**
-   * Current non-null NotebookDoc cell -> execution_id pointers.
-   *
-   * Cleared or deleted cells are omitted. Subscribe to `executionViewChanges$`
-   * when null pointer transitions matter.
+   * Await revocation acknowledgment. Idempotent after success; disconnection rejects.
+   * Without acknowledgment, remote revocation can take up to the 120-second lease expiry.
    */
-  cell_execution_ids: Record<string, string>;
-  executions: Record<string, ExecutionViewSnapshot>;
-  queue: ExecutionQueueProjection | null;
+  close(): Promise<void>;
 }
 
-export type RuntimeState = Record<string, unknown>;
-
-export type RuntimeKind = "python" | "deno" | (string & {});
+/**
+ * Return null if host telemetry is unsupported or the capability probe is unavailable.
+ * Permission defaults to denied.
+ * Keep the handle alive while active and await close() when finished. Garbage collection
+ * terminates its socket without awaiting revocation. The handle never reconnects.
+ * Older native binaries omit this export; feature-detect it when supporting those binaries.
+ */
+export function openTelemetryRegistration(
+  options: OpenTelemetryRegistrationOptions,
+): Promise<TelemetryRegistration | null>;
 
 export const PackageManager: {
   readonly Uv: "uv";
@@ -247,6 +257,14 @@ export class Session {
   runCell(source: string, options?: RunCellOptions): Promise<CellResult>;
   saveNotebook(path?: string): Promise<void>;
   exportSnapshotPair(): Promise<SnapshotPair>;
+  /**
+   * Return the current NotebookDoc heads after the connected daemon accepts them.
+   * Later edits are not covered. Rejects on timeout, close, disconnect, rejection,
+   * and unsupported peers (including hosted bridges). Persistent local rooms
+   * preserve recovery-journal-before-acceptance; ephemeral rooms promise acceptance
+   * only. Does not export an .ipynb or acknowledge runtime, comments, or widgets.
+   */
+  confirmNotebookSync(): Promise<string[]>;
   listCells(): Promise<CellSnapshot[]>;
   getCell(cellId: string): Promise<CellSnapshot | null>;
   createCell(source: string, options?: CreateCellOptions): Promise<string>;
@@ -265,7 +283,9 @@ export class Session {
   removeDependencies(packages: string[], options?: DependencyEditOptions): Promise<number>;
   getDependencyStatus(): Promise<DependencyStatus>;
   getRuntimeStatus(): Promise<RuntimeStatus>;
+  /** Stable immutable state; explicitly copy it if mutable ownership is needed. */
   getExecutionView(): ExecutionView;
+  readonly executions: NotebookExecutionStore;
   dependencyFingerprint(): Promise<string | null>;
   approveTrust(observedHeads?: string[]): Promise<void>;
   syncEnvironment(): Promise<void>;
@@ -276,6 +296,28 @@ export const NativeSession: unknown;
 
 export function defaultSocketPath(): string;
 export function socketPathForChannel(channel: "stable" | "nightly"): string;
+
+export interface InitializeEnvironmentYmlOptions {
+  /** Existing absolute directory the local host is authorized to write. */
+  directory: string;
+  /** Optional name containing only letters, numbers, '.', '_' and '-'. */
+  name?: string;
+  /** Conda match specs. Pip subsections are not supported by this initializer. */
+  dependencies: string[];
+  /** 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: string[];
+}
+
+/**
+ * Explicitly create environment.yml using the local host's filesystem authority.
+ * Returns its filesystem-canonical absolute path. Rejects existing files/symlinks.
+ * Checks for environment.yaml first; hosts must coordinate other writers of it.
+ * Does not install packages, approve trust, contact a daemon or change a kernel.
+ */
+export function initializeEnvironmentYml(options: InitializeEnvironmentYmlOptions): Promise<string>;
+
 export function createNotebook(options?: CreateNotebookOptions): Promise<Session>;
 export function openNotebook(notebookId: string, options?: OpenNotebookOptions): Promise<Session>;
 export function openNotebookPath(path: string, options?: OpenNotebookOptions): Promise<Session>;

package/src/relay.d.ts

@@ -32,6 +32,15 @@ export interface QueryDaemonOptions {
 
 export interface DaemonInfo {
   version: string;
+  /** Protocol support only. Missing on older native bindings; treat missing as false. */
+  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;
@@ -82,5 +91,9 @@ export function connectRelay(notebookId: string, options?: OpenRelayOptions): Pr
 export function defaultSocketPath(): string;
 /** Resolve a stable or nightly daemon endpoint independently of this package's build channel. */
 export function socketPathForChannel(channel: "stable" | "nightly"): string;
-/** Return null until the selected daemon is ready to answer pool requests. */
+/**
+ * Return null when metadata is unavailable. A responding incompatible daemon
+ * returns metadata with compatibilityError. This probe does not authenticate
+ * a process or guarantee compatibility of a later notebook connection.
+ */
 export function queryDaemonInfo(options?: QueryDaemonOptions): Promise<DaemonInfo | null>;

package/src/session.cjs

@@ -1,5 +1,6 @@
 "use strict";
 
+const { createNotebookExecutionStore } = require("./execution-store.cjs");
 const { Subject } = require("rxjs");
 const { parseJsonEvent } = require("./napi-observables.cjs");
 
@@ -7,7 +8,7 @@ class Session {
   constructor(nativeSession) {
     this._native = nativeSession;
     this._subscriptions = [];
-    this._executionView = emptyExecutionView();
+    this.executions = createNotebookExecutionStore();
     this._runtimeStateSubject = new Subject();
     this._executionTransitionsSubject = new Subject();
     this._executionViewChangesSubject = new Subject();
@@ -56,7 +57,7 @@ class Session {
       this._subscriptions.push(
         nativeSession.onExecutionViewChange((json) => {
           const changeset = parseJsonEvent(json);
-          applyExecutionViewChangeset(this._executionView, changeset);
+          this.executions.applyChangeset(changeset);
           this._executionViewChangesSubject.next(changeset);
         }),
       );
@@ -202,7 +203,11 @@ class Session {
   }
 
   getExecutionView() {
-    return cloneExecutionView(this._executionView);
+    return this.executions.getSnapshot();
+  }
+
+  confirmNotebookSync() {
+    return this._native.confirmNotebookSync();
   }
 
   close() {
@@ -233,71 +238,6 @@ function normalizeDependencyOptions(options) {
   return { packageManager: options.packageManager };
 }
 
-function emptyExecutionView() {
-  return {
-    cell_execution_ids: {},
-    executions: {},
-    queue: null,
-  };
-}
-
-function applyExecutionViewChangeset(view, changeset) {
-  for (const [cellId, executionId] of changeset?.cell_pointer_changes ?? []) {
-    if (executionId == null) {
-      delete view.cell_execution_ids[cellId];
-    } else {
-      view.cell_execution_ids[cellId] = executionId;
-    }
-  }
-
-  for (const [executionId, snapshot] of changeset?.execution_upserts ?? []) {
-    view.executions[executionId] = cloneExecutionSnapshot(snapshot);
-  }
-
-  for (const executionId of changeset?.removed_execution_ids ?? []) {
-    delete view.executions[executionId];
-  }
-
-  if (Object.hasOwn(changeset ?? {}, "queue")) {
-    view.queue = cloneQueueProjection(changeset.queue ?? null);
-  }
-}
-
-function cloneExecutionView(view) {
-  return {
-    cell_execution_ids: { ...view.cell_execution_ids },
-    executions: Object.fromEntries(
-      Object.entries(view.executions).map(([executionId, snapshot]) => [
-        executionId,
-        cloneExecutionSnapshot(snapshot),
-      ]),
-    ),
-    queue: cloneQueueProjection(view.queue),
-  };
-}
-
-function cloneExecutionSnapshot(snapshot) {
-  return {
-    ...snapshot,
-    output_ids: Array.from(snapshot?.output_ids ?? []),
-  };
-}
-
-function cloneQueueProjection(queue) {
-  if (queue == null) return null;
-  return {
-    executing_execution_id: queue.executing_execution_id ?? null,
-    queued_execution_ids: Array.from(queue.queued_execution_ids ?? []),
-    notebook:
-      queue.notebook == null
-        ? queue.notebook
-        : {
-            executing_cell_id: queue.notebook.executing_cell_id ?? null,
-            queued_cell_ids: Array.from(queue.notebook.queued_cell_ids ?? []),
-          },
-  };
-}
-
 module.exports = {
   Session,
 };