@yaklabs-ai/plugin-sdk 0.12.3 → 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.3"
+    "@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.3",
+  "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[]>;
 

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()) {

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. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@yaklabs-ai/plugin-sdk",
-  "version": "0.12.3",
+  "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