@mafdet/cli 0.4.0 → 0.4.2

package/dist/sessions/open.js

@@ -0,0 +1,96 @@
+// CLI-024 · Opening a saved session to continue it.
+//
+// The order here is the point: read from disk, check what has changed since,
+// and only then rebuild the context. Nothing reaches the model until the user
+// sends their next message, so opening a conversation is free (plan §20.2) -
+// and the checks are all re-derived from the key in use *now*, never from
+// what the session was recorded with.
+import { existsSync } from "node:fs";
+import { join } from "node:path";
+import { acquireSessionLock, SessionLockedError, } from "./lock.js";
+import { describeBlocker, permissionsForResume, rebuildContext, resumeBlockers, } from "./resume.js";
+import { SessionWriter, readSession } from "./store.js";
+export function openForResume(input) {
+    const directory = join(input.root, input.sessionId);
+    if (!existsSync(directory))
+        return { kind: "missing" };
+    let session;
+    try {
+        session = readSession(directory);
+    }
+    catch (error) {
+        return {
+            kind: "unreadable",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    // Taken before anything is written, so two processes cannot interleave into
+    // one transcript.
+    let lock;
+    try {
+        lock = acquireSessionLock(directory);
+    }
+    catch (error) {
+        if (error instanceof SessionLockedError) {
+            return { kind: "locked", reason: error.message };
+        }
+        throw error;
+    }
+    let writer;
+    try {
+        writer = SessionWriter.reopen(directory);
+    }
+    catch (error) {
+        lock.release();
+        return {
+            kind: "unreadable",
+            reason: error instanceof Error ? error.message : String(error),
+        };
+    }
+    const rebuilt = rebuildContext({
+        events: session.events,
+        systemPrompt: input.systemPrompt,
+    });
+    return {
+        kind: "opened",
+        metadata: session.metadata,
+        messages: rebuilt.messages,
+        writer,
+        lock,
+        blockers: resumeBlockers({
+            modelId: session.metadata.model_id,
+            workspace: session.metadata.workspace,
+            callable: input.callable,
+            agentCapable: input.agentCapable,
+            workspaceExists: existsSync(session.metadata.workspace),
+            forAgent: true,
+        }),
+        omitted: rebuilt.omitted,
+        toolRunsSummarised: rebuilt.toolRunsSummarised,
+        permissions: permissionsForResume(input.allowedCommandsThisRun),
+    };
+}
+/**
+ * What to tell the user when a session is reopened.
+ *
+ * The cost sentence is the one that earns its place: opening was free, but the
+ * next message re-sends this history as input tokens, and someone who does not
+ * know that will be surprised by the bill rather than by the feature.
+ */
+export function describeResume(result) {
+    const lines = [
+        `resuming "${result.metadata.title}" (${result.metadata.model_id})`,
+    ];
+    if (result.toolRunsSummarised > 0) {
+        lines.push(`  ${result.toolRunsSummarised} earlier tool run(s) are summarised, not repeated`);
+    }
+    if (result.omitted > 0) {
+        lines.push(`  ${result.omitted} older message(s) left out to fit the context`);
+    }
+    lines.push("  opening this cost nothing; your next message re-sends the history above");
+    lines.push("  as input tokens, and approvals from last time do not carry over");
+    for (const blocker of result.blockers) {
+        lines.push(`  ! ${describeBlocker(blocker)}`);
+    }
+    return lines.join("\n") + "\n";
+}

package/dist/sessions/policy.d.ts

@@ -0,0 +1,32 @@
+export type RecordingSurface = 
+/** TUI or `mafdet agent` with a terminal. */
+"interactive"
+/** A single `mafdet chat "..."`. */
+ | "one-shot"
+/** Piped, --json, CI: something is parsing this. */
+ | "machine";
+export interface RecordingInput {
+    readonly surface: RecordingSurface;
+    readonly noHistory: boolean;
+    /** `--save` on a one-shot run. */
+    readonly save: boolean;
+}
+export interface RecordingDecision {
+    readonly record: boolean;
+    /** Why, in words, for `mafdet config list` and for the tests. */
+    readonly because: string;
+}
+export declare function decideRecording(input: RecordingInput): RecordingDecision;
+/**
+ * Said once, the first time anything is written on this machine.
+ *
+ * Both halves are load-bearing. "Stored locally, we do not read it" is true of
+ * the archive and false if read as "we cannot see your conversation" - the
+ * messages are sent to the API to be answered regardless of whether a
+ * transcript is kept. Saying only the first half would be a privacy claim we
+ * cannot stand behind.
+ */
+export declare function firstSaveNotice(sessionsPath: string): string;
+/** Marker that the notice has been shown, so it is shown once and not again. */
+export declare const NOTICE_FILE = ".notice-shown";
+//# sourceMappingURL=policy.d.ts.map

package/dist/sessions/policy.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"policy.d.ts","sourceRoot":"","sources":["../../src/sessions/policy.ts"],"names":[],"mappings":"AAUA,MAAM,MAAM,gBAAgB;AAC1B,6CAA6C;AAC3C,aAAa;AACf,oCAAoC;GAClC,UAAU;AACZ,oDAAoD;GAClD,SAAS,CAAC;AAEd,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,OAAO,EAAE,gBAAgB,CAAC;IACnC,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,kCAAkC;IAClC,QAAQ,CAAC,IAAI,EAAE,OAAO,CAAC;CACxB;AAED,MAAM,WAAW,iBAAiB;IAChC,QAAQ,CAAC,MAAM,EAAE,OAAO,CAAC;IACzB,iEAAiE;IACjE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;CAC1B;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,cAAc,GAAG,iBAAiB,CAqBxE;AAED;;;;;;;;GAQG;AACH,wBAAgB,eAAe,CAAC,YAAY,EAAE,MAAM,GAAG,MAAM,CAiB5D;AAED,gFAAgF;AAChF,eAAO,MAAM,WAAW,kBAAkB,CAAC"}

package/dist/sessions/policy.js

@@ -0,0 +1,57 @@
+// CLI-023 · Whether this run records anything, and what the user is told.
+//
+// Plan §20.4. Recording is on by default for interactive work and off
+// everywhere a machine is reading, and `--no-history` must leave *no* file
+// behind - not an empty directory, not an index entry, nothing. A flag that
+// merely hid the transcript would be worse than no flag, because the user
+// would believe it.
+import { redact } from "../security/redact.js";
+export function decideRecording(input) {
+    if (input.noHistory) {
+        return { record: false, because: "--no-history was given" };
+    }
+    if (input.surface === "machine") {
+        // Not a privacy judgement so much as a correctness one: a script's run is
+        // not a conversation anyone will resume.
+        return { record: false, because: "output is being read by a machine" };
+    }
+    if (input.surface === "one-shot") {
+        return input.save
+            ? { record: true, because: "--save was given" }
+            : {
+                record: false,
+                because: "a single chat is not recorded unless --save",
+            };
+    }
+    return {
+        record: true,
+        because: "interactive sessions are recorded by default",
+    };
+}
+/**
+ * Said once, the first time anything is written on this machine.
+ *
+ * Both halves are load-bearing. "Stored locally, we do not read it" is true of
+ * the archive and false if read as "we cannot see your conversation" - the
+ * messages are sent to the API to be answered regardless of whether a
+ * transcript is kept. Saying only the first half would be a privacy claim we
+ * cannot stand behind.
+ */
+export function firstSaveNotice(sessionsPath) {
+    return ([
+        "",
+        "  Conversations are saved on this computer only, at",
+        `    ${redact(sessionsPath)}`,
+        "  They are not uploaded, and Mafdet does not have a copy of them.",
+        "",
+        "  This is separate from how the model works: the messages you send are",
+        "  still sent to the API to be answered, and appear in your usage records.",
+        "  What stays local is the saved transcript.",
+        "",
+        "  The file is plain text and includes any source the agent read.",
+        "  Turn it off with --no-history, or delete with 'mafdet sessions delete'.",
+        "",
+    ].join("\n") + "\n");
+}
+/** Marker that the notice has been shown, so it is shown once and not again. */
+export const NOTICE_FILE = ".notice-shown";

package/dist/sessions/reconcile.d.ts

@@ -0,0 +1,49 @@
+import type { LedgerUsageEvent } from "../api/account.js";
+import type { StoredEvent } from "./store.js";
+import type { SessionEvent } from "./store.js";
+export interface ReconcilePlan {
+    /** Request ids worth asking this key about. */
+    readonly wanted: ReadonlySet<string>;
+    /** Already reconciled on an earlier run; asking again would be wasted. */
+    readonly alreadySettled: number;
+    /** No request id was ever returned, so no answer exists to fetch. */
+    readonly unanswerable: number;
+    /** Paid for by a different key; a different key has to ask. */
+    readonly otherKey: number;
+    /** Recorded before per-key attribution, so we cannot tell which key paid. */
+    readonly unattributed: number;
+}
+/**
+ * Decide what to ask about, from the transcript alone.
+ *
+ * `unattributed` requests are still asked about. They were written by a CLI
+ * old enough not to record which key paid, and since the answer can only come
+ * back scoped to the current key, a match is itself the proof that this key
+ * paid for it. Excluding them would make old sessions permanently
+ * unreconcilable in exchange for no safety at all.
+ */
+export declare function planReconciliation(events: readonly StoredEvent[], currentKeyDigest: string): ReconcilePlan;
+export interface MatchResult {
+    readonly settlements: readonly SessionEvent[];
+    /** Asked about but not in the ledger's answer. */
+    readonly missing: readonly string[];
+}
+/**
+ * Pair the ledger's rows with the ids we asked about.
+ *
+ * Rows for requests this session never made are dropped rather than recorded:
+ * the same key pays for other sessions, and this file is a record of one
+ * conversation.
+ */
+export declare function matchSettlements(plan: ReconcilePlan, ledger: readonly LedgerUsageEvent[], observedAt: string): MatchResult;
+/**
+ * How many days back the ledger has to be asked about.
+ *
+ * Derived from when the session started, plus a day of slack for clock skew
+ * and for a session that ran past midnight. The endpoint caps the window at
+ * 90 days; asking for more is rejected outright, so it is clamped here rather
+ * than turned into a failed command.
+ */
+export declare const MAX_LEDGER_DAYS = 90;
+export declare function daysToCover(createdAt: string, now?: Date): number;
+//# sourceMappingURL=reconcile.d.ts.map

package/dist/sessions/reconcile.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"reconcile.d.ts","sourceRoot":"","sources":["../../src/sessions/reconcile.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,gBAAgB,EAAE,MAAM,mBAAmB,CAAC;AAC1D,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAC9C,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,YAAY,CAAC;AAE/C,MAAM,WAAW,aAAa;IAC5B,+CAA+C;IAC/C,QAAQ,CAAC,MAAM,EAAE,WAAW,CAAC,MAAM,CAAC,CAAC;IACrC,0EAA0E;IAC1E,QAAQ,CAAC,cAAc,EAAE,MAAM,CAAC;IAChC,qEAAqE;IACrE,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,+DAA+D;IAC/D,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,6EAA6E;IAC7E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;CAC/B;AAED;;;;;;;;GAQG;AACH,wBAAgB,kBAAkB,CAChC,MAAM,EAAE,SAAS,WAAW,EAAE,EAC9B,gBAAgB,EAAE,MAAM,GACvB,aAAa,CAwCf;AAED,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,WAAW,EAAE,SAAS,YAAY,EAAE,CAAC;IAC9C,kDAAkD;IAClD,QAAQ,CAAC,OAAO,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;;;GAMG;AACH,wBAAgB,gBAAgB,CAC9B,IAAI,EAAE,aAAa,EACnB,MAAM,EAAE,SAAS,gBAAgB,EAAE,EACnC,UAAU,EAAE,MAAM,GACjB,WAAW,CAyBb;AAOD;;;;;;;GAOG;AACH,eAAO,MAAM,eAAe,KAAK,CAAC;AAElC,wBAAgB,WAAW,CAAC,SAAS,EAAE,MAAM,EAAE,GAAG,GAAE,IAAiB,GAAG,MAAM,CAM7E"}

package/dist/sessions/reconcile.js

@@ -0,0 +1,115 @@
+// CLI-027 · Turning a local estimate into the ledger's own figure.
+//
+// Plan §20.14. The shape of the whole feature follows from one fact: the
+// server's `/keyinfo/usage-events` is scoped to the key that calls it. So the
+// CLI never has to prove ownership of a request - if a request id comes back
+// from a call made with this key, it was this key's request. That is why
+// reconciling needs nothing but the id: no session id, no title, no workspace,
+// no message, no tool argument leaves the machine.
+//
+// What the local key digest adds is not authorisation but honesty. Without it,
+// a request paid for by another key looks exactly like one the ledger has not
+// caught up with yet, and the user is told to wait for something that will
+// never arrive. With it, we can say which key to run this under instead.
+import { isComparableKeyRef } from "../security/redact.js";
+/**
+ * Decide what to ask about, from the transcript alone.
+ *
+ * `unattributed` requests are still asked about. They were written by a CLI
+ * old enough not to record which key paid, and since the answer can only come
+ * back scoped to the current key, a match is itself the proof that this key
+ * paid for it. Excluding them would make old sessions permanently
+ * unreconcilable in exchange for no safety at all.
+ */
+export function planReconciliation(events, currentKeyDigest) {
+    const settled = new Set();
+    for (const event of events) {
+        if (event.type === "settlement" && typeof event.request_id === "string") {
+            settled.add(event.request_id);
+        }
+    }
+    const wanted = new Set();
+    let alreadySettled = 0;
+    let unanswerable = 0;
+    let otherKey = 0;
+    let unattributed = 0;
+    for (const event of events) {
+        if (event.type !== "usage")
+            continue;
+        const id = event.request_id;
+        if (typeof id !== "string" || id.length === 0) {
+            unanswerable += 1;
+            continue;
+        }
+        if (settled.has(id)) {
+            alreadySettled += 1;
+            continue;
+        }
+        const ref = typeof event.api_key_ref === "string" ? event.api_key_ref : "";
+        if (isComparableKeyRef(ref)) {
+            if (ref !== currentKeyDigest) {
+                otherKey += 1;
+                continue;
+            }
+        }
+        else {
+            unattributed += 1;
+        }
+        wanted.add(id);
+    }
+    return { wanted, alreadySettled, unanswerable, otherKey, unattributed };
+}
+/**
+ * Pair the ledger's rows with the ids we asked about.
+ *
+ * Rows for requests this session never made are dropped rather than recorded:
+ * the same key pays for other sessions, and this file is a record of one
+ * conversation.
+ */
+export function matchSettlements(plan, ledger, observedAt) {
+    const byId = new Map();
+    for (const row of ledger) {
+        if (plan.wanted.has(row.request_id))
+            byId.set(row.request_id, row);
+    }
+    const settlements = [];
+    const missing = [];
+    for (const id of plan.wanted) {
+        const row = byId.get(id);
+        if (row === undefined) {
+            missing.push(id);
+            continue;
+        }
+        settlements.push({
+            type: "settlement",
+            request_id: id,
+            // Kept as the string the server sent. Parsing it into a number here is
+            // how integer micro-USD becomes a float somewhere downstream.
+            settled_charge_micro_usd: normaliseMicro(row.platform_charge_micro_usd),
+            server_status: typeof row.status === "string" ? row.status : "unknown",
+            observed_at: observedAt,
+        });
+    }
+    return { settlements, missing };
+}
+/** Anything that is not an integer count of micro-USD is not a charge. */
+function normaliseMicro(value) {
+    return typeof value === "string" && /^-?\d+$/.test(value) ? value : "0";
+}
+/**
+ * How many days back the ledger has to be asked about.
+ *
+ * Derived from when the session started, plus a day of slack for clock skew
+ * and for a session that ran past midnight. The endpoint caps the window at
+ * 90 days; asking for more is rejected outright, so it is clamped here rather
+ * than turned into a failed command.
+ */
+export const MAX_LEDGER_DAYS = 90;
+export function daysToCover(createdAt, now = new Date()) {
+    const started = Date.parse(createdAt);
+    if (!Number.isFinite(started))
+        return MAX_LEDGER_DAYS;
+    const elapsed = now.getTime() - started;
+    const days = Math.ceil(elapsed / 86_400_000) + 1;
+    return Math.min(Math.max(days, 1), MAX_LEDGER_DAYS);
+}

package/dist/sessions/recorder.d.ts

@@ -0,0 +1,42 @@
+import type { AgentEvent } from "../agent/loop.js";
+import { SessionWriter } from "./store.js";
+export interface RecorderOptions {
+    readonly writer: SessionWriter;
+    readonly root: string;
+    /**
+     * An irreversible fingerprint of the key paying for this run, so usage can
+     * be split per key (§20.3) without the key itself ever being written.
+     */
+    readonly apiKeyRef?: string;
+    /** Told once, with the first failure, then never again. */
+    readonly onProblem?: (message: string) => void;
+}
+/**
+ * Turns agent events into stored events.
+ *
+ * `tool_awaiting_approval` and `turn` are not recorded: the first is a UI
+ * state, and the second is derivable. What is recorded is what happened.
+ */
+export declare class SessionRecorder {
+    private readonly options;
+    private broken;
+    private dirty;
+    constructor(options: RecorderOptions);
+    get sessionId(): string;
+    /** The user's own words, which the agent event stream never carries. */
+    goal(text: string): void;
+    observe(event: AgentEvent): void;
+    /** Refresh the listing. Cheap enough per goal, wasteful per event. */
+    checkpoint(): void;
+    setTitle(title: string): void;
+    close(): void;
+    private write;
+    /**
+     * Stop recording, say so once, and let the session carry on.
+     *
+     * Silence would be worse: the user believes there is a transcript. Repeating
+     * it every event would be worse still.
+     */
+    private fail;
+}
+//# sourceMappingURL=recorder.d.ts.map

package/dist/sessions/recorder.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"recorder.d.ts","sourceRoot":"","sources":["../../src/sessions/recorder.ts"],"names":[],"mappings":"AAQA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,kBAAkB,CAAC;AAEnD,OAAO,EAAE,aAAa,EAAqB,MAAM,YAAY,CAAC;AAE9D,MAAM,WAAW,eAAe;IAC9B,QAAQ,CAAC,MAAM,EAAE,aAAa,CAAC;IAC/B,QAAQ,CAAC,IAAI,EAAE,MAAM,CAAC;IACtB;;;OAGG;IACH,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;IAC5B,2DAA2D;IAC3D,QAAQ,CAAC,SAAS,CAAC,EAAE,CAAC,OAAO,EAAE,MAAM,KAAK,IAAI,CAAC;CAChD;AAED;;;;;GAKG;AACH,qBAAa,eAAe;IAId,OAAO,CAAC,QAAQ,CAAC,OAAO;IAHpC,OAAO,CAAC,MAAM,CAAS;IACvB,OAAO,CAAC,KAAK,CAAS;gBAEO,OAAO,EAAE,eAAe;IAErD,IAAI,SAAS,IAAI,MAAM,CAEtB;IAED,wEAAwE;IACxE,IAAI,CAAC,IAAI,EAAE,MAAM,GAAG,IAAI;IAIxB,OAAO,CAAC,KAAK,EAAE,UAAU,GAAG,IAAI;IAoDhC,sEAAsE;IACtE,UAAU,IAAI,IAAI;IAUlB,QAAQ,CAAC,KAAK,EAAE,MAAM,GAAG,IAAI;IAU7B,KAAK,IAAI,IAAI;IASb,OAAO,CAAC,KAAK;IAUb;;;;;OAKG;IACH,OAAO,CAAC,IAAI;CAOb"}

package/dist/sessions/recorder.js

@@ -0,0 +1,147 @@
+// CLI-024 · Recording a live session.
+//
+// A thin bridge from the agent's event stream to the store, and deliberately
+// thin: it decides nothing about permissions, sends nothing, and every failure
+// it meets is swallowed. A disk that is full, or a state directory that has
+// become unwritable, must not end someone's conversation - losing the
+// transcript is bad, losing the work in progress is worse.
+import { upsertIndexEntry } from "./index-file.js";
+/**
+ * Turns agent events into stored events.
+ *
+ * `tool_awaiting_approval` and `turn` are not recorded: the first is a UI
+ * state, and the second is derivable. What is recorded is what happened.
+ */
+export class SessionRecorder {
+    options;
+    broken = false;
+    dirty = false;
+    constructor(options) {
+        this.options = options;
+    }
+    get sessionId() {
+        return this.options.writer.sessionId;
+    }
+    /** The user's own words, which the agent event stream never carries. */
+    goal(text) {
+        this.write({ type: "user_message", content: text });
+    }
+    observe(event) {
+        if (event.type === "text") {
+            this.write({ type: "assistant_message", content: event.text });
+        }
+        else if (event.type === "tool_started") {
+            this.write({
+                type: "tool_call",
+                tool: event.name,
+                arguments: safeParse(event.arguments),
+            });
+        }
+        else if (event.type === "tool") {
+            this.write({
+                type: "tool_result",
+                tool: event.name,
+                status: event.ok ? "succeeded" : "failed",
+                content: event.detail,
+            });
+        }
+        else if (event.type === "declined") {
+            this.write({
+                type: "tool_result",
+                tool: event.name,
+                status: "refused",
+                content: event.summary,
+            });
+        }
+        else if (event.type === "rate_limited") {
+            // Recorded because §20.2 is explicit that waiting is not a request: the
+            // aggregation must be able to show the delay without inflating the count.
+            this.write({
+                type: "rate_limited",
+                wait_ms: event.waitMs,
+                attempt: event.attempt,
+            });
+        }
+        else if (event.type === "usage") {
+            this.write({
+                type: "usage",
+                ...(event.requestId === undefined
+                    ? {}
+                    : { request_id: event.requestId }),
+                model_id: event.model,
+                prompt_tokens: event.promptTokens,
+                completion_tokens: event.completionTokens,
+                estimated_charge_micro_usd: event.costMicroUsd.toString(),
+                ...(this.options.apiKeyRef === undefined
+                    ? {}
+                    : { api_key_ref: this.options.apiKeyRef }),
+                // Local arithmetic only. Whether the gateway settled at this figure is
+                // a separate question, answered in CLI-027, and calling it "settled"
+                // here would be a claim we cannot make.
+                settlement_status: "pending",
+            });
+        }
+    }
+    /** Refresh the listing. Cheap enough per goal, wasteful per event. */
+    checkpoint() {
+        if (this.broken || !this.dirty)
+            return;
+        this.dirty = false;
+        try {
+            upsertIndexEntry(this.options.root, this.options.writer.metadata);
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    setTitle(title) {
+        if (this.broken)
+            return;
+        try {
+            this.options.writer.setTitle(title);
+            this.dirty = true;
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    close() {
+        this.checkpoint();
+        try {
+            this.options.writer.close();
+        }
+        catch {
+            // Closing is bookkeeping; nothing depends on it succeeding.
+        }
+    }
+    write(event) {
+        if (this.broken)
+            return;
+        try {
+            this.options.writer.append(event);
+            this.dirty = true;
+        }
+        catch (error) {
+            this.fail(error);
+        }
+    }
+    /**
+     * Stop recording, say so once, and let the session carry on.
+     *
+     * Silence would be worse: the user believes there is a transcript. Repeating
+     * it every event would be worse still.
+     */
+    fail(error) {
+        this.broken = true;
+        const message = error instanceof Error ? error.message : String(error);
+        this.options.onProblem?.(`not recording this conversation any more: ${message}`);
+    }
+}
+function safeParse(raw) {
+    try {
+        return JSON.parse(raw || "{}");
+    }
+    catch {
+        return { raw };
+    }
+}

package/dist/sessions/resume.d.ts

@@ -0,0 +1,67 @@
+import type { ChatMessage } from "../agent/loop.js";
+import type { StoredEvent } from "./store.js";
+export interface RebuildInput {
+    readonly events: readonly StoredEvent[];
+    readonly systemPrompt: string;
+    /** Roughly how much of the past to carry. Oldest turns are dropped first. */
+    readonly maxMessages?: number;
+}
+export interface RebuiltContext {
+    readonly messages: ChatMessage[];
+    /** How many stored events were left out, for an honest one-line summary. */
+    readonly omitted: number;
+    /** Tool activity is summarised rather than replayed; this counts it. */
+    readonly toolRunsSummarised: number;
+}
+/**
+ * Rebuild the messages to send, from what was stored.
+ *
+ * Tool activity becomes a short note in the conversation rather than a
+ * `tool_calls` block: the model learns that a file was read without being
+ * handed a half-finished plan to resume, and the API cannot be asked to
+ * reference a tool call whose result no longer exists.
+ */
+export declare function rebuildContext(input: RebuildInput): RebuiltContext;
+export type ResumeBlocker = {
+    readonly kind: "model-unavailable";
+    readonly modelId: string;
+} | {
+    readonly kind: "model-not-agent-capable";
+    readonly modelId: string;
+} | {
+    readonly kind: "workspace-missing";
+    readonly workspace: string;
+};
+export interface ResumeCheckInput {
+    readonly modelId: string;
+    readonly workspace: string;
+    /** Model ids this key can call right now. */
+    readonly callable: readonly string[];
+    /** Of those, the ones the agent may drive. */
+    readonly agentCapable: readonly string[];
+    readonly workspaceExists: boolean;
+    /** Whether the caller intends to run the agent, or only to read the log. */
+    readonly forAgent: boolean;
+}
+/**
+ * What stands in the way of continuing, checked before anything is sent.
+ *
+ * Everything here is re-derived from the *current* key: a session recorded
+ * with a key that could call a model says nothing about whether this key can.
+ */
+export declare function resumeBlockers(input: ResumeCheckInput): readonly ResumeBlocker[];
+export declare function describeBlocker(blocker: ResumeBlocker): string;
+/**
+ * What a resumed run starts with, stated so the caller cannot forget.
+ *
+ * Returned as data rather than left implicit: every field here is a permission
+ * that deliberately does *not* survive, and a reviewer should be able to see
+ * that in one place.
+ */
+export interface ResumedPermissions {
+    readonly approvals: "none";
+    readonly allowedCommands: readonly string[];
+    readonly mayReplayTools: false;
+}
+export declare function permissionsForResume(declaredThisRun: readonly string[]): ResumedPermissions;
+//# sourceMappingURL=resume.d.ts.map

package/dist/sessions/resume.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"resume.d.ts","sourceRoot":"","sources":["../../src/sessions/resume.ts"],"names":[],"mappings":"AAYA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,kBAAkB,CAAC;AACpD,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,WAAW,YAAY;IAC3B,QAAQ,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,CAAC;IACxC,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,6EAA6E;IAC7E,QAAQ,CAAC,WAAW,CAAC,EAAE,MAAM,CAAC;CAC/B;AAED,MAAM,WAAW,cAAc;IAC7B,QAAQ,CAAC,QAAQ,EAAE,WAAW,EAAE,CAAC;IACjC,4EAA4E;IAC5E,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,wEAAwE;IACxE,QAAQ,CAAC,kBAAkB,EAAE,MAAM,CAAC;CACrC;AAID;;;;;;;GAOG;AACH,wBAAgB,cAAc,CAAC,KAAK,EAAE,YAAY,GAAG,cAAc,CAwClE;AAED,MAAM,MAAM,aAAa,GACrB;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GAChE;IAAE,QAAQ,CAAC,IAAI,EAAE,yBAAyB,CAAC;IAAC,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;CAAE,GACtE;IAAE,QAAQ,CAAC,IAAI,EAAE,mBAAmB,CAAC;IAAC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;CAAE,CAAC;AAEvE,MAAM,WAAW,gBAAgB;IAC/B,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,6CAA6C;IAC7C,QAAQ,CAAC,QAAQ,EAAE,SAAS,MAAM,EAAE,CAAC;IACrC,8CAA8C;IAC9C,QAAQ,CAAC,YAAY,EAAE,SAAS,MAAM,EAAE,CAAC;IACzC,QAAQ,CAAC,eAAe,EAAE,OAAO,CAAC;IAClC,4EAA4E;IAC5E,QAAQ,CAAC,QAAQ,EAAE,OAAO,CAAC;CAC5B;AAED;;;;;GAKG;AACH,wBAAgB,cAAc,CAC5B,KAAK,EAAE,gBAAgB,GACtB,SAAS,aAAa,EAAE,CAa1B;AAED,wBAAgB,eAAe,CAAC,OAAO,EAAE,aAAa,GAAG,MAAM,CAS9D;AAED;;;;;;GAMG;AACH,MAAM,WAAW,kBAAkB;IACjC,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAC;IAC3B,QAAQ,CAAC,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IAC5C,QAAQ,CAAC,cAAc,EAAE,KAAK,CAAC;CAChC;AAED,wBAAgB,oBAAoB,CAClC,eAAe,EAAE,SAAS,MAAM,EAAE,GACjC,kBAAkB,CAQpB"}