@agentage/cli 0.32.0 → 0.34.0

package/README.md

@@ -94,6 +94,14 @@ too. Account-channel provisioning still needs an interactive `agentage setup` se
 - [`docs/reference.md`](docs/reference.md) - every command and flag, the full sync
   options, MCP details, and environment variables.
 
+## Telemetry (off by default)
+
+Nothing leaves your machine unless you ask for it. The CLI and its local helper ship with
+`@agentage/observability`, which stays inert until `OTEL_EXPORTER_OTLP_ENDPOINT` points at a
+collector you choose - then the CLI reports as `agentage-cli` and the helper as `agentage-daemon`
+(override with `OTEL_SERVICE_NAME`). Every line it writes goes to stderr, so `--json` output and the
+helper's MCP wire stay clean.
+
 ## Development
 
 ```bash

package/dist/cli.js

@@ -1,54 +1,15 @@
 #!/usr/bin/env node
-import chalk from 'chalk';
-import { Command } from 'commander';
-import { registerDaemon } from './commands/daemon/daemon-cmd.js';
-import { registerMemory } from './commands/memory/memory.js';
-import { registerSetup } from './commands/auth/setup.js';
-import { registerStatus } from './commands/status/status.js';
-import { registerUpdate } from './commands/update/update.js';
-import { registerVault } from './commands/vault/vault.js';
-import { disableDaemon } from './lib/daemon/daemon-pref.js';
-import { refreshUpdateCache, updateHint } from './lib/update/update-cache.js';
-import { VERSION } from './utils/version.js';
+// The bin is a loader, nothing else. @agentage/observability instruments node:http, fetch and MCP
+// tool registration through module hooks, and a hook only sees a module imported after it is
+// registered - so the bootstrap runs first and the program is imported dynamically behind it.
 // Dependency-free guard so the message survives even if deps fail to parse on old Node.
 const nodeMajor = Number(process.versions.node.split('.')[0]);
 if (nodeMajor < 22) {
     process.stderr.write(`agentage requires Node.js >= 22 (you have v${process.versions.node})\n`);
     process.exit(1);
 }
-const program = new Command();
-program
-    .name('agentage')
-    .description('The offline-first terminal client for agentage Memory')
-    .version(VERSION)
-    .option('--no-daemon', 'run memory verbs in-process instead of via the daemon');
-program.addHelpText('after', '\nNew here? Run: agentage vault add <name> --local, or agentage setup to connect an account.');
-program.hook('preAction', () => {
-    if (program.opts().daemon === false)
-        disableDaemon();
-});
-// After any command (except the update-aware ones, which report richer state themselves), print a
-// one-line hint from the cache, then kick a fire-and-forget refresh. Never awaited, never throws -
-// the command output is already done and the cache-only read keeps this instant. The hint is
-// suppressed under --json so it never corrupts machine-readable output.
-program.hook('postAction', (_thisCommand, actionCommand) => {
-    const name = actionCommand.name();
-    if (name === 'status' || name === 'update')
-        return;
-    if (!actionCommand.opts()['json']) {
-        const hint = updateHint();
-        if (hint)
-            console.error(chalk.dim(hint)); // stderr: never corrupt piped stdout
-    }
-    void refreshUpdateCache();
-});
-registerSetup(program);
-registerStatus(program);
-registerVault(program);
-registerMemory(program);
-registerDaemon(program);
-registerUpdate(program);
-program.parseAsync().catch((err) => {
-    console.error(err instanceof Error ? err.message : String(err));
-    process.exit(1);
-});
+const { CLI_SERVICE, startObservability } = await import('./observability.js');
+await startObservability(CLI_SERVICE);
+const { run } = await import('./program.js');
+await run();
+export {};

package/dist/daemon/entry.d.ts

@@ -0,0 +1,8 @@
+export declare const isEaddrinuse: (err: unknown) => boolean;
+export declare const createStateCleanup: (remove: () => void) => {
+    markOwned: () => void;
+    cleanup: () => void;
+};
+export declare const safeReschedule: (steps: Array<() => void>, onError: (msg: string) => void) => void;
+export declare const mcpEnabled: (env?: NodeJS.ProcessEnv) => boolean;
+export declare const boot: () => void;

package/dist/daemon/entry.js

@@ -0,0 +1,113 @@
+import { unwatchFile, watchFile } from 'node:fs';
+import { createClientProvider } from './client-provider.js';
+import { EADDRINUSE_EXIT_CODE, generateDaemonToken, removePidFile, removePortFile, removeTokenFile, resolvePort, writePidFile, writePortFile, writeTokenFile, } from './lifecycle.js';
+import { createDaemonServer } from './server.js';
+import { loadLocalMemoryServer } from '../mcp/local-server.js';
+import { vaultsJsonPath } from '../lib/vault/vaults.js';
+import { createDiscoverWatcher } from '../sync/discover/watcher.js';
+import { createSyncManager } from '../sync/git/manager.js';
+import { VERSION } from '../utils/version.js';
+export const isEaddrinuse = (err) => typeof err === 'object' && err !== null && err.code === 'EADDRINUSE';
+// Gate state-file cleanup on ownership: a loser of an autostart race must never wipe the winner's
+// pid/port/token files. Only the process that actually wrote them may remove them.
+export const createStateCleanup = (remove) => {
+    let owned = false;
+    return {
+        markOwned: () => {
+            owned = true;
+        },
+        cleanup: () => {
+            if (owned)
+                remove();
+        },
+    };
+};
+// Run each reschedule independently: a transiently-invalid config edit must not crash the daemon or
+// stop the others rescheduling; the throwing one keeps its last-good schedule.
+export const safeReschedule = (steps, onError) => {
+    for (const step of steps) {
+        try {
+            step();
+        }
+        catch (err) {
+            onError(err instanceof Error ? err.message : String(err));
+        }
+    }
+};
+// MCP is served at /mcp by default; AGENTAGE_DAEMON_NO_MCP=1 leaves buildMcpServer unset so the
+// endpoint 404s (the `daemon start --no-mcp` flag sets this on the spawned process).
+export const mcpEnabled = (env = process.env) => env['AGENTAGE_DAEMON_NO_MCP'] !== '1';
+// Unset/empty/invalid -> undefined (the watcher's defaults apply); the watcher floors low values.
+const envInt = (name) => {
+    const raw = process.env[name];
+    if (!raw)
+        return undefined;
+    const v = Number(raw);
+    return Number.isFinite(v) && v >= 0 ? v : undefined;
+};
+const state = createStateCleanup(() => {
+    removePidFile();
+    removePortFile();
+    removeTokenFile();
+});
+// The detached, long-lived engine host: one loopback HTTP server that owns a single in-process
+// engine and serialises every vault mutation, avoiding concurrent git index.lock collisions. It
+// runs the git sync loop and reschedules on config change.
+const main = async () => {
+    const port = resolvePort();
+    const authToken = generateDaemonToken();
+    const git = createSyncManager();
+    const discover = createDiscoverWatcher({
+        log: (msg) => console.log(`[discover] ${msg}`),
+        debounceMs: envInt('AGENTAGE_DISCOVER_DEBOUNCE_MS'),
+        pollMs: envInt('AGENTAGE_DISCOVER_POLL_MS'),
+    });
+    const server = createDaemonServer({
+        getClient: createClientProvider(),
+        buildMcpServer: mcpEnabled() ? loadLocalMemoryServer : undefined,
+        sync: {
+            status: () => ({ ...git.status(), discover: discover.status() }),
+            runNow: (vault) => git.runNow(vault),
+        },
+        authToken,
+        version: VERSION,
+    });
+    await server.start(port);
+    writePidFile(process.pid);
+    writePortFile(port);
+    writeTokenFile(authToken);
+    state.markOwned();
+    const reschedule = () => safeReschedule([() => git.reschedule(), () => discover.reschedule()], (msg) => console.error(`[daemon] reschedule failed: ${msg}`));
+    reschedule();
+    const configPath = vaultsJsonPath();
+    watchFile(configPath, { interval: 2000 }, reschedule);
+    const shutdown = () => {
+        unwatchFile(configPath);
+        git.stop();
+        discover.stop();
+        server.stop().finally(() => {
+            state.cleanup();
+            process.exit(0);
+        });
+    };
+    process.on('SIGTERM', shutdown);
+    process.on('SIGINT', shutdown);
+};
+// Boot the real daemon. Invoked by the bin (src/daemon-entry.ts) once the observability bootstrap
+// has run; importing this module for tests must never start a server.
+export const boot = () => {
+    process.on('uncaughtException', (err) => {
+        console.error(`[daemon] uncaught: ${err instanceof Error ? err.message : String(err)}`);
+        state.cleanup();
+        process.exit(1);
+    });
+    main().catch((err) => {
+        if (isEaddrinuse(err)) {
+            // Another daemon owns the port + our state files: exit distinctly, touch nothing.
+            process.exit(EADDRINUSE_EXIT_CODE);
+        }
+        console.error(err instanceof Error ? err.message : String(err));
+        state.cleanup();
+        process.exit(1);
+    });
+};

package/dist/daemon-entry.d.ts

@@ -1,7 +1 @@
-export declare const isEaddrinuse: (err: unknown) => boolean;
-export declare const createStateCleanup: (remove: () => void) => {
-    markOwned: () => void;
-    cleanup: () => void;
-};
-export declare const safeReschedule: (steps: Array<() => void>, onError: (msg: string) => void) => void;
-export declare const mcpEnabled: (env?: NodeJS.ProcessEnv) => boolean;
+export {};

package/dist/daemon-entry.js

@@ -1,118 +1,9 @@
-import { unwatchFile, watchFile } from 'node:fs';
-import { fileURLToPath } from 'node:url';
-import { createClientProvider } from './daemon/client-provider.js';
-import { EADDRINUSE_EXIT_CODE, generateDaemonToken, removePidFile, removePortFile, removeTokenFile, resolvePort, writePidFile, writePortFile, writeTokenFile, } from './daemon/lifecycle.js';
-import { createDaemonServer } from './daemon/server.js';
-import { loadLocalMemoryServer } from './mcp/local-server.js';
-import { vaultsJsonPath } from './lib/vault/vaults.js';
-import { createDiscoverWatcher } from './sync/discover/watcher.js';
-import { createSyncManager } from './sync/git/manager.js';
-import { VERSION } from './utils/version.js';
-export const isEaddrinuse = (err) => typeof err === 'object' && err !== null && err.code === 'EADDRINUSE';
-// Gate state-file cleanup on ownership: a loser of an autostart race must never wipe the winner's
-// pid/port/token files. Only the process that actually wrote them may remove them.
-export const createStateCleanup = (remove) => {
-    let owned = false;
-    return {
-        markOwned: () => {
-            owned = true;
-        },
-        cleanup: () => {
-            if (owned)
-                remove();
-        },
-    };
-};
-// Run each reschedule independently: a transiently-invalid config edit must not crash the daemon or
-// stop the others rescheduling; the throwing one keeps its last-good schedule.
-export const safeReschedule = (steps, onError) => {
-    for (const step of steps) {
-        try {
-            step();
-        }
-        catch (err) {
-            onError(err instanceof Error ? err.message : String(err));
-        }
-    }
-};
-// MCP is served at /mcp by default; AGENTAGE_DAEMON_NO_MCP=1 leaves buildMcpServer unset so the
-// endpoint 404s (the `daemon start --no-mcp` flag sets this on the spawned process).
-export const mcpEnabled = (env = process.env) => env['AGENTAGE_DAEMON_NO_MCP'] !== '1';
-// Unset/empty/invalid -> undefined (the watcher's defaults apply); the watcher floors low values.
-const envInt = (name) => {
-    const raw = process.env[name];
-    if (!raw)
-        return undefined;
-    const v = Number(raw);
-    return Number.isFinite(v) && v >= 0 ? v : undefined;
-};
-const state = createStateCleanup(() => {
-    removePidFile();
-    removePortFile();
-    removeTokenFile();
-});
-// The detached, long-lived engine host: one loopback HTTP server that owns a single in-process
-// engine and serialises every vault mutation, avoiding concurrent git index.lock collisions. It
-// runs the git sync loop and reschedules on config change.
-const main = async () => {
-    const port = resolvePort();
-    const authToken = generateDaemonToken();
-    const git = createSyncManager();
-    const discover = createDiscoverWatcher({
-        log: (msg) => console.log(`[discover] ${msg}`),
-        debounceMs: envInt('AGENTAGE_DISCOVER_DEBOUNCE_MS'),
-        pollMs: envInt('AGENTAGE_DISCOVER_POLL_MS'),
-    });
-    const server = createDaemonServer({
-        getClient: createClientProvider(),
-        buildMcpServer: mcpEnabled() ? loadLocalMemoryServer : undefined,
-        sync: {
-            status: () => ({ ...git.status(), discover: discover.status() }),
-            runNow: (vault) => git.runNow(vault),
-        },
-        authToken,
-        version: VERSION,
-    });
-    await server.start(port);
-    writePidFile(process.pid);
-    writePortFile(port);
-    writeTokenFile(authToken);
-    state.markOwned();
-    const reschedule = () => safeReschedule([() => git.reschedule(), () => discover.reschedule()], (msg) => console.error(`[daemon] reschedule failed: ${msg}`));
-    reschedule();
-    const configPath = vaultsJsonPath();
-    watchFile(configPath, { interval: 2000 }, reschedule);
-    const shutdown = () => {
-        unwatchFile(configPath);
-        git.stop();
-        discover.stop();
-        server.stop().finally(() => {
-            state.cleanup();
-            process.exit(0);
-        });
-    };
-    process.on('SIGTERM', shutdown);
-    process.on('SIGINT', shutdown);
-};
-// Only self-invoke when run directly (spawnDaemon's `node daemon-entry.js`); importing for tests
-// must not boot a daemon.
-const invokedDirectly = () => {
-    const entry = process.argv[1];
-    return !!entry && fileURLToPath(import.meta.url) === entry;
-};
-if (invokedDirectly()) {
-    process.on('uncaughtException', (err) => {
-        console.error(`[daemon] uncaught: ${err instanceof Error ? err.message : String(err)}`);
-        state.cleanup();
-        process.exit(1);
-    });
-    main().catch((err) => {
-        if (isEaddrinuse(err)) {
-            // Another daemon owns the port + our state files: exit distinctly, touch nothing.
-            process.exit(EADDRINUSE_EXIT_CODE);
-        }
-        console.error(err instanceof Error ? err.message : String(err));
-        state.cleanup();
-        process.exit(1);
-    });
-}
+// The daemon's bin, a loader and nothing else: @agentage/observability instruments node:http and
+// MCP tool registration through module hooks that only see modules imported after they register, so
+// the bootstrap runs before the daemon itself is loaded. The path stays src/daemon-entry.ts because
+// spawnDaemon resolves dist/daemon-entry.js.
+const { DAEMON_SERVICE, startObservability } = await import('./observability.js');
+await startObservability(DAEMON_SERVICE);
+const { boot } = await import('./daemon/entry.js');
+boot();
+export {};

package/dist/lib/daemon/daemon-client.js

@@ -2,6 +2,7 @@ import { spawn as spawnChild } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import chalk from 'chalk';
 import { EADDRINUSE_EXIT_CODE, readDaemonToken, resolvePort } from '../../daemon/lifecycle.js';
+import { daemonServiceName } from '../../observability.js';
 import { VERSION } from '../../utils/version.js';
 const base = (port) => `http://127.0.0.1:${port}`;
 // The 0600 token file is the daemon's auth: read it fresh per call so a restart's new token is
@@ -97,6 +98,8 @@ export const spawnDaemon = async (port, opts = {}) => {
             env: {
                 ...process.env,
                 AGENTAGE_DAEMON_PORT: String(port),
+                // Its own service in telemetry: never inherit the name we defaulted into the CLI's env.
+                OTEL_SERVICE_NAME: daemonServiceName(),
                 ...(opts.noMcp ? { AGENTAGE_DAEMON_NO_MCP: '1' } : {}),
             },
         });

package/dist/observability.d.ts

@@ -0,0 +1,4 @@
+export declare const CLI_SERVICE = "agentage-cli";
+export declare const DAEMON_SERVICE = "agentage-daemon";
+export declare const daemonServiceName: () => string;
+export declare const startObservability: (service: string) => Promise<void>;

package/dist/observability.js

@@ -0,0 +1,35 @@
+// Telemetry for the CLI and its daemon, through @agentage/observability. A real dependency here
+// (unlike @agentage/server-memory, which must stay npx-light): `agentage` is installed once,
+// globally. It is inert until OTEL_EXPORTER_OTLP_ENDPOINT names a collector, and every line it
+// writes goes to stderr - stdout stays the machine-readable channel (`--json`, the daemon's
+// JSON-RPC wire).
+// Captured before startObservability() can overwrite it, so the daemon we spawn can tell a name the
+// user chose from the default we injected.
+const userServiceName = process.env['OTEL_SERVICE_NAME'];
+export const CLI_SERVICE = 'agentage-cli';
+export const DAEMON_SERVICE = 'agentage-daemon';
+// What OTEL_SERVICE_NAME the spawned daemon should run under: the user's, else our own default.
+export const daemonServiceName = () => userServiceName || DAEMON_SERVICE;
+// Guarded even though the kit is a dependency: a half-installed global must degrade to a working
+// CLI, never to a stack trace on every command.
+export const startObservability = async (service) => {
+    // The kit (1.0.0) announces an enabled tracer with one console.log, which would land in a
+    // `--json` payload or on the daemon's JSON-RPC wire. Divert stdout to stderr while it boots; drop
+    // this once the kit writes that line to stderr itself.
+    const stdoutWrite = process.stdout.write;
+    process.stdout.write = process.stderr.write.bind(process.stderr);
+    try {
+        if (!process.env['OTEL_SERVICE_NAME'])
+            process.env['OTEL_SERVICE_NAME'] = service;
+        await import('@agentage/observability/bootstrap');
+    }
+    catch (err) {
+        if (process.env['AGENTAGE_DEBUG']) {
+            const reason = err instanceof Error ? err.message : String(err);
+            console.error(`[agentage] observability off: ${reason}`); // stderr: never corrupt stdout
+        }
+    }
+    finally {
+        process.stdout.write = stdoutWrite;
+    }
+};

package/dist/program.d.ts

@@ -0,0 +1 @@
+export declare const run: () => Promise<void>;

package/dist/program.js

@@ -0,0 +1,50 @@
+import chalk from 'chalk';
+import { Command } from 'commander';
+import { registerDaemon } from './commands/daemon/daemon-cmd.js';
+import { registerMemory } from './commands/memory/memory.js';
+import { registerSetup } from './commands/auth/setup.js';
+import { registerStatus } from './commands/status/status.js';
+import { registerUpdate } from './commands/update/update.js';
+import { registerVault } from './commands/vault/vault.js';
+import { disableDaemon } from './lib/daemon/daemon-pref.js';
+import { refreshUpdateCache, updateHint } from './lib/update/update-cache.js';
+import { VERSION } from './utils/version.js';
+const program = new Command();
+program
+    .name('agentage')
+    .description('The offline-first terminal client for agentage Memory')
+    .version(VERSION)
+    .option('--no-daemon', 'run memory verbs in-process instead of via the daemon');
+program.addHelpText('after', '\nNew here? Run: agentage vault add <name> --local, or agentage setup to connect an account.');
+program.hook('preAction', () => {
+    if (program.opts().daemon === false)
+        disableDaemon();
+});
+// After any command (except the update-aware ones, which report richer state themselves), print a
+// one-line hint from the cache, then kick a fire-and-forget refresh. Never awaited, never throws -
+// the command output is already done and the cache-only read keeps this instant. The hint is
+// suppressed under --json so it never corrupts machine-readable output.
+program.hook('postAction', (_thisCommand, actionCommand) => {
+    const name = actionCommand.name();
+    if (name === 'status' || name === 'update')
+        return;
+    if (!actionCommand.opts()['json']) {
+        const hint = updateHint();
+        if (hint)
+            console.error(chalk.dim(hint)); // stderr: never corrupt piped stdout
+    }
+    void refreshUpdateCache();
+});
+registerSetup(program);
+registerStatus(program);
+registerVault(program);
+registerMemory(program);
+registerDaemon(program);
+registerUpdate(program);
+// Called by the bin (src/cli.ts) once the observability bootstrap has run.
+export const run = async () => {
+    await program.parseAsync().catch((err) => {
+        console.error(err instanceof Error ? err.message : String(err));
+        process.exit(1);
+    });
+};

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@agentage/cli",
-  "version": "0.32.0",
+  "version": "0.34.0",
   "description": "The agentage CLI - connect this machine to agentage from the terminal",
   "type": "module",
   "main": "./dist/index.js",
@@ -41,14 +41,16 @@
   },
   "dependencies": {
     "@agentage/memory-core": "^0.5.0",
-    "@agentage/server-memory": "^0.7.0",
+    "@agentage/observability": "^1.3.0",
+    "@agentage/server-memory": "^0.10.0",
     "@modelcontextprotocol/sdk": "^1.29.0",
+    "@opentelemetry/api": "^1.9.0",
     "chalk": "^6.0.0",
     "commander": "^15.0.0",
     "open": "^11.0.0"
   },
   "devDependencies": {
-    "@anthropic-ai/sdk": "0.124.0",
+    "@anthropic-ai/sdk": "0.129.0",
     "@playwright/test": "latest",
     "@types/node": "latest",
     "@typescript-eslint/eslint-plugin": "latest",