@yaklabs-ai/plugin-sdk 0.54.0 → 0.54.1

package/dist/kay-app-session-summary.d.ts

@@ -25,6 +25,254 @@ declare function AddReadonlyDeferred<Type extends TSchema>(type: Type, options?:
  */
 declare type AgentMessage = Message | CustomAgentMessages[keyof CustomAgentMessages];
 
+/**
+ * The optional schema-validated terminal output contract a session may declare
+ * (issue #2234). `schema` is a bounded JSON object (a JSON Schema); `required`
+ * (default off) decides whether a text-only completion settles the turn -
+ * `true` holds every run to a submission, while the `"per-run"` literal defers
+ * the decision to each run's driver (a reused subagent session's assignment
+ * runs are stamped; its internal wake turns are not);
+ * `sessionTitle` (default off) adds the reserved `submit_final` field a turn
+ * uses to rename its own session; `whenToSubmit` is the one sentence telling the
+ * model when an OPTIONAL submission is worth making (ignored when `required`
+ * is `true` or `"per-run"`).
+ * The wire enforces the size caps and the credential-key tripwire; the herd
+ * kernel enforces the full acceptance policy (JSON-only, depth, non-local
+ * `$ref`).
+ *
+ * STRICT on purpose, which makes this schema a required stop for every new
+ * contract field: an unmirrored one is not merely absent on the wire, it fails
+ * the whole contract's parse, and the consumer that reads a stored session drops
+ * the contract entirely rather than reporting anything.
+ */
+declare const AgentRuntimeFinalOutputContract: z.ZodObject<{
+    schema: z.ZodType<{
+        [key: string]: JsonValue_4;
+    }, unknown, z.core.$ZodTypeInternals<{
+        [key: string]: JsonValue_4;
+    }, unknown>>;
+    required: z.ZodOptional<z.ZodUnion<readonly [z.ZodBoolean, z.ZodLiteral<"per-run">]>>;
+    sessionTitle: z.ZodOptional<z.ZodBoolean>;
+    whenToSubmit: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+declare type AgentRuntimeFinalOutputContract = z.infer<typeof AgentRuntimeFinalOutputContract>;
+
+/** Model pricing in USD per one million tokens. */
+declare const AgentRuntimeModelCost: z.ZodObject<{
+    input: z.ZodNumber;
+    output: z.ZodNumber;
+    cacheRead: z.ZodNumber;
+    cacheWrite: z.ZodNumber;
+}, z.core.$strict>;
+
+declare type AgentRuntimeModelCost = z.infer<typeof AgentRuntimeModelCost>;
+
+declare const AgentRuntimeModelFeatures: z.ZodObject<{
+    thinking: z.ZodBoolean;
+    vision: z.ZodBoolean;
+    toolUse: z.ZodBoolean;
+    streaming: z.ZodBoolean;
+    reasoning: z.ZodOptional<z.ZodBoolean>;
+    inputModalities: z.ZodArray<z.ZodEnum<{
+        text: "text";
+        image: "image";
+        audio: "audio";
+        video: "video";
+        pdf: "pdf";
+        embedding: "embedding";
+    }>>;
+    outputModalities: z.ZodArray<z.ZodEnum<{
+        text: "text";
+        image: "image";
+        audio: "audio";
+        video: "video";
+        pdf: "pdf";
+        embedding: "embedding";
+    }>>;
+    structuredOutput: z.ZodOptional<z.ZodBoolean>;
+    promptCaching: z.ZodOptional<z.ZodBoolean>;
+    contextWindow: z.ZodOptional<z.ZodNumber>;
+    maxOutputTokens: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
+declare type AgentRuntimeModelFeatures = z.infer<typeof AgentRuntimeModelFeatures>;
+
+declare const AgentRuntimeModelScores: z.ZodObject<{
+    intelligence: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+    }, z.core.$strict>>;
+    coding: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+    }, z.core.$strict>>;
+    speedTps: z.ZodOptional<z.ZodObject<{
+        value: z.ZodNumber;
+    }, z.core.$strict>>;
+    categories: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
+        value: z.ZodNumber;
+    }, z.core.$strict>>>;
+    source: z.ZodOptional<z.ZodString>;
+    asOf: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+declare type AgentRuntimeModelScores = z.infer<typeof AgentRuntimeModelScores>;
+
+declare const AgentRuntimeModelTierId: z.ZodEnum<{
+    small: "small";
+    medium: "medium";
+    large: "large";
+    ultra: "ultra";
+}>;
+
+declare type AgentRuntimeModelTierId = z.infer<typeof AgentRuntimeModelTierId>;
+
+/**
+ * One product model tier (resolved through the provider tier tables), projected with the
+ * model the tier RESOLVES TO for this runtime right now. `resolved` is absent
+ * when nothing - pin or floor - is currently eligible; the preview is
+ * point-in-time (checked-strength, never minting), so surfaces re-fetch rather
+ * than cache it across auth changes.
+ */
+declare const AgentRuntimeModelTierInfo: z.ZodObject<{
+    id: z.ZodEnum<{
+        small: "small";
+        medium: "medium";
+        large: "large";
+        ultra: "ultra";
+    }>;
+    displayName: z.ZodString;
+    description: z.ZodString;
+    resolved: z.ZodOptional<z.ZodObject<{
+        provider: z.ZodString;
+        modelId: z.ZodString;
+        modelReference: z.ZodString;
+        displayName: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>>;
+}, z.core.$strict>;
+
+declare type AgentRuntimeModelTierInfo = z.infer<typeof AgentRuntimeModelTierInfo>;
+
+/**
+ * One session-steward observation (hindsight): structured FACTS, never
+ * actions - appended to the session's log as a `session_steward` custom entry,
+ * from which summary state derives (`stewardTitle` / `stewardCommentary` /
+ * `stewardNextSteps` / `stewardCompactionSuggested`). Derivation is
+ * side-effect-free by contract. The compaction flag has two consumers:
+ * auto-compaction taken once at append time behind the
+ * `kayLoop.hindsight.stewardAutoCompact` flag, and - when auto-compact is
+ * off - the standing `stewardCompactionSuggested` summary field that backs
+ * the UI's "compact now" affordance. NOT itself a wire payload - it
+ * lives here as the ONE shared source of the summary's steward fields (the
+ * entry on disk, the backend fold, and the stored-state reader all validate
+ * against it); only the derived summary fields ever cross the wire.
+ */
+declare const AgentRuntimeSessionStewardEntry: z.ZodObject<{
+    titleChange: z.ZodNullable<z.ZodString>;
+    summaryAddition: z.ZodNullable<z.ZodString>;
+    nextSteps: z.ZodOptional<z.ZodArray<z.ZodString>>;
+    workHeadline: z.ZodOptional<z.ZodString>;
+    workHeadlineReview: z.ZodOptional<z.ZodArray<z.ZodUnion<readonly [z.ZodObject<{
+        labelKind: z.ZodEnum<{
+            purpose: "purpose";
+            result: "result";
+        }>;
+        text: z.ZodString;
+        faultProbability: z.ZodNullable<z.ZodNumber>;
+        accepted: z.ZodBoolean;
+        reason: z.ZodOptional<z.ZodString>;
+    }, z.core.$strict>, z.ZodObject<{
+        attempt: z.ZodObject<{
+            outcome: z.ZodEnum<{
+                error: "error";
+                none: "none";
+                rejected: "rejected";
+            }>;
+        }, z.core.$strict>;
+    }, z.core.$strict>]>>>;
+    workBlock: z.ZodOptional<z.ZodObject<{
+        firstToolResultEntryId: z.ZodString;
+        lastToolResultEntryId: z.ZodString;
+        toolResultEntryIds: z.ZodArray<z.ZodString>;
+    }, z.core.$strict>>;
+    goodCompactionOpportunity: z.ZodOptional<z.ZodBoolean>;
+    suggestedModelTier: z.ZodOptional<z.ZodNullable<z.ZodEnum<{
+        small: "small";
+        medium: "medium";
+        large: "large";
+        ultra: "ultra";
+    }>>>;
+    reviewedThroughEntryId: z.ZodOptional<z.ZodString>;
+    outcomeVerdict: z.ZodOptional<z.ZodNullable<z.ZodObject<{
+        verdict: z.ZodEnum<{
+            bad: "bad";
+            good: "good";
+            mixed: "mixed";
+            unclear: "unclear";
+        }>;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        basis: z.ZodString;
+        correctionsObserved: z.ZodNumber;
+        retriesObserved: z.ZodNumber;
+        rubricVersion: z.ZodNumber;
+    }, z.core.$strict>>>;
+    deferredVerdicts: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        subjectSessionId: z.ZodString;
+        verdict: z.ZodEnum<{
+            bad: "bad";
+            good: "good";
+            mixed: "mixed";
+            unclear: "unclear";
+        }>;
+        confidence: z.ZodEnum<{
+            low: "low";
+            medium: "medium";
+            high: "high";
+        }>;
+        basis: z.ZodString;
+        rubricVersion: z.ZodNumber;
+    }, z.core.$strict>>>;
+}, z.core.$strict>;
+
+declare type AgentRuntimeSessionStewardEntry = z.infer<typeof AgentRuntimeSessionStewardEntry>;
+
+/** One trailing-window spend view (mirrors `SpendWindowView`). */
+declare const AgentRuntimeSpendWindow: z.ZodObject<{
+    window: z.ZodEnum<{
+        trailing24h: "trailing24h";
+        trailing7d: "trailing7d";
+        trailing30d: "trailing30d";
+        trailing90d: "trailing90d";
+    }>;
+    measuredUsd: z.ZodNumber;
+    estimatedUsd: z.ZodNumber;
+    unknownTurns: z.ZodNumber;
+    tokens: z.ZodObject<{
+        input: z.ZodNumber;
+        output: z.ZodNumber;
+        cacheRead: z.ZodNumber;
+        cacheWrite: z.ZodNumber;
+    }, z.core.$strict>;
+    effectiveUsdPerMTok: z.ZodOptional<z.ZodNumber>;
+}, z.core.$strict>;
+
+declare type AgentRuntimeSpendWindow = z.infer<typeof AgentRuntimeSpendWindow>;
+
+declare const AgentRuntimeThinkingLevel: z.ZodEnum<{
+    max: "max";
+    off: "off";
+    minimal: "minimal";
+    low: "low";
+    medium: "medium";
+    high: "high";
+    xhigh: "xhigh";
+}>;
+
+declare type AgentRuntimeThinkingLevel = z.infer<typeof AgentRuntimeThinkingLevel>;
+
 declare const Alpha: TAlpha;
 
 /** Creates a Any type. */
@@ -1265,6 +1513,12 @@ declare type JsonValue_3 = string | number | boolean | null | JsonValue_3[] | {
 
 declare const JsonValue_3: z.ZodType<JsonValue_3>;
 
+declare type JsonValue_4 = string | number | boolean | null | JsonValue_4[] | {
+    [key: string]: JsonValue_4;
+};
+
+declare const JsonValue_4: z.ZodType<JsonValue_4>;
+
 /** The inert session-config subset a plugin-authored agent definition may contribute. */
 declare interface KayAppAgentDefinitionConfig {
     /**
@@ -1288,13 +1542,7 @@ declare interface KayAppAgentDefinitionConfig {
 }
 
 /** A plugin-authored definition's structured-output contract (the wire's final-output shape). */
-declare interface KayAppAgentDefinitionFinalOutput {
-    /** JSON Schema for the structured value a matching turn submits. */
-    readonly schema: JsonSchema;
-    readonly required?: boolean | "per-run";
-    readonly sessionTitle?: boolean;
-    readonly whenToSubmit?: string;
-}
+declare type KayAppAgentDefinitionFinalOutput = ReadonlyContract<AgentRuntimeFinalOutputContract>;
 
 /**
  * An opaque handle to one definition THIS plugin registered. `define` returns it; `sessions.run`
@@ -1400,27 +1648,10 @@ declare type KayAppModelCompleteOutcome = {
 };
 
 /** Per-million-token model prices projected by the host. */
-declare interface KayAppModelCost {
-    readonly input: number;
-    readonly output: number;
-    readonly cacheRead: number;
-    readonly cacheWrite: number;
-}
+declare type KayAppModelCost = Readonly<AgentRuntimeModelCost>;
 
 /** Model capabilities safe for plugin policy and presentation. */
-declare interface KayAppModelFeatures {
-    readonly thinking: boolean;
-    readonly vision: boolean;
-    readonly toolUse: boolean;
-    readonly streaming: boolean;
-    readonly reasoning?: boolean;
-    readonly inputModalities: readonly KayAppModelModality[];
-    readonly outputModalities: readonly KayAppModelModality[];
-    readonly structuredOutput?: boolean;
-    readonly promptCaching?: boolean;
-    readonly contextWindow?: number;
-    readonly maxOutputTokens?: number;
-}
+declare type KayAppModelFeatures = ReadonlyContract<AgentRuntimeModelFeatures>;
 
 /** The plugin-safe projection of one model in Bonsai's live model catalog. */
 declare interface KayAppModelInfo {
@@ -1450,9 +1681,6 @@ declare interface KayAppModelInfo {
     readonly disabledBy?: "privacy-setting" | "subscription-reauth";
 }
 
-/** Input or output modality advertised by a model. */
-declare type KayAppModelModality = "text" | "image" | "audio" | "video" | "pdf" | "embedding";
-
 /** Safe model catalog plus an optional, consented direct-completion broker. */
 declare interface KayAppModels {
     /** Returns the current projection; an empty catalog is an empty array. */
@@ -1477,23 +1705,11 @@ declare interface KayAppModels {
     complete?(input: KayAppModelCompleteInput): Promise<KayAppModelCompleteOutcome>;
 }
 
-/** One normalized model score. */
-declare interface KayAppModelScore {
-    readonly value: number;
-}
-
 /** Optional host-curated scores and their provenance. */
-declare interface KayAppModelScores {
-    readonly intelligence?: KayAppModelScore;
-    readonly coding?: KayAppModelScore;
-    readonly speedTps?: KayAppModelScore;
-    readonly categories?: Readonly<Record<string, KayAppModelScore>>;
-    readonly source?: string;
-    readonly asOf?: string;
-}
+declare type KayAppModelScores = ReadonlyContract<AgentRuntimeModelScores>;
 
 /** Bonsai's canonical task-difficulty tier vocabulary at the plugin boundary. */
-declare type KayAppModelTierId = "small" | "medium" | "large" | "ultra";
+declare type KayAppModelTierId = AgentRuntimeModelTierId;
 
 /**
  * The plugin-safe projection of one product model tier (small/medium/large/ultra -
@@ -1503,17 +1719,7 @@ declare type KayAppModelTierId = "small" | "medium" | "large" | "ultra";
  * something derivable from the model alone (the same model can be curated onto two
  * different tiers), so `listTiers()` is the only seam a plugin reads it through.
  */
-declare interface KayAppModelTierInfo {
-    readonly id: KayAppModelTierId;
-    readonly displayName: string;
-    readonly description: string;
-    readonly resolved?: {
-        readonly provider: string;
-        readonly modelId: string;
-        readonly modelReference: string;
-        readonly displayName?: string;
-    };
-}
+declare type KayAppModelTierInfo = ReadonlyContract<AgentRuntimeModelTierInfo>;
 
 /** An ephemeral one-shot agent definition. Identity and permission rules remain host-owned. */
 declare interface KayAppSessionAgentDefinition {
@@ -1529,33 +1735,7 @@ declare interface KayAppSessionAgentDefinition {
  * optional field follows one rule: OMITTED says nothing and leaves the standing value alone, while
  * an explicit value replaces it (`[]` withdraws the next steps, `false` clears a compaction offer).
  */
-declare interface KayAppSessionAnnotation {
-    readonly titleChange: string | null;
-    readonly summaryAddition: string | null;
-    readonly nextSteps?: readonly string[] | undefined;
-    /** A one-line label for the closed work block {@link workBlock} names. */
-    readonly workHeadline?: string;
-    readonly workHeadlineReview?: readonly ({
-        readonly labelKind: "result" | "purpose";
-        readonly text: string;
-        readonly faultProbability: number | null;
-        readonly accepted: boolean;
-        readonly reason?: string;
-    } | {
-        readonly attempt: {
-            readonly outcome: "none" | "rejected" | "error";
-        };
-    })[];
-    readonly workBlock?: WorkBlockCoverage;
-    readonly goodCompactionOpportunity?: boolean;
-    /** The last entry the annotation reviewed: the transcript marker's anchor. */
-    readonly reviewedThroughEntryId?: string;
-    /** A tier the remaining work suits better, or null when the current one still fits. */
-    readonly suggestedModelTier?: KayAppModelTierId | null;
-    readonly outcomeVerdict?: KayAppSessionOutcomeVerdict | null;
-    /** At most three; a verdict naming the annotated session itself is dropped. */
-    readonly deferredVerdicts?: readonly KayAppSessionDeferredVerdict[];
-}
+declare type KayAppSessionAnnotation = ReadonlyContract<AgentRuntimeSessionStewardEntry>;
 
 /** One stored session's spend, including the sessions it started. */
 declare interface KayAppSessionCost {
@@ -1623,21 +1803,7 @@ declare interface KayAppSessionCostModelBreakdown {
 }
 
 /** Token counts across a set of model calls. */
-declare interface KayAppSessionCostTokens {
-    readonly input: number;
-    readonly output: number;
-    readonly cacheRead: number;
-    readonly cacheWrite: number;
-}
-
-/** A verdict about an EARLIER session, filed on the annotated one and naming its subject. */
-declare interface KayAppSessionDeferredVerdict {
-    readonly subjectSessionId: string;
-    readonly verdict: KayAppSessionVerdict;
-    readonly confidence: KayAppSessionVerdictConfidence;
-    readonly basis: string;
-    readonly rubricVersion: number;
-}
+declare type KayAppSessionCostTokens = Readonly<AgentRuntimeSpendWindow["tokens"]>;
 
 /** One bounded page from the host's stored transcript reader. */
 declare interface KayAppSessionEntryBatch {
@@ -1750,19 +1916,6 @@ declare type KayAppSessionOrigin = {
     readonly forkedAtEntryId?: string | undefined;
 };
 
-/** A judgment of whether the annotated session's own work served the user. */
-declare interface KayAppSessionOutcomeVerdict {
-    readonly verdict: KayAppSessionVerdict;
-    readonly confidence: KayAppSessionVerdictConfidence;
-    /** The stated evidence. The host cuts an over-long basis on a word boundary. */
-    readonly basis: string;
-    /** User-correction turns counted in the transcript. */
-    readonly correctionsObserved: number;
-    /** Visible retry loops counted in the transcript. */
-    readonly retriesObserved: number;
-    readonly rubricVersion: number;
-}
-
 /**
  * One bounded page of a session's stored transcript, oldest first, or why there is none. Pass
  * `cursor` back for the next page. `replace` means the page starts over from the first record: the
@@ -2295,12 +2448,6 @@ export declare interface KayAppSessionSummaryResult {
     readonly continuation?: KayAppSessionSummaryContinuation;
 }
 
-/** How a session's work is judged to have served the user. `"unclear"` is a real answer, not a failure. */
-declare type KayAppSessionVerdict = "good" | "mixed" | "bad" | "unclear";
-
-/** The judge's own certainty: a tuning filter, never a weight the reader applies. */
-declare type KayAppSessionVerdictConfidence = "low" | "medium" | "high";
-
 export declare interface KayAppSessionWorkSummary {
     readonly goal: string;
     readonly work: readonly string[];
@@ -2337,7 +2484,7 @@ declare interface KayAppStoredSession {
 }
 
 /** Bonsai's reasoning-effort ladder, in ascending order. */
-declare type KayAppThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
+declare type KayAppThinkingLevel = AgentRuntimeThinkingLevel;
 
 /**
  * The host-stamped per-call context an app-contributed tool's `execute` receives. The app
@@ -3060,6 +3207,10 @@ declare function Readonly_2<Type extends TSchema>(type: Type): TAddReadonly<Type
 
 declare const Readonly_3: (input: string) => [unknown, string] | [];
 
+declare type ReadonlyContract<T> = T extends readonly (infer Item)[] ? readonly ReadonlyContract<Item>[] : T extends object ? {
+    readonly [Key in keyof T]: ReadonlyContract<T[Key]>;
+} : T;
+
 declare type ReadonlyKeys<Properties extends TProperties, Result extends PropertyKey = {
     [Key in keyof Properties]: Properties[Key] extends TReadonly<TSchema> ? (Properties[Key] extends TOptional<Properties[Key]> ? never : Key) : never;
 }[keyof Properties]> = Result;
@@ -7676,18 +7827,6 @@ declare const WithValue: (input: string) => [unknown, string] | [];
 
 declare function WithValueMapping(input: unknown): unknown;
 
-declare type WorkBlockCoverage = z.infer<typeof WorkBlockCoverageSchema>;
-
-/**
- * Exact ordered completed executions, addressed by persisted tool-result entry IDs.
- * Provider call IDs can repeat across retries and turns; they are never ownership keys.
- */
-declare const WorkBlockCoverageSchema: z.ZodObject<{
-    firstToolResultEntryId: z.ZodString;
-    lastToolResultEntryId: z.ZodString;
-    toolResultEntryIds: z.ZodArray<z.ZodString>;
-}, z.core.$strict>;
-
 declare interface XAdditionalItems<AdditionalItems extends XSchema = XSchema> {
     additionalItems: AdditionalItems;
 }