@quantumclaw/quantumclaw 2026.3.22

package/docs/plugins/manifest.md

@@ -0,0 +1,241 @@
+---
+summary: "Plugin manifest + JSON schema requirements (strict config validation)"
+read_when:
+  - You are building an QuantumClaw plugin
+  - You need to ship a plugin config schema or debug plugin validation errors
+title: "Plugin Manifest"
+---
+
+# Plugin manifest (quantumclaw.plugin.json)
+
+This page is for the **native QuantumClaw plugin manifest** only.
+
+For compatible bundle layouts, see [Plugin bundles](/plugins/bundles).
+
+Compatible bundle formats use different manifest files:
+
+- Codex bundle: `.codex-plugin/plugin.json`
+- Claude bundle: `.claude-plugin/plugin.json` or the default Claude component
+  layout without a manifest
+- Cursor bundle: `.cursor-plugin/plugin.json`
+
+QuantumClaw auto-detects those bundle layouts too, but they are not validated
+against the `quantumclaw.plugin.json` schema described here.
+
+For compatible bundles, QuantumClaw currently reads bundle metadata plus declared
+skill roots, Claude command roots, Claude bundle `settings.json` defaults, and
+supported hook packs when the layout matches QuantumClaw runtime expectations.
+
+Every native QuantumClaw plugin **must** ship a `quantumclaw.plugin.json` file in the
+**plugin root**. QuantumClaw uses this manifest to validate configuration
+**without executing plugin code**. Missing or invalid manifests are treated as
+plugin errors and block config validation.
+
+See the full plugin system guide: [Plugins](/tools/plugin).
+For the native capability model and current external-compatibility guidance:
+[Capability model](/plugins/architecture#public-capability-model).
+
+## What this file does
+
+`quantumclaw.plugin.json` is the metadata QuantumClaw reads before it loads your
+plugin code.
+
+Use it for:
+
+- plugin identity
+- config validation
+- auth and onboarding metadata that should be available without booting plugin
+  runtime
+- config UI hints
+
+Do not use it for:
+
+- registering runtime behavior
+- declaring code entrypoints
+- npm install metadata
+
+Those belong in your plugin code and `package.json`.
+
+## Minimal example
+
+```json
+{
+  "id": "voice-call",
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {}
+  }
+}
+```
+
+## Rich example
+
+```json
+{
+  "id": "openrouter",
+  "name": "OpenRouter",
+  "description": "OpenRouter provider plugin",
+  "version": "1.0.0",
+  "providers": ["openrouter"],
+  "providerAuthEnvVars": {
+    "openrouter": ["OPENROUTER_API_KEY"]
+  },
+  "providerAuthChoices": [
+    {
+      "provider": "openrouter",
+      "method": "api-key",
+      "choiceId": "openrouter-api-key",
+      "choiceLabel": "OpenRouter API key",
+      "groupId": "openrouter",
+      "groupLabel": "OpenRouter",
+      "optionKey": "openrouterApiKey",
+      "cliFlag": "--openrouter-api-key",
+      "cliOption": "--openrouter-api-key <key>",
+      "cliDescription": "OpenRouter API key",
+      "onboardingScopes": ["text-inference"]
+    }
+  ],
+  "uiHints": {
+    "apiKey": {
+      "label": "API key",
+      "placeholder": "sk-or-v1-...",
+      "sensitive": true
+    }
+  },
+  "configSchema": {
+    "type": "object",
+    "additionalProperties": false,
+    "properties": {
+      "apiKey": {
+        "type": "string"
+      }
+    }
+  }
+}
+```
+
+## Top-level field reference
+
+| Field                 | Required | Type                             | What it means                                                                                                                |
+| --------------------- | -------- | -------------------------------- | ---------------------------------------------------------------------------------------------------------------------------- |
+| `id`                  | Yes      | `string`                         | Canonical plugin id. This is the id used in `plugins.entries.<id>`.                                                          |
+| `configSchema`        | Yes      | `object`                         | Inline JSON Schema for this plugin's config.                                                                                 |
+| `enabledByDefault`    | No       | `true`                           | Marks a bundled plugin as enabled by default. Omit it, or set any non-`true` value, to leave the plugin disabled by default. |
+| `kind`                | No       | `"memory"` \| `"context-engine"` | Declares an exclusive plugin kind used by `plugins.slots.*`.                                                                 |
+| `channels`            | No       | `string[]`                       | Channel ids owned by this plugin. Used for discovery and config validation.                                                  |
+| `providers`           | No       | `string[]`                       | Provider ids owned by this plugin.                                                                                           |
+| `providerAuthEnvVars` | No       | `Record<string, string[]>`       | Cheap provider-auth env metadata that QuantumClaw can inspect without loading plugin code.                                      |
+| `providerAuthChoices` | No       | `object[]`                       | Cheap auth-choice metadata for onboarding pickers, preferred-provider resolution, and simple CLI flag wiring.                |
+| `skills`              | No       | `string[]`                       | Skill directories to load, relative to the plugin root.                                                                      |
+| `name`                | No       | `string`                         | Human-readable plugin name.                                                                                                  |
+| `description`         | No       | `string`                         | Short summary shown in plugin surfaces.                                                                                      |
+| `version`             | No       | `string`                         | Informational plugin version.                                                                                                |
+| `uiHints`             | No       | `Record<string, object>`         | UI labels, placeholders, and sensitivity hints for config fields.                                                            |
+
+## providerAuthChoices reference
+
+Each `providerAuthChoices` entry describes one onboarding or auth choice.
+QuantumClaw reads this before provider runtime loads.
+
+| Field              | Required | Type                                            | What it means                                                                                            |
+| ------------------ | -------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
+| `provider`         | Yes      | `string`                                        | Provider id this choice belongs to.                                                                      |
+| `method`           | Yes      | `string`                                        | Auth method id to dispatch to.                                                                           |
+| `choiceId`         | Yes      | `string`                                        | Stable auth-choice id used by onboarding and CLI flows.                                                  |
+| `choiceLabel`      | No       | `string`                                        | User-facing label. If omitted, QuantumClaw falls back to `choiceId`.                                        |
+| `choiceHint`       | No       | `string`                                        | Short helper text for the picker.                                                                        |
+| `groupId`          | No       | `string`                                        | Optional group id for grouping related choices.                                                          |
+| `groupLabel`       | No       | `string`                                        | User-facing label for that group.                                                                        |
+| `groupHint`        | No       | `string`                                        | Short helper text for the group.                                                                         |
+| `optionKey`        | No       | `string`                                        | Internal option key for simple one-flag auth flows.                                                      |
+| `cliFlag`          | No       | `string`                                        | CLI flag name, such as `--openrouter-api-key`.                                                           |
+| `cliOption`        | No       | `string`                                        | Full CLI option shape, such as `--openrouter-api-key <key>`.                                             |
+| `cliDescription`   | No       | `string`                                        | Description used in CLI help.                                                                            |
+| `onboardingScopes` | No       | `Array<"text-inference" \| "image-generation">` | Which onboarding surfaces this choice should appear in. If omitted, it defaults to `["text-inference"]`. |
+
+## uiHints reference
+
+`uiHints` is a map from config field names to small rendering hints.
+
+```json
+{
+  "uiHints": {
+    "apiKey": {
+      "label": "API key",
+      "help": "Used for OpenRouter requests",
+      "placeholder": "sk-or-v1-...",
+      "sensitive": true
+    }
+  }
+}
+```
+
+Each field hint can include:
+
+| Field         | Type       | What it means                           |
+| ------------- | ---------- | --------------------------------------- |
+| `label`       | `string`   | User-facing field label.                |
+| `help`        | `string`   | Short helper text.                      |
+| `tags`        | `string[]` | Optional UI tags.                       |
+| `advanced`    | `boolean`  | Marks the field as advanced.            |
+| `sensitive`   | `boolean`  | Marks the field as secret or sensitive. |
+| `placeholder` | `string`   | Placeholder text for form inputs.       |
+
+## Manifest versus package.json
+
+The two files serve different jobs:
+
+| File                   | Use it for                                                                                                         |
+| ---------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| `quantumclaw.plugin.json` | Discovery, config validation, auth-choice metadata, and UI hints that must exist before plugin code runs           |
+| `package.json`         | npm metadata, dependency installation, and the `quantumclaw` block used for entrypoints and setup or catalog metadata |
+
+If you are unsure where a piece of metadata belongs, use this rule:
+
+- if QuantumClaw must know it before loading plugin code, put it in `quantumclaw.plugin.json`
+- if it is about packaging, entry files, or npm install behavior, put it in `package.json`
+
+## JSON Schema requirements
+
+- **Every plugin must ship a JSON Schema**, even if it accepts no config.
+- An empty schema is acceptable (for example, `{ "type": "object", "additionalProperties": false }`).
+- Schemas are validated at config read/write time, not at runtime.
+
+## Validation behavior
+
+- Unknown `channels.*` keys are **errors**, unless the channel id is declared by
+  a plugin manifest.
+- `plugins.entries.<id>`, `plugins.allow`, `plugins.deny`, and `plugins.slots.*`
+  must reference **discoverable** plugin ids. Unknown ids are **errors**.
+- If a plugin is installed but has a broken or missing manifest or schema,
+  validation fails and Doctor reports the plugin error.
+- If plugin config exists but the plugin is **disabled**, the config is kept and
+  a **warning** is surfaced in Doctor + logs.
+
+See [Configuration reference](/configuration) for the full `plugins.*` schema.
+
+## Notes
+
+- The manifest is **required for native QuantumClaw plugins**, including local filesystem loads.
+- Runtime still loads the plugin module separately; the manifest is only for
+  discovery + validation.
+- Only documented manifest fields are read by the manifest loader. Avoid adding
+  custom top-level keys here.
+- `providerAuthEnvVars` is the cheap metadata path for auth probes, env-marker
+  validation, and similar provider-auth surfaces that should not boot plugin
+  runtime just to inspect env names.
+- `providerAuthChoices` is the cheap metadata path for auth-choice pickers,
+  `--auth-choice` resolution, preferred-provider mapping, and simple onboarding
+  CLI flag registration before provider runtime loads. For runtime wizard
+  metadata that requires provider code, see
+  [Provider runtime hooks](/plugins/architecture#provider-runtime-hooks).
+- Exclusive plugin kinds are selected through `plugins.slots.*`.
+  - `kind: "memory"` is selected by `plugins.slots.memory`.
+  - `kind: "context-engine"` is selected by `plugins.slots.contextEngine`
+    (default: built-in `legacy`).
+- `channels`, `providers`, and `skills` can be omitted when a plugin does not
+  need them.
+- If your plugin depends on native modules, document the build steps and any
+  package-manager allowlist requirements (for example, pnpm `allow-build-scripts`
+  - `pnpm rebuild <package>`).

package/docs/plugins/sdk-channel-plugins.md

@@ -0,0 +1,370 @@
+---
+title: "Building Channel Plugins"
+sidebarTitle: "Channel Plugins"
+summary: "Step-by-step guide to building a messaging channel plugin for QuantumClaw"
+read_when:
+  - You are building a new messaging channel plugin
+  - You want to connect QuantumClaw to a messaging platform
+  - You need to understand the ChannelPlugin adapter surface
+---
+
+# Building Channel Plugins
+
+This guide walks through building a channel plugin that connects QuantumClaw to a
+messaging platform. By the end you will have a working channel with DM security,
+pairing, reply threading, and outbound messaging.
+
+<Info>
+  If you have not built any QuantumClaw plugin before, read
+  [Getting Started](/plugins/building-plugins) first for the basic package
+  structure and manifest setup.
+</Info>
+
+## How channel plugins work
+
+Channel plugins do not need their own send/edit/react tools. QuantumClaw keeps one
+shared `message` tool in core. Your plugin owns:
+
+- **Config** — account resolution and setup wizard
+- **Security** — DM policy and allowlists
+- **Pairing** — DM approval flow
+- **Outbound** — sending text, media, and polls to the platform
+- **Threading** — how replies are threaded
+
+Core owns the shared message tool, prompt wiring, session bookkeeping, and
+dispatch.
+
+## Walkthrough
+
+<Steps>
+  <Step title="Package and manifest">
+    Create the standard plugin files. The `channel` field in `package.json` is
+    what makes this a channel plugin:
+
+    <CodeGroup>
+    ```json package.json
+    {
+      "name": "@myorg/quantumclaw-acme-chat",
+      "version": "1.0.0",
+      "type": "module",
+      "quantumclaw": {
+        "extensions": ["./index.ts"],
+        "setupEntry": "./setup-entry.ts",
+        "channel": {
+          "id": "acme-chat",
+          "label": "Acme Chat",
+          "blurb": "Connect QuantumClaw to Acme Chat."
+        }
+      }
+    }
+    ```
+
+    ```json quantumclaw.plugin.json
+    {
+      "id": "acme-chat",
+      "kind": "channel",
+      "channels": ["acme-chat"],
+      "name": "Acme Chat",
+      "description": "Acme Chat channel plugin",
+      "configSchema": {
+        "type": "object",
+        "additionalProperties": false,
+        "properties": {
+          "acme-chat": {
+            "type": "object",
+            "properties": {
+              "token": { "type": "string" },
+              "allowFrom": {
+                "type": "array",
+                "items": { "type": "string" }
+              }
+            }
+          }
+        }
+      }
+    }
+    ```
+    </CodeGroup>
+
+  </Step>
+
+  <Step title="Build the channel plugin object">
+    The `ChannelPlugin` interface has many optional adapter surfaces. Start with
+    the minimum — `id` and `setup` — and add adapters as you need them.
+
+    Create `src/channel.ts`:
+
+    ```typescript src/channel.ts
+    import {
+      createChatChannelPlugin,
+      createChannelPluginBase,
+    } from "quantumclaw/plugin-sdk/core";
+    import type { QuantumClawConfig } from "quantumclaw/plugin-sdk/core";
+    import { acmeChatApi } from "./client.js"; // your platform API client
+
+    type ResolvedAccount = {
+      accountId: string | null;
+      token: string;
+      allowFrom: string[];
+      dmPolicy: string | undefined;
+    };
+
+    function resolveAccount(
+      cfg: QuantumClawConfig,
+      accountId?: string | null,
+    ): ResolvedAccount {
+      const section = (cfg.channels as Record<string, any>)?.["acme-chat"];
+      const token = section?.token;
+      if (!token) throw new Error("acme-chat: token is required");
+      return {
+        accountId: accountId ?? null,
+        token,
+        allowFrom: section?.allowFrom ?? [],
+        dmPolicy: section?.dmSecurity,
+      };
+    }
+
+    export const acmeChatPlugin = createChatChannelPlugin<ResolvedAccount>({
+      base: createChannelPluginBase({
+        id: "acme-chat",
+        setup: {
+          resolveAccount,
+          inspectAccount(cfg, accountId) {
+            const section =
+              (cfg.channels as Record<string, any>)?.["acme-chat"];
+            return {
+              enabled: Boolean(section?.token),
+              configured: Boolean(section?.token),
+              tokenStatus: section?.token ? "available" : "missing",
+            };
+          },
+        },
+      }),
+
+      // DM security: who can message the bot
+      security: {
+        dm: {
+          channelKey: "acme-chat",
+          resolvePolicy: (account) => account.dmPolicy,
+          resolveAllowFrom: (account) => account.allowFrom,
+          defaultPolicy: "allowlist",
+        },
+      },
+
+      // Pairing: approval flow for new DM contacts
+      pairing: {
+        text: {
+          idLabel: "Acme Chat username",
+          message: "Send this code to verify your identity:",
+          notify: async ({ target, code }) => {
+            await acmeChatApi.sendDm(target, `Pairing code: ${code}`);
+          },
+        },
+      },
+
+      // Threading: how replies are delivered
+      threading: { topLevelReplyToMode: "reply" },
+
+      // Outbound: send messages to the platform
+      outbound: {
+        attachedResults: {
+          sendText: async (params) => {
+            const result = await acmeChatApi.sendMessage(
+              params.to,
+              params.text,
+            );
+            return { messageId: result.id };
+          },
+        },
+        base: {
+          sendMedia: async (params) => {
+            await acmeChatApi.sendFile(params.to, params.filePath);
+          },
+        },
+      },
+    });
+    ```
+
+    <Accordion title="What createChatChannelPlugin does for you">
+      Instead of implementing low-level adapter interfaces manually, you pass
+      declarative options and the builder composes them:
+
+      | Option | What it wires |
+      | --- | --- |
+      | `security.dm` | Scoped DM security resolver from config fields |
+      | `pairing.text` | Text-based DM pairing flow with code exchange |
+      | `threading` | Reply-to-mode resolver (fixed, account-scoped, or custom) |
+      | `outbound.attachedResults` | Send functions that return result metadata (message IDs) |
+
+      You can also pass raw adapter objects instead of the declarative options
+      if you need full control.
+    </Accordion>
+
+  </Step>
+
+  <Step title="Wire the entry point">
+    Create `index.ts`:
+
+    ```typescript index.ts
+    import { defineChannelPluginEntry } from "quantumclaw/plugin-sdk/core";
+    import { acmeChatPlugin } from "./src/channel.js";
+
+    export default defineChannelPluginEntry({
+      id: "acme-chat",
+      name: "Acme Chat",
+      description: "Acme Chat channel plugin",
+      plugin: acmeChatPlugin,
+      registerFull(api) {
+        api.registerCli(
+          ({ program }) => {
+            program
+              .command("acme-chat")
+              .description("Acme Chat management");
+          },
+          { commands: ["acme-chat"] },
+        );
+      },
+    });
+    ```
+
+    `defineChannelPluginEntry` handles the setup/full registration split
+    automatically. See
+    [Entry Points](/plugins/sdk-entrypoints#definechannelpluginentry) for all
+    options.
+
+  </Step>
+
+  <Step title="Add a setup entry">
+    Create `setup-entry.ts` for lightweight loading during onboarding:
+
+    ```typescript setup-entry.ts
+    import { defineSetupPluginEntry } from "quantumclaw/plugin-sdk/core";
+    import { acmeChatPlugin } from "./src/channel.js";
+
+    export default defineSetupPluginEntry(acmeChatPlugin);
+    ```
+
+    QuantumClaw loads this instead of the full entry when the channel is disabled
+    or unconfigured. It avoids pulling in heavy runtime code during setup flows.
+    See [Setup and Config](/plugins/sdk-setup#setup-entry) for details.
+
+  </Step>
+
+  <Step title="Handle inbound messages">
+    Your plugin needs to receive messages from the platform and forward them to
+    QuantumClaw. The typical pattern is a webhook that verifies the request and
+    dispatches it through your channel's inbound handler:
+
+    ```typescript
+    registerFull(api) {
+      api.registerHttpRoute({
+        path: "/acme-chat/webhook",
+        auth: "plugin", // plugin-managed auth (verify signatures yourself)
+        handler: async (req, res) => {
+          const event = parseWebhookPayload(req);
+
+          // Your inbound handler dispatches the message to QuantumClaw.
+          // The exact wiring depends on your platform SDK —
+          // see a real example in extensions/msteams or extensions/googlechat.
+          await handleAcmeChatInbound(api, event);
+
+          res.statusCode = 200;
+          res.end("ok");
+          return true;
+        },
+      });
+    }
+    ```
+
+    <Note>
+      Inbound message handling is channel-specific. Each channel plugin owns
+      its own inbound pipeline. Look at bundled channel plugins
+      (e.g. `extensions/msteams`, `extensions/googlechat`) for real patterns.
+    </Note>
+
+  </Step>
+
+  <Step title="Test">
+    Write colocated tests in `src/channel.test.ts`:
+
+    ```typescript src/channel.test.ts
+    import { describe, it, expect } from "vitest";
+    import { acmeChatPlugin } from "./channel.js";
+
+    describe("acme-chat plugin", () => {
+      it("resolves account from config", () => {
+        const cfg = {
+          channels: {
+            "acme-chat": { token: "test-token", allowFrom: ["user1"] },
+          },
+        } as any;
+        const account = acmeChatPlugin.setup!.resolveAccount(cfg, undefined);
+        expect(account.token).toBe("test-token");
+      });
+
+      it("inspects account without materializing secrets", () => {
+        const cfg = {
+          channels: { "acme-chat": { token: "test-token" } },
+        } as any;
+        const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
+        expect(result.configured).toBe(true);
+        expect(result.tokenStatus).toBe("available");
+      });
+
+      it("reports missing config", () => {
+        const cfg = { channels: {} } as any;
+        const result = acmeChatPlugin.setup!.inspectAccount!(cfg, undefined);
+        expect(result.configured).toBe(false);
+      });
+    });
+    ```
+
+    ```bash
+    pnpm test -- extensions/acme-chat/
+    ```
+
+    For shared test helpers, see [Testing](/plugins/sdk-testing).
+
+  </Step>
+</Steps>
+
+## File structure
+
+```
+extensions/acme-chat/
+├── package.json              # quantumclaw.channel metadata
+├── quantumclaw.plugin.json      # Manifest with config schema
+├── index.ts                  # defineChannelPluginEntry
+├── setup-entry.ts            # defineSetupPluginEntry
+├── api.ts                    # Public exports (optional)
+├── runtime-api.ts            # Internal runtime exports (optional)
+└── src/
+    ├── channel.ts            # ChannelPlugin via createChatChannelPlugin
+    ├── channel.test.ts       # Tests
+    ├── client.ts             # Platform API client
+    └── runtime.ts            # Runtime store (if needed)
+```
+
+## Advanced topics
+
+<CardGroup cols={2}>
+  <Card title="Threading options" icon="git-branch" href="/plugins/sdk-entrypoints#registration-mode">
+    Fixed, account-scoped, or custom reply modes
+  </Card>
+  <Card title="Message tool integration" icon="puzzle" href="/plugins/architecture#channel-plugins-and-the-shared-message-tool">
+    describeMessageTool and action discovery
+  </Card>
+  <Card title="Target resolution" icon="crosshair" href="/plugins/architecture#channel-target-resolution">
+    inferTargetChatType, looksLikeId, resolveTarget
+  </Card>
+  <Card title="Runtime helpers" icon="settings" href="/plugins/sdk-runtime">
+    TTS, STT, media, subagent via api.runtime
+  </Card>
+</CardGroup>
+
+## Next steps
+
+- [Provider Plugins](/plugins/sdk-provider-plugins) — if your plugin also provides models
+- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
+- [SDK Testing](/plugins/sdk-testing) — test utilities and contract tests
+- [Plugin Manifest](/plugins/manifest) — full manifest schema