@wardby/cli 0.1.0

package/dist/providers/jobs/safe-extract.d.ts

@@ -0,0 +1,9 @@
+import type { Readable } from "node:stream";
+export interface SafeExtractLimits {
+    maxBytes: number;
+    maxEntries: number;
+}
+export interface SafeExtractOptions {
+    signal?: AbortSignal;
+}
+export declare function safeExtract(source: Readable, root: string, limits: SafeExtractLimits, options?: SafeExtractOptions): Promise<void>;

package/dist/providers/jobs/safe-extract.js

@@ -0,0 +1,325 @@
+import { chmod, lstat, mkdir, open, readlink, realpath, symlink as createSymlink } from "node:fs/promises";
+import { dirname, isAbsolute, resolve, sep } from "node:path";
+import tar from "tar-stream";
+const MAX_SYMLINK_HOPS = 40;
+function fail(code) {
+    throw new Error(code);
+}
+/** "./a/b" -> "a/b"; "./" -> "" (the root itself). Rejects anything that could leave the root. */
+function normalize(name) {
+    if (name.includes("\0") || name.startsWith("/"))
+        fail("extract_path_invalid");
+    let path = name.replace(/^(\.\/)+/, "").replace(/\/+$/, "");
+    if (path === ".")
+        path = "";
+    if (path === "")
+        return "";
+    const segments = path.split("/");
+    if (segments.some((s) => s === "" || s === "." || s === ".."))
+        fail("extract_path_invalid");
+    return path;
+}
+function inside(root, target) {
+    return target === root || target.startsWith(`${root}${sep}`);
+}
+function executableMode(headerMode) {
+    return (headerMode ?? 0) & 0o111 ? 0o755 : 0o644;
+}
+/** Maps any error that escaped our own fixed extract_* codes to a path-free fallback. */
+function mapError(err) {
+    if (err instanceof Error && /^extract_/.test(err.message))
+        return err;
+    const code = err?.code;
+    if (code === "EEXIST" || code === "ENOTDIR" || code === "ENOTEMPTY")
+        return new Error("extract_duplicate_entry");
+    return new Error("extract_io");
+}
+/** Lexically applies path components ("." skip, ".." pop, else append) — no filesystem access. */
+function applyLexically(base, components) {
+    let current = base;
+    for (const component of components) {
+        if (component === "" || component === ".")
+            continue;
+        if (component === "..") {
+            current = dirname(current);
+            continue;
+        }
+        current = current === sep ? `${sep}${component}` : `${current}${sep}${component}`;
+    }
+    return current;
+}
+/**
+ * Resolves `components` starting from the already-real `startReal`, like realpath but tolerant of a
+ * dangling tail: once a component doesn't exist (or a non-final one isn't a directory), the rest is
+ * applied lexically instead of failing. Any symlink encountered along the way is followed for real
+ * (readlink + splice its target in front of what's left), which is what catches a chain of in-tree
+ * symlinks that composes into a physical escape even though each hop looks fine on its own.
+ */
+async function resolveWalk(startReal, components) {
+    let current = startReal;
+    let remaining = components.slice();
+    let hops = 0;
+    while (remaining.length > 0) {
+        const component = remaining.shift();
+        if (component === "" || component === ".")
+            continue;
+        if (component === "..") {
+            current = dirname(current);
+            continue;
+        }
+        const candidate = current === sep ? `${sep}${component}` : `${current}${sep}${component}`;
+        let stats;
+        try {
+            stats = await lstat(candidate);
+        }
+        catch (err) {
+            const code = err.code;
+            if (code === "ENOENT" || code === "ENOTDIR") {
+                return applyLexically(current, [component, ...remaining]);
+            }
+            throw err;
+        }
+        if (stats.isSymbolicLink()) {
+            hops += 1;
+            if (hops > MAX_SYMLINK_HOPS)
+                fail("extract_symlink_escape");
+            const linkTarget = await readlink(candidate);
+            if (isAbsolute(linkTarget))
+                fail("extract_symlink_escape");
+            remaining = linkTarget.split("/").concat(remaining);
+            continue;
+        }
+        current = candidate;
+    }
+    return current;
+}
+export async function safeExtract(source, root, limits, options) {
+    const base = resolve(root);
+    const recordedSymlinks = new Map();
+    const seen = new Set();
+    let entries = 0;
+    let bytes = 0;
+    const extract = tar.extract();
+    let rejectFailed;
+    const failed = new Promise((_resolve, reject) => {
+        rejectFailed = reject;
+    });
+    failed.catch(() => undefined);
+    const onStreamError = (err) => rejectFailed(err);
+    extract.once("error", onStreamError);
+    source.once("error", onStreamError);
+    const signal = options?.signal;
+    const onAbort = () => rejectFailed(new Error("extract_aborted"));
+    if (signal) {
+        if (signal.aborted)
+            onAbort();
+        else
+            signal.addEventListener("abort", onAbort, { once: true });
+    }
+    function guard(operation) {
+        return Promise.race([operation, failed]);
+    }
+    // Created (and so subscribed to tar-stream's internal 'entry'/'close' events) before any `await`,
+    // including the realpath below: tar-stream's async iterator only delivers an entry to listeners that
+    // were attached before it was emitted, so creating this after an async gap can silently miss the very
+    // first entry and hang forever waiting for one that already came and went.
+    const extractIterator = extract[Symbol.asyncIterator]();
+    source.pipe(extract);
+    try {
+        const rootReal = await guard(realpath(base));
+        /**
+         * Creates (if needed) and verifies every directory named by `segments`, one component at a time,
+         * starting from `rootReal`, and returns the resulting real path. For each component: `lstat` it; if
+         * it doesn't exist, `mkdir` just that one component (non-recursive — its parent was already verified
+         * real by the previous iteration), re-`lstat`ing on a raced `EEXIST`. Then — whether it already
+         * existed or was just created — `lstat` it again: if that's a symlink, `extract_through_symlink`
+         * (this is what stops phase 2a from creating or `chmod`ing through a symlink an *earlier* entry in
+         * this same extraction created, including one that's only a case-insensitive alias of the component
+         * being resolved); if it exists but isn't a directory at all, `extract_duplicate_entry` (preserves
+         * the existing "file blocking a nested path" behavior). Only once a component is freshly confirmed by
+         * `lstat` to be a real, non-symlink directory does it get `chmod`'d to 0o755 — never by a path that
+         * was merely assumed to still be what an earlier check saw.
+         */
+        async function ensureDirectory(segments) {
+            let current = rootReal;
+            for (const component of segments) {
+                const child = current === sep ? `${sep}${component}` : `${current}${sep}${component}`;
+                let exists = true;
+                try {
+                    await guard(lstat(child));
+                }
+                catch (err) {
+                    if (err.code !== "ENOENT")
+                        throw err;
+                    exists = false;
+                }
+                if (!exists) {
+                    try {
+                        await guard(mkdir(child, { mode: 0o755 }));
+                    }
+                    catch (err) {
+                        if (err.code !== "EEXIST")
+                            throw err;
+                    }
+                }
+                const stats = await guard(lstat(child));
+                if (stats.isSymbolicLink())
+                    fail("extract_through_symlink");
+                if (!stats.isDirectory())
+                    fail("extract_duplicate_entry");
+                await guard(chmod(child, 0o755));
+                current = child;
+            }
+            return current;
+        }
+        // Phase 1 (streaming): create directories and regular files; validate and record symlinks.
+        for (;;) {
+            const step = await guard(extractIterator.next());
+            if (step.done)
+                break;
+            const entry = step.value;
+            const { header } = entry;
+            entries += 1;
+            if (entries > limits.maxEntries) {
+                entry.resume();
+                fail("extract_entry_limit");
+            }
+            const path = normalize(header.name);
+            if (path === "") {
+                entry.resume();
+                continue;
+            }
+            const segments = path.split("/");
+            for (let i = 1; i < segments.length; i += 1) {
+                if (recordedSymlinks.has(segments.slice(0, i).join("/"))) {
+                    entry.resume();
+                    fail("extract_through_symlink");
+                }
+            }
+            if (seen.has(path)) {
+                entry.resume();
+                fail("extract_duplicate_entry");
+            }
+            seen.add(path);
+            const target = resolve(base, path);
+            if (!inside(base, target)) {
+                entry.resume();
+                fail("extract_path_invalid");
+            }
+            // Count every entry type's declared size before draining/consuming its body: a symlink (or any
+            // other type) can carry a body up to its declared size, and this must be rejected before we ever
+            // read a byte of it, not after.
+            const declaredSize = header.size ?? 0;
+            if (bytes + declaredSize > limits.maxBytes) {
+                entry.resume();
+                fail("extract_size_limit");
+            }
+            bytes += declaredSize;
+            switch (header.type) {
+                case "directory": {
+                    entry.resume();
+                    try {
+                        await ensureDirectory(segments);
+                    }
+                    catch (err) {
+                        throw mapError(err);
+                    }
+                    break;
+                }
+                case "file":
+                case "contiguous-file": {
+                    if (entry.destroyed)
+                        throw mapError(new Error("entry stream destroyed"));
+                    let fh;
+                    try {
+                        const parentReal = await ensureDirectory(segments.slice(0, -1));
+                        const fileTarget = resolve(parentReal, segments[segments.length - 1]);
+                        const openPromise = open(fileTarget, "wx", 0o644);
+                        try {
+                            fh = await guard(openPromise);
+                        }
+                        catch (err) {
+                            // If `failed` won the race, `open()` may still resolve later with a real handle that
+                            // nothing else will ever close — close it then. Harmless (and a no-op) if `open()` itself
+                            // is what rejected instead, since then it never produced a handle at all.
+                            openPromise.then((handle) => handle.close().catch(() => undefined)).catch(() => undefined);
+                            throw err;
+                        }
+                    }
+                    catch (err) {
+                        throw mapError(err);
+                    }
+                    try {
+                        let streamed = 0;
+                        const bodyIterator = entry[Symbol.asyncIterator]();
+                        for (;;) {
+                            const chunkStep = await guard(bodyIterator.next());
+                            if (chunkStep.done)
+                                break;
+                            const chunk = chunkStep.value;
+                            streamed += chunk.byteLength;
+                            if (streamed > limits.maxBytes)
+                                fail("extract_size_limit");
+                            await guard(fh.write(chunk));
+                        }
+                        await guard(fh.chmod(executableMode(header.mode)));
+                    }
+                    finally {
+                        await fh.close().catch(() => undefined);
+                    }
+                    break;
+                }
+                case "symlink": {
+                    entry.resume();
+                    const link = header.linkname ?? "";
+                    if (link === "" || link.startsWith("/") || !inside(base, resolve(dirname(target), link))) {
+                        fail("extract_symlink_escape");
+                    }
+                    recordedSymlinks.set(path, link);
+                    break;
+                }
+                default:
+                    entry.resume();
+                    fail("extract_special_entry");
+            }
+        }
+        // Phase 2a: materialize every recorded symlink, now that the real tree is final. `ensureDirectory`
+        // rejects (extract_through_symlink) rather than create or chmod through a symlink an earlier
+        // iteration of this same loop created — including one that's merely a case-insensitive alias of the
+        // parent this symlink names — and a same-path collision with a phase-1-created path surfaces as
+        // EEXIST from `symlink()` itself, mapped to extract_duplicate_entry.
+        for (const [path, link] of recordedSymlinks) {
+            const segments = path.split("/");
+            try {
+                const parentReal = await ensureDirectory(segments.slice(0, -1));
+                const target = resolve(parentReal, segments[segments.length - 1]);
+                await guard(createSymlink(link, target));
+            }
+            catch (err) {
+                throw mapError(err);
+            }
+        }
+        // Phase 2b: validate every created symlink against the real filesystem. A lexical check can't see a
+        // chain of in-tree symlinks (e.g. s -> "..", t -> "s/..") whose composed, physically-resolved target
+        // lands outside root even though each link's own text looks contained.
+        for (const [path, link] of recordedSymlinks) {
+            const segments = path.split("/");
+            const parentReal = await guard(resolveWalk(rootReal, segments.slice(0, -1)));
+            const finalReal = await guard(resolveWalk(parentReal, link.split("/")));
+            if (!(finalReal === rootReal || finalReal.startsWith(`${rootReal}${sep}`))) {
+                fail("extract_symlink_escape");
+            }
+        }
+    }
+    catch (err) {
+        source.destroy();
+        extract.destroy();
+        throw mapError(err);
+    }
+    finally {
+        if (signal)
+            signal.removeEventListener("abort", onAbort);
+        extract.removeListener("error", onStreamError);
+        source.removeListener("error", onStreamError);
+    }
+}

package/dist/providers/jobs/types.d.ts

@@ -0,0 +1,78 @@
+/**
+ * Trusted control-plane contract for isolated coding jobs. User-controlled
+ * values are carried in a versioned input artifact, never expanded into an
+ * arbitrary environment map or shell command.
+ */
+export interface JobResourceLimits {
+    cpus: number;
+    memoryMb: number;
+    pids: number;
+    diskMb: number;
+}
+export interface JobSpec {
+    kind: "coding-agent";
+    runId: string;
+    /** Omitted specs are legacy Codex jobs and retain the single-worker topology. */
+    provider?: "codex" | "claude-code";
+    image: string;
+    /** Required only for Claude's credential-free repository tool container. */
+    toolImage?: string;
+    inputArtifact: string;
+    timeoutSec: number;
+    limits: JobResourceLimits;
+    labels: Record<string, string>;
+}
+/** Opaque provider reference. Callers persist both fields exactly as given. */
+export interface JobHandle {
+    backend: string;
+    id: string;
+}
+export type JobStatus = {
+    state: "pending" | "running";
+} | {
+    state: "succeeded";
+} | {
+    state: "failed";
+    reason?: string;
+} | {
+    state: "stopped";
+} | {
+    state: "lost";
+};
+export interface JobResult {
+    exitCode: number;
+    reason: "completed" | "failed" | "stopped" | "timed_out" | "lost";
+    resultArtifact?: string;
+    /** Fixed worker-owned failure code; never raw container output. */
+    diagnostic?: string;
+}
+/**
+ * Lifecycle invariants implemented by every launcher:
+ *
+ * - `launch` is idempotent by runId for an identical spec and rejects a
+ *   different spec for the same runId.
+ * - pending may become running or terminal; running may become terminal;
+ *   terminal states never change.
+ * - `collect` is repeatable for a terminal job until `remove` succeeds.
+ * - `stop` and `remove` are idempotent and best effort; removing an active
+ *   job is rejected so cleanup cannot silently become an implicit stop.
+ * - no operation implicitly relaunches a missing, stopped, or removed job.
+ */
+export interface JobLauncher {
+    /**
+     * The handle `launch(spec)` will return, when a backend can derive it from the spec alone with no
+     * side effects. Callers persist it *before* launching, so a crash mid-launch still leaves a handle
+     * to stop and remove the run's resources with. `launch` must return an equal handle. Backends that
+     * cannot know the handle in advance omit this, and callers persist only after `launch` returns.
+     */
+    plannedHandle?: (spec: JobSpec) => JobHandle | undefined;
+    launch: (spec: JobSpec) => Promise<JobHandle>;
+    status: (handle: JobHandle) => Promise<JobStatus>;
+    collect: (handle: JobHandle) => Promise<JobResult>;
+    stop: (handle: JobHandle, reason?: string) => Promise<void>;
+    remove: (handle: JobHandle) => Promise<void>;
+}
+/** A launcher that can safely copy a terminal worker workspace back to trusted storage. */
+export interface WorkspaceJobLauncher extends JobLauncher {
+    materializeWorkspace: (handle: JobHandle, destination: string) => Promise<void>;
+}

package/dist/providers/jobs/types.js

@@ -0,0 +1,6 @@
+/**
+ * Trusted control-plane contract for isolated coding jobs. User-controlled
+ * values are carried in a versioned input artifact, never expanded into an
+ * arbitrary environment map or shell command.
+ */
+export {};

package/dist/providers/jobs/workspace-swap.d.ts

@@ -0,0 +1,2 @@
+/** Fills a fresh staging directory next to `destination`, validates it, then atomically swaps it into place. */
+export declare function replaceDirectoryFromStaging(destination: string, maxBytes: number, destinationInvalidError: string, fill: (staging: string) => Promise<void>): Promise<void>;

package/dist/providers/jobs/workspace-swap.js

@@ -0,0 +1,47 @@
+/**
+ * Replaces a trusted workspace directory with a freshly filled copy, shared by
+ * the Docker and Kubernetes launchers. The copy is filled into a staging
+ * directory beside the destination, validated, and only then swapped into
+ * place by rename, with the original restored if the swap fails.
+ *
+ * A fill that rejects has, by definition, produced an untrusted tree (it may
+ * contain escaping symlinks): it is never walked, validated, or renamed — the
+ * staging directory is removed with `rm({ recursive, force })`, which unlinks
+ * symlinks rather than following them.
+ */
+import { lstat, mkdtemp, realpath, rename, rm } from "node:fs/promises";
+import { dirname, join, resolve } from "node:path";
+import { validateMaterializedWorkspace } from "./docker.js";
+/** Fills a fresh staging directory next to `destination`, validates it, then atomically swaps it into place. */
+export async function replaceDirectoryFromStaging(destination, maxBytes, destinationInvalidError, fill) {
+    const target = resolve(destination);
+    const parent = dirname(target);
+    const [parentReal, targetReal, targetStat] = await Promise.all([realpath(parent), realpath(target), lstat(target)]);
+    if (!targetStat.isDirectory() ||
+        targetStat.isSymbolicLink() ||
+        targetReal !== resolve(parentReal, target.slice(parent.length + 1))) {
+        throw new Error(destinationInvalidError);
+    }
+    const staging = await mkdtemp(join(parentReal, ".wardby-workspace-stage-"));
+    const backup = await mkdtemp(join(parentReal, ".wardby-workspace-backup-"));
+    await rm(backup, { recursive: true });
+    let targetMoved = false;
+    try {
+        await fill(staging);
+        await validateMaterializedWorkspace(staging, maxBytes);
+        await rename(targetReal, backup);
+        targetMoved = true;
+        await rename(staging, targetReal);
+        targetMoved = false;
+        await rm(backup, { recursive: true, force: true });
+    }
+    catch (error) {
+        if (targetMoved)
+            await rename(backup, targetReal).catch(() => undefined);
+        throw error;
+    }
+    finally {
+        await rm(staging, { recursive: true, force: true });
+        await rm(backup, { recursive: true, force: true });
+    }
+}

package/dist/providers/llm/anthropic.d.ts

@@ -0,0 +1,13 @@
+/**
+ * Direct Anthropic (Claude) adapter for the LlmProvider seam. `@anthropic-ai/sdk`
+ * is imported only here; all protocol/pricing-dispatch logic lives in the
+ * shared ClaudeLlmProvider base class (claude-provider.ts) — this file's only
+ * job is constructing the right client and pricing module.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { ClaudeLlmProvider } from "./claude-provider.js";
+export { anthropicSupportedModels } from "./pricing-anthropic.js";
+export declare function anthropicCredentialsPresent(env?: NodeJS.ProcessEnv): boolean;
+export declare class AnthropicLlmProvider extends ClaudeLlmProvider {
+    constructor(apiKey?: string, client?: Anthropic);
+}

package/dist/providers/llm/anthropic.js

@@ -0,0 +1,21 @@
+/**
+ * Direct Anthropic (Claude) adapter for the LlmProvider seam. `@anthropic-ai/sdk`
+ * is imported only here; all protocol/pricing-dispatch logic lives in the
+ * shared ClaudeLlmProvider base class (claude-provider.ts) — this file's only
+ * job is constructing the right client and pricing module.
+ */
+import Anthropic from "@anthropic-ai/sdk";
+import { ClaudeLlmProvider } from "./claude-provider.js";
+import { anthropicPriceUsd, getAnthropicPricing } from "./pricing-anthropic.js";
+export { anthropicSupportedModels } from "./pricing-anthropic.js";
+export function anthropicCredentialsPresent(env = process.env) {
+    return Boolean(env.ANTHROPIC_API_KEY);
+}
+export class AnthropicLlmProvider extends ClaudeLlmProvider {
+    constructor(apiKey = process.env.ANTHROPIC_API_KEY ?? "", client) {
+        if (!client && !apiKey) {
+            throw new Error("ANTHROPIC_API_KEY is not set — required by the Anthropic LlmProvider adapter.");
+        }
+        super(client ?? new Anthropic({ apiKey }), { getPricing: getAnthropicPricing, priceUsd: anthropicPriceUsd });
+    }
+}

package/dist/providers/llm/bedrock.d.ts

@@ -0,0 +1,19 @@
+/**
+ * Bedrock-Claude adapter for the LlmProvider seam. `@anthropic-ai/bedrock-sdk`
+ * is imported only here; all protocol/pricing-dispatch logic lives in the
+ * shared ClaudeLlmProvider base class (claude-provider.ts) — AnthropicBedrock
+ * exposes the identical .messages.stream() surface as @anthropic-ai/sdk, so
+ * this file's only job is constructing the right client and pricing module.
+ *
+ * Named BedrockClaudeLlmProvider, not BedrockLlmProvider: Bedrock hosts
+ * multiple model vendors, and this adapter only ever speaks the
+ * Anthropic-native protocol for Claude models. A future non-Claude Bedrock
+ * adapter gets its own name, not a rename of this one.
+ */
+import { AnthropicBedrock } from "@anthropic-ai/bedrock-sdk";
+import { ClaudeLlmProvider } from "./claude-provider.js";
+export { bedrockClaudeSupportedModels } from "./pricing-bedrock-claude.js";
+export declare function bedrockCredentialsPresent(env?: NodeJS.ProcessEnv): boolean;
+export declare class BedrockClaudeLlmProvider extends ClaudeLlmProvider {
+    constructor(region?: string, client?: AnthropicBedrock);
+}

package/dist/providers/llm/bedrock.js

@@ -0,0 +1,33 @@
+/**
+ * Bedrock-Claude adapter for the LlmProvider seam. `@anthropic-ai/bedrock-sdk`
+ * is imported only here; all protocol/pricing-dispatch logic lives in the
+ * shared ClaudeLlmProvider base class (claude-provider.ts) — AnthropicBedrock
+ * exposes the identical .messages.stream() surface as @anthropic-ai/sdk, so
+ * this file's only job is constructing the right client and pricing module.
+ *
+ * Named BedrockClaudeLlmProvider, not BedrockLlmProvider: Bedrock hosts
+ * multiple model vendors, and this adapter only ever speaks the
+ * Anthropic-native protocol for Claude models. A future non-Claude Bedrock
+ * adapter gets its own name, not a rename of this one.
+ */
+import { AnthropicBedrock } from "@anthropic-ai/bedrock-sdk";
+import { ClaudeLlmProvider } from "./claude-provider.js";
+import { bedrockClaudePriceUsd, getBedrockClaudePricing } from "./pricing-bedrock-claude.js";
+export { bedrockClaudeSupportedModels } from "./pricing-bedrock-claude.js";
+export function bedrockCredentialsPresent(env = process.env) {
+    // A region is the one thing Bedrock always needs; AWS resolves actual
+    // credentials from the standard default chain (env keys, shared config,
+    // IAM role) — this only gates whether the adapter registers at all.
+    return Boolean(env.BEDROCK_REGION ?? env.AWS_REGION);
+}
+export class BedrockClaudeLlmProvider extends ClaudeLlmProvider {
+    constructor(region = process.env.BEDROCK_REGION ?? process.env.AWS_REGION ?? "", client) {
+        if (!client && !region) {
+            throw new Error("BEDROCK_REGION (or AWS_REGION) is required by the Bedrock Claude LlmProvider adapter.");
+        }
+        super(client ?? new AnthropicBedrock({ awsRegion: region }), {
+            getPricing: getBedrockClaudePricing,
+            priceUsd: bedrockClaudePriceUsd,
+        });
+    }
+}

package/dist/providers/llm/claude-messages.d.ts

@@ -0,0 +1,106 @@
+import type { LlmMessage, LlmRequest, LlmToolDef, LlmStreamEvent, LlmUsage } from "./types.js";
+export interface CacheControl {
+    type: "ephemeral";
+}
+export interface ClaudeTextBlock {
+    type: "text";
+    text: string;
+    cache_control?: CacheControl;
+}
+export interface ClaudeToolUseBlock {
+    type: "tool_use";
+    id: string;
+    name: string;
+    input: unknown;
+    cache_control?: CacheControl;
+}
+export interface ClaudeToolResultBlock {
+    type: "tool_result";
+    tool_use_id: string;
+    content: string;
+    cache_control?: CacheControl;
+}
+export type ClaudeContentBlock = ClaudeTextBlock | ClaudeToolUseBlock | ClaudeToolResultBlock;
+export interface ClaudeMessage {
+    role: "user" | "assistant";
+    content: ClaudeContentBlock[];
+}
+export interface ClaudeTool {
+    name: string;
+    description: string;
+    input_schema: Record<string, unknown>;
+    cache_control?: CacheControl;
+}
+export interface ClaudeRequest {
+    system?: ClaudeTextBlock[];
+    messages: ClaudeMessage[];
+    tools?: ClaudeTool[];
+    max_tokens: number;
+}
+/**
+ * Same shape sent to the API in `toClaudeRequest` — kept as one function so
+ * a pre-flight token estimate (AnthropicLlmProvider.countTokens) can never
+ * drift from what's actually serialized into the request. Mirrors the
+ * OpenAI adapter's `toOpenAiTools`, which guards against the same failure
+ * class: a duplicated tool-schema mapping once desynced the pre-flight
+ * estimate from the real request and broke the budget guardrail's turn-1
+ * refuse guarantee (measured 44-52% under-count).
+ */
+export declare function toClaudeTools(tools: LlmToolDef[]): ClaudeTool[];
+/**
+ * Raw (pre-inflation) offline token estimate shared by every Claude-protocol
+ * adapter. Each caller applies its own inflation constant on top.
+ */
+export declare function estimateClaudeTokens(messages: LlmMessage[], tools?: LlmToolDef[]): number;
+export declare function toClaudeRequest(req: LlmRequest, defaultMaxTokens: number): ClaudeRequest;
+/**
+ * Two-breakpoint canonical caching. Anthropic's cache order is
+ * tools -> system -> messages, so a breakpoint on the last system block
+ * caches tools+system (static across the run). A rolling breakpoint on the
+ * last message's final block grows the conversation cache each turn.
+ * Sub-minimum prefixes (1024/2048 tokens) are silently un-cached by Anthropic.
+ */
+export declare function withCacheBreakpoints(req: ClaudeRequest): ClaudeRequest;
+interface ClaudeUsage {
+    input_tokens?: number;
+    cache_read_input_tokens?: number;
+    cache_creation_input_tokens?: number;
+    output_tokens?: number;
+}
+export type ClaudeStreamEvent = {
+    type: "message_start";
+    message: {
+        usage: ClaudeUsage;
+    };
+} | {
+    type: "content_block_start";
+    index: number;
+    content_block: {
+        type: "text" | "tool_use";
+        id?: string;
+        name?: string;
+    };
+} | {
+    type: "content_block_delta";
+    index: number;
+    delta: {
+        type: "text_delta";
+        text: string;
+    } | {
+        type: "input_json_delta";
+        partial_json: string;
+    };
+} | {
+    type: "content_block_stop";
+    index: number;
+} | {
+    type: "message_delta";
+    delta: {
+        stop_reason?: string;
+    };
+    usage?: ClaudeUsage;
+} | {
+    type: "message_stop";
+};
+export declare function mapClaudeStream(events: AsyncIterable<ClaudeStreamEvent>, priceUsd: (usage: LlmUsage) => number): AsyncIterable<LlmStreamEvent>;
+export {};