@shardflux/sdk 0.6.2 → 0.8.0

package/dist/capture-adapters.js

@@ -0,0 +1,432 @@
+import { errorInfo, parseArguments } from "./capture-serialize.js";
+const str = (v) => (typeof v === 'string' && v.length > 0 ? v : null);
+const obj = (v) => (typeof v === 'object' && v !== null ? v : null);
+/** A copy of `target` with its prototype and own properties, and `key` replaced by `value` (the original is untouched). */
+export function copyWith(target, key, value) {
+    const descriptors = Object.getOwnPropertyDescriptors(target);
+    const own = descriptors[key];
+    descriptors[key] = { value, writable: true, configurable: true, enumerable: own ? own.enumerable === true : false };
+    return Object.create(Object.getPrototypeOf(target), descriptors);
+}
+function wrapMethod(target, key, spec, core) {
+    const original = target[key];
+    const wrapped = function (...args) {
+        let s;
+        try {
+            s = spec(args);
+        }
+        catch {
+            return original.apply(this, args);
+        }
+        return core.observe(s, original, this, args);
+    };
+    Object.defineProperty(wrapped, 'name', { value: original.name, configurable: true });
+    Object.defineProperty(wrapped, 'length', { value: original.length, configurable: true });
+    return copyWith(target, key, wrapped);
+}
+// ---- shape detection --------------------------------------------------------------------------------------------
+const toolName = (t, key) => key ?? str(t.name) ?? str(t.id) ?? 'tool';
+const isOpenAIFunctionTool = (t) => t.type === 'function' && typeof t.invoke === 'function' && 'parameters' in t;
+const isAnthropicRunnable = (t) => typeof t.run === 'function' && ('input_schema' in t || typeof t.parse === 'function');
+const isMastraTool = (t) => typeof t.execute === 'function' && Object.prototype.hasOwnProperty.call(t, 'mastra') && 'id' in t;
+const isWorkspaceTool = (t) => typeof t.execute === 'function' && 'permission' in t && 'parameters' in t;
+/** A tool definition without an executor (AI SDK provider or client-side tool, Anthropic server tool): left as it is. */
+const isDefinitionOnly = (t) => typeof t.execute !== 'function' && typeof t.run !== 'function' && typeof t.invoke !== 'function' && ('inputSchema' in t || 'input_schema' in t || 'parameters' in t || t.type === 'provider' || t.type === 'provider-defined');
+/** A Mastra ValidationError is returned, not thrown: recorded with status error. */
+function mastraPost(v) {
+    const o = obj(v);
+    if (o && o.error === true && 'validationErrors' in o)
+        return { output: v, status: 'error', error: { type: 'ValidationError', message: typeof o.message === 'string' ? o.message : 'validation failed' } };
+    return { output: v };
+}
+/** A LangChain ToolMessage: recorded as its content (plus artifact), status error when the message says so. */
+export function isToolMessage(v) {
+    const o = obj(v);
+    if (!o || typeof o.tool_call_id !== 'string' || !('content' in o))
+        return false;
+    try {
+        const getType = o._getType;
+        return o.type === 'tool' || (typeof getType === 'function' && getType.call(o) === 'tool') || o.constructor?.name === 'ToolMessage';
+    }
+    catch {
+        return false;
+    }
+}
+function toolMessagePost(v) {
+    if (!isToolMessage(v))
+        return { output: v };
+    const output = v.artifact !== undefined ? { content: v.content, artifact: v.artifact } : v.content;
+    if (v.status === 'error')
+        return { output, status: 'error', error: { type: 'ToolError', message: typeof v.content === 'string' ? v.content : JSON.stringify(v.content) } };
+    return { output };
+}
+/** An MCP CallToolResult with isError: status error, message from its first text block. */
+function mcpPost(v) {
+    const o = obj(v);
+    if (!o || (o.isError !== true && o.is_error !== true))
+        return { output: v };
+    const first = Array.isArray(o.content) ? o.content.map(obj).find((b) => b?.type === 'text' && typeof b.text === 'string') : undefined;
+    return { output: v, status: 'error', error: { type: 'McpToolError', message: first?.text ?? 'the tool reported an error' } };
+}
+function executeSpec(name, source, final, post) {
+    return (args) => {
+        const opts = obj(args[1]);
+        const callId = str(opts?.toolCallId) ?? str(obj(opts?.agent)?.toolCallId) ?? null;
+        return { tool: name, source, input: args[0], callId, final, ...(post ? { post } : {}) };
+    };
+}
+function wrapOne(core, t, key, preferred) {
+    if (typeof t === 'function') {
+        if (!key)
+            throw new TypeError('capture.tools(): a bare function needs a name; pass an object { name: fn }');
+        return wrapFunction(core, key, t);
+    }
+    const o = obj(t);
+    if (!o)
+        throw new TypeError(`capture.tools(): ${key ? `"${key}"` : 'an item'} is not a tool (got ${t === null ? 'null' : typeof t})`);
+    const name = toolName(o, key);
+    if (isOpenAIFunctionTool(o))
+        return wrapMethod(o, 'invoke', openAIInvokeSpec(name), core);
+    if (isAnthropicRunnable(o))
+        return wrapMethod(o, 'run', anthropicRunSpec(name), core);
+    if (typeof o.execute === 'function') {
+        if (isWorkspaceTool(o))
+            return wrapMethod(o, 'execute', executeSpec(name, 'workspace', false), core);
+        if (isMastraTool(o) || preferred === 'mastra')
+            return wrapMethod(o, 'execute', executeSpec(name, 'mastra', true, mastraPost), core);
+        if ('inputSchema' in o || preferred === 'ai-sdk')
+            return wrapMethod(o, 'execute', executeSpec(name, 'ai-sdk', true), core);
+        return wrapMethod(o, 'execute', executeSpec(name, preferred ?? 'wrap', false), core);
+    }
+    if (typeof o.invoke === 'function')
+        return wrapMethod(o, 'invoke', langchainInvokeSpec(name), core);
+    if (typeof o.run === 'function')
+        return wrapMethod(o, 'run', anthropicRunSpec(name), core);
+    if (isDefinitionOnly(o))
+        return o;
+    throw new TypeError(`capture.tools(): ${key ? `"${key}"` : `"${name}"`} has no execute, run or invoke method`);
+}
+function wrapFunction(core, name, fn) {
+    const wrapped = function (...args) {
+        return core.observe({ tool: name, source: 'wrap', input: args.length === 1 ? args[0] : args, callId: null }, fn, this, args);
+    };
+    Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+    Object.defineProperty(wrapped, 'length', { value: fn.length, configurable: true });
+    return wrapped;
+}
+const TOOL_METADATA = ['name', 'description', 'parameters', 'inputSchema', 'input_schema', 'schema', 'id'];
+/**
+ * One tool object, not a collection: an executor (`execute` / `run` / `invoke`) plus tool metadata (name, description,
+ * parameters or a schema), and not a record whose values are all functions: `{ execute: sqlFn, fetch_url: fetchFn }`
+ * is two plain-function tools, one of them named `execute`.
+ */
+function looksLikeOneTool(o) {
+    if (typeof o.execute !== 'function' && typeof o.run !== 'function' && typeof o.invoke !== 'function')
+        return false;
+    const values = Object.values(o);
+    if (values.length > 0 && values.every((v) => typeof v === 'function'))
+        return false;
+    return TOOL_METADATA.some((k) => k in o && typeof o[k] !== 'function' && o[k] !== undefined);
+}
+function wrapCollection(core, tools, preferred) {
+    if (Array.isArray(tools))
+        return tools.map((t) => wrapOne(core, t, undefined, preferred));
+    const o = obj(tools);
+    if (!o)
+        throw new TypeError(`capture.tools() takes an array or an object of tools (got ${tools === null ? 'null' : typeof tools})`);
+    if (looksLikeOneTool(o))
+        return wrapOne(core, o, undefined, preferred);
+    const out = Object.create(Object.getPrototypeOf(o));
+    for (const [k, v] of Object.entries(o))
+        out[k] = wrapOne(core, v, k, preferred);
+    return out;
+}
+// ---- per framework ----------------------------------------------------------------------------------------------
+function anthropicRunSpec(name) {
+    return (args) => {
+        const ctx = obj(args[1]);
+        const use = obj(ctx?.toolUse) ?? obj(ctx?.toolUseBlock);
+        return { tool: name, source: 'anthropic', input: args[0], callId: str(use?.id) };
+    };
+}
+function openAIInvokeSpec(name) {
+    return (args) => {
+        const details = obj(args[2]);
+        const call = obj(details?.toolCall);
+        return { tool: name, source: 'openai-agents', input: parseArguments(args[1]), callId: str(call?.callId) ?? str(call?.id) };
+    };
+}
+function langchainInvokeSpec(name) {
+    return (args) => {
+        const input = obj(args[0]);
+        const isCall = input !== null && input.type === 'tool_call' && 'args' in input;
+        const config = obj(args[1]);
+        const callId = (isCall ? str(input.id) : null) ?? str(obj(config?.toolCall)?.id);
+        return { tool: name, source: 'langchain', input: isCall ? input.args : args[0], callId, post: toolMessagePost };
+    };
+}
+const LANGCHAIN_PENDING = 10_000;
+const SHARDFLUX_MCP = '^mcp__shardflux__';
+export function createAdapters(core) {
+    const aiSdkEnd = (event) => {
+        try {
+            const call = event.toolCall ?? {};
+            const out = event.toolOutput;
+            let output;
+            let error;
+            if (out) {
+                if (out.type === 'tool-error')
+                    error = out.error ?? new Error('tool error');
+                else
+                    output = out.output;
+            }
+            else if (typeof event.success === 'boolean') {
+                if (event.success)
+                    output = event.output;
+                else
+                    error = event.error ?? new Error('tool error');
+            }
+            const durationMs = event.toolExecutionMs ?? event.durationMs;
+            core.hook({
+                tool: call.toolName ?? 'tool',
+                input: call.input,
+                output,
+                error,
+                callId: call.toolCallId ?? null,
+                ...(typeof durationMs === 'number' ? { durationMs, startedAt: Date.now() - durationMs } : {}),
+                source: 'ai-sdk',
+            });
+        }
+        catch {
+            // never into the harness
+        }
+    };
+    const aiSdk = {
+        tools: (tools) => wrapCollection(core, tools, 'ai-sdk'),
+        callbacks: ((opts = {}) => (opts.legacy ? { experimental_onToolCallFinish: aiSdkEnd } : { onToolExecutionEnd: aiSdkEnd })),
+    };
+    const mastra = {
+        hooks: (existing) => {
+            const theirs = existing?.afterToolCall;
+            return {
+                ...(existing ?? {}),
+                afterToolCall: async (ctx) => {
+                    try {
+                        const context = obj(ctx.context);
+                        const post = mastraPost(ctx.output);
+                        const agentId = str(obj(ctx.metadata)?.agentId);
+                        core.hook({
+                            tool: str(ctx.toolName) ?? 'tool',
+                            input: ctx.input,
+                            output: post.output,
+                            error: ctx.error ?? post.error,
+                            ...(post.status && ctx.error === undefined ? { status: post.status } : {}),
+                            callId: str(context?.toolCallId) ?? str(obj(context?.agent)?.toolCallId),
+                            ...(agentId ? { meta: { agent_id: agentId } } : {}),
+                            source: 'mastra',
+                        });
+                    }
+                    catch {
+                        // never into the harness
+                    }
+                    if (theirs)
+                        await theirs(ctx);
+                },
+            };
+        },
+        tools: (tools) => wrapCollection(core, tools, 'mastra'),
+    };
+    const anthropic = {
+        tools: (tools) => {
+            if (!Array.isArray(tools))
+                return wrapCollection(core, tools);
+            return tools.map((t) => {
+                const o = obj(t);
+                if (o && typeof o.run === 'function')
+                    return wrapMethod(o, 'run', anthropicRunSpec(toolName(o)), core);
+                return t; // server tools and plain definitions pass through
+            });
+        },
+    };
+    const openaiAgents = {
+        tools: (tools) => {
+            const one = (t) => {
+                const o = obj(t);
+                return o && typeof o.invoke === 'function' ? wrapMethod(o, 'invoke', openAIInvokeSpec(toolName(o)), core) : t;
+            };
+            return (Array.isArray(tools) ? tools.map(one) : one(tools));
+        },
+        execute: (name, fn) => {
+            const wrapped = function (...args) {
+                const call = obj(obj(args[2])?.toolCall);
+                return core.observe({ tool: name, source: 'openai-agents', input: args[0], callId: str(call?.callId) ?? str(call?.id) }, fn, this, args);
+            };
+            Object.defineProperty(wrapped, 'name', { value: fn.name, configurable: true });
+            Object.defineProperty(wrapped, 'length', { value: fn.length, configurable: true });
+            return wrapped;
+        },
+        attach: (target) => {
+            // Runner: (context, agent, tool, result, details); Agent: (context, tool, result, details). Read from the end.
+            const listener = (...args) => {
+                try {
+                    const details = obj(args[args.length - 1]);
+                    const result = args[args.length - 2];
+                    const tool = obj(args[args.length - 3]);
+                    const call = obj(details?.toolCall);
+                    core.hook({
+                        tool: str(tool?.name) ?? str(call?.name) ?? 'tool',
+                        input: parseArguments(call?.arguments),
+                        output: result,
+                        callId: str(call?.callId) ?? str(call?.id),
+                        source: 'openai-agents',
+                    });
+                }
+                catch {
+                    // never into the harness
+                }
+            };
+            target.on('agent_tool_end', listener);
+            return () => {
+                target.off('agent_tool_end', listener);
+            };
+        },
+    };
+    const claude = {
+        hooks: (existing) => {
+            const record = (input, toolUseID, failed) => {
+                try {
+                    const i = obj(input) ?? {};
+                    const meta = {};
+                    if (str(i.agent_id))
+                        meta.agent_id = i.agent_id;
+                    if (str(i.agent_type))
+                        meta.agent_type = i.agent_type;
+                    if (str(obj(i.mcp_server)?.name))
+                        meta.server = obj(i.mcp_server).name;
+                    const durationMs = typeof i.duration_ms === 'number' ? i.duration_ms : undefined;
+                    core.hook({
+                        tool: str(i.tool_name) ?? 'tool',
+                        input: i.tool_input,
+                        ...(failed
+                            ? { error: { type: i.is_interrupt === true ? 'Interrupted' : 'ToolError', message: typeof i.error === 'string' ? i.error : errorInfo(i.error).message }, status: i.is_interrupt === true ? 'cancelled' : 'error' }
+                            : { output: i.tool_response }),
+                        callId: str(i.tool_use_id) ?? str(toolUseID),
+                        ...(durationMs !== undefined ? { durationMs, startedAt: Date.now() - durationMs } : {}),
+                        ...(Object.keys(meta).length > 0 ? { meta } : {}),
+                        source: 'claude-agent-sdk',
+                    });
+                }
+                catch {
+                    // never into the harness
+                }
+            };
+            const base = { ...(existing ?? {}) };
+            const add = (event, m) => [...(base[event] ?? []), m];
+            return {
+                ...base,
+                PreToolUse: add('PreToolUse', {
+                    matcher: SHARDFLUX_MCP,
+                    hooks: [
+                        async () => {
+                            await core.settle();
+                            return {};
+                        },
+                    ],
+                }),
+                PostToolUse: add('PostToolUse', {
+                    hooks: [
+                        (input, toolUseID) => {
+                            record(input, toolUseID, false);
+                            return Promise.resolve({});
+                        },
+                    ],
+                }),
+                PostToolUseFailure: add('PostToolUseFailure', {
+                    hooks: [
+                        (input, toolUseID) => {
+                            record(input, toolUseID, true);
+                            return Promise.resolve({});
+                        },
+                    ],
+                }),
+            };
+        },
+    };
+    const langchain = {
+        handler: () => {
+            const pending = new Map();
+            const take = (runId) => {
+                const p = pending.get(runId);
+                pending.delete(runId);
+                return p;
+            };
+            return {
+                handleToolStart(tool, input, runId, _parentRunId, _tags, _metadata, runName, toolCallId) {
+                    try {
+                        const t = obj(tool);
+                        const ids = Array.isArray(t?.id) ? t.id : [];
+                        const name = str(runName) ?? str(t?.name) ?? str(ids[ids.length - 1]) ?? 'tool';
+                        pending.set(runId, { tool: name, input: parseArguments(input), callId: str(toolCallId), startedAt: Date.now() });
+                        if (pending.size > LANGCHAIN_PENDING)
+                            pending.delete(pending.keys().next().value);
+                    }
+                    catch {
+                        // never into the harness
+                    }
+                },
+                handleToolEnd(output, runId) {
+                    try {
+                        const p = take(runId);
+                        const post = toolMessagePost(output);
+                        const msg = isToolMessage(output) ? output : null;
+                        core.hook({
+                            tool: p?.tool ?? str(msg?.name) ?? 'tool',
+                            input: p?.input,
+                            output: post.output,
+                            ...(post.error !== undefined ? { error: post.error } : {}),
+                            ...(post.status ? { status: post.status } : {}),
+                            callId: p?.callId ?? str(msg?.tool_call_id),
+                            ...(p ? { startedAt: p.startedAt, durationMs: Date.now() - p.startedAt } : {}),
+                            source: 'langchain',
+                        });
+                    }
+                    catch {
+                        // never into the harness
+                    }
+                },
+                handleToolError(err, runId) {
+                    try {
+                        const p = take(runId);
+                        core.hook({ tool: p?.tool ?? 'tool', input: p?.input, error: err ?? new Error('tool error'), callId: p?.callId ?? null, ...(p ? { startedAt: p.startedAt, durationMs: Date.now() - p.startedAt } : {}), source: 'langchain' });
+                    }
+                    catch {
+                        // never into the harness
+                    }
+                },
+            };
+        },
+    };
+    const mcp = {
+        instrument: (client, opts = {}) => {
+            const target = client;
+            const hadOwn = Object.prototype.hasOwnProperty.call(target, 'callTool');
+            const ownBefore = target.callTool;
+            const original = client.callTool;
+            const meta = opts.server ? { server: opts.server } : undefined;
+            const patched = function (...args) {
+                const params = obj(args[0]);
+                return core.observe({ tool: str(params?.name) ?? 'tool', source: 'mcp', input: params?.arguments ?? {}, callId: null, hookLevel: true, post: mcpPost, ...(meta ? { meta } : {}) }, original, this, args);
+            };
+            target.callTool = patched;
+            return () => {
+                if (target.callTool !== patched)
+                    return; // patched again by someone else: leave theirs
+                if (hadOwn)
+                    target.callTool = ownBefore;
+                else
+                    delete target.callTool;
+            };
+        },
+    };
+    return { wrapAny: (tools) => wrapCollection(core, tools), aiSdk, mastra, anthropic, openaiAgents, claude, langchain, mcp };
+}

package/dist/capture-serialize.d.ts

@@ -0,0 +1,97 @@
+/** One file to write, `path` relative to the run directory. */
+export interface StoredFile {
+    path: string;
+    data: Uint8Array;
+    contentType: string;
+    sha256: string;
+}
+/** An entry of the index line's `parts` (multi-part outputs). */
+export interface CapturePart {
+    path: string;
+    content_type: string;
+    bytes: number;
+    sha256: string;
+}
+export type DropReason = 'queue_full' | 'too_large' | 'write_failed' | 'serialize_failed';
+/** What an output becomes: the files to store (in write order) and the index line's output fields. */
+export interface OutputPlan {
+    files: StoredFile[];
+    outputPath: string | null;
+    contentType: string | null;
+    /** Bytes of every stored file. */
+    bytes: number;
+    sha256: string | null;
+    truncated: boolean;
+    parts?: CapturePart[];
+    dropped?: DropReason;
+    /** `stream_not_captured` for a Response, ReadableStream, Node stream or Blob (never read). */
+    note?: string;
+}
+export declare const DEFAULT_MAX_OUTPUT_BYTES: number;
+export declare const sha256Hex: (data: Uint8Array) => string;
+/**
+ * The tool name as used in file names: every Unicode code point outside `[A-Za-z0-9._-]` becomes `_`, cut to 64
+ * characters; an empty result becomes `tool`.
+ */
+export declare function sanitizeToolName(name: string): string;
+/** Sequence numbers in file names: zero-padded to 6 digits (more digits past 999999). */
+export declare const padSeq: (seq: number) => string;
+/** Raw bytes as the capture stores them: Uint8Array (and Buffer), ArrayBuffer, DataView. Other typed arrays are JSON. */
+export declare function asBytes(value: unknown): Uint8Array | null;
+/** Extension and content type from magic bytes; `.bin` `application/octet-stream` when none matches. */
+export declare function sniff(bytes: Uint8Array): {
+    ext: string;
+    contentType: string;
+};
+/**
+ * Values capture never reads (reading would consume them): Response, ReadableStream, Node streams, Blob, generator
+ * objects and other async iterables (a wrapped tool's async generator is teed instead; see capture.ts).
+ */
+export declare function isUnreadable(value: unknown): boolean;
+/** Parses a JSON arguments string (OpenAI); anything else is kept as it is. An empty string is `{}`. */
+export declare function parseArguments(v: unknown): unknown;
+/** An error as the index line and outputs carry it: `{type, message}`. */
+export declare function errorInfo(err: unknown): {
+    type: string;
+    message: string;
+};
+/**
+ * Converts any value to plain JSON data (objects, arrays, strings, finite numbers, booleans, null): `toJSON`, Date →
+ * ISO string, Map → object, Set → array, BigInt → string, NaN/Infinity → null, errors → `{type, message}`, nested bytes
+ * → `{"$base64"}`, cycles → `"[Circular]"`, unconvertible → `{"$type","$repr"}`. Functions and symbols inside objects
+ * are left out and inside arrays become null, as in JSON.stringify. Never throws. `undefined` at the top stays
+ * undefined.
+ */
+export declare function toJsonSafe(value: unknown): unknown;
+/** Compact JSON of any value (via toJsonSafe); never throws. Undefined becomes `null`. */
+export declare function safeStringify(value: unknown): string;
+/** A JSON object or array in strict JSON (no NaN/Infinity), surrounded only by JSON whitespace. */
+export declare function isJsonContainerText(s: string): boolean;
+/** The longest prefix of at most `max` bytes that ends on a UTF-8 character boundary. */
+export declare function cutUtf8(bytes: Uint8Array, max: number): Uint8Array;
+export declare function dropped(reason: DropReason, note?: string): OutputPlan;
+type Json = null | boolean | number | string | Json[] | {
+    [k: string]: Json;
+};
+/** An MCP-like result: `content` a non-empty array of objects with a string `type`, other keys from the MCP set. */
+export declare function isMcpLike(v: unknown): v is {
+    content: Array<Record<string, Json>>;
+} & Record<string, Json>;
+/** A content-block array: non-empty, every item an object whose `type` is a known block type. */
+export declare function isBlockArray(v: unknown): v is Array<Record<string, Json>>;
+/**
+ * Plans how `value` is stored. `base` is `<seq>-<tool>` (zero-padded seq, sanitized tool name). Never throws.
+ */
+export declare function planOutput(value: unknown, base: string, maxOutputBytes?: number): OutputPlan;
+/** Items of an async iterable as `.jsonl` (rule 7): one compact JSON line per item, cut at `max` bytes. */
+export declare class JsonlCollector {
+    #private;
+    truncated: boolean;
+    count: number;
+    constructor(max: number);
+    push(item: unknown): void;
+    /** The items collected so far, parsed back (a cut last line is left out). */
+    values(): unknown[];
+    plan(base: string): OutputPlan;
+}
+export {};