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

package/dist/index.js

@@ -10,6 +10,7 @@ import { cardShowCommand, cardPublishCommand, cardValidateCommand, cardEditComma
 import { policyInitCommand, policyValidateCommand, policyPublishCommand, policyListCommand, policyTestCommand, policyEvaluateCommand, } from "./commands/policy.js";
 import { protectionShowCommand, protectionPublishCommand, protectionValidateCommand, protectionEditCommand, protectionDriftCommand, } from "./commands/protection.js";
 import { agentsListCommand, agentsClaimCommand, agentsMoveCommand } from "./commands/agents.js";
+import { agentSessionsCommand, agentShowCommand, liveSessionDeps, } from "./commands/agent-sessions.js";
 import { orgListCommand, orgShowCommand, orgUseCommand } from "./commands/org.js";
 import { teamListCommand, teamShowCommand, teamTemplateCommand, teamPreviewComposeCommand, teamAdminGrantCommand, teamAdminRevokeCommand, teamAdminListCommand, teamCoverageCommand, } from "./commands/team.js";
 import { advisoriesListCommand, advisoriesShowCommand } from "./commands/advisories.js";
@@ -26,6 +27,7 @@ import { agentDoctorCommand } from "./commands/agent-doctor.js";
 import { agentSetupCommand } from "./commands/agent-setup.js";
 import { agentInviteCommand, runAgentInvocation } from "./commands/agent-invite.js";
 import { applyConfigToEnv, loadLauncherConfig } from "./lib/launcher-config.js";
+import { resolveImplicit } from "./lib/agent.js";
 import { wrapCommand } from "./commands/wrap.js";
 import { onboardCommand } from "./commands/onboard.js";
 import { skillsListCommand, skillsDescribeCommand } from "./commands/skills.js";
@@ -102,7 +104,7 @@ const collectRepeatable = (value, previous) => {
 const agentCmd = program
     .command("agent [session] [passthrough...]")
     .description("Launch your governed agent (Claude Code in v1) through the Mnemom gateway — governed identity + optional sealed goal contract. Plain `mnemom agent` asks for a session name and an optional goal. " +
-    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `invite <token>` redeems a Mnemom Agent invitation; `list` / `claim` / `move` manage the agents in your orgs.")
+    "Sub-verbs: `setup` provisions your governed agent; `doctor` preflights prerequisites; `config …` manages persistent settings (~/.mnemom/launcher.toml); `invite <token>` redeems a Mnemom Agent invitation; `list` / `claim` / `move` manage the agents in your orgs; `sessions` lists your past launches and `show [ref]` merges one with its live goal state.")
     .option("--goal <statement>", "Contract goal statement (required if any contract flag is given)")
     .option("--requirement <text>", "Contract requirement (repeatable)", collectRepeatable, [])
     .option("--allow <glob>", "Allowed path/glob (repeatable)", collectRepeatable, [])
@@ -111,6 +113,8 @@ const agentCmd = program
     .option("--budget <usd>", "Guardrail: spend ceiling in USD (positive number)")
     .option("--max-turns <n>", "Guardrail: turn ceiling (positive integer)")
     .option("--stall <n>", "Guardrail: consecutive no-write turns (positive integer)")
+    .option("--implicit", "Goal alignment without a sealed contract: the gateway infers the goal from your messages and revises it as you steer (not combinable with --goal/--requirement/--allow/--forbid/--goal-id; the guardrail ceilings still apply)")
+    .option("--no-implicit", "Goal alignment off for this launch even when launcher.toml sets goal_mode = implicit")
     .option("--conversation-id <id>", "x-mnemom-conversation-id (default: auto-generated)")
     .option("--cli <name|path>", "Coding-agent CLI to launch: a name or full path (default: claude)")
     .option("--gateway <url>", "Gateway host override (default: https://gateway.mnemom.ai; or MNEMOM_AGENT_GATEWAY)")
@@ -174,10 +178,19 @@ const agentCmd = program
             return;
         }
         const numToStr = (n) => n === undefined ? undefined : String(n);
-        // Config guardrails apply only when a contract is actually intended (a
-        // --goal is present), so a saved ceiling never forces an unrequested
-        // contract (which would then demand --goal and fail the launch).
-        const contractIntended = Boolean(opts.goal && opts.goal.trim());
+        // Implicit mode: --implicit / --no-implicit win; a --goal statement seals
+        // (the standing config default never overrides it); else launcher.toml
+        // `goal_mode`; else off. Pure + unit-tested in lib/agent.ts.
+        const implicit = resolveImplicit({
+            goal: opts.goal,
+            implicit: opts.implicit,
+            configGoalMode: cfg.goalMode,
+        });
+        // Config guardrails apply only when goal alignment is actually intended (a
+        // --goal is present, or implicit mode — where they ride on the mode header),
+        // so a saved ceiling never forces an unrequested contract (which would
+        // then demand --goal and fail the launch).
+        const contractIntended = Boolean(opts.goal && opts.goal.trim()) || implicit;
         // The governed identity rides on the program-level `--agent` (which
         // shadows a subcommand `--agent` under commander@12 — the MNE-238 class),
         // exactly as status/logs/onboard read it.
@@ -188,6 +201,7 @@ const agentCmd = program
             allow: opts.allow,
             forbid: opts.forbid,
             goalId: opts.goalId,
+            implicit,
             budget: opts.budget ?? (contractIntended ? numToStr(cfg.guardrails?.budgetUsd) : undefined),
             maxTurns: opts.maxTurns ?? (contractIntended ? numToStr(cfg.guardrails?.maxTurns) : undefined),
             stall: opts.stall ?? (contractIntended ? numToStr(cfg.guardrails?.stallTurns) : undefined),
@@ -685,6 +699,34 @@ agentCmd
         process.exit(1);
     }
 });
+agentCmd
+    .command("sessions")
+    .description("List your Mnemom Agent sessions from the local ledger (~/.mnemom/sessions.jsonl), newest first — the last 20 unless --all")
+    .option("--all", "Every session, not just the newest 20")
+    .option("--json", "Output the rows as JSON instead of a table")
+    .action(async (opts) => {
+    try {
+        await agentSessionsCommand({ all: opts.all, json: opts.json }, liveSessionDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
+agentCmd
+    .command("show [ref]")
+    .description("Show one session — the local launch record merged with the gateway's live goal state (sealed contract, latest verdict, guardrails). " +
+    "`ref` is a session name (newest match wins) or a unique conversation-id prefix; omitted = the newest session")
+    .option("--json", "Output the merged view as JSON (each section tagged with its source)")
+    .action(async (ref, opts) => {
+    try {
+        await agentShowCommand(ref, { json: opts.json }, liveSessionDeps);
+    }
+    catch (error) {
+        console.error("Error:", error instanceof Error ? error.message : error);
+        process.exit(1);
+    }
+});
 // ============================================================================
 // Organization management (ADR-044, Piece 1 of T1-3.1)
 // ============================================================================

package/dist/lib/agent-ledger.d.ts

@@ -0,0 +1,91 @@
+/**
+ * The local session ledger for `mnemom agent` — `~/.mnemom/sessions.jsonl`, one
+ * JSON line per REAL launch (never `--dry-run`), newest last.
+ *
+ * Pure module: the directory, the clock and the pid are injected so the append
+ * and the read are unit-testable with a temp dir. The record is deliberately a
+ * closed shape — the Anthropic key, the custom-headers line and the child env
+ * are never part of it (see `SessionRecord`), so nothing secret can ride along.
+ *
+ * Writes are best-effort: `appendSessionRecord` never throws — a failure comes
+ * back as `{ ok: false, error }` and the caller decides how loudly to warn.
+ */
+import type { LaunchShape, SealedContract } from "./agent.js";
+/** The ledger's file name under MNEMOM_DIR. */
+export declare const LEDGER_FILE = "sessions.jsonl";
+/** The ledger keeps only the newest this-many launches. */
+export declare const LEDGER_CAP = 200;
+/** The sealed-contract fields the ledger keeps (no goal_id — the statement is the identity). */
+export interface SessionRecordContract {
+    statement: string;
+    requirements?: string[];
+    allowed_paths?: string[];
+    forbidden_paths?: string[];
+    max_turns?: number;
+    budget_usd?: number;
+    stall_turns?: number;
+}
+/** One launch, as written to the ledger. */
+export interface SessionRecord {
+    v: 1;
+    /** ISO-8601 UTC. */
+    started_at: string;
+    /** The session (scenario) name. */
+    session: string;
+    conversation_id: string;
+    /** The x-mnemom-agent slug the launch ran under. */
+    agent_slug: string;
+    /** The agent record id when it resolved at launch, else null. */
+    agent_id: string | null;
+    org_id: string;
+    org_label: string;
+    gateway_host: string;
+    launch_shape: LaunchShape;
+    model: string | null;
+    effort: string | null;
+    /** The coding-agent CLI's basename, e.g. "claude". */
+    cli: string;
+    contract: SessionRecordContract | null;
+}
+/** What the call site supplies — the ledger stamps `v` and `started_at`. */
+export type SessionRecordInput = Omit<SessionRecord, "v" | "started_at">;
+/** The injected environment of the ledger. */
+export interface LedgerDeps {
+    /** The directory holding the ledger (MNEMOM_DIR in production). */
+    dir: string;
+    /** The clock (stamps `started_at` and names the rewrite temp file). */
+    now: () => Date;
+    /** The writing process's pid (names the rewrite temp file). */
+    pid: number;
+}
+export type AppendResult = {
+    ok: true;
+    record: SessionRecord;
+    path: string;
+} | {
+    ok: false;
+    error: string;
+};
+/**
+ * Project a sealed contract onto the ledger's contract shape (drops `goal_id`,
+ * keeps only defined fields). `null` in, `null` out.
+ */
+export declare function toLedgerContract(sealed: SealedContract | null): SessionRecordContract | null;
+/** The ledger's path under `dir`. */
+export declare function ledgerPath(dir: string): string;
+/**
+ * Append one launch to the ledger, atomically and capped:
+ *   - `dir` is created 0o700 when missing; the file is created 0o600;
+ *   - the new line is appended when the ledger stays within LEDGER_CAP lines,
+ *     otherwise the newest LEDGER_CAP lines (this one included) are rewritten
+ *     via a temp file + rename, so a reader never sees a torn file.
+ * Never throws — a failure is returned as `{ ok: false, error }`.
+ */
+export declare function appendSessionRecord(input: SessionRecordInput, deps: LedgerDeps): AppendResult;
+/**
+ * Read the ledger, oldest first (file order). A missing file is an empty
+ * ledger; a line that is not a v1 record object is skipped, never fatal.
+ */
+export declare function readSessionRecords(deps: Pick<LedgerDeps, "dir">): SessionRecord[];
+/** One ledger line → a record, or null when it is not a v1 record object. */
+export declare function parseRecord(line: string): SessionRecord | null;

package/dist/lib/agent-ledger.js

@@ -0,0 +1,126 @@
+/**
+ * The local session ledger for `mnemom agent` — `~/.mnemom/sessions.jsonl`, one
+ * JSON line per REAL launch (never `--dry-run`), newest last.
+ *
+ * Pure module: the directory, the clock and the pid are injected so the append
+ * and the read are unit-testable with a temp dir. The record is deliberately a
+ * closed shape — the Anthropic key, the custom-headers line and the child env
+ * are never part of it (see `SessionRecord`), so nothing secret can ride along.
+ *
+ * Writes are best-effort: `appendSessionRecord` never throws — a failure comes
+ * back as `{ ok: false, error }` and the caller decides how loudly to warn.
+ */
+import { appendFileSync, mkdirSync, readFileSync, renameSync, writeFileSync } from "node:fs";
+import { join } from "node:path";
+/** The ledger's file name under MNEMOM_DIR. */
+export const LEDGER_FILE = "sessions.jsonl";
+/** The ledger keeps only the newest this-many launches. */
+export const LEDGER_CAP = 200;
+/**
+ * Project a sealed contract onto the ledger's contract shape (drops `goal_id`,
+ * keeps only defined fields). `null` in, `null` out.
+ */
+export function toLedgerContract(sealed) {
+    if (!sealed)
+        return null;
+    const out = { statement: sealed.statement };
+    if (sealed.requirements !== undefined)
+        out.requirements = sealed.requirements;
+    if (sealed.allowed_paths !== undefined)
+        out.allowed_paths = sealed.allowed_paths;
+    if (sealed.forbidden_paths !== undefined)
+        out.forbidden_paths = sealed.forbidden_paths;
+    if (sealed.max_turns !== undefined)
+        out.max_turns = sealed.max_turns;
+    if (sealed.budget_usd !== undefined)
+        out.budget_usd = sealed.budget_usd;
+    if (sealed.stall_turns !== undefined)
+        out.stall_turns = sealed.stall_turns;
+    return out;
+}
+/** The ledger's path under `dir`. */
+export function ledgerPath(dir) {
+    return join(dir, LEDGER_FILE);
+}
+/**
+ * Read the ledger text, or null when the file does not exist. Read-and-catch
+ * rather than exists-then-read so there is no window in which the file can
+ * change between the check and the read (CodeQL js/file-system-race).
+ */
+function readLedgerText(path) {
+    try {
+        return readFileSync(path, "utf8");
+    }
+    catch (err) {
+        if (err.code === "ENOENT")
+            return null;
+        throw err;
+    }
+}
+/**
+ * Append one launch to the ledger, atomically and capped:
+ *   - `dir` is created 0o700 when missing; the file is created 0o600;
+ *   - the new line is appended when the ledger stays within LEDGER_CAP lines,
+ *     otherwise the newest LEDGER_CAP lines (this one included) are rewritten
+ *     via a temp file + rename, so a reader never sees a torn file.
+ * Never throws — a failure is returned as `{ ok: false, error }`.
+ */
+export function appendSessionRecord(input, deps) {
+    const path = ledgerPath(deps.dir);
+    try {
+        const record = { v: 1, started_at: deps.now().toISOString(), ...input };
+        mkdirSync(deps.dir, { recursive: true, mode: 0o700 });
+        const line = `${JSON.stringify(record)}\n`;
+        const text = readLedgerText(path);
+        const existing = text === null ? [] : nonEmptyLines(text);
+        if (existing.length + 1 > LEDGER_CAP) {
+            const kept = [...existing, JSON.stringify(record)].slice(-LEDGER_CAP);
+            const tmp = join(deps.dir, `.${LEDGER_FILE}.tmp-${deps.pid}-${deps.now().getTime()}`);
+            writeFileSync(tmp, `${kept.join("\n")}\n`, { mode: 0o600 });
+            renameSync(tmp, path);
+        }
+        else {
+            appendFileSync(path, line, { mode: 0o600 });
+        }
+        return { ok: true, record, path };
+    }
+    catch (err) {
+        return { ok: false, error: err instanceof Error ? err.message : String(err) };
+    }
+}
+/**
+ * Read the ledger, oldest first (file order). A missing file is an empty
+ * ledger; a line that is not a v1 record object is skipped, never fatal.
+ */
+export function readSessionRecords(deps) {
+    const path = ledgerPath(deps.dir);
+    const text = readLedgerText(path);
+    if (text === null)
+        return [];
+    const out = [];
+    for (const line of nonEmptyLines(text)) {
+        const parsed = parseRecord(line);
+        if (parsed)
+            out.push(parsed);
+    }
+    return out;
+}
+/** One ledger line → a record, or null when it is not a v1 record object. */
+export function parseRecord(line) {
+    let value;
+    try {
+        value = JSON.parse(line);
+    }
+    catch {
+        return null;
+    }
+    if (!value || typeof value !== "object" || Array.isArray(value))
+        return null;
+    const rec = value;
+    if (rec.v !== 1)
+        return null;
+    return rec;
+}
+function nonEmptyLines(text) {
+    return text.split("\n").filter((l) => l.trim().length > 0);
+}

package/dist/lib/agent.d.ts

@@ -48,6 +48,14 @@ export interface ContractFlags {
     maxTurns?: string | number;
     budget?: string | number;
     stall?: string | number;
+    /**
+     * `--implicit`: goal alignment WITHOUT a sealed contract. No `x-mnemom-contract`
+     * is sent; the gateway infers the goal from the user's own messages (revision 1
+     * after the first message) and revises it as the user steers. The guardrail
+     * ceilings still apply — they ride on the `x-mnemom-goal-mode` header instead
+     * of inside a contract. Cannot be combined with the sealed-contract flags.
+     */
+    implicit?: boolean;
 }
 /** The three launch shapes the command supports (see commands/code.ts). */
 export type LaunchShape = "terminal" | "remote-control" | "server";
@@ -116,6 +124,15 @@ export interface SealedContractEnvelope {
  * here matches whatever the gateway seals for the same flags.
  */
 export declare function assembleContract(flags: ContractFlags): SealedContractEnvelope | null;
+/** The request header that opts a conversation into implicit goal mode. */
+export declare const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
+/**
+ * The `x-mnemom-goal-mode` header value for `--implicit`, or null when the flag
+ * is absent: `implicit[; max_turns=N][; budget_usd=X][; stall_turns=N]` — the
+ * guardrail ceilings validated exactly as `assembleContract` validates them (a
+ * non-positive ceiling is refused, never silently dropped into an unguarded run).
+ */
+export declare function buildGoalModeHeader(flags: ContractFlags): string | null;
 /**
  * Resolve the launch shape from the flags and the `MNEMOM_AGENT_REMOTE_CONTROL`
  * env var (the flags win). Default is `terminal` — a plain governed launch in
@@ -142,7 +159,8 @@ export declare function launchPreferenceExplicit(opts: {
 /**
  * Build the `ANTHROPIC_CUSTOM_HEADERS` value for the terminal-only launch: the
  * real Anthropic key as `x-api-key`, plus the governed-identity headers and the
- * sealed contract when present. Newline-separated, exactly the wire shape Claude
+ * sealed contract when present (or the implicit goal-mode header when the launch
+ * is `--implicit` — never both). Newline-separated, exactly the wire shape Claude
  * Code sends to the /anthropic door. NB: the returned string contains the key —
  * callers must place it only in the child's env, never in a log line.
  */
@@ -151,4 +169,28 @@ export declare function buildCustomHeaders(opts: {
     agent: string;
     conversationId: string;
     contractB64?: string;
+    /** `buildGoalModeHeader` output for an `--implicit` launch. */
+    goalMode?: string;
 }): string;
+/**
+ * The persistable goal-alignment default (`launcher.toml` `goal_mode`). Only the
+ * two statement-free modes can be a standing default: a SEALED contract needs a
+ * per-session statement, so it is always a per-launch `--goal`.
+ */
+export type GoalModeDefault = "implicit" | "off";
+/**
+ * Is this launch implicit-mode? Precedence, highest wins:
+ *   1. an explicit flag — `--implicit` (true) or `--no-implicit` (false);
+ *   2. a `--goal` statement — a sealed contract is a per-launch choice that the
+ *      standing config default must never silently override;
+ *   3. the config default `goal_mode = "implicit"`;
+ *   4. off.
+ * Pure so every arm is unit-tested; the caller passes the resolved value on to
+ * `assembleContract` / `buildGoalModeHeader` (which still refuse `--implicit`
+ * combined with a contract flag — that conflict is EXPLICIT and is reported).
+ */
+export declare function resolveImplicit(opts: {
+    goal?: string;
+    implicit?: boolean;
+    configGoalMode?: GoalModeDefault;
+}): boolean;

package/dist/lib/agent.js

@@ -132,6 +132,12 @@ function hasText(v) {
  * here matches whatever the gateway seals for the same flags.
  */
 export function assembleContract(flags) {
+    // Implicit goal mode seals nothing: the ceilings ride on the mode header
+    // (`buildGoalModeHeader`), so a `--budget` alone must not demand `--goal` here.
+    if (flags.implicit) {
+        assertImplicitCompatible(flags);
+        return null;
+    }
     if (!contractFlagsPresent(flags))
         return null;
     const statement = (flags.goal ?? "").trim();
@@ -178,6 +184,58 @@ export function assembleContract(flags) {
         sha: sha256Hex16(canonical),
     };
 }
+/** The request header that opts a conversation into implicit goal mode. */
+export const GOAL_MODE_HEADER = "x-mnemom-goal-mode";
+const SEALED_ONLY_FLAGS = "--goal/--requirement/--allow/--forbid/--goal-id";
+/**
+ * `--implicit` and a sealed contract are mutually exclusive: on the gateway a
+ * sealed `x-mnemom-contract` always wins and would silently switch implicit mode
+ * off, so the launch refuses the combination rather than ship a header that does
+ * nothing.
+ */
+function assertImplicitCompatible(flags) {
+    const sealed = hasText(flags.goal) ||
+        (flags.requirement?.length ?? 0) > 0 ||
+        (flags.allow?.length ?? 0) > 0 ||
+        (flags.forbid?.length ?? 0) > 0 ||
+        hasText(flags.goalId);
+    if (sealed) {
+        throw new Error(`--implicit cannot be combined with ${SEALED_ONLY_FLAGS}: a sealed contract always wins on ` +
+            "the gateway and would silently switch implicit mode off. Drop --implicit to seal a " +
+            "contract, or drop the contract flags to let the gateway infer the goal from your messages.");
+    }
+}
+/**
+ * The `x-mnemom-goal-mode` header value for `--implicit`, or null when the flag
+ * is absent: `implicit[; max_turns=N][; budget_usd=X][; stall_turns=N]` — the
+ * guardrail ceilings validated exactly as `assembleContract` validates them (a
+ * non-positive ceiling is refused, never silently dropped into an unguarded run).
+ */
+export function buildGoalModeHeader(flags) {
+    if (!flags.implicit)
+        return null;
+    assertImplicitCompatible(flags);
+    const parts = ["implicit"];
+    if (flags.maxTurns !== undefined) {
+        if (!isPositiveInt(flags.maxTurns)) {
+            throw new Error(`--max-turns must be a positive integer (got '${flags.maxTurns}').`);
+        }
+        parts.push(`max_turns=${Number(flags.maxTurns)}`);
+    }
+    if (flags.budget !== undefined) {
+        if (!isPositiveNumber(flags.budget)) {
+            throw new Error(`--budget must be a positive USD amount (got '${flags.budget}').`);
+        }
+        parts.push(`budget_usd=${Number(flags.budget)}`);
+    }
+    if (flags.stall !== undefined) {
+        if (!isPositiveInt(flags.stall)) {
+            throw new Error(`--stall must be a positive integer (got '${flags.stall}').`);
+        }
+        parts.push(`stall_turns=${Number(flags.stall)}`);
+    }
+    return parts.join("; ");
+}
 /** Trim, drop empties — matches the gateway's `stringArray` filtering. */
 function cleanList(values) {
     return (values ?? []).map((v) => v.trim()).filter((v) => v.length > 0);
@@ -236,7 +294,8 @@ export function launchPreferenceExplicit(opts, env = process.env) {
 /**
  * Build the `ANTHROPIC_CUSTOM_HEADERS` value for the terminal-only launch: the
  * real Anthropic key as `x-api-key`, plus the governed-identity headers and the
- * sealed contract when present. Newline-separated, exactly the wire shape Claude
+ * sealed contract when present (or the implicit goal-mode header when the launch
+ * is `--implicit` — never both). Newline-separated, exactly the wire shape Claude
  * Code sends to the /anthropic door. NB: the returned string contains the key —
  * callers must place it only in the child's env, never in a log line.
  */
@@ -248,5 +307,25 @@ export function buildCustomHeaders(opts) {
     ];
     if (opts.contractB64)
         lines.push(`x-mnemom-contract: ${opts.contractB64}`);
+    if (opts.goalMode)
+        lines.push(`${GOAL_MODE_HEADER}: ${opts.goalMode}`);
     return lines.join("\n");
 }
+/**
+ * Is this launch implicit-mode? Precedence, highest wins:
+ *   1. an explicit flag — `--implicit` (true) or `--no-implicit` (false);
+ *   2. a `--goal` statement — a sealed contract is a per-launch choice that the
+ *      standing config default must never silently override;
+ *   3. the config default `goal_mode = "implicit"`;
+ *   4. off.
+ * Pure so every arm is unit-tested; the caller passes the resolved value on to
+ * `assembleContract` / `buildGoalModeHeader` (which still refuse `--implicit`
+ * combined with a contract flag — that conflict is EXPLICIT and is reported).
+ */
+export function resolveImplicit(opts) {
+    if (opts.implicit !== undefined)
+        return opts.implicit;
+    if (hasText(opts.goal))
+        return false;
+    return opts.configGoalMode === "implicit";
+}

package/dist/lib/api.d.ts

@@ -1219,6 +1219,68 @@ export declare const CODE_NOT_ENABLED = "code_not_enabled";
  * for membership/transport failures.
  */
 export declare function getCodeEntitlement(orgId?: string): Promise<CodeEntitlement>;
+/** The gateway's sealed contract for a conversation (absent arrays are `[]`). */
+export interface AgentSessionSealed {
+    contract: {
+        goal_id?: string;
+        statement: string;
+        requirements: string[];
+        allowed_paths: string[];
+        forbidden_paths: string[];
+        max_turns?: number;
+        budget_usd?: number;
+        stall_turns?: number;
+    };
+    /** The gateway's hash of the sealed contract — NOT the CLI's launch-time sha. */
+    hash: string;
+    sealed_at: string;
+}
+/** The latest goal-judge verdict stored for the conversation. */
+export interface AgentSessionVerdict {
+    turn: number;
+    verdict: "aligned" | "drifting" | "violation";
+    reason: string;
+    at: string;
+    streak_start?: number;
+}
+export interface AgentSessionGuardrails {
+    ceilings: {
+        /** null = inactive */
+        max_turns: number | null;
+        budget_usd: number | null;
+        stall_turns: number | null;
+    };
+    state: {
+        turns: number;
+        spend_usd: number;
+        stall_run: number;
+        fired: {
+            turns?: boolean;
+            budget?: boolean;
+            stall?: boolean;
+        };
+    } | null;
+}
+/** `GET /v1/agent/sessions/{conversationId}` 200 body. Nulls mean "nothing stored" — absence is data. */
+export interface AgentSessionResponse {
+    conversation_id: string;
+    agent: {
+        id: string;
+        name: string | null;
+    };
+    org_id: string;
+    sealed: AgentSessionSealed | null;
+    verdict: AgentSessionVerdict | null;
+    turn: number | null;
+    guardrails: AgentSessionGuardrails | null;
+}
+/**
+ * The live goal state of one `mnemom agent` session, read through mnemom-api
+ * (org-scoped; the api proxies the gateway's internal read). Non-OK responses
+ * keep the server's `code` + `details` (`agent_not_found`, `gateway_unavailable`)
+ * so `mnemom agent show` can name the reason.
+ */
+export declare function getAgentSession(conversationId: string, agentId: string, orgId: string): Promise<AgentSessionResponse>;
 /** `POST /v1/invites/accept` 200 body. Never carries an amount — only whether the
  *  starter grant fired or was deferred for a later backfill. */
 export interface AcceptProductInviteResult {

package/dist/lib/api.js

@@ -1538,6 +1538,17 @@ export async function getCodeEntitlement(orgId) {
     const q = orgId ? `?org_id=${encodeURIComponent(orgId)}` : "";
     return codeFetch(`/v1/code/entitlement${q}`, {}, "Could not check Mnemom Agent access");
 }
+/**
+ * The live goal state of one `mnemom agent` session, read through mnemom-api
+ * (org-scoped; the api proxies the gateway's internal read). Non-OK responses
+ * keep the server's `code` + `details` (`agent_not_found`, `gateway_unavailable`)
+ * so `mnemom agent show` can name the reason.
+ */
+export async function getAgentSession(conversationId, agentId, orgId) {
+    // `org_id` is the org the launch resolved (the ledger record's), so an agent that
+    // lives in a non-primary org resolves instead of 404ing against the caller's primary org.
+    return codeFetch(`/v1/agent/sessions/${encodeURIComponent(conversationId)}?agent_id=${encodeURIComponent(agentId)}&org_id=${encodeURIComponent(orgId)}`, {}, "Could not read the session's live state");
+}
 /** Redeem a `pinv_…` product invite (a Mnemom Agent invitation) for the signed-in user. */
 export async function acceptProductInvite(token) {
     return codeFetch("/v1/invites/accept", { method: "POST", body: JSON.stringify({ token }) }, "Could not redeem the invitation");

package/dist/lib/auth.js

@@ -117,7 +117,14 @@ export async function getAccessToken() {
     if (auth.expiresAt > now + 60) {
         return auth.accessToken;
     }
-    // Auto-refresh
+    // Auto-refresh. A *thrown* error from refreshStoredTokens() (transient
+    // exhaustion / non-revoke 4xx from oauthRefreshTokens(), MNE-7394) is
+    // intentionally allowed to propagate here rather than being coerced to the
+    // `null` re-login signal — a momentary AS outage must not masquerade as
+    // "credentials revoked". Only a genuine invalid_grant/invalid_client returns
+    // null (see refreshStoredTokens). Refining caller-side handling (distinguish
+    // propagate-vs-degrade) is tracked under MNE-7394's parent lane card
+    // (keith/oauth-token-lifetime).
     const refreshed = await refreshStoredTokens(auth);
     if (refreshed)
         return refreshed.accessToken;
@@ -139,6 +146,9 @@ export async function forceRefreshAccessToken() {
     const auth = getAuthInfo();
     if (!auth?.refreshToken)
         return null;
+    // As in getAccessToken, a thrown transient-exhaustion / non-revoke error from
+    // refreshStoredTokens() propagates rather than being coerced to null (MNE-7394;
+    // caller-side refinement tracked under keith/oauth-token-lifetime).
     const refreshed = await refreshStoredTokens(auth);
     return refreshed?.accessToken ?? null;
 }
@@ -226,6 +236,16 @@ export async function loginWithDeviceFlow() {
  * Refresh the stored tokens via the OAuth refresh_token grant. Requires both a
  * refresh token and the client_id they were issued to; returns null (rather
  * than throwing) when refresh isn't possible so callers degrade to re-login.
+ *
+ * Note: oauthRefreshTokens() returns null ONLY on a definitive revoke
+ * (invalid_grant/invalid_client) or missing credentials; on transient
+ * exhaustion (repeated 5xx / network faults) or any other non-revoke 4xx it
+ * *throws* (MNE-7394 / R6). That thrown error is intentionally allowed to
+ * propagate through this function to its callers rather than being coerced to
+ * null, so a momentary blip never presents as "credentials revoked". Refining
+ * the caller-side handling (propagate-vs-degrade in
+ * getAccessToken/forceRefreshAccessToken) is tracked under MNE-7394's parent
+ * lane card (keith/oauth-token-lifetime).
  */
 async function refreshStoredTokens(auth) {
     if (!auth.refreshToken || !auth.clientId)

package/dist/lib/format.d.ts

@@ -37,3 +37,9 @@ export declare const fmt: {
      */
     badge(text: string, color?: BadgeColor): string;
 };
+/**
+ * Human-friendly age of an ISO timestamp relative to now — "<1m ago", "42m ago",
+ * "3h 5m ago", "2d 4h ago"; a timestamp ahead of the clock reads "in the future?".
+ * Shared by `mnemom validate` and `mnemom agent sessions` / `show`.
+ */
+export declare function formatRelativeAge(startedAt: string): string;

package/dist/lib/format.js

@@ -64,3 +64,23 @@ export const fmt = {
         return colorFn(`[${text}]`);
     },
 };
+/**
+ * Human-friendly age of an ISO timestamp relative to now — "<1m ago", "42m ago",
+ * "3h 5m ago", "2d 4h ago"; a timestamp ahead of the clock reads "in the future?".
+ * Shared by `mnemom validate` and `mnemom agent sessions` / `show`.
+ */
+export function formatRelativeAge(startedAt) {
+    const ageMs = Date.now() - Date.parse(startedAt);
+    if (ageMs < 0)
+        return "in the future?";
+    const m = Math.floor(ageMs / 60_000);
+    if (m < 1)
+        return "<1m ago";
+    if (m < 60)
+        return `${m}m ago`;
+    const h = Math.floor(m / 60);
+    if (h < 24)
+        return `${h}h ${m % 60}m ago`;
+    const d = Math.floor(h / 24);
+    return `${d}d ${h % 24}h ago`;
+}