@mercury-fw/cli 0.47.0 → 0.48.0

package/CHANGELOG.md

@@ -1,5 +1,30 @@
 # @mercury-fw/cli
 
+## 0.48.0
+
+### Minor Changes
+
+- 62bb3a3: - `persona.name` is the assistant's name, Mercury when left out. A name that's blank, longer than 40 characters or on more than one line stops the app at startup.
+  - Every text the model reads refers to the name as `{{assistant}}`, and the core puts the persona's name there: the persona's identity and tone, the system prompt, plugin fragments, skills and tool descriptions. The model no longer takes "Mercury" for its own name when the app calls its assistant something else.
+  - Where the one acting is the system around the model, the texts say "the system" or "this instance" instead of Mercury: the wiki tools, the cli-engine's errors, the jira skill and its issue lists.
+  - Plugins get `assistantName` in their `build()` context, and channels in their runtime context, for texts they build while running. The login messages, the linking reply and the HTTP login page name the assistant that way.
+  - The tools a person runs as the assistant itself are `<tool>AsSelf`, previously `<tool>AsMercury`. The `mercury.act-as-self` roles are unchanged.
+  - `mfw create` writes the assistant's name as `persona.name`, with `persona/identity.md` and `persona/tone.md` referring to it. An existing app keeps working as it is: to rename its assistant everywhere, add `name` to its persona and write `{{assistant}}` in its persona files.
+
+### Patch Changes
+
+- Updated dependencies [62bb3a3]
+  - @mercury-fw/core@0.48.0
+  - @mercury-fw/utils@0.48.0
+
+## 0.47.1
+
+### Patch Changes
+
+- e005ca4: - `mfw e2e`: a REPL that exits before its stderr has been read no longer reports "exited with code N:" without the reason.
+  - @mercury-fw/core@0.47.1
+  - @mercury-fw/utils@0.47.1
+
 ## 0.47.0
 
 ### Patch Changes

package/README.md

@@ -47,7 +47,7 @@ Without a global install: `bun create mercury-agent my-agent` creates an app, an
 Writes a new Mercury app into `<folder>`, which has to be missing or empty; the folder's own name is turned into kebab case (`My Agent` becomes `my-agent`, the path above it stays as typed). Without flags it asks:
 
 - the app name (the `name` in `package.json`, defaulting to the folder's);
-- the assistant's name and role, which become `persona/identity.md` ("You are Hermes, the platform team's release assistant.") next to a `persona/tone.md` to edit;
+- the assistant's name and role: the name becomes `persona.name` in the config, the role `persona/identity.md` ("You are {{assistant}}, the platform team's release assistant.", the core putting the name in place of `{{assistant}}`), next to a `persona/tone.md` to edit;
 - which channels and which tool plugins to include (none is fine: the REPL always works);
 - the git remote for `origin`, which you can leave empty (most of the time it doesn't exist yet when you scaffold).
 

package/dist/src/e2e/session.d.ts

@@ -10,6 +10,20 @@ export type ReplSessionOptions = {
     name: string;
     /** How long one turn may take. */
     timeoutMs: number;
+    /** Starts the REPL; a test hands in a stand-in process. */
+    spawn?: (argv: string[], cwd: string) => ReplProcess;
+};
+/** The parts of a spawned process the session uses. */
+export type ReplProcess = {
+    stdin: {
+        write: (text: string) => unknown;
+        flush: () => unknown;
+        end: () => unknown;
+    };
+    stdout: ReadableStream<Uint8Array>;
+    stderr: ReadableStream<Uint8Array>;
+    exited: Promise<number>;
+    kill: () => void;
 };
 /** Starts the REPL and returns the session over it once the REPL is ready
  * (its first prompt is out), so a turn's time is only the turn's; throws

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.47.0",
+  "version": "0.48.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,20 +41,20 @@
   "comment:shape": "The Mercury CLI (`mfw`). `mfw create <dir>` writes a new Mercury app from the template. The framework packages move in lockstep with it, so a new app gets them at the CLI's own version; plugins and channels at the registry's latest. The plugin and channel packages are devDependencies only for the catalog test. `main(argv)` is exported for create-mercury-agent.",
   "dependencies": {
     "@clack/prompts": "^1.8.1",
-    "@mercury-fw/core": "0.47.0",
-    "@mercury-fw/utils": "0.47.0",
+    "@mercury-fw/core": "0.48.0",
+    "@mercury-fw/utils": "0.48.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
     "@mercury-fw/auth-oidc": "0.2.0",
     "@mercury-fw/auth-static": "0.2.1",
     "@mercury-fw/channel-google-chat": "0.7.0",
-    "@mercury-fw/channel-http": "0.8.3",
+    "@mercury-fw/channel-http": "0.8.4",
     "@mercury-fw/directory-static": "0.1.1",
-    "@mercury-fw/formatter": "0.47.0",
+    "@mercury-fw/formatter": "0.48.0",
     "@mercury-fw/plugin-atlassian-admin": "0.3.2",
     "@mercury-fw/plugin-bitbucket": "0.4.1",
-    "@mercury-fw/plugin-jira": "0.6.2",
+    "@mercury-fw/plugin-jira": "0.6.3",
     "@mercury-fw/plugin-zitadel": "0.3.2",
     "@mercury-fw/typescript-config": "*",
     "@types/bun": "^1.4.2",

package/src/e2e/session.ts

@@ -22,13 +22,31 @@ export type ReplSessionOptions = {
   name: string;
   /** How long one turn may take. */
   timeoutMs: number;
+  /** Starts the REPL; a test hands in a stand-in process. */
+  spawn?: (argv: string[], cwd: string) => ReplProcess;
 };
 
+/** The parts of a spawned process the session uses. */
+export type ReplProcess = {
+  stdin: { write: (text: string) => unknown; flush: () => unknown; end: () => unknown };
+  stdout: ReadableStream<Uint8Array>;
+  stderr: ReadableStream<Uint8Array>;
+  exited: Promise<number>;
+  kill: () => void;
+};
+
+/** How long, once the REPL is gone, its stderr may take to be read to its end. */
+const STDERR_DRAIN_MS = 1000;
+
+function spawnRepl(argv: string[], cwd: string): ReplProcess {
+  return Bun.spawn(argv, { cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+}
+
 /** Starts the REPL and returns the session over it once the REPL is ready
  * (its first prompt is out), so a turn's time is only the turn's; throws
  * when the REPL exits or doesn't get there in time. */
 export async function openReplSession(opts: ReplSessionOptions): Promise<Session<ReplReply>> {
-  const proc = Bun.spawn(opts.argv, { cwd: opts.cwd, stdin: "pipe", stdout: "pipe", stderr: "pipe" });
+  const proc = (opts.spawn ?? spawnRepl)(opts.argv, opts.cwd);
   let stdout = "";
   let stderr = "";
   let exited: number | undefined;
@@ -42,8 +60,11 @@ export async function openReplSession(opts: ReplSessionOptions): Promise<Session
     }
   };
   void pump(proc.stdout, (t) => (stdout += t));
-  void pump(proc.stderr, (t) => (stderr += t));
-  void proc.exited.then((code) => {
+  const stderrRead = pump(proc.stderr, (t) => (stderr += t)).catch(() => {});
+  // The exit counts once stderr is read to its end, or the reason it gives is
+  // lost; a grandchild still holding the pipe open bounds the wait.
+  void proc.exited.then(async (code) => {
+    await Promise.race([stderrRead, new Promise((r) => setTimeout(r, STDERR_DRAIN_MS))]);
     exited = code;
     notify();
   });

package/src/program.ts

@@ -52,7 +52,7 @@ function buildProgram(handlers: ProgramHandlers, result: { code: number }): Comm
     .command("create")
     .summary("writes a new Mercury app")
     .description(
-      "Writes a new Mercury app into <folder>, which has to be missing or empty (its own name is turned into kebab case). Without options it asks for the app name, the assistant's name and role, and which channels (with the HTTP channel's auth provider) and tool plugins to include; then it writes mercury.config.ts for that selection, the persona (persona/identity.md, persona/tone.md), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Then it runs bun install, and creates a git repository on main with a first commit, adding the origin when given (nothing is pushed).",
+      "Writes a new Mercury app into <folder>, which has to be missing or empty (its own name is turned into kebab case). Without options it asks for the app name, the assistant's name and role, and which channels (with the HTTP channel's auth provider) and tool plugins to include; then it writes mercury.config.ts for that selection, with the assistant's name as persona.name, the persona (persona/identity.md, persona/tone.md, which refer to the name as {{assistant}}), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the app reads. Then it runs bun install, and creates a git repository on main with a first commit, adding the origin when given (nothing is pushed).",
     )
     .argument("<folder>", "where to write the app")
     .option("--name <name>", "app name, as in package.json (default: the folder's name)")

package/src/render.ts

@@ -8,7 +8,7 @@
  * written in catalog order, whatever order they were chosen in; the auth
  * provider, when there is one, after the channels.
  */
-import { DEFAULT_PERSONA_TONE } from "@mercury-fw/core";
+import { DEFAULT_PERSONA_IDENTITY, DEFAULT_PERSONA_TONE, assistantNameOf } from "@mercury-fw/core";
 import { CATALOG, type CatalogEntry, type EnvVar } from "./catalog.ts";
 import indexTs from "../template/src/index.ts.tpl" with { type: "text" };
 import replTs from "../template/src/repl.ts.tpl" with { type: "text" };
@@ -79,12 +79,11 @@ export function renderApp(input: RenderInput): Map<string, string> {
     ["README.md", renderReadme(input.name, channels, auth, tools, directory)],
     ["docker-compose.yml", renderCompose(input.name, channels.some((c) => c.id === "http"))],
     ["markdown.d.ts", markdownDts],
-    ["mercury.config.ts", renderConfig(channels, auth, tools, directory)],
+    ["mercury.config.ts", renderConfig(assistantName, channels, auth, tools, directory)],
     ["package.json", renderPackageJson(input.name, channels, auth, tools, input.versions, directory)],
-    ["persona/identity.md", `You are ${assistantName}, ${input.role.trim().replace(/\.+$/, "")}.\n`],
-    // A replacer function, not a string: in a replacement string "$&" and the
-    // like are patterns, and the name must land verbatim.
-    ["persona/tone.md", `${DEFAULT_PERSONA_TONE.replaceAll("Mercury", () => assistantName)}\n`],
+    // The name is persona.name in the config; the persona files refer to it.
+    ["persona/identity.md", `You are {{assistant}}, ${input.role.trim().replace(/\.+$/, "")}.\n`],
+    ["persona/tone.md", `${DEFAULT_PERSONA_TONE}\n`],
     ["src/index.ts", indexTs],
     ["src/repl.ts", replTs],
     ["tsconfig.json", tsconfigJson],
@@ -115,6 +114,8 @@ function validate(input: RenderInput): void {
   if (/[\r\n]/.test(input.assistantName) || /[\r\n]/.test(input.role)) {
     throw new Error("The assistant name and role must each be one line");
   }
+  // What the app would refuse at startup.
+  assistantNameOf({ name: input.assistantName });
   const selection =
     selectionError(input.channels, input.plugins, input.auth, input.directory) ?? pairingError(input.channels, input.auth);
   if (selection !== undefined) {
@@ -164,6 +165,7 @@ function selected(kind: CatalogEntry["kind"], ids: string[]): CatalogEntry[] {
  * any, then the config with each plugin (wrapped in the formatter when it has
  * starting rules) and channel. */
 function renderConfig(
+  assistantName: string,
   channels: CatalogEntry[],
   auth: CatalogEntry | undefined,
   tools: CatalogEntry[],
@@ -197,7 +199,7 @@ function renderConfig(
     ...imports,
     "",
     `${helpers}export default defineMercuryConfig({`,
-    "  persona: { identity, tone },",
+    `  persona: { name: ${JSON.stringify(assistantName)}, identity, tone },`,
     plugins,
     channelList,
     ...(auth ? [`  auth: ${auth.exportName},`] : []),