@prismer/runtime 2.0.4 → 2.0.6

package/dist/index.d.cts

@@ -1,9 +1,411 @@
 import { z } from 'zod';
-import { EventEmitter } from 'node:events';
 import Database from 'better-sqlite3';
+import { EventEmitter } from 'node:events';
 import { IncomingMessage, ServerResponse } from 'node:http';
 import { Command } from 'commander';
 
+type IMAgentStatus = 'online' | 'busy' | 'idle' | 'offline';
+interface HostedAgentDeclaration {
+    imUserId: string;
+    name: string;
+    adapterName: string;
+    capabilities: string[];
+    profiles: Array<{
+        id: string;
+        version: number;
+    }>;
+}
+interface AgentHostDeclarePayload {
+    daemonId: string;
+    daemonVersion: string;
+    platform: 'darwin' | 'linux' | 'win32';
+    agents: HostedAgentDeclaration[];
+}
+interface RejectedHostedAgent {
+    imUserId: string;
+    reason: 'bound-to-other-daemon' | 'not-owned' | 'unknown';
+    ownerDaemonId?: string;
+}
+interface HostAckedPayload {
+    workspaceId: string;
+    syncCursor: {
+        workspaces: number;
+        agent_profiles: number;
+        [key: string]: number;
+    };
+    profilesToSync: string[];
+    /** Profile IDs the daemon declared but that no longer exist on the cloud
+     *  (soft-deleted). The daemon should remove these from its local store. */
+    profilesToDelete: string[];
+    acceptedAgents?: string[];
+    rejectedAgents?: RejectedHostedAgent[];
+}
+interface AgentStatusChangedPayload {
+    agentImUserId: string;
+    status: IMAgentStatus;
+    activeProfileId?: string;
+    runningTaskIds?: string[];
+}
+interface TaskDispatchContextEntry {
+    sender: string;
+    senderRole: 'human' | 'agent' | 'admin' | 'system';
+    content: string;
+    createdAt: string;
+    /** Wave-8 W1: assets the human attached to THIS chat message. */
+    attachedAssetIds?: string[];
+}
+/** Wave-8 W1: hydrated asset reference attached to a dispatch. */
+interface AssetRef {
+    assetId: string;
+    contentHash: string;
+    mime: string | null;
+    sizeBytes: number | null;
+    kind: string;
+    workspaceId: string;
+    role: 'attachment' | 'context';
+    /**
+     * 14b rev.3 §3.0.4 — cloud-hosted URL for this asset, when present.
+     * Adapters prefer this for image/file blocks (cheaper than base64) but
+     * fall back to `base64` when the URL is not reachable by the upstream
+     * LLM provider (D35 smart probing).
+     */
+    cdnUrl?: string;
+    /**
+     * Optional human-readable filename. Surfaced to adapters that want to
+     * label `input_file` blocks (OpenClaw `/v1/responses`).
+     */
+    filename?: string;
+}
+/**
+ * 14b rev.3 §3.0.4 / §9 P3 — what `resolveAssetRefs` hands to an adapter for
+ * multimodal-aware dispatch. Extends AssetRef with:
+ *  - `localPath` — daemon's local cache copy (still surfaced so file-based
+ *     tools in legacy adapters keep working);
+ *  - `base64` — populated when daemon decided cdnUrl was unreachable and
+ *     inlined the bytes (D35 fallback);
+ *  - `reachable` — cdnUrl reachability probe result for adapter introspection.
+ */
+interface ResolvedAssetRef extends AssetRef {
+    localPath?: string;
+    base64?: string;
+    reachable?: 'cdn' | 'base64' | 'unknown';
+}
+interface TaskDispatchRequestPayload {
+    taskId: string;
+    /** Agent target for runtimeRoute='agent'. Shell dispatches do not use this. */
+    agentImUserId?: string;
+    /** Runtime/device target for runtimeRoute='shell'. */
+    targetDaemonId?: string;
+    profileId: string;
+    capability: string;
+    prompt: string;
+    /** Execution surface. `shell` is daemon-local command execution. */
+    runtimeRoute?: 'agent' | 'sandbox' | 'shell';
+    metadata?: Record<string, unknown>;
+    timeoutMs?: number;
+    context?: TaskDispatchContextEntry[];
+    conversationId?: string;
+    /**
+     * Channel mode for the originating conversation. Optional and
+     * forward-compatible: when missing, daemon renders 'unknown' in the
+     * [Channel context] prompt block. See appendChannelContext in
+     * daemon/dispatch.ts.
+     *   - `direct`: 1:1 DM (no @-mention needed in reply).
+     *   - `group`: multi-party room (end reply with `@<recipient>` to
+     *     continue the chain).
+     */
+    conversationType?: 'direct' | 'group';
+    /**
+     * Active participants of the dispatch's conversation. Daemon injects this
+     * into [Channel context] so the agent knows the authoritative recipient list
+     * without hallucinating or having to call `prismer.conversation.listAgents`. Capped at 50
+     * entries server-side.
+     */
+    participants?: Array<{
+        imUserId: string;
+        username: string;
+        displayName: string;
+        role: string;
+        agentType?: string | null;
+    }>;
+    /** Wave-8 W1: assets cloud wants daemon to fold into agent context. */
+    assetRefs?: AssetRef[];
+}
+interface TaskDispatchProgressPayload {
+    taskId: string;
+    progress: number;
+    message?: string;
+    detail?: Record<string, unknown>;
+}
+/** Wave-8 W1: how the daemon handled a single AssetRef. */
+type AssetDispatchStrategy = 'inline-text' | 'inline-text-truncated' | 'uri-only' | 'fetched-https' | 'error';
+interface AssetDispatchObservation {
+    /** AssetRef.assetId for cloud-attached refs; undefined for L5 https fetches. */
+    assetId?: string;
+    contentHash: string;
+    mime: string | null;
+    sizeBytes: number | null;
+    strategy: AssetDispatchStrategy;
+    inlinedBytes?: number;
+    error?: string;
+    /** L5: original URL the user wrote in the prompt. */
+    originalUrl?: string;
+    /** L5: post-redirect URL the body was actually downloaded from. */
+    finalUrl?: string;
+    /** L5: end-to-end fetch duration in ms (DNS + connect + body read). */
+    durationMs?: number;
+}
+interface TaskDispatchReplyPayload {
+    taskId: string;
+    ok: boolean;
+    output?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    assetIds?: string[];
+    metrics?: {
+        tokensUsed?: number;
+        durationMs?: number;
+    };
+    /** Wave-8 W1: per-asset handling report. */
+    assetObservability?: AssetDispatchObservation[];
+}
+interface TaskCancelPayload {
+    taskId: string;
+    reason?: string;
+}
+interface IMWSMessage<T = unknown> {
+    type: string;
+    payload: T;
+    requestId?: string;
+    timestamp: number;
+}
+interface WorkspaceChangedPayload {
+    workspaceId: string;
+    /** ISO-8601 timestamp from im_workspaces.updatedAt. */
+    updatedAt: string;
+}
+interface AgentProfileChangedPayload {
+    profileId: string;
+    version: number;
+}
+interface AgentChangedPayload {
+    agentImUserId: string;
+    fields: {
+        displayName?: string;
+        capabilities?: string[];
+    };
+}
+interface WorkspaceFileChangedPayload {
+    workspaceId: string;
+    path: string;
+    operation: 'create' | 'update' | 'delete';
+    assetId?: string;
+    contentHash?: string;
+    version: number;
+}
+interface AssetChangedPayload {
+    workspaceId: string;
+    assetId: string;
+    operation: 'create' | 'update' | 'delete';
+    contentHash?: string;
+    assetIndexSeq?: number;
+    revision?: number;
+}
+
+type MemoryPageType = 'hub' | 'leaf' | 'decision' | 'glossary' | 'archive';
+type MemoryVisibility = {
+    kind: 'workspace';
+} | {
+    kind: 'agent';
+    imUserId: string;
+} | {
+    kind: 'private';
+    imUserId: string;
+};
+type ActorKind = 'human' | 'agent';
+type MemorySyncStatus = 'local-only' | 'pending' | 'acked' | 'remote-conflict';
+interface MemoryPage {
+    id: string;
+    workspaceId: string;
+    path: string;
+    title: string | null;
+    description: string | null;
+    contentHash: string;
+    version: number;
+    pageType: MemoryPageType;
+    visibility: MemoryVisibility;
+    encrypted: boolean;
+    stale: boolean;
+    archivedAt: number | null;
+    sourceAssetId: string | null;
+    sourceRefs: string[];
+    syncStatus: MemorySyncStatus;
+    createdAt: number;
+    updatedAt: number;
+}
+interface MemoryPageContent {
+    pageId: string;
+    version: number;
+    content: string;
+}
+interface MemoryLink {
+    sourceUri: string;
+    targetUri: string;
+    relation: string;
+    weight: number;
+    extractedFromPageId: string | null;
+}
+interface MemorySearchResult {
+    pageId: string;
+    path: string;
+    title: string | null;
+    snippet: string;
+    score: number;
+    tokenCount: number;
+}
+interface MemorySearchOptions {
+    topK?: number;
+    relevanceThreshold?: number;
+    maxBytes?: number;
+    pageType?: MemoryPageType[];
+}
+interface MemoryWriteInput {
+    workspaceId: string;
+    path: string;
+    content: string;
+    pageType?: MemoryPageType;
+    title?: string;
+    description?: string;
+    visibility?: MemoryVisibility;
+    sourceAssetId?: string;
+    sourceRefs?: string[];
+    stale?: boolean;
+    actorImUserId: string;
+    actorKind: ActorKind;
+}
+interface MemoryStats {
+    workspaceId: string | null;
+    pageCount: number;
+    pendingOutbox: number;
+    deadLetterCount: number;
+    lastSyncAt: number | null;
+    dbPath: string;
+}
+
+interface MemoryStoreOptions {
+    /** Absolute path to the SQLite database file. Parent dir created with 0o700 if absent. */
+    dbPath: string;
+    /** Workspace this store belongs to. Reject ops referencing other workspaces. */
+    workspaceId: string;
+    /** Device identifier. Stamped onto version + outbox rows at write time. */
+    deviceId: string;
+}
+declare class MemoryStore {
+    private readonly opts;
+    private db;
+    constructor(opts: MemoryStoreOptions);
+    open(): void;
+    close(): void;
+    loadByPath(pagePath: string): MemoryPage | null;
+    loadById(pageId: string): MemoryPage | null;
+    loadContent(pageId: string, version?: number): MemoryPageContent | null;
+    list(options?: {
+        pageType?: MemoryPageType;
+        limit?: number;
+    }): MemoryPage[];
+    write(input: MemoryWriteInput): MemoryPage;
+    invalidate(pageIds: string[], _reason: string): void;
+    upsertLink(link: MemoryLink): void;
+    stats(): MemoryStats;
+    /**
+     * Record sync cursor for incremental sync. Used by cloud-sync.ts to
+     * persist the high-water mark for future cursor-based catch-up.
+     */
+    recordCursor(workspaceId: string, cursor: string): void;
+    /**
+     * Internal accessor for outbox.ts — outbox writes its own table within the
+     * same DB. Returning the live Database handle keeps outbox transactions
+     * shareable with store transactions if ever needed.
+     */
+    rawDb(): Database.Database;
+    /** Workspace this store is bound to (read-only). */
+    workspaceId(): string;
+    /** Device id stamped onto version + outbox rows. */
+    deviceId(): string;
+    private requireDb;
+    private rowToPage;
+}
+
+type MemoryScope = 'workspace-shared' | 'agent-private';
+interface ScopedMemoryStoreOptions {
+    /** Filesystem root, e.g. `~/.prismer/memory` (will create per-workspace dir under). */
+    rootDir: string;
+    /** Workspace identifier — used both as the cloud workspaceId and the dir slug. */
+    workspaceId: string;
+    /** Optional human-friendly slug for the dir; defaults to workspaceId. */
+    workspaceSlug?: string;
+    /** Device identifier, stamped onto outbox + version rows. */
+    deviceId: string;
+}
+interface ScopedWriteInput extends Omit<MemoryWriteInput, 'workspaceId'> {
+    scope: MemoryScope;
+    /** Required when scope='agent-private'; rejected when scope='workspace-shared'. */
+    agentImUserId?: string;
+}
+interface ScopedSearchInput {
+    query: string;
+    scope: MemoryScope;
+    /** Required when scope='agent-private' — search only this agent's bucket. */
+    agentImUserId?: string;
+    options?: MemorySearchOptions;
+}
+/**
+ * Per-workspace, per-bucket SQLite store with the same lifecycle semantics
+ * as the existing single-store MemoryStore class.
+ */
+declare class ScopedMemoryStore {
+    private readonly opts;
+    private sharedStore;
+    private agentStores;
+    private readonly workspaceDir;
+    constructor(opts: ScopedMemoryStoreOptions);
+    /** Resolve the shared store (lazy open). */
+    shared(): MemoryStore;
+    /** Resolve the per-agent store (lazy open). */
+    forAgent(agentImUserId: string): MemoryStore;
+    /** Resolve the right store for (scope, agentImUserId). */
+    resolve(scope: MemoryScope, agentImUserId?: string): MemoryStore;
+    /** Write a memory page into the correct bucket. */
+    write(input: ScopedWriteInput): {
+        pageId: string;
+        scope: MemoryScope;
+        agentImUserId?: string;
+    };
+    /**
+     * Search only the requested bucket. This is the daemon-first FTS5 path
+     * referenced by FF_MEMORY_SEARCH_DAEMON_FIRST.
+     */
+    search(input: ScopedSearchInput): MemorySearchResult[];
+    /**
+     * Search across BOTH the shared bucket and the requesting agent's private
+     * bucket, merging results by descending score. Used by the recall-injector
+     * so the agent's prompt sees both shared knowledge and its own private notes.
+     */
+    searchForAgent(query: string, agentImUserId: string, options?: MemorySearchOptions): MemorySearchResult[];
+    /** List which agent ids currently have a private DB on disk (for diagnostics). */
+    listAgentBuckets(): string[];
+    /** Total disk footprint (best-effort; sums each bucket's main DB file). */
+    diskBytes(): {
+        shared: number;
+        perAgent: Record<string, number>;
+        total: number;
+    };
+    /** Close all underlying stores. */
+    close(): void;
+}
+
 type AdapterKind = 'long-running' | 'interactive';
 /**
  * Adapter definition: how the daemon hosts one class of agent
@@ -70,6 +472,17 @@ interface AgentProfile {
      */
     agentUsername?: string;
 }
+interface TaskHeartbeatHandle {
+    setPhase(phase: string): void;
+    touchStep(): void;
+}
+interface StepRecorderHandle {
+    recordPhaseChange(phase: string): void;
+    recordToolCall(toolName: string, input: unknown, toolCallId?: string): void;
+    recordToolResult(toolCallId: string, output: unknown): void;
+    recordReasoningChunk(text: string): void;
+    recordError(message: string, payload?: Record<string, unknown>): void;
+}
 interface TaskInput {
     taskId: string;
     prompt: string;
@@ -81,6 +494,59 @@ interface TaskInput {
         detail?: Record<string, unknown>;
     }) => void;
     signal?: AbortSignal;
+    /**
+     * Wave-3 D2 observability handles. Optional — pre-Wave-3 adapters that
+     * don't read these still function (heartbeat keeps ticking with the
+     * adapter's last-set phase; no step timeline is emitted).
+     *
+     * `heartbeat`:
+     *   - Adapter calls `heartbeat.setPhase('thinking' | 'tool_use' | ...)`
+     *     when the lifecycle advances. The 15s timer is owned by dispatch.ts;
+     *     adapters MUST NOT start/stop it themselves.
+     *   - Adapter may call `heartbeat.touchStep()` around observable boundaries
+     *     (tool call, token emission) so cloud's 45s "stuck" reaper can
+     *     distinguish slow-but-alive from truly silent.
+     *
+     * `recorder`:
+     *   - Per-task run step uploader. Adapter calls `recordToolCall`,
+     *     `recordToolResult`, `recordReasoningChunk`, `recordPhaseChange`,
+     *     `recordError` at the relevant moments. Implementation is throttled
+     *     for reasoning_chunk (500ms batched).
+     *   - Per §3.0.2 Gap C-⑤, short skill calls (<10s) may rely solely on
+     *     the default 'tool_use' phase; long-running ones SHOULD self-report.
+     *
+     * See sdk/prismer-cloud/runtime/src/daemon/task-heartbeat.ts and
+     *     sdk/prismer-cloud/runtime/src/daemon/step-recorder.ts.
+     */
+    heartbeat?: TaskHeartbeatHandle;
+    recorder?: StepRecorderHandle;
+    /**
+     * 14b rev.3 §3.0.4 / §9 P3 — assets the daemon has resolved (cdnUrl
+     * reachability probed, base64 prefetched if necessary). Multimodal-aware
+     * adapters (Hermes `/v1/chat/completions`, OpenClaw `/v1/responses`) lift
+     * image/file blocks into their wire format; text-like inlining is still
+     * handled by `dispatch.ts:composePrompt` (it stays in the `prompt` string).
+     * Empty/undefined preserves the legacy text-only contract.
+     */
+    assetRefs?: ResolvedAssetRef[];
+    /**
+     * v2.0 Wave 4-E6 (doc 14 §4.7 Track-F) — scoped daemon memory store.
+     *
+     * Optional handle the adapter may use to:
+     *   - Search this agent's memory buckets (workspace-shared + agent-private)
+     *     for daemon-first FTS5 lookup (0 round-trips to cloud)
+     *   - Build a `[Relevant memory]` system block via the recall-injector for
+     *     prompt enrichment before the LLM call
+     *
+     * When undefined, the adapter MUST NOT attempt local memory recall (legacy
+     * behaviour pre-Wave-4 — cloud `/memory/search` is the only path). When
+     * defined, FF_MEMORY_SEARCH_DAEMON_FIRST and operatingPrinciples drive
+     * whether the adapter actually injects.
+     *
+     * Wiring is owned by dispatch.ts (resolves per-agent slot → ScopedMemoryStore
+     * → passes here). Adapters never instantiate the store themselves.
+     */
+    memoryStore?: ScopedMemoryStore;
 }
 interface TaskResult {
     ok: boolean;
@@ -528,7 +994,7 @@ type LocalDb = Database.Database;
 declare function openLocalDb(path: string): LocalDb;
 declare function runMigrations(db: LocalDb): void;
 declare function currentSchemaVersion(db: LocalDb): number;
-declare const TARGET_SCHEMA_VERSION = 3;
+declare const TARGET_SCHEMA_VERSION = 4;
 
 type SyncResourceType = 'workspace' | 'agent' | 'agent_profile';
 type SyncOperation = 'create' | 'update' | 'delete';
@@ -1062,183 +1528,6 @@ declare class ParseClaimController {
     }): HeartbeatHandle;
 }
 
-type IMAgentStatus = 'online' | 'busy' | 'idle' | 'offline';
-interface HostedAgentDeclaration {
-    imUserId: string;
-    name: string;
-    adapterName: string;
-    capabilities: string[];
-    profiles: Array<{
-        id: string;
-        version: number;
-    }>;
-}
-interface AgentHostDeclarePayload {
-    daemonId: string;
-    daemonVersion: string;
-    platform: 'darwin' | 'linux' | 'win32';
-    agents: HostedAgentDeclaration[];
-}
-interface HostAckedPayload {
-    workspaceId: string;
-    syncCursor: {
-        workspaces: number;
-        agent_profiles: number;
-        [key: string]: number;
-    };
-    profilesToSync: string[];
-    /** Profile IDs the daemon declared but that no longer exist on the cloud
-     *  (soft-deleted). The daemon should remove these from its local store. */
-    profilesToDelete: string[];
-}
-interface AgentStatusChangedPayload {
-    agentImUserId: string;
-    status: IMAgentStatus;
-    activeProfileId?: string;
-    runningTaskIds?: string[];
-}
-interface TaskDispatchContextEntry {
-    sender: string;
-    senderRole: 'human' | 'agent' | 'admin' | 'system';
-    content: string;
-    createdAt: string;
-    /** Wave-8 W1: assets the human attached to THIS chat message. */
-    attachedAssetIds?: string[];
-}
-/** Wave-8 W1: hydrated asset reference attached to a dispatch. */
-interface AssetRef {
-    assetId: string;
-    contentHash: string;
-    mime: string | null;
-    sizeBytes: number | null;
-    kind: string;
-    workspaceId: string;
-    role: 'attachment' | 'context';
-}
-interface TaskDispatchRequestPayload {
-    taskId: string;
-    /** Agent target for runtimeRoute='agent'. Shell dispatches do not use this. */
-    agentImUserId?: string;
-    /** Runtime/device target for runtimeRoute='shell'. */
-    targetDaemonId?: string;
-    profileId: string;
-    capability: string;
-    prompt: string;
-    /** Execution surface. `shell` is daemon-local command execution. */
-    runtimeRoute?: 'agent' | 'sandbox' | 'shell';
-    metadata?: Record<string, unknown>;
-    timeoutMs?: number;
-    context?: TaskDispatchContextEntry[];
-    conversationId?: string;
-    /**
-     * Channel mode for the originating conversation. Optional and
-     * forward-compatible: when missing, daemon renders 'unknown' in the
-     * [Channel context] prompt block. See appendChannelContext in
-     * daemon/dispatch.ts.
-     *   - `direct`: 1:1 DM (no @-mention needed in reply).
-     *   - `group`: multi-party room (end reply with `@<recipient>` to
-     *     continue the chain).
-     */
-    conversationType?: 'direct' | 'group';
-    /**
-     * Active participants of the dispatch's conversation. Daemon injects this
-     * into [Channel context] so the agent knows the authoritative recipient list
-     * without hallucinating or having to call `prismer.conversation.listAgents`. Capped at 50
-     * entries server-side.
-     */
-    participants?: Array<{
-        imUserId: string;
-        username: string;
-        displayName: string;
-        role: string;
-        agentType?: string | null;
-    }>;
-    /** Wave-8 W1: assets cloud wants daemon to fold into agent context. */
-    assetRefs?: AssetRef[];
-}
-interface TaskDispatchProgressPayload {
-    taskId: string;
-    progress: number;
-    message?: string;
-    detail?: Record<string, unknown>;
-}
-/** Wave-8 W1: how the daemon handled a single AssetRef. */
-type AssetDispatchStrategy = 'inline-text' | 'inline-text-truncated' | 'uri-only' | 'fetched-https' | 'error';
-interface AssetDispatchObservation {
-    /** AssetRef.assetId for cloud-attached refs; undefined for L5 https fetches. */
-    assetId?: string;
-    contentHash: string;
-    mime: string | null;
-    sizeBytes: number | null;
-    strategy: AssetDispatchStrategy;
-    inlinedBytes?: number;
-    error?: string;
-    /** L5: original URL the user wrote in the prompt. */
-    originalUrl?: string;
-    /** L5: post-redirect URL the body was actually downloaded from. */
-    finalUrl?: string;
-    /** L5: end-to-end fetch duration in ms (DNS + connect + body read). */
-    durationMs?: number;
-}
-interface TaskDispatchReplyPayload {
-    taskId: string;
-    ok: boolean;
-    output?: string;
-    error?: {
-        code: string;
-        message: string;
-    };
-    assetIds?: string[];
-    metrics?: {
-        tokensUsed?: number;
-        durationMs?: number;
-    };
-    /** Wave-8 W1: per-asset handling report. */
-    assetObservability?: AssetDispatchObservation[];
-}
-interface TaskCancelPayload {
-    taskId: string;
-    reason?: string;
-}
-interface IMWSMessage<T = unknown> {
-    type: string;
-    payload: T;
-    requestId?: string;
-    timestamp: number;
-}
-interface WorkspaceChangedPayload {
-    workspaceId: string;
-    /** ISO-8601 timestamp from im_workspaces.updatedAt. */
-    updatedAt: string;
-}
-interface AgentProfileChangedPayload {
-    profileId: string;
-    version: number;
-}
-interface AgentChangedPayload {
-    agentImUserId: string;
-    fields: {
-        displayName?: string;
-        capabilities?: string[];
-    };
-}
-interface WorkspaceFileChangedPayload {
-    workspaceId: string;
-    path: string;
-    operation: 'create' | 'update' | 'delete';
-    assetId?: string;
-    contentHash?: string;
-    version: number;
-}
-interface AssetChangedPayload {
-    workspaceId: string;
-    assetId: string;
-    operation: 'create' | 'update' | 'delete';
-    contentHash?: string;
-    assetIndexSeq?: number;
-    revision?: number;
-}
-
 type PrismerUriType = 'asset' | 'file';
 interface ParsedPrismerUri {
     /** Original full URI string. */
@@ -1479,6 +1768,29 @@ declare class OutboxWatcher {
     private currentScanDirs;
     private tick;
     private scanDir;
+    /**
+     * F2B — report an OUTBOX_MIME_MISMATCH task event to cloud so the task log
+     * gains an auditable record of the rejection. Without this, the failure is
+     * silent (file quarantined locally, agent unaware) and the next dispatch
+     * loops on the same bad strategy.
+     *
+     * Best-effort: every catch site swallows errors. We never want this
+     * upstream call to block local quarantine or trigger a retry loop, because
+     * the reject decision is already final by the time we get here.
+     *
+     * Endpoint contract: POST /api/im/tasks/:id/event
+     *   { code: 'OUTBOX_MIME_MISMATCH', payload: { file, daemonError }, message }
+     * Only callable when `task?.taskId` is known — pre-dispatch outbox files
+     * (no active task) are quarantined silently as before.
+     */
+    private reportMimeMismatchToCloud;
+    /**
+     * Move a file under `<dir>/_rejected/` so it stops being a scan candidate
+     * (the loop skips the reserved subdir) and operators can find the
+     * offending artifact. Filename collision is rare per task; on collision
+     * we append a millisecond suffix to keep the original observable.
+     */
+    private quarantine;
     private upload;
 }
 
@@ -1576,6 +1888,15 @@ interface DispatchDeps {
      * Keyed by workspaceId. If absent, #ref resolution is skipped entirely.
      */
     assetMetadataIndexes?: Map<string, AssetMetadataIndex>;
+    /**
+     * 14b D34=C — optional override for image vision-fallback. Enabled by
+     * default when image assetRefs are present.
+     */
+    visionAux?: {
+        enabled?: boolean;
+        cacheDir?: string;
+        timeoutMs?: number;
+    };
 }
 declare function handleDispatch(payload: TaskDispatchRequestPayload, requestId: string | undefined, deps: DispatchDeps): Promise<TaskDispatchReplyPayload>;
 /**
@@ -1907,6 +2228,14 @@ declare class LocalServer {
      * to `/api/sandboxes/:id/snapshot/manifest`.
      */
     private handleSnapshot;
+    /**
+     * POST /v1/agents/:agentId/dump-state — agent-scoped daemon manifest.
+     *
+     * This is narrower than `/v1/snapshot`: it walks only the current agent's
+     * profile/work dirs so cloud can attach the result to IMAgentSnapshot without
+     * capturing unrelated agents hosted in the same daemon/container.
+     */
+    private handleAgentDumpState;
     /**
      * POST /local/asset/write — agent-gen adapter RPC.
      *
@@ -1985,12 +2314,15 @@ declare class Runner extends EventEmitter {
     private workspaceId;
     private wsConnected;
     private readonly hostedAgents;
+    private readonly rejectedHostedAgentIds;
     private readonly runningTasks;
     private lastTaskError?;
     private heartbeatTimer?;
     private taskReaperTimer?;
     private skillResyncTimer?;
     private skillSyncInFlight;
+    private pendingReplyCache;
+    private pendingReplyRecoveryDone;
     constructor(opts?: RunnerOptions);
     start(): Promise<void>;
     /**
@@ -2076,11 +2408,40 @@ declare class Runner extends EventEmitter {
     private wireWsHandlers;
     private sendDeclare;
     private handleIncoming;
+    /**
+     * v2.0 §4.8.1 — webhook dispatch over WS reverse channel.
+     *
+     * Acks via `webhook.dispatch.reply { _rpcId, ok, acceptedAt }` immediately
+     * after `handleAgentMessageDispatch()` returns its synchronous response
+     * — the actual reply (the agent's reply text/attachments) still flows
+     * through `postMessageDispatchReply()` which posts to
+     * `/api/im/dispatch/reply` after the adapter finishes. That mirrors the
+     * HTTP /dispatch contract: ack first, asynchronous final reply via the
+     * dispatch-reply REST endpoint.
+     *
+     * The `_rpcId` field is the only addition versus the HTTP path; we strip
+     * it before passing the payload to the dispatch handler so existing
+     * validation logic doesn't trip on an unknown field.
+     */
+    private onWebhookDispatch;
     private onHostAcked;
+    private applyHostAckOwnershipLock;
     private onTaskDispatch;
     private onTaskCancel;
     private findMessageDispatchAgent;
     private postMessageDispatchReply;
+    /**
+     * v2.0 §4.8.1 (Wave 4-E4) — submit the transport-probe report. Called
+     * from `onHostAcked` so the daemon's container row exists in cloud
+     * before we POST to /runtime/transport-report.
+     *
+     * The gatewayUrl reported here is `http://<local-ipv4>:<localPort>`
+     * (typically `http://192.168.x.x:3210`). For a daemon without a local
+     * HTTP server (startLocalServer=false in tests) we still post the
+     * probe with `gatewayUrl=null` so cloud knows transport='ws' is the
+     * only path.
+     */
+    private reportTransport;
     private onAgentChanged;
     private onAgentProfileChanged;
     private syncProfileFromCloud;
@@ -2268,17 +2629,17 @@ declare const CodexConfigSchema: z.ZodObject<{
      */
     apiKeyEnv: z.ZodDefault<z.ZodString>;
 }, "strip", z.ZodTypeAny, {
+    sandbox: "read-only" | "workspace-write" | "danger-full-access";
     model: string;
     cwd: string;
-    sandbox: "read-only" | "workspace-write" | "danger-full-access";
     apiKeyEnv: string;
     systemPrompt?: string | undefined;
     envVars?: Record<string, string> | undefined;
 }, {
     cwd: string;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
     model?: string | undefined;
     systemPrompt?: string | undefined;
-    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
     envVars?: Record<string, string> | undefined;
     apiKeyEnv?: string | undefined;
 }>;
@@ -2294,4 +2655,4 @@ declare const codexAdapter: AdapterDef;
 declare function buildProgram(): Command;
 declare function runCli(argv?: string[]): Promise<void>;
 
-export { type AcquireResult, type AdapterDef, type AdapterKind, AdapterRegistry, type AdapterService, type AgentChangedPayload, type AgentDispatchReplyAttachment, type AgentDispatchReplyPayload, type AgentDispatchReplyStatus, type AgentDispatchRequest, type AgentDispatchResponse, type AgentHostDeclarePayload, type AgentProfile, type AgentProfileChangedPayload, type AgentStatusChangedPayload, AssetCache, type AssetCacheOptions, type AssetChangedPayload, type AssetDispatchObservation, type AssetDispatchStrategy, type AssetRef, BUILTIN_ROLE_TEMPLATES, type CachedAsset, type ClaudeCodeConfig, CloudClient, type CloudClientOptions, CloudError, type CloudResponse, type CodexConfig, type Config, type ConfigPaths, ConfigSchema, type DispatchDeps, type Envelope, type FlushFn, type FlushResult, type HealthStatus, type HermesProfileConfig, type HostAckedPayload, type HostedAgentDeclaration, type IMAgentStatus, type IMWSMessage, type LocalDb, LocalServer, type LocalServerOptions, type LocalServerState, type MessageDispatchAgent, type MessageDispatchDeps, type MessageDispatchHandle, type MessageDispatchTaskInput, type NormalizedContent, type OpenClawProfileConfig, type PairOptions, type PairResult, type ParseClaim, ParseClaimController, type ParseClaimControllerOptions, type ParsedPrismerUri, type PrismerUriType, type RoleTemplate, Runner, type RunnerOptions, ServicePool, type SyncOperation, SyncQueue, type SyncQueueRow, type SyncResourceType, type SyncStatus, SyncWorker, type SyncWorkerOptions, TARGET_SCHEMA_VERSION, type TaskCancelPayload, type TaskDispatchContextEntry, type TaskDispatchProgressPayload, type TaskDispatchReplyPayload, type TaskDispatchRequestPayload, type TaskInput, type TaskResult, UriResolver, type UriResolverOptions, type UrlResolution, type ValidationResult, WS_CLOSE, type WorkspaceChangedPayload, type WorkspaceFileBinding, type WorkspaceFileChangedPayload, WorkspaceMirror, type WorkspaceMirrorOptions, WsClient, type WsClientOptions, buildProgram, claudeCodeAdapter, codexAdapter, composePrompt, configExists, currentSchemaVersion, deriveWsUrl, envelope, extractHttpUrls, getRoleTemplate, handleAgentMessageDispatch, handleDispatch, hermesAdapter, isDaemonId, listRoleTemplates, loadConfig, newDaemonId, nextBackoffMs, openLocalDb, openclawAdapter, pair, parseCodexOutput, parseUris, resolvePaths, runCli, runMigrations, saveConfig };
+export { type AcquireResult, type AdapterDef, type AdapterKind, AdapterRegistry, type AdapterService, type AgentChangedPayload, type AgentDispatchReplyAttachment, type AgentDispatchReplyPayload, type AgentDispatchReplyStatus, type AgentDispatchRequest, type AgentDispatchResponse, type AgentHostDeclarePayload, type AgentProfile, type AgentProfileChangedPayload, type AgentStatusChangedPayload, AssetCache, type AssetCacheOptions, type AssetChangedPayload, type AssetDispatchObservation, type AssetDispatchStrategy, type AssetRef, BUILTIN_ROLE_TEMPLATES, type CachedAsset, type ClaudeCodeConfig, CloudClient, type CloudClientOptions, CloudError, type CloudResponse, type CodexConfig, type Config, type ConfigPaths, ConfigSchema, type DispatchDeps, type Envelope, type FlushFn, type FlushResult, type HealthStatus, type HermesProfileConfig, type HostAckedPayload, type HostedAgentDeclaration, type IMAgentStatus, type IMWSMessage, type LocalDb, LocalServer, type LocalServerOptions, type LocalServerState, type MessageDispatchAgent, type MessageDispatchDeps, type MessageDispatchHandle, type MessageDispatchTaskInput, type NormalizedContent, type OpenClawProfileConfig, type PairOptions, type PairResult, type ParseClaim, ParseClaimController, type ParseClaimControllerOptions, type ParsedPrismerUri, type PrismerUriType, type RejectedHostedAgent, type RoleTemplate, Runner, type RunnerOptions, ServicePool, type SyncOperation, SyncQueue, type SyncQueueRow, type SyncResourceType, type SyncStatus, SyncWorker, type SyncWorkerOptions, TARGET_SCHEMA_VERSION, type TaskCancelPayload, type TaskDispatchContextEntry, type TaskDispatchProgressPayload, type TaskDispatchReplyPayload, type TaskDispatchRequestPayload, type TaskInput, type TaskResult, UriResolver, type UriResolverOptions, type UrlResolution, type ValidationResult, WS_CLOSE, type WorkspaceChangedPayload, type WorkspaceFileBinding, type WorkspaceFileChangedPayload, WorkspaceMirror, type WorkspaceMirrorOptions, WsClient, type WsClientOptions, buildProgram, claudeCodeAdapter, codexAdapter, composePrompt, configExists, currentSchemaVersion, deriveWsUrl, envelope, extractHttpUrls, getRoleTemplate, handleAgentMessageDispatch, handleDispatch, hermesAdapter, isDaemonId, listRoleTemplates, loadConfig, newDaemonId, nextBackoffMs, openLocalDb, openclawAdapter, pair, parseCodexOutput, parseUris, resolvePaths, runCli, runMigrations, saveConfig };