@mercury-fw/cli 0.70.0 → 0.72.0

package/CHANGELOG.md

@@ -1,5 +1,26 @@
 # @mercury-fw/cli
 
+## 0.72.0
+
+### Minor Changes
+
+- 468cb12: - `mfw create`: new apps declare `traces: { sink: jsonlTraces(), level: "meta" }` and depend on `@mercury-fw/trace-jsonl`
+  - **Migration:** to record traces, `bun add @mercury-fw/trace-jsonl` at the framework's version, add `import { jsonlTraces } from "@mercury-fw/trace-jsonl";` and `traces: { sink: jsonlTraces(), level: "meta" },` to `mercury.config.ts`, then in `src/index.ts` pass `tracer: app.tracer` to `loadChannels` and `await app.tracer.flush();` before `process.exit(0)` in `shutdown`
+
+### Patch Changes
+
+- Updated dependencies [468cb12]
+  - @mercury-fw/core@0.72.0
+  - @mercury-fw/utils@0.72.0
+
+## 0.71.0
+
+### Patch Changes
+
+- Updated dependencies [2b08f7e]
+  - @mercury-fw/core@0.71.0
+  - @mercury-fw/utils@0.71.0
+
 ## 0.70.0
 
 ### Patch Changes

package/README.md

@@ -53,7 +53,7 @@ Writes a new Mercury app into `<folder>`, which has to be missing or empty; the
 - 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).
 
-It writes the `mercury.config.ts` for that selection, the persona, a `locales/` folder with an `en.json` for the texts people see (empty, or the starting formatter rules' own texts: `app.jira.no-issues` with Jira), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the chosen pieces read. Its `package.json` declares `plugins/*` as workspaces, the place for the app's own plugins (each a package in `plugins/<name>`, which the image copies before installing), and a `test` script (`bun test`, the plugins' tests included); the workspaces make Bun install with its isolated linker, and the Dockerfile's PATH step follows the links it makes. A plugin that hands over lists comes wrapped in the formatter with a starting rule, yours to change.
+It writes the `mercury.config.ts` for that selection, the persona, the traces (`@mercury-fw/trace-jsonl`, at level `meta`, in `.mercury/traces/` on the vault's volume), a `locales/` folder with an `en.json` for the texts people see (empty, or the starting formatter rules' own texts: `app.jira.no-issues` with Jira), the service and REPL entrypoints, a Dockerfile, a compose file with Qdrant, and an env example listing every variable the chosen pieces read. Its `package.json` declares `plugins/*` as workspaces, the place for the app's own plugins (each a package in `plugins/<name>`, which the image copies before installing), and a `test` script (`bun test`, the plugins' tests included); the workspaces make Bun install with its isolated linker, and the Dockerfile's PATH step follows the links it makes. A plugin that hands over lists comes wrapped in the formatter with a starting rule, yours to change.
 
 Then it runs `bun install` in the app and creates a git repository on `main` with a first commit (`bun.lock` included), adding `origin` when you gave one; nothing is pushed. Each step is best effort and never undoes the ones before it: an install that fails still leaves the app committed, without the lockfile, and the closing message says what to run. The repository is skipped when the folder is already inside one (an app created in a monorepo belongs to it). Whether git can commit is git's call: when it refuses (no identity, a hook) or isn't installed, the message reports why and lists the commands to finish by hand. `bun install` prints its own output as it runs.
 

package/dist/src/render.d.ts

@@ -13,6 +13,8 @@ export type RenderInput = {
     directory?: string;
     versions: Record<string, string>;
 };
+/** The trace sink every new app declares, writing the traces to files on the vault's volume. */
+export declare const TRACE_SINK_PACKAGE = "@mercury-fw/trace-jsonl";
 /** Builds every file of the new app. Throws on an invalid app name, an empty
  * assistant name or role, an id the catalog doesn't have, or a package with no
  * version in `input.versions`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mercury-fw/cli",
-  "version": "0.70.0",
+  "version": "0.72.0",
   "type": "module",
   "license": "MIT",
   "repository": {
@@ -41,8 +41,8 @@
   "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.70.0",
-    "@mercury-fw/utils": "0.70.0",
+    "@mercury-fw/core": "0.72.0",
+    "@mercury-fw/utils": "0.72.0",
     "commander": "^15.0.0"
   },
   "devDependencies": {
@@ -51,7 +51,7 @@
     "@mercury-fw/channel-google-chat": "0.12.0",
     "@mercury-fw/channel-http": "0.16.0",
     "@mercury-fw/directory-static": "0.1.2",
-    "@mercury-fw/formatter": "0.70.0",
+    "@mercury-fw/formatter": "0.72.0",
     "@mercury-fw/plugin-atlassian-admin": "0.5.1",
     "@mercury-fw/plugin-bitbucket": "0.6.1",
     "@mercury-fw/plugin-confluence": "0.1.0",

package/src/render.ts

@@ -83,12 +83,24 @@ const CONFIG_HEADER = `/**
  * provider when a channel needs one, how the lists its plugins hand over read,
  * the assistant's persona and the languages it speaks (\`i18n\`: a file per
  * language in \`locales/\`, \`en.json\` overriding the English texts) and its version
- * (\`version\`, its \`package.json\`'s, shown on the HTTP channel's \`/version\`). The entrypoints
+ * (\`version\`, its \`package.json\`'s, shown on the HTTP channel's \`/version\`) and where
+ * the traces of what it does go (\`traces\`). The entrypoints
  * (\`src/index.ts\`, \`src/repl.ts\`) hand this config to \`composeMercury\`.
  *
  * Every tool plugin and channel declared here is active.
  */`;
 
+/** The trace sink every new app declares, writing the traces to files on the vault's volume. */
+export const TRACE_SINK_PACKAGE = "@mercury-fw/trace-jsonl";
+
+/** The config's `traces` entry, with what it records and where. */
+const TRACES_SECTION = [
+  "  // What the agent does, as events in .mercury/traces/ on the vault's volume:",
+  "  // a file per day, the last 7 days with activity kept. \"meta\" records names,",
+  "  // outcomes and times; \"args\" also what the tools were given. Remove to record nothing.",
+  '  traces: { sink: jsonlTraces(), level: "meta" },',
+].join("\n");
+
 /** Builds every file of the new app. Throws on an invalid app name, an empty
  * assistant name or role, an id the catalog doesn't have, or a package with no
  * version in `input.versions`. */
@@ -254,6 +266,7 @@ function renderConfig(
   for (const c of [...channels, ...(auth ? [auth] : []), ...(directory ? [directory] : [])]) {
     imports.push(`import { ${c.exportName} } from "${c.package}";`);
   }
+  imports.push(`import { jsonlTraces } from "${TRACE_SINK_PACKAGE}";`);
 
   const helpers = withRules.map((t) => `${t.formatter?.helpers}\n\n`).join("");
 
@@ -278,6 +291,7 @@ function renderConfig(
     ...(directory ? [`  directory: ${directory.exportName},`] : []),
     MODEL_SECTION,
     "  i18n: { locales: { en } },",
+    TRACES_SECTION,
     VERSION_COMMENT,
     "  version: pkg.version,",
     "});",
@@ -318,7 +332,7 @@ function renderPackageJson(
   directory: CatalogEntry | undefined,
 ): string {
   const chosen = [...channels, ...(auth ? [auth] : []), ...tools, ...(directory ? [directory] : [])];
-  const packages = [...new Set(["@mercury-fw/core", ...chosen.flatMap(entryPackages)])];
+  const packages = [...new Set(["@mercury-fw/core", TRACE_SINK_PACKAGE, ...chosen.flatMap(entryPackages)])];
   if (tools.some((t) => t.formatter)) {
     packages.push("@mercury-fw/formatter");
   }

package/src/versions.ts

@@ -7,7 +7,7 @@
 import pkg from "../package.json";
 
 /** The framework packages a new app can depend on: always at the CLI's version. */
-export const FRAMEWORK_PACKAGES = ["@mercury-fw/cli", "@mercury-fw/core", "@mercury-fw/formatter"];
+export const FRAMEWORK_PACKAGES = ["@mercury-fw/cli", "@mercury-fw/core", "@mercury-fw/formatter", "@mercury-fw/trace-jsonl"];
 
 /** The registry asked when `MFW_REGISTRY` doesn't name another. */
 export const DEFAULT_REGISTRY = "https://registry.npmjs.org";

package/template/src/index.ts.tpl

@@ -12,7 +12,7 @@ import mercuryConfig from "../mercury.config.ts";
 
 const app = await composeMercury(mercuryConfig);
 
-const loadedChannels: LoadedChannel[] = loadChannels(app.channels, { runtime: app.channelRuntime });
+const loadedChannels: LoadedChannel[] = loadChannels(app.channels, { runtime: app.channelRuntime, tracer: app.tracer });
 for (const { name, provider } of loadedChannels) {
   await provider.start(app.handleTurn);
   console.error(`[channel] ${name} started`);
@@ -34,6 +34,8 @@ async function shutdown(signal: string): Promise<void> {
     await provider.stop?.();
     console.error(`[shutdown] channel ${name} stopped`);
   }
+  // The last events written before the signal, stored before exiting.
+  await app.tracer.flush();
   process.exit(0);
 }
 process.on("SIGINT", () => void shutdown("SIGINT"));