@yaklabs-ai/plugin-sdk 0.15.2 → 0.26.3

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

@@ -110,7 +110,7 @@ declare type AttachmentsMessage = CustomMessage<AttachmentsDetails> & {
  * or an {@link IdentityAttribution} for identity-bearing origins with no registry entry.
  *
  * Narrowing hazard: `SourceInfo` and `IdentityAttribution` both have a `string` `source`,
- * so a `source` value never distinguishes them — narrow `SourceInfo` by `"path" in x`
+ * so a `source` value never distinguishes them - narrow `SourceInfo` by `"path" in x`
  * (its required field), not by inspecting `source`.
  */
 declare type AttributionSource = SourceInfo | {
@@ -126,7 +126,7 @@ declare type AttributionSource = SourceInfo | {
 /**
  * The availability-facts message: who the user is connected as, which auth-gated tools are
  * waiting on a connect, and which installed plugins are not connected. DURABLE and never
- * turn-bound — that is the whole point of the kind.
+ * turn-bound - that is the whole point of the kind.
  *
  * These three facts used to be rendered into the system prompt, where they were the last
  * in-session prefix mutation (#2996): each of them changes on a connect or disconnect, and a
@@ -453,9 +453,9 @@ declare const CorpusResourceInvocationQuery: z.ZodObject<{
     }, z.core.$strict>>;
     limit: z.ZodOptional<z.ZodNumber>;
     rootCreatedByKind: z.ZodOptional<z.ZodEnum<{
+        plugin: "plugin";
         human: "human";
         agent: "agent";
-        plugin: "plugin";
         trigger: "trigger";
         daemon: "daemon";
     }>>;
@@ -540,7 +540,7 @@ declare const DAEMON_SERVICE_TURN_CUSTOM_TYPE = "daemon_service_turn";
 /**
  * A daemon-synthesized turn; `service` selects the per-service wrapper at the
  * boundary. `followup_lane` (a followup session's instruction turn) has no
- * reserved wrapper tag yet — it renders through the generic provenance-aware
+ * reserved wrapper tag yet - it renders through the generic provenance-aware
  * `kay_context` fallback until the lane message shape settles.
  */
 declare interface DaemonServiceTurnDetails {
@@ -549,8 +549,8 @@ declare interface DaemonServiceTurnDetails {
     /**
      * A short, HUMAN-facing description of this turn, for a visible service whose
      * `content` is not written for a person. For `"continuation"`, `content` is
-     * the MODEL's input — a runtime-authored instruction ("Complete the
-     * remaining part of that request. Do not propose another …") — and showing
+     * the MODEL's input - a runtime-authored instruction ("Complete the
+     * remaining part of that request. Do not propose another ...") - and showing
      * it to a person reads as though the user is being instructed, so the visible
      * row renders THIS instead. A continuation renderer missing a summary must
      * degrade to its own generic phrasing, never to `content`. For
@@ -632,9 +632,9 @@ declare interface DroppedContribution {
 
 /**
  * The Dynamic Context message: retrieval-produced context delivered right after human
- * text enters the conversation (prompt, steer, or a drained follow-up batch — one
+ * text enters the conversation (prompt, steer, or a drained follow-up batch - one
  * message per delivery moment). Assembled by the daemon's Dynamic Context coordinator
- * from per-contributor sections; push-only (contributors add a section or nothing —
+ * from per-contributor sections; push-only (contributors add a section or nothing -
  * they never mutate the human text or cancel the turn). Persisted like any other
  * message so the append-only transcript keeps the prompt cache warm.
  */
@@ -642,7 +642,7 @@ declare const DYNAMIC_CONTEXT_CUSTOM_TYPE = "dynamic_context";
 
 /**
  * The delivery moment that produced a Dynamic Context message: a new human prompt, a
- * mid-run steer, or a drained follow-up queue bundled as one batch (the batch law —
+ * mid-run steer, or a drained follow-up queue bundled as one batch (the batch law -
  * one retrieval pass per delivery moment, N drained texts = one message).
  */
 declare type DynamicContextChannel = "prompt" | "steer" | "follow_up";
@@ -679,7 +679,7 @@ declare type DynamicContextMessage = CustomMessage<DynamicContextDetails> & {
 /**
  * One contributor's section of a Dynamic Context message. `contributorId` owns the
  * inner wrapper tag at the model boundary (derived from the registration id, sanitized
- * by the projection — never free-form), so sections stay parsable per contributor.
+ * by the projection - never free-form), so sections stay parsable per contributor.
  */
 declare interface DynamicContextSection {
     readonly contributorId: string;
@@ -835,6 +835,42 @@ declare const Factor: (input: string) => [unknown, string] | [];
 
 declare function FactorMapping(input: [unknown, unknown, unknown, unknown, unknown]): unknown;
 
+declare const FAILURE_RELATIONS: readonly ["caused-by", "retry-of", "recovery-of", "cleanup-of"];
+
+declare type FailureJsonValue = null | boolean | number | string | readonly FailureJsonValue[] | {
+    readonly [key: string]: FailureJsonValue;
+};
+
+declare interface FailureOccurrence<C = FailureJsonValue> {
+    readonly ref: FailureRef;
+    readonly sourceRef: FailureRef;
+    readonly domain: string;
+    readonly code: string;
+    readonly context: {
+        readonly component: string;
+        readonly operation: string;
+        readonly operationRef?: FailureRef | undefined;
+        readonly attemptRef?: FailureRef | undefined;
+        readonly phase?: string | undefined;
+        readonly requestRef?: FailureRef | undefined;
+        readonly traceId?: string | undefined;
+        readonly spanId?: string | undefined;
+    };
+    readonly cause: C;
+    readonly relations?: readonly {
+        readonly kind: FailureRelationKind;
+        readonly failureRef: FailureRef;
+    }[] | undefined;
+    readonly diagnosticRef?: FailureRef | undefined;
+}
+
+declare interface FailureRef {
+    readonly authority: string;
+    readonly id: string;
+}
+
+declare type FailureRelationKind = (typeof FAILURE_RELATIONS)[number];
+
 /** Creates a Function type. */
 declare function _Function_<Parameters extends TSchema[], ReturnType extends TSchema>(parameters: [...Parameters], returnType: ReturnType, options?: TSchemaOptions): TFunction<Parameters, ReturnType>;
 
@@ -1206,6 +1242,10 @@ declare type JsonRepresentation<T> = IsAny_2<T> extends true ? JsonValue : unkno
     [TKey in keyof T]: JsonRepresentation<Exclude<T[TKey], undefined>>;
 } : never;
 
+declare const JsonSchema: z.ZodRecord<z.ZodString, z.ZodType<JsonValue_3, unknown, z.core.$ZodTypeInternals<JsonValue_3, unknown>>>;
+
+declare type JsonSchema = z.infer<typeof JsonSchema>;
+
 declare type JsonValue = null | boolean | number | string | readonly JsonValue[] | JsonObject;
 
 declare type JsonValue_2 = null | boolean | number | string | JsonValue_2[] | {
@@ -1218,115 +1258,68 @@ declare type JsonValue_3 = string | number | boolean | null | JsonValue_3[] | {
 
 declare const JsonValue_3: z.ZodType<JsonValue_3>;
 
-/**
- * Raw read access to every stored session's transcript. Always present on
- * `KayAppPluginApi`; each read is checked against the `corpus.read` claim, and refused
- * unless the user has granted it. Data is raw and un-redacted — the plugin filters to what it
- * needs. Invocation queries are bounded pages. Transcript reads materialize a whole session
- * before yielding; the iterable does not promise per-entry streaming or an allocation bound.
- */
-declare interface KayAppCorpus {
-    /** Page invocation leads under the live grant; inspect exclusions even on available empty pages. */
-    listResourceInvocations(query: CorpusResourceInvocationQuery): Promise<CorpusResourceInvocationPage>;
-    /** Enumerate every stored session, newest-first. */
-    listSessions(): AsyncIterable<KayAppCorpusSession>;
+/** The inert session-config subset a plugin-authored agent definition may contribute. */
+declare interface KayAppAgentDefinitionConfig {
     /**
-     * Yield one session's full entry log oldest→newest; an unknown id yields nothing. Treat the
-     * entries as read-only: for a session the daemon holds in memory they are its live objects.
+     * The definition's instructions: what this agent exists to do. Rendered as the
+     * agent-configuration trailer at the END of Bonsai's own prompt document, subordinate to
+     * everything above it. A definition never replaces Bonsai's prompt; it extends it.
      */
-    readEntries(sessionId: string): AsyncIterable<TranscriptEntry>;
-    /**
-     * Active-branch entries from the latest canonical human turn opener (send companions included)
-     * through the anchor, oldest first. Mid-turn steers and machine wakes remain inside that window;
-     * attachment-only openers and fresh card answers count. Missing sessions/anchors return [];
-     * unsupported hosts may omit it.
-     * Reads never fall back to materializing the full log.
-     */
-    readLatestHumanWindow?(sessionId: string, options?: {
-        readonly throughEntryId?: string;
-    }): Promise<readonly TranscriptEntry[]>;
-    /**
-     * Read one bounded page of a session's stored transcript. The host resolves `sessionId` to its
-     * authoritative indexed path and validates the opaque cursor before reading. When
-     * `throughEntryId` is supplied, the page ends at that entry and the cursor stays at the start of
-     * the commit holding it: the commit's other entries are returned for the caller to filter, and
-     * the next page replays that commit. A page can hold no entries at all (storage records with no
-     * entry) while more follows; a record longer than the page is stepped over and counted in
-     * `oversizedRecords`.
-     */
-    readEntryBatch?(sessionId: string, options?: {
-        readonly cursor?: JsonValue_3;
-        readonly throughEntryId?: string;
-        /** Host-only cancellation for the bounded physical read. */
-        readonly signal?: AbortSignal;
-    }): Promise<KayAppCorpusEntryBatch>;
+    readonly instructions?: string;
+    readonly activeToolNames?: readonly KayAppSessionRunHostToolName[];
+    readonly backgroundTasksEnabled?: boolean;
+    readonly model?: string;
+    readonly thinkingLevel?: KayAppThinkingLevel;
+    readonly cwd?: string;
     /**
-     * Read a cheap transcript change marker without loading the entry log. Unknown or deleted
-     * sessions yield `undefined`.
+     * The definition's structured-output contract for a settled turn. Bonsai's own default agent
+     * carries its standing-recap contract through this field; a plugin-authored definition may
+     * carry one too, with the same discipline: keep it optional, and use `whenToSubmit` to say
+     * when it applies rather than making every turn terminate through it.
      */
-    readSessionSourceMark(sessionId: string): Promise<KayAppCorpusSourceMark | undefined>;
+    readonly finalOutput?: KayAppAgentDefinitionFinalOutput;
 }
 
-/** One bounded page from the host's stored transcript reader. */
-declare interface KayAppCorpusEntryBatch {
-    readonly entries: readonly TranscriptEntry[];
-    /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
-    readonly cursor: JsonValue_3;
-    /** Opaque cursor at the physical page start, for a partial logical chunk. */
-    readonly pageStartCursor?: JsonValue_3;
-    readonly mode: "replace" | "append";
-    /**
-     * `record-too-large`: a record longer than the page that the host could not step over, because
-     * its end is not written yet or lies past the host's scan limit.
-     */
-    readonly status: "complete" | "more" | "awaiting-append" | "record-too-large";
-    /** Present when a caller supplied `throughEntryId`. */
-    readonly anchorFound?: boolean;
-    /** Records on this page the host could not parse; its other entries are returned. */
-    readonly malformedRecords: number;
-    /**
-     * Records longer than the page that this read stepped over without parsing them: at most one,
-     * and the page then holds no entries. When the caller's `throughEntryId` is inside it,
-     * `anchorFound` is true and the cursor is after it.
-     */
-    readonly oversizedRecords?: number;
-    /** Bytes of the stepped-over record, when there is one. */
-    readonly oversizedRecordBytes?: number;
+/** 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;
+}
+
+/**
+ * An opaque handle to one definition THIS plugin registered. `define` returns it; `sessions.run`
+ * accepts it in place of an inline definition.
+ *
+ * The brand keeps plugin code from CONSTRUCTING one - there is no value of this type an honest
+ * plugin can author, so a legitimate ref only ever exists by being returned from this plugin's own
+ * `define` call. That is a TypeScript authoring property, not the runtime security boundary: a
+ * determined plugin can still forge a structurally similar object at runtime, where the brand is
+ * erased. The actual boundary is host-side - the host re-validates every ref it receives against
+ * its own live registry (does a definition with this identity still exist, and does it belong to
+ * the calling plugin), on every use. A forged or stale ref resolves to nothing and the run is
+ * rejected; it never resolves to somebody else's definition.
+ */
+declare interface KayAppAgentDefinitionRef {
+    /** Brand only - erased at runtime, and unnameable (so unconstructable) from plugin code. */
+    readonly [kayAppAgentDefinitionRefBrand]: "kay.app/agent-definition-ref";
 }
 
-/** One stored session, as the granted corpus enumerates them. Keyed by its stable `sessionId`. */
-declare interface KayAppCorpusSession {
+declare const kayAppAgentDefinitionRefBrand: unique symbol;
+
+/** A newly persisted AgentSession. */
+declare interface KayAppCreatedSession {
     readonly sessionId: string;
+    readonly title?: string | undefined;
     /**
-     * Who the session is for, as stamped when it was created: a person's own session (`user`), a
-     * spawned subagent, or a session Bonsai runs with nobody watching (`system`, `followup`). It lets
-     * a reader skip sessions without opening their transcripts. Absent when the index does not know
-     * it (a session older than origin stamping, or a row not yet rebuilt from its transcript): that
-     * is unknown, not `user`.
+     * Whether a requested first turn actually started. Absent when no `message` was asked for.
+     *
+     * False means the session is open but empty: say so rather than claiming a running start that
+     * did not happen. True means the turn began, not that it completed.
      */
-    readonly origin?: KayAppSessionOrigin | undefined;
-    /** Resolved session title from the live index, when one exists. */
-    readonly title?: string | undefined;
-    /** Session creation time in ISO-8601 UTC, when the index has it. */
-    readonly createdAt?: string | undefined;
-    /** Last conversation activity in ISO-8601 UTC, when the index has it. */
-    readonly updatedAt?: string | undefined;
-    /** Current execution directory, when the index has it. */
-    readonly cwd?: string | undefined;
-    /** Persisted project binding; `null` means explicitly unassigned. */
-    readonly projectId?: string | null | undefined;
-    /** Parent session for a spawned member, when lineage is indexed. */
-    readonly parentSessionId?: string | null | undefined;
-    /** Family root session identity, when lineage is indexed. */
-    readonly rootSessionId?: string | undefined;
-}
-
-/** Cheap identity for the current contents of one stored session transcript. */
-declare interface KayAppCorpusSourceMark {
-    readonly mtimeMs: number;
-    readonly sizeBytes: number;
-    /** Opaque content/source identity; absent on legacy or test corpus implementations. */
-    readonly sourceRevision?: string | undefined;
+    readonly messageDelivered?: boolean | undefined;
 }
 
 /**
@@ -1356,10 +1349,17 @@ declare interface KayAppModelCompleteInput {
     /** Exact provider-qualified reference or `small`/`medium`/`large`/`ultra`. */
     readonly model: string;
     readonly thinkingLevel?: KayAppThinkingLevel;
-    /** Defaults to 2048; accepted range is 1–8192. */
+    /** Defaults to 2048; accepted range is 1-8192. */
     readonly maxTokens?: number;
-    /** Defaults to 60000 ms; accepted range is 1000–120000 ms. */
+    /** Defaults to 60000 ms; accepted range is 1000-120000 ms. */
     readonly timeoutMs?: number;
+    /**
+     * The session event this call answers. With one, the call's spend is charged to
+     * `cause.sourceSessionId`, which must be a session one of this plugin's `sessionEvents` handlers
+     * is handling right now (otherwise the call is `rejected`). Without one, the spend is the
+     * plugin's own.
+     */
+    readonly cause?: KayAppSessionEventCause;
 }
 
 declare type KayAppModelCompleteOutcome = {
@@ -1433,13 +1433,14 @@ declare interface KayAppModelInfo {
     readonly releaseDate?: string;
     readonly composition?: "single" | "router" | "ensemble";
     /**
-     * Why the model is switched off right now, when a setting the person
-     * controls disables it: `privacy-setting` is Bonsai's switch that turns off
-     * hosted providers that store data. Bonsai never selects a disabled model
-     * and refuses a request on it, so a plugin should not offer or pin one.
-     * Absent means the model is not disabled.
+     * Why the model is switched off right now. `privacy-setting` is Bonsai's
+     * switch that turns off hosted providers that store data;
+     * `subscription-reauth` means the provider's only credential is a
+     * subscription the provider refused to renew, until the person reconnects it.
+     * Bonsai never selects a disabled model and refuses a request on it, so a
+     * plugin should not offer or pin one. Absent means the model is not disabled.
      */
-    readonly disabledBy?: "privacy-setting";
+    readonly disabledBy?: "privacy-setting" | "subscription-reauth";
 }
 
 /** Input or output modality advertised by a model. */
@@ -1454,9 +1455,12 @@ declare interface KayAppModels {
     /**
      * Returns the four product model tiers, each with its live point-in-time resolution
      * when one is currently eligible right now. Re-fetch rather than cache across auth or
-     * precedence-config changes — the projection is checked-strength, never minting.
+     * precedence-config changes - the projection is checked-strength, never minting.
      */
-    listTiers(): Promise<readonly KayAppModelTierInfo[]>;
+    listTiers(options?: {
+        /** Resolve each tier on this provider, the way a session pinned to it would. */
+        readonly provider?: string;
+    }): Promise<readonly KayAppModelTierInfo[]>;
     /**
      * Run one isolated, cost-accounted completion. Present only when the host composed a model
      * lane; each call authorizes a `models.complete` claim (kay.app) against the grant ledger.
@@ -1485,7 +1489,7 @@ declare interface KayAppModelScores {
 declare type KayAppModelTierId = "small" | "medium" | "large" | "ultra";
 
 /**
- * The plugin-safe projection of one product model tier (small/medium/large/ultra —
+ * The plugin-safe projection of one product model tier (small/medium/large/ultra -
  * see {@link KayAppModels.listTiers}), with its live point-in-time resolution when a model
  * is currently eligible for it. Deliberately has NO analogous per-model tier field on
  * {@link KayAppModelInfo}: a model's tier membership is carried-forward identity, not
@@ -1504,6 +1508,226 @@ declare interface KayAppModelTierInfo {
     };
 }
 
+/** An ephemeral one-shot agent definition. Identity and permission rules remain host-owned. */
+declare interface KayAppSessionAgentDefinition {
+    readonly name: string;
+    readonly description?: string;
+    readonly icon?: string;
+    readonly config: KayAppAgentDefinitionConfig;
+}
+
+/**
+ * One annotation on a session's log: what the person sees beside the conversation (its title, its
+ * recap line, the suggested next steps, a work block's headline) and the facts behind them. Each
+ * 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[];
+}
+
+/** One stored session's spend, including the sessions it started. */
+declare interface KayAppSessionCost {
+    readonly sessionId: string;
+    readonly rootSessionId: string;
+    /** When the read finished, ISO-8601 UTC. */
+    readonly asOf: string;
+    /** The days the read covered, and whether it stopped before the whole range. */
+    readonly coverage: {
+        readonly startDay: string;
+        readonly endDay: string;
+        readonly scan: {
+            readonly complete: true;
+        } | {
+            readonly complete: false;
+            readonly completeAfterDay: string;
+        };
+        readonly truncated: boolean;
+        /** True when the model list was capped; the totals still count every call. */
+        readonly modelInventoryTruncated?: boolean;
+    };
+    readonly total: KayAppSessionCostBreakdown;
+    /** Calls the session made itself. */
+    readonly direct: KayAppSessionCostBreakdown;
+    /** Calls made by sessions it started. */
+    readonly descendants: KayAppSessionCostBreakdown;
+    /** Calls in the session family that name no session. */
+    readonly unattributed: KayAppSessionCostBreakdown;
+    readonly descendantSessionCount: number;
+    readonly models: readonly KayAppSessionCostModelBreakdown[];
+}
+
+/**
+ * What `readCost` answers. `unavailable` covers a plugin without `sessions.read`, a host that records
+ * no usage, an unknown or deleted session, and a read that failed; it is never zeros.
+ */
+declare type KayAppSessionCostAnswer = {
+    readonly status: "ok";
+    readonly cost: KayAppSessionCost;
+} | {
+    readonly status: "unavailable";
+    readonly reason: string;
+};
+
+/**
+ * What a set of model calls cost. Measured dollars come from the provider; catalog estimates
+ * price calls the provider did not bill directly; unknown calls have no price either way.
+ */
+declare interface KayAppSessionCostBreakdown {
+    readonly measuredUsd: number;
+    readonly measuredCallCount: number;
+    readonly catalogEstimateUsd: number;
+    readonly catalogEstimateCallCount: number;
+    readonly unknownCallCount: number;
+    readonly callCount: number;
+    readonly tokens: KayAppSessionCostTokens;
+}
+
+declare interface KayAppSessionCostModelBreakdown {
+    /** Null when older telemetry has no model identity. */
+    readonly model: string | null;
+    /** The one provider that served this model's calls; absent when unattributed or split. */
+    readonly provider?: string;
+    readonly total: KayAppSessionCostBreakdown;
+}
+
+/** 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;
+}
+
+/** One bounded page from the host's stored transcript reader. */
+declare interface KayAppSessionEntryBatch {
+    readonly entries: readonly TranscriptEntry[];
+    /** Opaque JSON cursor after the physical page; only the host may interpret it or open its path. */
+    readonly cursor: JsonValue_3;
+    /** Opaque cursor at the physical page start, for a partial logical chunk. */
+    readonly pageStartCursor?: JsonValue_3;
+    readonly mode: "replace" | "append";
+    /**
+     * `record-too-large`: a record longer than the page that the host could not step over, because
+     * its end is not written yet or lies past the host's scan limit.
+     */
+    readonly status: "complete" | "more" | "awaiting-append" | "record-too-large";
+    /** Present when a caller supplied `throughEntryId`. */
+    readonly anchorFound?: boolean;
+    /** Records on this page the host could not parse; its other entries are returned. */
+    readonly malformedRecords: number;
+    /**
+     * Records longer than the page that this read stepped over without parsing them: at most one,
+     * and the page then holds no entries. When the caller's `throughEntryId` is inside it,
+     * `anchorFound` is true and the cursor is after it.
+     */
+    readonly oversizedRecords?: number;
+    /** Bytes of the stepped-over record, when there is one. */
+    readonly oversizedRecordBytes?: number;
+}
+
+/**
+ * The cause a plugin supplies to {@link KayAppAgents.run} (G1, 2026-09) - what a
+ * `app.sessionEvents.subscribe` handler is reacting to. This is the WHOLE cause the plugin
+ * states; the host derives `plugin` itself from the calling plugin id (never taken from this
+ * object), mints a `traceId`, and stamps the spawned session's provenance with everything here.
+ *
+ * TWO KINDS (G5, 2026-09). `kind` omitted or `"session-event"` is the original, LIVE shape: a
+ * `sessionEvents.subscribe` handler reacting to a published event, which the `event` field names.
+ * `kind: "backfill"` is a plugin's own HISTORICAL-session sweep - run at its own initiative (over
+ * sessions it discovers through its granted `KayAppSessions`, not from a published event), so there
+ * is no `event` to carry. A backfill cause should always supply `dedupeKey` (by convention
+ * `` `backfill:${sessionId}` ``, never enforced by the host) so a sweep can never double-run the
+ * same historical session across daemon restarts.
+ */
+declare type KayAppSessionEventCause = {
+    readonly kind?: "session-event";
+    /** This plugin's own name for the handler making this run, e.g. `"work-record"`. Not minted. */
+    readonly handler: string;
+    /** The session whose event caused this run - ordinarily the event's own `sessionId`. */
+    readonly sourceSessionId: string;
+    readonly event: {
+        readonly type: KayAppSessionEventType;
+        readonly entryId: string;
+        /**
+         * The delivered event's own {@link KayAppTurnSettledSessionEvent.runId}, when the handler
+         * has one to relay - always present for a `turn-settled` event, legitimately absent for a
+         * `phase-shift` one (an observation can span more than one run). Relay it verbatim; never
+         * substitute a run id resolved another way.
+         */
+        readonly runId?: string;
+        /** Exact prior persisted boundary for a projected human-message event; null means empty history. */
+        readonly throughEntryId?: string | null;
+    };
+    /**
+     * Exact-match dedupe key. The host REFUSES a second run carrying the same key outright (a
+     * rejected outcome, never a silent skip), so a handler can tell a genuine duplicate from an
+     * ordinary rejection. Omit to admit every call unconditionally.
+     */
+    readonly dedupeKey?: string;
+} | {
+    readonly kind: "backfill";
+    readonly handler: string;
+    readonly sourceSessionId: string;
+    readonly dedupeKey?: string;
+};
+
+/**
+ * A closed, extensible union: a projected human or persisted assistant message, a settled turn, an accepted phase-shift
+ * observation, or a projected interface action. They share one subscribable set now that there is
+ * no dispatcher chaining one job's completion into another's `when`. Adding a type is additive,
+ * never breaking: `assistant-message` is the fifth.
+ */
+declare type KayAppSessionEventType = "human-message" | "assistant-message" | "turn-settled" | "phase-shift" | "ui-action";
+
+/** Index rows, most recently active first. Deleted sessions are never listed. */
+declare interface KayAppSessionList {
+    readonly sessions: readonly KayAppStoredSession[];
+    /** How many sessions the index lists in total; present only for the offset form. */
+    readonly totalCount?: number;
+}
+
+/** One page of the session index by position, or the rows for these ids. */
+declare type KayAppSessionListRequest = {
+    readonly offset: number;
+    readonly limit: number;
+} | {
+    readonly sessionIds: readonly string[];
+};
+
 declare type KayAppSessionOrigin = {
     readonly kind: "user";
     readonly surface?: string | undefined;
@@ -1519,6 +1743,448 @@ 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
+ * first page always does, and a later one does when the session was written to after your first
+ * page was read and a write changed a record before the cursor, or when its storage was replaced.
+ * Anything derived from earlier pages is then stale; the `replace` page is the new first page.
+ */
+declare type KayAppSessionPage = {
+    readonly kind: "page";
+    readonly items: readonly KayAppSessionPageItem[];
+    /** Opaque JSON: only the host interprets it. */
+    readonly cursor: JsonValue_3;
+    readonly mode: "replace" | "append";
+    /** `more`: read again from `cursor`. `complete`: nothing more is stored. */
+    readonly status: "more" | "complete";
+} | KayAppSessionPageFailure;
+
+/**
+ * Why a session's page could not be read: `unknown` (no index row, or a deleted one), `missing`
+ * (indexed, but its storage is gone), `unrecognized` (a chat still on its legacy `.jsonl`, which
+ * converts on its next open), `unreadable` (a permission refusal, an I/O error or a store the
+ * host cannot read, with its reason), `busy` (the host's reads are overloaded, out of memory or
+ * timed out; the same read may succeed in a moment), or `escaped` (the index row resolves outside
+ * this install's session storage, so nothing was read).
+ */
+declare type KayAppSessionPageFailure = {
+    readonly kind: "unknown";
+} | {
+    readonly kind: "missing";
+} | {
+    readonly kind: "unrecognized";
+} | {
+    readonly kind: "unreadable";
+    readonly reason: string;
+} | {
+    readonly kind: "busy";
+    readonly reason: string;
+} | {
+    readonly kind: "escaped";
+};
+
+/**
+ * One item of a {@link KayAppSessionPage}, in stored order: an entry, or a stored record that did
+ * not parse (`unreadable`, with the storage row's id), which still takes its place. Rely on
+ * `entry`, `preview`, `unreadable` and `entryId`; `commitSeq` and `commitIndex` only order items
+ * within one session's pages and are not stable across hosts.
+ *
+ * An entry over 256 KiB stored is its preview: its long text is cut to about its first 8 KB and
+ * its images and files are replaced, and `preview.bytes` is the whole entry's stored size. Body
+ * references stay with the host, so no SDK read returns the rest yet.
+ */
+declare type KayAppSessionPageItem = (Omit<Extract<TranscriptPageItem, {
+    readonly entry: unknown;
+}>, "bodies"> & {
+    readonly preview?: {
+        readonly bytes: number;
+    };
+}) | Extract<TranscriptPageItem, {
+    readonly unreadable: unknown;
+}>;
+
+/**
+ * What one headless system run reports back. The run's spend is read from the
+ * ledger after the turn settles; `cost` is absent when no spend rows were
+ * found and `complete: false` marks a run with at least one unpriced turn.
+ */
+declare interface KayAppSessionRunBase {
+    readonly kind: "ran";
+    readonly sessionId: string;
+    /** The run that produced this outcome, when the owning path can name it. */
+    readonly runId?: string | undefined;
+    /** Host-captured provenance for the producing session, retained for direct store writes. */
+    readonly provenanceCapture?: Record<string, unknown> | undefined;
+    /** The run's final output text (the headless session's reply channel). */
+    readonly output: string;
+    /** Present when a structured completion was requested and the run completed. */
+    readonly result?: JsonValue_3;
+    readonly errorMessage?: string | undefined;
+    /** Attested live host-tool roster when the caller requested one explicitly. */
+    readonly activeToolNames?: readonly KayAppSessionRunHostToolName[] | undefined;
+    readonly cost?: {
+        readonly usd: number;
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly complete: boolean;
+    } | undefined;
+}
+
+/** How a headless system run returns its terminal answer. */
+declare type KayAppSessionRunCompletion = {
+    readonly kind: "text";
+} | {
+    readonly kind: "structured";
+    /** JSON Schema for the required value returned through `result`. */
+    readonly schema: JsonSchema;
+};
+
+/** Provider-neutral recorded classification; an unclassified failure omits the field. */
+declare type KayAppSessionRunFailureReason = Exclude<RunFailureReason, "unknown">;
+
+/**
+ * The identity of a failed run's retained failure: the same ref the runtime keeps on the
+ * session and the automation run. A workflow that fails BECAUSE this run failed passes it as
+ * its error's `cause` (`{ cause: { failureRef } }`), and the host reports that failure, not a
+ * guess from whichever run settled last.
+ */
+declare interface KayAppSessionRunFailureRef {
+    readonly authority: string;
+    readonly id: string;
+}
+
+/** One host-tool name in a one-shot system run's explicit ceiling. */
+declare type KayAppSessionRunHostToolName = string;
+
+/** The one-shot headless run request shared by `sessions.run` and workflow contexts. */
+declare interface KayAppSessionRunInput {
+    /** Attribution slug (`^[a-z][a-z0-9-]*$`) naming what this run is for. */
+    readonly purpose: string;
+    readonly instructions: string;
+    /** Defaults to ordinary reply text when omitted. */
+    readonly completion?: KayAppSessionRunCompletion | undefined;
+    readonly label?: string | undefined;
+    /**
+     * Stable identity of this call within one run. Two calls with the same key are the same unit
+     * of work: on resume after a crash, a settled result for the key is returned instead of running
+     * the agent again. Omit it and the call is never memoized: it re-runs if the run resumes.
+     *
+     * Only a workflow's `runAgent` reads this. `sessions.run` has no run to resume, so it ignores
+     * the key entirely.
+     *
+     * The key is YOUR declaration, so it must name the WORK and nothing else. Anything regenerated
+     * per attempt (a UUID, a timestamp, a nonce spliced into the prompt) makes every key unique and
+     * memoizes nothing. Derive it from the item being worked on: the bucket key, the source id, a
+     * constant for a stage that happens once.
+     *
+     * The same key twice inside one run is legitimate and is NOT collapsed: a retry of a stage that
+     * failed is a second unit of work, and the engine matches the i-th call for a key to the i-th
+     * recorded result. Distinct work must therefore carry distinct keys, because reusing one key
+     * for two different items would hand the first item's result to the second on resume.
+     *
+     * At most 200 characters, and non-empty once trimmed; anything else is rejected at the call.
+     */
+    readonly key?: string | undefined;
+    readonly cwd?: string | undefined;
+    /**
+     * How long the run may take. What an omitted value means belongs to the door you called, and
+     * the two doors differ:
+     *
+     * - `sessions.run` - omitted is five minutes, and any value is clamped into [10 s, 600 s].
+     *   This door always bounds its runs, so `null` is rejected.
+     * - a workflow's `runAgent` - omitted means the agent runs until it FINISHES, however long that
+     *   takes. A number bounds it (unclamped, up to the protocol's one-hour maximum), and `null` is
+     *   the explicit spelling of the same "no clock" the omitted form already gives you.
+     */
+    readonly timeoutMs?: number | null | undefined;
+    /**
+     * Absolute epoch-millisecond boundary for admission plus execution. The host starts a turn
+     * only when one full `timeoutMs` still fits strictly before this deadline, so a run with no
+     * clock cannot carry one - it has no turn length to fit.
+     */
+    readonly deadlineAtMs?: number | undefined;
+    /**
+     * Explicit host-tool roster for this one-shot run. The host enforces it as a subtractive
+     * ceiling; reserved session-builtins such as `submit_final` remain available. The caller owns
+     * any replay-safety policy for the names it supplies.
+     */
+    readonly activeToolNames?: readonly KayAppSessionRunHostToolName[] | undefined;
+    /**
+     * The run's model, as either an exact pin (a provider-qualified reference from
+     * `KayAppModels.list`) or a tier word (`small`/`medium`/`large`/`ultra` -
+     * see `KayAppModels.listTiers`); absent, the daemon resolves
+     * the configured default. A tier word resolves through the same chokepoint every
+     * other tier selection does - the daemon picks the concrete model, never the
+     * plugin. An unavailable pin fails the run rather than silently substituting.
+     */
+    readonly model?: string | undefined;
+    /** Pin the run's thinking level; absent, the daemon resolves its default. */
+    readonly thinkingLevel?: KayAppThinkingLevel | undefined;
+    /**
+     * Which agent runs this one-shot, in either of the two forms a plugin may name one.
+     *
+     * An INLINE {@link KayAppSessionAgentDefinition} describes an agent for this run alone: the
+     * host stamps its identity, accepts no permission rules, and the definition dies with the run.
+     * It stays for one-shot callers with nothing to reuse.
+     *
+     * A {@link KayAppAgentDefinitionRef} names one of THIS plugin's definitions registered during
+     * activation, which may carry permission rules and may own its own `completion` contract.
+     * When the referenced definition owns a completion, a run-level {@link completion} is
+     * REJECTED rather than merged - see {@link KayAppAgentDefinition.completion}.
+     *
+     * Absent, the run takes the host's default agent, unchanged.
+     */
+    readonly agent?: KayAppSessionAgentDefinition | KayAppAgentDefinitionRef | undefined;
+}
+
+declare type KayAppSessionRunOutcome = (KayAppSessionRunBase & {
+    readonly state: "failed";
+    /** The retained failure record, absent when the runtime kept none for this run. */
+    readonly failure?: (RunFailureRecord & {
+        readonly retryable: boolean;
+    }) | undefined;
+    /** The retained failure's identity, when the runtime kept one for this run. */
+    readonly failureRef?: KayAppSessionRunFailureRef | undefined;
+    /** Present when the runtime could classify the failure. */
+    readonly failureReason?: KayAppSessionRunFailureReason | undefined;
+    /** Bounded provider-suggested delay before retrying this terminal failure. */
+    readonly retryAfterMs?: number | undefined;
+}) | (KayAppSessionRunBase & {
+    readonly state: "completed" | "cancelled";
+    readonly failureReason?: never;
+}) | {
+    readonly kind: "unavailable";
+}
+/** The host refused the run - pool exhausted or invalid input. */
+| {
+    readonly kind: "rejected";
+    readonly reason: string;
+}
+/**
+* `agents.run`-only (G1, 2026-09): `cause.dedupeKey` matched an already-admitted run.
+* `existingSessionId` names that run's session so a handler can look up its result instead of
+* treating this as an ordinary rejection. `sessions.run`/`workflows` never produce
+* this case - they carry no `cause.dedupeKey` concept - so their existing exhaustive switches
+* are unaffected in practice; only a switch reached through `agents.run`'s outcome need add it.
+*/
+| {
+    readonly kind: "deduplicated";
+    readonly existingSessionId: string;
+};
+
+/** Settled run outcomes of one session, tallied from its log. */
+declare interface KayAppSessionRunTally {
+    readonly completed: number;
+    readonly interrupted: number;
+    readonly cancelled: number;
+    readonly failed: number;
+}
+
+/**
+ * Stored conversation reads and session operations. Reads check `sessions.read`; actions retain
+ * their separate `sessions.create`, `sessions.update`, and `sessions.run` claims. Control methods
+ * are absent when the host composed no session-control lane. History is raw and un-redacted.
+ * `readEntries` may materialize a whole session; use bounded reads for bounded allocation.
+ */
+declare interface KayAppSessions {
+    /** Page invocation leads under the live grant; inspect exclusions even on available empty pages. */
+    listResourceInvocations(query: CorpusResourceInvocationQuery): Promise<CorpusResourceInvocationPage>;
+    /** Enumerate every stored session, newest-first. */
+    listSessions(): AsyncIterable<KayAppStoredSession>;
+    /**
+     * Yield one session's full entry log oldest->newest; an unknown id yields nothing. Treat the
+     * entries as read-only: for a session the daemon holds in memory they are its live objects.
+     */
+    readEntries(sessionId: string): AsyncIterable<TranscriptEntry>;
+    /**
+     * Active-branch entries from the latest canonical human turn opener (send companions included)
+     * through the anchor, oldest first. Mid-turn steers and machine wakes remain inside that window;
+     * attachment-only openers and fresh card answers count. Missing sessions/anchors return [];
+     * unsupported hosts may omit it.
+     * Reads never fall back to materializing the full log.
+     */
+    readLatestHumanWindow?(sessionId: string, options?: {
+        readonly throughEntryId?: string;
+    }): Promise<readonly TranscriptEntry[]>;
+    /**
+     * What one stored session cost, which models served it, and from which providers. A session's
+     * cost is part of reading it, so this checks `sessions.read` like the other reads (SDK 0.17.4).
+     * Never rejects: anything it cannot answer is `unavailable`. Unsupported hosts may omit it.
+     */
+    readCost?(sessionId: string): Promise<KayAppSessionCostAnswer>;
+    /**
+     * Read one bounded page of a session's stored transcript. The host resolves `sessionId` to its
+     * authoritative indexed path and validates the opaque cursor before reading. When
+     * `throughEntryId` is supplied, the page ends at that entry and the cursor stays at the start of
+     * the commit holding it: the commit's other entries are returned for the caller to filter, and
+     * the next page replays that commit. A page can hold no entries at all (storage records with no
+     * entry) while more follows; a record longer than the page is stepped over and counted in
+     * `oversizedRecords`.
+     */
+    readEntryBatch?(sessionId: string, options?: {
+        readonly cursor?: JsonValue_3;
+        readonly throughEntryId?: string;
+        /** Host-only cancellation for the bounded physical read. */
+        readonly signal?: AbortSignal;
+    }): Promise<KayAppSessionEntryBatch>;
+    /**
+     * Read one page of a session's stored transcript (SDK 0.19.2): every record, at most 256 records
+     * and 1 MiB per page, with an entry over 256 KiB returned as its preview (see
+     * {@link KayAppSessionPageItem}). The host resolves the id through its session index (a deleted
+     * session is `unknown`), checks the storage lies inside this install's session storage, and
+     * answers a session it cannot read as a typed failure rather than a rejection. Checked against
+     * `sessions.read` at every call, a continuation included. Unsupported hosts may omit it.
+     */
+    readPage?(sessionId: string, options?: {
+        readonly cursor?: JsonValue_3;
+    }): Promise<KayAppSessionPage>;
+    /**
+     * One page of the session index, or the rows for given ids (SDK 0.19.2), at most 500 rows or
+     * ids per call: ids past that are dropped, so page by offset/limit or chunk the ids. Checked
+     * against `sessions.read`. Unsupported hosts may omit it.
+     */
+    listSessionPage?(request: KayAppSessionListRequest): Promise<KayAppSessionList>;
+    /**
+     * Read a cheap transcript change marker without loading the entry log. Unknown or deleted
+     * sessions yield `undefined`.
+     */
+    readSessionSourceMark(sessionId: string): Promise<KayAppSessionSourceMark | undefined>;
+    /**
+     * The session's standing recap, run tally and model choice, folded by the host from the
+     * session's own log. Checked against `sessions.read`. An unknown session resolves `undefined`.
+     */
+    readSessionState?(sessionId: string): Promise<KayAppSessionState | undefined>;
+    /**
+     * Write one annotation onto a session's log. Checked against `sessions.annotate`, and only for
+     * a session whose event one of this plugin's `sessionEvents` handlers is handling right now: a
+     * call for any other session, or after the handler returned, rejects. The host applies its own
+     * bounds to every verdict. `judgeModel` names the `provider/modelId` that rendered the verdicts,
+     * when it is not the session's own model.
+     */
+    annotate?(sessionId: string, annotation: KayAppSessionAnnotation, options?: {
+        readonly judgeModel?: string;
+    }): Promise<void>;
+    /**
+     * Ask the host to compact a session's context now. Checked against `sessions.compact`, bound
+     * like {@link annotate}. Resolves `false`, a normal answer, when the person has not allowed it or
+     * the context is too empty to be worth a compaction; `true` once it compacted. Rejects only when
+     * an allowed compaction failed.
+     */
+    compact?(sessionId: string): Promise<boolean>;
+    create?(input: {
+        /** Omit to inherit the opener's cwd, unless an explicit project supplies its default. */
+        readonly cwd?: string;
+        /** Omit to inherit the opener; null explicitly selects no project. */
+        readonly projectId?: string | null;
+        readonly title?: string | undefined;
+        /**
+         * The new session's model, as a tier word (`small`, `medium`, `large`, `ultra`): the daemon
+         * picks the concrete model through the same tier resolution every other tier choice takes.
+         * Absent, the person's own selection applies, so a session a plugin opens on its own account
+         * runs on whatever they happen to be using, Ultra included. Work that does not need a strong
+         * model names a tier. A tier only: an exact model pin is not offered here.
+         */
+        readonly tier?: KayAppModelTierId | undefined;
+        /**
+         * The session asking for this one, so the daemon can record which session opened it.
+         * Pass the calling tool's own `ctx.sessionId` and nothing else: the daemon vets the id
+         * against its live sessions and drops an edge it cannot confirm, so an invented value
+         * buys nothing.
+         */
+        readonly openedBySessionId?: string;
+        /**
+         * A first user turn to deliver into the new session, so it opens already working rather than
+         * blank. Absent leaves it empty and waiting.
+         *
+         * Resolves once the turn has STARTED, never once it has finished: the caller is mid-turn in
+         * its own session, and waiting on another agent's whole answer would freeze the conversation
+         * that opened the tab. Check {@link KayAppCreatedSession.messageDelivered} to see whether it
+         * actually started.
+         */
+        readonly message?: string;
+    }): Promise<{
+        readonly kind: "created";
+        readonly session: KayAppCreatedSession;
+    } | {
+        readonly kind: "unavailable";
+    }>;
+    /**
+     * Admit one approved command into a blank session this capability instance created. The host
+     * resolves the command against the session's live command index and returns once it is admitted,
+     * not when the model turn finishes. Implementations may omit this on older hosts.
+     */
+    start?(input: {
+        readonly sessionId: string;
+        readonly command: string;
+        readonly typedName: string;
+        readonly argsText: string;
+    }): Promise<{
+        readonly kind: "started";
+    } | {
+        readonly kind: "unavailable";
+    }>;
+    /**
+     * Change this tool call's current session project without changing its working directory.
+     * Checked against `sessions.update`. The host-stamped context selects the session; plugins
+     * cannot target an arbitrary session id.
+     */
+    setProject?(input: {
+        readonly projectId: string | null;
+    }, context: KayAppToolContext): Promise<{
+        readonly kind: "updated";
+        readonly projectId: string | null;
+        readonly cwd: string;
+    } | {
+        readonly kind: "unavailable";
+    }>;
+    /**
+     * Run one hidden headless system session through Bonsai's harness and resolve
+     * with its final output - the sole sanctioned way for a `kay.app` plugin to
+     * spend model tokens outside a session-event handler. Checked per call against
+     * the `sessions.run` claim. A plugin may request a model/tier and supply
+     * a strict ephemeral agent definition, but the host validates and resolves
+     * both, strips permission authority, and stamps the spend surface as
+     * `plugin/<pluginId>/<purpose>`, so every run is ledger-attributed to the
+     * plugin by construction.
+     */
+    run?(input: KayAppSessionRunInput): Promise<KayAppSessionRunOutcome>;
+}
+
+/** Cheap identity for the current contents of one stored session transcript. */
+declare interface KayAppSessionSourceMark {
+    readonly mtimeMs: number;
+    readonly sizeBytes: number;
+    /** Opaque content/source identity; absent on legacy or test corpus implementations. */
+    readonly sourceRevision?: string | undefined;
+}
+
+/** A few facts folded from one session's own log, without reading the log. */
+declare interface KayAppSessionState {
+    /** The recap line the person is reading now; absent when the session has none yet. */
+    readonly standingRecap?: string;
+    /** Absent when the host cannot answer for the session. */
+    readonly runTally?: KayAppSessionRunTally;
+    /** The session's model choice when it is a tier; absent for an exact model or none. */
+    readonly modelSelection?: {
+        readonly tierId: KayAppModelTierId;
+        readonly provider?: string;
+    };
+}
+
 export declare interface KayAppSessionSummaryChunk {
     readonly goal: string;
     readonly work: readonly string[];
@@ -1601,6 +2267,12 @@ 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[];
@@ -1609,14 +2281,49 @@ export declare interface KayAppSessionWorkSummary {
     readonly openWork: readonly string[];
 }
 
-/**
- * The plugin-facing `kay.app` models contract (`app.models`): the plugin-safe model catalog and
- * tiers, image-model resolution, the direct-completion broker, and the reasoning-effort ladder that
- * sessions and completions share. Changes to this contract belong in this module.
- */
+/** One indexed stored conversation, keyed by its stable `sessionId`. */
+declare interface KayAppStoredSession {
+    readonly sessionId: string;
+    /**
+     * Who the session is for, as stamped when it was created: a person's own session (`user`), a
+     * spawned subagent, or a session Bonsai runs with nobody watching (`system`, `followup`). It lets
+     * a reader skip sessions without opening their transcripts. Absent when the index does not know
+     * it (a session older than origin stamping, or a row not yet rebuilt from its transcript): that
+     * is unknown, not `user`.
+     */
+    readonly origin?: KayAppSessionOrigin | undefined;
+    /** Resolved session title from the live index, when one exists. */
+    readonly title?: string | undefined;
+    /** Session creation time in ISO-8601 UTC, when the index has it. */
+    readonly createdAt?: string | undefined;
+    /** Last conversation activity in ISO-8601 UTC, when the index has it. */
+    readonly updatedAt?: string | undefined;
+    /** Current execution directory, when the index has it. */
+    readonly cwd?: string | undefined;
+    /** Persisted project binding; `null` means explicitly unassigned. */
+    readonly projectId?: string | null | undefined;
+    /** Parent session for a spawned member, when lineage is indexed. */
+    readonly parentSessionId?: string | null | undefined;
+    /** Family root session identity, when lineage is indexed. */
+    readonly rootSessionId?: string | undefined;
+}
+
 /** Bonsai's reasoning-effort ladder, in ascending order. */
 declare type KayAppThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
+/**
+ * The host-stamped per-call context an app-contributed tool's `execute` receives. The app
+ * activation is app-lifetime code serving EVERY session, so unlike a kernel tool (whose session
+ * is ambient) it must be told which session is calling - the same host-stamping rule as
+ * `ctx.sessionId` on an app URI module's `UriResolveContext`, and never caller-influenced.
+ */
+declare interface KayAppToolContext {
+    /** The calling session's stable id. */
+    readonly sessionId: string;
+    /** The calling session's live, re-rootable working directory at execute time. */
+    readonly cwd: string;
+}
+
 /** Applies a KeyOf action to the given type. */
 declare function KeyOf<Type extends TSchema>(type: Type, options?: TSchemaOptions): TKeyOf_2<Type>;
 
@@ -2348,7 +3055,7 @@ declare type ReadonlyOptionalKeys<Properties extends TProperties, Result extends
 declare const ReadonlyType: typeof ReadonlyObject;
 
 /** Return the same source revision used by {@link summarizeSession}, without model calls. */
-export declare function readSessionSummaryRevision(corpus: KayAppCorpus, sessionId: string): Promise<string | undefined>;
+export declare function readSessionSummaryRevision(storedSessions: KayAppSessions, sessionId: string): Promise<string | undefined>;
 
 /** Creates a Record type. */
 declare function Record_2<Key extends TSchema, Value extends TSchema>(key: Key, value: Value, options?: TObjectOptions): TRecordAction<Key, Value>;
@@ -2437,6 +3144,9 @@ declare function ReturnTypeDeferred<Type extends TSchema>(type: Type, options?:
  */
 declare const RUN_CONTINUATION_CARRIER_CUSTOM_TYPE = "herd_run_continuation";
 
+/** Observed cause of a failed request or interrupted run. */
+declare const RUN_FAILURE_REASONS: readonly ["account_unreachable", "auth", "cancelled", "content_blocked", "context_overflow", "final_output_missing", "invalid_request", "model_disabled", "model_unavailable", "network", "organization_unavailable", "overloaded", "quota_exhausted", "rate_limit", "runtime_interrupted", "safeguard_block", "seat_unpaid", "server_error", "sign_in_required", "stream_interrupted", "timeout", "unknown"];
+
 /**
  * What a {@link RUN_CONTINUATION_CARRIER_CUSTOM_TYPE} carrier records about the failed turns it
  * continues.
@@ -2458,12 +3168,80 @@ declare type RunContinuationCarrierMessage = CustomMessage<RunContinuationCarrie
     readonly display: false;
 };
 
+declare type RunFailureCause = z.infer<typeof runFailureCauseSchema>;
+
+declare const runFailureCauseSchema: z.ZodObject<{
+    reason: z.ZodEnum<{
+        cancelled: "cancelled";
+        timeout: "timeout";
+        account_unreachable: "account_unreachable";
+        auth: "auth";
+        content_blocked: "content_blocked";
+        context_overflow: "context_overflow";
+        final_output_missing: "final_output_missing";
+        invalid_request: "invalid_request";
+        model_disabled: "model_disabled";
+        model_unavailable: "model_unavailable";
+        network: "network";
+        organization_unavailable: "organization_unavailable";
+        overloaded: "overloaded";
+        quota_exhausted: "quota_exhausted";
+        rate_limit: "rate_limit";
+        runtime_interrupted: "runtime_interrupted";
+        safeguard_block: "safeguard_block";
+        seat_unpaid: "seat_unpaid";
+        server_error: "server_error";
+        sign_in_required: "sign_in_required";
+        stream_interrupted: "stream_interrupted";
+        unknown: "unknown";
+    }>;
+    source: z.ZodEnum<{
+        assistant_message: "assistant_message";
+        exception: "exception";
+        runtime: "runtime";
+    }>;
+    authDisposition: z.ZodOptional<z.ZodEnum<{
+        unauthorized: "unauthorized";
+        forbidden: "forbidden";
+    }>>;
+    provider: z.ZodOptional<z.ZodString>;
+    api: z.ZodOptional<z.ZodString>;
+    model: z.ZodOptional<z.ZodString>;
+    httpStatus: z.ZodOptional<z.ZodNumber>;
+    providerCode: z.ZodOptional<z.ZodString>;
+    exitCode: z.ZodOptional<z.ZodNullable<z.ZodNumber>>;
+    signal: z.ZodOptional<z.ZodNullable<z.ZodString>>;
+    observation: z.ZodOptional<z.ZodEnum<{
+        process_exit: "process_exit";
+        next_launch: "next_launch";
+    }>>;
+    retryAfterMs: z.ZodOptional<z.ZodNumber>;
+    retryable: z.ZodOptional<z.ZodBoolean>;
+    accountId: z.ZodOptional<z.ZodString>;
+    authSource: z.ZodOptional<z.ZodEnum<{
+        oauth: "oauth";
+        "api-key": "api-key";
+    }>>;
+    credentialRef: z.ZodOptional<z.ZodString>;
+}, z.core.$strict>;
+
+declare type RunFailureOccurrence = FailureOccurrence<RunFailureCause>;
+
+declare type RunFailureReason = (typeof RUN_FAILURE_REASONS)[number];
+
+declare type RunFailureRecord = z.infer<typeof runFailureRecordSchema>;
+
+declare const runFailureRecordSchema: z.ZodObject<{
+    failure: z.ZodType<RunFailureOccurrence, unknown, z.core.$ZodTypeInternals<RunFailureOccurrence, unknown>>;
+    errorText: z.ZodString;
+}, z.core.$strict>;
+
 /**
  * A durable runtime notice: the daemon telling the HUMAN, in the transcript,
- * that something it was going to do on their behalf did not happen — and why.
+ * that something it was going to do on their behalf did not happen - and why.
  * Same kernel posture as {@link COLLABORATION_MESSAGE_CUSTOM_TYPE}: the kernel
  * persists and projects the typed carrier; the daemon decides when one is
- * warranted. Delivery never starts a run — that is the type's whole reason to
+ * warranted. Delivery never starts a run - that is the type's whole reason to
  * exist. Its producers are the daemon's `RuntimeNoticeKind`s (agent-runtime
  * `context-message-builders.ts`). The first was #3365's dropped-continuation
  * path, retired with readiness continuations (#12512): a state a user could not
@@ -2476,7 +3254,7 @@ declare const RUNTIME_NOTICE_CUSTOM_TYPE = "runtime_notice";
 /**
  * Details of a {@link RUNTIME_NOTICE_CUSTOM_TYPE} entry. `noticeKind` is a
  * closed vocabulary owned by the daemon's builder (`RuntimeNoticeKind` in
- * agent-runtime) — the kernel persists and projects whatever kind arrives,
+ * agent-runtime) - the kernel persists and projects whatever kind arrives,
  * typed as string here for the same reason collaboration `kind` stays narrow
  * there and open here: the kernel must not need a release to learn a new one.
  */
@@ -2962,7 +3740,7 @@ declare const SessionProvenanceRecord: z.ZodObject<{
 
 declare type SessionProvenanceRecord = z.infer<typeof SessionProvenanceRecord>;
 
-export declare function sessionSummarySourceRevision(mark: KayAppCorpusSourceMark): string;
+export declare function sessionSummarySourceRevision(mark: KayAppSessionSourceMark): string;
 
 declare interface SourceInfo {
     path: string;
@@ -3098,7 +3876,7 @@ declare const SUBAGENT_RESULT_CUSTOM_TYPE = "subagent_result";
 
 /**
  * A child-declared, openable result reference: a resolved URI + a display title.
- * Kernel-generic on purpose — herd-agent must not learn Bonsai "artifact" semantics.
+ * Kernel-generic on purpose - herd-agent must not learn Bonsai "artifact" semantics.
  */
 declare interface SubagentDeliverable {
     readonly uri: string;
@@ -3108,7 +3886,7 @@ declare interface SubagentDeliverable {
 /**
  * Details of a subagent-result context message. Provenance rides the fixed `provenance` key (the
  * `AttributionSource` family: `{source:"subagent", sourceId: childSessionId, label?}`), shared with
- * every other context kind — the legacy `attribution` sibling is no longer written.
+ * every other context kind - the legacy `attribution` sibling is no longer written.
  */
 declare interface SubagentResultDetails {
     readonly provenance: AttributionSource;
@@ -3123,10 +3901,10 @@ declare interface SubagentResultDetails {
      */
     readonly summary?: string;
     /**
-     * The settled task this result answers — the per-assignment correlation key
+     * The settled task this result answers - the per-assignment correlation key
      * (#2933). `childSessionId` alone is NOT an identity: follow-up tasks reuse
      * the child session, so one child can produce many results. Absent on rows
-     * persisted before the key existed — readers of legacy rows must tolerate
+     * persisted before the key existed - readers of legacy rows must tolerate
      * several same-`sourceId` rows with no task key and treat recency, not
      * first-match, as the tiebreaker.
      */
@@ -3162,7 +3940,7 @@ declare type SubagentResultMessage = CustomMessage<SubagentResultDetails> & {
 export declare function summarizeSession(input: SummarizeSessionInput): Promise<KayAppSessionSummaryResult>;
 
 export declare interface SummarizeSessionInput {
-    readonly corpus: KayAppCorpus;
+    readonly sessions: KayAppSessions;
     readonly models: KayAppModels;
     readonly sessionId: string;
     readonly previous?: KayAppSessionSummaryResult;
@@ -5617,8 +6395,73 @@ declare type TPropertyValues<Properties extends TProperties, Keys extends string
 
 declare type TPropertyValuesReduce<Properties extends TProperties, Keys extends string[], Result extends TSchema[] = []> = Keys extends [infer Left extends string, ...infer Right extends string[]] ? Left extends keyof Properties ? TPropertyValuesReduce<Properties, Right, [...Result, Properties[Left]]> : TPropertyValuesReduce<Properties, Right, Result> : Result;
 
+/**
+ * Where a body an item's preview leaves out lives. A reference is a position, not a capability:
+ * holding one grants nothing. It crosses process boundaries (to the app, to plugins) as plain data,
+ * and is fetched on demand through the host, which authorizes the caller for the session again and
+ * resolves the storage from the session, never from the reference, so a reference cannot reach
+ * another session.
+ *
+ * - `record`: the entry is larger than the page allowed. With `contentIndex`, the body is the JSON
+ *   of that one content block of the entry's message (a long text, an image, a file the preview
+ *   cut or replaced); an entry whose size lies in content blocks is referenced block by block.
+ *   Without it, the body is the whole projected entry's JSON, which a reader issues for every
+ *   entry it cuts, beside the block references when the entry has some, or alone when they would
+ *   not fit the item. A caller reads only references a page issued and never builds one, so a
+ *   reader may make them opaque. Either way the reader extracts and slices the body in storage,
+ *   never holding more than a chunk of it. The body is the projection as of commit `asOf`, so
+ *   every chunk of one body comes from the same version: when a later commit changes the
+ *   entry's projection (an overlay, an input binding), retrieval rejects with `body_changed` and the
+ *   caller reads the entry again for a fresh reference. Otherwise the reference lives as long as
+ *   the file's incarnation.
+ * - `tool-output`: the tool result was clamped when it entered the transcript and its full output
+ *   was spilled beside the session (what `tool-output://<toolCallId>` reads). It lives as long as the
+ *   session's directory; a spill that was never written or was since removed reads as
+ *   `body_missing`.
+ */
+declare type TranscriptBodyReference = {
+    readonly kind: "record";
+    readonly incarnation: string;
+    readonly entryId: string;
+    /** One content block of the entry's message, 0-based; absent for the whole entry. */
+    readonly contentIndex?: number;
+    /** The head commit the preview was cut at: the projection the body is read as. */
+    readonly asOf: number;
+    /** The body's size, in bytes of its JSON form. */
+    readonly bytes: number;
+} | {
+    readonly kind: "tool-output";
+    readonly toolCallId: string;
+    /** Absent when the reader did not stat the spill. */
+    readonly bytes?: number;
+};
+
 declare type TranscriptEntry = MessageEntry | CompactionEntry | BranchSummaryEntry | CustomEntry;
 
+/**
+ * One item of a page, in stored order. With `bodies`, `entry` is a preview: its large text is cut
+ * and its images and files replaced, so the item fits the page, and each reference says where one
+ * left-out body is: the whole entry, one replaced block, the spilled tool output. A spilled tool
+ * result always lists its `tool-output` reference, also when the entry is cut too. An
+ * `unreadable` item is a stored record that does not parse as an entry; it still takes a place,
+ * and its id is the storage row's, which every stored record has, so a cursor can name it.
+ * `(commitSeq, commitIndex)` is the item's stored order, so a holder can insert an item it did not
+ * have (a revision that makes an entry appear) at its place. The entry's own `seq` is not a
+ * position here: a reader that pages by cursor does not count the entries before an item.
+ */
+declare type TranscriptPageItem = {
+    readonly entry: TranscriptEntry;
+    readonly commitSeq: number;
+    /** The record's place among its commit's stored records: items sort by (commitSeq, commitIndex). */
+    readonly commitIndex: number;
+    readonly bodies?: readonly TranscriptBodyReference[];
+} | {
+    readonly unreadable: "malformed-json" | "malformed-entry";
+    readonly commitSeq: number;
+    readonly commitIndex: number;
+    readonly entryId: string;
+};
+
 declare type TReadonly<Type extends TSchema = TSchema> = (Type & {
     '~readonly': true;
 });
@@ -6514,7 +7357,7 @@ declare type TZipDistributionArray<Arguments extends TSchema[], DistributionArra
 
 declare const UI_ACTION_CUSTOM_TYPE = "ui_action";
 
-/** A generative-UI interaction — the human acting, carried with its originating tool call. */
+/** A generative-UI interaction - the human acting, carried with its originating tool call. */
 declare interface UiActionDetails {
     readonly provenance: AttributionSource;
     /**
@@ -6606,14 +7449,14 @@ declare interface Usage {
 
 /**
  * The user-invoked message: everything the composer INTENTIONALLY pulled into a
- * send — today the resolved content of skill- and prompt-template-bound slash
- * commands — carried beside the human turn instead of fabricated into its text.
+ * send - today the resolved content of skill- and prompt-template-bound slash
+ * commands - carried beside the human turn instead of fabricated into its text.
  * The user turn stays exactly what was typed (`/pr-review 123`); this message
  * delivers what that intent resolved to, one message per send, in per-feature
- * sections (`skills`, `prompt_templates` — a future feature adds a SIBLING
+ * sections (`skills`, `prompt_templates` - a future feature adds a SIBLING
  * section, never a second meaning for an existing one). Sibling of
  * `dynamic_context` in grammar (a sectioned wrapper) but not in policy: it is
- * assembled synchronously and fail-closed at command dispatch — never a
+ * assembled synchronously and fail-closed at command dispatch - never a
  * retrieval pass, budget, or debounce, because the content IS the send's
  * meaning, not something computed from it.
  */
@@ -6628,18 +7471,18 @@ declare const USER_PASTED_CONTENT_CUSTOM_TYPE = "user_pasted_content";
 
 /**
  * The user shell command result: a command the HUMAN ran directly through the
- * composer's `!` shell escape — no model in the loop, no permission prompt —
+ * composer's `!` shell escape - no model in the loop, no permission prompt -
  * carried into context so the agent can pick up where the user's manual work
  * left off. The third verb of the user-origin family: `tab_context` is what the
  * user is looking at, `ui_action` is what they clicked, `user_shell_command` is
- * what they DID. Durable (never turn-bound) and it must never wake the agent —
+ * what they DID. Durable (never turn-bound) and it must never wake the agent -
  * delivery policy lives with the host (D1: silent context).
  */
 declare const USER_SHELL_COMMAND_CUSTOM_TYPE = "user_shell_command";
 
 /**
  * Details of a `user_invoked` message. The message `content` is empty by
- * construction — the model wrapper renders entirely from these typed sections
+ * construction - the model wrapper renders entirely from these typed sections
  * (the `dynamic_context` details-first posture). One typed slot per feature
  * section; both are always present (empty arrays elide their section at the
  * model boundary).
@@ -6652,7 +7495,7 @@ declare interface UserInvokedDetails {
 
 /**
  * One invocation entry inside a `user_invoked` feature section: the resource's
- * resolved name, the literal command the user typed (`/pr-review 123` — kept
+ * resolved name, the literal command the user typed (`/pr-review 123` - kept
  * verbatim, alias and all), and the resolved content that command pulled in.
  */
 declare interface UserInvokedEntry {
@@ -6710,7 +7553,7 @@ declare type UserPastedContentMessage = CustomMessage<UserPastedContentDetails>
  */
 declare interface UserShellCommandDetails {
     readonly provenance: AttributionSource;
-    /** The background-task id the run rode — correlates the card with live task events. */
+    /** The background-task id the run rode - correlates the card with live task events. */
     readonly taskId: string;
     readonly command: string;
     readonly cwd: string;
@@ -6805,6 +7648,18 @@ 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;
 }