@mafdet/cli 0.3.0

package/dist/agent/command-policy.js

@@ -0,0 +1,133 @@
+/**
+ * What a model is allowed to ask the machine to run.
+ *
+ * The central decision: there is no shell. A command is tokenised into argv
+ * and handed to execFile, so `;`, `&&`, backticks, `$(...)`, pipes and
+ * redirects have no meaning to anything downstream — there is nothing to
+ * inject into. Rather than accept them and try to sanitise, the policy refuses
+ * them and says why, because a sanitiser is a thing that can be wrong once.
+ */
+/** Shell syntax that would only make sense if a shell were involved. */
+const SHELL_METACHARACTERS = /[;&|`$><(){}\n\r]|\$\(|\|\|/;
+/** Refused outright, even with an approval and even on the allowlist. */
+const NEVER = [
+    { pattern: /^sudo$/i, reason: "sudo is never run by the agent" },
+    { pattern: /^su$/i, reason: "su is never run by the agent" },
+    { pattern: /^doas$/i, reason: "doas is never run by the agent" },
+    { pattern: /^chown$/i, reason: "changing ownership is out of scope" },
+    { pattern: /^shutdown$/i, reason: "power commands are out of scope" },
+    { pattern: /^reboot$/i, reason: "power commands are out of scope" },
+];
+/**
+ * Split a command line the way a shell would for simple cases: whitespace
+ * separates, quotes group. Anything more exotic is refused above, so this
+ * never has to be clever.
+ */
+export function tokenize(command) {
+    const tokens = [];
+    let current = "";
+    let quote;
+    let started = false;
+    for (const char of command) {
+        if (quote) {
+            if (char === quote)
+                quote = undefined;
+            else
+                current += char;
+            continue;
+        }
+        if (char === '"' || char === "'") {
+            quote = char;
+            started = true;
+            continue;
+        }
+        if (/\s/.test(char)) {
+            if (started || current.length > 0)
+                tokens.push(current);
+            current = "";
+            started = false;
+            continue;
+        }
+        current += char;
+    }
+    if (quote)
+        throw new Error("unbalanced quote");
+    if (started || current.length > 0)
+        tokens.push(current);
+    return tokens;
+}
+/**
+ * @param allowlist entries from `--allow-command`. An entry matches when it is
+ *   the whole command or a leading prefix of its tokens, so "pnpm test"
+ *   permits "pnpm test --filter x" but never "pnpm publish".
+ */
+export function assessCommand(command, allowlist = []) {
+    const trimmed = command.trim();
+    if (trimmed.length === 0)
+        return { ok: false, reason: "empty command" };
+    if (trimmed.includes("\0"))
+        return { ok: false, reason: "command contains a NUL byte" };
+    if (SHELL_METACHARACTERS.test(trimmed)) {
+        return {
+            ok: false,
+            reason: "shell syntax is not supported - commands run directly, without a shell, so pipes, redirects, chaining and substitution cannot be used. Run one program at a time.",
+        };
+    }
+    let argv;
+    try {
+        argv = tokenize(trimmed);
+    }
+    catch (error) {
+        return { ok: false, reason: error.message };
+    }
+    if (argv.length === 0)
+        return { ok: false, reason: "empty command" };
+    const program = argv[0];
+    if (program.startsWith("-")) {
+        return { ok: false, reason: "a command must start with a program name" };
+    }
+    // An absolute or relative path as the program would sidestep both the
+    // allowlist's intent and PATH; the workspace boundary does not cover exec.
+    if (program.includes("/") || program.includes("\\")) {
+        return {
+            ok: false,
+            reason: "run a program by name, not by path",
+        };
+    }
+    for (const rule of NEVER) {
+        if (rule.pattern.test(program))
+            return { ok: false, reason: rule.reason };
+    }
+    return { ok: true, argv, preApproved: matchesAllowlist(argv, allowlist) };
+}
+function matchesAllowlist(argv, allowlist) {
+    for (const entry of allowlist) {
+        let prefix;
+        try {
+            prefix = tokenize(entry.trim());
+        }
+        catch {
+            continue;
+        }
+        if (prefix.length === 0 || prefix.length > argv.length)
+            continue;
+        if (prefix.every((token, index) => token === argv[index]))
+            return true;
+    }
+    return false;
+}
+/** Terminal control sequences, stripped before any output is shown or sent. */
+export function stripAnsi(text) {
+    return (text
+        // CSI: ESC [ ... final byte - colours, cursor moves, screen clears.
+        .replace(/\u001b\[[0-?]*[ -/]*[@-~]/g, "")
+        // OSC: ESC ] ... BEL (or ST). The payload has to go too - stripping only
+        // the introducer would leave "0;retitled" sitting in the output.
+        .replace(/\u001b\][^\u0007\u001b]*(?:\u0007|\u001b\\)?/g, "")
+        // Other single-character escapes, including OSC introducers.
+        .replace(/\u001b[@-Z\\-_]/g, "")
+        // Remaining C0 controls. Tab, newline and carriage return survive; the
+        // rest can retitle a window, move the cursor or hide what follows, and a
+        // model's output is not a trusted source of terminal instructions.
+        .replace(/[\u0000-\u0008\u000b\u000c\u000e-\u001f\u007f]/g, ""));
+}

package/dist/agent/loop.d.ts

@@ -0,0 +1,107 @@
+import type { HttpClient } from "../api/http.js";
+import type { CatalogModel } from "../api/models.js";
+import type { Approver } from "./approvals.js";
+import { type ToolContext, type ToolDefinition } from "./tools/types.js";
+/** Plan §7.4. */
+export declare const DEFAULT_LIMITS: {
+    maxTurns: number;
+    maxWallClockMs: number;
+    /** Bounded 429 handling (§7.5): both the count and the total wait are capped. */
+    maxRateLimitRetries: number;
+    maxTotalWaitMs: number;
+    maxCostMicroUsd: bigint | undefined;
+};
+export type AgentLimits = typeof DEFAULT_LIMITS;
+export type StopReason = "completed" | "max_turns" | "timeout" | "max_cost" | "cancelled" | "rate_limited" | "error";
+export interface AgentReport {
+    stopReason: StopReason;
+    /** The model's last text answer, if it produced one. */
+    finalText: string;
+    turns: number;
+    modelRequests: number;
+    rateLimitHits: number;
+    totalWaitMs: number;
+    toolRuns: {
+        name: string;
+        ok: boolean;
+    }[];
+    promptTokens: number;
+    completionTokens: number;
+    costMicroUsd: bigint;
+    /** Set when the run ended because something failed. */
+    error?: string;
+}
+export interface AgentOptions {
+    client: HttpClient;
+    model: string;
+    /** Priced from the catalogue with the gateway's own arithmetic. */
+    pricing?: CatalogModel;
+    goal: string;
+    systemPrompt: string;
+    tools: ToolDefinition[];
+    toolContext: ToolContext;
+    /**
+     * Conversation carried across goals by an interactive session. Passed in, it
+     * is appended to in place, so the caller keeps the state and can compact it.
+     */
+    history?: ChatMessage[];
+    /** Asked before any tool that is not auto-approved. Defaults to refusing. */
+    approver?: Approver;
+    limits?: Partial<AgentLimits>;
+    signal?: AbortSignal;
+    /** Progress goes to stderr; the caller decides how to show it. */
+    onEvent?: (event: AgentEvent) => void;
+    /** Injected in tests to make backoff deterministic. */
+    sleep?: (ms: number) => Promise<void>;
+    now?: () => number;
+    random?: () => number;
+}
+export type AgentEvent = {
+    type: "turn";
+    turn: number;
+} | {
+    type: "tool";
+    name: string;
+    ok: boolean;
+    detail: string;
+} | {
+    type: "declined";
+    name: string;
+    summary: string;
+} | {
+    type: "text";
+    text: string;
+} | {
+    type: "rate_limited";
+    waitMs: number;
+    attempt: number;
+};
+export interface ChatMessage {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null;
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+}
+interface ToolCall {
+    id: string;
+    type: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+}
+/**
+ * The read-only agent loop.
+ *
+ * Two rules shape everything here. Model requests are strictly serial, so the
+ * key's RPM is never the thing that breaks a run. And a request that may
+ * already have been billed is never replayed: only an explicit 429 is
+ * retried, because CLI-001 measured that a throttled request writes a
+ * zero-charge ledger row, while a timeout or a 5xx may mean the model already
+ * generated an answer someone paid for.
+ */
+export declare function runAgent(options: AgentOptions): Promise<AgentReport>;
+/** Retry-After when the server gave one; otherwise exponential with jitter. */
+export declare function backoffMs(retryAfterSeconds: number | undefined, attempt: number, random?: () => number): number;
+export {};
+//# sourceMappingURL=loop.d.ts.map

package/dist/agent/loop.d.ts.map

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

package/dist/agent/loop.js

@@ -0,0 +1,242 @@
+import { ApiError } from "../api/errors.js";
+import { toolToJsonSchema, } from "./tools/types.js";
+/** Plan §7.4. */
+export const DEFAULT_LIMITS = {
+    maxTurns: 30,
+    maxWallClockMs: 30 * 60 * 1000,
+    /** Bounded 429 handling (§7.5): both the count and the total wait are capped. */
+    maxRateLimitRetries: 5,
+    maxTotalWaitMs: 120_000,
+    maxCostMicroUsd: undefined,
+};
+/**
+ * The read-only agent loop.
+ *
+ * Two rules shape everything here. Model requests are strictly serial, so the
+ * key's RPM is never the thing that breaks a run. And a request that may
+ * already have been billed is never replayed: only an explicit 429 is
+ * retried, because CLI-001 measured that a throttled request writes a
+ * zero-charge ledger row, while a timeout or a 5xx may mean the model already
+ * generated an answer someone paid for.
+ */
+export async function runAgent(options) {
+    const limits = { ...DEFAULT_LIMITS, ...options.limits };
+    const now = options.now ?? Date.now;
+    const sleep = options.sleep ?? ((ms) => new Promise((r) => setTimeout(r, ms)));
+    const random = options.random ?? Math.random;
+    const started = now();
+    const byName = new Map(options.tools.map((tool) => [tool.name, tool]));
+    const toolSchemas = options.tools.map(toolToJsonSchema);
+    const messages = options.history ?? [];
+    if (messages.length === 0) {
+        messages.push({ role: "system", content: options.systemPrompt });
+    }
+    messages.push({ role: "user", content: options.goal });
+    const report = {
+        stopReason: "completed",
+        finalText: "",
+        turns: 0,
+        modelRequests: 0,
+        rateLimitHits: 0,
+        totalWaitMs: 0,
+        toolRuns: [],
+        promptTokens: 0,
+        completionTokens: 0,
+        costMicroUsd: 0n,
+    };
+    for (let turn = 1; turn <= limits.maxTurns; turn += 1) {
+        if (options.signal?.aborted)
+            return stop(report, "cancelled");
+        if (now() - started > limits.maxWallClockMs)
+            return stop(report, "timeout");
+        if (limits.maxCostMicroUsd !== undefined &&
+            report.costMicroUsd >= limits.maxCostMicroUsd) {
+            return stop(report, "max_cost");
+        }
+        report.turns = turn;
+        options.onEvent?.({ type: "turn", turn });
+        let response;
+        try {
+            response = await requestWithRateLimitHandling(options, limits, {
+                model: options.model,
+                messages,
+                tools: toolSchemas,
+                tool_choice: "auto",
+            }, report, { sleep, now, random, started });
+        }
+        catch (error) {
+            if (error instanceof ApiError && error.kind === "cancelled") {
+                return stop(report, "cancelled");
+            }
+            if (error instanceof ApiError && error.kind === "rate_limited") {
+                return stop(report, "rate_limited", error.message);
+            }
+            return stop(report, "error", error instanceof Error ? error.message : String(error));
+        }
+        const usage = response.usage;
+        report.promptTokens += usage?.prompt_tokens ?? 0;
+        report.completionTokens += usage?.completion_tokens ?? 0;
+        // Cost comes from returned usage, never from the reservation: CLI-000B
+        // showed the reserve cannot see the tool schema and under-counts badly.
+        report.costMicroUsd += priceTurn(options.pricing, usage);
+        const choice = response.choices?.[0];
+        const message = choice?.message;
+        const calls = message?.tool_calls ?? [];
+        if (typeof message?.content === "string" && message.content.length > 0) {
+            report.finalText = message.content;
+            options.onEvent?.({ type: "text", text: message.content });
+        }
+        if (calls.length === 0) {
+            // Keep the answer in the history so a session's next turn has context.
+            messages.push({ role: "assistant", content: message?.content ?? "" });
+            return stop(report, "completed");
+        }
+        messages.push({
+            role: "assistant",
+            content: message?.content ?? null,
+            tool_calls: calls,
+        });
+        // Serial on purpose: two tools must never race on the same file, and a
+        // cancel between them must stop the rest.
+        for (const call of calls) {
+            if (options.signal?.aborted)
+                return stop(report, "cancelled");
+            const { text, ok } = await runToolCall(call, byName, options);
+            report.toolRuns.push({ name: call.function.name, ok });
+            options.onEvent?.({
+                type: "tool",
+                name: call.function.name,
+                ok,
+                detail: text,
+            });
+            messages.push({ role: "tool", tool_call_id: call.id, content: text });
+        }
+    }
+    return stop(report, "max_turns");
+}
+/**
+ * A tool failure is data for the model, not the end of the run: a bad path or
+ * a stale hash should come back as a structured message it can correct from
+ * (§7.2). What the model may never do is reach a tool that is not on the list.
+ */
+async function runToolCall(call, byName, options) {
+    const context = options.toolContext;
+    const tool = byName.get(call.function.name);
+    if (!tool) {
+        return {
+            ok: false,
+            text: `error: no such tool '${call.function.name}'. Available: ${[...byName.keys()].join(", ")}`,
+        };
+    }
+    let args;
+    try {
+        args = JSON.parse(call.function.arguments || "{}");
+    }
+    catch {
+        return { ok: false, text: "error: arguments were not valid JSON" };
+    }
+    const parsed = tool.schema.safeParse(args);
+    if (!parsed.success) {
+        return {
+            ok: false,
+            text: `error: invalid arguments: ${parsed.error.issues
+                .map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`)
+                .join("; ")}`,
+        };
+    }
+    try {
+        if (tool.autoApproved) {
+            if (!tool.run)
+                throw new Error(`${tool.name} has no implementation`);
+            return { ok: true, text: tool.run(parsed.data, context) };
+        }
+        if (!tool.prepare)
+            throw new Error(`${tool.name} cannot be approved`);
+        // Prepare first: this computes the diff and validates the edit without
+        // touching the disk, so a refusal below leaves nothing behind.
+        const action = tool.prepare(parsed.data, context);
+        // No approver means no writes. Failing closed here is what stops a
+        // miswired caller from turning a read-only run into a writing one.
+        // An action can carry advance approval - an --allow-command entry the user
+        // declared up front - which is the only way anything runs unprompted.
+        const approver = options.approver;
+        const approved = action.preApproved === true ||
+            (approver
+                ? await approver.approve({
+                    summary: action.summary,
+                    preview: action.preview,
+                })
+                : false);
+        if (!approved) {
+            options.onEvent?.({
+                type: "declined",
+                name: tool.name,
+                summary: action.summary,
+            });
+            return {
+                ok: false,
+                text: `the user declined: ${action.summary}. Nothing was changed or run. Do not retry the same action; ask what to do differently.`,
+            };
+        }
+        return { ok: true, text: await action.commit() };
+    }
+    catch (error) {
+        return { ok: false, text: `error: ${error.message}` };
+    }
+}
+async function requestWithRateLimitHandling(options, limits, body, report, clock) {
+    for (let attempt = 0;; attempt += 1) {
+        try {
+            report.modelRequests += 1;
+            const { data } = await options.client.postJson("/chat/completions", body, { signal: options.signal });
+            return data;
+        }
+        catch (error) {
+            // Everything except an explicit 429 propagates. A timeout or a 5xx may
+            // already have produced (and billed) a generation, so replaying it
+            // would risk paying twice for one answer.
+            if (!(error instanceof ApiError) || !error.retryable)
+                throw error;
+            report.rateLimitHits += 1;
+            if (attempt + 1 > limits.maxRateLimitRetries)
+                throw error;
+            const wait = backoffMs(error.retryAfterSeconds, attempt, clock.random);
+            if (report.totalWaitMs + wait > limits.maxTotalWaitMs)
+                throw error;
+            if (clock.now() - clock.started + wait > limits.maxWallClockMs)
+                throw error;
+            report.totalWaitMs += wait;
+            options.onEvent?.({
+                type: "rate_limited",
+                waitMs: wait,
+                attempt: attempt + 1,
+            });
+            await clock.sleep(wait);
+        }
+    }
+}
+/** Retry-After when the server gave one; otherwise exponential with jitter. */
+export function backoffMs(retryAfterSeconds, attempt, random = Math.random) {
+    if (retryAfterSeconds !== undefined && retryAfterSeconds >= 0) {
+        return Math.min(retryAfterSeconds * 1000, 60_000);
+    }
+    const base = Math.min(1000 * 2 ** attempt, 30_000);
+    // Full jitter: a fleet of CLIs must not retry in lockstep.
+    return Math.round(base * (0.5 + random() * 0.5));
+}
+function priceTurn(model, usage) {
+    if (!model?.inputPricePer1mMicroUsd ||
+        !model.outputPricePer1mMicroUsd ||
+        !usage) {
+        return 0n;
+    }
+    const ceilDiv = (tokens, price) => (BigInt(Math.max(0, tokens)) * BigInt(price) + 999999n) / 1000000n;
+    return (ceilDiv(usage.prompt_tokens ?? 0, model.inputPricePer1mMicroUsd) +
+        ceilDiv(usage.completion_tokens ?? 0, model.outputPricePer1mMicroUsd));
+}
+function stop(report, reason, error) {
+    report.stopReason = reason;
+    if (error)
+        report.error = error;
+    return report;
+}

package/dist/agent/session.d.ts

@@ -0,0 +1,62 @@
+import type { HttpClient } from "../api/http.js";
+import type { CatalogModel } from "../api/models.js";
+import type { Approver } from "./approvals.js";
+import { type ChatMessage } from "./loop.js";
+import type { ToolContext, ToolDefinition } from "./tools/types.js";
+export interface SessionOptions {
+    client: HttpClient;
+    model: string;
+    pricing?: CatalogModel;
+    /** Everything the catalogue says this key may drive, for /model. */
+    catalog: readonly CatalogModel[];
+    systemPrompt: string;
+    tools: ToolDefinition[];
+    toolContext: ToolContext;
+    approver?: Approver;
+    mode: string;
+    allowedCommands: readonly string[];
+    stdout: (text: string) => void;
+    stderr: (text: string) => void;
+    input?: NodeJS.ReadableStream;
+    /**
+     * Reads the next line, or undefined at end of input. Injected by tests;
+     * production wraps readline. Keeping this a function rather than a stream
+     * means the session's control flow can be tested without a terminal.
+     */
+    readLine?: () => Promise<string | undefined>;
+    signal?: AbortSignal;
+}
+export interface SessionSummary {
+    goals: number;
+    turns: number;
+    modelRequests: number;
+    toolRuns: number;
+    promptTokens: number;
+    completionTokens: number;
+    costMicroUsd: bigint;
+}
+/**
+ * The interactive session (plan §4.4).
+ *
+ * One conversation across many goals, so the agent keeps what it learned. The
+ * session owns the history — which is what makes /compact possible — and the
+ * running totals, so /cost and the closing summary describe the whole session
+ * rather than the last question.
+ */
+export declare function runSession(options: SessionOptions): Promise<SessionSummary>;
+/**
+ * Shorten the conversation in place.
+ *
+ * This truncates rather than summarising: a summary would cost a model call
+ * and could quietly invent detail. It keeps the system prompt and the opening
+ * goal, then cuts to the most recent user message.
+ *
+ * The cut must land on a user message. An assistant turn that carries
+ * `tool_calls` and its matching `tool` results form one indivisible unit — cut
+ * between them and the next request is rejected for referencing a tool call
+ * that is no longer there.
+ *
+ * @returns how many messages were removed.
+ */
+export declare function compactHistory(history: ChatMessage[]): number;
+//# sourceMappingURL=session.d.ts.map

package/dist/agent/session.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"session.d.ts","sourceRoot":"","sources":["../../src/agent/session.ts"],"names":[],"mappings":"AAEA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,gBAAgB,CAAC;AACjD,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,kBAAkB,CAAC;AAIrD,OAAO,KAAK,EAAE,QAAQ,EAAE,MAAM,gBAAgB,CAAC;AAC/C,OAAO,EAA6B,KAAK,WAAW,EAAE,MAAM,WAAW,CAAC;AACxE,OAAO,KAAK,EAAE,WAAW,EAAE,cAAc,EAAE,MAAM,kBAAkB,CAAC;AAapE,MAAM,WAAW,cAAc;IAC7B,MAAM,EAAE,UAAU,CAAC;IACnB,KAAK,EAAE,MAAM,CAAC;IACd,OAAO,CAAC,EAAE,YAAY,CAAC;IACvB,oEAAoE;IACpE,OAAO,EAAE,SAAS,YAAY,EAAE,CAAC;IACjC,YAAY,EAAE,MAAM,CAAC;IACrB,KAAK,EAAE,cAAc,EAAE,CAAC;IACxB,WAAW,EAAE,WAAW,CAAC;IACzB,QAAQ,CAAC,EAAE,QAAQ,CAAC;IACpB,IAAI,EAAE,MAAM,CAAC;IACb,eAAe,EAAE,SAAS,MAAM,EAAE,CAAC;IACnC,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,MAAM,EAAE,CAAC,IAAI,EAAE,MAAM,KAAK,IAAI,CAAC;IAC/B,KAAK,CAAC,EAAE,MAAM,CAAC,cAAc,CAAC;IAC9B;;;;OAIG;IACH,QAAQ,CAAC,EAAE,MAAM,OAAO,CAAC,MAAM,GAAG,SAAS,CAAC,CAAC;IAC7C,MAAM,CAAC,EAAE,WAAW,CAAC;CACtB;AAED,MAAM,WAAW,cAAc;IAC7B,KAAK,EAAE,MAAM,CAAC;IACd,KAAK,EAAE,MAAM,CAAC;IACd,aAAa,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,MAAM,CAAC;IACjB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;IACzB,YAAY,EAAE,MAAM,CAAC;CACtB;AAED;;;;;;;GAOG;AACH,wBAAsB,UAAU,CAC9B,OAAO,EAAE,cAAc,GACtB,OAAO,CAAC,cAAc,CAAC,CAwFzB;AAgHD;;;;;;;;;;;;;GAaG;AACH,wBAAgB,cAAc,CAAC,OAAO,EAAE,WAAW,EAAE,GAAG,MAAM,CA2B7D"}