@agentskit/chat-devtools 0.1.0

package/LICENSE

@@ -0,0 +1,22 @@
+MIT License
+
+Copyright (c) 2026 AgentsKit
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.
+

package/README.md

@@ -0,0 +1,5 @@
+# @agentskit/chat-devtools
+
+Application trace capture, upstream replay-fixture composition, and semantic renderer parity diagnostics for AgentsKit Chat.
+
+This package does not record or replay model calls. Use `createRecordingAdapter` and `createReplayAdapter` from `@agentskit/eval/replay`; store the resulting cassette beside application traces with `createReplayFixture`.

package/dist/index.cjs

@@ -0,0 +1,164 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// src/index.ts
+var index_exports = {};
+__export(index_exports, {
+  ApplicationTraceRecordSchema: () => ApplicationTraceRecordSchema,
+  RendererOutcomeSchema: () => RendererOutcomeSchema,
+  ReplayFixtureSchema: () => ReplayFixtureSchema,
+  SemanticOutcomeSchema: () => SemanticOutcomeSchema,
+  TraceCategorySchema: () => TraceCategorySchema,
+  captureActionPolicyTrace: () => captureActionPolicyTrace,
+  captureActionTrace: () => captureActionTrace,
+  captureTurnTrace: () => captureTurnTrace,
+  compareRendererOutcomes: () => compareRendererOutcomes,
+  createReplayFixture: () => createReplayFixture,
+  createTraceCapture: () => createTraceCapture,
+  parseReplayFixture: () => parseReplayFixture,
+  serializeReplayFixture: () => serializeReplayFixture
+});
+module.exports = __toCommonJS(index_exports);
+var import_replay = require("@agentskit/eval/replay");
+var import_zod = require("zod");
+var IdSchema = import_zod.z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+var DetailSchema = import_zod.z.record(import_zod.z.string().min(1).max(128), import_zod.z.json()).refine((value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <= 65536, "Trace detail exceeds 64 KiB.");
+var TraceCategorySchema = import_zod.z.enum(["route", "agent", "repair", "fallback", "policy", "action", "lifecycle"]);
+var ApplicationTraceRecordSchema = import_zod.z.object({
+  id: IdSchema,
+  sequence: import_zod.z.number().int().nonnegative(),
+  at: import_zod.z.iso.datetime(),
+  category: TraceCategorySchema,
+  parentId: IdSchema.optional(),
+  detail: DetailSchema
+}).strict().readonly();
+var redact = (value, fields) => {
+  if (Array.isArray(value)) return value.map((item) => redact(item, fields));
+  if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fields.has(key.toLowerCase()) ? "[REDACTED]" : redact(item, fields)]));
+  return value;
+};
+var deepFreeze = (value) => {
+  if (Array.isArray(value)) {
+    value.forEach(deepFreeze);
+    return Object.freeze(value);
+  }
+  if (value !== null && typeof value === "object") {
+    Object.values(value).forEach(deepFreeze);
+    return Object.freeze(value);
+  }
+  return value;
+};
+var createTraceCapture = (options = {}) => {
+  const fields = new Set((options.redactFields ?? []).map((field) => field.toLowerCase()));
+  const records = [];
+  return {
+    append: (input) => {
+      if (input.parentId !== void 0 && !records.some((record2) => record2.id === input.parentId)) throw new Error("Trace parent must refer to an earlier record.");
+      const sequence = records.length;
+      const detail = DetailSchema.parse(redact(DetailSchema.parse(input.detail), fields));
+      const record = deepFreeze(ApplicationTraceRecordSchema.parse({ id: `trace-${sequence}`, sequence, at: input.at ?? (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(), category: input.category, ...input.parentId === void 0 ? {} : { parentId: input.parentId }, detail }));
+      records.push(record);
+      return record;
+    },
+    snapshot: () => Object.freeze(records.map((record) => deepFreeze({ ...record, detail: structuredClone(record.detail) })))
+  };
+};
+var captureTurnTrace = (capture, trace, parentId) => capture.append({
+  category: trace.kind === "deterministic" ? "route" : trace.kind === "agentic" ? "agent" : trace.kind === "repaired" ? "repair" : "fallback",
+  detail: { kind: trace.kind, ...trace.routeId === void 0 ? {} : { routeId: trace.routeId }, fromState: trace.fromState, toState: trace.toState },
+  ...parentId === void 0 ? {} : { parentId }
+});
+var captureActionPolicyTrace = (capture, trace, parentId) => capture.append({
+  category: "policy",
+  at: new Date(trace.timestamp).toISOString(),
+  detail: { policyTraceId: trace.id, toolCallId: trace.toolCallId, action: trace.action, phase: trace.phase, decision: trace.decision, reason: trace.reason, requiredCapabilities: [...trace.requiredCapabilities] },
+  ...parentId === void 0 ? {} : { parentId }
+});
+var captureActionTrace = (capture, action, parentId) => capture.append({
+  category: "action",
+  detail: { action: action.action, toolCallId: action.toolCallId, status: action.status, expiresAt: action.expiresAt },
+  ...parentId === void 0 ? {} : { parentId }
+});
+var ReplayFixtureSchema = import_zod.z.object({
+  protocol: import_zod.z.literal("agentskit.chat.replay"),
+  version: import_zod.z.literal(1),
+  cassette: import_zod.z.unknown(),
+  traces: import_zod.z.array(ApplicationTraceRecordSchema).max(1e4)
+}).strict().readonly().superRefine((fixture, context) => {
+  const prior = /* @__PURE__ */ new Set();
+  fixture.traces.forEach((trace, index) => {
+    if (trace.sequence !== index) context.addIssue({ code: "custom", path: ["traces", index, "sequence"], message: "Trace sequence must be contiguous." });
+    if (prior.has(trace.id)) context.addIssue({ code: "custom", path: ["traces", index, "id"], message: "Trace ids must be unique." });
+    if (trace.parentId !== void 0 && !prior.has(trace.parentId)) context.addIssue({ code: "custom", path: ["traces", index, "parentId"], message: "Trace parent must precede its child." });
+    prior.add(trace.id);
+  });
+});
+var createReplayFixture = (cassette, traces) => {
+  const upstream = (0, import_replay.parseCassette)((0, import_replay.serializeCassette)(cassette));
+  const envelope = ReplayFixtureSchema.parse({ protocol: "agentskit.chat.replay", version: 1, cassette: upstream, traces });
+  return { ...envelope, cassette: upstream };
+};
+var serializeReplayFixture = (fixture) => JSON.stringify(createReplayFixture(fixture.cassette, fixture.traces), null, 2);
+var parseReplayFixture = (input) => {
+  if (new TextEncoder().encode(input).byteLength > 16777216) throw new Error("Replay fixture exceeds 16 MiB.");
+  const envelope = ReplayFixtureSchema.parse(JSON.parse(input));
+  const cassette = (0, import_replay.parseCassette)(JSON.stringify(envelope.cassette));
+  return { ...envelope, cassette };
+};
+var SemanticOutcomeSchema = import_zod.z.object({ turnId: IdSchema, kind: IdSchema, value: import_zod.z.json().optional() }).strict().readonly();
+var RendererOutcomeSchema = import_zod.z.object({ renderer: IdSchema, outcomes: import_zod.z.array(SemanticOutcomeSchema).max(1e4) }).strict().readonly();
+var canonical = (value) => JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right))) : item);
+var compareRendererOutcomes = (input) => {
+  const renderers = import_zod.z.array(RendererOutcomeSchema).min(2).parse(input);
+  if (new Set(renderers.map((item) => item.renderer)).size !== renderers.length) throw new Error("Renderer ids must be unique.");
+  const key = (outcome) => `${outcome.turnId}\0${outcome.kind}`;
+  for (const item of renderers) if (new Set(item.outcomes.map(key)).size !== item.outcomes.length) throw new Error("Turn and kind pairs must be unique per renderer.");
+  const baseline = renderers[0];
+  const expected = new Map(baseline.outcomes.map((outcome) => [key(outcome), outcome]));
+  const outcomeKeys = new Set(renderers.flatMap((renderer) => renderer.outcomes.map(key)));
+  const mismatches = [];
+  for (const renderer of renderers.slice(1)) {
+    const actual = new Map(renderer.outcomes.map((outcome) => [key(outcome), outcome]));
+    for (const outcomeKey of outcomeKeys) {
+      const left = expected.get(outcomeKey);
+      const right = actual.get(outcomeKey);
+      if (canonical(left) !== canonical(right)) {
+        const [turnId, kind] = outcomeKey.split("\0");
+        mismatches.push({ renderer: renderer.renderer, turnId, kind, ...left === void 0 ? {} : { expected: left }, ...right === void 0 ? {} : { actual: right } });
+      }
+    }
+  }
+  return deepFreeze(structuredClone({ ok: mismatches.length === 0, baseline: baseline.renderer, renderers: renderers.map((item) => item.renderer), mismatches }));
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  ApplicationTraceRecordSchema,
+  RendererOutcomeSchema,
+  ReplayFixtureSchema,
+  SemanticOutcomeSchema,
+  TraceCategorySchema,
+  captureActionPolicyTrace,
+  captureActionTrace,
+  captureTurnTrace,
+  compareRendererOutcomes,
+  createReplayFixture,
+  createTraceCapture,
+  parseReplayFixture,
+  serializeReplayFixture
+});

package/dist/index.d.cts

@@ -0,0 +1,107 @@
+import { Cassette } from '@agentskit/eval/replay';
+import { ActionPolicyTrace, ActionConfirmation, TurnTrace } from '@agentskit/chat';
+import { z } from 'zod';
+
+declare const TraceCategorySchema: z.ZodEnum<{
+    route: "route";
+    agent: "agent";
+    repair: "repair";
+    fallback: "fallback";
+    policy: "policy";
+    action: "action";
+    lifecycle: "lifecycle";
+}>;
+declare const ApplicationTraceRecordSchema: z.ZodReadonly<z.ZodObject<{
+    id: z.ZodString;
+    sequence: z.ZodNumber;
+    at: z.ZodISODateTime;
+    category: z.ZodEnum<{
+        route: "route";
+        agent: "agent";
+        repair: "repair";
+        fallback: "fallback";
+        policy: "policy";
+        action: "action";
+        lifecycle: "lifecycle";
+    }>;
+    parentId: z.ZodOptional<z.ZodString>;
+    detail: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strict>>;
+type TraceCategory = z.infer<typeof TraceCategorySchema>;
+type ApplicationTraceRecord = z.infer<typeof ApplicationTraceRecordSchema>;
+interface TraceCaptureOptions {
+    readonly redactFields?: readonly string[];
+    readonly now?: () => Date;
+}
+interface AppendTraceInput {
+    readonly category: TraceCategory;
+    readonly detail: Readonly<Record<string, unknown>>;
+    readonly parentId?: string;
+    readonly at?: string;
+}
+interface TraceCapture {
+    append(input: AppendTraceInput): ApplicationTraceRecord;
+    snapshot(): readonly ApplicationTraceRecord[];
+}
+declare const createTraceCapture: (options?: TraceCaptureOptions) => TraceCapture;
+declare const captureTurnTrace: (capture: TraceCapture, trace: TurnTrace, parentId?: string) => ApplicationTraceRecord;
+declare const captureActionPolicyTrace: (capture: TraceCapture, trace: ActionPolicyTrace, parentId?: string) => ApplicationTraceRecord;
+declare const captureActionTrace: (capture: TraceCapture, action: ActionConfirmation, parentId?: string) => ApplicationTraceRecord;
+declare const ReplayFixtureSchema: z.ZodReadonly<z.ZodObject<{
+    protocol: z.ZodLiteral<"agentskit.chat.replay">;
+    version: z.ZodLiteral<1>;
+    cassette: z.ZodUnknown;
+    traces: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        id: z.ZodString;
+        sequence: z.ZodNumber;
+        at: z.ZodISODateTime;
+        category: z.ZodEnum<{
+            route: "route";
+            agent: "agent";
+            repair: "repair";
+            fallback: "fallback";
+            policy: "policy";
+            action: "action";
+            lifecycle: "lifecycle";
+        }>;
+        parentId: z.ZodOptional<z.ZodString>;
+        detail: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+type ReplayFixture = Omit<z.infer<typeof ReplayFixtureSchema>, 'cassette'> & {
+    readonly cassette: Cassette;
+};
+declare const createReplayFixture: (cassette: Cassette, traces: readonly ApplicationTraceRecord[]) => ReplayFixture;
+declare const serializeReplayFixture: (fixture: ReplayFixture) => string;
+declare const parseReplayFixture: (input: string) => ReplayFixture;
+declare const SemanticOutcomeSchema: z.ZodReadonly<z.ZodObject<{
+    turnId: z.ZodString;
+    kind: z.ZodString;
+    value: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$strict>>;
+declare const RendererOutcomeSchema: z.ZodReadonly<z.ZodObject<{
+    renderer: z.ZodString;
+    outcomes: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        turnId: z.ZodString;
+        kind: z.ZodString;
+        value: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+type SemanticOutcome = z.infer<typeof SemanticOutcomeSchema>;
+type RendererOutcome = z.infer<typeof RendererOutcomeSchema>;
+interface ParityMismatch {
+    readonly renderer: string;
+    readonly turnId: string;
+    readonly kind: string;
+    readonly expected?: SemanticOutcome;
+    readonly actual?: SemanticOutcome;
+}
+interface RendererParityReport {
+    readonly ok: boolean;
+    readonly baseline: string;
+    readonly renderers: readonly string[];
+    readonly mismatches: readonly ParityMismatch[];
+}
+declare const compareRendererOutcomes: (input: readonly RendererOutcome[]) => RendererParityReport;
+
+export { type AppendTraceInput, type ApplicationTraceRecord, ApplicationTraceRecordSchema, type ParityMismatch, type RendererOutcome, RendererOutcomeSchema, type RendererParityReport, type ReplayFixture, ReplayFixtureSchema, type SemanticOutcome, SemanticOutcomeSchema, type TraceCapture, type TraceCaptureOptions, type TraceCategory, TraceCategorySchema, captureActionPolicyTrace, captureActionTrace, captureTurnTrace, compareRendererOutcomes, createReplayFixture, createTraceCapture, parseReplayFixture, serializeReplayFixture };

package/dist/index.d.ts

@@ -0,0 +1,107 @@
+import { Cassette } from '@agentskit/eval/replay';
+import { ActionPolicyTrace, ActionConfirmation, TurnTrace } from '@agentskit/chat';
+import { z } from 'zod';
+
+declare const TraceCategorySchema: z.ZodEnum<{
+    route: "route";
+    agent: "agent";
+    repair: "repair";
+    fallback: "fallback";
+    policy: "policy";
+    action: "action";
+    lifecycle: "lifecycle";
+}>;
+declare const ApplicationTraceRecordSchema: z.ZodReadonly<z.ZodObject<{
+    id: z.ZodString;
+    sequence: z.ZodNumber;
+    at: z.ZodISODateTime;
+    category: z.ZodEnum<{
+        route: "route";
+        agent: "agent";
+        repair: "repair";
+        fallback: "fallback";
+        policy: "policy";
+        action: "action";
+        lifecycle: "lifecycle";
+    }>;
+    parentId: z.ZodOptional<z.ZodString>;
+    detail: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+}, z.core.$strict>>;
+type TraceCategory = z.infer<typeof TraceCategorySchema>;
+type ApplicationTraceRecord = z.infer<typeof ApplicationTraceRecordSchema>;
+interface TraceCaptureOptions {
+    readonly redactFields?: readonly string[];
+    readonly now?: () => Date;
+}
+interface AppendTraceInput {
+    readonly category: TraceCategory;
+    readonly detail: Readonly<Record<string, unknown>>;
+    readonly parentId?: string;
+    readonly at?: string;
+}
+interface TraceCapture {
+    append(input: AppendTraceInput): ApplicationTraceRecord;
+    snapshot(): readonly ApplicationTraceRecord[];
+}
+declare const createTraceCapture: (options?: TraceCaptureOptions) => TraceCapture;
+declare const captureTurnTrace: (capture: TraceCapture, trace: TurnTrace, parentId?: string) => ApplicationTraceRecord;
+declare const captureActionPolicyTrace: (capture: TraceCapture, trace: ActionPolicyTrace, parentId?: string) => ApplicationTraceRecord;
+declare const captureActionTrace: (capture: TraceCapture, action: ActionConfirmation, parentId?: string) => ApplicationTraceRecord;
+declare const ReplayFixtureSchema: z.ZodReadonly<z.ZodObject<{
+    protocol: z.ZodLiteral<"agentskit.chat.replay">;
+    version: z.ZodLiteral<1>;
+    cassette: z.ZodUnknown;
+    traces: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        id: z.ZodString;
+        sequence: z.ZodNumber;
+        at: z.ZodISODateTime;
+        category: z.ZodEnum<{
+            route: "route";
+            agent: "agent";
+            repair: "repair";
+            fallback: "fallback";
+            policy: "policy";
+            action: "action";
+            lifecycle: "lifecycle";
+        }>;
+        parentId: z.ZodOptional<z.ZodString>;
+        detail: z.ZodRecord<z.ZodString, z.ZodJSONSchema>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+type ReplayFixture = Omit<z.infer<typeof ReplayFixtureSchema>, 'cassette'> & {
+    readonly cassette: Cassette;
+};
+declare const createReplayFixture: (cassette: Cassette, traces: readonly ApplicationTraceRecord[]) => ReplayFixture;
+declare const serializeReplayFixture: (fixture: ReplayFixture) => string;
+declare const parseReplayFixture: (input: string) => ReplayFixture;
+declare const SemanticOutcomeSchema: z.ZodReadonly<z.ZodObject<{
+    turnId: z.ZodString;
+    kind: z.ZodString;
+    value: z.ZodOptional<z.ZodJSONSchema>;
+}, z.core.$strict>>;
+declare const RendererOutcomeSchema: z.ZodReadonly<z.ZodObject<{
+    renderer: z.ZodString;
+    outcomes: z.ZodArray<z.ZodReadonly<z.ZodObject<{
+        turnId: z.ZodString;
+        kind: z.ZodString;
+        value: z.ZodOptional<z.ZodJSONSchema>;
+    }, z.core.$strict>>>;
+}, z.core.$strict>>;
+type SemanticOutcome = z.infer<typeof SemanticOutcomeSchema>;
+type RendererOutcome = z.infer<typeof RendererOutcomeSchema>;
+interface ParityMismatch {
+    readonly renderer: string;
+    readonly turnId: string;
+    readonly kind: string;
+    readonly expected?: SemanticOutcome;
+    readonly actual?: SemanticOutcome;
+}
+interface RendererParityReport {
+    readonly ok: boolean;
+    readonly baseline: string;
+    readonly renderers: readonly string[];
+    readonly mismatches: readonly ParityMismatch[];
+}
+declare const compareRendererOutcomes: (input: readonly RendererOutcome[]) => RendererParityReport;
+
+export { type AppendTraceInput, type ApplicationTraceRecord, ApplicationTraceRecordSchema, type ParityMismatch, type RendererOutcome, RendererOutcomeSchema, type RendererParityReport, type ReplayFixture, ReplayFixtureSchema, type SemanticOutcome, SemanticOutcomeSchema, type TraceCapture, type TraceCaptureOptions, type TraceCategory, TraceCategorySchema, captureActionPolicyTrace, captureActionTrace, captureTurnTrace, compareRendererOutcomes, createReplayFixture, createTraceCapture, parseReplayFixture, serializeReplayFixture };

package/dist/index.js

@@ -0,0 +1,127 @@
+// src/index.ts
+import { parseCassette, serializeCassette } from "@agentskit/eval/replay";
+import { z } from "zod";
+var IdSchema = z.string().regex(/^[A-Za-z0-9][A-Za-z0-9._:-]{0,127}$/);
+var DetailSchema = z.record(z.string().min(1).max(128), z.json()).refine((value) => new TextEncoder().encode(JSON.stringify(value)).byteLength <= 65536, "Trace detail exceeds 64 KiB.");
+var TraceCategorySchema = z.enum(["route", "agent", "repair", "fallback", "policy", "action", "lifecycle"]);
+var ApplicationTraceRecordSchema = z.object({
+  id: IdSchema,
+  sequence: z.number().int().nonnegative(),
+  at: z.iso.datetime(),
+  category: TraceCategorySchema,
+  parentId: IdSchema.optional(),
+  detail: DetailSchema
+}).strict().readonly();
+var redact = (value, fields) => {
+  if (Array.isArray(value)) return value.map((item) => redact(item, fields));
+  if (value !== null && typeof value === "object") return Object.fromEntries(Object.entries(value).map(([key, item]) => [key, fields.has(key.toLowerCase()) ? "[REDACTED]" : redact(item, fields)]));
+  return value;
+};
+var deepFreeze = (value) => {
+  if (Array.isArray(value)) {
+    value.forEach(deepFreeze);
+    return Object.freeze(value);
+  }
+  if (value !== null && typeof value === "object") {
+    Object.values(value).forEach(deepFreeze);
+    return Object.freeze(value);
+  }
+  return value;
+};
+var createTraceCapture = (options = {}) => {
+  const fields = new Set((options.redactFields ?? []).map((field) => field.toLowerCase()));
+  const records = [];
+  return {
+    append: (input) => {
+      if (input.parentId !== void 0 && !records.some((record2) => record2.id === input.parentId)) throw new Error("Trace parent must refer to an earlier record.");
+      const sequence = records.length;
+      const detail = DetailSchema.parse(redact(DetailSchema.parse(input.detail), fields));
+      const record = deepFreeze(ApplicationTraceRecordSchema.parse({ id: `trace-${sequence}`, sequence, at: input.at ?? (options.now?.() ?? /* @__PURE__ */ new Date()).toISOString(), category: input.category, ...input.parentId === void 0 ? {} : { parentId: input.parentId }, detail }));
+      records.push(record);
+      return record;
+    },
+    snapshot: () => Object.freeze(records.map((record) => deepFreeze({ ...record, detail: structuredClone(record.detail) })))
+  };
+};
+var captureTurnTrace = (capture, trace, parentId) => capture.append({
+  category: trace.kind === "deterministic" ? "route" : trace.kind === "agentic" ? "agent" : trace.kind === "repaired" ? "repair" : "fallback",
+  detail: { kind: trace.kind, ...trace.routeId === void 0 ? {} : { routeId: trace.routeId }, fromState: trace.fromState, toState: trace.toState },
+  ...parentId === void 0 ? {} : { parentId }
+});
+var captureActionPolicyTrace = (capture, trace, parentId) => capture.append({
+  category: "policy",
+  at: new Date(trace.timestamp).toISOString(),
+  detail: { policyTraceId: trace.id, toolCallId: trace.toolCallId, action: trace.action, phase: trace.phase, decision: trace.decision, reason: trace.reason, requiredCapabilities: [...trace.requiredCapabilities] },
+  ...parentId === void 0 ? {} : { parentId }
+});
+var captureActionTrace = (capture, action, parentId) => capture.append({
+  category: "action",
+  detail: { action: action.action, toolCallId: action.toolCallId, status: action.status, expiresAt: action.expiresAt },
+  ...parentId === void 0 ? {} : { parentId }
+});
+var ReplayFixtureSchema = z.object({
+  protocol: z.literal("agentskit.chat.replay"),
+  version: z.literal(1),
+  cassette: z.unknown(),
+  traces: z.array(ApplicationTraceRecordSchema).max(1e4)
+}).strict().readonly().superRefine((fixture, context) => {
+  const prior = /* @__PURE__ */ new Set();
+  fixture.traces.forEach((trace, index) => {
+    if (trace.sequence !== index) context.addIssue({ code: "custom", path: ["traces", index, "sequence"], message: "Trace sequence must be contiguous." });
+    if (prior.has(trace.id)) context.addIssue({ code: "custom", path: ["traces", index, "id"], message: "Trace ids must be unique." });
+    if (trace.parentId !== void 0 && !prior.has(trace.parentId)) context.addIssue({ code: "custom", path: ["traces", index, "parentId"], message: "Trace parent must precede its child." });
+    prior.add(trace.id);
+  });
+});
+var createReplayFixture = (cassette, traces) => {
+  const upstream = parseCassette(serializeCassette(cassette));
+  const envelope = ReplayFixtureSchema.parse({ protocol: "agentskit.chat.replay", version: 1, cassette: upstream, traces });
+  return { ...envelope, cassette: upstream };
+};
+var serializeReplayFixture = (fixture) => JSON.stringify(createReplayFixture(fixture.cassette, fixture.traces), null, 2);
+var parseReplayFixture = (input) => {
+  if (new TextEncoder().encode(input).byteLength > 16777216) throw new Error("Replay fixture exceeds 16 MiB.");
+  const envelope = ReplayFixtureSchema.parse(JSON.parse(input));
+  const cassette = parseCassette(JSON.stringify(envelope.cassette));
+  return { ...envelope, cassette };
+};
+var SemanticOutcomeSchema = z.object({ turnId: IdSchema, kind: IdSchema, value: z.json().optional() }).strict().readonly();
+var RendererOutcomeSchema = z.object({ renderer: IdSchema, outcomes: z.array(SemanticOutcomeSchema).max(1e4) }).strict().readonly();
+var canonical = (value) => JSON.stringify(value, (_key, item) => item !== null && typeof item === "object" && !Array.isArray(item) ? Object.fromEntries(Object.entries(item).sort(([left], [right]) => left.localeCompare(right))) : item);
+var compareRendererOutcomes = (input) => {
+  const renderers = z.array(RendererOutcomeSchema).min(2).parse(input);
+  if (new Set(renderers.map((item) => item.renderer)).size !== renderers.length) throw new Error("Renderer ids must be unique.");
+  const key = (outcome) => `${outcome.turnId}\0${outcome.kind}`;
+  for (const item of renderers) if (new Set(item.outcomes.map(key)).size !== item.outcomes.length) throw new Error("Turn and kind pairs must be unique per renderer.");
+  const baseline = renderers[0];
+  const expected = new Map(baseline.outcomes.map((outcome) => [key(outcome), outcome]));
+  const outcomeKeys = new Set(renderers.flatMap((renderer) => renderer.outcomes.map(key)));
+  const mismatches = [];
+  for (const renderer of renderers.slice(1)) {
+    const actual = new Map(renderer.outcomes.map((outcome) => [key(outcome), outcome]));
+    for (const outcomeKey of outcomeKeys) {
+      const left = expected.get(outcomeKey);
+      const right = actual.get(outcomeKey);
+      if (canonical(left) !== canonical(right)) {
+        const [turnId, kind] = outcomeKey.split("\0");
+        mismatches.push({ renderer: renderer.renderer, turnId, kind, ...left === void 0 ? {} : { expected: left }, ...right === void 0 ? {} : { actual: right } });
+      }
+    }
+  }
+  return deepFreeze(structuredClone({ ok: mismatches.length === 0, baseline: baseline.renderer, renderers: renderers.map((item) => item.renderer), mismatches }));
+};
+export {
+  ApplicationTraceRecordSchema,
+  RendererOutcomeSchema,
+  ReplayFixtureSchema,
+  SemanticOutcomeSchema,
+  TraceCategorySchema,
+  captureActionPolicyTrace,
+  captureActionTrace,
+  captureTurnTrace,
+  compareRendererOutcomes,
+  createReplayFixture,
+  createTraceCapture,
+  parseReplayFixture,
+  serializeReplayFixture
+};

package/package.json

@@ -0,0 +1,48 @@
+{
+  "name": "@agentskit/chat-devtools",
+  "version": "0.1.0",
+  "description": "Replayable application traces and semantic renderer parity for AgentsKit Chat.",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/AgentsKit-io/agentskit-chat.git",
+    "directory": "packages/devtools"
+  },
+  "homepage": "https://github.com/AgentsKit-io/agentskit-chat#readme",
+  "bugs": {
+    "url": "https://github.com/AgentsKit-io/agentskit-chat/issues"
+  },
+  "type": "module",
+  "main": "./dist/index.cjs",
+  "module": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js",
+      "require": "./dist/index.cjs"
+    }
+  },
+  "files": [
+    "dist"
+  ],
+  "dependencies": {
+    "@agentskit/eval": "^0.4.19",
+    "zod": "^4.3.6",
+    "@agentskit/chat": "0.1.0"
+  },
+  "devDependencies": {
+    "@agentskit/core": "^1.12.2",
+    "@types/node": "^25.0.0",
+    "tsup": "^8.5.1"
+  },
+  "publishConfig": {
+    "access": "public",
+    "provenance": true
+  },
+  "scripts": {
+    "build": "tsup src/index.ts --format esm,cjs --dts --clean",
+    "lint": "tsc --noEmit",
+    "test": "vitest run --coverage"
+  }
+}