@deepstrike/wasm 0.2.19 → 0.2.20

package/dist/index.d.ts

@@ -1,4 +1,5 @@
-export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./runtime/index.js";
+export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, ReplayProvider, extractRecordedMessages, judge, buildEvalMessages, parseVerdict, verdictOutputSchema, } from "./runtime/index.js";
+export type { ReplayProviderOpts, Criterion, Verdict, VerdictDetail, JudgeArgs, } from "./runtime/index.js";
 export type { NativeOsProfile, OsProfileId, MemoryPolicy, MemoryWriteRateLimit, ResourceQuota, RuntimeOptions, SchedulerBudget, SessionEvent, SessionLog, RunContext, ExecutionPlane, } from "./runtime/index.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";

package/dist/index.js

@@ -1,4 +1,4 @@
-export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./runtime/index.js";
+export { RuntimeRunner, collectText, InMemorySessionLog, LocalExecutionPlane, DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, ReplayProvider, extractRecordedMessages, judge, buildEvalMessages, parseVerdict, verdictOutputSchema, } from "./runtime/index.js";
 export { FilteredExecutionPlane } from "./runtime/filtered-plane.js";
 export { SubAgentOrchestrator, defaultSubAgentOrchestrator, spawnStandalone } from "./runtime/sub-agent-orchestrator.js";
 export { workflowSpecToKernel, workflowNodeSpecToKernel, submitWorkflowNodesToKernel, submitWorkflowToKernel, submitWorkflowNodesTool, startWorkflowTool, fanoutSynthesize, generateAndFilter, verifyRules } from "./runtime/types/agent.js";

package/dist/runtime/eval.d.ts

@@ -0,0 +1,45 @@
+/**
+ * `judge()` — one-shot quality scoring against a goal + criteria using the kernel's `gen_eval`.
+ *
+ * Mirrors the Node SDK's `node/src/runtime/eval.ts`. WASM port differences:
+ *   - The kernel is loaded asynchronously via `getKernel()`, so the wrapper functions are async
+ *     where the Node versions are sync. `judge()` was already async on both ports.
+ *
+ * See node/src/runtime/eval.ts for the full design rationale.
+ */
+import type { LLMProvider, Message } from "../types.js";
+export interface Criterion {
+    text: string;
+    required?: boolean;
+    weight?: number;
+}
+export interface VerdictDetail {
+    criterion: string;
+    passed: boolean;
+    score: number;
+    feedback: string;
+}
+export interface Verdict {
+    passed: boolean;
+    overallScore: number;
+    feedback: string;
+    details: VerdictDetail[];
+}
+export interface JudgeArgs {
+    provider: LLMProvider;
+    goal: string;
+    criteria: Criterion[];
+    result: string;
+    signal?: AbortSignal;
+}
+/** Build the kernel's eval prompt for (goal, criteria, result). Async — the WASM kernel loads lazily. */
+export declare function buildEvalMessages(goal: string, criteria: Criterion[], result: string): Promise<Message[]>;
+/** Parse a Verdict from raw judge-LLM text. */
+export declare function parseVerdict(text: string): Promise<Verdict>;
+/** The JSON Schema the kernel expects judge output to conform to. */
+export declare function verdictOutputSchema(): Promise<Record<string, unknown>>;
+/**
+ * Run one judge pass: render the eval prompt, stream the provider, parse the verdict.
+ * Throws when the provider returns no text.
+ */
+export declare function judge(args: JudgeArgs): Promise<Verdict>;

package/dist/runtime/eval.js

@@ -0,0 +1,51 @@
+/**
+ * `judge()` — one-shot quality scoring against a goal + criteria using the kernel's `gen_eval`.
+ *
+ * Mirrors the Node SDK's `node/src/runtime/eval.ts`. WASM port differences:
+ *   - The kernel is loaded asynchronously via `getKernel()`, so the wrapper functions are async
+ *     where the Node versions are sync. `judge()` was already async on both ports.
+ *
+ * See node/src/runtime/eval.ts for the full design rationale.
+ */
+import { getKernel } from "./kernel.js";
+/** Build the kernel's eval prompt for (goal, criteria, result). Async — the WASM kernel loads lazily. */
+export async function buildEvalMessages(goal, criteria, result) {
+    const kernel = await getKernel();
+    return kernel.buildEvalMessages(goal, criteria.map(c => ({ text: c.text, required: c.required ?? true, weight: c.weight })), result, 1, false);
+}
+/** Parse a Verdict from raw judge-LLM text. */
+export async function parseVerdict(text) {
+    const kernel = await getKernel();
+    const v = kernel.parseVerdict(text);
+    return {
+        passed: v.passed,
+        overallScore: v.overallScore,
+        feedback: v.feedback,
+        details: (v.details ?? []),
+    };
+}
+/** The JSON Schema the kernel expects judge output to conform to. */
+export async function verdictOutputSchema() {
+    const kernel = await getKernel();
+    return JSON.parse(kernel.verdictOutputSchema(false));
+}
+/**
+ * Run one judge pass: render the eval prompt, stream the provider, parse the verdict.
+ * Throws when the provider returns no text.
+ */
+export async function judge(args) {
+    const msgs = await buildEvalMessages(args.goal, args.criteria, args.result);
+    const ctx = {
+        systemText: msgs.filter(m => m.role === "system").map(m => m.content).join("\n\n"),
+        turns: msgs.filter(m => m.role !== "system"),
+    };
+    let text = "";
+    for await (const evt of args.provider.stream(ctx, [], undefined, undefined, args.signal)) {
+        if (evt.type === "text_delta")
+            text += evt.delta;
+    }
+    if (!text) {
+        throw new Error("judge: provider produced no text");
+    }
+    return parseVerdict(text);
+}

package/dist/runtime/index.d.ts

@@ -7,5 +7,10 @@ export { RuntimeRunner, collectText } from "./runner.js";
 export { builtinReducers, resolveReducer } from "./reducers.js";
 export type { Reducer, ReducerRegistry, ReducerInput } from "./reducers.js";
 export { getKernel } from "./kernel.js";
+export { ReplayProvider } from "./replay-provider.js";
+export type { ReplayProviderOpts } from "./replay-provider.js";
+export { extractRecordedMessages } from "./replay-fixture.js";
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./eval.js";
+export type { Criterion, Verdict, VerdictDetail, JudgeArgs } from "./eval.js";
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./os-profile.js";
 export type { NativeOsProfile, OsProfileId } from "./os-profile.js";

package/dist/runtime/index.js

@@ -3,4 +3,7 @@ export { LocalExecutionPlane } from "./execution-plane.js";
 export { RuntimeRunner, collectText } from "./runner.js";
 export { builtinReducers, resolveReducer } from "./reducers.js";
 export { getKernel } from "./kernel.js";
+export { ReplayProvider } from "./replay-provider.js";
+export { extractRecordedMessages } from "./replay-fixture.js";
+export { judge, buildEvalMessages, parseVerdict, verdictOutputSchema } from "./eval.js";
 export { DEFAULT_NATIVE_ATTENTION_POLICY, DEFAULT_NATIVE_GOVERNANCE_POLICY, DEFAULT_SANDBOX_POLICY, assertNativeProfile, osProfile, validateDeclarativePolicy, } from "./os-profile.js";

package/dist/runtime/replay-fixture.d.ts

@@ -0,0 +1,26 @@
+/**
+ * Fixture helpers for `ReplayProvider`.
+ *
+ * The canonical persistence shape for a recorded run is a `SessionLog` of `llm_completed` events
+ * (already written by the runner on every live run). `extractRecordedMessages` walks such a log and
+ * pulls the assistant turns in order, so the fixture is just "a prior session log + the messages
+ * the LLM produced". No new on-disk format.
+ */
+import type { Message } from "../types.js";
+import type { SessionEvent } from "./session-log.js";
+/**
+ * Extract the ordered list of assistant Messages from a recorded session log.
+ *
+ * Walks `llm_completed` events (which is what the runner appends for every LLM call) and produces
+ * one Message per event. Pass the result directly to `new ReplayProvider(messages)`.
+ *
+ * Accepts both wire shapes the SDK uses interchangeably:
+ *   - in-memory: `{ toolCalls, tokenCount, providerReplay }` (camelCase)
+ *   - serialised session-log: `{ tool_calls, token_count, provider_replay }` (snake_case)
+ *
+ * @param events Session events, in original order. Accepts both `{ event, seq }` (the shape
+ *               `SessionLog.read()` returns) and a bare `SessionEvent[]`.
+ */
+export declare function extractRecordedMessages(events: Array<{
+    event: SessionEvent;
+} | SessionEvent>): Message[];

package/dist/runtime/replay-fixture.js

@@ -0,0 +1,51 @@
+/**
+ * Fixture helpers for `ReplayProvider`.
+ *
+ * The canonical persistence shape for a recorded run is a `SessionLog` of `llm_completed` events
+ * (already written by the runner on every live run). `extractRecordedMessages` walks such a log and
+ * pulls the assistant turns in order, so the fixture is just "a prior session log + the messages
+ * the LLM produced". No new on-disk format.
+ */
+/**
+ * Extract the ordered list of assistant Messages from a recorded session log.
+ *
+ * Walks `llm_completed` events (which is what the runner appends for every LLM call) and produces
+ * one Message per event. Pass the result directly to `new ReplayProvider(messages)`.
+ *
+ * Accepts both wire shapes the SDK uses interchangeably:
+ *   - in-memory: `{ toolCalls, tokenCount, providerReplay }` (camelCase)
+ *   - serialised session-log: `{ tool_calls, token_count, provider_replay }` (snake_case)
+ *
+ * @param events Session events, in original order. Accepts both `{ event, seq }` (the shape
+ *               `SessionLog.read()` returns) and a bare `SessionEvent[]`.
+ */
+export function extractRecordedMessages(events) {
+    const out = [];
+    for (const entry of events) {
+        const event = isWrapped(entry) ? entry.event : entry;
+        if (event.kind !== "llm_completed")
+            continue;
+        const e = event;
+        const tcRaw = (e.toolCalls ?? e.tool_calls);
+        const tokenCount = (e.tokenCount ?? e.token_count);
+        out.push({
+            role: "assistant",
+            content: typeof e.content === "string" ? e.content : "",
+            ...(Array.isArray(tcRaw) && tcRaw.length > 0
+                ? { toolCalls: normalizeToolCalls(tcRaw) }
+                : {}),
+            ...(tokenCount !== undefined ? { tokenCount } : {}),
+        });
+    }
+    return out;
+}
+function isWrapped(x) {
+    return !!x && typeof x === "object" && "event" in x;
+}
+function normalizeToolCalls(tcs) {
+    return tcs.map(tc => ({
+        id: tc.id,
+        name: tc.name,
+        arguments: typeof tc.arguments === "string" ? tc.arguments : JSON.stringify(tc.arguments),
+    }));
+}

package/dist/runtime/replay-provider.d.ts

@@ -0,0 +1,69 @@
+/**
+ * ReplayProvider — an LLMProvider that emits previously-recorded assistant messages
+ * instead of calling a real LLM API.
+ *
+ * Purpose: deterministic re-runs for benchmarking, CI, and golden regression. Useful when you want
+ * to hold the model's behavior constant and measure something else (prompt-size cost Δ across
+ * RuntimeOptions variants, codegen of follow-on kernel work, etc.).
+ *
+ * Distinct from `provider-replay.ts`: that file's `seedProviderReplay` / `peekProviderReplay` is a
+ * session-repair *reasoning-content cache* — it preserves `reasoning_content` / `native_blocks` so
+ * the model sees its own thinking when context is re-rendered. It does NOT skip LLM calls.
+ * `ReplayProvider` is the orthogonal, request-skipping mechanism: it returns recorded responses
+ * directly, never hitting an API.
+ *
+ * Cost-accounting under replay:
+ *   - `inputTokens` is ESTIMATED from the rendered context this call carries (NOT a recorded value
+ *     from the original run). That's the point of replay-for-benchmarking: prompt may differ across
+ *     variants, response is pinned, so a cost Δ purely reflects the prompt change.
+ *   - `outputTokens` is taken from `message.tokenCount` when present; otherwise estimated from
+ *     `message.content.length / 4`.
+ *   - `cacheReadInputTokens` / `cacheCreationInputTokens` are emitted as 0 — replay has no real
+ *     cache state. Mechanisms whose Δ depends on cache behavior must validate with a live A/B too.
+ *
+ * Tokenizer: by default a `chars/4` estimator (±20% for English; worse for code/JSON). For tighter
+ * numbers plug `opts.tokenizer = tiktokenEncoder` or similar.
+ */
+import type { LLMProvider, Message, ProviderDescriptor, ProviderRunState, RenderedContext, StreamEvent, ToolSchema } from "../types.js";
+export interface ReplayProviderOpts {
+    /**
+     * Maps a rendered-context text payload to a token count. Defaults to `chars / 4`.
+     * Pass a real encoder (tiktoken etc.) for accurate cost accounting under replay.
+     */
+    tokenizer?: (text: string) => number;
+    /**
+     * Provider descriptor advertised via `descriptor()`. Defaults to a generic
+     * `{ provider: "replay", protocol: "replay", ... }` shape. Override when a downstream consumer
+     * needs to detect the original provider (e.g., for protocol-specific decoding paths).
+     */
+    descriptor?: ProviderDescriptor;
+    /**
+     * When true, `stream()` and `complete()` wrap to the start once the fixture is exhausted,
+     * instead of throwing. Useful for loop tests that need to keep going past the recorded length.
+     * Defaults to false.
+     */
+    wrap?: boolean;
+}
+export declare class ReplayProvider implements LLMProvider {
+    private cursor;
+    private readonly messages;
+    private readonly tokenizer;
+    private readonly _descriptor;
+    private readonly wrap;
+    /**
+     * @param messages Ordered list of assistant messages to replay (one per LLM call).
+     * @param opts Optional tokenizer / descriptor / wrap-around behavior.
+     */
+    constructor(messages: ReadonlyArray<Message>, opts?: ReplayProviderOpts);
+    descriptor(): ProviderDescriptor;
+    /** Number of messages consumed so far. */
+    consumed(): number;
+    /** Number of messages remaining in the fixture (returns 0 in wrap mode once cursor passes end). */
+    remaining(): number;
+    /** Reset the cursor — useful for re-running the same fixture in a fresh session. */
+    reset(): void;
+    complete(_context: RenderedContext, _tools: ToolSchema[]): Promise<Message>;
+    stream(context: RenderedContext, tools: ToolSchema[], _extensions?: Record<string, unknown>, _state?: ProviderRunState, _signal?: AbortSignal): AsyncIterable<StreamEvent>;
+    private pull;
+    private estimateInputTokens;
+}

package/dist/runtime/replay-provider.js

@@ -0,0 +1,152 @@
+/**
+ * ReplayProvider — an LLMProvider that emits previously-recorded assistant messages
+ * instead of calling a real LLM API.
+ *
+ * Purpose: deterministic re-runs for benchmarking, CI, and golden regression. Useful when you want
+ * to hold the model's behavior constant and measure something else (prompt-size cost Δ across
+ * RuntimeOptions variants, codegen of follow-on kernel work, etc.).
+ *
+ * Distinct from `provider-replay.ts`: that file's `seedProviderReplay` / `peekProviderReplay` is a
+ * session-repair *reasoning-content cache* — it preserves `reasoning_content` / `native_blocks` so
+ * the model sees its own thinking when context is re-rendered. It does NOT skip LLM calls.
+ * `ReplayProvider` is the orthogonal, request-skipping mechanism: it returns recorded responses
+ * directly, never hitting an API.
+ *
+ * Cost-accounting under replay:
+ *   - `inputTokens` is ESTIMATED from the rendered context this call carries (NOT a recorded value
+ *     from the original run). That's the point of replay-for-benchmarking: prompt may differ across
+ *     variants, response is pinned, so a cost Δ purely reflects the prompt change.
+ *   - `outputTokens` is taken from `message.tokenCount` when present; otherwise estimated from
+ *     `message.content.length / 4`.
+ *   - `cacheReadInputTokens` / `cacheCreationInputTokens` are emitted as 0 — replay has no real
+ *     cache state. Mechanisms whose Δ depends on cache behavior must validate with a live A/B too.
+ *
+ * Tokenizer: by default a `chars/4` estimator (±20% for English; worse for code/JSON). For tighter
+ * numbers plug `opts.tokenizer = tiktokenEncoder` or similar.
+ */
+const DEFAULT_DESCRIPTOR = {
+    provider: "replay",
+    protocol: "openai-chat",
+    model: "replay",
+    reasoning: { supported: false, preserveAcrossToolTurns: false },
+    toolCalls: { supported: true, requiresStrictPairing: false },
+};
+export class ReplayProvider {
+    cursor = 0;
+    messages;
+    tokenizer;
+    _descriptor;
+    wrap;
+    /**
+     * @param messages Ordered list of assistant messages to replay (one per LLM call).
+     * @param opts Optional tokenizer / descriptor / wrap-around behavior.
+     */
+    constructor(messages, opts = {}) {
+        this.messages = messages;
+        this.tokenizer = opts.tokenizer ?? defaultTokenizer;
+        this._descriptor = opts.descriptor ?? DEFAULT_DESCRIPTOR;
+        this.wrap = !!opts.wrap;
+    }
+    descriptor() {
+        return this._descriptor;
+    }
+    /** Number of messages consumed so far. */
+    consumed() {
+        return this.cursor;
+    }
+    /** Number of messages remaining in the fixture (returns 0 in wrap mode once cursor passes end). */
+    remaining() {
+        return Math.max(0, this.messages.length - this.cursor);
+    }
+    /** Reset the cursor — useful for re-running the same fixture in a fresh session. */
+    reset() {
+        this.cursor = 0;
+    }
+    async complete(_context, _tools) {
+        const msg = this.pull();
+        return {
+            role: "assistant",
+            content: msg.content,
+            ...(msg.toolCalls ? { toolCalls: msg.toolCalls } : {}),
+            ...(msg.tokenCount !== undefined ? { tokenCount: msg.tokenCount } : {}),
+        };
+    }
+    async *stream(context, tools, _extensions, _state, _signal) {
+        const msg = this.pull();
+        const inputTokens = this.estimateInputTokens(context, tools);
+        const outputTokens = msg.tokenCount !== undefined ? msg.tokenCount : this.tokenizer(msg.content || "");
+        const usage = {
+            type: "usage",
+            totalTokens: inputTokens + outputTokens,
+            inputTokens,
+            outputTokens,
+            cacheReadInputTokens: 0,
+            cacheCreationInputTokens: 0,
+        };
+        yield usage;
+        if (msg.content) {
+            const delta = { type: "text_delta", delta: msg.content };
+            yield delta;
+        }
+        for (const tc of msg.toolCalls ?? []) {
+            let args = {};
+            try {
+                args = JSON.parse(tc.arguments || "{}");
+            }
+            catch {
+                // Malformed recorded arguments — pass an empty object. The runner's downstream tool
+                // execution will surface the error if the tool needs them.
+            }
+            const call = { type: "tool_call", id: tc.id, name: tc.name, arguments: args };
+            yield call;
+        }
+    }
+    pull() {
+        if (this.cursor >= this.messages.length) {
+            if (this.wrap && this.messages.length > 0) {
+                this.cursor = 0;
+            }
+            else {
+                throw new Error(`ReplayProvider: fixture exhausted (consumed=${this.cursor}, total=${this.messages.length})`);
+            }
+        }
+        return this.messages[this.cursor++];
+    }
+    estimateInputTokens(context, tools) {
+        const text = renderContextToText(context, tools);
+        return this.tokenizer(text);
+    }
+}
+// ── helpers ───────────────────────────────────────────────────────────────────
+function defaultTokenizer(text) {
+    return Math.ceil(text.length / 4);
+}
+function renderContextToText(context, tools) {
+    const parts = [];
+    if (context.systemText)
+        parts.push(context.systemText);
+    if (context.systemStable)
+        parts.push(context.systemStable);
+    if (context.systemKnowledge)
+        parts.push(context.systemKnowledge);
+    if (context.stateTurn?.content)
+        parts.push(context.stateTurn.content);
+    for (const turn of context.turns ?? []) {
+        if (turn.content)
+            parts.push(turn.content);
+        for (const part of turn.contentParts ?? []) {
+            const p = part;
+            if (typeof p.output === "string")
+                parts.push(p.output);
+            else if (typeof p.text === "string")
+                parts.push(p.text);
+        }
+        for (const tc of turn.toolCalls ?? []) {
+            parts.push(`${tc.name} ${tc.arguments}`);
+        }
+    }
+    for (const tool of tools) {
+        parts.push(`${tool.name} ${tool.description} ${tool.parameters}`);
+    }
+    return parts.join("\n");
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@deepstrike/wasm",
-  "version": "0.2.19",
+  "version": "0.2.20",
   "description": "DeepStrike WASM SDK — browser, Cloudflare Workers, Deno Deploy",
   "type": "module",
   "main": "dist/index.js",
@@ -15,7 +15,7 @@
     "test": "node --experimental-vm-modules node_modules/.bin/jest"
   },
   "dependencies": {
-    "@deepstrike/wasm-kernel": "0.2.19"
+    "@deepstrike/wasm-kernel": "0.2.20"
   },
   "devDependencies": {
     "@types/jest": "^30.0.0",