@punica/editor 1.0.5 → 1.0.7

package/types/punica.module.runtime.llm.d.ts

@@ -0,0 +1,470 @@
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * User-facing quality profile. Providers are free to map these to concrete
+     * models / quantizations / routing policies.
+     */
+    export type LlmProfile = 'fast' | 'balanced' | 'accurate';
+
+    export type LlmRole = 'system' | 'user' | 'assistant' | 'tool';
+
+    export type LlmRoutePreference = 'auto' | 'local' | 'remote';
+
+    export interface LlmMessage {
+      role: LlmRole;
+      content: string;
+      name?: string;
+      /**
+       * Tool calls requested by an assistant turn (substrate shape). Set when
+       * replaying an assistant message that invoked tools back to the model on
+       * the next agent-loop iteration. The host transport encodes these to the
+       * vendor wire format (OpenAI `tool_calls`, Anthropic `tool_use`, …).
+       * Strict remote APIs require this so a following tool-role message can be
+       * correlated via `toolCallId`.
+       */
+      toolCalls?: ToolCall[];
+      /**
+       * For a `role: 'tool'` result message — the id of the assistant tool call
+       * this result answers. Encoded to the vendor `tool_call_id` field. Lenient
+       * local servers ignore it; strict remote APIs (OpenAI) require it.
+       */
+      toolCallId?: string;
+    }
+
+    /**
+     * Substrate-neutral prompt-cache hints. The substrate states WHAT is
+     * stable about the request; hosts translate to vendor wire syntax
+     * (Anthropic `cache_control`, OpenAI `prompt_cache_key`, llama.cpp
+     * `cache_prompt`). Vendors without prompt caching ignore the hints —
+     * the deterministic ordering the hints assume still helps implicit
+     * KV-cache reuse on local servers.
+     */
+    export interface LlmCacheHints {
+      /**
+       * The `tools` array and system prompt are byte-stable for the
+       * lifetime of `cacheKey` — safe to cache as a prefix.
+       */
+      stableToolsAndSystem?: boolean;
+      /**
+       * Number of leading messages guaranteed identical to the previous
+       * request with the same `cacheKey` (the cached conversation
+       * prefix). 0 on the first request of a run; grows monotonically as
+       * the caller appends — and resets after history compaction rewrites
+       * the prefix.
+       */
+      stableMessagePrefix?: number;
+      /**
+       * Cache routing key — requests sharing it target the same cached
+       * prefix (typically the run/conversation correlation id).
+       */
+      cacheKey?: string;
+      /** TTL preference; vendors ignore when unsupported. */
+      ttl?: '5m' | '1h';
+    }
+
+    export interface LlmChatRequest {
+      messages: LlmMessage[];
+      profile?: LlmProfile;
+      temperature?: number;
+      maxTokens?: number;
+      /**
+       * Optional correlation id used for auditing and tracing.
+       */
+      correlationId?: string;
+      /**
+       * Optional routing preference. When set to 'remote', the runtime may need
+       * explicit user approval (Policy kind = "llm.remote").
+       */
+      route?: LlmRoutePreference;
+      /**
+       * Optional provider identifier (e.g. "remote:openai", "local:llama.cpp").
+       * Used for policy scoping and audit.
+       */
+      providerId?: string;
+      /**
+       * Optional response format. When set to 'json_object', the LLM is instructed
+       * to return valid JSON. Used for structured output.
+       */
+      responseFormat?: 'json_object' | 'text';
+      /**
+       * Optional concrete model identifier hint.
+       * When set, providers may use this to select a specific expert model
+       * (e.g. a particular local GGUF or remote model family/size).
+       */
+      modelId?: string;
+      /**
+       * Optional list of concrete model identifiers for multi-expert scenarios.
+       * The runtime/capability layer is responsible for orchestrating multiple
+       * calls; providers typically receive one modelId at a time.
+       */
+      modelIds?: string[];
+      /**
+       * Optional substrate-side tool catalog for AI tool calling.
+       * Providers translate this to vendor-specific tool/function-call format
+       * (OpenAI functions, Anthropic tool_use, native JSON schema, etc.).
+       * The set of tools an AI can invoke during this chat turn.
+       */
+      tools?: ToolDef[];
+      /**
+       * Optional tool-call control:
+       *  - 'auto'  : provider decides when to call tools (default)
+       *  - 'none'  : never call tools (text-only response)
+       *  - 'required' : must call at least one tool
+       *  - { type: 'tool'; name: string } : force a specific tool
+       */
+      toolChoice?: ToolChoice;
+      /**
+       * Optional cancellation signal (Faz 0b Stop/iptal). When the caller aborts
+       * the signal, the runtime stops consuming the provider stream and host
+       * adapters should abort the in-flight request (fetch/SDK). Carried on the
+       * request because the host `LlmApi` only receives the request object;
+       * inside the gateway the same signal travels on `InvocationContext.signal`.
+       */
+      signal?: AbortSignal;
+      /**
+       * Optional prompt-cache hints (see LlmCacheHints). Set by callers
+       * whose request prefix is deterministic across turns (the agent
+       * loop); translated to vendor syntax host-side.
+       */
+      cacheHints?: LlmCacheHints;
+    }
+
+    export interface LlmUsage {
+      inputTokens?: number;
+      outputTokens?: number;
+      totalTokens?: number;
+      /**
+       * Input tokens served from the vendor's prompt cache (Anthropic
+       * `cache_read_input_tokens`, OpenAI `prompt_tokens_details.cached_tokens`).
+       * A subset of `inputTokens`; billed at the vendor's reduced cache-read
+       * rate. Absent when the vendor reports no cache activity.
+       */
+      cacheReadInputTokens?: number;
+      /**
+       * Input tokens written to the vendor's prompt cache this call
+       * (Anthropic `cache_creation_input_tokens`). Absent when the vendor
+       * reports no cache activity.
+       */
+      cacheCreationInputTokens?: number;
+    }
+
+    export interface LlmChatResponse {
+      text: string;
+      modelId?: string;
+      provider?: string; // e.g. "local", "remote:openai", etc.
+      usage?: LlmUsage;
+      raw?: unknown;
+      /**
+       * Optional accountability metadata describing this concrete call.
+       * Populated by the substrate's LLM perimeter; useful for cost
+       * reporting, fallback chain tracing, and audit events.
+       */
+      meta?: LlmCallMeta;
+      /**
+       * Optional tool calls emitted by the assistant in this response.
+       * Each entry is the unified substrate ToolCall shape (vendor
+       * formats are normalized by the provider). Empty / undefined
+       * means a plain text response.
+       */
+      toolCalls?: ToolCall[];
+    }
+
+    /**
+     * Substrate-side tool / capability declaration shape passed to an LLM
+     * provider. Providers translate to vendor-specific formats internally.
+     */
+    export interface ToolDef {
+      /**
+       * Stable capability identifier (matches the entry in the Trinity
+       * capability registry, e.g. "fs.readFile", "llm.plan",
+       * "ivy.node.echo").
+       */
+      name: string;
+      /**
+       * Human-readable description of what the tool does. Surfaced to
+       * the LLM as part of the tool catalog prompt.
+       */
+      description: string;
+      /**
+       * Input JSON Schema. Providers convert this to their native
+       * tool-parameter schema (OpenAI function parameters, Anthropic
+       * tool input_schema, etc.).
+       */
+      parameters: JSONSchema;
+    }
+
+    /**
+     * Tool-call control directive sent to the provider. Mirrors common
+     * vendor semantics (OpenAI tool_choice, Anthropic tool_choice).
+     */
+    export type ToolChoice =
+      | 'auto'
+      | 'none'
+      | 'required'
+      | { type: 'tool'; name: string };
+
+    /**
+     * Unified tool call emitted by the LLM. Substrate providers normalize
+     * vendor formats (OpenAI function_call / tool_calls, Anthropic
+     * tool_use, native JSON) to this single shape.
+     */
+    export interface ToolCall {
+      /**
+       * Provider-supplied call id (used to correlate tool result messages
+       * back to the originating call when streamed).
+       */
+      id: string;
+      /**
+       * Capability id the LLM wants to invoke. Matches ToolDef.name.
+       */
+      name: string;
+      /**
+       * Arguments object the LLM produced. Substrate-side validation
+       * (matching ToolDef.parameters) happens in the runtime layer
+       * before dispatch through the gateway.
+       */
+      arguments: Record<string, unknown>;
+    }
+
+    /**
+     * Accountability metadata for a concrete LLM call. Populated by the
+     * substrate's perimeter; surfaced via response.meta, the `llm.call`
+     * kernel event, and the cost.report capability.
+     */
+    export interface LlmCallMeta {
+      /**
+       * Provider id that actually served the request (e.g. "anthropic",
+       * "openai", "ollama", "local:llama.cpp", "litellm-proxy"). May
+       * differ from the requested providerId when fallback advances.
+       */
+      provider: string;
+      /**
+       * Concrete model id the provider used (e.g. "claude-sonnet-4-6",
+       * "gpt-4o", "llama3:70b-q4_K_M").
+       */
+      model: string;
+      promptTokens: number;
+      completionTokens: number;
+      /**
+       * Total cost of this call in USD. Computed from the host-injected
+       * pricing table (`setLlmPricingTable`). Zero for substrate-only
+       * paths (MockLlmProvider) and when no pricing is configured.
+       */
+      totalCost: number;
+      latencyMs: number;
+      /**
+       * True when the response was served from a substrate-side cache
+       * (semantic or deterministic) without hitting the provider.
+       */
+      cacheHit?: boolean;
+      /**
+       * Zero-indexed position in the fallback chain that served this
+       * call. 0 = primary provider served; >0 = fallback advanced.
+       * Undefined when the call did not go through a fallback chain.
+       */
+      fallbackChainPosition?: number;
+    }
+
+    /**
+     * Streaming chunk emitted by `LlmProvider.chatStream`. The variants
+     * form a discriminated union on `type`.
+     *
+     * `thinking` carries the model's reasoning trace (e.g. Anthropic
+     * extended thinking `thinking_delta`), kept on a separate channel
+     * from `content` so consumers can render it in a distinct,
+     * collapsible surface. Providers that do not expose a reasoning
+     * channel simply never emit it — consumers must feature-detect and
+     * hide the surface rather than fabricate one.
+     */
+    export type LlmChunk =
+      | { type: 'content'; text: string }
+      | { type: 'thinking'; text: string }
+      | { type: 'tool_call'; toolCall: ToolCall }
+      | { type: 'done'; response: LlmChatResponse }
+      | { type: 'error'; error: { code: string; message: string } };
+
+    export interface EmbedRequest {
+      /**
+       * Texts to embed. Providers may batch internally; substrate does
+       * not impose a per-request size limit but hosts may.
+       */
+      texts: string[];
+      /**
+       * Optional concrete embedder model identifier (e.g.
+       * "text-embedding-3-small"). Host-specific.
+       */
+      modelId?: string;
+    }
+
+    export interface EmbedResponse {
+      /**
+       * One vector per input text, in the same order as `texts`.
+       */
+      vectors: number[][];
+      modelId?: string;
+      provider?: string;
+      usage?: LlmUsage;
+      meta?: LlmCallMeta;
+    }
+
+    /**
+     * Provider capability surface flags. A provider advertises which
+     * features it supports; the substrate uses this set to decide what
+     * it can dispatch through a given provider (and to pick fallbacks
+     * when a request requires a feature the primary does not have).
+     */
+    export type LlmProviderCapability =
+      | 'chat'
+      | 'complete'
+      | 'embed'
+      | 'image'
+      | 'tool-use'
+      | 'streaming'
+      | 'thinking';
+
+    /**
+     * Substrate-pure LLM provider abstraction.
+     *
+     * Hosts (Electron, browser) implement this interface and inject
+     * concrete providers via the runtime registry. The substrate itself
+     * ships only `MockLlmProvider` (fixture-driven, no network); real
+     * HTTP/IPC adapters (Anthropic, OpenAI, Ollama, LiteLLM, etc.) live
+     * in host territory. Neutrality is proven by multi-shape fixture
+     * conformance, not by a single reference implementation.
+     */
+    export interface LlmProvider {
+      /**
+       * Stable provider identifier (e.g. "anthropic", "openai",
+       * "ollama-local", "litellm-proxy", "mock"). Used in policy
+       * scoping, audit events, and provider-invariant tracking.
+       */
+      id: string;
+      /**
+       * Set of capabilities this provider exposes. Substrate consults
+       * this to gate which dispatches the provider can serve.
+       */
+      capabilities: Set<LlmProviderCapability>;
+      chat(req: LlmChatRequest): Promise<LlmChatResponse>;
+      /**
+       * Streaming chat. Optional — providers that don't support
+       * streaming should omit this and not advertise the 'streaming'
+       * capability flag.
+       */
+      chatStream?(req: LlmChatRequest): AsyncIterable<LlmChunk>;
+      /**
+       * Embedding generation. Optional — providers that don't support
+       * embeddings should omit this and not advertise the 'embed'
+       * capability flag.
+       */
+      embed?(req: EmbedRequest): Promise<EmbedResponse>;
+    }
+
+    /**
+     * Provider specification entry used inside a fallback chain. Each
+     * entry names a provider id (must be registered) plus optional
+     * per-spec model override; the substrate's fallback state machine
+     * advances through `attempts` of these.
+     */
+    export interface ProviderSpec {
+      providerId: string;
+      modelId?: string;
+    }
+
+    /**
+     * Fallback policy: how the substrate's fallback state machine reacts
+     * to each terminal signal coming from a provider. The substrate
+     * recognizes three signals; hosts choose how each maps to behavior.
+     *
+     *  - 'next'  : advance to the next ProviderSpec in the chain
+     *  - 'fail'  : terminate the call with the last error
+     *  - 'queue' : flag the call for later retry (substrate sets the
+     *              `pendingQueue` state; an actual queue mechanism lives
+     *              in the host)
+     */
+    export interface FallbackPolicy {
+      onError?: 'next' | 'fail' | 'queue';
+      onTimeout?: 'next' | 'fail' | 'queue';
+      onRateLimit?: 'next' | 'fail' | 'queue';
+    }
+
+    /**
+     * LLM model metadata (catalog record).
+     * Mirrors host-side model catalogs (Electron).
+     */
+    export interface LlmModel {
+      id: string;
+      family: string;
+      parameters: string;
+      variant?: string;
+      quant?: string;
+      sizeBytes: number;
+      minRamGb?: number;
+      minVramGb?: number | null;
+      profiles?: LlmProfile[];
+      license?: string;
+      downloadUrls?: string[];
+      sha256?: string;
+      fileName?: string;
+    }
+
+    export interface InstalledLlmModel {
+      id: string;
+      filePath: string;
+      installedAtMs: number;
+    }
+
+    export interface LlmModelManagerState {
+      activeModelId: string | null;
+      installed: InstalledLlmModel[];
+    }
+
+    export interface LocalLlmServerStatus {
+      running: boolean;
+      host: string;
+      port: number;
+      url: string | null;
+    }
+
+    /**
+     * Optional host-provided LLM manager API.
+     * Electron typically provides this via IPC (window.api.llm.*) and the runtime
+     * exposes it as a facade under runtime.llm.manager.
+     */
+    export interface LlmManagerApi {
+      listModels(opts?: { profile?: LlmProfile }): Promise<LlmModel[]>;
+      listInstalled(): Promise<LlmModelManagerState>;
+      setActiveModel(modelId: string | null): Promise<void>;
+      removeModel(modelId: string): Promise<void>;
+      downloadModel(modelId: string): Promise<void>;
+      pickModelFile(): Promise<{ canceled: boolean; path?: string }>;
+      importModelFile(opts: {
+        modelId: string;
+        sourcePath: string;
+        fileName?: string;
+      }): Promise<void>;
+      localServerStatus(): Promise<LocalLlmServerStatus>;
+      startLocalServer(opts?: {
+        host?: string;
+        port?: number;
+      }): Promise<LocalLlmServerStatus>;
+      stopLocalServer(): Promise<void>;
+    }
+
+    export interface LlmApi {
+      chat(req: LlmChatRequest): Promise<LlmChatResponse>;
+      /**
+       * Optional streaming chat. Hosts that back a streaming-capable
+       * provider expose it here; the substrate runtime facade wraps it
+       * with the same remote-policy gating as `chat`. When absent, the
+       * substrate falls back to a single-shot `chat` surfaced as one
+       * `content` + `done` chunk, so streaming consumers keep working
+       * (without live tokens) against non-streaming hosts.
+       */
+      chatStream?(req: LlmChatRequest): AsyncIterable<LlmChunk>;
+      /**
+       * Optional manager API (Electron).
+       */
+      manager?: LlmManagerApi;
+    }
+  }
+}

package/types/punica.module.runtime.mcp.d.ts

@@ -0,0 +1,139 @@
+declare module 'punica' {
+  namespace runtime {
+    namespace mcp {
+      type McpTransportKind = 'stdio' | 'streamable-http' | 'sse';
+
+      interface McpStdioConfig {
+        kind: 'stdio';
+        /** CLI command to spawn (e.g. "npx"). */
+        command: string;
+        args?: string[];
+        /** Extra environment variables injected into the child process. */
+        env?: Record<string, string>;
+      }
+
+      interface McpHttpConfig {
+        kind: 'streamable-http' | 'sse';
+        url: string;
+        headers?: Record<string, string>;
+      }
+
+      type McpTransportConfig = McpStdioConfig | McpHttpConfig;
+
+      interface McpServerConfig extends McpTransportConfig {
+        /** Unique server identifier — used as the `mcp.<id>.<tool>` capability namespace. */
+        id: string;
+        /** Human-readable display name (optional; falls back to id). */
+        name?: string;
+      }
+
+      interface McpToolInfo {
+        name: string;
+        description?: string;
+        /** JSON Schema for the tool's input object. */
+        inputSchema: JSONSchema;
+        /** Punica-specific overrides embedded in MCP `_meta.punica`. */
+        _meta?: JSONObject;
+      }
+
+      interface McpServerHandle {
+        readonly serverId: string;
+        readonly transportKind: McpTransportKind;
+        /** Tool list at the time of connection (or after last tools/list refresh). */
+        readonly tools: McpToolInfo[];
+        /** Disconnect this server and unregister all its capabilities. */
+        disconnect(): Promise<void>;
+      }
+
+      type McpTrafficDirection = 'outbound' | 'inbound';
+
+      /**
+       * Payload of the `mcp.request` / `mcp.response` kernel events.
+       *
+       * Every JSON-RPC exchange with an MCP server is published as a
+       * request/response pair matched by `callId` (also stamped as
+       * `envelope.correlationId`). Emitters:
+       * - `runtime:mcp:client` — outbound traffic to connected servers
+       *   (all methods, including the initialize/tools-list handshake);
+       * - `extension:ivy-mcp-server` — inbound traffic from external
+       *   MCP clients served by the editor (`transport: 'host'`).
+       *
+       * Bodies are pretty-printed JSON truncated to 16 384 chars
+       * (`truncated: true`, `*Bytes` = untruncated size). Token counts
+       * are estimates from the kernel token estimator. Notifications
+       * emit a single `mcp.request` with `kind: 'notification'` and no
+       * matching response. The event names deliberately avoid `.error`
+       * / `.failed` suffixes so the event store never persists bodies
+       * to disk; errors surface as `isError` + `envelope.kind: 'error'`.
+       */
+      interface McpTrafficEventPayload {
+        direction: McpTrafficDirection;
+        serverId: string;
+        serverName?: string;
+        transport?: McpTransportKind | 'host';
+        method: string;
+        /** Only set for `tools/call`. */
+        toolName?: string;
+        /** Pairing key between the request and response events. */
+        callId: string;
+        kind: 'request' | 'notification';
+        requestJson?: string;
+        requestBytes?: number;
+        requestTokens?: number;
+        responseJson?: string;
+        responseBytes?: number;
+        responseTokens?: number;
+        isError?: boolean;
+        errorMessage?: string;
+        durationMs?: number;
+        /** True when the body was cut at the 16 384-char cap. */
+        truncated?: boolean;
+      }
+
+      interface McpApi {
+        /**
+         * Connect to an MCP server, discover its tools, and register them
+         * as capabilities in the unified registry under the `mcp` origin.
+         *
+         * Fails with a descriptive error if transport cannot be established.
+         * Emits `capability.registered` for each discovered tool.
+         */
+        connect(config: McpServerConfig): Promise<McpServerHandle>;
+
+        /**
+         * Disconnect a previously connected server by its id.
+         * Unregisters all its capabilities and emits `capability.unregistered`.
+         * No-op if the server is not currently connected.
+         */
+        disconnect(serverId: string): Promise<void>;
+
+        /** List all currently connected MCP server handles. */
+        listServers(): McpServerHandle[];
+
+        /**
+         * List tools for a specific server (or all servers when omitted).
+         * Returns an empty array if the server is not connected.
+         */
+        listTools(serverId?: string): McpToolInfo[];
+
+        /**
+         * Directly invoke an MCP tool (bypasses the capability gateway).
+         * Prefer routing through the gateway via `capability.call()` for
+         * governance. This method is exposed for host-level diagnostics.
+         */
+        callTool(
+          serverId: string,
+          toolName: string,
+          args: JSONObject
+        ): Promise<JSONObject>;
+      }
+    }
+  }
+
+  namespace runtime {
+    interface RuntimeApi {
+      /** MCP server connection + tool-as-capability bridge. */
+      readonly mcp: runtime.mcp.McpApi;
+    }
+  }
+}

package/types/punica.module.runtime.modelRuntimes.d.ts

@@ -0,0 +1,90 @@
+/// <reference path="punica.module.runtime.models.d.ts" />
+/// <reference path="punica.module.runtime.inference.d.ts" />
+
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Local model execution seam. A `ModelRuntime` is a pluggable engine
+     * (GGUF / Transformers / ONNX / custom) that turns a `LocalModelRecord`
+     * into a running local API. The substrate owns only the abstraction +
+     * dispatch; the actual engine launch lives in the host/extension layer.
+     *
+     * See docs/model-runtimes.md (§2.1, §2.4).
+     */
+    export namespace modelRuntimes {
+      /**
+       * Handle to a started local runtime. `endpoint` is OpenAI-compatible
+       * (e.g. http://127.0.0.1:8080) and is what `runtime.llm.chat({ route:
+       * 'local' })` ultimately talks to. `runtimeId` identifies the owning
+       * runtime so the dispatcher can route `stop` back to it.
+       */
+      export interface LocalRuntimeHandle {
+        endpoint: string;
+        runtimeId: string;
+        /**
+         * Tasks this started runtime can serve (e.g. ['text-generation',
+         * 'embeddings']). Lets `runtime.inference` consumers know what a handle
+         * supports before calling `infer`. See docs/model-runtimes.md §9.2.
+         */
+        tasks?: models.ModelTask[];
+        /**
+         * Host-assigned managed-process id, when the runtime spawned its server
+         * via `runtime.host.servers` (so `stop` can target the exact process).
+         */
+        serverId?: string;
+      }
+
+      /**
+       * A pluggable local model execution engine. Constructed eagerly;
+       * `punica.*` must only be dereferenced lazily inside method bodies
+       * (mirrors the facade lazy-init invariant).
+       */
+      export interface ModelRuntime {
+        /** Stable id, e.g. "gguf", "transformers", "onnx". */
+        id: string;
+        /** Format-based dispatch test against a model record. */
+        canRun(record: models.LocalModelRecord): boolean;
+        /** Start the engine for this record and return a live endpoint. */
+        start(record: models.LocalModelRecord): Promise<LocalRuntimeHandle>;
+        /**
+         * Stop a handle previously returned by `start`. Handle-scoped (not
+         * global) so multiple live models can be stopped independently.
+         */
+        stop(handle: LocalRuntimeHandle): Promise<void>;
+        /**
+         * Optional task-general inference for non-chat tasks (embeddings /
+         * vision / ASR / rerank). Engines that only serve chat omit this; the
+         * `runtime.inference` dispatcher errors clearly when a runtime lacks it
+         * or does not support the requested task. Chat/text-generation stays on
+         * `runtime.llm.chat({ route: 'local' })`. See docs/model-runtimes.md §9.2.
+         */
+        infer?(req: inference.InferRequest): Promise<inference.InferResponse>;
+      }
+
+      /**
+       * Registry of available `ModelRuntime` engines. The dispatcher selects
+       * the first runtime whose `canRun(record)` is true.
+       */
+      export interface ModelRuntimeRegistry {
+        register(runtime: ModelRuntime): void;
+        get(id: string): ModelRuntime | undefined;
+        list(): ModelRuntime[];
+        /** First registered runtime whose `canRun(record)` is true. */
+        select(record: models.LocalModelRecord): ModelRuntime | undefined;
+      }
+
+      /**
+       * Dispatcher facade surfaced on the runtime namespace. Picks a runtime
+       * for a record and starts it; routes `stop` back to the owning runtime
+       * via `handle.runtimeId`.
+       */
+      export interface ModelRuntimesApi {
+        registry: ModelRuntimeRegistry;
+        /** Select a runtime for `record` and start it. Throws if none match. */
+        start(record: models.LocalModelRecord): Promise<LocalRuntimeHandle>;
+        /** Stop via the runtime that owns `handle`. Throws if unregistered. */
+        stop(handle: LocalRuntimeHandle): Promise<void>;
+      }
+    }
+  }
+}