@mercury-fw/channel-http 0.1.0

package/README.md

@@ -0,0 +1,86 @@
+# @mercury-fw/channel-http
+
+Gives a [Mercury](https://github.com/lucabro81/mercury-fw) agent an HTTP surface to build a custom UI on: one conversational turn per request, streamed back as Server-Sent Events, plus confirmation and read-only routes over what the agent holds (conversations, the wiki, memory, its plugins).
+
+```bash
+bun add @mercury-fw/channel-http
+```
+
+```ts
+import { httpChannel } from "@mercury-fw/channel-http";
+
+channels: [httpChannel],
+```
+
+| Variable | |
+|---|---|
+| `HTTP_SURFACE_PORT` | The port (default `4100`). |
+| `HTTP_SURFACE_CORS_ORIGIN` | The origin a browser UI calls from (default `*`). |
+
+## API
+
+It's active whenever it's declared in `mercury.config.ts`'s `channels`; remove it there to turn the surface off. It listens on `HTTP_SURFACE_PORT` (default `4100`). **No authentication** — do not publish the port outside the container network (same posture as the admin panel). Base URL `http://<host>:<port>`.
+
+**CORS** is enabled on every response and every route answers an `OPTIONS` preflight, so a browser UI on another origin can call it. The allowed origin is `HTTP_SURFACE_CORS_ORIGIN` (default `*`; no credentials are used).
+
+The full contract is described by an **OpenAPI document**, served raw at `GET /openapi.yaml` and published as a rendered docs page on GitHub Pages (see `packages/channels/channel-http/openapi.yaml`, the single source of truth).
+
+All responses are JSON except `POST /turn`, which streams `text/event-stream`. Every JSON response is either `{ "ok": true, ... }` or, on error, `{ "ok": false, "error": "<message>" }` with HTTP `400`/`500`.
+
+## `POST /turn`
+
+Runs one conversational turn; the reply streams back as Server-Sent Events.
+
+**Request body** (`application/json`):
+
+| field | type | required | description |
+|---|---|---|---|
+| `text` | string | yes | The user message. A bare confirmation token here confirms a staged action (see the `pending` event) without invoking the model. |
+| `conversationId` | string | no | Opaque, client-owned id that continues a conversation. Omitted ⇒ a fresh one-off session. |
+
+**Responses**: `200 text/event-stream` (the events below); `400` if `text` is missing or the body isn't JSON.
+
+Reasoning and answer text arrive as **incremental deltas** — never one finished block — so a UI renders them live; treat the `final` event as the authoritative text. **To cancel** a turn (e.g. a generation that's diverging), close the connection: Mercury aborts the in-flight generation.
+
+**SSE events** — each is `event: <name>` followed by `data: <json>`:
+
+| event | data | when |
+|---|---|---|
+| `reasoning` | `{ chunk, id }` | a model reasoning delta |
+| `reasoning_end` | `{ id, failed }` | a reasoning block ends |
+| `tool` | `{ label, detail, toolCallId }` | a tool call starts |
+| `tool_finish` | `{ toolCallId, outcome }` | a tool call settles (`outcome`: `success` \| `failed` \| `pending`) |
+| `text` | `{ chunk }` | an answer-text delta |
+| `pending` | `{ command, token }` | a confirm-required action was staged; send `token` back to confirm it — as a later `/turn` `text`, or via `POST /confirm` |
+| `final` | `{ text }` | the complete answer (also emitted for a token confirmation, with no model turn) |
+| `error` | `{ message }` | the turn failed mid-stream |
+
+```bash
+curl -N -X POST http://localhost:4100/turn \
+  -H 'content-type: application/json' \
+  -d '{"text":"Quante issue nel progetto KAN?","conversationId":"c1"}'
+```
+
+## `POST /confirm`
+
+Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, conversationId }`; returns `{ ok: true, resolved: true, text }` when the token was a pending confirmation, `{ ok: true, resolved: false }` otherwise. `400` if `token` or `conversationId` is missing. Never invokes the model.
+
+## Read-only introspection
+
+All `GET`, all JSON, all reporting state already held in-process.
+
+| endpoint | `data` on success |
+|---|---|
+| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — a conversation's durable transcript in order; `400` if `id` is missing |
+| `GET /conversations?limit=<n>` | `{ conversations: [{ sessionKey, lastTimestamp, preview }] }` — known conversations, most-recently-active first |
+| `GET /manifest` | `{ manifest: { coreApiVersion, plugins: [{ name, apiVersion, active, skills, hasBuild, customStatus }], activeClis, skills } }` |
+| `GET /confirmations` | `{ pending: [{ sessionKey, binary, args, expiresAt }] }` — tokens are deliberately never included |
+| `GET /tool-log` | `{ entries: [...] }` |
+| `GET /health` | `{ uptimeSeconds, memory, qdrantReachable, ollamaReachable }` |
+| `GET /wiki/list` | `{ files: [...] }` |
+| `GET /wiki/read?path=<vault-path>` | `{ content }` — `400` if `path` is missing |
+| `GET /wiki/grep?pattern=<regex>` | `{ matches: [...] }` — `400` if `pattern` is missing |
+| `GET /memory/scroll?collection=<name>&limit=<n>&offset=<cursor>` | one page of the named episodic/semantic collection |
+| `GET /openapi.yaml` | the OpenAPI document for this surface (`text/yaml`) |
+
+Conversation history and the conversation list are backed by the durable verbatim archive; they degrade to empty when the vector store is unreachable.

package/dist/http-provider.d.ts

@@ -0,0 +1,27 @@
+/**
+ * The HTTP channel's `Provider` — a thin wrapper that makes the HTTP surface a
+ * first-class channel the composition root starts and stops. The conversational
+ * mechanics (the `/turn` endpoint, SSE, the confirm interception) live in
+ * `http-server.ts`; this file only satisfies the `Provider` contract around it.
+ *
+ * `start` launches the Bun.serve and resolves immediately — the server runs in
+ * the background, so the composition root proceeds. `notify` is a no-op: HTTP is
+ * request/response, with no persistent connection to push a proactive message to
+ * (that stays with Google Chat). `stop` closes the socket on shutdown. Confirm is
+ * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
+ */
+import { type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import type { Provider, ChannelHostReads } from "@mercury-fw/channel-types";
+export type HttpProviderDeps = {
+    port: number;
+    /** Bare-token interception before the model. */
+    confirm: ConfirmFn;
+    /** Structured resolver for the `/confirm` endpoint's `resolved` flag. */
+    resolveConfirmation: ResolveConfirmationFn;
+    reads?: ChannelHostReads;
+    /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
+    corsOrigin?: string;
+};
+export declare function createHttpProvider(deps: HttpProviderDeps): Provider & {
+    stop(): Promise<void>;
+};

package/dist/http-server.d.ts

@@ -0,0 +1,88 @@
+/**
+ * The HTTP surface's Bun.serve and its one conversational endpoint (4a).
+ * `POST /turn` runs a real model turn and streams the result back as
+ * Server-Sent Events, mirroring what `terminal-provider.ts` does with console
+ * chunks: reasoning/text deltas as they arrive, a `pending` event carrying the
+ * token when a turn stages a confirm-required action, a `final` event with the
+ * complete answer. A bare confirmation token in `text` is resolved by the
+ * injected `confirm` capability, before the model is ever consulted.
+ *
+ * `handleTurnRequest` is exported (and takes its collaborators as deps — the
+ * injected `confirm` and the ephemeral session key) so the streaming behaviour
+ * is unit-tested without standing up a socket. The read-only routes (4b) mount
+ * alongside `/turn` here, driven by the injected `reads` getters.
+ *
+ * No auth by design — this surface is opt-in (enabled by listing this channel in
+ * `mercury.config.ts`) and must not be reachable from outside the container
+ * network, the same posture as the admin panel. Confirm resolution is injected
+ * (`confirm`/`resolveConfirmation`), so this package never imports the app.
+ */
+import { type HandleTurn, type ChannelHostReads, type ConfirmOutcome } from "@mercury-fw/channel-types";
+/** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
+export type ConfirmFn = (token: string, sessionKey: string, userId: string) => Promise<string | null>;
+/** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
+export type ResolveConfirmationFn = (token: string, sessionKey: string, userId: string) => Promise<ConfirmOutcome>;
+export type TurnRequestDeps = {
+    handleTurn: HandleTurn;
+    /** Bare-token interception before the model, injected by the core. */
+    confirm: ConfirmFn;
+    /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
+    corsOrigin?: string;
+    /** Test seam for the ephemeral session key when the client sends no conversationId. */
+    newSessionKey?: () => string;
+};
+/**
+ * Serves the OpenAPI document that describes this surface — the single source
+ * of truth in `apps/mercury/openapi.yaml`, also rendered as the GitHub Pages
+ * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
+ * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
+ */
+export declare function openApiResponse(corsOrigin?: string): Response;
+/**
+ * Runs one `POST /turn` request and returns an SSE stream Response. The body is
+ * `{ text, conversationId? }`; `conversationId` (opaque, client-owned) becomes
+ * the session key so a client can continue a conversation — Mercury already
+ * keys its histories by session, so many conversations run concurrently, each
+ * one-on-one (`multiUser: false`). No `conversationId` means a fresh ephemeral
+ * session. Never throws: a bad body is a 400, a mid-turn failure is an `error`
+ * event on the stream.
+ */
+export declare function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response>;
+export type ConfirmRequestDeps = {
+    resolveConfirmation: ResolveConfirmationFn;
+    corsOrigin?: string;
+};
+/**
+ * `POST /confirm { token, conversationId }` — the explicit confirmation
+ * endpoint. A nicer contract for a UI than re-POSTing the bare token as `text`
+ * to `/turn`, but the exact same mechanism underneath: it resolves the token
+ * through the injected `resolveConfirmation`, keyed on
+ * `conversationId` as the session. `resolved: true` means the token matched a
+ * pending confirmation and its staged action was consumed and run; the `text`
+ * then reports whether that execution succeeded. `resolved: false` means the
+ * token was not a pending confirmation (unknown, expired, already used, or not
+ * even token-shaped). Never touches the model.
+ */
+export declare function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response>;
+/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
+type ReadRoute = {
+    GET: (req: Request) => Response | Promise<Response>;
+    OPTIONS: () => Response;
+};
+/**
+ * Builds the read-only routes, each carrying CORS headers on its `GET` and a
+ * shared `OPTIONS` preflight so a browser UI on `corsOrigin` (default `*`) can
+ * reach them. `jsonRoute` wraps a getter into a `GET` that always JSON-encodes
+ * with the CORS headers merged in; `badRequest` does the same for a 400.
+ */
+export declare function readRoutes(reads: ChannelHostReads, corsOrigin?: string): Record<string, ReadRoute>;
+export type HttpServerDeps = TurnRequestDeps & {
+    port: number;
+    reads?: ChannelHostReads;
+    /** The `/confirm` endpoint's structured resolver, injected by the core. */
+    resolveConfirmation: ResolveConfirmationFn;
+};
+/** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
+ * when `reads` is supplied. */
+export declare function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.serve>;
+export {};

package/dist/index.d.ts

@@ -0,0 +1,16 @@
+/**
+ * The HTTP channel plugin: an opt-in conversational HTTP surface (SSE `/turn`,
+ * `/confirm`, read-only introspection routes, the OpenAPI doc) that a custom UI
+ * calls. Exported as a `ChannelPlugin` the core's channel loader consumes; it
+ * does not import the app. Enabled by listing it in `mercury.config.ts` — there
+ * is no runtime inert condition (unlike Google Chat's subscription): if it's
+ * declared, it starts.
+ *
+ * `build` reads its port and CORS origin from `env` and takes the confirm
+ * capabilities and in-process reads from the injected context (dependency
+ * inversion). Those two are optional on the contract but required here, so a
+ * context missing them throws — the loader isolates it fail-soft.
+ */
+import { type ChannelPlugin } from "@mercury-fw/channel-types";
+export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
+export declare const httpChannel: ChannelPlugin;

package/http-provider.ts

@@ -0,0 +1,48 @@
+/**
+ * The HTTP channel's `Provider` — a thin wrapper that makes the HTTP surface a
+ * first-class channel the composition root starts and stops. The conversational
+ * mechanics (the `/turn` endpoint, SSE, the confirm interception) live in
+ * `http-server.ts`; this file only satisfies the `Provider` contract around it.
+ *
+ * `start` launches the Bun.serve and resolves immediately — the server runs in
+ * the background, so the composition root proceeds. `notify` is a no-op: HTTP is
+ * request/response, with no persistent connection to push a proactive message to
+ * (that stays with Google Chat). `stop` closes the socket on shutdown. Confirm is
+ * injected (`confirm`/`resolveConfirmation`), so this package never imports the app.
+ */
+import { startHttpServer, type ConfirmFn, type ResolveConfirmationFn } from "./http-server.ts";
+import type { Provider, HandleTurn, ChannelHostReads } from "@mercury-fw/channel-types";
+
+export type HttpProviderDeps = {
+  port: number;
+  /** Bare-token interception before the model. */
+  confirm: ConfirmFn;
+  /** Structured resolver for the `/confirm` endpoint's `resolved` flag. */
+  resolveConfirmation: ResolveConfirmationFn;
+  reads?: ChannelHostReads;
+  /** Allowed CORS origin echoed to a browser UI; defaults to `*` in the server. */
+  corsOrigin?: string;
+};
+
+export function createHttpProvider(deps: HttpProviderDeps): Provider & { stop(): Promise<void> } {
+  let server: ReturnType<typeof startHttpServer> | undefined;
+  return {
+    async start(handleTurn: HandleTurn): Promise<void> {
+      server = startHttpServer({
+        port: deps.port,
+        handleTurn,
+        confirm: deps.confirm,
+        resolveConfirmation: deps.resolveConfirmation,
+        reads: deps.reads,
+        corsOrigin: deps.corsOrigin,
+      });
+    },
+    async notify(): Promise<{ sessionKey: string }> {
+      // No proactive push channel over HTTP (request/response only).
+      return { sessionKey: "" };
+    },
+    async stop(): Promise<void> {
+      server?.stop();
+    },
+  };
+}

package/http-server.ts

@@ -0,0 +1,329 @@
+/**
+ * The HTTP surface's Bun.serve and its one conversational endpoint (4a).
+ * `POST /turn` runs a real model turn and streams the result back as
+ * Server-Sent Events, mirroring what `terminal-provider.ts` does with console
+ * chunks: reasoning/text deltas as they arrive, a `pending` event carrying the
+ * token when a turn stages a confirm-required action, a `final` event with the
+ * complete answer. A bare confirmation token in `text` is resolved by the
+ * injected `confirm` capability, before the model is ever consulted.
+ *
+ * `handleTurnRequest` is exported (and takes its collaborators as deps — the
+ * injected `confirm` and the ephemeral session key) so the streaming behaviour
+ * is unit-tested without standing up a socket. The read-only routes (4b) mount
+ * alongside `/turn` here, driven by the injected `reads` getters.
+ *
+ * No auth by design — this surface is opt-in (enabled by listing this channel in
+ * `mercury.config.ts`) and must not be reachable from outside the container
+ * network, the same posture as the admin panel. Confirm resolution is injected
+ * (`confirm`/`resolveConfirmation`), so this package never imports the app.
+ */
+import {
+  detectPendingConfirmation,
+  PENDING_CONFIRMATION_NOTE,
+  type HandleTurn,
+  type TurnSink,
+  type ChannelHostReads,
+  type ConfirmOutcome,
+} from "@mercury-fw/channel-types";
+
+/** Resolves a bare confirmation token to a reply string, or `null` if the input isn't a token. Injected by the core (`ctx.confirm`). */
+export type ConfirmFn = (token: string, sessionKey: string, userId: string) => Promise<string | null>;
+/** The structured sibling of {@link ConfirmFn}, for the `/confirm` `resolved` flag. Injected by the core (`ctx.resolveConfirmation`). */
+export type ResolveConfirmationFn = (token: string, sessionKey: string, userId: string) => Promise<ConfirmOutcome>;
+
+export type TurnRequestDeps = {
+  handleTurn: HandleTurn;
+  /** Bare-token interception before the model, injected by the core. */
+  confirm: ConfirmFn;
+  /** Allowed CORS origin echoed back to a browser UI; defaults to `*`. */
+  corsOrigin?: string;
+  /** Test seam for the ephemeral session key when the client sends no conversationId. */
+  newSessionKey?: () => string;
+};
+
+const SSE_HEADERS = {
+  "content-type": "text/event-stream; charset=utf-8",
+  "cache-control": "no-cache",
+  connection: "keep-alive",
+};
+
+/**
+ * The CORS headers echoed on every response so a browser UI served from a
+ * different origin (the separate custom-UI project) can call this surface.
+ * No credentials are ever used here, so a wildcard origin is safe; a specific
+ * origin can still be pinned via `HTTP_SURFACE_CORS_ORIGIN`.
+ */
+function corsHeaders(origin: string): Record<string, string> {
+  return {
+    "access-control-allow-origin": origin,
+    "access-control-allow-methods": "GET, POST, OPTIONS",
+    "access-control-allow-headers": "content-type",
+  };
+}
+
+/** 204 preflight response for an `OPTIONS` request, carrying only CORS headers. */
+function preflight(origin: string): Response {
+  return new Response(null, { status: 204, headers: corsHeaders(origin) });
+}
+
+/**
+ * Serves the OpenAPI document that describes this surface — the single source
+ * of truth in `apps/mercury/openapi.yaml`, also rendered as the GitHub Pages
+ * API docs. Served raw as `text/yaml` (no YAML parser needed at runtime); most
+ * tooling (Redoc, Swagger UI, Postman) reads YAML directly.
+ */
+export function openApiResponse(corsOrigin = "*"): Response {
+  const file = Bun.file(new URL("./openapi.yaml", import.meta.url));
+  return new Response(file, {
+    headers: { "content-type": "text/yaml; charset=utf-8", ...corsHeaders(corsOrigin) },
+  });
+}
+
+/**
+ * Runs one `POST /turn` request and returns an SSE stream Response. The body is
+ * `{ text, conversationId? }`; `conversationId` (opaque, client-owned) becomes
+ * the session key so a client can continue a conversation — Mercury already
+ * keys its histories by session, so many conversations run concurrently, each
+ * one-on-one (`multiUser: false`). No `conversationId` means a fresh ephemeral
+ * session. Never throws: a bad body is a 400, a mid-turn failure is an `error`
+ * event on the stream.
+ */
+export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Promise<Response> {
+  const origin = deps.corsOrigin ?? "*";
+  const cors = corsHeaders(origin);
+  let body: { text?: unknown; conversationId?: unknown };
+  try {
+    body = (await req.json()) as typeof body;
+  } catch {
+    return Response.json({ ok: false, error: "body must be JSON" }, { status: 400, headers: cors });
+  }
+  if (typeof body.text !== "string" || body.text.trim().length === 0) {
+    return Response.json({ ok: false, error: "missing text" }, { status: 400, headers: cors });
+  }
+  const text = body.text;
+  const sessionKey =
+    typeof body.conversationId === "string" && body.conversationId.trim().length > 0
+      ? body.conversationId.trim()
+      : (deps.newSessionKey ?? (() => crypto.randomUUID()))();
+
+  // Aborted when the client disconnects (see the stream's `cancel` below) so
+  // the in-flight turn stops instead of running to completion — the "stop"
+  // affordance for a diverging generation.
+  const abort = new AbortController();
+
+  const stream = new ReadableStream<Uint8Array>({
+    async start(controller) {
+      const encoder = new TextEncoder();
+      // Once the client is gone the controller is closed; enqueuing then throws.
+      // Swallow it — there's no consumer left to receive the event anyway.
+      const send = (event: string, data: unknown) => {
+        try {
+          controller.enqueue(encoder.encode(`event: ${event}\ndata: ${JSON.stringify(data)}\n\n`));
+        } catch {
+          /* stream already closed/canceled */
+        }
+      };
+      const close = () => {
+        try {
+          controller.close();
+        } catch {
+          /* already closed */
+        }
+      };
+
+      // Same deterministic interception as every other channel — a
+      // previously-approved mutation must never depend on the model.
+      const confirmReply = await deps.confirm(text, sessionKey, sessionKey);
+      if (confirmReply !== null) {
+        send("final", { text: confirmReply });
+        close();
+        return;
+      }
+
+      const sink: TurnSink = {
+        onToolStart: (label, detail, toolCallId) => send("tool", { label, detail, toolCallId }),
+        onToolFinish: (toolCallId, outcome) => send("tool_finish", { toolCallId, outcome }),
+        onTextChunk: (chunk) => {
+          if (chunk !== PENDING_CONFIRMATION_NOTE) send("text", { chunk });
+        },
+        onReasoningChunk: (chunk, id) => send("reasoning", { chunk, id }),
+        onReasoningEnd: (id, failed) => send("reasoning_end", { id, failed }),
+        onStep: (step) => {
+          const pending = detectPendingConfirmation(step);
+          if (pending) send("pending", { command: pending.summary, token: pending.token });
+        },
+        onUsage: () => {},
+        finalize: async (finalText) => send("final", { text: finalText }),
+        dispose: () => {},
+      };
+
+      try {
+        await deps.handleTurn(
+          {
+            channel: "http",
+            multiUser: false,
+            text,
+            sessionKey,
+            wikiUserId: sessionKey,
+            logPrefix: `[http:${sessionKey}] `,
+            abortSignal: abort.signal,
+          },
+          sink,
+        );
+      } catch (err) {
+        // A client-initiated cancellation is a clean stop, not a failure —
+        // don't surface it as an `error` event (and there's no client left).
+        if (!abort.signal.aborted) {
+          send("error", { message: err instanceof Error ? err.message : String(err) });
+        }
+      }
+      close();
+    },
+    // Fires when the client disconnects (closes the EventSource / aborts the
+    // fetch): abort the in-flight turn so generation stops promptly.
+    cancel() {
+      abort.abort();
+    },
+  });
+
+  return new Response(stream, { headers: { ...SSE_HEADERS, ...cors } });
+}
+
+export type ConfirmRequestDeps = {
+  resolveConfirmation: ResolveConfirmationFn;
+  corsOrigin?: string;
+};
+
+/**
+ * `POST /confirm { token, conversationId }` — the explicit confirmation
+ * endpoint. A nicer contract for a UI than re-POSTing the bare token as `text`
+ * to `/turn`, but the exact same mechanism underneath: it resolves the token
+ * through the injected `resolveConfirmation`, keyed on
+ * `conversationId` as the session. `resolved: true` means the token matched a
+ * pending confirmation and its staged action was consumed and run; the `text`
+ * then reports whether that execution succeeded. `resolved: false` means the
+ * token was not a pending confirmation (unknown, expired, already used, or not
+ * even token-shaped). Never touches the model.
+ */
+export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDeps): Promise<Response> {
+  const cors = corsHeaders(deps.corsOrigin ?? "*");
+  let body: { token?: unknown; conversationId?: unknown };
+  try {
+    body = (await req.json()) as typeof body;
+  } catch {
+    return Response.json({ ok: false, error: "body must be JSON" }, { status: 400, headers: cors });
+  }
+  const token = typeof body.token === "string" ? body.token.trim() : "";
+  const sessionKey = typeof body.conversationId === "string" ? body.conversationId.trim() : "";
+  if (token.length === 0 || sessionKey.length === 0) {
+    return Response.json({ ok: false, error: "missing token or conversationId" }, { status: 400, headers: cors });
+  }
+  const outcome = await deps.resolveConfirmation(token, sessionKey, sessionKey);
+  switch (outcome.status) {
+    case "not-a-token":
+    case "not-found":
+      return Response.json({ ok: true, resolved: false }, { headers: cors });
+    case "ok":
+      return Response.json({ ok: true, resolved: true, text: `Confermato ed eseguito: ${JSON.stringify(outcome.data)}` }, { headers: cors });
+    case "failed":
+      return Response.json({ ok: true, resolved: true, text: `Confermato, ma l'esecuzione è fallita: ${outcome.error}` }, { headers: cors });
+  }
+}
+
+/** A single read route: its `GET` handler plus the shared `OPTIONS` preflight. */
+type ReadRoute = {
+  GET: (req: Request) => Response | Promise<Response>;
+  OPTIONS: () => Response;
+};
+
+/**
+ * Builds the read-only routes, each carrying CORS headers on its `GET` and a
+ * shared `OPTIONS` preflight so a browser UI on `corsOrigin` (default `*`) can
+ * reach them. `jsonRoute` wraps a getter into a `GET` that always JSON-encodes
+ * with the CORS headers merged in; `badRequest` does the same for a 400.
+ */
+export function readRoutes(reads: ChannelHostReads, corsOrigin = "*"): Record<string, ReadRoute> {
+  const cors = corsHeaders(corsOrigin);
+  const json = (payload: object, status = 200): Response =>
+    Response.json(payload, { status, headers: cors });
+  const badRequest = (message: string): Response => json({ ok: false, error: message }, 400);
+  const requireParam = (req: Request, name: string): string | null => new URL(req.url).searchParams.get(name);
+  const options = () => preflight(corsOrigin);
+  const route = (GET: ReadRoute["GET"]): ReadRoute => ({ GET, OPTIONS: options });
+  return {
+    "/manifest": route(() => json({ ok: true, manifest: reads.manifest() })),
+    "/confirmations": route(() => json({ ok: true, pending: reads.pendingConfirmations() })),
+    "/conversation": route(async (req) => {
+      const url = new URL(req.url);
+      const id = url.searchParams.get("id");
+      if (!id) return badRequest("missing ?id");
+      const limit = Number(url.searchParams.get("limit") ?? "200");
+      const offset = url.searchParams.get("offset") ?? undefined;
+      return json({ ok: true, ...(await reads.conversation(id, limit, offset) as object) });
+    }),
+    "/conversations": route(async (req) => {
+      const limit = Number(new URL(req.url).searchParams.get("limit") ?? "50");
+      return json({ ok: true, ...(await reads.conversations(limit) as object) });
+    }),
+    "/tool-log": route(() => json({ ok: true, entries: reads.toolLog() })),
+    "/health": route(async () => json({ ok: true, ...(await reads.health() as object) })),
+    "/wiki/list": route(async () => json({ ok: true, files: await reads.wikiList() })),
+    "/wiki/read": route(async (req) => {
+      const path = requireParam(req, "path");
+      if (!path) return badRequest("missing ?path");
+      return json({ ok: true, content: await reads.wikiRead(path) });
+    }),
+    "/wiki/grep": route(async (req) => {
+      const pattern = requireParam(req, "pattern");
+      if (!pattern) return badRequest("missing ?pattern");
+      return json({ ok: true, matches: await reads.wikiGrep(pattern) });
+    }),
+    "/memory/scroll": route(async (req) => {
+      const url = new URL(req.url);
+      const collection = url.searchParams.get("collection");
+      if (!collection) return badRequest("missing ?collection");
+      const limit = Number(url.searchParams.get("limit") ?? "50");
+      const offset = url.searchParams.get("offset") ?? undefined;
+      return json({ ok: true, ...(await reads.memoryScroll(collection, limit, offset) as object) });
+    }),
+  };
+}
+
+export type HttpServerDeps = TurnRequestDeps & {
+  port: number;
+  reads?: ChannelHostReads;
+  /** The `/confirm` endpoint's structured resolver, injected by the core. */
+  resolveConfirmation: ResolveConfirmationFn;
+};
+
+/** Starts the HTTP surface: `POST /turn` (4a) plus the read-only routes (4b)
+ * when `reads` is supplied. */
+export function startHttpServer(deps: HttpServerDeps): ReturnType<typeof Bun.serve> {
+  const origin = deps.corsOrigin ?? "*";
+  return Bun.serve({
+    port: deps.port,
+    // Bind all interfaces inside the container so a published port can reach it
+    // (Bun defaults to loopback-only, unreachable through Docker's port proxy).
+    // This is not "externally reachable": the container network still isolates
+    // it — production simply does not publish the port (see docker-compose).
+    hostname: "0.0.0.0",
+    // Disable the idle timeout (Bun defaults to 10s): an SSE turn can go quiet
+    // for longer than that between events — the model loading, a slow CLI
+    // subprocess — and a timeout there would reset the stream mid-turn.
+    idleTimeout: 0,
+    routes: {
+      "/turn": { POST: (req) => handleTurnRequest(req, deps), OPTIONS: () => preflight(origin) },
+      "/confirm": {
+        POST: (req) => handleConfirmRequest(req, { resolveConfirmation: deps.resolveConfirmation, corsOrigin: origin }),
+        OPTIONS: () => preflight(origin),
+      },
+      "/openapi.yaml": { GET: () => openApiResponse(origin), OPTIONS: () => preflight(origin) },
+      ...(deps.reads ? readRoutes(deps.reads, origin) : {}),
+    },
+    error: (err) =>
+      Response.json(
+        { ok: false, error: err instanceof Error ? err.message : String(err) },
+        { status: 500, headers: corsHeaders(origin) },
+      ),
+  });
+}

package/index.ts

@@ -0,0 +1,34 @@
+/**
+ * The HTTP channel plugin: an opt-in conversational HTTP surface (SSE `/turn`,
+ * `/confirm`, read-only introspection routes, the OpenAPI doc) that a custom UI
+ * calls. Exported as a `ChannelPlugin` the core's channel loader consumes; it
+ * does not import the app. Enabled by listing it in `mercury.config.ts` — there
+ * is no runtime inert condition (unlike Google Chat's subscription): if it's
+ * declared, it starts.
+ *
+ * `build` reads its port and CORS origin from `env` and takes the confirm
+ * capabilities and in-process reads from the injected context (dependency
+ * inversion). Those two are optional on the contract but required here, so a
+ * context missing them throws — the loader isolates it fail-soft.
+ */
+import { CHANNEL_API_VERSION, type ChannelPlugin } from "@mercury-fw/channel-types";
+import { createHttpProvider } from "./http-provider.ts";
+
+export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
+
+export const httpChannel: ChannelPlugin = {
+  apiVersion: CHANNEL_API_VERSION,
+  name: "http",
+  build: (ctx) => {
+    if (!ctx.resolveConfirmation || !ctx.reads) {
+      throw new Error("http channel requires the resolveConfirmation and reads capabilities on the runtime context");
+    }
+    return createHttpProvider({
+      port: Number(ctx.env.HTTP_SURFACE_PORT ?? "4100"),
+      corsOrigin: ctx.env.HTTP_SURFACE_CORS_ORIGIN ?? "*",
+      confirm: ctx.confirm,
+      resolveConfirmation: ctx.resolveConfirmation,
+      reads: ctx.reads,
+    });
+  },
+};

package/openapi.yaml

@@ -0,0 +1,418 @@
+openapi: 3.1.0
+info:
+  title: Mercury HTTP surface
+  version: 0.17.1
+  description: >
+    The HTTP surface of Mercury — the intended primary channel for a
+    custom web UI. It is enabled by declaring the `http` channel in
+    `mercury.config.ts` and, by design,
+    carries **no authentication**: it must not be published outside the trusted
+    container network (production simply does not expose the port). CORS is
+    enabled on every response (`Access-Control-Allow-Origin`, configurable via
+    `HTTP_SURFACE_CORS_ORIGIN`, default `*`) and every route answers an `OPTIONS`
+    preflight, so a browser UI on another origin can call it.
+
+
+    ## Conversations
+
+    A conversation is identified by an opaque, client-owned `conversationId`,
+    which becomes Mercury's session key. Omitting it on `POST /turn` starts a
+    fresh ephemeral conversation. The durable transcript of a conversation is
+    readable via `GET /conversation`, and the list of known conversations via
+    `GET /conversations` (both backed by the verbatim archive; they degrade to
+    empty when the vector store is unreachable).
+
+
+    ## Streaming and cancellation
+
+    `POST /turn` streams the answer as Server-Sent Events: reasoning and text
+    arrive as **incremental deltas** (never a single finished block), followed by
+    an authoritative `final` event. To cancel a turn whose generation is
+    diverging, the client simply closes the connection — Mercury aborts the
+    in-flight generation.
+
+
+    ## Confirmation
+
+    An irreversible action is never executed on the model's say-so: the turn
+    emits a `pending` event carrying a one-time `token`. The client confirms by
+    sending that token back — either as the `text` of a follow-up `POST /turn`,
+    or via `POST /confirm`.
+servers:
+  - url: http://localhost:4100
+    description: Local/dev surface (HTTP_SURFACE_PORT, default 4100)
+paths:
+  /turn:
+    post:
+      summary: Run a conversational turn (SSE stream)
+      description: >
+        Runs one model turn and streams the result as `text/event-stream`. If
+        `text` is a pending confirmation token it is resolved deterministically
+        without ever consulting the model. Close the connection to cancel an
+        in-flight turn.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/TurnRequest"
+      responses:
+        "200":
+          description: >
+            An SSE stream. Each event is one of the types in `TurnEvent`:
+            `reasoning`/`reasoning_end`, `text` (incremental deltas), `tool`/
+            `tool_finish` (status of a tool call), `pending` (a staged
+            confirm-required action, with its command and token), `final` (the
+            authoritative complete answer), and `error`.
+          content:
+            text/event-stream:
+              schema:
+                $ref: "#/components/schemas/TurnEvent"
+        "400":
+          description: Missing/invalid body.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /confirm:
+    post:
+      summary: Confirm a staged irreversible action
+      description: >
+        Runs a one-time confirmation token through the same mechanism the
+        bare-token-in-`text` path uses, keyed on `conversationId`. Never touches
+        the model.
+      requestBody:
+        required: true
+        content:
+          application/json:
+            schema:
+              $ref: "#/components/schemas/ConfirmRequest"
+      responses:
+        "200":
+          description: >
+            `resolved: true` (with the reply `text`) when the token was a pending
+            confirmation, `resolved: false` when it was not (unknown, expired, or
+            already used).
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConfirmResult"
+        "400":
+          description: Missing token or conversationId.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /conversation:
+    get:
+      summary: A conversation's durable transcript
+      parameters:
+        - name: id
+          in: query
+          required: true
+          description: The conversationId (session key) whose messages to return.
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 200
+        - name: offset
+          in: query
+          required: false
+          description: Opaque pagination cursor from a previous page's `nextOffset`.
+          schema:
+            type: string
+      responses:
+        "200":
+          description: The conversation's messages in chronological order.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConversationPage"
+        "400":
+          description: Missing `?id`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /conversations:
+    get:
+      summary: List known conversations (most-recently-active first)
+      parameters:
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 50
+      responses:
+        "200":
+          description: The conversation list.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/ConversationList"
+  /health:
+    get:
+      summary: Liveness/health of Mercury and its dependencies
+      responses:
+        "200":
+          description: Health snapshot.
+          content:
+            application/json:
+              schema:
+                type: object
+  /manifest:
+    get:
+      summary: The loaded plugins, tools and skills
+      responses:
+        "200":
+          description: Plugin manifest.
+          content:
+            application/json:
+              schema:
+                type: object
+  /confirmations:
+    get:
+      summary: Currently pending confirmations (tokens redacted)
+      responses:
+        "200":
+          description: Pending confirmations.
+          content:
+            application/json:
+              schema:
+                type: object
+  /tool-log:
+    get:
+      summary: Recent tool-call log entries
+      responses:
+        "200":
+          description: Tool log.
+          content:
+            application/json:
+              schema:
+                type: object
+  /wiki/list:
+    get:
+      summary: List the wiki vault's files
+      responses:
+        "200":
+          description: File list.
+          content:
+            application/json:
+              schema:
+                type: object
+  /wiki/read:
+    get:
+      summary: Read one wiki vault file
+      parameters:
+        - name: path
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: File content.
+          content:
+            application/json:
+              schema:
+                type: object
+        "400":
+          description: Missing `?path`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /wiki/grep:
+    get:
+      summary: Grep the wiki vault
+      parameters:
+        - name: pattern
+          in: query
+          required: true
+          schema:
+            type: string
+      responses:
+        "200":
+          description: Matches.
+          content:
+            application/json:
+              schema:
+                type: object
+        "400":
+          description: Missing `?pattern`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /memory/scroll:
+    get:
+      summary: Scroll a Qdrant memory collection
+      parameters:
+        - name: collection
+          in: query
+          required: true
+          schema:
+            type: string
+        - name: limit
+          in: query
+          required: false
+          schema:
+            type: integer
+            default: 50
+        - name: offset
+          in: query
+          required: false
+          schema:
+            type: string
+      responses:
+        "200":
+          description: A page of points.
+          content:
+            application/json:
+              schema:
+                type: object
+        "400":
+          description: Missing `?collection`.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
+  /openapi.yaml:
+    get:
+      summary: This OpenAPI document
+      responses:
+        "200":
+          description: The raw OpenAPI YAML.
+          content:
+            text/yaml:
+              schema:
+                type: string
+components:
+  schemas:
+    TurnRequest:
+      type: object
+      required: [text]
+      properties:
+        text:
+          type: string
+          description: The user's message, or a bare confirmation token.
+        conversationId:
+          type: string
+          description: Opaque, client-owned. Omit to start a fresh ephemeral conversation.
+    TurnEvent:
+      type: object
+      description: The shape carried by each SSE `data:` line, per event type.
+      properties:
+        chunk:
+          type: string
+          description: On `text`/`reasoning` — an incremental delta.
+        id:
+          type: string
+          description: On `reasoning`/`reasoning_end` — the reasoning block id.
+        failed:
+          type: boolean
+          description: On `reasoning_end`.
+        label:
+          type: string
+          description: On `tool` — a human status label.
+        detail:
+          type: string
+          description: On `tool` — optional detail.
+        toolCallId:
+          type: string
+          description: On `tool`/`tool_finish`.
+        outcome:
+          type: string
+          description: On `tool_finish` — success/failed.
+        command:
+          type: string
+          description: On `pending` — the staged action's summary.
+        token:
+          type: string
+          description: On `pending` — the one-time confirmation token.
+        text:
+          type: string
+          description: On `final` — the authoritative complete answer.
+        message:
+          type: string
+          description: On `error` — the failure message.
+    ConfirmRequest:
+      type: object
+      required: [token, conversationId]
+      properties:
+        token:
+          type: string
+        conversationId:
+          type: string
+    ConfirmResult:
+      type: object
+      required: [ok, resolved]
+      properties:
+        ok:
+          type: boolean
+        resolved:
+          type: boolean
+        text:
+          type: string
+          description: The confirmation reply, present when `resolved` is true.
+    Message:
+      type: object
+      required: [role, content, timestamp]
+      properties:
+        role:
+          type: string
+          enum: [user, assistant]
+        content:
+          type: string
+        timestamp:
+          type: string
+          description: ISO 8601, millisecond precision — the durable ordering key.
+    ConversationPage:
+      type: object
+      required: [ok, messages]
+      properties:
+        ok:
+          type: boolean
+        messages:
+          type: array
+          items:
+            $ref: "#/components/schemas/Message"
+        nextOffset:
+          description: Opaque cursor for the next page, or null when exhausted.
+          oneOf:
+            - type: string
+            - type: "null"
+    ConversationSummary:
+      type: object
+      required: [sessionKey, lastTimestamp, preview]
+      properties:
+        sessionKey:
+          type: string
+        lastTimestamp:
+          type: string
+        preview:
+          type: string
+    ConversationList:
+      type: object
+      required: [ok, conversations]
+      properties:
+        ok:
+          type: boolean
+        conversations:
+          type: array
+          items:
+            $ref: "#/components/schemas/ConversationSummary"
+    Error:
+      type: object
+      required: [ok, error]
+      properties:
+        ok:
+          type: boolean
+          enum: [false]
+        error:
+          type: string

package/package.json

@@ -0,0 +1,41 @@
+{
+  "name": "@mercury-fw/channel-http",
+  "version": "0.1.0",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/lucabro81/mercury-fw.git",
+    "directory": "packages/channels/channel-http"
+  },
+  "files": [
+    "*.ts",
+    "dist",
+    "openapi.yaml",
+    "CHANGELOG.md",
+    "!**/*.test.ts"
+  ],
+  "publishConfig": {
+    "access": "public"
+  },
+  "peerDependencies": {
+    "@mercury-fw/channel-types": ">=0.24.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@mercury-fw/channel-types": "0.25.0",
+    "@mercury-fw/plugin-types": "0.25.0",
+    "@mercury-fw/typescript-config": "*",
+    "@types/bun": "^1.4.0",
+    "typescript": "^6.0.3"
+  },
+  "exports": {
+    ".": {
+      "mercury-fw-source": "./index.ts",
+      "types": "./dist/index.d.ts",
+      "default": "./index.ts"
+    }
+  },
+  "scripts": {
+    "test": "bun test",
+    "typecheck": "tsc --noEmit"
+  }
+}