@xandreed/sdk 0.14.0 → 0.15.0

package/dist/turn/memory-checkpoint.adapter.js

@@ -0,0 +1,62 @@
+import { Effect, Exit, Option, Ref, Schema, Semaphore } from "effect";
+import { canonicalJson, frameworkDraft, MEMORY_KINDS, MemorySnapshotCandidate, MemorySnapshotData, SessionLogError, storedJson } from "@xandreed/core";
+import { entryOfEvent, prepareMemorySnapshot } from "@xandreed/core/internal";
+const invalid = (message, cause) => new SessionLogError({ code: "session.decode", message, ...cause === void 0 ? {} : { cause } }), locate = (events) => Effect.forEach(events, (event) => entryOfEvent(event).pipe(Effect.map((entry) => Option.map(entry, (entry) => ({ event, entry }))), Effect.mapError((cause) => invalid("snapshot source memory did not decode", cause))), { concurrency: 1 }).pipe(Effect.map((all) => all.flatMap(Option.toArray))), candidateJson = (candidate) => Schema.encodeEffect(MemorySnapshotCandidate)(candidate).pipe(Effect.flatMap(storedJson), Effect.mapError((cause) => invalid("memory snapshot candidate did not encode", cause)));
+export const makeMemoryCheckpoint = Effect.fnUntraced(function* (writer, history) {
+  const gate = yield* Semaphore.make(1), known = yield* Ref.make(Option.none()), terminal = yield* Ref.make(Option.none()), located = yield* Ref.make(Option.none()), historyLocated = Ref.get(located).pipe(Effect.flatMap(Option.match({
+    onNone: () => history.pipe(Effect.flatMap(locate), Effect.tap((entries) => Ref.set(located, Option.some(entries)))),
+    onSome: Effect.succeed
+  }))), refresh = Effect.gen(function* () {
+    const previous = yield* Option.match(yield* Ref.get(known), {
+      onNone: () => historyLocated.pipe(Effect.map((entries) => ({ entries, cursor: writer.started.seq - 1 }))),
+      onSome: Effect.succeed
+    }), own = (yield* writer.snapshot(MEMORY_KINDS, previous.cursor)).filter((event) => event.session === writer.started.session && event.seq > previous.cursor), next = { entries: [...previous.entries, ...yield* locate(own)], cursor: own.reduce((last, event) => Math.max(last, event.seq), previous.cursor) };
+    yield* Ref.set(known, Option.some(next));
+    return next.entries;
+  });
+  return {
+    load: gate.withPermits(1)(Effect.gen(function* () {
+      const selected = writer.memorySnapshot === void 0 ? Option.none() : yield* writer.memorySnapshot;
+      if (Option.isNone(selected))
+        return Option.none();
+      const row = selected.value;
+      if (row.kind !== "memory.snapshot")
+        return yield* Effect.fail(invalid("selected memory snapshot has the wrong kind"));
+      if (row.session === writer.started.session && row.seq >= writer.started.seq)
+        return yield* Effect.fail(invalid("selected memory snapshot is outside this turn's history"));
+      const data = yield* storedJson(row.data).pipe(Effect.flatMap(Schema.decodeUnknownEffect(MemorySnapshotData)), Effect.mapError((cause) => invalid("selected memory snapshot did not decode", cause))), all = yield* historyLocated, publicationSession = all.findIndex(({ event }) => event.session === row.session), before = (item, index) => item.event.session === row.session ? item.event.seq < row.seq : publicationSession >= 0 && index < publicationSession, anchor = all.findIndex(({ event }) => event.session === data.anchor.session && event.seq === data.anchor.seq), through = all.findIndex(({ event }) => event.session === data.through.session && event.seq === data.through.seq);
+      if (anchor < 0 || through < anchor || !before(all[anchor], anchor) || !before(all[through], through) || all[anchor].entry.body._tag !== "TurnStarted")
+        return yield* Effect.fail(invalid("selected memory snapshot cursors do not identify a visible kept turn and frontier"));
+      return Option.some({ strategy: data.strategy, anchor: all[anchor].entry.id, through: all[through].entry.id, entries: data.entries });
+    })),
+    save: Effect.fnUntraced(function* (input) {
+      const encoded = yield* candidateJson(input), candidate = yield* Schema.decodeUnknownEffect(MemorySnapshotCandidate)(encoded).pipe(Effect.mapError((cause) => invalid("memory snapshot candidate did not decode", cause))), key = canonicalJson(encoded);
+      return yield* gate.withPermits(1)(Effect.uninterruptible(Effect.gen(function* () {
+        const previous = yield* Ref.get(terminal);
+        if (Option.isSome(previous) && previous.value.key === key)
+          return yield* previous.value.exit;
+        const exit = yield* Effect.gen(function* () {
+          const actual = yield* refresh, anchor = actual.findIndex(({ entry }) => entry.id === candidate.anchor), through = actual.findIndex(({ entry }) => entry.id === candidate.through);
+          if (anchor < 0 || through < 0)
+            return;
+          if (through < anchor || actual[anchor].entry.body._tag !== "TurnStarted")
+            return yield* Effect.fail(invalid("memory snapshot candidate has an invalid source frontier"));
+          const expected = yield* prepareMemorySnapshot(actual.slice(0, through + 1).map(({ entry }) => entry), candidate.strategy);
+          if (Option.isNone(expected) || canonicalJson(yield* candidateJson(expected.value)) !== key)
+            return yield* Effect.fail(invalid("memory snapshot candidate differs from its durable source"));
+          const data = yield* Schema.encodeEffect(MemorySnapshotData)({
+            version: 1,
+            strategy: candidate.strategy,
+            anchor: { session: actual[anchor].event.session, seq: actual[anchor].event.seq },
+            through: { session: actual[through].event.session, seq: actual[through].event.seq },
+            entries: candidate.entries
+          }).pipe(Effect.flatMap(storedJson), Effect.mapError((cause) => invalid("memory snapshot did not encode", cause)));
+          yield* writer.append([frameworkDraft("memory.snapshot", data)]);
+          yield* writer.flush;
+        }).pipe(Effect.interruptible, Effect.exit);
+        yield* Ref.set(terminal, Option.some({ key, exit }));
+        return yield* exit;
+      })));
+    })
+  };
+});

package/dist/turn/model-call-recorder.adapter.d.ts

@@ -0,0 +1,9 @@
+import { Effect } from "effect";
+import { HarnessError, ModelCallData, ModelCallLegacyUsage } from "@xandreed/core";
+import type { ModelCallRecorder, TurnError, TurnWriter } from "@xandreed/core";
+/** One writer owns durability; observers only see accepted terminal facts. */
+export declare const makeTurnModelCallRecorder: (writer: TurnWriter, publish: (data: ModelCallData) => Effect.Effect<void, TurnError>) => Effect.Effect<{
+    recorder: ModelCallRecorder;
+    close: Effect.Effect<void, never, never>;
+    legacy: (data: ModelCallLegacyUsage) => Effect.Effect<void, HarnessError, never>;
+}, TurnError, never>;

package/dist/turn/model-call-recorder.adapter.js

@@ -0,0 +1,93 @@
+import { Context, Deferred, Effect, Exit, Option, Ref, Schema, Semaphore } from "effect";
+import {
+  canonicalJson,
+  frameworkDraft,
+  HarnessError,
+  ModelCallData,
+  ModelCallLegacyUsage,
+  readStored,
+  replayableContext,
+  storedJson,
+  turnModelCallsOf
+} from "@xandreed/core";
+import { CurrentModelCallNotifications, CurrentToolResultReceipt } from "@xandreed/core/internal";
+import { ModelCallRecorderPhase } from "./model-call-recorder.entity.js";
+import { mergeModelCalls, modelCallKey } from "./model-call-recorder.entity.functions.js";
+const invalid = (message, cause) => new HarnessError({ code: "events.encode", message, ...cause === void 0 ? {} : { cause } }), CallText = Schema.fromJsonString(ModelCallData), LegacyText = Schema.fromJsonString(ModelCallLegacyUsage), LegacyListText = Schema.fromJsonString(Schema.Array(ModelCallLegacyUsage)), copyCall = (data) => Schema.encodeEffect(CallText)(data).pipe(Effect.flatMap(Schema.decodeUnknownEffect(CallText))), copyLegacy = (data) => Schema.encodeEffect(LegacyListText)(data).pipe(Effect.flatMap(Schema.decodeUnknownEffect(LegacyListText)));
+export const makeTurnModelCallRecorder = Effect.fnUntraced(function* (writer, publish) {
+  const ownRows = (kinds) => writer.snapshot(kinds, writer.started.seq), before = yield* ownRows(["model.called", "step.usage"]), seededCalls = yield* turnModelCallsOf(before, writer.admitted.turn).pipe(Effect.mapError((cause) => invalid("the turn's model-call ledger did not decode", cause))), seededLegacy = yield* readStored("step.usage", before.filter((event) => Option.contains(event.turn, writer.admitted.turn))).pipe(Effect.map((records) => records.map(({ data }) => ({ model: data.model, usage: data.usage, run: data.run, step: data.step, replayed: !0 }))), Effect.mapError((cause) => invalid("the turn's selected usage did not decode", cause))), originalKeys = new Set(seededCalls.map(modelCallKey)), phase = yield* Ref.make({ _tag: "Open", calls: seededCalls.map((data) => ({ data, replayed: !0 })), legacy: seededLegacy }), claims = yield* Ref.make(new Map), observers = yield* Ref.make([]), order = yield* Semaphore.make(1), deliver = (observer, call) => Ref.modify(observer.seen, (seen) => {
+    const key = modelCallKey(call.data);
+    return seen.has(key) ? [!1, seen] : [!0, new Set([...seen, key])];
+  }).pipe(Effect.flatMap((fresh) => fresh ? copyCall(call.data).pipe(Effect.orDie, Effect.flatMap((snapshot) => observer.listener.called(snapshot, { replayed: call.replayed })), Effect.provide(observer.context)) : Effect.void), Effect.interruptible, Effect.ignoreCause({ log: "Warn", message: "a model-call billing observer failed" })), deliverAll = (listeners, calls) => Effect.forEach(listeners, (observer) => Effect.forEach(calls, (call) => deliver(observer, call), { concurrency: 1, discard: !0 }), { concurrency: 1, discard: !0 }), reconcile = ownRows(["model.called"]).pipe(Effect.flatMap((events) => turnModelCallsOf(events, writer.admitted.turn)), Effect.flatMap((calls) => Ref.update(phase, (current) => mergeModelCalls(current, calls.map((data) => ({ data, replayed: originalKeys.has(modelCallKey(data)) }))))), Effect.ignoreCause({ log: "Warn", message: "the model-call billing snapshot could not be refreshed" })), recorder = {
+    record: Effect.fn("turn.record_model_call")(function* (data) {
+      const encoded = yield* Schema.encodeEffect(ModelCallData)(data).pipe(Effect.flatMap(storedJson), Effect.mapError((cause) => invalid("model.called did not encode", cause))), fact = yield* Schema.decodeUnknownEffect(ModelCallData)(encoded).pipe(Effect.mapError((cause) => invalid("model.called did not decode", cause)));
+      if (Option.exists(fact.runId, (runId) => runId !== writer.admitted.runId))
+        return yield* Effect.fail(invalid("model.called belongs to another admitted run"));
+      const key = modelCallKey(fact), text = canonicalJson(encoded);
+      return yield* Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+        const done = yield* Deferred.make(), fresh = { encoded: text, done }, claim = yield* Ref.modify(claims, (all) => {
+          const prior = all.get(key);
+          return prior === void 0 ? [{ _tag: "Own", claim: fresh }, new Map([...all, [key, fresh]])] : [{ _tag: "Join", claim: prior }, all];
+        });
+        if (claim.claim.encoded !== text)
+          return yield* Effect.fail(invalid("model.called repeated a terminal key with different facts"));
+        const notifying = yield* CurrentModelCallNotifications;
+        if (claim._tag === "Join") {
+          if (notifying.has(claim.claim) && !(yield* Deferred.isDone(claim.claim.done)))
+            return yield* Effect.fail(new HarnessError({ code: "events.depth", message: "model.called cannot re-enter its own terminal recording notification" }));
+          return yield* Deferred.await(claim.claim.done).pipe(Effect.interruptible);
+        }
+        const operation = Effect.gen(function* () {
+          const listeners = yield* order.withPermits(1)(Effect.uninterruptible(Effect.gen(function* () {
+            const current = yield* Ref.get(phase);
+            if (ModelCallRecorderPhase.guards.Closed(current))
+              return yield* Effect.fail(new HarnessError({ code: "turn.closed", message: "the model-call recorder's owner is closed" }));
+            const existing = current.calls.find((call) => modelCallKey(call.data) === key);
+            if (existing !== void 0) {
+              const known = yield* Schema.encodeEffect(ModelCallData)(existing.data).pipe(Effect.flatMap(storedJson), Effect.mapError((cause) => invalid("model.called did not encode", cause)));
+              if (canonicalJson(known) !== text)
+                return yield* Effect.fail(invalid("model.called repeated a durable key with different facts"));
+              return Option.none();
+            }
+            yield* writer.append([frameworkDraft("model.called", encoded)]);
+            yield* writer.flush;
+            yield* Ref.update(phase, (state) => ({ ...state, calls: [...state.calls, { data: fact, replayed: !1 }] }));
+            return Option.some(yield* Ref.get(observers));
+          })));
+          yield* Option.match(listeners, {
+            onNone: () => Effect.void,
+            onSome: (all) => deliverAll(all, [{ data: fact, replayed: !1 }]).pipe(Effect.andThen(copyCall(fact).pipe(Effect.mapError((cause) => invalid("model.called notification did not encode", cause)), Effect.flatMap(publish))), Effect.provideService(CurrentModelCallNotifications, new Set([...notifying, claim.claim])), Effect.interruptible)
+          });
+        }), exit = yield* Effect.exit(restore(operation));
+        yield* Deferred.done(claim.claim.done, exit);
+        return yield* exit;
+      }));
+    }),
+    observe: Effect.fn("turn.observe_model_calls")(function* (listener) {
+      const observer = { listener, context: Context.omit(CurrentModelCallNotifications, CurrentToolResultReceipt)(replayableContext(yield* Effect.context())), seen: yield* Ref.make(new Set) }, current = yield* order.withPermits(1)(Effect.gen(function* () {
+        yield* reconcile;
+        const current = yield* Ref.get(phase);
+        if (ModelCallRecorderPhase.guards.Open(current))
+          yield* Ref.update(observers, (all) => [...all, observer]);
+        return current;
+      }));
+      yield* deliverAll([observer], current.calls);
+      if (ModelCallRecorderPhase.guards.Closed(current))
+        yield* copyLegacy(current.legacy).pipe(Effect.orDie, Effect.flatMap(listener.closed), Effect.provide(observer.context), Effect.ignoreCause({ log: "Warn", message: "a model-call billing observer failed to close" }));
+    })
+  }, close = yield* Effect.cached(Effect.gen(function* () {
+    const ending = yield* order.withPermits(1)(Effect.gen(function* () {
+      yield* reconcile;
+      const current = yield* Ref.get(phase), closed = { ...current, _tag: "Closed" };
+      yield* Ref.set(phase, closed);
+      return { current, listeners: yield* Ref.get(observers) };
+    }));
+    yield* deliverAll(ending.listeners, ending.current.calls);
+    yield* Effect.forEach(ending.listeners, (observer) => copyLegacy(ending.current.legacy).pipe(Effect.orDie, Effect.flatMap(observer.listener.closed), Effect.provide(observer.context), Effect.ignoreCause({ log: "Warn", message: "a model-call billing observer failed to close" })), { concurrency: 1, discard: !0 });
+  }));
+  return {
+    recorder,
+    close,
+    legacy: (data) => Schema.encodeEffect(LegacyText)(data).pipe(Effect.flatMap(Schema.decodeUnknownEffect(LegacyText)), Effect.mapError((cause) => invalid("selected usage did not encode", cause)), Effect.flatMap((snapshot) => Ref.update(phase, (current) => ModelCallRecorderPhase.guards.Open(current) ? { ...current, legacy: [...current.legacy, snapshot] } : current)))
+  };
+});

package/dist/turn/model-call-recorder.entity.d.ts

@@ -0,0 +1,145 @@
+import { Schema } from "effect";
+export declare const ObservedModelCall: Schema.Struct<{
+    readonly data: Schema.Struct<{
+        readonly callId: Schema.brand<Schema.Trimmed, "ModelCallId">;
+        readonly attempt: Schema.Int;
+        readonly purpose: Schema.Literals<readonly ["Loop", "Helper"]>;
+        readonly method: Schema.Literals<readonly ["Text", "Object", "Stream"]>;
+        readonly model: Schema.OptionFromNullOr<typeof import("@xandreed/core").ModelSelection>;
+        readonly runId: Schema.OptionFromNullOr<Schema.brand<Schema.String, "RunId">>;
+        readonly run: Schema.OptionFromNullOr<Schema.brand<Schema.Int, "RunOrdinal">>;
+        readonly step: Schema.OptionFromNullOr<Schema.Int>;
+        readonly durationMs: Schema.Finite;
+        readonly usage: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unknown", {}>, Schema.TaggedStruct<"Known", {
+            readonly usage: Schema.Struct<{
+                readonly inputTokens: Schema.Int;
+                readonly outputTokens: Schema.Int;
+                readonly totalTokens: Schema.Int;
+                readonly cacheReadTokens: Schema.Int;
+                readonly cacheWriteTokens: Schema.Int;
+                readonly reasoningTokens: Schema.Int;
+            }>;
+        }>, Schema.TaggedStruct<"Partial", {
+            readonly usage: Schema.Struct<{
+                readonly inputTokens: Schema.Int;
+                readonly outputTokens: Schema.Int;
+                readonly totalTokens: Schema.Int;
+                readonly cacheReadTokens: Schema.Int;
+                readonly cacheWriteTokens: Schema.Int;
+                readonly reasoningTokens: Schema.Int;
+            }>;
+            readonly reported: Schema.$Array<Schema.Literals<readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens"]>>;
+        }>]>;
+        readonly outcome: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Completed", {}>, Schema.TaggedStruct<"Failed", {
+            readonly failure: Schema.OptionFromNullOr<Schema.Literals<readonly ["ContextOverflow", "Authentication", "InvalidRequest", "RateLimit", "Quota", "Transient", "InvalidResponse", "Timeout", "Unknown"]>>;
+        }>, Schema.TaggedStruct<"Interrupted", {}>]>;
+    }>;
+    readonly replayed: Schema.Boolean;
+}>;
+export type ObservedModelCall = typeof ObservedModelCall.Type;
+export declare const ModelCallRecorderPhase: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Open", {
+    calls: Schema.$Array<Schema.Struct<{
+        readonly data: Schema.Struct<{
+            readonly callId: Schema.brand<Schema.Trimmed, "ModelCallId">;
+            readonly attempt: Schema.Int;
+            readonly purpose: Schema.Literals<readonly ["Loop", "Helper"]>;
+            readonly method: Schema.Literals<readonly ["Text", "Object", "Stream"]>;
+            readonly model: Schema.OptionFromNullOr<typeof import("@xandreed/core").ModelSelection>;
+            readonly runId: Schema.OptionFromNullOr<Schema.brand<Schema.String, "RunId">>;
+            readonly run: Schema.OptionFromNullOr<Schema.brand<Schema.Int, "RunOrdinal">>;
+            readonly step: Schema.OptionFromNullOr<Schema.Int>;
+            readonly durationMs: Schema.Finite;
+            readonly usage: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unknown", {}>, Schema.TaggedStruct<"Known", {
+                readonly usage: Schema.Struct<{
+                    readonly inputTokens: Schema.Int;
+                    readonly outputTokens: Schema.Int;
+                    readonly totalTokens: Schema.Int;
+                    readonly cacheReadTokens: Schema.Int;
+                    readonly cacheWriteTokens: Schema.Int;
+                    readonly reasoningTokens: Schema.Int;
+                }>;
+            }>, Schema.TaggedStruct<"Partial", {
+                readonly usage: Schema.Struct<{
+                    readonly inputTokens: Schema.Int;
+                    readonly outputTokens: Schema.Int;
+                    readonly totalTokens: Schema.Int;
+                    readonly cacheReadTokens: Schema.Int;
+                    readonly cacheWriteTokens: Schema.Int;
+                    readonly reasoningTokens: Schema.Int;
+                }>;
+                readonly reported: Schema.$Array<Schema.Literals<readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens"]>>;
+            }>]>;
+            readonly outcome: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Completed", {}>, Schema.TaggedStruct<"Failed", {
+                readonly failure: Schema.OptionFromNullOr<Schema.Literals<readonly ["ContextOverflow", "Authentication", "InvalidRequest", "RateLimit", "Quota", "Transient", "InvalidResponse", "Timeout", "Unknown"]>>;
+            }>, Schema.TaggedStruct<"Interrupted", {}>]>;
+        }>;
+        readonly replayed: Schema.Boolean;
+    }>>;
+    legacy: Schema.$Array<Schema.Struct<{
+        readonly model: Schema.OptionFromNullOr<Schema.String>;
+        readonly usage: Schema.Struct<{
+            readonly inputTokens: Schema.Number;
+            readonly outputTokens: Schema.Number;
+            readonly totalTokens: Schema.Number;
+            readonly cacheReadTokens: Schema.Number;
+            readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+            readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        }>;
+        readonly run: Schema.brand<Schema.Int, "RunOrdinal">;
+        readonly step: Schema.Int;
+        readonly replayed: Schema.Boolean;
+    }>>;
+}>, Schema.TaggedStruct<"Closed", {
+    calls: Schema.$Array<Schema.Struct<{
+        readonly data: Schema.Struct<{
+            readonly callId: Schema.brand<Schema.Trimmed, "ModelCallId">;
+            readonly attempt: Schema.Int;
+            readonly purpose: Schema.Literals<readonly ["Loop", "Helper"]>;
+            readonly method: Schema.Literals<readonly ["Text", "Object", "Stream"]>;
+            readonly model: Schema.OptionFromNullOr<typeof import("@xandreed/core").ModelSelection>;
+            readonly runId: Schema.OptionFromNullOr<Schema.brand<Schema.String, "RunId">>;
+            readonly run: Schema.OptionFromNullOr<Schema.brand<Schema.Int, "RunOrdinal">>;
+            readonly step: Schema.OptionFromNullOr<Schema.Int>;
+            readonly durationMs: Schema.Finite;
+            readonly usage: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Unknown", {}>, Schema.TaggedStruct<"Known", {
+                readonly usage: Schema.Struct<{
+                    readonly inputTokens: Schema.Int;
+                    readonly outputTokens: Schema.Int;
+                    readonly totalTokens: Schema.Int;
+                    readonly cacheReadTokens: Schema.Int;
+                    readonly cacheWriteTokens: Schema.Int;
+                    readonly reasoningTokens: Schema.Int;
+                }>;
+            }>, Schema.TaggedStruct<"Partial", {
+                readonly usage: Schema.Struct<{
+                    readonly inputTokens: Schema.Int;
+                    readonly outputTokens: Schema.Int;
+                    readonly totalTokens: Schema.Int;
+                    readonly cacheReadTokens: Schema.Int;
+                    readonly cacheWriteTokens: Schema.Int;
+                    readonly reasoningTokens: Schema.Int;
+                }>;
+                readonly reported: Schema.$Array<Schema.Literals<readonly ["inputTokens", "outputTokens", "cacheReadTokens", "cacheWriteTokens", "reasoningTokens"]>>;
+            }>]>;
+            readonly outcome: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Completed", {}>, Schema.TaggedStruct<"Failed", {
+                readonly failure: Schema.OptionFromNullOr<Schema.Literals<readonly ["ContextOverflow", "Authentication", "InvalidRequest", "RateLimit", "Quota", "Transient", "InvalidResponse", "Timeout", "Unknown"]>>;
+            }>, Schema.TaggedStruct<"Interrupted", {}>]>;
+        }>;
+        readonly replayed: Schema.Boolean;
+    }>>;
+    legacy: Schema.$Array<Schema.Struct<{
+        readonly model: Schema.OptionFromNullOr<Schema.String>;
+        readonly usage: Schema.Struct<{
+            readonly inputTokens: Schema.Number;
+            readonly outputTokens: Schema.Number;
+            readonly totalTokens: Schema.Number;
+            readonly cacheReadTokens: Schema.Number;
+            readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+            readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        }>;
+        readonly run: Schema.brand<Schema.Int, "RunOrdinal">;
+        readonly step: Schema.Int;
+        readonly replayed: Schema.Boolean;
+    }>>;
+}>]>;
+export type ModelCallRecorderPhase = typeof ModelCallRecorderPhase.Type;

package/dist/turn/model-call-recorder.entity.functions.d.ts

@@ -0,0 +1,5 @@
+import type { ModelCallData } from "@xandreed/core";
+import type { ModelCallRecorderPhase, ObservedModelCall } from "./model-call-recorder.entity.js";
+export declare const modelCallKey: (data: ModelCallData) => string;
+/** Fresh durable order wins; retain facts whose accepted ACK is newer than the snapshot. */
+export declare const mergeModelCalls: (phase: ModelCallRecorderPhase, calls: ReadonlyArray<ObservedModelCall>) => ModelCallRecorderPhase;

package/dist/turn/model-call-recorder.entity.functions.js

@@ -0,0 +1,4 @@
+export const modelCallKey = (data) => `${data.callId}:${data.attempt}`, mergeModelCalls = (phase, calls) => {
+  const keys = new Set(calls.map((call) => modelCallKey(call.data)));
+  return { ...phase, calls: [...calls, ...phase.calls.filter((call) => !keys.has(modelCallKey(call.data)))] };
+};

package/dist/turn/model-call-recorder.entity.js

@@ -0,0 +1,8 @@
+import { Schema } from "effect";
+import { ModelCallData, ModelCallLegacyUsage } from "@xandreed/core";
+export const ObservedModelCall = Schema.Struct({ data: ModelCallData, replayed: Schema.Boolean });
+const facts = { calls: Schema.Array(ObservedModelCall), legacy: Schema.Array(ModelCallLegacyUsage) };
+export const ModelCallRecorderPhase = Schema.Union([
+  Schema.TaggedStruct("Open", facts),
+  Schema.TaggedStruct("Closed", facts)
+]).pipe(Schema.toTaggedUnion("_tag"));

package/dist/turn/tool-registry.conformance.d.ts

@@ -0,0 +1,61 @@
+import { Context, Effect } from "effect";
+import type { Scope } from "effect";
+import { ToolRegistry } from "@xandreed/core";
+import type { Capability } from "@xandreed/core";
+import type { ConformanceCheck } from "@xandreed/core/conformance";
+type Registry = Context.Service.Shape<typeof ToolRegistry>;
+/**
+ * What the kit asks of the registry it builds: the most calls a turn may make.
+ *
+ * @public
+ */
+export interface ToolRegistryLimits {
+    readonly maxCallsPerRun: number;
+    readonly readConcurrency?: number;
+    readonly toolPolicy?: Readonly<Record<string, {
+        readonly concurrency?: number;
+        readonly maxCallsPerRun?: number;
+        readonly breakAfter?: number;
+        readonly breakOn?: "defects" | "failures";
+    }>>;
+}
+/**
+ * The ToolRegistry contract, as checks: the catalog and the run's tools
+ * hold every tool and skill the capabilities define; always-on skills are
+ * active once the matcher's choice is applied, other skills only once
+ * activated, an unknown skill is refused (`skills.unknown`), a skill whose
+ * permission is not granted is not activated, and the active set only grows,
+ * publishing `skills.activated` for what is new; `load_skill` refuses an
+ * unknown skill and an ungranted one as the call's result, under a
+ * PascalCase name and never the host's code; `load_skill` calls running
+ * at once (tool concurrency above 1) leave every loaded tool active and
+ * listed, each published and recorded once; a handled call publishes
+ * `tool.started`, its handler's `tool.progress` and `tool.completed` under
+ * one invocation id (`<runId>:call:<n>`), and the handler sees that call
+ * as `CurrentToolInvocation` and the services where the tools were opened,
+ * the ones it declares (`RegisteredTool.requires`) included. The provider's
+ * pairing key reaches the invocation, every lifecycle event and its journal
+ * record as `toolCallId` (absent on direct calls without one). A run lacking
+ * a service a tool declares fails to open its tools with
+ * `requires.missing`, naming the tool and the service; and a call refused
+ * before its handler runs (`inactive`, `forbidden`, `denied`, `call-limit`,
+ * `tool-call-limit`) takes its invocation id first, publishes one
+ * `tool.refused` with its input and no `tool.started`, never runs the
+ * handler, and fails with the refusal's message as its result, under a
+ * PascalCase name (`Failure.error`).
+ * The registry publishes these events on the run's bus (`RunContext.events`)
+ * only, and never writes the journal itself: the turn journals them (the sdk's
+ * `TurnLive` keeps `tool.progress` out and stores a `tool.refused` without
+ * its input). The kit reads the journal to catch a registry that writes it
+ * directly; what the turn does with the events is `TurnLive`'s, not the
+ * registry's.
+ *
+ * `make` builds a registry over the kit's capabilities for each check, with
+ * at most `maxCallsPerRun` calls per turn and no permissions granted unless
+ * the turn's `PermissionGrants` say so. The kit runs each turn over the sdk's
+ * `TurnLive` with a writer that keeps the turn's events in memory, opens
+ * the tools with a `SessionEnvironment` (which one of its tools declares)
+ * and calls them with another, as a step would.
+ */
+export declare const toolRegistryConformance: (make: (capabilities: ReadonlyArray<Capability>, limits: ToolRegistryLimits) => Effect.Effect<Registry, unknown, Scope.Scope>) => ReadonlyArray<ConformanceCheck>;
+export {};