@mnemom/mnemom 0.17.33 → 0.17.34-next.2

package/dist/commands/durable-sessions.js

@@ -0,0 +1,303 @@
+/**
+ * `mnemom agent sessions` and `mnemom agent show <name>` with the `durable` gate on (BACKBONE C1;
+ * C01-R12, R24, R25, R27, R28; C11-R27): read from the server registry, never from the local
+ * ledger. With the gate off these are not reached and the ledger commands run exactly as today.
+ *
+ *   sessions  one row per session: name, user-facing state (of the EFFECTIVE state), agent,
+ *             machine, spend (guard_state.spend_usd to cents for locked rows, `-` for tracked) and
+ *             last activity; under a row, its fix line and the grant warning when they apply.
+ *   show      the S1 SHOW_KEYS sections in order (the --json keys are the same strings, same
+ *             order); keys that do not apply to a tracked session print NA_TEXT (null in --json).
+ *
+ * A registry that is absent for this caller (route 404, not entitled 403) falls back to the ledger
+ * command (`fallback`); an unreachable one refuses with session_registry_unavailable.
+ */
+import { APPROVALS_TEXT_M1, JOURNAL_TAIL_N, NA_TEXT, OUTAGE_TEXT_M1, SEAT_TEXT_M1, SHOW_KEYS, SHOW_KEYS_LOCKED_ONLY, STORAGE_TEXT_M1, } from "../vendor/shared/durable-contract/fixlines.js";
+import { RegistryAnswerError, RegistryUnavailable, } from "../lib/durable/api.js";
+import { DurableRefusal, printDurableRefusal } from "../lib/durable/refusal.js";
+import { effectiveOf, grantWarning, isEnded, isLocked, lastActivity, liveRow, machineText, reasonOf, rowFixLine, spendJson, spendText, stateLabel, userState, } from "../lib/durable/view.js";
+const registryDown = (detail) => new DurableRefusal({
+    code: "session_registry_unavailable",
+    message: `mnemom agent: the session registry is unreachable (${detail})`,
+    fix: null,
+});
+/** Rows from the registry, or "absent" (route 404 / not entitled 403). Down -> a refusal is thrown. */
+export async function readRows(api, filter) {
+    try {
+        return await api.listSessions(filter);
+    }
+    catch (e) {
+        if (e instanceof RegistryUnavailable)
+            throw registryDown(e.message);
+        if (e instanceof RegistryAnswerError) {
+            if (e.answer.status === 403 || e.answer.status === 404)
+                return "absent";
+            throw registryDown(`HTTP ${e.answer.status}`);
+        }
+        throw e;
+    }
+}
+/** Newest first by last activity (rows without one last, input order kept among equals). */
+export function newestFirst(rows) {
+    const t = (r) => {
+        const v = lastActivity(r);
+        const n = v ? Date.parse(v) : NaN;
+        return Number.isFinite(n) ? n : -Infinity;
+    };
+    return rows
+        .map((r, i) => ({ r, i }))
+        .sort((a, b) => t(b.r) - t(a.r) || a.i - b.i)
+        .map((x) => x.r);
+}
+const SESSIONS_DEFAULT_LIMIT = 20;
+/** One row's --json document and its fix / grant lines (the human table prints the same). */
+export function sessionJson(row, launcherKey, home) {
+    const nameHeld = !isEnded(row);
+    const machine = isLocked(row) ? machineText(row) : NA_TEXT;
+    return {
+        name: row.name ?? null,
+        conversation_id: row.conversation_id,
+        state: stateLabel(row),
+        internal_state: row.state,
+        effective_state: effectiveOf(row),
+        state_reason: reasonOf(row),
+        durable_mode: isLocked(row) ? "locked" : "tracked",
+        agent: row.agent_name ?? row.agent_id,
+        machine: machine === NA_TEXT ? null : machine,
+        spend: spendJson(row),
+        last_activity: lastActivity(row),
+        fix: rowFixLine(row, { launcherKey, nameHeld }, home),
+        grant_warning: isLocked(row) && !isEnded(row) ? grantWarning(row, home.nowMs) : null,
+    };
+}
+export async function durableSessionsCommand(opts, deps, fallback) {
+    let rows;
+    try {
+        rows = await readRows(deps.api, {});
+    }
+    catch (e) {
+        if (e instanceof DurableRefusal)
+            return printDurableRefusal(e, opts.json === true, deps);
+        throw e;
+    }
+    if (rows === "absent")
+        return fallback();
+    const shown = newestFirst(rows).slice(0, opts.all ? undefined : SESSIONS_DEFAULT_LIMIT);
+    const key = deps.launcherKey();
+    const home = await deps.home();
+    const docs = shown.map((r) => sessionJson(r, key, home));
+    if (opts.json) {
+        deps.out(JSON.stringify(docs, null, 2));
+        return 0;
+    }
+    if (docs.length === 0) {
+        deps.out("No sessions yet. Start one with `mnemom agent <name>`.");
+        return 0;
+    }
+    const header = ["NAME", "STATE", "AGENT", "MACHINE", "SPEND", "LAST ACTIVITY"];
+    const cells = shown.map((r, i) => {
+        const d = docs[i];
+        return [
+            d.name ?? d.conversation_id.slice(0, 8),
+            d.state,
+            d.agent,
+            d.machine ?? NA_TEXT,
+            spendText(r),
+            d.last_activity ?? NA_TEXT,
+        ];
+    });
+    const widths = header.map((h, c) => Math.max(h.length, ...cells.map((row) => (row[c] ?? "").length)));
+    const line = (vals) => vals
+        .map((v, c) => (c === vals.length - 1 ? v : v.padEnd(widths[c] ?? 0)))
+        .join("  ")
+        .trimEnd();
+    deps.out(line(header));
+    cells.forEach((row, i) => {
+        deps.out(line(row));
+        const d = docs[i];
+        if (d.fix)
+            deps.out(`  fix: ${d.fix}`);
+        if (d.grant_warning)
+            deps.out(`  ${d.grant_warning}`);
+    });
+    return 0;
+}
+const rec = (v) => v !== null && typeof v === "object" && !Array.isArray(v) ? v : {};
+const strOrNull = (v) => (typeof v === "string" && v !== "" ? v : null);
+const numOrNull = (v) => typeof v === "number" && Number.isFinite(v) ? v : null;
+/** The show document: SHOW_KEYS in order; locked-only keys are null on a tracked session. */
+export function showDocument(i) {
+    const { row } = i;
+    const d = i.detail ?? {};
+    const locked = isLocked(row);
+    const s = sessionJson(row, i.launcherKey, i.home);
+    const charter = rec(d.charter);
+    const guard = rec(row.guard_state ?? d.guard_state);
+    const goalSrc = rec(d.goal);
+    const journalSrc = Array.isArray(d.journal) ? d.journal : Array.isArray(d.events) ? d.events : [];
+    const doc = {
+        state: {
+            state: userState(row),
+            label: s.state,
+            internal_state: s.internal_state,
+            effective_state: s.effective_state,
+            state_reason: s.state_reason,
+            fix: s.fix,
+        },
+        machine: {
+            machine: s.machine,
+            executor_id: row.home_executor_id ?? row.home_executor?.id ?? null,
+            hostname: row.home_executor?.hostname ?? null,
+            grant_warning: s.grant_warning,
+        },
+        sharing: {
+            other_live_sessions: i.others === null ? null : i.others.map((o) => o.name ?? o.conversation_id),
+            durable_only: i.durableOnly === "protocol_error" ? null : i.durableOnly,
+            durable_only_error: i.durableOnly === "protocol_error" ? "protocol_error" : null,
+        },
+        goal: Object.keys(goalSrc).length === 0
+            ? null
+            : {
+                statement: strOrNull(goalSrc.statement),
+                requirements: Array.isArray(goalSrc.requirements) ? goalSrc.requirements : [],
+            },
+        rules: strOrNull(charter.profile ?? d.rules ?? d.profile),
+        pins: {
+            card_hash_prefix: strOrNull(charter.card_hash_prefix ?? d.card_hash_prefix),
+            policy_engine_major: numOrNull(charter.policy_engine_major ?? d.policy_engine_major),
+        },
+        limits: {
+            budget_usd: numOrNull(guard.budget_usd ?? row.budget_usd),
+            spend: s.spend,
+            max_turns: numOrNull(guard.max_turns ?? charter.max_turns),
+            max_duration_s: numOrNull(guard.max_duration_s ?? charter.max_duration_s),
+        },
+        approvals: APPROVALS_TEXT_M1,
+        outage: OUTAGE_TEXT_M1,
+        storage: STORAGE_TEXT_M1,
+        seat: SEAT_TEXT_M1,
+        journal: journalSrc.slice(-JOURNAL_TAIL_N).map((e) => {
+            const r = rec(e);
+            return { kind: strOrNull(r.kind ?? r.event), at: strOrNull(r.at ?? r.created_at) };
+        }),
+    };
+    if (!locked)
+        for (const k of SHOW_KEYS_LOCKED_ONLY)
+            doc[k] = null;
+    return doc;
+}
+/** The human lines of a show document, one section per SHOW_KEYS entry, in order. */
+export function showLines(name, doc) {
+    const lines = [name];
+    const put = (k, v) => {
+        lines.push(`  ${`${k}:`.padEnd(11)}${v}`);
+    };
+    for (const k of SHOW_KEYS) {
+        const v = doc[k];
+        if (v === null) {
+            put(k, NA_TEXT);
+            continue;
+        }
+        const r = rec(v);
+        switch (k) {
+            case "state": {
+                put(k, `${String(r.label)} (${String(r.internal_state)})`);
+                if (r.fix)
+                    lines.push(`             fix: ${String(r.fix)}`);
+                break;
+            }
+            case "machine":
+                put(k, String(r.machine ?? NA_TEXT));
+                if (r.grant_warning)
+                    lines.push(`             ${String(r.grant_warning)}`);
+                break;
+            case "sharing": {
+                // Only a list actually read is "no other live sessions"; an unread one is unknown.
+                const others = Array.isArray(r.other_live_sessions) ? r.other_live_sessions : null;
+                const only = r.durable_only === true
+                    ? "; agent is durable-only"
+                    : r.durable_only_error === "protocol_error"
+                        ? "; durable-only unknown (protocol error: the agent record has no agent_durable_only)"
+                        : "";
+                const live = others === null
+                    ? "other live sessions unknown (session registry unavailable)"
+                    : others.length === 0
+                        ? "no other live sessions"
+                        : others.join(", ");
+                put(k, `${live}${only}`);
+                break;
+            }
+            case "goal":
+                put(k, String(r.statement ?? NA_TEXT));
+                break;
+            case "pins":
+                put(k, `card ${String(r.card_hash_prefix ?? NA_TEXT)} · policy engine ${String(r.policy_engine_major ?? NA_TEXT)}`);
+                break;
+            case "limits":
+                put(k, `budget ${r.budget_usd ?? NA_TEXT} (spent ${String(r.spend ?? NA_TEXT)}) · max turns ${r.max_turns ?? NA_TEXT} · time ${r.max_duration_s ?? NA_TEXT}`);
+                break;
+            case "journal": {
+                const j = Array.isArray(v) ? v : [];
+                put(k, j.length === 0 ? NA_TEXT : `${j.length} recent`);
+                for (const e of j)
+                    lines.push(`             ${String(rec(e).at ?? "")} ${String(rec(e).kind ?? "")}`.trimEnd());
+                break;
+            }
+            default:
+                put(k, String(v));
+        }
+    }
+    return lines;
+}
+/** A 200 agent record's agent_durable_only: a boolean, or a protocol error when it is missing. */
+export function durableOnlyOf(body) {
+    const v = rec(rec(body).agent ?? body).agent_durable_only;
+    return typeof v === "boolean" ? v : "protocol_error";
+}
+export async function durableShowCommand(ref, opts, deps, fallback) {
+    // No ref, or a ref that names no registry session: the ledger show (a cid prefix, or the newest).
+    if (ref === undefined)
+        return fallback();
+    let rows;
+    try {
+        rows = await readRows(deps.api, { name: ref });
+    }
+    catch (e) {
+        if (e instanceof DurableRefusal)
+            return printDurableRefusal(e, opts.json === true, deps);
+        throw e;
+    }
+    if (rows === "absent")
+        return fallback();
+    const row = liveRow(rows) ?? newestFirst(rows)[0] ?? null;
+    if (row === null)
+        return fallback();
+    const [detail, siblings, durableOnly] = await Promise.all([
+        deps.api
+            .getSession(row.conversation_id, row.agent_id, "goal")
+            .then((a) => (a.status === 200 ? rec(rec(a.body).session ?? a.body) : null))
+            .catch(() => null),
+        readRows(deps.api, { agentId: row.agent_id }).catch(() => "absent"),
+        deps.api
+            .getAgent(row.agent_id)
+            .then((a) => (a.status === 200 ? durableOnlyOf(a.body) : null))
+            .catch(() => null),
+    ]);
+    const others = siblings === "absent"
+        ? null
+        : siblings.filter((o) => o.conversation_id !== row.conversation_id && !isEnded(o));
+    const doc = showDocument({
+        row,
+        detail,
+        others,
+        durableOnly,
+        launcherKey: deps.launcherKey(),
+        home: await deps.home(),
+    });
+    if (opts.json)
+        deps.out(JSON.stringify(doc, null, 2));
+    else
+        for (const l of showLines(row.name ?? ref, doc))
+            deps.out(l);
+    return 0;
+}

package/dist/commands/durable-verbs.d.ts

@@ -0,0 +1,116 @@
+/**
+ * The flat durable owner verbs (BACKBONE C1; S1 owner-verbs.ts, ROUTES.own_*; C11, C16):
+ *
+ *   mnemom agent pause|resume|done|kill <name> [--json]
+ *   mnemom agent amend <name> [--budget <n>] [--turns <n>] [--json]
+ *   mnemom agent sessions unlock <name>
+ *   mnemom agent containment pause|resume <agent>
+ *
+ * The API decides (S1 owner-verb table, first match wins); the CLI resolves the name through the
+ * registry, sends the verb, and renders the answer: a refusal with its S1 fix line and machine
+ * code, a 200 no-op with its state, a 202 device step (user_code + verification_uri_complete,
+ * polled at the server interval with the 202's device_code and client_id; never a token printed
+ * or kept), or the applied change. `done`/`kill` on a tracked session also stop the local tracked
+ * claude after the 200 (final F04; SIGTERM, SIGKILL after TRACKED_STOP_GRACE_S).
+ *
+ * Every dependency is injected (`DurableVerbDeps`), so each branch is unit-tested.
+ */
+import { type LauncherKey } from "../vendor/shared/durable-contract/fixlines.js";
+import type { RouteName } from "../vendor/shared/durable-contract/routes.js";
+import { type ApiAnswer, type RegistryRow } from "../lib/durable/api.js";
+import { DurableRefusal } from "../lib/durable/refusal.js";
+/** The slice of DurableApi the verbs use (a fake in tests). */
+export interface VerbApi {
+    listSessions(filter: {
+        name?: string;
+        agentId?: string;
+    }): Promise<RegistryRow[]>;
+    ownerVerb(route: RouteName, cid: string, agentId: string, body?: unknown): Promise<ApiAnswer>;
+    containment(orgId: string, agentId: string, verb: "pause" | "resume"): Promise<ApiAnswer>;
+    getAgent(agentId: string): Promise<ApiAnswer>;
+    /** Agents by name across the caller's orgs (the org fleet; JWT). */
+    agentsByName(name: string): Promise<Array<{
+        id: string;
+        org_id: string;
+    }>>;
+    devicePoll(deviceCode: string, clientId: string): Promise<ApiAnswer>;
+    credentialType(): Promise<"jwt" | "api-key" | "none">;
+}
+export interface DurableVerbDeps {
+    api: VerbApi;
+    launcherKey: () => LauncherKey;
+    out: (line: string) => void;
+    err: (line: string) => void;
+    sleep: (ms: number) => Promise<void>;
+    now: () => number;
+    /** Stop the local tracked claude of a session (done/kill on tracked, final F04). Absent: nothing to stop. */
+    stopTrackedClaude?: (row: RegistryRow, graceS: number) => Promise<void>;
+}
+export type OwnerVerbWord = "pause" | "resume" | "done" | "kill";
+/** The session a verb acts on: the non-terminal row holding the name, else the newest row. */
+export declare function resolveTarget(api: VerbApi, name: string): Promise<RegistryRow>;
+/**
+ * A refusal from an API answer: the API's message and code, its rendered fix (details.fix, as the
+ * API already applied the fix-line rule), else the CLI's catalogue fallback for that code.
+ */
+export declare function refusalFromAnswer(a: ApiAnswer, name: string, launcherKey: LauncherKey, row?: RegistryRow): DurableRefusal;
+/** The catalogue fix the CLI prints when the API body carries none. */
+export declare function fallbackFix(code: string, details: Record<string, unknown>, name: string, launcherKey: LauncherKey, row?: RegistryRow): string | null;
+/** The device-step fields of a 202 body (C16-R01). */
+export interface DeviceStep {
+    user_code: string;
+    verification_uri_complete: string;
+    device_code: string;
+    interval: number;
+    client_id: string;
+    approval_id?: string;
+}
+export declare function deviceStepOf(body: unknown): DeviceStep | null;
+/** How long the CLI keeps polling a device step before giving up (the approval TTL). */
+export declare const DEVICE_STEP_POLL_MAX_MS: number;
+/**
+ * Print the device step and poll until it resolves. 0 when applied; throws a DurableRefusal when
+ * denied, expired or refused. Never prints the device_code or any token.
+ */
+export declare function runDeviceStep(step: DeviceStep, note: string | null, deps: DurableVerbDeps): Promise<number>;
+/** Run one verb end to end and return its exit status (refusals rendered here). */
+export declare function runVerb(verb: OwnerVerbWord | "amend" | "unlock", name: string, body: Record<string, unknown>, opts: {
+    json?: boolean;
+}, deps: DurableVerbDeps): Promise<number>;
+/**
+ * Confirm an applied done / kill: the answer's own `{changed: true, state}` when it names the ended
+ * state, else one re-read of the session by conversation id. Throws a refusal (nothing stopped
+ * locally) when neither shows the session ended.
+ */
+export declare function confirmEnded(verb: "done" | "kill", row: RegistryRow, a: ApiAnswer, api: VerbApi, name: string): Promise<void>;
+export declare function handleVerbError(e: unknown, json: boolean, deps: DurableVerbDeps): number;
+/** Parse a positive amount (amend --budget); `integer` for a count (amend --turns). */
+export declare function parsePositive(flag: string, raw: string | undefined, integer?: boolean): number | undefined;
+export declare function amendCommand(name: string, opts: {
+    budget?: string;
+    turns?: string;
+    json?: boolean;
+}, deps: DurableVerbDeps): Promise<number>;
+export declare function unlockCommand(name: string, deps: DurableVerbDeps): Promise<number>;
+/**
+ * `mnemom agent containment pause|resume <agent>` (BACKBONE C1, amendment 35; C16-R30): a thin
+ * verb over POST /v1/orgs/{org}/agents/{id}/pause|resume. The org comes from the agent record,
+ * never the active org. It needs a session login: on an API-key-only credential, or the api's
+ * 403 org_scope_requires_session, it exits non-zero with the containment_login line and never
+ * sends the API key or prints the raw 403.
+ */
+export declare function containmentCommand(verb: "pause" | "resume", agentRef: string, deps: DurableVerbDeps): Promise<number>;
+/** An agent id as the CLI recognises one (lib/api.ts resolveAgentId). */
+export declare const AGENT_ID_RE: RegExp;
+/**
+ * The containment target and its org, from the agent record (never the active org): an id is read
+ * with GET /v1/agents/{id}; a name is looked up in the caller's org fleets and must match exactly one.
+ */
+export declare function resolveContainmentAgent(agentRef: string, deps: DurableVerbDeps, launcherKey: LauncherKey): Promise<{
+    orgId: string;
+    agentId: string;
+}>;
+/** The thin verbs (pause/resume/done/kill) with no body. */
+export declare function ownerVerbCommand(verb: OwnerVerbWord, name: string, opts: {
+    json?: boolean;
+}, deps: DurableVerbDeps): Promise<number>;