@makinbakin/sdk 0.0.1-rc.2 → 0.0.1-rc.21

package/_internal/core/adapters/runtime/concepts.d.ts

@@ -1,11 +1,15 @@
-import type { AdapterHealthCheckDefinition, AdapterInitOpts, Unsubscribe } from '../shared';
+import type { AdapterInitOpts, MessageUsage, RuntimeExecToolProvider, Unsubscribe } from '../shared';
+import type { ActivityClass } from '@makinbakin/sdk/types';
 import type { ChannelCapability } from './capabilities';
+export type { MessageUsage } from '../shared';
 export type RuntimeMetadata = Record<string, unknown>;
 export interface RuntimeAgent {
     id: string;
     name: string;
     role?: string;
     model?: string;
+    /** Model this agent's spawned subagents use (runtimes with a subagent concept). */
+    subagentModel?: string;
     status?: 'active' | 'inactive' | 'unknown';
     metadata?: RuntimeMetadata;
 }
@@ -19,14 +23,12 @@ export interface CreateRuntimeAgentInput {
 export interface UpdateRuntimeAgentInput {
     name?: string;
     role?: string;
-    model?: string;
+    /** `null` clears the assignment (agent falls back to the routing default). */
+    model?: string | null;
+    /** `null` clears. Reject via routingSupport().perAgentSubagentModel=false runtimes. */
+    subagentModel?: string | null;
     metadata?: RuntimeMetadata;
 }
-export interface RuntimePermissionPatch {
-    allow?: string[];
-    deny?: string[];
-    replace?: boolean;
-}
 export interface RuntimeAllowlistPatch {
     add?: string[];
     remove?: string[];
@@ -38,31 +40,132 @@ export interface WorkspaceFile {
     updatedAt?: string;
     metadata?: RuntimeMetadata;
 }
+/**
+ * Size stats for one file the runtime loads at session start. Names + sizes
+ * only — content never crosses the adapter boundary (#357). `kind` is
+ * classified by the adapter so callers never re-derive runtime-private
+ * file conventions.
+ */
+export interface WorkspaceFileStat {
+    /** Path relative to the agent's workspace root (e.g. 'AGENTS.md', 'skills/foo/SKILL.md'). */
+    name: string;
+    bytes: number;
+    mtimeMs: number;
+    kind: 'canonical' | 'skill' | 'memory';
+}
 export type RuntimeMessageToolsMode = 'auto' | 'none';
 export interface RuntimeMessageToolPolicy {
     /**
      * Controls whether runtime-native tools are available for this agent turn.
      * `none` disables tools. Omit or use `auto` for runtime/provider defaults.
+     * Native tool policy beyond on/off is ADAPTER-PRIVATE — callers never name
+     * native tools.
      */
     toolsMode?: RuntimeMessageToolsMode;
-    /** Optional runtime-native tool allowlist for this turn. */
+    /**
+     * Per-turn allowlist of BAKIN EXEC TOOLS by exact name (e.g.
+     * `bakin_exec_tasks_get`). Scope is the exec-tool set ONLY — never
+     * runtime-native tools (audit M3: OpenClaw once forwarded these as native
+     * policy while Pi filtered exec tools, so `toolsAllow: ['read']` meant two
+     * different things). Enforcement is mechanism-dependent: in-process
+     * runtimes filter the tool bridge per turn; runtimes whose exec tools ride
+     * session-static transports (OpenClaw's per-agent MCP servers) cannot
+     * filter per-turn and must IGNORE the fields with a loud warning — never
+     * misapply them to native tools.
+     */
     toolsAllow?: string[];
-    /** Optional runtime-native tool denylist for this turn. */
+    /** Per-turn denylist of Bakin exec tools by exact name (same scope/enforcement as `toolsAllow`). */
     toolsDeny?: string[];
 }
+/** Local file offered to the runtime as model input for one turn. */
+export interface MessageAttachment {
+    path: string;
+    mimeType: string;
+}
 export interface MessageArgs extends RuntimeMessageToolPolicy {
     agentId: string;
     content: string;
+    /** Producer-assigned usage class; omitted interactive turns default to user. */
+    activityClass?: ActivityClass;
+    /**
+     * Image attachments for the turn (runtime support is declared by
+     * `capabilities().imageInput`; adapters reject unsupported media loudly
+     * rather than silently dropping pixels).
+     */
+    attachments?: MessageAttachment[];
+    /**
+     * Utility turn: ask the runtime to suppress visible session side effects
+     * (control-UI visibility, prompt persistence) where it supports them.
+     * The thread still exists for idempotency; it just stays out of the way.
+     */
+    ephemeral?: boolean;
     /**
      * Adapter-neutral durable conversation key. Runtime adapters should map the
      * same agentId + threadId pair to the same provider/runtime session.
      */
     threadId?: string;
+    /**
+     * Absolute path of a per-run working directory for this turn. Set ONLY by
+     * dispatch, only for runtimes declaring `concurrency.sameAgentTurns:
+     * 'isolated'` — core allocates the dir (under Bakin territory, never the
+     * runtime's home) and the adapter uses it as the session cwd, seeding its
+     * own context conventions (project context, skills, memory write paths) so
+     * the isolated turn loses nothing. Chat and ephemeral/system sends never
+     * carry it: the agent's shared workspace stays their cwd. Adapters that
+     * declare 'serialized' never receive the field.
+     */
+    runWorkspace?: string;
+    /**
+     * Per-turn model override (`provider/model` id). Omit to use the agent's
+     * configured model. The caller (Bakin's routing policy) resolves it.
+     */
+    model?: string;
+    /**
+     * Per-turn thinking level. Omit to use the runtime/agent default.
+     */
+    thinking?: string;
+    /**
+     * Best-effort turn cancellation. On abort, adapters MUST reject the send
+     * promptly with RuntimeError kind 'aborted' and SHOULD cancel the
+     * provider-side run where the runtime supports it (fail-open: a provider
+     * that can't cancel still gets the local rejection).
+     */
+    signal?: AbortSignal;
+    /**
+     * Best-effort live-activity tap for a `send()` turn (prelaunch-hardening
+     * R7/D-plan-1): invoked with `tool` and `status` chunks as the runtime
+     * surfaces them — text deltas do NOT flow here (use `messaging.stream`
+     * to render prose live). No delivery guarantee, no chunk is required to
+     * appear, and no ordering guarantee relative to the send() settle (a
+     * late-arriving frame may tap after the promise resolves). Adapters
+     * contain callback exceptions — a throwing tap never fails the turn.
+     * Ignored by `messaging.stream`, whose iterator already carries chunks.
+     */
+    onActivity?: (chunk: ChatChunk) => void;
+    /**
+     * Byte threshold above which a died turn's completion counts as
+     * "oversized output" in its RuntimeTurnDiagnosis (the recovery ladder
+     * treats runaway-output deaths differently from ordinary interrupts).
+     * Dispatch passes `settings.dispatch.oversizedOutputBytes`; adapters fall
+     * back to their own default (128 KiB) when omitted. Typed here — NOT a
+     * metadata-bag key (audit M4: core policy must never ride the opaque bag).
+     */
+    oversizedOutputBytes?: number;
     metadata?: RuntimeMetadata;
 }
+/**
+ * Fallback for `MessageArgs.oversizedOutputBytes` when the caller omits it —
+ * THE single source both adapters and `settings.dispatch.oversizedOutputBytes`
+ * default from (previously duplicated per adapter; parity by reference, not
+ * by copy). Both adapters measure the same thing: UTF-8 bytes of the turn's
+ * assistant output text, strict `>`.
+ */
+export declare const DEFAULT_OVERSIZED_OUTPUT_BYTES: number;
 export interface MessageResult {
     id: string;
     content?: string;
+    /** Per-turn token usage, omitted when the runtime reported none. */
+    usage?: MessageUsage;
     metadata?: RuntimeMetadata;
 }
 export interface RuntimeToolActivity {
@@ -77,24 +180,69 @@ export interface RuntimeToolActivity {
     exitCode?: number;
     metadata?: RuntimeMetadata;
 }
-export interface ChatChunk {
-    type: 'text' | 'tool' | 'status' | 'done' | 'error';
+/** Render format for a text chunk's content. Absent means 'markdown'. */
+export type ChatTextFormat = 'markdown' | 'plain' | 'code';
+/**
+ * One chunk of a streaming agent turn — the turn-output normalization
+ * contract every adapter emits and every consumer renders against.
+ *
+ * Behavioral contract (pinned today by the per-adapter suites —
+ * tests/adapter-openclaw/stream-events.test.ts and
+ * tests/integration/pi/turn.test.ts; the cross-adapter conformance suite
+ * lands with prelaunch-hardening PR 3):
+ * - Chunk GRANULARITY may vary by adapter: per-token deltas, coalesced
+ *   spans, or one chunk per turn are all legal. Consumers accumulate
+ *   `text` content in arrival order and must not assume a cadence.
+ * - `done` is yielded EXACTLY ONCE, always last; no chunk of any kind
+ *   follows it.
+ * - A DELIBERATE abort (the turn's `kind:'aborted'` settle) ends the
+ *   stream with a clean `done` — never an `error` chunk. Abort is a
+ *   clean end, not a failure.
+ * - `tool` and `status` chunks are BEST-EFFORT liveness: adapters emit
+ *   what their runtime exposes, and none is guaranteed to appear.
+ * - Terminal failure ends the stream with an `error` chunk (its `data`
+ *   carries `{ kind }` — the RuntimeError kind — when known) and NO
+ *   `done`; the iterator itself never throws.
+ * - Adapters emit CLASSIFIED, STRUCTURED chunks only — never
+ *   pre-rendered HTML/ANSI or raw JSON/shell dumps in `content`.
+ *   Stripping runtime-specific noise is the adapter's job.
+ */
+export type ChatChunk = 
+/** Assistant text. `format` hints rendering; absent = markdown. */
+{
+    type: 'text';
+    content: string;
+    format?: ChatTextFormat;
+    data?: RuntimeMetadata;
+}
+/** Tool activity; `data` is always the structured RuntimeToolActivity. */
+ | {
+    type: 'tool';
     content?: string;
-    data?: RuntimeMetadata | RuntimeToolActivity;
+    data: RuntimeToolActivity;
 }
-export interface ToolDefinition {
-    name: string;
-    description?: string;
-    inputSchema?: unknown;
+/** Turn lifecycle hint (e.g. 'thinking'). */
+ | {
+    type: 'status';
+    content?: string;
+    data?: RuntimeMetadata;
 }
-export interface ToolResult {
-    ok: boolean;
-    output?: unknown;
-    error?: {
-        message: string;
-        recoverable: boolean;
-    };
+/** Clean turn end (success or deliberate abort) — exactly once, always last.
+ *  `usage` carries the turn's token accounting when the runtime reports it —
+ *  parity with `send()`: a runtime whose send results carry usage must
+ *  attach it here too (conformance-pinned), so streamed turns are meterable. */
+ | {
+    type: 'done';
+    content?: string;
+    data?: RuntimeMetadata;
+    usage?: MessageUsage;
 }
+/** Terminal failure — `data.kind` carries the RuntimeError kind when known. */
+ | {
+    type: 'error';
+    content?: string;
+    data?: RuntimeMetadata;
+};
 export interface ChannelInfo {
     id: string;
     platform: string;
@@ -145,6 +293,28 @@ export interface ContentDeliveryArgs {
         metadata?: RuntimeMetadata;
     };
 }
+export interface CreateThreadArgs {
+    /** Channel ref the anchor message lives in (provider or provider:target). */
+    channel: string;
+    /** Delivery ref of the message to anchor the thread to (e.g. "message:<id>"). */
+    messageRef?: string;
+    name: string;
+}
+export interface CreatedThread {
+    threadId: string;
+    /**
+     * Provider-addressable channel ref for posting INTO the thread (opaque to
+     * callers — provider target syntax stays inside the adapter).
+     */
+    channelRef: string;
+}
+export interface EditChannelMessageArgs {
+    /** Channel ref the message lives in (provider or provider:target). */
+    channel: string;
+    /** Delivery ref of the message to edit (e.g. "message:<id>"). */
+    messageRef: string;
+    body: string;
+}
 export interface ApprovalOption {
     id: string;
     label: string;
@@ -203,31 +373,6 @@ export interface ApprovalResolveEvent {
     response: ApprovalResponse;
     channelId: string;
 }
-export interface ChannelMessageEvent {
-    channelId: string;
-    messageId: string;
-    actor: {
-        type: 'agent' | 'human';
-        id: string;
-        displayName?: string;
-    };
-    body: string;
-    threadId?: string;
-    receivedAt: string;
-    metadata?: RuntimeMetadata;
-}
-export interface ChannelInteractionEvent {
-    channelId: string;
-    interactionId: string;
-    actor: {
-        type: 'agent' | 'human';
-        id: string;
-        displayName?: string;
-    };
-    kind: string;
-    payload: RuntimeMetadata;
-    receivedAt: string;
-}
 export interface DurableApprovalRecord {
     approvalId: string;
     owner: {
@@ -259,6 +404,25 @@ export interface RuntimeSession {
     updatedAt?: string;
     metadata?: RuntimeMetadata;
 }
+export interface RuntimeSessionStoreStats {
+    agentId: string;
+    /** Live entries in the runtime's session store for this agent. */
+    storeEntries: number;
+    /**
+     * Top-level files in the agent's sessions directory (session artifacts,
+     * including the store itself) — cache subtrees are excluded so the
+     * orphaned-artifact ratio stays meaningful.
+     */
+    fileCount: number;
+    /** Total bytes of the agent's sessions directory, subtrees included. */
+    diskBytes: number;
+    /**
+     * Adapter-owned operator guidance for shrinking this agent's store (CLI
+     * commands, config knobs). Health surfaces render it verbatim — provider
+     * specifics belong HERE, never hardcoded upstream of the adapter.
+     */
+    remediation?: string;
+}
 export interface RuntimeMemoryTier {
     id: string;
     label: string;
@@ -298,6 +462,177 @@ export interface RuntimeMemorySearchResult {
     results: unknown[];
     metadata?: RuntimeMetadata;
 }
+/**
+ * What the runtime's ACTIVE configuration can accept as model input
+ * (spec: enrichment-runtime-fallback §3). Adapter-declared from the
+ * runtime's own model catalog for the SELECTED agent's effective model
+ * (default: the main agent) — conservative false on any ambiguity, never
+ * model-name heuristics.
+ */
+export interface RuntimeCapabilities {
+    imageInput: boolean;
+    audioInput: boolean;
+}
+/**
+ * One capability's provisioning state on a runtime:
+ * - 'native'      — the runtime provides it directly.
+ * - 'shimmed'     — the runtime doesn't, but a Bakin-owned shim fills it.
+ * - 'unavailable' — neither; degrade honestly + surface in the UI.
+ */
+export type CapabilityMode = 'native' | 'shimmed' | 'unavailable';
+/**
+ * How agents on this runtime invoke Bakin exec tools:
+ * - 'in-process' — exec tools are first-class session tools; the agent calls
+ *                  `bakin_exec_*` directly (Pi's in-process bridge).
+ * - 'mcp'        — the runtime's native MCP client reaches Bakin's MCP server;
+ *                  tools appear namespaced as `<mcpServerTemplate>.<tool>`.
+ * - 'cli-shim'   — the agent shells `<shimCommand>` (inert extension point for
+ *                  a future runtime that can neither embed nor speak MCP).
+ */
+export type ToolAccessStyle = 'in-process' | 'mcp' | 'cli-shim';
+export interface RuntimeToolAccess {
+    style: ToolAccessStyle;
+    /** 'mcp': per-agent server-name template, e.g. `bakin-<agent>`. */
+    mcpServerTemplate?: string;
+    /** 'cli-shim': shell command template. */
+    shimCommand?: string;
+    /** One canonical, style-appropriate example call. */
+    example?: string;
+    /**
+     * Whether this runtime can ENFORCE `MessageArgs.toolsAllow`/`toolsDeny`
+     * per turn. In-process runtimes filter their tool bridge per call (true);
+     * runtimes whose exec tools ride session-static transports (OpenClaw's
+     * per-agent MCP servers) cannot (false) — they ignore the fields with a
+     * loud warning. Callers needing a RESTRICTED turn must feature-detect
+     * this and refuse rather than degrade fail-open.
+     */
+    perTurnExecToolFiltering?: boolean;
+}
+/**
+ * Result of `verifyToolAccess()` — a runtime-neutral report on whether this
+ * runtime's tool-access wiring is currently in place, so core (onboarding,
+ * doctor) can surface drift WITHOUT knowing any provider's config shape.
+ * `in-process` runtimes report `ok: true` with no issues (nothing to
+ * provision); `mcp` runtimes report missing/stale server entries.
+ */
+export interface ToolAccessProvisioningStatus {
+    style: ToolAccessStyle;
+    ok: boolean;
+    /** Human-readable drift descriptions when `ok` is false. */
+    issues: string[];
+    details?: Record<string, unknown>;
+}
+/**
+ * The unified capability declaration — every runtime-provided capability that
+ * has a native/shim/gap choice. Bakin renders agent instructions from it,
+ * routes to shims when `shimmed`, degrades honestly when `unavailable`, and
+ * plugins query it instead of assuming. Always-Bakin-owned capabilities
+ * (scheduling, heartbeats, tasks, assets, audit) are NOT here — they have no
+ * native/shim choice. `input` folds in the former modality-only capabilities.
+ */
+export interface CapabilitySet {
+    toolCalling: {
+        mode: 'native';
+        access: RuntimeToolAccess;
+    };
+    delivery: {
+        mode: CapabilityMode;
+    };
+    imageGen: {
+        mode: CapabilityMode;
+    };
+    memory: {
+        mode: 'native' | 'unavailable';
+    };
+    sessions: {
+        mode: 'native' | 'unavailable';
+    };
+    workspaceFiles: {
+        mode: 'native' | 'unavailable';
+    };
+    input: RuntimeCapabilities;
+    /**
+     * Can two turns for ONE agent run simultaneously without colliding?
+     * - 'isolated'   — the adapter honors `MessageArgs.runWorkspace` (per-turn
+     *                  cwd), so concurrent same-agent turns each work in their
+     *                  own directory; parallel-safe.
+     * - 'serialized' — the adapter/provider cannot isolate runs (one shared
+     *                  workspace per agent); dispatch clamps that agent to one
+     *                  turn at a time regardless of settings, with a visible
+     *                  receipt — never a silent drop.
+     * Conformance-pinned: declaring 'isolated' without actually honoring
+     * runWorkspace fails the runtime conformance suite.
+     */
+    concurrency: {
+        sameAgentTurns: 'isolated' | 'serialized';
+    };
+}
+/**
+ * Presence-only credential report (P2.2): WHICH LLM providers and channels
+ * have usable credentials configured in the runtime — names only, NEVER
+ * secret material. Drives the onboarding llm/channels checks; each adapter
+ * reads its own config internally so credential shapes never leak upstream.
+ */
+/**
+ * Presence-only credential KIND: 'api-key' = metered pay-per-use billing;
+ * 'oauth' = subscription login (plan quota). An entry carrying both reports
+ * 'api-key' — the key is what the provider bills. Never carries values.
+ */
+export type RuntimeCredentialKind = 'api-key' | 'oauth';
+export interface RuntimeCredentialStatus {
+    /** Provider names with usable credentials (api key / token / OAuth). */
+    llmProviders: string[];
+    /**
+     * Per-provider credential kind (billing-lane detection, cost-control v2).
+     * Optional — consumers treat absence as unknown and stay conservative
+     * (unknown bills as metered, never silently uncapped-as-free).
+     */
+    llmCredentials?: Array<{
+        provider: string;
+        kind: RuntimeCredentialKind;
+    }>;
+    /** Channel names with usable credentials. Empty on channel-less runtimes. */
+    channels: string[];
+}
+/**
+ * Runtime-owned model routing policy (P2.3): the knobs the RUNTIME honors at
+ * session time — default model for agents without an assignment, failover
+ * order, subagent default, alias map. Bakin manages these through this
+ * neutral surface; each adapter maps to its native store, so a runtime's
+ * policy survives untouched while another runtime is active (round-trip by
+ * construction).
+ */
+export interface RuntimeRoutingPolicy {
+    /** Default model for agents without an explicit assignment. '' when unset. */
+    defaultModel: string;
+    /** Failover models tried in order when the default fails. */
+    fallbackModels: string[];
+    /** Default model for spawned subagents. Null when unset/unsupported. */
+    defaultSubagentModel: string | null;
+    /** Alias name → target model id. */
+    aliases: Record<string, string>;
+}
+/**
+ * Which routing-policy fields this runtime actually HONORS. Static
+ * declaration (like describeToolAccess): UIs hide unsupported controls and
+ * `setRoutingPolicy` rejects patches carrying unsupported fields — a knob
+ * the runtime ignores must never be silently stored.
+ */
+export interface RuntimeRoutingSupport {
+    defaultModel: boolean;
+    fallbackModels: boolean;
+    defaultSubagentModel: boolean;
+    aliases: boolean;
+    /** Per-agent subagentModel via agents.update. */
+    perAgentSubagentModel: boolean;
+    /**
+     * Per-turn thinking levels this runtime HONORS on messaging.send. Bakin's
+     * routing layer clamps requested levels to this set (with receipt + audit
+     * evidence) before the send — an adapter must honor every level it
+     * declares and declare every level it honors (conformance-pinned).
+     */
+    supportedThinkingLevels: readonly string[];
+}
 export interface RuntimeAvailableModel {
     id: string;
     name?: string;
@@ -308,38 +643,134 @@ export interface RuntimeAvailableModel {
     tags?: string[];
     metadata?: RuntimeMetadata;
 }
-export interface TaskDispatchArgs {
-    bakinTaskId: string;
-    agentId?: string;
-    title: string;
-    description?: string;
+export type RuntimeImageOutputFormat = 'png' | 'jpeg' | 'jpg' | 'webp';
+export type RuntimeImageBackground = 'transparent' | 'opaque' | 'auto';
+/**
+ * Image capability is intentionally all-optional. A thin runtime that exposes a
+ * single image tool maps on by filling minimal fields (e.g. one synthesized
+ * provider with a defaultModel); a rich runtime fills more. Consumers MUST
+ * treat a sparse capability as normal and never require a field a thin runtime
+ * cannot provide — gaps are filled below, in the adapter/shim, not pushed up
+ * into plugins. See .claude/knowledge/media-generation-adapter-architecture.md.
+ */
+export interface RuntimeImageProviderCapabilities {
+    generate?: {
+        maxCount?: number;
+        supportsSize?: boolean;
+        supportsAspectRatio?: boolean;
+        supportsResolution?: boolean;
+    };
+    edit?: {
+        enabled?: boolean;
+        maxCount?: number;
+        maxInputImages?: number;
+        supportsSize?: boolean;
+        supportsAspectRatio?: boolean;
+        supportsResolution?: boolean;
+    };
+    geometry?: {
+        sizes?: string[];
+        aspectRatios?: string[];
+        resolutions?: string[];
+    };
+    output?: {
+        formats?: string[];
+        qualities?: string[];
+        backgrounds?: string[];
+    };
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeImageProvider {
+    id: string;
+    label?: string;
+    defaultModel?: string;
+    models?: string[];
+    available?: boolean;
+    configured?: boolean;
+    selected?: boolean;
+    capabilities?: RuntimeImageProviderCapabilities;
     metadata?: RuntimeMetadata;
 }
-export interface TaskDispatchResult {
-    flowId: string;
-}
-export interface TaskExecutionStatus {
-    flowId: string;
-    bakinTaskId?: string;
-    state: 'queued' | 'running' | 'blocked' | 'succeeded' | 'failed' | 'cancelled' | 'unknown';
-    currentStep?: string | null;
-    blockingReason?: string | null;
-    retryCount?: number;
-    startedAt?: string | null;
-    endedAt?: string | null;
-    updatedAt?: string | null;
+export interface RuntimeImageGenerateInput {
+    prompt: string;
+    provider?: string;
+    model?: string;
+    count?: number;
+    width?: number;
+    height?: number;
+    size?: string;
+    aspectRatio?: string;
+    resolution?: string;
+    outputFormat?: RuntimeImageOutputFormat;
+    background?: RuntimeImageBackground;
+    /**
+     * Reference/context image file paths conditioning the generation. The caller
+     * (Bakin) resolves managed asset ids to concrete paths before the adapter
+     * sees them. Native generation has no file input, so a generate carrying
+     * references is routed through the edit-style invocation (#418).
+     */
+    referenceImages?: string[];
+    timeoutMs?: number;
     metadata?: RuntimeMetadata;
 }
-export interface ListExecutionsOpts {
-    bakinTaskId?: string;
-    agentId?: string;
-    state?: TaskExecutionStatus['state'];
-    limit?: number;
+export interface RuntimeImageEditInput extends RuntimeImageGenerateInput {
+    files: string[];
+}
+export interface RuntimeImageFile {
+    filePath: string;
+    mimeType?: string;
+    width?: number;
+    height?: number;
+    provider?: string;
+    model?: string;
+    url?: string;
+    metadata?: RuntimeMetadata;
 }
-export interface TaskExecutionEvent {
-    flowId: string;
-    bakinTaskId?: string;
-    status: TaskExecutionStatus;
+export interface RuntimeImageGenerationResult {
+    images: RuntimeImageFile[];
+    provider?: string;
+    model?: string;
+    providerText?: string;
+    metadata?: RuntimeMetadata;
+}
+export interface RuntimeImagesAccess {
+    providers(): Promise<RuntimeImageProvider[]>;
+    generate(input: RuntimeImageGenerateInput): Promise<RuntimeImageGenerationResult>;
+    edit(input: RuntimeImageEditInput): Promise<RuntimeImageGenerationResult>;
+}
+/**
+ * A runtime extension: third-party code the RUNTIME loads in-process during
+ * agent turns (Pi extensions today). Provider-neutral shape — ids/labels/
+ * paths only, never provider config. Discovery is INERT: listing never
+ * executes extension code.
+ */
+export interface RuntimeExtensionInfo {
+    /** Stable identifier used for allow/revoke — the real absolute module path. */
+    id: string;
+    label: string;
+    /** Where it came from, human-readable (e.g. "npm:some-pkg", "extensions dir"). */
+    source: string;
+    /** Real absolute load path (symlinks resolved) — half the trust identity. */
+    path: string;
+    /** Current content hash of the file — the other half of the trust identity. */
+    sha256: string;
+    /**
+     * pending  — discovered but NOT loaded into turns (unapproved, or its
+     *            content changed since approval)
+     * allowed  — approved path+hash; loads into agent turns
+     * blocked  — policy mode 'none': nothing loads
+     */
+    status: 'allowed' | 'pending' | 'blocked';
+}
+/**
+ * OPTIONAL: trust management for runtime-loaded extensions. Runtimes without
+ * an extension mechanism OMIT the member; callers feature-detect
+ * (`runtime.extensions?.`). Listing is read-only and inert. The trust store
+ * itself (allowlist) is Bakin-owned settings — see
+ * `src/core/runtime-extensions.ts` for the ONE mutation engine.
+ */
+export interface RuntimeExtensionsAccess {
+    list(): Promise<RuntimeExtensionInfo[]>;
 }
 export interface CronJob {
     id: string;
@@ -376,21 +807,48 @@ export interface RawCronSnapshot {
     capturedAt: string;
     snapshot: unknown;
 }
-export interface RuntimeConfigAccess {
-    get<T = Record<string, unknown>>(): Promise<T>;
-    update(patch: Record<string, unknown>): Promise<void>;
-    replace<T = Record<string, unknown>>(next: T, reason: string): Promise<void>;
-    raw<T = unknown>(key: string, reason: string): Promise<T>;
-}
+/**
+ * URI scheme for runtime-private media references (`media://inbound/…`).
+ * The ONE place upstream code may learn the scheme: callers detect
+ * media references with this constant and hand them to `media.resolveUri`
+ * (feature-detected) — the adapter owns what the URI means.
+ */
+export declare const RUNTIME_MEDIA_URI_SCHEME = "media://";
 export interface AgentRuntimeAdapter {
     readonly name: string;
     readonly version: string;
     readonly requiredCoreVersion: string;
     initialize(opts: AdapterInitOpts): Promise<void>;
     shutdown(): Promise<void>;
+    /**
+     * "Can this runtime serve a turn?" — a CHEAP probe (an HTTP health hit, a
+     * credential-presence read; never an LLM call). Resolves `false` rather
+     * than throwing when the runtime cannot serve (unreachable process,
+     * uninitialized adapter, no LLM credentials). Deeper diagnostics are
+     * registered separately with the canonical Health registry.
+     */
     ping(): Promise<boolean>;
+    /**
+     * Re-read ALL durable config: credentials, model registry, settings,
+     * provisioned tool access. External-process runtimes may bounce the
+     * process; in-process runtimes must drop every cache so the next call
+     * re-reads disk. Callers (team/models plugins) invoke this after config
+     * writes and expect the next read to reflect them.
+     */
     restart(): Promise<void>;
-    getHealthChecks(): AdapterHealthCheckDefinition[];
+    /**
+     * CRUD error contract (R28): `get` returns `null` for a missing agent —
+     * absence is a value, never a throw. Mutations addressing a MISSING agent
+     * (`update`, `updateAllowlist`, `remove`) reject with a typed
+     * `RuntimeError` kind `'not_found'`. Workspace-file writes are exempt BY
+     * DESIGN: they provision the workspace directory on demand (creating an
+     * agent's first file is a legitimate provisioning step, not an error).
+     * Provider/runtime failures on these surfaces are typed `RuntimeError`s
+     * (adapters map them in their own errors module — core never classifies
+     * on message text); caller-INPUT validation (invalid names/paths,
+     * unsupported options) may throw plain `Error`s — those signal programmer
+     * error before any runtime interaction, not runtime state.
+     */
     agents: {
         list(): Promise<RuntimeAgent[]>;
         get(agentId: string): Promise<RuntimeAgent | null>;
@@ -401,19 +859,44 @@ export interface AgentRuntimeAdapter {
         readWorkspaceFile(agentId: string, path: string): Promise<WorkspaceFile | null>;
         writeWorkspaceFile(agentId: string, file: WorkspaceFile): Promise<void>;
         removeWorkspaceFile(agentId: string, path: string): Promise<void>;
-        updatePermissions(agentId: string, patch: RuntimePermissionPatch): Promise<void>;
+        /**
+         * Read-only size stats for the files the runtime loads at session start
+         * (canonical bootstrap files, skills, memory notes). Null when the agent
+         * has no workspace. Optional: runtimes without a file-backed workspace
+         * omit it, and callers must treat absence as "stats unavailable" —
+         * skip, never error.
+         */
+        workspaceFileStats?(agentId: string): Promise<WorkspaceFileStat[] | null>;
+        /**
+         * The SUBAGENT-DISPATCH allowlist: the patch strings are AGENT IDS this
+         * agent may dispatch subtasks to (P5.3 live incident: these were once fed
+         * into an exec-tool name filter — they are never tool names). OpenClaw
+         * writes `agents.list[].subagents.allowAgents` in its config; Pi stores
+         * the registry record's `allowlist`, consumed by its tool bridge when
+         * filtering subagent dispatch targets. Installer/team flows add every
+         * newly installed agent to its dispatchers here.
+         */
         updateAllowlist(agentId: string, patch: RuntimeAllowlistPatch): Promise<void>;
-        heartbeat(agentId: string): Promise<boolean>;
     };
     messaging: {
         send(args: MessageArgs): Promise<MessageResult>;
+        /**
+         * Stream one agent turn as normalized ChatChunks. See the ChatChunk
+         * doc for the behavioral contract: adapter-varying granularity,
+         * `done` exactly once and last, best-effort tool/status liveness,
+         * terminal failure = `error` chunk then end (never a throw from
+         * iteration), classified/structured chunks only.
+         */
         stream(args: MessageArgs): AsyncIterable<ChatChunk>;
     };
-    tools: {
-        invoke(agentId: string, name: string, args: unknown): Promise<ToolResult>;
-        list(agentId: string): Promise<ToolDefinition[]>;
-    };
-    channels: {
+    /**
+     * OPTIONAL capability (P2.1): runtimes without a channel/delivery layer
+     * (Pi) OMIT this member entirely — no throwing stubs. Callers MUST
+     * feature-detect (`runtime.channels?.…` or a guarded local) and degrade
+     * honestly: empty channel lists, log-only alerts, UI-only approval gates.
+     * `capabilities().delivery.mode` reports the same fact declaratively.
+     */
+    channels?: {
         list(): Promise<ChannelInfo[]>;
         sendNotification(args: NotificationArgs): Promise<DeliveryResult>;
         sendMessage(args: ChannelMessageArgs): Promise<DeliveryResult>;
@@ -423,8 +906,13 @@ export interface AgentRuntimeAdapter {
         cancelApproval(args: CancelApprovalArgs): Promise<void>;
         resolveApproval(args: ResolveApprovalArgs): Promise<void>;
         subscribeApprovalResponses(handler: (event: ApprovalResolveEvent) => void): Unsubscribe;
-        onMessage(handler: (event: ChannelMessageEvent) => void): Unsubscribe;
-        onInteraction(handler: (event: ChannelInteractionEvent) => void): Unsubscribe;
+        /**
+         * Optional threading/editing capabilities. Adapters for providers without
+         * threads or message editing omit them; callers MUST feature-detect and
+         * fall back to flat channel messages — never error on absence.
+         */
+        createThread?(args: CreateThreadArgs): Promise<CreatedThread | null>;
+        editMessage?(args: EditChannelMessageArgs): Promise<void>;
     };
     skills: {
         list(agentId?: string): Promise<RuntimeSkill[]>;
@@ -435,6 +923,12 @@ export interface AgentRuntimeAdapter {
     sessions: {
         list(agentId?: string): Promise<RuntimeSession[]>;
         get(sessionId: string): Promise<RuntimeSession | null>;
+        /**
+         * Per-agent session-store disk stats. Optional: runtimes without a
+         * file-backed session store omit it, and callers must treat absence
+         * as "stats unavailable" — skip, never error.
+         */
+        storeStats?(): Promise<RuntimeSessionStoreStats[]>;
     };
     memory: {
         listTiers(): Promise<RuntimeMemoryTier[]>;
@@ -463,15 +957,94 @@ export interface AgentRuntimeAdapter {
         listAvailable(opts?: {
             includeUnavailable?: boolean;
         }): Promise<RuntimeAvailableModel[]>;
+        /** Static declaration of which routing-policy fields this runtime honors. */
+        routingSupport(): RuntimeRoutingSupport;
+        /** The runtime's current routing policy (unsupported fields empty). */
+        routingPolicy(): Promise<RuntimeRoutingPolicy>;
+        /**
+         * Merge a partial policy into the runtime's native store. MUST throw on
+         * a patch carrying a field `routingSupport()` declares unsupported.
+         * `reason` feeds the adapter's audit trail.
+         */
+        setRoutingPolicy(patch: Partial<RuntimeRoutingPolicy>, reason: string): Promise<void>;
     };
-    tasks: {
-        dispatch(args: TaskDispatchArgs): Promise<TaskDispatchResult>;
-        getExecutionStatus(flowId: string): Promise<TaskExecutionStatus>;
-        listExecutions(opts?: ListExecutionsOpts): Promise<TaskExecutionStatus[]>;
-        cancelExecution(flowId: string): Promise<void>;
-        subscribeExecutionUpdates(handler: (event: TaskExecutionEvent) => void): Unsubscribe;
+    /**
+     * The unified capability declaration for this runtime, evaluated for
+     * `opts.agentId`'s effective model (default: the main agent) where
+     * model-dependent (input modality). Async: the report surface for the
+     * runtime-switch UI + plugin capability queries. `input` is conservative-
+     * false on any ambiguity, never model-name heuristics.
+     *
+     * Modes are HONEST: a static `'native'` declaration is acceptable only
+     * when the surface is unconditionally implemented (the standard the T28
+     * sessions fix restored — a declared-native stub is a contract violation,
+     * pinned by the runtime conformance suite's capability-honesty check).
+     */
+    capabilities(opts?: {
+        agentId?: string;
+    }): Promise<CapabilitySet>;
+    /**
+     * How agents on this runtime invoke Bakin exec tools — drives the
+     * tool-usage wording of dispatch prompts + projected AGENTS.md. SYNC +
+     * static (declared wiring, not probed state) so it's callable from the
+     * synchronous prompt-assembly path; `capabilities().toolCalling.access`
+     * returns the same facts for the async report surface.
+     */
+    describeToolAccess(): RuntimeToolAccess;
+    /**
+     * Presence-only credential report for the runtime's LLM providers and
+     * channels (P2.2). `opts.agentId` scopes provider credentials to one
+     * agent's profile where the runtime keys them per-agent (default: the
+     * main agent). Never returns secret material.
+     */
+    credentialStatus(opts?: {
+        agentId?: string;
+    }): Promise<RuntimeCredentialStatus>;
+    /**
+     * Wire up this runtime so its agents can reach Bakin's exec tools.
+     * Idempotent + re-invokable: run at init AND whenever the agent roster or
+     * exec-tool set changes (agent-create, plugin (un)load).
+     *   - in-process (Pi): no-op — tools are injected per session via the
+     *     `execTools` provider passed to `initialize`.
+     *   - mcp (OpenClaw): write `config.mcp.servers[bakin-<agent>]` for every
+     *     agent, pruning stale Bakin entries; needs `bakinMcpBaseUrl` (init opt).
+     *   - cli-shim: no-op stub.
+     * The `execTools` provider reads the LIVE registry; runtimes that inject
+     * tools by value re-read it here so late registrations become visible.
+     */
+    provisionToolAccess(execTools?: RuntimeExecToolProvider): Promise<void>;
+    /**
+     * Tear down what `provisionToolAccess` wrote. in-process/cli-shim: no-op.
+     * mcp: remove Bakin-owned `bakin-*` server entries. Called by the
+     * runtime-switch flow (P3.2) on switch-away.
+     */
+    deprovisionToolAccess(): Promise<void>;
+    /**
+     * Report whether tool-access provisioning is currently in place, WITHOUT
+     * writing. Drives the onboarding/doctor drift surfaces through a
+     * runtime-neutral status so core never inspects a provider's config shape.
+     */
+    verifyToolAccess(): Promise<ToolAccessProvisioningStatus>;
+    images?: RuntimeImagesAccess;
+    extensions?: RuntimeExtensionsAccess;
+    /**
+     * Access to the runtime's private media store (e.g. channel attachments).
+     * `resolveUri` maps a runtime-private URI (`RUNTIME_MEDIA_URI_SCHEME`-
+     * prefixed) to an absolute local file path; null for unknown schemes or
+     * missing files — never throws for not-found. Optional: runtimes without a
+     * media store omit it, and callers must treat absence as "cannot resolve".
+     */
+    media?: {
+        resolveUri(uri: string): Promise<string | null>;
     };
-    cron: {
+    /**
+     * OPTIONAL capability (P2.1): the RUNTIME's native cron surface (jobs the
+     * runtime/agents create for themselves — Bakin surfaces them read-only and
+     * can adopt them). Runtimes without one (Pi) OMIT the member; Bakin-owned
+     * task scheduling (the schedule plugin's own tick scheduler) is unaffected.
+     * Callers MUST feature-detect and treat absence as "no native jobs".
+     */
+    cron?: {
         list(): Promise<CronJob[]>;
         get(id: string): Promise<CronJob | null>;
         create(input: CreateCronJobInput): Promise<CronJob>;
@@ -482,5 +1055,4 @@ export interface AgentRuntimeAdapter {
         getRaw(id: string, reason: string): Promise<unknown | null>;
         restoreRaw(id: string, snapshot: unknown, reason: string): Promise<CronJob>;
     };
-    config: RuntimeConfigAccess;
 }