lumiverse-spindle-types 0.4.44 → 0.4.45

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "lumiverse-spindle-types",
-  "version": "0.4.44",
+  "version": "0.4.45",
   "types": "./src/index.ts",
   "keywords": [
     "lumiverse",

package/src/api.ts

@@ -1169,6 +1169,96 @@ export interface FrontendProcessStopOptionsDTO {
   reason?: string;
 }
 
+// ─── Backend Process Lifecycle DTOs ─────────────────────────────────────
+
+/** High-level lifecycle state for an isolated backend subprocess tracked by the host. */
+export type BackendProcessStateDTO =
+  | "starting"
+  | "running"
+  | "stopping"
+  | "stopped"
+  | "completed"
+  | "failed"
+  | "timed_out";
+
+/** Terminal reason attached to backend-process lifecycle events and snapshots when available. */
+export type BackendProcessExitReasonDTO =
+  | "completed"
+  | "failed"
+  | "stopped"
+  | "timed_out"
+  | "backend_unloaded"
+  | "replaced";
+
+/** Options used when spawning an isolated backend subprocess from the backend worker. */
+export interface BackendProcessSpawnOptionsDTO {
+  /** Built JS entry file under the extension repo, typically in `dist/`. */
+  entry: string;
+  /** Optional logical label used for lifecycle filtering and dedupe semantics. Defaults to `entry`. */
+  kind?: string;
+  /** Optional extension-defined stable key used for dedupe / replacement semantics. */
+  key?: string;
+  /** Optional process-scoped startup payload delivered to the subprocess entry. */
+  payload?: unknown;
+  /** Arbitrary metadata stored alongside the process snapshot for backend bookkeeping. */
+  metadata?: Record<string, unknown>;
+  /** For operator-scoped extensions only. */
+  userId?: string;
+  /** Reject spawn if the subprocess does not call `process.ready()` within this window. */
+  startupTimeoutMs?: number;
+  /** Mark the subprocess timed out if it stops heartbeating for this long after ready. */
+  heartbeatTimeoutMs?: number;
+  /** Replace any existing process with the same `key` for the target user. */
+  replaceExisting?: boolean;
+}
+
+/** Filter used for backend subprocess list queries. */
+export interface BackendProcessListOptionsDTO {
+  userId?: string;
+  kind?: string;
+  key?: string;
+  state?: BackendProcessStateDTO;
+}
+
+/** Current host-tracked snapshot of an isolated backend subprocess. */
+export interface BackendProcessInfoDTO {
+  processId: string;
+  entry: string;
+  kind: string;
+  key?: string;
+  state: BackendProcessStateDTO;
+  userId?: string;
+  metadata?: Record<string, unknown>;
+  startedAt: string;
+  readyAt?: string;
+  lastHeartbeatAt?: string;
+  endedAt?: string;
+  exitReason?: BackendProcessExitReasonDTO;
+  error?: string;
+}
+
+/** Lifecycle event emitted to backend workers for isolated backend subprocesses. */
+export interface BackendProcessLifecycleEventDTO {
+  processId: string;
+  entry: string;
+  kind: string;
+  key?: string;
+  userId?: string;
+  state: BackendProcessStateDTO;
+  previousState?: BackendProcessStateDTO;
+  at: string;
+  exitReason?: BackendProcessExitReasonDTO;
+  error?: string;
+  metadata?: Record<string, unknown>;
+}
+
+/** Options for graceful isolated-backend-process termination. */
+export interface BackendProcessStopOptionsDTO {
+  userId?: string;
+  /** Optional reason surfaced to the subprocess stop handler. */
+  reason?: string;
+}
+
 // ─── Generation Event Payload DTOs ──────────────────────────────────────
 
 /** Payload for `GENERATION_STARTED` events. */
@@ -1735,6 +1825,12 @@ export type WorkerToHost =
   | { type: "frontend_process_get"; requestId: string; processId: string }
   | { type: "frontend_process_stop"; requestId: string; processId: string; options?: FrontendProcessStopOptionsDTO }
   | { type: "frontend_process_send"; processId: string; payload: unknown; userId?: string }
+  // ─── Backend Process Lifecycle (free tier) ────────────────────────────
+  | { type: "backend_process_spawn"; requestId: string; options: BackendProcessSpawnOptionsDTO }
+  | { type: "backend_process_list"; requestId: string; filter?: BackendProcessListOptionsDTO }
+  | { type: "backend_process_get"; requestId: string; processId: string }
+  | { type: "backend_process_stop"; requestId: string; processId: string; options?: BackendProcessStopOptionsDTO }
+  | { type: "backend_process_send"; processId: string; payload: unknown; userId?: string }
   // ─── Macro Resolution (free tier) ──────────────────────────────────
   | { type: "macros_resolve"; requestId: string; template: string; chatId?: string; characterId?: string; userId?: string; commit?: boolean }
   // ─── Image Generation (gated: "image_gen") ──────────────────────────
@@ -1853,6 +1949,8 @@ export type HostToWorker =
   | { type: "frontend_message"; payload: unknown; userId: string }
   | { type: "frontend_process_lifecycle"; event: FrontendProcessLifecycleEventDTO }
   | { type: "frontend_process_message"; processId: string; payload: unknown; userId: string }
+  | { type: "backend_process_lifecycle"; event: BackendProcessLifecycleEventDTO }
+  | { type: "backend_process_message"; processId: string; payload: unknown; userId: string }
   | {
       type: "oauth_callback";
       requestId: string;

package/src/index.ts

@@ -84,7 +84,14 @@ export type {
    FrontendProcessInfoDTO,
    FrontendProcessLifecycleEventDTO,
    FrontendProcessStopOptionsDTO,
-   GenerationStartedPayloadDTO,
+   BackendProcessStateDTO,
+   BackendProcessExitReasonDTO,
+   BackendProcessSpawnOptionsDTO,
+   BackendProcessListOptionsDTO,
+   BackendProcessInfoDTO,
+   BackendProcessLifecycleEventDTO,
+   BackendProcessStopOptionsDTO,
+    GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
   GenerationStoppedPayloadDTO,
@@ -145,7 +152,13 @@ export type {
 
 export type { ExtensionInfo } from "./extension-info";
 
-export type { SpindleAPI, FrontendProcessHandle } from "./spindle-api";
+export type {
+  SpindleAPI,
+  FrontendProcessHandle,
+  BackendProcessHandle,
+  SpindleBackendProcessContext,
+  SpindleBackendProcessModule,
+} from "./spindle-api";
 
 export type {
   CouncilMember,

package/src/spindle-api.ts

@@ -58,6 +58,11 @@ import type {
   FrontendProcessInfoDTO,
   FrontendProcessLifecycleEventDTO,
   FrontendProcessStopOptionsDTO,
+  BackendProcessSpawnOptionsDTO,
+  BackendProcessListOptionsDTO,
+  BackendProcessInfoDTO,
+  BackendProcessLifecycleEventDTO,
+  BackendProcessStopOptionsDTO,
   GenerationStartedPayloadDTO,
   StreamTokenPayloadDTO,
   GenerationEndedPayloadDTO,
@@ -92,6 +97,62 @@ export interface FrontendProcessHandle {
   refresh(): Promise<FrontendProcessInfoDTO | null>;
 }
 
+export interface BackendProcessHandle {
+  /** Host-assigned process ID unique within the extension runtime. */
+  readonly processId: string;
+  /** Built subprocess entry file spawned by the host. */
+  readonly entry: string;
+  /** Logical process kind used for filtering and dedupe semantics. */
+  readonly kind: string;
+  /** Optional extension-defined stable key. */
+  readonly key?: string;
+  /** Current known snapshot at the time the handle was created or last refreshed. */
+  readonly info: BackendProcessInfoDTO;
+  /** Send a process-scoped message to the isolated subprocess. */
+  send(payload: unknown): void;
+  /** Request graceful termination. */
+  stop(options?: BackendProcessStopOptionsDTO): Promise<void>;
+  /** Fetch the latest authoritative snapshot from the host. */
+  refresh(): Promise<BackendProcessInfoDTO | null>;
+}
+
+/** Controller passed to a backend subprocess entry exported by the extension. */
+export interface SpindleBackendProcessContext {
+  /** Host-assigned ID unique within the extension runtime. */
+  processId: string;
+  /** Built entry file the host spawned. */
+  entry: string;
+  /** Logical process kind supplied during spawn. */
+  kind: string;
+  /** Optional extension-defined stable key passed at spawn time. */
+  key?: string;
+  /** Arbitrary spawn payload provided by the parent backend runtime. */
+  payload: unknown;
+  /** Optional backend-side bookkeeping metadata snapshot. */
+  metadata?: Record<string, unknown>;
+  /** Target user for operator-scoped spawns. */
+  userId?: string;
+  /** Signal that startup completed successfully. Required for startup watchdogs. */
+  ready(): void;
+  /** Refresh the host-side heartbeat timer for long-lived loops. */
+  heartbeat(): void;
+  /** Send a process-scoped message back to the parent backend runtime. */
+  send(payload: unknown): void;
+  /** Subscribe to process-scoped messages from the parent backend runtime. */
+  onMessage(handler: (payload: unknown) => void): () => void;
+  /** Mark the subprocess as completed and release host tracking. */
+  complete(result?: unknown): void;
+  /** Mark the subprocess as failed. */
+  fail(error: string): void;
+  /** Called when the parent backend runtime requests graceful termination. */
+  onStop(handler: (detail: { reason?: string }) => void): () => void;
+}
+
+export type SpindleBackendProcessModule = {
+  default?: (process: SpindleBackendProcessContext) => void | (() => void) | Promise<void | (() => void)>;
+  run?: (process: SpindleBackendProcessContext) => void | (() => void) | Promise<void | (() => void)>;
+};
+
 /** The global `spindle` object available in backend extension workers */
 export interface SpindleAPI {
   /** Subscribe to generation-started events (requires `generation` permission). The optional `userId` identifies which user triggered the event. */
@@ -870,6 +931,36 @@ export interface SpindleAPI {
     ): () => void;
   };
 
+  /**
+   * Host-owned lifecycle controller for isolated backend subprocesses.
+   *
+   * Use this when one slice of backend extension logic may block or hang and
+   * you need the host to retain kill authority via startup and heartbeat
+   * watchdogs. The spawned entry receives a
+   * {@link SpindleBackendProcessContext} and communicates only with its parent
+   * backend runtime through process-scoped messages.
+   */
+  backendProcesses: {
+    /**
+     * Spawn an isolated backend subprocess and wait for the entry to call
+     * `process.ready()`. If `startupTimeoutMs` elapses first, the promise
+     * rejects and the process transitions to `timed_out`.
+     */
+    spawn(options: BackendProcessSpawnOptionsDTO): Promise<BackendProcessHandle>;
+    /** List tracked backend subprocesses visible to this extension runtime. */
+    list(filter?: BackendProcessListOptionsDTO): Promise<BackendProcessInfoDTO[]>;
+    /** Get a single tracked subprocess by ID. Returns `null` if it no longer exists. */
+    get(processId: string): Promise<BackendProcessInfoDTO | null>;
+    /** Request graceful termination of a tracked subprocess. */
+    stop(processId: string, options?: BackendProcessStopOptionsDTO): Promise<void>;
+    /** Subscribe to lifecycle transitions (`starting`, `running`, `timed_out`, etc.). */
+    onLifecycle(handler: (event: BackendProcessLifecycleEventDTO) => void): () => void;
+    /** Receive process-scoped messages sent from the subprocess entry. */
+    onMessage(
+      handler: (event: { processId: string; payload: unknown; userId: string }) => void,
+    ): () => void;
+  };
+
   /** Logging */
   log: {
     info(msg: string): void;