@mafdet/cli 0.3.0

package/dist/agent/tools/run-command.js

@@ -0,0 +1,116 @@
+import { spawn } from "node:child_process";
+import { z } from "zod";
+import { assessCommand, stripAnsi } from "../command-policy.js";
+import { finishOutput } from "./read-only.js";
+/** Plan §7.4: a single local command gets two minutes. */
+export const COMMAND_TIMEOUT_MS = 120_000;
+const MAX_COMMAND_OUTPUT_BYTES = 256 * 1024;
+/**
+ * Run one program, with no shell and nothing inherited that it does not need.
+ *
+ * `detached` puts the child in its own process group so a timeout can kill the
+ * whole tree. Killing only the parent leaves the grandchildren running — the
+ * failure mode where a "timed out" test run keeps holding a port.
+ */
+export async function executeCommand(argv, cwd, timeoutMs = COMMAND_TIMEOUT_MS) {
+    return new Promise((resolve) => {
+        const child = spawn(argv[0], [...argv.slice(1)], {
+            cwd,
+            shell: false,
+            // Its own process group, so the timeout below can reach the whole tree.
+            // spawnSync cannot do this at all, which is why this is asynchronous.
+            detached: process.platform !== "win32",
+            // A deliberately small environment. The API key is the point: a test
+            // script, a postinstall hook or a compromised dependency must not read
+            // the user's credentials out of its own environment (plan §8.4).
+            env: {
+                PATH: process.env.PATH ?? "",
+                HOME: process.env.HOME ?? "",
+                LANG: process.env.LANG ?? "C",
+                CI: "1",
+            },
+        });
+        let output = "";
+        let truncated = false;
+        let timedOut = false;
+        const collect = (chunk) => {
+            if (truncated)
+                return;
+            output += chunk.toString("utf8");
+            if (Buffer.byteLength(output, "utf8") > MAX_COMMAND_OUTPUT_BYTES) {
+                output =
+                    output.slice(0, MAX_COMMAND_OUTPUT_BYTES) + "\n[output truncated]";
+                truncated = true;
+            }
+        };
+        child.stdout?.on("data", collect);
+        child.stderr?.on("data", collect);
+        const timer = setTimeout(() => {
+            timedOut = true;
+            killTree(child.pid);
+            // A process ignoring SIGTERM still has to go.
+            setTimeout(() => killTree(child.pid, "SIGKILL"), 2000).unref();
+        }, timeoutMs);
+        const finish = (code, signal) => {
+            clearTimeout(timer);
+            resolve({ code, signal, output: stripAnsi(output), timedOut });
+        };
+        child.on("error", (error) => finish(null, null));
+        child.on("close", (code, signal) => finish(code, signal));
+    });
+}
+/**
+ * Kill the whole process group, not just the child.
+ *
+ * Killing the parent alone leaves grandchildren running - the familiar case
+ * where a "timed out" test runner keeps holding a port. The negative pid is
+ * POSIX; Windows has no process groups in this sense, so there the direct
+ * child is killed and the limitation is stated rather than papered over
+ * (no Windows machine here to verify a taskkill /T path).
+ */
+function killTree(pid, signal = "SIGTERM") {
+    if (pid === undefined)
+        return;
+    try {
+        if (process.platform === "win32")
+            process.kill(pid, signal);
+        else
+            process.kill(-pid, signal);
+    }
+    catch {
+        // Already exited, or never became a group leader.
+    }
+}
+export const runCommandTool = {
+    name: "run_command",
+    description: "Run one program in the workspace, without a shell. No pipes, redirects or chaining; run a single program with arguments.",
+    autoApproved: false,
+    schema: z.object({
+        command: z
+            .string()
+            .min(1)
+            .describe("A single program with arguments, e.g. 'pnpm test --filter web'"),
+    }),
+    prepare(args, context) {
+        const verdict = assessCommand(args.command, context.allowedCommands ?? []);
+        if (!verdict.ok || !verdict.argv) {
+            throw new Error(verdict.reason ?? "command refused");
+        }
+        const argv = verdict.argv;
+        return {
+            summary: `run: ${argv.join(" ")}`,
+            preview: `cwd: ${context.workspace.root}\nenv: PATH, HOME, LANG, CI (no credentials)\ntimeout: ${COMMAND_TIMEOUT_MS / 1000}s`,
+            // An --allow-command entry is the user's advance approval; anything else
+            // is asked about every single time (plan §7.1: run_command is "每次确认").
+            preApproved: verdict.preApproved === true,
+            commit: async () => {
+                const result = await executeCommand(argv, context.workspace.root);
+                const status = result.timedOut
+                    ? `timed out after ${COMMAND_TIMEOUT_MS / 1000}s (process group killed)`
+                    : `exit ${result.code ?? "signal " + result.signal}`;
+                return finishOutput(`$ ${argv.join(" ")}\n${status}\n${result.output}`);
+            },
+        };
+    },
+};
+export const COMMAND_TOOLS = [runCommandTool];

package/dist/agent/tools/types.d.ts

@@ -0,0 +1,46 @@
+import { z } from "zod";
+import type { Workspace } from "../../filesystem/workspace.js";
+export interface ToolContext {
+    workspace: Workspace;
+    /** Injected in tests; production shells out to git. */
+    runGit?: (args: readonly string[], cwd: string) => string;
+    /** `--allow-command` entries: advance approval for exactly these commands. */
+    allowedCommands?: readonly string[];
+}
+/**
+ * What a non-auto-approved tool produces instead of acting: a description, a
+ * preview to show the user, and a commit closure the loop calls only after an
+ * approval. Nothing has touched the disk when this is returned.
+ */
+export interface PreparedAction {
+    summary: string;
+    preview: string;
+    /** The user approved this in advance (an allowlist entry); do not prompt. */
+    preApproved?: boolean;
+    commit(): string | Promise<string>;
+}
+export interface ToolDefinition<Schema extends z.ZodType = z.ZodType> {
+    name: string;
+    description: string;
+    schema: Schema;
+    /** Read-only tools run without asking; writes and shells never will. */
+    autoApproved: boolean;
+    /** Used for auto-approved tools. */
+    run?(args: z.infer<Schema>, context: ToolContext): string;
+    /** Required when `autoApproved` is false: plan, show, then commit. */
+    prepare?(args: z.infer<Schema>, context: ToolContext): PreparedAction;
+}
+/**
+ * The JSON Schema handed to the model, generated from the same Zod schema that
+ * validates what comes back — so the contract the model is shown and the
+ * contract enforced locally cannot drift apart.
+ */
+export declare function toolToJsonSchema(tool: ToolDefinition): {
+    type: "function";
+    function: {
+        name: string;
+        description: string;
+        parameters: unknown;
+    };
+};
+//# sourceMappingURL=types.d.ts.map

package/dist/agent/tools/types.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"types.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/types.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,CAAC,EAAE,MAAM,KAAK,CAAC;AAExB,OAAO,KAAK,EAAE,SAAS,EAAE,MAAM,+BAA+B,CAAC;AAE/D,MAAM,WAAW,WAAW;IAC1B,SAAS,EAAE,SAAS,CAAC;IACrB,uDAAuD;IACvD,MAAM,CAAC,EAAE,CAAC,IAAI,EAAE,SAAS,MAAM,EAAE,EAAE,GAAG,EAAE,MAAM,KAAK,MAAM,CAAC;IAC1D,8EAA8E;IAC9E,eAAe,CAAC,EAAE,SAAS,MAAM,EAAE,CAAC;CACrC;AAED;;;;GAIG;AACH,MAAM,WAAW,cAAc;IAC7B,OAAO,EAAE,MAAM,CAAC;IAChB,OAAO,EAAE,MAAM,CAAC;IAChB,6EAA6E;IAC7E,WAAW,CAAC,EAAE,OAAO,CAAC;IACtB,MAAM,IAAI,MAAM,GAAG,OAAO,CAAC,MAAM,CAAC,CAAC;CACpC;AAED,MAAM,WAAW,cAAc,CAAC,MAAM,SAAS,CAAC,CAAC,OAAO,GAAG,CAAC,CAAC,OAAO;IAClE,IAAI,EAAE,MAAM,CAAC;IACb,WAAW,EAAE,MAAM,CAAC;IACpB,MAAM,EAAE,MAAM,CAAC;IACf,wEAAwE;IACxE,YAAY,EAAE,OAAO,CAAC;IACtB,oCAAoC;IACpC,GAAG,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,MAAM,CAAC;IAC1D,sEAAsE;IACtE,OAAO,CAAC,CAAC,IAAI,EAAE,CAAC,CAAC,KAAK,CAAC,MAAM,CAAC,EAAE,OAAO,EAAE,WAAW,GAAG,cAAc,CAAC;CACvE;AAED;;;;GAIG;AACH,wBAAgB,gBAAgB,CAAC,IAAI,EAAE,cAAc,GAAG;IACtD,IAAI,EAAE,UAAU,CAAC;IACjB,QAAQ,EAAE;QAAE,IAAI,EAAE,MAAM,CAAC;QAAC,WAAW,EAAE,MAAM,CAAC;QAAC,UAAU,EAAE,OAAO,CAAA;KAAE,CAAC;CACtE,CASA"}

package/dist/agent/tools/types.js

@@ -0,0 +1,16 @@
+import { z } from "zod";
+/**
+ * The JSON Schema handed to the model, generated from the same Zod schema that
+ * validates what comes back — so the contract the model is shown and the
+ * contract enforced locally cannot drift apart.
+ */
+export function toolToJsonSchema(tool) {
+    return {
+        type: "function",
+        function: {
+            name: tool.name,
+            description: tool.description,
+            parameters: z.toJSONSchema(tool.schema, { io: "input" }),
+        },
+    };
+}

package/dist/agent/tools/write.d.ts

@@ -0,0 +1,3 @@
+import type { ToolDefinition } from "./types.js";
+export declare const WRITE_TOOLS: ToolDefinition[];
+//# sourceMappingURL=write.d.ts.map

package/dist/agent/tools/write.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"write.d.ts","sourceRoot":"","sources":["../../../src/agent/tools/write.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EAA+B,cAAc,EAAE,MAAM,YAAY,CAAC;AA8E9E,eAAO,MAAM,WAAW,EAAE,cAAc,EAA2B,CAAC"}

package/dist/agent/tools/write.js

@@ -0,0 +1,68 @@
+import { z } from "zod";
+import { planCreate, planEdit } from "../../filesystem/workspace.js";
+import { finishOutput } from "./read-only.js";
+/**
+ * The two write tools. Neither is auto-approved: the loop must route them
+ * through an approver, and the approver's default answer is no.
+ *
+ * They deliberately cannot overwrite a whole file. A model that has drifted
+ * from reality then fails on an unmatched `old_text` instead of silently
+ * replacing work it never read (plan §7.2).
+ */
+const editFile = {
+    name: "edit_file",
+    description: "Replace an exact, unique snippet in an existing file. old_text must appear exactly once; include surrounding lines to make it unique.",
+    autoApproved: false,
+    schema: z.object({
+        path: z.string().min(1).describe("Workspace-relative path"),
+        old_text: z
+            .string()
+            .min(1)
+            .describe("Exact text to replace, quoted from the file"),
+        new_text: z
+            .string()
+            .describe("Replacement text (may be empty to delete the snippet)"),
+    }),
+    prepare(args, context) {
+        const planned = planEdit(context.workspace, {
+            path: args.path,
+            oldText: args.old_text,
+            newText: args.new_text,
+        });
+        return {
+            summary: `edit ${planned.path}`,
+            preview: planned.diff,
+            commit: () => {
+                planned.apply();
+                return finishOutput(`edited ${planned.path}\n${planned.diff}`);
+            },
+        };
+    },
+};
+const createFile = {
+    name: "create_file",
+    description: "Create a new file. Fails if the path already exists.",
+    autoApproved: false,
+    schema: z.object({
+        path: z
+            .string()
+            .min(1)
+            .describe("Workspace-relative path that does not exist yet"),
+        content: z.string().describe("Full contents of the new file"),
+    }),
+    prepare(args, context) {
+        const planned = planCreate(context.workspace, {
+            path: args.path,
+            content: args.content,
+        });
+        return {
+            summary: `create ${planned.path}`,
+            preview: planned.diff,
+            commit: () => {
+                planned.apply();
+                return finishOutput(`created ${planned.path} (${args.content.length} characters)`);
+            },
+        };
+    },
+};
+export const WRITE_TOOLS = [editFile, createFile];

package/dist/api/account.d.ts

@@ -0,0 +1,39 @@
+import type { HttpClient } from "./http.js";
+/**
+ * The account plane (`backend.mafdet.ai/keyinfo/*`). Amounts arrive as integer
+ * micro-USD strings and stay strings all the way to the renderer.
+ */
+export interface Wallet {
+    balance_micro_usd: string;
+    bonus_micro_usd: string;
+    frozen_micro_usd: string;
+    available_micro_usd: string;
+    currency_anchor: string;
+}
+export interface UsageSummary {
+    days: number;
+    from: string;
+    to: string;
+    count: number;
+    input_tokens: number;
+    output_tokens: number;
+    total_tokens: number;
+    charge_micro_usd: string;
+}
+export interface Subscription {
+    status: string;
+    plan_slug?: string;
+    plan_name?: string;
+    current_period_end?: string;
+    playground?: {
+        allowance_micro_usd: string;
+        used_micro_usd: string;
+        remaining_micro_usd: string;
+        usage_percent: number;
+        state: string;
+    };
+}
+export declare function fetchWallet(client: HttpClient): Promise<Wallet>;
+export declare function fetchUsage(client: HttpClient, days?: number): Promise<UsageSummary>;
+export declare function fetchSubscription(client: HttpClient): Promise<Subscription>;
+//# sourceMappingURL=account.d.ts.map

package/dist/api/account.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"account.d.ts","sourceRoot":"","sources":["../../src/api/account.ts"],"names":[],"mappings":"AACA,OAAO,KAAK,EAAE,UAAU,EAAE,MAAM,WAAW,CAAC;AAE5C;;;GAGG;AAEH,MAAM,WAAW,MAAM;IACrB,iBAAiB,EAAE,MAAM,CAAC;IAC1B,eAAe,EAAE,MAAM,CAAC;IACxB,gBAAgB,EAAE,MAAM,CAAC;IACzB,mBAAmB,EAAE,MAAM,CAAC;IAC5B,eAAe,EAAE,MAAM,CAAC;CACzB;AAED,MAAM,WAAW,YAAY;IAC3B,IAAI,EAAE,MAAM,CAAC;IACb,IAAI,EAAE,MAAM,CAAC;IACb,EAAE,EAAE,MAAM,CAAC;IACX,KAAK,EAAE,MAAM,CAAC;IACd,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,EAAE,MAAM,CAAC;IACtB,YAAY,EAAE,MAAM,CAAC;IACrB,gBAAgB,EAAE,MAAM,CAAC;CAC1B;AAED,MAAM,WAAW,YAAY;IAC3B,MAAM,EAAE,MAAM,CAAC;IACf,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,kBAAkB,CAAC,EAAE,MAAM,CAAC;IAC5B,UAAU,CAAC,EAAE;QACX,mBAAmB,EAAE,MAAM,CAAC;QAC5B,cAAc,EAAE,MAAM,CAAC;QACvB,mBAAmB,EAAE,MAAM,CAAC;QAC5B,aAAa,EAAE,MAAM,CAAC;QACtB,KAAK,EAAE,MAAM,CAAC;KACf,CAAC;CACH;AAyBD,wBAAsB,WAAW,CAAC,MAAM,EAAE,UAAU,GAAG,OAAO,CAAC,MAAM,CAAC,CAKrE;AAED,wBAAsB,UAAU,CAC9B,MAAM,EAAE,UAAU,EAClB,IAAI,CAAC,EAAE,MAAM,GACZ,OAAO,CAAC,YAAY,CAAC,CAMvB;AAED,wBAAsB,iBAAiB,CACrC,MAAM,EAAE,UAAU,GACjB,OAAO,CAAC,YAAY,CAAC,CAKvB"}

package/dist/api/account.js

@@ -0,0 +1,39 @@
+import { ApiError } from "./errors.js";
+/**
+ * The account plane answers 401 with its own error shape when the key lacks
+ * `account:read`. That is a scope problem, not a bad key, and saying so saves
+ * the user from regenerating a key that was fine.
+ */
+function explainScope(error) {
+    if (error instanceof ApiError &&
+        (error.kind === "auth" || error.kind === "forbidden")) {
+        throw new ApiError({
+            kind: error.kind,
+            exitCode: error.exitCode,
+            status: error.status,
+            requestId: error.requestId,
+            message: "this key cannot read account data - it needs the 'account:read' scope. " +
+                "Model calls are unaffected; create a key with that scope to use `mafdet account`.",
+        });
+    }
+    throw error;
+}
+export async function fetchWallet(client) {
+    const { data } = await client
+        .getJson("/keyinfo/wallet")
+        .catch(explainScope);
+    return data;
+}
+export async function fetchUsage(client, days) {
+    const query = days === undefined ? "" : `?days=${days}`;
+    const { data } = await client
+        .getJson(`/keyinfo/usage-summary${query}`)
+        .catch(explainScope);
+    return data;
+}
+export async function fetchSubscription(client) {
+    const { data } = await client
+        .getJson("/keyinfo/subscription")
+        .catch(explainScope);
+    return data;
+}

package/dist/api/errors.d.ts

@@ -0,0 +1,38 @@
+import { ExitCode } from "../output/exit-codes.js";
+export type ApiErrorKind = "auth" | "forbidden" | "payment" | "rate_limited" | "request" | "server" | "timeout" | "cancelled" | "network" | "too_large";
+/**
+ * One error type for everything the API can do to us, carrying the decision a
+ * caller needs: which exit code, and whether replaying is safe.
+ */
+export declare class ApiError extends Error {
+    readonly kind: ApiErrorKind;
+    readonly status?: number;
+    readonly exitCode: ExitCode;
+    /** Only ever true for an explicit 429 (plan §7.5). */
+    readonly retryable: boolean;
+    readonly retryAfterSeconds?: number;
+    /** Mafdet's own error code, dug out of the nested payload when present. */
+    readonly code?: string;
+    /** Upstream correlation id, for support tickets. */
+    readonly requestId?: string;
+    constructor(init: {
+        kind: ApiErrorKind;
+        message: string;
+        status?: number;
+        exitCode: ExitCode;
+        retryable?: boolean;
+        retryAfterSeconds?: number;
+        code?: string;
+        requestId?: string;
+    });
+}
+/**
+ * Mafdet's guards answer with a JSON document stringified *into*
+ * `error.message`, so the machine-readable code is one parse deeper than the
+ * OpenAI shape suggests (CLI-001 §3).
+ */
+export declare function mafdetErrorCode(body: unknown): string | undefined;
+/** Seconds to wait, from a `Retry-After` that may be seconds or an HTTP date. */
+export declare function parseRetryAfter(header: string | null, now?: number): number | undefined;
+export declare function errorForResponse(status: number, body: unknown, headers: Headers, requestId?: string): ApiError;
+//# sourceMappingURL=errors.d.ts.map

package/dist/api/errors.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"errors.d.ts","sourceRoot":"","sources":["../../src/api/errors.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,QAAQ,EAAE,MAAM,yBAAyB,CAAC;AAGnD,MAAM,MAAM,YAAY,GACpB,MAAM,GACN,WAAW,GACX,SAAS,GACT,cAAc,GACd,SAAS,GACT,QAAQ,GACR,SAAS,GACT,WAAW,GACX,SAAS,GACT,WAAW,CAAC;AAEhB;;;GAGG;AACH,qBAAa,QAAS,SAAQ,KAAK;IACjC,QAAQ,CAAC,IAAI,EAAE,YAAY,CAAC;IAC5B,QAAQ,CAAC,MAAM,CAAC,EAAE,MAAM,CAAC;IACzB,QAAQ,CAAC,QAAQ,EAAE,QAAQ,CAAC;IAC5B,sDAAsD;IACtD,QAAQ,CAAC,SAAS,EAAE,OAAO,CAAC;IAC5B,QAAQ,CAAC,iBAAiB,CAAC,EAAE,MAAM,CAAC;IACpC,2EAA2E;IAC3E,QAAQ,CAAC,IAAI,CAAC,EAAE,MAAM,CAAC;IACvB,oDAAoD;IACpD,QAAQ,CAAC,SAAS,CAAC,EAAE,MAAM,CAAC;gBAEhB,IAAI,EAAE;QAChB,IAAI,EAAE,YAAY,CAAC;QACnB,OAAO,EAAE,MAAM,CAAC;QAChB,MAAM,CAAC,EAAE,MAAM,CAAC;QAChB,QAAQ,EAAE,QAAQ,CAAC;QACnB,SAAS,CAAC,EAAE,OAAO,CAAC;QACpB,iBAAiB,CAAC,EAAE,MAAM,CAAC;QAC3B,IAAI,CAAC,EAAE,MAAM,CAAC;QACd,SAAS,CAAC,EAAE,MAAM,CAAC;KACpB;CAcF;AAED;;;;GAIG;AACH,wBAAgB,eAAe,CAAC,IAAI,EAAE,OAAO,GAAG,MAAM,GAAG,SAAS,CAqBjE;AAmBD,iFAAiF;AACjF,wBAAgB,eAAe,CAC7B,MAAM,EAAE,MAAM,GAAG,IAAI,EACrB,GAAG,GAAE,MAAmB,GACvB,MAAM,GAAG,SAAS,CAOpB;AAED,wBAAgB,gBAAgB,CAC9B,MAAM,EAAE,MAAM,EACd,IAAI,EAAE,OAAO,EACb,OAAO,EAAE,OAAO,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,QAAQ,CAyDV"}

package/dist/api/errors.js

@@ -0,0 +1,149 @@
+import { ExitCode } from "../output/exit-codes.js";
+import { redact } from "../security/redact.js";
+/**
+ * One error type for everything the API can do to us, carrying the decision a
+ * caller needs: which exit code, and whether replaying is safe.
+ */
+export class ApiError extends Error {
+    kind;
+    status;
+    exitCode;
+    /** Only ever true for an explicit 429 (plan §7.5). */
+    retryable;
+    retryAfterSeconds;
+    /** Mafdet's own error code, dug out of the nested payload when present. */
+    code;
+    /** Upstream correlation id, for support tickets. */
+    requestId;
+    constructor(init) {
+        // Upstream messages quote the key prefix and its hash (CLI-001), so the
+        // message is redacted at construction — before it can be logged or thrown
+        // past a handler that forgets.
+        super(redact(init.message));
+        this.name = "ApiError";
+        this.kind = init.kind;
+        this.status = init.status;
+        this.exitCode = init.exitCode;
+        this.retryable = init.retryable ?? false;
+        this.retryAfterSeconds = init.retryAfterSeconds;
+        this.code = init.code;
+        this.requestId = init.requestId;
+    }
+}
+/**
+ * Mafdet's guards answer with a JSON document stringified *into*
+ * `error.message`, so the machine-readable code is one parse deeper than the
+ * OpenAI shape suggests (CLI-001 §3).
+ */
+export function mafdetErrorCode(body) {
+    // Third shape, found by running the real thing: mafdet's own request guards
+    // answer FastAPI-style, `{"detail": {"code": "TTS_VOICE_REQUIRED"}}` — no
+    // `error` object at all. Decoding only the OpenAI shape turned a precise,
+    // actionable reason into "request rejected (400)".
+    const detail = body?.detail;
+    if (detail && typeof detail === "object") {
+        const code = detail.code;
+        if (typeof code === "string")
+            return code;
+    }
+    const message = body?.error?.message;
+    if (typeof message !== "string" || !message.trimStart().startsWith("{")) {
+        return undefined;
+    }
+    try {
+        const inner = JSON.parse(message);
+        return typeof inner.code === "string" ? inner.code : undefined;
+    }
+    catch {
+        return undefined;
+    }
+}
+function messageOf(body, fallback) {
+    const openai = body?.error?.message;
+    if (typeof openai === "string" && openai.length > 0)
+        return openai;
+    // FastAPI-shaped guard rejections: a bare string, or an object whose code is
+    // the whole story.
+    const detail = body?.detail;
+    if (typeof detail === "string" && detail.length > 0)
+        return detail;
+    if (detail && typeof detail === "object") {
+        const code = detail.code;
+        if (typeof code === "string")
+            return code;
+    }
+    // The account plane uses its own shape: { error_code, message }.
+    const business = body?.message;
+    if (typeof business === "string" && business.length > 0)
+        return business;
+    return fallback;
+}
+/** Seconds to wait, from a `Retry-After` that may be seconds or an HTTP date. */
+export function parseRetryAfter(header, now = Date.now()) {
+    if (!header)
+        return undefined;
+    const seconds = Number(header.trim());
+    if (Number.isFinite(seconds) && seconds >= 0)
+        return seconds;
+    const at = Date.parse(header);
+    if (Number.isNaN(at))
+        return undefined;
+    return Math.max(0, Math.round((at - now) / 1000));
+}
+export function errorForResponse(status, body, headers, requestId) {
+    const code = mafdetErrorCode(body);
+    const base = { status, code, requestId };
+    if (status === 401) {
+        return new ApiError({
+            ...base,
+            kind: "auth",
+            exitCode: ExitCode.Auth,
+            message: messageOf(body, "authentication failed - check MAFDET_API_KEY"),
+        });
+    }
+    if (status === 403) {
+        return new ApiError({
+            ...base,
+            kind: "forbidden",
+            exitCode: ExitCode.Auth,
+            // 403 covers both "your key may not call this model" and a mistyped id:
+            // the allowlist is checked before the id is resolved (CLI-001), so the
+            // caller must compare against its own model list before blaming either.
+            message: messageOf(body, "this key may not use that model"),
+        });
+    }
+    if (status === 402) {
+        return new ApiError({
+            ...base,
+            kind: "payment",
+            exitCode: ExitCode.Auth,
+            message: messageOf(body, "insufficient balance"),
+        });
+    }
+    if (status === 429) {
+        return new ApiError({
+            ...base,
+            kind: "rate_limited",
+            exitCode: ExitCode.Unavailable,
+            retryable: true,
+            retryAfterSeconds: parseRetryAfter(headers.get("retry-after")),
+            message: messageOf(body, "rate limited"),
+        });
+    }
+    if (status >= 500) {
+        return new ApiError({
+            ...base,
+            kind: "server",
+            exitCode: ExitCode.Unavailable,
+            // Deliberately not retryable: the upstream may already be generating,
+            // and generation costs money (plan §7.5).
+            message: messageOf(body, `upstream error (${status})`),
+        });
+    }
+    return new ApiError({
+        ...base,
+        kind: "request",
+        exitCode: ExitCode.Usage,
+        message: messageOf(body, `request rejected (${status})`),
+    });
+}

package/dist/api/http.d.ts

@@ -0,0 +1,63 @@
+export declare const DEFAULT_TIMEOUT_MS = 120000;
+/** A JSON answer this large is a bug or an attack, not a model reply. */
+export declare const DEFAULT_MAX_BYTES: number;
+export interface HttpClientOptions {
+    baseUrl: string;
+    apiKey?: string;
+    userAgent: string;
+    timeoutMs?: number;
+    maxBytes?: number;
+    /** Injectable for tests. */
+    fetchImpl?: typeof fetch;
+}
+export interface RequestOptions {
+    /** Caller's cancellation (Ctrl+C); combined with the timeout. */
+    signal?: AbortSignal;
+    timeoutMs?: number;
+    maxBytes?: number;
+    headers?: Record<string, string>;
+}
+export interface HttpResponse<T> {
+    data: T;
+    status: number;
+    headers: Headers;
+    /** Server-side correlation id when the gateway returns one. */
+    requestId?: string;
+}
+/**
+ * The one place that talks to the network.
+ *
+ * It deliberately does NOT retry. Only an explicit 429 is even retryable, and
+ * the decision belongs to the caller that knows whether replaying is safe —
+ * a timeout or a 5xx may mean the model already started generating, and
+ * generation is already billed (plan §7.5).
+ */
+export declare class HttpClient {
+    private readonly baseUrl;
+    private readonly apiKey?;
+    private readonly userAgent;
+    private readonly timeoutMs;
+    private readonly maxBytes;
+    private readonly fetchImpl;
+    constructor(options: HttpClientOptions);
+    getJson<T>(path: string, options?: RequestOptions): Promise<HttpResponse<T>>;
+    postJson<T>(path: string, body: unknown, options?: RequestOptions): Promise<HttpResponse<T>>;
+    /** For `/v1/audio/speech`, which answers with audio bytes. */
+    postBinary(path: string, body: unknown, options?: RequestOptions): Promise<HttpResponse<Uint8Array>>;
+    /** Raw streaming response, for the SSE reader to consume. */
+    postStream(path: string, body: unknown, options?: RequestOptions): Promise<{
+        response: Response;
+        requestId?: string;
+    }>;
+    private send;
+    private readJson;
+    private errorFrom;
+}
+/**
+ * Read a body while counting bytes, so an endless or oversized response is cut
+ * off rather than filling memory. Content-Length is checked first when it is
+ * present, but the running count is what actually enforces the cap — a
+ * streaming body may not declare a length.
+ */
+export declare function readCapped(response: Response, maxBytes: number, requestId?: string): Promise<Uint8Array>;
+//# sourceMappingURL=http.d.ts.map

package/dist/api/http.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"http.d.ts","sourceRoot":"","sources":["../../src/api/http.ts"],"names":[],"mappings":"AAKA,eAAO,MAAM,kBAAkB,SAAU,CAAC;AAC1C,yEAAyE;AACzE,eAAO,MAAM,iBAAiB,QAAmB,CAAC;AAElD,MAAM,WAAW,iBAAiB;IAChC,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,CAAC,EAAE,MAAM,CAAC;IAChB,SAAS,EAAE,MAAM,CAAC;IAClB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,4BAA4B;IAC5B,SAAS,CAAC,EAAE,OAAO,KAAK,CAAC;CAC1B;AAED,MAAM,WAAW,cAAc;IAC7B,iEAAiE;IACjE,MAAM,CAAC,EAAE,WAAW,CAAC;IACrB,SAAS,CAAC,EAAE,MAAM,CAAC;IACnB,QAAQ,CAAC,EAAE,MAAM,CAAC;IAClB,OAAO,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,MAAM,CAAC,CAAC;CAClC;AAED,MAAM,WAAW,YAAY,CAAC,CAAC;IAC7B,IAAI,EAAE,CAAC,CAAC;IACR,MAAM,EAAE,MAAM,CAAC;IACf,OAAO,EAAE,OAAO,CAAC;IACjB,+DAA+D;IAC/D,SAAS,CAAC,EAAE,MAAM,CAAC;CACpB;AAED;;;;;;;GAOG;AACH,qBAAa,UAAU;IACrB,OAAO,CAAC,QAAQ,CAAC,OAAO,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,MAAM,CAAC,CAAS;IACjC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAe;gBAE7B,OAAO,EAAE,iBAAiB;IAShC,OAAO,CAAC,CAAC,EACb,IAAI,EAAE,MAAM,EACZ,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAKrB,QAAQ,CAAC,CAAC,EACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,CAAC,CAAC,CAAC;IAK3B,8DAA8D;IACxD,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC,YAAY,CAAC,UAAU,CAAC,CAAC;IAiBpC,6DAA6D;IACvD,UAAU,CACd,IAAI,EAAE,MAAM,EACZ,IAAI,EAAE,OAAO,EACb,OAAO,GAAE,cAAmB,GAC3B,OAAO,CAAC;QAAE,QAAQ,EAAE,QAAQ,CAAC;QAAC,SAAS,CAAC,EAAE,MAAM,CAAA;KAAE,CAAC;YASxC,IAAI;YA4DJ,QAAQ;YAuCR,SAAS;CAexB;AAED;;;;;GAKG;AACH,wBAAsB,UAAU,CAC9B,QAAQ,EAAE,QAAQ,EAClB,QAAQ,EAAE,MAAM,EAChB,SAAS,CAAC,EAAE,MAAM,GACjB,OAAO,CAAC,UAAU,CAAC,CAkCrB"}