@mafdet/cli 0.4.1 → 0.4.2

package/dist/sessions/usage.js

@@ -0,0 +1,157 @@
+// CLI-025 · Adding up what a session used.
+//
+// This module does arithmetic and nothing else. In particular it never prices
+// anything: it sums the `estimated_charge_micro_usd` each request already
+// recorded, which the agent loop computed with the gateway's own arithmetic.
+// A second price implementation here would drift from the first one, and the
+// first one is the one that was reconciled against the ledger.
+//
+// The four states in §20.7 are the other half. `estimated` is what we worked
+// out locally; `settled` is what the server's ledger says; `pending` means the
+// answer exists but has not been fetched; `unknown` means we never got a
+// request id and so can never ask. They are counted separately because
+// collapsing them would let a display show an estimate as though it were the
+// final charge.
+const ZERO = {
+    modelRequests: 0,
+    promptTokens: 0,
+    completionTokens: 0,
+    estimatedMicroUsd: 0n,
+    settledMicroUsd: 0n,
+    bySettlement: { settled: 0, pending: 0, unknown: 0 },
+};
+/**
+ * A request with no id can never be reconciled, whatever it says.
+ *
+ * CLI-001 found that a cancelled or timed-out request may not return one, and
+ * calling such a request `pending` would promise an answer that will never
+ * arrive.
+ *
+ * Note what is *not* consulted: the `settlement_status` written on the usage
+ * line itself. That records what was known at the moment of the request, which
+ * is always "pending" - only a `settlement` event, appended by CLI-027 after
+ * the ledger was actually asked, can make a request settled.
+ */
+function statusOf(event, settled) {
+    if (typeof event.request_id !== "string" || event.request_id.length === 0) {
+        return "unknown";
+    }
+    return settled ? "settled" : "pending";
+}
+function add(base, event, settledMicro) {
+    const status = statusOf(event, settledMicro !== undefined);
+    return {
+        modelRequests: base.modelRequests + 1,
+        promptTokens: base.promptTokens + count(event.prompt_tokens),
+        completionTokens: base.completionTokens + count(event.completion_tokens),
+        estimatedMicroUsd: base.estimatedMicroUsd + micro(event.estimated_charge_micro_usd),
+        settledMicroUsd: status === "settled"
+            ? base.settledMicroUsd + (settledMicro ?? 0n)
+            : base.settledMicroUsd,
+        bySettlement: {
+            ...base.bySettlement,
+            [status]: base.bySettlement[status] + 1,
+        },
+    };
+}
+/**
+ * The settled amount per request id, from the `settlement` events.
+ *
+ * Read in a first pass because a settlement is appended long after the request
+ * it settles. Later wins: re-running `--refresh` after the ledger corrected a
+ * charge should show the correction, not the first answer we happened to get.
+ */
+function settlementsIn(events) {
+    const found = new Map();
+    for (const event of events) {
+        if (event.type !== "settlement")
+            continue;
+        const id = event.request_id;
+        if (typeof id !== "string" || id.length === 0)
+            continue;
+        found.set(id, micro(event.settled_charge_micro_usd));
+    }
+    return found;
+}
+function count(value) {
+    return typeof value === "number" && Number.isFinite(value) ? value : 0;
+}
+/** Money is integral end to end; a malformed figure counts as zero, not NaN. */
+function micro(value) {
+    if (typeof value !== "string" || !/^-?\d+$/.test(value))
+        return 0n;
+    return BigInt(value);
+}
+export function summariseUsage(events) {
+    let totals = ZERO;
+    const byModel = new Map();
+    const byKey = new Map();
+    const settlements = settlementsIn(events);
+    let userMessages = 0;
+    let toolRuns = 0;
+    let toolRunsRefused = 0;
+    let rateLimitHits = 0;
+    let rateLimitWaitMs = 0;
+    for (const event of events) {
+        if (event.type === "user_message") {
+            userMessages += 1;
+        }
+        else if (event.type === "tool_result") {
+            toolRuns += 1;
+            if (event.status === "refused")
+                toolRunsRefused += 1;
+        }
+        else if (event.type === "rate_limited") {
+            rateLimitHits += 1;
+            rateLimitWaitMs += count(event.wait_ms);
+        }
+        else if (event.type === "usage") {
+            const usage = event;
+            const settled = typeof usage.request_id === "string"
+                ? settlements.get(usage.request_id)
+                : undefined;
+            totals = add(totals, usage, settled);
+            const model = typeof usage.model_id === "string" ? usage.model_id : "(unknown model)";
+            byModel.set(model, add(byModel.get(model) ?? ZERO, usage, settled));
+            // Grouped only when the key is known: inventing a bucket for requests
+            // recorded before per-key attribution existed would misattribute them.
+            if (typeof usage.api_key_ref === "string" &&
+                usage.api_key_ref.length > 0) {
+                byKey.set(usage.api_key_ref, add(byKey.get(usage.api_key_ref) ?? ZERO, usage, settled));
+            }
+        }
+    }
+    return {
+        ...totals,
+        userMessages,
+        toolRuns,
+        toolRunsRefused,
+        rateLimitHits,
+        rateLimitWaitMs,
+        byModel: [...byModel.entries()]
+            .map(([modelId, t]) => ({ modelId, ...t }))
+            .sort((a, b) => b.modelRequests - a.modelRequests),
+        byKey: [...byKey.entries()]
+            .map(([apiKeyRef, t]) => ({ apiKeyRef, ...t }))
+            .sort((a, b) => b.modelRequests - a.modelRequests),
+    };
+}
+/**
+ * How to describe the settled column without overclaiming.
+ *
+ * Returns undefined when there is nothing honest to say, so a caller renders
+ * no figure rather than a zero - a zero reads as "it was free".
+ */
+export function settledCaveat(totals) {
+    const { settled, pending, unknown } = totals.bySettlement;
+    if (settled === 0 && pending === 0 && unknown === 0)
+        return undefined;
+    const parts = [];
+    if (pending > 0)
+        parts.push(`${pending} not settled yet`);
+    if (unknown > 0)
+        parts.push(`${unknown} with no request id, so unknowable`);
+    if (parts.length === 0)
+        return undefined;
+    return `${parts.join(", ")}; the estimate covers all ${totals.modelRequests}`;
+}

package/dist/tui/agent-surface.d.ts

@@ -1,5 +1,6 @@
 import { runSession, type SessionOptions, type SessionSummary } from "../agent/session.js";
 import { type TerminalCapabilities } from "./theme.js";
+import type { SessionRecorder } from "../sessions/recorder.js";
 import type { WidgetIo } from "./widgets.js";
 export interface AgentSurfaceOptions {
     readonly io: WidgetIo;
@@ -16,6 +17,8 @@ export interface AgentSurfaceOptions {
      * the signal to whatever controller existed at startup.
      */
     readonly getSignal?: () => AbortSignal | undefined;
+    /** Present when this run is being recorded; absent for --no-history. */
+    readonly recorder?: SessionRecorder;
     /** Injected by the tests; production uses runSession. */
     readonly run?: typeof runSession;
 }

package/dist/tui/agent-surface.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"agent-surface.d.ts","sourceRoot":"","sources":["../../src/tui/agent-surface.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,IAAI,CACpB,cAAc,EACd,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAC1D,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;IACnD,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,UAAU,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA+B7B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CA6CzB;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,oBAAoB,GACjC,MAAM,CAgBR"}
+{"version":3,"file":"agent-surface.d.ts","sourceRoot":"","sources":["../../src/tui/agent-surface.ts"],"names":[],"mappings":"AAQA,OAAO,EACL,UAAU,EACV,KAAK,cAAc,EACnB,KAAK,cAAc,EACpB,MAAM,qBAAqB,CAAC;AAI7B,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAEhE,OAAO,KAAK,EAAE,eAAe,EAAE,MAAM,yBAAyB,CAAC;AAC/D,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,mBAAmB;IAClC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,0EAA0E;IAC1E,QAAQ,CAAC,OAAO,EAAE,IAAI,CACpB,cAAc,EACd,QAAQ,GAAG,QAAQ,GAAG,UAAU,GAAG,UAAU,GAAG,SAAS,CAC1D,CAAC;IACF;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;IACnD,wEAAwE;IACxE,QAAQ,CAAC,QAAQ,CAAC,EAAE,eAAe,CAAC;IACpC,yDAAyD;IACzD,QAAQ,CAAC,GAAG,CAAC,EAAE,OAAO,UAAU,CAAC;CAClC;AAED;;;;;;GAMG;AACH,wBAAsB,UAAU,CAC9B,EAAE,EAAE,QAAQ,EACZ,MAAM,EAAE,MAAM,GACb,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CA+B7B;AAED,wBAAsB,eAAe,CACnC,OAAO,EAAE,mBAAmB,GAC3B,OAAO,CAAC,cAAc,CAAC,CA8DzB;AAED,wBAAgB,aAAa,CAC3B,OAAO,EAAE,cAAc,EACvB,YAAY,EAAE,oBAAoB,GACjC,MAAM,CAgBR"}

package/dist/tui/agent-surface.js

@@ -56,6 +56,7 @@ export async function runAgentSurface(options) {
     const cards = new ToolCardLog();
     const run = options.run ?? runSession;
     const onEvent = (event) => {
+        options.recorder?.observe(event);
         const changed = cards.apply(event);
         if (changed !== undefined) {
             options.stdout.write(renderCard(changed, capabilities));
@@ -74,7 +75,20 @@ export async function runAgentSurface(options) {
         // Here everything is on one terminal, so it goes to the same place.
         stderr: (text) => void options.stdout.write(dim(text)),
         approver: tuiApprover(io),
-        readLine: () => promptLine(io, "> "),
+        readLine: async () => {
+            // Checkpoint between goals rather than per event: the listing only needs
+            // to be current when someone might go and look at it.
+            options.recorder?.checkpoint();
+            const line = await promptLine(io, "> ");
+            // The user's own words never appear in the agent event stream, so they
+            // are recorded here. Slash commands are control, not conversation.
+            if (line !== undefined &&
+                line.trim().length > 0 &&
+                !line.startsWith("/")) {
+                options.recorder?.goal(line);
+            }
+            return line;
+        },
         onEvent,
     };
     // Installed after the spread, on purpose - see getSignal above.
@@ -86,6 +100,7 @@ export async function runAgentSurface(options) {
         });
     }
     const summary = await run(sessionOptions);
+    options.recorder?.close();
     options.stdout.write(renderSummary(summary, capabilities));
     return summary;
 }

package/dist/tui/app.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/tui/app.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAaxD,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAQrE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAgInE"}
+{"version":3,"file":"app.d.ts","sourceRoot":"","sources":["../../src/tui/app.ts"],"names":[],"mappings":"AAUA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AACnD,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAaxD,OAAO,EAAwB,KAAK,SAAS,EAAE,MAAM,eAAe,CAAC;AAcrE,MAAM,WAAW,UAAU;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,KAAK,EAAE,MAAM,CAAC,UAAU,GAAG;QAAE,KAAK,CAAC,EAAE,OAAO,CAAC;QAAC,KAAK,CAAC,EAAE,OAAO,CAAA;KAAE,CAAC;IACzE,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;IAC3D,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAC;IACzB,QAAQ,CAAC,OAAO,EAAE,MAAM,GAAG,SAAS,CAAC;IACrC,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,wEAAwE;IACxE,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;CAClC;AAED,wBAAsB,MAAM,CAAC,OAAO,EAAE,UAAU,GAAG,OAAO,CAAC,QAAQ,CAAC,CAiJnE"}

package/dist/tui/app.js

@@ -16,7 +16,9 @@ import { palette, detectCapabilities, } from "./theme.js";
 import { followResize } from "./resize.js";
 import { installTerminalGuard } from "./terminal.js";
 import { inspectWorkspace, renderWorkspaceSummary, } from "./workspace-summary.js";
-import { parsePermissions, startAgent } from "./start-agent.js";
+import { parsePermissions, parseSessionOptions, startAgent, } from "./start-agent.js";
+import { sessionsDir } from "../config/paths.js";
+import { chooseSession } from "./session-centre.js";
 import { select } from "./widgets.js";
 export async function runTui(options) {
     // Live, not a snapshot: a window resized mid-session must not keep laying
@@ -104,6 +106,17 @@ export async function runTui(options) {
         if (chosen === undefined)
             return ExitCode.Cancelled;
         options.stdout.write(renderWorkspaceSummary(inspectWorkspace(options.workspace, existsSync), capabilities));
+        // Offered only when there is something to resume, and only when the user
+        // did not already say what they wanted on the command line.
+        const sessionOptions = parseSessionOptions(options.argv);
+        let resumeId = sessionOptions.resumeId;
+        if (resumeId === undefined && !sessionOptions.noHistory) {
+            const choice = await chooseSession(io, sessionsDir(options.commandIo.env ?? process.env));
+            if (choice.kind === "cancelled")
+                return ExitCode.Cancelled;
+            if (choice.kind === "resume")
+                resumeId = choice.sessionId;
+        }
         return await startAgent({
             io,
             capabilities,
@@ -113,6 +126,10 @@ export async function runTui(options) {
             model: chosen,
             workspace: options.workspace,
             permissions: parsePermissions(options.argv),
+            session: {
+                ...sessionOptions,
+                ...(resumeId === undefined ? {} : { resumeId }),
+            },
             getSignal: () => {
                 inFlight ??= new AbortController();
                 return inFlight.signal;

package/dist/tui/route.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/tui/route.ts"],"names":[],"mappings":"AAOA,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAClB,qBAAqB,GACrB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,MAAM,aAAa;AACvB,gDAAgD;AAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AAC1B,4EAA4E;GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,yEAAyE;GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC5D;AAyBD,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAoBlE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAezD"}
+{"version":3,"file":"route.d.ts","sourceRoot":"","sources":["../../src/tui/route.ts"],"names":[],"mappings":"AAOA,0EAA0E;AAC1E,MAAM,MAAM,UAAU,GAClB,qBAAqB,GACrB,aAAa,GACb,eAAe,GACf,gBAAgB,GAChB,WAAW,GACX,IAAI,CAAC;AAET,MAAM,MAAM,aAAa;AACvB,gDAAgD;AAC9C;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE;AAC1B,4EAA4E;GAC1E;IAAE,QAAQ,CAAC,IAAI,EAAE,SAAS,CAAA;CAAE;AAC9B,yEAAyE;GACvE;IAAE,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;IAAC,QAAQ,CAAC,cAAc,EAAE,UAAU,CAAA;CAAE,CAAC;AAEpE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,CAAC;IACjC,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,WAAW,EAAE,OAAO,CAAC;IAC9B,QAAQ,CAAC,GAAG,EAAE,QAAQ,CAAC,MAAM,CAAC,MAAM,EAAE,MAAM,GAAG,SAAS,CAAC,CAAC,CAAC;CAC5D;AA0CD,wBAAgB,WAAW,CAAC,KAAK,EAAE,gBAAgB,GAAG,aAAa,CAoBlE;AAED,yEAAyE;AACzE,wBAAgB,cAAc,CAAC,MAAM,EAAE,UAAU,GAAG,MAAM,CAezD"}

package/dist/tui/route.js

@@ -9,9 +9,26 @@
  * `mafdet` so that `mafdet --json` can never be answered with a drawing.
  */
 const MACHINE_FLAGS = new Set(["--json", "--quiet", "-q"]);
-/** Treated as a command rather than a bare invocation. */
+/** Flags whose next argument is a value, not a command. */
+const FLAGS_TAKING_A_VALUE = new Set([
+    "--title",
+    "--allow-command",
+    "--resume",
+]);
 function hasCommand(argv) {
-    return argv.some((arg) => !arg.startsWith("-"));
+    for (let i = 0; i < argv.length; i += 1) {
+        const arg = argv[i];
+        if (arg.startsWith("-")) {
+            // `mafdet --title "Fix login"` is still a bare invocation: the value
+            // belongs to the flag, and reading it as a command would send the user
+            // to "unknown command 'Fix login'".
+            if (FLAGS_TAKING_A_VALUE.has(arg))
+                i += 1;
+            continue;
+        }
+        return true;
+    }
+    return false;
 }
 /**
  * CI systems attach a pipe often enough that the TTY checks usually catch them,

package/dist/tui/session-centre.d.ts

@@ -0,0 +1,15 @@
+import { type IndexEntry } from "../sessions/index-file.js";
+import { type TerminalCapabilities } from "./theme.js";
+import { type WidgetIo } from "./widgets.js";
+export type SessionChoice = {
+    readonly kind: "new";
+} | {
+    readonly kind: "resume";
+    readonly sessionId: string;
+} | {
+    readonly kind: "cancelled";
+};
+export declare function recentSessions(root: string): readonly IndexEntry[];
+export declare function describeSession(entry: IndexEntry, capabilities: TerminalCapabilities): string;
+export declare function chooseSession(io: WidgetIo, root: string): Promise<SessionChoice>;
+//# sourceMappingURL=session-centre.d.ts.map

package/dist/tui/session-centre.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session-centre.d.ts","sourceRoot":"","sources":["../../src/tui/session-centre.ts"],"names":[],"mappings":"AAOA,OAAO,EAAa,KAAK,UAAU,EAAE,MAAM,2BAA2B,CAAC;AACvE,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,EAAU,KAAK,QAAQ,EAAE,MAAM,cAAc,CAAC;AAKrD,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,KAAK,CAAA;CAAE,GACxB;IAAE,QAAQ,CAAC,IAAI,EAAE,QAAQ,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,GACvD;IAAE,QAAQ,CAAC,IAAI,EAAE,WAAW,CAAA;CAAE,CAAC;AAEnC,wBAAgB,cAAc,CAAC,IAAI,EAAE,MAAM,GAAG,SAAS,UAAU,EAAE,CAQlE;AAED,wBAAgB,eAAe,CAC7B,KAAK,EAAE,UAAU,EACjB,YAAY,EAAE,oBAAoB,GACjC,MAAM,CAQR;AAOD,wBAAsB,aAAa,CACjC,EAAE,EAAE,QAAQ,EACZ,IAAI,EAAE,MAAM,GACX,OAAO,CAAC,aAAa,CAAC,CAoBxB"}

package/dist/tui/session-centre.js

@@ -0,0 +1,59 @@
+// CLI-024 · New conversation, or one of the recent ones.
+//
+// Offered only when there is something to resume: a menu whose only entry is
+// "New conversation" is a keystroke charged for nothing. Everything here reads
+// the local index and sends no request, so browsing costs nothing (plan 20.2).
+import { formatUsd } from "../output/money.js";
+import { loadIndex } from "../sessions/index-file.js";
+import { palette } from "./theme.js";
+import { select } from "./widgets.js";
+/** How many recent conversations to offer before it stops being a list. */
+const RECENT_LIMIT = 8;
+export function recentSessions(root) {
+    try {
+        return loadIndex(root).sessions.slice(0, RECENT_LIMIT);
+    }
+    catch {
+        // A store we cannot read is a store with nothing to offer, not a failure
+        // that should stop someone starting a new conversation.
+        return [];
+    }
+}
+export function describeSession(entry, capabilities) {
+    const parts = [
+        entry.model_id,
+        workspaceName(entry.workspace),
+        `${entry.model_requests} request(s)`,
+        `~${formatUsd(entry.estimated_charge_micro_usd)}`,
+    ];
+    return palette(capabilities).dim(parts.join(" - "));
+}
+function workspaceName(workspace) {
+    const name = workspace.split(/[\\/]/).filter(Boolean).at(-1);
+    return name === undefined || name.length === 0 ? workspace : name;
+}
+export async function chooseSession(io, root) {
+    const recent = recentSessions(root);
+    if (recent.length === 0)
+        return { kind: "new" };
+    const answer = await select(io, {
+        title: "What would you like to do?",
+        items: [
+            { value: "", label: "New conversation" },
+            ...recent.map((entry) => ({
+                value: entry.session_id,
+                label: entry.title,
+                detail: stripStyles(describeSession(entry, io.capabilities)),
+            })),
+        ],
+    });
+    if (answer.kind === "cancelled")
+        return { kind: "cancelled" };
+    return answer.value === ""
+        ? { kind: "new" }
+        : { kind: "resume", sessionId: answer.value };
+}
+/** The select widget dims details itself; doubling it up reads as a bug. */
+function stripStyles(text) {
+    return text.replace(new RegExp(`${String.fromCharCode(27)}\\[[0-9;]*m`, "g"), "");
+}

package/dist/tui/start-agent.d.ts

@@ -3,6 +3,12 @@ import { type CommandIo } from "../commands/runtime.js";
 import { ExitCode } from "../output/exit-codes.js";
 import { type TerminalCapabilities } from "./theme.js";
 import type { WidgetIo } from "./widgets.js";
+export interface SessionOptions {
+    readonly noHistory: boolean;
+    readonly title?: string;
+    /** Continue this session rather than starting a new one. */
+    readonly resumeId?: string;
+}
 export interface AgentPermissions {
     readonly allowWrite: boolean;
     readonly allowedCommands: readonly string[];
@@ -13,6 +19,8 @@ export interface AgentPermissions {
  * The same spellings the agent command uses, so there is one grammar for
  * granting these and no second one to keep in step.
  */
+/** `--no-history` and `--title`, read off the bare invocation. */
+export declare function parseSessionOptions(argv: readonly string[]): SessionOptions;
 export declare function parsePermissions(argv: readonly string[]): AgentPermissions;
 export interface StartAgentOptions {
     readonly io: WidgetIo;
@@ -25,6 +33,7 @@ export interface StartAgentOptions {
     readonly model: ResolvedModel;
     readonly workspace: string;
     readonly permissions: AgentPermissions;
+    readonly session?: SessionOptions;
     /**
      * Read fresh for every goal. A cancel aborts the request in flight and then
      * swaps in a new controller, so the session survives Ctrl+C instead of

package/dist/tui/start-agent.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"start-agent.d.ts","sourceRoot":"","sources":["../../src/tui/start-agent.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAEnD,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAe1E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;CACpD;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,QAAQ,CAAC,CA0DnB"}
+{"version":3,"file":"start-agent.d.ts","sourceRoot":"","sources":["../../src/tui/start-agent.ts"],"names":[],"mappings":"AAaA,OAAO,KAAK,EAAE,aAAa,EAAE,MAAM,kBAAkB,CAAC;AACtD,OAAO,EAAgB,KAAK,SAAS,EAAE,MAAM,wBAAwB,CAAC;AAEtE,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAcnD,OAAO,EAAW,KAAK,oBAAoB,EAAE,MAAM,YAAY,CAAC;AAChE,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,cAAc,CAAC;AAE7C,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,KAAK,CAAC,EAAE,MAAM,CAAC;IACxB,4DAA4D;IAC5D,QAAQ,CAAC,QAAQ,CAAC,EAAE,MAAM,CAAC;CAC5B;AAED,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,UAAU,EAAE,OAAO,CAAC;IAC7B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;CAC7C;AAED;;;;;GAKG;AACH,kEAAkE;AAClE,wBAAgB,mBAAmB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,cAAc,CAqB3E;AAED,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,GAAG,gBAAgB,CAe1E;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,EAAE,EAAE,QAAQ,CAAC;IACtB,QAAQ,CAAC,YAAY,EAAE,oBAAoB,CAAC;IAC5C,QAAQ,CAAC,MAAM,EAAE;QAAE,KAAK,CAAC,IAAI,EAAE,MAAM,GAAG,OAAO,CAAA;KAAE,CAAC;IAClD,QAAQ,CAAC,SAAS,EAAE,SAAS,CAAC;IAC9B,QAAQ,CAAC,MAAM,EAAE,MAAM,CAAC;IACxB,QAAQ,CAAC,KAAK,EAAE,aAAa,CAAC;IAC9B,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,WAAW,EAAE,gBAAgB,CAAC;IACvC,QAAQ,CAAC,OAAO,CAAC,EAAE,cAAc,CAAC;IAClC;;;;;OAKG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,WAAW,GAAG,SAAS,CAAC;CACpD;AAED,wBAAsB,UAAU,CAC9B,OAAO,EAAE,iBAAiB,GACzB,OAAO,CAAC,QAAQ,CAAC,CAkGnB"}

package/dist/tui/start-agent.js

@@ -9,6 +9,13 @@ import { buildToolset, READ_ONLY_PROMPT, WRITE_PROMPT, } from "../commands/agent
 import { buildRuntime } from "../commands/runtime.js";
 import { Workspace } from "../filesystem/workspace.js";
 import { ExitCode } from "../output/exit-codes.js";
+import { existsSync, writeFileSync } from "node:fs";
+import { sessionsDir } from "../config/paths.js";
+import { keyDigest } from "../security/redact.js";
+import { SessionRecorder } from "../sessions/recorder.js";
+import { SessionWriter } from "../sessions/store.js";
+import { NOTICE_FILE, decideRecording, firstSaveNotice, } from "../sessions/policy.js";
+import { describeResume, openForResume } from "../sessions/open.js";
 import { runAgentSurface } from "./agent-surface.js";
 import { palette } from "./theme.js";
 /**
@@ -17,6 +24,32 @@ import { palette } from "./theme.js";
  * The same spellings the agent command uses, so there is one grammar for
  * granting these and no second one to keep in step.
  */
+/** `--no-history` and `--title`, read off the bare invocation. */
+export function parseSessionOptions(argv) {
+    let title;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] !== "--title")
+            continue;
+        const value = argv[i + 1];
+        if (value !== undefined && !value.startsWith("-")) {
+            title = value;
+            i += 1;
+        }
+    }
+    let resumeId;
+    for (let i = 0; i < argv.length; i += 1) {
+        if (argv[i] !== "--resume")
+            continue;
+        const value = argv[i + 1];
+        if (value !== undefined && !value.startsWith("-"))
+            resumeId = value;
+    }
+    return {
+        noHistory: argv.includes("--no-history"),
+        ...(title === undefined ? {} : { title }),
+        ...(resumeId === undefined ? {} : { resumeId }),
+    };
+}
 export function parsePermissions(argv) {
     let allowWrite = false;
     const allowedCommands = [];
@@ -58,8 +91,37 @@ export async function startAgent(options) {
             ? ` - commands: ${options.permissions.allowedCommands.join(", ")}`
             : "") +
         "\n  type a goal, or /help for the session commands\n\n"));
+    const opened = options.session?.resumeId
+        ? openForResume({
+            root: sessionsDir(options.commandIo.env ?? process.env),
+            sessionId: options.session.resumeId,
+            systemPrompt: mode === "read-only" ? READ_ONLY_PROMPT : WRITE_PROMPT,
+            callable: [options.model.modelId],
+            agentCapable: options.model.agentEligible
+                ? [options.model.modelId]
+                : [],
+            allowedCommandsThisRun: options.permissions.allowedCommands,
+        })
+        : undefined;
+    if (opened !== undefined && opened.kind !== "opened") {
+        options.stdout.write(`\n  ${bold("cannot resume that conversation")}: ${opened.kind === "missing"
+            ? "no session with that id on this computer"
+            : opened.reason}\n\n`);
+        return ExitCode.General;
+    }
+    if (opened !== undefined)
+        options.stdout.write(dim(describeResume(opened)));
+    const recorder = opened !== undefined
+        ? new SessionRecorder({
+            writer: opened.writer,
+            root: sessionsDir(options.commandIo.env ?? process.env),
+            apiKeyRef: keyDigest(options.apiKey),
+            onProblem: (message) => void options.stdout.write(dim(`  ${message}\n`)),
+        })
+        : startRecording(options, mode);
     await runAgentSurface({
         io: options.io,
+        ...(recorder === undefined ? {} : { recorder }),
         capabilities: options.capabilities,
         stdout: options.stdout,
         ...(options.getSignal === undefined
@@ -77,8 +139,68 @@ export async function startAgent(options) {
                 allowedCommands: options.permissions.allowedCommands,
             },
             mode,
+            // The rebuilt conversation, or nothing for a new session. runSession
+            // appends to this array in place, which is what continues the thread.
+            ...(opened === undefined ? {} : { history: opened.messages }),
             allowedCommands: options.permissions.allowedCommands,
         },
     });
     return ExitCode.Ok;
 }
+/**
+ * Open a recorder for this run, or not.
+ *
+ * Returns undefined for `--no-history`, and - importantly - reaches the
+ * filesystem only when it is going to record. A flag that still created an
+ * empty directory would be a flag the user was right not to trust.
+ */
+function startRecording(options, mode) {
+    const decision = decideRecording({
+        surface: "interactive",
+        noHistory: options.session?.noHistory ?? false,
+        save: false,
+    });
+    if (!decision.record)
+        return undefined;
+    const env = options.commandIo.env ?? process.env;
+    const root = sessionsDir(env);
+    try {
+        const writer = SessionWriter.create({
+            root,
+            title: options.session?.title ?? defaultTitle(options.workspace),
+            modelId: options.model.modelId,
+            workspace: options.workspace,
+            mode,
+        });
+        showNoticeOnce(root, options);
+        return new SessionRecorder({
+            writer,
+            root,
+            apiKeyRef: keyDigest(options.apiKey),
+            onProblem: (message) => void options.stdout.write(palette(options.capabilities).dim(`  ${message}\n`)),
+        });
+    }
+    catch (error) {
+        // A store that cannot be opened is worth one line, not a dead session.
+        const message = error instanceof Error ? error.message : String(error);
+        options.stdout.write(palette(options.capabilities).dim(`  not recording this conversation: ${message}\n`));
+        return undefined;
+    }
+}
+/** The directory name is the most useful thing we know before anyone speaks. */
+function defaultTitle(workspace) {
+    const name = workspace.split(/[\\/]/).filter(Boolean).at(-1);
+    return name === undefined || name.length === 0 ? "Conversation" : name;
+}
+function showNoticeOnce(root, options) {
+    const marker = `${root}/${NOTICE_FILE}`;
+    try {
+        if (existsSync(marker))
+            return;
+        options.stdout.write(firstSaveNotice(root));
+        writeFileSync(marker, `${new Date().toISOString()}\n`, { mode: 0o600 });
+    }
+    catch {
+        // Showing it twice is a much smaller problem than failing to start.
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@mafdet/cli",
-  "version": "0.4.1",
+  "version": "0.4.2",
   "description": "Mafdet AI command line — model calls, account queries, and a permissioned local agent.",
   "type": "module",
   "license": "MIT",