@punica/editor 1.10.8 → 1.10.9

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@punica/editor",
-  "version": "1.10.8",
+  "version": "1.10.9",
   "description": "Punica Editor",
   "private": false,
   "type": "module",

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

@@ -473,6 +473,68 @@ declare module 'punica' {
 
       export const sessions: AiSessionsApi;
 
+      /**
+       * One capability's record in the tool-usage history.
+       *
+       * Four fields, and the list is the whole contract rather than a
+       * starting point: a capability id, how often it ran, how often that
+       * worked, and when it last did. There is deliberately nowhere here for
+       * a prompt, an argument or a path.
+       */
+      export interface ToolUsageEntry {
+        capabilityId: string;
+        calls: number;
+        /** Successful calls; `calls - ok` failed. */
+        ok: number;
+        /** Epoch ms of the most recent call. */
+        last: number;
+        /**
+         * The weight tool selection currently gives this capability, in
+         * [0, 1): recent use, saturating volume and success rate multiplied
+         * together. Reported alongside the raw counts because the counts on
+         * their own do not explain a ranking.
+         */
+        prior: number;
+      }
+
+      /**
+       * Persistence seam for the usage history. Host-injectable in the same
+       * shape as the approval and session stores, but asynchronous, because
+       * both of its call sites already are and a synchronous store would
+       * silently rank as though the user were new whenever a read landed
+       * before hydration.
+       *
+       * Every method is best-effort by contract: the prior is an
+       * optimization, and a store that fails must degrade to ranking without
+       * history rather than fail a run.
+       */
+      export interface ToolUsageStore {
+        read(): Promise<Record<string, { calls: number; ok: number; last: number }>>;
+        record(capabilityId: string, ok: boolean, atMs: number): Promise<void>;
+        forget(): Promise<void>;
+      }
+
+      /**
+       * `punica.kernel.AI.toolUsage` — what tool selection learned from this
+       * installation, and the switch that forgets it.
+       *
+       * Tool selection blends a capability's own call history into its
+       * ranking, so the product gets better at choosing the longer it is
+       * used. That is invisible by construction, which is the reason this
+       * surface exists: a person can read exactly what is stored and empty it
+       * in one call.
+       */
+      export interface ToolUsageApi {
+        /** Everything known, strongest prior first. */
+        list(): Promise<ToolUsageEntry[]>;
+        /** Erase the history. Ranking returns to a fresh install's. */
+        forget(): Promise<void>;
+        /** Host injection; `undefined` restores the substrate default. */
+        setStore(store: ToolUsageStore | undefined): void;
+      }
+
+      export const toolUsage: ToolUsageApi;
+
       export interface AiApi {
         initialize(): void;
         /**