@femtomc/mu-server 26.2.73 → 26.2.74

package/README.md

@@ -1,6 +1,8 @@
 # @femtomc/mu-server
 
-HTTP API server for mu. Powers `mu serve`, the web UI, and programmatic status/control endpoints.
+HTTP API server for mu control-plane infrastructure. Powers `mu serve`, messaging frontend transport routes, and control-plane/session coordination endpoints.
+
+> Scope note: server-routed business query/mutation gateway endpoints have been removed. Business reads/writes are CLI-first, while long-lived runtime coordination (runs/activities/heartbeats/cron) stays server-owned.
 
 ## Installation
 
@@ -39,8 +41,6 @@ Bun.serve(server);
   ```json
   {
     "repo_root": "/path/to/repo",
-    "open_count": 10,
-    "ready_count": 3,
     "control_plane": {
       "active": true,
       "adapters": ["slack"],
@@ -99,79 +99,71 @@ Bun.serve(server);
   ```
   - Response includes generation metadata and, when telegram generation handling runs, `telegram_generation` lifecycle detail.
 - `POST /api/control-plane/rollback` - Explicit rollback trigger (same pipeline, reason=`rollback`)
+- `GET /api/control-plane/channels` - Capability/discovery snapshot for mounted adapter channels (route, verification contract, configured/active/frontend flags)
 
-### Issues
+### Session Flash Inbox (cross-session context handoff)
 
-- `GET /api/issues` - List issues
-  - Query params: `?status=open&tag=bug&contains=crash&limit=50`
-  - `limit` defaults to `200` and is clamped to `<= 200`.
-- `GET /api/issues/:id` - Get issue by ID
-- `POST /api/issues` - Create new issue
-  ```json
-  {
-    "title": "Issue title",
-    "body": "Issue description",
-    "tags": ["bug", "priority", "role:worker"],
-    "priority": 2
-  }
-  ```
-- `PATCH /api/issues/:id` - Update issue
-- `POST /api/issues/:id/close` - Close issue
+- `POST /api/session-flash` - Create a session-targeted flash message
   ```json
   {
-    "outcome": "success"
+    "session_id": "operator-abc123",
+    "session_kind": "cp_operator",
+    "body": "Use context id ctx-123 for this question",
+    "context_ids": ["ctx-123"],
+    "source": "neovim"
   }
   ```
-- `POST /api/issues/:id/claim` - Claim issue (changes status to in_progress)
-- `GET /api/issues/ready` - Get ready issues
-  - Query params: `?root=issue-id&contains=worker&limit=20`
-  - `limit` defaults to `200` and is clamped to `<= 200`.
-
-### Forum
-
-- `GET /api/forum/topics` - List forum topics
-  - Query params: `?prefix=issue:&limit=20`
-  - `limit` defaults to `100` and is clamped to `<= 200`.
-- `GET /api/forum/read` - Read messages from topic
-  - Query params: `?topic=issue:123&limit=50`
-  - `limit` defaults to `50` and is clamped to `<= 200`.
-- `POST /api/forum/post` - Post message to topic
+- `GET /api/session-flash` - List flash messages
+  - Query params: `session_id`, `session_kind`, `status=pending|delivered|all`, `contains`, `limit`
+- `GET /api/session-flash/:flash_id` - Get one flash message by id
+- `POST /api/session-flash/ack` - Mark a flash message delivered/acknowledged
+
+### Session Turn Injection (canonical transcript turn)
+
+- `POST /api/session-turn` - Run a real turn in an existing target session and return reply + new context cursor
   ```json
   {
-    "topic": "issue:123",
-    "body": "Message content",
-    "author": "username"
+    "session_id": "operator-abc123",
+    "session_kind": "cp_operator",
+    "body": "Summarize the last plan and propose next steps.",
+    "source": "neovim"
   }
   ```
-
-### Context Retrieval (Cross-store historical memory)
-
-- `GET /api/context/search` - Search across `.mu` history stores
-  - Query params: `query`/`q`, `limit`, `source`/`sources`, `issue_id`, `run_id`, `session_id`,
-    `conversation_key`, `channel`, `channel_tenant_id`, `channel_conversation_id`, `actor_binding_id`,
-    `topic`, `author`, `role`, `since`, `until`.
-- `GET /api/context/timeline` - Ordered timeline view anchored to a scope
-  - Requires at least one anchor filter: `conversation_key`, `issue_id`, `run_id`, `session_id`, `topic`, or `channel`.
-  - Supports `order=asc|desc` and same filters as search.
-- `GET /api/context/stats` - Source-level cardinality/text-size stats for indexed context items.
-
-Context source kinds:
-
-- `issues`, `forum`, `events`
-- `cp_commands`, `cp_outbox`, `cp_adapter_audit`, `cp_operator_turns`, `cp_telegram_ingress`
-- `operator_sessions`, `cp_operator_sessions`
+  - Optional overrides: `session_file`, `session_dir`, `provider`, `model`, `thinking`, `extension_profile`
+  - Response includes: `turn.reply`, `turn.context_entry_id`, `turn.session_file`
+
+### Control-plane Coordination Endpoints
+
+- Runs:
+  - `GET /api/runs`
+  - `POST /api/runs/start`
+  - `POST /api/runs/resume`
+  - `POST /api/runs/interrupt`
+  - `GET /api/runs/:id`
+  - `GET /api/runs/:id/trace`
+- Scheduling + orchestration:
+  - `GET|POST|PATCH|DELETE /api/heartbeats...`
+  - `GET|POST|PATCH|DELETE /api/cron...`
+  - `GET|POST /api/activities...`
+  - Heartbeat/cron ticks dispatch operator wake turns and broadcast the resulting operator reply.
+- Identity bindings:
+  - `GET /api/identities`
+  - `POST /api/identities/link`
+  - `POST /api/identities/unlink`
+- Observability:
+  - `GET /api/events`
+  - `GET /api/events/tail`
 
 ## Running the Server
 
-### With Web UI (Recommended)
+### With terminal operator session (recommended)
 
-The easiest way to run the server with the bundled web interface (and default terminal operator session):
+The easiest way to run the server with the default terminal operator session:
 
 ```bash
 # From any mu repository
-mu serve              # API + web UI + terminal operator session
-mu serve --no-open    # Skip browser auto-open (headless/SSH)
-mu serve --port 8080  # Custom shared API/web UI port
+mu serve              # API + terminal operator session
+mu serve --port 8080  # Custom API/operator port
 ```
 
 Type `/exit` (or press Ctrl+C) to stop both the operator session and server.
@@ -215,13 +207,9 @@ bun run start
 ## Architecture
 
 The server uses:
-- Filesystem-backed JSONL stores (FsJsonlStore)
-- IssueStore and ForumStore from mu packages
+- Filesystem-backed JSONL event storage (FsJsonlStore)
 - Bun's built-in HTTP server
-- Simple REST-style JSON API
+- Control-plane adapter/webhook transport + session coordination routes
 - Generation-supervised control-plane hot reload lifecycle (see `docs/adr-0001-control-plane-hot-reload.md`)
 
-All data is persisted to `.mu/` directory:
-- `.mu/issues.jsonl` - Issue data
-- `.mu/forum.jsonl` - Forum messages
-- `.mu/events.jsonl` - Event log
+Control-plane/coordination data is persisted to `.mu/` (for example `.mu/events.jsonl` and `.mu/control-plane/*`).

package/dist/api/control_plane.js

@@ -1,3 +1,35 @@
+import { CONTROL_PLANE_CHANNEL_ADAPTER_SPECS } from "@femtomc/mu-control-plane";
+function asRecord(value) {
+    if (!value || typeof value !== "object" || Array.isArray(value)) {
+        return null;
+    }
+    return value;
+}
+function activeChannelsFromStatus(status) {
+    const record = asRecord(status);
+    const adapters = Array.isArray(record?.adapters) ? record.adapters : [];
+    const set = new Set();
+    for (const adapter of adapters) {
+        if (typeof adapter === "string" && adapter.trim().length > 0) {
+            set.add(adapter.trim());
+        }
+    }
+    return set;
+}
+function configuredForChannel(config, channel) {
+    switch (channel) {
+        case "slack":
+            return typeof config.control_plane.adapters.slack.signing_secret === "string";
+        case "discord":
+            return typeof config.control_plane.adapters.discord.signing_secret === "string";
+        case "telegram":
+            return typeof config.control_plane.adapters.telegram.webhook_secret === "string";
+        case "neovim":
+            return typeof config.control_plane.adapters.neovim.shared_secret === "string";
+        default:
+            return false;
+    }
+}
 export async function controlPlaneRoutes(request, url, deps, headers) {
     const path = url.pathname;
     if (path === "/api/control-plane/reload") {
@@ -24,5 +56,29 @@ export async function controlPlaneRoutes(request, url, deps, headers) {
         const result = await deps.reloadControlPlane("rollback");
         return Response.json(result, { status: result.ok ? 200 : 500, headers });
     }
+    if (path === "/api/control-plane/channels") {
+        if (request.method !== "GET") {
+            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
+        }
+        const [config, status] = await Promise.all([deps.loadConfigFromDisk(), Promise.resolve(deps.getControlPlaneStatus())]);
+        const activeChannels = activeChannelsFromStatus(status);
+        const channels = CONTROL_PLANE_CHANNEL_ADAPTER_SPECS.map((spec) => ({
+            channel: spec.channel,
+            route: spec.route,
+            ingress_payload: spec.ingress_payload,
+            verification: spec.verification,
+            ack_format: spec.ack_format,
+            delivery_semantics: spec.delivery_semantics,
+            deferred_delivery: spec.deferred_delivery,
+            configured: configuredForChannel(config, spec.channel),
+            active: activeChannels.has(spec.channel),
+            frontend: spec.channel === "neovim",
+        }));
+        return Response.json({
+            ok: true,
+            generated_at_ms: Date.now(),
+            channels,
+        }, { headers });
+    }
     return Response.json({ error: "Not Found" }, { status: 404, headers });
 }

package/dist/api/cron.js

@@ -1,5 +1,4 @@
-import { cronScheduleInputFromBody, hasCronScheduleInput, parseCronTarget, } from "../cron_request.js";
-import { normalizeWakeMode } from "../server_types.js";
+import { cronScheduleInputFromBody, hasCronScheduleInput } from "../cron_request.js";
 export async function cronRoutes(request, url, deps, headers) {
     const path = url.pathname;
     if (path === "/api/cron/status") {
@@ -15,15 +14,13 @@ export async function cronRoutes(request, url, deps, headers) {
         }
         const enabledRaw = url.searchParams.get("enabled")?.trim().toLowerCase();
         const enabled = enabledRaw === "true" ? true : enabledRaw === "false" ? false : undefined;
-        const targetKindRaw = url.searchParams.get("target_kind")?.trim().toLowerCase();
-        const targetKind = targetKindRaw === "run" || targetKindRaw === "activity" ? targetKindRaw : undefined;
         const scheduleKindRaw = url.searchParams.get("schedule_kind")?.trim().toLowerCase();
         const scheduleKind = scheduleKindRaw === "at" || scheduleKindRaw === "every" || scheduleKindRaw === "cron"
             ? scheduleKindRaw
             : undefined;
         const limitRaw = url.searchParams.get("limit");
         const limit = limitRaw && /^\d+$/.test(limitRaw) ? Math.max(1, Math.min(500, Number.parseInt(limitRaw, 10))) : undefined;
-        const programs = await deps.cronPrograms.list({ enabled, targetKind, scheduleKind, limit });
+        const programs = await deps.cronPrograms.list({ enabled, scheduleKind, limit });
         return Response.json({ count: programs.length, programs }, { headers });
     }
     if (path === "/api/cron/create") {
@@ -41,24 +38,17 @@ export async function cronRoutes(request, url, deps, headers) {
         if (!title) {
             return Response.json({ error: "title is required" }, { status: 400, headers });
         }
-        const parsedTarget = parseCronTarget(body);
-        if (!parsedTarget.target) {
-            return Response.json({ error: parsedTarget.error ?? "invalid target" }, { status: 400, headers });
-        }
         if (!hasCronScheduleInput(body)) {
             return Response.json({ error: "schedule is required" }, { status: 400, headers });
         }
         const schedule = cronScheduleInputFromBody(body);
         const reason = typeof body.reason === "string" ? body.reason.trim() : undefined;
-        const wakeMode = normalizeWakeMode(body.wake_mode);
         const enabled = typeof body.enabled === "boolean" ? body.enabled : undefined;
         try {
             const program = await deps.cronPrograms.create({
                 title,
-                target: parsedTarget.target,
                 schedule,
                 reason,
-                wakeMode,
                 enabled,
                 metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
                     ? body.metadata
@@ -85,24 +75,13 @@ export async function cronRoutes(request, url, deps, headers) {
         if (!programId) {
             return Response.json({ error: "program_id is required" }, { status: 400, headers });
         }
-        let target;
-        if (typeof body.target_kind === "string") {
-            const parsedTarget = parseCronTarget(body);
-            if (!parsedTarget.target) {
-                return Response.json({ error: parsedTarget.error ?? "invalid target" }, { status: 400, headers });
-            }
-            target = parsedTarget.target;
-        }
         const schedule = hasCronScheduleInput(body) ? cronScheduleInputFromBody(body) : undefined;
-        const wakeMode = Object.hasOwn(body, "wake_mode") ? normalizeWakeMode(body.wake_mode) : undefined;
         try {
             const result = await deps.cronPrograms.update({
                 programId,
                 title: typeof body.title === "string" ? body.title : undefined,
                 reason: typeof body.reason === "string" ? body.reason : undefined,
-                wakeMode,
                 enabled: typeof body.enabled === "boolean" ? body.enabled : undefined,
-                target,
                 schedule,
                 metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
                     ? body.metadata

package/dist/api/heartbeats.js

@@ -1,4 +1,3 @@
-import { normalizeWakeMode } from "../server_types.js";
 export async function heartbeatRoutes(request, url, deps, headers) {
     const path = url.pathname;
     if (path === "/api/heartbeats") {
@@ -7,11 +6,9 @@ export async function heartbeatRoutes(request, url, deps, headers) {
         }
         const enabledRaw = url.searchParams.get("enabled")?.trim().toLowerCase();
         const enabled = enabledRaw === "true" ? true : enabledRaw === "false" ? false : undefined;
-        const targetKindRaw = url.searchParams.get("target_kind")?.trim().toLowerCase();
-        const targetKind = targetKindRaw === "run" || targetKindRaw === "activity" ? targetKindRaw : undefined;
         const limitRaw = url.searchParams.get("limit");
         const limit = limitRaw && /^\d+$/.test(limitRaw) ? Math.max(1, Math.min(500, Number.parseInt(limitRaw, 10))) : undefined;
-        const programs = await deps.heartbeatPrograms.list({ enabled, targetKind, limit });
+        const programs = await deps.heartbeatPrograms.list({ enabled, limit });
         return Response.json({ count: programs.length, programs }, { headers });
     }
     if (path === "/api/heartbeats/create") {
@@ -29,46 +26,16 @@ export async function heartbeatRoutes(request, url, deps, headers) {
         if (!title) {
             return Response.json({ error: "title is required" }, { status: 400, headers });
         }
-        const targetKind = typeof body.target_kind === "string" ? body.target_kind.trim().toLowerCase() : "";
-        let target = null;
-        if (targetKind === "run") {
-            const jobId = typeof body.run_job_id === "string" ? body.run_job_id.trim() : "";
-            const rootIssueId = typeof body.run_root_issue_id === "string" ? body.run_root_issue_id.trim() : "";
-            if (!jobId && !rootIssueId) {
-                return Response.json({ error: "run target requires run_job_id or run_root_issue_id" }, { status: 400, headers });
-            }
-            target = {
-                kind: "run",
-                job_id: jobId || null,
-                root_issue_id: rootIssueId || null,
-            };
-        }
-        else if (targetKind === "activity") {
-            const activityId = typeof body.activity_id === "string" ? body.activity_id.trim() : "";
-            if (!activityId) {
-                return Response.json({ error: "activity target requires activity_id" }, { status: 400, headers });
-            }
-            target = {
-                kind: "activity",
-                activity_id: activityId,
-            };
-        }
-        else {
-            return Response.json({ error: "target_kind must be run or activity" }, { status: 400, headers });
-        }
         const everyMs = typeof body.every_ms === "number" && Number.isFinite(body.every_ms)
             ? Math.max(0, Math.trunc(body.every_ms))
             : undefined;
         const reason = typeof body.reason === "string" ? body.reason.trim() : undefined;
-        const wakeMode = normalizeWakeMode(body.wake_mode);
         const enabled = typeof body.enabled === "boolean" ? body.enabled : undefined;
         try {
             const program = await deps.heartbeatPrograms.create({
                 title,
-                target,
                 everyMs,
                 reason,
-                wakeMode,
                 enabled,
                 metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
                     ? body.metadata
@@ -95,46 +62,14 @@ export async function heartbeatRoutes(request, url, deps, headers) {
         if (!programId) {
             return Response.json({ error: "program_id is required" }, { status: 400, headers });
         }
-        let target;
-        if (typeof body.target_kind === "string") {
-            const targetKind = body.target_kind.trim().toLowerCase();
-            if (targetKind === "run") {
-                const jobId = typeof body.run_job_id === "string" ? body.run_job_id.trim() : "";
-                const rootIssueId = typeof body.run_root_issue_id === "string" ? body.run_root_issue_id.trim() : "";
-                if (!jobId && !rootIssueId) {
-                    return Response.json({ error: "run target requires run_job_id or run_root_issue_id" }, { status: 400, headers });
-                }
-                target = {
-                    kind: "run",
-                    job_id: jobId || null,
-                    root_issue_id: rootIssueId || null,
-                };
-            }
-            else if (targetKind === "activity") {
-                const activityId = typeof body.activity_id === "string" ? body.activity_id.trim() : "";
-                if (!activityId) {
-                    return Response.json({ error: "activity target requires activity_id" }, { status: 400, headers });
-                }
-                target = {
-                    kind: "activity",
-                    activity_id: activityId,
-                };
-            }
-            else {
-                return Response.json({ error: "target_kind must be run or activity" }, { status: 400, headers });
-            }
-        }
-        const wakeMode = Object.hasOwn(body, "wake_mode") ? normalizeWakeMode(body.wake_mode) : undefined;
         try {
             const result = await deps.heartbeatPrograms.update({
                 programId,
                 title: typeof body.title === "string" ? body.title : undefined,
-                target,
                 everyMs: typeof body.every_ms === "number" && Number.isFinite(body.every_ms)
                     ? Math.max(0, Math.trunc(body.every_ms))
                     : undefined,
                 reason: typeof body.reason === "string" ? body.reason : undefined,
-                wakeMode,
                 enabled: typeof body.enabled === "boolean" ? body.enabled : undefined,
                 metadata: body.metadata && typeof body.metadata === "object" && !Array.isArray(body.metadata)
                     ? body.metadata

package/dist/api/identities.js

@@ -24,8 +24,9 @@ export async function identityRoutes(request, url, deps, headers) {
             return Response.json({ error: "invalid json body" }, { status: 400, headers });
         }
         const channel = typeof body.channel === "string" ? body.channel.trim() : "";
-        if (!channel || (channel !== "slack" && channel !== "discord" && channel !== "telegram")) {
-            return Response.json({ error: "channel is required (slack, discord, telegram)" }, { status: 400, headers });
+        if (!channel ||
+            (channel !== "slack" && channel !== "discord" && channel !== "telegram" && channel !== "neovim")) {
+            return Response.json({ error: "channel is required (slack, discord, telegram, neovim)" }, { status: 400, headers });
         }
         const actorId = typeof body.actor_id === "string" ? body.actor_id.trim() : "";
         if (!actorId) {

package/dist/api/runs.js

@@ -1,4 +1,3 @@
-import { normalizeWakeMode } from "../server_types.js";
 export async function runRoutes(request, url, deps, headers) {
     const path = url.pathname;
     if (path === "/api/runs") {
@@ -34,16 +33,6 @@ export async function runRoutes(request, url, deps, headers) {
             if (!run) {
                 return Response.json({ error: "run supervisor unavailable" }, { status: 503, headers });
             }
-            await deps.registerAutoRunHeartbeatProgram(run).catch(async (error) => {
-                await deps.context.eventLog.emit("run.auto_heartbeat.lifecycle", {
-                    source: "mu-server.runs",
-                    payload: {
-                        action: "register_failed",
-                        run_job_id: run.job_id,
-                        error: deps.describeError(error),
-                    },
-                });
-            });
             return Response.json({ ok: true, run }, { status: 201, headers });
         }
         catch (err) {
@@ -73,16 +62,6 @@ export async function runRoutes(request, url, deps, headers) {
             if (!run) {
                 return Response.json({ error: "run supervisor unavailable" }, { status: 503, headers });
             }
-            await deps.registerAutoRunHeartbeatProgram(run).catch(async (error) => {
-                await deps.context.eventLog.emit("run.auto_heartbeat.lifecycle", {
-                    source: "mu-server.runs",
-                    payload: {
-                        action: "register_failed",
-                        run_job_id: run.job_id,
-                        error: deps.describeError(error),
-                    },
-                });
-            });
             return Response.json({ ok: true, run }, { status: 201, headers });
         }
         catch (err) {
@@ -109,61 +88,8 @@ export async function runRoutes(request, url, deps, headers) {
         if (!result) {
             return Response.json({ error: "run supervisor unavailable" }, { status: 503, headers });
         }
-        if (!result.ok && result.reason === "not_running" && result.run) {
-            await deps.disableAutoRunHeartbeatProgram({
-                jobId: result.run.job_id,
-                status: result.run.status,
-                reason: "interrupt_not_running",
-            }).catch(() => {
-                // best effort cleanup only
-            });
-        }
         return Response.json(result, { status: result.ok ? 200 : 404, headers });
     }
-    if (path === "/api/runs/heartbeat") {
-        if (request.method !== "POST") {
-            return Response.json({ error: "Method Not Allowed" }, { status: 405, headers });
-        }
-        let body;
-        try {
-            body = (await request.json());
-        }
-        catch {
-            return Response.json({ error: "invalid json body" }, { status: 400, headers });
-        }
-        const rootIssueId = typeof body.root_issue_id === "string" ? body.root_issue_id.trim() : null;
-        const jobId = typeof body.job_id === "string" ? body.job_id.trim() : null;
-        const reason = typeof body.reason === "string" ? body.reason.trim() : null;
-        const wakeMode = normalizeWakeMode(body.wake_mode);
-        const result = await deps.controlPlaneProxy.heartbeatRun?.({
-            rootIssueId,
-            jobId,
-            reason,
-            wakeMode,
-        });
-        if (!result) {
-            return Response.json({ error: "run supervisor unavailable" }, { status: 503, headers });
-        }
-        if (!result.ok && result.reason === "not_running" && result.run) {
-            await deps.disableAutoRunHeartbeatProgram({
-                jobId: result.run.job_id,
-                status: result.run.status,
-                reason: "run_not_running",
-            }).catch(() => {
-                // best effort cleanup only
-            });
-        }
-        if (result.ok) {
-            return Response.json(result, { status: 200, headers });
-        }
-        if (result.reason === "missing_target") {
-            return Response.json(result, { status: 400, headers });
-        }
-        if (result.reason === "not_running") {
-            return Response.json(result, { status: 409, headers });
-        }
-        return Response.json(result, { status: 404, headers });
-    }
     if (path.startsWith("/api/runs/")) {
         const rest = path.slice("/api/runs/".length);
         const [rawId, maybeSub] = rest.split("/");
@@ -192,15 +118,6 @@ export async function runRoutes(request, url, deps, headers) {
         if (!run) {
             return Response.json({ error: "run not found" }, { status: 404, headers });
         }
-        if (run.status !== "running") {
-            await deps.disableAutoRunHeartbeatProgram({
-                jobId: run.job_id,
-                status: run.status,
-                reason: "run_terminal_snapshot",
-            }).catch(() => {
-                // best effort cleanup only
-            });
-        }
         return Response.json(run, { headers });
     }
     return Response.json({ error: "Not Found" }, { status: 404, headers });

package/dist/api/session_flash.d.ts

@@ -0,0 +1,60 @@
+import type { ServerRoutingDependencies } from "../server_routing.js";
+export type SessionFlashStatus = "pending" | "delivered";
+export type SessionFlashRecord = {
+    flash_id: string;
+    created_at_ms: number;
+    session_id: string;
+    session_kind: string | null;
+    body: string;
+    context_ids: string[];
+    source: string | null;
+    metadata: Record<string, unknown>;
+    from: {
+        channel: string | null;
+        channel_tenant_id: string | null;
+        channel_conversation_id: string | null;
+        actor_binding_id: string | null;
+    };
+    status: SessionFlashStatus;
+    delivered_at_ms: number | null;
+    delivered_by: string | null;
+    delivery_note: string | null;
+};
+export declare function getSessionFlashPath(repoRoot: string): string;
+export declare function listSessionFlashRecords(opts: {
+    repoRoot: string;
+    sessionId?: string | null;
+    sessionKind?: string | null;
+    status?: SessionFlashStatus | "all";
+    contains?: string | null;
+    limit?: number;
+}): Promise<SessionFlashRecord[]>;
+export declare function getSessionFlashRecord(opts: {
+    repoRoot: string;
+    flashId: string;
+}): Promise<SessionFlashRecord | null>;
+export declare function createSessionFlashRecord(opts: {
+    repoRoot: string;
+    sessionId: string;
+    body: string;
+    sessionKind?: string | null;
+    contextIds?: string[];
+    source?: string | null;
+    metadata?: Record<string, unknown>;
+    from?: {
+        channel?: string | null;
+        channel_tenant_id?: string | null;
+        channel_conversation_id?: string | null;
+        actor_binding_id?: string | null;
+    };
+    nowMs?: number;
+}): Promise<SessionFlashRecord>;
+export declare function ackSessionFlashRecord(opts: {
+    repoRoot: string;
+    flashId: string;
+    sessionId?: string | null;
+    deliveredBy?: string | null;
+    note?: string | null;
+    nowMs?: number;
+}): Promise<SessionFlashRecord | null>;
+export declare function sessionFlashRoutes(request: Request, url: URL, deps: ServerRoutingDependencies, headers: Headers): Promise<Response>;