@yaklabs-ai/plugin-sdk 0.8.4

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 YakLabs
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/README.md

@@ -0,0 +1,205 @@
+# @yaklabs-ai/plugin-sdk
+
+The SDK for authoring a **Kay directory plugin** — a plugin you write in a
+repository and add to Kay through an approved plugin repository source.
+
+Published to the public npm registry under the MIT licence.
+
+## Install
+
+There is no registry configuration, no `.npmrc`, and no access token. Depend on
+it under the name your plugin code actually imports:
+
+```json
+{
+  "dependencies": {
+    "@kay/plugin-sdk": "npm:@yaklabs-ai/plugin-sdk@^0.8.4"
+  }
+}
+```
+
+**The alias is not cosmetic.** The package is published as
+`@yaklabs-ai/plugin-sdk`, but Kay's daemon resolves the specifier
+`@kay/plugin-sdk` when it loads your entrypoint, so that is the name your source
+must import. The alias installs the published package at
+`node_modules/@kay/plugin-sdk`, satisfying both.
+
+<details>
+<summary>Installing a release older than 0.8.0</summary>
+
+Releases before 0.8.0 shipped only to GitHub Packages, where access is Yak Labs
+organization membership. To install one, point the `@yaklabs-ai` scope at that
+registry in an `.npmrc` beside your `package.json`:
+
+```
+@yaklabs-ai:registry=https://npm.pkg.github.com
+//npm.pkg.github.com/:_authToken=${GITHUB_TOKEN}
+```
+
+`GITHUB_TOKEN` must be a **classic** personal access token with the
+`read:packages` scope — GitHub Packages' npm registry does not accept
+fine-grained tokens. Prefer upgrading instead; the public releases need none of
+this.
+
+</details>
+
+## Use
+
+Working with an agent? This package ships the skill that teaches one the whole
+authoring flow — scaffold, the SDK resolution contract, the reload loop, and
+the diagnostics to read when a plugin does not load. Point your agent at
+`node_modules/@kay/plugin-sdk/skills/directory-plugin-authoring/SKILL.md`
+before it writes any plugin code.
+
+```ts
+import {
+  defineTool,
+  textResult,
+  toolParameters,
+  z,
+  type KayAgentActivate,
+} from "@kay/plugin-sdk/kay-agent";
+
+const greet = defineTool({
+  name: "widgets_greet",
+  label: "Greet",
+  description: "Greet someone by name.",
+  parameters: toolParameters(z.object({ name: z.string() })),
+  async execute(_toolCallId, params) {
+    return textResult(`Hello, ${params.name}!`, undefined);
+  },
+});
+
+const activate: KayAgentActivate = (api) => {
+  api.registerTool(greet);
+};
+
+export default activate;
+```
+
+## Entrypoints
+
+| Import                              | What it gives you                                                          |
+| ----------------------------------- | -------------------------------------------------------------------------- |
+| `@kay/plugin-sdk/kay-agent`         | Tools, URI modules, search providers, auth — the per-session agent surface |
+| `@kay/plugin-sdk/kay-app`           | App-lifetime surface: storage, endpoints, app-scoped URI modules           |
+| `@kay/plugin-sdk/kay-agent/testing` | `invokeToolForTest`, `fauxAuthContext` — for your own `node --test` runs   |
+| `@kay/plugin-sdk/disclosure`        | The conformance audit Kay gates your plugin with — run it before you ship  |
+
+`kay-agent/host` is intentionally not published; it is Kay's own loading
+machinery, not an authoring API.
+
+## Check yourself against the gate that can reject you
+
+Kay runs `auditPluginDisclosure` against your `kay.agent` target **at load,
+fail-closed**: one violation and the whole target fails — no tools, no URI
+modules, no skills. It is the same function this entrypoint exports, so the
+run below is the run Kay does.
+
+```ts
+import {
+  auditPluginDisclosure,
+  collectUriModulesFromKayAgentActivate,
+} from "@kay/plugin-sdk/disclosure";
+
+import activate from "../src/kay-agent.ts";
+import manifest from "../kay-plugin.json" with { type: "json" };
+
+const violations = await auditPluginDisclosure({
+  // Recover what activate() ACTUALLY registers — the same input the loader audits.
+  modules: collectUriModulesFromKayAgentActivate(activate),
+  declaredSkills: manifest.targets?.kay?.agent?.contributes?.skills ?? [],
+});
+if (violations.length > 0) throw new Error(JSON.stringify(violations, null, 2));
+```
+
+(Reading the manifest needs `"resolveJsonModule": true` in your `tsconfig.json`
+— `pnpm create-plugin` sets it. Restating your skills inline instead is the
+thing that drifts.)
+
+Pass the loader's inputs, not a subset — the audit judges what it is given:
+
+- `modules` — from the probe, not a hand-assembled list. A module your
+  `activate` registers conditionally is exactly the one a hand-written list
+  forgets.
+- `declaredSkills` — your manifest's
+  `targets.kay.agent.contributes.skills` (`{ localId, description }`). Omit
+  them and the module ↔ skill cross-link rules cannot fire.
+- `commandBoundSkillIds` — the `localId` of every skill bound to a declared
+  command (`contributes.commands[].handler.kind === "skill"`). Omit it when
+  you have such commands and you will see `skill-link-missing-scheme`
+  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
+and call your own `help()`, so run them in Node, and keep `activate` free of
+side effects: the probe calls it.
+
+`PLUGIN_DISCLOSURE_CONTRACT` names the floor this SDK enforces. Kay's load
+failure names the floor **it** enforces. Different numbers mean the rules
+moved, not your code — update this package and re-run.
+
+A newer floor always has a release: every change to the rule set publishes a
+version of this package as it lands, so "update and re-run" is never blocked on
+someone remembering to cut one. If the numbers differ, a newer version exists.
+
+## What this package is, and is not, at runtime
+
+Installing this SDK gives you **types, editor completion, and a runtime you can
+execute in your own tests**. It is not what runs inside Kay.
+
+When the daemon loads your plugin, chord bundles its declared target and keeps
+`@kay/plugin-sdk/*` as a host external. Those imports resolve to the SDK
+**bundled with the Kay app**. The host's copy always wins. That is deliberate —
+one implementation, the one the daemon is built against — but it has a
+consequence worth stating plainly:
+
+> If your installed SDK is newer than your Kay app, code that typechecks against
+> a newly-added API can still fail at load time, because the running host does
+> not have it.
+
+Importing an entire subpath the host does not know about fails loudly and
+specifically (a `target-load` diagnostic naming the subpath, shown on the
+Plugins page). A _symbol_ that exists here but not in the host's older copy is
+not caught that way. Keep the SDK version in step with the Kay app you run.
+
+The same skew applies to the conformance floor, and in the direction that
+bites: if your Kay app is **newer** than this package, it can enforce a rule
+your copy of the audit does not know about, so a green local run is not a
+promise the host will load you. That is why the load failure names its
+contract number — compare it against `PLUGIN_DISCLOSURE_CONTRACT` here, and if
+they differ, update before you debug your code.
+
+## Install the plugin in Kay
+
+The fastest route is the local plugin root. Put the plugin directory in
+`~/.kay/plugins/<your-plugin>/` and turn it on in **Settings → Plugins**. That
+root is already consented, so there is no repository to stage and no Trust step,
+and your edits load without restarting Kay.
+
+To share a plugin with someone who does not have your files, commit it to a Git
+repository and have them add it under **Settings → Plugins → Plugin sources →
+Add repository source**. They stage the source, Trust it, and enable the plugin;
+Trust and activation are separate gates.
+
+A plugin executes as a trusted in-process Node module with the daemon's own
+authority. **The SDK does not provide a sandbox.** Putting code in the local
+plugin root is itself the decision to run it, with no prompt in between — so
+treat that directory exactly as carefully as you would Trust an unfamiliar
+repository.
+
+## Requirements
+
+Use Node.js 24 with an ESM package (`"type": "module"`) and ordinary
+TypeScript. For standalone authoring and typechecking, install `typescript`
+and `@types/node@^24`, and run `tsc --noEmit`; the scaffold's machine-local
+checkout script is not the standalone path. The SDK's `kay-app` declarations
+use `node:sqlite`, which TypeScript cannot resolve without the Node 24
+typings.
+
+When Kay loads your plugin, chord bundles the declared entrypoint and its
+relative imports. Multi-file entrypoints are supported, and TypeScript syntax
+that native stripping cannot execute, such as enums, namespaces, constructor
+parameter properties, and decorators, is compiled into the bundle. The host
+SDK remains external and is supplied by the running Kay app.

package/THIRD-PARTY-INVENTORY.json

@@ -0,0 +1,65 @@
+{
+  "schemaVersion": 1,
+  "package": "@yaklabs-ai/plugin-sdk",
+  "version": "0.8.4",
+  "target": "npm",
+  "firstPartyLicense": "MIT",
+  "bundled": [
+    {
+      "name": "@earendil-works/pi-agent-core",
+      "version": "0.87.0",
+      "license": "MIT",
+      "copyright": "Copyright (c) 2025 Mario Zechner",
+      "source": "https://github.com/earendil-works/pi/tree/v0.87.0/packages/agent",
+      "licenseSource": "https://github.com/earendil-works/pi/blob/v0.87.0/LICENSE",
+      "upstreamCommit": "16787ad5b2dc748047f314ca1bfe7708f30f54f3",
+      "noticeFile": "THIRD-PARTY-NOTICES.md"
+    },
+    {
+      "name": "@earendil-works/pi-ai",
+      "version": "0.87.1",
+      "license": "MIT",
+      "copyright": "Copyright (c) 2025 Mario Zechner",
+      "source": "https://github.com/earendil-works/pi/tree/v0.87.1/packages/ai",
+      "licenseSource": "https://github.com/earendil-works/pi/blob/v0.87.1/LICENSE",
+      "upstreamCommit": "f07218c4d4bbc12bef056a7058c3dd49dfe41abe",
+      "noticeFile": "THIRD-PARTY-NOTICES.md"
+    },
+    {
+      "name": "@earendil-works/chord",
+      "version": "0.87.0",
+      "license": "MIT",
+      "copyright": "Copyright (c) 2025 Mario Zechner",
+      "source": "https://github.com/earendil-works/pi/tree/v0.87.0/packages/chord",
+      "licenseSource": "https://github.com/earendil-works/pi/blob/v0.87.0/LICENSE",
+      "upstreamCommit": "16787ad5b2dc748047f314ca1bfe7708f30f54f3",
+      "noticeFile": "THIRD-PARTY-NOTICES.md"
+    },
+    {
+      "name": "typebox",
+      "version": "1.3.27",
+      "license": "MIT",
+      "copyright": "Copyright (c) 2017-2026 Haydn Paterson",
+      "source": "https://github.com/sinclairzx81/typebox/tree/1.3.27",
+      "licenseSource": "https://github.com/sinclairzx81/typebox/blob/1.3.27/license",
+      "upstreamCommit": "ffe23ba614322bf0dcb846ceaf7c1bbc7ef0bba6",
+      "noticeFile": "THIRD-PARTY-NOTICES.md"
+    }
+  ],
+  "external": [
+    {
+      "name": "zod",
+      "license": "MIT",
+      "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": "@typesafe-ai/sdk",
+      "license": "MIT",
+      "source": "https://github.com/typesafe-ai/typesafe-sdk-js",
+      "note": "Types-only: the SDK re-exports the vendor's Jev client types, and the vendor's nominal class must stay a single declaration across entrypoints. Installed as a consumer dependency; a plugin never declares it itself.",
+      "versionRange": "0.6.0"
+    }
+  ]
+}

package/THIRD-PARTY-NOTICES.md

@@ -0,0 +1,103 @@
+# Third-party notices
+
+This package bundles 4 first-party-selected component(s). The notices below are reproduced verbatim from each component's upstream MIT license source.
+
+## @earendil-works/pi-agent-core@0.87.0
+
+- Source: https://github.com/earendil-works/pi/tree/v0.87.0/packages/agent
+- License source: https://github.com/earendil-works/pi/blob/v0.87.0/LICENSE
+- Upstream commit: 16787ad5b2dc748047f314ca1bfe7708f30f54f3
+
+## @earendil-works/chord@0.87.0
+
+- Source: https://github.com/earendil-works/pi/tree/v0.87.0/packages/chord
+- License source: https://github.com/earendil-works/pi/blob/v0.87.0/LICENSE
+- Upstream commit: 16787ad5b2dc748047f314ca1bfe7708f30f54f3
+
+License text for the component(s) above, verbatim from the license source:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## @earendil-works/pi-ai@0.87.1
+
+- Source: https://github.com/earendil-works/pi/tree/v0.87.1/packages/ai
+- License source: https://github.com/earendil-works/pi/blob/v0.87.1/LICENSE
+- Upstream commit: f07218c4d4bbc12bef056a7058c3dd49dfe41abe
+
+License text for the component(s) above, verbatim from the license source:
+
+MIT License
+
+Copyright (c) 2025 Mario Zechner
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+
+## typebox@1.3.27
+
+- Source: https://github.com/sinclairzx81/typebox/tree/1.3.27
+- License source: https://github.com/sinclairzx81/typebox/blob/1.3.27/license
+- Upstream commit: ffe23ba614322bf0dcb846ceaf7c1bbc7ef0bba6
+
+License text for the component(s) above, verbatim from the license source:
+
+TypeBox
+
+The MIT License (MIT)
+
+Copyright (c) 2017-2026 Haydn Paterson
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in
+all copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN
+THE SOFTWARE.
+
+The package's own code is licensed under the MIT License in `LICENSE`.