@quantumclaw/quantumclaw 2026.3.22

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

@@ -0,0 +1,370 @@
+---
+title: "Building Provider Plugins"
+sidebarTitle: "Provider Plugins"
+summary: "Step-by-step guide to building a model provider plugin for QuantumClaw"
+read_when:
+  - You are building a new model provider plugin
+  - You want to add an OpenAI-compatible proxy or custom LLM to QuantumClaw
+  - You need to understand provider auth, catalogs, and runtime hooks
+---
+
+# Building Provider Plugins
+
+This guide walks through building a provider plugin that adds a model provider
+(LLM) to QuantumClaw. By the end you will have a provider with a model catalog,
+API key auth, and dynamic model resolution.
+
+<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>
+
+## Walkthrough
+
+<Steps>
+  <Step title="Package and manifest">
+    <CodeGroup>
+    ```json package.json
+    {
+      "name": "@myorg/quantumclaw-acme-ai",
+      "version": "1.0.0",
+      "type": "module",
+      "quantumclaw": {
+        "extensions": ["./index.ts"],
+        "providers": ["acme-ai"]
+      }
+    }
+    ```
+
+    ```json quantumclaw.plugin.json
+    {
+      "id": "acme-ai",
+      "name": "Acme AI",
+      "description": "Acme AI model provider",
+      "providers": ["acme-ai"],
+      "providerAuthEnvVars": {
+        "acme-ai": ["ACME_AI_API_KEY"]
+      },
+      "providerAuthChoices": [
+        {
+          "provider": "acme-ai",
+          "method": "api-key",
+          "choiceId": "acme-ai-api-key",
+          "choiceLabel": "Acme AI API key",
+          "groupId": "acme-ai",
+          "groupLabel": "Acme AI",
+          "cliFlag": "--acme-ai-api-key",
+          "cliOption": "--acme-ai-api-key <key>",
+          "cliDescription": "Acme AI API key"
+        }
+      ],
+      "configSchema": {
+        "type": "object",
+        "additionalProperties": false
+      }
+    }
+    ```
+    </CodeGroup>
+
+    The manifest declares `providerAuthEnvVars` so QuantumClaw can detect
+    credentials without loading your plugin runtime.
+
+  </Step>
+
+  <Step title="Register the provider">
+    A minimal provider needs an `id`, `label`, `auth`, and `catalog`:
+
+    ```typescript index.ts
+    import { definePluginEntry } from "quantumclaw/plugin-sdk/plugin-entry";
+    import { createProviderApiKeyAuthMethod } from "quantumclaw/plugin-sdk/provider-auth";
+
+    export default definePluginEntry({
+      id: "acme-ai",
+      name: "Acme AI",
+      description: "Acme AI model provider",
+      register(api) {
+        api.registerProvider({
+          id: "acme-ai",
+          label: "Acme AI",
+          docsPath: "/providers/acme-ai",
+          envVars: ["ACME_AI_API_KEY"],
+
+          auth: [
+            createProviderApiKeyAuthMethod({
+              providerId: "acme-ai",
+              methodId: "api-key",
+              label: "Acme AI API key",
+              hint: "API key from your Acme AI dashboard",
+              optionKey: "acmeAiApiKey",
+              flagName: "--acme-ai-api-key",
+              envVar: "ACME_AI_API_KEY",
+              promptMessage: "Enter your Acme AI API key",
+              defaultModel: "acme-ai/acme-large",
+            }),
+          ],
+
+          catalog: {
+            order: "simple",
+            run: async (ctx) => {
+              const apiKey =
+                ctx.resolveProviderApiKey("acme-ai").apiKey;
+              if (!apiKey) return null;
+              return {
+                provider: {
+                  baseUrl: "https://api.acme-ai.com/v1",
+                  apiKey,
+                  api: "openai-completions",
+                  models: [
+                    {
+                      id: "acme-large",
+                      name: "Acme Large",
+                      reasoning: true,
+                      input: ["text", "image"],
+                      cost: { input: 3, output: 15, cacheRead: 0.3, cacheWrite: 3.75 },
+                      contextWindow: 200000,
+                      maxTokens: 32768,
+                    },
+                    {
+                      id: "acme-small",
+                      name: "Acme Small",
+                      reasoning: false,
+                      input: ["text"],
+                      cost: { input: 1, output: 5, cacheRead: 0.1, cacheWrite: 1.25 },
+                      contextWindow: 128000,
+                      maxTokens: 8192,
+                    },
+                  ],
+                },
+              };
+            },
+          },
+        });
+      },
+    });
+    ```
+
+    That is a working provider. Users can now
+    `quantumclaw onboard --acme-ai-api-key <key>` and select
+    `acme-ai/acme-large` as their model.
+
+  </Step>
+
+  <Step title="Add dynamic model resolution">
+    If your provider accepts arbitrary model IDs (like a proxy or router),
+    add `resolveDynamicModel`:
+
+    ```typescript
+    api.registerProvider({
+      // ... id, label, auth, catalog from above
+
+      resolveDynamicModel: (ctx) => ({
+        id: ctx.modelId,
+        name: ctx.modelId,
+        provider: "acme-ai",
+        api: "openai-completions",
+        baseUrl: "https://api.acme-ai.com/v1",
+        reasoning: false,
+        input: ["text"],
+        cost: { input: 0, output: 0, cacheRead: 0, cacheWrite: 0 },
+        contextWindow: 128000,
+        maxTokens: 8192,
+      }),
+    });
+    ```
+
+    If resolving requires a network call, use `prepareDynamicModel` for async
+    warm-up — `resolveDynamicModel` runs again after it completes.
+
+  </Step>
+
+  <Step title="Add runtime hooks (as needed)">
+    Most providers only need `catalog` + `resolveDynamicModel`. Add hooks
+    incrementally as your provider requires them.
+
+    <Tabs>
+      <Tab title="Token exchange">
+        For providers that need a token exchange before each inference call:
+
+        ```typescript
+        prepareRuntimeAuth: async (ctx) => {
+          const exchanged = await exchangeToken(ctx.apiKey);
+          return {
+            apiKey: exchanged.token,
+            baseUrl: exchanged.baseUrl,
+            expiresAt: exchanged.expiresAt,
+          };
+        },
+        ```
+      </Tab>
+      <Tab title="Custom headers">
+        For providers that need custom request headers or body modifications:
+
+        ```typescript
+        // wrapStreamFn returns a StreamFn derived from ctx.streamFn
+        wrapStreamFn: (ctx) => {
+          if (!ctx.streamFn) return undefined;
+          const inner = ctx.streamFn;
+          return async (params) => {
+            params.headers = {
+              ...params.headers,
+              "X-Acme-Version": "2",
+            };
+            return inner(params);
+          };
+        },
+        ```
+      </Tab>
+      <Tab title="Usage and billing">
+        For providers that expose usage/billing data:
+
+        ```typescript
+        resolveUsageAuth: async (ctx) => {
+          const auth = await ctx.resolveOAuthToken();
+          return auth ? { token: auth.token } : null;
+        },
+        fetchUsageSnapshot: async (ctx) => {
+          return await fetchAcmeUsage(ctx.token, ctx.timeoutMs);
+        },
+        ```
+      </Tab>
+    </Tabs>
+
+    <Accordion title="All 21 available hooks">
+      QuantumClaw calls hooks in this order. Most providers only use 2-3:
+
+      | # | Hook | When to use |
+      | --- | --- | --- |
+      | 1 | `catalog` | Model catalog or base URL defaults |
+      | 2 | `resolveDynamicModel` | Accept arbitrary upstream model IDs |
+      | 3 | `prepareDynamicModel` | Async metadata fetch before resolving |
+      | 4 | `normalizeResolvedModel` | Transport rewrites before the runner |
+      | 5 | `capabilities` | Transcript/tooling metadata |
+      | 6 | `prepareExtraParams` | Default request params |
+      | 7 | `wrapStreamFn` | Custom headers/body wrappers |
+      | 8 | `formatApiKey` | Custom runtime token shape |
+      | 9 | `refreshOAuth` | Custom OAuth refresh |
+      | 10 | `buildAuthDoctorHint` | Auth repair guidance |
+      | 11 | `isCacheTtlEligible` | Prompt cache TTL gating |
+      | 12 | `buildMissingAuthMessage` | Custom missing-auth hint |
+      | 13 | `suppressBuiltInModel` | Hide stale upstream rows |
+      | 14 | `augmentModelCatalog` | Synthetic forward-compat rows |
+      | 15 | `isBinaryThinking` | Binary thinking on/off |
+      | 16 | `supportsXHighThinking` | `xhigh` reasoning support |
+      | 17 | `resolveDefaultThinkingLevel` | Default `/think` policy |
+      | 18 | `isModernModelRef` | Live/smoke model matching |
+      | 19 | `prepareRuntimeAuth` | Token exchange before inference |
+      | 20 | `resolveUsageAuth` | Custom usage credential parsing |
+      | 21 | `fetchUsageSnapshot` | Custom usage endpoint |
+
+      For detailed descriptions and real-world examples, see
+      [Internals: Provider Runtime Hooks](/plugins/architecture#provider-runtime-hooks).
+    </Accordion>
+
+  </Step>
+
+  <Step title="Add extra capabilities (optional)">
+    A provider plugin can register speech, media understanding, image
+    generation, and web search alongside text inference:
+
+    ```typescript
+    register(api) {
+      api.registerProvider({ id: "acme-ai", /* ... */ });
+
+      api.registerSpeechProvider({
+        id: "acme-ai",
+        label: "Acme Speech",
+        isConfigured: ({ config }) => Boolean(config.messages?.tts),
+        synthesize: async (req) => ({
+          audioBuffer: Buffer.from(/* PCM data */),
+          outputFormat: "mp3",
+          fileExtension: ".mp3",
+          voiceCompatible: false,
+        }),
+      });
+
+      api.registerMediaUnderstandingProvider({
+        id: "acme-ai",
+        capabilities: ["image", "audio"],
+        describeImage: async (req) => ({ text: "A photo of..." }),
+        transcribeAudio: async (req) => ({ text: "Transcript..." }),
+      });
+
+      api.registerImageGenerationProvider({
+        id: "acme-ai",
+        label: "Acme Images",
+        generate: async (req) => ({ /* image result */ }),
+      });
+    }
+    ```
+
+    QuantumClaw classifies this as a **hybrid-capability** plugin. This is the
+    recommended pattern for company plugins (one plugin per vendor). See
+    [Internals: Capability Ownership](/plugins/architecture#capability-ownership-model).
+
+  </Step>
+
+  <Step title="Test">
+    ```typescript src/provider.test.ts
+    import { describe, it, expect } from "vitest";
+    // Export your provider config object from index.ts or a dedicated file
+    import { acmeProvider } from "./provider.js";
+
+    describe("acme-ai provider", () => {
+      it("resolves dynamic models", () => {
+        const model = acmeProvider.resolveDynamicModel!({
+          modelId: "acme-beta-v3",
+        } as any);
+        expect(model.id).toBe("acme-beta-v3");
+        expect(model.provider).toBe("acme-ai");
+      });
+
+      it("returns catalog when key is available", async () => {
+        const result = await acmeProvider.catalog!.run({
+          resolveProviderApiKey: () => ({ apiKey: "test-key" }),
+        } as any);
+        expect(result?.provider?.models).toHaveLength(2);
+      });
+
+      it("returns null catalog when no key", async () => {
+        const result = await acmeProvider.catalog!.run({
+          resolveProviderApiKey: () => ({ apiKey: undefined }),
+        } as any);
+        expect(result).toBeNull();
+      });
+    });
+    ```
+
+  </Step>
+</Steps>
+
+## File structure
+
+```
+extensions/acme-ai/
+├── package.json              # quantumclaw.providers metadata
+├── quantumclaw.plugin.json      # Manifest with providerAuthEnvVars
+├── index.ts                  # definePluginEntry + registerProvider
+└── src/
+    ├── provider.test.ts      # Tests
+    └── usage.ts              # Usage endpoint (optional)
+```
+
+## Catalog order reference
+
+`catalog.order` controls when your catalog merges relative to built-in
+providers:
+
+| Order     | When          | Use case                                        |
+| --------- | ------------- | ----------------------------------------------- |
+| `simple`  | First pass    | Plain API-key providers                         |
+| `profile` | After simple  | Providers gated on auth profiles                |
+| `paired`  | After profile | Synthesize multiple related entries             |
+| `late`    | Last pass     | Override existing providers (wins on collision) |
+
+## Next steps
+
+- [Channel Plugins](/plugins/sdk-channel-plugins) — if your plugin also provides a channel
+- [SDK Runtime](/plugins/sdk-runtime) — `api.runtime` helpers (TTS, search, subagent)
+- [SDK Overview](/plugins/sdk-overview) — full subpath import reference
+- [Plugin Internals](/plugins/architecture#provider-runtime-hooks) — hook details and bundled examples

package/docs/plugins/sdk-runtime.md

@@ -0,0 +1,345 @@
+---
+title: "Plugin SDK Runtime"
+sidebarTitle: "Runtime Helpers"
+summary: "api.runtime -- the injected runtime helpers available to plugins"
+read_when:
+  - You need to call core helpers from a plugin (TTS, STT, image gen, web search, subagent)
+  - You want to understand what api.runtime exposes
+  - You are accessing config, agent, or media helpers from plugin code
+---
+
+# Plugin Runtime Helpers
+
+Reference for the `api.runtime` object injected into every plugin during
+registration. Use these helpers instead of importing host internals directly.
+
+<Tip>
+  **Looking for a walkthrough?** See [Channel Plugins](/plugins/sdk-channel-plugins)
+  or [Provider Plugins](/plugins/sdk-provider-plugins) for step-by-step guides
+  that show these helpers in context.
+</Tip>
+
+```typescript
+register(api) {
+  const runtime = api.runtime;
+}
+```
+
+## Runtime namespaces
+
+### `api.runtime.agent`
+
+Agent identity, directories, and session management.
+
+```typescript
+// Resolve the agent's working directory
+const agentDir = api.runtime.agent.resolveAgentDir(cfg);
+
+// Resolve agent workspace
+const workspaceDir = api.runtime.agent.resolveAgentWorkspaceDir(cfg);
+
+// Get agent identity
+const identity = api.runtime.agent.resolveAgentIdentity(cfg);
+
+// Get default thinking level
+const thinking = api.runtime.agent.resolveThinkingDefault(cfg, provider, model);
+
+// Get agent timeout
+const timeoutMs = api.runtime.agent.resolveAgentTimeoutMs(cfg);
+
+// Ensure workspace exists
+await api.runtime.agent.ensureAgentWorkspace(cfg);
+
+// Run an embedded Pi agent (requires sessionFile + workspaceDir at minimum)
+const agentDir = api.runtime.agent.resolveAgentDir(cfg);
+const result = await api.runtime.agent.runEmbeddedPiAgent({
+  sessionId: "my-plugin:task-1",
+  sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
+  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
+  prompt: "Summarize the latest changes",
+});
+```
+
+**Session store helpers** are under `api.runtime.agent.session`:
+
+```typescript
+const storePath = api.runtime.agent.session.resolveStorePath(cfg);
+const store = api.runtime.agent.session.loadSessionStore(cfg);
+await api.runtime.agent.session.saveSessionStore(cfg, store);
+const filePath = api.runtime.agent.session.resolveSessionFilePath(cfg, sessionId);
+```
+
+### `api.runtime.agent.defaults`
+
+Default model and provider constants:
+
+```typescript
+const model = api.runtime.agent.defaults.model; // e.g. "anthropic/claude-sonnet-4-6"
+const provider = api.runtime.agent.defaults.provider; // e.g. "anthropic"
+```
+
+### `api.runtime.subagent`
+
+Launch and manage background subagent runs.
+
+```typescript
+// Start a subagent run
+const { runId } = await api.runtime.subagent.run({
+  sessionKey: "agent:main:subagent:search-helper",
+  message: "Expand this query into focused follow-up searches.",
+  provider: "openai", // optional override
+  model: "gpt-4.1-mini", // optional override
+  deliver: false,
+});
+
+// Wait for completion
+const result = await api.runtime.subagent.waitForRun({ runId, timeoutMs: 30000 });
+
+// Read session messages
+const { messages } = await api.runtime.subagent.getSessionMessages({
+  sessionKey: "agent:main:subagent:search-helper",
+  limit: 10,
+});
+
+// Delete a session
+await api.runtime.subagent.deleteSession({
+  sessionKey: "agent:main:subagent:search-helper",
+});
+```
+
+<Warning>
+  Model overrides (`provider`/`model`) require operator opt-in via
+  `plugins.entries.<id>.subagent.allowModelOverride: true` in config.
+  Untrusted plugins can still run subagents, but override requests are rejected.
+</Warning>
+
+### `api.runtime.tts`
+
+Text-to-speech synthesis.
+
+```typescript
+// Standard TTS
+const clip = await api.runtime.tts.textToSpeech({
+  text: "Hello from QuantumClaw",
+  cfg: api.config,
+});
+
+// Telephony-optimized TTS
+const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
+  text: "Hello from QuantumClaw",
+  cfg: api.config,
+});
+
+// List available voices
+const voices = await api.runtime.tts.listVoices({
+  provider: "elevenlabs",
+  cfg: api.config,
+});
+```
+
+Uses core `messages.tts` configuration and provider selection. Returns PCM audio
+buffer + sample rate.
+
+### `api.runtime.mediaUnderstanding`
+
+Image, audio, and video analysis.
+
+```typescript
+// Describe an image
+const image = await api.runtime.mediaUnderstanding.describeImageFile({
+  filePath: "/tmp/inbound-photo.jpg",
+  cfg: api.config,
+  agentDir: "/tmp/agent",
+});
+
+// Transcribe audio
+const { text } = await api.runtime.mediaUnderstanding.transcribeAudioFile({
+  filePath: "/tmp/inbound-audio.ogg",
+  cfg: api.config,
+  mime: "audio/ogg", // optional, for when MIME cannot be inferred
+});
+
+// Describe a video
+const video = await api.runtime.mediaUnderstanding.describeVideoFile({
+  filePath: "/tmp/inbound-video.mp4",
+  cfg: api.config,
+});
+
+// Generic file analysis
+const result = await api.runtime.mediaUnderstanding.runFile({
+  filePath: "/tmp/inbound-file.pdf",
+  cfg: api.config,
+});
+```
+
+Returns `{ text: undefined }` when no output is produced (e.g. skipped input).
+
+<Info>
+  `api.runtime.stt.transcribeAudioFile(...)` remains as a compatibility alias
+  for `api.runtime.mediaUnderstanding.transcribeAudioFile(...)`.
+</Info>
+
+### `api.runtime.imageGeneration`
+
+Image generation.
+
+```typescript
+const result = await api.runtime.imageGeneration.generate({
+  prompt: "A robot painting a sunset",
+  cfg: api.config,
+});
+
+const providers = api.runtime.imageGeneration.listProviders({ cfg: api.config });
+```
+
+### `api.runtime.webSearch`
+
+Web search.
+
+```typescript
+const providers = api.runtime.webSearch.listProviders({ config: api.config });
+
+const result = await api.runtime.webSearch.search({
+  config: api.config,
+  args: { query: "QuantumClaw plugin SDK", count: 5 },
+});
+```
+
+### `api.runtime.media`
+
+Low-level media utilities.
+
+```typescript
+const webMedia = await api.runtime.media.loadWebMedia(url);
+const mime = await api.runtime.media.detectMime(buffer);
+const kind = api.runtime.media.mediaKindFromMime("image/jpeg"); // "image"
+const isVoice = api.runtime.media.isVoiceCompatibleAudio(filePath);
+const metadata = await api.runtime.media.getImageMetadata(filePath);
+const resized = await api.runtime.media.resizeToJpeg(buffer, { maxWidth: 800 });
+```
+
+### `api.runtime.config`
+
+Config load and write.
+
+```typescript
+const cfg = await api.runtime.config.loadConfig();
+await api.runtime.config.writeConfigFile(cfg);
+```
+
+### `api.runtime.system`
+
+System-level utilities.
+
+```typescript
+await api.runtime.system.enqueueSystemEvent(event);
+api.runtime.system.requestHeartbeatNow();
+const output = await api.runtime.system.runCommandWithTimeout(cmd, args, opts);
+const hint = api.runtime.system.formatNativeDependencyHint(pkg);
+```
+
+### `api.runtime.events`
+
+Event subscriptions.
+
+```typescript
+api.runtime.events.onAgentEvent((event) => {
+  /* ... */
+});
+api.runtime.events.onSessionTranscriptUpdate((update) => {
+  /* ... */
+});
+```
+
+### `api.runtime.logging`
+
+Logging.
+
+```typescript
+const verbose = api.runtime.logging.shouldLogVerbose();
+const childLogger = api.runtime.logging.getChildLogger({ plugin: "my-plugin" }, { level: "debug" });
+```
+
+### `api.runtime.modelAuth`
+
+Model and provider auth resolution.
+
+```typescript
+const auth = await api.runtime.modelAuth.getApiKeyForModel({ model, cfg });
+const providerAuth = await api.runtime.modelAuth.resolveApiKeyForProvider({
+  provider: "openai",
+  cfg,
+});
+```
+
+### `api.runtime.state`
+
+State directory resolution.
+
+```typescript
+const stateDir = api.runtime.state.resolveStateDir();
+```
+
+### `api.runtime.tools`
+
+Memory tool factories and CLI.
+
+```typescript
+const getTool = api.runtime.tools.createMemoryGetTool(/* ... */);
+const searchTool = api.runtime.tools.createMemorySearchTool(/* ... */);
+api.runtime.tools.registerMemoryCli(/* ... */);
+```
+
+### `api.runtime.channel`
+
+Channel-specific runtime helpers (available when a channel plugin is loaded).
+
+## Storing runtime references
+
+Use `createPluginRuntimeStore` to store the runtime reference for use outside
+the `register` callback:
+
+```typescript
+import { createPluginRuntimeStore } from "quantumclaw/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "quantumclaw/plugin-sdk/runtime-store";
+
+const store = createPluginRuntimeStore<PluginRuntime>("my-plugin runtime not initialized");
+
+// In your entry point
+export default defineChannelPluginEntry({
+  id: "my-plugin",
+  name: "My Plugin",
+  description: "Example",
+  plugin: myPlugin,
+  setRuntime: store.setRuntime,
+});
+
+// In other files
+export function getRuntime() {
+  return store.getRuntime(); // throws if not initialized
+}
+
+export function tryGetRuntime() {
+  return store.tryGetRuntime(); // returns null if not initialized
+}
+```
+
+## Other top-level `api` fields
+
+Beyond `api.runtime`, the API object also provides:
+
+| Field                    | Type                      | Description                                               |
+| ------------------------ | ------------------------- | --------------------------------------------------------- |
+| `api.id`                 | `string`                  | Plugin id                                                 |
+| `api.name`               | `string`                  | Plugin display name                                       |
+| `api.config`             | `QuantumClawConfig`          | Current config snapshot                                   |
+| `api.pluginConfig`       | `Record<string, unknown>` | Plugin-specific config from `plugins.entries.<id>.config` |
+| `api.logger`             | `PluginLogger`            | Scoped logger (`debug`, `info`, `warn`, `error`)          |
+| `api.registrationMode`   | `PluginRegistrationMode`  | `"full"`, `"setup-only"`, or `"setup-runtime"`            |
+| `api.resolvePath(input)` | `(string) => string`      | Resolve a path relative to the plugin root                |
+
+## Related
+
+- [SDK Overview](/plugins/sdk-overview) -- subpath reference
+- [SDK Entry Points](/plugins/sdk-entrypoints) -- `definePluginEntry` options
+- [Plugin Internals](/plugins/architecture) -- capability model and registry