@yaklabs-ai/plugin-sdk 0.11.0 → 0.12.3

package/dist/kay-agent-testing.d.ts

@@ -1,4 +1,3 @@
-import type { TypeSafeClient } from '@typesafe-ai/sdk';
 import { z } from 'zod';
 
 /**
@@ -23,6 +22,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
@@ -54,8 +56,18 @@ declare interface AgentToolResult<T = JsonValue_3 | 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_3;
     /** Usage from the final tool execution itself, if available. Not used for main LLM context accounting. */
     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.
@@ -246,6 +258,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. */
@@ -371,6 +397,13 @@ declare interface DelegatedConnectContext {
 /** What a delegated scheme's `connect` resolves with: the material to vault + optional label/provenance. */
 declare interface DelegatedConnectResult {
     readonly material: DelegatedSecretMaterial;
+    /**
+     * A stable account id for this sign-in, used instead of a freshly minted one, so a reconnect
+     * overwrites the same record (and keeps it the default) rather than adding a sibling. 1-128
+     * characters: letters, digits, and `._:@+-`, starting with a letter or digit; any other value
+     * fails the connect. Absent mints a fresh id per connect.
+     */
+    readonly accountId?: string;
     /** Account display label; a caller-supplied `service_connect` label takes precedence. */
     readonly label?: string;
     /** Structured provenance the scheme derived during connect; persisted via the vault's write-path. */
@@ -498,24 +531,8 @@ declare interface ExtensionPaths {
 export declare function fauxAuthContext(overrides?: Partial<ExtensionAuthContext>): ExtensionAuthContext;
 
 /** The capability handles a `KayAgentPluginApi` always carries — authority is decided per call. */
-export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interceptToolCall" | "withJev" | "events">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time">;
 
-/**
- * The brokered capability handles every `KayAgentPluginApi` carries, as doubles that refuse
- * to be used. Spread them into a hand-rolled activation fake:
- *
- * ```ts
- * createMyPluginKayAgent()({ ...fauxKayAgentCapabilities(), uri: { registerModule }, ... });
- * ```
- *
- * They exist because the handles are ALWAYS present on the real api — the daemon composes every
- * brokered capability unconditionally and decides authority at each call (`filesystem.read
- * {root}`, `network.connect {connect}`, ...), so presence is not a grant signal a plugin may
- * feature-detect, and a fake that omits one is not a `KayAgentPluginApi`. The four I/O brokers
- * reject on use; `interceptToolCall` is a registration, so like the fakes' own `registerTool` it
- * accepts and drops. A test that exercises a capability overrides that one handle after the
- * spread; the rest keep refusing.
- */
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
 /**
@@ -531,6 +548,216 @@ declare interface ImageContent {
     mimeType: string;
 }
 
+/**
+ * The value a Browser Interaction driver sets as `credentialGuard` to declare that every act runs
+ * the page-side credential guard from `@kay/interaction-page-scripts` (never type into or click a
+ * sign-in form). The engine refuses to register a browser driver without it.
+ */
+declare const INTERACTION_CREDENTIAL_GUARD = "kay.credential-guard/v1";
+
+declare interface InteractionActed {
+    /** The address of the target acted on, when it changed (an open landed in a new page). */
+    readonly target?: string;
+    readonly url: string;
+    readonly title: string;
+    /** What the action visibly caused: a dialog, an alert, a page opened beside it. */
+    readonly changes?: readonly string[];
+    readonly notes?: readonly string[];
+    /** Fresh browser sign-in state for the service the engine named in the open spec. */
+    readonly webSession?: {
+        readonly state: "signed-in" | "signed-out" | "unknown";
+        readonly checkedAt: number | null;
+    };
+}
+
+/**
+ * One action over a candidate from the latest observation of the same target. `fill` replaces the
+ * field's contents unless `append` is set, and presses Enter afterwards when `submit` is set.
+ */
+declare type InteractionAction = {
+    readonly kind: "click";
+    readonly element: InteractionCandidate;
+} | {
+    readonly kind: "fill";
+    readonly element: InteractionCandidate;
+    readonly text: string;
+    readonly submit?: boolean;
+    readonly append?: boolean;
+} | {
+    readonly kind: "select";
+    readonly element: InteractionCandidate;
+} | {
+    readonly kind: "activate";
+    readonly element: InteractionCandidate;
+} | {
+    readonly kind: "press";
+    readonly element: InteractionCandidate;
+}
+/**
+* Scroll by `delta` px (positive is down). With `element` (a `scroll` candidate that names a
+* node), the scroll container that candidate scrolls; without, the whole page or window.
+*/
+| {
+    readonly kind: "scroll";
+    readonly delta: number;
+    readonly element?: InteractionCandidate;
+} | {
+    readonly kind: "wait";
+};
+
+/**
+ * One element (or control) an observation offers, with the kind of action it supports. `id` is
+ * the driver's per-observation id; the engine mints its own session-unique ids over it. Extra
+ * fields are the driver's native identity (a page node number, an accessibility token), returned
+ * to the driver untouched in {@link InteractionAction}.
+ */
+declare interface InteractionCandidate {
+    readonly id: string;
+    readonly kind: InteractionCandidateKind;
+    readonly label: string;
+    readonly node?: number | undefined;
+    readonly role?: string | undefined;
+    readonly value?: string | undefined;
+    readonly current_value?: string | undefined;
+    readonly checked?: string | undefined;
+    readonly selected?: string | undefined;
+    readonly expanded?: string | undefined;
+    readonly delta?: number | undefined;
+    /** Where an element outside the visible area sits; absent means on screen. */
+    readonly position?: "above" | "below" | "beside" | undefined;
+    /** A `press` candidate's key (`return`, `escape`, `tab`); its id is `press_<key>` by convention. */
+    readonly key?: string | undefined;
+    /** The region the element sits in; see {@link InteractionRegion}. */
+    readonly region?: InteractionRegion | undefined;
+    /**
+     * The `node` of the scroll container (a list or pane that scrolls on its own) the element sits
+     * in, matching that container's `scroll` candidates; absent when it sits in none.
+     */
+    readonly scroller?: number | undefined;
+    readonly [native: string]: unknown;
+}
+
+/** The candidate kinds a driver may offer. */
+declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
+
+declare interface InteractionDriver {
+    /** Unique in the session. `builtin:` is reserved for Kay's own drivers. */
+    readonly id: string;
+    /** Human-readable name the agent sees beside the driver's targets. */
+    readonly label: string;
+    readonly kind: InteractionDriverKind;
+    /** Required on a `browser` driver; see {@link INTERACTION_CREDENTIAL_GUARD}. */
+    readonly credentialGuard?: typeof INTERACTION_CREDENTIAL_GUARD;
+    /** Whether the driver can act at all right now (platform, grants, a live connection). */
+    isAvailable(): Promise<boolean>;
+    targets(): Promise<InteractionOutcome<{
+        readonly targets: readonly InteractionTarget[];
+    }>>;
+    observe(target: string | undefined, options?: {
+        readonly fullText?: boolean;
+    }): Promise<InteractionOutcome<InteractionObserved>>;
+    act(target: string | undefined, action: InteractionAction): Promise<InteractionOutcome<InteractionActed>>;
+    screenshot(target: string | undefined): Promise<InteractionOutcome<{
+        readonly png: Uint8Array;
+    }>>;
+    open(spec: InteractionOpenSpec): Promise<InteractionOutcome<InteractionActed>>;
+}
+
+/**
+ * The Interaction driver contract: what a plugin implements to let Kay's agent drive something
+ * on the user's machine (a browser, an app, a remote screen) through the harness-owned
+ * Interaction engine.
+ *
+ * The engine owns everything that is policy: the `interaction_*` tools, the session-unique element
+ * ids the agent sees, the run loop that drives a goal step by step, the permission check before
+ * every action, screenshots, and reports. A driver owns only its own I/O: list what it can drive,
+ * observe one target as a list of actionable candidates, perform one action on a candidate from
+ * its latest observation, capture a screenshot, and open a page or app. It chooses no actions,
+ * maps no permissions, and retries nothing beyond its own transport. That split is what makes
+ * every tool work on every driver.
+ *
+ * Shape mirrors `SearchProvider` behind `web_search`: one tool set owned by the harness, many
+ * backends registered per session, the `builtin:` id namespace reserved for Kay's own.
+ */
+/** "Browser Interaction" drives web pages; "Computer Use Interaction" drives native apps. */
+declare type InteractionDriverKind = "browser" | "computer-use";
+
+/** A failed operation. `unavailable`: nothing to act on; `refused`: will not run as asked. */
+declare interface InteractionFailure {
+    readonly ok: false;
+    readonly reason: "unavailable" | "refused" | "error";
+    readonly message: string;
+}
+
+/** What a driver sees on one target. */
+declare interface InteractionObservation {
+    readonly url: string;
+    readonly title: string;
+    /** Visible text, or the whole page's text when the observe asked for `fullText`; capped. */
+    readonly text: string;
+    readonly actions: readonly InteractionCandidate[];
+    /** Candidates the driver dropped to stay within its cap. */
+    readonly omitted_actions: number;
+}
+
+declare interface InteractionObserved {
+    /** The address of the target observed; absent when the default target has no address. */
+    readonly target?: string;
+    readonly observation: InteractionObservation;
+    /** Lines the engine shows the agent under the observation (where the target sits, siblings). */
+    readonly notes?: readonly string[];
+}
+
+/** Navigate a page to `url`, or launch / switch to the app `app` names (a bundle id or a name). */
+declare interface InteractionOpenSpec {
+    readonly target?: string;
+    readonly url?: string;
+    readonly app?: string;
+    /** The service whose browser sign-in state to report after navigation, when the engine knows it. */
+    readonly webSessionServiceId?: string;
+}
+
+declare type InteractionOutcome<T> = ({
+    readonly ok: true;
+} & T) | InteractionFailure;
+
+/**
+ * The part of a page or window an element sits in: the open dialog, menu, or sheet it belongs to,
+ * else its landmark (navigation, main, a window). `front` marks the overlay covering the rest: a
+ * modal dialog (or one held by a full-screen overlay), a sheet, or a floating menu, the last such
+ * in the document; elements outside it
+ * usually cannot be clicked while it is open. A docked or always-visible dialog or menu is a
+ * region but never in front.
+ */
+declare interface InteractionRegion {
+    readonly role: string;
+    readonly name: string;
+    readonly front?: boolean | undefined;
+}
+
+/**
+ * One surface Kay ships, in the driver contract's own shape, so a plugin's driver is the surface
+ * plus an identity: `{ id, label, kind, ...api.interaction.desktop }`. Each call is checked
+ * against the plugin's `interaction.surface {surface}` grant, and then against the session's
+ * permissions exactly as the agent's `interaction_*` tools are: an act is judged as the plugin
+ * permission it amounts to (a Send click in Gmail as a Gmail write), an open as `interaction_open`,
+ * an observation or screenshot as `interaction_read`. A refused or unavailable call answers
+ * `{ ok: false }` (and `isAvailable()` false) rather than throwing.
+ */
+declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targets" | "observe" | "act" | "screenshot" | "open">;
+
+/**
+ * One thing a driver can be pointed at. `id` is a driver-owned address, unique across every
+ * driver in the session (prefix it with your scheme), that the agent passes back as `target`.
+ * `active` marks the driver's default target.
+ */
+declare interface InteractionTarget {
+    readonly id: string;
+    readonly title: string;
+    readonly url?: string;
+    readonly active: boolean;
+}
+
 /**
  * Invoke a plugin tool definition's `execute` in a test, owning the **one sanctioned cast** past
  * `ToolExecutionAwareParams<unknown>` — the phantom-wire-shaped type every `ToolDefinition`'s
@@ -549,6 +776,118 @@ declare interface ImageContent {
  */
 export declare function invokeToolForTest<TDetails = unknown>(tool: ToolDefinition<any, TDetails>, params: Record<string, unknown>, ctx?: ToolContext): Promise<AgentToolResult<TDetails>>;
 
+/** The answer shape one question gets back. */
+declare type JevAnswerFor<Q> = Q extends JevBoolQuestion ? JevBoolAnswer : Q extends JevChoiceQuestion<infer L> ? JevChoiceAnswer<L> : Q extends JevScoreQuestion ? JevScoreAnswer : never;
+
+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. */
+declare interface JevBoolQuestion {
+    readonly type: "bool";
+    readonly instructions: string;
+    readonly criteria?: {
+        readonly true: string;
+        readonly false: string;
+    };
+}
+
+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. */
+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. */
+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;
+    };
+}
+
+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.
+ */
+declare interface JevClient {
+    classify<const Q extends JevQuestions>(request: JevClassifyRequest<Q>, options?: {
+        readonly signal?: AbortSignal;
+    }): Promise<JevClassification<Q>>;
+}
+
+declare type JevQuestion = JevBoolQuestion | JevChoiceQuestion | JevScoreQuestion;
+
+/** A rubric: questions keyed by the name each answer comes back under. */
+declare type JevQuestions = Readonly<Record<string, JevQuestion>>;
+
+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. */
+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.
+ */
+declare type JevState = object;
+
 declare type JsonObject = {
     [key: string]: JsonValue_3;
 };
@@ -586,10 +925,18 @@ declare interface KayAgentEvents {
     publish(localId: string, payload: unknown): void;
 }
 
-/** Claim-checked filesystem operations. Paths are root-relative; canonical host paths never cross the seam. */
+/**
+ * Claim-checked filesystem operations. Paths are root-relative; canonical host paths never cross
+ * the seam. Writes are atomic: readers see the old file or the new one, never a partial write. A
+ * replace keeps the file's mode but makes a new file, so owner and extended attributes are not
+ * carried over. On a volume without hard links an exclusive create can briefly show an empty file.
+ */
 declare interface KayAgentFilesystem {
     readText(location: KayAgentFilesystemLocation): Promise<string>;
-    writeText(location: KayAgentFilesystemLocation, content: string): Promise<void>;
+    writeText(location: KayAgentFilesystemLocation, content: string, options?: KayAgentFilesystemWriteOptions): Promise<void>;
+    /** The whole file, or the requested window of it. */
+    readBytes(location: KayAgentFilesystemLocation, range?: KayAgentFilesystemByteRange): Promise<Uint8Array>;
+    writeBytes(location: KayAgentFilesystemLocation, bytes: Uint8Array, options?: KayAgentFilesystemWriteOptions): Promise<void>;
     mkdir(location: KayAgentFilesystemLocation): Promise<void>;
     readDir(location: KayAgentFilesystemLocation): Promise<readonly KayAgentFilesystemEntry[]>;
     stat(location: KayAgentFilesystemLocation): Promise<KayAgentFilesystemStat>;
@@ -598,6 +945,12 @@ declare interface KayAgentFilesystem {
     realpath(location: KayAgentFilesystemLocation): Promise<string>;
 }
 
+/** A byte window of a file; `maxBytes` is capped by the host. */
+declare interface KayAgentFilesystemByteRange {
+    readonly offset: number;
+    readonly maxBytes: number;
+}
+
 declare interface KayAgentFilesystemEntry {
     readonly name: string;
     readonly kind: "file" | "directory" | "symlink" | "other";
@@ -615,6 +968,27 @@ declare interface KayAgentFilesystemStat {
     readonly modifiedAtMs: number;
 }
 
+declare interface KayAgentFilesystemWriteOptions {
+    /** Fail with `already_exists` instead of replacing a file already at the location. */
+    readonly exclusive?: boolean;
+}
+
+declare interface KayAgentInteractionSurfaces {
+    /**
+     * Kay's built-in browser pane: the pages in the user's Bonsai tabs. The page-side credential
+     * guard runs on every act, so a driver over this surface may declare
+     * {@link INTERACTION_CREDENTIAL_GUARD}.
+     */
+    readonly browserPane: InteractionSurface;
+    /**
+     * The user's desktop through the platform's accessibility APIs: native apps as targets
+     * (`app://<bundle id>`), their windows' controls as elements. On macOS Kay drives it with its
+     * bundled accessibility worker under the app's Accessibility permission; on a platform with no
+     * backend it reports itself unavailable.
+     */
+    readonly desktop: InteractionSurface;
+}
+
 /** One knowledge-index hit — a reference and within-list rank score, never a snippet. */
 declare interface KayAgentKnowledgeHit {
     readonly uri: string;
@@ -767,9 +1141,17 @@ declare interface KayAgentPluginApi {
      * command it is about to run, and against the host's executable binding.
      */
     readonly process: KayAgentProcess;
+    /**
+     * Always present; the interaction surfaces Kay ships (its browser pane, and the desktop through
+     * the platform accessibility APIs), each call checked against `interaction.surface {surface}`
+     * and the session's permissions (see {@link InteractionSurface}).
+     * Wrap one in an {@link InteractionDriver} and register it with
+     * {@link KayAgentPluginApi.registerInteractionDriver} to make it drivable by the agent.
+     */
+    readonly interaction: KayAgentInteractionSurfaces;
     /**
      * 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. That is the point: with no absent state to feature-detect,
@@ -777,6 +1159,14 @@ declare interface KayAgentPluginApi {
      * guard it with `if (api.withJev !== undefined)`.
      */
     readonly withJev: WithJev;
+    /**
+     * The daemon's clock and the time zone the user is in, read together on each `snapshot()` call.
+     * Always present and ungated: it confers no authority, since a plugin runs in the daemon's
+     * process and can read the clock itself. Read the user's zone here, never from `Intl` or
+     * `process.env.TZ`, and render user-facing times in it rather than an event's own zone. This is
+     * the same zone-of-record port the session stamp uses; see {@link KayAppTime.snapshot}.
+     */
+    readonly time: KayAppTime;
     /**
      * Publish the plugin's declared events, for example so a default notification rule can tell the
      * user what the agent just did. Always present, like {@link withJev}: there is nothing to
@@ -798,6 +1188,14 @@ declare interface KayAgentPluginApi {
      * from `ctx.auth`. A provider without a binding reuses inference credentials or needs none.
      */
     registerSearchProvider(provider: SearchProvider): void;
+    /**
+     * Register an Interaction driver (a backend behind the `interaction_*` tools: something the agent
+     * can read, click, type into, and open). The engine owns the tools, element ids, run loop,
+     * permission checks, and screenshots; the driver owns only its I/O. Declare the driver's `id`
+     * under `contributes.interactionDrivers` in kay-plugin.json first. A `browser` driver must set
+     * `credentialGuard` (see {@link INTERACTION_CREDENTIAL_GUARD}).
+     */
+    registerInteractionDriver(driver: InteractionDriver): void;
     /**
      * Register a content converter (turns raw bytes of a mime type into agent-facing content behind the
      * read tool's finalize stage). Parallel to the kernel's `registerConverter`. Converters are
@@ -998,9 +1396,84 @@ declare interface KayAgentWhiteboardUpdateInput {
     readonly title?: string;
 }
 
+/**
+ * `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.
+ */
+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. */
+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";
+}
+
 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;
@@ -1051,29 +1524,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;
 }
@@ -1386,8 +1856,15 @@ declare interface PluginDelegatedScheme {
     /** Run the connect flow and mint the material to store. Throw to fail the connect. */
     readonly connect: (ctx: PluginDelegatedConnectContext) => Promise<PluginDelegatedConnectResult>;
     /**
-     * Mint fresh material from the current (expiring) material. Absent means non-refreshable:
-     * expired material resolves as-is (like an OAuth scheme without a refresh token).
+     * Mint fresh material from the current (expiring) material, including the `data` the last
+     * connect or refresh returned. Kay calls this only inside its credential authority, which holds
+     * the refresh lease and saves the result; this hook performs the exchange and nothing else.
+     * Returned `data` replaces the stored `data`; omitted `data` keeps it. Returned `expiresAt`
+     * replaces the stored expiry; omitted `expiresAt` means the new material does not expire.
+     * Throw {@link DelegatedRefreshRejectedError} when the provider refused the grant for good (the
+     * user must reconnect); any other throw is retried with backoff and keeps the account connected.
+     * Absent means non-refreshable: expired material resolves as-is (like an OAuth scheme without a
+     * refresh token).
      */
     readonly refresh?: (material: PluginDelegatedSecretMaterial) => Promise<PluginDelegatedSecretMaterial>;
     /**
@@ -1996,6 +2473,19 @@ declare interface ToolCallModel {
  */
 declare type ToolCallOrigin = "model" | "host";
 
+/** 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;
+};
+
 /**
  * What a tool call ADDRESSES, resolved by the session before execution from facts it already
  * holds for auth scoping: a URI verb's matched module (and the extension that registered it), or
@@ -2038,6 +2528,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
@@ -2607,6 +3104,21 @@ declare interface UriModule {
      */
     readonly title?: string;
     readonly fallback?: boolean;
+    /**
+     * Whether this module parses the read tool's trailing line selector out of its own addresses.
+     * Absent or false: the host owns the explicit forms (`:50-200`, `:50-`, `:50+10`, `:raw`). The
+     * read tool strips one before dispatch, hands `read` the bare address, and applies the window
+     * to what comes back, so a module never has to know the grammar for the read tool's own
+     * `Continue with '<address>:N-M'` banner to work on its addresses (#10754). A bare trailing
+     * `:<digits>` is never taken from such a module: it is too common inside real ids (a Figma
+     * node `1:2`), so it reaches the module as written.
+     *
+     * Declare `true` only when the module must see the raw address: its grammar can end in an
+     * explicit-range shape, it wants the bare `:50` form too, or it windows the content itself
+     * (streaming a large file, skipping a cap it applies to an unwindowed read). Such a module
+     * calls `parseLineSelector` itself and reports what it did through `RawResource.selector`.
+     */
+    readonly ownsLineSelectors?: boolean;
     readonly claims?: readonly UriClaim[];
     /** Migration-only prompt summary until structured help/catalog coverage replaces prose. */
     readonly description?: string;
@@ -2616,14 +3128,17 @@ declare interface UriModule {
     /** Pure route/payload validation applied before a consequential permission ask. */
     readonly preflight?: UriOperationPreflightPolicy;
     /**
-     * Structured facts naming the WHOLE consequence of this call, or `undefined` when
-     * the route cannot honestly be described on a one-line approval surface. The module
+     * Structured facts for approval surfaces, or `undefined` when unavailable.
+     * A one-line description must name the whole consequence; `preview` instead
+     * supplies expanded, literal-text detail and suppresses one-line approval. The module
      * owns the static action phrase, target resolution, payload decoding and declaration
      * of covered payload fields and query parameters. Unknown fields cost the summary.
      * The host owns framing, the whole-quote fit (no elision) and display-safety admission.
      *
      * Unlike preflight, this hook is async and may do I/O. Resolve names through `ctx`,
-     * the same dispatch context used by execution, never an ambient or cached account.
+     * the same dispatch context used by execution, never an ambient or cached account. A name
+     * the module resolved under that account may be cached for a bounded time, keyed by that
+     * account's identity and never answered to another account or after a failed lookup.
      * The host calls it once before raising the ask, enforces the short `ctx.signal`
      * deadline and discards late answers. A throw yields no summary and a module-attributed
      * diagnostic; declining costs a click into the app, never an under-described approval.
@@ -2633,6 +3148,26 @@ declare interface UriModule {
         readonly uri: string;
         readonly payload: unknown;
     }, ctx: UriResolveContext): Promise<UriOperationDescription | undefined>;
+    /**
+     * A short, render-only name for the resource a settled call on `request.uri` touched, which the
+     * host stamps on the tool result's `details` so a transcript row can name it where it would
+     * otherwise print the address (`#lane-analytics` and `thread`, not a channel id). Answer
+     * `undefined` for any address you cannot honestly name.
+     *
+     * Called once per successful URI verb call, AFTER the verb handler has returned, with the same
+     * dispatch context. Resolve names through `ctx` and nothing else, and prefer a cache your own
+     * verb handlers warm, keyed by the executing account: a name one account saw is never answered
+     * to another, and a failed, blank or aborted lookup is never cached. The host bounds the wait
+     * (a finished result is held at most a quarter of a second), gives `ctx.signal` a hard deadline,
+     * and drops a late, thrown or refused answer without failing the call; a throw is reported as a
+     * module-attributed diagnostic. The label is a label, never an identity: the address remains the
+     * click target, hover text and accessible name. It is UI-only, so it never enters the tool
+     * result's content and no telemetry reads it.
+     *
+     * Unlike `describeOperation` this is not an approval surface: it carries no consequence, no
+     * quote and no coverage claim, and nothing may gate a permission on it.
+     */
+    labelResource?(request: UriResourceLabelRequest, ctx: UriResolveContext): Promise<UriResourceLabel | undefined>;
     /**
      * Per-resource observability: does a `format: "observation"` read of THIS
      * uri render source-native material ({@link UriResolveContext.format})?
@@ -2753,6 +3288,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. */
@@ -3016,6 +3563,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;
@@ -3332,8 +3897,8 @@ 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.
  *
@@ -3341,10 +3906,9 @@ 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
@@ -3353,7 +3917,7 @@ declare type WhiteboardValue = z.infer<typeof WhiteboardValue>;
 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>;