@mnemom/mnemom 0.17.3-next.5 → 0.17.3

package/dist/lib/experimental.js

@@ -0,0 +1,226 @@
+/**
+ * Experimental features — the single registry and the pure logic around it.
+ *
+ * An experimental feature is OFF unless the user turns it on (`mnemom experimental
+ * enable <id>`, stored in ~/.mnemom/config.json `experimental.enabled`, or the
+ * MNEMOM_EXPERIMENTAL env var). While it is off its flags and commands are hidden
+ * from --help, using one fails with a pointer to `mnemom experimental enable`, and
+ * its launcher.toml keys are ignored with the same pointer. The contract: an
+ * experimental feature may change or be removed in any release, with no
+ * deprecation period.
+ *
+ * Everything here is pure or dependency-injected; index.ts and the command
+ * modules are the thin drivers.
+ */
+export const EXPERIMENTAL_FEATURES = [
+    {
+        id: "context-handoff",
+        summary: "Register the `handoff(note)` MCP tool and turn on the gateway's context-handoff capability for the session",
+        since: "0.17.3",
+        gates: {
+            flags: ["--context-handoff"],
+            configKeys: ["context_handoff"],
+            commands: [],
+            env: ["MNEMOM_AGENT_CONTEXT_HANDOFF"],
+        },
+    },
+    {
+        id: "slack",
+        summary: "Attach the Slack channel to a session: messages addressed to it arrive in it, and it can reply",
+        since: "0.17.3",
+        gates: {
+            flags: ["--slack"],
+            configKeys: ["slack_channel", "slack_listen", "slack_allow"],
+            commands: ["mnemom agent slack"],
+            env: [],
+        },
+    },
+    {
+        id: "implicit",
+        summary: "Implicit goal alignment: the gateway infers the goal from your messages and revises it as you steer",
+        since: "0.17.3",
+        gates: {
+            flags: ["--implicit"],
+            configKeys: ["goal_mode = implicit"],
+            commands: ["mnemom agent goal show|pin|reset"],
+            env: [],
+        },
+    },
+];
+export const EXPERIMENTAL_IDS = EXPERIMENTAL_FEATURES.map((f) => f.id);
+export const EXPERIMENTAL_ENV = "MNEMOM_EXPERIMENTAL";
+export const EXPERIMENTAL_CONTRACT = "Experimental features may change or be removed in any release, with no deprecation period.";
+export function isExperimentalId(value) {
+    return EXPERIMENTAL_IDS.includes(value);
+}
+/** Registry order, deduplicated, unknown ids dropped. */
+function normalize(ids) {
+    const set = new Set(ids);
+    return EXPERIMENTAL_IDS.filter((id) => set.has(id));
+}
+/**
+ * Which experimental features are on. Precedence: MNEMOM_EXPERIMENTAL (a comma
+ * list of ids, `all`, or `none`) replaces the stored set; else config.json
+ * `experimental.enabled`; else everything off.
+ */
+export function resolveExperimental(opts) {
+    const raw = (opts.env[EXPERIMENTAL_ENV] ?? "").trim();
+    if (raw !== "") {
+        const tokens = raw
+            .split(",")
+            .map((t) => t.trim().toLowerCase())
+            .filter(Boolean);
+        if (tokens.includes("all"))
+            return { enabled: [...EXPERIMENTAL_IDS], source: "env", unknown: [] };
+        const listed = tokens.filter((t) => t !== "none");
+        return {
+            enabled: normalize(listed),
+            source: "env",
+            unknown: listed.filter((t) => !isExperimentalId(t)),
+        };
+    }
+    const stored = Array.isArray(opts.stored?.enabled) ? opts.stored.enabled.map(String) : undefined;
+    if (stored === undefined)
+        return { enabled: [], source: "default", unknown: [] };
+    return {
+        enabled: normalize(stored),
+        source: "config",
+        unknown: stored.filter((t) => !isExperimentalId(t)),
+    };
+}
+/** The one-line stderr notice for a launch with experimental features on; null when none are. */
+export function experimentalNotice(enabled) {
+    if (enabled.length === 0)
+        return null;
+    return `mnemom agent: experimental: ${enabled.join(", ")} — may change or break without notice`;
+}
+/** The error for using an experimental flag or command while its feature is off. */
+export function gatedMessage(what, id) {
+    return `${what} is experimental. Turn it on with \`mnemom experimental enable ${id}\`.`;
+}
+/** Thrown when a gated flag or command is used while its feature is off; the CLI exits 2. */
+export class ExperimentalGateError extends Error {
+    exitCode = 2;
+    constructor(what, id) {
+        super(gatedMessage(what, id));
+        this.name = "ExperimentalGateError";
+    }
+}
+/** Throw for the first use whose feature is off. */
+export function assertEnabled(uses, enabled) {
+    for (const u of uses) {
+        if (u.used && !enabled.includes(u.id))
+            throw new ExperimentalGateError(u.what, u.id);
+    }
+}
+/**
+ * The feature a launcher.toml key/value belongs to, when setting it only has an
+ * effect with that feature on. `goal_mode = off`, `context_handoff = false` and
+ * `slack_listen = false` are harmless either way.
+ */
+export function experimentalIdForConfigKey(key, value) {
+    switch (key) {
+        case "slack_channel":
+        case "slack_allow":
+            return "slack";
+        case "slack_listen":
+            return value === "true" ? "slack" : undefined;
+        case "context_handoff":
+            return value === "true" ? "context-handoff" : undefined;
+        case "goal_mode":
+            return value === "implicit" ? "implicit" : undefined;
+        default:
+            return undefined;
+    }
+}
+/** Is an env value one of the truthy spellings resolveContextHandoff accepts? */
+function truthy(raw) {
+    return ["1", "true", "on", "yes"].includes((raw ?? "").trim().toLowerCase());
+}
+/**
+ * The stderr lines for experimental settings a launch ignores because their feature
+ * is off: launcher.toml keys (`entries` as `[key, value]`) and MNEMOM_AGENT_CONTEXT_HANDOFF.
+ */
+export function ignoredSettingLines(opts) {
+    const lines = [];
+    for (const [key, value] of opts.entries) {
+        const id = experimentalIdForConfigKey(key, value);
+        if (id && !opts.enabled.includes(id)) {
+            lines.push(`mnemom agent: ignoring launcher.toml ${gatedMessage(key, id)}`);
+        }
+    }
+    if (truthy(opts.env.MNEMOM_AGENT_CONTEXT_HANDOFF) && !opts.enabled.includes("context-handoff")) {
+        lines.push(`mnemom agent: ignoring ${gatedMessage("MNEMOM_AGENT_CONTEXT_HANDOFF", "context-handoff")}`);
+    }
+    return lines;
+}
+/** The features an existing launcher.toml already uses (the one-time migration). */
+export function featuresInUse(entries) {
+    return normalize(entries.flatMap(([k, v]) => {
+        const id = experimentalIdForConfigKey(k, v);
+        return id ? [id] : [];
+    }));
+}
+/** One-time notice for users who had implicit goal alignment by default (no goal_mode set). */
+export const IMPLICIT_NOW_OFF_NOTICE = "mnemom: implicit goal alignment is now experimental and OFF by default (it used to be on). " +
+    "Turn it back on with `mnemom experimental enable implicit`, or seal a goal per launch with --goal.\n";
+/**
+ * First run after the upgrade that introduced experimental features: config.json has
+ * no `experimental` section yet, so turn on whatever the user's launcher.toml already
+ * uses, persist (an empty list too — the section's presence marks the migration
+ * done), and say once which were kept on. A malformed launcher.toml skips the
+ * migration this run (the launch reports that file itself) so it retries next time.
+ * Never throws.
+ */
+export function migrateExperimental(deps) {
+    try {
+        if (deps.stored() !== undefined)
+            return null;
+        const entries = deps.launcherEntries();
+        const ids = featuresInUse(entries);
+        deps.persist(ids);
+        if (ids.length > 0) {
+            deps.writeErr(`mnemom: ${ids.join(", ")} ${ids.length === 1 ? "is" : "are"} now experimental and kept on because your launcher.toml uses ${ids.length === 1 ? "it" : "them"} — see \`mnemom experimental list\`.\n`);
+        }
+        // Implicit was the unconfigured DEFAULT, so most users relied on it without a
+        // goal_mode entry. Don't let it switch off silently for them: say so once.
+        const optedOut = entries.some(([k, v]) => k === "goal_mode" && v === "off");
+        if (!ids.includes("implicit") && !optedOut)
+            deps.writeErr(IMPLICIT_NOW_OFF_NOTICE);
+        return ids;
+    }
+    catch {
+        return null;
+    }
+}
+/** The feature a launcher.toml key belongs to at all (for marking `mnemom agent config list`). */
+export function configKeyFeature(key) {
+    if (key === "slack_channel" || key === "slack_listen" || key === "slack_allow")
+        return "slack";
+    if (key === "context_handoff")
+        return "context-handoff";
+    if (key === "goal_mode")
+        return "implicit";
+    return undefined;
+}
+/**
+ * ` (experimental, off)` for a launcher.toml key whose feature is off, else "". With a
+ * `value`, only a setting that would take effect is marked (`goal_mode = off` is not).
+ */
+export function configKeyMark(key, value, enabled) {
+    const id = value === undefined ? configKeyFeature(key) : experimentalIdForConfigKey(key, value);
+    return id && !enabled.includes(id) ? " (experimental, off)" : "";
+}
+/** `null` when `id` is on, else the gated-use message. */
+export function gateCheck(what, id, enabled) {
+    return enabled.includes(id) ? null : gatedMessage(what, id);
+}
+/**
+ * How a command's catch reports an error: a gated use prints its guidance bare and
+ * exits 2; anything else keeps the CLI's `Error: <message>` and exit 1.
+ */
+export function reportCliError(error) {
+    if (error instanceof ExperimentalGateError)
+        return { args: [error.message], code: 2 };
+    return { args: ["Error:", error instanceof Error ? error.message : error], code: 1 };
+}

package/dist/lib/launcher-config.d.ts

@@ -15,6 +15,7 @@
  * resolvers in lib/code.ts keep the built-in default as the final fallback);
  * the caller folds the plain-value settings under the CLI flags.
  */
+import type { ExperimentalId } from "./experimental.js";
 import { type ContextProfile, type GoalModeDefault, type LaunchShape } from "./agent.js";
 /** The human-editable settings file. Secret key lives elsewhere (launcher.json). */
 export declare const LAUNCHER_CONFIG_PATH: string;
@@ -98,3 +99,11 @@ export declare function writeLauncherConfig(cfg: LauncherConfig, path?: string):
  * (see resolveLaunchShape): terminal→"0", remote-control→"1", server→"server".
  */
 export declare function applyConfigToEnv(cfg: LauncherConfig, env?: NodeJS.ProcessEnv): void;
+/** The set keys of `cfg` as `[key, value]` pairs (CONFIG_KEYS order, values stringified). */
+export declare function launcherEntries(cfg: LauncherConfig): Array<[string, string]>;
+/**
+ * `cfg` without the settings of experimental features that are off (a copy; `cfg` is
+ * untouched): `slack_*` while `slack` is off, `context_handoff` while `context-handoff` is
+ * off, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ */
+export declare function withoutDisabledExperimental(cfg: LauncherConfig, enabled: readonly ExperimentalId[]): LauncherConfig;

package/dist/lib/launcher-config.js

@@ -86,7 +86,7 @@ function ensureGuardrails(cfg) {
 export const CONFIG_KEYS = [
     {
         key: "gateway",
-        describe: "Gateway host (default https://gateway.mnemom.ai — the us-2/prod cell)",
+        describe: "Gateway host (default: the gateway of the cell the CLI uses — prod unless MNEMOM_ENV/MNEMOM_RING/MNEMOM_GATEWAY_URL say otherwise; a different cell is refused)",
         get: (c) => c.gateway,
         set: (c, v) => {
             c.gateway = coerceNonEmpty("gateway", v);
@@ -402,3 +402,28 @@ export function applyConfigToEnv(cfg, env = process.env) {
         env.MNEMOM_AGENT_CONTEXT_PROFILE = cfg.contextProfile;
     }
 }
+/** The set keys of `cfg` as `[key, value]` pairs (CONFIG_KEYS order, values stringified). */
+export function launcherEntries(cfg) {
+    return CONFIG_KEYS.flatMap((spec) => {
+        const v = spec.get(cfg);
+        return v === undefined ? [] : [[spec.key, String(v)]];
+    });
+}
+/**
+ * `cfg` without the settings of experimental features that are off (a copy; `cfg` is
+ * untouched): `slack_*` while `slack` is off, `context_handoff` while `context-handoff` is
+ * off, and `goal_mode = implicit` while `implicit` is off (`goal_mode = off` is kept).
+ */
+export function withoutDisabledExperimental(cfg, enabled) {
+    const out = { ...cfg };
+    if (!enabled.includes("slack")) {
+        delete out.slackChannel;
+        delete out.slackListen;
+        delete out.slackAllow;
+    }
+    if (!enabled.includes("context-handoff"))
+        delete out.contextHandoff;
+    if (!enabled.includes("implicit") && out.goalMode === "implicit")
+        delete out.goalMode;
+    return out;
+}

package/dist/lib/slack-router.js

@@ -53,7 +53,9 @@ export function ensureRouter(argv = [process.execPath, process.argv[1] ?? "mnemo
 }
 /** Run the router until the process is killed. Reconnects on disconnect. */
 export async function runRouter(opts) {
-    const log = opts.log ?? ((l) => console.error(`[slack-router] ${l}`));
+    // Lines carry Slack-supplied values (channel, handles, disconnect reason);
+    // strip CR/LF so a crafted message cannot forge extra log lines.
+    const log = opts.log ?? ((l) => console.error(`[slack-router] ${l.replace(/\n|\r/g, "")}`));
     const fetchImpl = opts.fetchImpl ?? fetch;
     const WS = globalThis.WebSocket;
     if (!WS)

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mnemom/mnemom",
-  "version": "0.17.3-next.5",
+  "version": "0.17.3",
   "description": "Transparent AI agent tracing",
   "type": "module",
   "bin": {