@prismer/runtime 1.9.1 → 1.9.6

package/dist/index.d.cts

@@ -0,0 +1,1643 @@
+import { z } from 'zod';
+import { EventEmitter } from 'node:events';
+import Database from 'better-sqlite3';
+import { IncomingMessage, ServerResponse } from 'node:http';
+import { Command } from 'commander';
+
+type AdapterKind = 'long-running' | 'interactive';
+/**
+ * Adapter definition: how the daemon hosts one class of agent
+ * (Hermes, Claude Code, OpenClaw, ...).
+ *
+ * One Adapter ←(1:N)─ Agent ←(1:N)─ AgentProfile
+ *
+ * Long-running adapters implement {@link AdapterDef.ensureService} and
+ * return a reusable {@link AdapterService} (e.g. HTTP client to
+ * `hermes gateway`). Interactive adapters implement
+ * {@link AdapterDef.dispatch} and spawn a fresh subprocess per task
+ * (e.g. `claude --headless`).
+ */
+interface AdapterDef {
+    /** Unique name, e.g. 'hermes', 'claude-code'. Matches `IMAgentCard.adapterName`. */
+    name: string;
+    /** Long-running services expose ensureService; interactive adapters expose dispatch. */
+    kind: AdapterKind;
+    /** Capability tags surfaced to mobile (e.g. ['shell', 'code', 'mcp']). */
+    capabilities: string[];
+    /** Zod schema validating `AgentProfile.config` for this adapter. */
+    workspaceSchema: z.ZodSchema;
+    /** Long-running: ensure the underlying service is reachable. May spawn or just connect. */
+    ensureService?(profile: AgentProfile): Promise<AdapterService>;
+    /** Interactive: one-shot dispatch (spawn-per-task). */
+    dispatch?(profile: AgentProfile, task: TaskInput): Promise<TaskResult>;
+    /** Validate config before persisting `AgentProfile.config`. */
+    validate(config: unknown): ValidationResult;
+    /** Health probe — binary in PATH, HTTP endpoint reachable, etc. */
+    health(): Promise<HealthStatus>;
+}
+/**
+ * AgentProfile mirrors the cloud `im_agent_profiles` row.
+ *
+ * Field names match Track A's `IMAgentProfile` Prisma model + `AgentProfileDTO`
+ * in `src/im/api/agent-profiles.ts` (m1, merged in d5186ca / a4b3d89).
+ *
+ * Daemon-local SQLite mirror columns use snake_case
+ * (workspace_id / agent_im_user_id) per docs/refactor/04-daemon-runtime.md
+ * §SQLite schema; the TS types stay camelCase across the boundary.
+ */
+interface AgentProfile {
+    id: string;
+    workspaceId: string;
+    agentImUserId: string;
+    adapterName: string;
+    name: string;
+    config: Record<string, unknown>;
+    version: number;
+    createdAt: Date;
+    updatedAt: Date;
+    /**
+     * IMUser.username of the agent bound to this profile. Used by long-running
+     * adapters (e.g. Hermes) to derive a stable, human-readable per-agent
+     * profile directory and to scope MCP env so per-call agent identity is not
+     * lost when multiple agents share a daemon. Parallel task F1 populates this
+     * on the cloud DTO; runtime treats it as optional to stay backwards-compat
+     * with snapshots produced before F1 lands.
+     */
+    agentUsername?: string;
+}
+interface TaskInput {
+    taskId: string;
+    prompt: string;
+    metadata?: Record<string, unknown>;
+    timeoutMs?: number;
+    onProgress?: (p: {
+        progress: number;
+        message?: string;
+        detail?: Record<string, unknown>;
+    }) => void;
+    signal?: AbortSignal;
+}
+interface TaskResult {
+    ok: boolean;
+    output?: string;
+    error?: {
+        code: string;
+        message: string;
+    };
+    artifacts?: Array<{
+        kind: string;
+        storageUri: string;
+        mime?: string;
+        size?: number;
+    }>;
+    metrics?: {
+        tokensUsed?: number;
+        durationMs?: number;
+    };
+    /** Adapter-private metadata used by daemon-side bridges/observability. */
+    metadata?: Record<string, unknown>;
+}
+/**
+ * Reusable handle to a long-running adapter's underlying service.
+ * For Hermes this wraps an HTTP client to `hermes gateway`; for OpenClaw
+ * (1.9.5+) it wraps an in-process TS worker.
+ */
+interface AdapterService {
+    /** Service-specific identifier (e.g. 'http://127.0.0.1:8642' for hermes). */
+    id: string;
+    dispatch(task: TaskInput): Promise<TaskResult>;
+    healthy(): Promise<boolean>;
+    /** Optional: stop the service. May be no-op if user owns lifecycle. */
+    shutdown?(): Promise<void>;
+    /** Optional: subscribe to crash events. */
+    on?(event: 'crash', cb: (err: Error) => void): void;
+}
+interface ValidationResult {
+    ok: boolean;
+    errors?: string[];
+}
+interface HealthStatus {
+    available: boolean;
+    reason?: string;
+    hint?: string;
+}
+
+/**
+ * Process-wide adapter registry.
+ *
+ * Maps `adapter.name` → {@link AdapterDef}. Selection policy lives in
+ * `daemon/dispatch.ts`; the registry is just a typed Map.
+ *
+ * Shell cherry-picked (conceptually, not via cp) from
+ * `feat/release190-milestone:sdk/prismer-cloud/runtime/src/adapter-registry.ts`.
+ * The registered type was swapped `AdapterImpl` → `AdapterDef` per the
+ * 1.9.x adapter contract; `tiersSupported` (PARA tier) is dropped — 1.9.x
+ * uses capability tags only.
+ */
+declare class AdapterRegistry {
+    private readonly adapters;
+    register(adapter: AdapterDef): void;
+    unregister(name: string): boolean;
+    has(name: string): boolean;
+    get(name: string): AdapterDef | undefined;
+    list(): AdapterDef[];
+    size(): number;
+    /**
+     * Find adapters that satisfy a capability tag.
+     *
+     * Match rules (deterministic, sorted by name):
+     * - exact: adapter declared the tag verbatim
+     * - wildcard: adapter declared `code.*` → matches `code.write`
+     */
+    findByCapability(capability: string): AdapterDef[];
+}
+
+declare const HermesProfileConfigSchema: z.ZodObject<{
+    /** Hermes profile name (default: AgentProfile.id slice). */
+    hermesProfileName: z.ZodOptional<z.ZodString>;
+    /** Hermes API server port. Distinct profiles use distinct ports to avoid clashes. */
+    port: z.ZodDefault<z.ZodNumber>;
+    /** Bearer token from `~/.hermes/.env API_SERVER_KEY`. */
+    apiKey: z.ZodString;
+    /** Auto-spawn `hermes -p <name> gateway run` if not reachable. Default false. */
+    autoStart: z.ZodDefault<z.ZodBoolean>;
+    /** Wait timeout when autoStart=true. */
+    startupTimeoutMs: z.ZodDefault<z.ZodNumber>;
+    /**
+     * Configure Hermes' inference provider to use Prismer Cloud's existing
+     * OpenAI-compatible provider endpoint before starting the gateway.
+     */
+    configurePrismerProvider: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Auto-install the @prismer/mcp-server stdio MCP server into the Hermes
+     * profile so the long-running role agent can drive Workspace tasks
+     * (create / update / approve / move) through tool calls. Default true.
+     */
+    installPrismerMcpServer: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Override the absolute path to @prismer/mcp-server's `dist/index.js`.
+     * If unset the adapter resolves it via Node's module resolver from the
+     * runtime install location, then falls back to PRISMER_MCP_SERVER env.
+     */
+    prismerMcpServerPath: z.ZodOptional<z.ZodString>;
+    /** Model sent to Prismer's /api/v1/chat/completions endpoint. */
+    model: z.ZodDefault<z.ZodString>;
+    /** Named custom provider written into Hermes config.yaml. */
+    prismerProviderName: z.ZodDefault<z.ZodString>;
+    /** Override cloud provider base. Defaults to PRISMER_BASE_URL + /api/v1. */
+    prismerProviderBaseUrl: z.ZodOptional<z.ZodString>;
+    /** Env key Hermes reads from profile .env for the Prismer API key. */
+    prismerApiKeyEnv: z.ZodDefault<z.ZodString>;
+    /**
+     * Mirror Prismer work_item projections into Hermes native Kanban as triage
+     * cards. Triage avoids duplicate execution; Prismer's agent_run remains the
+     * executable source of truth.
+     */
+    mirrorNativeKanban: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Mirror Prismer standing-objective IMTask projections into Hermes' native
+     * per-session GoalManager state (`state.db.state_meta["goal:<session_id>"]`).
+     * Hermes has no public goals REST/CLI surface; this writes the documented
+     * native state key directly and records the exact bridge result on the task.
+     */
+    mirrorNativeGoals: z.ZodDefault<z.ZodBoolean>;
+    /**
+     * Optional checkout path for Hermes Agent source. Used only as a fallback
+     * when the installed `hermes` binary is older than the native Kanban CLI
+     * surface but the local source tree contains hermes_cli/kanban_db.py.
+     */
+    hermesSourceDir: z.ZodOptional<z.ZodString>;
+    nativeMirrorTimeoutMs: z.ZodDefault<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    port: number;
+    apiKey: string;
+    autoStart: boolean;
+    startupTimeoutMs: number;
+    configurePrismerProvider: boolean;
+    installPrismerMcpServer: boolean;
+    model: string;
+    prismerProviderName: string;
+    prismerApiKeyEnv: string;
+    mirrorNativeKanban: boolean;
+    mirrorNativeGoals: boolean;
+    nativeMirrorTimeoutMs: number;
+    hermesProfileName?: string | undefined;
+    prismerMcpServerPath?: string | undefined;
+    prismerProviderBaseUrl?: string | undefined;
+    hermesSourceDir?: string | undefined;
+}, {
+    apiKey: string;
+    hermesProfileName?: string | undefined;
+    port?: number | undefined;
+    autoStart?: boolean | undefined;
+    startupTimeoutMs?: number | undefined;
+    configurePrismerProvider?: boolean | undefined;
+    installPrismerMcpServer?: boolean | undefined;
+    prismerMcpServerPath?: string | undefined;
+    model?: string | undefined;
+    prismerProviderName?: string | undefined;
+    prismerProviderBaseUrl?: string | undefined;
+    prismerApiKeyEnv?: string | undefined;
+    mirrorNativeKanban?: boolean | undefined;
+    mirrorNativeGoals?: boolean | undefined;
+    hermesSourceDir?: string | undefined;
+    nativeMirrorTimeoutMs?: number | undefined;
+}>;
+type HermesProfileConfig = z.infer<typeof HermesProfileConfigSchema>;
+declare const hermesAdapter: AdapterDef;
+
+interface WsClientOptions {
+    /** Cloud WS URL, e.g. `wss://cloud.prismer.dev/ws` or `ws://127.0.0.1:3000/ws`. */
+    url: string;
+    /** API key passed as `?token=<apiKey>` (matches 1.7.x token query auth). */
+    apiKey: string;
+    /** Initial reconnect delay (ms). Defaults to 1000. */
+    reconnectInitialMs?: number;
+    /** Reconnect cap (ms). Defaults to 60_000. */
+    reconnectMaxMs?: number;
+    /** Max consecutive reconnect attempts before entering degraded mode. Defaults to 30. */
+    maxReconnectAttempts?: number;
+    /** How long to stay in degraded mode before retrying (ms). Defaults to 5 minutes. */
+    degradedCooldownMs?: number;
+}
+/** Subset of close codes we special-case. */
+declare const WS_CLOSE: {
+    /** RFC 6455 normal closure — no reconnect. */
+    readonly NORMAL: 1000;
+    /** Custom auth failure — no auto-reconnect; surface to user. */
+    readonly AUTH: 4001;
+};
+/**
+ * Events emitted:
+ *  - `open`             ws successfully opened
+ *  - `message` (msg)    incoming JSON-parsed message
+ *  - `close` (code, reason)  connection closed (auto-reconnect happens after this)
+ *  - `error` (err)      transport error or invalid JSON received
+ *  - `drop` (msg)       send() called when not OPEN; caller may enqueue
+ *  - `auth-failed`      close code 4001 — user must rerun setup; no auto-reconnect
+ *  - `degraded`         max reconnect attempts hit; pausing for cooldown
+ *  - `reconnect-scheduled` (ms) reconnect timer set
+ */
+declare class WsClient extends EventEmitter {
+    private opts;
+    private ws?;
+    private reconnectMs;
+    private reconnectAttempts;
+    private closed;
+    private reconnectTimer?;
+    constructor(opts: WsClientOptions);
+    start(): void;
+    /** Send a JSON-serializable message. Caller is responsible for envelope construction. */
+    send(msg: unknown): void;
+    /** Close intentionally — no reconnect. */
+    close(code?: 1000): void;
+    isOpen(): boolean;
+    private connect;
+    private scheduleReconnect;
+}
+
+type LocalDb = Database.Database;
+/**
+ * Open `~/.prismer/local.db` (or any path), enable WAL, run migrations.
+ * Idempotent — safe to call multiple times.
+ *
+ * Pass `:memory:` for in-test usage.
+ */
+declare function openLocalDb(path: string): LocalDb;
+declare function runMigrations(db: LocalDb): void;
+declare function currentSchemaVersion(db: LocalDb): number;
+declare const TARGET_SCHEMA_VERSION = 2;
+
+type SyncResourceType = 'workspace' | 'agent' | 'agent_profile';
+type SyncOperation = 'create' | 'update' | 'delete';
+type SyncStatus = 'pending' | 'failed_conflict' | 'failed_other';
+interface SyncQueueRow {
+    id: number;
+    resource_type: SyncResourceType;
+    resource_id: string;
+    operation: SyncOperation;
+    payload: string;
+    attempt_count: number;
+    last_attempt_at: number | null;
+    next_attempt_at: number;
+    status: SyncStatus;
+}
+declare function nextBackoffMs(attemptCount: number): number;
+declare class SyncQueue {
+    private db;
+    constructor(db: LocalDb);
+    enqueue(input: {
+        resourceType: SyncResourceType;
+        resourceId: string;
+        operation: SyncOperation;
+        payload: unknown;
+        /** Defaults to now (ready immediately). */
+        runAt?: number;
+    }): number;
+    /** Take up to `limit` rows whose next_attempt_at <= now and status='pending'. Oldest first. */
+    dequeueBatch(limit: number, now?: number): SyncQueueRow[];
+    markCompleted(id: number): void;
+    markConflict(id: number): void;
+    /** Increment attempt + reschedule via backoff. Caller passes the current attempt_count. */
+    markBackoff(id: number, currentAttemptCount: number): void;
+    /** Permanent failure (4xx other than 409). */
+    markFailedOther(id: number): void;
+    pendingCount(): number;
+    /** All rows for a given resource (debugging / CLI status). */
+    listForResource(type: SyncResourceType, id: string): SyncQueueRow[];
+}
+
+interface FlushResult {
+    ok: boolean;
+    /** HTTP status when applicable. 409 → markConflict; 400-499 (other) → markFailedOther; else markBackoff. */
+    status?: number;
+    message?: string;
+}
+/** Caller injects the actual cloud HTTP push (m3). Scaffold uses a noop that returns ok:true. */
+type FlushFn = (row: SyncQueueRow) => Promise<FlushResult>;
+interface SyncWorkerOptions {
+    queue: SyncQueue;
+    flush: FlushFn;
+    /** Tick interval in ms. Defaults to 5000. */
+    tickMs?: number;
+    /** Max rows per tick. Defaults to 10. */
+    batchSize?: number;
+}
+/**
+ * Events:
+ *  - `tick` ({ pending, processed })   each completed tick
+ *  - `flushed` (row, result)           one row push outcome
+ *  - `error` (err, row?)               unexpected error in flush()
+ */
+declare class SyncWorker extends EventEmitter {
+    private opts;
+    private timer?;
+    private running;
+    constructor(opts: SyncWorkerOptions);
+    start(): void;
+    stop(): void;
+    /**
+     * Drain up to `batchSize` ready rows. Public for test injection.
+     * Re-entrant guarded — concurrent ticks return immediately.
+     */
+    tick(): Promise<{
+        processed: number;
+    }>;
+    private handleResult;
+}
+
+interface RoleTemplate {
+    templateName: string;
+    displayName: string;
+    description: string;
+    applicableAdapters: string[];
+    configSchema: Record<string, unknown>;
+}
+declare const BUILTIN_ROLE_TEMPLATES: ReadonlyArray<RoleTemplate>;
+declare function getRoleTemplate(name: string): RoleTemplate | undefined;
+declare function listRoleTemplates(): ReadonlyArray<{
+    name: string;
+    displayName: string;
+    description: string;
+}>;
+
+declare const ConfigSchema: z.ZodObject<{
+    /** API key from `prismer setup`, or env override. */
+    api_key: z.ZodString;
+    /** Cloud REST + WS base; `ws://` is derived by stripping `http`. */
+    cloud_api_base: z.ZodString;
+    /** Stable per-machine daemon identifier. Generated once on first setup. */
+    daemon_id: z.ZodString;
+    /** Optional adapter-specific overrides keyed by adapter name. */
+    adapters: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodRecord<z.ZodString, z.ZodUnknown>>>;
+    /** Local daemon shell execution. Default disabled. */
+    shell: z.ZodOptional<z.ZodObject<{
+        enabled: z.ZodDefault<z.ZodBoolean>;
+        default_cwd: z.ZodOptional<z.ZodString>;
+        defaultCwd: z.ZodOptional<z.ZodString>;
+        shell: z.ZodOptional<z.ZodEnum<["bash", "zsh", "sh"]>>;
+        max_timeout_ms: z.ZodOptional<z.ZodNumber>;
+        maxTimeoutMs: z.ZodOptional<z.ZodNumber>;
+        max_output_bytes: z.ZodOptional<z.ZodNumber>;
+        maxOutputBytes: z.ZodOptional<z.ZodNumber>;
+        allowed_workspaces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        allowedWorkspaces: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    }, "strip", z.ZodTypeAny, {
+        enabled: boolean;
+        shell?: "bash" | "zsh" | "sh" | undefined;
+        default_cwd?: string | undefined;
+        defaultCwd?: string | undefined;
+        max_timeout_ms?: number | undefined;
+        maxTimeoutMs?: number | undefined;
+        max_output_bytes?: number | undefined;
+        maxOutputBytes?: number | undefined;
+        allowed_workspaces?: string[] | undefined;
+        allowedWorkspaces?: string[] | undefined;
+    }, {
+        shell?: "bash" | "zsh" | "sh" | undefined;
+        enabled?: boolean | undefined;
+        default_cwd?: string | undefined;
+        defaultCwd?: string | undefined;
+        max_timeout_ms?: number | undefined;
+        maxTimeoutMs?: number | undefined;
+        max_output_bytes?: number | undefined;
+        maxOutputBytes?: number | undefined;
+        allowed_workspaces?: string[] | undefined;
+        allowedWorkspaces?: string[] | undefined;
+    }>>;
+    /** Local cache settings. */
+    cache: z.ZodOptional<z.ZodObject<{
+        max_bytes: z.ZodDefault<z.ZodNumber>;
+    }, "strip", z.ZodTypeAny, {
+        max_bytes: number;
+    }, {
+        max_bytes?: number | undefined;
+    }>>;
+}, "strip", z.ZodTypeAny, {
+    api_key: string;
+    cloud_api_base: string;
+    daemon_id: string;
+    shell?: {
+        enabled: boolean;
+        shell?: "bash" | "zsh" | "sh" | undefined;
+        default_cwd?: string | undefined;
+        defaultCwd?: string | undefined;
+        max_timeout_ms?: number | undefined;
+        maxTimeoutMs?: number | undefined;
+        max_output_bytes?: number | undefined;
+        maxOutputBytes?: number | undefined;
+        allowed_workspaces?: string[] | undefined;
+        allowedWorkspaces?: string[] | undefined;
+    } | undefined;
+    adapters?: Record<string, Record<string, unknown>> | undefined;
+    cache?: {
+        max_bytes: number;
+    } | undefined;
+}, {
+    api_key: string;
+    cloud_api_base: string;
+    daemon_id: string;
+    shell?: {
+        shell?: "bash" | "zsh" | "sh" | undefined;
+        enabled?: boolean | undefined;
+        default_cwd?: string | undefined;
+        defaultCwd?: string | undefined;
+        max_timeout_ms?: number | undefined;
+        maxTimeoutMs?: number | undefined;
+        max_output_bytes?: number | undefined;
+        maxOutputBytes?: number | undefined;
+        allowed_workspaces?: string[] | undefined;
+        allowedWorkspaces?: string[] | undefined;
+    } | undefined;
+    adapters?: Record<string, Record<string, unknown>> | undefined;
+    cache?: {
+        max_bytes?: number | undefined;
+    } | undefined;
+}>;
+type Config = z.infer<typeof ConfigSchema>;
+interface ConfigPaths {
+    /** Default `~/.prismer`. */
+    root: string;
+    configFile: string;
+    localDb: string;
+    cacheDir: string;
+    logsDir: string;
+    /**
+     * Per-task run scratch dirs. Each chat-mention dispatch creates
+     * `${runsDir}/${taskId}/_outbox/` for adapter-produced files; the
+     * OutboxWatcher uploads from there into IMAssets.
+     */
+    runsDir: string;
+}
+/**
+ * Resolve paths for the prismer home directory. Honors `PRISMER_HOME` env var;
+ * defaults to `~/.prismer`.
+ */
+declare function resolvePaths(home?: string): ConfigPaths;
+declare function configExists(paths?: ConfigPaths): boolean;
+/**
+ * Read and validate config. Env vars override file values for `api_key` and
+ * `cloud_api_base` (handy in CI / dev without rewriting config.toml).
+ */
+declare function loadConfig(paths?: ConfigPaths): Config;
+declare function saveConfig(config: Config, paths?: ConfigPaths): void;
+/** Derive a `wss?://` URL from a `https?://` base. Trailing `/ws` appended. */
+declare function deriveWsUrl(httpBase: string): string;
+
+declare function newDaemonId(): string;
+declare function isDaemonId(s: string): boolean;
+
+interface CloudClientOptions {
+    baseUrl: string;
+    apiKey: string;
+    /** Per-request timeout (ms). Defaults to 30s. */
+    defaultTimeoutMs?: number;
+    /** Pluggable fetch (tests inject a stub). */
+    fetchImpl?: typeof fetch;
+}
+interface CloudResponse<T> {
+    ok: boolean;
+    status: number;
+    data?: T;
+    error?: {
+        code: string;
+        message: string;
+    };
+}
+declare class CloudClient {
+    private readonly opts;
+    private readonly fetchImpl;
+    constructor(opts: CloudClientOptions);
+    /** Low-level request. Caller decides on retry; sync-worker handles backoff. */
+    request<T = unknown>(method: 'GET' | 'POST' | 'PATCH' | 'PUT' | 'DELETE', path: string, init?: {
+        body?: unknown;
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+        auth?: boolean;
+    }): Promise<CloudResponse<T>>;
+    /** Convenience: GET expecting `{ ok, data }` envelope. Returns `data` or throws. */
+    get<T>(path: string, opts?: {
+        signal?: AbortSignal;
+    }): Promise<T>;
+    urlFor(path: string): string;
+    /** Raw byte download (for asset cache). Returns response so caller can stream body. */
+    fetchRaw(path: string, init?: {
+        headers?: Record<string, string>;
+        signal?: AbortSignal;
+        timeoutMs?: number;
+    }): Promise<Response>;
+}
+declare class CloudError extends Error {
+    readonly status: number;
+    readonly code: string;
+    constructor(status: number, code: string, message: string);
+}
+
+interface Envelope<T = unknown> {
+    type: string;
+    payload: T;
+    requestId?: string;
+    timestamp: number;
+}
+declare function envelope<T>(type: string, payload: T, requestId?: string): Envelope<T>;
+
+interface CachedAsset {
+    contentHash: string;
+    sizeBytes: number;
+    mime: string | null;
+    localPath: string;
+    fetchedAt: number;
+    lastUsedAt: number;
+    pin: boolean;
+}
+interface AssetCacheOptions {
+    db: LocalDb;
+    cloud: CloudClient;
+    /** ~/.prismer/cache. */
+    cacheDir: string;
+    /** LRU cap in bytes. Default 5 GiB. */
+    maxBytes?: number;
+}
+/**
+ * Local asset cache.
+ *
+ * `getOrFetch(hash, opts)` returns the local path; downloads from
+ * `GET /api/im/assets/by-hash/:hash?wsId=…` on miss. Pinned rows survive LRU.
+ */
+declare class AssetCache {
+    private readonly db;
+    private readonly cloud;
+    private readonly cacheDir;
+    private readonly maxBytes;
+    constructor(opts: AssetCacheOptions);
+    /** Local file path for a content hash. Files split by first 2 chars for fs scaling. */
+    pathFor(hash: string): string;
+    get(hash: string): CachedAsset | undefined;
+    /** Bump `last_used_at` (call when an asset is consulted). */
+    touch(hash: string): void;
+    pin(hash: string): void;
+    unpin(hash: string): void;
+    /**
+     * Get or fetch by hash. On miss, downloads the raw bytes and caches them.
+     *
+     * Why two endpoints: `GET /api/im/assets/by-hash/:hash` returns the JSON
+     * `AssetDTO` (id, contentHash, storageUri, …) — *metadata only*. The raw
+     * bytes live at `GET /api/im/assets/:id`. If `opts.assetId` is supplied
+     * the caller already has the id from an `AssetRef`, so we go straight to
+     * the byte endpoint; otherwise we resolve `hash → id` first (one extra
+     * round-trip on the metadata route) before downloading the body.
+     *
+     * Earlier this method called `by-hash` and treated the JSON body as the
+     * asset content — the daemon stored the 500-byte metadata blob on disk
+     * and `resolveAssetRefs` inlined that JSON into the prompt. The agent
+     * saw `{"id":"…","storageUri":"…"}` instead of the user's file and
+     * concluded the upload had failed.
+     */
+    getOrFetch(hash: string, opts?: {
+        workspaceIdHint?: string;
+        signal?: AbortSignal;
+        assetId?: string;
+    }): Promise<CachedAsset>;
+    /** Insert an already-on-disk asset into the cache (e.g., asset just produced by adapter). */
+    registerLocal(hash: string, localPath: string, mime?: string): CachedAsset;
+    /** Total bytes across all rows (incl. pinned). */
+    totalBytes(): number;
+    /** Run LRU eviction until under cap. Pinned rows are never evicted. */
+    evictIfOver(): {
+        removed: number;
+        freed: number;
+    };
+}
+
+interface WorkspaceFileBinding {
+    workspaceId: string;
+    path: string;
+    assetId: string;
+    contentHash: string;
+    version: number;
+    syncedAt: number | null;
+    dirty: boolean;
+}
+interface WorkspaceMirrorOptions {
+    db: LocalDb;
+    cloud: CloudClient;
+    workspaceId: string;
+    /**
+     * Per-workspace state dir. Caller should pass ~/.prismer/<wid>/ so different
+     * paired workspaces don't race on the cursor file.
+     */
+    workspaceStateDir: string;
+}
+/**
+ * Mirror reads cloud-side path→asset bindings into SQLite for fast local
+ * lookup. The cursor file is the only piece of state that must survive
+ * daemon restart; the SQLite mirror is rebuilt from scratch by the very
+ * first pullDelta() with no cursor.
+ */
+declare class WorkspaceMirror {
+    private readonly db;
+    private readonly cloud;
+    private readonly workspaceId;
+    private readonly cursorPath;
+    constructor(opts: WorkspaceMirrorOptions);
+    /** Persisted cursor for this workspace, or null on first run / corrupted file. */
+    readCursor(): string | null;
+    private writeCursor;
+    /**
+     * Pull workspace_file changes since the persisted cursor and upsert into
+     * the local mirror. Soft-deleted rows are removed from the mirror; active
+     * rows are upserted with synced_at = now and dirty = 0.
+     *
+     * Returns the count of items applied + the new cursor (may be unchanged
+     * when the cloud has nothing new). Idempotent — safe to retry.
+     */
+    pullDelta(opts?: {
+        signal?: AbortSignal;
+    }): Promise<{
+        applied: number;
+        cursor: string | null;
+    }>;
+    /** Lookup the active binding for a workspace path. Returns undefined if not mirrored. */
+    lookupByPath(path: string): WorkspaceFileBinding | undefined;
+    /** Find an asset's contentHash via any path binding (asset may map to many paths). */
+    hashForAssetId(assetId: string): string | undefined;
+    /** All active bindings for this workspace — used by status / debug surfaces. */
+    list(): WorkspaceFileBinding[];
+    /** Wipe the mirror for this workspace (e.g., re-pair). Cursor file is left intact. */
+    clear(): void;
+}
+
+interface ParseClaim {
+    id: string;
+    workspaceId: string;
+    assetId: string;
+    ingestVersion: number;
+    claimantImUserId: string;
+    claimantDeviceId: string;
+    status: 'active' | 'completed' | 'abandoned';
+    claimedAt: string;
+    heartbeatAt: string;
+    completedAt: string | null;
+}
+type AcquireResult = {
+    kind: 'acquired';
+    claim: ParseClaim;
+} | {
+    kind: 'refreshed';
+    claim: ParseClaim;
+} | {
+    kind: 'claimed_active';
+    current: ParseClaim;
+} | {
+    kind: 'already_complete';
+    current: ParseClaim;
+};
+type ClaimLostReason = 'claim_taken_over' | 'claim_inactive';
+interface ParseClaimControllerOptions {
+    cloud: CloudClient;
+    /** Daemon's persisted device id. Same value across heartbeats / completions. */
+    deviceId: string;
+    /** Heartbeat interval (ms). Default 10s — well below the 30s server TTL. */
+    heartbeatIntervalMs?: number;
+}
+interface HeartbeatHandle {
+    stop: () => void;
+    /**
+     * Symbol.dispose so consumers can write `using hb = ctrl.startHeartbeat(...)`
+     * once they're on TypeScript 5.2 + Node 22 explicit-resource-management.
+     * Without that runtime support the field is harmless dead weight; the
+     * explicit `stop()` is the universal contract.
+     */
+    [Symbol.dispose]: () => void;
+}
+/**
+ * Coordinates a single daemon's asset-parse claims. Owns no global state —
+ * callers may run multiple controllers if they share the same device id.
+ */
+declare class ParseClaimController {
+    private readonly cloud;
+    private readonly deviceId;
+    private readonly heartbeatIntervalMs;
+    constructor(opts: ParseClaimControllerOptions);
+    /**
+     * Acquire (or refresh) a claim. The return value is a 4-variant tagged
+     * union — callers must branch on `kind`. Throws on transport / 5xx / 4xx
+     * codes that aren't part of the documented contract (e.g. `claim_race`
+     * is mapped to a thrown Error so the worker can retry).
+     */
+    acquire(input: {
+        assetId: string;
+        ingestVersion: number;
+    }): Promise<AcquireResult>;
+    /**
+     * Refresh the heartbeat for an active claim. Throws `ClaimLostError` on
+     * HTTP 410 with code `claim_taken_over` or `claim_inactive` — caller
+     * should abort the parse work. Throws plain `Error` on any other failure.
+     */
+    sendHeartbeat(claimId: string): Promise<ParseClaim>;
+    /**
+     * Mark a claim complete. Throws `ClaimLostError` on 410 (claim was
+     * stolen before the worker finished — output should be discarded).
+     */
+    complete(claimId: string): Promise<ParseClaim>;
+    /**
+     * Start a heartbeat loop in the background. Returns a handle with `stop()`
+     * and a Symbol.dispose alias for the `using` pattern.
+     *
+     * On 410 (claim taken over or marked inactive) the loop stops itself and
+     * invokes `opts.onLost` so the parse worker can abort. Other transient
+     * errors (network blip, 5xx) are logged to stderr and the loop retries on
+     * the next tick — the server-side TTL (default 30s) will only drop us if
+     * the partition outlasts the TTL.
+     */
+    startHeartbeat(claimId: string, opts?: {
+        onLost?: (reason: ClaimLostReason) => void;
+    }): HeartbeatHandle;
+}
+
+type PrismerUriType = 'asset' | 'file';
+interface ParsedPrismerUri {
+    /** Original full URI string. */
+    raw: string;
+    /**
+     * Owner segment for legacy `prismer://<owner>/...` form (informational,
+     * not ACL-checked). For `prismer://workspace/<wid>/...` this is the
+     * literal string 'workspace' — prefer `workspaceId` instead.
+     */
+    owner: string;
+    type: PrismerUriType;
+    /** For type='asset': the sha256 hash. For legacy file URIs: '<wsId>/<path>'. */
+    rest: string;
+    /** Convenience parses for type='file' and for workspace-form 'asset'. */
+    workspaceId?: string;
+    filePath?: string;
+}
+/**
+ * Find every recognized `prismer://...` reference in a string.
+ * Only `asset` and `file` types are recognized — other types (memory,
+ * context, conversation, evolution, task, pair) pass through untouched.
+ */
+declare function parseUris(text: string): ParsedPrismerUri[];
+interface UriResolverOptions {
+    db: LocalDb;
+    cloud: CloudClient;
+    assetCache: AssetCache;
+}
+declare class UriResolver {
+    private readonly db;
+    private readonly cloud;
+    private readonly assetCache;
+    constructor(opts: UriResolverOptions);
+    /**
+     * Resolve a single URI to a local file path. Throws on auth/4xx;
+     * caller decides whether to leave the URI in place (best-effort) or fail.
+     */
+    resolveOne(uri: ParsedPrismerUri, opts?: {
+        signal?: AbortSignal;
+    }): Promise<string>;
+    /**
+     * Walk a string, replace every `prismer://(asset|file)/...` with `file://<localPath>`.
+     * Unrecognized URIs pass through. Returns rewritten text + the list of pinned hashes.
+     */
+    rewrite(text: string, opts?: {
+        pin?: boolean;
+        signal?: AbortSignal;
+    }): Promise<{
+        text: string;
+        resolvedHashes: string[];
+    }>;
+    /** Bulk-rewrite an array of strings (e.g. context entries' content). */
+    rewriteAll(texts: string[], opts?: {
+        pin?: boolean;
+        signal?: AbortSignal;
+    }): Promise<{
+        texts: string[];
+        resolvedHashes: string[];
+    }>;
+    private lookupFile;
+}
+
+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[];
+}
+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' | 'error';
+interface AssetDispatchObservation {
+    assetId: string;
+    contentHash: string;
+    mime: string | null;
+    sizeBytes: number | null;
+    strategy: AssetDispatchStrategy;
+    inlinedBytes?: number;
+    error?: string;
+}
+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 OutboxWatcherOptions {
+    /**
+     * Default directory to watch when no setActiveTask has narrowed it.
+     * Container mode: `/workspace/_outbox`. Host mode: omit (no default
+     * scan — only watch when an active task points at a specific dir).
+     */
+    outboxDir?: string;
+    /** Cloud client (already configured with apiKey + baseUrl). */
+    cloud: CloudClient;
+    /**
+     * Container identifier — required by the cloud's kind=sandbox-output
+     * contract as metadata.containerId. Read from env PRISMER_CONTAINER_ID
+     * when controller injected one; otherwise the daemon_id as fallback so
+     * the request still passes validation. Host-mode (kind=agent-output)
+     * uploads bypass containerId validation.
+     */
+    containerId: string;
+    /**
+     * Resolver for the owning workspace at upload time. Returns null when no
+     * workspace context is yet known — the watcher will skip the file and
+     * retry on the next scan tick.
+     */
+    workspaceId: () => string | null;
+    /** Poll interval in ms. Default 2000. */
+    pollIntervalMs?: number;
+    /** Optional log sink (default writes to stdout/stderr). */
+    log?: {
+        info: (msg: string) => void;
+        warn: (msg: string) => void;
+    };
+}
+interface ActiveTask {
+    taskId: string;
+    /** Adapter name; surfaces in upload metadata for observability. */
+    adapter?: string;
+    /**
+     * Per-task outbox directory. When set, scans this directory in
+     * addition to `opts.outboxDir`. Files uploaded from here are tagged
+     * with `kind=agent-output` (host-mode contract).
+     */
+    outboxDir?: string;
+}
+declare class OutboxWatcher {
+    private opts;
+    private timer?;
+    private uploaded;
+    /**
+     * Host-mode tasks keyed by taskId. Each entry has its own `outboxDir`
+     * and the watcher scans every entry's directory each tick. Concurrent
+     * dispatches (Wave-9: orchestrator + spawned worker on the same daemon)
+     * each occupy their own slot — finishing one dispatch only removes its
+     * slot, leaving every other concurrent dispatch's tracking intact.
+     *
+     * Replaces the v1 single `activeTask` slot which was last-wins and
+     * caused cross-dispatch clobbering: an orchestrator finishing first
+     * would `setActiveTask(null)` and silently discard the concurrent
+     * worker's outbox tracking.
+     */
+    private activeTasks;
+    /**
+     * Legacy container/sandbox task. Used only when an `ActiveTask` is set
+     * **without** an `outboxDir` (i.e. the legacy `setActiveTask` shape
+     * where the watcher's default `opts.outboxDir` is the scan target).
+     * Single slot because the legacy container deployment only ever runs
+     * one task at a time per container.
+     */
+    private legacyContainerTask;
+    private busy;
+    /**
+     * Per-task accumulated assetIds. Populated on each successful upload
+     * keyed by the task whose outbox dir the file came from.
+     * `flushPending(taskId)` drains and returns this list so dispatch.ts
+     * can stamp it onto task.dispatch.reply.assetIds.
+     */
+    private pendingByTask;
+    constructor(opts: OutboxWatcherOptions);
+    /**
+     * Register a host-mode task envelope. Each call adds (or replaces) an
+     * entry keyed by `task.taskId` so concurrent dispatches do not clobber
+     * each other.
+     *
+     * Requires `task.outboxDir` to be set — the per-task workdir is the
+     * isolation boundary. For the legacy container/sandbox single-slot
+     * shape (no per-task dir), use `setActiveTask` instead.
+     */
+    addActiveTask(task: ActiveTask): void;
+    /**
+     * Remove a host-mode task entry by id. No-op if the id was not
+     * registered. Idempotent — dispatch.ts calls this in `finally{}` after
+     * `flushPending` so a failed dispatch still clears its slot.
+     */
+    removeActiveTask(taskId: string): void;
+    /**
+     * Legacy single-slot API.
+     *
+     *   - Non-null with `outboxDir` → forwards to `addActiveTask` (host
+     *     mode). The caller is still responsible for `removeActiveTask`
+     *     (or another `setActiveTask(null)`) at teardown.
+     *   - Non-null **without** `outboxDir` → store in the legacy container
+     *     slot. Uploads from `opts.outboxDir` are tagged with this task.
+     *   - `null` → clear the legacy container slot only. Does NOT touch
+     *     the host-mode `activeTasks` map; concurrent host-mode dispatches
+     *     keep their own slots until they call `removeActiveTask`
+     *     themselves.
+     *
+     * The null-clears-only-legacy semantic is the core fix for the
+     * Wave-9 concurrency race: previously a finishing orchestrator's
+     * `setActiveTask(null)` would clobber a still-running worker's
+     * tracking, dropping its uploads on the floor.
+     */
+    setActiveTask(task: ActiveTask | null): void;
+    /**
+     * Drain and return the assetIds collected for `taskId` since the last
+     * flush. Idempotent — calling twice with the same id returns `[]` the
+     * second time. dispatch.ts calls this once at reply-build time.
+     */
+    flushPending(taskId: string): string[];
+    start(): void;
+    stop(): void;
+    /**
+     * Force a synchronous scan — useful for tests + e2e harnesses that want to
+     * trigger upload after writing a file rather than wait for the next tick.
+     * Also used by dispatch.ts at reply-build time to drain any pending files
+     * before flushPending() is called.
+     */
+    scanNow(): Promise<void>;
+    private log;
+    /**
+     * Build the list of directories to scan this tick — one entry per
+     * concurrently-active task plus the legacy container slot (if any).
+     * Each entry carries its own `task` envelope so uploads can be tagged
+     * and accumulated per-task without sharing global mutable state.
+     *
+     * Dedup so a directory configured in both spots only scans once
+     * (legacy single-task case where opts.outboxDir == legacyTask.outboxDir
+     * is unlikely but cheap to handle).
+     */
+    private currentScanDirs;
+    private tick;
+    private scanDir;
+    private upload;
+}
+
+interface DispatchDeps {
+    registry: AdapterRegistry;
+    cloud: CloudClient;
+    uriResolver: UriResolver;
+    assetCache: AssetCache;
+    ws: WsClient;
+    /** Cap on total chars of joined context history. Default 8000. */
+    contextMaxChars?: number;
+    /** Resolves a long-running adapter's service handle (cached across calls). */
+    ensureService: (profile: AgentProfile, adapter: AdapterDef) => Promise<AdapterService>;
+    /** Aborts the in-flight adapter dispatch when cloud sends task.cancel. */
+    signal?: AbortSignal;
+    /** Hook for tests / observability. */
+    onProgress?: (taskId: string, p: TaskDispatchProgressPayload) => void;
+    /**
+     * Outbox uploader. When provided, dispatch creates a per-task outbox
+     * directory under `paths.runsDir`, points the watcher at it via
+     * setActiveTask, and drains its assetIds into reply.assetIds at flush
+     * time. Optional so tests can omit it.
+     */
+    outboxWatcher?: OutboxWatcher;
+    /** Daemon paths — used to derive the per-task outbox dir. */
+    paths?: ConfigPaths;
+}
+declare function handleDispatch(payload: TaskDispatchRequestPayload, requestId: string | undefined, deps: DispatchDeps): Promise<TaskDispatchReplyPayload>;
+/**
+ * Concatenate context entries + current prompt. Trims oldest entries first when
+ * total chars exceed `maxChars` (matches Track C's `trimContextWindow` behavior).
+ *
+ * `assetBlocks` (Wave-8 W1) is prepended above the conversation history. They
+ * are *not* counted against `maxChars` — assets are content the user
+ * explicitly attached, so dropping them silently when the chat history
+ * happens to be long would defeat the whole point of the attachment.
+ */
+declare function composePrompt(currentPrompt: string, context: TaskDispatchContextEntry[], maxChars: number, assetBlocks?: string[]): string;
+
+declare class ServicePool {
+    private readonly services;
+    /**
+     * Returns a service handle for the profile, lazily calling `adapter.ensureService`
+     * on first use or after a crash. Re-checks `healthy()` before returning a cached entry.
+     */
+    ensureService(profile: AgentProfile, adapter: AdapterDef): Promise<AdapterService>;
+    /** Drop a service handle (e.g. on profile delete or daemon shutdown). */
+    drop(profileId: string): Promise<void>;
+    /** Drop all handles, e.g. on graceful shutdown. */
+    shutdown(): Promise<void>;
+    size(): number;
+}
+
+interface LocalServerOptions {
+    port: number;
+    /** Snapshot getter — runner provides current state on demand. */
+    getState: () => LocalServerState;
+    /**
+     * Optional dispatch sink called when POST /v1/runs receives a task envelope
+     * from the sandbox controller. Phase 1 contract: the sink is fire-and-forget;
+     * daemon acks immediately with `{ runId, status: 'accepted' }`. Cloud-side
+     * task lifecycle (status → done/failed) is closed asynchronously by the
+     * daemon's WS upstream channel in S4 follow-up. The runner provides this
+     * sink; tests may pass a stub.
+     */
+    onDispatch?: (payload: DispatchPayload, runId: string) => void;
+    /**
+     * Install or update one hosted agent/profile in the daemon's local mirror.
+     * The runner persists it, reloads hostedAgents, and redeclares to cloud.
+     */
+    onInstallAgent?: (payload: InstallAgentPayload) => Promise<InstallAgentResult>;
+    /**
+     * Filesystem root for snapshot manifests. Default `/workspace`. POST
+     * /v1/snapshot walks this tree, computes per-file sha256 + size + mtime,
+     * and returns the manifest. Cloud-side persistence (POST
+     * /api/sandboxes/:id/snapshot/manifest) is a separate step in Phase 1.
+     */
+    snapshotRoot?: string;
+    /**
+     * Optional first-pass handler for `/local/memory/*` routes. Returns true
+     * if the request was handled (response written); false to let the normal
+     * route table fall through. Wired by the daemon runner from
+     * `attachMemoryRpc()` in `daemon/memory/rpc.ts` when memory is enabled.
+     * When set, /healthz reports `memoryReady: true`.
+     */
+    attachMemory?: (req: IncomingMessage, res: ServerResponse) => Promise<boolean>;
+    /**
+     * Optional handler for `POST /local/asset/write` — agent-gen adapter
+     * (daemon/asset/origin/agent-gen.ts). Synchronous: agent posts bytes,
+     * daemon uploads to cloud, returns prismer:// URI in one round-trip.
+     * Sink receives the parsed JSON body and returns a structured result.
+     */
+    onAssetWrite?: (body: unknown) => Promise<AssetWriteHandlerResult>;
+}
+interface AssetWriteHandlerResult {
+    status: 200 | 400 | 502;
+    body: unknown;
+}
+/**
+ * Dispatch envelope received from the sandbox controller proxy. The schema
+ * mirrors `DaemonDispatchSchema` in `infra/sandbox-controller/src/api/v1/
+ * containers.ts` — kept permissive so the controller can pass through any
+ * future fields without a daemon-side bump.
+ *
+ * Phase 1 escape hatch: when `shellCommand` is present, the daemon spawns
+ * it via `bash -c` with cwd=/workspace as a fire-and-forget subprocess.
+ * This bridges the gap until S4 wires the WS-mediated adapter dispatch +
+ * completion path. Production traffic does NOT set shellCommand — task
+ * service forwards it only when present in IMTask.metadata.shellCommand
+ * (a test escape hatch).
+ */
+interface DispatchPayload {
+    taskId: string;
+    adapter?: string;
+    prompt?: string;
+    env?: Record<string, string>;
+    shellCommand?: string;
+    [k: string]: unknown;
+}
+interface InstallAgentPayload {
+    workspaceId: string;
+    imUserId: string;
+    name: string;
+    adapterName: string;
+    capabilities: string[];
+    profile: {
+        id: string;
+        name: string;
+        adapterName: string;
+        config: Record<string, unknown>;
+        version: number;
+    };
+}
+interface InstallAgentResult {
+    ok: true;
+    daemonId: string;
+    installedAgent: {
+        imUserId: string;
+        name: string;
+        adapterName: string;
+        profileId: string;
+    };
+    hostedAgents: Array<{
+        imUserId: string;
+        name: string;
+        adapterName: string;
+    }>;
+}
+interface LocalServerState {
+    daemonId: string;
+    cloudBaseUrl?: string;
+    workspaceId?: string | null;
+    pid: number;
+    startedAt: number;
+    wsConnected: boolean;
+    hostedAgents: Array<{
+        imUserId: string;
+        name: string;
+        adapterName: string;
+    }>;
+    runningTaskIds: string[];
+    observability?: {
+        adapters?: Record<string, unknown>;
+        lastTaskError?: {
+            taskId: string;
+            message: string;
+            at: string;
+        };
+    };
+}
+declare class LocalServer {
+    private opts;
+    private server?;
+    constructor(opts: LocalServerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    private route;
+    private routeStandard;
+    /**
+     * POST /v1/agents/install — cloud/controller installs one hosted agent on
+     * this daemon. The payload is intentionally explicit and idempotent: the
+     * runner upserts local `agents` and `agent_profiles` rows, reloads the
+     * in-memory declaration set, then sends `agent.host.declare` immediately.
+     */
+    private handleInstallAgent;
+    /**
+     * POST /v1/snapshot — daemon-first FS manifest snapshot.
+     *
+     * Walks `snapshotRoot` (default `/workspace`), computes per-file
+     * sha256 + sizeBytes + mtime, returns `{ files: [...], rootPath }`.
+     * Skips dotfiles + the `_outbox/_uploaded` reserved subdir. Phase 1
+     * caller (cloud or controller) is responsible for POSTing the result
+     * to `/api/sandboxes/:id/snapshot/manifest`.
+     */
+    private handleSnapshot;
+    /**
+     * POST /local/asset/write — agent-gen adapter RPC.
+     *
+     * Body: { workspaceId, bytes (base64), filename, mime?, path?, description?, sourceAgentImUserId? }
+     * Response 200: { assetId, contentHash, prismerUri }
+     * 400 on validation failure; 502 on cloud upstream failure; 501 if no sink wired.
+     */
+    private handleAssetWrite;
+    /**
+     * POST /v1/runs — dispatch ack-only (Cloud 3 S3 Phase 1).
+     *
+     * The sandbox controller resolves the pod IP and POSTs a task envelope here.
+     * Phase 1 just acknowledges receipt and forwards the payload to onDispatch
+     * (the runner). Actual task execution + cloud-side completion are wired in
+     * S4 (daemon WS upstream emits task.dispatch.reply once the adapter finishes).
+     *
+     * Response on success: 202 + `{ runId, status: 'accepted' }`.
+     * Bad JSON / missing taskId: 400. Internal error: 500.
+     */
+    private handleDispatch;
+}
+
+interface RunnerOptions {
+    /** Override config path; defaults to ~/.prismer. */
+    paths?: ConfigPaths;
+    /** Skip starting the local 127.0.0.1 server (useful in tests). */
+    startLocalServer?: boolean;
+    /** Local server port; defaults to 3210. */
+    localPort?: number;
+    /** Override daemonVersion reported in agent.host.declare. */
+    daemonVersion?: string;
+    /** Pre-loaded config (skip filesystem read). */
+    configOverride?: Config;
+    /** Override built-in adapter list (tests). */
+    adaptersOverride?: AdapterDef[];
+}
+declare class Runner extends EventEmitter {
+    private opts;
+    private config;
+    private paths;
+    private db;
+    private cloud;
+    private ws;
+    private syncWorker;
+    private syncQueue;
+    private assetCache;
+    private uriResolver;
+    private registry;
+    private servicePool;
+    private shellConfig;
+    private localServer?;
+    private outboxWatcher?;
+    private memoryWiring?;
+    private state;
+    private startedAt;
+    private workspaceId;
+    private wsConnected;
+    private readonly hostedAgents;
+    private readonly runningTasks;
+    private lastTaskError?;
+    private heartbeatTimer?;
+    private taskReaperTimer?;
+    constructor(opts?: RunnerOptions);
+    start(): Promise<void>;
+    stop(): Promise<void>;
+    isRunning(): boolean;
+    /**
+     * Phase 1 escape hatch — see `DispatchPayload.shellCommand`. Spawns
+     * `bash -c <cmd>` with cwd=/workspace, mirrors output to pod logs.
+     * Fire-and-forget; nothing here writes back to cloud.
+     */
+    private runShellCommand;
+    snapshotState(): LocalServerState;
+    /**
+     * Re-read the local `agents` table (populated by `prismer agent register`)
+     * and re-populate `hostedAgents` map. Profiles per agent come from local
+     * `agent_profiles` table (filled by host.acked sync).
+     */
+    loadAgentsFromDb(): void;
+    /**
+     * Register an in-process AgentProfile snapshot (called by agent CLI / sync layer).
+     * Used to populate the `agents` list in agent.host.declare.
+     */
+    setHostedAgent(agent: {
+        imUserId: string;
+        name: string;
+        adapterName: string;
+        capabilities: string[];
+        profiles: Array<{
+            id: string;
+            version: number;
+        }>;
+    }): void;
+    private installHostedAgent;
+    private installStaticHostedAgentFromEnv;
+    private wireWsHandlers;
+    private sendDeclare;
+    private handleIncoming;
+    private onHostAcked;
+    private onTaskDispatch;
+    private onTaskCancel;
+    private onAgentChanged;
+    private onAgentProfileChanged;
+    private syncProfileFromCloud;
+    private resolveOwnedAgent;
+    private onWorkspaceChanged;
+    private onWorkspaceFileChanged;
+    private snapshotAdapterObservability;
+    /**
+     * SyncWorker FlushFn — pushes local writes to cloud.
+     *
+     * Maps:
+     *   workspace      → PATCH /api/im/workspaces/:id
+     *   agent_profile  → PATCH /api/im/agent_profiles/:id
+     *   agent          → PATCH /api/im/agents/:imUserId
+     * On 'create' we POST instead. On 'delete' we DELETE.
+     */
+    /**
+     * SyncWorker FlushFn — pushes one local sync row to cloud via CloudClient.
+     *
+     * resource_type × operation → endpoint:
+     *   workspace.create      → POST   /api/im/workspaces
+     *   workspace.update      → PATCH  /api/im/workspaces/:id
+     *   workspace.delete      → DELETE /api/im/workspaces/:id
+     *   agent.create          → POST   /api/im/register   (the only public path
+     *                                                       that creates an
+     *                                                       IMUser of role='agent')
+     *   agent.update          → PATCH  /api/im/agents/:id
+     *   agent.delete          → DELETE /api/im/agents/:id
+     *   agent_profile.create  → POST   /api/im/agent_profiles
+     *   agent_profile.update  → PATCH  /api/im/agent_profiles/:id
+     *   agent_profile.delete  → DELETE /api/im/agent_profiles/:id
+     *
+     * Error classification per docs/refactor/13-error-handling.md §2.1 / §2.7:
+     *   2xx           → ok:true   (SyncWorker drops the row)
+     *   408 / 429     → retryable (SyncWorker re-queues with exponential backoff)
+     *   5xx / net err → retryable
+     *   4xx (other)   → permanent (SyncWorker marks failed; 409 is conflict)
+     */
+    private flushSyncRow;
+}
+
+interface PairOptions {
+    cloudBaseUrl: string;
+    /** Human-readable label visible to the approver in mobile UI. */
+    deviceName?: string;
+    /** Override config save path (tests). */
+    paths?: ConfigPaths;
+    /** Number of poll attempts (5 s each). Default 60 → 5 min. */
+    maxPollAttempts?: number;
+    /** Pluggable fetch (tests). */
+    fetchImpl?: typeof fetch;
+    /** Allow overwriting existing config. Default false. */
+    force?: boolean;
+    /** Hook for test capture of the QR URL. */
+    onQrReady?: (qrUrl: string) => void;
+    /**
+     * LAN-dev bypass: skip QR + mobile approval and auto-approve the offer
+     * as the named human IMUser. Requires `LOCAL_ONLY=1` in this process AND
+     * cloud-side `LOCAL_ONLY=1 && NODE_ENV !== 'production'`. Without those
+     * env conditions the cloud returns 403 and we surface the error.
+     */
+    asUserEmail?: string;
+    /** Override LOCAL_ONLY env read (tests). */
+    isLocalOnly?: () => boolean;
+    /** Override poll wait (tests). Default 5_000ms. */
+    pollIntervalMs?: number;
+}
+interface PairResult {
+    config: Config;
+    paths: ConfigPaths;
+}
+declare function pair(opts: PairOptions): Promise<PairResult>;
+
+declare const CCConfigSchema: z.ZodObject<{
+    cwd: z.ZodString;
+    model: z.ZodDefault<z.ZodString>;
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    envVars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    mcpServers: z.ZodOptional<z.ZodArray<z.ZodObject<{
+        name: z.ZodString;
+        command: z.ZodString;
+        args: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+        env: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    }, "strip", z.ZodTypeAny, {
+        name: string;
+        command: string;
+        env?: Record<string, string> | undefined;
+        args?: string[] | undefined;
+    }, {
+        name: string;
+        command: string;
+        env?: Record<string, string> | undefined;
+        args?: string[] | undefined;
+    }>, "many">>;
+    allowedTools: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    maxTurns: z.ZodDefault<z.ZodNumber>;
+    baseURL: z.ZodOptional<z.ZodString>;
+    apiKeyRef: z.ZodOptional<z.ZodString>;
+    route: z.ZodDefault<z.ZodEnum<["default", "prismer", "omniroute"]>>;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    cwd: string;
+    maxTurns: number;
+    route: "default" | "prismer" | "omniroute";
+    systemPrompt?: string | undefined;
+    allowedTools?: string[] | undefined;
+    envVars?: Record<string, string> | undefined;
+    mcpServers?: {
+        name: string;
+        command: string;
+        env?: Record<string, string> | undefined;
+        args?: string[] | undefined;
+    }[] | undefined;
+    baseURL?: string | undefined;
+    apiKeyRef?: string | undefined;
+}, {
+    cwd: string;
+    model?: string | undefined;
+    systemPrompt?: string | undefined;
+    allowedTools?: string[] | undefined;
+    envVars?: Record<string, string> | undefined;
+    mcpServers?: {
+        name: string;
+        command: string;
+        env?: Record<string, string> | undefined;
+        args?: string[] | undefined;
+    }[] | undefined;
+    maxTurns?: number | undefined;
+    baseURL?: string | undefined;
+    apiKeyRef?: string | undefined;
+    route?: "default" | "prismer" | "omniroute" | undefined;
+}>;
+type ClaudeCodeConfig = z.infer<typeof CCConfigSchema>;
+declare const claudeCodeAdapter: AdapterDef;
+
+declare const CodexConfigSchema: z.ZodObject<{
+    /** Working directory for the codex subprocess. */
+    cwd: z.ZodString;
+    /**
+     * Model identifier passed to --model (e.g. 'codex-mini-latest', 'o4-mini').
+     * Default matches the Codex CLI built-in default as of 2026-05.
+     */
+    model: z.ZodDefault<z.ZodString>;
+    /**
+     * Sandbox level for the codex subprocess.
+     *   read-only         — analysis only; code-gen tasks will stall
+     *   workspace-write   — write inside cwd, read-only outside (recommended)
+     *   danger-full-access — no restrictions; safe only inside isolated containers
+     */
+    sandbox: z.ZodDefault<z.ZodEnum<["read-only", "workspace-write", "danger-full-access"]>>;
+    /** Optional system prompt prepended to the user prompt as a preamble (see U4). */
+    systemPrompt: z.ZodOptional<z.ZodString>;
+    /** Extra env vars merged into the codex subprocess environment. */
+    envVars: z.ZodOptional<z.ZodRecord<z.ZodString, z.ZodString>>;
+    /**
+     * Name of the env var holding the OpenAI API key. Defaults to
+     * 'OPENAI_API_KEY' (Codex CLI default). Override if using a workspace-
+     * scoped key under a different name.
+     */
+    apiKeyEnv: z.ZodDefault<z.ZodString>;
+}, "strip", z.ZodTypeAny, {
+    model: string;
+    sandbox: "read-only" | "workspace-write" | "danger-full-access";
+    cwd: string;
+    apiKeyEnv: string;
+    systemPrompt?: string | undefined;
+    envVars?: Record<string, string> | undefined;
+}, {
+    cwd: string;
+    model?: string | undefined;
+    systemPrompt?: string | undefined;
+    sandbox?: "read-only" | "workspace-write" | "danger-full-access" | undefined;
+    envVars?: Record<string, string> | undefined;
+    apiKeyEnv?: string | undefined;
+}>;
+type CodexConfig = z.infer<typeof CodexConfigSchema>;
+/**
+ * Parse `codex exec --json` stdout. The CLI emits newline-delimited JSON
+ * lines on stdout; we look for the final-message line and extract its
+ * content. Tolerant: any parse failure falls back to raw stdout.
+ */
+declare function parseCodexOutput(stdout: string): string;
+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 AgentHostDeclarePayload, type AgentProfile, type AgentProfileChangedPayload, type AgentStatusChangedPayload, AssetCache, type AssetCacheOptions, 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 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 ValidationResult, WS_CLOSE, type WorkspaceChangedPayload, type WorkspaceFileBinding, type WorkspaceFileChangedPayload, WorkspaceMirror, type WorkspaceMirrorOptions, WsClient, type WsClientOptions, buildProgram, claudeCodeAdapter, codexAdapter, composePrompt, configExists, currentSchemaVersion, deriveWsUrl, envelope, getRoleTemplate, handleDispatch, hermesAdapter, isDaemonId, listRoleTemplates, loadConfig, newDaemonId, nextBackoffMs, openLocalDb, pair, parseCodexOutput, parseUris, resolvePaths, runCli, runMigrations, saveConfig };