@mercury-fw/core 0.32.0 → 0.34.0

package/CHANGELOG.md

@@ -1,5 +1,45 @@
 # @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
+
+- a493d9b: - A plugin whose CLI keeps its login in a folder declares it in its `package.json` (`mercury.cliCredentials`): `{ folder }` under `~/.config`, the default, or `{ path }` anywhere else under the home. Any plugin's CLI gets the login mechanism, not only the first-party ones.
+  - The core unpacks each declared login from its env variable onto the credentials volume (`~/.config`) at startup, only when the folder isn't there yet, for the service and the REPL alike; a folder declared elsewhere in the home lives on the volume under `~/.config/mercury-home`, linked from its usual place. It warns about a declared folder with neither the folder nor the variable.
+  - `mfw credentials set|reset <plugin>` names the plugin by its package or its CLI's folder (`@mercury-fw/plugin-jira` or `jira-cli`), read from the app's installed plugins; the short name (`jira`) is no longer accepted, and reset asks for the folder's name.
+  - `mfw create` no longer writes `docker-entrypoint.sh` or the credentials variables in the env example, and always mounts the `cli-credentials` volume; an existing app's entrypoint keeps working alongside.
+  - The generated README explains how a plugin's CLI gets its login without listing plugins.
+  - jira, bitbucket and atlassian-admin declare their CLI's login folder; their READMEs point to `mfw credentials set`.
+
+### Patch Changes
+
+- Updated dependencies [a493d9b]
+  - @mercury-fw/utils@0.33.0
+  - @mercury-fw/plugin-types@0.33.0
+  - @mercury-fw/channel-types@0.33.0
+  - @mercury-fw/cli-engine@0.33.0
+  - @mercury-fw/confirm-engine@0.33.0
+
 ## 0.32.0
 
 ### Minor Changes

package/dist/src/credentials/materialize.d.ts

@@ -0,0 +1,13 @@
+/** Where to read the declarations and where to unpack them. */
+export interface MaterializeOptions {
+    /** The app's folder (its package.json and node_modules). */
+    appDir: string;
+    /** The home the CLIs run with; its `.config` is the credentials volume. */
+    homeDir: string;
+    env: Record<string, string | undefined>;
+    log: (msg: string) => void;
+}
+/** Unpacks every declared login that's missing from the volume and has its
+ * variable set, and links one declared outside `~/.config`; warns about one
+ * that has neither, and logs each dependency it couldn't read. */
+export declare function materializeCliCredentials({ appDir, homeDir, env, log }: MaterializeOptions): Promise<void>;

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.32.0",
+  "version": "0.34.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -31,10 +31,11 @@
     "test": "bun test"
   },
   "dependencies": {
-    "@mercury-fw/channel-types": "0.32.0",
-    "@mercury-fw/cli-engine": "0.32.0",
-    "@mercury-fw/confirm-engine": "0.32.0",
-    "@mercury-fw/plugin-types": "0.32.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

@@ -21,6 +21,7 @@ import { createConfirmationStore, createStageConfirmation, tryConfirm, resolveCo
 import { createDisplayStore } from "./tools/display-store.ts";
 import { createPresentTool } from "./tools/present-tool.ts";
 import { loadPlugins } from "./plugins/plugin-loader.ts";
+import { materializeCliCredentials } from "./credentials/materialize.ts";
 import type { MercuryConfig } from "./config/define-config.ts";
 import { createSessionHistory, type SessionHistory, type Message } from "./session/history.ts";
 import { createSummarizer } from "./session/summarizer.ts";
@@ -66,6 +67,7 @@ import { listWikiFilesInRoots, readWikiFile, readWikiFileInRoots, readIndexFile
 import { runRawTriagePass, runIndexAndOrphanPass, runContradictionCheckPass } from "./wiki/self-review-runner.ts";
 import { startSelfReviewCron } from "./cron/self-review-cron.ts";
 import { resolve as resolvePath } from "node:path";
+import { homedir } from "node:os";
 import type { Tool } from "ai";
 import { startAdminServer } from "./admin/server.ts";
 // The HTTP surface's read routes (4b) reuse the admin panel's per-domain
@@ -148,6 +150,15 @@ export async function composeMercury(config: MercuryConfig): Promise<ComposedApp
   // that fails (an invalid allowlist, missing configuration) degrades only itself.
   const plugins = config.plugins;
 
+  // A plugin's CLI that keeps its login in a folder finds it in place before
+  // the plugin loads: unpacked from the env file on a fresh credentials volume.
+  await materializeCliCredentials({
+    appDir: process.cwd(),
+    homeDir: homedir(),
+    env: process.env,
+    log: (msg) => console.error(msg),
+  });
+
   const loadedPlugins = await loadPlugins(plugins, {
     model,
     env: process.env,
@@ -372,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/credentials/materialize.ts

@@ -0,0 +1,104 @@
+/**
+ * Unpacks each plugin-declared CLI credentials variable onto the config folder
+ * at startup. A plugin whose CLI keeps its login in a folder declares it in its
+ * package.json (`mercury.cliCredentials`, read by `@mercury-fw/utils`); the
+ * app's env file carries that folder packed into a variable (`mfw credentials
+ * set` writes it). In the container `~/.config` is the credentials volume, so
+ * this unpacks only while a CLI's folder isn't there yet: what the CLI writes
+ * back afterwards, like a refreshed token, stays across redeploys and an older
+ * variable never overwrites it. A login declared elsewhere in the home lives
+ * on the volume too (`volumePath`), and the home path is made a link to it at
+ * every start, since the rest of the home is the image's and starts over each
+ * time. Called by `composeMercury` before the plugins load, so the service and
+ * the REPL both get it. Never throws: a CLI without its login degrades only
+ * that plugin's calls. It works on the home it's given, so an app run outside
+ * its container (against the Docker-first rule) would unpack into the real
+ * home: only with a credentials variable set and the folder missing there.
+ */
+import { existsSync, lstatSync, mkdirSync, mkdtempSync, readlinkSync, renameSync, rmSync, symlinkSync } from "node:fs";
+import { basename, dirname, join } from "node:path";
+import { appCliCredentials, volumePath, type CliCredentials } from "@mercury-fw/utils";
+
+/** Where to read the declarations and where to unpack them. */
+export interface MaterializeOptions {
+  /** The app's folder (its package.json and node_modules). */
+  appDir: string;
+  /** The home the CLIs run with; its `.config` is the credentials volume. */
+  homeDir: string;
+  env: Record<string, string | undefined>;
+  log: (msg: string) => void;
+}
+
+/** Unpacks every declared login that's missing from the volume and has its
+ * variable set, and links one declared outside `~/.config`; warns about one
+ * that has neither, and logs each dependency it couldn't read. */
+export async function materializeCliCredentials({ appDir, homeDir, env, log }: MaterializeOptions): Promise<void> {
+  let declared: CliCredentials[];
+  try {
+    const read = appCliCredentials(appDir);
+    for (const problem of read.problems) log(`CLI credentials: ${problem}`);
+    declared = read.declared;
+  } catch (err) {
+    log(`CLI credentials not unpacked: ${err instanceof Error ? err.message : String(err)}`);
+    return;
+  }
+  for (const c of declared) {
+    const target = join(homeDir, volumePath(c.path));
+    if (!existsSync(target)) {
+      const value = env[c.variable];
+      if (value === undefined || value === "") {
+        log(
+          `${c.package}: no login for its CLI (no ${c.name} folder, ${c.variable} not set): run mfw credentials set ${c.name}`,
+        );
+        continue;
+      }
+      try {
+        await unpack(value, basename(c.path), target);
+      } catch (err) {
+        log(`${c.package}: could not unpack ${c.variable} into ${c.name}: ${err instanceof Error ? err.message : String(err)}`);
+        continue;
+      }
+    }
+    const link = join(homeDir, c.path);
+    if (link === target) continue;
+    try {
+      linkTo(target, link, (msg) => log(`${c.package}: ${msg}`));
+    } catch (err) {
+      log(`${c.package}: could not link ${link} to the credentials volume: ${err instanceof Error ? err.message : String(err)}`);
+    }
+  }
+}
+
+/** Makes `link` a symlink to `target` unless it already is one; anything else
+ * at `link` is never replaced, only reported. */
+function linkTo(target: string, link: string, log: (msg: string) => void): void {
+  const existing = lstatSync(link, { throwIfNoEntry: false });
+  if (existing === undefined) {
+    mkdirSync(dirname(link), { recursive: true });
+    symlinkSync(target, link);
+  } else if (!existing.isSymbolicLink() || readlinkSync(link) !== target) {
+    log(`${link} is already there and isn't a link to the credentials volume: the CLI won't find its login`);
+  }
+}
+
+/** Extracts only `member` from the base64 tar.gz into a staging folder next to
+ * `target`, then moves it to `target`: a failed extraction leaves nothing
+ * behind that would count as present on the next start. */
+async function unpack(value: string, member: string, target: string): Promise<void> {
+  mkdirSync(dirname(target), { recursive: true });
+  const staging = mkdtempSync(join(dirname(target), `.${member}-`));
+  try {
+    const proc = Bun.spawn(["tar", "-xzf", "-", "-C", staging, member], {
+      stdin: Buffer.from(value, "base64"),
+      stdout: "ignore",
+      stderr: "pipe",
+    });
+    const [code, stderr] = await Promise.all([proc.exited, new Response(proc.stderr).text()]);
+    if (code !== 0 || !existsSync(join(staging, member))) {
+      throw new Error(stderr.trim() || `tar exited with ${code}`);
+    }
+    renameSync(join(staging, member), target);
+  } finally {
+    rmSync(staging, { recursive: true, force: true });
+  }
+}

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)];
 }