@xandreed/core 0.13.0 → 0.14.0

package/dist/session/tasks.conformance.d.ts

@@ -0,0 +1,70 @@
+import { Context, Effect, Option, Scope } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { TaskActivity } from "../ports/activity.port.js";
+import type { Sessions } from "../ports/sessions.port.js";
+import { TaskExecutor, TaskRunner } from "../ports/tasks.port.js";
+import type { Tasks } from "../ports/tasks.port.js";
+type Runner = Context.Service.Shape<typeof TaskRunner>;
+type Executor = Context.Service.Shape<typeof TaskExecutor>;
+/** A task runner as the kit builds one. */
+export interface TaskRunnerFixture {
+    readonly runner: Runner;
+    /** Its `TaskActivity`, when it provides one: then checked against the work it runs. */
+    readonly activity: Option.Option<Context.Service.Shape<typeof TaskActivity>>;
+}
+/**
+ * The TaskRunner contract, as checks: `run` returns once the work is handed
+ * over, before it ends, and the work runs once; it goes on when the caller
+ * that handed it over is interrupted and its scope closed; the deadline it
+ * is told is none or not in the past; it runs without the caller's
+ * services (a task outlives the turn that started it); with a
+ * `TaskActivity`, the work counts from the moment `run` hands it over until
+ * it ends, and `idle` waits for all of it; and closing the scope the runner
+ * was made in interrupts the work still running (it counts no more), so a
+ * task's turn ends interrupted rather than lost.
+ *
+ * `make` is run afresh for each check, in a scope the kit closes. A runner
+ * that hands work to something outside this process's scope (a serverless
+ * `waitUntil`) cannot interrupt it: give it `{ interruptsOnClose: false }`
+ * to leave that check out. The checks wait up to two seconds on the live
+ * clock for work they expect, so run the kit on the live clock.
+ */
+export declare const taskRunnerConformance: (make: Effect.Effect<TaskRunnerFixture, unknown, Scope.Scope>, options?: {
+    readonly interruptsOnClose?: boolean;
+}) => ReadonlyArray<ConformanceCheck>;
+/** What the kit's executor gives the tasks backend. */
+export interface TasksDependencies {
+    readonly runner: Runner;
+    readonly executor: Executor;
+}
+/** A tasks backend as the kit builds one: its `Tasks` and the `Sessions` they run over. */
+export interface TasksFixture {
+    readonly sessions: Context.Service.Shape<typeof Sessions>;
+    readonly tasks: Context.Service.Shape<typeof Tasks>;
+}
+/**
+ * The Tasks contract, as checks: a task runs as one turn of a child session
+ * (a spawn starts empty; a fork's history is the parent's up to its last
+ * closed turn), its result reaches the parent's inbox once and the parent
+ * reacts to it once, after the turn in flight; the parent records
+ * `task.started` once per task, and starting a task again runs it once; a
+ * failed turn's result says why; a cancel stops the child's turn and
+ * delivers nothing; a task does not start tasks; and `reconcile` starts a
+ * task whose runner never ran it, and delivers, once, a finished result
+ * whose delivery was lost. The kit loses one by filling the parent's inbox
+ * until `deliver` fails with `InboxFull` before the task ends: that check
+ * relies on the backend leaving a result the full inbox refused for a later
+ * `reconcile`, and runs only over a `Sessions` whose inbox refuses an item
+ * within 256 deliveries (one that takes them all passes it unchecked).
+ *
+ * `make` builds the backend for each check over the kit's own `TaskRunner`
+ * (each piece of work on a fiber the kit waits for, with the services the
+ * check had when it built the runner and none of the caller's, as a
+ * conforming runner runs it; or dropped, as by a runner that died) and
+ * `TaskExecutor` (a child turn answers
+ * `found: <instructions>` unless the check says otherwise; a reaction
+ * records the turn it ran on). The checks wait up to two seconds on the live
+ * clock for background work to end, so run the kit on the live clock.
+ */
+export declare const tasksConformance: (make: (dependencies: TasksDependencies) => Effect.Effect<TasksFixture, unknown, Scope.Scope>) => ReadonlyArray<ConformanceCheck>;
+export {};

package/dist/session/tasks.conformance.js

@@ -0,0 +1,213 @@
+import { Clock, Context, Deferred, Effect, Exit, Fiber, FiberSet, Option, Ref, Scope } from "effect";
+import { check, eventually, expect, fail, freshId, kindsOf, settles } from "../conformance.functions.js";
+import { HarnessError } from "../harness/plugin.entity.js";
+import { TaskExecutor, TaskRunner } from "../ports/tasks.port.js";
+import { UserMessage } from "../turn/user-message.entity.js";
+const WAIT = "2 seconds", within = (id, message) => (effect) => Effect.timeoutOrElse(effect, { duration: WAIT, orElse: () => fail(id, message) }), CallerProbe = Context.Reference("efferent/conformance/TaskRunnerCaller", { defaultValue: () => "none" });
+export const taskRunnerConformance = (make, options = {}) => {
+  const scoped = (name, id, body) => check(name, id, () => Effect.scoped(make.pipe(Effect.flatMap(body)))), handOver = (runner, id, work) => runner.run(work).pipe(within(id, `run did not return within ${WAIT} of being called: it must return once the work is handed over, not when the work ends`));
+  return [
+    scoped("run returns once the work is handed over, before it ends, and the work runs once", "hand-over", ({ runner }) => Effect.gen(function* () {
+      const runs = yield* Ref.make(0), release = yield* Deferred.make(), ended = yield* Deferred.make(), handing = yield* Effect.forkChild(runner.run(() => Ref.update(runs, (count) => count + 1).pipe(Effect.andThen(Deferred.await(release)), Effect.andThen(Deferred.succeed(ended, void 0))))), returned = yield* Effect.timeoutOption(Fiber.await(handing), WAIT);
+      yield* Deferred.succeed(release, void 0);
+      yield* expect("hand-over", Option.isSome(returned), `run did not return within ${WAIT} while its work waited: it runs the work instead of handing it over`);
+      yield* expect("hand-over", Option.exists(returned, Exit.isSuccess), "run failed");
+      yield* Deferred.await(ended).pipe(within("hand-over", `the work never ended within ${WAIT} of being released`));
+      yield* Effect.yieldNow;
+      const count = yield* Ref.get(runs);
+      yield* expect("hand-over", count === 1, `the work ran ${count} times`);
+    })),
+    scoped("the work goes on when the caller that handed it over is interrupted and its scope closed", "outlives-caller", ({ runner }) => Effect.gen(function* () {
+      const started = yield* Deferred.make(), release = yield* Deferred.make(), ended = yield* Deferred.make(), handed = yield* Deferred.make(), caller = yield* Effect.forkChild(Effect.scoped(runner.run(() => Deferred.succeed(started, void 0).pipe(Effect.andThen(Deferred.await(release)), Effect.andThen(Deferred.succeed(ended, void 0))))).pipe(Effect.andThen(Deferred.succeed(handed, void 0)), Effect.andThen(Effect.never)));
+      yield* Deferred.await(started).pipe(within("outlives-caller", `the work did not start within ${WAIT}`));
+      yield* Deferred.await(handed).pipe(within("outlives-caller", `run did not return within ${WAIT} while its work waited`));
+      yield* Fiber.interrupt(caller);
+      yield* Deferred.succeed(release, void 0);
+      yield* Deferred.await(ended).pipe(within("outlives-caller", "the work stopped with the caller that handed it over"));
+    })),
+    scoped("the work is told a deadline that is none or not in the past", "deadline", ({ runner }) => Effect.gen(function* () {
+      const told = yield* Deferred.make(), before = yield* Clock.currentTimeMillis;
+      yield* handOver(runner, "deadline", (deadline) => Deferred.succeed(told, deadline).pipe(Effect.asVoid));
+      const deadline = yield* Deferred.await(told).pipe(within("deadline", `the work did not run within ${WAIT}`));
+      yield* expect("deadline", Option.match(deadline, { onNone: () => !0, onSome: (at) => at >= before }), `the work was told a deadline ${Option.getOrNull(deadline)} before the hand-over at ${before}`);
+    })),
+    scoped("the work runs without the services of the caller that handed it over", "isolation", ({ runner }) => Effect.gen(function* () {
+      const seen = yield* Deferred.make();
+      yield* handOver(runner, "isolation", () => Effect.service(CallerProbe).pipe(Effect.flatMap((value) => Deferred.succeed(seen, value)), Effect.asVoid)).pipe(Effect.provideService(CallerProbe, "the caller's"));
+      const value = yield* Deferred.await(seen).pipe(within("isolation", `the work did not run within ${WAIT}`));
+      yield* expect("isolation", value !== "the caller's", "the work ran with the services of the caller that handed it over (the turn that starts a task ends before it)");
+    })),
+    scoped("TaskActivity counts the work from the moment run hands it over until it ends, and idle waits for all of it", "activity", ({ runner, activity }) => Option.match(activity, {
+      onNone: () => Effect.void,
+      onSome: (probe) => Effect.gen(function* () {
+        yield* expect("activity", (yield* probe.running) === 0, "a new runner counts work running");
+        yield* expect("activity", yield* settles(yield* Effect.forkChild(probe.idle)), "idle does not complete with nothing running");
+        const releases = [yield* Deferred.make(), yield* Deferred.make()];
+        yield* handOver(runner, "activity", () => Deferred.await(releases[0]));
+        const afterOne = yield* probe.running;
+        yield* expect("activity", afterOne === 1, `right after run returned, ${afterOne} pieces of work count (the work counts from the hand-over)`);
+        yield* handOver(runner, "activity", () => Deferred.await(releases[1]));
+        yield* expect("activity", (yield* probe.running) === 2, `with two pieces of work handed over, ${yield* probe.running} count`);
+        const idle = yield* Effect.forkChild(probe.idle);
+        yield* expect("activity", !(yield* settles(idle)), "idle completed while work was running");
+        yield* Deferred.succeed(releases[0], void 0);
+        const one = yield* eventually(probe.running, (count) => count === 1);
+        yield* expect("activity", one === 1, `after one piece of work ended, ${one} count`);
+        yield* expect("activity", !(yield* settles(idle)), "idle completed while work was still running");
+        yield* Deferred.succeed(releases[1], void 0);
+        yield* Fiber.join(idle).pipe(within("activity", `idle did not complete within ${WAIT} of the last work ending`));
+        yield* expect("activity", (yield* probe.running) === 0, `after all the work ended, ${yield* probe.running} pieces count`);
+      })
+    })),
+    ...options.interruptsOnClose === !1 ? [] : [
+      check("closing the scope the runner was made in interrupts the work still running, which then counts no more", "scope-close", () => Effect.scoped(Effect.gen(function* () {
+        const runnerScope = yield* Effect.acquireRelease(Scope.make(), (scope) => Scope.close(scope, Exit.void)), fixture = yield* make.pipe(Scope.provide(runnerScope)), started = yield* Deferred.make(), interrupted = yield* Deferred.make();
+        yield* Effect.forkChild(fixture.runner.run(() => Deferred.succeed(started, void 0).pipe(Effect.andThen(Effect.never), Effect.onInterrupt(() => Deferred.succeed(interrupted, void 0)))));
+        yield* Deferred.await(started).pipe(within("scope-close", `the work did not start within ${WAIT}`));
+        yield* Scope.close(runnerScope, Exit.void);
+        yield* Deferred.await(interrupted).pipe(within("scope-close", `the work was not interrupted within ${WAIT} of the runner's scope closing`));
+        yield* Option.match(fixture.activity, {
+          onNone: () => Effect.void,
+          onSome: (probe) => eventually(probe.running, (count) => count === 0).pipe(Effect.flatMap((count) => expect("scope-close", count === 0, `after the runner's scope closed, ${count} pieces of work count`)))
+        });
+      })))
+    ]
+  ];
+};
+const ofKind = (events, kind) => events.filter((event) => event.kind === kind), reasons = (events) => ofKind(events, "turn.ended").map((event) => String(event.data.reason)).join(), FILL = 256, fillInbox = (sessions, parent, n = 0) => n >= FILL ? Effect.succeed(!1) : sessions.deliver(parent, { id: `fill-${n}`, source: { kind: "conformance", id: `fill-${n}` }, content: `filler ${n}` }).pipe(Effect.as(!1), Effect.catchTag("InboxFull", () => Effect.succeed(!0)), Effect.flatMap((full) => full ? Effect.succeed(!0) : fillInbox(sessions, parent, n + 1)));
+export const tasksConformance = (make) => {
+  const harness = (owner, childTurn = (_writer, task) => Effect.succeed({ outcome: "completed", reply: Option.some(`found: ${task.instructions}`) })) => Effect.gen(function* () {
+    const fibers = yield* FiberSet.make(), built = yield* Effect.context(), dropping = yield* Ref.make(!1), turns = yield* Ref.make([]), reactions = yield* Ref.make([]), runner = TaskRunner.of({
+      run: (work) => Ref.get(dropping).pipe(Effect.flatMap((drop) => drop ? Effect.void : FiberSet.run(fibers, work(Option.none()).pipe(Effect.updateContext((_) => built))).pipe(Effect.asVoid)))
+    }), react = (writer) => Ref.update(reactions, (all) => [...all, writer.admitted]), executor = TaskExecutor.of({
+      turn: (writer, task) => writer.history([]).pipe(Effect.flatMap((history) => Ref.update(turns, (all) => [...all, { admitted: writer.admitted, task, history: kindsOf(history) }])), Effect.andThen(childTurn(writer, task))),
+      react
+    }), fixture = yield* make({ runner, executor }), parent = yield* fixture.sessions.create({ owner }).pipe(Effect.map((view) => ({ id: view.header.id, owner })));
+    return {
+      ...fixture,
+      parent,
+      dropping,
+      turns: Ref.get(turns),
+      reactions: Ref.get(reactions),
+      react,
+      idle: (id) => FiberSet.awaitEmpty(fibers).pipe(within(id, `the background work did not end within ${WAIT}`)),
+      read: (address) => fixture.sessions.read(address)
+    };
+  }), scoped = (name, id, body) => check(name, id, (owner) => Effect.scoped(body(owner))), done = { reason: "completed", failure: Option.none() };
+  return [
+    scoped("a task runs as one turn of a child session, its result reaches the parent's inbox once, and the parent reacts once", "run", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner), view = yield* h.tasks.start(h.parent, { instructions: "look it up", mode: "spawn" });
+      yield* expect("run", view.parent === h.parent.id && view.child === view.taskId && view.instructions === "look it up" && view.mode === "spawn" && ["pending", "running", "completed"].includes(view.status), `start returned ${view.status} for ${view.child} under ${view.parent}`);
+      yield* h.idle("run");
+      const status = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("run", status.status === "completed" && Option.contains(status.reply, "found: look it up") && status.delivered && Option.isNone(status.failure), `the finished task reads ${status.status}, reply ${Option.getOrNull(status.reply)}, delivered ${status.delivered}`);
+      const child = { id: view.child, owner }, lineage = (yield* h.sessions.get(child)).header.parent;
+      yield* expect("run", Option.exists(lineage, (at) => at.id === h.parent.id), "the task's session is not a child of the parent");
+      const childEvents = yield* h.read(child);
+      yield* expect("run", ofKind(childEvents, "turn.started").length === 1 && reasons(childEvents) === "completed", `the child holds ${ofKind(childEvents, "turn.started").length} turns, ended ${reasons(childEvents)}`);
+      const ran = yield* h.turns;
+      yield* expect("run", ran.length === 1 && ran[0].admitted.session.id === view.child && ran[0].task.taskId === view.taskId && ran[0].task.instructions === "look it up" && ran[0].history === "", `the executor ran ${ran.length} child turns, the first with history [${ran[0]?.history ?? ""}]`);
+      const reacted = yield* h.reactions;
+      yield* expect("run", reacted.length === 1 && reacted[0].origin === "inbox" && reacted[0].session.id === h.parent.id && reacted[0].claimed.length === 1 && reacted[0].claimed[0].content.includes("found: look it up"), `the parent reacted ${reacted.length} times${reacted.length > 0 ? `, to ${reacted[0].claimed.length} items` : ""}`);
+      const parentEvents = yield* h.read(h.parent), started = ofKind(parentEvents, "task.started");
+      yield* expect("run", started.length === 1 && started[0].data.taskId === view.taskId, `the parent records ${started.length} task.started`);
+      yield* expect("run", ofKind(parentEvents, "inbox.queued").length === 1, `the parent's inbox took ${ofKind(parentEvents, "inbox.queued").length} deliveries`);
+      const listed = (yield* h.tasks.list(h.parent)).map((task) => task.taskId).join();
+      yield* expect("run", listed === view.taskId, `the parent lists [${listed}]`);
+    })),
+    scoped("starting a task again (by its id, while it runs or after) runs it once", "start-once", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner), taskId = yield* freshId, input = { taskId, instructions: "once", mode: "spawn" }, first = yield* h.tasks.start(h.parent, input), again = yield* h.tasks.start(h.parent, input);
+      yield* h.idle("start-once");
+      const after = yield* h.tasks.start(h.parent, input);
+      yield* h.idle("start-once");
+      yield* expect("start-once", [first, again, after].every((view) => view.taskId === taskId), "a start of the same task returned another task");
+      const counts = {
+        listed: (yield* h.tasks.list(h.parent)).length,
+        turns: (yield* h.turns).length,
+        reactions: (yield* h.reactions).length,
+        started: ofKind(yield* h.read(h.parent), "task.started").length,
+        delivered: ofKind(yield* h.read(h.parent), "inbox.queued").length
+      };
+      yield* expect("start-once", Object.values(counts).every((count) => count === 1), `three starts of one task gave ${JSON.stringify(counts)}`);
+    })),
+    scoped("a result that arrives during the parent's turn waits for it, and a fork's history is the parent's up to its last closed turn", "after-turn", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner), say = (text) => ({ _tag: "User", userMessage: new UserMessage({ text }), runId: `run-${text}`, key: text, command: {} });
+      yield* Effect.scoped(h.sessions.begin(h.parent, say("one")).pipe(Effect.tap((writer) => writer.end(done))));
+      const open = yield* Effect.acquireRelease(Scope.make(), (scope) => Scope.close(scope, Exit.void)), writer = yield* h.sessions.begin(h.parent, say("two")).pipe(Scope.provide(open)), view = yield* h.tasks.start(h.parent, { instructions: "compare", mode: "fork" });
+      yield* h.idle("after-turn");
+      const status = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("after-turn", status.status === "completed" && status.delivered, `the task finished as ${status.status}, delivered ${status.delivered}`);
+      yield* expect("after-turn", (yield* h.reactions).length === 0, "the parent reacted while its turn was open");
+      const ended = yield* writer.end(done);
+      yield* expect("after-turn", ended.pending === 1, `the parent's turn ended with ${ended.pending} items waiting`);
+      yield* h.sessions.drain(h.parent, h.react);
+      yield* expect("after-turn", (yield* h.reactions).length === 1, `after the parent's turn the drain reacted ${(yield* h.reactions).length} times`);
+      const history = (yield* h.turns)[0]?.history ?? "none";
+      yield* expect("after-turn", history.startsWith("turn.started@1,") && history.endsWith("turn.ended@1") && !history.includes("@2"), `the fork's child turn saw the history [${history}]`);
+    })),
+    scoped("a failed child turn is a failed task that says why, and the parent still hears of it", "failed", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner, () => Effect.fail(new HarnessError({ code: "conformance.down", message: "the model is down" }))), view = yield* h.tasks.start(h.parent, { instructions: "doomed", mode: "spawn" });
+      yield* h.idle("failed");
+      const status = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("failed", status.status === "failed" && Option.exists(status.failure, (failure) => failure.code === "conformance.down") && status.delivered, `the task reads ${status.status}, failure ${JSON.stringify(Option.getOrNull(status.failure))}, delivered ${status.delivered}`);
+      yield* expect("failed", reasons(yield* h.read({ id: view.child, owner })) === "failed", "the child's turn did not end failed");
+      yield* expect("failed", (yield* h.reactions).length === 1, `the parent reacted ${(yield* h.reactions).length} times`);
+    })),
+    scoped("a cancel stops the child's turn and delivers nothing; a finished or unknown task is not cancelled", "cancel", (owner) => Effect.gen(function* () {
+      const entered = yield* Deferred.make(), h = yield* harness(owner, () => Deferred.succeed(entered, void 0).pipe(Effect.andThen(Effect.never))), view = yield* h.tasks.start(h.parent, { instructions: "forever", mode: "spawn" });
+      yield* Deferred.await(entered).pipe(within("cancel", `the child's turn did not start within ${WAIT}`));
+      const running = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("cancel", running.status === "running", `a task in its turn reads ${running.status}`);
+      yield* expect("cancel", yield* h.tasks.cancel(h.parent, view.taskId), "cancelling a running task answered false");
+      yield* h.idle("cancel");
+      const cancelled = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("cancel", cancelled.status === "cancelled" && !cancelled.delivered, `the cancelled task reads ${cancelled.status}, delivered ${cancelled.delivered}`);
+      yield* expect("cancel", reasons(yield* h.read({ id: view.child, owner })) === "cancelled", "the child's turn did not end cancelled");
+      yield* expect("cancel", (yield* h.reactions).length === 0 && ofKind(yield* h.read(h.parent), "inbox.queued").length === 0, "the cancelled task delivered something");
+      yield* expect("cancel", !(yield* h.tasks.cancel(h.parent, view.taskId)), "cancelling a cancelled task answered true");
+      const unknown = [yield* Effect.flip(h.tasks.cancel(h.parent, "no-such-task")), yield* Effect.flip(h.tasks.status(h.parent, "no-such-task"))];
+      yield* expect("cancel", unknown.every((error) => error._tag === "TaskMissing"), `an unknown task gave ${unknown.map((error) => error._tag).join()}`);
+    })),
+    scoped("a task does not start tasks", "depth", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner), view = yield* h.tasks.start(h.parent, { instructions: "first", mode: "spawn" });
+      yield* h.idle("depth");
+      const nested = yield* Effect.flip(h.tasks.start({ id: view.child, owner }, { instructions: "deeper", mode: "spawn" }));
+      yield* expect("depth", nested._tag === "TaskRefused" && nested.reason === "depth", `a task's session starting a task gave ${nested._tag}`);
+    })),
+    scoped("reconcile starts a task its runner never ran, which then delivers; done, it finds nothing more", "reconcile", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner);
+      yield* Ref.set(h.dropping, !0);
+      const view = yield* h.tasks.start(h.parent, { instructions: "never ran", mode: "spawn" }), lost = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("reconcile", lost.status === "pending", `a task whose runner dropped it reads ${lost.status}`);
+      yield* Ref.set(h.dropping, !1);
+      const first = yield* h.tasks.reconcile(h.parent);
+      yield* expect("reconcile", first.started === 1 && first.delivered === 0, `reconcile answered ${JSON.stringify(first)}`);
+      yield* h.idle("reconcile");
+      const status = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("reconcile", status.status === "completed" && status.delivered && (yield* h.reactions).length === 1, `the reconciled task reads ${status.status}, delivered ${status.delivered}`);
+      const second = yield* h.tasks.reconcile(h.parent);
+      yield* h.idle("reconcile");
+      yield* expect("reconcile", second.started === 0 && second.delivered === 0 && (yield* h.turns).length === 1, `reconciling again answered ${JSON.stringify(second)}`);
+    })),
+    scoped("reconcile delivers a finished result whose delivery was lost (the parent's inbox was full), once", "reconcile-delivery", (owner) => Effect.gen(function* () {
+      const h = yield* harness(owner);
+      if (!(yield* fillInbox(h.sessions, h.parent)))
+        return;
+      const view = yield* h.tasks.start(h.parent, { instructions: "lost on the way", mode: "spawn" });
+      yield* h.idle("reconcile-delivery");
+      const lost = yield* h.tasks.status(h.parent, view.taskId);
+      yield* expect("reconcile-delivery", lost.status === "completed" && !lost.delivered, `a task whose result the parent's full inbox refused reads ${lost.status}, delivered ${lost.delivered}`);
+      yield* h.sessions.drain(h.parent, h.react, { maxTurns: FILL + 1 });
+      yield* expect("reconcile-delivery", (yield* h.sessions.get(h.parent)).pending === 0, "draining the parent left items waiting");
+      const first = yield* h.tasks.reconcile(h.parent);
+      yield* expect("reconcile-delivery", first.delivered === 1 && first.started === 0, `reconcile answered ${JSON.stringify(first)}`);
+      yield* h.idle("reconcile-delivery");
+      const before = (yield* h.reactions).length;
+      yield* h.sessions.drain(h.parent, h.react);
+      const status = yield* h.tasks.status(h.parent, view.taskId), reacted = yield* h.reactions;
+      yield* expect("reconcile-delivery", status.delivered && reacted.length === before + 1 && (reacted.at(-1)?.claimed.some((claimed) => claimed.content.includes("found: lost on the way")) ?? !1), `after reconcile the task reads delivered ${status.delivered}, and the parent reacted ${reacted.length - before} times to it`);
+      const second = yield* h.tasks.reconcile(h.parent);
+      yield* expect("reconcile-delivery", second.started === 0 && second.delivered === 0 && (yield* h.turns).length === 1, `reconciling again answered ${JSON.stringify(second)}`);
+    }))
+  ];
+};

package/dist/session/tasks.conformance.test.d.ts

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

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

@@ -37,6 +37,8 @@ export declare const MemoryRenderRecipe: Schema.Struct<{
     readonly media: Schema.Struct<{
         readonly mode: Schema.Literals<readonly ["none", "inline"]>;
         readonly maxImages: Schema.Int;
+        /** Base64 characters of the images sent as images; a header written before 0.14.0 reads `MEDIA_LIMITS.requestChars`. */
+        readonly maxChars: Schema.withDecodingDefaultKey<Schema.Int, never>;
     }>;
 }>;
 export type MemoryRenderRecipe = typeof MemoryRenderRecipe.Type;
@@ -67,6 +69,8 @@ export declare const ModelRequestHeader: Schema.Struct<{
         readonly media: Schema.Struct<{
             readonly mode: Schema.Literals<readonly ["none", "inline"]>;
             readonly maxImages: Schema.Int;
+            /** Base64 characters of the images sent as images; a header written before 0.14.0 reads `MEDIA_LIMITS.requestChars`. */
+            readonly maxChars: Schema.withDecodingDefaultKey<Schema.Int, never>;
         }>;
     }>;
     /** The last memory entry the build included (its cut); none for an empty log. */

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

@@ -1,4 +1,5 @@
-import { Schema } from "effect";
+import { Effect, Schema } from "effect";
+import { MEDIA_LIMITS } from "../domain/media.entity.js";
 import { ModelCallPolicy } from "../domain/model-call-policy.entity.js";
 import { EntryId } from "../memory/memory-log.entity.js";
 export const ModelRequestDescriptor = Schema.Struct({
@@ -23,7 +24,11 @@ export const ModelRequestDescriptor = Schema.Struct({
   replies: Schema.Boolean,
   stepContext: Schema.Literals(["tail", "none"]),
   digests: Schema.Boolean,
-  media: Schema.Struct({ mode: Schema.Literals(["none", "inline"]), maxImages: Schema.Int })
+  media: Schema.Struct({
+    mode: Schema.Literals(["none", "inline"]),
+    maxImages: Schema.Int,
+    maxChars: Schema.Int.pipe(Schema.withDecodingDefaultKey(Effect.succeed(MEDIA_LIMITS.requestChars)))
+  })
 }), ModelRequestHeader = Schema.Struct({
   version: Schema.Literal(1),
   runId: Schema.String,

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

@@ -10,7 +10,10 @@ 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.
+ * after completion, the run's usage, the step cap, the request's
+ * `captureTraceContent` provided to its model calls as `CurrentTraceContent`,
+ * and a request refused over an image planned again and sent once more
+ * when `onMediaRejected` answers true, failing the step when it answers false.
  */
 export declare const stepLoopConformance: (loop: Context.Service.Shape<typeof StepLoop>) => ReadonlyArray<ConformanceCheck>;
 export {};

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

@@ -1,9 +1,12 @@
-import { LanguageModel, Tool, Toolkit } from "effect/ai";
+import { AiError, LanguageModel, Tool, Toolkit } from "effect/ai";
 import { Context, Effect, Option, Ref, Schema, Stream } from "effect";
 import { ConformanceFailure } from "../conformance.entity.js";
+import { sameUsage } from "../conformance.functions.js";
 import { Failure } from "../domain/failure.entity.js";
 import { HarnessError } from "../harness/plugin.entity.js";
+import { sumUsage } from "../domain/token-usage.entity.functions.js";
 import { CurrentAgentStep } from "../loop/stepContext.js";
+import { CurrentTraceContent } from "../loop/traceContent.js";
 import { entryId } from "../memory/memory-log.entity.functions.js";
 import { makeTurnEvents, makeTurnTasks } from "./turn-bus.js";
 const Probe = Tool.make("probe", {
@@ -17,11 +20,18 @@ 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 billed = (input, output) => ({
+  inputTokens: { total: input, uncached: input - 30, cacheRead: 20, cacheWrite: 10 },
+  outputTokens: { total: output, text: output - 3, reasoning: 3 }
+}), withUsage = (reply, value) => reply.map((part) => part.type === "finish" ? { ...part, usage: value } : part), imageRefusal = AiError.make({
+  module: "Conformance",
+  method: "generateText",
+  reason: new AiError.InvalidRequestError({ description: "messages.0.content.0.image: the image could not be processed" })
+}), 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")])),
+  const calls = yield* Ref.make([]), dispatches = yield* Ref.make([]), traceContent = 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.tap(() => Effect.service(CurrentTraceContent).pipe(Effect.flatMap((capture) => Ref.update(traceContent, (all) => [...all, capture])))), Effect.flatMap((index) => scenario.refuseFirst === !0 && index === 0 ? Effect.fail(imageRefusal) : Effect.succeed([...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* () {
@@ -66,17 +76,31 @@ const incomplete = { complete: !1, awaiting: [], facts: {} }, observe = (loop, s
     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) }),
+    plan: (info) => (scenario.planned?.(info.stepIndex) ?? Effect.void).pipe(Effect.as({
+      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,
+    onMediaRejected: scenario.onMediaRejected ?? (() => Effect.succeed(!1)),
     completion: (info) => scenario.completion?.(info.stepIndex, tasks) ?? Effect.succeed(incomplete),
     steering: Effect.succeed(Option.none()),
     correctives: Option.none(),
     events,
     tasks,
-    cacheKey: Option.none()
+    cacheKey: Option.none(),
+    captureTraceContent: scenario.captureTraceContent ?? !1
+  };
+  return {
+    result: yield* loop.run(request).pipe(Effect.provideService(CurrentTraceContent, scenario.ambientTraceContent ?? !1)),
+    events: yield* Ref.get(seen),
+    providerCalls: yield* Ref.get(calls),
+    recorded: yield* Ref.get(recorded),
+    dispatches: yield* Ref.get(dispatches),
+    traceContent: yield* Ref.get(traceContent)
   };
-  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) => [
   {
@@ -154,6 +178,48 @@ export const stepLoopConformance = (loop) => [
       yield* expect("complete", providerCalls.length === 1 && result.outcome === "completed", `${providerCalls.length} provider calls, ${result.outcome}`);
     })
   },
+  {
+    name: "RunResult.usage is the sum of the run's assistant.message usage, cache writes and reasoning included",
+    run: Effect.gen(function* () {
+      const { events, result } = yield* observe(loop, { script: [withUsage(probeCall("c1", 1), billed(100, 10)), withUsage(textReply("done"), billed(140, 20))] }), published = events.flatMap((event) => event._tag === "assistant.message" ? [event.usage] : []), total = sumUsage(published);
+      yield* expect("usage", published.length === 2 && sameUsage(result.usage, total), `the run reported ${JSON.stringify(result.usage)}, its ${published.length} assistant messages ${JSON.stringify(total)}`);
+      yield* expect("usage", total.inputTokens === 240 && total.cacheReadTokens === 40 && total.cacheWriteTokens === 20 && total.outputTokens === 30 && total.reasoningTokens === 6 && total.totalTokens === 270, `the assistant messages did not carry the provider's usage: ${JSON.stringify(total)}`);
+    })
+  },
+  {
+    name: "provides the request's captureTraceContent to its model calls as CurrentTraceContent, whatever the caller's",
+    run: Effect.gen(function* () {
+      const script = [probeCall("c1", 1), textReply("done")], on = yield* observe(loop, { script, captureTraceContent: !0, ambientTraceContent: !1 }), off = yield* observe(loop, { script, captureTraceContent: !1, ambientTraceContent: !0 });
+      yield* expect("trace-content", on.traceContent.length === 2 && on.traceContent.every((capture) => capture), `with captureTraceContent on under a caller's off, the model calls read ${JSON.stringify(on.traceContent)}`);
+      yield* expect("trace-content", off.traceContent.length === 2 && off.traceContent.every((capture) => !capture), `with captureTraceContent off under a caller's on, the model calls read ${JSON.stringify(off.traceContent)}`);
+    })
+  },
+  {
+    name: "a request refused over an image is planned again and sent once more when onMediaRejected answers true",
+    run: Effect.gen(function* () {
+      const reasons = yield* Ref.make([]), plans = yield* Ref.make([]), { dispatches, providerCalls, result } = yield* observe(loop, {
+        script: [],
+        refuseFirst: !0,
+        onMediaRejected: (reason) => Ref.update(reasons, (all) => [...all, reason]).pipe(Effect.as(!0)),
+        planned: (step) => Ref.update(plans, (all) => [...all, step])
+      }), asked = yield* Ref.get(reasons), planned = (yield* Ref.get(plans)).filter((step) => step === 0).length;
+      yield* expect("media-rejected", asked.length === 1 && asked.every((reason) => /image/i.test(reason)), `onMediaRejected was asked ${JSON.stringify(asked)}`);
+      yield* expect("media-rejected", planned === 2, `step 0 was planned ${planned} times, not twice`);
+      yield* expect("media-rejected", dispatches.join() === "0,0" && providerCalls.length === 2 && result.outcome === "completed", `dispatches ${dispatches.join()}, ${providerCalls.length} provider calls, ${result.outcome}`);
+    })
+  },
+  {
+    name: "a request refused over an image fails the step when onMediaRejected answers false",
+    run: Effect.gen(function* () {
+      const asked = yield* Ref.make(0), calls = yield* Ref.make(0), result = yield* Effect.result(observe(loop, {
+        script: [],
+        refuseFirst: !0,
+        providerCall: Ref.update(calls, (count) => count + 1),
+        onMediaRejected: () => Ref.update(asked, (count) => count + 1).pipe(Effect.as(!1))
+      })), [rejections, sent] = [yield* Ref.get(asked), yield* Ref.get(calls)];
+      yield* expect("media-rejected", result._tag === "Failure" && rejections === 1 && sent === 1, `${result._tag} after ${sent} provider calls, onMediaRejected asked ${rejections} times`);
+    })
+  },
   {
     name: "the step cap ends the run as partial",
     run: Effect.gen(function* () {

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

@@ -0,0 +1,38 @@
+import { Context, Effect } from "effect";
+import type { Scope } from "effect";
+import type { ConformanceCheck } from "../conformance.entity.js";
+import type { Capability } from "../ports/capability.port.js";
+import { ToolRegistry } from "../ports/tool-registry.port.js";
+type Registry = Context.Service.Shape<typeof ToolRegistry>;
+/** What the kit asks of the registry it builds: the most calls a turn may make. */
+export interface ToolRegistryLimits {
+    readonly maxCallsPerRun: number;
+}
+/**
+ * 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; 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;
+ * 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.
+ * The registry publishes these events on the run's bus (`RunContext.events`)
+ * only, and never writes the journal itself: the turn journals them (core'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 core's
+ * `TurnLive` with a writer that keeps the turn's events in memory.
+ */
+export declare const toolRegistryConformance: (make: (capabilities: ReadonlyArray<Capability>, limits: ToolRegistryLimits) => Effect.Effect<Registry, unknown, Scope.Scope>) => ReadonlyArray<ConformanceCheck>;
+export {};