@yaklabs-ai/plugin-sdk 0.12.2 → 0.12.3

package/README.md

@@ -13,7 +13,7 @@ it under the name your plugin code actually imports:
 ```json
 {
   "dependencies": {
-    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.2"
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.12.3"
   }
 }
 ```

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [

package/dist/disclosure.d.ts

@@ -1257,6 +1257,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
@@ -1486,6 +1494,81 @@ 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" | "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";
@@ -3146,8 +3229,9 @@ 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.
@@ -3305,6 +3389,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. */

package/dist/disclosure.js

@@ -806,7 +806,12 @@ function createKayAgentProbeCapabilityHandles() {
     withJev: INERT_WITH_JEV,
     // Fire-and-forget on the real api too, so dropping is the inert shape: nothing to hang on.
     events: { publish: () => {
-    } }
+    } },
+    // A probe has no user-time port, so it answers the zone as unknown — the same contract the
+    // real capability keeps for a zone the host cannot read.
+    time: {
+      snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
+    }
   };
 }
 

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

@@ -531,7 +531,7 @@ 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" | "interaction" | "interceptToolCall" | "withJev" | "events">;
+export declare type FauxKayAgentCapabilities = Pick<KayAgentPluginApi, "filesystem" | "network" | "webSession" | "process" | "whiteboard" | "interaction" | "interceptToolCall" | "withJev" | "events" | "time">;
 
 export declare function fauxKayAgentCapabilities(): FauxKayAgentCapabilities;
 
@@ -1159,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
@@ -1388,6 +1396,81 @@ 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" | "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";
@@ -3045,8 +3128,9 @@ 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.
@@ -3204,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. */

package/dist/kay-agent-testing.js

@@ -185,7 +185,13 @@ function fauxKayAgentCapabilities() {
     // Accepts and drops, like the registrations above: the real `publish` never throws, so a
     // rejecting double would fail tests for a reason production never has. A test asserting what
     // its plugin publishes overrides this handle after the spread.
-    events: { publish: () => void 0 }
+    events: { publish: () => void 0 },
+    // A test double has no user-time port, so it answers the zone as unknown — the same contract
+    // the real capability keeps for a zone the host cannot read. A test that exercises a plugin's
+    // zone-of-record path overrides this handle after the spread.
+    time: {
+      snapshot: () => ({ nowMs: 0, zone: "UTC", zoneSource: "utc-fallback" })
+    }
   };
 }
 function defaultTestToolContext() {

package/dist/kay-agent.d.ts

@@ -1620,6 +1620,14 @@ export 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
@@ -1863,6 +1871,81 @@ export 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 const KayPluginManifestV1: z.ZodObject<{
     protocol: z.ZodLiteral<"kay.plugin.v1">;
     id: z.ZodString;
@@ -2188,6 +2271,9 @@ declare const KayPluginManifestV1: z.ZodObject<{
                             kind: z.ZodLiteral<"working-document">;
                         }, z.core.$strict>, z.ZodObject<{
                             kind: z.ZodLiteral<"browser-pane">;
+                        }, z.core.$strict>, z.ZodObject<{
+                            kind: z.ZodLiteral<"page">;
+                            pageId: z.ZodString;
                         }, z.core.$strict>], "kind">;
                         variants: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodObject<{
                             resourceKind: z.ZodString;
@@ -4889,8 +4975,9 @@ export 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.
@@ -5065,6 +5152,18 @@ export 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. */

package/dist/kay-app.d.ts

@@ -3890,7 +3890,8 @@ export declare interface KayAppStorage {
 export declare type KayAppThinkingLevel = "off" | "minimal" | "low" | "medium" | "high" | "xhigh" | "max";
 
 /**
- * `app.time`: host facts about time. Added in SDK 0.12.1: a plugin that calls it declares
+ * `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.
  */
@@ -3923,12 +3924,16 @@ export declare interface KayAppTime {
 }
 
 /**
- * The plugin-facing `kay.app` time contract: the daemon's clock and the time zone the user is in,
+ * 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 `app.time` adds is the daemon's answer
+ * daemon's process and can already read the clock. What the door adds is the daemon's answer
  * for the USER's zone, and a label for the case where that answer is unknown.
+ *
+ * This is a leaf module. It lives beside both target SDKs (rather than inside `kay-app`) so the
+ * `kay.agent` SDK can expose the same door without importing the `kay.app` surface, which pulls
+ * that surface into every agent-facing bundle.
  */
 /** One reading of the daemon's clock and the user's time zone. Each call returns a new object. */
 export declare interface KayAppTimeSnapshot {
@@ -5122,7 +5127,7 @@ declare interface ResolveTokenSuccess {
  * failure.
  */
 /** Provider-neutral factual category for a failed model run. */
-declare type RunFailureReason = "auth" | "budget_exceeded" | "content_blocked" | "context_overflow" | "invalid_request" | "model_unavailable" | "network" | "overloaded" | "quota_exhausted" | "rate_limit" | "safeguard_block" | "seat_unpaid" | "server_error" | "stream_interrupted" | "timeout" | "unknown";
+declare type RunFailureReason = "auth" | "content_blocked" | "context_overflow" | "invalid_request" | "model_unavailable" | "network" | "overloaded" | "quota_exhausted" | "rate_limit" | "safeguard_block" | "seat_unpaid" | "server_error" | "stream_interrupted" | "timeout" | "unknown";
 
 declare type SchemaInput = z.ZodType | JsonSchema;
 
@@ -6388,6 +6393,18 @@ declare interface UriOperationDescription {
     readonly target: string;
     /** Model-authored content; the host flattens, budgets, elides and bounds it. */
     readonly quote?: string;
+    /** Full, render-only detail. Hosts must not turn a rich preview into one-line approval. */
+    readonly preview?: {
+        readonly title: string;
+        readonly description?: string;
+        readonly fields?: readonly {
+            readonly label: string;
+            readonly value: string;
+            readonly oldValue?: string;
+        }[];
+    };
+    /** True only when every displayed fact comes from the input, independent of the executing account. */
+    readonly accountIndependent?: true;
     /** What this description accounts for; the host refuses undeclared input. */
     readonly accounts: {
         /** The payload actually read by the module, after its own decoding. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.2",
+  "version": "0.12.3",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",