@mnemom/mnemom 0.17.0-next.7 → 0.17.0-next.9

package/README.md

@@ -44,6 +44,32 @@ That's it. `mnemom init` detects your configured AI provider API keys (Anthropic
 | `mnemom card publish <file>`  | Publish alignment card from JSON file                |
 | `mnemom card validate <file>` | Validate card JSON locally                           |
 | `mnemom usage --org <id>`     | Show per-person token and request consumption        |
+| `mnemom agent [name]`         | Launch a governed coding agent through the gateway   |
+
+### `mnemom agent` — goal alignment
+
+`mnemom agent` launches your coding-agent CLI (Claude Code today) with its model traffic
+routed through the Mnemom gateway under a governed identity. Goal alignment — the judge
+nudging the agent back when it drifts from your goal — comes in three modes; a bare
+`mnemom agent` in a terminal asks which one you want (Enter = off, for now):
+
+| Mode         | How                                                                                                            | What is sent                                |
+| ------------ | -------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
+| **Implicit** | `--implicit` — the gateway infers the goal from your own messages and revises it as you steer; nothing to type | `x-mnemom-goal-mode: implicit`, no contract |
+| **Sealed**   | `--goal "<statement>"` (+ `--requirement/--allow/--forbid/--goal-id`) — sealed as a contract on the first turn | `x-mnemom-contract`                         |
+| **Off**      | neither                                                                                                        | neither header                              |
+
+`--implicit` cannot be combined with the sealed-contract flags: a sealed contract always
+wins on the gateway and would silently switch implicit mode off, so the launch refuses the
+mix. The guardrail ceilings (`--budget`, `--max-turns`, `--stall`, or `guardrails.*` in
+`~/.mnemom/launcher.toml`) apply in both modes — in implicit mode they ride on the mode
+header. In implicit mode the goal lags your steering by one request: a response to a new
+message carries `x-mnemom-goal-steer: queued` and the revision the agent acted under;
+the next request reads the new revision (`x-mnemom-goal-revision`).
+
+Make one mode the standing default with `mnemom agent config set goal_mode implicit`
+(or `off`); `--goal` still seals for that launch and `--no-implicit` turns it off for one
+launch. A sealed contract needs a per-launch statement, so it cannot be the default.
 
 ## How It Works
 

package/dist/commands/agent-config.d.ts

@@ -15,3 +15,15 @@
  */
 /** Entry point for `mnemom agent config <verb> [args...]`. Throws on misuse. */
 export declare function agentConfigCommand(argv: string[]): Promise<void>;
+/**
+ * `$VISUAL` / `$EDITOR` is a program plus optional plain flags (`code --wait`, `emacsclient -t`),
+ * never shell syntax: the value is split on whitespace and every token must be a bare
+ * program name, path, or flag. Anything else (quotes, `;`, `$(`, backticks, redirections, …) is
+ * refused with a remediation rather than handed to spawnSync — the editor is launched WITHOUT a
+ * shell, so such a value could only ever fail confusingly or, via a lookalike binary on PATH, run
+ * something the user did not mean. Exported for the tests.
+ */
+export declare function parseEditorSpec(spec: string): {
+    bin: string;
+    args: string[];
+};

package/dist/commands/agent-config.js

@@ -98,8 +98,8 @@ function editConfig() {
     // Seed a header-only file so $EDITOR opens something with guidance, not a blank.
     if (!existsSync(LAUNCHER_CONFIG_PATH))
         writeLauncherConfig(loadLauncherConfig());
-    const editor = process.env.VISUAL || process.env.EDITOR || fallbackEditor();
-    const res = spawnSync(editor, [LAUNCHER_CONFIG_PATH], { stdio: "inherit" });
+    const { bin: editor, args: editorArgs } = parseEditorSpec(process.env.VISUAL || process.env.EDITOR || fallbackEditor());
+    const res = spawnSync(editor, [...editorArgs, LAUNCHER_CONFIG_PATH], { stdio: "inherit" });
     if (res.error) {
         throw new Error(`mnemom agent config edit: could not launch editor '${editor}': ${res.error.message}\n` +
             `  Set $EDITOR, or edit ${LAUNCHER_CONFIG_PATH} directly.`);
@@ -108,6 +108,23 @@ function editConfig() {
     loadLauncherConfig();
     out(`Saved ${LAUNCHER_CONFIG_PATH}.`);
 }
+/**
+ * `$VISUAL` / `$EDITOR` is a program plus optional plain flags (`code --wait`, `emacsclient -t`),
+ * never shell syntax: the value is split on whitespace and every token must be a bare
+ * program name, path, or flag. Anything else (quotes, `;`, `$(`, backticks, redirections, …) is
+ * refused with a remediation rather than handed to spawnSync — the editor is launched WITHOUT a
+ * shell, so such a value could only ever fail confusingly or, via a lookalike binary on PATH, run
+ * something the user did not mean. Exported for the tests.
+ */
+export function parseEditorSpec(spec) {
+    const tokens = spec.trim().split(/\s+/).filter(Boolean);
+    const SAFE = /^[A-Za-z0-9_./+=:@,-]+$/;
+    if (tokens.length === 0 || !tokens.every((t) => SAFE.test(t))) {
+        throw new Error(`mnemom agent config edit: refusing to run $VISUAL/$EDITOR value '${spec}' — only a program name or path plus plain flags is accepted (no shell syntax).\n` +
+            `  Set $EDITOR to e.g. 'code --wait', or edit ${LAUNCHER_CONFIG_PATH} directly.`);
+    }
+    return { bin: tokens[0], args: tokens.slice(1) };
+}
 function fallbackEditor() {
     for (const cand of ["nano", "vim", "vi"]) {
         const r = spawnSync("sh", ["-c", `command -v "$1" >/dev/null 2>&1`, "sh", cand], {
@@ -158,6 +175,9 @@ function deleteKey(cfg, key) {
         case "effort":
             delete cfg.effort;
             break;
+        case "goal_mode":
+            delete cfg.goalMode;
+            break;
         case "cli":
             delete cfg.cli;
             break;

package/dist/commands/agent-session.d.ts

@@ -7,25 +7,35 @@
  *
  *   1. a SESSION NAME — labels the session in traces and the claude.ai session
  *      list (defaults to the current folder's name);
- *   2. an optional GOAL — one line. With a goal, Mnemom seals a goal contract
- *      for the session and the judge nudges the agent back when it drifts (a
- *      little µ per turn). Without one, the session runs governed but with goal
- *      alignment OFF: no contract header is sent, so the gateway's goal hook is
- *      simply not engaged for the conversation.
+ *   2. GOAL ALIGNMENT — one of three:
+ *      - INFER it from your messages (implicit mode): nothing to type; the
+ *        gateway reads your own messages, revises the goal as you steer, and the
+ *        judge nudges the agent back when it drifts (a little µ per new message
+ *        and per judged turn). Sends `x-mnemom-goal-mode: implicit`, no contract.
+ *      - TYPE a one-line goal: sealed as a contract for the session; the judge
+ *        nudges against it (a little µ per turn). Sends `x-mnemom-contract`.
+ *      - OFF: the session runs governed with goal alignment off — neither header
+ *        is sent, so the gateway's goal hooks are simply not engaged.
  *
  * Non-interactive runs (pipes, CI) never prompt — they get a clear error asking
- * for a name. `--goal` on the command line always wins over the prompt. Pure
- * apart from the injected `ask` functions, so every arm is unit-tested.
+ * for a name. `--goal` on the command line always wins over the prompt, and a
+ * resolved implicit launch (`--implicit`, or launcher.toml `goal_mode =
+ * "implicit"` with no `--no-implicit`) skips it too. Pure apart from the
+ * injected `ask` functions, so every arm is unit-tested.
  */
 export interface SessionAsk {
     askInput(question: string): Promise<string>;
     askYesNo(question: string, defaultYes: boolean): Promise<boolean>;
+    /** Numbered single-select; resolves the chosen label, or null on no/invalid choice. */
+    askSelect(question: string, options: string[]): Promise<string | null>;
 }
 export interface SessionSetupInput {
     /** The positional `[scenario]` (session name), if given. */
     scenario?: string;
     /** `--goal <statement>`, if given — skips the goal prompt. */
     goal?: string;
+    /** Resolved implicit mode (flag or config default) — skips the goal prompt; alignment on without a contract. */
+    implicit?: boolean;
     interactive: boolean;
     /** For the default session name (tests inject one). */
     cwd?: string;
@@ -34,17 +44,23 @@ export interface SessionSetupInput {
 }
 export interface SessionSetup {
     scenario: string;
-    /** The goal statement to seal, or undefined = goal alignment off. */
+    /** The goal statement to seal, or undefined = no sealed contract (implicit or off). */
     goal?: string;
-    goalAlignment: "on" | "off";
+    goalAlignment: "on" | "implicit" | "off";
     /** True when the terminal prompts ran. */
     prompted: boolean;
 }
 export declare const NO_SESSION_NAME_MESSAGE: string;
+/** The three goal-alignment choices offered by the interactive prompt (labels are the select options). */
+export declare const GOAL_CHOICE_IMPLICIT = "Infer my goal from my messages \u2014 nothing to type; revised as I steer (implicit mode)";
+export declare const GOAL_CHOICE_TYPED = "Type a one-line goal \u2014 sealed as a contract for this session";
+export declare const GOAL_CHOICE_OFF = "Off \u2014 run governed with goal alignment off (Enter)";
+export declare const GOAL_CHOICES: readonly string[];
+export declare const GOAL_CHOICE_QUESTION = "Goal alignment for this session?";
 /** Current folder name, sanitised like an agent slug; "session" when that is empty. */
 export declare function defaultSessionName(cwd?: string): string;
 /** The one-line status printed at launch so the customer always knows the mode. */
-export declare function goalAlignmentLine(on: boolean): string;
+export declare function goalAlignmentLine(mode: boolean | "on" | "implicit" | "off"): string;
 /**
  * Resolve the session name + goal for this launch. See the module doc for the
  * rules. Throws NO_SESSION_NAME_MESSAGE when no name was given and we cannot ask.

package/dist/commands/agent-session.js

@@ -7,29 +7,50 @@
  *
  *   1. a SESSION NAME — labels the session in traces and the claude.ai session
  *      list (defaults to the current folder's name);
- *   2. an optional GOAL — one line. With a goal, Mnemom seals a goal contract
- *      for the session and the judge nudges the agent back when it drifts (a
- *      little µ per turn). Without one, the session runs governed but with goal
- *      alignment OFF: no contract header is sent, so the gateway's goal hook is
- *      simply not engaged for the conversation.
+ *   2. GOAL ALIGNMENT — one of three:
+ *      - INFER it from your messages (implicit mode): nothing to type; the
+ *        gateway reads your own messages, revises the goal as you steer, and the
+ *        judge nudges the agent back when it drifts (a little µ per new message
+ *        and per judged turn). Sends `x-mnemom-goal-mode: implicit`, no contract.
+ *      - TYPE a one-line goal: sealed as a contract for the session; the judge
+ *        nudges against it (a little µ per turn). Sends `x-mnemom-contract`.
+ *      - OFF: the session runs governed with goal alignment off — neither header
+ *        is sent, so the gateway's goal hooks are simply not engaged.
  *
  * Non-interactive runs (pipes, CI) never prompt — they get a clear error asking
- * for a name. `--goal` on the command line always wins over the prompt. Pure
- * apart from the injected `ask` functions, so every arm is unit-tested.
+ * for a name. `--goal` on the command line always wins over the prompt, and a
+ * resolved implicit launch (`--implicit`, or launcher.toml `goal_mode =
+ * "implicit"` with no `--no-implicit`) skips it too. Pure apart from the
+ * injected `ask` functions, so every arm is unit-tested.
  */
 import { basename } from "node:path";
 import { sanitizeAgentName } from "../lib/agent.js";
 export const NO_SESSION_NAME_MESSAGE = "mnemom agent: a session name is required here (e.g. `mnemom agent onboarding`). " +
     "In a terminal, plain `mnemom agent` asks for one.";
+/** The three goal-alignment choices offered by the interactive prompt (labels are the select options). */
+export const GOAL_CHOICE_IMPLICIT = "Infer my goal from my messages — nothing to type; revised as I steer (implicit mode)";
+export const GOAL_CHOICE_TYPED = "Type a one-line goal — sealed as a contract for this session";
+export const GOAL_CHOICE_OFF = "Off — run governed with goal alignment off (Enter)";
+export const GOAL_CHOICES = [
+    GOAL_CHOICE_IMPLICIT,
+    GOAL_CHOICE_TYPED,
+    GOAL_CHOICE_OFF,
+];
+export const GOAL_CHOICE_QUESTION = "Goal alignment for this session?";
 /** Current folder name, sanitised like an agent slug; "session" when that is empty. */
 export function defaultSessionName(cwd = process.cwd()) {
     return sanitizeAgentName(basename(cwd)) || "session";
 }
 /** The one-line status printed at launch so the customer always knows the mode. */
-export function goalAlignmentLine(on) {
-    return on
+export function goalAlignmentLine(mode) {
+    const m = mode === true ? "on" : mode === false ? "off" : mode;
+    if (m === "implicit") {
+        return ("mnemom agent: goal alignment: on, implicit (no sealed contract — the gateway infers your goal " +
+            "from your own messages, revises it as you steer, and the judge nudges the agent back when it drifts)");
+    }
+    return m === "on"
         ? "mnemom agent: goal alignment: on (the judge nudges the agent back when it drifts from your goal)"
-        : "mnemom agent: goal alignment: off (no goal set — pass --goal or set one when prompted)";
+        : "mnemom agent: goal alignment: off (no goal set — pass --goal or --implicit, or set one when prompted)";
 }
 const defaultSay = (line = "") => console.error(line);
 /**
@@ -39,12 +60,13 @@ const defaultSay = (line = "") => console.error(line);
 export async function resolveSessionSetup(input, ask) {
     const say = input.say ?? defaultSay;
     const flagGoal = (input.goal ?? "").trim();
+    const implicit = input.implicit === true;
     const given = (input.scenario ?? "").trim();
     if (given) {
         return {
             scenario: given,
             goal: flagGoal || undefined,
-            goalAlignment: flagGoal ? "on" : "off",
+            goalAlignment: flagGoal ? "on" : implicit ? "implicit" : "off",
             prompted: false,
         };
     }
@@ -57,22 +79,36 @@ export async function resolveSessionSetup(input, ask) {
     say(`  (Next time you can pass it directly: mnemom agent <name>.)`);
     const typed = await ask.askInput(`Session name [${fallback}]:`);
     const scenario = sanitizeAgentName(typed.trim()) || fallback;
-    // ── 2. goal (skipped when --goal was given) ──
+    // ── 2. goal alignment (skipped when --goal or implicit mode was resolved) ──
     if (flagGoal) {
         return { scenario, goal: flagGoal, goalAlignment: "on", prompted: true };
     }
+    if (implicit) {
+        return { scenario, goalAlignment: "implicit", prompted: true };
+    }
     say();
-    say("Goal alignment — an optional one-line goal for this session.");
-    say("  With a goal, Mnemom's judge watches each turn and nudges the agent back when it drifts");
-    say("  (a little µ per turn). Without one, the session runs governed with goal alignment off.");
-    const wantsGoal = await ask.askYesNo("Set a goal for this session?", true);
-    if (!wantsGoal) {
-        return { scenario, goalAlignment: "off", prompted: true };
+    say("Goal alignment — how Mnemom keeps this session on track. Three choices:");
+    say("  Infer: nothing to type — the gateway reads your own messages, revises the goal as you");
+    say("    steer, and the judge nudges the agent back when it drifts (a little µ per message + turn).");
+    say("  Type a goal: one line, sealed as a contract; the judge nudges against it (a little µ per turn).");
+    say("  Off: the session runs governed with goal alignment off (the default — just press Enter).");
+    say("  (Make one the default: mnemom agent config set goal_mode implicit|off.)");
+    const choice = await ask.askSelect(GOAL_CHOICE_QUESTION, [...GOAL_CHOICES]);
+    if (choice === GOAL_CHOICE_IMPLICIT) {
+        return { scenario, goalAlignment: "implicit", prompted: true };
+    }
+    if (choice === GOAL_CHOICE_TYPED) {
+        const goal = (await ask.askInput("Goal (one line):")).trim();
+        if (!goal) {
+            say("  No goal entered — continuing with goal alignment off.");
+            return { scenario, goalAlignment: "off", prompted: true };
+        }
+        return { scenario, goal, goalAlignment: "on", prompted: true };
     }
-    const goal = (await ask.askInput("Goal (one line):")).trim();
-    if (!goal) {
-        say("  No goal entered — continuing with goal alignment off.");
-        return { scenario, goalAlignment: "off", prompted: true };
+    // Enter (no pick) and any invalid pick both resolve to null → off. Off is the
+    // deliberate default for now: a µ-costing mode is never picked by a bare Enter.
+    if (choice !== GOAL_CHOICE_OFF) {
+        say("  Goal alignment off (press 1 or 2 next time to turn it on).");
     }
-    return { scenario, goal, goalAlignment: "on", prompted: true };
+    return { scenario, goalAlignment: "off", prompted: true };
 }

package/dist/commands/agent-sessions.d.ts

@@ -0,0 +1,99 @@
+/**
+ * `mnemom agent sessions [--all] [--json]` and `mnemom agent show [ref] [--json]`
+ * — the read side of the local session ledger (`~/.mnemom/sessions.jsonl`, one
+ * line per real launch) merged with the gateway's live goal state for one
+ * session (`GET /v1/agent/sessions/{conversationId}` via mnemom-api).
+ *
+ * Pure apart from the injected deps (`readRecords`, `fetchSession`, `out`,
+ * `err`), so every arm is unit-tested; `liveSessionDeps` is the thin driver
+ * index.ts wires in.
+ *
+ * Hash note: the CLI's launch-time envelope sha will NOT equal the gateway's
+ * sealed hash in general (the gateway normalises absent arrays to `[]`), so the
+ * local sha is never printed as "the sealed hash" and no mismatch is flagged —
+ * only the server's hash is shown, labelled "sealed hash".
+ */
+import { type SessionRecord } from "../lib/agent-ledger.js";
+import { type AgentSessionResponse } from "../lib/api.js";
+export interface SessionCommandDeps {
+    /** The ledger, newest first. */
+    readRecords: () => SessionRecord[];
+    /** The live state from mnemom-api; rejects when unreachable / not found. */
+    fetchSession: (conversationId: string, agentId: string, orgId: string) => Promise<AgentSessionResponse>;
+    out: (line: string) => void;
+    err: (line: string) => void;
+}
+/** The production wiring (index.ts). Lazy so a test that mocks lib/api without
+ *  this export can still import index.ts. */
+export declare const liveSessionDeps: SessionCommandDeps;
+export declare const NO_SESSIONS_MESSAGE = "No sessions yet \u2014 run `mnemom agent` to start one.";
+export declare const DEFAULT_SESSIONS_LIMIT = 20;
+export interface SessionRefMatch {
+    record: SessionRecord;
+    /** Older records sharing the same session name (only for name matches). */
+    others: SessionRecord[];
+}
+export interface SessionRefAmbiguous {
+    record: null;
+    /** Every record whose conversation id starts with the ref. */
+    candidates: SessionRecord[];
+}
+/**
+ * Resolve `[ref]` against the ledger (newest first):
+ *   - no ref → the newest record;
+ *   - an exact session name → the newest record with that name, older ones in `others`;
+ *   - else a conversation-id prefix → the unique match, or `{record: null, candidates}`
+ *     when several share the prefix;
+ *   - nothing matches (or the ledger is empty) → null.
+ */
+export declare function resolveSessionRef(records: SessionRecord[], ref?: string): SessionRefMatch | SessionRefAmbiguous | null;
+/** Goal alignment as the ledger recorded it: a contract at launch ⇒ on. */
+export declare function localGoalFlag(record: SessionRecord): "on" | "off";
+/**
+ * Render the ledger as a table, newest first — the newest
+ * `DEFAULT_SESSIONS_LIMIT` rows unless `all`, with a footer naming the rest.
+ */
+export declare function formatSessionsTable(rows: SessionRecord[], opts: {
+    all?: boolean;
+}): string[];
+/** `turns 3/10 (crossed)` — value against its ceiling (none ⇒ just the value). */
+export declare function gauge(label: string, value: number, ceiling: number | null, fired: boolean | undefined): string;
+/**
+ * The human view for `mnemom agent show`: the local record, then the live
+ * gateway state (or a dim "live state unavailable (<reason>)" line when
+ * `remote` is null).
+ */
+export declare function buildShowView(local: SessionRecord, remote: AgentSessionResponse | null, reason?: string): string[];
+/** The `--json` shape: the local record and the live section each tagged with its source. */
+export interface ShowJson {
+    session: SessionRecord & {
+        source: "local";
+    };
+    goal_alignment: "on" | "off";
+    live: {
+        source: "gateway";
+        available: true;
+        sealed: AgentSessionResponse["sealed"];
+        verdict: AgentSessionResponse["verdict"];
+        turn: AgentSessionResponse["turn"];
+        guardrails: AgentSessionResponse["guardrails"];
+    } | {
+        source: "gateway";
+        available: false;
+        reason: string;
+    };
+}
+export declare function buildShowJson(local: SessionRecord, remote: AgentSessionResponse | null, reason?: string): ShowJson;
+export interface AgentSessionsOptions {
+    all?: boolean;
+    json?: boolean;
+}
+/** `mnemom agent sessions [--all] [--json]` */
+export declare function agentSessionsCommand(opts: AgentSessionsOptions, deps: SessionCommandDeps): Promise<void>;
+export interface AgentShowOptions {
+    json?: boolean;
+}
+/** Why the live read could not happen, from the thrown error. */
+export declare function unavailableReason(err: unknown): string;
+/** `mnemom agent show [ref] [--json]` */
+export declare function agentShowCommand(ref: string | undefined, opts: AgentShowOptions, deps: SessionCommandDeps): Promise<void>;