@axiastudio/aioc 0.1.0-beta.2 → 0.1.0-beta.3

package/README.md

@@ -64,6 +64,10 @@ Canonical examples reference:
 - run record hook via `run(..., { record })` for external persistence/audit adapters
 - run record prompt snapshots per turn (`turn`, `agentName`, `promptVersion`, `promptHash`, optional `promptText`)
 - run record request fingerprints per turn (`requestHash`, segment hashes, `runtimeVersion`, `fingerprintSchemaVersion`)
+- run record utilities:
+  - `extractToolCalls(...)`
+  - `compareRunRecords(...)`
+  - `replayFromRunRecord(...)` with modes `live | strict | hybrid`
 - JSON helper `toJsonValue(...)` to map runtime artifacts (for example `RunRecord.items`) into JSON-safe values for storage adapters
 - message helpers `user(...)`, `assistant(...)`, `system(...)`
 - `setDefaultProvider(...)`
@@ -92,6 +96,63 @@ Privacy baseline highlights:
 - `record.contextRedactor` should be considered mandatory for production run-record persistence.
 - sink adapters should implement encryption, access controls, retention, and deletion policies.
 
+## RunRecord Utilities
+
+### `extractToolCalls(...)`
+
+```ts
+import { extractToolCalls } from "@axiastudio/aioc";
+
+const calls = extractToolCalls(runRecord);
+// [{ callId, name, arguments, output?, hasOutput, turn?, argsCanonicalJson, argsHash }]
+```
+
+### `compareRunRecords(...)`
+
+```ts
+import { compareRunRecords } from "@axiastudio/aioc";
+
+const comparison = compareRunRecords(runRecordA, runRecordB, {
+  responseMatchMode: "exact",
+  includeSections: ["response", "toolCalls", "policy", "guardrails", "metadata"],
+});
+
+if (!comparison.equal) {
+  console.log(comparison.summary);
+  console.log(comparison.metrics);
+  console.log(comparison.differences);
+}
+```
+
+### `replayFromRunRecord(...)` (strict)
+
+```ts
+import { allow, replayFromRunRecord } from "@axiastudio/aioc";
+
+const replay = await replayFromRunRecord({
+  sourceRunRecord,
+  agent,
+  mode: "strict",
+  runOptions: {
+    policies: {
+      toolPolicy: () => allow("allow_replay"),
+    },
+  },
+});
+
+console.log(replay.result.finalOutput);
+console.log(replay.replayStats);
+```
+
+`replayFromRunRecord(...)` does not bypass policy enforcement: in `strict` and `hybrid` modes, provide `runOptions.policies` when tool/handoff execution must be authorized.
+
+### Minimal examples (step-by-step)
+
+- `npm run example:rru:01-extract` (`extractToolCalls(...)` from a static `RunRecord`)
+- `npm run example:rru:02-compare` (`compareRunRecords(...)` with structured diff output)
+- `npm run example:rru:03-replay-strict` (`replayFromRunRecord(...)` in `strict` mode)
+- `npm run example:rru:04-replay-hybrid` (`replayFromRunRecord(...)` in `hybrid` mode)
+
 ## Test Commands
 
 - `npm run test:unit`
@@ -104,34 +165,12 @@ Privacy baseline highlights:
 - `npm run example:hello` (minimal single-agent run)
 - `npm run example:tool-policy` (tool calls with deterministic policy gate)
 - `npm run example:run-record` (run record persistence with redaction + audit)
+- `npm run example:rru:01-extract` (minimal extract tool-calls example)
+- `npm run example:rru:02-compare` (minimal run-record comparison example)
+- `npm run example:rru:03-replay-strict` (minimal strict replay example)
+- `npm run example:rru:04-replay-hybrid` (minimal hybrid replay example)
 - `npm run example:non-regression` (advanced v1/v2 run-record diff)
 
-## Python Alpha Port
-
-Python runtime is available under `py/` (Python 3.11+), with governance-first parity against core TS semantics:
-
-- `Agent`, `RunContext`, `run(...)` (stream/non-stream), tool registration, handoff
-- deterministic default-deny policy gates for tool/handoff
-- unified tool/handoff output envelope `{ status, code, publicReason, data }`
-- typed runtime errors for deny/guardrail/max-turns
-- run record sink adapter + context redaction + policy/guardrail decision capture
-- provider setup helpers: `setup_mistral()`, `setup_openai()`, `setup_provider()`
-- JSON-safe helper `to_json_value(...)`
-
-Python test command:
-
-- `cd py && python3 -m unittest discover -s tests -p 'test_*.py'`
-
-Python examples:
-
-- `cd py && python3 examples/basic/hello_world.py`
-- `cd py && python3 examples/basic/tool_policy_allow_deny.py`
-- `cd py && python3 examples/basic/run_record_sink.py`
-
-Migration mapping reference:
-
-- `docs/TS-PY-MIGRATION.md`
-
 ## License
 
 - Project license: `MIT` (`LICENSE`)

package/dist/canonical-json.d.ts

@@ -0,0 +1,8 @@
+export type CanonicalJsonValue = null | string | number | boolean | CanonicalJsonValue[] | {
+    [key: string]: CanonicalJsonValue;
+};
+export declare function normalizeCanonicalJsonValue(value: unknown, seen?: WeakSet<object>): CanonicalJsonValue;
+export declare function toCanonicalJson(value: unknown): string;
+export declare function hashCanonicalJson(canonicalJson: string): string;
+export declare function hashCanonicalJsonValue(value: unknown): string;
+//# sourceMappingURL=canonical-json.d.ts.map

package/dist/canonical-json.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"canonical-json.d.ts","sourceRoot":"","sources":["../src/canonical-json.ts"],"names":[],"mappings":"AAEA,MAAM,MAAM,kBAAkB,GAC1B,IAAI,GACJ,MAAM,GACN,MAAM,GACN,OAAO,GACP,kBAAkB,EAAE,GACpB;IAAE,CAAC,GAAG,EAAE,MAAM,GAAG,kBAAkB,CAAA;CAAE,CAAC;AAE1C,wBAAgB,2BAA2B,CACzC,KAAK,EAAE,OAAO,EACd,IAAI,GAAE,OAAO,CAAC,MAAM,CAAiB,GACpC,kBAAkB,CAiFpB;AAED,wBAAgB,eAAe,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAEtD;AAED,wBAAgB,iBAAiB,CAAC,aAAa,EAAE,MAAM,GAAG,MAAM,CAE/D;AAED,wBAAgB,sBAAsB,CAAC,KAAK,EAAE,OAAO,GAAG,MAAM,CAE7D"}

package/dist/canonical-json.js

@@ -0,0 +1,76 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.normalizeCanonicalJsonValue = normalizeCanonicalJsonValue;
+exports.toCanonicalJson = toCanonicalJson;
+exports.hashCanonicalJson = hashCanonicalJson;
+exports.hashCanonicalJsonValue = hashCanonicalJsonValue;
+const node_crypto_1 = require("node:crypto");
+function normalizeCanonicalJsonValue(value, seen = new WeakSet()) {
+    if (value === null) {
+        return null;
+    }
+    const valueType = typeof value;
+    if (valueType === "string" ||
+        valueType === "number" ||
+        valueType === "boolean") {
+        return value;
+    }
+    if (valueType === "undefined") {
+        return "[undefined]";
+    }
+    if (valueType === "bigint") {
+        return `[bigint:${String(value)}]`;
+    }
+    if (valueType === "symbol") {
+        return `[symbol:${String(value)}]`;
+    }
+    if (valueType === "function") {
+        return "[function]";
+    }
+    if (value instanceof Date) {
+        return value.toISOString();
+    }
+    if (value instanceof RegExp) {
+        return value.toString();
+    }
+    if (Array.isArray(value)) {
+        return value.map((entry) => normalizeCanonicalJsonValue(entry, seen));
+    }
+    if (value instanceof Set) {
+        const entries = [...value].map((entry) => normalizeCanonicalJsonValue(entry, seen));
+        entries.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
+        return entries;
+    }
+    if (value instanceof Map) {
+        const entries = [...value.entries()].map(([key, entry]) => [
+            normalizeCanonicalJsonValue(key, seen),
+            normalizeCanonicalJsonValue(entry, seen),
+        ]);
+        entries.sort((left, right) => JSON.stringify(left[0]).localeCompare(JSON.stringify(right[0])));
+        return entries;
+    }
+    if (value && typeof value === "object") {
+        const objectValue = value;
+        if (seen.has(objectValue)) {
+            return "[circular]";
+        }
+        seen.add(objectValue);
+        const normalized = {};
+        const keys = Object.keys(objectValue).sort();
+        for (const key of keys) {
+            normalized[key] = normalizeCanonicalJsonValue(objectValue[key], seen);
+        }
+        seen.delete(objectValue);
+        return normalized;
+    }
+    return String(value);
+}
+function toCanonicalJson(value) {
+    return JSON.stringify(normalizeCanonicalJsonValue(value));
+}
+function hashCanonicalJson(canonicalJson) {
+    return (0, node_crypto_1.createHash)("sha256").update(canonicalJson).digest("hex");
+}
+function hashCanonicalJsonValue(value) {
+    return hashCanonicalJson(toCanonicalJson(value));
+}

package/dist/index.d.ts

@@ -13,6 +13,7 @@ export * from "./providers/mistral";
 export * from "./providers/openai";
 export * from "./run";
 export * from "./run-record";
+export * from "./run-record-utils";
 export * from "./run-context";
 export * from "./tool";
 export * from "./types";

package/dist/index.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}
+{"version":3,"file":"index.d.ts","sourceRoot":"","sources":["../src/index.ts"],"names":[],"mappings":"AAAA,cAAc,SAAS,CAAC;AACxB,cAAc,UAAU,CAAC;AACzB,cAAc,UAAU,CAAC;AACzB,cAAc,cAAc,CAAC;AAC7B,cAAc,QAAQ,CAAC;AACvB,cAAc,UAAU,CAAC;AACzB,cAAc,YAAY,CAAC;AAC3B,cAAc,UAAU,CAAC;AACzB,cAAc,kBAAkB,CAAC;AACjC,cAAc,kBAAkB,CAAC;AACjC,cAAc,8BAA8B,CAAC;AAC7C,cAAc,qBAAqB,CAAC;AACpC,cAAc,oBAAoB,CAAC;AACnC,cAAc,OAAO,CAAC;AACtB,cAAc,cAAc,CAAC;AAC7B,cAAc,oBAAoB,CAAC;AACnC,cAAc,eAAe,CAAC;AAC9B,cAAc,QAAQ,CAAC;AACvB,cAAc,SAAS,CAAC"}

package/dist/index.js

@@ -29,6 +29,7 @@ __exportStar(require("./providers/mistral"), exports);
 __exportStar(require("./providers/openai"), exports);
 __exportStar(require("./run"), exports);
 __exportStar(require("./run-record"), exports);
+__exportStar(require("./run-record-utils"), exports);
 __exportStar(require("./run-context"), exports);
 __exportStar(require("./tool"), exports);
 __exportStar(require("./types"), exports);

package/dist/run-record-utils.d.ts

@@ -0,0 +1,84 @@
+import { Agent } from "./agent";
+import type { RunRecord } from "./run-record";
+import type { AgentInputItem, NonStreamRunOptions, RunResult } from "./types";
+export interface ExtractedToolCall {
+    callId: string;
+    name: string;
+    arguments: unknown;
+    output?: unknown;
+    hasOutput: boolean;
+    turn?: number;
+    argsCanonicalJson: string;
+    argsHash: string;
+}
+export declare function extractToolCalls<TContext>(input: RunRecord<TContext>): ExtractedToolCall[];
+export declare function extractToolCalls(input: AgentInputItem[]): ExtractedToolCall[];
+export type RunRecordComparisonSection = "response" | "toolCalls" | "policy" | "guardrails" | "metadata";
+export interface CompareRunRecordsOptions {
+    includeSections?: RunRecordComparisonSection[];
+    excludeSections?: RunRecordComparisonSection[];
+    responseMatchMode?: "exact";
+}
+export interface RunRecordDifference {
+    path: string;
+    kind: "mismatch" | "missing_left" | "missing_right";
+    left?: unknown;
+    right?: unknown;
+}
+export interface RunRecordComparisonSummary {
+    sameFinalResponse: boolean;
+    sameToolCallShape: boolean;
+    samePolicyDecisions: boolean;
+    sameGuardrailDecisions: boolean;
+}
+export interface RunRecordComparisonMetrics {
+    responseLengthA: number;
+    responseLengthB: number;
+    toolCallsA: number;
+    toolCallsB: number;
+    matchedToolCalls: number;
+    missingToolCalls: number;
+    extraToolCalls: number;
+}
+export interface RunRecordComparison {
+    equal: boolean;
+    summary: RunRecordComparisonSummary;
+    metrics: RunRecordComparisonMetrics;
+    differences: RunRecordDifference[];
+}
+export declare function compareRunRecords<TContextA, TContextB>(left: RunRecord<TContextA>, right: RunRecord<TContextB>, options?: CompareRunRecordsOptions): RunRecordComparison;
+export type ReplayMode = "live" | "strict" | "hybrid";
+export interface MissingToolCallResolution {
+    action: "throw" | "use_live" | "use_output";
+    output?: unknown;
+}
+export interface ReplayMissingToolCallInput {
+    mode: ReplayMode;
+    toolName: string;
+    arguments: unknown;
+    argsCanonicalJson: string;
+    argsHash: string;
+}
+export type ReplayMissingToolCallHandler = (input: ReplayMissingToolCallInput) => MissingToolCallResolution | Promise<MissingToolCallResolution>;
+export interface ReplayStats {
+    recordedToolCalls: number;
+    replayedFromRecord: number;
+    missingToolCalls: number;
+    liveFallbackCalls: number;
+}
+export interface ReplayFromRunRecordInput<TContext = unknown> {
+    sourceRunRecord: RunRecord<TContext>;
+    agent?: Agent<TContext>;
+    agentFactory?: () => Agent<TContext> | Promise<Agent<TContext>>;
+    mode: ReplayMode;
+    runOptions?: Omit<NonStreamRunOptions<TContext>, "stream">;
+    metadataOverrides?: Record<string, unknown>;
+    onMissingToolCall?: ReplayMissingToolCallHandler;
+}
+export interface ReplayFromRunRecordResult<TContext = unknown> {
+    result: RunResult<TContext>;
+    replayRunRecord?: RunRecord<TContext>;
+    replayStats: ReplayStats;
+}
+export declare function replayFromRunRecord<TContext = unknown>(input: ReplayFromRunRecordInput<TContext>): Promise<ReplayFromRunRecordResult<TContext>>;
+//# sourceMappingURL=run-record-utils.d.ts.map

package/dist/run-record-utils.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"run-record-utils.d.ts","sourceRoot":"","sources":["../src/run-record-utils.ts"],"names":[],"mappings":"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"}

package/dist/run-record-utils.js

@@ -0,0 +1,447 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.extractToolCalls = extractToolCalls;
+exports.compareRunRecords = compareRunRecords;
+exports.replayFromRunRecord = replayFromRunRecord;
+const agent_1 = require("./agent");
+const canonical_json_1 = require("./canonical-json");
+const run_1 = require("./run");
+function buildExtractedToolCall(callId, name, rawArguments, turn) {
+    const normalizedArguments = typeof rawArguments === "undefined" ? {} : rawArguments;
+    const argsCanonicalJson = (0, canonical_json_1.toCanonicalJson)(normalizedArguments);
+    return {
+        callId,
+        name,
+        arguments: normalizedArguments,
+        hasOutput: false,
+        turn,
+        argsCanonicalJson,
+        argsHash: (0, canonical_json_1.hashCanonicalJson)(argsCanonicalJson),
+    };
+}
+function extractToolCalls(input) {
+    const items = Array.isArray(input) ? input : input.items;
+    const orderedCalls = [];
+    const callsById = new Map();
+    let toolTurn = 0;
+    for (const item of items) {
+        if (item.type === "tool_call_item") {
+            toolTurn += 1;
+            const extracted = buildExtractedToolCall(item.callId, item.name, item.arguments, toolTurn);
+            callsById.set(item.callId, extracted);
+            orderedCalls.push(extracted);
+            continue;
+        }
+        if (item.type === "tool_call_output_item") {
+            const existing = callsById.get(item.callId);
+            if (!existing) {
+                const orphanCall = buildExtractedToolCall(item.callId, "", {}, undefined);
+                orphanCall.output = item.output;
+                orphanCall.hasOutput = true;
+                callsById.set(item.callId, orphanCall);
+                orderedCalls.push(orphanCall);
+                continue;
+            }
+            existing.output = item.output;
+            existing.hasOutput = true;
+        }
+    }
+    return orderedCalls.map((call) => ({ ...call }));
+}
+function compareArraysByCanonical(path, left, right, differences) {
+    let same = left.length === right.length;
+    if (left.length !== right.length) {
+        differences.push({
+            path: `${path}.length`,
+            kind: "mismatch",
+            left: left.length,
+            right: right.length,
+        });
+    }
+    const maxLength = Math.max(left.length, right.length);
+    for (let index = 0; index < maxLength; index += 1) {
+        const leftItem = left[index];
+        const rightItem = right[index];
+        if (typeof leftItem === "undefined") {
+            same = false;
+            differences.push({
+                path: `${path}[${index}]`,
+                kind: "missing_left",
+                right: rightItem,
+            });
+            continue;
+        }
+        if (typeof rightItem === "undefined") {
+            same = false;
+            differences.push({
+                path: `${path}[${index}]`,
+                kind: "missing_right",
+                left: leftItem,
+            });
+            continue;
+        }
+        const leftCanonical = (0, canonical_json_1.toCanonicalJson)(leftItem);
+        const rightCanonical = (0, canonical_json_1.toCanonicalJson)(rightItem);
+        if (leftCanonical !== rightCanonical) {
+            same = false;
+            differences.push({
+                path: `${path}[${index}]`,
+                kind: "mismatch",
+                left: leftItem,
+                right: rightItem,
+            });
+        }
+    }
+    return same;
+}
+function resolveSections(options) {
+    const allSections = [
+        "response",
+        "toolCalls",
+        "policy",
+        "guardrails",
+        "metadata",
+    ];
+    const included = options?.includeSections
+        ? new Set(options.includeSections)
+        : new Set(allSections);
+    for (const section of options?.excludeSections ?? []) {
+        included.delete(section);
+    }
+    return included;
+}
+function toToolCallKey(call) {
+    return `${call.name}\u001f${call.argsHash}`;
+}
+function countByKey(calls) {
+    const counts = new Map();
+    for (const call of calls) {
+        const key = toToolCallKey(call);
+        counts.set(key, (counts.get(key) ?? 0) + 1);
+    }
+    return counts;
+}
+function compareRunRecords(left, right, options) {
+    const sections = resolveSections(options);
+    const differences = [];
+    const toolCallsLeft = extractToolCalls(left);
+    const toolCallsRight = extractToolCalls(right);
+    const metrics = {
+        responseLengthA: left.response.length,
+        responseLengthB: right.response.length,
+        toolCallsA: toolCallsLeft.length,
+        toolCallsB: toolCallsRight.length,
+        matchedToolCalls: 0,
+        missingToolCalls: 0,
+        extraToolCalls: 0,
+    };
+    const leftCounts = countByKey(toolCallsLeft);
+    const rightCounts = countByKey(toolCallsRight);
+    const allKeys = new Set([...leftCounts.keys(), ...rightCounts.keys()]);
+    for (const key of allKeys) {
+        const leftCount = leftCounts.get(key) ?? 0;
+        const rightCount = rightCounts.get(key) ?? 0;
+        metrics.matchedToolCalls += Math.min(leftCount, rightCount);
+        if (leftCount > rightCount) {
+            metrics.missingToolCalls += leftCount - rightCount;
+        }
+        if (rightCount > leftCount) {
+            metrics.extraToolCalls += rightCount - leftCount;
+        }
+    }
+    let sameFinalResponse = true;
+    if (sections.has("response")) {
+        const responseMatchMode = options?.responseMatchMode ?? "exact";
+        if (responseMatchMode === "exact" && left.response !== right.response) {
+            sameFinalResponse = false;
+            differences.push({
+                path: "response",
+                kind: "mismatch",
+                left: left.response,
+                right: right.response,
+            });
+        }
+    }
+    let sameToolCallShape = true;
+    if (sections.has("toolCalls")) {
+        if (toolCallsLeft.length !== toolCallsRight.length) {
+            sameToolCallShape = false;
+            differences.push({
+                path: "toolCalls.length",
+                kind: "mismatch",
+                left: toolCallsLeft.length,
+                right: toolCallsRight.length,
+            });
+        }
+        const maxLength = Math.max(toolCallsLeft.length, toolCallsRight.length);
+        for (let index = 0; index < maxLength; index += 1) {
+            const leftCall = toolCallsLeft[index];
+            const rightCall = toolCallsRight[index];
+            if (!leftCall) {
+                sameToolCallShape = false;
+                differences.push({
+                    path: `toolCalls[${index}]`,
+                    kind: "missing_left",
+                    right: rightCall,
+                });
+                continue;
+            }
+            if (!rightCall) {
+                sameToolCallShape = false;
+                differences.push({
+                    path: `toolCalls[${index}]`,
+                    kind: "missing_right",
+                    left: leftCall,
+                });
+                continue;
+            }
+            if (leftCall.name !== rightCall.name) {
+                sameToolCallShape = false;
+                differences.push({
+                    path: `toolCalls[${index}].name`,
+                    kind: "mismatch",
+                    left: leftCall.name,
+                    right: rightCall.name,
+                });
+            }
+            if (leftCall.argsHash !== rightCall.argsHash) {
+                sameToolCallShape = false;
+                differences.push({
+                    path: `toolCalls[${index}].argsHash`,
+                    kind: "mismatch",
+                    left: leftCall.argsHash,
+                    right: rightCall.argsHash,
+                });
+            }
+            if (leftCall.hasOutput !== rightCall.hasOutput) {
+                differences.push({
+                    path: `toolCalls[${index}].hasOutput`,
+                    kind: "mismatch",
+                    left: leftCall.hasOutput,
+                    right: rightCall.hasOutput,
+                });
+            }
+            if (leftCall.hasOutput && rightCall.hasOutput) {
+                const leftOutputCanonical = (0, canonical_json_1.toCanonicalJson)(leftCall.output);
+                const rightOutputCanonical = (0, canonical_json_1.toCanonicalJson)(rightCall.output);
+                if (leftOutputCanonical !== rightOutputCanonical) {
+                    differences.push({
+                        path: `toolCalls[${index}].output`,
+                        kind: "mismatch",
+                        left: leftCall.output,
+                        right: rightCall.output,
+                    });
+                }
+            }
+        }
+    }
+    let samePolicyDecisions = true;
+    if (sections.has("policy")) {
+        samePolicyDecisions = compareArraysByCanonical("policyDecisions", left.policyDecisions, right.policyDecisions, differences);
+    }
+    let sameGuardrailDecisions = true;
+    if (sections.has("guardrails")) {
+        sameGuardrailDecisions = compareArraysByCanonical("guardrailDecisions", left.guardrailDecisions ?? [], right.guardrailDecisions ?? [], differences);
+    }
+    if (sections.has("metadata")) {
+        const leftMetadataCanonical = (0, canonical_json_1.toCanonicalJson)(left.metadata ?? {});
+        const rightMetadataCanonical = (0, canonical_json_1.toCanonicalJson)(right.metadata ?? {});
+        if (leftMetadataCanonical !== rightMetadataCanonical) {
+            differences.push({
+                path: "metadata",
+                kind: "mismatch",
+                left: left.metadata,
+                right: right.metadata,
+            });
+        }
+    }
+    return {
+        equal: differences.length === 0,
+        summary: {
+            sameFinalResponse,
+            sameToolCallShape,
+            samePolicyDecisions,
+            sameGuardrailDecisions,
+        },
+        metrics,
+        differences,
+    };
+}
+function createMissingToolCallError(input) {
+    return new Error([
+        `Missing recorded tool output for "${input.toolName}".`,
+        `argsHash=${input.argsHash}.`,
+        `argsCanonicalJson=${input.argsCanonicalJson}`,
+    ].join(" "));
+}
+function buildRecordedToolQueues(source) {
+    const calls = extractToolCalls(source).filter((call) => call.hasOutput && call.name.length > 0);
+    const queues = new Map();
+    for (const call of calls) {
+        const key = toToolCallKey(call);
+        const queue = queues.get(key);
+        if (queue) {
+            queue.push(call);
+            continue;
+        }
+        queues.set(key, [call]);
+    }
+    return queues;
+}
+function findRecordedToolOutput(queues, toolName, args, mode) {
+    const argsCanonicalJson = (0, canonical_json_1.toCanonicalJson)(args);
+    const argsHash = (0, canonical_json_1.hashCanonicalJson)(argsCanonicalJson);
+    const key = `${toolName}\u001f${argsHash}`;
+    const queue = queues.get(key);
+    if (queue && queue.length > 0) {
+        const matched = queue.shift();
+        if (matched) {
+            return {
+                status: "recorded",
+                output: matched.output,
+            };
+        }
+    }
+    return {
+        status: "missing",
+        input: {
+            mode,
+            toolName,
+            arguments: args,
+            argsCanonicalJson,
+            argsHash,
+        },
+    };
+}
+function resolveMissingToolCall(mode, input, handler) {
+    if (!handler) {
+        if (mode === "hybrid") {
+            return { action: "use_live" };
+        }
+        return { action: "throw" };
+    }
+    return handler(input);
+}
+function isRunRecordSink(sink) {
+    return typeof sink === "object" && sink !== null && "write" in sink;
+}
+async function writeRunRecordToSink(sink, record) {
+    if (!sink) {
+        return;
+    }
+    if (typeof sink === "function") {
+        await sink(record);
+        return;
+    }
+    if (isRunRecordSink(sink)) {
+        await sink.write(record);
+    }
+}
+function cloneAgentWithReplayedTools(sourceAgent, mode, queues, replayStats, onMissingToolCall, cache = new Map()) {
+    const existing = cache.get(sourceAgent);
+    if (existing) {
+        return existing;
+    }
+    const cloned = new agent_1.Agent({
+        name: sourceAgent.name,
+        handoffDescription: sourceAgent.handoffDescription,
+        instructions: sourceAgent.instructions,
+        promptVersion: sourceAgent.promptVersion,
+        model: sourceAgent.model,
+        modelSettings: sourceAgent.modelSettings,
+        tools: [],
+        handoffs: [],
+        outputGuardrails: sourceAgent.outputGuardrails,
+    });
+    cache.set(sourceAgent, cloned);
+    const wrappedTools = sourceAgent.tools.map((toolDefinition) => {
+        return {
+            name: toolDefinition.name,
+            description: toolDefinition.description,
+            parameters: toolDefinition.parameters,
+            execute: async (input, runContext) => {
+                const lookup = findRecordedToolOutput(queues, toolDefinition.name, input, mode);
+                if (lookup.status === "recorded") {
+                    replayStats.replayedFromRecord += 1;
+                    return lookup.output;
+                }
+                replayStats.missingToolCalls += 1;
+                const resolution = await resolveMissingToolCall(mode, lookup.input, onMissingToolCall);
+                if (resolution.action === "use_output") {
+                    replayStats.replayedFromRecord += 1;
+                    return resolution.output;
+                }
+                if (resolution.action === "use_live") {
+                    replayStats.liveFallbackCalls += 1;
+                    return toolDefinition.execute(input, runContext);
+                }
+                throw createMissingToolCallError(lookup.input);
+            },
+        };
+    });
+    const wrappedHandoffs = sourceAgent.handoffs.map((handoffAgent) => cloneAgentWithReplayedTools(handoffAgent, mode, queues, replayStats, onMissingToolCall, cache));
+    cloned.tools = wrappedTools;
+    cloned.handoffs = wrappedHandoffs;
+    return cloned;
+}
+async function resolveReplayAgent(input) {
+    if (input.agent && input.agentFactory) {
+        throw new Error("Replay configuration is ambiguous: provide either agent or agentFactory, not both.");
+    }
+    if (input.agentFactory) {
+        return input.agentFactory();
+    }
+    if (input.agent) {
+        return input.agent;
+    }
+    throw new Error("Replay configuration is missing an agent or agentFactory.");
+}
+async function replayFromRunRecord(input) {
+    const baseAgent = await resolveReplayAgent(input);
+    const extractedSourceCalls = extractToolCalls(input.sourceRunRecord);
+    const replayStats = {
+        recordedToolCalls: extractedSourceCalls.filter((call) => call.hasOutput)
+            .length,
+        replayedFromRecord: 0,
+        missingToolCalls: 0,
+        liveFallbackCalls: 0,
+    };
+    const mode = input.mode;
+    const replayAgent = mode === "live"
+        ? baseAgent
+        : cloneAgentWithReplayedTools(baseAgent, mode, buildRecordedToolQueues(input.sourceRunRecord), replayStats, input.onMissingToolCall);
+    const runOptions = input.runOptions ?? {};
+    const replayContext = typeof runOptions.context === "undefined"
+        ? input.sourceRunRecord.contextSnapshot
+        : runOptions.context;
+    const replayPolicies = runOptions.policies;
+    let replayRunRecord;
+    const shouldCaptureReplayRecord = Boolean(runOptions.record) || Boolean(input.metadataOverrides);
+    let replayRecordOptions = runOptions.record;
+    if (shouldCaptureReplayRecord) {
+        const sink = runOptions.record?.sink;
+        replayRecordOptions = {
+            ...(runOptions.record ?? {}),
+            metadata: {
+                ...(runOptions.record?.metadata ?? {}),
+                ...(input.metadataOverrides ?? {}),
+            },
+            sink: async (record) => {
+                replayRunRecord = record;
+                await writeRunRecordToSink(sink, record);
+            },
+        };
+    }
+    const result = await (0, run_1.run)(replayAgent, input.sourceRunRecord.question, {
+        ...runOptions,
+        context: replayContext,
+        policies: replayPolicies,
+        stream: false,
+        record: replayRecordOptions,
+    });
+    return {
+        result,
+        replayRunRecord,
+        replayStats,
+    };
+}

package/dist/run-recorder-runtime.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run-recorder-runtime.d.ts","sourceRoot":"","sources":["../src/run-recorder-runtime.ts"],"names":[],"mappings":"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"}
+{"version":3,"file":"run-recorder-runtime.d.ts","sourceRoot":"","sources":["../src/run-recorder-runtime.ts"],"names":[],"mappings":"AAIA,OAAO,KAAK,EACV,uBAAuB,EACvB,oBAAoB,EACpB,oBAAoB,EACpB,wBAAwB,EAGxB,gBAAgB,EAEjB,MAAM,cAAc,CAAC;AACtB,OAAO,KAAK,EAAE,cAAc,EAAE,MAAM,SAAS,CAAC;AAE9C,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,oBAAoB,EACpB,WAAW,CACZ,CAAC;AACF,MAAM,MAAM,8BAA8B,GAAG,IAAI,CAC/C,uBAAuB,EACvB,WAAW,CACZ,CAAC;AACF,MAAM,MAAM,2BAA2B,GAAG,IAAI,CAC5C,oBAAoB,EACpB,WAAW,GAAG,YAAY,GAAG,YAAY,CAC1C,GAAG;IACF,UAAU,CAAC,EAAE,MAAM,CAAC;CACrB,CAAC;AACF,MAAM,MAAM,+BAA+B,GAAG,IAAI,CAChD,wBAAwB,EACtB,WAAW,GACX,gBAAgB,GAChB,0BAA0B,GAC1B,aAAa,GACb,kBAAkB,GAClB,cAAc,GACd,WAAW,GACX,mBAAmB,GACnB,cAAc,GACd,WAAW,CACd,GAAG;IACF,YAAY,CAAC,EAAE,MAAM,CAAC;IACtB,QAAQ,EAAE,cAAc,EAAE,CAAC;IAC3B,KAAK,EAAE,KAAK,CAAC;QACX,IAAI,EAAE,MAAM,CAAC;QACb,WAAW,EAAE,MAAM,CAAC;QACpB,UAAU,EAAE,OAAO,CAAC;KACrB,CAAC,CAAC;IACH,aAAa,CAAC,EAAE,MAAM,CAAC,MAAM,EAAE,OAAO,CAAC,CAAC;CACzC,CAAC;AA+BF,UAAU,wBAAwB,CAAC,QAAQ;IACzC,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,CAAC;IACjC,OAAO,EAAE,QAAQ,CAAC;IAClB,YAAY,EAAE,MAAM,CAAC;IACrB,aAAa,CAAC,EAAE,gBAAgB,CAAC,QAAQ,CAAC,CAAC;CAC5C;AAED,UAAU,0BAA0B;IAClC,SAAS,EAAE,MAAM,CAAC;IAClB,KAAK,CAAC,EAAE,MAAM,CAAC;IACf,KAAK,EAAE,cAAc,EAAE,CAAC;CACzB;AAyFD,qBAAa,WAAW,CAAC,QAAQ,GAAG,OAAO;IACzC,OAAO,CAAC,QAAQ,CAAC,eAAe,CAAmC;IACnE,OAAO,CAAC,QAAQ,CAAC,WAAW,CAAS;IACrC,OAAO,CAAC,QAAQ,CAAC,SAAS,CAAS;IACnC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAS;IAClC,OAAO,CAAC,QAAQ,CAAC,YAAY,CAAS;IACtC,OAAO,CAAC,QAAQ,CAAC,QAAQ,CAAC,CAA0B;IACpD,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA4C;IAC5E,OAAO,CAAC,QAAQ,CAAC,iBAAiB,CAAU;IAE5C,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAC9D,OAAO,CAAC,QAAQ,CAAC,kBAAkB,CAAiC;IACpE,OAAO,CAAC,QAAQ,CAAC,eAAe,CAA8B;IAC9D,OAAO,CAAC,QAAQ,CAAC,mBAAmB,CAAkC;IACtE,OAAO,CAAC,mBAAmB,CAAM;IACjC,OAAO,CAAC,gBAAgB,CAAS;IAEjC,OAAO;WAoBM,MAAM,CAAC,QAAQ,GAAG,OAAO,EACpC,OAAO,EAAE,wBAAwB,CAAC,QAAQ,CAAC,GAC1C,OAAO,CAAC,WAAW,CAAC,QAAQ,CAAC,CAAC;IAsBjC,gBAAgB,GAAI,UAAU,2BAA2B,KAAG,IAAI,CAK9D;IAEF,mBAAmB,GAAI,UAAU,8BAA8B,KAAG,IAAI,CAKpE;IAEF,gBAAgB,GAAI,UAAU,2BAA2B,KAAG,IAAI,CAW9D;IAEF,oBAAoB,GAClB,aAAa,+BAA+B,KAC3C,IAAI,CAgCL;IAEF,eAAe,GAAI,SAAS,MAAM,KAAG,IAAI,CAEvC;IAEI,aAAa,CAAC,OAAO,EAAE,0BAA0B,GAAG,OAAO,CAAC,IAAI,CAAC;IAIjE,UAAU,CACd,OAAO,EAAE,0BAA0B,EACnC,KAAK,EAAE,OAAO,GACb,OAAO,CAAC,IAAI,CAAC;YAIF,IAAI;CA0CnB"}

package/dist/run-recorder-runtime.js

@@ -4,6 +4,7 @@ exports.RunRecorder = void 0;
 const node_crypto_1 = require("node:crypto");
 const node_fs_1 = require("node:fs");
 const node_path_1 = require("node:path");
+const canonical_json_1 = require("./canonical-json");
 const REQUEST_FINGERPRINT_SCHEMA_VERSION = "request-fingerprint.v1";
 function resolveRuntimeVersion() {
     const envVersion = process.env.AIOC_RUNTIME_VERSION?.trim() ??
@@ -26,71 +27,6 @@ function resolveRuntimeVersion() {
     return "unknown";
 }
 const RUNTIME_VERSION = resolveRuntimeVersion();
-function normalizeForHash(value, seen = new WeakSet()) {
-    if (value === null) {
-        return null;
-    }
-    const valueType = typeof value;
-    if (valueType === "string" ||
-        valueType === "number" ||
-        valueType === "boolean") {
-        return value;
-    }
-    if (valueType === "undefined") {
-        return "[undefined]";
-    }
-    if (valueType === "bigint") {
-        return `[bigint:${String(value)}]`;
-    }
-    if (valueType === "symbol") {
-        return `[symbol:${String(value)}]`;
-    }
-    if (valueType === "function") {
-        return "[function]";
-    }
-    if (value instanceof Date) {
-        return value.toISOString();
-    }
-    if (value instanceof RegExp) {
-        return value.toString();
-    }
-    if (Array.isArray(value)) {
-        return value.map((item) => normalizeForHash(item, seen));
-    }
-    if (value instanceof Set) {
-        const entries = [...value].map((entry) => normalizeForHash(entry, seen));
-        entries.sort((left, right) => JSON.stringify(left).localeCompare(JSON.stringify(right)));
-        return entries;
-    }
-    if (value instanceof Map) {
-        const entries = [...value.entries()].map(([key, entry]) => [
-            normalizeForHash(key, seen),
-            normalizeForHash(entry, seen),
-        ]);
-        entries.sort((left, right) => JSON.stringify(left[0]).localeCompare(JSON.stringify(right[0])));
-        return entries;
-    }
-    if (value && typeof value === "object") {
-        const objectValue = value;
-        if (seen.has(objectValue)) {
-            return "[circular]";
-        }
-        seen.add(objectValue);
-        const normalized = {};
-        const keys = Object.keys(objectValue).sort();
-        for (const key of keys) {
-            normalized[key] = normalizeForHash(objectValue[key], seen);
-        }
-        seen.delete(objectValue);
-        return normalized;
-    }
-    return String(value);
-}
-function hashForFingerprint(value) {
-    return (0, node_crypto_1.createHash)("sha256")
-        .update(JSON.stringify(normalizeForHash(value)))
-        .digest("hex");
-}
 function extractQuestion(input) {
     if (typeof input === "string") {
         return input;
@@ -233,11 +169,11 @@ class RunRecorder {
             model: fingerprint.model,
             runtimeVersion: RUNTIME_VERSION,
             fingerprintSchemaVersion: REQUEST_FINGERPRINT_SCHEMA_VERSION,
-            requestHash: hashForFingerprint(requestPayload),
-            systemPromptHash: hashForFingerprint(normalizedSystemPrompt),
-            messagesHash: hashForFingerprint(fingerprint.messages),
-            toolsHash: hashForFingerprint(normalizedTools),
-            modelSettingsHash: hashForFingerprint(normalizedModelSettings),
+            requestHash: (0, canonical_json_1.hashCanonicalJsonValue)(requestPayload),
+            systemPromptHash: (0, canonical_json_1.hashCanonicalJsonValue)(normalizedSystemPrompt),
+            messagesHash: (0, canonical_json_1.hashCanonicalJsonValue)(fingerprint.messages),
+            toolsHash: (0, canonical_json_1.hashCanonicalJsonValue)(normalizedTools),
+            modelSettingsHash: (0, canonical_json_1.hashCanonicalJsonValue)(normalizedModelSettings),
             messageCount: fingerprint.messages.length,
             toolCount: normalizedTools.length,
         });

package/dist/run.d.ts

@@ -4,6 +4,13 @@ type MutableRunState<TContext> = {
     history: AgentInputItem[];
     lastAgent: Agent<TContext>;
 };
+export type ToolResultEnvelopeStatus = "ok" | "denied";
+export interface ToolResultEnvelope {
+    status: ToolResultEnvelopeStatus;
+    code: string | null;
+    publicReason: string | null;
+    data: unknown | null;
+}
 export declare class StreamedRunResult<TContext = unknown> {
     private consumed;
     private stream;

package/dist/run.d.ts.map

@@ -1 +1 @@
-{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAuBhC,OAAO,EACL,cAAc,EAEd,mBAAmB,EAGnB,SAAS,EACT,cAAc,EACd,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAUjB,KAAK,eAAe,CAAC,QAAQ,IAAI;IAC/B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CAC5B,CAAC;AAwpBF,qBAAa,iBAAiB,CAAC,QAAQ,GAAG,OAAO;IAC/C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,KAAK,CAA4B;gBAGvC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAC/C,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC;IAMlC,QAAQ,IAAI,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAQnD,IAAI,OAAO,IAAI,cAAc,EAAE,CAE9B;IAED,IAAI,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,CAE/B;CACF;AAED,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAClC,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAExC,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACtC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC"}
+{"version":3,"file":"run.d.ts","sourceRoot":"","sources":["../src/run.ts"],"names":[],"mappings":"AAAA,OAAO,EAAE,KAAK,EAAE,MAAM,SAAS,CAAC;AAuBhC,OAAO,EACL,cAAc,EAEd,mBAAmB,EAGnB,SAAS,EACT,cAAc,EACd,gBAAgB,EACjB,MAAM,SAAS,CAAC;AAUjB,KAAK,eAAe,CAAC,QAAQ,IAAI;IAC/B,OAAO,EAAE,cAAc,EAAE,CAAC;IAC1B,SAAS,EAAE,KAAK,CAAC,QAAQ,CAAC,CAAC;CAC5B,CAAC;AAGF,MAAM,MAAM,wBAAwB,GAAG,IAAI,GAAG,QAAQ,CAAC;AAEvD,MAAM,WAAW,kBAAkB;IACjC,MAAM,EAAE,wBAAwB,CAAC;IACjC,IAAI,EAAE,MAAM,GAAG,IAAI,CAAC;IACpB,YAAY,EAAE,MAAM,GAAG,IAAI,CAAC;IAC5B,IAAI,EAAE,OAAO,GAAG,IAAI,CAAC;CACtB;AA8oBD,qBAAa,iBAAiB,CAAC,QAAQ,GAAG,OAAO;IAC/C,OAAO,CAAC,QAAQ,CAAS;IACzB,OAAO,CAAC,MAAM,CAA0C;IACxD,OAAO,CAAC,KAAK,CAA4B;gBAGvC,MAAM,EAAE,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC,EAC/C,KAAK,EAAE,eAAe,CAAC,QAAQ,CAAC;IAMlC,QAAQ,IAAI,aAAa,CAAC,cAAc,CAAC,QAAQ,CAAC,CAAC;IAQnD,IAAI,OAAO,IAAI,cAAc,EAAE,CAE9B;IAED,IAAI,SAAS,IAAI,KAAK,CAAC,QAAQ,CAAC,CAE/B;CACF;AAED,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,EAAE,gBAAgB,CAAC,QAAQ,CAAC,GAClC,OAAO,CAAC,iBAAiB,CAAC,QAAQ,CAAC,CAAC,CAAC;AAExC,wBAAsB,GAAG,CAAC,QAAQ,GAAG,OAAO,EAC1C,aAAa,EAAE,KAAK,CAAC,QAAQ,CAAC,EAC9B,KAAK,EAAE,MAAM,GAAG,cAAc,EAAE,EAChC,OAAO,CAAC,EAAE,mBAAmB,CAAC,QAAQ,CAAC,GACtC,OAAO,CAAC,SAAS,CAAC,QAAQ,CAAC,CAAC,CAAC"}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@axiastudio/aioc",
-  "version": "0.1.0-beta.2",
+  "version": "0.1.0-beta.3",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",
   "files": [
@@ -20,10 +20,12 @@
     "example:hello": "tsx src/examples/basic/hello-world.ts",
     "example:tool-policy": "tsx src/examples/basic/tools.ts",
     "example:run-record": "tsx src/examples/basic/run-record-sink.ts",
+    "example:rru:01-extract": "tsx src/examples/run-record-utils-minimal/01-extract-tool-calls.ts",
+    "example:rru:02-compare": "tsx src/examples/run-record-utils-minimal/02-compare-run-records.ts",
+    "example:rru:03-replay-strict": "tsx src/examples/run-record-utils-minimal/03-replay-strict.ts",
+    "example:rru:04-replay-hybrid": "tsx src/examples/run-record-utils-minimal/04-replay-hybrid.ts",
     "example:non-regression": "tsx src/examples/non-regression/v1-v2-runrecord-diff.ts",
     "test:mistral": "tsx src/examples/mistral-smoke.ts",
-    "test:guardrail": "tsx src/examples/guardrail-smoke.ts",
-    "test:policy": "tsx src/examples/policy-smoke.ts",
     "prepack": "npm run build:package"
   },
   "keywords": [
@@ -55,7 +57,7 @@
   "homepage": "https://github.com/axiastudio/aioc",
   "publishConfig": {
     "access": "public",
-    "tag": "next"
+    "tag": "latest"
   },
   "dependencies": {
     "dotenv": "^17.2.3",