@mercury-fw/core 0.33.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,25 @@
 # @mercury-fw/core
 
+## 0.34.0
+
+### Minor Changes
+
+- 8bed46b: - A turn carries a `Principal` (the person behind it and the provider that vouched for them) instead of the opaque `userId` and `wikiUserId`; the core derives every per-person id from it.
+  - Episodic memory follows the principal, not the channel: a session is captured whenever a provider vouched for the person. Google Chat keeps the ids it had; the terminal and the HTTP channel (until it authenticates its callers) send a principal nobody vouched for, so they stay out of episodic memory as before.
+  - The HTTP channel accepts a `conversationId` on `/turn` and `/confirm` only made of letters, digits, `-` and `_`, up to 128 characters once trimmed, and answers `400` otherwise: a client-chosen id can no longer reach another user's wiki notes, forge log lines or break the turn. An existing HTTP conversation whose id has other characters can still be read with `/conversation`, but not continued. `/conversation` keeps opening any session key `/conversations` lists, whatever channel it came from.
+  - The model's wiki read tools refuse a per-user id that isn't one path segment, as writes already did.
+  - `CHANNEL_API_VERSION` is 2: a channel written for version 1 is refused at load.
+  - The first-party channels declare their channel api version as a literal, so an older channel can't claim a newer contract it doesn't implement.
+
+### Patch Changes
+
+- Updated dependencies [8bed46b]
+  - @mercury-fw/channel-types@0.34.0
+  - @mercury-fw/confirm-engine@0.34.0
+  - @mercury-fw/plugin-types@0.34.0
+  - @mercury-fw/cli-engine@0.34.0
+  - @mercury-fw/utils@0.34.0
+
 ## 0.33.0
 
 ### Minor Changes

package/dist/src/wiki/frontmatter-schema.d.ts

@@ -41,8 +41,8 @@ export declare const ConfirmationFrontmatterSchema: z.ZodObject<{
     type: z.ZodLiteral<"confirmation">;
     status: z.ZodEnum<{
         pending: "pending";
-        failed: "failed";
         confirmed: "confirmed";
+        failed: "failed";
     }>;
     requested_at: z.ZodString;
     resolved_at: z.ZodNullable<z.ZodString>;

package/dist/src/wiki/wiki-note.d.ts

@@ -1,3 +1,5 @@
+/** Throws unless `value` is exactly one non-empty path segment (no separator, not `.` or `..`). Shared by the read side's per-user root. */
+export declare function assertNoPathSeparator(label: string, value: string): void;
 /** `path` relative to curated/: a vault-relative one (`curated/x.md`, as
  * listing, reading and grepping give it) loses its leading `curated/`. */
 export declare function relativeToCurated(path: string): string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/core",
-  "version": "0.33.0",
+  "version": "0.34.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,11 +31,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.33.0",
-    "@mercury-fw/cli-engine": "0.33.0",
-    "@mercury-fw/confirm-engine": "0.33.0",
-    "@mercury-fw/plugin-types": "0.33.0",
-    "@mercury-fw/utils": "0.33.0",
+    "@mercury-fw/channel-types": "0.34.0",
+    "@mercury-fw/cli-engine": "0.34.0",
+    "@mercury-fw/confirm-engine": "0.34.0",
+    "@mercury-fw/plugin-types": "0.34.0",
+    "@mercury-fw/utils": "0.34.0",
     "@qdrant/js-client-rest": "^1.19.0",
     "ai": "^7.0.126",
     "ai-sdk-ollama": "^4.4.0",

package/src/compose.ts

@@ -383,7 +383,7 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
 
   // `wikiUserId` is separate from `sessionKey`: inferred/users/<userId> notes
   // are scoped per-person, not per-(space,person) pair, so it must not include
-  // the space. An identity-less channel (the terminal) uses a fixed id.
+  // the space. The turn runner derives it from the turn's principal.
   function buildTools(
     sessionKey: string,
     wikiUserId: string,

package/src/router/terminal-provider.ts

@@ -17,10 +17,13 @@ import { getLoadedContextLength } from "../model/context-size.ts";
 import { detectPendingConfirmation } from "../session/pending-confirmation.ts";
 import { PENDING_CONFIRMATION_NOTE } from "../session/agent-turn.ts";
 import type { Provider, HandleTurn, TurnSink } from "./provider.ts";
+import type { Principal } from "@mercury-fw/channel-types";
 import type { StepInfo } from "../session/step-info.ts";
 import type { writeConfirmationNote } from "../wiki/wiki-note.ts";
 
 const TERMINAL_SESSION_KEY = "terminal";
+/** The terminal is a single-user debug console: one fixed principal nobody vouched for, so its sessions stay out of episodic memory. */
+const TERMINAL_PRINCIPAL: Principal = { id: "terminal", provider: "none" };
 
 export type TerminalProviderDeps = {
   confirmDeps: {
@@ -134,7 +137,7 @@ export function createTerminalProvider(deps: TerminalProviderDeps): Provider {
               multiUser: false,
               text: input,
               sessionKey: TERMINAL_SESSION_KEY,
-              wikiUserId: TERMINAL_SESSION_KEY,
+              principal: TERMINAL_PRINCIPAL,
               logPrefix: "",
             },
             sink,

package/src/router/turn-runner.ts

@@ -24,6 +24,7 @@ export type { PostTurnGuard };
 import type { SessionHistory } from "../session/history.ts";
 import { recordStep } from "../session/tool-log-buffer.ts";
 import type { HandleTurn, InboundTurn, TurnSink } from "./provider.ts";
+import type { Principal } from "@mercury-fw/channel-types";
 
 export type TurnRunnerDeps = {
   model: LanguageModel;
@@ -93,15 +94,32 @@ export type TurnRunnerDeps = {
   takeSurfacedDisplays?: (sessionKey: string) => string[];
 };
 
+/**
+ * The per-person ids the core derives from a turn's principal. `captureUserId`
+ * is the raw id, set only when a provider vouched for the person, so a turn
+ * nobody vouched for is never tracked for Layer-3 capture. `wikiUserId` is the
+ * same id encoded for `inferred/users/<id>` and the verbatim archive, so a "/"
+ * can't add a segment; `.` and `..` survive encoding and are refused by the
+ * wiki's own guards. `toWellFormed` keeps a lone surrogate from making the
+ * encoding throw.
+ */
+function principalIds(principal: Principal): { captureUserId?: string; wikiUserId: string } {
+  return {
+    captureUserId: principal.provider === "none" ? undefined : principal.id,
+    wikiUserId: encodeURIComponent(principal.id.toWellFormed()),
+  };
+}
+
 /** Builds the shared `HandleTurn` every provider's driver calls once it has a real message to run through the model. */
 export function createTurnRunner(deps: TurnRunnerDeps): HandleTurn {
   const postTurnGuards = deps.postTurnGuards ?? [];
   const logPostTurnGuard = deps.logPostTurnGuardFn ?? ((message: string) => console.log(message));
 
   return async (turn: InboundTurn, sink: TurnSink): Promise<void> => {
-    const tracked = turn.userId !== undefined;
+    const { captureUserId, wikiUserId } = principalIds(turn.principal);
+    const tracked = captureUserId !== undefined;
     if (tracked) {
-      deps.trackSession(turn.sessionKey, turn.userId as string, (deps.now ?? Date.now)());
+      deps.trackSession(turn.sessionKey, captureUserId, (deps.now ?? Date.now)());
       deps.registerCaptureCallback(turn.sessionKey, sink.onToolStart, sink.onToolFinish);
     }
 
@@ -119,10 +137,10 @@ export function createTurnRunner(deps: TurnRunnerDeps): HandleTurn {
       // already scheduled when the sink was constructed keeps running
       // otherwise, firing on its own 60s schedule regardless of whether
       // the turn itself already failed and was reported.
-      history = await deps.getOrCreateHistory(turn.sessionKey, tracked, turn.userId);
+      history = await deps.getOrCreateHistory(turn.sessionKey, tracked, captureUserId);
       const text = await (deps.runTurnFn ?? runTurn)(history, turn.text, {
         model: deps.model,
-        tools: deps.buildTools(turn.sessionKey, turn.wikiUserId, sink.onToolStart, sink.onToolFinish),
+        tools: deps.buildTools(turn.sessionKey, wikiUserId, sink.onToolStart, sink.onToolFinish),
         system: turn.multiUser ? deps.systemPrompts.multiUser : deps.systemPrompts.singleUser,
         onTextChunk: sink.onTextChunk,
         onReasoningChunk: sink.onReasoningChunk,
@@ -187,12 +205,16 @@ export function createTurnRunner(deps: TurnRunnerDeps): HandleTurn {
       // propagate out of this awaited handler and take the process down.
       if (deps.captureVerbatim) {
         // The archive is per-person and space-independent, so it keys on
-        // wikiUserId — Mercury's canonical per-user id, the same identity the
-        // wiki notes use — not the space-scoped session.
-        const userId = turn.wikiUserId;
+        // wikiUserId (the same identity the wiki notes use), not the
+        // space-scoped session.
         try {
-          await deps.captureVerbatim({ sessionKey: turn.sessionKey, userId, role: "user", content: turn.text });
-          await deps.captureVerbatim({ sessionKey: turn.sessionKey, userId, role: "assistant", content: assistantText });
+          await deps.captureVerbatim({ sessionKey: turn.sessionKey, userId: wikiUserId, role: "user", content: turn.text });
+          await deps.captureVerbatim({
+            sessionKey: turn.sessionKey,
+            userId: wikiUserId,
+            role: "assistant",
+            content: assistantText,
+          });
         } catch (err) {
           console.log(
             `[verbatim-archive] capture failed, turn unaffected: ${String(err instanceof Error ? err.message : err)}`,

package/src/wiki/wiki-note.ts

@@ -50,7 +50,8 @@ function resolveWithinRoot(root: string, ...segments: string[]): string {
   return target;
 }
 
-function assertNoPathSeparator(label: string, value: string): void {
+/** Throws unless `value` is exactly one non-empty path segment (no separator, not `.` or `..`). Shared by the read side's per-user root. */
+export function assertNoPathSeparator(label: string, value: string): void {
   if (value === "" || value.includes("/") || value.includes("\\") || value === "." || value === "..") {
     throw new Error(`invalid ${label}: ${JSON.stringify(value)}`);
   }

package/src/wiki/wiki-read.ts

@@ -10,6 +10,7 @@
  */
 import { readFile, stat } from "node:fs/promises";
 import { join, relative, resolve, sep } from "node:path";
+import { assertNoPathSeparator } from "./wiki-note.ts";
 
 async function pathExists(path: string): Promise<boolean> {
   try {
@@ -21,6 +22,7 @@ async function pathExists(path: string): Promise<boolean> {
 }
 
 function allowedRoots(vaultPath: string, userId: string): string[] {
+  assertNoPathSeparator("userId", userId);
   const vaultRoot = resolve(vaultPath);
   return [resolve(vaultRoot, "curated"), resolve(vaultRoot, "inferred", "users", userId)];
 }