amness 0.0.0-stage → 0.1.2

package/dist/src/harness.d.ts

@@ -0,0 +1,411 @@
+import { type Schema } from "./schema.ts";
+export type ToolCall = {
+    id: string;
+    type?: "function";
+    function: {
+        name: string;
+        arguments: string;
+    };
+};
+export type Usage = {
+    prompt_tokens?: number;
+    completion_tokens?: number;
+    total_tokens?: number; /** part of the prompt served from the provider's cache */
+    cached_tokens?: number; /** set when the provider reported nothing and the harness estimated (about 4 characters per token) */
+    estimated?: boolean; /** part of the output spent on hidden reasoning */
+    reasoning_tokens?: number;
+};
+export type Message = {
+    role: "system" | "user" | "assistant" | "tool";
+    content: string | null; /** pictures attached to a user message (base64) */
+    images?: {
+        mime: string;
+        data: string;
+    }[];
+    tool_calls?: ToolCall[];
+    tool_call_id?: string;
+    usage?: Usage;
+    /** Provider-native content blocks (e.g. Claude thinking blocks). Kept verbatim in history and handed back to the adapter. */
+    raw?: unknown;
+};
+export type ToolSpec = {
+    name: string;
+    description: string;
+    parameters: Schema;
+};
+/** Any chat model: messages + tool specs in, assistant message out (attach `usage` if known). See openai.ts. */
+export type ModelOpts = {
+    signal?: AbortSignal; /** Cap on generated tokens for this call (used for cache keep-alive pings; adapters may ignore it). */
+    maxTokens?: number; /** Called with each piece of assistant text as it is generated (streaming adapters only). */
+    onText?: (delta: string) => void; /** Called with pieces of the model's reasoning summary, where the provider exposes one. */
+    onThinking?: (delta: string) => void;
+};
+export type Model = ((messages: Message[], tools: ToolSpec[], opts?: ModelOpts) => Promise<Message>) & {
+    /** Set by adapters whose provider binds reasoning to the exact history (Claude): the harness then never edits past turns. */
+    appendOnly?: boolean;
+    /** Which wire API the adapter is using right now (e.g. "responses" / "chat"); adapters may change it at runtime. */
+    api?: () => string;
+};
+export type ToolCtx = {
+    registry: Registry;
+    step: number; /** id of this tool call (subagent events carry it as `parent` so a UI can nest them under their card) */
+    callId?: string; /** Aborted when the run is interrupted; long-running tools should honour it. */
+    signal?: AbortSignal; /** Publish a custom event (e.g. a live file diff) to `onEvent`. */
+    emit?: (e: Event) => void;
+};
+export type Tool<A = any> = {
+    name: string;
+    description: string;
+    schema: Schema;
+    run: (args: A, ctx: ToolCtx) => unknown | Promise<unknown>;
+    /** Hidden from the model until it finds it via `tool_search` (keeps prompts small when you have many tools). */
+    deferred?: boolean;
+    /** Availability per turn; the tool is only shown (and callable) while this returns true. */
+    when?: (s: {
+        step: number;
+        messages: Message[];
+    }) => boolean;
+    /** Needs human approval before running. A function may return true, or a string reason, to flag a specific call. */
+    risky?: boolean | ((args: A) => boolean | string);
+    /** Human-readable preview of what this call will do (a diff, a command), shown in the approval prompt. */
+    preview?: (args: A) => string | undefined;
+    /** Never changes anything (safe in plan mode, safe to run in a read-only subagent). */
+    readOnly?: boolean;
+    /** Its output comes from outside (the web, an MCP server): it is wrapped as untrusted data, and commands that copy text from it need approval. */
+    untrusted?: boolean;
+    /** Per-call answer to "may this run at the same time as other calls?", for tools where it depends on the arguments. Overrides `readOnly`/`parallel` for scheduling. */
+    concurrent?: (args: any) => boolean;
+    /** Safe to run at the same time as other calls even though it is not read-only (e.g. a subagent working in its own context). Everything else runs one at a time, in call order. */
+    parallel?: boolean;
+};
+export declare const defineTool: <A = any>(t: Tool<A>) => Tool<A>;
+/** The live set of tools. Mutate it between or during runs (tools receive it as `ctx.registry`); changes show up next turn. */
+export declare class Registry {
+    tools: Map<string, Tool<any>>;
+    loaded: Set<string>;
+    constructor(ts?: Tool[]);
+    add(...ts: Tool[]): this;
+    remove(name: string): boolean;
+    get(name: string): Tool<any> | undefined;
+    hasDeferred(): boolean;
+    visible(s: {
+        step: number;
+        messages: Message[];
+    }): Tool<any>[];
+    /** Keyword-rank the not-yet-loaded deferred tools by name + description. */
+    search(q: string, n?: number): Tool<any>[];
+}
+export type Event = {
+    kind: "toolstart";
+    id: string;
+    name: string;
+    args: string;
+} | {
+    kind: "tool";
+    id?: string;
+    name: string;
+    args: string;
+    result: string;
+} | {
+    kind: "text";
+    delta: string;
+} | {
+    kind: "thinking";
+    delta: string;
+} | {
+    kind: "assistant";
+    text: string;
+    streamed: boolean;
+} | {
+    kind: "todos";
+    todos: {
+        content: string;
+        status: "pending" | "in_progress" | "done";
+    }[];
+} | {
+    kind: "steer";
+    text: string;
+} | {
+    kind: "nudge" | "loop" | "rejected" | "repair" | "denied" | "budget" | "tools" | "aborted";
+    detail: string;
+} | {
+    kind: "edit";
+    path: string;
+    created: boolean;
+    added: number;
+    removed: number;
+    diff: string; /** File content before the edit (null = it did not exist); lets a UI offer undo. */
+    before?: string | null;
+} | {
+    kind: "turn";
+    step: number;
+    tokens: number;
+    prompt: number;
+    completion: number;
+    cached: number;
+    reasoning: number;
+} | {
+    kind: "rollover";
+    detail: string;
+}
+/** Context that was shrunk without losing anything current (chars; roughly 4 per token). */
+ | {
+    kind: "trim";
+    saved: number;
+    what: string;
+}
+/** The request prefix changed since the last call, so the provider's prompt cache will miss from `at` onward (message index; -1 = tool definitions). */
+ | {
+    kind: "cachebreak";
+    reason: string;
+    at: number;
+}
+/** Where the loop is: lets a UI show live progress. `step` is 0-based; `n` is the number of tool calls in the batch. */
+ | {
+    kind: "phase";
+    phase: "model" | "tools" | "verify" | "compact";
+    step: number;
+    max: number;
+    n?: number;
+}
+/** A lifecycle hook ran: what it did (blocked, added context, warned). */
+ | {
+    kind: "hook";
+    event: string;
+    detail: string;
+    blocked: boolean;
+}
+/** What the run really did, from recorded facts (not the model's words): shown after an accepted finish. */
+/** The independent reviewer's verdict on a finish. */
+ | {
+    kind: "review";
+    pass: boolean;
+    findings: string[];
+    inconclusive?: boolean;
+}
+/** Only when `record` is set: the messages a run started from, and every message the model produced (for trace replay). */
+ | {
+    kind: "run";
+    messages: Message[];
+} | {
+    kind: "model";
+    message: Message;
+}
+/** Why a call was allowed without asking, forced to ask, or refused: the rule, the floor or the taint check. */
+ | {
+    kind: "policy";
+    tool: string;
+    action: "allow" | "ask" | "deny";
+    reason: string;
+} | {
+    kind: "audit";
+    changed: string[];
+    testsAfterLastEdit: boolean | undefined;
+    notes: string[];
+} | {
+    kind: "finish";
+    summary: string;
+};
+/** Shared token/time cap. Pass one instance to a harness (and its subagents) to bound the whole run. */
+/** Servers that report no token usage (many local ones) would make every cap useless, so estimate it: about 4 characters per token. Marked, so a UI can show it as approximate. */
+export declare function ensureUsage(m: Message, sent: Message[]): Message;
+export declare class Budget {
+    tokens: number;
+    promptTokens: number;
+    completionTokens: number; /** prompt tokens the provider served from its cache */
+    cachedTokens: number;
+    calls: number;
+    t0: number;
+    maxTokens: number;
+    maxMs: number;
+    constructor(o?: {
+        maxTokens?: number;
+        maxMs?: number;
+    });
+    /** Set on a slice made by `slice()`: everything it spends is charged to the parent too. */
+    parent?: Budget;
+    /** A smaller budget for a subagent: at most `share` of what is left here (and no more than `max` tokens). Its spending counts against this budget as well. */
+    slice(share: number, max?: number): Budget;
+    add(m: Message): void;
+    /** What the cap is measured in: tokens, with cached input counted at a tenth (it costs about that much, and a long session re-reads its history every turn). */
+    get effective(): number;
+    get ms(): number;
+    /** How much of the tightest cap is used, 0 to 1 (0 when there is no cap). */
+    get fraction(): number;
+    exceeded(): string | null;
+}
+export type Approve = (req: {
+    name: string;
+    args: any;
+    reason?: string;
+    preview?: string;
+    id?: string; /** from the built-in safety floor: "don't ask again" shortcuts must not skip this prompt */
+    floor?: boolean;
+}) => Promise<boolean | string> | boolean | string;
+/** Turn-off switches, mainly so evals can measure what each guard is worth. */
+export type Guard = "nudge" | "loop" | "compact" | "stuck" | "wrapup" | "condense" | "schedule" | "ledger" | "stagnation" | "review" | "redact";
+export type Options = {
+    model: Model;
+    /** A fixed list, or a live Registry you can add to / remove from at any time. */
+    tools?: Tool[] | Registry;
+    system?: string;
+    /** Gate for `finish`: return true/undefined to accept, or a string / {ok:false, feedback} to reject with feedback. */
+    verify?: (summary: string) => Promise<true | string | void | {
+        ok: boolean;
+        feedback?: string;
+    }> | true | string | void;
+    maxSteps?: number;
+    /** Chars of transcript before old tool output is elided. */
+    contextBudget?: number;
+    budget?: Budget;
+    /** Asked before any `risky` tool call. Return true to allow, or false / a string (shown to the model) to deny. No handler = deny. */
+    approve?: Approve;
+    /** Your own context strategy: called before each model request with the conversation; return a new list of messages to replace it, or nothing to keep it. */
+    context?: (msgs: Message[], info: {
+        step: number;
+        promptTokens: number;
+        budget: number;
+    }) => Message[] | void | Promise<Message[] | void>;
+    /** Policy as code: called with each tool call before it runs (see plugins.ts checkPolicies). */
+    policy?: (call: {
+        tool: string;
+        args: Record<string, unknown>;
+    }) => Promise<{
+        action: "allow" | "ask" | "deny";
+        reason?: string;
+        plugin?: string;
+    } | undefined>;
+    /** Called at the start of every turn with the full transcript; persist it to resume after a crash or pause. */
+    checkpoint?: (messages: Message[]) => void;
+    off?: Guard[];
+    /**
+     * Long-run memory management without editing history: when the context passes a threshold, the model writes a handoff
+     * note and the run continues in a fresh context seeded with the task + that note. Works for every provider.
+     */
+    rollover?: {
+        afterTokens?: number;
+        afterChars?: number;
+    };
+    /** Receives each handoff note (persist it; it is also a portable summary of the work so far). */
+    onHandoff?: (note: string) => void;
+    /** Rules that allow, force-ask or deny a call before the permission mode is consulted (see `Permissions`). Deny wins; allow skips the prompt. */
+    permissions?: {
+        check(tool: string, args: Record<string, any>): {
+            action: "allow" | "ask" | "deny" | "none";
+            rule?: string;
+            reason?: string;
+            floor?: boolean;
+        };
+    };
+    /** Turns without any objective improvement (failing-test count, new files edited, new code) before the loop reflects, then stops. Default 8; 0 switches it off. */
+    stagnationTurns?: number;
+    /** An independent reviewer consulted before a finish is accepted (after the ledger and the verify gate). A failing review sends its findings back; at most twice, then the work is accepted and flagged. */
+    reviewer?: (ctx: {
+        task: string;
+        summary: string;
+        messages: Message[];
+    }) => Promise<{
+        pass: boolean;
+        findings: string[];
+        inconclusive?: boolean;
+    }>;
+    /** What to do when a shell command contains text copied from an untrusted tool result (a web page, an MCP server): `ask` (default) forces an approval, whatever the mode or allow rules; `deny` refuses; `off` ignores it. */
+    taint?: "ask" | "deny" | "off";
+    /** Mask secrets (API keys, tokens, private keys, credential assignments) in tool results before the model sees them. Default on in the coding agent. */
+    redact?: boolean;
+    /** Claims ledger (see `Ledger`): records edits and commands, and rejects a `finish` whose summary claims things that did not happen. */
+    ledger?: {
+        onEdit(e: {
+            path: string;
+            added: number;
+            removed: number;
+            created: boolean;
+            diff?: string;
+        }): void;
+        onCommand(cmd: string, result: string): void;
+        check(summary: string, o?: {
+            gated?: boolean;
+        }): string[];
+        audit(task: string): {
+            changed: string[];
+            testsAfterLastEdit: boolean | undefined;
+            notes: string[];
+        };
+    };
+    /** Model for the handoff note written when the context rolls over (often a cheaper one). Default: `model`. */
+    compactModel?: Model;
+    /** Emit `run` and `model` events with full message content, so a trace can be replayed later (see `replay`). Larger traces; off unless asked. */
+    record?: boolean;
+    /** Lifecycle hooks (see `Hooks`). PreToolUse can block or rewrite a call, PostToolUse can add context to a result, Stop can reject a finish, PreCompact can veto trimming. */
+    hooks?: {
+        run(event: "PreToolUse" | "PostToolUse" | "PreCompact" | "Stop" | "SessionStart" | "UserPromptSubmit" | "PreModel" | "PostModel", payload: Record<string, unknown>): Promise<{
+            block?: string;
+            context?: string;
+            args?: Record<string, unknown>;
+            tools?: string[];
+            then?: string;
+            warnings: string[];
+        }>;
+    };
+    /** Interrupt the run: it stops at the next safe point (history stays consistent, so it can be resumed). */
+    signal?: AbortSignal | (() => AbortSignal | undefined);
+    /** Polled at the start of every turn: messages the user typed while the agent was working ("steering"). They join the conversation immediately. */
+    inbox?: () => string[];
+    onEvent?: (e: Event) => void;
+};
+export declare const HANDOFF_PROMPT = "Your context is about to be reset. Write a handoff note for yourself; you will continue from it with no other memory of this session. Do not call tools; reply with the note only (under 500 words), in this shape:\nGOAL: what the user wants, in your own words\nDONE: what is finished, with exact file paths and decisions made\nSTATE: what you verified (commands run, results), what is still failing\nNEXT: the concrete next steps, in order\nGOTCHAS: facts learned the hard way (commands, quirks, dead ends not to repeat)";
+/** Ask the model to summarise the transcript so far. Tool specs are passed because some APIs require them when history contains tool calls. */
+export declare function makeHandoff(model: Model, specs: ToolSpec[], msgs: Message[], budget?: Budget): Promise<string>;
+export type RunResult = {
+    text: string;
+    finished: boolean;
+    steps: number;
+    messages: Message[];
+    stopped?: "budget" | "maxSteps" | "aborted" | "stuck" | "blocked";
+    tokens: number;
+};
+export declare const DEFAULT_SYSTEM = "You are an autonomous agent. Work until the task is DONE, then call `finish`.\n- Act, don't narrate. If you say you will do something, do it in the same turn with a tool call.\n- Don't ask permission or clarification unless truly blocked; choose a sensible default and state it in `finish`.\n- Never invent tool output, data or identifiers. If unsure, check with a tool.\n- Verify your work before finishing. Only call `finish` when verified.\n- If an approach fails twice, change approach instead of repeating it.\n- Tool errors are information: read them, fix your call, retry.\n- `finish(summary)`: what you did, how you verified, assumptions made.";
+export declare const clip: (s: string, n?: number) => string;
+/**
+ * Shrink a tool observation before it enters the transcript, keeping what the next action depends on
+ * (CoACT's "action-preserving" rule, done with rules instead of a trained compressor): strip terminal control codes and
+ * progress-bar redraws, collapse repeated lines, and when still too long keep head and tail plus the error-looking lines from the middle.
+ */
+export declare function condense(s: string, max?: number): string;
+/** Same call repeated later in the transcript: the older output is stale, so drop it first (cheapest compaction, loses nothing current). */
+export declare function supersede(msgs: Message[], keep?: number, isRead?: (tool: string) => boolean): number;
+/** Elide old tool outputs once the transcript passes `budget` chars; the last `keep` messages stay intact. */
+export declare function compact(msgs: Message[], budget?: number, keep?: number): number;
+type PrefixSig = {
+    tools: string;
+    msgs: string[];
+};
+/** Cheap fingerprint of what the provider caches: the tool definitions, then each message in order. */
+export declare const prefixSignature: (msgs: Message[], specs: ToolSpec[]) => PrefixSig;
+/** Where (and why) this request stops matching the previous one. Pure appends return undefined: that is the cache-friendly case. */
+export declare function firstCacheBreak(prev: PrefixSig | undefined, now: PrefixSig): {
+    reason: string;
+    at: number;
+} | undefined;
+/** A call reduced to what it does, so trivial differences (key order, extra spaces in a command) do not hide a repeat. */
+export declare function canonicalCall(name: string, args: unknown): string;
+/** A repeating pattern of 2 to 4 different calls at the end of `hist` (A B A B A B, A B C A B C A B C...). Exact repeats of one call are handled separately. */
+export declare function findCycle(hist: string[], minReps?: number): string[] | undefined;
+/** Does this command contain a run of three or more words (or one very long word) copied verbatim from an untrusted tool result? Returns the tool it came from. */
+export declare function taintedBy(cmd: string, pool: {
+    source: string;
+    text: string;
+}[]): string | undefined;
+export declare function createHarness(o: Options): {
+    run: (task: string, opts?: {
+        resume?: Message[];
+    }) => Promise<RunResult>;
+    extract: <T = unknown>(prompt: string, schema: Schema, attempts?: number) => Promise<T>;
+    warm: (msgs: Message[], opts?: {
+        signal?: AbortSignal;
+    }) => Promise<{
+        prompt: number;
+        cached: number;
+    }>;
+};
+export {};