@mafdet/cli 0.4.1 → 0.4.2

package/dist/sessions/resume.js

@@ -0,0 +1,100 @@
+// CLI-024 · Turning a saved transcript back into model context.
+//
+// Plan §20.6. The rule that shapes this file: a resumed session inherits the
+// conversation and nothing else. Historical tool calls are context, never
+// instructions to re-run; every approval expired when the process that granted
+// it exited; and `--allow-command` has to be declared again by this run.
+//
+// So the rebuild deliberately drops the `tool_calls` structure and keeps only
+// what was said. A replayed `tool_calls` block would invite the model to
+// continue a plan the user approved yesterday, in a workspace that has since
+// changed, with permissions this run may not have.
+const DEFAULT_MAX_MESSAGES = 40;
+/**
+ * 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 function rebuildContext(input) {
+    const limit = input.maxMessages ?? DEFAULT_MAX_MESSAGES;
+    const turns = [];
+    let toolRunsSummarised = 0;
+    const pendingTools = [];
+    const flushTools = () => {
+        if (pendingTools.length === 0)
+            return;
+        turns.push({
+            role: "assistant",
+            content: `(earlier in this session I used: ${pendingTools.join(", ")})`,
+        });
+        pendingTools.length = 0;
+    };
+    for (const event of input.events) {
+        if (event.type === "user_message") {
+            flushTools();
+            turns.push({ role: "user", content: String(event.content ?? "") });
+        }
+        else if (event.type === "assistant_message") {
+            flushTools();
+            turns.push({ role: "assistant", content: String(event.content ?? "") });
+        }
+        else if (event.type === "tool_call") {
+            toolRunsSummarised += 1;
+            pendingTools.push(String(event.tool ?? "a tool"));
+        }
+        // tool_result and usage carry nothing the next turn needs: the result is
+        // already reflected in whatever the assistant said afterwards.
+    }
+    flushTools();
+    // Drop from the front, keeping the most recent exchange intact.
+    const omitted = Math.max(turns.length - limit, 0);
+    const kept = omitted > 0 ? turns.slice(omitted) : turns;
+    return {
+        messages: [{ role: "system", content: input.systemPrompt }, ...kept],
+        omitted,
+        toolRunsSummarised,
+    };
+}
+/**
+ * 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 function resumeBlockers(input) {
+    const blockers = [];
+    if (!input.callable.includes(input.modelId)) {
+        blockers.push({ kind: "model-unavailable", modelId: input.modelId });
+    }
+    else if (input.forAgent && !input.agentCapable.includes(input.modelId)) {
+        // Admission is not inherited either: a model may have lost its verified
+        // tool calling since the session was recorded.
+        blockers.push({ kind: "model-not-agent-capable", modelId: input.modelId });
+    }
+    if (!input.workspaceExists) {
+        blockers.push({ kind: "workspace-missing", workspace: input.workspace });
+    }
+    return blockers;
+}
+export function describeBlocker(blocker) {
+    switch (blocker.kind) {
+        case "model-unavailable":
+            return `${blocker.modelId} is not callable with the key you are using now - choose another model to continue`;
+        case "model-not-agent-capable":
+            return `${blocker.modelId} has no verified tool calling now, so the agent cannot drive it - choose another model`;
+        case "workspace-missing":
+            return `${blocker.workspace} no longer exists - you can read this conversation, or continue it in another directory`;
+    }
+}
+export function permissionsForResume(declaredThisRun) {
+    return {
+        approvals: "none",
+        // Only what this process was given. The recorded session's list is not
+        // even consulted - reading it would be the first step towards honouring it.
+        allowedCommands: [...declaredThisRun],
+        mayReplayTools: false,
+    };
+}

package/dist/sessions/store.d.ts

@@ -0,0 +1,141 @@
+export declare const SCHEMA_VERSION = 1;
+export type SessionEvent = {
+    readonly type: "user_message";
+    readonly content: string;
+} | {
+    readonly type: "assistant_message";
+    readonly content: string;
+} | {
+    readonly type: "tool_call";
+    readonly tool: string;
+    readonly arguments: unknown;
+} | {
+    readonly type: "tool_result";
+    readonly tool: string;
+    readonly status: string;
+    readonly content: string;
+} | {
+    /** A 429 and what it cost in waiting. Not a model request; see §20.2. */
+    readonly type: "rate_limited";
+    readonly wait_ms: number;
+    readonly attempt: number;
+} | {
+    readonly type: "usage";
+    readonly request_id?: string;
+    readonly model_id: string;
+    readonly prompt_tokens: number;
+    readonly completion_tokens: number;
+    readonly estimated_charge_micro_usd: string;
+    readonly settlement_status: "pending" | "settled" | "unknown";
+    /**
+     * Which key paid, as an irreversible digest. Plan §20.3 requires
+     * per-key attribution and forbids storing the key, so the two are
+     * reconciled by storing something that can be compared but not used.
+     */
+    readonly api_key_ref?: string;
+} | {
+    /**
+     * CLI-027 · What the server's ledger says one request actually cost.
+     *
+     * Appended rather than written back over the `usage` line it settles.
+     * The log is append-only for a reason - a transcript that gets rewritten
+     * after the fact is no longer a record of what happened - and this way a
+     * reconciliation that is interrupted halfway leaves the earlier half
+     * settled and the rest simply unsettled.
+     */
+    readonly type: "settlement";
+    readonly request_id: string;
+    readonly settled_charge_micro_usd: string;
+    /** The ledger's own word for the request, e.g. `success`. */
+    readonly server_status: string;
+    readonly observed_at: string;
+};
+export interface StoredEvent {
+    readonly seq: number;
+    readonly type: string;
+    readonly [key: string]: unknown;
+}
+export interface SessionMetadata {
+    schema_version: number;
+    session_id: string;
+    title: string;
+    created_at: string;
+    updated_at: string;
+    model_id: string;
+    workspace: string;
+    mode: string;
+    message_count: number;
+    model_requests: number;
+    prompt_tokens: number;
+    completion_tokens: number;
+    estimated_charge_micro_usd: string;
+}
+export declare class SessionStoreError extends Error {
+}
+/** Time-ordered and collision-resistant, without pulling in a ulid package. */
+export declare function newSessionId(now?: number): string;
+export interface OpenOptions {
+    readonly root: string;
+    readonly sessionId?: string;
+    readonly title: string;
+    readonly modelId: string;
+    readonly workspace: string;
+    readonly mode: string;
+    readonly now?: () => Date;
+}
+/**
+ * A session being written to.
+ *
+ * Held open for the life of the process. Every append is a complete line
+ * followed by a metadata refresh, so a crash leaves a readable store.
+ */
+export declare class SessionWriter {
+    readonly directory: string;
+    private meta;
+    private readonly now;
+    private seq;
+    private closed;
+    private constructor();
+    static create(options: OpenOptions): SessionWriter;
+    /**
+     * Continue writing to a session that already exists.
+     *
+     * The sequence picks up from the last complete event, so a resumed session
+     * is one file rather than two - and a partial last line from an earlier
+     * crash is simply written past, since `readSession` already ignores it.
+     */
+    static reopen(directory: string, now?: () => Date): SessionWriter;
+    get sessionId(): string;
+    get metadata(): Readonly<SessionMetadata>;
+    /**
+     * Append one event.
+     *
+     * Redacted first, and deliberately at this boundary rather than at each call
+     * site: a single place to be right about, and no way for a new event type to
+     * be added that forgets.
+     */
+    append(event: SessionEvent): StoredEvent;
+    private touch;
+    setTitle(title: string): void;
+    close(): void;
+    /** Temp file plus rename: a crash never leaves half a metadata document. */
+    private writeMetadata;
+}
+export interface ReadSession {
+    readonly metadata: SessionMetadata;
+    readonly events: readonly StoredEvent[];
+    /** Set when the last line was incomplete, which a crash mid-append leaves. */
+    readonly truncatedTail: boolean;
+}
+/**
+ * Read a session back.
+ *
+ * A partial final line is dropped rather than treated as corruption: it is the
+ * expected result of being killed mid-append, and everything before it is
+ * still exactly what happened.
+ */
+export declare function readSession(directory: string): ReadSession;
+/** Session directories present on disk, newest first by mtime of metadata. */
+export declare function listSessionDirectories(root: string): string[];
+export declare function deleteSession(directory: string): void;
+//# sourceMappingURL=store.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"store.d.ts","sourceRoot":"","sources":["../../src/sessions/store.ts"],"names":[],"mappings":"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"}

package/dist/sessions/store.js

@@ -0,0 +1,272 @@
+// CLI-023 · The local session store.
+//
+// Plan §20.5. One directory per session: a small metadata file that is
+// rewritten atomically, and an append-only JSONL of events. No SQLite, so the
+// package keeps its single runtime dependency.
+//
+// Two properties drive the shape:
+//
+//   - An interrupted write must cost at most the last event. Appending whole
+//     lines gives that for free; rewriting a JSON blob would not.
+//   - Nothing written here may carry a credential. Everything goes through
+//     `redact()` on the way to disk - the forbidden list in §20.5 covers what
+//     the CLI holds, not a password the user typed into a prompt.
+import { appendFileSync, lstatSync, mkdirSync, readFileSync, readdirSync, renameSync, rmdirSync, unlinkSync, writeFileSync, } from "node:fs";
+import { join } from "node:path";
+import { redactDeep } from "../security/redact.js";
+export const SCHEMA_VERSION = 1;
+/** Directory 0700, files 0600: no other user on the machine needs this. */
+const DIR_MODE = 0o700;
+const FILE_MODE = 0o600;
+export class SessionStoreError extends Error {
+}
+/** Time-ordered and collision-resistant, without pulling in a ulid package. */
+export function newSessionId(now = Date.now()) {
+    const time = now.toString(36).padStart(9, "0");
+    let random = "";
+    for (let i = 0; i < 10; i += 1) {
+        random += "0123456789abcdefghijklmnopqrstuvwxyz"[Math.floor(Math.random() * 36)];
+    }
+    return `ses_${time}${random}`;
+}
+/**
+ * Refuse a path that is a symlink, and create directories with tight modes.
+ *
+ * A symlinked session directory is how someone else's file gets appended to,
+ * or how a transcript gets written somewhere world-readable.
+ */
+function ensureDirectory(path) {
+    mkdirSync(path, { recursive: true, mode: DIR_MODE });
+    assertNotLink(path);
+}
+function assertNotLink(path) {
+    let stats;
+    try {
+        stats = lstatSync(path);
+    }
+    catch {
+        return; // Does not exist yet; nothing to impersonate.
+    }
+    if (stats.isSymbolicLink()) {
+        throw new SessionStoreError(`refusing to use ${path}: it is a symbolic link`);
+    }
+}
+/**
+ * A session being written to.
+ *
+ * Held open for the life of the process. Every append is a complete line
+ * followed by a metadata refresh, so a crash leaves a readable store.
+ */
+export class SessionWriter {
+    directory;
+    meta;
+    now;
+    seq = 0;
+    closed = false;
+    constructor(directory, meta, now) {
+        this.directory = directory;
+        this.meta = meta;
+        this.now = now;
+    }
+    static create(options) {
+        const now = options.now ?? (() => new Date());
+        const sessionId = options.sessionId ?? newSessionId();
+        const directory = join(options.root, sessionId);
+        assertNotLink(options.root);
+        ensureDirectory(directory);
+        const timestamp = now().toISOString();
+        const meta = {
+            schema_version: SCHEMA_VERSION,
+            session_id: sessionId,
+            title: options.title,
+            created_at: timestamp,
+            updated_at: timestamp,
+            model_id: options.modelId,
+            workspace: options.workspace,
+            mode: options.mode,
+            message_count: 0,
+            model_requests: 0,
+            prompt_tokens: 0,
+            completion_tokens: 0,
+            estimated_charge_micro_usd: "0",
+        };
+        const writer = new SessionWriter(directory, meta, now);
+        writer.writeMetadata();
+        return writer;
+    }
+    /**
+     * Continue writing to a session that already exists.
+     *
+     * The sequence picks up from the last complete event, so a resumed session
+     * is one file rather than two - and a partial last line from an earlier
+     * crash is simply written past, since `readSession` already ignores it.
+     */
+    static reopen(directory, now) {
+        assertNotLink(directory);
+        const existing = readSession(directory);
+        const writer = new SessionWriter(directory, { ...existing.metadata }, now ?? (() => new Date()));
+        writer.seq = existing.events.reduce((highest, event) => Math.max(highest, event.seq), 0);
+        return writer;
+    }
+    get sessionId() {
+        return this.meta.session_id;
+    }
+    get metadata() {
+        return this.meta;
+    }
+    /**
+     * Append one event.
+     *
+     * Redacted first, and deliberately at this boundary rather than at each call
+     * site: a single place to be right about, and no way for a new event type to
+     * be added that forgets.
+     */
+    append(event) {
+        if (this.closed)
+            throw new SessionStoreError("session is closed");
+        this.seq += 1;
+        const stored = {
+            seq: this.seq,
+            ...redactDeep(event),
+        };
+        const line = `${JSON.stringify(stored)}\n`;
+        const path = join(this.directory, "events.jsonl");
+        assertNotLink(path);
+        appendFileSync(path, line, { mode: FILE_MODE });
+        this.touch(event);
+        return stored;
+    }
+    touch(event) {
+        // Reconciling is bookkeeping about a past request, not new activity: it
+        // adds no message and no request, and bumping `updated_at` would push the
+        // session to the top of a list ordered by when it was last *used*.
+        if (event.type === "settlement")
+            return;
+        if (event.type === "user_message" || event.type === "assistant_message") {
+            this.meta.message_count += 1;
+        }
+        if (event.type === "usage") {
+            this.meta.model_requests += 1;
+            this.meta.prompt_tokens += event.prompt_tokens;
+            this.meta.completion_tokens += event.completion_tokens;
+            // Money stays integral: strings in, BigInt to add, string out.
+            this.meta.estimated_charge_micro_usd = (BigInt(this.meta.estimated_charge_micro_usd) +
+                BigInt(event.estimated_charge_micro_usd)).toString();
+        }
+        this.meta.updated_at = this.now().toISOString();
+        this.writeMetadata();
+    }
+    setTitle(title) {
+        this.meta.title = title;
+        this.meta.updated_at = this.now().toISOString();
+        this.writeMetadata();
+    }
+    close() {
+        this.closed = true;
+    }
+    /** Temp file plus rename: a crash never leaves half a metadata document. */
+    writeMetadata() {
+        const target = join(this.directory, "metadata.json");
+        const temp = join(this.directory, `.metadata.${process.pid}.tmp`);
+        try {
+            writeFileSync(temp, `${JSON.stringify(this.meta, null, 2)}\n`, {
+                mode: FILE_MODE,
+            });
+            renameSync(temp, target);
+        }
+        catch (error) {
+            try {
+                unlinkSync(temp);
+            }
+            catch {
+                // May never have been created.
+            }
+            throw error;
+        }
+    }
+}
+/**
+ * Read a session back.
+ *
+ * A partial final line is dropped rather than treated as corruption: it is the
+ * expected result of being killed mid-append, and everything before it is
+ * still exactly what happened.
+ */
+export function readSession(directory) {
+    const metaPath = join(directory, "metadata.json");
+    let metadata;
+    try {
+        metadata = JSON.parse(readFileSync(metaPath, "utf8"));
+    }
+    catch (error) {
+        throw new SessionStoreError(`cannot read ${metaPath}: ${error instanceof Error ? error.message : String(error)}`);
+    }
+    if (typeof metadata.schema_version !== "number") {
+        throw new SessionStoreError(`${metaPath} has no schema_version`);
+    }
+    if (metadata.schema_version > SCHEMA_VERSION) {
+        throw new SessionStoreError(`${metaPath} was written by a newer version of the CLI (schema ${metadata.schema_version}); upgrade to read it`);
+    }
+    let raw = "";
+    try {
+        raw = readFileSync(join(directory, "events.jsonl"), "utf8");
+    }
+    catch {
+        return { metadata, events: [], truncatedTail: false };
+    }
+    const lines = raw.split("\n");
+    const trailing = lines.pop();
+    const truncatedTail = trailing !== undefined && trailing.length > 0;
+    const events = [];
+    for (const line of lines) {
+        if (line.length === 0)
+            continue;
+        try {
+            events.push(JSON.parse(line));
+        }
+        catch {
+            // One unreadable line does not invalidate the rest of the transcript.
+        }
+    }
+    return { metadata, events, truncatedTail };
+}
+/** Session directories present on disk, newest first by mtime of metadata. */
+export function listSessionDirectories(root) {
+    let entries;
+    try {
+        entries = readdirSync(root, { withFileTypes: true });
+    }
+    catch {
+        return [];
+    }
+    return entries
+        .filter((entry) => entry.isDirectory() && entry.name.startsWith("ses_"))
+        .map((entry) => join(root, entry.name))
+        .sort();
+}
+export function deleteSession(directory) {
+    assertNotLink(directory);
+    for (const name of ["events.jsonl", "metadata.json"]) {
+        try {
+            unlinkSync(join(directory, name));
+        }
+        catch {
+            // Already gone.
+        }
+    }
+    try {
+        // Anything else in there (a stale temp file) goes too, then the directory.
+        for (const entry of readdirSync(directory)) {
+            unlinkSync(join(directory, entry));
+        }
+    }
+    catch {
+        // Nothing left to remove.
+    }
+    try {
+        rmdirSync(directory);
+    }
+    catch {
+        // Leave it; listing filters on metadata anyway.
+    }
+}

package/dist/sessions/usage.d.ts

@@ -0,0 +1,35 @@
+import type { StoredEvent } from "./store.js";
+export type SettlementStatus = "settled" | "pending" | "unknown";
+export interface UsageTotals {
+    readonly modelRequests: number;
+    readonly promptTokens: number;
+    readonly completionTokens: number;
+    readonly estimatedMicroUsd: bigint;
+    /** Only the requests whose settled figure is actually known. */
+    readonly settledMicroUsd: bigint;
+    readonly bySettlement: Readonly<Record<SettlementStatus, number>>;
+}
+export interface UsageBreakdown extends UsageTotals {
+    /** Conversation shape, which is not the same as the request count (§20.2). */
+    readonly userMessages: number;
+    readonly toolRuns: number;
+    readonly toolRunsRefused: number;
+    /** 429s are waiting, not requests: counted apart so neither inflates. */
+    readonly rateLimitHits: number;
+    readonly rateLimitWaitMs: number;
+    readonly byModel: readonly (UsageTotals & {
+        readonly modelId: string;
+    })[];
+    readonly byKey: readonly (UsageTotals & {
+        readonly apiKeyRef: string;
+    })[];
+}
+export declare function summariseUsage(events: readonly StoredEvent[]): UsageBreakdown;
+/**
+ * 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 declare function settledCaveat(totals: UsageTotals): string | undefined;
+//# sourceMappingURL=usage.d.ts.map

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

@@ -0,0 +1 @@
+{"version":3,"file":"usage.d.ts","sourceRoot":"","sources":["../../src/sessions/usage.ts"],"names":[],"mappings":"AAeA,OAAO,KAAK,EAAE,WAAW,EAAE,MAAM,YAAY,CAAC;AAE9C,MAAM,MAAM,gBAAgB,GAAG,SAAS,GAAG,SAAS,GAAG,SAAS,CAAC;AAEjE,MAAM,WAAW,WAAW;IAC1B,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,gBAAgB,EAAE,MAAM,CAAC;IAClC,QAAQ,CAAC,iBAAiB,EAAE,MAAM,CAAC;IACnC,gEAAgE;IAChE,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,YAAY,EAAE,QAAQ,CAAC,MAAM,CAAC,gBAAgB,EAAE,MAAM,CAAC,CAAC,CAAC;CACnE;AAED,MAAM,WAAW,cAAe,SAAQ,WAAW;IACjD,8EAA8E;IAC9E,QAAQ,CAAC,YAAY,EAAE,MAAM,CAAC;IAC9B,QAAQ,CAAC,QAAQ,EAAE,MAAM,CAAC;IAC1B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,yEAAyE;IACzE,QAAQ,CAAC,aAAa,EAAE,MAAM,CAAC;IAC/B,QAAQ,CAAC,eAAe,EAAE,MAAM,CAAC;IACjC,QAAQ,CAAC,OAAO,EAAE,SAAS,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,OAAO,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;IAC1E,QAAQ,CAAC,KAAK,EAAE,SAAS,CAAC,WAAW,GAAG;QAAE,QAAQ,CAAC,SAAS,EAAE,MAAM,CAAA;KAAE,CAAC,EAAE,CAAC;CAC3E;AA2FD,wBAAgB,cAAc,CAAC,MAAM,EAAE,SAAS,WAAW,EAAE,GAAG,cAAc,CA6D7E;AAED;;;;;GAKG;AACH,wBAAgB,aAAa,CAAC,MAAM,EAAE,WAAW,GAAG,MAAM,GAAG,SAAS,CAQrE"}