@ycodium-ai/plugin-api 0.1.0

package/README.md

@@ -0,0 +1,106 @@
+# @ycodium-ai/plugin-api
+
+Types and `definePlugin` for writing Ycodium plugins. Zero runtime dependencies.
+
+A plugin is a normal npm package that a Ycodium machine loads into its server. It can add
+agent tools, react to things that happen, contribute a settings card or a page, and keep its
+own state across restarts.
+
+## Install
+
+```
+npm install --save-dev @ycodium-ai/plugin-api
+```
+
+This package is types only at build time — nothing of it ends up in your bundle.
+
+## A plugin is an npm package
+
+Declare the entry file under `ycodium.plugin`:
+
+```json
+{
+  "name": "my-ycodium-plugin",
+  "version": "0.1.0",
+  "type": "module",
+  "keywords": ["ycodium-plugin"],
+  "files": ["dist"],
+  "ycodium": {
+    "plugin": "./dist/index.js",
+    "displayName": "My plugin",
+    "description": "One line about what it does.",
+    "permissions": []
+  }
+}
+```
+
+And export the definition:
+
+```ts
+import { definePlugin, PLUGIN_API_VERSION } from "@ycodium-ai/plugin-api";
+
+export default definePlugin({
+  id: "my-plugin",
+  apiVersion: PLUGIN_API_VERSION,
+  activate: (ctx) => {
+    ctx.log.info("hello");
+
+    ctx.reactor({
+      name: "greet",
+      events: ["thread.created"],
+      handle: async (event) => {
+        ctx.log.info("a thread appeared", { threadId: event.aggregateId });
+      },
+    });
+
+    ctx.onDispose(() => {
+      // Release anything you opened. The host calls this on unload and on upgrade.
+    });
+  },
+});
+```
+
+Publish it to npmjs.com under your own name. There is no submission and no review. Users
+install it with:
+
+```
+ycodium plugin add my-ycodium-plugin
+```
+
+## Bundle your entry file
+
+The host loads your entry by absolute path, from a directory inside the user's Ycodium home
+— not inside your package's dependency tree. A bare `import` at runtime will not resolve
+there.
+
+**Bundle your entry into one ESM file with no runtime imports.** Types from this package are
+compile-time only and erase during bundling, so importing it for types is fine.
+
+## Permissions
+
+Anything that reaches outside the plugin is declared in `ycodium.permissions` and shown to
+the user before they install. Reading files under a prefix, spawning a named program,
+reading credentials — each is a separate declaration. Declare nothing you do not use: the
+list is the first thing a user reads about your plugin.
+
+## Being found
+
+Add `ycodium-plugin` to your `keywords`:
+
+```
+npm search keywords:ycodium-plugin
+```
+
+Ycodium's plugin settings search the same way, so a published package with that keyword
+shows up there without anyone registering it.
+
+## THERE WILL BE COMPATIBILITY-BREAKING CHANGES
+
+`PLUGIN_API_VERSION` is checked for **exact equality**. The current API is 2. Plugins targeting
+API 1 are refused before activation. API 2 replaces the Teams-specific host methods with generic
+execution ownership, command receipts, notifications, and plugin contributions. Update plugins
+against the current types and republish; there is no compatibility layer.
+
+## License
+
+UNLICENSED.