@xandreed/core 0.13.0 → 0.14.0

package/dist/turn/turn-event.entity.js

@@ -3,6 +3,7 @@ import { DecisionRecord } from "../decision-record.entity.js";
 import { ToolCallId } from "../domain/message.entity.js";
 import { TokenUsage } from "../domain/token-usage.entity.js";
 import { ActivationSource, EntryId } from "../memory/memory-log.entity.js";
+import { JsonObject } from "../session/session-log.entity.js";
 import { UserMessage } from "./user-message.entity.js";
 const Labels = Schema.Record(Schema.String, Schema.String), Data = Schema.Record(Schema.String, Schema.Unknown);
 export const CompletionVerdict = Schema.Struct({
@@ -12,11 +13,17 @@ export const CompletionVerdict = Schema.Struct({
 }), TurnStartedEvent = Schema.TaggedStruct("turn.started", {
   runId: Schema.String,
   turn: Schema.Int,
-  userMessage: UserMessage
+  userMessage: UserMessage,
+  meta: JsonObject,
+  resumes: Schema.optionalKey(Schema.Int)
+}).annotate({
+  description: "Published once per turn when memory takes the user's message as turn `turn` (`TurnMemory.persistMessage`; `Agent.turn` runs it before the host's `use`). `runId` names the run, `userMessage` is what the user said (as the session stored it: its images, inline as base64, normalised), `meta` is the host's metadata the turn was begun with (`{}` when none was given; never shown to the model), and `resumes`, present only on a turn that resumes an earlier one, is that turn's number. Not journaled from the bus: the session stored its own `turn.started` when the turn began, with `meta` and `resumes` only when they were given. A subscription made in `use` never sees it; one in the host's per-turn layer or a session plugin does."
 }), StepStartedEvent = Schema.TaggedStruct("step.started", {
   step: Schema.Int,
   planned: Schema.Boolean,
   activeTools: Schema.Array(Schema.String)
+}).annotate({
+  description: "Published by the step loop as each step starts. `planned` is true for step 0 of a host-planned batch, which makes no provider call; `activeTools` are the tool names the step offers the model. Journaled as `step.started`."
 }), ToolStartedEvent = Schema.TaggedStruct("tool.started", {
   step: Schema.Int,
   invocationId: Schema.String,
@@ -24,6 +31,17 @@ export const CompletionVerdict = Schema.Struct({
   input: Schema.Unknown,
   labels: Labels,
   stage: Schema.OptionFromNullOr(Schema.String)
+}).annotate({
+  description: "Published by the tool registry just before a tool's handler runs. `invocationId` (`<runId>:call:<n>`) pairs it with its `tool.progress` and `tool.completed`; `input` is the decoded parameters; `labels` and `stage` come from the tool's annotations. A refused call (inactive, forbidden, denied, over a limit) publishes `tool.refused` instead, and no other `tool.*` event; `step.ended.results` lists every recorded result, refused calls included. Journaled as `tool.started`, input included."
+}), ToolRefusalReason = Schema.Literals(["inactive", "forbidden", "denied", "call-limit", "tool-call-limit"]), ToolRefusedEvent = Schema.TaggedStruct("tool.refused", {
+  step: Schema.Int,
+  invocationId: Schema.String,
+  tool: Schema.String,
+  input: Schema.Unknown,
+  reason: ToolRefusalReason,
+  message: Schema.String
+}).annotate({
+  description: "Published by the tool registry when it refuses a call before the handler runs, in place of `tool.started`: the tool is not active (`inactive`: not loaded, or not available in this conversation), the turn lacks a permission it needs (`forbidden`), the host's `ActionPolicy` denied it (`denied`), the turn's call limit is reached (`call-limit`) or the tool's own (`tool-call-limit`). `invocationId` is minted for the call as for any other (the refused call takes its `<runId>:call:<n>`); `message` is what the model receives as the call's failed result, which `step.ended.results` lists as not ok. The model is offered only active tools, so `inactive` comes from a call made through the handlers directly (a host's, another tool's); `forbidden` also from a tool an earlier turn activated whose permission this turn lacks. Journaled as `tool.refused` without `input`."
 }), ToolCompletedEvent = Schema.TaggedStruct("tool.completed", {
   step: Schema.Int,
   invocationId: Schema.String,
@@ -35,6 +53,16 @@ export const CompletionVerdict = Schema.Struct({
   durationMs: Schema.Number,
   labels: Labels,
   stage: Schema.OptionFromNullOr(Schema.String)
+}).annotate({
+  description: "Published by the tool registry when a handler returned or failed (`ok`). `result` is the decoded value, `encoded` its wire form as the model receives it. `durationMs` runs from just after `tool.started` to the handler's exit, so it includes any wait for the tool's read or write lane. Journaled as `tool.completed` without `input`, `result` and `encoded`: memory keeps the call and its result (`memory.message`, `memory.tool-result`)."
+}), ToolProgressEvent = Schema.TaggedStruct("tool.progress", {
+  step: Schema.Int,
+  invocationId: Schema.String,
+  tool: Schema.String,
+  channel: Schema.Literals(["stdout", "stderr", "status"]),
+  text: Schema.String
+}).annotate({
+  description: "Published by `publishToolProgress` from inside a tool handler, between that call's `tool.started` and `tool.completed` (same `step`, `invocationId` and `tool`). `channel` is stdout or stderr for a command's output as it arrives, status for anything else the tool reports; `text` is that output or message. Transient: never journaled; `tool.completed` carries the result."
 }), StepResult = Schema.Struct({
   entry: EntryId,
   toolCallId: ToolCallId,
@@ -44,13 +72,19 @@ export const CompletionVerdict = Schema.Struct({
   step: Schema.Int,
   status: Schema.Literals(["completed", "failed", "cancelled"]),
   results: Schema.Array(StepResult)
+}).annotate({
+  description: "Published by the step loop after the step's tail is recorded. `status` is completed, failed or cancelled; `results` are the step's recorded tool results (memory entry, tool call id, tool, ok), in log order, refused calls included. Journaled as `step.ended`."
 }), CompletionEvaluatedEvent = Schema.TaggedStruct("completion.evaluated", {
   step: Schema.Int,
   verdict: CompletionVerdict
+}).annotate({
+  description: "Published by the step loop after `step.ended`, with the verdict of the host's completion policy for that step. A verdict that awaits tasks is evaluated again once they finish, publishing a second event. Journaled as `completion.evaluated`."
 }), SkillsActivatedEvent = Schema.TaggedStruct("skills.activated", {
   skills: Schema.Array(Schema.String),
   tools: Schema.Array(Schema.String),
   source: ActivationSource
+}).annotate({
+  description: "Published by the tool registry when skills (and their tools) become active: always-on skills, the intent matcher, the model's `load_skill`, or the host. Not journaled from the bus: memory records the activation as `memory.skills`."
 }), ContextBuiltEvent = Schema.TaggedStruct("context.built", {
   step: Schema.Int,
   turn: Schema.Int,
@@ -60,10 +94,15 @@ export const CompletionVerdict = Schema.Struct({
   systemFingerprint: Schema.String,
   estimatedTokens: Schema.Int,
   reservedTokens: Schema.Int,
+  budgetTokens: Schema.Int,
   compactions: Schema.Int,
   activeTools: Schema.Array(Schema.String)
+}).annotate({
+  description: "Published before each provider call, once the step's context is built (none for a planned step 0). It carries the memory strategy and its version, the context and system-prompt fingerprints, the token estimate of the messages, the tokens reserved for the system prompt and tool schemas, the run's `budgetTokens` (the whole request's; memory compacted the messages toward `budgetTokens - reservedTokens`), how many compactions the build applied, and the active tools. Journaled as `context.built` (records written before 0.14.0 have no `budgetTokens`); the full request is journaled beside it as `request.prepared`."
 }), DecisionRecordedEvent = Schema.TaggedStruct("decision.recorded", {
   record: DecisionRecord
+}).annotate({
+  description: "Published by `recordDecision`, for example when `turn.tools.select` or `apply` records the skill selection: the decision record holds the candidates, the policy version and what was chosen. Journaled as `decision.recorded`."
 }), AssistantMessageEvent = Schema.TaggedStruct("assistant.message", {
   step: Schema.Int,
   text: Schema.String,
@@ -71,23 +110,39 @@ export const CompletionVerdict = Schema.Struct({
   model: Schema.OptionFromNullOr(Schema.String),
   toolCalls: Schema.Array(Schema.Struct({ id: Schema.String, tool: Schema.String, input: Schema.Unknown })),
   usage: TokenUsage
+}).annotate({
+  description: "Published by the step loop once per provider response, after that step's tools ran and its tail is recorded: the text, the reasoning, the model, the tool calls and the token usage (input with its cache reads and writes inside, output with its reasoning inside). A host-planned step 0 carries zero usage. Journaled only as `step.usage` (step, model, usage): the content itself is memory's `memory.message`."
 }), AssistantDeltaEvent = Schema.TaggedStruct("assistant.delta", {
   step: Schema.Int,
   channel: Schema.Literals(["text", "reasoning", "tool-params"]),
   id: Schema.String,
   delta: Schema.String
+}).annotate({
+  description: "Published by the step loop for each streamed increment while `limits.streaming` is on (the default), on channel text, reasoning or tool-params; `id` groups the increments of one content part. Transient: never journaled, and restated in full by `assistant.message`. A stream that falls back to a non-streamed call (`stream.fallback`) publishes none."
+}), StreamFallbackEvent = Schema.TaggedStruct("stream.fallback", {
+  step: Schema.Int,
+  message: Schema.String
+}).annotate({
+  description: "Published by the step loop when a streamed provider call fails before its first part: the step is answered by a non-streamed call instead, and so is every later step of the run. Once per run at most. `message` is the stream's error as text, cut to 300 characters; it can quote the provider's error. A stream that fails after its first part fails the step instead (its tools may have run). A refusal over an image (an `InvalidRequestError` that names one) is no stream failure: it has no fallback; the turn omits the images and sends the step again (`StepRequest.onMediaRejected`), or the step fails. Journaled as `stream.fallback`."
 }), TurnEndedEvent = Schema.TaggedStruct("turn.ended", {
   runId: Schema.String,
   turn: Schema.Int,
   outcome: Schema.Literals(["completed", "partial", "failed"]),
-  reply: Schema.OptionFromNullOr(Schema.String)
+  reply: Schema.OptionFromNullOr(Schema.String),
+  usage: TokenUsage
+}).annotate({
+  description: "Published once when the turn's reply is recorded (`TurnMemory.persistReply`, from `guardTurn`), also when the turn fails, with outcome failed; `usage` is the turn's usage, the usage of its `assistant.message` events summed (`RunContext.usage`). Under `Agent.turn` it is published after `use`, the host's per-turn layer and the turn-dependent plugins have closed, and their subscriptions with them: only a subscription whose scope is still open sees it, such as one made with `Scope.provide(observerScope)` over the caller's outer scope, or one registered around `TurnLive` by a host composing the turn itself. Otherwise read the `TurnResult` `Agent.turn` returns (its `usage` is the same total), or the stored `turn.reply` and `turn.ended`, and `turnUsageOf` over the stored events. Not journaled from the bus: memory stores `turn.reply` and the session its own `turn.ended` (reason and failure, no usage)."
 }), HostEvent = Schema.TaggedStruct("host", {
   name: Schema.Trimmed.check(Schema.isNonEmpty()),
   data: Data
+}).annotate({
+  description: "An application's own event (`defineHostEvent`), published by the host's code, tools or tasks. `name` is the host's namespace and `data` the payload as its schema encodes it. Journaled under `name` as its kind; a name in `RESERVED_KINDS` fails the publish with `events.reserved`."
 }), TurnEvent = Schema.Union([
   TurnStartedEvent,
   StepStartedEvent,
   ToolStartedEvent,
+  ToolRefusedEvent,
+  ToolProgressEvent,
   ToolCompletedEvent,
   StepEndedEvent,
   CompletionEvaluatedEvent,
@@ -96,6 +151,24 @@ export const CompletionVerdict = Schema.Struct({
   DecisionRecordedEvent,
   AssistantMessageEvent,
   AssistantDeltaEvent,
+  StreamFallbackEvent,
   TurnEndedEvent,
   HostEvent
-]), TransientTurnEvents = ["assistant.delta"];
+]), TransientTurnEvents = ["assistant.delta", "tool.progress"], TURN_EVENT_NAMES = [
+  "turn.started",
+  "step.started",
+  "tool.started",
+  "tool.refused",
+  "tool.progress",
+  "tool.completed",
+  "step.ended",
+  "completion.evaluated",
+  "skills.activated",
+  "context.built",
+  "decision.recorded",
+  "assistant.message",
+  "assistant.delta",
+  "stream.fallback",
+  "turn.ended",
+  "host"
+];

package/dist/turn/turn-event.entity.test.d.ts

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

package/dist/turn/turn-lifecycle.d.ts

@@ -1,12 +1,13 @@
 import { Effect } from "effect";
 import type { HarnessError } from "../harness/plugin.entity.js";
 import { RunContext } from "../ports/run-context.port.js";
+import type { TurnWriter } from "../ports/sessions.port.js";
 import type { StepLoop } from "../ports/step-loop.port.js";
 import type { RunTools } from "../ports/tool-registry.port.js";
 import { TurnEvents, TurnTasks } from "../ports/turn-events.port.js";
 import { TurnMemory, TurnToolbox } from "../ports/turn-scope.port.js";
 import type { TurnRunOptions } from "../ports/turn-scope.port.js";
-import type { Turn, TurnOutcome, TurnTools } from "../ports/turn.port.js";
+import type { Turn, TurnOutcome, TurnResult, TurnTools } from "../ports/turn.port.js";
 import type { TurnRunServices } from "./turn-run.js";
 /** Open the turn's tools (once). Their handlers run with the services of where this runs: open them inside the host's layer. */
 export declare const openTurnTools: Effect.Effect<RunTools, HarnessError, TurnToolbox>;
@@ -18,15 +19,52 @@ export declare const settleTurn: Effect.Effect<void, HarnessError, TurnEvents |
 export declare const finishTurn: (outcome: TurnOutcome) => Effect.Effect<void, HarnessError, TurnMemory | TurnEvents | RunContext>;
 /**
  * Run a turn's body to its end: once it succeeds, the turn settles (tasks
- * and background reactions) and finishes with its outcome. When it fails
- * or is interrupted, the turn finishes as failed and keeps the body's
- * cause. A HarnessError carried as a defect (a subscriber's failure behind
- * a `never` error channel) fails the turn, typed.
+ * and background reactions) and finishes with its outcome, returned with
+ * the turn's usage (`RunContext.usage`, the same total `turn.ended`
+ * carries). When it fails or is interrupted, the turn finishes as failed
+ * and keeps the body's cause, and the usage its provider calls spent so far
+ * goes on the current span as `efferent.usage.*_tokens` (the turn's
+ * `agent.turn` when `guardTurn` runs under `traceTurn` with no span between,
+ * as in `Agent.turn`; `traceTurn` records it itself when the turn returns).
+ * A HarnessError carried as a defect (a subscriber's failure behind a
+ * `never` error channel) fails the turn, typed.
  */
-export declare const guardTurn: <E, R>(body: Effect.Effect<TurnOutcome, E, R>) => Effect.Effect<TurnOutcome, E | HarnessError, R | TurnMemory | TurnEvents | TurnTasks | RunContext>;
+export declare const guardTurn: <E, R>(body: Effect.Effect<TurnOutcome, E, R>) => Effect.Effect<TurnResult, E | HarnessError, R | TurnMemory | TurnEvents | TurnTasks | RunContext>;
 /**
  * The `Turn` a host's code works with, over the turn's services (the one
- * `Agent.turn` hands to `use`): its `run` is `runTurnLoop` with `options`.
- * The message must be persisted and the tools open.
+ * `Agent.turn` hands to `use`): its `run` is `runTurnLoop` with `options`,
+ * its spans under the span current where `run` is called. The message must
+ * be persisted and the tools open.
  */
 export declare const turnOf: (options?: TurnRunOptions) => Effect.Effect<Turn, HarnessError, TurnRunServices | RunContext | StepLoop>;
+/** What a turn's span (`traceTurn`) shows besides the turn's ids. */
+export interface TurnTraceOptions {
+    /**
+     * The keys of the turn's metadata (`AdmittedTurn.meta`) whose values the
+     * span carries, as `efferent.meta.<key>`: none by default, since metadata
+     * may hold what a trace backend should not (a user, a tenant). A string,
+     * number or boolean is kept as it is, anything else as its JSON; a key the
+     * turn's metadata lacks is left out.
+     */
+    readonly spanMeta?: ReadonlyArray<string>;
+}
+/**
+ * Run a turn under its span, `agent.turn`, the root of everything the turn
+ * does (under the caller's span, if any). It starts once the turn is
+ * admitted (`writer`), with `efferent.session.id`, `efferent.run.id`,
+ * `efferent.turn`, `gen_ai.conversation.id` (the session), `efferent.origin`,
+ * `efferent.resumes` (on a resume) and `options.spanMeta`'s
+ * `efferent.meta.<key>`; every span under it
+ * carries the first three too. It ends with `efferent.outcome` (the
+ * `TurnEnding` reason of the turn's exit: completed, partial, failed or
+ * interrupted; a turn cancelled or reaped while it ran shows as failed with
+ * `turn.closed`), `efferent.failure.code` when the turn failed or was
+ * interrupted, and the turn's usage
+ * (`efferent.usage.{input,output,cache_read,cache_write,reasoning,total}_tokens`):
+ * when it returned, from its result; when it failed, what `guardTurn`
+ * records, so `guardTurn` runs under this span with no span between.
+ * `Agent.turn` encloses everything after `Sessions.begin`
+ * in it: the turn-dependent plugins, the host's layer, the tools opened, `use`,
+ * the reply and the end; a host composing its own turn wraps the same.
+ */
+export declare const traceTurn: (writer: TurnWriter, options?: TurnTraceOptions) => <E, R>(effect: Effect.Effect<TurnResult, E, R>) => Effect.Effect<TurnResult, E, R>;

package/dist/turn/turn-lifecycle.js

@@ -1,7 +1,9 @@
 import { Effect, Exit, Option } from "effect";
+import { replayableContext } from "../loop/traceContent.js";
 import { RunContext } from "../ports/run-context.port.js";
 import { TurnEvents, TurnTasks } from "../ports/turn-events.port.js";
 import { TurnMemory, TurnToolbox } from "../ports/turn-scope.port.js";
+import { turnEndingOf } from "../session/sessions.entity.functions.js";
 import { harnessDefectsAsFailures } from "./turn-bus.js";
 import { runTurnLoop } from "./turn-run.js";
 const failed = { outcome: "failed", reply: Option.none() };
@@ -27,14 +29,15 @@ export const openTurnTools = TurnToolbox.pipe(Effect.flatMap((toolbox) => toolbo
   yield* (yield* RunContext).flush;
 }), guardTurn = (body) => harnessDefectsAsFailures(body.pipe(Effect.tap(() => settleTurn))).pipe(Effect.onExit(Exit.match({
   onSuccess: () => Effect.void,
-  onFailure: () => finishTurn(failed).pipe(Effect.catchCause(() => Effect.void))
-})), Effect.tap(finishTurn)), turnOf = (options = {}) => Effect.gen(function* () {
-  const services = yield* Effect.context(), run = yield* RunContext, memory = yield* TurnMemory;
+  onFailure: () => finishTurn(failed).pipe(Effect.catchCause(() => Effect.void), Effect.andThen(RunContext.pipe(Effect.flatMap((run) => run.usage), Effect.flatMap((usage) => Effect.annotateCurrentSpan(turnUsageAttributes(usage))))))
+})), Effect.tap(finishTurn), Effect.flatMap((outcome) => RunContext.pipe(Effect.flatMap((run) => run.usage), Effect.map((usage) => ({ outcome: outcome.outcome, reply: outcome.reply, usage }))))), turnOf = (options = {}) => Effect.gen(function* () {
+  const services = replayableContext(yield* Effect.context()), run = yield* RunContext, memory = yield* TurnMemory;
   return {
     conversation: run.conversation,
     runId: run.runId,
     turn: yield* memory.number,
     userMessage: run.userMessage,
+    admitted: run.admitted,
     memory: run.memory,
     events: run.events,
     tasks: run.tasks,
@@ -42,7 +45,34 @@ export const openTurnTools = TurnToolbox.pipe(Effect.flatMap((toolbox) => toolbo
     context: memory.context,
     reply: (text) => Effect.succeed({ outcome: "completed", reply: Option.some(text) }),
     run: (policy) => runTurnLoop(policy, options).pipe(Effect.provide(services)),
+    usage: run.usage,
     flush: run.flush,
     write: run.write
   };
 });
+const turnIds = (admitted) => ({
+  "efferent.session.id": admitted.session.id,
+  "efferent.run.id": admitted.runId,
+  "efferent.turn": admitted.turn
+}), metaAttribute = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value), turnSpanAttributes = (admitted, spanMeta) => ({
+  ...turnIds(admitted),
+  "gen_ai.conversation.id": admitted.session.id,
+  "efferent.origin": admitted.origin,
+  ...admitted.resumes === void 0 ? {} : { "efferent.resumes": admitted.resumes },
+  ...Object.fromEntries(spanMeta.filter((key) => Object.hasOwn(admitted.meta, key)).map((key) => [`efferent.meta.${key}`, metaAttribute(admitted.meta[key])]))
+}), turnUsageAttributes = (usage) => ({
+  "efferent.usage.input_tokens": usage.inputTokens,
+  "efferent.usage.output_tokens": usage.outputTokens,
+  "efferent.usage.cache_read_tokens": usage.cacheReadTokens,
+  "efferent.usage.cache_write_tokens": usage.cacheWriteTokens,
+  "efferent.usage.reasoning_tokens": usage.reasoningTokens,
+  "efferent.usage.total_tokens": usage.totalTokens
+}), turnEndAttributes = (exit) => {
+  const ending = turnEndingOf(exit);
+  return {
+    "efferent.outcome": ending.reason,
+    ...Option.match(ending.failure, { onNone: () => ({}), onSome: (failure) => ({ "efferent.failure.code": failure.code }) }),
+    ...Exit.match(exit, { onSuccess: (result) => turnUsageAttributes(result.usage), onFailure: () => ({}) })
+  };
+};
+export const traceTurn = (writer, options = {}) => (effect) => effect.pipe(Effect.onExit((exit) => Effect.annotateCurrentSpan(turnEndAttributes(exit))), Effect.annotateSpans(turnIds(writer.admitted)), Effect.withSpan("agent.turn", { attributes: turnSpanAttributes(writer.admitted, options.spanMeta ?? []) }));

package/dist/turn/turn-lifecycle.test.d.ts

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

package/dist/turn/turn-run.d.ts

@@ -15,11 +15,23 @@ export declare const schemaTokens: (tools: RunTools, active: ReadonlyArray<strin
 export declare const cacheKeyOf: (prefix: string, conversation: string) => Option.Option<string>;
 /**
  * Prepare one run of the step loop over the turn's services, in this
- * order: the policy's planned skills are activated, the turn-tier sections
- * are recorded, and memory is maintained for the turn's start. Everything
+ * order: the run's budget is checked (`turn.budget` unless it is an integer
+ * of at least 1), the policy's planned skills are activated, the turn-tier
+ * sections are recorded, and memory is maintained for the turn's start
+ * with the whole budget. Each step gives memory what the system prompt and
+ * the active tools' schemas leave of the budget, and fails with
+ * `context.budget` when they leave nothing. Everything
  * where this runs (the policy's services, the turn's, a host layer's) is
  * captured: the policy callbacks, the prompt sections and the tool handlers
- * run with it.
+ * run with it, without the span current here (`replayableContext`), so
+ * their spans nest under the step that calls them. Trace content is the
+ * policy's `captureTraceContent`, else the options', else
+ * `CurrentTraceContent` here. When a provider refuses a step's request over
+ * an image, `onMediaRejected` records an `OmitMedia` of the images that
+ * build sent, and the step's next plan, that one only, rebuilds the context
+ * with the same model choice, system prompt, directive and resolved model
+ * (no second `policy.model` or `policy.step` call, no second
+ * `StepContext`). Any other plan of a step calls the policy again.
  */
 export declare const stepRequestOf: <P>(policy: TurnPolicy<P>, options?: TurnRunOptions) => Effect.Effect<StepRequest, HarnessError, P | TurnRunServices>;
 /** One run of the turn: `stepRequestOf`, then the StepLoop. */

package/dist/turn/turn-run.js

@@ -1,12 +1,14 @@
-import { Context, Effect, Option } from "effect";
+import { Context, Effect, Option, Ref } from "effect";
 import { LanguageModel } from "effect/ai";
 import { toolParametersSchema } from "../loop/toolSchema.js";
+import { isBudgetTokens } from "../domain/token-usage.entity.functions.js";
 import { HarnessError } from "../harness/plugin.entity.js";
-import { canonicalJson, estimateTokens, fingerprintOf } from "../memory/memory-log.entity.functions.js";
+import { canonicalJson, entriesSendingMedia, estimateTokens, fingerprintOf } from "../memory/memory-log.entity.functions.js";
 import { StepLoop } from "../ports/step-loop.port.js";
 import { TurnEvents, TurnTasks } from "../ports/turn-events.port.js";
 import { TurnMemory, TurnPrompt, TurnToolbox } from "../ports/turn-scope.port.js";
 import { CurrentModelCallPolicy } from "../loop/modelPolicy.js";
+import { CurrentTraceContent, replayableContext } from "../loop/traceContent.js";
 import {
   checkModelRequest,
   modelRequestDescriptorOf,
@@ -15,26 +17,33 @@ import {
   reconstructModelRequest,
   resolveModelRequest
 } from "./model-request.entity.functions.js";
-const defaultLimits = { maxSteps: 50, toolConcurrency: 1, streaming: !0, requireCompletion: !1 }, defaultBudgetTokens = 64000, incomplete = { complete: !1, awaiting: [], facts: {} }, noDirective = { context: Option.none(), toolChoice: Option.none() };
+const MEDIA_REJECTION_CHARS = 500, defaultLimits = { maxSteps: 50, toolConcurrency: 1, streaming: !0, requireCompletion: !1 }, defaultBudgetTokens = 64000, incomplete = { complete: !1, awaiting: [], facts: {} }, noDirective = { context: Option.none(), toolChoice: Option.none() }, failure = (code, message) => new HarnessError({ code, message });
 export const schemaTokens = (tools, active) => active.reduce((sum, name) => {
   const tool = tools.toolkit.tools[name];
   return tool === void 0 ? sum : sum + estimateTokens(`${tool.description ?? ""}${canonicalJson(toolParametersSchema(tool))}`);
 }, 0), cacheKeyOf = (prefix, conversation) => Option.map(Option.filter(Option.some(prefix), (value) => value.length > 0), (value) => `${value}:${conversation}`), stepRequestOf = (policy, options = {}) => Effect.gen(function* () {
-  const runServices = yield* Effect.context(), inRun = (effect) => effect.pipe(Effect.provide(runServices)), memory = yield* TurnMemory, prompt = yield* TurnPrompt, events = yield* TurnEvents, tasks = yield* TurnTasks, tools = yield* (yield* TurnToolbox).tools, session = memory.session, runId = (yield* session.renderRecipe("none")).currentRun, defaultModel = Context.getOption(runServices, LanguageModel.LanguageModel), number = yield* memory.number, limits = { ...defaultLimits, ...options.limits, ...policy.limits }, budget = policy.budgetTokens ?? options.budgetTokens ?? defaultBudgetTokens, stepContext = policy.stepContext ?? "tail";
+  const runServices = replayableContext(yield* Effect.context()), inRun = (effect) => effect.pipe(Effect.provide(runServices)), memory = yield* TurnMemory, prompt = yield* TurnPrompt, events = yield* TurnEvents, tasks = yield* TurnTasks, tools = yield* (yield* TurnToolbox).tools, session = memory.session, runId = (yield* session.renderRecipe("none")).currentRun, defaultModel = Context.getOption(runServices, LanguageModel.LanguageModel), number = yield* memory.number, limits = { ...defaultLimits, ...options.limits, ...policy.limits }, budget = policy.budgetTokens ?? options.budgetTokens ?? defaultBudgetTokens;
+  if (!isBudgetTokens(budget))
+    return yield* Effect.fail(failure("turn.budget", `budgetTokens must be an integer of at least 1, not ${budget}`));
+  const stepContext = policy.stepContext ?? "tail";
   yield* Option.match(Option.fromNullishOr(policy.initial), {
     onNone: () => Effect.void,
     onSome: (batch) => batch.skills.length === 0 ? Effect.void : tools.activate(batch.skills, "host").pipe(Effect.asVoid)
   });
   yield* inRun(prompt.turnSections);
   yield* session.maintain({ phase: "turn-start", lastUsage: Option.none(), budgetTokens: budget, views: tools.views });
-  const plan = (info) => Effect.gen(function* () {
+  const planned = yield* Ref.make(Option.none()), replanning = yield* Ref.make(Option.none()), decide = (info) => Effect.gen(function* () {
     const choice = policy.model === void 0 ? Option.none() : yield* inRun(policy.model(info)), system = yield* inRun(prompt.system(Option.flatMap(choice, (value) => value.variant))), directive = policy.step === void 0 ? noDirective : yield* inRun(policy.step(info));
     yield* Option.match(directive.context, {
       onNone: () => Effect.void,
       onSome: (text) => session.record([{ _tag: "StepContext", step: info.stepIndex, text }], info.stepIndex).pipe(Effect.asVoid)
     });
-    const reserved = estimateTokens(system) + schemaTokens(tools, info.activeTools);
-    yield* session.maintain({ phase: "step", lastUsage: info.lastUsage, budgetTokens: Math.max(1, budget - reserved), views: tools.views });
+    return { choice, system, directive };
+  }), plan = (info) => Effect.gen(function* () {
+    const again = Option.filter(yield* Ref.getAndSet(replanning, Option.none()), (last) => last.step === info.stepIndex), { choice, system, directive } = Option.isSome(again) ? again.value.decision : yield* decide(info), reserved = estimateTokens(system) + schemaTokens(tools, info.activeTools);
+    if (budget <= reserved)
+      return yield* Effect.fail(failure("context.budget", `The system prompt and tool schemas take ${reserved} tokens, all of the ${budget}-token context budget: raise budgetTokens or offer fewer tools`));
+    yield* session.maintain({ phase: "step", lastUsage: info.lastUsage, budgetTokens: budget - reserved, views: tools.views });
     const built = yield* session.build({ stepContext: stepContext === "tail" ? "tail" : "none" }), render = yield* session.renderRecipe(stepContext === "tail" ? "tail" : "none");
     yield* events.publish({
       _tag: "context.built",
@@ -46,15 +55,17 @@ export const schemaTokens = (tools, active) => active.reduce((sum, name) => {
       systemFingerprint: fingerprintOf(system),
       estimatedTokens: built.estimatedTokens,
       reservedTokens: reserved,
+      budgetTokens: budget,
       compactions: built.compactions.length,
       activeTools: info.activeTools
     });
     const stepText = stepContext === "system" ? Option.getOrElse(directive.context, () => "") : "", finalSystem = [system, stepText].filter((part) => part.length > 0).join(`
 
-`), model = yield* Option.match(Option.orElse(Option.map(choice, (value) => value.model), () => defaultModel), {
+`), model = Option.isSome(again) ? again.value.model : yield* Option.match(Option.orElse(Option.map(choice, (value) => value.model), () => defaultModel), {
       onNone: () => Effect.succeed(Option.none()),
       onSome: (chosen) => resolveModelRequest(chosen).pipe(Effect.map(Option.some))
     });
+    yield* Ref.set(planned, Option.some({ step: info.stepIndex, decision: { choice, system, directive }, model, through: built.through, render }));
     yield* memory.prepareRequest({
       version: 1,
       runId,
@@ -95,11 +106,28 @@ export const schemaTokens = (tools, active) => active.reduce((sum, name) => {
       });
     }),
     record: (step, tail) => session.recordTail(tail, tools.views, step),
+    onMediaRejected: (reason) => Effect.gen(function* () {
+      const last = yield* Ref.get(planned);
+      if (Option.isNone(last))
+        return !1;
+      const entries = yield* session.entries, through = last.value.through, built = Option.isNone(through) ? [] : entries.slice(0, entries.findIndex((entry) => entry.id === through.value) + 1), sent = entriesSendingMedia(built, last.value.render);
+      if (sent.length === 0)
+        return !1;
+      yield* session.record([{
+        _tag: "Compaction",
+        strategy: session.strategy.id,
+        version: session.strategy.version,
+        action: { _tag: "OmitMedia", entries: sent, reason: reason.slice(0, MEDIA_REJECTION_CHARS) }
+      }], last.value.step);
+      yield* Ref.set(replanning, last);
+      return !0;
+    }),
     completion: (info) => policy.completion === void 0 ? Effect.succeed(incomplete) : inRun(policy.completion(info)),
     steering: options.steering ?? Effect.succeed(Option.none()),
     correctives: Option.fromNullishOr(policy.correctives),
     events,
     tasks,
-    cacheKey: options.cacheKey ?? Option.none()
+    cacheKey: options.cacheKey ?? Option.none(),
+    captureTraceContent: policy.captureTraceContent ?? options.captureTraceContent ?? (yield* Effect.service(CurrentTraceContent))
   };
 }), runTurnLoop = (policy, options = {}) => stepRequestOf(policy, options).pipe(Effect.flatMap((request) => StepLoop.pipe(Effect.flatMap((loop) => loop.run(request)))));

package/dist/turn/turn.adapter.d.ts

@@ -9,11 +9,12 @@ import type { TurnLiveInput } from "../ports/turn-scope.port.js";
 /**
  * One admitted turn's services, over the turn's writer, built in this order:
  * the event bus and the tasks, with the writer as the bus's FIRST
- * subscriber (every stored event is queued before any reaction runs); then
- * the memory session, opened over the session's earlier memory events where
- * this layer is built (a digester or summarizer there is used), and
- * RunContext. It also holds the tools slot (`TurnToolbox`) and the prompt
- * state (`TurnPrompt`). The message was stored when the turn began; memory
+ * subscriber (every stored event is queued before any reaction runs) and
+ * the turn's usage (`RunContext.usage`) as the second; then the memory
+ * session, opened over the session's earlier memory events where this
+ * layer is built (a digester or summarizer there is used), and RunContext.
+ * It also holds the tools slot (`TurnToolbox`) and the prompt state
+ * (`TurnPrompt`). The message was stored when the turn began; memory
  * takes it at `TurnMemory.persistMessage`, and records nothing before it
  * (`TurnMemory.context` waits for it). Tasks run in the layer's scope:
  * they are interrupted when it closes.

package/dist/turn/turn.adapter.js

@@ -1,4 +1,5 @@
 import { Context, Effect, Layer, Option, Ref, Schema, Scope, Semaphore } from "effect";
+import { addUsage, zeroUsage } from "../domain/token-usage.entity.functions.js";
 import { HarnessError } from "../harness/plugin.entity.js";
 import { fingerprintOf } from "../memory/memory-log.entity.functions.js";
 import { readerOf } from "../memory/memory-session.js";
@@ -17,6 +18,8 @@ const failure = (code, message) => new HarnessError({ code, message }), inCaller
 export const TurnLive = (input) => Layer.effectContext(Effect.gen(function* () {
   const scope = yield* Effect.scope, memory = yield* ConversationMemory, registry = yield* ToolRegistry, sections = Option.getOrElse(yield* Effect.serviceOption(Capabilities), () => []).flatMap((capability) => capability.promptSections), writer = input.turn, admitted = writer.admitted, events = yield* makeTurnEvents({ maxDepth: input.maxEventDepth ?? 8 }), tasks = yield* makeTurnTasks(scope);
   yield* events.subscribe(storedDraft(admitted.turn), (draft) => draft instanceof HarnessError ? Effect.fail(draft) : writer.append([draft]));
+  const usage = yield* Ref.make(zeroUsage);
+  yield* events.subscribe((event) => event._tag === "assistant.message" ? Option.some(event.usage) : Option.none(), (step) => Ref.update(usage, (total) => addUsage(total, step)));
   const message = yield* Ref.make({ _tag: "Waiting", early: [] }), history = yield* Ref.make(Option.none()), decoded = (stored) => entriesOfEvents(stored).pipe(Effect.mapError((error) => failure("memory.log", `undecodable memory events: ${error.message}`))), readHistory = writer.history(MEMORY_KINDS).pipe(Effect.flatMap(decoded)), log = {
     read: readHistory.pipe(Effect.tap((entries) => Ref.set(history, Option.some(entries)))),
     append: (entries) => Effect.gen(function* () {
@@ -36,12 +39,14 @@ export const TurnLive = (input) => Layer.effectContext(Effect.gen(function* () {
     session: admitted.session,
     runId: admitted.runId,
     userMessage: admitted.userMessage,
+    admitted,
     memory: reader,
     events,
     tasks,
     activate: (skills) => openTools.pipe(Effect.flatMap((tools) => tools.activate(skills, "host"))),
     flush: writer.flush,
-    write: writer.write
+    write: writer.write,
+    usage: Ref.get(usage)
   }), requestKinds = [...MEMORY_KINDS, "request.prepared"], snapshots = yield* Semaphore.make(1), snapshot = yield* Ref.make(Option.none()), requestSnapshot = snapshots.withPermits(1)(Effect.gen(function* () {
     const known = yield* Option.match(yield* Ref.get(snapshot), {
       onNone: () => Ref.get(history).pipe(Effect.flatMap(Option.match({ onNone: () => readHistory, onSome: Effect.succeed })), Effect.map((entries) => ({ entries, requests: [], cursor: writer.started.seq - 1 }))),
@@ -70,7 +75,14 @@ export const TurnLive = (input) => Layer.effectContext(Effect.gen(function* () {
       yield* session.record([{ _tag: "TurnStarted", userMessage: admitted.userMessage }], 0);
       const early = yield* Ref.modify(message, (state) => [state._tag === "Waiting" ? state.early : [], { _tag: "Taken", number }]);
       yield* early.length === 0 ? Effect.void : session.record(early.map(contextBody), 0);
-      yield* events.publish({ _tag: "turn.started", runId: admitted.runId, turn: number, userMessage: admitted.userMessage });
+      yield* events.publish({
+        _tag: "turn.started",
+        runId: admitted.runId,
+        turn: number,
+        userMessage: admitted.userMessage,
+        meta: admitted.meta,
+        ...admitted.resumes === void 0 ? {} : { resumes: admitted.resumes }
+      });
       return number;
     }),
     context: (entry) => Ref.modify(message, (state) => state._tag === "Waiting" ? [!1, { _tag: "Waiting", early: [...state.early, entry] }] : [!0, state]).pipe(Effect.flatMap((now) => now ? session.record([contextBody(entry)], 0).pipe(Effect.asVoid) : Effect.void)),
@@ -79,7 +91,7 @@ export const TurnLive = (input) => Layer.effectContext(Effect.gen(function* () {
       if (Option.isNone(number) || (yield* Ref.getAndSet(replied, !0)))
         return;
       yield* session.record([{ _tag: "TurnEnded", outcome: outcome.outcome, reply: outcome.reply }], 0);
-      yield* events.publish({ _tag: "turn.ended", runId: admitted.runId, turn: number.value, outcome: outcome.outcome, reply: outcome.reply });
+      yield* events.publish({ _tag: "turn.ended", runId: admitted.runId, turn: number.value, outcome: outcome.outcome, reply: outcome.reply, usage: yield* Ref.get(usage) });
     })
   }), opened = yield* Ref.make(!1), toolbox = TurnToolbox.of({
     open: Effect.gen(function* () {

package/dist/turn/turn.conformance.d.ts

@@ -9,12 +9,21 @@ import type { TurnRunner } from "../ports/turn.port.js";
  * the session's writer is the bus's first subscriber; the user's message
  * is in memory before the matcher reads the history; the reply is recorded
  * and the turn ended exactly once on success, failure and interrupt; tasks
- * are joined before the reply; and the host layer sees only earlier turns.
+ * are joined before the reply; a model-driven turn's `TurnResult.usage` is
+ * what its stored `step.usage` records sum to (`turnUsageOf`); the user's
+ * attachments reach the first request as image parts; and the host layer
+ * sees only earlier turns.
  *
  * `runner` is acquired afresh for each check. `services` are merged into
  * every turn's services (the model, the `Sessions` the turns begin with, and
  * whatever else the runner requires); each check makes its own session, and
  * the kit adds its own IntentMatcher, which the runner's tools must consult
- * (plugin-tool-discovery does).
+ * (plugin-tool-discovery does). The usage check runs the turn's loop twice
+ * with the kit's own model, which answers with text only, under a policy
+ * that completes after the first reply (`requireCompletion: false`, a
+ * complete verdict); its expected counts follow the calls the model answered.
+ * The attachments check runs the loop once with a model of its own that
+ * records each request; it needs the composition's memory to admit one small
+ * image (the memory plugins' defaults do; `maxMediaChars: 0` does not).
  */
 export declare const turnConformance: (runner: Effect.Effect<TurnRunner, HarnessError, Scope.Scope>, services?: Context.Context<never>) => ReadonlyArray<ConformanceCheck>;