@punica/editor 1.0.6 → 1.0.7

package/types/punica.module.kernel.policy.d.ts

@@ -0,0 +1,273 @@
+declare module 'punica' {
+  export namespace kernel {
+    export type PolicyMode = 'suggest' | 'execute';
+    export type PolicyRisk = 'low' | 'medium' | 'high' | (string & {});
+    export type PolicyApproval = 'none' | 'plan' | 'step' | (string & {});
+    export type ApprovalScope = 'once' | 'workspace' | 'always';
+
+    export type ApprovalKey = string;
+
+    export interface PolicyRequest {
+      /**
+       * Logical kind of the guarded action (e.g. "capability", "llm.remote").
+       */
+      kind: string;
+      /**
+       * Identifier within the kind (e.g. capabilityId, providerId).
+       */
+      id: string;
+      risk: PolicyRisk;
+      approval: PolicyApproval;
+      /**
+       * Optional human-readable reason shown in UI prompts.
+       */
+      reason?: string;
+    }
+
+    /**
+     * Multi-stage approval chain primitives — Sub-step 3.L.
+     *
+     * An approval chain replaces a single approver with a small
+     * state machine. Three shapes:
+     *
+     *   - `sequential` — approvers must approve **in order**.
+     *     Approver[i+1] is only asked after approver[i] approves.
+     *     Any denial in the chain → full denial.
+     *   - `parallel`   — approvers are asked simultaneously.
+     *     Chain GRANTED when `quorum` (default = all) approvals
+     *     have landed; DENIED when so many denials have landed
+     *     that quorum is mathematically impossible.
+     *   - `single`     — degenerate one-approver chain (kept
+     *     in the union so callers can treat all approvals
+     *     uniformly).
+     *
+     * Substrate ships the type + state machine; the orchestrator
+     * (UI / host) drives which approver gets asked next + how the
+     * UI surfaces partial state. The substrate stays headless.
+     */
+
+    /**
+     * Logical approver — kept abstract so hosts can map `id` to
+     * user / role / group / OIDC subject / etc.
+     */
+    export interface ApproverSpec {
+      /** Substrate-opaque approver identifier. */
+      id: string;
+      /** Optional display label for UIs. */
+      label?: string;
+    }
+
+    /** A single approver's response on a chain. */
+    export interface ApproverDecision {
+      /** Approver id (must match an entry in the chain spec). */
+      approverId: string;
+      /** Approve / deny — chain consumes this on `recordChainDecision`. */
+      decision: 'approve' | 'deny';
+      /** Epoch ms when the approver decided. */
+      timestampMs: number;
+      /** Optional reason — surfaced in audit. */
+      reason?: string;
+    }
+
+    /** Chain-level outcome of `recordChainDecision`. */
+    export type ApprovalChainStatus = 'pending' | 'granted' | 'denied';
+
+    /** Discriminated union — every chain runs as one of these. */
+    export type ApprovalChainSpec =
+      | {
+          type: 'sequential';
+          approvers: readonly ApproverSpec[];
+        }
+      | {
+          type: 'parallel';
+          approvers: readonly ApproverSpec[];
+          /**
+           * Approvals required out of `approvers.length`. Default =
+           * all approvers (effectively unanimous parallel). Must be
+           * `1 <= quorum <= approvers.length`.
+           */
+          quorum?: number;
+        }
+      | {
+          type: 'single';
+          approver: ApproverSpec;
+        };
+
+    /** Snapshot of a running chain — read-only from the caller's POV. */
+    export interface ApprovalChainState {
+      /** Caller-supplied chain id; load-bearing for store lookups. */
+      chainId: string;
+      /** The shape the chain runs under (frozen at creation). */
+      spec: ApprovalChainSpec;
+      /** Decisions landed so far, in arrival order. */
+      decisions: readonly ApproverDecision[];
+      /** Current overall status. */
+      status: ApprovalChainStatus;
+    }
+
+    export interface ApprovalRecord {
+      key: ApprovalKey;
+      kind: string;
+      id: string;
+      scope: ApprovalScope;
+      workspaceId?: string;
+      risk: PolicyRisk;
+      approval: PolicyApproval;
+      reason?: string;
+      decidedBy?: string;
+      timestampMs: number;
+      /**
+       * Optional chain reference — Sub-step 3.L. When present,
+       * this approval landed as part of a multi-stage chain
+       * (`ApprovalChainState.chainId`). Audit consumers join
+       * record + chain state by this id.
+       */
+      chainRef?: string;
+      /**
+       * Time-bounded approvals — Sub-step 3.F. Epoch ms after which
+       * the approval is considered expired. `hasApproval` returns
+       * false once `Date.now() >= expiresAt`; `listApprovals`
+       * filters expired records by default (`{ includeExpired:
+       * true }` to retain them). Undefined = permanent approval
+       * (pre-3.F semantics preserved).
+       *
+       * The substrate stores the absolute epoch — callers compute
+       * `Date.now() + durationMs` for relative durations. UI
+       * preset durations (1 saat / 1 gün / kalıcı) live in host
+       * code, not substrate.
+       */
+      expiresAt?: number;
+    }
+
+    export interface PolicyDecision {
+      allowed: boolean;
+      mode: PolicyMode;
+      requiresApproval: boolean;
+      suggestedScope?: ApprovalScope;
+      reason?: string;
+    }
+
+    export interface PolicyApi {
+      setMode(mode: PolicyMode): void;
+      getMode(): PolicyMode;
+
+      evaluate(
+        req: PolicyRequest,
+        ctx?: { workspaceId?: string }
+      ): PolicyDecision;
+
+      requestApproval(
+        req: PolicyRequest,
+        ctx?: {
+          workspaceId?: string;
+          correlationId?: string;
+          /**
+           * Trace id of the invocation hitting the gate (an agent run id
+           * for agent-loop calls) — carried into the pending approval so
+           * waiters/UI can match a pending to its run.
+           */
+          traceId?: string;
+        }
+      ): void;
+
+      hasApproval(
+        req: PolicyRequest,
+        scope: ApprovalScope,
+        ctx?: { workspaceId?: string }
+      ): boolean;
+
+      recordApproval(
+        req: PolicyRequest,
+        scope: ApprovalScope,
+        ctx?: {
+          workspaceId?: string;
+          decidedBy?: string;
+          /**
+           * Time-bound the approval — Sub-step 3.F. Epoch ms;
+           * `hasApproval` rejects after this point. Undefined =
+           * permanent.
+           */
+          expiresAt?: number;
+        }
+      ): ApprovalRecord;
+
+      revokeApproval(
+        rec: Pick<ApprovalRecord, 'kind' | 'id' | 'scope' | 'workspaceId'>
+      ): boolean;
+
+      /**
+       * @param options - 3.F: `includeExpired` (default false)
+       *   retains approvals whose `expiresAt <= Date.now()`. Pre-
+       *   3.F callers ignored expiry entirely; the default
+       *   behavior change is intentional — expired approvals are
+       *   no longer load-bearing.
+       */
+      listApprovals(options?: { includeExpired?: boolean }): ApprovalRecord[];
+      clearApprovals(): void;
+
+      /**
+       * Export policy state (mode + approvals) as JSON.
+       */
+      exportState(): PolicyExport;
+
+      /**
+       * Import policy state from JSON. Returns number of approvals imported.
+       */
+      importState(data: PolicyExport, options?: { merge?: boolean }): number;
+
+      /**
+       * Policy templates: workspace-scoped policy templates
+       */
+      saveTemplate(
+        name: string,
+        template: PolicyTemplate,
+        workspaceId?: string
+      ): void;
+      getTemplate(name: string, workspaceId?: string): PolicyTemplate | null;
+      listTemplates(workspaceId?: string): PolicyTemplate[];
+      deleteTemplate(name: string, workspaceId?: string): boolean;
+
+      /**
+       * Export policy audit log (approvals, decisions) as CSV/JSON.
+       */
+      exportAuditLog(options?: {
+        format?: 'json' | 'csv';
+        since?: number;
+        until?: number;
+        workspaceId?: string;
+      }): string;
+    }
+
+    /**
+     * Policy template for workspace-scoped policy rules
+     */
+    export interface PolicyTemplate {
+      name: string;
+      description?: string;
+      workspaceId?: string;
+      rules: Array<{
+        kind: string;
+        id?: string;
+        risk?: 'low' | 'medium' | 'high';
+        approval?: 'none' | 'plan' | 'step';
+        condition?: string; // Future: expression for conditional rules
+      }>;
+      createdAtMs?: number;
+      updatedAtMs?: number;
+    }
+
+    /**
+     * Exported policy state format (v2).
+     */
+    export interface PolicyExport {
+      version: 2;
+      exportedAt: number;
+      mode: PolicyMode;
+      approvals: ApprovalRecord[];
+    }
+
+    export namespace Policy {
+      const manager: PolicyApi;
+    }
+  }
+}

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

@@ -0,0 +1,107 @@
+declare module 'punica' {
+  export namespace kernel {
+    export type TaskKind = 'op' | 'code' | 'shell' | 'pipeline' | 'custom';
+
+    export type TaskStatus =
+      | 'pending'
+      | 'running'
+      | 'success'
+      | 'failed'
+      | 'cancelled';
+
+    export interface TaskDefinition {
+      /** Unique identifier for this task definition. */
+      id: string;
+      /** Human-readable label shown in UIs. */
+      label: string;
+      /** High-level category (build, test, etc.). */
+      kind: TaskKind;
+      /** Command to execute (e.g. a shell command, script, or workflow id). */
+      command: string;
+      /** Optional arguments passed to the command. */
+      args?: string[];
+      /** Working directory when executing the task. */
+      cwd?: string;
+      /** Environment variables for the task process. */
+      env?: Record<string, string>;
+      /** Logical group for UI filtering. */
+      group?: 'build' | 'test' | 'lint' | 'deploy' | 'other';
+      /**
+       * Optional flag or configuration indicating that the task should
+       * automatically be re-run when it finishes.
+       */
+      autoRerun?: boolean;
+    }
+
+    export interface TaskRun {
+      /** Unique id for this concrete run. */
+      runId: string;
+      /** Id of the TaskDefinition this run belongs to. */
+      definitionId: string;
+      /** Human-readable label (usually from the definition). */
+      label: string;
+      /** Current status of the run. */
+      status: TaskStatus;
+      /** When the run started, as ISO string. */
+      startedAt: string;
+      /** When the run finished, as ISO string. */
+      finishedAt?: string;
+      /** Exit code from the underlying process, if any. */
+      exitCode?: number | null;
+      /** Optional error message for failed runs. */
+      errorMessage?: string;
+      /** Associated terminal session id, if any. */
+      terminalId?: string;
+      /** Workspace id for the run, if applicable. */
+      workspaceId?: string;
+      /** Environment id used for this run, if applicable. */
+      environmentId?: string;
+    }
+
+    export interface TasksQuery {
+      status?: TaskStatus[];
+      definitionId?: string;
+      workspaceId?: string;
+    }
+
+    export interface TasksApi {
+      /** List all registered task definitions. */
+      listDefinitions(): Promise<TaskDefinition[]>;
+      /** Register or update a task definition. */
+      registerDefinition(def: TaskDefinition): void;
+      /** Remove a task definition. */
+      unregisterDefinition(id: string): void;
+      /** Start a new task run. */
+      run(id: string, options?: { environmentId?: string }): Promise<TaskRun>;
+      /** Look up a single run by id. */
+      getRun(id: string): Promise<TaskRun | null>;
+      /** List all runs, optionally filtered by status/definition/workspace. */
+      listRuns(query?: TasksQuery): Promise<TaskRun[]>;
+      /** Request cancellation of a running task. */
+      cancel(id: string): Promise<void>;
+      /** Subscribe to task run updates. */
+      onDidChangeRun(listener: (run: TaskRun) => void): () => void;
+    }
+
+    /**
+     * Tasks module façade surfaced under `punica.kernel.Tasks`.
+     *
+     * Hosts/extensions can use this to access the global tasks API.
+     */
+    export namespace Tasks {
+      /**
+       * Default tasks manager instance used across the workbench.
+       * Runtime dependencies (terminals, workspace) are resolved lazily from punica.runtime.
+       */
+      const manager: TasksApi;
+      /**
+       * Factory function to create a new TasksApi instance bound to specific runtime dependencies.
+       * Use `manager` for the global singleton instance.
+       */
+      function createTasksApi(
+        terminals: runtime.TerminalApi,
+        workspace?: runtime.WorkspaceApi
+      ): TasksApi;
+    }
+  }
+}

package/types/punica.module.kernel.timeServer.d.ts

@@ -0,0 +1,16 @@
+declare module 'punica' {
+  export namespace kernel {
+    export namespace TimeServer {
+      interface ISubscriber {
+        update(time: Date): void;
+      }
+
+      interface ITimeServerManager {
+        subscribe(subscriber: ISubscriber): void;
+        unsubscribe(subscriber: ISubscriber): void;
+      }
+
+      const manager: ITimeServerManager;
+    }
+  }
+}

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

@@ -0,0 +1,214 @@
+/// <reference path="punica.module.runtime.capabilities.d.ts" />
+/// <reference path="punica.module.runtime.compute.d.ts" />
+/// <reference path="punica.module.runtime.datasets.d.ts" />
+/// <reference path="punica.module.runtime.models.d.ts" />
+/// <reference path="punica.module.runtime.modelRuntimes.d.ts" />
+/// <reference path="punica.module.runtime.inference.d.ts" />
+/// <reference path="punica.module.runtime.vectors.d.ts" />
+
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Terminal session metadata shared between host and extensions.
+     * This describes a single logical terminal session owned by the host.
+     */
+    export type TerminalBackendKind = 'local' | 'remote' | 'custom';
+
+    export interface TerminalSessionInfo {
+      id: string;
+      backend: TerminalBackendKind;
+      cwd: string;
+      shell: string;
+      title?: string;
+      createdAt: number;
+      pty?: boolean;
+    }
+
+    export interface TerminalCreateOptions {
+      cwd?: string;
+      shell?: string;
+      title?: string;
+      /**
+       * Optional environment overrides for the spawned shell.
+       */
+      env?: Record<string, string>;
+    }
+
+    /**
+     * Stream-oriented terminal API. Hosts provide a concrete implementation
+     * (Electron: local node-pty, browser: WebSocket to remote shell, etc.)
+     * and extensions only depend on this abstraction.
+     */
+    export interface TerminalApi {
+      create(opts?: TerminalCreateOptions): Promise<TerminalSessionInfo>;
+      write(id: string, data: string): void;
+      resize(id: string, cols: number, rows: number): void;
+      close(id: string): void;
+      onData(id: string, listener: (data: string) => void): () => void;
+      onExit(
+        id: string,
+        listener: (code: number | null, signal?: string) => void
+      ): () => void;
+      list(): Promise<TerminalSessionInfo[]>;
+    }
+
+    /**
+     * Aggregate host/runtime capabilities exposed to extensions.
+     *
+     * This surface is intentionally limited to integration concerns
+     * (filesystem, search, vcs, workspace, resources, terminals). Core
+     * domain models live under the `kernel` namespace and UI/shell
+     * surfaces live under the `shell` namespace.
+     */
+    interface RuntimeApi {
+      /**
+       * Current high-level lifecycle phase for the workbench/host. Hosts are
+       * responsible for updating this field as the system progresses through
+       * startup, workspace loading, background work and shutdown.
+       */
+      lifecyclePhase?: LifecyclePhase;
+      fs: FileSystemProvider;
+      fileOpeners: FileOpenersApi;
+      search: SearchApi;
+      vcs: VcsApi;
+      terminals: TerminalApi;
+      /**
+       * Host-backed task runner primitive (exec/spawn via host, e.g. Electron).
+       */
+      tasks: TaskRunnerApi;
+      /**
+       * Workspace-level context and operations for the current host.
+       */
+      workspace: WorkspaceApi;
+      /**
+       * Shared catalog of logical resources (datasets, services, secrets, agents, etc.).
+       */
+      resources: ResourcesApi;
+
+      /**
+       * Minimal in-memory secrets API.
+       */
+      secrets: SecretsApi;
+
+      /**
+       * LLM provider interface. Hosts decide whether this is backed by local
+       * models, remote APIs, or a hybrid routing layer.
+       */
+      llm: LlmApi;
+
+      /**
+       * Compute execution interface for code execution (Python, Node, etc.).
+       * Supports both ephemeral and stateful session-based execution.
+       */
+      compute: compute.ComputeApi;
+
+      /**
+       * Datasets interface for dataset discovery, mounting, and access.
+       * Vendor-free contract for dataset providers (Kaggle, HuggingFace, S3, local, etc.).
+       */
+      datasets: datasets.DatasetsApi;
+
+      /**
+       * Models interface for model discovery, mounting, and access.
+       * Vendor-free contract for model providers (HuggingFace, Bedrock, local, etc.).
+       */
+      models: models.ModelsApi;
+
+      /**
+       * Local model execution seam: dispatch a model record to a pluggable
+       * runtime (GGUF/Transformers/ONNX/custom) and obtain a live endpoint.
+       * See docs/model-runtimes.md.
+       */
+      modelRuntimes: modelRuntimes.ModelRuntimesApi;
+
+      /**
+       * Task-general inference surface for non-chat tasks (embeddings / vision /
+       * ASR / rerank) on started local runtimes. Chat stays on `llm.chat`. See
+       * docs/model-runtimes.md §9.2.
+       */
+      inference: inference.InferenceApi;
+
+      /**
+       * Local vector index (similarity store) — pairs with `inference`
+       * embeddings for RAG. Pure vector store; never computes embeddings. See
+       * docs/model-runtimes.md §9.8.
+       */
+      vectors: vectors.VectorsApi;
+
+      /**
+       * Host data-directory surface: an absolute, out-of-workspace location for
+       * heavy artifacts (model weights, dataset files) plus a fs surface scoped
+       * to it. Injected by hosts with a real filesystem (Electron); may be
+       * absent on a browser host. See docs/model-runtimes.md.
+       */
+      host: host.HostApi;
+
+      /**
+       * Capability gateway for centralized capability invocation.
+       */
+      capabilities: CapabilitiesApi;
+
+      /**
+       * Host wiring helpers for registering providers.
+       * These methods are always available at runtime for extension convenience.
+       */
+      setFsProvider: (provider: FileSystemProvider) => void;
+      setLlmProvider: (provider: LlmApi) => void;
+      setComputeProvider: (provider: compute.ComputeProvider) => void;
+      setComputeRuntime: (runtime: compute.LanguageRuntime) => void;
+      setDatasetProvider: (provider: datasets.DatasetProvider) => void;
+      setModelProvider: (provider: models.ModelProvider) => void;
+      setModelRuntime: (runtime: modelRuntimes.ModelRuntime) => void;
+      setHostProvider: (provider: host.HostApi) => void;
+      setVectorsProvider: (provider: vectors.VectorsApi) => void;
+      setSearchProvider: (provider: SearchApi) => void;
+      setWorkspaceProvider: (provider: WorkspaceApi) => void;
+      setTerminalProvider: (provider: TerminalApi) => void;
+      setVcsProvider: (provider: VcsApi) => void;
+      setResourcesProvider: (provider: ResourcesApi) => void;
+      setTasksProvider: (provider: TaskRunnerApi) => void;
+      setSecretsProvider: (provider: SecretsApi) => void;
+    }
+  }
+
+  export const runtime: runtime.RuntimeApi;
+
+  /**
+   * Shared diagnostics model for Problems/Errors panels.
+   */
+  export type ProblemSeverity = 'error' | 'warning' | 'info';
+
+  export interface ProblemItem {
+    id: string;
+    file: string;
+    line: number;
+    column: number;
+    message: string;
+    source?: string;
+    code?: string | number;
+    severity: ProblemSeverity;
+  }
+
+  /**
+   * Shared output/log entry model for Output panels and log viewers.
+   */
+  export type OutputLevel = 'info' | 'warning' | 'error';
+
+  export interface OutputEntry {
+    id: string;
+    channel: string;
+    text: string;
+    timestamp: string;
+    level: OutputLevel;
+  }
+
+  // NOTE: Hosts should attach concrete implementations directly via
+  //   window.punica.runtime.search = <runtime.SearchApi>
+  //   window.punica.runtime.vcs = <runtime.VcsApi>
+  //   window.punica.runtime.terminals = <runtime.TerminalApi>
+  //   window.punica.runtime.workspace = <runtime.WorkspaceApi>
+  //   window.punica.runtime.resources = <runtime.ResourcesApi>
+  //   window.punica.runtime.llm = <runtime.LlmApi>
+  //   window.punica.runtime.setFsProvider(<runtime.FileSystemProvider>)
+  //   window.punica.runtime.fileOpeners = <runtime.FileOpenersApi>
+}