@alisio/sdk 0.8.0 → 0.10.0

package/dist/index.d.ts

@@ -752,10 +752,23 @@ export interface RunEventDataMap {
         reason: "manual" | "auto" | "budget";
         error: string;
     };
-    /** Tool results clipped in place to fit the context budget. */
+    /**
+     * Tool results clipped in place to fit the context budget. Elision by the Context Governor is
+     * never reported here: it lives only in `context_governed`.
+     */
     context_reduced: {
         messages: number;
+        /** Why the results were clipped; absent on events from older cores. */
+        reason?: "budget";
+        /** Estimate of the tokens the clip saved (characters divided by the shared heuristic). */
+        tokensSaved?: number;
     };
+    /**
+     * What the Context Governor decided for one model request (modes `shadow` and `on`; never
+     * emitted when it is `off`). Counts, enum keys, tool names and provider call ids only: no paths,
+     * patterns, stub text or file content.
+     */
+    context_governed: ContextGovernedData;
     session_context_injected: {
         tokens: number;
         sources: string[];
@@ -806,6 +819,136 @@ export interface RunEventDataMap {
         actual: ProofStatus;
     };
 }
+/**
+ * Kind of a context segment. Consumers must accept values they do not know: the list can grow.
+ */
+export type ContextSegmentKind = "system" | "instructions" | "user" | "assistant" | "tool_call" | "tool_result" | "checkpoint" | "invariant" | "memory" | "other";
+/** Why the Context Governor replaced a tool result with a stub. Consumers must accept new values. */
+export type ContextElisionReason = "superseded_read" | "stale_bg_output" | "duplicate_search";
+/** Tool results the model saw (`observed`) and later acted on (`used`). */
+export interface ContextUsageCounts {
+    observed: number;
+    used: number;
+}
+/**
+ * Payload of `context_governed`. Token figures are ESTIMATES (about 4 characters per token), never
+ * provider usage. Consumers must ignore fields they do not know.
+ */
+export interface ContextGovernedData {
+    policyVersion: number;
+    mode: "shadow" | "on";
+    /** 1-based number of the model request inside the run. */
+    request: number;
+    /** Messages in the history of this request. */
+    messages: number;
+    /** Inventory segments of that history (without pinned ones). */
+    segments: number;
+    /** Tool results that would be (`shadow`) or were (`on`) replaced by a stub. */
+    elided: number;
+    byReason: Record<ContextElisionReason, number>;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    /** Call ids elided for the first time at this request (at most 32). */
+    elidedCallIds?: string[];
+    /** How many newly elided call ids did not fit in `elidedCallIds`. */
+    elidedCallIdsOmitted?: number;
+    /** Counts of the invariants block of this request; never its text. */
+    invariants?: {
+        count: number;
+        chars: number;
+        omitted: number;
+    };
+    /** Heuristic usage of the tool results seen by this process in this session (advisory). */
+    usage?: {
+        observed: number;
+        used: number;
+        pending: number;
+        unattributed: number;
+        byKind?: Partial<Record<ContextSegmentKind, ContextUsageCounts>>;
+        /** At most 16 tools; the rest are folded into `other`. */
+        byTool?: Record<string, ContextUsageCounts>;
+    };
+}
+/** Where an invariant comes from. Consumers must accept values they do not know. */
+export type ContextInvariantKind = "instruction" | "goal" | "plan" | "criterion" | "grant";
+/** How protected a context segment is. Consumers must accept values they do not know. */
+export type ContextCriticality = "pinned" | "high" | "normal" | "low";
+/**
+ * One piece of the history a model request carries, as `GET /api/sessions/:sid/context/report`
+ * and `/context` explain it. Ids and counts only: never the text of the segment.
+ */
+export interface ContextSegment {
+    /** Stable id (the id the Governor uses for the same segment). */
+    id: string;
+    kind: ContextSegmentKind;
+    /** File path, tool name or message role. */
+    origin?: string;
+    /** Provider call id of a `tool_call` / `tool_result` segment. */
+    callId?: string;
+    /** Token ESTIMATE, never provider usage. */
+    tokens: number;
+    criticality: ContextCriticality;
+    /** Why the segment has that criticality. */
+    reason?: string;
+    /** Present when the Governor replaced (`on`) or would replace (`shadow`) the result by a stub. */
+    elided?: {
+        reason: ContextElisionReason;
+        /** Call id of the later result that made this one redundant. */
+        replacedBy?: string;
+        tokensSaved: number;
+    };
+    /** Heuristic: a later call acted on the same path. Absent when it cannot be decided. */
+    used?: boolean;
+}
+/**
+ * `GET /api/sessions/:sid/context/report`: what the next model request of a session carries and
+ * what the Context Governor does with it. The one report that the web panel, `/context` in the TUI
+ * and the `context_governed` events agree on. Token figures are ESTIMATES. With `mode: "off"` the
+ * Governor measures nothing, so `segments` is empty.
+ */
+export interface ContextReport {
+    sessionId: string;
+    policyVersion: number;
+    mode: "off" | "shadow" | "on";
+    /** 1-based request number of the latest `context_governed` event of this process, if any. */
+    request?: number;
+    /** Messages in the history. */
+    messages: number;
+    /** Segments of the history that count for `ContextGovernedData.segments` plus the pinned ones, in order. */
+    segments: ContextSegment[];
+    /** Segments dropped from `segments` to bound the report (elided, pinned and low ones stay first). */
+    segmentsOmitted?: number;
+    tokensBefore: number;
+    tokensAfter: number;
+    tokensSaved: number;
+    /** Tool results replaced (`on`) or that would be (`shadow`). */
+    elided: number;
+    byReason: Record<ContextElisionReason, number>;
+    /**
+     * The standing context the next request carries after a compaction, as counts only: never the
+     * text of an instruction, goal, plan or criterion. All zero before the first compaction.
+     */
+    invariants: {
+        /** Invariants collected for the next request. */
+        count: number;
+        /** How many of them did not fit `context.invariants.maxChars` and are left out of the request. */
+        omitted: number;
+        byKind: Partial<Record<ContextInvariantKind, number>>;
+    };
+    /** Share of the tool results the agent acted on later; only kinds with decided results. */
+    usedRatioByKind: Partial<Record<ContextSegmentKind, number>>;
+    /** Heuristic usage counts of this process (advisory, lost on restart). */
+    usage?: {
+        observed: number;
+        used: number;
+        pending: number;
+        unattributed: number;
+        stubOnly: number;
+        rereads: number;
+        byTool?: Record<string, ContextUsageCounts>;
+    };
+}
 /** Every `RunEvent.type` the core emits today. `RunEvent.type` itself stays `string`. */
 export type RunEventType = keyof RunEventDataMap;
 /** Event types never persisted to the session store (and therefore without `eventId`). */
@@ -3095,6 +3238,14 @@ export interface EvalRunRecord {
          * treated as not reported by every aggregation.
          */
         usagePartial?: true;
+        /**
+         * Input tokens the provider served from its prompt cache, summed over the turns. ABSENT when
+         * the provider did not report it (never 0 for "unknown"); an explicit 0 from the provider is
+         * kept. Main-loop calls only, like `inputTokens`.
+         */
+        cachedInputTokens?: number;
+        /** True when only SOME turns that reported usage also reported cached tokens: the sum understates. */
+        cachedPartial?: true;
         wallMs: number;
         turns: number;
         toolCalls: number;
@@ -3170,6 +3321,10 @@ export interface EvalTaskMetrics {
         varianceTokens?: number;
         tokensPerSuccess?: number;
         wallMsPerSuccess?: number;
+        /** cachedInput / input tokens over the judged runs that reported it (see `cachedInputRuns`). */
+        cachedInputRatio?: number;
+        /** How many judged runs of this task reported cached input completely. */
+        cachedInputRuns?: number;
     };
     /** Present only when the caller supplied rates and every judged run reported usage. */
     estimated?: {
@@ -3212,6 +3367,18 @@ export interface EvalReport {
         budgetExceeded: number;
         runs?: number;
         failed?: number;
+        /**
+         * Provider cached input of this arm, over the judged runs that reported it completely (no
+         * partial sums, no partial usage). Absent when none did: no ratio is computed from nothing.
+         * `ratio` is tokens / inputTokens pooled over those runs, not a mean of run ratios.
+         */
+        cachedInput?: {
+            tokens: number;
+            inputTokens: number;
+            ratio: number;
+            runsReporting: number;
+            runsJudged: number;
+        };
     };
     /** The rates behind every `estimated` figure; absent when none was supplied. */
     rates?: EvalRates;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@alisio/sdk",
-  "version": "0.8.0",
+  "version": "0.10.0",
   "description": "Typed plugin SDK for Alisio: the stable contract for tools, commands, context, compaction and session hooks, model completions and storage. Types only plus tiny helpers; zero runtime dependencies.",
   "author": "Gustavo Gutiérrez",
   "license": "MIT",