@punica/editor 1.0.6 → 1.0.8

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

@@ -0,0 +1,246 @@
+/// <reference path="./punica.module.ivy.d.ts" />
+
+/**
+ * Multi-Runtime Test Harness Type Definitions
+ *
+ * Defines the contract for testing execution safety guarantees
+ * (timeout/retry/concurrency/rate-limit/cancel) across different runtimes.
+ */
+
+declare module 'punica' {
+  export namespace runtime {
+    export namespace harness {
+      /**
+       * Runtime adapter interface for test harness.
+       * Implemented by JS/TS dev runtime and Python runtime gateway.
+       */
+      export interface RuntimeAdapter {
+        /**
+         * Runtime identifier (e.g., "js-ts-dev", "python-jeg").
+         */
+        id: string;
+
+        /**
+         * Execute a capability through this runtime.
+         *
+         * @param capabilityId - Capability identifier
+         * @param input - Input payload
+         * @param executionDefaults - Capability execution defaults
+         * @param executionOverride - Optional workflow node override
+         * @param runBudget - Optional run-level budget
+         * @returns Promise resolving to output
+         */
+        execute(
+          capabilityId: string,
+          input: unknown,
+          executionDefaults?: CapabilityExecutionDefaults,
+          executionOverride?: ivy.ExecutionOverride,
+          runBudget?: ivy.RunBudget
+        ): Promise<unknown>;
+
+        /**
+         * Cancel a running execution.
+         *
+         * @param runId - Run identifier
+         * @param mode - Cancellation mode
+         */
+        cancel(runId: string, mode: ivy.CancellationMode): Promise<void>;
+
+        /**
+         * Get execution events for a run.
+         *
+         * @param runId - Run identifier
+         * @returns Async iterable of execution events
+         */
+        getExecutionEvents(runId: string): AsyncIterable<ivy.ExecutionEvent>;
+      }
+
+      /**
+       * Golden scenario definition.
+       * Represents a test case with deterministic inputs and expected outcomes.
+       */
+      export interface GoldenScenario {
+        /**
+         * Scenario identifier.
+         */
+        id: string;
+
+        /**
+         * Human-readable description.
+         */
+        description: string;
+
+        /**
+         * Capability identifier to test.
+         */
+        capabilityId: string;
+
+        /**
+         * Input payload.
+         */
+        input: unknown;
+
+        /**
+         * Execution defaults to apply.
+         */
+        executionDefaults?: CapabilityExecutionDefaults;
+
+        /**
+         * Execution override to apply.
+         */
+        executionOverride?: ivy.ExecutionOverride;
+
+        /**
+         * Run budget constraints.
+         */
+        runBudget?: ivy.RunBudget;
+
+        /**
+         * Expected outcome.
+         */
+        expected: {
+          /**
+           * Whether execution should succeed.
+           */
+          ok: boolean;
+
+          /**
+           * Expected output (if ok is true).
+           */
+          output?: unknown;
+
+          /**
+           * Expected error message pattern (if ok is false).
+           */
+          errorPattern?: string;
+
+          /**
+           * Expected execution events (ordered).
+           */
+          events?: Array<{
+            type: ivy.ExecutionEvent['type'];
+            [key: string]: unknown;
+          }>;
+
+          /**
+           * Expected execution duration range (milliseconds).
+           */
+          durationMs?: {
+            min?: number;
+            max?: number;
+          };
+        };
+      }
+
+      /**
+       * Test result for a scenario run.
+       */
+      export interface ScenarioResult {
+        /**
+         * Scenario identifier.
+         */
+        scenarioId: string;
+
+        /**
+         * Runtime adapter identifier.
+         */
+        runtimeId: string;
+
+        /**
+         * Whether the scenario passed.
+         */
+        ok: boolean;
+
+        /**
+         * Actual output (if execution succeeded).
+         */
+        output?: unknown;
+
+        /**
+         * Actual error (if execution failed).
+         */
+        error?: {
+          message: string;
+          code?: string;
+        };
+
+        /**
+         * Actual execution events.
+         */
+        events: ivy.ExecutionEvent[];
+
+        /**
+         * Actual execution duration (milliseconds).
+         */
+        durationMs: number;
+
+        /**
+         * Validation errors (if any).
+         */
+        validationErrors?: string[];
+      }
+
+      /**
+       * Harness test runner interface.
+       */
+      export interface HarnessRunner {
+        /**
+         * Run a scenario against a runtime adapter.
+         *
+         * @param scenario - Scenario to run
+         * @param adapter - Runtime adapter to test
+         * @returns Test result
+         */
+        runScenario(
+          scenario: GoldenScenario,
+          adapter: RuntimeAdapter
+        ): Promise<ScenarioResult>;
+
+        /**
+         * Run multiple scenarios against multiple adapters.
+         *
+         * @param scenarios - Scenarios to run
+         * @param adapters - Runtime adapters to test
+         * @returns Test results
+         */
+        runScenarios(
+          scenarios: GoldenScenario[],
+          adapters: RuntimeAdapter[]
+        ): Promise<ScenarioResult[]>;
+      }
+
+      /**
+       * Predefined golden scenario factory functions for common safety guarantee tests.
+       */
+      export interface ScenarioFactories {
+        /**
+         * Timeout scenario: capability should timeout after specified duration.
+         */
+        timeout: (timeoutMs: number) => GoldenScenario;
+
+        /**
+         * Retry scenario: capability should retry on transient errors.
+         */
+        retry: (maxAttempts: number, initialDelayMs: number) => GoldenScenario;
+
+        /**
+         * Concurrency scenario: multiple concurrent executions should respect limits.
+         */
+        concurrency: (
+          maxConcurrent: number,
+          numExecutions: number
+        ) => GoldenScenario;
+
+        /**
+         * Rate limit scenario: executions should be rate-limited.
+         */
+        rateLimit: (perSecond: number, numExecutions: number) => GoldenScenario;
+
+        /**
+         * Cancellation scenario: execution should be cancellable.
+         */
+        cancellation: (mode: ivy.CancellationMode) => GoldenScenario;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,272 @@
+declare module 'punica' {
+  export namespace runtime {
+    export namespace host {
+      /**
+       * Filesystem surface scoped to the host's data directory (see
+       * `HostApi.dataDir`), distinct from the workspace-scoped `runtime.fs`.
+       * Paths may be absolute (under the data dir) or relative to it; the host
+       * rejects anything that escapes the data-dir root. `list`/`stat` return
+       * absolute paths so callers can persist a stable pointer.
+       *
+       * This exists so heavy artifacts (model weights, dataset files) can live
+       * OUTSIDE the workspace while the workspace `.punica` index keeps only an
+       * absolute pointer — `runtime.fs` stays strictly workspace-scoped.
+       */
+      /** A byte range within a fixed-stride record, for `readStrided`. */
+      export interface StridedSlice {
+        /** Byte offset of the slice within a single record. */
+        offset: number;
+        /** Slice length in bytes. */
+        length: number;
+      }
+
+      /**
+       * Instruction for `readStrided`: a mechanical, format-agnostic gather over
+       * a fixed-stride binary file. The host reads sequentially from `start`,
+       * walks records of `stride` bytes, and for every `keepEvery`-th record
+       * (up to `count` records) copies the requested `slices` into the output.
+       * It carries no knowledge of what the bytes mean — callers (e.g. a
+       * point-cloud viewer) own all format semantics.
+       */
+      export interface StridedReadOptions {
+        /** Byte offset where the first record begins. */
+        start: number;
+        /** Size of one record in bytes. */
+        stride: number;
+        /** Keep every Nth record (1 = keep all). */
+        keepEvery: number;
+        /** Byte ranges to copy out of each kept record. */
+        slices: StridedSlice[];
+        /** Total number of records to walk before stopping. */
+        count: number;
+      }
+
+      export interface HostDataFs {
+        /** List entries under `path` (relative to the data dir, or absolute). */
+        list(path?: string, opts?: ListOptions): Promise<FileEntry[]>;
+        /**
+         * Read a file's contents. Text files are returned as UTF-8; common image
+         * types are returned as a `data:` URL so viewers can render them without
+         * a binary surface. Large files are refused (callers should not read
+         * multi-GB blobs as text). Enables in-app preview of data-dir files.
+         */
+        readFile(path: string): Promise<string>;
+        /**
+         * Read a raw byte range from a data-dir file. Unlike `readFile` this
+         * returns binary and never refuses by size (the range is bounded by
+         * `length`). Lets callers read headers / chunks of large binary files.
+         * Optional: only hosts with a real filesystem (Electron) provide it.
+         */
+        readBytes?(
+          path: string,
+          offset: number,
+          length: number
+        ): Promise<ArrayBuffer>;
+        /**
+         * Mechanically gather a decimated subset of a fixed-stride binary file
+         * (see `StridedReadOptions`). Format-agnostic — used e.g. by the LIDAR
+         * viewer to downsample multi-GB point clouds without moving the whole
+         * file across IPC. Optional: Electron-only; a browser host omits it.
+         */
+        readStrided?(
+          path: string,
+          opts: StridedReadOptions
+        ): Promise<ArrayBuffer>;
+        /** Per-path metadata (size, timestamps, kind). */
+        stat(path: string): Promise<FileStat>;
+        /** Create a directory, recursive by default (`mkdir -p`). */
+        mkdir(path: string, opts?: MkdirOptions): Promise<void>;
+        /** Delete a single file. */
+        deleteFile(path: string): Promise<void>;
+        /** Delete a folder (recursive). */
+        deleteFolder(path: string): Promise<void>;
+      }
+
+      /** Options for launching a managed, long-running local server process. */
+      export interface HostServerStartOptions {
+        /** Executable / command to spawn (e.g. a model server binary). */
+        command: string;
+        /** Command-line arguments. */
+        args?: string[];
+        /** Working directory for the spawned process. */
+        cwd?: string;
+        /** Extra environment variables merged over the host environment. */
+        env?: Record<string, string>;
+        /**
+         * Optional readiness probe. When set, `start` resolves only once an
+         * HTTP GET to this URL gets any response, or rejects (and the process
+         * is killed) once `readyTimeoutMs` elapses. Lets engine plugins wait for
+         * the server's HTTP endpoint without cross-origin fetches from the
+         * renderer (the probe runs in the host/main process).
+         */
+        readyProbeUrl?: string;
+        /** Readiness timeout in ms (default host-defined, e.g. 60000). */
+        readyTimeoutMs?: number;
+      }
+
+      /** Handle to a started managed server process. */
+      export interface HostServerHandle {
+        /** Host-assigned id; pass to `stop`/`status`. */
+        id: string;
+        /** OS process id, when known. */
+        pid: number | null;
+      }
+
+      /** Liveness of a managed server process. */
+      export interface HostServerStatus {
+        id: string;
+        running: boolean;
+        pid: number | null;
+      }
+
+      /**
+       * Engine-neutral managed-process surface: start/stop/inspect a
+       * long-running local server (e.g. a model inference server). The host does
+       * NOT know what engine it runs — it only spawns the command, tracks the
+       * child, optionally waits for an HTTP readiness probe, and kills it on
+       * `stop`. This is the generic execution primitive `ModelRuntime` adapters
+       * use (see docs/model-runtimes.md §2.4, §9): engine specifics stay in the
+       * plugin; lifecycle ownership stays in the host. Distinct from
+       * `runtime.tasks.run` (which runs a command to completion and returns no
+       * handle, so it cannot manage a persistent server).
+       */
+      export interface HostServerApi {
+        /** Spawn a managed server; optionally wait for `readyProbeUrl`. */
+        start(opts: HostServerStartOptions): Promise<HostServerHandle>;
+        /** Stop (kill) a managed server by id. No-op if already gone. */
+        stop(id: string): Promise<void>;
+        /** Report whether the managed server is still running. */
+        status(id: string): Promise<HostServerStatus>;
+      }
+
+      /** A JSON-over-HTTP request executed in the host (main) process. */
+      export interface HostHttpJsonRequest {
+        /** HTTP method (default 'GET'). */
+        method?: 'GET' | 'POST';
+        /** Absolute URL (e.g. a local model server endpoint). */
+        url: string;
+        /** Extra request headers (merged over `Content-Type: application/json`). */
+        headers?: Record<string, string>;
+        /** Request body; JSON-serialized when present. */
+        body?: unknown;
+        /** Request timeout in ms (default host-defined). */
+        timeoutMs?: number;
+      }
+
+      /** Response from a `requestJson` call. */
+      export interface HostHttpJsonResponse {
+        /** HTTP status code. */
+        status: number;
+        /** Parsed JSON body (or null when the body was empty/non-JSON). */
+        json: unknown;
+      }
+
+      /**
+       * Engine-neutral JSON-over-HTTP surface executed in the host (main)
+       * process. Model-runtime plugins use it to talk to a local inference
+       * server's OpenAI-compatible endpoints (e.g. POST `/v1/embeddings`) — the
+       * renderer cannot safely fetch the local endpoint directly (same reason
+       * the chat path routes through host IPC). The host does NOT know what
+       * engine/task it serves; it only performs the HTTP request. Provided by
+       * hosts with network access (Electron); a browser host may omit it, in
+       * which case the facade throws a clear error on use.
+       */
+      export interface HostHttpApi {
+        requestJson(req: HostHttpJsonRequest): Promise<HostHttpJsonResponse>;
+      }
+
+      /** Options for starting the inbound MCP server listener. */
+      export interface HostMcpServerStartOptions {
+        /** Transport to expose. `stdio` requires the bridge CLI + an http listener. */
+        transport: 'http' | 'stdio';
+        /** TCP port for the http transport (host picks a default when omitted). */
+        port?: number;
+      }
+
+      /** Liveness/address of the inbound MCP server listener. */
+      export interface HostMcpServerStatus {
+        running: boolean;
+        transport?: 'http' | 'stdio';
+        port?: number;
+        /** Base URL clients connect to (http transport). */
+        url?: string;
+        /**
+         * Absolute path of the stdio bridge CLI on the host machine. Clients
+         * spawn it (`node <bridgePath> --port <port>`) to reach the http
+         * listener over a stdio transport. Resolved by the host for both dev
+         * and packaged builds; omitted when the host cannot resolve it.
+         */
+        bridgePath?: string;
+      }
+
+      /** An inbound MCP JSON-RPC request forwarded from the transport. */
+      export interface HostMcpServerRequest {
+        /** Correlation id; echo it back via `reply`. */
+        requestId: string;
+        /** The parsed JSON-RPC request object. */
+        payload: unknown;
+      }
+
+      /**
+       * Engine-neutral INBOUND MCP server surface (Electron only). Opens a local
+       * listener (http on 127.0.0.1, or stdio via a bridge CLI) that accepts MCP
+       * JSON-RPC from external clients (Claude Desktop, inspector). Because the
+       * capability gateway lives in the renderer, the host forwards each inbound
+       * request to the renderer via `onRequest` and writes the renderer's
+       * `reply` back to the transport. The host owns only the socket/stdio
+       * framing; all protocol + governance logic stays in the renderer/extension
+       * (see docs/projection-conformance.md §6/§7 D1). Hosts without Node
+       * (browser) omit this; the facade throws a clear error on use.
+       *
+       * HTTP endpoint contract (matches the substrate MCP client transport):
+       * `GET /` info probe · `GET /sse` event stream returning an
+       * `mcp-session-id` header · `POST /messages` JSON-RPC answered in the
+       * response body (bare `POST /` accepted for the stdio bridge).
+       */
+      export interface HostMcpServerApi {
+        /** Start the listener for the given transport. */
+        start(opts: HostMcpServerStartOptions): Promise<HostMcpServerStatus>;
+        /** Stop the listener. No-op if not running. */
+        stop(): Promise<void>;
+        /** Current listener state. */
+        status(): Promise<HostMcpServerStatus>;
+        /** Subscribe to inbound MCP requests. Returns an unsubscribe fn. */
+        onRequest(handler: (req: HostMcpServerRequest) => void): () => void;
+        /** Reply to a forwarded request (`null` response = no reply written). */
+        reply(requestId: string, response: unknown): void;
+      }
+
+      /**
+       * Host-injected surface for the host's persistent data directory — the
+       * place for large artifacts that must NOT pollute the workspace. Provided
+       * by hosts that have a real filesystem (Electron); a browser host may not
+       * inject this, in which case the facade throws a clear error on use.
+       */
+      export interface HostApi {
+        /**
+         * Absolute path to the host data directory root, created on first use.
+         * Subtrees (`models/`, `datasets/`, ...) are created lazily by callers
+         * via `dataFs.mkdir`.
+         */
+        dataDir(): Promise<string>;
+        /** Filesystem surface scoped to the data directory. */
+        dataFs: HostDataFs;
+        /**
+         * Optional managed-process surface (Electron). Hosts that cannot spawn
+         * processes (browser) omit it; the facade throws a clear error on use.
+         */
+        servers?: HostServerApi;
+        /**
+         * Optional JSON-over-HTTP surface (Electron). Hosts without network
+         * access omit it; the facade throws a clear error on use.
+         */
+        http?: HostHttpApi;
+        /**
+         * Optional inbound MCP server surface (Electron). Hosts that cannot open
+         * a local listener (browser) omit it; the facade throws on use.
+         */
+        mcpServer?: HostMcpServerApi;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,164 @@
+/// <reference path="punica.module.runtime.models.d.ts" />
+/// <reference path="punica.module.runtime.modelRuntimes.d.ts" />
+/// <reference path="punica.module.runtime.llm.d.ts" />
+
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Task-general inference consumption surface (Phase 7b). The local-model
+     * substrate runs more than chat: embeddings / vision / ASR / rerank. Chat
+     * stays on `runtime.llm.chat({ route: 'local' })`; every OTHER task goes
+     * through `runtime.inference.infer(req)`, which dispatches to the engine that
+     * owns the started handle (`handle.runtimeId` -> `ModelRuntime.infer`).
+     *
+     * Requests/responses are a discriminated union on `task` so vision/ASR slot
+     * in later (7c) without changing the dispatcher. See docs/model-runtimes.md
+     * §9.2.
+     */
+    export namespace inference {
+      /** Common fields for every inference request. */
+      interface InferRequestBase {
+        /**
+         * Handle of a started runtime (from `runtime.modelRuntimes.start`). The
+         * dispatcher routes to its owning engine via `handle.runtimeId`.
+         */
+        handle: modelRuntimes.LocalRuntimeHandle;
+        /** Optional concrete model id hint (engine-specific). */
+        modelId?: string;
+        /** Optional correlation id for auditing/tracing. */
+        correlationId?: string;
+      }
+
+      /** Embeddings request — one vector per input text. */
+      export interface EmbeddingsInferRequest extends InferRequestBase {
+        task: 'embeddings';
+        /** Texts to embed; vectors are returned in the same order. */
+        input: string[];
+      }
+
+      /** Rerank request — score `documents` by relevance to `query`. */
+      export interface RerankInferRequest extends InferRequestBase {
+        task: 'rerank';
+        /** The search query the documents are scored against. */
+        query: string;
+        /** Candidate documents to score/rank. */
+        documents: string[];
+        /** Optional cap on how many ranked results to return. */
+        topN?: number;
+      }
+
+      /**
+       * Speech-to-text (ASR) request. Audio is carried base64-encoded in JSON
+       * (transported via `runtime.host.http`), so no binary/multipart host path
+       * is needed; targets local servers that accept JSON-base64 audio. See
+       * docs/model-runtimes.md §9.5.
+       */
+      export interface SpeechToTextInferRequest extends InferRequestBase {
+        task: 'speech-to-text';
+        /** Base64-encoded audio bytes. */
+        audio: string;
+        /** Container/codec hint, e.g. 'wav' | 'mp3' | 'flac'. */
+        format?: string;
+        /** Optional BCP-47 language hint (e.g. 'tr', 'en'). */
+        language?: string;
+      }
+
+      /**
+       * Vision (image understanding) request — caption / visual Q&A on a single
+       * image. The image is carried base64-in-JSON; the ONNX runtime builds an
+       * OpenAI vision request (a `data:` image URL inside chat-completions
+       * content — the OpenAI standard), so no binary host path is needed. See
+       * docs/model-runtimes.md §9.5.
+       */
+      export interface VisionInferRequest extends InferRequestBase {
+        task: 'vision';
+        /** Base64-encoded image bytes. */
+        image: string;
+        /** Image MIME type for the data URL (default 'image/png'). */
+        mimeType?: string;
+        /** Optional instruction; defaults to a generic "describe this image". */
+        prompt?: string;
+      }
+
+      /**
+       * Discriminated union of inference requests. Embeddings (7b) + rerank +
+       * speech-to-text + vision (7c).
+       */
+      export type InferRequest =
+        | EmbeddingsInferRequest
+        | RerankInferRequest
+        | SpeechToTextInferRequest
+        | VisionInferRequest;
+
+      /** Embeddings response — one vector per input text, input order. */
+      export interface EmbeddingsInferResponse {
+        task: 'embeddings';
+        vectors: number[][];
+        modelId?: string;
+        provider?: string;
+        usage?: LlmUsage;
+      }
+
+      /** A single reranked document: its original index + relevance score. */
+      export interface RerankResult {
+        /** Index into the request's `documents` array. */
+        index: number;
+        /** Relevance score (higher = more relevant; engine-defined scale). */
+        score: number;
+      }
+
+      /**
+       * Rerank response — `results` ordered most-relevant-first (or as the
+       * engine returns them), each pointing back at the original document index.
+       */
+      export interface RerankInferResponse {
+        task: 'rerank';
+        results: RerankResult[];
+        modelId?: string;
+        provider?: string;
+        usage?: LlmUsage;
+      }
+
+      /** Speech-to-text response — the transcribed text. */
+      export interface SpeechToTextInferResponse {
+        task: 'speech-to-text';
+        text: string;
+        /** Detected/used language, when the engine reports it. */
+        language?: string;
+        modelId?: string;
+        provider?: string;
+        usage?: LlmUsage;
+      }
+
+      /** Vision response — the model's text answer about the image. */
+      export interface VisionInferResponse {
+        task: 'vision';
+        text: string;
+        modelId?: string;
+        provider?: string;
+        usage?: LlmUsage;
+      }
+
+      /** Discriminated union of inference responses. */
+      export type InferResponse =
+        | EmbeddingsInferResponse
+        | RerankInferResponse
+        | SpeechToTextInferResponse
+        | VisionInferResponse;
+
+      /**
+       * Inference dispatcher facade surfaced as `runtime.inference`. Routes a
+       * request to the engine that owns `req.handle`, validating the engine
+       * exposes `infer` and supports the requested task.
+       */
+      export interface InferenceApi {
+        /**
+         * Run a non-chat inference task on a started local runtime. Throws if
+         * the owning runtime is not registered, does not implement `infer`, or
+         * does not support `req.task`.
+         */
+        infer(req: InferRequest): Promise<InferResponse>;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,15 @@
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * High-level lifecycle phases for the Punica workbench / host.
+     */
+    export type LifecyclePhase =
+      | 'bootstrapping'
+      | 'coreReady'
+      | 'noWorkspace'
+      | 'workspaceLoading'
+      | 'workbenchReady'
+      | 'background'
+      | 'shutdown';
+  }
+}