@xandreed/core 0.4.0 → 0.11.0

package/dist/turn/model-request.entity.d.ts

@@ -0,0 +1,99 @@
+import { Schema } from "effect";
+/** Public provider options only. Credentials and endpoint authorization never belong here. */
+export declare const ModelRequestDescriptor: Schema.Struct<{
+    readonly provider: Schema.String;
+    readonly model: Schema.String;
+    readonly settings: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export type ModelRequestDescriptor = typeof ModelRequestDescriptor.Type;
+/**
+ * The model-visible declaration. A provider-defined tool (one the provider
+ * runs) keeps its id and name, and its args only as their key names and the
+ * SHA-256 of their canonical JSON: args can carry credentials (a remote tool
+ * server's authorization), so their values are never stored. A dispatch
+ * compares the digests, so any change of a value still diverges.
+ */
+export declare const ModelRequestTool: Schema.Struct<{
+    readonly name: Schema.String;
+    readonly description: Schema.String;
+    readonly parameters: Schema.Unknown;
+    readonly provider: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly name: Schema.String;
+        readonly argKeys: Schema.$Array<Schema.String>;
+        readonly argsDigest: Schema.String;
+    }>>;
+}>;
+export type ModelRequestTool = typeof ModelRequestTool.Type;
+/** A saved pure-render recipe: replay uses these options even after a memory plugin upgrade. */
+export declare const MemoryRenderRecipe: Schema.Struct<{
+    readonly strategy: Schema.String;
+    readonly currentTurn: Schema.Int;
+    readonly currentRun: Schema.String;
+    readonly turnContext: Schema.Literals<readonly ["current", "all"]>;
+    readonly replies: Schema.Boolean;
+    readonly stepContext: Schema.Literals<readonly ["tail", "none"]>;
+    readonly digests: Schema.Boolean;
+    readonly media: Schema.Struct<{
+        readonly mode: Schema.Literals<readonly ["none", "inline"]>;
+        readonly maxImages: Schema.Int;
+    }>;
+}>;
+export type MemoryRenderRecipe = typeof MemoryRenderRecipe.Type;
+/**
+ * Durable protocol, separate from diagnostic context/model events. Messages
+ * remain in memory events: the request is rebuilt from the memory entries up
+ * to `through`, the last one its build folded, with the saved `render`
+ * recipe, so a memory write recorded after the build (a reaction to
+ * `context.built`) is not part of it. Each header is self-contained: it
+ * repeats the full system text and every active tool's declaration, a
+ * deliberate storage trade-off so one event (and the memory before it)
+ * rebuilds a request without reading other headers.
+ */
+export declare const ModelRequestHeader: Schema.Struct<{
+    readonly version: Schema.Literal<1>;
+    readonly runId: Schema.String;
+    readonly step: Schema.Int;
+    readonly strategyVersion: Schema.String;
+    readonly system: Schema.String;
+    readonly render: Schema.Struct<{
+        readonly strategy: Schema.String;
+        readonly currentTurn: Schema.Int;
+        readonly currentRun: Schema.String;
+        readonly turnContext: Schema.Literals<readonly ["current", "all"]>;
+        readonly replies: Schema.Boolean;
+        readonly stepContext: Schema.Literals<readonly ["tail", "none"]>;
+        readonly digests: Schema.Boolean;
+        readonly media: Schema.Struct<{
+            readonly mode: Schema.Literals<readonly ["none", "inline"]>;
+            readonly maxImages: Schema.Int;
+        }>;
+    }>;
+    /** The last memory entry the build included (its cut); none for an empty log. */
+    readonly through: Schema.OptionFromNullOr<Schema.brand<Schema.Trimmed, "EntryId">>;
+    readonly contextFingerprint: Schema.String;
+    readonly tools: Schema.$Array<Schema.Struct<{
+        readonly name: Schema.String;
+        readonly description: Schema.String;
+        readonly parameters: Schema.Unknown;
+        readonly provider: Schema.OptionFromNullOr<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly name: Schema.String;
+            readonly argKeys: Schema.$Array<Schema.String>;
+            readonly argsDigest: Schema.String;
+        }>>;
+    }>>;
+    readonly toolChoice: Schema.Unknown;
+    /** None explicitly marks an opaque model whose provider configuration cannot be inspected. */
+    readonly model: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly provider: Schema.String;
+        readonly model: Schema.String;
+        readonly settings: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>>;
+    readonly cacheKey: Schema.OptionFromNullOr<Schema.String>;
+    readonly callPolicy: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly effort: Schema.Literals<readonly ["none", "low", "medium", "high", "xhigh", "max"]>;
+        readonly maxOutputTokens: Schema.optional<Schema.Number>;
+    }>>;
+}>;
+export type ModelRequestHeader = typeof ModelRequestHeader.Type;

package/dist/turn/model-request.entity.functions.d.ts

@@ -0,0 +1,108 @@
+import { Effect, Option } from "effect";
+import { Prompt, Tool } from "effect/ai";
+import type { LanguageModel } from "effect/ai";
+import type { ModelCallPolicy } from "../domain/model-call-policy.entity.js";
+import { HarnessError } from "../harness/plugin.entity.js";
+import type { LogEntry } from "../memory/memory-log.entity.js";
+import type { SessionLogEvent } from "../session/session-log.entity.js";
+import { ModelRequestDescriptor, ModelRequestHeader } from "./model-request.entity.js";
+import type { ModelRequestTool } from "./model-request.entity.js";
+/** Attach inspectable public configuration to an otherwise opaque Effect AI model. */
+export declare const describeModel: (model: LanguageModel.LanguageModel, descriptor: ModelRequestDescriptor | Effect.Effect<ModelRequestDescriptor, HarnessError>) => LanguageModel.LanguageModel;
+/** An undescribed model is explicitly opaque; descriptions are checked at each dispatch. */
+export declare const modelRequestDescriptorOf: (model: LanguageModel.LanguageModel) => Effect.Effect<Option.Option<ModelRequestDescriptor>, HarnessError>;
+/**
+ * A model that reads its configuration per call (a settings-backed router)
+ * resolves it once per step: the model `resolve` returns serves the step's
+ * header and every provider attempt of the step (a stream's fallback
+ * included), so a configuration change applies from the next step.
+ */
+export declare const resolvingModel: (model: LanguageModel.LanguageModel, resolve: Effect.Effect<LanguageModel.LanguageModel, HarnessError>) => LanguageModel.LanguageModel;
+/** The model one step uses: a resolving model's resolution, any other model itself. */
+export declare const resolveModelRequest: (model: LanguageModel.LanguageModel) => Effect.Effect<LanguageModel.LanguageModel, HarnessError>;
+/** Serialize active tools in activation order, independently at preparation and dispatch. */
+export declare const modelRequestTools: (tools: ReadonlyArray<Tool.Any>) => ReadonlyArray<ModelRequestTool>;
+/** Last header for this run and step, decoded from a fresh durable snapshot. */
+export declare const modelRequestHeaderOf: (events: ReadonlyArray<SessionLogEvent>, runId: string, step: number) => Effect.Effect<ModelRequestHeader, HarnessError>;
+/** A model request as a dispatch check compares it: the Effect AI prompt, and the parts the header declares. */
+export interface ComparedModelRequest {
+    readonly prompt: Prompt.Prompt;
+    readonly tools: ReadonlyArray<ModelRequestTool>;
+    readonly toolChoice: unknown;
+    readonly model: Option.Option<ModelRequestDescriptor>;
+    readonly cacheKey: Option.Option<string>;
+    readonly callPolicy: Option.Option<ModelCallPolicy>;
+}
+/**
+ * Rebuild a request from its header and memory facts: the entries up to the
+ * header's cut, folded with its saved render recipe, never with current
+ * plugin definitions. Fails with `request.diverged` (`context`) when they do
+ * not rebuild the context the header was prepared from (a fork's own log
+ * without its parent's history, say).
+ */
+export declare const reconstructModelRequest: (header: ModelRequestHeader, entries: ReadonlyArray<LogEntry>) => Effect.Effect<{
+    prompt: Prompt.Prompt;
+    contextFingerprint: string;
+    tools: readonly {
+        readonly name: string;
+        readonly description: string;
+        readonly parameters: unknown;
+        readonly provider: Option.Option<{
+            readonly id: string;
+            readonly name: string;
+            readonly argKeys: readonly string[];
+            readonly argsDigest: string;
+        }>;
+    }[];
+    toolChoice: unknown;
+    model: Option.Option<{
+        readonly provider: string;
+        readonly model: string;
+        readonly settings: {
+            readonly [x: string]: unknown;
+        };
+    }>;
+    cacheKey: Option.Option<string>;
+    callPolicy: Option.Option<{
+        readonly effort: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+        readonly maxOutputTokens?: number | undefined;
+    }>;
+}, HarnessError, never>;
+/** Reconstruct one historical request from the events up to its header, excluding later responses and turns. */
+export declare const replayModelRequest: (events: ReadonlyArray<SessionLogEvent>, runId: string, step: number) => Effect.Effect<{
+    prompt: Prompt.Prompt;
+    contextFingerprint: string;
+    tools: readonly {
+        readonly name: string;
+        readonly description: string;
+        readonly parameters: unknown;
+        readonly provider: Option.Option<{
+            readonly id: string;
+            readonly name: string;
+            readonly argKeys: readonly string[];
+            readonly argsDigest: string;
+        }>;
+    }[];
+    toolChoice: unknown;
+    model: Option.Option<{
+        readonly provider: string;
+        readonly model: string;
+        readonly settings: {
+            readonly [x: string]: unknown;
+        };
+    }>;
+    cacheKey: Option.Option<string>;
+    callPolicy: Option.Option<{
+        readonly effort: "none" | "low" | "medium" | "high" | "xhigh" | "max";
+        readonly maxOutputTokens?: number | undefined;
+    }>;
+}, HarnessError, never>;
+/** Freeze JSON message data before handing it to a model wrapper. */
+export declare const freezeModelRequest: <A>(value: A) => A;
+/**
+ * Compare canonical model-visible bytes, part by part, not object identity or
+ * hashes alone. A divergence fails with `request.diverged`, its message
+ * starting with the first part that differs (`system`, `messages`, `tools`,
+ * `toolChoice`, `model`, `cacheKey` or `callPolicy`).
+ */
+export declare const checkModelRequest: (expected: ComparedModelRequest, actual: ComparedModelRequest) => Effect.Effect<void, HarnessError>;

package/dist/turn/model-request.entity.functions.js

@@ -0,0 +1,167 @@
+import { Effect, Option, Schema } from "effect";
+import { Prompt, Tool } from "effect/ai";
+import { HarnessError } from "../harness/plugin.entity.js";
+import { toPromptMessages } from "../loop/mapping.js";
+import { toolParametersSchema } from "../loop/toolSchema.js";
+import { canonicalJson, buildContext } from "../memory/memory-log.entity.functions.js";
+import { entriesOfEvents } from "../session/session-event.entity.functions.js";
+import { ModelRequestDescriptor, ModelRequestHeader } from "./model-request.entity.js";
+const descriptorKey = "efferent/model-request-descriptor", resolverKey = "efferent/model-request-resolver";
+export const describeModel = (model, descriptor) => {
+  return { ...model, [descriptorKey]: Effect.isEffect(descriptor) ? descriptor : Effect.succeed(descriptor) };
+}, modelRequestDescriptorOf = (model) => {
+  const candidate = descriptorKey in model ? model[descriptorKey] : void 0;
+  return Effect.isEffect(candidate) ? candidate.pipe(Effect.flatMap(Schema.decodeUnknownEffect(ModelRequestDescriptor)), Effect.map(Option.some), Effect.mapError((error) => error instanceof HarnessError ? error : new HarnessError({ code: "request.descriptor", message: error.message }))) : Effect.succeed(Option.none());
+}, resolvingModel = (model, resolve) => {
+  return { ...model, [resolverKey]: resolve };
+}, resolveModelRequest = (model) => {
+  const candidate = resolverKey in model ? model[resolverKey] : void 0;
+  return Effect.isEffect(candidate) ? candidate : Effect.succeed(model);
+};
+const initialHash = [1779033703, 3144134277, 1013904242, 2773480762, 1359893119, 2600822924, 528734635, 1541459225], rounds = [
+  1116352408,
+  1899447441,
+  3049323471,
+  3921009573,
+  961987163,
+  1508970993,
+  2453635748,
+  2870763221,
+  3624381080,
+  310598401,
+  607225278,
+  1426881987,
+  1925078388,
+  2162078206,
+  2614888103,
+  3248222580,
+  3835390401,
+  4022224774,
+  264347078,
+  604807628,
+  770255983,
+  1249150122,
+  1555081692,
+  1996064986,
+  2554220882,
+  2821834349,
+  2952996808,
+  3210313671,
+  3336571891,
+  3584528711,
+  113926993,
+  338241895,
+  666307205,
+  773529912,
+  1294757372,
+  1396182291,
+  1695183700,
+  1986661051,
+  2177026350,
+  2456956037,
+  2730485921,
+  2820302411,
+  3259730800,
+  3345764771,
+  3516065817,
+  3600352804,
+  4094571909,
+  275423344,
+  430227734,
+  506948616,
+  659060556,
+  883997877,
+  958139571,
+  1322822218,
+  1537002063,
+  1747873779,
+  1955562222,
+  2024104815,
+  2227730452,
+  2361852424,
+  2428436474,
+  2756734187,
+  3204031479,
+  3329325298
+], rotr = (value, bits) => value >>> bits | value << 32 - bits, at = (words, index) => words[index] ?? 0, sha256Of = (text) => {
+  const bytes = new TextEncoder().encode(text), size = Math.ceil((bytes.length + 9) / 64) * 64, padded = new Uint8Array(size);
+  padded.set(bytes);
+  padded[bytes.length] = 128;
+  const view = new DataView(padded.buffer);
+  view.setUint32(size - 8, Math.floor(bytes.length / 536870912));
+  view.setUint32(size - 4, bytes.length * 8 >>> 0);
+  const schedule = (block) => Array.from({ length: 48 }, (_, index) => index + 16).reduce((words, index) => {
+    const early = at(words, index - 15), late = at(words, index - 2), s0 = rotr(early, 7) ^ rotr(early, 18) ^ early >>> 3, s1 = rotr(late, 17) ^ rotr(late, 19) ^ late >>> 10;
+    return [...words, at(words, index - 16) + s0 + at(words, index - 7) + s1 >>> 0];
+  }, Array.from({ length: 16 }, (_, index) => view.getUint32(block * 64 + index * 4))), compress = (hash, block) => {
+    const [a, b, c, d, e, f, g, h] = schedule(block).reduce(([a, b, c, d, e, f, g, h], word, index) => {
+      const t1 = h + (rotr(e, 6) ^ rotr(e, 11) ^ rotr(e, 25)) + (e & f ^ ~e & g) + at(rounds, index) + word >>> 0, t2 = (rotr(a, 2) ^ rotr(a, 13) ^ rotr(a, 22)) + (a & b ^ a & c ^ b & c) >>> 0;
+      return [t1 + t2 >>> 0, a, b, c, d + t1 >>> 0, e, f, g];
+    }, hash);
+    return [
+      hash[0] + a >>> 0,
+      hash[1] + b >>> 0,
+      hash[2] + c >>> 0,
+      hash[3] + d >>> 0,
+      hash[4] + e >>> 0,
+      hash[5] + f >>> 0,
+      hash[6] + g >>> 0,
+      hash[7] + h >>> 0
+    ];
+  };
+  return Array.from({ length: size / 64 }, (_, block) => block).reduce(compress, initialHash).map((word) => word.toString(16).padStart(8, "0")).join("");
+}, providerArgs = (args) => ({
+  argKeys: typeof args === "object" && args !== null && !Array.isArray(args) ? Object.keys(args).sort() : [],
+  argsDigest: sha256Of(canonicalJson(args))
+});
+export const modelRequestTools = (tools) => tools.map((tool) => ({
+  name: tool.name,
+  description: Tool.getDescription(tool) ?? "",
+  parameters: Tool.isDynamic(tool) && tool.jsonSchema !== void 0 ? tool.jsonSchema : toolParametersSchema(tool),
+  provider: Tool.isProviderDefined(tool) ? Option.some({ id: tool.id, name: tool.providerName, ...providerArgs(tool.args) }) : Option.none()
+})), modelRequestHeaderOf = (events, runId, step) => {
+  const header = events.filter((event) => event.kind === "request.prepared" && event.data.runId === runId && event.data.step === step).at(-1);
+  return header === void 0 ? Effect.fail(new HarnessError({ code: "request.missing", message: `No durable request header for ${runId} step ${step}` })) : Schema.decodeUnknownEffect(ModelRequestHeader)(header.data).pipe(Effect.mapError((error) => new HarnessError({ code: "request.decode", message: error.message })));
+};
+const diverged = (part, detail) => new HarnessError({ code: "request.diverged", message: `${part}: ${detail}` }), entriesThrough = (entries, through) => Option.match(through, {
+  onNone: () => Effect.succeed([]),
+  onSome: (id) => {
+    const cut = entries.findIndex((entry) => entry.id === id);
+    return cut < 0 ? Effect.fail(diverged("context", `the memory entry ${id} the request was built through is not in the events`)) : Effect.succeed(entries.slice(0, cut + 1));
+  }
+});
+export const reconstructModelRequest = (header, entries) => Effect.gen(function* () {
+  const context = buildContext(yield* entriesThrough(entries, header.through), header.render);
+  if (context.fingerprint !== header.contextFingerprint)
+    return yield* Effect.fail(diverged("context", `the memory events rebuild context ${context.fingerprint}, the request was prepared from ${header.contextFingerprint}`));
+  return {
+    prompt: Prompt.concat(Prompt.make([{ role: "system", content: header.system }]), Prompt.make(toPromptMessages(context.messages))),
+    contextFingerprint: context.fingerprint,
+    tools: header.tools,
+    toolChoice: header.toolChoice,
+    model: header.model,
+    cacheKey: header.cacheKey,
+    callPolicy: header.callPolicy
+  };
+}), replayModelRequest = (events, runId, step) => Effect.gen(function* () {
+  const header = yield* modelRequestHeaderOf(events, runId, step), position = events.findLastIndex((event) => event.kind === "request.prepared" && event.data.runId === runId && event.data.step === step), entries = yield* entriesOfEvents(events.slice(0, position + 1)).pipe(Effect.mapError((error) => new HarnessError({ code: "request.memory", message: error.message })));
+  return yield* reconstructModelRequest(header, entries);
+}), freezeModelRequest = (value) => {
+  if (typeof value !== "object" || value === null)
+    return value;
+  Object.values(value).map(freezeModelRequest);
+  return Object.freeze(value);
+};
+const requestParts = (request) => [
+  ["system", request.prompt.content.slice(0, 1)],
+  ["messages", request.prompt.content.slice(1)],
+  ["tools", request.tools],
+  ["toolChoice", request.toolChoice],
+  ["model", request.model],
+  ["cacheKey", request.cacheKey],
+  ["callPolicy", request.callPolicy]
+];
+export const checkModelRequest = (expected, actual) => {
+  const dispatched = requestParts(actual), differing = requestParts(expected).find(([, value], index) => canonicalJson(value) !== canonicalJson(dispatched[index]?.[1]));
+  return differing === void 0 ? Effect.void : Effect.fail(diverged(differing[0], "the dispatched request differs from its saved header and memory events"));
+};

package/dist/turn/model-request.entity.js

@@ -0,0 +1,41 @@
+import { Schema } from "effect";
+import { ModelCallPolicy } from "../domain/model-call-policy.entity.js";
+import { EntryId } from "../memory/memory-log.entity.js";
+export const ModelRequestDescriptor = Schema.Struct({
+  provider: Schema.String,
+  model: Schema.String,
+  settings: Schema.Record(Schema.String, Schema.Unknown)
+}), ModelRequestTool = Schema.Struct({
+  name: Schema.String,
+  description: Schema.String,
+  parameters: Schema.Unknown,
+  provider: Schema.OptionFromNullOr(Schema.Struct({
+    id: Schema.String,
+    name: Schema.String,
+    argKeys: Schema.Array(Schema.String),
+    argsDigest: Schema.String
+  }))
+}), MemoryRenderRecipe = Schema.Struct({
+  strategy: Schema.String,
+  currentTurn: Schema.Int,
+  currentRun: Schema.String,
+  turnContext: Schema.Literals(["current", "all"]),
+  replies: Schema.Boolean,
+  stepContext: Schema.Literals(["tail", "none"]),
+  digests: Schema.Boolean,
+  media: Schema.Struct({ mode: Schema.Literals(["none", "inline"]), maxImages: Schema.Int })
+}), ModelRequestHeader = Schema.Struct({
+  version: Schema.Literal(1),
+  runId: Schema.String,
+  step: Schema.Int,
+  strategyVersion: Schema.String,
+  system: Schema.String,
+  render: MemoryRenderRecipe,
+  through: Schema.OptionFromNullOr(EntryId),
+  contextFingerprint: Schema.String,
+  tools: Schema.Array(ModelRequestTool),
+  toolChoice: Schema.Unknown,
+  model: Schema.OptionFromNullOr(ModelRequestDescriptor),
+  cacheKey: Schema.OptionFromNullOr(Schema.String),
+  callPolicy: Schema.OptionFromNullOr(ModelCallPolicy)
+});

package/dist/turn/model-request.entity.test.d.ts

@@ -0,0 +1 @@
+export {};

package/dist/turn/prompt-sections.d.ts

@@ -0,0 +1,10 @@
+import { Effect } from "effect";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { PromptContext, PromptSection } from "../ports/capability.port.js";
+/** Static sections first (the cacheable prefix), then session ones; each tier by order, then id. */
+export declare const orderSections: (sections: ReadonlyArray<PromptSection>) => ReadonlyArray<PromptSection>;
+/** Render sections in order; a section that renders None is left out. Their requirements are the caller's. */
+export declare const renderSections: (sections: ReadonlyArray<PromptSection>, context: PromptContext) => Effect.Effect<ReadonlyArray<{
+    readonly section: PromptSection;
+    readonly text: string;
+}>, HarnessError, unknown>;

package/dist/turn/prompt-sections.js

@@ -0,0 +1,3 @@
+import { Effect, Option } from "effect";
+const tierRank = (section) => section.tier === "static" ? 0 : section.tier === "session" ? 1 : 2;
+export const orderSections = (sections) => [...sections].sort((left, right) => tierRank(left) - tierRank(right) || left.order - right.order || left.id.localeCompare(right.id)), renderSections = (sections, context) => Effect.forEach(orderSections(sections), (section) => section.render(context).pipe(Effect.map((text) => Option.map(text, (value) => ({ section, text: value }))))).pipe(Effect.map((rendered) => rendered.flatMap(Option.toArray)));

package/dist/turn/step-loop.conformance.d.ts

@@ -0,0 +1,16 @@
+import type { Response } from "effect/ai";
+import { Context } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { StepLoop } from "../ports/step-loop.port.js";
+type Part = Response.PartEncoded;
+/** A scripted provider reply calling `probe`. */
+export declare const probeCall: (id: string, n: number) => ReadonlyArray<Part>;
+export declare const textReply: (text: string) => ReadonlyArray<Part>;
+/**
+ * The `StepLoop` contract, as checks any implementation must pass:
+ * per-step event order, recorded results on `step.ended`, planned batches
+ * without a provider call, forced tool choices, awaiting verdicts, no call
+ * after completion, and the step cap.
+ */
+export declare const stepLoopConformance: (loop: Context.Service.Shape<typeof StepLoop>) => ReadonlyArray<ConformanceCheck>;
+export {};

package/dist/turn/step-loop.conformance.js

@@ -0,0 +1,164 @@
+import { LanguageModel, Tool, Toolkit } from "effect/ai";
+import { Context, Effect, Option, Ref, Schema, Stream } from "effect";
+import { ConformanceFailure } from "../conformance.entity.js";
+import { Failure } from "../domain/failure.entity.js";
+import { HarnessError } from "../harness/plugin.entity.js";
+import { CurrentAgentStep } from "../loop/stepContext.js";
+import { entryId } from "../memory/memory-log.entity.functions.js";
+import { makeTurnEvents, makeTurnTasks } from "./turn-bus.js";
+const Probe = Tool.make("probe", {
+  description: "Echo a number.",
+  parameters: Schema.Struct({ n: Schema.Finite }),
+  success: Schema.Number,
+  failure: Failure,
+  failureMode: "return"
+}), typed = Toolkit.make(Probe), erased = [Probe], toolkit = Toolkit.make(...erased), usage = { inputTokens: { total: 10 }, outputTokens: { total: 2 } };
+export const probeCall = (id, n) => [
+  { type: "tool-call", id, name: Probe.name, params: { n }, providerExecuted: !1 },
+  { type: "finish", reason: "tool-calls", usage }
+], textReply = (text) => [{ type: "text", text }, { type: "finish", reason: "stop", usage }];
+const incomplete = { complete: !1, awaiting: [], facts: {} }, observe = (loop, scenario) => Effect.scoped(Effect.gen(function* () {
+  const scope = yield* Effect.scope, events = yield* makeTurnEvents({ maxDepth: 8 }), tasks = yield* makeTurnTasks(scope), seen = yield* Ref.make([]);
+  yield* events.subscribe(Option.some, (event) => Ref.update(seen, (all) => [...all, event]));
+  const calls = yield* Ref.make([]), dispatches = yield* Ref.make([]), model = yield* LanguageModel.make({
+    generateText: (options) => Ref.modify(calls, (all) => [all.length, [...all, options.toolChoice]]).pipe(Effect.tap(() => scenario.providerCall ?? Effect.void), Effect.map((index) => [...scenario.script[index] ?? textReply("done")])),
+    streamText: () => Stream.die("the conformance provider does not stream")
+  }), invocations = yield* Ref.make(0), handlers = yield* typed.toHandlers({
+    probe: ({ n }) => Effect.gen(function* () {
+      const step = Option.getOrElse(yield* Effect.service(CurrentAgentStep), () => -1), invocationId = `probe:${yield* Ref.getAndUpdate(invocations, (value) => value + 1)}`, base = { step, invocationId, tool: Probe.name, input: { n }, labels: {}, stage: Option.none() };
+      yield* events.publish({ _tag: "tool.started", ...base }).pipe(Effect.orDie);
+      yield* events.publish({ _tag: "tool.completed", ...base, ok: !0, result: n, encoded: n, durationMs: 0 }).pipe(Effect.orDie);
+      return n;
+    })
+  }), tools = {
+    toolkit,
+    handlers,
+    active: Effect.succeed([Probe.name]),
+    activate: () => Effect.succeed([Probe.name]),
+    match: (userMessage) => Effect.succeed({ userMessage, skills: [], probabilities: Option.none(), record: Option.none() }),
+    apply: () => Effect.succeed([Probe.name]),
+    select: () => Effect.succeed([Probe.name]),
+    views: {
+      view: (_tool, encoded) => Effect.succeed({ text: String(encoded), version: "1", subjects: [], artifacts: [], pinned: !1 }),
+      compact: () => Effect.succeed(Option.none()),
+      digest: () => Effect.succeed(Option.none())
+    },
+    pollable: [],
+    skills: []
+  }, recorded = yield* Ref.make([]), record = (step, tail) => Ref.modify(recorded, (all) => {
+    const entries = tail.flatMap((message) => message.role !== "tool" ? [{ _tag: "Message", message }] : message.content.map((part) => ({
+      _tag: "ToolResult",
+      toolCallId: part.toolCallId,
+      toolName: part.toolName,
+      isError: part.isError ?? !1,
+      encoded: part.output,
+      view: String(part.output),
+      viewVersion: "1",
+      subjects: [],
+      artifacts: [],
+      pinned: !1
+    }))).map((body, index) => ({ id: entryId("conformance", all.length + index), runId: "conformance", turn: 1, step, at: 0, body }));
+    return [entries, [...all, ...entries]];
+  });
+  yield* scenario.before?.(tasks) ?? Effect.void;
+  const request = {
+    tools,
+    handlers: Context.merge(handlers, Context.make(LanguageModel.LanguageModel, model)),
+    limits: { maxSteps: scenario.maxSteps ?? 6, toolConcurrency: 1, streaming: !1, requireCompletion: !1 },
+    initial: Option.fromNullishOr(scenario.initial),
+    plan: () => Effect.succeed({ model: Option.none(), system: "conformance", messages: [{ role: "user", content: "go" }], toolChoice: Option.fromNullishOr(scenario.toolChoice) }),
+    dispatch: (step) => Ref.update(dispatches, (all) => [...all, step]).pipe(Effect.andThen(scenario.dispatch?.(step) ?? Effect.void)),
+    record,
+    completion: (info) => scenario.completion?.(info.stepIndex, tasks) ?? Effect.succeed(incomplete),
+    steering: Effect.succeed(Option.none()),
+    correctives: Option.none(),
+    events,
+    tasks,
+    cacheKey: Option.none()
+  };
+  return { result: yield* loop.run(request), events: yield* Ref.get(seen), providerCalls: yield* Ref.get(calls), recorded: yield* Ref.get(recorded), dispatches: yield* Ref.get(dispatches) };
+}).pipe(Effect.mapError((error) => new ConformanceFailure({ check: "run", message: error.message })))), expect = (check, holds, message) => holds ? Effect.void : Effect.fail(new ConformanceFailure({ check, message })), stepOf = (event) => ("step" in event) ? Option.some(event.step) : Option.none(), indexOf = (events, tag, step) => events.findIndex((event) => event._tag === tag && Option.contains(stepOf(event), step));
+export const stepLoopConformance = (loop) => [
+  {
+    name: "validates every real request immediately before dispatch, excluding planned batches",
+    run: Effect.gen(function* () {
+      const { dispatches, providerCalls } = yield* observe(loop, { initial: { calls: [{ name: Probe.name, params: { n: 2 } }], skills: [] }, script: [textReply("done")] });
+      yield* expect("dispatch", dispatches.join() === "1" && providerCalls.length === 1, `dispatches ${dispatches.join()}, ${providerCalls.length} provider calls`);
+    })
+  },
+  {
+    name: "a failed durable request check prevents the provider call",
+    run: Effect.gen(function* () {
+      const calls = yield* Ref.make(0), result = yield* Effect.result(observe(loop, {
+        script: [textReply("must not run")],
+        providerCall: Ref.update(calls, (count) => count + 1),
+        dispatch: () => Effect.fail(new HarnessError({ code: "request.diverged", message: "fixture request changed" }))
+      }));
+      yield* expect("dispatch", result._tag === "Failure" && (yield* Ref.get(calls)) === 0, "a rejected request reached the provider");
+    })
+  },
+  {
+    name: "orders step.started < tool.* < step.ended < completion.evaluated within every step",
+    run: Effect.gen(function* () {
+      const check = "order", { events } = yield* observe(loop, { script: [probeCall("c1", 1), textReply("done")] });
+      yield* Effect.forEach([0, 1], (step) => Effect.gen(function* () {
+        const started = indexOf(events, "step.started", step), ended = indexOf(events, "step.ended", step), evaluated = indexOf(events, "completion.evaluated", step), toolEvents = events.flatMap((event, index) => (event._tag === "tool.started" || event._tag === "tool.completed") && event.step === step ? [index] : []);
+        yield* expect(check, started >= 0 && ended > started && evaluated > ended, `step ${step}: started ${started}, ended ${ended}, evaluated ${evaluated}`);
+        yield* expect(check, toolEvents.every((index) => index > started && index < ended), `step ${step}: tool events outside the step`);
+      }));
+      yield* expect(check, events.some((event) => event._tag === "tool.completed" && event.step === 0), "the probe call of step 0 was not published");
+    })
+  },
+  {
+    name: "step.ended lists the step's recorded tool results by entry id",
+    run: Effect.gen(function* () {
+      const { events, recorded } = yield* observe(loop, { script: [probeCall("c1", 1), textReply("done")] }), ended = events.find((event) => event._tag === "step.ended" && event.step === 0), results = ended?._tag === "step.ended" ? ended.results : [], expected = recorded.filter((entry) => entry.step === 0 && entry.body._tag === "ToolResult").map((entry) => String(entry.id));
+      yield* expect("results", results.length === 1 && results.map((result) => String(result.entry)).join() === expected.join() && results[0]?.tool === Probe.name, `expected ${expected.join()}, got ${results.map((result) => result.entry).join()}`);
+    })
+  },
+  {
+    name: "a planned first batch runs without a provider call",
+    run: Effect.gen(function* () {
+      const { events, providerCalls } = yield* observe(loop, { initial: { calls: [{ name: Probe.name, params: { n: 2 } }], skills: [] }, script: [textReply("done")] }), first = events.find((event) => event._tag === "step.started" && event.step === 0);
+      yield* expect("planned", first?._tag === "step.started" && first.planned, "step 0 is not marked planned");
+      yield* expect("planned", events.some((event) => event._tag === "tool.completed" && event.step === 0), "the planned call did not run in step 0");
+      yield* expect("planned", providerCalls.length === 1, `expected 1 provider call, got ${providerCalls.length}`);
+    })
+  },
+  {
+    name: "a forced tool choice reaches the provider",
+    run: Effect.gen(function* () {
+      const { providerCalls } = yield* observe(loop, { toolChoice: { tool: Probe.name }, script: [textReply("done")] }), choice = providerCalls[0];
+      yield* expect("tool-choice", typeof choice === "object" && choice !== null && "tool" in choice && choice.tool === Probe.name, `the provider saw ${JSON.stringify(choice)}`);
+    })
+  },
+  {
+    name: "an awaiting verdict joins its tasks and is evaluated once more",
+    run: Effect.gen(function* () {
+      const done = yield* Ref.make(!1), { events, providerCalls, result } = yield* observe(loop, {
+        script: [probeCall("c1", 1)],
+        before: (tasks) => tasks.fork("work", Effect.sleep("20 millis").pipe(Effect.andThen(Ref.set(done, !0)))),
+        completion: () => Ref.get(done).pipe(Effect.map((complete) => ({ complete, awaiting: complete ? [] : ["work"], facts: {} })))
+      }), verdicts = events.flatMap((event) => event._tag === "completion.evaluated" && event.step === 0 ? [event.verdict] : []);
+      yield* expect("awaiting", verdicts.length === 2 && verdicts[0]?.complete === !1 && verdicts[1]?.complete === !0, `step 0 verdicts: ${JSON.stringify(verdicts)}`);
+      yield* expect("awaiting", providerCalls.length === 1 && result.outcome === "completed", `${providerCalls.length} provider calls, ${result.outcome}`);
+    })
+  },
+  {
+    name: "no provider call follows a complete verdict",
+    run: Effect.gen(function* () {
+      const { providerCalls, result } = yield* observe(loop, {
+        script: [probeCall("c1", 1), probeCall("c2", 2)],
+        completion: () => Effect.succeed({ complete: !0, awaiting: [], facts: {} })
+      });
+      yield* expect("complete", providerCalls.length === 1 && result.outcome === "completed", `${providerCalls.length} provider calls, ${result.outcome}`);
+    })
+  },
+  {
+    name: "the step cap ends the run as partial",
+    run: Effect.gen(function* () {
+      const { providerCalls, result } = yield* observe(loop, { maxSteps: 2, script: [probeCall("c1", 1), probeCall("c2", 2), probeCall("c3", 3)] });
+      yield* expect("step-cap", result.outcome === "partial" && result.reason === "step-cap" && providerCalls.length === 2, `${result.outcome}/${result.reason} after ${providerCalls.length} provider calls`);
+    })
+  }
+];

package/dist/turn/testing.d.ts

@@ -0,0 +1,30 @@
+import { Effect, Option, Ref } from "effect";
+import { ConversationId } from "../domain/message.entity.js";
+import type { TurnWriter } from "../ports/sessions.port.js";
+import type { SessionLogEvent } from "../session/session-log.entity.js";
+/**
+ * A turn writer that keeps the session's events in memory, for testing the
+ * turn's pieces without a sessions plugin: the turn is begun (its
+ * `turn.started` stored) over `history`, writes are stored at once, and the
+ * turn is never closed from outside.
+ */
+export declare const recordingTurnWriter: (input: {
+    readonly runId: string;
+    readonly text: string;
+    readonly turn?: number;
+    readonly history?: ReadonlyArray<SessionLogEvent>;
+    readonly conversation?: ConversationId;
+}) => Effect.Effect<{
+    writer: TurnWriter;
+    stored: Ref.Ref<readonly {
+        readonly session: string & import("effect/Brand").Brand<"ConversationId">;
+        readonly seq: number;
+        readonly turn: Option.Option<number>;
+        readonly kind: string;
+        readonly at: number;
+        readonly data: {
+            readonly [x: string]: unknown;
+        };
+    }[]>;
+    kinds: Effect.Effect<string[], never, never>;
+}, never, never>;