@mercury-fw/channel-http 0.3.0 → 0.4.0

package/CHANGELOG.md

@@ -1,5 +1,23 @@
 # @mercury-fw/channel-http
 
+## 0.4.0
+
+### Minor Changes
+
+- 521db42: Isolation between the people an agent talks to.
+
+  - The core keeps one identity per person, `<provider>:<id>`, so two providers issuing the same id are two people. Memory, the conversation archive, the tool log and pending confirmations are keyed on it.
+  - The wiki has a common area (`curated/`) everyone reads and an area per person (`users/<key>/`), which the model sees as `personal/`. Listing, reading and grepping reach the common area and the caller's own area, nothing else.
+  - Breaking: the model's `write_file` writes only under `personal/notes/`. The new `promote_note` tool copies one of the person's notes into `curated/`, and only once they confirm it with the token.
+  - A confirmation can only be confirmed by whoever staged it, in the same session. Its note is written once, in the person's area: a staged note no longer stays "pending" after it's resolved, for ids such as Google Chat's `users/<n>`.
+  - Breaking, `@mercury-fw/channel-types`: channel contract 3. `confirm` and `resolveConfirmation` take the caller's `Principal`, and so does every read getter except `manifest` and `health`. Channels written for contract 2 are refused.
+  - `@mercury-fw/confirm-engine`: the store's `stage`, `take` and `pending` take the owner's key.
+  - Breaking, `@mercury-fw/channel-http`: every read route returns only the caller's data. `/conversation?id=` takes one of the caller's `conversationId`s and `/conversations` lists them by `conversationId`. `/wiki/read` answers `404` outside what the caller can see, and `/memory/scroll` answers `400` for a collection that isn't kept per person.
+  - `@mercury-fw/channel-google-chat`: on channel contract 3.
+  - At startup, an instance's existing data moves to the new layout. Google Chat and terminal notes go into their areas, and Qdrant's ids go onto the new keys. Ids that don't say which provider they came from are left in place and logged.
+  - `mfw vault read` refuses a path outside the vault.
+  - The admin panel's wiki box edits the common area with the operator's tools (list, read, grep, `write_curated`), the same the nightly review uses.
+
 ## 0.3.0
 
 ### Minor Changes

package/README.md

@@ -76,20 +76,20 @@ Explicit alternative to re-sending a token as `/turn` `text`. Body `{ token, con
 
 ## Read-only introspection
 
-All `GET`, all JSON, all reporting state already held in-process. They need an authenticated caller, but each one still shows every person's data: scoping them per person is the next step.
+All `GET`, all JSON, all reporting state already held in-process. They need an authenticated caller and show only what belongs to them: their conversations, confirmations, tool calls and memory, and the wiki as they see it (the team's `curated/` plus their own notes as `personal/`). Someone else's data doesn't exist as far as a caller can tell; only `/manifest` and `/health` are the same for everyone.
 
 | endpoint | `data` on success |
 |---|---|
-| `GET /conversation?id=<sessionKey>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — a conversation's durable transcript in order; `400` if `id` is missing. Any session key `/conversations` lists opens here, whatever channel it came from |
-| `GET /conversations?limit=<n>` | `{ conversations: [{ sessionKey, lastTimestamp, preview }] }` — known conversations, most-recently-active first |
+| `GET /conversation?id=<conversationId>&limit=<n>&offset=<cursor>` | `{ messages: [{ role, content, timestamp }], nextOffset }` — one of your conversations, its durable transcript in order (empty for an id that isn't yours); `400` if `id` is missing or has other characters than `/turn` accepts |
+| `GET /conversations?limit=<n>` | `{ conversations: [{ conversationId, lastTimestamp, preview }] }` — your 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 /confirmations` | `{ pending: [{ sessionKey, summary, expiresAt }] }` — your pending confirmations; tokens are deliberately never included |
+| `GET /tool-log` | `{ entries: [...] }` — the tool calls of your recent turns |
 | `GET /health` | `{ uptimeSeconds, memory, qdrantReachable, ollamaReachable }` |
-| `GET /wiki/list` | `{ files: [...] }` |
-| `GET /wiki/read?path=<vault-path>` | `{ content }` — `400` if `path` is missing |
+| `GET /wiki/list` | `{ files: [...] }` — `curated/...` and `personal/...` paths |
+| `GET /wiki/read?path=<path>` | `{ content }` — a path as `/wiki/list` gives it; `400` if `path` is missing, `404` if it isn't among yours |
 | `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 /memory/scroll?collection=<name>&limit=<n>&offset=<cursor>` | one page of your points in a collection kept per person (verbatim archive, episodic memory, semantic facts); `400` for any other 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-server.d.ts

@@ -19,11 +19,11 @@
  * Confirm resolution is injected too (`confirm`/`resolveConfirmation`), so this
  * package never imports the app.
  */
-import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome } from "@mercury-fw/channel-types";
+import { type HandleTurn, type Authenticate, type ChannelHostReads, type ConfirmOutcome, type Principal } 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>;
+export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => 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 ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
 export type TurnRequestDeps = {
     handleTurn: HandleTurn;
     /** Who is calling, injected from the app's auth provider; `null` = refused. */
@@ -81,7 +81,10 @@ type ReadRoute = {
  * 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. Every `GET` asks `authenticate` first and answers 401 without
- * calling its getter when nobody is calling; the preflight doesn't ask.
+ * calling its getter when nobody is calling; the preflight doesn't ask. The
+ * caller's principal goes to every per-person getter, so the core answers with
+ * their data only; a conversation is named by its conversationId, as on
+ * `/turn`, and its session key is built from the caller.
  * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
  * same for a 400.
  */

package/http-server.ts

@@ -27,6 +27,7 @@ import {
   type Authenticate,
   type ChannelHostReads,
   type ConfirmOutcome,
+  type Principal,
 } from "@mercury-fw/channel-types";
 
 /**
@@ -43,9 +44,9 @@ function forLog(text: string): string {
 }
 
 /** 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>;
+export type ConfirmFn = (token: string, sessionKey: string, principal: Principal) => 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 ResolveConfirmationFn = (token: string, sessionKey: string, principal: Principal) => Promise<ConfirmOutcome>;
 
 export type TurnRequestDeps = {
   handleTurn: HandleTurn;
@@ -169,7 +170,7 @@ export async function handleTurnRequest(req: Request, deps: TurnRequestDeps): Pr
 
       // Same deterministic interception as every other channel — a
       // previously-approved mutation must never depend on the model.
-      const confirmReply = await deps.confirm(text, sessionKey, principal.id);
+      const confirmReply = await deps.confirm(text, sessionKey, principal);
       if (confirmReply !== null) {
         send("final", { text: confirmReply });
         close();
@@ -263,7 +264,7 @@ export async function handleConfirmRequest(req: Request, deps: ConfirmRequestDep
   if (!CONVERSATION_ID.test(conversationId)) {
     return Response.json({ ok: false, error: "invalid conversationId" }, { status: 400, headers: cors });
   }
-  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal.id);
+  const outcome = await deps.resolveConfirmation(token, `${principal.id}:${conversationId}`, principal);
   switch (outcome.status) {
     case "not-a-token":
     case "not-found":
@@ -285,7 +286,10 @@ type ReadRoute = {
  * 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. Every `GET` asks `authenticate` first and answers 401 without
- * calling its getter when nobody is calling; the preflight doesn't ask.
+ * calling its getter when nobody is calling; the preflight doesn't ask. The
+ * caller's principal goes to every per-person getter, so the core answers with
+ * their data only; a conversation is named by its conversationId, as on
+ * `/turn`, and its session key is built from the caller.
  * `json` JSON-encodes with the CORS headers merged in; `badRequest` does the
  * same for a 400.
  */
@@ -296,45 +300,60 @@ export function readRoutes(reads: ChannelHostReads, authenticate: Authenticate,
   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: async (req) => ((await authenticate(req)) === null ? unauthorized(corsOrigin) : GET(req)),
+  const route = (GET: (req: Request, principal: Principal) => Response | Promise<Response>): ReadRoute => ({
+    GET: async (req) => {
+      const principal = await authenticate(req);
+      return principal === null ? unauthorized(corsOrigin) : GET(req, principal);
+    },
     OPTIONS: options,
   });
   return {
     "/manifest": route(() => json({ ok: true, manifest: reads.manifest() })),
-    "/confirmations": route(() => json({ ok: true, pending: reads.pendingConfirmations() })),
-    "/conversation": route(async (req) => {
+    "/confirmations": route((_req, principal) => json({ ok: true, pending: reads.pendingConfirmations(principal) })),
+    "/conversation": route(async (req, principal) => {
       const url = new URL(req.url);
       const id = url.searchParams.get("id");
       if (!id) return badRequest("missing ?id");
+      if (!CONVERSATION_ID.test(id)) return badRequest("invalid conversationId");
       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) });
+      return json({ ok: true, ...(await reads.conversation(principal, `${principal.id}:${id}`, limit, offset) as object) });
     }),
-    "/conversations": route(async (req) => {
+    "/conversations": route(async (req, principal) => {
       const limit = Number(new URL(req.url).searchParams.get("limit") ?? "50");
-      return json({ ok: true, ...(await reads.conversations(limit) as object) });
+      const { conversations } = (await reads.conversations(principal, limit)) as {
+        conversations: Array<{ sessionKey: string; lastTimestamp: string; preview: string }>;
+      };
+      const prefix = `${principal.id}:`;
+      return json({
+        ok: true,
+        conversations: conversations
+          .filter((c) => c.sessionKey.startsWith(prefix))
+          .map((c) => ({ conversationId: c.sessionKey.slice(prefix.length), lastTimestamp: c.lastTimestamp, preview: c.preview })),
+      });
     }),
-    "/tool-log": route(() => json({ ok: true, entries: reads.toolLog() })),
+    "/tool-log": route((_req, principal) => json({ ok: true, entries: reads.toolLog(principal) })),
     "/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) => {
+    "/wiki/list": route(async (_req, principal) => json({ ok: true, files: await reads.wikiList(principal) })),
+    "/wiki/read": route(async (req, principal) => {
       const path = requireParam(req, "path");
       if (!path) return badRequest("missing ?path");
-      return json({ ok: true, content: await reads.wikiRead(path) });
+      const content = await reads.wikiRead(principal, path);
+      return content === null ? json({ ok: false, error: "not found" }, 404) : json({ ok: true, content });
     }),
-    "/wiki/grep": route(async (req) => {
+    "/wiki/grep": route(async (req, principal) => {
       const pattern = requireParam(req, "pattern");
       if (!pattern) return badRequest("missing ?pattern");
-      return json({ ok: true, matches: await reads.wikiGrep(pattern) });
+      return json({ ok: true, matches: await reads.wikiGrep(principal, pattern) });
     }),
-    "/memory/scroll": route(async (req) => {
+    "/memory/scroll": route(async (req, principal) => {
       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) });
+      const page = await reads.memoryScroll(principal, collection, limit, offset);
+      return page === null ? badRequest(`unknown collection: ${collection}`) : json({ ok: true, ...(page as object) });
     }),
   };
 }

package/index.ts

@@ -20,7 +20,7 @@ export { createHttpProvider, type HttpProviderDeps } from "./http-provider.ts";
 export const httpChannel: ChannelPlugin = {
   // The contract this channel is written for, as a literal: importing
   // CHANNEL_API_VERSION would report whichever contract is installed.
-  apiVersion: 2,
+  apiVersion: 3,
   name: "http",
   build: (ctx) => {
     if (!ctx.resolveConfirmation || !ctx.reads) {

package/openapi.yaml

@@ -21,6 +21,15 @@ info:
     anything runs.
 
 
+    ## What a caller sees
+
+    Every read is scoped to the caller: their own conversations, pending
+    confirmations, tool calls and memory, and the wiki as they see it, the
+    team's common area (`curated/`) plus their own notes (`personal/`).
+    Someone else's data doesn't exist as far as a caller can tell. Only
+    `/manifest` and `/health` are the same for everyone.
+
+
     ## Conversations
 
     A conversation is identified by an opaque, client-owned `conversationId`
@@ -28,10 +37,11 @@ info:
     `<caller id>:<conversationId>`, so the same id sent by someone else is a
     conversation of their own, and a confirmation token staged in one person's
     conversation is never found from another's. Omitting `conversationId` 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).
+    `POST /turn` starts a fresh ephemeral conversation. The durable transcript
+    of one of the caller's conversations is readable via `GET /conversation`,
+    and the list of their conversations via `GET /conversations` (both backed
+    by the verbatim archive; they degrade to empty when the vector store is
+    unreachable).
 
 
     ## Streaming and cancellation
@@ -127,9 +137,10 @@ paths:
         - name: id
           in: query
           required: true
-          description: The session key whose messages to return, as `/conversations` lists it (any channel's; an HTTP one is `<caller id>:<conversationId>`).
+          description: The caller's `conversationId`, as `/conversations` lists it.
           schema:
             type: string
+            pattern: "^[A-Za-z0-9_-]{1,128}$"
         - name: limit
           in: query
           required: false
@@ -146,20 +157,20 @@ paths:
         "401":
           $ref: "#/components/responses/Unauthorized"
         "200":
-          description: The conversation's messages in chronological order.
+          description: The conversation's messages in chronological order; none when it isn't one of the caller's.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/ConversationPage"
         "400":
-          description: Missing `?id`.
+          description: Missing or malformed `?id`.
           content:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
   /conversations:
     get:
-      summary: List known conversations (most-recently-active first)
+      summary: List the caller's conversations (most-recently-active first)
       parameters:
         - name: limit
           in: query
@@ -202,7 +213,7 @@ paths:
                 type: object
   /confirmations:
     get:
-      summary: Currently pending confirmations (tokens redacted)
+      summary: The caller's pending confirmations (tokens redacted)
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
@@ -214,7 +225,7 @@ paths:
                 type: object
   /tool-log:
     get:
-      summary: Recent tool-call log entries
+      summary: The tool calls made in the caller's recent turns
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
@@ -226,7 +237,7 @@ paths:
                 type: object
   /wiki/list:
     get:
-      summary: List the wiki vault's files
+      summary: List the wiki files the caller can see (`curated/` and `personal/`)
       responses:
         "401":
           $ref: "#/components/responses/Unauthorized"
@@ -238,11 +249,12 @@ paths:
                 type: object
   /wiki/read:
     get:
-      summary: Read one wiki vault file
+      summary: Read one wiki file the caller can see
       parameters:
         - name: path
           in: query
           required: true
+          description: A path as `/wiki/list` gives it, e.g. `curated/team.md` or `personal/notes/plan.md`.
           schema:
             type: string
       responses:
@@ -260,9 +272,15 @@ paths:
             application/json:
               schema:
                 $ref: "#/components/schemas/Error"
+        "404":
+          description: No such file among those the caller can see.
+          content:
+            application/json:
+              schema:
+                $ref: "#/components/schemas/Error"
   /wiki/grep:
     get:
-      summary: Grep the wiki vault
+      summary: Grep the wiki files the caller can see
       parameters:
         - name: pattern
           in: query
@@ -287,11 +305,12 @@ paths:
                 $ref: "#/components/schemas/Error"
   /memory/scroll:
     get:
-      summary: Scroll a Qdrant memory collection
+      summary: Scroll the caller's points in a memory collection
       parameters:
         - name: collection
           in: query
           required: true
+          description: One of the collections kept per person (the verbatim archive, episodic memory, semantic facts), by its configured name.
           schema:
             type: string
         - name: limit
@@ -315,7 +334,7 @@ paths:
               schema:
                 type: object
         "400":
-          description: Missing `?collection`.
+          description: Missing `?collection`, or one that isn't kept per person.
           content:
             application/json:
               schema:
@@ -452,9 +471,9 @@ components:
             - type: "null"
     ConversationSummary:
       type: object
-      required: [sessionKey, lastTimestamp, preview]
+      required: [conversationId, lastTimestamp, preview]
       properties:
-        sessionKey:
+        conversationId:
           type: string
         lastTimestamp:
           type: string

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/channel-http",
-  "version": "0.3.0",
+  "version": "0.4.0",
   "license": "MIT",
   "repository": {
     "type": "git",
@@ -18,11 +18,11 @@
     "access": "public"
   },
   "peerDependencies": {
-    "@mercury-fw/channel-types": ">=0.35.0 <1.0.0"
+    "@mercury-fw/channel-types": ">=0.36.0 <1.0.0"
   },
   "devDependencies": {
-    "@mercury-fw/channel-types": "0.35.0",
-    "@mercury-fw/plugin-types": "0.35.0",
+    "@mercury-fw/channel-types": "0.36.0",
+    "@mercury-fw/plugin-types": "0.36.0",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",
     "typescript": "^6.0.3"