nodmix 2026.5.25

package/docs/plugins/building-plugins.md

@@ -0,0 +1,330 @@
+---
+summary: "Create your first Nodmix plugin in minutes"
+title: "Building plugins"
+sidebarTitle: "Getting Started"
+doc-schema-version: 1
+read_when:
+  - You want to create a new Nodmix plugin
+  - You need a quick-start for plugin development
+  - You are choosing between channel, provider, CLI backend, tool, or hook docs
+---
+
+Plugins extend Nodmix without changing core. A plugin can add a messaging
+channel, model provider, local CLI backend, agent tool, hook, media provider,
+or another plugin-owned capability.
+
+You do not need to add an external plugin to the Nodmix repository. Publish
+the package to [ClawHub](/clawhub) and users install it with:
+
+```bash
+nodmix plugins install clawhub:<package-name>
+```
+
+Bare package specs still install from npm during the launch cutover. Use the
+`clawhub:` prefix when you want ClawHub resolution.
+
+## Requirements
+
+- Use Node 22.19 or newer and a package manager such as `npm` or `pnpm`.
+- Be familiar with TypeScript ESM modules.
+- For in-repo bundled plugin work, clone the repository and run `pnpm install`.
+  Source-checkout plugin development is pnpm-only because Nodmix loads bundled
+  plugins from `extensions/*` workspace packages.
+
+## Choose the plugin shape
+
+<CardGroup cols={2}>
+  <Card title="Channel plugin" icon="messages-square" href="/plugins/sdk-channel-plugins">
+    Connect Nodmix to a messaging platform.
+  </Card>
+  <Card title="Provider plugin" icon="cpu" href="/plugins/sdk-provider-plugins">
+    Add a model, media, search, fetch, speech, or realtime provider.
+  </Card>
+  <Card title="CLI backend plugin" icon="terminal" href="/plugins/cli-backend-plugins">
+    Run a local AI CLI through Nodmix model fallback.
+  </Card>
+  <Card title="Tool plugin" icon="wrench" href="/plugins/tool-plugins">
+    Register agent tools.
+  </Card>
+</CardGroup>
+
+## Quickstart
+
+Build a minimal tool plugin by registering one required agent tool. This is the
+shortest useful plugin shape and shows the package, manifest, entry point, and
+local proof.
+
+<Steps>
+  <Step title="Create package metadata">
+    <CodeGroup>
+
+```json package.json
+{
+  "name": "@myorg/nodmix-my-plugin",
+  "version": "1.0.0",
+  "type": "module",
+  "nodmix": {
+    "extensions": ["./index.ts"],
+    "compat": {
+      "pluginApi": ">=2026.3.24-beta.2",
+      "minGatewayVersion": "2026.3.24-beta.2"
+    },
+    "build": {
+      "nodmixVersion": "2026.3.24-beta.2",
+      "pluginSdkVersion": "2026.3.24-beta.2"
+    }
+  }
+}
+```
+
+```json nodmix.plugin.json
+{
+  "id": "my-plugin",
+  "name": "My Plugin",
+  "description": "Adds a custom tool to Nodmix",
+  "contracts": {
+    "tools": ["my_tool"]
+  },
+  "activation": {
+    "onStartup": true
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false
+  }
+}
+```
+
+    </CodeGroup>
+
+    Published external plugins should point runtime entries at built JavaScript
+    files. See [SDK entry points](/plugins/sdk-entrypoints) for the full entry
+    point contract.
+
+    Every plugin needs a manifest, even when it has no config. Runtime tools
+    must appear in `contracts.tools` so Nodmix can discover ownership without
+    eagerly loading every plugin runtime. Set `activation.onStartup`
+    intentionally. This example starts on Gateway startup.
+
+    For every manifest field, see [Plugin manifest](/plugins/manifest).
+
+  </Step>
+
+  <Step title="Register the tool">
+    ```typescript index.ts
+    import { Type } from "typebox";
+    import { definePluginEntry } from "nodmix/plugin-sdk/plugin-entry";
+
+    export default definePluginEntry({
+      id: "my-plugin",
+      name: "My Plugin",
+      description: "Adds a custom tool to Nodmix",
+      register(api) {
+        api.registerTool({
+          name: "my_tool",
+          description: "Echo one input value",
+          parameters: Type.Object({ input: Type.String() }),
+          async execute(_id, params) {
+            return {
+              content: [{ type: "text", text: `Got: ${params.input}` }],
+            };
+          },
+        });
+      },
+    });
+    ```
+
+    Use `definePluginEntry` for non-channel plugins. Channel plugins use
+    `defineChannelPluginEntry`.
+
+  </Step>
+
+  <Step title="Test the runtime">
+    For an installed or external plugin, inspect the loaded runtime:
+
+    ```bash
+    nodmix plugins inspect my-plugin --runtime --json
+    ```
+
+    If the plugin registers a CLI command, run that command too. For example,
+    a demo command should have an execution proof such as
+    `nodmix demo-plugin ping`.
+
+    For a bundled plugin in this repository, Nodmix discovers source-checkout
+    plugin packages from the `extensions/*` workspace. Run the closest targeted
+    test:
+
+    ```bash
+    pnpm test -- extensions/my-plugin/
+    pnpm check
+    ```
+
+  </Step>
+
+  <Step title="Publish">
+    Validate the package before publishing:
+
+    ```bash
+    clawhub package publish your-org/your-plugin --dry-run
+    clawhub package publish your-org/your-plugin
+    ```
+
+    The canonical ClawHub snippets live in `docs/snippets/plugin-publish/`.
+
+  </Step>
+
+  <Step title="Install">
+    Install the published package through ClawHub:
+
+    ```bash
+    nodmix plugins install clawhub:your-org/your-plugin
+    ```
+
+  </Step>
+</Steps>
+
+<a id="registering-agent-tools"></a>
+
+## Registering tools
+
+Tools can be required or optional. Required tools are always available when the
+plugin is enabled. Optional tools require user opt-in.
+
+```typescript
+register(api) {
+  api.registerTool(
+    {
+      name: "workflow_tool",
+      description: "Run a workflow",
+      parameters: Type.Object({ pipeline: Type.String() }),
+      async execute(_id, params) {
+        return { content: [{ type: "text", text: params.pipeline }] };
+      },
+    },
+    { optional: true },
+  );
+}
+```
+
+Every tool registered with `api.registerTool(...)` must also be declared in the
+plugin manifest:
+
+```json
+{
+  "contracts": {
+    "tools": ["workflow_tool"]
+  },
+  "toolMetadata": {
+    "workflow_tool": {
+      "optional": true
+    }
+  }
+}
+```
+
+Users opt in with `tools.allow`:
+
+```json5
+{
+  tools: { allow: ["workflow_tool"] }, // or ["my-plugin"] for all tools from one plugin
+}
+```
+
+Use optional tools for side effects, unusual binaries, or capabilities that
+should not be exposed by default. Tool names must not conflict with core tools;
+conflicts are skipped and reported in plugin diagnostics. Malformed
+registrations, including tool descriptors without `parameters`, are skipped and
+reported the same way. Registered tools are typed functions the model can call
+after policy and allowlist checks pass.
+
+Tool factories receive a runtime-supplied context object. Use `ctx.activeModel`
+when a tool needs to log, display, or adapt to the active model for the current
+turn. The object can include `provider`, `modelId`, and `modelRef`. Treat it as
+informational runtime metadata, not as a security boundary against the local
+operator, installed plugin code, or a modified Nodmix runtime. Sensitive local
+tools should still require an explicit plugin or operator opt-in and fail closed
+when active-model metadata is missing or unsuitable.
+
+The manifest declares ownership and discovery; execution still calls the live
+registered tool implementation. Keep `toolMetadata.<tool>.optional: true`
+aligned with `api.registerTool(..., { optional: true })` so Nodmix can avoid
+loading that plugin runtime until the tool is explicitly allowlisted.
+
+## Import conventions
+
+Import from focused SDK subpaths:
+
+```typescript
+import { definePluginEntry } from "nodmix/plugin-sdk/plugin-entry";
+import { createPluginRuntimeStore } from "nodmix/plugin-sdk/runtime-store";
+```
+
+Do not import from the deprecated root barrel:
+
+```typescript
+import { definePluginEntry } from "nodmix/plugin-sdk";
+```
+
+Within your plugin package, use local barrel files such as `api.ts` and
+`runtime-api.ts` for internal imports. Do not import your own plugin through an
+SDK path. Provider-specific helpers should stay in the provider package unless
+the seam is truly generic.
+
+Custom Gateway RPC methods are an advanced entry point. Keep them on a
+plugin-specific prefix; core admin namespaces such as `config.*`,
+`exec.approvals.*`, `operator.admin.*`, `wizard.*`, and `update.*` stay reserved
+and resolve to `operator.admin`. The
+`nodmix/plugin-sdk/gateway-method-runtime` bridge is reserved for plugin HTTP
+routes that declare `contracts.gatewayMethodDispatch: ["authenticated-request"]`.
+
+For the full import map, see [Plugin SDK overview](/plugins/sdk-overview).
+
+## Pre-submission checklist
+
+<Check>**package.json** has correct `nodmix` metadata</Check>
+<Check>**nodmix.plugin.json** manifest is present and valid</Check>
+<Check>Entry point uses `defineChannelPluginEntry` or `definePluginEntry`</Check>
+<Check>All imports use focused `plugin-sdk/<subpath>` paths</Check>
+<Check>Internal imports use local modules, not SDK self-imports</Check>
+<Check>Tests pass (`pnpm test -- <bundled-plugin-root>/my-plugin/`)</Check>
+<Check>`pnpm check` passes (in-repo plugins)</Check>
+
+## Test against beta releases
+
+1. Watch for GitHub release tags on [nodmix/nodmix](https://github.com/nodmix/nodmix/releases) and subscribe via `Watch` > `Releases`. Beta tags look like `v2026.3.N-beta.1`. You can also turn on notifications for the official Nodmix X account [@nodmix](https://x.com/nodmix) for release announcements.
+2. Test your plugin against the beta tag as soon as it appears. The window before stable is typically only a few hours.
+3. Post in your plugin's thread in the `plugin-forum` Discord channel after testing with either `all good` or what broke. If you do not have a thread yet, create one.
+4. If something breaks, open or update an issue titled `Beta blocker: <plugin-name> - <summary>` and apply the `beta-blocker` label. Put the issue link in your thread.
+5. Open a PR to `main` titled `fix(<plugin-id>): beta blocker - <summary>` and link the issue in both the PR and your Discord thread. Contributors cannot label PRs, so the title is the PR-side signal for maintainers and automation. Blockers with a PR get merged; blockers without one might ship anyway. Maintainers watch these threads during beta testing.
+6. Silence means green. If you miss the window, your fix likely lands in the next cycle.
+
+## Next steps
+
+<CardGroup cols={2}>
+  <Card title="Channel Plugins" icon="messages-square" href="/plugins/sdk-channel-plugins">
+    Build a messaging channel plugin
+  </Card>
+  <Card title="Provider Plugins" icon="cpu" href="/plugins/sdk-provider-plugins">
+    Build a model provider plugin
+  </Card>
+  <Card title="CLI Backend Plugins" icon="terminal" href="/plugins/cli-backend-plugins">
+    Register a local AI CLI backend
+  </Card>
+  <Card title="SDK Overview" icon="book-open" href="/plugins/sdk-overview">
+    Import map and registration API reference
+  </Card>
+  <Card title="Runtime Helpers" icon="settings" href="/plugins/sdk-runtime">
+    TTS, search, subagent via api.runtime
+  </Card>
+  <Card title="Testing" icon="test-tubes" href="/plugins/sdk-testing">
+    Test utilities and patterns
+  </Card>
+  <Card title="Plugin Manifest" icon="file-json" href="/plugins/manifest">
+    Full manifest schema reference
+  </Card>
+</CardGroup>
+
+## Related
+
+- [Plugin hooks](/plugins/hooks)
+- [Plugin architecture](/plugins/architecture)

package/docs/plugins/bundles.md

@@ -0,0 +1,310 @@
+---
+summary: "Install and use Codex, Claude, and Cursor bundles as Nodmix plugins"
+read_when:
+  - You want to install a Codex, Claude, or Cursor-compatible bundle
+  - You need to understand how Nodmix maps bundle content into native features
+  - You are debugging bundle detection or missing capabilities
+title: "Plugin bundles"
+---
+
+Nodmix can install plugins from three external ecosystems: **Codex**, **Claude**,
+and **Cursor**. These are called **bundles** — content and metadata packs that
+Nodmix maps into native features like skills, hooks, and MCP tools.
+
+<Info>
+  Bundles are **not** the same as native Nodmix plugins. Native plugins run
+  in-process and can register any capability. Bundles are content packs with
+  selective feature mapping and a narrower trust boundary.
+</Info>
+
+## Why bundles exist
+
+Many useful plugins are published in Codex, Claude, or Cursor format. Instead
+of requiring authors to rewrite them as native Nodmix plugins, Nodmix
+detects these formats and maps their supported content into the native feature
+set. This means you can install a Claude command pack or a Codex skill bundle
+and use it immediately.
+
+## Install a bundle
+
+<Steps>
+  <Step title="Install from a directory, archive, or marketplace">
+    ```bash
+    # Local directory
+    nodmix plugins install ./my-bundle
+
+    # Archive
+    nodmix plugins install ./my-bundle.tgz
+
+    # Claude marketplace
+    nodmix plugins marketplace list <marketplace-name>
+    nodmix plugins install <plugin-name>@<marketplace-name>
+    ```
+
+  </Step>
+
+  <Step title="Verify detection">
+    ```bash
+    nodmix plugins list
+    nodmix plugins inspect <id>
+    ```
+
+    Bundles show as `Format: bundle` with a subtype of `codex`, `claude`, or `cursor`.
+
+  </Step>
+
+  <Step title="Restart and use">
+    ```bash
+    nodmix gateway restart
+    ```
+
+    Mapped features (skills, hooks, MCP tools, LSP defaults) are available in the next session.
+
+  </Step>
+</Steps>
+
+## What Nodmix maps from bundles
+
+Not every bundle feature runs in Nodmix today. Here is what works and what
+is detected but not yet wired.
+
+### Supported now
+
+| Feature       | How it maps                                                                                 | Applies to     |
+| ------------- | ------------------------------------------------------------------------------------------- | -------------- |
+| Skill content | Bundle skill roots load as normal Nodmix skills                                           | All formats    |
+| Commands      | `commands/` and `.cursor/commands/` treated as skill roots                                  | Claude, Cursor |
+| Hook packs    | Nodmix-style `HOOK.md` + `handler.ts` layouts                                             | Codex          |
+| MCP tools     | Bundle MCP config merged into embedded Pi settings; supported stdio and HTTP servers loaded | All formats    |
+| LSP servers   | Claude `.lsp.json` and manifest-declared `lspServers` merged into embedded Pi LSP defaults  | Claude         |
+| Settings      | Claude `settings.json` imported as embedded Pi defaults                                     | Claude         |
+
+#### Skill content
+
+- bundle skill roots load as normal Nodmix skill roots
+- Claude `commands` roots are treated as additional skill roots
+- Cursor `.cursor/commands` roots are treated as additional skill roots
+
+This means Claude markdown command files work through the normal Nodmix skill
+loader. Cursor command markdown works through the same path.
+
+#### Hook packs
+
+- bundle hook roots work **only** when they use the normal Nodmix hook-pack
+  layout. Today this is primarily the Codex-compatible case:
+  - `HOOK.md`
+  - `handler.ts` or `handler.js`
+
+#### MCP for Pi
+
+- enabled bundles can contribute MCP server config
+- Nodmix merges bundle MCP config into the effective embedded Pi settings as
+  `mcpServers`
+- Nodmix exposes supported bundle MCP tools during embedded Pi agent turns by
+  launching stdio servers or connecting to HTTP servers
+- the `coding` and `messaging` tool profiles include bundle MCP tools by
+  default; use `tools.deny: ["bundle-mcp"]` to opt out for an agent or gateway
+- project-local Pi settings still apply after bundle defaults, so workspace
+  settings can override bundle MCP entries when needed
+- bundle MCP tool catalogs are sorted deterministically before registration, so
+  upstream `listTools()` order changes do not thrash prompt-cache tool blocks
+
+##### Transports
+
+MCP servers can use stdio or HTTP transport:
+
+**Stdio** launches a child process:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "my-server": {
+        "command": "node",
+        "args": ["server.js"],
+        "env": { "PORT": "3000" }
+      }
+    }
+  }
+}
+```
+
+**HTTP** connects to a running MCP server over `sse` by default, or `streamable-http` when requested:
+
+```json
+{
+  "mcp": {
+    "servers": {
+      "my-server": {
+        "url": "http://localhost:3100/mcp",
+        "transport": "streamable-http",
+        "headers": {
+          "Authorization": "Bearer ${MY_SECRET_TOKEN}"
+        },
+        "connectionTimeoutMs": 30000
+      }
+    }
+  }
+}
+```
+
+- `transport` may be set to `"streamable-http"` or `"sse"`; when omitted, Nodmix uses `sse`
+- `type: "http"` is a CLI-native downstream shape; use `transport: "streamable-http"` in Nodmix config. `nodmix mcp set` and `nodmix doctor --fix` normalize the common alias.
+- only `http:` and `https:` URL schemes are allowed
+- `headers` values support `${ENV_VAR}` interpolation
+- a server entry with both `command` and `url` is rejected
+- URL credentials (userinfo and query params) are redacted from tool
+  descriptions and logs
+- `connectionTimeoutMs` overrides the default 30-second connection timeout for
+  both stdio and HTTP transports
+
+##### Tool naming
+
+Nodmix registers bundle MCP tools with provider-safe names in the form
+`serverName__toolName`. For example, a server keyed `"vigil-harbor"` exposing a
+`memory_search` tool registers as `vigil-harbor__memory_search`.
+
+- characters outside `A-Za-z0-9_-` are replaced with `-`
+- fragments that would start with a non-letter get a letter prefix, so numeric
+  server keys such as `12306` become provider-safe tool prefixes
+- server prefixes are capped at 30 characters
+- full tool names are capped at 64 characters
+- empty server names fall back to `mcp`
+- colliding sanitized names are disambiguated with numeric suffixes
+- final exposed tool order is deterministic by safe name to keep repeated Pi
+  turns cache-stable
+- profile filtering treats all tools from one bundle MCP server as plugin-owned
+  by `bundle-mcp`, so profile allowlists and deny lists can include either
+  individual exposed tool names or the `bundle-mcp` plugin key
+
+#### Embedded Pi settings
+
+- Claude `settings.json` is imported as default embedded Pi settings when the
+  bundle is enabled
+- Nodmix sanitizes shell override keys before applying them
+
+Sanitized keys:
+
+- `shellPath`
+- `shellCommandPrefix`
+
+#### Embedded Pi LSP
+
+- enabled Claude bundles can contribute LSP server config
+- Nodmix loads `.lsp.json` plus any manifest-declared `lspServers` paths
+- bundle LSP config is merged into the effective embedded Pi LSP defaults
+- only supported stdio-backed LSP servers are runnable today; unsupported
+  transports still show up in `nodmix plugins inspect <id>`
+
+### Detected but not executed
+
+These are recognized and shown in diagnostics, but Nodmix does not run them:
+
+- Claude `agents`, `hooks.json` automation, `outputStyles`
+- Cursor `.cursor/agents`, `.cursor/hooks.json`, `.cursor/rules`
+- Codex inline/app metadata beyond capability reporting
+
+## Bundle formats
+
+<AccordionGroup>
+  <Accordion title="Codex bundles">
+    Markers: `.codex-plugin/plugin.json`
+
+    Optional content: `skills/`, `hooks/`, `.mcp.json`, `.app.json`
+
+    Codex bundles fit Nodmix best when they use skill roots and Nodmix-style
+    hook-pack directories (`HOOK.md` + `handler.ts`).
+
+  </Accordion>
+
+  <Accordion title="Claude bundles">
+    Two detection modes:
+
+    - **Manifest-based:** `.claude-plugin/plugin.json`
+    - **Manifestless:** default Claude layout (`skills/`, `commands/`, `agents/`, `hooks/`, `.mcp.json`, `.lsp.json`, `settings.json`)
+
+    Claude-specific behavior:
+
+    - `commands/` is treated as skill content
+    - `settings.json` is imported into embedded Pi settings (shell override keys are sanitized)
+    - `.mcp.json` exposes supported stdio tools to embedded Pi
+    - `.lsp.json` plus manifest-declared `lspServers` paths load into embedded Pi LSP defaults
+    - `hooks/hooks.json` is detected but not executed
+    - Custom component paths in the manifest are additive (they extend defaults, not replace them)
+
+  </Accordion>
+
+  <Accordion title="Cursor bundles">
+    Markers: `.cursor-plugin/plugin.json`
+
+    Optional content: `skills/`, `.cursor/commands/`, `.cursor/agents/`, `.cursor/rules/`, `.cursor/hooks.json`, `.mcp.json`
+
+    - `.cursor/commands/` is treated as skill content
+    - `.cursor/rules/`, `.cursor/agents/`, and `.cursor/hooks.json` are detect-only
+
+  </Accordion>
+</AccordionGroup>
+
+## Detection precedence
+
+Nodmix checks for native plugin format first:
+
+1. `nodmix.plugin.json` or valid `package.json` with `nodmix.extensions` — treated as **native plugin**
+2. Bundle markers (`.codex-plugin/`, `.claude-plugin/`, or default Claude/Cursor layout) — treated as **bundle**
+
+If a directory contains both, Nodmix uses the native path. This prevents
+dual-format packages from being partially installed as bundles.
+
+## Runtime dependencies and cleanup
+
+- Third-party compatible bundles do not get startup `npm install` repair. They
+  should be installed through `nodmix plugins install` and ship everything
+  they need in the installed plugin directory.
+- Nodmix-owned bundled plugins are either shipped lightweight in core or
+  downloadable through the plugin installer. Gateway startup never runs a
+  package manager for them.
+- `nodmix doctor --fix` removes legacy staged dependency directories and can
+  recover downloadable plugins that are missing from the local plugin index when
+  config references them.
+
+## Security
+
+Bundles have a narrower trust boundary than native plugins:
+
+- Nodmix does **not** load arbitrary bundle runtime modules in-process
+- Skills and hook-pack paths must stay inside the plugin root (boundary-checked)
+- Settings files are read with the same boundary checks
+- Supported stdio MCP servers may be launched as subprocesses
+
+This makes bundles safer by default, but you should still treat third-party
+bundles as trusted content for the features they do expose.
+
+## Troubleshooting
+
+<AccordionGroup>
+  <Accordion title="Bundle is detected but capabilities do not run">
+    Run `nodmix plugins inspect <id>`. If a capability is listed but marked as
+    not wired, that is a product limit — not a broken install.
+  </Accordion>
+
+  <Accordion title="Claude command files do not appear">
+    Make sure the bundle is enabled and the markdown files are inside a detected
+    `commands/` or `skills/` root.
+  </Accordion>
+
+  <Accordion title="Claude settings do not apply">
+    Only embedded Pi settings from `settings.json` are supported. Nodmix does
+    not treat bundle settings as raw config patches.
+  </Accordion>
+
+  <Accordion title="Claude hooks do not execute">
+    `hooks/hooks.json` is detect-only. If you need runnable hooks, use the
+    Nodmix hook-pack layout or ship a native plugin.
+  </Accordion>
+</AccordionGroup>
+
+## Related
+
+- [Install and Configure Plugins](/tools/plugin)
+- [Building Plugins](/plugins/building-plugins) — create a native plugin
+- [Plugin Manifest](/plugins/manifest) — native manifest schema