@yaklabs-ai/plugin-sdk 0.12.2 → 0.12.4

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.4"
   }
 }
 ```
@@ -131,8 +131,10 @@ Pass the loader's inputs, not a subset — the audit judges what it is given:
   violations Kay itself would not report.
 
 `auditSkillCodegenPairs({ declaredSkills, exportedSkills, packageDir })` is the
-companion check for a bundled-skill plugin. Both are pure — they return
-violations rather than asserting — so any runner works. Both read from disk
+companion check for a bundled-skill plugin. It compares the decoded YAML
+`name` and `description` with the export, so quoting and block scalars are
+supported; body content must match after trimming surrounding whitespace.
+Both return violations rather than asserting, so any runner works. Both read from disk
 and call your own `help()`, so run them in Node, and keep `activate` free of
 side effects: the probe calls it.
 

package/THIRD-PARTY-INVENTORY.json

@@ -1,7 +1,7 @@
 {
   "schemaVersion": 1,
   "package": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.2",
+  "version": "0.12.4",
   "target": "npm",
   "firstPartyLicense": "MIT",
   "bundled": [
@@ -53,6 +53,13 @@
       "source": "https://github.com/colinhacks/zod",
       "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
       "versionRange": "^4.0.0"
+    },
+    {
+      "name": "yaml",
+      "license": "ISC",
+      "source": "https://github.com/eemeli/yaml",
+      "note": "Installed as a consumer dependency; it is not bundled into the staged artifacts.",
+      "versionRange": "^2.9.0"
     }
   ]
 }

package/dist/disclosure.d.ts

@@ -213,7 +213,8 @@ export declare interface AuditPluginDisclosureInput {
  * The codegen-pair equivalence check every bundled-skill plugin hand-rolled (see
  * `plugins/ARCHITECTURE.md` → "Bundled skills", step 4): every exported `PluginSkillDefinition`
  * must have a matching manifest declaration (same `localId`, same `description`), and the
- * declared `SKILL.md` file's frontmatter + body must match the export byte-for-byte.
+ * declared `SKILL.md` file's decoded YAML name and description must match the export.
+ * The body is compared byte-for-byte after trimming surrounding whitespace.
  */
 export declare function auditSkillCodegenPairs(input: AuditSkillCodegenPairsInput): Promise<readonly DisclosureViolation[]>;
 
@@ -1257,6 +1258,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 +1495,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 +3230,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 +3390,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

@@ -1,5 +1,6 @@
 // packages/plugin-sdk/dist/disclosure/disclosure-conformance.js
 import { readFile } from "node:fs/promises";
+import { parse as parseYaml } from "yaml";
 
 // packages/herd-uri/dist/connection.js
 var CONNECTION_SELECTOR_RE = /^([a-zA-Z][a-zA-Z0-9+.-]*:\/\/)@([^/]+)(?:\/(.*))?$/;
@@ -700,24 +701,36 @@ async function auditSkillCodegenPairFile(skill, declaration, packageDir) {
     ];
   }
   const codegenPairMatch = /^---\r?\n([\s\S]*?)\r?\n---\r?\n([\s\S]*)$/.exec(file);
-  const frontmatter = codegenPairMatch?.[1] === void 0 ? void 0 : `${codegenPairMatch[1]}
-`;
+  const yaml = codegenPairMatch?.[1];
+  let frontmatter = {};
+  let parseError;
+  if (yaml !== void 0) {
+    try {
+      const parsed = parseYaml(yaml);
+      if (parsed !== null && typeof parsed === "object" && !Array.isArray(parsed)) {
+        frontmatter = parsed;
+      } else {
+        parseError = "frontmatter must be a YAML mapping";
+      }
+    } catch (error) {
+      parseError = errorMessage(error);
+    }
+  }
+  const parseDetail = parseError === void 0 ? "" : ` Could not parse '${declaration.path}': ${parseError}`;
   const body = codegenPairMatch?.[2];
   const violations = [];
-  if (frontmatter === void 0 || !frontmatter.includes(`name: ${skill.name}
-`)) {
+  if (frontmatter["name"] !== skill.name) {
     violations.push({
       moduleId: skill.name,
       rule: "skill-twin-frontmatter-name-mismatch",
-      detail: `SKILL.md frontmatter does not declare 'name: ${skill.name}'.`
+      detail: `SKILL.md frontmatter name does not match the exported name '${skill.name}'.${parseDetail}`
     });
   }
-  if (frontmatter === void 0 || !frontmatter.includes(`description: ${skill.description}
-`)) {
+  if (frontmatter["description"] !== skill.description) {
     violations.push({
       moduleId: skill.name,
       rule: "skill-twin-frontmatter-description-mismatch",
-      detail: "SKILL.md frontmatter description does not match the exported description."
+      detail: `SKILL.md frontmatter description does not match the exported description.${parseDetail}`
     });
   }
   if (body === void 0 || body.trim() !== skill.content.trim()) {
@@ -806,7 +819,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

@@ -2322,6 +2322,30 @@ export declare interface KayAppEndpoints {
     register(name: string, handler: (payload: unknown) => unknown | Promise<unknown>): void;
 }
 
+/**
+ * The plugin-facing `kay.app` repository contract: what git checkout encloses a folder, read by
+ * the host.
+ *
+ * Ungated and always present, like `app.paths`: a plugin runs in the daemon's process and could
+ * read these files itself. What `app.repos` adds is that the host reads them asynchronously, under
+ * a time limit, and shares one cache with the daemon. A plugin that reads `.git` files with
+ * `node:fs` sync calls blocks the daemon's event loop for as long as each read takes, which on a
+ * protected or unresponsive folder can be a very long time (kay#11575).
+ */
+/** One `[remote "<name>"]` in the repository's common `config`. */
+export declare interface KayAppGitRemote {
+    readonly name: string;
+    /** The `url =` value as written, still usable to connect. */
+    readonly url: string;
+    /**
+     * `url` reduced to a key that is the same however the repository is addressed: no scheme, user
+     * or port, lowercase host, no trailing `.git` (`git@github.com:org/repo.git` and
+     * `https://github.com/org/repo` are both `github.com/org/repo`). Absent when `url` reduces to
+     * nothing. For `owner/repo`, take the last two `/` segments.
+     */
+    readonly identity?: string;
+}
+
 /** A real human carrier projected into the source session's transcript. */
 export declare interface KayAppHumanMessageSessionEvent extends KayAppSessionEventBase {
     readonly type: "human-message";
@@ -2698,6 +2722,13 @@ export declare interface KayAppPluginApi {
      * `Intl` or `process.env.TZ`; see {@link KayAppTime.snapshot}.
      */
     readonly time: KayAppTime;
+    /**
+     * Git facts about any folder (its checkout, primary checkout, common dir, remotes, and git's
+     * linked-worktree registry), read by the host asynchronously and under a time limit. Always
+     * present and ungated, like {@link paths}. Use it instead of reading `.git` files with `node:fs`,
+     * which blocks the daemon; see {@link KayAppRepos}.
+     */
+    readonly repos: KayAppRepos;
     /**
      * Read/arrange access to the live desktop workspace. Present whenever the host has a workspace
      * (a headless daemon may not); absence is a host fact, never a grant signal. Reading the snapshot
@@ -2872,6 +2903,102 @@ export declare interface KayAppRegisterUriModuleOptions {
     readonly scope: "app";
 }
 
+/** The git checkout that encloses a folder. Paths are absolute and not resolved through symlinks. */
+export declare interface KayAppRepoFacts {
+    /** The directory holding the `.git` entry: the nearest checkout at or above the folder. */
+    readonly repoRoot: string;
+    /**
+     * This checkout's own git directory: `<repoRoot>/.git`, or the target of a `.git` pointer file
+     * (a linked worktree or a submodule). `null` when the pointer could not be read.
+     */
+    readonly gitDir: string | null;
+    /**
+     * The git directory every worktree of the repository shares, as `git rev-parse
+     * --git-common-dir` names it; for a submodule, its own `.git/modules/<name>`. `null` when the
+     * host cannot place it (an unreadable pointer or `commondir` file).
+     */
+    readonly commonDir: string | null;
+    /**
+     * The primary checkout that owns a linked worktree; `repoRoot` itself for an ordinary
+     * checkout, a submodule, or a worktree of a bare repository. Every worktree of one repository
+     * shares this value.
+     */
+    readonly primaryCheckoutRoot: string;
+    /** A stable name for the repository: the primary checkout's directory name. */
+    readonly displayName: string;
+    /** Every remote in the common `config`, in file order. Empty when the config is unreadable. */
+    readonly remotes: readonly KayAppGitRemote[];
+    /**
+     * The `origin` remote. `absent` means the config was read and has no origin; `unavailable`
+     * means the config could not be read, which is not the same answer and is usually temporary.
+     */
+    readonly origin: {
+        readonly kind: "origin";
+        readonly url: string;
+        readonly identity: string;
+    } | {
+        readonly kind: "absent";
+    } | {
+        readonly kind: "unavailable";
+        readonly detail: string;
+    };
+}
+
+export declare interface KayAppRepoReadOptions {
+    /**
+     * How old a cached answer may be, in milliseconds. `0` asks the host to read again; `Infinity`
+     * accepts any cached answer. Default 5000.
+     */
+    readonly maxAgeMs?: number;
+}
+
+/** What the host knows about one folder. */
+export declare type KayAppRepoResolution = {
+    readonly kind: "resolved";
+    /** The folder asked about, as an absolute path. */
+    readonly folder: string;
+    /**
+     * Whether the folder itself exists. A folder that is gone still reports the checkout that
+     * encloses where it was, so a deleted subdirectory keeps its repository.
+     */
+    readonly folderExists: boolean;
+    /** `null` when no checkout encloses the folder. */
+    readonly repo: KayAppRepoFacts | null;
+} | {
+    /**
+     * The host could not answer: `timeout` when the reads took longer than the host's time limit
+     * (the folder may be on an unresponsive drive), `error` when they failed unexpectedly. Not
+     * cached, so asking again later may succeed. Treat it as "do not know", never as "no repo".
+     */
+    readonly kind: "unknown";
+    readonly folder: string;
+    readonly reason: "timeout" | "error";
+    readonly detail: string;
+};
+
+/**
+ * `app.repos`: git facts about folders, read by the host. Added in SDK 0.12.4: a plugin that calls
+ * it declares `compatibility.sdk` `^0.12.4`, so an older Bonsai refuses a directory or repository
+ * plugin at load instead of the call failing.
+ *
+ * Both members never reject and do not use `this`, so they are safe to destructure. Call them
+ * where you need the answer, not inside `activate()`.
+ */
+export declare interface KayAppRepos {
+    /**
+     * The checkout that encloses `folder` (an absolute path), or why the host could not tell. A
+     * relative path answers `unknown`.
+     */
+    readonly resolve: (folder: string, options?: KayAppRepoReadOptions) => Promise<KayAppRepoResolution>;
+    /**
+     * The working directories of the linked worktrees git has registered under `commonDir`
+     * (`<commonDir>/worktrees/<name>/gitdir`), including ones whose directory has since been
+     * deleted. Empty when there are none; `undefined` when the registry or one of its entries could
+     * not be read, or not in time. `undefined` is not cached; treat it as "do not know".
+     */
+    readonly linkedWorktrees: (commonDir: string, options?: KayAppRepoReadOptions) => Promise<readonly string[] | undefined>;
+}
+
 /** What the plugin is asking for, and what it intends to do with it. */
 export declare interface KayAppResolveCredentialRequest {
     /** An auth service this plugin's own manifest declares, by its LOCAL id. */
@@ -3890,7 +4017,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 +4051,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 +5254,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 +6520,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.4",
   "description": "The Kay plugin SDK — types and helpers for authoring a Kay directory plugin.",
   "author": "YakLabs",
   "type": "module",
@@ -51,7 +51,8 @@
     "skills"
   ],
   "dependencies": {
-    "zod": "^4.0.0"
+    "zod": "^4.0.0",
+    "yaml": "^2.9.0"
   },
   "publishConfig": {
     "registry": "https://registry.npmjs.org",

package/skills/directory-plugin-authoring/SKILL.md

@@ -55,6 +55,31 @@ and symlinking `node_modules/@kay` into the copy does not rescue it either: pnpm
 layout does not expose workspace packages that way. The scaffold exists precisely so this
 cannot happen.
 
+## Check the manifest before you wait for a load
+
+```
+pnpm plugin:check ~/.kay/plugins/widgets
+```
+
+Run from the root of a Kay checkout, against the plugin directory. It runs the daemon's OWN
+manifest schema and contract resolver (imported from `@kay/plugin-protocol`, not re-implemented),
+so it answers "would Kay accept this manifest?" in about a second instead of after a load cycle.
+Run it after every manifest edit, and before concluding a plugin is broken for some deeper reason.
+
+It prints the resolved global contribution ids, exits non-zero when the plugin would be refused,
+and separates the two outcomes that look alike from outside:
+
+- **Refused outright** — schema-invalid manifest, a reserved `kay.*` / `herd.*` id, a declared
+  path escaping the plugin directory, or contributions that do not resolve. Every contribution
+  shares ONE flat `<namespace>.<localId>` space ACROSS kinds, so a tool and an endpoint both
+  called `inspect` collide and the whole plugin is refused (#8936).
+- **Loads, minus something** — a retired `compatibility` / `permissions.byTarget` key the parser
+  strips silently, a `toolName` that is not the namespace-derived name (that tool is excluded and
+  nothing tells the user), a missing entrypoint or skill file.
+
+It reads the manifest only. A clean verdict says nothing about `activate()` throwing, the
+disclosure audit, or an id another installed plugin already claims.
+
 ## The SDK resolution contract
 
 - Plugin source imports `@kay/plugin-sdk/<subpath>` as a **bare specifier**
@@ -123,8 +148,10 @@ edited.
    IS a git repository: a version is a commit, and a directory without git backing fails to
    load (the plugin's row says exactly that, with the fix). So after writing the files, commit
    them: `git init && git add -A && git commit -m "adopt plugin"` inside the plugin directory.
-   The daemon watches the root, so the plugin appears by itself within a couple of seconds, no
-   verb called and no restart; the source refresh verb forces the walk if you want it now.
+   The daemon watches the root and, under the watch, checks each plugin's Git HEAD every 5
+   seconds, so it notices the plugin by itself within about 10 seconds even when file events
+   are not arriving: no verb called and no restart. The source refresh verb forces the walk if
+   you want it now.
 
    The root is `<home>/.kay/plugins`, and **`<home>` is the running instance's home**: a dev
    app launched against its own state root has its own plugins root, not your real
@@ -144,9 +171,13 @@ list` names the exact local root — because writing into the wrong one produces
    commit** identifies the serving snapshot. Try new tools in a fresh session;
    an existing session may still hold its previous generation.
 
-   A failed committed update keeps the last working revision and shows the load
-   diagnostic. Fix and commit the repair. Explicit source refresh retries discovery
-   or a failed read; it never activates uncommitted files. Keep runtime data in
+   Kay notices a commit within about 10 seconds even with no file events, and acquiring it may
+   take up to 30 seconds more. A **Running commit** still behind `git rev-parse --short HEAD` a
+   minute later, with a diagnostic on the plugin's row, is a failed read: fix what it names
+   instead of refreshing and waiting. Without a diagnostic, refresh the `local` source. A failed committed
+   update keeps the last working revision and shows that diagnostic. Fix and commit the
+   repair. Explicit source refresh skips the wait and retries a failed read; a commit
+   does not normally need it, and it never activates uncommitted files. Keep runtime data in
    host-owned plugin storage, not beside the snapshot's source files.
 
 4. **Grant what the manifest asks for, or activation is refused.** Anything declared under
@@ -177,9 +208,10 @@ list` names the exact local root — because writing into the wrong one produces
 The commit is the activation boundary, so run these against the working tree first. Each catches
 a failure class the load would otherwise be the first thing to surface:
 
-1. **Validate `kay-plugin.json` against `KayPluginManifestV1`** (from `@kay/plugin-protocol`),
-   not just "it is valid JSON" — that schema is the gate the scan actually runs. Check every
-   declared target's endpoints are namespaced correctly.
+1. **Run `pnpm plugin:check <dir>`** from a Kay checkout. It validates `kay-plugin.json` against
+   `KayPluginManifestV1` and resolves its contributions with the daemon's own resolver (both from
+   `@kay/plugin-protocol`), not just "it is valid JSON": that schema and resolver are the gate the
+   scan actually runs. A non-zero exit means the plugin would be refused.
 2. **Run the disclosure audit yourself**: `auditPluginDisclosure` from `@kay/plugin-sdk/disclosure`.
    It is not redundant with typecheck. A plugin shipped a `search` verb with no `verbDocs` entry
    that typechecked clean and would have failed the whole `kay.agent` target.
@@ -229,6 +261,8 @@ on the plugin's row (or on the plugin source's row, when the whole source found
 - **The disclosure audit is fail-closed** and runs on every directory plugin; a violation fails
   the whole `kay.agent` target. Run `auditPluginDisclosure` yourself before committing, per the
   pre-commit checks above.
+- **Before any of the above, run `pnpm plugin:check <dir>`.** A manifest the daemon cannot
+  resolve produces a plugin that never appears, and the check names the reason without a load.
 
 ## Declaring a scheduled workflow