@clutor/cli 0.0.0-stage → 0.1.0

package/dist/index.d.ts

@@ -0,0 +1,615 @@
+import { Receipt, MemoryPlan, LlmClient, GateResult, StreamMetrics, ModelLayout, GgufFile, ShadowWorkspace, AgentEvent, AgentResult, FileDiff } from '@clutor/core';
+import { z } from 'zod';
+import { Server } from 'node:http';
+import { NodeProject } from '@clutor/core/node';
+export { ConflictError } from '@clutor/core/node';
+
+interface ParsedArgs {
+    positional: string[];
+    flags: Map<string, string | true>;
+}
+/** Tiny `--flag value` / `--flag=value` / `--bool` parser. `booleans` lists flags that never take a value. */
+declare function parseArgs(argv: string[], booleans?: readonly string[]): ParsedArgs;
+declare const flagString: (a: ParsedArgs, name: string) => string | undefined;
+declare const flagBool: (a: ParsedArgs, name: string) => boolean;
+declare function flagInt(a: ParsedArgs, name: string, min: number, max: number): number | undefined;
+declare class UsageError extends Error {
+    constructor(message: string);
+}
+
+interface DecideEndpoint {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+}
+interface DecideResult {
+    choice: string;
+    probabilities: Record<string, number>;
+    probabilityMassOnChoices: number;
+    latencyMs: number;
+}
+/** The request was wrong (400) or the model server could not answer it (502). */
+declare class DecideError extends Error {
+    readonly status: 400 | 502;
+    constructor(status: 400 | 502, message: string);
+}
+/**
+ * One forward pass, one token: the model's own probability for each choice's letter, read from the first-token log-probabilities.
+ * Not calibrated. Shared by `clutor decide` and `POST /v1/decide`.
+ */
+declare function runDecide(e: DecideEndpoint, prompt: string, choices: string[], f?: typeof fetch): Promise<DecideResult>;
+/**
+ * Signs a decision into the project's receipt log, so it chains with the agent's receipts. The receipt records a SHA-256 of the prompt, not the
+ * prompt itself, because the log is meant to be shared for verification.
+ */
+declare function sealDecision(root: string, model: string, prompt: string, choices: string[], r: DecideResult, startedAt: string): Promise<Receipt>;
+
+declare function findLlamaServer(env?: NodeJS.ProcessEnv, extraDirs?: string[]): string | null;
+interface LlamaCapabilities {
+    flags: Set<string>;
+    /** `--flash-attn on|off|auto` (newer builds) rather than a bare `--flash-attn` switch. */
+    flashAttnTakesValue: boolean;
+    helpText: string;
+}
+/** Runs `llama-server --help` and records which options this build knows, so unsupported flags are never passed. */
+declare function probeLlamaServer(binary: string, timeoutMs?: number): Promise<LlamaCapabilities>;
+interface LlamaArgsInput {
+    modelPath: string;
+    port: number;
+    contextTokens: number;
+    kvBits: 16 | 8 | 4;
+    threads?: number;
+    plan?: Pick<MemoryPlan, "strategy">;
+    caps: LlamaCapabilities;
+    extraArgs?: string[];
+    /** Where llama-server may save and restore KV-cache snapshots. */
+    slotSavePath?: string;
+}
+declare function buildLlamaArgs(i: LlamaArgsInput): {
+    args: string[];
+    notes: string[];
+};
+type BackendState = "stopped" | "starting" | "ready" | "failed";
+declare class BackendManager {
+    readonly port: number;
+    private readonly fetchFn;
+    state: BackendState;
+    error: string | null;
+    private child;
+    private readonly log;
+    private readonly listeners;
+    constructor(port: number, fetchFn?: typeof globalThis.fetch);
+    get baseUrl(): string;
+    get recentLog(): string[];
+    onState(f: (s: BackendState) => void): () => void;
+    private set;
+    start(binary: string, args: string[], opts?: {
+        readyTimeoutMs?: number;
+        env?: NodeJS.ProcessEnv;
+    }): Promise<void>;
+    stop(): Promise<void>;
+}
+/**
+ * Saves and restores a llama-server slot's KV cache (POST /slots/<id>?action=save|restore). Used so the project map and instructions,
+ * which every agent step starts with, are not recomputed on the next run. Every call is best effort: a refusal just means a slower first step.
+ */
+declare class SlotSnapshots {
+    private readonly baseUrl;
+    private readonly slot;
+    private readonly fetchFn;
+    readonly stats: {
+        restored: number;
+        saved: number;
+        restoreMisses: number;
+        failures: number;
+    };
+    constructor(baseUrl: string, slot?: number, fetchFn?: typeof globalThis.fetch);
+    private url;
+    private post;
+    restore(name: string): Promise<boolean>;
+    save(name: string): Promise<boolean>;
+}
+/** Wraps a model client so the shared prefix (instructions + project map) is restored before the first call and saved after it. */
+declare function withPrefixSnapshots(inner: LlmClient, snaps: SlotSnapshots): LlmClient & {
+    snapshots: SlotSnapshots;
+};
+
+declare const CONFIG_FILE = "clutor.config.json";
+declare const DEFAULT_PORT = 4320;
+declare const ConfigSchema: z.ZodObject<{
+    port: z.ZodDefault<z.ZodNumber>;
+    host: z.ZodDefault<z.ZodString>;
+    models: z.ZodDefault<z.ZodString>;
+    backend: z.ZodDefault<z.ZodObject<{
+        kind: z.ZodDefault<z.ZodEnum<{
+            none: "none";
+            openai: "openai";
+            "llama-server": "llama-server";
+        }>>;
+        baseUrl: z.ZodOptional<z.ZodString>;
+        model: z.ZodOptional<z.ZodString>;
+        apiKeyEnv: z.ZodOptional<z.ZodString>;
+        llamaServer: z.ZodDefault<z.ZodObject<{
+            binary: z.ZodOptional<z.ZodString>;
+            model: z.ZodOptional<z.ZodString>;
+            port: z.ZodDefault<z.ZodNumber>;
+            threads: z.ZodOptional<z.ZodNumber>;
+            extraArgs: z.ZodDefault<z.ZodArray<z.ZodString>>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    memory: z.ZodDefault<z.ZodObject<{
+        ramCeilingGiB: z.ZodOptional<z.ZodNumber>;
+        osHeadroomGiB: z.ZodOptional<z.ZodNumber>;
+        contextTokens: z.ZodDefault<z.ZodNumber>;
+        kvBits: z.ZodDefault<z.ZodUnion<readonly [z.ZodLiteral<16>, z.ZodLiteral<8>, z.ZodLiteral<4>]>>;
+        diskGBps: z.ZodOptional<z.ZodNumber>;
+    }, z.core.$strict>>;
+    cache: z.ZodDefault<z.ZodObject<{
+        policy: z.ZodDefault<z.ZodEnum<{
+            lru: "lru";
+            wtinylfu: "wtinylfu";
+            adaptive: "adaptive";
+        }>>;
+        smartRoute: z.ZodDefault<z.ZodObject<{
+            enabled: z.ZodDefault<z.ZodBoolean>;
+            maxSubstitutions: z.ZodDefault<z.ZodNumber>;
+            candidates: z.ZodDefault<z.ZodNumber>;
+            maxDeltaP: z.ZodDefault<z.ZodNumber>;
+        }, z.core.$strict>>;
+    }, z.core.$strict>>;
+    agent: z.ZodDefault<z.ZodObject<{
+        toolMode: z.ZodDefault<z.ZodEnum<{
+            json: "json";
+            native: "native";
+        }>>;
+        maxSteps: z.ZodDefault<z.ZodNumber>;
+        verifyCommand: z.ZodOptional<z.ZodString>;
+        autoApproveProjectCommands: z.ZodDefault<z.ZodBoolean>;
+        commandTimeoutSeconds: z.ZodDefault<z.ZodNumber>;
+        constrainToolCalls: z.ZodDefault<z.ZodBoolean>;
+        prefixSnapshots: z.ZodDefault<z.ZodBoolean>;
+    }, z.core.$strict>>;
+    corsOrigins: z.ZodDefault<z.ZodArray<z.ZodString>>;
+}, z.core.$strict>;
+type ClutorConfig = z.infer<typeof ConfigSchema>;
+declare class ConfigError extends Error {
+    constructor(message: string);
+}
+declare function loadConfig(dir: string, file?: string): {
+    config: ClutorConfig;
+    path: string | null;
+    root: string;
+};
+
+declare function table(rows: string[][], header?: string[]): string;
+declare const pct: (x: number) => string;
+declare const tps: (x: number) => string;
+declare function formatPlan(name: string, quant: string | undefined, p: MemoryPlan): string;
+declare function formatGates(g: GateResult[]): string;
+declare function formatSimulation(base: StreamMetrics, c: StreamMetrics): string;
+
+interface ResolvedModel {
+    id: string;
+    name: string;
+    source: "catalog" | "file";
+    path?: string;
+    layout: ModelLayout;
+    gguf?: GgufFile;
+    quant?: string;
+}
+declare class ModelError extends Error {
+    constructor(message: string);
+}
+/** `deepseek-v3`, `deepseek-v3@Q4_K_M`, or the path of a .gguf file. */
+declare function resolveModel(ref: string, opts?: {
+    modelsDir?: string;
+    allowFiles?: boolean;
+}): Promise<ResolvedModel>;
+interface LocalModel {
+    file: string;
+    path: string;
+    bytes: number;
+}
+declare function listLocalModels(dir: string): Promise<LocalModel[]>;
+/**
+ * Real models small enough to download and test with. Sizes are the file sizes Hugging Face reported on 2026-10-30; the download
+ * is checked against the size the server announces, and nothing is fetched unless you run `clutor pull`.
+ */
+interface Download {
+    id: string;
+    catalogId: string;
+    repo: string;
+    file: string;
+    bytes: number;
+    note: string;
+}
+declare const DOWNLOADS: Download[];
+declare const downloadUrl: (d: Download) => string;
+declare class DownloadError extends Error {
+    constructor(message: string);
+}
+/** Downloads `url` to `dest` through a `.part` file, refusing to start without room for it and refusing a size the server did not announce. */
+declare function downloadFile(url: string, dest: string, opts?: {
+    fetch?: typeof fetch;
+    expectedBytes?: number;
+    onProgress?: (done: number, total: number) => void;
+}): Promise<number>;
+
+/** Translation between the Ollama HTTP API and an OpenAI-compatible backend, so tools that speak Ollama can use whatever Clutor fronts. */
+interface OllamaMessage {
+    role: string;
+    content: string;
+}
+interface OllamaChatRequest {
+    model?: string;
+    messages?: OllamaMessage[];
+    prompt?: string;
+    system?: string;
+    stream?: boolean;
+    options?: {
+        temperature?: number;
+        num_predict?: number;
+        top_p?: number;
+        stop?: string[];
+    };
+}
+declare function toOpenAiBody(req: OllamaChatRequest, model: string, kind: "chat" | "generate"): Record<string, unknown>;
+/** Converts one non-streaming OpenAI reply into one Ollama reply. */
+declare function fromOpenAiReply(kind: "chat" | "generate", model: string, body: {
+    choices?: Array<{
+        message?: {
+            content?: string | null;
+        };
+        finish_reason?: string;
+    }>;
+    usage?: {
+        prompt_tokens?: number;
+        completion_tokens?: number;
+    };
+}): Record<string, unknown>;
+/** Converts an OpenAI event stream into Ollama's newline-delimited JSON. */
+declare function streamToOllama(kind: "chat" | "generate", model: string, body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+
+/**
+ * One agent task, held in memory so a UI can watch it (events are kept and replayed to late subscribers), approve commands it wants to
+ * run, and then apply or discard what it did. Nothing reaches the project folder until `apply`.
+ */
+type SessionEvent = AgentEvent | {
+    type: "approval";
+    requestId: string;
+    command: string;
+    network: boolean;
+} | {
+    type: "approval_resolved";
+    requestId: string;
+    allowed: boolean;
+} | {
+    type: "applied";
+    checkpointId: string;
+    files: number;
+} | {
+    type: "rolled_back";
+    checkpointId: string;
+};
+interface SessionInfo {
+    id: string;
+    dir: string;
+    task: string;
+    status: "running" | "finished" | "max_steps" | "aborted" | "stuck" | "error";
+    startedAt: string;
+    result?: AgentResult;
+    diffs: FileDiff[];
+    pendingApprovals: Array<{
+        requestId: string;
+        command: string;
+        network: boolean;
+    }>;
+    checkpointId?: string;
+    gates: GateResult[];
+}
+declare class AgentSession {
+    readonly dir: string;
+    readonly task: string;
+    readonly project: NodeProject;
+    readonly ws: ShadowWorkspace;
+    private readonly cfg;
+    private readonly hostRamBytes;
+    readonly id: string;
+    readonly events: SessionEvent[];
+    readonly startedAt: string;
+    status: SessionInfo["status"];
+    result?: AgentResult;
+    checkpointId?: string;
+    private readonly subs;
+    private readonly pending;
+    private readonly abort;
+    private lastDiffs;
+    private done;
+    constructor(dir: string, task: string, project: NodeProject, ws: ShadowWorkspace, cfg: ClutorConfig, hostRamBytes: number);
+    private push;
+    /** Replays everything so far, then streams new events until the task ends. Returns a function that stops listening. */
+    subscribe(from: number, send: (e: SessionEvent) => void, onEnd: () => void): () => void;
+    start(llm: LlmClient): void;
+    wait(): Promise<void>;
+    private askApproval;
+    resolveApproval(requestId: string, allow: boolean): boolean;
+    stop(): void;
+    /** Writes the agent's changes to the project (after checking nothing changed under it), with a checkpoint to roll back to. */
+    apply(force?: boolean): Promise<{
+        checkpointId: string;
+        files: number;
+    }>;
+    rollback(force?: boolean): Promise<void>;
+    info(): Promise<SessionInfo>;
+}
+
+/** A project directory the server may work in: it must exist, be a directory, and is stored by its real path (links resolved). */
+declare function normaliseRoot(dir: string): Promise<string>;
+declare const isInside: (root: string, p: string) => boolean;
+
+interface ServerOptions {
+    root: string;
+    config: ClutorConfig;
+    version: string;
+    backend?: BackendManager;
+    /** Starts the model (llama-server) on request. Provided by whoever owns the configuration. */
+    startBackend?: () => Promise<void>;
+    /** Folders the server may work in from the start (the CLI passes the current folder). */
+    roots?: string[];
+    /** Fixed token for tests; otherwise random. */
+    token?: string;
+    fetch?: typeof globalThis.fetch;
+    log?: (line: string) => void;
+}
+interface ClutorServer {
+    readonly http: Server;
+    readonly token: string;
+    listen(): Promise<{
+        host: string;
+        port: number;
+    }>;
+    close(): Promise<void>;
+    addRoot(dir: string): Promise<string>;
+    readonly sessions: Map<string, AgentSession>;
+}
+declare function createClutorServer(o: ServerOptions): ClutorServer;
+
+/** Parses a text/event-stream body into the `data:` payloads, in order. */
+declare function parseSse(body: ReadableStream<Uint8Array>): AsyncGenerator<string>;
+
+/**
+ * A Model Context Protocol server (JSON-RPC 2.0 over HTTP) with read-only tools, so an editor or agent that speaks MCP can ask Clutor
+ * about a project and about whether a model fits. It cannot change files or run commands.
+ */
+interface Rpc {
+    jsonrpc?: string;
+    id?: string | number | null;
+    method?: string;
+    params?: Record<string, unknown>;
+}
+declare function handleMcp(req: Rpc, ctx: {
+    isRoot(dir: string): Promise<string | null>;
+}): Promise<{
+    status: number;
+    body: unknown;
+}>;
+
+interface Io {
+    out(line: string): void;
+    err(line: string): void;
+    cwd: string;
+    /** Asks the user a question and returns the answer. Absent when there is no terminal. */
+    prompt?(question: string): Promise<string>;
+}
+/** State that survives from one task to the next inside an interactive session (see repl.ts). One-shot commands run without it. */
+interface SessionState {
+    /** The model server, started on the first task and kept for the rest of the session. */
+    backend?: BackendManager;
+    /** Check to run after each task; set with /verify. It is the user's own command, so it runs without asking. */
+    verify?: string;
+    /** Run commands without asking (/yes). */
+    auto: boolean;
+    /** Checkpoint of the last applied task, for /undo. */
+    lastCheckpoint?: {
+        id: string;
+        dir: string;
+    };
+    /** One line per finished task, given to the next task so the agent knows what already happened. */
+    notes: string[];
+    /** Tokens the model server reported, summed over the session (measured, not estimated). */
+    usage: {
+        promptTokens: number;
+        completionTokens: number;
+    };
+}
+declare const version: () => string;
+declare function main(argv: string[], io: Io, session?: SessionState): Promise<number>;
+/** Starts llama-server if the configuration asks for it, and returns the manager. */
+declare function startBackendIfConfigured(config: ClutorConfig, io: Io, existing?: BackendManager): Promise<BackendManager | undefined>;
+
+/**
+ * The interactive session that `clutor` opens when it is started with no command in a terminal. Text you type is a task for the coding
+ * agent (its changes are held aside until you approve them); a line starting with `/` is a command. Most commands are the ordinary
+ * clutor commands, so they behave exactly as they do outside the session.
+ */
+type Run = (argv: string[], session: SessionState) => Promise<number>;
+type EngineView = (config: ClutorConfig, what: "layers" | "cache") => Promise<void>;
+/** Splits a line into words, honouring single and double quotes. */
+declare function splitWords(line: string): string[];
+declare function runRepl(io: Io, run: Run, engine: EngineView): Promise<number>;
+
+/** Where llama-server saves KV-cache snapshots. They contain the project map the model read, so they stay in the user's own home folder. */
+declare const slotDir: () => string;
+/** llama-server refuses `--slot-save-path` for a folder that does not exist, so make it before starting. */
+declare function ensureSlotDir(): string;
+/**
+ * The model client the agent uses. Against a local llama-server it (1) constrains decoding to the tool-call JSON Schema, (2) keeps the
+ * conversation in one slot so the server reuses its cached prefix between steps, and (3) saves and restores that prefix between runs.
+ * Against any other OpenAI-compatible server only (1) is attempted, and dropped automatically if the server refuses it.
+ */
+declare function agentLlm(config: ClutorConfig, ep: {
+    baseUrl: string;
+    model: string;
+    apiKey?: string;
+    local: boolean;
+}, fetchFn?: typeof globalThis.fetch): LlmClient;
+
+/**
+ * The native engine (c/): a C program that reads a GGUF file directly and streams its experts from disk through Clutor's cache.
+ * It does not run a transformer yet. What it measures is real (bytes read, time spent waiting for them, cache and prefetch behaviour);
+ * what it routes with is a synthetic router, and every report says so.
+ */
+declare class EngineError extends Error {
+    constructor(message: string);
+}
+/** The `c/` folder of a source checkout (absent in an installed package). */
+declare function engineSourceDir(): string;
+declare function findEngine(env?: NodeJS.ProcessEnv): string | undefined;
+declare function run(bin: string, args: string[], opts?: {
+    timeoutMs?: number;
+    cwd?: string;
+}): Promise<{
+    code: number;
+    stdout: string;
+    stderr: string;
+}>;
+/** Compiles the engine from source with `make` (needs a C compiler). Returns the path of the binary. */
+declare function buildEngine(): Promise<string>;
+interface EngineInfo {
+    arch: string;
+    name: string;
+    layers: number;
+    experts: number;
+    expertsUsed: number;
+    moeLayers: number;
+    residentBytes: number;
+    maxDenseBytes: number;
+    maxExpertBytes: number;
+    totalBytes: number;
+    unsizedTensors: number;
+    layerTable: Array<{
+        denseBytes: number;
+        expertBytes: number;
+        routerBytes: number;
+    }>;
+}
+interface StreamOptions {
+    tokens?: number;
+    warmup?: number;
+    cacheMb?: number;
+    stage?: number;
+    policy?: "lru" | "wtinylfu" | "adaptive";
+    smart?: string;
+    prefetch?: boolean;
+    ioThreads?: number;
+    seed?: number;
+    locality?: number;
+    predictCorr?: number;
+    computeUs?: number;
+    windowPct?: number;
+    noOsCache?: boolean;
+    /** auto: keep the dense weights in RAM when they fit in a quarter of it; ring: re-read two layers at a time every token. */
+    dense?: "auto" | "resident" | "ring";
+    /** kernel: a Q4_0 x Q8_0 dot-product kernel over every loaded byte (default); checksum: a cheap hash, so the run measures I/O alone. */
+    compute?: "kernel" | "checksum";
+    /** Scenario: measured tokens [at, at+len) route uniformly at random (scan noise); all others use one fixed tight topic. */
+    shift?: {
+        at: number;
+        len: number;
+    };
+    /** Record hits and peak RSS every N measured tokens. */
+    window?: number;
+}
+interface StreamReport {
+    provenance: {
+        routing: string;
+        disk: string;
+        compute: string;
+    };
+    model: {
+        name: string;
+        arch: string;
+        layers: number;
+        experts: number;
+        expertsUsed: number;
+        expertBytes: number;
+    };
+    config: {
+        policy: string;
+        cacheSlots: number;
+        stageSlots: number;
+        smartRoute: boolean;
+        J: number;
+        M: number;
+        tau: number;
+        denseMode: "resident" | "ring";
+        densePreloadBytes: number;
+        computeMode: "kernel" | "checksum";
+        computeKernel: string;
+        prefetch: boolean;
+        ioThreads: number;
+        osCacheBypass: boolean;
+        tokens: number;
+        warmup: number;
+        seed: number;
+        locality: number;
+        predictCorr: number;
+    };
+    totals: {
+        accesses: number;
+        hits: number;
+        stageHits: number;
+        misses: number;
+        bypass: number;
+        hitRate: number;
+        substituted: number;
+        droppedMass: number;
+        maxDeltaP: number;
+        admitRejects: number;
+        evictions: number;
+        prefetchIssued: number;
+        prefetchLate: number;
+        prefetchWasted: number;
+        demandBytes: number;
+        prefetchBytes: number;
+        denseBytes: number;
+        wallSeconds: number;
+        ioWaitSeconds: number;
+        computeSeconds: number;
+        readSecondsTotal: number;
+        overlap: number;
+        tokensPerSecond: number;
+        gbPerToken: number;
+        missesPerToken: number;
+        checksum: string;
+    };
+    /** ru_maxrss of the engine process, bytes: before it allocated anything, and at the end of the run. */
+    rss: {
+        startBytes: number;
+        peakBytes: number; /** Process baseline plus every buffer and table the run allocates, all pages touched. */
+        predictedBytes: number;
+    };
+    scenario: {
+        shiftAt: number;
+        shiftLen: number;
+    };
+    windows: Array<{
+        tokEnd: number;
+        accesses: number;
+        hits: number;
+        peakRssBytes: number;
+    }>;
+    layers: Array<{
+        layer: number;
+        accesses: number;
+        hits: number;
+        misses: number;
+        substituted: number;
+        ioWaitSeconds: number;
+    }>;
+}
+declare function engineInfo(bin: string, file: string): Promise<EngineInfo>;
+declare function engineStream(bin: string, file: string, o?: StreamOptions, timeoutMs?: number): Promise<StreamReport>;
+
+export { AgentSession, BackendManager, CONFIG_FILE, ConfigError, ConfigSchema, DEFAULT_PORT, DOWNLOADS, DecideError, DownloadError, EngineError, ModelError, SlotSnapshots, UsageError, agentLlm, buildEngine, buildLlamaArgs, createClutorServer, downloadFile, downloadUrl, engineInfo, engineSourceDir, engineStream, ensureSlotDir, findEngine, findLlamaServer, flagBool, flagInt, flagString, formatGates, formatPlan, formatSimulation, fromOpenAiReply, handleMcp, isInside, listLocalModels, loadConfig, main, normaliseRoot, parseArgs, parseSse, pct, probeLlamaServer, resolveModel, run, runDecide, runRepl, sealDecision, slotDir, splitWords, startBackendIfConfigured, streamToOllama, table, toOpenAiBody, tps, version, withPrefixSnapshots };
+export type { BackendState, ClutorConfig, ClutorServer, DecideEndpoint, DecideResult, Download, EngineInfo, Io, LlamaArgsInput, LlamaCapabilities, LocalModel, OllamaChatRequest, OllamaMessage, ParsedArgs, ResolvedModel, ServerOptions, SessionEvent, SessionInfo, SessionState, StreamOptions, StreamReport };