@punica/editor 1.26.1 → 1.28.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.26.1",
+  "version": "1.28.0",
   "description": "Punica Editor",
   "private": false,
   "type": "module",
@@ -26,6 +26,7 @@
     "check:permissions": "node scripts/check-permissions.mjs",
     "check:empty-states": "node scripts/check-empty-states.mjs",
     "check:capability-handlers": "node scripts/check-capability-handlers.mjs",
+    "check:instruction-classes": "node scripts/check-instruction-classes.mjs",
     "report:capability-actions": "node scripts/report-capability-actions.mjs",
     "test": "vitest run",
     "test:watch": "vitest",

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

@@ -23,16 +23,42 @@ declare module 'punica' {
         maxTokens?: number;
         /** Response format: 'json_object' for structured output, 'text' for free-form */
         responseFormat?: 'json_object' | 'text';
+        /**
+         * How much of `maxTokens` this class may spend on reasoning.
+         *
+         * Absent means `none`, which is what twelve of the fleet's fifteen
+         * classes want: `maxTokens` reaches a local server as `num_predict`
+         * and caps thinking and answer together, so a formatting job that
+         * declares 400 tokens against a reasoning core returns nothing.
+         * Declare `auto` to keep the pre-1.27.0 wire and let the model think.
+         */
+        reasoning?: runtime.LlmReasoningMode;
         /**
          * 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.
+         *
+         * **Reaches a model only when NO provider chain applies.** The chain —
+         * the class's own, or the default one the active AI core registers —
+         * is resolved first and replaces the single-model path entirely, and a
+         * host may additionally distrust a `modelId` on a request that named
+         * no target (the Electron host does, so a local GGUF name is never
+         * sent to a remote vendor). To say where a class runs, declare
+         * `providerChain`. Four shipped classes named a model installed
+         * nowhere here for months without anything noticing, which is why
+         * `scripts/check-instruction-classes.mjs` now refuses the field in an
+         * `.ic.yaml`.
          */
         expertModelId?: string;
         /**
-         * Optional static risk level override for this instruction class.
-         * When not provided, risk is determined dynamically via LLM-based assessment.
+         * This class's risk level, which decides single- vs multi-expert
+         * routing.
+         *
+         * Declare one. `assess` — and, for classes written before it existed,
+         * omitting the field — asks the kernel to work it out, and that is a
+         * full extra `llm.chat` round trip on every invocation whose answer
+         * the chain path then discards unread.
          */
-        riskLevel?: 'low' | 'medium' | 'high';
+        riskLevel?: 'low' | 'medium' | 'high' | 'assess';
         /**
          * Optional explicit list of expert model identifiers for multi-expert scenarios.
          * When provided, auto-selection can use or extend this list.
@@ -106,6 +132,8 @@ declare module 'punica' {
         options?: {
           temperature?: number;
           maxTokens?: number;
+          /** Per-call override of the class's reasoning mode. */
+          reasoning?: runtime.LlmReasoningMode;
           timeoutMs?: number;
           /** Skip cache lookup (force fresh response) */
           skipCache?: boolean;

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

@@ -313,6 +313,49 @@ declare module 'punica' {
 
       /** The installed event exporter — never undefined; a no-op by default. */
       getEventTelemetryExporter: () => kernel.EventTelemetryExporter;
+
+      /**
+       * Install the development response cache, so a repeated LLM request is
+       * answered from the last answer instead of from the model.
+       *
+       * **There is no substrate default and the absent state is the shipped
+       * one**: with nothing installed every call reaches a model, which is
+       * how the product has behaved since the previous cache was deleted for
+       * leaking answers across tenants. That is the opposite default from the
+       * cost aggregator on purpose — an aggregator nobody enabled records
+       * numbers nobody reads, while a cache nobody enabled changes what the
+       * product answers.
+       *
+       * A hit skips the provider call and nothing else: the remote-policy
+       * gate runs first and is evaluated against the provider the stored
+       * answer names, so a hit is governed exactly as the call it replaces.
+       * It reports `usage` as zeros and `LlmCallMeta.cacheHit: true`.
+       *
+       * Pass `undefined` to turn it off; the store it replaces keeps its
+       * entries until someone calls `clear()`.
+       */
+      setLlmResponseCache: (cache: LlmResponseCache | undefined) => void;
+
+      /**
+       * The installed cache, or `undefined` when none is — which is also how
+       * a host asks it for `stats()`.
+       *
+       * On the facade because the setter does not survive without it: a
+       * written value that no published code reads is what the build
+       * eliminates, and `setApprovalTokenSigner` once shipped compiled down
+       * to an empty function for exactly that reason.
+       */
+      getLlmResponseCache: () => LlmResponseCache | undefined;
+
+      /**
+       * The substrate's store: bounded, expiring, process-local. Constructing
+       * one is on the facade beside the setter so that turning the cache on
+       * is one line — a host that had to write its own store first would be
+       * looking at a seam with no callers.
+       */
+      InMemoryLlmResponseCache: new (
+        options?: InMemoryLlmResponseCacheOptions
+      ) => LlmResponseCache;
     }
 
     /**

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

@@ -10,6 +10,31 @@ declare module 'punica' {
 
     export type LlmRoutePreference = 'auto' | 'local' | 'remote';
 
+    /**
+     * How much of the output budget a reasoning model may spend on thinking.
+     *
+     * `maxTokens` reaches a local server as `num_predict`, which caps thinking
+     * and answer TOGETHER — so a class that declares a small budget against a
+     * reasoning core spends all of it thinking and returns nothing. Measured
+     * 2026-09-01: a 125-character tutor hint costs 2,138 output tokens on
+     * `qwen3.5:9b`, against a class that declares 400.
+     *
+     * - `none`  — ask the provider not to think. This is the DEFAULT for an
+     *   instruction class that declares nothing, because twelve of the fleet's
+     *   fifteen classes are formatting or extraction jobs.
+     * - `auto`  — send nothing and let the provider decide, which is the wire
+     *   exactly as it was before this field existed.
+     *
+     * There is deliberately no `extended`: no class asks for it today, and a
+     * value that cannot be measured is a claim rather than a capability. It
+     * arrives with the measurement that needs it.
+     *
+     * Only the local route and the `ollama` vendor put anything on the wire
+     * for `none`; for the others "off" is already the default and an
+     * unrecognised argument is an error, so nothing is sent.
+     */
+    export type LlmReasoningMode = 'none' | 'auto';
+
     export interface LlmMessage {
       role: LlmRole;
       content: string;
@@ -136,6 +161,28 @@ declare module 'punica' {
        * loop); translated to vendor syntax host-side.
        */
       cacheHints?: LlmCacheHints;
+      /**
+       * How much of `maxTokens` the provider may spend on reasoning. Absent is
+       * read as `none` by the LLM capability perimeter; a provider adapter
+       * that receives `undefined` sends nothing.
+       */
+      reasoning?: LlmReasoningMode;
+      /**
+       * Bypass the development response cache for this call — go to the
+       * model, and store what comes back.
+       *
+       * It skips the READ, not the write. A flag that skipped both would
+       * leave the stale entry in place for the next caller, so an entry could
+       * never be refreshed — only waited out.
+       *
+       * Only meaningful while a host has installed a cache
+       * (`setLlmResponseCache`); with none installed every call already
+       * reaches the model and this changes nothing. `kernel.llm`'s
+       * `options.skipCache` is forwarded here, which is what finally gave
+       * that flag a reader: it was accepted and ignored from the day the old
+       * cache was deleted until 2026-09-02.
+       */
+      skipCache?: boolean;
     }
 
     export interface LlmUsage {
@@ -495,6 +542,70 @@ declare module 'punica' {
       stopLocalServer(): Promise<void>;
     }
 
+    /**
+     * One stored answer.
+     */
+    export interface LlmResponseCacheEntry {
+      /** The response as the provider returned it, `usage` included. */
+      response: LlmChatResponse;
+      /** Epoch ms — the store's own expiry clock. */
+      storedAtMs: number;
+    }
+
+    export interface LlmResponseCacheStats {
+      entries: number;
+      hits: number;
+      misses: number;
+      stores: number;
+      /**
+       * Tokens the hits did not spend, summed from each entry's own
+       * `usage.totalTokens` as it was served. Absent usage counts as 0, so
+       * this is a floor.
+       */
+      tokensSaved: number;
+    }
+
+    /**
+     * The development response cache (LLMOps 2.6).
+     *
+     * **The substrate computes the key; a store only holds what it is
+     * handed.** That division is the whole point of the type: the cache this
+     * replaces was keyed on `instructionClass:userPrompt`, which named
+     * neither the workspace, the user, the model nor the temperature, and two
+     * tenants asking one question shared an answer. A host store keyed by the
+     * host would put that decision back where no substrate test can see it.
+     *
+     * `get` and `set` may be async so a host can back this with disk or a
+     * shared service. A host store that is SHARED between people must be
+     * paired with `setHostIdentity`, because an unset identity keys every one
+     * of them as the same anonymous subject.
+     *
+     * See `docs/llm-response-cache.md`.
+     */
+    export interface LlmResponseCache {
+      get(
+        key: string
+      ):
+        | LlmResponseCacheEntry
+        | undefined
+        | Promise<LlmResponseCacheEntry | undefined>;
+      set(key: string, entry: LlmResponseCacheEntry): void | Promise<void>;
+      clear(): void | Promise<void>;
+      stats(): LlmResponseCacheStats;
+    }
+
+    export interface InMemoryLlmResponseCacheOptions {
+      /** LRU cap. Defaults to 200 — a development session, not a corpus. */
+      maxEntries?: number;
+      /**
+       * Entry lifetime in ms. Defaults to one hour. The prompt is in the key,
+       * so this is not about edited prompts; it is about the case the key
+       * cannot see — the same `modelId` pointing at different weights after a
+       * pull.
+       */
+      ttlMs?: number;
+    }
+
     export interface LlmApi {
       chat(req: LlmChatRequest): Promise<LlmChatResponse>;
       /**

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

@@ -22,9 +22,17 @@ declare module 'punica' {
         endpoint: string;
         runtimeId: string;
         /**
-         * Tasks this started runtime can serve (e.g. ['text-generation',
-         * 'embeddings']). Lets `runtime.inference` consumers know what a handle
-         * supports before calling `infer`. See docs/model-runtimes.md §9.2.
+         * Tasks THIS started runtime can serve (e.g. ['text-generation',
+         * 'embeddings']), when they differ from what the engine can serve in
+         * general — a llama.cpp server started without `--embedding` is the
+         * case this exists for. `runtime.inference.infer` refuses a task that
+         * is not in the list.
+         *
+         * Absent means "not stated", not "none": the engine's static
+         * `ModelRuntime.tasks` is consulted next, and if that is absent too the
+         * request proceeds and the engine answers for itself. That ordering is
+         * what keeps runtimes written before either field kept working.
+         * See docs/model-runtimes.md §9.2.
          */
         tasks?: models.ModelTask[];
         /**
@@ -42,6 +50,19 @@ declare module 'punica' {
       export interface ModelRuntime {
         /** Stable id, e.g. "gguf", "transformers", "onnx". */
         id: string;
+        /**
+         * What this engine can serve, readable WITHOUT starting it.
+         *
+         * The per-handle `tasks` could only ever be read after a model was
+         * loaded, so "can this engine embed?" was a question with no cheap
+         * answer — a picker had to start a runtime to find out. Declare the
+         * engine's general capability here and narrow it per handle only when
+         * a particular start is more limited.
+         *
+         * An engine with no `infer` serves chat through
+         * `runtime.llm.chat({ route: 'local' })` and should still say so.
+         */
+        tasks?: models.ModelTask[];
         /** Format-based dispatch test against a model record. */
         canRun(record: models.LocalModelRecord): boolean;
         /** Start the engine for this record and return a live endpoint. */