@yaklabs-ai/plugin-sdk 0.11.0 → 0.12.3

package/dist/kay-app.d.ts

@@ -1,12 +1,4 @@
-import type { ChoiceResponse } from '@typesafe-ai/sdk';
-import type { NoulResponse } from '@typesafe-ai/sdk';
-import { Questions } from '@typesafe-ai/sdk';
-import type { ScoreResponse } from '@typesafe-ai/sdk';
 import type { StatementSync } from 'node:sqlite';
-import { SystemOneRequest } from '@typesafe-ai/sdk';
-import { SystemOneResult } from '@typesafe-ai/sdk';
-import { TypeSafeClient } from '@typesafe-ai/sdk';
-import { Usage } from '@typesafe-ai/sdk';
 import { z } from 'zod';
 
 /**
@@ -31,6 +23,9 @@ declare interface AccountIdentity {
     readonly avatarUrl?: string;
     /** Issuer-asserted beta-tester flag; only Kay's product-account service sets it. */
     readonly betaTester?: boolean;
+    readonly activeOrganizationId?: string;
+    readonly organizationSelectionState?: "selected" | "unresolved";
+    readonly organizationScopeEpoch?: number;
     /**
      * Provider-native session id claim (WorkOS's `sid`), needed to call the provider's own
      * session-revocation endpoint at sign-out (`POST /user_management/sessions/revoke`, not yet
@@ -53,8 +48,18 @@ export declare interface AgentToolResult<T = JsonValue | undefined> {
     content: (TextContent | ImageContent)[];
     /** Arbitrary structured details for logs or UI rendering. */
     details: T;
+    /**
+     * Machine-readable result matching the tool's `outputSchema`, for programmatic callers. Not sent
+     * to the model; `content` remains the model-facing result.
+     */
+    structuredContent?: JsonValue;
     /** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
-    usage?: Usage_2;
+    usage?: Usage;
+    /**
+     * Report a failure without throwing. The model sees `content` as an error result, like a thrown
+     * error, but `details` and `structuredContent` are kept for the UI and programmatic callers.
+     */
+    isError?: boolean;
     /**
      * Hint that the agent should stop after the current tool batch.
      * Early termination only happens when every finalized tool result in the batch sets this to true.
@@ -153,8 +158,10 @@ declare interface AssistantMessage {
     responseId?: string;
     /** Exact provider-native effort level used for this response. Absent for legacy or unmanaged responses. */
     providerThinkingLevel?: string;
+    /** Pi thinking level the agent loop requested for this response. Absent outside the agent loop and for legacy responses. */
+    thinkingLevel?: ModelThinkingLevel;
     diagnostics?: AssistantMessageDiagnostic[];
-    usage: Usage_2;
+    usage: Usage;
     stopReason: StopReason;
     deferred?: DeferredHandle;
     errorMessage?: string;
@@ -250,6 +257,20 @@ declare interface BackgroundTaskSnapshot {
 
 declare type BackgroundTaskStatus = "queued" | "running" | "completed" | "failed" | "cancelled";
 
+/** Fields shared by every catalog entry, regardless of what you can do with it. */
+declare interface BaseModel<TApi extends string> {
+    id: string;
+    name: string;
+    api: TApi;
+    provider: ProviderId;
+    baseUrl: string;
+    input: ("text" | "image")[];
+    /** Provider input limits and cache-safe preprocessing metadata. */
+    inputLimits?: ModelInputLimits;
+    cost: ModelCost;
+    headers?: Record<string, string>;
+}
+
 /** Compatibility settings for Amazon Bedrock models. */
 declare interface BedrockCompat {
     /** Whether the model supports Bedrock strict tool schemas. Default: false. */
@@ -261,7 +282,7 @@ declare interface BranchSummaryEntry extends EntryBase {
     fromId: string | null;
     summary: string;
     details?: JsonValue_2;
-    usage?: Usage_2;
+    usage?: Usage;
     fromHook: boolean;
 }
 
@@ -272,15 +293,13 @@ declare type ChatTemplateKwargValue = string | number | boolean | null | {
     omitWhenOff?: boolean;
 };
 
-export { ChoiceResponse }
-
 declare interface CompactionEntry extends EntryBase {
     type: "compaction";
     summary: string;
     retainedTail: AgentMessage[];
     tokensBefore: number;
     details?: JsonValue_2;
-    usage?: Usage_2;
+    usage?: Usage;
     fromHook: boolean;
 }
 
@@ -406,6 +425,12 @@ export declare function createFallbackOnlySignals(): KayAppSignals;
  */
 export declare function createFallbackOnlyWithJev(): WithJev;
 
+/**
+ * The `app.skills` a host with no skill store or catalog binds: every read answers
+ * `not-available`, so a plugin's code path never depends on host composition.
+ */
+export declare function createUnavailableSkills(message: string): KayAppSkills;
+
 declare interface CustomEntry extends EntryBase {
     type: "custom";
     customType: string;
@@ -608,6 +633,150 @@ declare type IsJsonProperty<T> = IsAny<T> extends true ? false : unknown extends
  */
 export declare function isRetryable(result: KayAppAccountAssertionFailure): boolean;
 
+export declare type JevAnswer = JevBoolAnswer | JevChoiceAnswer | JevScoreAnswer;
+
+/** The answer shape one question gets back. */
+export declare type JevAnswerFor<Q> = Q extends JevBoolQuestion ? JevBoolAnswer : Q extends JevChoiceQuestion<infer L> ? JevChoiceAnswer<L> : Q extends JevScoreQuestion ? JevScoreAnswer : never;
+
+export declare interface JevBoolAnswer {
+    readonly type: "bool";
+    /** P(yes), from 0 to 1. */
+    readonly probability: number;
+}
+
+/** A yes/no question. `criteria` says what yes and what no mean; omit it to leave both open. */
+export declare interface JevBoolQuestion {
+    readonly type: "bool";
+    readonly instructions: string;
+    readonly criteria?: {
+        readonly true: string;
+        readonly false: string;
+    };
+}
+
+/**
+ * The one error `classify` rejects with. It carries a classification, never the provider's own
+ * message or body: those can echo the request state, and this error reaches logs.
+ */
+export declare class JevCallError extends Error {
+    readonly transport: JevTransport;
+    readonly kind: JevCallErrorKind;
+    /** The final attempt's HTTP status, when a response arrived. */
+    readonly status: number | undefined;
+    constructor(init: {
+        readonly transport: JevTransport;
+        readonly kind: JevCallErrorKind;
+        readonly status?: number | undefined;
+    });
+}
+
+/**
+ * Why a Jev call failed, as a closed set:
+ *
+ * - `http`: the route answered with an error status (`status` says which).
+ * - `too-large`: the route refused the request's size (413, or a 400 naming the token limit).
+ * - `network`: no response arrived.
+ * - `aborted`: the call was cancelled.
+ * - `invalid-answer`: the route answered, but not with an answer for every asked question.
+ */
+export declare type JevCallErrorKind = "http" | "too-large" | "network" | "aborted" | "invalid-answer";
+
+export declare interface JevChoiceAnswer<L extends string = string> {
+    readonly type: "choice";
+    readonly choice: L;
+    readonly confidence: number;
+    /** P(label) for every offered label. */
+    readonly probabilities: Readonly<Record<L, number>>;
+}
+
+/** A choice among labels. Each label maps to what it means; an empty string leaves it open. */
+export declare interface JevChoiceQuestion<L extends string = string> {
+    readonly type: "choice";
+    readonly instructions: string;
+    readonly criteria: Readonly<Record<L, string>>;
+}
+
+/** One answered request: every asked question has an answer of its own kind. */
+export declare interface JevClassification<Q extends JevQuestions = JevQuestions> {
+    /** The Jev model the host asked. */
+    readonly model: string;
+    readonly answers: {
+        readonly [K in keyof Q]: JevAnswerFor<Q[K]>;
+    };
+    /** Token counts, when the route reported them. */
+    readonly usage?: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+    };
+}
+
+export declare interface JevClassifyRequest<Q extends JevQuestions = JevQuestions> {
+    readonly state: JevState;
+    readonly questions: Q;
+}
+
+/**
+ * The Jev client a `use` body receives. `classify` either resolves with an answer for every
+ * asked question, each of its question's kind, or rejects with a {@link JevCallError}; it never
+ * resolves with a partial or substituted answer.
+ */
+export declare interface JevClient {
+    classify<const Q extends JevQuestions>(request: JevClassifyRequest<Q>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<JevClassification<Q>>;
+}
+
+export declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
+
+/** A rubric: questions keyed by the name each answer comes back under. */
+export declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
+
+export declare interface JevScoreAnswer {
+    readonly type: "score";
+    /** The expected score, from 0 to the number of rungs minus one. */
+    readonly score: number;
+    readonly confidence: number;
+}
+
+/** A score over ordered rungs: the first criterion scores 0, the next 1, and so on. */
+export declare interface JevScoreQuestion {
+    readonly type: "score";
+    readonly instructions: string;
+    readonly criteria: readonly string[];
+}
+
+/**
+ * ---
+ * responsibility: The plugin-facing CONTRACT for Jev typed-decision inference — the shape of
+ *   `api.withJev` on both plugin SDK targets, the {@link JevClient} a `use` body receives, the
+ *   question and answer vocabulary it speaks, and the fallback-only implementation a host
+ *   without a Jev lane binds.
+ * owns:
+ *   - {@link WithJev}, {@link WithJevOptions}, {@link createFallbackOnlyWithJev}.
+ *   - {@link JevClient}, the {@link JevQuestion} and {@link JevAnswer} vocabulary, and
+ *     {@link JevCallError}.
+ * does_not_own:
+ *   - The wire. The host serves `classify` over whichever route the user's Jev provider order
+ *     picks; a plugin never sees a vendor client, a vendor type, or a route.
+ *   - Credential resolution, the `jev.use` decision, the Jev-branch budget, or usage accounting.
+ *     Those are host-side (`@kay/agent-runtime`'s `kay/jev/`).
+ * ---
+ *
+ * The vocabulary is Kay's own (SDK 0.12.0). Before it, `use` received TypeSafe's `TypeSafeClient`
+ * and plugins coded against a vendor's types. It follows pi's classifier contract, which the host
+ * runs Jev through: a yes/no question is `bool` and answers a `probability`, every instruction and
+ * criterion is text, and the state is a JSON object.
+ */
+/**
+ * The state a rubric reads: a JSON object, never text or an array. Every value must survive
+ * `JSON.stringify` unchanged (no functions or class instances), because it is sent as JSON.
+ * Typed as `object` so a state declared as an interface fits without an index signature.
+ */
+export declare type JevState = object;
+
+/** The route a Jev call took: the user's own TypeSafe key, or Bonsai's hosted gateway. */
+export declare type JevTransport = "direct" | "hosted";
+
 declare type JsonObject = {
     [key: string]: JsonValue;
 };
@@ -792,7 +961,10 @@ export declare interface KayAppAccount {
      * verdict — not only on identity moves. A listener whose reaction is expensive
      * (tearing down state, re-registering sources) must gate itself: re-read with
      * `profile`/`assertResult`, compare against the last-seen identity, and act only on a
-     * real move (kay#8553 is the looping-reconnect bug the looser reading licensed).
+     * real move (kay#8553 is the looping-reconnect bug the looser reading licensed). A gate
+     * that re-registers account-scoped sources must also act when a registration reports
+     * {@link KayAppDataSourceRegistration.isRetired}: the host's identity change is not always
+     * one `profile` shows, and a gate reading only the identity leaves the source retired.
      */
     subscribe(listener: () => void): () => void;
 }
@@ -1399,15 +1571,16 @@ export declare type KayAppAutomationMatch = {
  * {@link KayAppAutomationRunDetail.artifacts} and `externalResources` report,
  * deduplicated by URI. A session-scoped `output://` URI is one row per session.
  * `uri` is a `scheme://` URI, an absolute local file path, or an external
- * resource's canonical https URL.
+ * resource's canonical https URL. Stated action evidence wins over inferred
+ * verb evidence; within the same certainty, action precedence decides.
  */
 export declare interface KayAppAutomationProducedResourceItem {
     readonly uri: string;
-    /** By precedence `deleted` > `created` > `updated`; only an artifact receipt reports `deleted`. */
+    /** Stated evidence beats inferred evidence; within one certainty, `deleted` > `created` > `updated`. Only an artifact receipt reports `deleted`. */
     readonly action: "created" | "updated" | "deleted";
-    /** The session that produced it, and the one a session-scoped URI resolves against. */
+    /** The first activity-ordered session carrying the winning certainty and action; for a session-scoped URI, the session it resolves against. */
     readonly sessionId: string;
-    /** A real revision the run recorded for this URI, and how many; absent when it recorded none. */
+    /** The last revision recorded for the winning certainty/action, or the last revision of the highest-ranked revision-bearing contribution (stated before inferred, then action precedence), and how many distinct revisions there were; ordered by activity, not time. */
     readonly revision?: {
         readonly id: string;
         readonly count: number;
@@ -1833,6 +2006,8 @@ export declare interface KayAppCorpus {
      * indexed path and validates the opaque cursor before opening it. When `throughEntryId` is
      * supplied, the cursor stops at that entry's transaction line; a V4 line may carry later
      * entries, which are returned for the caller to filter and are replayed on the next page.
+     * A page can hold no entries at all (a run of storage lines) while more follows; a record
+     * longer than the page is stepped over and counted in `oversizedRecords`.
      */
     readEntryBatch?(sessionId: string, options?: {
         readonly cursor?: JsonValue_4;
@@ -1855,10 +2030,23 @@ export declare interface KayAppCorpusEntryBatch {
     /** Opaque cursor at the physical page start, for a partial logical chunk. */
     readonly pageStartCursor?: JsonValue_4;
     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;
 }
 
 /** One stored session, as the granted corpus enumerates them. Keyed by its stable `sessionId`. */
@@ -1896,7 +2084,8 @@ export declare interface KayAppData {
      * the registration in a `register()` you call both at activation and from your
      * `app.account.subscribe` listener. A source registered once at activation is gone for the
      * life of the process after the first identity change, and the renderer retries attaching to
-     * it forever.
+     * it forever. If that listener gates on identity, re-register as well whenever the current
+     * registration's {@link KayAppDataSourceRegistration.isRetired} answers `true`.
      */
     registerSource(sourceId: string, definition: KayAppDataSourceDefinition): KayAppDataSourceRegistration;
     /**
@@ -1994,6 +2183,16 @@ export declare interface KayAppDataSourceRegistration {
     invalidate(): void;
     /** Optional on older hosts; keep the producer's normal lifecycle when absent. */
     readonly demand?: KayAppDataSourceDemand;
+    /**
+     * Whether the host no longer serves this registration: it was disposed, replaced by a newer
+     * registration of the same source, or retired by an account identity change (see
+     * {@link KayAppData.registerSource}). A retired registration never comes back; register again.
+     * An `app.account` listener that gates its re-registration on its own reading of the identity
+     * must also re-register when this is `true`: the host's identity change and the one a plugin
+     * can observe need not coincide. The common case is the first sign-in resolution after boot,
+     * when `profile()` already carries the last-known subject. Optional on older hosts.
+     */
+    isRetired?(): boolean;
     dispose(): void;
 }
 
@@ -2028,7 +2227,7 @@ export declare type KayAppDataUnavailableReason =
 /** The backing read was attempted and threw. Look for the failure in the host's own log. */
 | "read-failed"
 /** A valid steady state with nothing to show — signed out, empty scope, feature off. */
-| "intentionally-unavailable";
+| "intentionally-unavailable" | "needs-reauthentication" | "device-reconnect-required";
 
 /** App-lifetime cleanup registered by a `kay.app` plugin during activation. */
 export declare type KayAppDisposer = () => void | Promise<void>;
@@ -2492,6 +2691,13 @@ export declare interface KayAppPluginApi {
      * posture to tighten if plugin execution is ever isolated (#3266).
      */
     readonly paths: KayAppPaths;
+    /**
+     * The daemon's clock and the time zone the user is in, with a label for a zone the host does not
+     * know. Always present and ungated, like {@link paths}: it confers no authority, since a plugin
+     * runs in the daemon's process and can read the clock itself. Read the zone here and not from
+     * `Intl` or `process.env.TZ`; see {@link KayAppTime.snapshot}.
+     */
+    readonly time: KayAppTime;
     /**
      * Read/arrange access to the live desktop workspace. Present whenever the host has a workspace
      * (a headless daemon may not); absence is a host fact, never a grant signal. Reading the snapshot
@@ -2576,7 +2782,7 @@ export declare interface KayAppPluginApi {
     readonly models: KayAppModels;
     /**
      * Jev typed-decision inference, as an OPTIONAL accelerator with a REQUIRED fallback. Each call
-     * is checked against `jev.use` — but a refused grant or a missing saved key both
+     * is checked against `jev.use` — but a refused grant or no usable Jev provider both
      * produce the same outcome: your `fallback` runs.
      *
      * Always present, on every host, unlike the grant-gated and host-fact-gated members above. That
@@ -2587,8 +2793,8 @@ export declare interface KayAppPluginApi {
     readonly withJev: WithJev;
     /**
      * Recorded Jev signals. `observe` runs a Jev inference and records the answer as a durable,
-     * provenance-stamped row; each call is checked against `jev.use`, and a refused grant, a
-     * missing saved key, a timeout, or a vendor error all produce the same outcome: an
+     * provenance-stamped row; each call is checked against `jev.use`, and a refused grant, no
+     * usable Jev provider, a timeout, or a vendor error all produce the same outcome: an
      * `unavailable` observation with `stored: false`. A name that breaks the recorded-name grammar
      * is refused as `invalid` before any of that. `list` and `listDetectors` read EVERY plugin's
      * recorded signals back, each call checked against `signals.read`, answering `unavailable` or
@@ -2598,6 +2804,15 @@ export declare interface KayAppPluginApi {
      * defined baseline beside it.
      */
     readonly signals: KayAppSignals;
+    /**
+     * Read-only metadata about the user's managed skills: identity, the exact `git-tree:<oid>`
+     * version each serves (the same identity skill invocations record), revision history, and
+     * suggested changes. Each call is checked against `skills.read`; a refused grant or a host
+     * with no skill store resolves to `{ status: "unavailable" }`, never a rejection, while the
+     * plugin is enabled. After it is disabled, a kept handle's methods throw synchronously. Always
+     * present, like {@link signals}.
+     */
+    readonly skills: KayAppSkills;
     /** The app-wide endpoint bus (register handlers a consuming surface invokes). */
     readonly endpoints: KayAppEndpoints;
     /** Publish one event declared by this plugin's `kay.app` manifest target. */
@@ -2754,16 +2969,17 @@ export declare type KayAppSessionCreator = SessionCreator;
 
 export declare type KayAppSessionDefiner = SessionDefiner;
 
-export declare type KayAppSessionEvent = KayAppHumanMessageSessionEvent | KayAppTurnSettledSessionEvent | KayAppPhaseShiftSessionEvent;
+export declare type KayAppSessionEvent = KayAppHumanMessageSessionEvent | KayAppTurnSettledSessionEvent | KayAppPhaseShiftSessionEvent | KayAppUiActionSessionEvent;
 
 declare interface KayAppSessionEventBase {
     readonly sessionId: string;
     /**
      * The event's own anchor entry: the projected human carrier, the settled turn's own last
-     * entry, or the phase-shift observation's `observationEntryId`. A handler bounds its OWN logical
-     * corpus interval using this id (via whatever packet-building helpers the plugin already owns);
-     * the door hands out no `readEntries()` closure, and re-validating what was read against the
-     * CURRENT branch — a rewind can race between publish and read — is the handler's own job.
+     * entry, the phase-shift observation's `observationEntryId`, or the projected `ui_action`
+     * entry. A handler bounds its OWN logical corpus interval using this id (via whatever
+     * packet-building helpers the plugin already owns); the door hands out no `readEntries()`
+     * closure, and re-validating what was read against the CURRENT branch — a rewind can race
+     * between publish and read — is the handler's own job.
      */
     readonly entryId: string;
     /** ISO-8601 publish time. */
@@ -2864,12 +3080,12 @@ export declare interface KayAppSessionEventsSubscribeOptions {
 }
 
 /**
- * A closed, extensible union: a projected human message, a settled turn, or an accepted
- * phase-shift observation. They share one subscribable set now that there is no dispatcher
- * chaining one job's completion into another's `when`. Adding a fourth type is additive, never
- * breaking.
+ * A closed, extensible union: a projected human 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: `ui-action` was the fourth.
  */
-export declare type KayAppSessionEventType = "human-message" | "turn-settled" | "phase-shift";
+export declare type KayAppSessionEventType = "human-message" | "turn-settled" | "phase-shift" | "ui-action";
 
 export declare type KayAppSessionIntent = SessionIntent;
 
@@ -3160,7 +3376,7 @@ export declare interface KayAppSignal {
     readonly source: KayAppSignalSource;
     readonly recordedAtMs: number;
     /** Keyed by question name, full probability distributions included. */
-    readonly answers: Readonly<Record<string, NoulResponse | ChoiceResponse | ScoreResponse>>;
+    readonly answers: Readonly<Record<string, KayAppSignalAnswer>>;
     /** The inference that produced the answers; absent when the host recorded only part of it. */
     readonly inference?: {
         readonly model: string;
@@ -3172,6 +3388,9 @@ export declare interface KayAppSignal {
     readonly inputDigest: string;
 }
 
+/** One stored answer: a {@link JevAnswer}, or a yes/no answer recorded before SDK 0.12.0. */
+export declare type KayAppSignalAnswer = JevAnswer | KayAppSignalNoulAnswer;
+
 /** One version of one detector, under one rubric, as the catalog lists it. */
 export declare interface KayAppSignalDetector {
     readonly pluginId: string;
@@ -3182,16 +3401,26 @@ export declare interface KayAppSignalDetector {
      * version mean the rubric was edited without a version bump.
      */
     readonly rubricDigest: string;
-    readonly questions: Questions;
+    readonly questions: Readonly<Record<string, KayAppSignalRubricQuestion>>;
     readonly firstRecordedAtMs: number;
     readonly lastRecordedAtMs: number;
 }
 
+/**
+ * A yes/no answer as rows recorded before SDK 0.12.0 carry it, in TypeSafe's vocabulary:
+ * `noul` is P(yes). Stored rows are never rewritten, so a reader still meets these.
+ */
+export declare interface KayAppSignalNoulAnswer {
+    readonly type: "noul";
+    readonly noul: number;
+}
+
 /**
  * The result of one observe call. `status` is the only field a caller must switch on:
  *
- * - `classified`: Jev answered; `answers`, `model`, and `usage` are the vendor's verbatim
- *   response, and `stored` says whether the row landed in the durable store.
+ * - `classified`: Jev answered; `answers` (one {@link JevAnswer} per question), `model`, and
+ *   `usage` are what the Jev call returned, and `stored` says whether the row landed in the
+ *   durable store.
  * - `unavailable`: Jev could not answer (no key, refused grant, timeout, vendor error, or a
  *   malformed response), or the host has no signals store at all (`reason: "no-store"`).
  *   `reason` names the host's classification; no row is written, so the same input can be
@@ -3242,6 +3471,18 @@ export declare interface KayAppSignalPage {
     readonly nextCursor?: string;
 }
 
+/**
+ * One question of a stored rubric, as the recording plugin wrote it. Rubrics recorded before
+ * SDK 0.12.0 use TypeSafe's vocabulary (`noul` for yes/no, and instructions or criteria that
+ * may be JSON rather than text), and a stored rubric is never rewritten, so only `type` is
+ * guaranteed.
+ */
+export declare interface KayAppSignalRubricQuestion {
+    readonly type: string;
+    readonly instructions?: unknown;
+    readonly criteria?: unknown;
+}
+
 /**
  * The plugin's signal door. `observe` runs the fused inference-and-record step; `list` and
  * `listDetectors` read recorded signals back. The plugin id is stamped by the host at the
@@ -3364,16 +3605,16 @@ export declare interface KayAppSignalsObserveInput {
      * transcript the source points at. So the projection must be a pure function of the
      * transcript and the detector version, or the row's evidence cannot be reproduced.
      */
-    readonly state: unknown;
+    readonly state: JevState;
     /**
-     * The typed questions to answer, as the vendor SDK accepts them. Stored once per digest. A
+     * The typed questions to answer. Stored once per digest. A
      * rubric asks 1 to 64 questions. Each name is an identifier (letters, digits, and `_`, not
      * starting with a digit), at most 64 characters, because a reader types it into a `where`
      * filter. A choice question offers at most {@link MAX_CHOICE_LABELS} labels, each 1 to 64
      * characters with no `,`, `@`, or control or invisible character (`\p{C}`), and no whitespace
      * but single spaces between words, so a reader can copy it back exactly from rendered text.
      */
-    readonly questions: Questions;
+    readonly questions: JevQuestions;
     readonly options?: WithJevOptions;
 }
 
@@ -3455,6 +3696,184 @@ export declare interface KayAppSignalsSessionQuery {
     readonly limit?: number;
 }
 
+/** One managed skill, as the skill catalog admits it. */
+export declare interface KayAppSkill {
+    /** Canonical id, `<canonical source id>/<name>`. Equal to a skill invocation's `resourceId`. */
+    readonly skillId: string;
+    /** `skill://<sourceId>/<name>`, the address sessions read the skill at. */
+    readonly uri: string;
+    /** The source's display id (`user`, a plugin slug, …) — never the canonical minted id. */
+    readonly sourceId: string;
+    readonly name: string;
+    readonly description: string;
+}
+
+/** One skill with its current version and its suggestions. */
+export declare interface KayAppSkillDetail extends KayAppSkill {
+    readonly versioning: KayAppSkillVersioning;
+    /**
+     * The version a session loading the skill now receives, as `git-tree:<oid>`. Absent when Kay
+     * keeps no history of the skill (`unversioned`), cannot read it, or the skill's files hold
+     * bytes no revision has recorded (`uncommitted`).
+     */
+    readonly version?: string;
+    /** The current revision id, when {@link version} is present. */
+    readonly revision?: string;
+    /**
+     * The skill's files hold bytes no revision has recorded: uncommitted changes, or files the
+     * skill's own `.gitignore` names, which a session loading it still receives.
+     */
+    readonly uncommitted: boolean;
+    /** Every suggestion recorded for the skill, any status, newest `createdAt` first. */
+    readonly suggestions: readonly KayAppSkillSuggestion[];
+}
+
+export declare interface KayAppSkillHistoryOptions {
+    /** At most this many revisions, newest first. Default 50, clamped to 1..500. */
+    readonly limit?: number;
+}
+
+export declare type KayAppSkillHistoryResult = {
+    readonly status: "ok";
+    readonly versioning: KayAppSkillVersioning;
+    /** Newest first. Empty when the skill is `unversioned` or `unavailable`. */
+    readonly revisions: readonly KayAppSkillRevision[];
+    /** More revisions exist than were returned. */
+    readonly truncated: boolean;
+} | KayAppSkillNotFound | KayAppSkillsUnavailable;
+
+/**
+ * The named skill is not one the catalog admits. Only answered when every skill source could be
+ * read: a name missing from a partial catalog answers `unavailable` instead, because its own
+ * source may be the unreadable one.
+ */
+export declare interface KayAppSkillNotFound {
+    readonly status: "not-found";
+    readonly message: string;
+}
+
+/** Who made a revision, as Kay recorded it when the revision was made. Absent fields are unknown. */
+export declare interface KayAppSkillProvenance {
+    /** The session whose work the revision records. */
+    readonly sessionId?: string;
+    /** Who that session acted as: `user`, `subagent`, `system/<surface>`, `followup/<surface>`. */
+    readonly actor?: string;
+}
+
+export declare type KayAppSkillReadResult = {
+    readonly status: "ok";
+    readonly skill: KayAppSkillDetail;
+} | KayAppSkillNotFound | KayAppSkillsUnavailable;
+
+/**
+ * The plugin-facing `kay.app` skills contract: a read-only view of the user's managed skills —
+ * which skills exist, the exact version each one serves, how each version came about, and the
+ * suggested changes waiting for (or already given) a person's review.
+ *
+ * Every call is checked against the `skills.read` claim at the call, so a grant or revocation
+ * takes effect on the next one. Like `app.signals`, the member is ALWAYS present and no call
+ * rejects while the plugin is enabled: an environment failure or a refused grant resolves to
+ * `{ status: "unavailable" }`. After the plugin is disabled, a kept handle's methods throw
+ * synchronously.
+ *
+ * It is metadata only. A skill's bytes are read through `skill://` (an agent's door), and there
+ * is no write here: a plugin changes a skill the way any session does, through `skill://`.
+ *
+ * ## Versions
+ *
+ * `version` is always `git-tree:<oid>` — the SAME identity a session records when it loads a
+ * skill (`CorpusResourceInvocation.version`). So "did this session load the skill before or
+ * after its last accepted suggestion?" is a comparison of values from the two APIs: find the
+ * newest revision in {@link KayAppSkills.history} that carries `acceptedSuggestionId`; a loaded
+ * version is at or after it when it equals that revision's version or a newer one's. A session
+ * that loaded the skill while its files held unrecorded bytes (uncommitted edits, or files its
+ * own `.gitignore` names) recorded a version no revision carries, so it cannot be placed.
+ */
+/**
+ * Which skill a call is about: its canonical id (`KayAppSkill.skillId`, the same value as a skill
+ * invocation's `resourceId`) or its `skill://<sourceId>/<name>` address.
+ */
+export declare type KayAppSkillRef = string;
+
+/** One revision of a skill's history. */
+export declare interface KayAppSkillRevision {
+    readonly revision: string;
+    /** `git-tree:<oid>`: the version a session loading this revision recorded. */
+    readonly version: string;
+    /** ISO-8601 time the revision was authored. */
+    readonly at: string;
+    /** `upstream`: the source shipped these bytes. `local`: they were changed on this machine. */
+    readonly line: "local" | "upstream";
+    /** One line about the change. */
+    readonly summary: string;
+    /** Set when accepting this suggestion made this revision the skill's content. */
+    readonly acceptedSuggestionId?: string;
+    readonly provenance?: KayAppSkillProvenance;
+}
+
+/** One exact point in a skill's history. */
+export declare interface KayAppSkillRevisionRef {
+    /** The revision id, as `skill://<sourceId>/<name>/@revision/<id>` takes it. */
+    readonly revision: string;
+    /** `git-tree:<oid>`. Absent only when the revision can no longer be read. */
+    readonly version?: string;
+}
+
+/** `app.skills`: read-only skill metadata, each call checked against `skills.read`. */
+export declare interface KayAppSkills {
+    /** Every managed skill the catalog admits, ordered by source then name. */
+    list(): Promise<KayAppSkillsListResult>;
+    /** One skill's identity, current version, and suggestions. */
+    read(skill: KayAppSkillRef): Promise<KayAppSkillReadResult>;
+    /** One skill's revisions, newest first, each with its version and how it came about. */
+    history(skill: KayAppSkillRef, options?: KayAppSkillHistoryOptions): Promise<KayAppSkillHistoryResult>;
+}
+
+export declare type KayAppSkillsListResult = {
+    readonly status: "ok";
+    readonly skills: readonly KayAppSkill[];
+    /**
+     * `false` when some source could not be read: an absent skill is then not proof that the
+     * user has no such skill.
+     */
+    readonly complete: boolean;
+} | KayAppSkillsUnavailable;
+
+/** One suggested change to a skill, in any status. */
+export declare interface KayAppSkillSuggestion {
+    readonly id: string;
+    readonly status: "pending" | "accepted" | "declined";
+    /** The proposer's stated reason, when one was recorded. */
+    readonly reason?: string;
+    readonly createdAt: string;
+    readonly updatedAt: string;
+    /** The skill revision the change was proposed against. */
+    readonly base: KayAppSkillRevisionRef;
+    /** The proposed content. */
+    readonly candidate: KayAppSkillRevisionRef;
+    /** What became the skill's content on acceptance; present only when `status` is `accepted`. */
+    readonly accepted?: KayAppSkillRevisionRef;
+    /** Who proposed it, from the candidate revision's own record. */
+    readonly provenance?: KayAppSkillProvenance;
+}
+
+/**
+ * Why a skills read could not be answered. `not-granted`: the user has not granted `skills.read`.
+ * `not-available`: this host has no skill store or catalog, or could not read it right now.
+ */
+export declare interface KayAppSkillsUnavailable {
+    readonly status: "unavailable";
+    readonly reason: "not-granted" | "not-available";
+    readonly message: string;
+}
+
+/**
+ * Whether Kay keeps a history for the skill, and how its local copy relates to its source.
+ * `unversioned`: the skill's files are the user's own, and Kay keeps no history of them.
+ * `unavailable`: Kay does keep one and cannot read it right now.
+ */
+export declare type KayAppSkillVersioning = "pristine" | "customized" | "update-available" | "diverged" | "unversioned" | "unavailable";
+
 /** Granted access to the plugin's isolated SQLite database. */
 export declare interface KayAppSqliteStorage {
     /** Open the database once per activation; repeated calls return the same handle. */
@@ -3470,6 +3889,81 @@ export declare interface KayAppStorage {
 /** Kay's reasoning-effort ladder, in ascending order. */
 export declare type KayAppThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
+/**
+ * `app.time` / `api.time`: host facts about time. Added to `kay.app` in SDK 0.12.1 and to
+ * `kay.agent` with the calendar zone-of-record work: a plugin that calls it declares
+ * `compatibility.sdk` `^0.12.1`, so an older Bonsai refuses a directory or repository plugin at
+ * load instead of the call failing.
+ */
+export declare interface KayAppTime {
+    /**
+     * Reads the daemon's clock and the user's time zone now.
+     *
+     * Every call asks the host again and returns a new object; nothing is cached. Call it where you
+     * need the value (inside a tool, a handler or a workflow step), not inside `activate()`: a value
+     * read there is as old as the activation, and the host can run a bundled plugin's `activate()`
+     * against a recording api that has no `time`, so a read there throws. The exception is a
+     * directory plugin that declares a workflow with a cron `timezone`: `workflows.define` is legal
+     * only during `activate()`, so it reads the zone there, and the schedule then keeps that zone.
+     * Keep the result for as long as you use it, and not across a long wait (a sleep, a timer, a
+     * queued run): the zone can change while you wait. On a daemon that runs on the user's machine,
+     * a change of the process's `TZ` shows in the next call. A `TZ` that names a zone wins over the
+     * operating system's zone, so a change of the operating-system zone does not show while the
+     * process has one. When `TZ` is unset or does not name a zone, a change of the operating-system
+     * zone is meant to show, but none has been seen on a real machine yet.
+     *
+     * A zone the host cannot determine is an answer (`zoneSource: "utc-fallback"`), not an error.
+     *
+     * Use this to find the zone, not `Intl.DateTimeFormat().resolvedOptions().timeZone`, which can
+     * keep a zone the runtime read earlier, or `process.env.TZ`, which is often unset or not a zone.
+     * Neither says that the zone is unknown.
+     *
+     * It does not use `this`, so it is safe to destructure.
+     */
+    readonly snapshot: () => KayAppTimeSnapshot;
+}
+
+/**
+ * The plugin-facing time contract: the daemon's clock and the time zone the user is in,
+ * read together in one call.
+ *
+ * Ungated and always present, like `app.paths`. It confers no authority: a plugin runs in the
+ * daemon's process and can already read the clock. What the door adds is the daemon's answer
+ * for the USER's zone, and a label for the case where that answer is unknown.
+ *
+ * This is a leaf module. It lives beside both target SDKs (rather than inside `kay-app`) so the
+ * `kay.agent` SDK can expose the same door without importing the `kay.app` surface, which pulls
+ * that surface into every agent-facing bundle.
+ */
+/** One reading of the daemon's clock and the user's time zone. Each call returns a new object. */
+export declare interface KayAppTimeSnapshot {
+    /** The daemon's clock when the snapshot was read: milliseconds since the Unix epoch. */
+    readonly nowMs: number;
+    /**
+     * The time zone the user is in, as an IANA id in the spelling ICU resolves (`America/New_York`).
+     * One zone can have two ids, and ICU picks one: `Asia/Kolkata` comes back as `Asia/Calcutta`. So
+     * never compare zone ids with `===`. A first-party plugin compares with `sameZone` from
+     * `@kay/time`. A plugin that imports only this SDK and node builtins resolves each id with
+     * `new Intl.DateTimeFormat("en-US", { timeZone: id }).resolvedOptions().timeZone` and compares the
+     * results. Pass `zone` as the `timeZone` of `Intl.DateTimeFormat` or `toLocaleString` to format a
+     * time for the user.
+     *
+     * When `zoneSource` is `utc-fallback` the zone is unknown, and this value is `UTC` only because a
+     * value is required.
+     */
+    readonly zone: string;
+    /**
+     * How the daemon found `zone`.
+     * - `host`: the daemon runs on the user's machine, and `zone` is the zone the daemon process
+     *   runs in, read for this call: the process's `TZ` when that names a zone, otherwise the
+     *   operating system's zone.
+     * - `utc-fallback`: the daemon does not know the user's zone. It runs on another machine (a remote
+     *   daemon), or the machine's zone could not be read or is not an IANA id. `zone` is `UTC`, which
+     *   here is a placeholder and not a fact about the user: do not show it to the user as their zone.
+     */
+    readonly zoneSource: "host" | "utc-fallback";
+}
+
 /**
  * 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
@@ -3587,6 +4081,22 @@ export declare interface KayAppTurnSettledSessionEvent extends KayAppSessionEven
     readonly originSurface?: string;
 }
 
+/**
+ * The person answered a card the agent drew with `ui_render` (pressed Send on a drafted message,
+ * submitted a form), published once the answer is projected into the source session's transcript.
+ *
+ * It names the answer and the call it answers, never the answer's content: a handler reads the
+ * `ui_action` entry and the `ui_render` call through the granted `KayAppCorpus`, like every other
+ * event here. A typed message does NOT publish this (it publishes `human-message`), and a click
+ * does not publish `human-message`. A click the host refuses at admission (a stale or duplicate
+ * card) is never projected and publishes nothing, so there is one event per accepted answer.
+ */
+export declare interface KayAppUiActionSessionEvent extends KayAppSessionEventBase {
+    readonly type: "ui-action";
+    /** The `ui_render` tool call the answer is for (the `ui_action` message's own `toolCallId`). */
+    readonly toolCallId: string;
+}
+
 export declare interface KayAppWhiteboard {
     /**
      * Binds read-only Whiteboard access to the exact context issued to this plugin's session source.
@@ -3715,6 +4225,14 @@ export declare interface KayAppWorkflowContext {
      * is gone. Settled memo results return directly. A crash after a turn settles but before its
      * memo commits can cause one extra continuation turn in the same session.
      *
+     * A keyed child whose turn fails for a transient reason (`network`, `stream_interrupted`,
+     * `overloaded`, `rate_limit`, `server_error`, or `timeout` when you declared no `timeoutMs`) is
+     * continued the same way: Kay waits, waits for the network when it can probe it, and sends a
+     * continuation to the same session, up to six times and for at most 20 hours after the first
+     * failure. A continuation the host refuses counts as one attempt and keeps the failure. Only
+     * the final outcome returns and is memoized. Unkeyed children and every other failure return at
+     * once.
+     *
      * This does not resume an interrupted tool's JavaScript. The continued agent may call it
      * again, so external effects still need idempotency when duplicates would matter.
      */
@@ -4000,7 +4518,7 @@ export declare interface KayAppWorkspaceTabSnapshot {
 
 declare type KnownApi = "openai-completions" | "mistral-conversations" | "openai-responses" | "azure-openai-responses" | "openai-codex-responses" | "anthropic-messages" | "bedrock-converse-stream" | "google-generative-ai" | "google-vertex" | "pi-messages";
 
-declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
+declare type KnownProvider = "amazon-bedrock" | "ant-ling" | "anthropic" | "google" | "google-vertex" | "openai" | "azure-openai-responses" | "openai-codex" | "radius" | "typesafe" | "nvidia" | "deepseek" | "github-copilot" | "xai" | "groq" | "cerebras" | "openrouter" | "vercel-ai-gateway" | "zai" | "zai-coding-cn" | "mistral" | "minimax" | "minimax-cn" | "moonshotai" | "moonshotai-cn" | "huggingface" | "fireworks" | "together" | "baseten" | "opencode" | "opencode-go" | "kimi-coding" | "meta" | "cloudflare-workers-ai" | "cloudflare-ai-gateway" | "qwen-token-plan" | "qwen-token-plan-cn" | "qwen-token-plan-individual" | "xiaomi" | "xiaomi-token-plan-cn" | "xiaomi-token-plan-ams" | "xiaomi-token-plan-sgp";
 
 declare interface LineRange {
     readonly start: number;
@@ -4062,29 +4580,26 @@ declare interface MistralConversationsCompat {
     supportsMidConvoSystemMessages?: boolean;
 }
 
-declare interface Model<TApi extends Api> {
-    id: string;
-    name: string;
-    api: TApi;
-    provider: ProviderId;
-    baseUrl: string;
+/** Chat model: usable with `stream()` and friends. */
+declare interface Model<TApi extends Api> extends BaseModel<TApi> {
+    /**
+     * Optional: chat is the default model type, so models without `type` are chat
+     * models. Narrow mixed model lists with `isModelType()` instead of comparing
+     * `type` directly.
+     */
+    type?: "chat";
     reasoning: boolean;
     /**
      * Maps pi thinking levels to provider/model-specific values.
      * Missing keys use provider defaults. null marks a level as unsupported.
      */
     thinkingLevelMap?: ThinkingLevelMap;
-    input: ("text" | "image")[];
-    /** Provider input limits and cache-safe preprocessing metadata. */
-    inputLimits?: ModelInputLimits;
-    cost: ModelCost;
     /** Prompt cache lifetimes per retention tier. Unset when the provider's cache behavior is unknown. */
     promptCache?: ModelPromptCache;
     contextWindow: number;
     maxTokens: number;
     /** Default sampling parameters for this model. See {@link StreamOptions.samplingParams}; per-request keys override these. */
     samplingParams?: Record<string, unknown>;
-    headers?: Record<string, string>;
     /** Compatibility overrides for OpenAI-compatible APIs. If not set, auto-detected from baseUrl. */
     compat?: TApi extends "openai-completions" ? OpenAICompletionsCompat : TApi extends "openai-responses" | "azure-openai-responses" | "openai-codex-responses" ? OpenAIResponsesCompat : TApi extends "anthropic-messages" ? AnthropicMessagesCompat : TApi extends "bedrock-converse-stream" ? BedrockCompat : TApi extends "mistral-conversations" ? MistralConversationsCompat : never;
 }
@@ -4137,7 +4652,27 @@ declare type ModelPromptCache = Partial<Record<Exclude<CacheRetention, "none">,
 
 declare type ModelThinkingLevel = "off" | ThinkingLevel;
 
-export { NoulResponse }
+/** A tool call that another tool made while it ran, for example from a codemode script. */
+declare interface NestedToolCallRecord {
+    id: string;
+    name: string;
+    /** Omitted when over the size limits; `argumentsBytes` then gives their size. */
+    arguments?: JsonObject;
+    /** UTF-8 size of the arguments as JSON, set when `arguments` is omitted. */
+    argumentsBytes?: number;
+    /** `unfinished`: the call was still running when the calling tool finished. */
+    status: "ok" | "error" | "unfinished";
+    durationMs?: number;
+    /** Error text, truncated. */
+    error?: string;
+}
+
+/** Bounded record of the nested calls a tool made. Results are not recorded. */
+declare interface NestedToolCalls {
+    calls: NestedToolCallRecord[];
+    /** False when calls were dropped, arguments omitted, or calls had not finished. */
+    complete: boolean;
+}
 
 /**
  * Compatibility settings for OpenAI-compatible completions APIs.
@@ -4304,6 +4839,11 @@ declare interface OpenRouterRouting {
     };
 }
 
+export declare function parseLineSelector(input: string): {
+    address: string;
+    selector: LineSelector;
+};
+
 export declare function payload(name: string, schema: SchemaInput, options?: UriPayloadOptions): UriPayloadContract;
 
 declare type PhaseShiftCost = z.infer<typeof phaseShiftCostSchema>;
@@ -4420,8 +4960,6 @@ declare interface ProxiedToolCall {
     readonly input: Record<string, unknown>;
 }
 
-export { Questions }
-
 declare interface RawResource {
     readonly uri: string;
     readonly content: string | Uint8Array;
@@ -4589,7 +5127,7 @@ declare interface ResolveTokenSuccess {
  * failure.
  */
 /** Provider-neutral factual category for a failed model run. */
-declare type RunFailureReason = "auth" | "budget_exceeded" | "content_blocked" | "context_overflow" | "invalid_request" | "model_unavailable" | "network" | "overloaded" | "quota_exhausted" | "rate_limit" | "safeguard_block" | "seat_unpaid" | "server_error" | "stream_interrupted" | "timeout" | "unknown";
+declare type RunFailureReason = "auth" | "content_blocked" | "context_overflow" | "invalid_request" | "model_unavailable" | "network" | "overloaded" | "quota_exhausted" | "rate_limit" | "safeguard_block" | "seat_unpaid" | "server_error" | "stream_interrupted" | "timeout" | "unknown";
 
 declare type SchemaInput = z.ZodType | JsonSchema;
 
@@ -4615,8 +5153,6 @@ declare interface ScopeRequirement {
     readonly alternatives: readonly ScopeAlternative[];
 }
 
-export { ScoreResponse }
-
 /**
  * Every SDK capability that can mint a session. A new door adds a value here.
  *
@@ -4674,6 +5210,7 @@ declare const SessionCausedByEvent: z.ZodObject<{
             "turn-settled": "turn-settled";
             "phase-shift": "phase-shift";
             "human-message": "human-message";
+            "ui-action": "ui-action";
         }>;
         entryId: z.ZodString;
         runId: z.ZodOptional<z.ZodString>;
@@ -4872,6 +5409,7 @@ declare const SessionProvenanceRecord: z.ZodObject<{
                 "turn-settled": "turn-settled";
                 "phase-shift": "phase-shift";
                 "human-message": "human-message";
+                "ui-action": "ui-action";
             }>;
             entryId: z.ZodString;
             runId: z.ZodOptional<z.ZodString>;
@@ -4943,10 +5481,6 @@ declare interface SystemMessage {
     timestamp: number;
 }
 
-export { SystemOneRequest }
-
-export { SystemOneResult }
-
 declare interface TextContent {
     type: "text";
     text: string;
@@ -5007,6 +5541,19 @@ declare interface ToolCall {
     namespace?: string;
 }
 
+/** A call to judge with {@link ToolContext.checkToolCallPermission}. */
+declare interface ToolCallPermissionCheck {
+    readonly toolName: string;
+    readonly input: Record<string, unknown>;
+}
+
+declare type ToolCallPermissionVerdict = {
+    readonly allowed: true;
+} | {
+    readonly allowed: false;
+    readonly reason: string;
+};
+
 declare interface ToolContext {
     readonly cwd: string;
     readonly model: Model<any> | undefined;
@@ -5031,6 +5578,13 @@ declare interface ToolContext {
      * behind itself. Present only with a live session. One request may be pending at a time.
      */
     readonly requestMidTurnCompaction?: (customInstructions?: string, trigger?: "command" | "suggestion") => MidTurnCompactionRequest;
+    /**
+     * Put a call this tool is about to cause through the session's permission gate, as if the agent
+     * had made it directly: classification, rules, mode, the auto approver, and the approval card.
+     * The call is only judged, never executed. For a tool whose effect is only knowable at run time
+     * (a click in a web page that turns out to send an email). Present only with a live session.
+     */
+    readonly checkToolCallPermission?: (call: ToolCallPermissionCheck) => Promise<ToolCallPermissionVerdict>;
     /**
      * Re-root the session into `newCwd` mid-run, recomposing the cwd-scoped substrate (builtin tools,
      * the capability registry, the system-prompt project line) in place so subsequent tool calls operate
@@ -5317,7 +5871,9 @@ declare type ToolResultMessage<TDetails = JsonValue> = IsJsonCompatible<TDetails
     content: (TextContent | ImageContent)[];
     details?: JsonRepresentation<TDetails>;
     /** Usage from the tool execution itself, if available. Not part of main LLM context accounting. */
-    usage?: Usage_2;
+    usage?: Usage;
+    /** Calls this tool made to other tools. Kept for the session record; not sent to the model. */
+    nestedCalls?: NestedToolCalls;
     isError: boolean;
     timestamp: number;
 } : never;
@@ -5343,8 +5899,6 @@ export declare function transcriptRoleLabel(role: "user" | "assistant"): "User"
 declare interface TSchema {
 }
 
-export { TypeSafeClient }
-
 declare interface UriAgentHint {
     readonly summary: string;
     readonly commonFlows?: readonly UriCommonFlow[];
@@ -5619,6 +6173,13 @@ export declare interface UriModule {
      * only after all specific (fallback-falsy) modules miss.
      */
     readonly fallback?: boolean;
+    /**
+     * The module parses the read tool's trailing line selector itself. Absent: the host strips
+     * an explicit range (`:50-200`, `:50-`, `:50+10`, `:raw`, never a bare `:50`), dispatches the
+     * bare address, and windows the result (`hostLineWindow`). Mirrors `@herd/uri`'s `UriModule.ownsLineSelectors`, which owns the
+     * full contract (#10754).
+     */
+    readonly ownsLineSelectors?: boolean;
     readonly claims?: readonly UriClaim[];
     /**
      * Optional; injected into the system prompt when the module is active. Omit
@@ -5646,6 +6207,13 @@ export declare interface UriModule {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * Name what a settled call on `request.uri` touched, for a transcript row (mirrors the protocol
+     * contract in `@herd/uri`). The host asks once per successful URI verb call after the handler
+     * returns, bounds the wait, and stamps the admitted answer on the result's `details` only; a
+     * throw, a late answer or a refused one costs the label, never the call.
+     */
+    labelResource?(request: UriResourceLabelRequest, ctx: UriResolveContext): Promise<UriResourceLabel | undefined>;
     /**
      * Set false when the generic write tool must reject `source` copies before
      * fetching the source. Inline `content` writes remain available.
@@ -5825,6 +6393,18 @@ declare interface UriOperationDescription {
     readonly target: string;
     /** Model-authored content; the host flattens, budgets, elides and bounds it. */
     readonly quote?: string;
+    /** Full, render-only detail. Hosts must not turn a rich preview into one-line approval. */
+    readonly preview?: {
+        readonly title: string;
+        readonly description?: string;
+        readonly fields?: readonly {
+            readonly label: string;
+            readonly value: string;
+            readonly oldValue?: string;
+        }[];
+    };
+    /** True only when every displayed fact comes from the input, independent of the executing account. */
+    readonly accountIndependent?: true;
     /** What this description accounts for; the host refuses undeclared input. */
     readonly accounts: {
         /** The payload actually read by the module, after its own decoding. */
@@ -6167,6 +6747,24 @@ declare interface UriResourceDescription {
     readonly sourceUrl?: string;
 }
 
+/**
+ * What a settled call touched, as a person would name it.
+ *
+ * `name` is the resource itself (`#lane-analytics`). `section` is the part of it the address
+ * reaches into (`thread`), and is absent when the address is the resource.
+ */
+declare interface UriResourceLabel {
+    readonly name: string;
+    readonly section?: string;
+}
+
+/** The call a module is asked to label. */
+declare interface UriResourceLabelRequest {
+    readonly operation: UriOperation;
+    /** The dispatch address: selector-stripped, the exact form the module's verb handler received. */
+    readonly uri: string;
+}
+
 declare interface UriSchemeClaim {
     readonly kind: "scheme";
     readonly scheme: string;
@@ -6338,9 +6936,7 @@ declare interface UrlPatternClaim {
     readonly examples?: readonly string[];
 }
 
-export { Usage }
-
-declare interface Usage_2 {
+declare interface Usage {
     input: number;
     output: number;
     cacheRead: number;
@@ -6502,8 +7098,8 @@ export declare type WhiteboardValue = z.infer<typeof WhiteboardValue>;
 /**
  * Run `use` against a live Jev client, falling back to `fallback` whenever Jev cannot serve the
  * call. The wrapper exists so a feature can ASK for a typed decision without ever depending on
- * one: `fallback` is required, and it runs whenever no host-managed key is saved,
- * the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
+ * one: `fallback` is required, and it runs whenever no provider in the user's Jev provider
+ * order holds a usable credential, the user has not granted `jev.use`, the branch exceeds its budget, `use` throws, or
  * `use` declines by returning `undefined`. With valid options, this rejects on an explicit
  * `signal` abort, reaching `deadlineAt`, or `fallback` itself throwing.
  *
@@ -6511,10 +7107,9 @@ export declare type WhiteboardValue = z.infer<typeof WhiteboardValue>;
  * {@link createFallbackOnlyWithJev}, so a caller never branches on availability — branching is
  * exactly how a fallback gets skipped.
  *
- * `jev` is the vendor's own `TypeSafeClient`, configured with the host's default model and base
- * URL. Native `request.model` overrides remain supported. It
- * is valid only for the duration of the callback: a reference retained past `use`'s scope is
- * refused at the transport, and an in-flight request is aborted when the call stops waiting.
+ * `jev` is a {@link JevClient} on the host's Jev model. It is valid only for the duration of
+ * the callback: a reference retained past `use`'s scope is refused at the transport, and an
+ * in-flight request is aborted when the call stops waiting.
  * The callback itself is ABANDONED, not interrupted — a host cannot stop arbitrary JavaScript
  * that is already running, so `use` must not perform side effects it would mind completing
  * unobserved. The same applies to a running fallback: abort/deadline stops waiting for it but
@@ -6523,7 +7118,7 @@ export declare type WhiteboardValue = z.infer<typeof WhiteboardValue>;
 export declare type WithJev = <T>(
 /** Return `undefined` to decline (the fallback runs). A feature whose real result can itself be
  *  `undefined` should return `null` or its own wrapper type instead. */
-use: (jev: TypeSafeClient) => T | undefined | PromiseLike<T | undefined>, 
+use: (jev: JevClient) => T | undefined | PromiseLike<T | undefined>, 
 /** Required. The behaviour the feature has without Jev. */
 fallback: () => T | PromiseLike<T>, options?: WithJevOptions) => Promise<T>;