@punica/editor 1.0.6 → 1.0.8

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

@@ -0,0 +1,274 @@
+declare module 'punica' {
+  export namespace kernel {
+    export type KernelEventKind = 'result' | 'progress' | 'error' | 'info';
+
+    /**
+     * Standard event envelope for correlation, auditing and tracing.
+     */
+    export interface KernelEventEnvelope {
+      /**
+       * Unique id for this specific event instance.
+       */
+      id: string;
+      /**
+       * Optional correlation id that ties multiple events together (e.g. a
+       * capability execution producing progress + result).
+       */
+      correlationId?: string;
+      /**
+       * Optional distributed trace id. When omitted, consumers may treat
+       * correlationId (or id) as the trace identifier.
+       */
+      traceId?: string;
+      /**
+       * Optional span id within a trace.
+       */
+      spanId?: string;
+      /**
+       * Optional parent span id within a trace (for nesting).
+       */
+      parentSpanId?: string;
+      /**
+       * Timestamp (ms since epoch) when this event was published.
+       */
+      timestampMs: number;
+      /**
+       * Optional source identifier (e.g. "ai-core", "extension:file-explorer").
+       */
+      source?: string;
+      /**
+       * Optional high-level kind for consumers.
+       */
+      kind?: KernelEventKind;
+    }
+
+    /**
+     * Standard kernel event record published through the EventsApi.
+     */
+    export interface KernelEvent {
+      name: string;
+      envelope: KernelEventEnvelope;
+      payload?: any;
+    }
+
+    /**
+     * Broker-side subscription filter (Sub-step 6.H).
+     *
+     * Declarative description of which events a subscription wants.
+     * All fields optional; an empty filter matches every event.
+     * Fields combine with AND; values inside an array combine with OR.
+     *
+     *  - `name`: exact event name, a `prefix.*` wildcard, or the bare
+     *    `*` catch-all. Same grammar as the retention module.
+     *  - `correlationId` / `traceId`: exact match against the matching
+     *    envelope field.
+     *  - `kind` / `source`: single value or array (OR within array).
+     */
+    export interface EventSubscriptionFilter {
+      name?: string | string[];
+      correlationId?: string;
+      traceId?: string;
+      kind?: KernelEventKind | KernelEventKind[];
+      source?: string | string[];
+    }
+
+    /**
+     * In-memory event bus for cross-module communication.
+     */
+    export interface EventsApi {
+      /**
+       * Publish an event with an optional payload. Event names are free-form
+       * but using dot-separated namespaces (e.g. "tasks.runChanged",
+       * "workspace.changed") is recommended.
+       */
+      publish(name: string, payload?: any): void;
+      /**
+       * Subscribe to a single event name. The listener receives the
+       * original payload (NOT the wrapped KernelEvent) — this is the
+       * legacy contract preserved for binary compatibility.
+       *
+       * Returns an unsubscribe function.
+       */
+      subscribe(name: string, listener: (payload: any) => void): () => void;
+      /**
+       * Subscribe with a broker-side filter (Sub-step 6.H). The
+       * listener receives the full `KernelEvent` (so it can read
+       * envelope metadata) and is invoked ONLY when the event matches
+       * `filter`. Filters combine with AND; array values within a
+       * field combine with OR; an empty filter matches every event.
+       *
+       * Returns an unsubscribe function.
+       */
+      subscribe(
+        filter: EventSubscriptionFilter,
+        listener: (event: KernelEvent) => void
+      ): () => void;
+      /**
+       * Subscribe to multiple events at once. Returns an unsubscribe
+       * function that removes all registered listeners.
+       */
+      subscribeMany(
+        names: string[],
+        listener: (event: { name: string; payload: any }) => void
+      ): () => void;
+
+      /**
+       * Create a correlation id suitable for tying multiple events together.
+       */
+      createCorrelationId(): string;
+
+      /**
+       * Publish a standard KernelEvent record. Returns the normalized envelope.
+       */
+      publishEvent(event: KernelEvent): KernelEventEnvelope;
+
+      /**
+       * Returns the most recent published events (in-memory audit buffer).
+       */
+      getRecent(limit?: number): KernelEvent[];
+
+      /**
+       * Filter events by various criteria.
+       * By default, only searches in-memory audit buffer.
+       * Set includePersisted=true to also search disk-persisted events (may be slower).
+       */
+      filterEvents(options?: {
+        correlationId?: string;
+        name?: string | string[];
+        kind?: KernelEventKind | KernelEventKind[];
+        source?: string | string[];
+        since?: number; // timestampMs
+        until?: number; // timestampMs
+        limit?: number;
+        includePersisted?: boolean;
+      }): KernelEvent[];
+
+      /**
+       * Load persisted events from disk (async).
+       * Useful for searching historical events beyond the in-memory audit buffer.
+       */
+      loadPersistedEvents?(options?: {
+        since?: number;
+        until?: number;
+        name?: string | string[];
+        limit?: number;
+      }): Promise<KernelEvent[]>;
+
+      /**
+       * Get all events for a specific correlationId (trace drilldown).
+       */
+      getTrace(correlationId: string): KernelEvent[];
+
+      /**
+       * Export events as JSON.
+       */
+      exportEvents(options?: {
+        format?: 'json' | 'csv';
+        filter?: Parameters<EventsApi['filterEvents']>[0];
+      }): string;
+
+      /**
+       * Clears the in-memory audit buffer.
+       */
+      clearAudit(): void;
+
+      /**
+       * Walk historical events (in-memory audit + persisted store)
+       * and either log them or re-publish them through the bus
+       * (Sub-step 6.I).
+       *
+       *  - `mode: 'log'` writes each matching event to console.log
+       *    in chronological order. Pure read; only stdout side-effect.
+       *  - `mode: 'dispatch'` re-publishes events so listeners fire
+       *    again. Dangerous in production — gated by the host-level
+       *    `setReplayDispatchAllowed(true)` flag.
+       *
+       * Filter fields share semantics with `EventSubscriptionFilter`
+       * (AND across fields, OR within arrays); `since`/`until` scope
+       * the time range; `limit` keeps the tail-most N matches.
+       */
+      replay(opts: EventReplayOptions): Promise<EventReplayResult>;
+    }
+
+    /**
+     * Replay scope + control (Sub-step 6.I). The first group of
+     * fields mirrors `EventSubscriptionFilter` matching semantics;
+     * the time-range fields scope the historical window; the
+     * mode/`includePersisted` fields select replay behavior.
+     */
+    export interface EventReplayOptions {
+      name?: string | string[];
+      correlationId?: string;
+      traceId?: string;
+      kind?: KernelEventKind | KernelEventKind[];
+      source?: string | string[];
+      since?: number;
+      until?: number;
+      limit?: number;
+      mode: 'log' | 'dispatch';
+      /** Defaults to true — historical replay queries the store. */
+      includePersisted?: boolean;
+    }
+
+    /** Outcome of an `events.replay(...)` call. */
+    export interface EventReplayResult {
+      count: number;
+      events: KernelEvent[];
+    }
+
+    /**
+     * OTel-compatible point-in-time span emitted for every published
+     * kernel event (Sub-step 6.L). Maps 1:1 to an `@opentelemetry/api`
+     * Span snapshot — hosts wrap their OTel SDK in an
+     * `EventTelemetryExporter` without translation work.
+     */
+    export interface EventSpan {
+      traceId?: string;
+      spanId: string;
+      parentSpanId?: string;
+      correlationId?: string;
+      name: string;
+      timestampMs: number;
+      kind?: KernelEventKind;
+      source?: string;
+      attributes: Record<string, unknown>;
+    }
+
+    /**
+     * Host contract for receiving event spans (Sub-step 6.L).
+     * Implementations MUST be non-blocking (queue + flush async).
+     * The substrate calls `exportSpan` from `publishEvent` on every
+     * event; throwing is tolerated (swallowed) but slow exporters
+     * will slow down every publish call directly.
+     */
+    export interface EventTelemetryExporter {
+      exportSpan(span: EventSpan): void;
+    }
+
+    /**
+     * Host contract for receiving EventStore self-metrics (Sub-step 6.L).
+     * Closes CONSTITUTION § Kapı 4's `events.store.write_lag` and
+     * `events.store.queue_depth` requirements. Callbacks are optional
+     * — observers implement only the metrics they care about.
+     */
+    export interface EventStoreMetricsObserver {
+      onWrite?(durationMs: number, count: number): void;
+      onQueueDepthChange?(depth: number): void;
+    }
+
+    /**
+     * Events module façade surfaced under `punica.kernel.Events`.
+     *
+     * Hosts/extensions can use this to create an EventsApi instance that backs
+     * the in-memory event bus used across the workbench.
+     */
+    export namespace Events {
+      /**
+       * Default event bus instance used across the workbench.
+       */
+      const manager: EventsApi;
+      function createEventsApi(): EventsApi;
+      function createCorrelationId(): string;
+    }
+  }
+}

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

@@ -0,0 +1,20 @@
+declare module 'punica' {
+  export namespace kernel {
+    export namespace History {
+      interface ICommand {
+        id: string;
+        execute(): void;
+        undo(): void;
+      }
+
+      interface IHistoryManager {
+        registerCommand(command: ICommand): void;
+        executeCommand(commandId: string): void;
+        undo(): void;
+        redo(): void;
+      }
+
+      const manager: IHistoryManager;
+    }
+  }
+}

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

@@ -0,0 +1,343 @@
+declare module 'punica' {
+  export namespace kernel {
+    export namespace llm {
+      /**
+       * LLM Instruction Class - Rule-based behavior definition for LLM capabilities.
+       *
+       * Paradigm: "LLM = CPU değil, instruction-class"
+       * LLM'ler artık bir kimlik (identity) değil, bir yetenek (capability) olarak görülür.
+       * Her instruction class bir role tanımlar ve deterministic, rule-based behavior sağlar.
+       */
+      export interface InstructionClass {
+        /** Unique identifier for this instruction class (e.g. 'planner', 'code-generator') */
+        id: string;
+        /** Role name (e.g. 'planner', 'code-generator', 'validator', 'reviewer') */
+        role: string;
+        /** System prompt that defines the LLM's behavior and rules */
+        systemPrompt: string;
+        /** Optional JSON Schema for structured output validation */
+        outputSchema?: JSONObject;
+        /** Default temperature for this instruction class */
+        temperature?: number;
+        /** Default max tokens for this instruction class */
+        maxTokens?: number;
+        /** Response format: 'json_object' for structured output, 'text' for free-form */
+        responseFormat?: 'json_object' | 'text';
+        /**
+         * Preferred model identifier for this instruction class (e.g. 'llama-3.2-8b-instruct-q4_k_m').
+         * Used by expert routing to select a single expert model.
+         */
+        expertModelId?: string;
+        /**
+         * Optional static risk level override for this instruction class.
+         * When not provided, risk is determined dynamically via LLM-based assessment.
+         */
+        riskLevel?: 'low' | 'medium' | 'high';
+        /**
+         * Optional explicit list of expert model identifiers for multi-expert scenarios.
+         * When provided, auto-selection can use or extend this list.
+         */
+        expertModelIds?: string[];
+        /**
+         * Unified capability definition for LLM consumption.
+         * If not provided, can be auto-generated from InstructionClass fields.
+         * This enables LLM planners to understand and reason about instruction classes
+         * in the same format as Extensions and Ivy Node capabilities.
+         */
+        capability?: CapabilityDefinition;
+        /**
+         * Origin extension ID that registered this instruction class.
+         * Used for lifecycle management and governance introspection.
+         * Example: 'extension-ivy-node', 'extension-ivy-agent'
+         */
+        originExtension?: string;
+        /**
+         * Product ID that this instruction class belongs to.
+         * Used for product-scoped routing.
+         * Example: 'ivy-node', 'ivy-agent', 'ivy-mcp', 'ivy-flowbook'
+         */
+        productId?: string;
+      }
+
+      /**
+       * Input for LLM capability invocation via instruction class.
+       * Used by capabilities like 'llm.invoke', 'llm.plan', etc.
+       */
+      export interface CapabilityInput {
+        /** Instruction class ID to use (references InstructionClass.id) */
+        instructionClass: string;
+        /** User prompt/query */
+        userPrompt: string;
+        /** Optional context for the LLM invocation */
+        context?: {
+          workspaceId?: string;
+          filePath?: string;
+          previousOutputs?: Record<string, unknown>;
+          capabilities?: Array<{ id: string; definition: unknown }>;
+        };
+        /** Optional overrides for instruction class defaults */
+        options?: {
+          temperature?: number;
+          maxTokens?: number;
+          timeoutMs?: number;
+          /** Skip cache lookup (force fresh response) */
+          skipCache?: boolean;
+          /** Enable streaming response (if supported by provider) */
+          stream?: boolean;
+          /** Skip multi-model fallback on failure */
+          skipFallback?: boolean;
+        };
+      }
+
+      /**
+       * Successful output from LLM capability invocation.
+       */
+      export interface CapabilityOutput {
+        ok: true;
+        /** Raw text output from LLM */
+        text: string;
+        /** Parsed structured output (if outputSchema was provided) */
+        structured?: unknown;
+        /** Metadata about the invocation */
+        metadata: {
+          instructionClass: string;
+          role: string;
+          originExtension?: string;
+          productId?: string;
+          tokensUsed?: number;
+          inputTokens?: number;
+          outputTokens?: number;
+          latencyMs?: number;
+          modelId?: string;
+          provider?: string;
+          cacheHit?: boolean;
+        };
+      }
+
+      /**
+       * Error output from LLM capability invocation.
+       */
+      export interface CapabilityError {
+        ok: false;
+        error: string;
+        /**
+         * Blocked status indicates the operation was prevented by policy/gate.
+         */
+        blocked?: boolean;
+        /**
+         * Stable reason code for blocked operations (e.g., 'LLM_PROFILE_NOT_REGISTERED').
+         */
+        reasonCode?: string;
+        metadata: {
+          instructionClass: string;
+          role: string;
+          originExtension?: string;
+          productId?: string;
+          cacheHit?: boolean;
+        };
+      }
+
+      /**
+       * Union type for LLM capability result.
+       */
+      export type CapabilityResult = CapabilityOutput | CapabilityError;
+
+      /**
+       * Instruction class summary for introspection/governance.
+       */
+      export interface InstructionClassSummary {
+        id: string;
+        role: string;
+        originExtension?: string;
+        productId?: string;
+        outputSchemaSummary?: string;
+      }
+
+      /**
+       * LLM Instruction Class Registry API.
+       * Allows registration and lookup of instruction classes for LLM capabilities.
+       */
+      export interface InstructionClassRegistry {
+        /**
+         * Register an instruction class.
+         * @param instructionClass The instruction class to register
+         * @param originExtension Optional origin extension ID (auto-detected if not provided)
+         */
+        register(
+          instructionClass: InstructionClass,
+          originExtension?: string
+        ): void;
+
+        /**
+         * Inject a product → originExtension resolver.
+         *
+         * The kernel is substrate and holds no knowledge of any
+         * specific product family. When an instruction class is
+         * registered with a `productId` but no explicit
+         * `originExtension`, the registry consults this resolver to
+         * derive the origin. The product/host layer owns the mapping,
+         * keeping product-specific concepts out of `kernel/`
+         * (CONSTITUTION §0). Absent resolver = no auto-detection.
+         */
+        registerProductOriginResolver(
+          resolver: (productId: string) => string | undefined
+        ): void;
+
+        /**
+         * Unregister an instruction class by ID.
+         * @param id Instruction class ID to unregister
+         */
+        unregister(id: string): void;
+
+        /**
+         * Unregister all instruction classes from a specific origin extension.
+         * @param originExtension Origin extension ID
+         */
+        unregisterByOrigin(originExtension: string): void;
+
+        /**
+         * Get an instruction class by ID.
+         */
+        get(id: string): InstructionClass | undefined;
+
+        /**
+         * List all registered instruction classes.
+         * @param filterActiveOnly If true, only return classes whose origin extension is currently active
+         */
+        list(filterActiveOnly?: boolean): InstructionClass[];
+
+        /**
+         * List instruction class summaries for introspection/governance.
+         * @param filterActiveOnly If true, only return classes whose origin extension is currently active
+         */
+        listSummaries(filterActiveOnly?: boolean): InstructionClassSummary[];
+
+        /**
+         * Check if an instruction class is registered.
+         */
+        has(id: string): boolean;
+
+        /**
+         * Check if an instruction class is available (registered and origin extension is active).
+         */
+        isAvailable(id: string): boolean;
+      }
+
+      /**
+       * High-level LLM API for kernel layer.
+       * Provides instruction class-based invocation and specialized methods.
+       */
+      export interface LlmApi {
+        /**
+         * Instruction class registry.
+         */
+        readonly instructionClassRegistry: InstructionClassRegistry;
+
+        /**
+         * List all registered instruction classes (introspection API for governance/debug).
+         * Returns summaries with origin extension and product ID metadata.
+         */
+        listInstructionClasses(
+          filterActiveOnly?: boolean
+        ): InstructionClassSummary[];
+
+        /**
+         * Invoke LLM using an instruction class.
+         *
+         * `opts.correlationId` lets the caller bind this invocation to its
+         * own session/trace id. When `input.options.stream` is set, the
+         * streaming `llm.chunk` deltas are published under this id so the
+         * caller can correlate live tokens with the originating turn.
+         */
+        invoke(
+          input: CapabilityInput,
+          opts?: { correlationId?: string }
+        ): Promise<CapabilityResult>;
+
+        /**
+         * Generate FlowBook IR from natural language query.
+         */
+        plan(input: {
+          query: string;
+          capabilities?: Array<{ id: string; definition: unknown }>;
+        }): Promise<CapabilityResult>;
+
+        /**
+         * Generate code from requirements.
+         */
+        generateCode(input: {
+          requirements: string;
+          language?: string;
+          context?: {
+            workspaceId?: string;
+            filePath?: string;
+            previousOutputs?: Record<string, unknown>;
+          };
+        }): Promise<CapabilityResult>;
+
+        /**
+         * Validate code and identify issues.
+         */
+        validator(input: {
+          code: string;
+          language?: string;
+          context?: {
+            workspaceId?: string;
+            filePath?: string;
+          };
+        }): Promise<CapabilityResult>;
+
+        /**
+         * Provide code review feedback.
+         */
+        reviewer(input: {
+          code: string;
+          language?: string;
+          context?: {
+            workspaceId?: string;
+            filePath?: string;
+          };
+        }): Promise<CapabilityResult>;
+
+        /**
+         * Edit and optimize FlowBook IR structures.
+         */
+        editWorkflow(input: {
+          flowBook: ivy.FlowBookDocument;
+          requirements?: string;
+          context?: {
+            workspaceId?: string;
+            filePath?: string;
+            capabilities?: Array<{ id: string; definition: unknown }>;
+          };
+        }): Promise<CapabilityResult>;
+      }
+
+      /**
+       * LLM manager API for kernel layer.
+       */
+      export interface LlmManager {
+        readonly api: LlmApi;
+      }
+
+      /**
+       * LLM manager instance.
+       */
+      export const manager: LlmManager;
+
+      /**
+       * CodegenBundle IR v0.1 - Multi-file code generation output format
+       */
+      export interface CodegenBundleV0_1 {
+        specVersion: '0.1';
+        summary?: string;
+        files: Array<{
+          path: string;
+          action: 'create' | 'update' | 'delete';
+          content?: string;
+          encoding?: 'utf-8';
+        }>;
+      }
+    }
+  }
+}

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

@@ -0,0 +1,64 @@
+declare module 'punica' {
+  export namespace kernel {
+    export type NotificationLevel = 'error' | 'warning' | 'info';
+
+    export interface NotificationItem {
+      /** Unique id for this notification. */
+      id: string;
+      /** Short title shown in UI. */
+      title?: string;
+      /** Detailed message text. */
+      message: string;
+      /** Optional logical source (extension id, subsystem, etc.). */
+      source?: string;
+      /** Level / severity for styling and filtering. */
+      level: NotificationLevel;
+      /** When the notification was created, as ISO string. */
+      timestamp?: string;
+      /** Whether the notification has been handled / dismissed. */
+      read?: boolean;
+      /** Optional command to execute when the user acts on the notification. */
+      actionCommandId?: string;
+    }
+
+    export interface NotificationsApi {
+      /**
+       * List all notifications, newest first.
+       */
+      list(): Promise<NotificationItem[]>;
+      /**
+       * Push a new notification into the global notification center.
+       */
+      push(item: NotificationItem): void;
+      /**
+       * Mark a notification as handled / dismissed.
+       */
+      markRead(id: string): void;
+      /**
+       * Clear notifications, optionally filtered by source.
+       */
+      clear(source?: string): void;
+      /**
+       * Subscribe to changes in the notification list.
+       */
+      onDidChange(listener: () => void): () => void;
+    }
+
+    /**
+     * Notifications module façade surfaced under `punica.kernel.Notifications`.
+     *
+     * Hosts/extensions can use this to access the global notification center.
+     */
+    export namespace Notifications {
+      /**
+       * Default notifications manager instance used across the workbench.
+       */
+      const manager: NotificationsApi;
+      /**
+       * Factory function to create a new NotificationsApi instance.
+       * Use `manager` for the global singleton instance.
+       */
+      function createNotificationsApi(): NotificationsApi;
+    }
+  }
+}