@shardflux/sdk 0.6.1 → 0.7.0

package/dist/capture.d.ts

@@ -0,0 +1,288 @@
+import type { CellClient } from './cell.js';
+import type { CaptureAdapters } from './capture-adapters.js';
+export type { CapturePart, DropReason } from './capture-serialize.js';
+/** `status` of an index line. */
+export type CaptureStatus = 'ok' | 'error' | 'cancelled' | 'incomplete' | 'retry';
+/** The integration that recorded a call (`source` of an index line). */
+export type CaptureSource = 'manual' | 'wrap' | 'ai-sdk' | 'mastra' | 'anthropic' | 'openai-agents' | 'claude-agent-sdk' | 'langchain' | 'mcp' | 'workspace' | (string & {});
+/** Tool names, a pattern, or a predicate. Applies to hook-level capture only. */
+export type CaptureSelector = readonly string[] | RegExp | ((tool: string, source: CaptureSource) => boolean);
+/** A call as `record()` takes it. */
+export interface CaptureCall {
+    tool: string;
+    input?: unknown;
+    /** The result as the tool returned it (bytes, strings, objects, MCP results, content blocks...). */
+    output?: unknown;
+    /** What the tool threw: recorded as `{type, message}`; the status defaults to `error` (`cancelled` for an AbortError). */
+    error?: unknown;
+    status?: CaptureStatus;
+    /** The model's tool call id (`toolu_…`, `call_…`): deduplicates, and lets the agent find the call. */
+    callId?: string | null;
+    /** When the call started (Date, epoch milliseconds or ISO string). */
+    startedAt?: Date | number | string | null;
+    durationMs?: number | null;
+    meta?: Record<string, unknown>;
+    source?: CaptureSource;
+}
+/** A recorded call: its run and sequence number. `seq` names its files (`<seq>-<tool>…`). */
+export interface CallRef {
+    run: string;
+    seq: number;
+    callId: string | null;
+}
+/** What `transform` receives (a copy) and returns. Return null to drop the call. */
+export interface CaptureEvent {
+    tool: string;
+    callId: string | null;
+    source: CaptureSource;
+    status: CaptureStatus;
+    input: unknown;
+    output: unknown;
+    error: {
+        type: string;
+        message: string;
+    } | null;
+    startedAt: string | null;
+    durationMs: number | null;
+    meta: Record<string, unknown>;
+}
+export type CaptureErrorKind = 'write' | 'queue_full' | 'too_large' | 'serialize' | 'transform' | 'gone' | 'discarded' | 'timeout';
+/** A capture problem, reported to `onError` (never thrown into the harness). */
+export declare class CaptureError extends Error {
+    readonly kind: CaptureErrorKind;
+    readonly seq: number | undefined;
+    readonly tool: string | undefined;
+    readonly callId: string | null | undefined;
+    /** The workspace path of a failed write. */
+    readonly path: string | undefined;
+    constructor(kind: CaptureErrorKind, message: string, extra?: {
+        seq?: number;
+        tool?: string;
+        callId?: string | null;
+        path?: string;
+        cause?: unknown;
+    });
+}
+export interface ToolCallCaptureOptions {
+    /** Absolute directory in the workspace (default `/home/user/tool-calls`). Point it at a subdirectory to group runs. */
+    dir?: string;
+    /** Hook-level adapters capture only these tools (explicit `record`/`run`/`wrap`/`tools` always record). */
+    include?: CaptureSelector;
+    /** Hook-level adapters skip these tools. */
+    exclude?: CaptureSelector;
+    /**
+     * Redacts or drops a call before it is written: receives a copy, returns the event to write or null to drop it. If it
+     * throws, the call is dropped (never written unredacted) and `onError` gets a `transform` error.
+     */
+    transform?: (event: CaptureEvent) => CaptureEvent | null | undefined;
+    /** Per call (default 32 MiB). Text and JSON over it are cut (`.part`, `truncated`); binary is not stored (`too_large`). */
+    maxOutputBytes?: number;
+    /** Inputs whose JSON is larger go to `<seq>-<tool>.input.json` (default 64 KiB). */
+    maxInlineInputBytes?: number;
+    /**
+     * Bytes held for pending calls: files, index lines and inline inputs (default 128 MiB). Over it the output (and a
+     * large input) is dropped and the call keeps a small index line with `dropped: "queue_full"`; the call never blocks.
+     */
+    maxPendingBytes?: number;
+    /**
+     * Calls recorded but not yet written (default 10 000), the hard bound on memory while the workspace is unreachable.
+     * Over it a call is not recorded at all (no index line; `record()` returns null), reported to `onError` as
+     * `queue_full` and counted in `stats.dropped`.
+     */
+    maxPendingCalls?: number;
+    /** Parallel file writes (default 4). */
+    concurrency?: number;
+    /** Index lines are appended every `batchDelayMs` (default 50) or 1 MiB. */
+    batchDelayMs?: number;
+    /** How long one write is retried (default 120 000 ms); then it is dropped as `write_failed`. */
+    retryWindowMs?: number;
+    /** Bound on the wait of `flush()`, `close()` and the read-your-writes barrier (default 30 000 ms). */
+    settleTimeoutMs?: number;
+    /** Tool-token attribution label for the capture's writes (default: the workspace handle's). */
+    agentLabel?: string;
+    /** Wake-on-use for the capture's writes (default: `workspace.wake()`); `null`: never wake, writes retry and drop. */
+    wake?: ((timeoutMs: number, signal?: AbortSignal) => Promise<boolean | void>) | null;
+    /** Lifecycle wait budget per write (busy waits plus wakes; default 120 000 ms). */
+    transitionTimeoutMs?: number;
+    /** Merged into every index line's `meta`. */
+    metadata?: Record<string, unknown>;
+    /** Write failures, drops, transform errors. Never thrown into the harness. */
+    onError?: (error: CaptureError) => void;
+}
+export interface CaptureStats {
+    /** Calls accepted (a sequence number was assigned). */
+    recorded: number;
+    /** Index lines appended (a call whose output was dropped still counts: its line says why). */
+    written: number;
+    /** Calls whose index line could not be written (retries exhausted, workspace gone, close timeout). */
+    failed: number;
+    /**
+     * Outputs not stored (`queue_full`, `too_large`, `write_failed`, `serialize_failed`), calls a throwing transform
+     * dropped, and calls not recorded because `maxPendingCalls` were pending.
+     */
+    dropped: number;
+    /** Calls `transform` returned null for. */
+    skipped: number;
+    /** Records ignored because the call id was already recorded. */
+    duplicates: number;
+    /** Pending calls dropped by delete/reset/close({discard}). */
+    discarded: number;
+    /** Write attempts retried. */
+    retries: number;
+    /** Calls recorded but not yet settled. */
+    pending: number;
+    /** Bytes held for pending calls (files, index lines, inline inputs). */
+    pendingBytes: number;
+}
+export interface CaptureFlushResult {
+    /** True when every call recorded before the call was settled within the timeout. */
+    complete: boolean;
+    written: number;
+    failed: number;
+    dropped: number;
+}
+/** A tool call in a harness's own shape: Anthropic `tool_use`, Responses `function_call`, Chat `tool_calls[i]`, or `{name, input}`. */
+export interface CallLike {
+    /** `tool_use`, `function_call`, `function`, `tool_call` (not used). */
+    type?: string;
+    id?: string | null;
+    call_id?: string | null;
+    callId?: string | null;
+    toolCallId?: string | null;
+    name?: string;
+    toolName?: string;
+    input?: unknown;
+    args?: unknown;
+    arguments?: unknown;
+    function?: {
+        name?: string;
+        arguments?: unknown;
+    };
+}
+export interface WrapOptions<A extends unknown[] = unknown[]> {
+    /** The call id from the arguments (default none). */
+    callId?: (...args: A) => string | null | undefined;
+    /** What to record as the input (default: the only argument, else the argument list). */
+    input?: (...args: A) => unknown;
+    source?: CaptureSource;
+    meta?: Record<string, unknown>;
+}
+/** The workspace side a capture writes through (created by `workspace.captureToolCalls()`). */
+export interface CaptureHost {
+    workspaceId: string;
+    /** The capture's own cell client: no read-your-writes barrier (writes never wait on themselves). */
+    cell: CellClient;
+    registry: CaptureRegistry;
+    /** Backoff sleep (the client's injected sleep, else an unref'd timer). */
+    sleep?: (ms: number) => Promise<void>;
+}
+/** Internal hooks the registry calls. */
+export declare const SETTLE: unique symbol;
+export declare const DISCARD: unique symbol;
+/**
+ * The captures of one client, by workspace id: Shardflux calls on the same client wait for writes recorded before them
+ * (read-your-writes), and delete/reset discard pending writes.
+ */
+export declare class CaptureRegistry {
+    #private;
+    add(workspaceId: string, capture: ToolCallCapture): void;
+    remove(workspaceId: string, capture: ToolCallCapture): void;
+    /**
+     * Waits for writes recorded before this call (not for later ones), each capture bounded by its settle timeout.
+     * Undefined when nothing is pending, so callers skip the await. Never rejects.
+     */
+    settle(workspaceId: string): Promise<void> | undefined;
+    /** Drops pending writes of the workspace (delete: the captures also close; reset: the README is written again). */
+    discard(workspaceId: string, reason: 'delete' | 'reset'): void;
+}
+/** `YYYYMMDDTHHMMSSmmmZ-xxxxxx`: sortable UTC start time plus 6 random base36 characters. */
+export declare function newRunId(now?: Date): string;
+/**
+ * Epoch milliseconds from a Date, a number or an ISO string; null when absent, invalid or out of range (epoch
+ * nanoseconds or seconds passed by mistake must not reach toISOString(), which throws for them).
+ */
+export declare function toMs(v: unknown): number | null;
+/**
+ * Wraps `fn` so each call is recorded into the capture active at call time (`capture.activate()`), and passes
+ * straight through when none is. For tools defined at import time in multi-tenant servers.
+ */
+export declare function captureTool<F extends (...args: never[]) => unknown>(name: string, fn: F, opts?: WrapOptions<Parameters<F>>): F;
+export declare class ToolCallCapture {
+    #private;
+    /** `YYYYMMDDTHHMMSSmmmZ-xxxxxx`. */
+    readonly runId: string;
+    /** The capture directory (`dir`). */
+    readonly dir: string;
+    /** `<dir>/<runId>`: index.jsonl and the output files. */
+    readonly runDir: string;
+    readonly workspaceId: string;
+    constructor(host: CaptureHost, opts?: ToolCallCaptureOptions);
+    /** Counters (a snapshot). */
+    get stats(): CaptureStats;
+    /** True after close() (or when the workspace was deleted): records are ignored. */
+    get closed(): boolean;
+    /**
+     * Records one finished call. Synchronous and cheap (serialization happens later); never throws. Returns null when the
+     * capture is closed or the call id was already recorded.
+     */
+    record(call: CaptureCall): CallRef | null;
+    /**
+     * Runs `fn` (your tool) for a model's tool call and records it: Anthropic `tool_use {id, name, input}`, Responses
+     * `function_call {call_id, name, arguments}`, a Chat `tool_calls` item `{id, function: {name, arguments}}`, or
+     * `{name, input}`. Returns exactly what `fn` returns (the same promise object; a sync result stays sync).
+     */
+    run<T>(call: CallLike, fn: () => T): T;
+    /**
+     * Wraps a tool function: every call is recorded. The wrapper returns what `fn` returns (the same value, the same
+     * promise object, the same thrown error; sync stays sync). An async generator is passed through item by item and its
+     * items are stored as `.jsonl`.
+     */
+    wrap<F extends (...args: never[]) => unknown>(name: string, fn: F, opts?: WrapOptions<Parameters<F>>): F;
+    /**
+     * Wraps a collection of tools and returns a copy of the same shape (objects are copied with their prototype; the
+     * originals are not modified). Detects `execute` (AI SDK, Mastra, Shardflux workspaceTools), `run` (Anthropic tool
+     * runner), `invoke` (OpenAI Agents FunctionTool, LangChain tools) and plain functions in an object. Throws TypeError
+     * for any other shape.
+     */
+    tools<T>(tools: T): T;
+    /** Runs `fn` with this capture active for `captureTool()` wrappers (AsyncLocalStorage). */
+    activate<T>(fn: () => T): T;
+    /** The paragraph you can put in a system prompt so the agent knows where its tool calls are (never injected). */
+    promptHint(): string;
+    /**
+     * Waits until every call recorded before it is written (or has failed), at most `timeoutMs` (default
+     * settleTimeoutMs). Never rejects. Serverless: `waitUntil(capture.flush())`, or `await capture.flush()` before
+     * returning.
+     */
+    flush(opts?: {
+        timeoutMs?: number;
+    }): Promise<CaptureFlushResult>;
+    /**
+     * Stops the capture: flushes what was recorded (bounded by `timeoutMs`), or drops it with `discard: true`, then
+     * ignores later records. Never rejects; calling it again returns the first close's result.
+     */
+    close(opts?: {
+        timeoutMs?: number;
+        discard?: boolean;
+    }): Promise<CaptureFlushResult>;
+    /** Framework adapters (created on first use). */
+    get adapters(): CaptureAdapters;
+    /** Vercel AI SDK: `tools: capture.aiSdk.tools(tools)` or `...capture.aiSdk.callbacks()`. */
+    get aiSdk(): CaptureAdapters['aiSdk'];
+    /** Mastra: `hooks: capture.mastra.hooks()` or `tools: capture.mastra.tools({...})`. */
+    get mastra(): CaptureAdapters['mastra'];
+    /** Anthropic SDK tool runner: `tools: capture.anthropic.tools([...])`. */
+    get anthropic(): CaptureAdapters['anthropic'];
+    /** OpenAI Agents JS: `capture.openaiAgents.attach(runner)` or `tools: capture.openaiAgents.tools([...])`. */
+    get openaiAgents(): CaptureAdapters['openaiAgents'];
+    /** Claude Agent SDK: `options.hooks = capture.claude.hooks(myHooks)`. */
+    get claude(): CaptureAdapters['claude'];
+    /** LangChain.js / LangGraph.js: `callbacks: [capture.langchain.handler()]`. */
+    get langchain(): CaptureAdapters['langchain'];
+    /** MCP client: `const release = capture.mcp.instrument(client, { server: 'github' })`. */
+    get mcp(): CaptureAdapters['mcp'];
+    /** Read-your-writes: waits for calls recorded so far (bounded, never rejects); undefined when nothing is pending. */
+    [SETTLE](): Promise<boolean> | undefined;
+    /** delete: drops pending writes and closes; reset: drops pending writes, the README is written again. */
+    [DISCARD](reason: 'delete' | 'reset'): void;
+}