@quantumclaw/quantumclaw 2026.3.22

package/docs/plugins/sdk-entrypoints.md

@@ -0,0 +1,161 @@
+---
+title: "Plugin Entry Points"
+sidebarTitle: "Entry Points"
+summary: "Reference for definePluginEntry, defineChannelPluginEntry, and defineSetupPluginEntry"
+read_when:
+  - You need the exact type signature of definePluginEntry or defineChannelPluginEntry
+  - You want to understand registration mode (full vs setup)
+  - You are looking up entry point options
+---
+
+# Plugin Entry Points
+
+Every plugin exports a default entry object. The SDK provides three helpers for
+creating them.
+
+<Tip>
+  **Looking for a walkthrough?** See [Channel Plugins](/plugins/sdk-channel-plugins)
+  or [Provider Plugins](/plugins/sdk-provider-plugins) for step-by-step guides.
+</Tip>
+
+## `definePluginEntry`
+
+**Import:** `quantumclaw/plugin-sdk/plugin-entry`
+
+For provider plugins, tool plugins, hook plugins, and anything that is **not**
+a messaging channel.
+
+```typescript
+import { definePluginEntry } from "quantumclaw/plugin-sdk/plugin-entry";
+
+export default definePluginEntry({
+  id: "my-plugin",
+  name: "My Plugin",
+  description: "Short summary",
+  register(api) {
+    api.registerProvider({
+      /* ... */
+    });
+    api.registerTool({
+      /* ... */
+    });
+  },
+});
+```
+
+### Channel entry options
+
+| Field          | Type                                                             | Required | Default             |
+| -------------- | ---------------------------------------------------------------- | -------- | ------------------- |
+| `id`           | `string`                                                         | Yes      | —                   |
+| `name`         | `string`                                                         | Yes      | —                   |
+| `description`  | `string`                                                         | Yes      | —                   |
+| `kind`         | `string`                                                         | No       | —                   |
+| `configSchema` | `QuantumClawPluginConfigSchema \| () => QuantumClawPluginConfigSchema` | No       | Empty object schema |
+| `register`     | `(api: QuantumClawPluginApi) => void`                               | Yes      | —                   |
+
+- `id` must match your `quantumclaw.plugin.json` manifest.
+- `kind` is for exclusive slots: `"memory"` or `"context-engine"`.
+- `configSchema` can be a function for lazy evaluation.
+
+## `defineChannelPluginEntry`
+
+**Import:** `quantumclaw/plugin-sdk/core`
+
+Wraps `definePluginEntry` with channel-specific wiring. Automatically calls
+`api.registerChannel({ plugin })` and gates `registerFull` on registration mode.
+
+```typescript
+import { defineChannelPluginEntry } from "quantumclaw/plugin-sdk/core";
+
+export default defineChannelPluginEntry({
+  id: "my-channel",
+  name: "My Channel",
+  description: "Short summary",
+  plugin: myChannelPlugin,
+  setRuntime: setMyRuntime,
+  registerFull(api) {
+    api.registerCli(/* ... */);
+    api.registerGatewayMethod(/* ... */);
+  },
+});
+```
+
+### Options
+
+| Field          | Type                                                             | Required | Default             |
+| -------------- | ---------------------------------------------------------------- | -------- | ------------------- |
+| `id`           | `string`                                                         | Yes      | —                   |
+| `name`         | `string`                                                         | Yes      | —                   |
+| `description`  | `string`                                                         | Yes      | —                   |
+| `plugin`       | `ChannelPlugin`                                                  | Yes      | —                   |
+| `configSchema` | `QuantumClawPluginConfigSchema \| () => QuantumClawPluginConfigSchema` | No       | Empty object schema |
+| `setRuntime`   | `(runtime: PluginRuntime) => void`                               | No       | —                   |
+| `registerFull` | `(api: QuantumClawPluginApi) => void`                               | No       | —                   |
+
+- `setRuntime` is called during registration so you can store the runtime reference
+  (typically via `createPluginRuntimeStore`).
+- `registerFull` only runs when `api.registrationMode === "full"`. It is skipped
+  during setup-only loading.
+
+## `defineSetupPluginEntry`
+
+**Import:** `quantumclaw/plugin-sdk/core`
+
+For the lightweight `setup-entry.ts` file. Returns just `{ plugin }` with no
+runtime or CLI wiring.
+
+```typescript
+import { defineSetupPluginEntry } from "quantumclaw/plugin-sdk/core";
+
+export default defineSetupPluginEntry(myChannelPlugin);
+```
+
+QuantumClaw loads this instead of the full entry when a channel is disabled,
+unconfigured, or when deferred loading is enabled. See
+[Setup and Config](/plugins/sdk-setup#setup-entry) for when this matters.
+
+## Registration mode
+
+`api.registrationMode` tells your plugin how it was loaded:
+
+| Mode              | When                              | What to register              |
+| ----------------- | --------------------------------- | ----------------------------- |
+| `"full"`          | Normal gateway startup            | Everything                    |
+| `"setup-only"`    | Disabled/unconfigured channel     | Channel registration only     |
+| `"setup-runtime"` | Setup flow with runtime available | Channel + lightweight runtime |
+
+`defineChannelPluginEntry` handles this split automatically. If you use
+`definePluginEntry` directly for a channel, check mode yourself:
+
+```typescript
+register(api) {
+  api.registerChannel({ plugin: myPlugin });
+  if (api.registrationMode !== "full") return;
+
+  // Heavy runtime-only registrations
+  api.registerCli(/* ... */);
+  api.registerService(/* ... */);
+}
+```
+
+## Plugin shapes
+
+QuantumClaw classifies loaded plugins by their registration behavior:
+
+| Shape                 | Description                                        |
+| --------------------- | -------------------------------------------------- |
+| **plain-capability**  | One capability type (e.g. provider-only)           |
+| **hybrid-capability** | Multiple capability types (e.g. provider + speech) |
+| **hook-only**         | Only hooks, no capabilities                        |
+| **non-capability**    | Tools/commands/services but no capabilities        |
+
+Use `quantumclaw plugins inspect <id>` to see a plugin's shape.
+
+## Related
+
+- [SDK Overview](/plugins/sdk-overview) — registration API and subpath reference
+- [Runtime Helpers](/plugins/sdk-runtime) — `api.runtime` and `createPluginRuntimeStore`
+- [Setup and Config](/plugins/sdk-setup) — manifest, setup entry, deferred loading
+- [Channel Plugins](/plugins/sdk-channel-plugins) — building the `ChannelPlugin` object
+- [Provider Plugins](/plugins/sdk-provider-plugins) — provider registration and hooks

package/docs/plugins/sdk-migration.md

@@ -0,0 +1,172 @@
+---
+title: "Plugin SDK Migration"
+sidebarTitle: "Migrate to SDK"
+summary: "Migrate from the legacy backwards-compatibility layer to the modern plugin SDK"
+read_when:
+  - You see the QUANTUMCLAW_PLUGIN_SDK_COMPAT_DEPRECATED warning
+  - You see the QUANTUMCLAW_EXTENSION_API_DEPRECATED warning
+  - You are updating a plugin to the modern plugin architecture
+  - You maintain an external QuantumClaw plugin
+---
+
+# Plugin SDK Migration
+
+QuantumClaw has moved from a broad backwards-compatibility layer to a modern plugin
+architecture with focused, documented imports. If your plugin was built before
+the new architecture, this guide helps you migrate.
+
+## What is changing
+
+The old plugin system provided two wide-open surfaces that let plugins import
+anything they needed from a single entry point:
+
+- **`quantumclaw/plugin-sdk/compat`** — a single import that re-exported dozens of
+  helpers. It was introduced to keep older hook-based plugins working while the
+  new plugin architecture was being built.
+- **`quantumclaw/extension-api`** — a bridge that gave plugins direct access to
+  host-side helpers like the embedded agent runner.
+
+Both surfaces are now **deprecated**. They still work at runtime, but new
+plugins must not use them, and existing plugins should migrate before the next
+major release removes them.
+
+<Warning>
+  The backwards-compatibility layer will be removed in a future major release.
+  Plugins that still import from these surfaces will break when that happens.
+</Warning>
+
+## Why this changed
+
+The old approach caused problems:
+
+- **Slow startup** — importing one helper loaded dozens of unrelated modules
+- **Circular dependencies** — broad re-exports made it easy to create import cycles
+- **Unclear API surface** — no way to tell which exports were stable vs internal
+
+The modern plugin SDK fixes this: each import path (`quantumclaw/plugin-sdk/\<subpath\>`)
+is a small, self-contained module with a clear purpose and documented contract.
+
+## How to migrate
+
+<Steps>
+  <Step title="Find deprecated imports">
+    Search your plugin for imports from either deprecated surface:
+
+    ```bash
+    grep -r "plugin-sdk/compat" my-plugin/
+    grep -r "quantumclaw/extension-api" my-plugin/
+    ```
+
+  </Step>
+
+  <Step title="Replace with focused imports">
+    Each export from the old surface maps to a specific modern import path:
+
+    ```typescript
+    // Before (deprecated backwards-compatibility layer)
+    import {
+      createChannelReplyPipeline,
+      createPluginRuntimeStore,
+      resolveControlCommandGate,
+    } from "quantumclaw/plugin-sdk/compat";
+
+    // After (modern focused imports)
+    import { createChannelReplyPipeline } from "quantumclaw/plugin-sdk/channel-reply-pipeline";
+    import { createPluginRuntimeStore } from "quantumclaw/plugin-sdk/runtime-store";
+    import { resolveControlCommandGate } from "quantumclaw/plugin-sdk/command-auth";
+    ```
+
+    For host-side helpers, use the injected plugin runtime instead of importing
+    directly:
+
+    ```typescript
+    // Before (deprecated extension-api bridge)
+    import { runEmbeddedPiAgent } from "quantumclaw/extension-api";
+    const result = await runEmbeddedPiAgent({ sessionId, prompt });
+
+    // After (injected runtime)
+    const result = await api.runtime.agent.runEmbeddedPiAgent({ sessionId, prompt });
+    ```
+
+    The same pattern applies to other legacy bridge helpers:
+
+    | Old import | Modern equivalent |
+    | --- | --- |
+    | `resolveAgentDir` | `api.runtime.agent.resolveAgentDir` |
+    | `resolveAgentWorkspaceDir` | `api.runtime.agent.resolveAgentWorkspaceDir` |
+    | `resolveAgentIdentity` | `api.runtime.agent.resolveAgentIdentity` |
+    | `resolveThinkingDefault` | `api.runtime.agent.resolveThinkingDefault` |
+    | `resolveAgentTimeoutMs` | `api.runtime.agent.resolveAgentTimeoutMs` |
+    | `ensureAgentWorkspace` | `api.runtime.agent.ensureAgentWorkspace` |
+    | session store helpers | `api.runtime.agent.session.*` |
+
+  </Step>
+
+  <Step title="Build and test">
+    ```bash
+    pnpm build
+    pnpm test -- my-plugin/
+    ```
+  </Step>
+</Steps>
+
+## Import path reference
+
+<Accordion title="Full import path table">
+  | Import path | Purpose | Key exports |
+  | --- | --- | --- |
+  | `plugin-sdk/plugin-entry` | Canonical plugin entry helper | `definePluginEntry` |
+  | `plugin-sdk/core` | Channel entry definitions, channel builders, base types | `defineChannelPluginEntry`, `createChatChannelPlugin` |
+  | `plugin-sdk/channel-setup` | Setup wizard adapters | `createOptionalChannelSetupSurface` |
+  | `plugin-sdk/channel-pairing` | DM pairing primitives | `createChannelPairingController` |
+  | `plugin-sdk/channel-reply-pipeline` | Reply prefix + typing wiring | `createChannelReplyPipeline` |
+  | `plugin-sdk/channel-config-helpers` | Config adapter factories | `createHybridChannelConfigAdapter` |
+  | `plugin-sdk/channel-config-schema` | Config schema builders | Channel config schema types |
+  | `plugin-sdk/channel-policy` | Group/DM policy resolution | `resolveChannelGroupRequireMention` |
+  | `plugin-sdk/channel-lifecycle` | Account status tracking | `createAccountStatusSink` |
+  | `plugin-sdk/channel-runtime` | Runtime wiring helpers | Channel runtime utilities |
+  | `plugin-sdk/channel-send-result` | Send result types | Reply result types |
+  | `plugin-sdk/runtime-store` | Persistent plugin storage | `createPluginRuntimeStore` |
+  | `plugin-sdk/allow-from` | Allowlist formatting | `formatAllowFromLowercase` |
+  | `plugin-sdk/allowlist-resolution` | Allowlist input mapping | `mapAllowlistResolutionInputs` |
+  | `plugin-sdk/command-auth` | Command gating | `resolveControlCommandGate` |
+  | `plugin-sdk/secret-input` | Secret input parsing | Secret input helpers |
+  | `plugin-sdk/webhook-ingress` | Webhook request helpers | Webhook target utilities |
+  | `plugin-sdk/reply-payload` | Message reply types | Reply payload types |
+  | `plugin-sdk/provider-onboard` | Provider onboarding patches | Onboarding config helpers |
+  | `plugin-sdk/keyed-async-queue` | Ordered async queue | `KeyedAsyncQueue` |
+  | `plugin-sdk/testing` | Test utilities | Test helpers and mocks |
+</Accordion>
+
+Use the narrowest import that matches the job. If you cannot find an export,
+check the source at `src/plugin-sdk/` or ask in Discord.
+
+## Removal timeline
+
+| When                   | What happens                                                            |
+| ---------------------- | ----------------------------------------------------------------------- |
+| **Now**                | Deprecated surfaces emit runtime warnings                               |
+| **Next major release** | Deprecated surfaces will be removed; plugins still using them will fail |
+
+All core plugins have already been migrated. External plugins should migrate
+before the next major release.
+
+## Suppressing the warnings temporarily
+
+Set these environment variables while you work on migrating:
+
+```bash
+QUANTUMCLAW_SUPPRESS_PLUGIN_SDK_COMPAT_WARNING=1 quantumclaw gateway run
+QUANTUMCLAW_SUPPRESS_EXTENSION_API_WARNING=1 quantumclaw gateway run
+```
+
+This is a temporary escape hatch, not a permanent solution.
+
+## Related
+
+- [Getting Started](/plugins/building-plugins) — build your first plugin
+- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
+- [Channel Plugins](/plugins/sdk-channel-plugins) — building channel plugins
+- [Provider Plugins](/plugins/sdk-provider-plugins) — building provider plugins
+- [Plugin Internals](/plugins/architecture) — architecture deep dive
+- [Plugin Manifest](/plugins/manifest) — manifest schema reference

package/docs/plugins/sdk-overview.md

@@ -0,0 +1,196 @@
+---
+title: "Plugin SDK Overview"
+sidebarTitle: "SDK Overview"
+summary: "Import map, registration API reference, and SDK architecture"
+read_when:
+  - You need to know which SDK subpath to import from
+  - You want a reference for all registration methods on QuantumClawPluginApi
+  - You are looking up a specific SDK export
+---
+
+# Plugin SDK Overview
+
+The plugin SDK is the typed contract between plugins and core. This page is the
+reference for **what to import** and **what you can register**.
+
+<Tip>
+  **Looking for a how-to guide?**
+  - First plugin? Start with [Getting Started](/plugins/building-plugins)
+  - Channel plugin? See [Channel Plugins](/plugins/sdk-channel-plugins)
+  - Provider plugin? See [Provider Plugins](/plugins/sdk-provider-plugins)
+</Tip>
+
+## Import convention
+
+Always import from a specific subpath:
+
+```typescript
+import { definePluginEntry } from "quantumclaw/plugin-sdk/plugin-entry";
+import { defineChannelPluginEntry } from "quantumclaw/plugin-sdk/core";
+
+// Deprecated — will be removed in the next major release
+import { definePluginEntry } from "quantumclaw/plugin-sdk";
+```
+
+Each subpath is a small, self-contained module. This keeps startup fast and
+prevents circular dependency issues.
+
+## Subpath reference
+
+The most commonly used subpaths, grouped by purpose. The full list of 100+
+subpaths is in `scripts/lib/plugin-sdk-entrypoints.json`.
+
+### Plugin entry
+
+| Subpath                   | Key exports                                                                                                                            |
+| ------------------------- | -------------------------------------------------------------------------------------------------------------------------------------- |
+| `plugin-sdk/plugin-entry` | `definePluginEntry`                                                                                                                    |
+| `plugin-sdk/core`         | `defineChannelPluginEntry`, `createChatChannelPlugin`, `createChannelPluginBase`, `defineSetupPluginEntry`, `buildChannelConfigSchema` |
+
+<AccordionGroup>
+  <Accordion title="Channel subpaths">
+    | Subpath | Key exports |
+    | --- | --- |
+    | `plugin-sdk/channel-setup` | `createOptionalChannelSetupSurface` |
+    | `plugin-sdk/channel-pairing` | `createChannelPairingController` |
+    | `plugin-sdk/channel-reply-pipeline` | `createChannelReplyPipeline` |
+    | `plugin-sdk/channel-config-helpers` | `createHybridChannelConfigAdapter` |
+    | `plugin-sdk/channel-config-schema` | Channel config schema types |
+    | `plugin-sdk/channel-policy` | `resolveChannelGroupRequireMention` |
+    | `plugin-sdk/channel-lifecycle` | `createAccountStatusSink` |
+    | `plugin-sdk/channel-inbound` | Debounce, mention matching, envelope helpers |
+    | `plugin-sdk/channel-send-result` | Reply result types |
+    | `plugin-sdk/channel-actions` | `createMessageToolButtonsSchema`, `createMessageToolCardSchema` |
+    | `plugin-sdk/channel-targets` | Target parsing/matching helpers |
+    | `plugin-sdk/channel-contract` | Channel contract types |
+    | `plugin-sdk/channel-feedback` | Feedback/reaction wiring |
+  </Accordion>
+
+  <Accordion title="Provider subpaths">
+    | Subpath | Key exports |
+    | --- | --- |
+    | `plugin-sdk/provider-auth` | `createProviderApiKeyAuthMethod`, `ensureApiKeyFromOptionEnvOrPrompt`, `upsertAuthProfile` |
+    | `plugin-sdk/provider-models` | `normalizeModelCompat` |
+    | `plugin-sdk/provider-catalog` | Catalog type re-exports |
+    | `plugin-sdk/provider-usage` | `fetchClaudeUsage` and similar |
+    | `plugin-sdk/provider-stream` | Stream wrapper types |
+    | `plugin-sdk/provider-onboard` | Onboarding config patch helpers |
+  </Accordion>
+
+  <Accordion title="Auth and security subpaths">
+    | Subpath | Key exports |
+    | --- | --- |
+    | `plugin-sdk/command-auth` | `resolveControlCommandGate` |
+    | `plugin-sdk/allow-from` | `formatAllowFromLowercase` |
+    | `plugin-sdk/secret-input` | Secret input parsing helpers |
+    | `plugin-sdk/webhook-ingress` | Webhook request/target helpers |
+  </Accordion>
+
+  <Accordion title="Runtime and storage subpaths">
+    | Subpath | Key exports |
+    | --- | --- |
+    | `plugin-sdk/runtime-store` | `createPluginRuntimeStore` |
+    | `plugin-sdk/config-runtime` | Config load/write helpers |
+    | `plugin-sdk/infra-runtime` | System event/heartbeat helpers |
+    | `plugin-sdk/agent-runtime` | Agent dir/identity/workspace helpers |
+    | `plugin-sdk/directory-runtime` | Config-backed directory query/dedup |
+    | `plugin-sdk/keyed-async-queue` | `KeyedAsyncQueue` |
+  </Accordion>
+
+  <Accordion title="Capability and testing subpaths">
+    | Subpath | Key exports |
+    | --- | --- |
+    | `plugin-sdk/image-generation` | Image generation provider types |
+    | `plugin-sdk/media-understanding` | Media understanding provider types |
+    | `plugin-sdk/speech` | Speech provider types |
+    | `plugin-sdk/testing` | `installCommonResolveTargetErrorCases`, `shouldAckReaction` |
+  </Accordion>
+</AccordionGroup>
+
+## Registration API
+
+The `register(api)` callback receives an `QuantumClawPluginApi` object with these
+methods:
+
+### Capability registration
+
+| Method                                        | What it registers              |
+| --------------------------------------------- | ------------------------------ |
+| `api.registerProvider(...)`                   | Text inference (LLM)           |
+| `api.registerChannel(...)`                    | Messaging channel              |
+| `api.registerSpeechProvider(...)`             | Text-to-speech / STT synthesis |
+| `api.registerMediaUnderstandingProvider(...)` | Image/audio/video analysis     |
+| `api.registerImageGenerationProvider(...)`    | Image generation               |
+| `api.registerWebSearchProvider(...)`          | Web search                     |
+
+### Tools and commands
+
+| Method                          | What it registers                             |
+| ------------------------------- | --------------------------------------------- |
+| `api.registerTool(tool, opts?)` | Agent tool (required or `{ optional: true }`) |
+| `api.registerCommand(def)`      | Custom command (bypasses the LLM)             |
+
+### Infrastructure
+
+| Method                                         | What it registers     |
+| ---------------------------------------------- | --------------------- |
+| `api.registerHook(events, handler, opts?)`     | Event hook            |
+| `api.registerHttpRoute(params)`                | Gateway HTTP endpoint |
+| `api.registerGatewayMethod(name, handler)`     | Gateway RPC method    |
+| `api.registerCli(registrar, opts?)`            | CLI subcommand        |
+| `api.registerService(service)`                 | Background service    |
+| `api.registerInteractiveHandler(registration)` | Interactive handler   |
+
+### Exclusive slots
+
+| Method                                     | What it registers                     |
+| ------------------------------------------ | ------------------------------------- |
+| `api.registerContextEngine(id, factory)`   | Context engine (one active at a time) |
+| `api.registerMemoryPromptSection(builder)` | Memory prompt section builder         |
+
+### Events and lifecycle
+
+| Method                                       | What it does                  |
+| -------------------------------------------- | ----------------------------- |
+| `api.on(hookName, handler, opts?)`           | Typed lifecycle hook          |
+| `api.onConversationBindingResolved(handler)` | Conversation binding callback |
+
+### API object fields
+
+| Field                    | Type                      | Description                                               |
+| ------------------------ | ------------------------- | --------------------------------------------------------- |
+| `api.id`                 | `string`                  | Plugin id                                                 |
+| `api.name`               | `string`                  | Display name                                              |
+| `api.config`             | `QuantumClawConfig`          | Current config snapshot                                   |
+| `api.pluginConfig`       | `Record<string, unknown>` | Plugin-specific config from `plugins.entries.<id>.config` |
+| `api.runtime`            | `PluginRuntime`           | [Runtime helpers](/plugins/sdk-runtime)                   |
+| `api.logger`             | `PluginLogger`            | Scoped logger (`debug`, `info`, `warn`, `error`)          |
+| `api.registrationMode`   | `PluginRegistrationMode`  | `"full"`, `"setup-only"`, or `"setup-runtime"`            |
+| `api.resolvePath(input)` | `(string) => string`      | Resolve path relative to plugin root                      |
+
+## Internal module convention
+
+Within your plugin, use local barrel files for internal imports:
+
+```
+my-plugin/
+  api.ts            # Public exports for external consumers
+  runtime-api.ts    # Internal-only runtime exports
+  index.ts          # Plugin entry point
+  setup-entry.ts    # Lightweight setup-only entry (optional)
+```
+
+<Warning>
+  Never import your own plugin through `quantumclaw/plugin-sdk/<your-plugin>`
+  from production code. Route internal imports through `./api.ts` or
+  `./runtime-api.ts`. The SDK path is the external contract only.
+</Warning>
+
+## Related
+
+- [Entry Points](/plugins/sdk-entrypoints) — `definePluginEntry` and `defineChannelPluginEntry` options
+- [Runtime Helpers](/plugins/sdk-runtime) — full `api.runtime` namespace reference
+- [Setup and Config](/plugins/sdk-setup) — packaging, manifests, config schemas
+- [Testing](/plugins/sdk-testing) — test utilities and lint rules
+- [SDK Migration](/plugins/sdk-migration) — migrating from deprecated surfaces
+- [Plugin Internals](/plugins/architecture) — deep architecture and capability model