@punica/editor 1.0.5 → 1.0.7

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

@@ -0,0 +1,175 @@
+/// <reference path="./punica.module.ivy.d.ts" />
+
+/**
+ * Runtime Capabilities API Type Definitions
+ */
+
+declare module 'punica' {
+  export namespace runtime {
+    /**
+     * Capability name identifier.
+     */
+    export type CapabilityName = string;
+
+    /**
+     * Actor that invokes a capability.
+     */
+    export interface InvocationActor {
+      /** Type of actor */
+      type: 'user' | 'extension' | 'ai';
+      /** Optional actor identifier */
+      id?: string;
+      /** Extension name (if type is 'extension') */
+      extensionName?: string;
+    }
+
+    /**
+     * Origin of the capability invocation.
+     */
+    export interface InvocationOrigin {
+      /** Kind of origin */
+      kind: 'command' | 'workflow' | 'ai';
+      /** Unique identifier for the origin */
+      id: string;
+      /** Extension name (if applicable) */
+      extension?: string;
+    }
+
+    /**
+     * Distributed tracing context.
+     */
+    export interface TraceContext {
+      /** Trace ID (correlates all spans in a request) */
+      traceId: string;
+      /** Parent span ID (for nested spans) */
+      parentSpanId?: string;
+    }
+
+    /**
+     * Policy evaluation context.
+     */
+    export interface PolicyContext {
+      /** Policy mode: 'suggest' (dry-run) or 'execute' */
+      mode: 'suggest' | 'execute';
+      /** Approval token (if approval was granted) */
+      approvalToken?: string;
+    }
+
+    /**
+     * Complete invocation context for a capability call.
+     */
+    export interface InvocationContext {
+      /** Session identifier */
+      sessionId: string;
+      /**
+       * Persistent AI conversation this call belongs to
+       * (`kernel.AI.sessions` id). Distinct from `sessionId`, which is
+       * the per-run/streaming correlation id (`llm.chunk` matching);
+       * one conversation spans many runs.
+       */
+      conversationId?: string;
+      /** Workspace identifier (optional) */
+      workspaceId?: string;
+      /** Actor information */
+      actor: InvocationActor;
+      /** Origin information */
+      origin: InvocationOrigin;
+      /** Tracing context */
+      trace: TraceContext;
+      /** Policy context */
+      policy: PolicyContext;
+      /**
+       * Optional cancellation signal (Faz 0b Stop/iptal). Threaded by the caller
+       * through `gateway.call(name, input, context)`; the pipeline forwards it to
+       * `provider.execute(input, ctx)`. Long-running providers (e.g.
+       * `llm.chatStream`) honor it to stop in-flight work. Travels out-of-band
+       * here rather than in `input`, so the data payload stays serializable and
+       * schema-clean.
+       */
+      signal?: AbortSignal;
+    }
+
+    /**
+     * Capability Gateway API
+     */
+    export interface CapabilityGatewayApi {
+      /**
+       * Call a capability through the gateway.
+       *
+       * @param name - Capability name
+       * @param input - Input payload
+       * @param context - Invocation context
+       * @param idempotencyKey - Optional idempotency key for safe retries
+       * @returns Promise resolving to output
+       */
+      call(
+        name: CapabilityName,
+        input: unknown,
+        context: InvocationContext,
+        idempotencyKey?: string
+      ): Promise<unknown>;
+    }
+
+    /**
+     * Capabilities API
+     */
+    export interface CapabilitiesApi {
+      /** Capability gateway */
+      gateway: CapabilityGatewayApi;
+    }
+
+    /**
+     * Python runtime gateway adapter interface.
+     *
+     * This interface defines the contract that a separate Python runtime project
+     * must implement to provide safety guarantees (rate limits, concurrency budgets,
+     * backpressure, timeouts, retry+jitter, cancellation mapping) above JEG.
+     *
+     * The Python runtime gateway:
+     * 1. Receives capability execution requests with execution defaults/overrides
+     * 2. Applies safety guarantees (rate limit, concurrency semaphore, timeout, retry+jitter)
+     * 3. Maps cancellation requests to JEG primitives (interrupt/restart/kill)
+     * 4. Emits standardized execution events for observability
+     * 5. Manages backpressure via bounded queues
+     */
+    export interface PythonRuntimeGatewayAdapter {
+      /**
+       * Execute a capability through the Python runtime gateway.
+       *
+       * @param capabilityId - Capability identifier
+       * @param input - Input payload
+       * @param context - Invocation context
+       * @param executionDefaults - Capability execution defaults (from CapabilityDefinition.execution)
+       * @param executionOverride - Optional workflow node override
+       * @param runBudget - Optional run-level budget constraints
+       * @param idempotencyKey - Optional idempotency key for safe retries
+       * @returns Promise resolving to output
+       */
+      execute(
+        capabilityId: string,
+        input: unknown,
+        context: InvocationContext,
+        executionDefaults?: CapabilityExecutionDefaults,
+        executionOverride?: ivy.ExecutionOverride,
+        runBudget?: ivy.RunBudget,
+        idempotencyKey?: string
+      ): Promise<unknown>;
+
+      /**
+       * Cancel a running capability execution.
+       *
+       * @param runId - Run identifier
+       * @param mode - Cancellation mode ('best-effort' or 'hard')
+       */
+      cancel(runId: string, mode: ivy.CancellationMode): Promise<void>;
+
+      /**
+       * Get execution event stream for a run.
+       *
+       * @param runId - Run identifier
+       * @returns Async iterable of execution events
+       */
+      getExecutionEvents(runId: string): AsyncIterable<ivy.ExecutionEvent>;
+    }
+  }
+}

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

@@ -0,0 +1,339 @@
+declare module 'punica' {
+  export namespace runtime {
+    export namespace compute {
+      /**
+       * Supported programming languages for code execution.
+       */
+      export type LanguageId =
+        | 'python'
+        | 'node'
+        | 'java'
+        | 'dotnet'
+        | 'bash'
+        | 'scala'
+        | 'r';
+
+      /**
+       * Resource limits for execution.
+       */
+      export interface ResourceLimits {
+        timeoutMs?: number;
+        cpu?: number;
+        memoryMb?: number;
+        gpu?: boolean;
+      }
+
+      /**
+       * Execution step definition.
+       */
+      export interface ExecutionStep {
+        id: string;
+        language: LanguageId;
+        code?: string;
+        entrypoint?: string;
+        files?: Array<{ path: string; content: string }>;
+        deps?: {
+          pip?: string[];
+          npm?: string[];
+          maven?: string[];
+          nuget?: string[];
+        };
+        env?: Record<string, string>;
+        cwd?: string;
+        resources?: ResourceLimits;
+        inputs?: Record<string, unknown>;
+        metadata?: Record<string, unknown>;
+      }
+
+      /**
+       * MIME bundle for display data (Jupyter-compatible).
+       * Matches ivy.MimeBundle type (Record<string, JSONValue>).
+       */
+      export type MimeBundle = Record<string, unknown>;
+
+      /**
+       * Cancellation reason for compute execution.
+       */
+      export type CancellationReason =
+        | 'user_requested'
+        | 'timeout'
+        | 'run_budget_exceeded'
+        | 'provider_error';
+
+      /**
+       * Execution event types emitted during code execution.
+       */
+      export type ExecutionEvent =
+        | {
+            type: 'started';
+            runId: string;
+            sessionId: string;
+            providerId: string;
+          }
+        | {
+            type: 'status';
+            runId: string;
+            state: 'busy' | 'idle';
+          }
+        | {
+            type: 'stdout';
+            runId: string;
+            text: string;
+          }
+        | {
+            type: 'stderr';
+            runId: string;
+            text: string;
+          }
+        | {
+            type: 'display';
+            runId: string;
+            displayId?: string;
+            mime: MimeBundle;
+            metadata?: Record<string, unknown>;
+          }
+        | {
+            type: 'result';
+            runId: string;
+            value?: unknown;
+            mime?: MimeBundle;
+          }
+        | {
+            type: 'error';
+            runId: string;
+            name?: string;
+            message: string;
+            stack?: string;
+            traceback?: string[];
+          }
+        | {
+            type: 'log';
+            runId: string;
+            level: 'debug' | 'info' | 'warn' | 'error';
+            message: string;
+          }
+        | {
+            type: 'cancelled';
+            runId: string;
+            reason: CancellationReason;
+            mode: 'best-effort' | 'hard';
+          }
+        | {
+            type: 'finished';
+            runId: string;
+            ok: boolean;
+            exitCode?: number;
+          };
+
+      /**
+       * JEG (Jupyter Enterprise Gateway) provider parameters.
+       */
+      export interface JegProviderParams {
+        /**
+         * JEG gateway URL (e.g., "http://jeg-gateway:8888").
+         */
+        gatewayUrl: string;
+        /**
+         * Optional authentication token or credentials.
+         */
+        authToken?: string;
+        /**
+         * Optional kernel spec mapping (kernel name -> JEG kernel spec identifier).
+         */
+        kernelSpecMapping?: Record<string, string>;
+        /**
+         * Optional HTTP headers to include in requests.
+         */
+        headers?: Record<string, string>;
+        /**
+         * Optional namespace/tenant identifier for multi-tenant JEG deployments.
+         */
+        namespace?: string;
+      }
+
+      /**
+       * Local process provider parameters.
+       */
+      export interface LocalProviderParams {
+        /**
+         * Optional working directory for process execution.
+         */
+        cwd?: string;
+        /**
+         * Optional environment variables.
+         */
+        env?: Record<string, string>;
+      }
+
+      /**
+       * Provider selector for session creation.
+       * Discriminated union for type-safe provider configuration.
+       */
+      export type ProviderSelector =
+        | {
+            id: 'jeg';
+            params: JegProviderParams;
+          }
+        | {
+            id: 'local';
+            params: LocalProviderParams;
+          }
+        | {
+            id: string;
+            params?: Record<string, unknown>;
+          };
+
+      /**
+       * Request to open a compute session.
+       */
+      export interface SessionOpenRequest {
+        provider?: ProviderSelector;
+        language: LanguageId;
+        kernelspec?: string;
+        env?: Record<string, string>;
+        cwd?: string;
+        resources?: ResourceLimits;
+        metadata?: Record<string, unknown>;
+      }
+
+      /**
+       * Options for running code.
+       */
+      export interface RunOptions {
+        runId?: string;
+        exclusive?: boolean;
+        silent?: boolean;
+      }
+
+      /**
+       * Compute session interface for stateful execution.
+       */
+      export interface ComputeSession {
+        id: string;
+        providerId: string;
+        language: LanguageId;
+        kernelspec?: string;
+        run(
+          step: ExecutionStep,
+          opts?: RunOptions
+        ): AsyncIterable<ExecutionEvent>;
+        interrupt(): Promise<void>;
+        restart(): Promise<void>;
+        close(): Promise<void>;
+      }
+
+      /**
+       * Session manager for opening and managing compute sessions.
+       */
+      export interface ComputeSessionManager {
+        open(request: SessionOpenRequest): Promise<ComputeSession>;
+      }
+
+      /**
+       * Registry for providers and language runtimes.
+       */
+      export interface ComputeRegistry {
+        registerProvider(provider: ComputeProvider): void;
+        registerLanguageRuntime(runtime: LanguageRuntime): void;
+        getProvider(id: string): ComputeProvider | undefined;
+        getLanguageRuntime(language: LanguageId): LanguageRuntime | undefined;
+        listProviders(): ComputeProvider[];
+      }
+
+      /**
+       * Main compute API surface.
+       */
+      export interface ComputeApi {
+        /**
+         * Run code in an ephemeral session (session is created and closed automatically).
+         */
+        run(
+          step: ExecutionStep,
+          opts?: RunOptions
+        ): AsyncIterable<ExecutionEvent>;
+        /**
+         * Cancel a running execution.
+         *
+         * Semantics:
+         * - For JEG provider: maps to kernel interrupt (best-effort) or kernel restart/kill (hard).
+         * - For local provider: maps to process signal (SIGTERM for best-effort, SIGKILL for hard).
+         * - Returns when cancellation is initiated; actual cancellation may be asynchronous.
+         *
+         * @param runId - Run identifier to cancel
+         * @param mode - Cancellation mode: 'best-effort' (graceful) or 'hard' (force)
+         */
+        cancel(runId: string, mode?: 'best-effort' | 'hard'): Promise<void>;
+        /**
+         * Session manager for stateful execution.
+         */
+        session: ComputeSessionManager;
+        /**
+         * Registry for providers and language runtimes.
+         */
+        registry: ComputeRegistry;
+      }
+
+      /**
+       * Session information passed to language runtimes.
+       */
+      export interface SessionInfo {
+        id: string;
+        providerId: string;
+        language: LanguageId;
+        kernelspec?: string;
+      }
+
+      /**
+       * Prepared run configuration (provider-specific).
+       */
+      export interface PreparedRun {
+        kind: 'jupyter' | 'process';
+        code?: string;
+        kernelspec?: string;
+        command?: string[];
+        files?: Array<{ path: string; content: string }>;
+        env?: Record<string, string>;
+        cwd?: string;
+        timeoutMs?: number;
+        meta?: Record<string, unknown>;
+      }
+
+      /**
+       * Language runtime adapter for preparing execution steps.
+       */
+      export interface LanguageRuntime {
+        language: LanguageId;
+        resolveKernelSpec?(req: SessionOpenRequest): string | undefined;
+        prepare(step: ExecutionStep, session: SessionInfo): PreparedRun;
+      }
+
+      /**
+       * Provider session interface (internal to providers).
+       */
+      export interface ProviderSession {
+        id: string;
+        run(
+          run: PreparedRun,
+          runId: string,
+          opts?: RunOptions
+        ): AsyncIterable<ExecutionEvent>;
+        interrupt(): Promise<void>;
+        restart(): Promise<void>;
+        close(): Promise<void>;
+      }
+
+      /**
+       * Compute provider interface (implemented by providers like local, jeg, etc.).
+       */
+      export interface ComputeProvider {
+        id: string;
+        label?: string; // Human-readable name (e.g., "Jupyter Enterprise Gateway")
+        kind?: string; // Provider type (e.g., "jeg", "local")
+        description?: string; // Optional description
+        openSession(
+          request: SessionOpenRequest & { kernelspec?: string }
+        ): Promise<ProviderSession>;
+      }
+    }
+  }
+}