@punica/editor 1.0.6 → 1.0.8

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

@@ -0,0 +1,254 @@
+declare module 'punica' {
+  export namespace runtime {
+    export namespace models {
+      /**
+       * Model provider identifier (e.g., "huggingface", "bedrock", "local").
+       */
+      export type ModelProviderId = string;
+
+      /**
+       * Model task types supported by the runtime.
+       */
+      export type ModelTask =
+        | 'text-generation'
+        | 'chat'
+        | 'embeddings'
+        | 'image-generation'
+        | 'speech-to-text'
+        | 'text-to-speech'
+        | 'rerank'
+        | 'vision';
+
+      /**
+       * On-disk weight format of a local model. Drives runtime dispatch
+       * (see docs/model-runtimes.md). 'unknown' means detection was
+       * inconclusive and the dispatcher must decide or error.
+       */
+      export type ModelFormat = 'gguf' | 'safetensors' | 'onnx' | 'unknown';
+
+      /**
+       * Reference to a model in a specific provider.
+       */
+      export interface ModelRef {
+        /**
+         * Provider identifier (e.g., "huggingface", "bedrock", "local").
+         */
+        provider: ModelProviderId;
+        /**
+         * Model identifier within the provider.
+         * Examples:
+         * - HuggingFace: "meta-llama/Llama-3.1-8B-Instruct"
+         * - Bedrock: "anthropic.claude-3-5-sonnet-20241022-v2:0"
+         * - Local: file path or identifier
+         */
+        id: string;
+        /**
+         * Optional revision/version identifier.
+         * - HuggingFace: git SHA/tag
+         * - Local: hash
+         */
+        revision?: string;
+        /**
+         * Model task type.
+         */
+        task: ModelTask;
+      }
+
+      /**
+       * Metadata about a model.
+       */
+      export interface ModelMetadata {
+        /**
+         * Reference to the model.
+         */
+        ref: ModelRef;
+        /**
+         * Human-readable name.
+         */
+        name: string;
+        /**
+         * Optional context window size (in tokens).
+         */
+        contextWindow?: number;
+        /**
+         * Optional supported modalities.
+         */
+        modalities?: Array<'text' | 'image' | 'audio'>;
+        /**
+         * Optional pricing information.
+         */
+        pricing?: {
+          unit: 'per_1k_tokens' | 'per_second' | 'per_image';
+          input?: number;
+          output?: number;
+        };
+        /**
+         * Optional limits and constraints.
+         */
+        limits?: {
+          maxInputTokens?: number;
+          maxOutputTokens?: number;
+          rateLimitPerMin?: number;
+        };
+      }
+
+      /**
+       * A mounted model that is accessible via a canonical endpoint.
+       */
+      export interface ModelHandle {
+        /**
+         * Reference to the model.
+         */
+        ref: ModelRef;
+        /**
+         * Canonical endpoint for accessing the model in compute/llm contexts.
+         * Format: "punica://model/{provider}/{id}"
+         */
+        endpoint: string;
+        /**
+         * Authentication mode for the model endpoint.
+         * - 'host': Host handles authentication (e.g., Electron with API keys)
+         * - 'provider': Provider handles authentication (e.g., Bedrock with AWS credentials)
+         * - 'none': No authentication required
+         */
+        authMode?: 'host' | 'provider' | 'none';
+      }
+
+      /**
+       * Options for mounting a model.
+       */
+      export interface MountOptions {
+        /**
+         * Authentication mode for the model endpoint.
+         */
+        authMode?: 'host' | 'provider' | 'none';
+      }
+
+      /**
+       * Options for listing models.
+       */
+      export interface ListOptions {
+        /**
+         * Optional task filter.
+         */
+        task?: ModelTask;
+        /**
+         * Optional search query.
+         */
+        query?: string;
+      }
+
+      /**
+       * Model provider interface (implemented by extensions).
+       */
+      export interface ModelProvider {
+        /**
+         * Unique provider identifier.
+         */
+        id: ModelProviderId;
+        /**
+         * Resolve model metadata from a reference.
+         */
+        resolve(ref: ModelRef): Promise<ModelMetadata>;
+        /**
+         * Mount a model and return a canonical endpoint for access.
+         */
+        mount(ref: ModelRef, opts?: MountOptions): Promise<ModelHandle>;
+        /**
+         * Unmount a model by endpoint.
+         */
+        unmount(endpoint: string): Promise<void>;
+        /**
+         * List available models from this provider.
+         */
+        list(opts?: ListOptions): Promise<ModelMetadata[]>;
+      }
+
+      /**
+       * Registry for model providers.
+       */
+      export interface ModelRegistry {
+        /**
+         * Register a model provider.
+         */
+        registerProvider(provider: ModelProvider): void;
+        /**
+         * Get a provider by ID.
+         */
+        getProvider(id: ModelProviderId): ModelProvider | undefined;
+        /**
+         * List all registered providers.
+         */
+        listProviders(): ModelProvider[];
+      }
+
+      /**
+       * Main models API surface.
+       */
+      export interface ModelsApi {
+        /**
+         * Resolve model metadata from a reference.
+         */
+        resolve(ref: ModelRef): Promise<ModelMetadata>;
+        /**
+         * Mount a model and return a canonical endpoint for access.
+         */
+        mount(ref: ModelRef, opts?: MountOptions): Promise<ModelHandle>;
+        /**
+         * Unmount a model by endpoint.
+         */
+        unmount(endpoint: string): Promise<void>;
+        /**
+         * List available models.
+         * If provider is specified, only lists from that provider.
+         * Otherwise, aggregates results from all providers.
+         */
+        list(opts?: {
+          provider?: ModelProviderId;
+          task?: ModelTask;
+          query?: string;
+        }): Promise<ModelMetadata[]>;
+        /**
+         * Registry for providers.
+         */
+        registry: ModelRegistry;
+      }
+
+      /**
+       * Local storage format for workspace models.
+       * Used by LocalModelProvider for .punica/models.json
+       */
+      export interface LocalModelRecord {
+        id: string;
+        provider: string;
+        name: string;
+        identifier: string;
+        task: ModelTask;
+        contextWindow?: number;
+        modalities?: Array<'text' | 'image' | 'audio'>;
+        description?: string;
+        createdAt?: string;
+        updatedAt?: string;
+        filePath?: string;
+        /**
+         * Directory holding a multi-file model (ONNX/genai: model.onnx +
+         * external data + tokenizer + genai_config.json). When set, runtimes
+         * prefer it over `filePath` (which assumes a single weights file).
+         */
+        dirPath?: string;
+        /** Detected on-disk weight format; drives runtime dispatch. */
+        format?: ModelFormat;
+        /** Resolved runtime id (e.g. "gguf"); set by the dispatcher. */
+        runtime?: string;
+      }
+
+      /**
+       * Index file format for local models storage.
+       */
+      export interface LocalModelsIndexFile {
+        version?: number;
+        models?: LocalModelRecord[];
+      }
+    }
+  }
+}

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

@@ -0,0 +1,59 @@
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Search capability models.
+     */
+    interface SearchMatch {
+      line: number;
+      col: number;
+      text: string;
+      cell_idx?: number | null;
+      cell_line?: number | null;
+      cell_id?: string | null;
+      cell_type?: string | null;
+    }
+
+    interface SearchFileResult {
+      file: string;
+      matchCount: number;
+      matches: SearchMatch[];
+    }
+
+    interface SearchResponse {
+      results: SearchFileResult[];
+    }
+
+    interface SearchQueryOptions {
+      q: string;
+      limit?: number;
+      /** Exact-case matching. Default false (index is case-insensitive). */
+      caseSensitive?: boolean;
+      /** Match whole words only. Default false. */
+      wholeWord?: boolean;
+      /** Treat `q` as a regular expression (bypasses the FTS index). Default false. */
+      isRegex?: boolean;
+      /** Glob of paths to include (e.g. "src/**"). Default all. */
+      include?: string;
+      /** Comma-separated globs of paths to exclude. */
+      exclude?: string;
+    }
+
+    /**
+     * Search capability: workspace-wide full-text search and index management.
+     */
+    interface SearchApi {
+      /**
+       * Execute a text search against the workspace index.
+       */
+      query(options: SearchQueryOptions): Promise<SearchResponse>;
+
+      /**
+       * (Optional) Trigger a full or incremental index operation.
+       * Implementations may ignore this if indexing is managed externally.
+       */
+      startIndex?(options?: {
+        verbose?: boolean;
+      }): Promise<void | { addedOrUpdated: number; removed: number }>;
+    }
+  }
+}

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

@@ -0,0 +1,26 @@
+declare module 'punica' {
+  export namespace runtime {
+    export type SecretName = string;
+
+    export interface SecretRecord {
+      name: SecretName;
+      createdAtMs: number;
+      updatedAtMs: number;
+    }
+
+    /**
+     * Minimal secrets API (v1 MVP).
+     *
+     * Notes:
+     * - In-memory only (no vault/persistence).
+     * - Intended primarily for preventing secrets from leaking in trace exports
+     *   and enabling simple { secretRef } resolution for capabilities.
+     */
+    export interface SecretsApi {
+      set(name: SecretName, value: string): void;
+      get(name: SecretName): string | null;
+      delete(name: SecretName): boolean;
+      list(): SecretRecord[];
+    }
+  }
+}

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

@@ -0,0 +1,27 @@
+declare module 'punica' {
+  export namespace runtime {
+    export interface TaskRunRequest {
+      command: string;
+      args?: string[];
+      cwd?: string;
+      env?: Record<string, string>;
+    }
+
+    export interface TaskRunResult {
+      exitCode: number | null;
+      stdout: string;
+      stderr: string;
+    }
+
+    /**
+     * Host-backed task runner capability.
+     *
+     * This is intentionally small and separate from kernel.Tasks (which models
+     * task definitions/runs). Here we only expose a "run a command" primitive
+     * suitable for capabilities like `tasks.run`.
+     */
+    export interface TaskRunnerApi {
+      run(request: TaskRunRequest): Promise<TaskRunResult>;
+    }
+  }
+}

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

@@ -0,0 +1,67 @@
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Version control (Git) capability models.
+     * These are intentionally minimal and based on simple-git / service-version-control-system responses.
+     */
+    interface VcsStatusSummary {
+      current: string | null;
+      tracking?: string | null;
+      ahead?: number;
+      behind?: number;
+      staged: string[];
+      modified: string[];
+      created: string[];
+      deleted: string[];
+      renamed: string[];
+      conflicted: string[];
+      not_added: string[];
+    }
+
+    interface VcsBranch {
+      name: string;
+      current: boolean;
+    }
+
+    interface VcsCommit {
+      hash: string;
+      date: string;
+      message: string;
+      authorName?: string;
+      authorEmail?: string;
+    }
+
+    /**
+     * Version control capability: high-level Git operations for the workspace repository.
+     */
+    interface VcsApi {
+      status(): Promise<VcsStatusSummary>;
+      branches(): Promise<VcsBranch[]>;
+      logs(options?: { limit?: number }): Promise<VcsCommit[]>;
+
+      init(options?: { defaultBranch?: string }): Promise<void>;
+      clone(options: {
+        url: string;
+        directory?: string;
+        branch?: string;
+      }): Promise<void>;
+
+      commit(options: { message: string; all?: boolean }): Promise<void>;
+      stage(paths: string[]): Promise<void>;
+      unstage(paths: string[]): Promise<void>;
+      discard(paths: string[]): Promise<void>;
+      reset(options?: { hard?: boolean; commit?: string }): Promise<void>;
+
+      switchBranch(name: string): Promise<void>;
+      createBranch(name: string, checkout?: boolean): Promise<void>;
+
+      fetch(options?: { remote?: string; branch?: string }): Promise<void>;
+      pull(options?: { remote?: string; branch?: string }): Promise<void>;
+      push(options?: {
+        remote?: string;
+        branch?: string;
+        setUpstream?: boolean;
+      }): Promise<void>;
+    }
+  }
+}

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

@@ -0,0 +1,74 @@
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Local vector index — a small, product-neutral similarity store. It pairs
+     * with `runtime.inference` embeddings to close the RAG gap: callers embed
+     * text (or images) into vectors, `upsert` them here, then `query` by a vector
+     * to retrieve the nearest records (cosine). It is a PURE vector store — it
+     * never computes embeddings itself, so it stays engine-agnostic. See
+     * docs/model-runtimes.md §9.8.
+     *
+     * The default substrate implementation is in-memory with best-effort
+     * persistence to `.punica/vectors/<collection>.json`; a host may inject a
+     * real vector DB via `setVectorsProvider`.
+     */
+    export namespace vectors {
+      /** A stored vector plus the payload returned on a match. */
+      export interface VectorRecord {
+        /** Stable id; re-upserting the same id replaces the record. */
+        id: string;
+        /** The embedding vector. */
+        vector: number[];
+        /** Optional original text (returned on matches; handy for RAG). */
+        text?: string;
+        /** Optional arbitrary metadata (returned on matches). */
+        metadata?: Record<string, unknown>;
+      }
+
+      /** A nearest-neighbour query. */
+      export interface VectorQuery {
+        /** Query vector to score every stored record against. */
+        vector: number[];
+        /** Max matches to return, best-first (default 10). */
+        topK?: number;
+        /** Collection to search (default 'default'). */
+        collection?: string;
+      }
+
+      /** A single query match. */
+      export interface VectorMatch {
+        id: string;
+        /** Cosine similarity in [-1, 1] (higher = more similar). */
+        score: number;
+        text?: string;
+        metadata?: Record<string, unknown>;
+      }
+
+      /** Options selecting a collection for a mutation. */
+      export interface CollectionOptions {
+        /** Collection name (default 'default'). */
+        collection?: string;
+      }
+
+      /**
+       * Vector index surface (`runtime.vectors`). Collections are independent
+       * namespaces within the store.
+       */
+      export interface VectorsApi {
+        /** Insert or replace records (by id) in a collection. */
+        upsert(
+          records: VectorRecord[],
+          opts?: CollectionOptions
+        ): Promise<void>;
+        /** Return the `topK` nearest records to `q.vector`, best-first. */
+        query(q: VectorQuery): Promise<VectorMatch[]>;
+        /** Remove records by id from a collection. */
+        delete(ids: string[], opts?: CollectionOptions): Promise<void>;
+        /** Remove every record from a collection. */
+        clear(opts?: CollectionOptions): Promise<void>;
+        /** Number of records in a collection. */
+        count(opts?: CollectionOptions): Promise<number>;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,134 @@
+declare module 'punica' {
+  export namespace runtime {
+    export type WorkspaceId = string;
+    export type EnvironmentId = string;
+    export type ResourceId = string;
+
+    export type WorkspaceKind = 'code' | 'data' | 'ml' | 'mono' | 'custom';
+
+    export interface Environment {
+      id: EnvironmentId;
+      name: string;
+      description?: string;
+      /**
+       * Environment-scoped variables. The host is responsible for mapping these
+       * to real process/env or remote runtime variables.
+       */
+      variables?: Record<string, string>;
+      /**
+       * Default bindings for this environment (e.g. default database, dataset).
+       */
+      bindings?: Record<string, ResourceId>;
+    }
+
+    export interface WorkspaceSummary {
+      id: WorkspaceId;
+      name: string;
+      kind: WorkspaceKind;
+      /**
+       * Workspace root URI understood by the host (e.g. file://, git://, s3://).
+       */
+      rootUri: string;
+      /**
+       * Last active environment id, if any.
+       */
+      currentEnvironmentId?: EnvironmentId;
+      tags?: string[];
+    }
+
+    export interface Workspace extends WorkspaceSummary {
+      environments: Environment[];
+      /**
+       * Resource identifiers associated with this workspace. Detailed metadata
+       * is retrieved via the ResourcesApi.
+       */
+      resourceIds?: ResourceId[];
+      metadata?: Record<string, unknown>;
+    }
+
+    export type ResourceKind =
+      | 'dataset'
+      | 'service'
+      | 'secret'
+      | 'agent'
+      | 'flow'
+      | 'notebook'
+      | 'config'
+      | 'custom';
+
+    export interface Resource {
+      id: ResourceId;
+      kind: ResourceKind;
+      name: string;
+      /**
+       * Logical location of the resource within the workspace (path, URI, etc.).
+       */
+      uri?: string;
+      /**
+       * Type-specific metadata (schema, owner, region, model id, etc.).
+       */
+      metadata?: Record<string, unknown>;
+      tags?: string[];
+      workspaceId?: WorkspaceId;
+    }
+
+    export interface WorkspaceApi {
+      /**
+       * Returns the currently active workspace with full details, or null when
+       * no workspace is open.
+       */
+      getCurrent(): Promise<Workspace | null>;
+      /**
+       * Lists all known workspaces on this host/installation.
+       */
+      list(): Promise<WorkspaceSummary[]>;
+      /**
+       * Switches to another workspace. Hosts control how this is implemented
+       * (e.g. opening a new window, reloading, etc.).
+       */
+      open(id: WorkspaceId): Promise<Workspace>;
+      /**
+       * Changes the active environment for the given workspace.
+       */
+      setEnvironment(
+        workspaceId: WorkspaceId,
+        envId: EnvironmentId
+      ): Promise<Workspace>;
+      /**
+       * Subscribe to workspace changes. Returns an unsubscribe function.
+       */
+      onDidChange(listener: (workspace: Workspace | null) => void): () => void;
+    }
+
+    export interface ResourcesQuery {
+      kinds?: ResourceKind[];
+      workspaceId?: WorkspaceId;
+      tags?: string[];
+      text?: string;
+    }
+
+    export interface ResourcesApi {
+      /**
+       * Lists resources matching the optional query filters.
+       */
+      list(query?: ResourcesQuery): Promise<Resource[]>;
+      /**
+       * Returns a single resource by id, or null when not found.
+       */
+      get(id: ResourceId): Promise<Resource | null>;
+      /**
+       * Allows extensions to register logical resources that they own or
+       * manage. Hosts may choose to persist these or derive them dynamically.
+       */
+      register(resource: Resource): void;
+      /**
+       * Unregister a previously registered resource.
+       */
+      unregister(id: ResourceId): void;
+      /**
+       * Subscribe to resource catalog changes. Returns an unsubscribe function.
+       */
+      onDidChange(listener: () => void): () => void;
+    }
+  }
+}

package/types/punica.module.shell.activityBar.d.ts

@@ -0,0 +1,42 @@
+declare module 'punica' {
+  export namespace shell {
+    export namespace ActivityBar {
+      type Alignment = 'primary' | 'secondary';
+      type ItemType = 'normal' | 'menu';
+
+      interface IItem {
+        id: string;
+        name: string;
+        alignment: Alignment;
+        title: string;
+        icon: string;
+        /**
+         * Optional command to execute when the activity bar item is clicked.
+         * This is typically a lightweight "open/focus" command that can
+         * trigger lazy activation via `onCommand:<id>` if needed.
+         */
+        command?: string;
+        /**
+         * Optional logical view id this activity item controls (e.g. the
+         * primarySidebar view id from `.punica/config.yaml`). When provided,
+         * the core can automatically show/hide the correct sidebar host.
+         */
+        viewId?: string;
+      }
+
+      interface IActivityBarManager {
+        addItem(item: IItem): void;
+        removeItem(itemId: string): void;
+        /**
+         * Optional helper for hosts/core to sync ActivityBar selection with the
+         * currently visible primarySidebar view. When a view id is provided,
+         * the manager should mark the corresponding item (if any) as active.
+         * Passing null clears the current selection.
+         */
+        setActiveByViewId?(viewId: string | null): void;
+      }
+
+      export const manager: IActivityBarManager;
+    }
+  }
+}