durar-ai 2026.4.4

package/docs/plugins/sdk-runtime.md

@@ -0,0 +1,381 @@
+---
+title: "Plugin Runtime Helpers"
+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
+const agentDir = api.runtime.agent.resolveAgentDir(cfg);
+const result = await api.runtime.agent.runEmbeddedPiAgent({
+  sessionId: "my-plugin:task-1",
+  runId: crypto.randomUUID(),
+  sessionFile: path.join(agentDir, "sessions", "my-plugin-task-1.jsonl"),
+  workspaceDir: api.runtime.agent.resolveAgentWorkspaceDir(cfg),
+  prompt: "Summarize the latest changes",
+  timeoutMs: api.runtime.agent.resolveAgentTimeoutMs(cfg),
+});
+```
+
+**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.taskFlow`
+
+Bind a Task Flow runtime to an existing Durar session key or trusted tool
+context, then create and manage Task Flows without passing an owner on every call.
+
+```typescript
+const taskFlow = api.runtime.taskFlow.fromToolContext(ctx);
+
+const created = taskFlow.createManaged({
+  controllerId: "my-plugin/review-batch",
+  goal: "Review new pull requests",
+});
+
+const child = taskFlow.runTask({
+  flowId: created.flowId,
+  runtime: "acp",
+  childSessionKey: "agent:main:subagent:reviewer",
+  task: "Review PR #123",
+  status: "running",
+  startedAt: Date.now(),
+});
+
+const waiting = taskFlow.setWaiting({
+  flowId: created.flowId,
+  expectedRevision: created.revision,
+  currentStep: "await-human-reply",
+  waitJson: { kind: "reply", channel: "telegram" },
+});
+```
+
+Use `bindSession({ sessionKey, requesterOrigin })` when you already have a
+trusted Durar session key from your own binding layer. Do not bind from raw
+user input.
+
+### `api.runtime.tts`
+
+Text-to-speech synthesis.
+
+```typescript
+// Standard TTS
+const clip = await api.runtime.tts.textToSpeech({
+  text: "Hello from Durar",
+  cfg: api.config,
+});
+
+// Telephony-optimized TTS
+const telephonyClip = await api.runtime.tts.textToSpeechTelephony({
+  text: "Hello from Durar",
+  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: "Durar 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 "Durar/plugin-sdk/runtime-store";
+import type { PluginRuntime } from "Durar/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`             | `DurarConfig`          | Current config snapshot (active in-memory runtime snapshot when available)                  |
+| `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`  | Current load mode; `"setup-runtime"` is the lightweight pre-full-entry startup/setup window |
+| `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