@yaklabs-ai/plugin-sdk 0.10.0 → 0.12.2

package/dist/kay-agent.d.ts

@@ -1,8 +1,3 @@
-import { Questions } from '@typesafe-ai/sdk';
-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';
 import type * as z_2 from 'zod';
 
@@ -28,6 +23,9 @@ export 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
@@ -100,8 +98,18 @@ export declare interface AgentToolResult<T = JsonValue_2 | 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_2;
     /** 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.
@@ -340,6 +348,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>;
+}
+
 export declare function basicUriHelp(options: {
     readonly uri: string;
     readonly title: string;
@@ -595,6 +617,27 @@ export declare interface CurrentResourceState {
     readonly content?: string | Uint8Array;
 }
 
+/**
+ * Declare the URIs a tool call created or updated as a side effect, on the result it returns.
+ *
+ * The declarations ride the result to the host, which records them in the transcript under the
+ * reserved `producedResources` details key, so an automation run lists them beside the URIs its
+ * `write` and `edit` calls changed. A declaration the contract refuses (not exactly `{ uri, action }`,
+ * a URI that is neither `scheme://…` nor an absolute local path, an unknown action) never fails the
+ * call, because its effect has already happened: the host records the call's claim as malformed,
+ * the run reports a gap for it, and the session logs a warning. A tool never writes the reserved key
+ * itself; the host drops whatever a result's own details hold there. Declarations ride only a
+ * returned result: a call that throws declares nothing.
+ *
+ * @param result The result the tool returns. Its `details` must be an object or `undefined`;
+ *   `undefined` becomes an empty object that carries the declarations.
+ * @param declarations Each names a `scheme://` URI or an absolute local path, compared as an
+ *   exact string, and whether the call `created` or `updated` it.
+ * @returns A copy of `result` carrying these declarations after any it already carried.
+ * @throws TypeError when `details` is neither an object nor `undefined`, which the types rule out.
+ */
+export declare function declareProducedResources<TDetails extends object | undefined>(result: AgentToolResult<TDetails>, declarations: readonly ProducedResourceDeclaration[]): AgentToolResult<DetailsWithProducedResources<TDetails>>;
+
 /**
  * The one-liner for an auth-gated tool (decision 002 addendum, F-19). Composes
  * {@link toolParameters}, {@link withResolvedAuth}, and `schema.parse` so `body` receives a
@@ -623,6 +666,8 @@ export declare function defineKayAgentAdvertisement(advertisement: KayAgentTarge
 
 export declare function defineTool<TParams extends ToolParametersWire = ToolParametersWire, TDetails = unknown>(definition: PluginToolDefinition<TParams, TDetails>): ToolDefinition<TParams, TDetails>;
 
+declare const DELEGATED_REFRESH_REJECTED: unique symbol;
+
 /**
  * What `service_connect` hands a delegated scheme's {@link DelegatedAuthScheme.connect}: the
  * scope being connected plus the host's browser-redirect capability when one is configured.
@@ -644,12 +689,29 @@ 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. */
     readonly provenance?: AccountProvenance;
 }
 
+/**
+ * The terminal failure of {@link PluginDelegatedScheme.refresh}: the provider no longer accepts the
+ * stored grant (an OAuth `invalid_grant`, say), so only a reconnect helps. Kay marks the account
+ * as needing a reconnect. Throw any other error for a failure that may pass on its own.
+ */
+export declare class DelegatedRefreshRejectedError extends Error {
+    readonly [DELEGATED_REFRESH_REJECTED] = true;
+    constructor(message: string, options?: ErrorOptions);
+}
+
 /**
  * Token material minted by a delegated scheme's extension-provided flow. Core reads only
  * `accessToken`/`expiresAt` (resolution + proactive refresh); `data` is an opaque blob the
@@ -685,6 +747,9 @@ declare interface DerivedToolClassification {
  */
 export declare function describeUriTextEditTarget(grammar: UriTextEditGrammar, index: number, count: number): string;
 
+/** `details` once it carries declarations: an `undefined` input becomes an empty object. */
+export declare type DetailsWithProducedResources<TDetails> = TDetails extends undefined ? Record<string, never> : TDetails;
+
 /**
  * The execute-time auth surface the SDK wrappers read off `ctx.auth`. Slice 3 attaches a
  * concrete implementation (vault + pkce refresh + active-account store) to ExtensionContext;
@@ -814,6 +879,366 @@ declare type InferToolInput<TParams extends ToolParametersWire> = TParams extend
     readonly [toolParametersInput]?: infer TInput;
 } ? TInput : TParams;
 
+/**
+ * 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.
+ */
+export declare const INTERACTION_CREDENTIAL_GUARD = "kay.credential-guard/v1";
+
+export 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.
+ */
+export 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}.
+ */
+export 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. */
+export declare type InteractionCandidateKind = "click" | "fill" | "select" | "scroll" | "wait" | "activate" | "press";
+
+export 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. */
+export declare type InteractionDriverKind = "browser" | "computer-use";
+
+/** A failed operation. `unavailable`: nothing to act on; `refused`: will not run as asked. */
+export declare interface InteractionFailure {
+    readonly ok: false;
+    readonly reason: "unavailable" | "refused" | "error";
+    readonly message: string;
+}
+
+/** What a driver sees on one target. */
+export 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;
+}
+
+export 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). */
+export 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;
+}
+
+export 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.
+ */
+export 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.
+ */
+export declare type InteractionSurface = Pick<InteractionDriver, "isAvailable" | "targets" | "observe" | "act" | "screenshot" | "open">;
+
+/** The interaction surfaces Kay itself ships, which plugins drive through `api.interaction`. */
+export declare type InteractionSurfaceName = "browser-pane" | "desktop";
+
+/**
+ * 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.
+ */
+export declare interface InteractionTarget {
+    readonly id: string;
+    readonly title: string;
+    readonly url?: string;
+    readonly active: boolean;
+}
+
+/** Whether `error` is a {@link DelegatedRefreshRejectedError}, including one from another SDK copy. */
+export declare function isDelegatedRefreshRejected(error: unknown): error is DelegatedRefreshRejectedError;
+
+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";
+
 /** The frozen `createJsonApiClient` surface — see the module doc for why it stops at these three. */
 export declare interface JsonApiClient {
     getJson<TBody = unknown>(url: string, options?: PluginApiQueryOptions): Promise<PluginApiResponse<TBody>>;
@@ -848,6 +1273,14 @@ declare type JsonValue_3 = string | number | boolean | null | JsonValue_3[] | {
 
 declare const JsonValue_3: z.ZodType<JsonValue_3>;
 
+/**
+ * The root selector the host binds to the session family's shared Whiteboard folder. The plugin
+ * that owns the Whiteboard gets the whole folder; every other plugin gets its own
+ * `plugins/<plugin-id>/` folder inside it. Calls on it are claims on
+ * `filesystem.read`/`filesystem.write` with this `root`, decided like any other.
+ */
+export declare const KAY_FAMILY_WHITEBOARD_FILESYSTEM_ROOT = "family-whiteboard";
+
 /** A plugin's Kay agent activation — receives only the brokered {@link KayAgentPluginApi}. */
 export declare type KayAgentActivate = (api: KayAgentPluginApi) => void;
 
@@ -938,10 +1371,18 @@ export 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.
+ */
 export 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>;
@@ -950,6 +1391,12 @@ export declare interface KayAgentFilesystem {
     realpath(location: KayAgentFilesystemLocation): Promise<string>;
 }
 
+/** A byte window of a file; `maxBytes` is capped by the host. */
+export declare interface KayAgentFilesystemByteRange {
+    readonly offset: number;
+    readonly maxBytes: number;
+}
+
 export declare interface KayAgentFilesystemEntry {
     readonly name: string;
     readonly kind: "file" | "directory" | "symlink" | "other";
@@ -974,6 +1421,35 @@ export declare interface KayAgentFilesystemStat {
     readonly modifiedAtMs: number;
 }
 
+export declare interface KayAgentFilesystemWriteOptions {
+    /** Fail with `already_exists` instead of replacing a file already at the location. */
+    readonly exclusive?: boolean;
+}
+
+/**
+ * The host's per-session sink a plugin's drivers register into. Bound by the host to the plugin
+ * and the session; a host that composed no Interaction engine drops registrations.
+ */
+export declare interface KayAgentInteractionDrivers {
+    register(driver: InteractionDriver): void;
+}
+
+export 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. */
 export declare interface KayAgentKnowledgeHit {
     readonly uri: string;
@@ -1126,9 +1602,17 @@ export 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,
@@ -1157,6 +1641,14 @@ export 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
@@ -1466,6 +1958,14 @@ declare const KayPluginManifestV1: z.ZodObject<{
                         displayName: z.ZodOptional<z.ZodString>;
                         schemes: z.ZodOptional<z.ZodArray<z.ZodString>>;
                     }, z.core.$strict>>>;
+                    interactionDrivers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+                        localId: z.ZodString;
+                        displayName: z.ZodOptional<z.ZodString>;
+                        kind: z.ZodEnum<{
+                            browser: "browser";
+                            "computer-use": "computer-use";
+                        }>;
+                    }, z.core.$strict>>>;
                     entityResolvers: z.ZodOptional<z.ZodArray<z.ZodObject<{
                         localId: z.ZodString;
                         displayName: z.ZodOptional<z.ZodString>;
@@ -1730,12 +2230,12 @@ declare const KayPluginManifestV1: z.ZodObject<{
                         capabilities: z.ZodOptional<z.ZodObject<{
                             endpoints: z.ZodOptional<z.ZodArray<z.ZodString>>;
                             host: z.ZodOptional<z.ZodArray<z.ZodEnum<{
+                                "skills.read": "skills.read";
                                 "automations.run": "automations.run";
                                 "navigation.open-session": "navigation.open-session";
                                 "cost.read": "cost.read";
                                 "billing.read": "billing.read";
                                 "context.read": "context.read";
-                                "skills.read": "skills.read";
                                 "memory.read": "memory.read";
                                 "usage.read": "usage.read";
                                 "self-improvement.read": "self-improvement.read";
@@ -2163,7 +2663,7 @@ declare type KayPluginManifestV1 = z.infer<typeof KayPluginManifestV1>;
 
 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;
@@ -2221,29 +2721,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;
 }
@@ -2776,6 +3273,10 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"signals.read">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.app">;
+        slug: z.ZodLiteral<"skills.read">;
+        envelope: z.ZodObject<{}, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"kay.app">;
         slug: z.ZodLiteral<"workspace.command">;
@@ -2855,6 +3356,7 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
             fallback: z.ZodArray<z.ZodObject<{
@@ -2871,6 +3373,7 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
                     default: "default";
                     allow: "allow";
                     ask: "ask";
+                    auto: "auto";
                 }>>;
             }, z.core.$strict>>;
         }, z.core.$strict>;
@@ -2878,6 +3381,15 @@ declare const PluginCapabilityRefusalV1: z.ZodObject<{
         target: z.ZodLiteral<"kay.agent">;
         slug: z.ZodLiteral<"tool-interception.register">;
         envelope: z.ZodObject<{}, z.core.$strict>;
+    }, z.core.$strict>, z.ZodObject<{
+        target: z.ZodLiteral<"kay.agent">;
+        slug: z.ZodLiteral<"interaction.surface">;
+        envelope: z.ZodObject<{
+            surface: z.ZodEnum<{
+                "browser-pane": "browser-pane";
+                desktop: "desktop";
+            }>;
+        }, z.core.$strict>;
     }, z.core.$strict>, z.ZodObject<{
         target: z.ZodLiteral<"plugin">;
         slug: z.ZodLiteral<"config.declare-section">;
@@ -2968,8 +3480,15 @@ export 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>;
     /**
@@ -3122,6 +3641,19 @@ export declare type PluginToolDefinition<TParams extends ToolParametersWire = To
     readonly execute: (toolCallId: string, params: ToolExecutionAwareParams<InferToolInput<TParams>>, signal: AbortSignal | undefined, onUpdate: AgentToolUpdateCallback<TDetails> | undefined, ctx: ToolContext) => Promise<AgentToolResult<TDetails>>;
 };
 
+/**
+ * What a run did to a URI. The words match the automation run wire's artifact actions. When one
+ * run both creates and updates a URI, the reader reports `created`.
+ */
+export declare type ProducedResourceAction = "created" | "updated";
+
+/** One URI a tool call created or updated as a side effect. */
+export declare interface ProducedResourceDeclaration {
+    /** A `scheme://…` URI or an absolute local file path, compared as an exact string. */
+    readonly uri: string;
+    readonly action: ProducedResourceAction;
+}
+
 declare type ProviderId = KnownProvider | string;
 
 /**
@@ -3135,8 +3667,6 @@ declare interface ProxiedToolCall {
     readonly input: Record<string, unknown>;
 }
 
-export { Questions }
-
 export declare interface RawResource {
     readonly uri: string;
     readonly content: string | Uint8Array;
@@ -3525,10 +4055,6 @@ declare interface SessionContext {
  * how most third-party APIs use `""` to mean "no value" rather than "the empty string". */
 export declare function str(record: Record<string, unknown> | undefined, key: string): string | undefined;
 
-export { SystemOneRequest }
-
-export { SystemOneResult }
-
 declare interface TextContent {
     type: "text";
     text: string;
@@ -3645,6 +4171,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
@@ -3687,6 +4226,13 @@ export 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
@@ -3973,7 +4519,11 @@ declare interface ToolPermissionHint {
 /** Controls whether a tool is expected to complete inline or via background adoption. */
 export declare type ToolRunPolicy = "inline" | "background";
 
-export { TypeSafeClient }
+/** A surface that answers every call `unavailable` with `message`: the uncomposed default. */
+export declare function unavailableInteractionSurface(message: string): InteractionSurface;
+
+/** Both surfaces unavailable: a host that composed no Interaction surfaces, a probe, a double. */
+export declare function unavailableInteractionSurfaces(message: string): KayAgentInteractionSurfaces;
 
 /**
  * One sentence naming the two dialects, for refusal messages. Callers prefix
@@ -4315,6 +4865,21 @@ export 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;
@@ -4331,7 +4896,9 @@ export declare interface UriModule {
      * 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.
@@ -4341,6 +4908,26 @@ export 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})?
@@ -4780,6 +5367,24 @@ export 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.
+ */
+export declare interface UriResourceLabel {
+    readonly name: string;
+    readonly section?: string;
+}
+
+/** The call a module is asked to label. */
+export 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;
@@ -5054,9 +5659,7 @@ declare interface UrlPatternClaim {
     readonly examples?: readonly string[];
 }
 
-export { Usage }
-
-declare interface Usage_2 {
+declare interface Usage {
     input: number;
     output: number;
     cacheRead: number;
@@ -5236,8 +5839,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.
  *
@@ -5245,10 +5848,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
@@ -5257,7 +5859,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>;