@xandreed/core 0.13.0 → 0.14.0

package/dist/ports/turn.port.d.ts

@@ -1,5 +1,6 @@
 import type { Context, Effect, Layer, Option, Scope } from "effect";
 import type { ConversationId } from "../domain/message.entity.js";
+import type { TokenUsage } from "../domain/token-usage.entity.js";
 import type { SkillDefinition } from "../harness/capability.entity.js";
 import type { HarnessError } from "../harness/plugin.entity.js";
 import type { CompletionVerdict } from "../turn/turn-event.entity.js";
@@ -9,7 +10,7 @@ import type { MemoryReader } from "./memory.port.js";
 import type { RunContext } from "./run-context.port.js";
 import type { TurnWriter } from "./sessions.port.js";
 import type { JsonObject } from "../session/session-log.entity.js";
-import type { SessionAddress } from "../session/sessions.entity.js";
+import type { AdmittedTurn, SessionAddress } from "../session/sessions.entity.js";
 import type { Correctives, LoopLimits, RunResult } from "./step-loop.port.js";
 import type { SkillMatch } from "./tool-registry.port.js";
 import type { TurnEvents, TurnEventsService, TurnTasks, TurnTasksService } from "./turn-events.port.js";
@@ -25,17 +26,46 @@ export interface TurnPolicy<R = never> {
     /** Read-only by contract: react to events, decide here. */
     readonly completion?: (step: StepInfo) => Effect.Effect<CompletionVerdict, HarnessError, R>;
     readonly limits?: Partial<LoopLimits>;
-    /** Input tokens one request may use (system, tool schemas and messages). */
+    /**
+     * This run's token budget (an integer of at least 1, else the run fails
+     * with `turn.budget`): the target memory compaction keeps each request
+     * under, the system prompt, tool schemas and messages estimated together,
+     * not a provider limit. The memory strategy is given the whole budget at
+     * the turn's start, and at each step what the system prompt and tool
+     * schemas leave of it (`context.budget` when they leave nothing): the
+     * window strategy compacts, spills and drops older turns to fit the budget
+     * it is given (and fails with `context.budget` when the current turn alone
+     * does not), the summary strategy summarizes once the messages pass its
+     * `triggerRatio` of it and keeps its `keepRatio`, and the digester ignores
+     * it. Overrides the agent's `budgetTokens` (64 000 by default).
+     */
     readonly budgetTokens?: number;
     /** Where the step context goes: closing the messages, or appended to the system prompt. */
     readonly stepContext?: "tail" | "system";
     readonly correctives?: Correctives;
+    /**
+     * Whether this run's spans may carry prompt and response content
+     * (`engine.step.input`, `engine.step.output`, the models plugin's
+     * `llm.reasoning`). Overrides the agent's `captureTraceContent`; off by
+     * default. Hosts own consent, masking and exporter retention.
+     */
+    readonly captureTraceContent?: boolean;
 }
 export interface TurnOutcome {
     readonly outcome: "completed" | "partial" | "failed";
     /** The reply follow-up turns remember. */
     readonly reply: Option.Option<string>;
 }
+/**
+ * What a turn runner returns: the outcome `use` gave, and the turn's usage,
+ * the usage of its `assistant.message` events summed (the stored
+ * `step.usage` records of the turn sum to the same, see `turnUsageOf`).
+ * Calls outside the step loop (a memory digester's or summarizer's utility
+ * model) and responses that never decoded are not in it.
+ */
+export interface TurnResult extends TurnOutcome {
+    readonly usage: TokenUsage;
+}
 export interface TurnTools {
     /** Ask the matcher without writing anything (run it beside other pre-turn work). */
     readonly match: (userMessage: UserMessage) => Effect.Effect<SkillMatch, HarnessError>;
@@ -53,6 +83,8 @@ export interface Turn {
     readonly runId: string;
     readonly turn: number;
     readonly userMessage: UserMessage;
+    /** The admitted turn as the session began it, the host's `meta` included (`RunContext.admitted`). */
+    readonly admitted: AdmittedTurn;
     readonly memory: MemoryReader;
     readonly events: TurnEventsService;
     readonly tasks: TurnTasksService;
@@ -66,6 +98,8 @@ export interface Turn {
     /** Answer without the loop; still a recorded turn. */
     readonly reply: (text: string) => Effect.Effect<TurnOutcome>;
     readonly run: <R = never>(policy: TurnPolicy<R>) => Effect.Effect<RunResult, HarnessError, R>;
+    /** The turn's usage so far, every run of it included (`RunContext.usage`). */
+    readonly usage: Effect.Effect<TokenUsage>;
     /** Wait until every journal write queued so far is stored (e.g. before delivering an answer). */
     readonly flush: Effect.Effect<void, HarnessError>;
     /** Run a host store write in journal order and return its result. */
@@ -76,12 +110,34 @@ export type TurnServices = RunContext | TurnEvents | TurnTasks;
 /** A turn to begin: the session (through the `Sessions` in the turn's services), the message and the run. */
 export interface NewTurn {
     readonly session: SessionAddress;
+    /** The user's message; when resuming, what the model sees after the resumed turn's steps (its own message again, or "Continue."). */
     readonly userMessage: UserMessage;
     readonly runId: string;
-    /** The idempotency key; the run id by default. */
+    /** The idempotency key; `resume:<n>` when resuming turn `n`, the run id otherwise. */
     readonly key?: string;
     /** The host's input beside the message, part of the key's fingerprint. */
     readonly command?: JsonObject;
+    /**
+     * The host's metadata for the turn (a request id, a tenant…): stored in
+     * `turn.started`, shown on `RunContext.admitted`, `Turn.admitted` and the
+     * bus `turn.started`, and given to `TurnAdmission`. Not part of the key's
+     * fingerprint, and never shown to the model.
+     */
+    readonly meta?: JsonObject;
+    /**
+     * Resume turn `n`: the session's last turn begun by a user, which ended
+     * cancelled or interrupted (only inbox turns, and resumes of it that
+     * failed, were cancelled or were interrupted, may have run since);
+     * otherwise, or when `n` is not a whole number of at least 1, the turn
+     * fails to begin with `turn.not-resumable`. Memory is what a plain new
+     * turn would see: what turn `n` stored (its message and whole steps), then
+     * this turn's message. Stored in `turn.started`, shown on `admitted` and
+     * the bus `turn.started`, and part of the key's fingerprint. With the
+     * default key `resume:<n>`, a retry is `turn.duplicate` once the resuming
+     * turn has begun, however it ended: to try a resume that failed again,
+     * pass a new key.
+     */
+    readonly resumes?: number;
 }
 /**
  * One turn's input. `turn` is either a turn the host already began (its
@@ -92,7 +148,16 @@ export interface NewTurn {
  */
 export interface TurnInput<A = never, E = never> {
     readonly turn: TurnWriter | NewTurn;
-    /** This turn's services: the model, per-turn budgets, data ports… */
+    /**
+     * This turn's services: the model, per-turn budgets, data ports… They may
+     * be a captured context: `Agent.turn` provides them without their trace
+     * state (`replayableContext`), so a parent span or span annotations among
+     * them are ignored (the turn's spans nest under the span where
+     * `Agent.turn` is called; wrap that call in `Effect.withParentSpan` for
+     * another parent). A `CurrentTraceContent` among them is kept: it is
+     * where the turn's runs start, under the agent's and the policy's
+     * `captureTraceContent`.
+     */
     readonly services: Context.Context<never>;
     /** A system prompt prefix before the contributed sections. */
     readonly system?: string;
@@ -109,5 +174,5 @@ export interface TurnInput<A = never, E = never> {
  * `turnConformance`).
  */
 export interface TurnRunner {
-    readonly turn: <A = never, E = never, R = never>(input: TurnInput<A, E>, use: (turn: Turn) => Effect.Effect<TurnOutcome, HarnessError, R>) => Effect.Effect<TurnOutcome, HarnessError | E, Exclude<R, A | TurnServices | Scope.Scope>>;
+    readonly turn: <A = never, E = never, R = never>(input: TurnInput<A, E>, use: (turn: Turn) => Effect.Effect<TurnOutcome, HarnessError, R>) => Effect.Effect<TurnResult, HarnessError | E, Exclude<R, A | TurnServices | Scope.Scope>>;
 }

package/dist/ports/utility-llm.port.d.ts

@@ -12,6 +12,8 @@ declare const UtilityCompletion_base: Schema.Class<UtilityCompletion, Schema.Str
         readonly outputTokens: Schema.Number;
         readonly totalTokens: Schema.Number;
         readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
     }>;
 }>, {}>;
 export declare class UtilityCompletion extends UtilityCompletion_base {

package/dist/session/activity.entity.d.ts

@@ -0,0 +1,42 @@
+import { Schema } from "effect";
+/**
+ * A turn this process holds open: its session, its number, and since when
+ * (this process's Clock time, in milliseconds, when its begin was stored and
+ * its writer handed over).
+ */
+export declare const ActiveTurn: Schema.Struct<{
+    readonly session: Schema.brand<Schema.String, "ConversationId">;
+    readonly turn: Schema.Int;
+    readonly since: Schema.Number;
+}>;
+export type ActiveTurn = typeof ActiveTurn.Type;
+/**
+ * The turns a `Sessions` holds open and the begins it is still working on
+ * (waiting for the host's admission, committing, starting the writer),
+ * read at one moment.
+ */
+export declare const TurnsInFlight: Schema.Struct<{
+    readonly open: Schema.$Array<Schema.Struct<{
+        readonly session: Schema.brand<Schema.String, "ConversationId">;
+        readonly turn: Schema.Int;
+        readonly since: Schema.Number;
+    }>>;
+    readonly beginning: Schema.Int;
+}>;
+export type TurnsInFlight = typeof TurnsInFlight.Type;
+/**
+ * What this process is busy with, for a `/ping` or a graceful shutdown: the
+ * turns it holds open (oldest first), the begins still in progress, the
+ * background tasks it runs, and whether there is any of them.
+ */
+export declare const ProcessActivity: Schema.Struct<{
+    readonly openTurns: Schema.$Array<Schema.Struct<{
+        readonly session: Schema.brand<Schema.String, "ConversationId">;
+        readonly turn: Schema.Int;
+        readonly since: Schema.Number;
+    }>>;
+    readonly beginningTurns: Schema.Int;
+    readonly runningTasks: Schema.Int;
+    readonly busy: Schema.Boolean;
+}>;
+export type ProcessActivity = typeof ProcessActivity.Type;

package/dist/session/activity.entity.functions.d.ts

@@ -0,0 +1,21 @@
+import { Effect } from "effect";
+import type { Duration } from "effect";
+import type { ProcessActivity } from "./activity.entity.js";
+/**
+ * What this process is busy with now: the turns its `TurnActivity` holds
+ * open or is beginning, and the work its `TaskActivity` runs. A probe that
+ * is not in the context counts as nothing open, beginning or running.
+ */
+export declare const processActivity: Effect.Effect<ProcessActivity>;
+/**
+ * Wait until this process holds no turn open, begins none and runs no
+ * background work at the same moment, and return that activity (`busy:
+ * false`). With a `timeout`, stop waiting then and return the activity as
+ * it is (`busy: true`, with what is still in flight). It admits nothing
+ * itself: to drain before a shutdown, stop admitting new turns first (the
+ * host's `TurnAdmission`, or its own front door), then wait, then stop the
+ * host's own request fibers, then close the scope the services live in.
+ */
+export declare const awaitIdle: (options?: {
+    readonly timeout?: Duration.Input;
+}) => Effect.Effect<ProcessActivity>;

package/dist/session/activity.entity.functions.js

@@ -0,0 +1,23 @@
+import { Effect, Option } from "effect";
+import { TaskActivity, TurnActivity } from "../ports/activity.port.js";
+const noTurns = { open: [], beginning: 0 };
+export const processActivity = Effect.gen(function* () {
+  const turns = yield* Effect.serviceOption(TurnActivity), tasks = yield* Effect.serviceOption(TaskActivity), inFlight = yield* Option.match(turns, { onNone: () => Effect.succeed(noTurns), onSome: (probe) => probe.current }), runningTasks = yield* Option.match(tasks, { onNone: () => Effect.succeed(0), onSome: (probe) => probe.running });
+  return {
+    openTurns: inFlight.open,
+    beginningTurns: inFlight.beginning,
+    runningTasks,
+    busy: inFlight.open.length > 0 || inFlight.beginning > 0 || runningTasks > 0
+  };
+});
+const settled = Effect.gen(function* () {
+  const turns = yield* Effect.serviceOption(TurnActivity), tasks = yield* Effect.serviceOption(TaskActivity);
+  yield* Option.match(turns, { onNone: () => Effect.void, onSome: (probe) => probe.idle });
+  yield* Option.match(tasks, { onNone: () => Effect.void, onSome: (probe) => probe.idle });
+  const now = yield* processActivity;
+  return now.busy ? yield* Effect.yieldNow.pipe(Effect.andThen(settled)) : now;
+});
+export const awaitIdle = (options) => Option.match(Option.fromNullishOr(options?.timeout), {
+  onNone: () => settled,
+  onSome: (timeout) => Effect.timeoutOption(settled, timeout).pipe(Effect.flatMap(Option.match({ onNone: () => processActivity, onSome: Effect.succeed })))
+});

package/dist/session/activity.entity.functions.test.d.ts

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

package/dist/session/activity.entity.js

@@ -0,0 +1,15 @@
+import { Schema } from "effect";
+import { ConversationId } from "../domain/message.entity.js";
+export const ActiveTurn = Schema.Struct({
+  session: ConversationId,
+  turn: Schema.Int,
+  since: Schema.Number
+}), TurnsInFlight = Schema.Struct({
+  open: Schema.Array(ActiveTurn),
+  beginning: Schema.Int
+}), ProcessActivity = Schema.Struct({
+  openTurns: Schema.Array(ActiveTurn),
+  beginningTurns: Schema.Int,
+  runningTasks: Schema.Int,
+  busy: Schema.Boolean
+});

package/dist/session/chassis.js

@@ -1,6 +1,7 @@
 import { Effect, Exit, Fiber, Option, PubSub, Ref, Stream, Semaphore } from "effect";
+import { replayableContext } from "../loop/traceContent.js";
 export const makeSession = (args) => Effect.gen(function* () {
-  const context = yield* Effect.context(), log = yield* Ref.make([]), hub = yield* PubSub.sliding(512), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), gate = yield* Semaphore.make(1), publish = (event) => args.isTransient?.(event) === !0 ? PubSub.publish(transientHub, event).pipe(Effect.asVoid) : Ref.modify(log, (entries) => {
+  const context = replayableContext(yield* Effect.context()), log = yield* Ref.make([]), hub = yield* PubSub.sliding(512), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), gate = yield* Semaphore.make(1), publish = (event) => args.isTransient?.(event) === !0 ? PubSub.publish(transientHub, event).pipe(Effect.asVoid) : Ref.modify(log, (entries) => {
     const entry = { seq: entries.length, event };
     return [entry, [...entries, entry]];
   }).pipe(Effect.flatMap((entry) => PubSub.publish(hub, entry)), Effect.asVoid), runContained = (text) => args.runTurn(text, publish).pipe(Effect.provide(context), Effect.catch((error) => publish(args.onError(String(error)))), Effect.catchDefect((defect) => publish(args.onError(`turn crashed: ${String(defect)}`)))), send = (text) => gate.withPermits(1)(Effect.gen(function* () {

package/dist/session/session-event.entity.d.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import type { TurnEventName } from "../turn/turn-event.entity.js";
 import { UserMessage } from "../turn/user-message.entity.js";
 /** Opens a turn: who asked, what they said, the host's command and the inbox items it claims. */
 export declare const TurnStartedData: Schema.Struct<{
@@ -14,11 +15,30 @@ export declare const TurnStartedData: Schema.Struct<{
     /** The memory entry the message is to the model, and when memory took it. */
     readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
     readonly at: Schema.Number;
+    /**
+     * The host's metadata for the turn (`BeginTurn.meta`), written only when
+     * given: not part of the key's fingerprint and never shown to the model.
+     */
+    readonly meta: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Unknown>>;
+    /**
+     * The earlier turn this one resumes (`BeginTurn.User.resumes`), written
+     * only when given: part of the key's fingerprint.
+     */
+    readonly resumes: Schema.optionalKey<Schema.Int>;
 }>;
 export type TurnStartedData = typeof TurnStartedData.Type;
 export declare const TurnEndReason: Schema.Literals<readonly ["completed", "partial", "failed", "cancelled", "interrupted"]>;
 export type TurnEndReason = typeof TurnEndReason.Type;
-/** Closes a turn. Not model-visible: what later turns remember is `turn.reply`. */
+/**
+ * Closes a turn. Not model-visible: what later turns remember is `turn.reply`.
+ * `failure.code` is the failing error's own code when it has one (a
+ * `HarnessError`'s); otherwise one of the framework's codes, `turn.failed`
+ * (a typed error without a code), `turn.defect`, `turn.interrupted` (an
+ * interrupted turn or scope), `turn.unended` (a scope closed before its turn
+ * ended) or `turn.lease` (a reaped turn), or a code the closer passes to
+ * `writer.end` itself (plugin-tasks: `task.turn`, `task.deadline`; a host's
+ * own). A cancel stores none.
+ */
 export declare const TurnEndedData: Schema.Struct<{
     readonly reason: Schema.Literals<readonly ["completed", "partial", "failed", "cancelled", "interrupted"]>;
     readonly failure: Schema.OptionFromNullOr<Schema.Struct<{
@@ -27,6 +47,36 @@ export declare const TurnEndedData: Schema.Struct<{
     }>>;
 }>;
 export type TurnEndedData = typeof TurnEndedData.Type;
+/** An inbox item as delivered (`inbox.queued`): its stable id, who sent it and the text a turn shows the model. */
+export declare const InboxQueuedData: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly source: Schema.$Record<Schema.String, Schema.Unknown>;
+    readonly content: Schema.String;
+}>;
+export type InboxQueuedData = typeof InboxQueuedData.Type;
+/** An inbox item given up on (`inbox.dropped`): as many turns took it and failed as the inbox allows. */
+export declare const InboxDroppedData: Schema.Struct<{
+    readonly id: Schema.String;
+    readonly reason: Schema.Literals<readonly ["attempts"]>;
+}>;
+export type InboxDroppedData = typeof InboxDroppedData.Type;
+/**
+ * One step's provider response as stored (`step.usage`): its step, model and
+ * token usage. The rest of `assistant.message` is memory's `memory.message`.
+ */
+export declare const StepUsageData: Schema.Struct<{
+    readonly step: Schema.Int;
+    readonly model: Schema.OptionFromNullOr<Schema.String>;
+    readonly usage: Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+    }>;
+}>;
+export type StepUsageData = typeof StepUsageData.Type;
 /** The kind each memory entry is stored under. `TurnStarted` is the turn's own `turn.started`. */
 export declare const MemoryKindOf: {
     readonly SystemPrepared: "memory.system";
@@ -43,13 +93,25 @@ export declare const MemoryKindOf: {
 export declare const MEMORY_KINDS: ReadonlyArray<string>;
 /** The turn's observable events stored from its bus (a host's records keep their own names). */
 export declare const TURN_EVENT_KINDS: ReadonlyArray<string>;
+/** Bus events not stored from the bus: memory or the session records them itself, and storing them again would be a second copy. */
+export declare const RECORDED_ELSEWHERE: ReadonlySet<TurnEventName>;
 /** The inbox and the session's own records. */
 export declare const SESSION_KINDS: ReadonlyArray<string>;
 /**
- * Kinds only Efferent writes: a host record under one of these names is refused.
- * `request.prepared` holds each request's full system text and tool
- * declarations (and step context in "system" mode), next to the memory
- * events: a host that redacts memory, or exports or streams session events,
- * handles it the same way.
+ * Every kind the framework writes to a session's journal: memory's, the
+ * bus events it stores, and the session's own. `journalSchemaOf(kind)` has
+ * the schema of each. `request.prepared` holds each request's full system
+ * text and tool declarations (and step context in "system" mode), next to
+ * the memory events: a host that redacts memory, or exports or streams
+ * session events, handles it the same way.
+ */
+export declare const JOURNAL_KINDS: ReadonlyArray<string>;
+/**
+ * Names only Efferent uses: a host event or a host record under one of
+ * these is refused. They are the kinds the framework writes
+ * (`JOURNAL_KINDS`) and every bus event's name (`TURN_EVENT_NAMES`), the
+ * ones never stored under their own name included (`assistant.message`,
+ * `assistant.delta`, `tool.progress`, `skills.activated`, `host`), so a host
+ * event never reads as one of the framework's.
  */
 export declare const RESERVED_KINDS: ReadonlyArray<string>;

package/dist/session/session-event.entity.functions.d.ts

@@ -1,4 +1,5 @@
 import { Effect, Option, Schema } from "effect";
+import type { TokenUsage } from "../domain/token-usage.entity.js";
 import { LogEntry } from "../memory/memory-log.entity.js";
 import type { TurnEvent as TurnEventType } from "../turn/turn-event.entity.js";
 import type { TurnEndedData as TurnEnded, TurnStartedData as TurnStarted } from "./session-event.entity.js";
@@ -18,14 +19,45 @@ export declare const turnEndedDraft: (turn: number, data: TurnEnded) => Effect.E
 export declare const turnStartedOf: (event: SessionLogEvent) => Effect.Effect<TurnStarted, Schema.SchemaError>;
 /** A stored `turn.ended`, decoded. */
 export declare const turnEndedOf: (event: SessionLogEvent) => Effect.Effect<TurnEnded, Schema.SchemaError>;
-/** One stored event → the memory entry it is, if it is one. */
+/**
+ * One stored event → the memory entry it is, if it is one. A `turn.started`
+ * is decoded once: its user message, attachments included, is the entry's.
+ */
 export declare const entryOfEvent: (event: SessionLogEvent) => Effect.Effect<Option.Option<LogEntry>, Schema.SchemaError>;
 /** The memory log held in a session's events, in log order. */
 export declare const entriesOfEvents: (events: ReadonlyArray<SessionLogEvent>) => Effect.Effect<ReadonlyArray<LogEntry>, Schema.SchemaError>;
+/**
+ * Turn `turn`'s usage from a session's stored events: its `step.usage`
+ * records summed, which is what the turn's `assistant.message` events
+ * carried (`TurnResult.usage`, `turn.ended.usage`). A record written before
+ * 0.14.0 reads 0 cache-write and reasoning tokens.
+ */
+export declare const turnUsageOf: (events: ReadonlyArray<SessionLogEvent>, turn: number) => Effect.Effect<TokenUsage, Schema.SchemaError>;
 /**
  * The stored form of one bus event of turn `turn`: its name and encoded
  * payload. Transient events are not stored; a host's event keeps its name
  * and data; an assistant message is stored only as the step's model and
- * usage (its content is memory's `memory.message`).
+ * usage (its content is memory's `memory.message`); `tool.completed` leaves
+ * out its input and result, `tool.refused` its input.
  */
 export declare const draftOfTurnEvent: (turn: number, event: TurnEventType) => Option.Option<SessionDraft>;
+/**
+ * The stored form of a memory entry (`memory.*`, `turn.reply`): the entry's
+ * id, run, step and time, and `body`, the entry's body without its `_tag`
+ * (the kind names it, see `MemoryKindOf`).
+ */
+export declare const StoredMemoryData: <Body extends Schema.Top>(body: Body) => Schema.Struct<{
+    readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+    readonly runId: Schema.String;
+    readonly step: Schema.Int;
+    readonly at: Schema.Number;
+    readonly body: Body;
+}>;
+/**
+ * The schema the framework stores a journal kind's `data` with: every kind
+ * in `JOURNAL_KINDS` has one. None for any other kind: a host's records, a
+ * plugin's own (such as the tasks plugin's `task.*`), and the reserved bus
+ * names never stored under their own name (`assistant.message`,
+ * `tool.progress`…).
+ */
+export declare const journalSchemaOf: (kind: string) => Option.Option<Schema.Codec<unknown, unknown>>;

package/dist/session/session-event.entity.functions.js

@@ -1,8 +1,19 @@
-import { Effect, Option, Schema } from "effect";
+import { Effect, Option, Schema, Struct } from "effect";
+import { sumUsage } from "../domain/token-usage.entity.functions.js";
 import { canonicalJson } from "../memory/memory-log.entity.functions.js";
-import { LogEntry } from "../memory/memory-log.entity.js";
-import { TransientTurnEvents, TurnEvent } from "../turn/turn-event.entity.js";
-import { MemoryKindOf, TurnEndedData, TurnStartedData } from "./session-event.entity.js";
+import { EntryId, LogBody, LogEntry } from "../memory/memory-log.entity.js";
+import { ModelRequestHeader } from "../turn/model-request.entity.js";
+import { ContextBuiltEvent, ToolCompletedEvent, ToolRefusedEvent, TransientTurnEvents, TurnEvent } from "../turn/turn-event.entity.js";
+import {
+  InboxDroppedData,
+  InboxQueuedData,
+  MemoryKindOf,
+  RECORDED_ELSEWHERE,
+  StepUsageData,
+  TURN_EVENT_KINDS,
+  TurnEndedData,
+  TurnStartedData
+} from "./session-event.entity.js";
 const encodeEntry = Schema.encodeEffect(LogEntry), decodeEntry = Schema.decodeUnknownEffect(LogEntry), encodeTurnEvent = Schema.encodeSync(TurnEvent), tagOfKind = new Map(Object.entries(MemoryKindOf).map(([tag, kind]) => [kind, tag])), canonical = (data) => JSON.parse(canonicalJson(data)), turnOf = (event) => Option.getOrElse(event.turn, () => 0);
 export const draftOfEntry = (entry) => entry.body._tag === "TurnStarted" ? Effect.succeed(Option.none()) : encodeEntry(entry).pipe(Effect.map((encoded) => {
   const { _tag, ...body } = encoded.body, kind = MemoryKindOf[_tag];
@@ -13,30 +24,57 @@ export const draftOfEntry = (entry) => entry.body._tag === "TurnStarted" ? Effec
   });
 })), draftsOfEntries = (entries) => Effect.forEach(entries, draftOfEntry).pipe(Effect.map((drafts) => drafts.flatMap(Option.toArray))), turnStartedDraft = (turn, data) => Schema.encodeEffect(TurnStartedData)(data).pipe(Effect.map((encoded) => ({ kind: "turn.started", turn: Option.some(turn), data: { ...encoded } }))), turnEndedDraft = (turn, data) => Schema.encodeEffect(TurnEndedData)(data).pipe(Effect.map((encoded) => ({ kind: "turn.ended", turn: Option.some(turn), data: { ...encoded } }))), turnStartedOf = (event) => Schema.decodeUnknownEffect(TurnStartedData)(canonical(event.data)), turnEndedOf = (event) => Schema.decodeUnknownEffect(TurnEndedData)(canonical(event.data)), entryOfEvent = (event) => {
   if (event.kind === "turn.started")
-    return turnStartedOf(event).pipe(Effect.flatMap((started) => decodeEntry({
+    return turnStartedOf(event).pipe(Effect.map((started) => Option.some({
       id: started.entry,
       runId: started.runId,
       turn: turnOf(event),
       step: 0,
       at: started.at,
-      body: { _tag: "TurnStarted", prompt: started.userMessage.text }
-    })), Effect.map(Option.some));
+      body: { _tag: "TurnStarted", userMessage: started.userMessage }
+    })));
   const tag = tagOfKind.get(event.kind);
   if (tag === void 0)
     return Effect.succeed(Option.none());
   const data = canonical(event.data), body = typeof data.body === "object" && data.body !== null ? data.body : {};
   return decodeEntry({ id: data.entry, runId: data.runId, turn: turnOf(event), step: data.step, at: data.at, body: { ...body, _tag: tag } }).pipe(Effect.map(Option.some));
 }, entriesOfEvents = (events) => Effect.forEach(events, entryOfEvent).pipe(Effect.map((entries) => entries.flatMap(Option.toArray)));
-const recordedElsewhere = new Set(["turn.started", "turn.ended", "skills.activated"]), withoutPayload = (data) => Object.fromEntries(Object.entries(data).filter(([key]) => key !== "result" && key !== "encoded" && key !== "input"));
-export const draftOfTurnEvent = (turn, event) => {
-  if (TransientTurnEvents.includes(event._tag) || recordedElsewhere.has(event._tag))
+const OMITTED_FROM_TOOL_COMPLETED = ["result", "encoded", "input"], OMITTED_FROM_TOOL_REFUSED = ["input"], without = (omitted) => (data) => Object.fromEntries(Object.entries(data).filter(([key]) => !omitted.includes(key))), storedPayload = new Map([
+  ["tool.completed", without(OMITTED_FROM_TOOL_COMPLETED)],
+  ["tool.refused", without(OMITTED_FROM_TOOL_REFUSED)]
+]), encodeStepUsage = Schema.encodeSync(StepUsageData), decodeStepUsage = Schema.decodeUnknownEffect(StepUsageData);
+export const turnUsageOf = (events, turn) => Effect.forEach(events.filter((event) => event.kind === "step.usage" && Option.contains(event.turn, turn)), (event) => decodeStepUsage(canonical(event.data))).pipe(Effect.map((records) => sumUsage(records.map((record) => record.usage)))), draftOfTurnEvent = (turn, event) => {
+  if (TransientTurnEvents.includes(event._tag) || RECORDED_ELSEWHERE.has(event._tag))
     return Option.none();
   if (event._tag === "host")
     return Option.some({ kind: event.name, turn: Option.some(turn), data: event.data });
+  if (event._tag === "assistant.message")
+    return Option.some({ kind: "step.usage", turn: Option.some(turn), data: { ...encodeStepUsage({ step: event.step, model: event.model, usage: event.usage }) } });
   const { _tag, ...data } = encodeTurnEvent(event);
-  if (_tag === "assistant.message") {
-    const { step, model, usage } = data;
-    return Option.some({ kind: "step.usage", turn: Option.some(turn), data: { step, model, usage } });
-  }
-  return Option.some({ kind: _tag, turn: Option.some(turn), data: _tag === "tool.completed" ? withoutPayload(data) : data });
-};
+  return Option.some({ kind: _tag, turn: Option.some(turn), data: Option.match(Option.fromNullishOr(storedPayload.get(_tag)), { onNone: () => data, onSome: (stored) => stored(data) }) });
+}, StoredMemoryData = (body) => Schema.Struct({
+  entry: EntryId,
+  runId: Schema.String,
+  step: Schema.Int,
+  at: Schema.Number,
+  body
+});
+const memorySchemas = LogBody.members.flatMap((member) => ("fields" in member) ? [[MemoryKindOf[member.fields._tag.schema.literal], StoredMemoryData(Schema.Struct(Struct.omit(member.fields, ["_tag"])))]] : []), laterKeys = new Map([
+  ["context.built", Schema.Struct(Struct.evolve(Struct.omit(ContextBuiltEvent.fields, ["_tag"]), { budgetTokens: (field) => Schema.optionalKey(field) }))]
+]), busSchemas = TurnEvent.members.flatMap((member) => {
+  const tag = member.fields._tag.schema.literal;
+  if (storedPayload.has(tag) || !TURN_EVENT_KINDS.includes(tag))
+    return [];
+  return [[tag, laterKeys.get(tag) ?? Schema.Struct(Struct.omit(member.fields, ["_tag"]))]];
+}), journalSchemas = new Map([
+  ["turn.started", TurnStartedData],
+  ["turn.ended", TurnEndedData],
+  ["step.usage", StepUsageData],
+  ["request.prepared", ModelRequestHeader],
+  ["inbox.queued", InboxQueuedData],
+  ["inbox.dropped", InboxDroppedData],
+  ["tool.completed", Schema.Struct(Struct.omit(ToolCompletedEvent.fields, ["_tag", ...OMITTED_FROM_TOOL_COMPLETED]))],
+  ["tool.refused", Schema.Struct(Struct.omit(ToolRefusedEvent.fields, ["_tag", ...OMITTED_FROM_TOOL_REFUSED]))],
+  ...memorySchemas,
+  ...busSchemas
+]);
+export const journalSchemaOf = (kind) => Option.fromNullishOr(journalSchemas.get(kind));

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

@@ -1,5 +1,7 @@
 import { Schema } from "effect";
+import { TokenUsage } from "../domain/token-usage.entity.js";
 import { EntryId } from "../memory/memory-log.entity.js";
+import { TURN_EVENT_NAMES } from "../turn/turn-event.entity.js";
 import { UserMessage } from "../turn/user-message.entity.js";
 import { JsonObject } from "./session-log.entity.js";
 export const TurnStartedData = Schema.Struct({
@@ -10,10 +12,23 @@ export const TurnStartedData = Schema.Struct({
   command: JsonObject,
   claimed: Schema.Array(Schema.String),
   entry: EntryId,
-  at: Schema.Number
+  at: Schema.Number,
+  meta: Schema.optionalKey(JsonObject),
+  resumes: Schema.optionalKey(Schema.Int)
 }), TurnEndReason = Schema.Literals(["completed", "partial", "failed", "cancelled", "interrupted"]), TurnEndedData = Schema.Struct({
   reason: TurnEndReason,
   failure: Schema.OptionFromNullOr(Schema.Struct({ code: Schema.String, message: Schema.String }))
+}), InboxQueuedData = Schema.Struct({
+  id: Schema.String,
+  source: JsonObject,
+  content: Schema.String
+}), InboxDroppedData = Schema.Struct({
+  id: Schema.String,
+  reason: Schema.Literals(["attempts"])
+}), StepUsageData = Schema.Struct({
+  step: Schema.Int,
+  model: Schema.OptionFromNullOr(Schema.String),
+  usage: TokenUsage
 }), MemoryKindOf = {
   SystemPrepared: "memory.system",
   TurnContext: "memory.section",
@@ -29,9 +44,11 @@ export const TurnStartedData = Schema.Struct({
   "step.ended",
   "step.usage",
   "tool.started",
+  "tool.refused",
   "tool.completed",
   "completion.evaluated",
   "context.built",
   "decision.recorded",
+  "stream.fallback",
   "request.prepared"
-], SESSION_KINDS = ["turn.ended", "inbox.queued", "inbox.dropped"], RESERVED_KINDS = [...MEMORY_KINDS, ...TURN_EVENT_KINDS, ...SESSION_KINDS];
+], RECORDED_ELSEWHERE = new Set(["turn.started", "turn.ended", "skills.activated"]), SESSION_KINDS = ["turn.ended", "inbox.queued", "inbox.dropped"], JOURNAL_KINDS = [...MEMORY_KINDS, ...TURN_EVENT_KINDS, ...SESSION_KINDS], RESERVED_KINDS = [...JOURNAL_KINDS, ...TURN_EVENT_NAMES.filter((name) => !JOURNAL_KINDS.includes(name))];

package/dist/session/session-log.conformance.d.ts

@@ -5,9 +5,10 @@ type Log = Context.Service.Shape<typeof SessionLog>;
 /**
  * The SessionLog contract, as checks any backend must pass: dense sequence
  * numbers, one revision per commit, compare-and-swap, the `notAfter` clock
- * check, JSON kept by value, reads by position and kind, listing order,
- * children and their removal. Every check uses fresh ids and a fresh owner,
- * so the kit is safe on a shared database.
+ * check, JSON kept by value, an event as large as a turn's images may make
+ * it (`MEDIA_LIMITS.requestChars` base64 characters), reads by position and
+ * kind, listing order, children and their removal. Every check uses fresh
+ * ids and a fresh owner, so the kit is safe on a shared database.
  */
 export declare const sessionLogConformance: (log: Log) => ReadonlyArray<ConformanceCheck>;
 export {};

package/dist/session/session-log.conformance.js

@@ -1,20 +1,9 @@
 import { Effect, Option } from "effect";
-import { ConformanceFailure } from "../conformance.entity.js";
-import { ConversationId } from "../domain/message.entity.js";
+import { check, expect, freshId, headerOf } from "../conformance.functions.js";
+import { MEDIA_LIMITS } from "../domain/media.entity.js";
 import { canonicalJson } from "../memory/memory-log.entity.functions.js";
-const fail = (check, message) => Effect.fail(new ConformanceFailure({ check, message })), expect = (check, holds, message) => holds ? Effect.void : fail(check, message), freshId = Effect.sync(() => ConversationId.make(crypto.randomUUID())), headerOf = (id, owner, parent = Option.none()) => ({
-  id,
-  owner,
-  origin: "user",
-  createdAt: 1767225600000,
-  meta: { title: "conformance", nested: { list: [1, "two", null] } },
-  parent
-}), draft = (kind, data, turn = Option.none()) => ({ kind, turn, data }), noEvents = { notAfter: Option.none(), state: Option.none() }, rich = { zeta: 1, alpha: { b: [!0, !1, { y: "\xFC", x: 0.5 }], a: "text \u2713" }, empty: {}, list: [] };
+const draft = (kind, data, turn = Option.none()) => ({ kind, turn, data }), noEvents = { notAfter: Option.none(), state: Option.none() }, rich = { zeta: 1, alpha: { b: [!0, !1, { y: "\xFC", x: 0.5 }], a: "text \u2713" }, empty: {}, list: [] };
 export const sessionLogConformance = (log) => {
-  const check = (name, id, body) => ({
-    name,
-    run: freshId.pipe(Effect.flatMap((owner) => body(`owner-${owner}`)), Effect.catch((error) => error instanceof ConformanceFailure ? Effect.fail(error) : fail(id, `unexpected ${typeof error === "object" && error !== null && "_tag" in error ? String(error._tag) : "error"}: ${JSON.stringify(error)}`)))
-  });
   return [
     check("a new session is empty: seq 0, revision 0, the header as given", "create", (owner) => Effect.gen(function* () {
       const id = yield* freshId, created = yield* log.create(headerOf(id, owner)), head = yield* log.head(id);
@@ -79,6 +68,19 @@ export const sessionLogConformance = (log) => {
       yield* expect("json", event !== void 0 && canonicalJson(event.data) === canonicalJson(rich), `data came back as ${JSON.stringify(event?.data)}`);
       yield* expect("json", canonicalJson((yield* log.head(id)).state) === canonicalJson(rich), "the state came back different");
     })),
+    check("an event holding MEDIA_LIMITS.requestChars of base64 (a message's images at their limit) comes back whole", "large", (owner) => Effect.gen(function* () {
+      const id = yield* freshId;
+      yield* log.create(headerOf(id, owner));
+      const each = MEDIA_LIMITS.requestChars / MEDIA_LIMITS.attachments, large = {
+        userMessage: {
+          text: "large",
+          attachments: Array.from({ length: MEDIA_LIMITS.attachments }, (_, index) => ({ type: "media", data: `${"QUJD".repeat(each / 4 - 1)}${String(index).padStart(4, "0")}` }))
+        }
+      };
+      yield* log.commit(id, { expect: 0, ...noEvents, events: [draft("large", large, Option.some(1))] });
+      const [event] = yield* log.read(id, { after: 0, limit: Option.none(), kinds: [] }), chars = (data) => canonicalJson(data ?? {}).length;
+      yield* expect("large", event !== void 0 && chars(event.data) === chars(large) && canonicalJson(event.data) === canonicalJson(large), `an event of ${chars(large)} characters came back with ${chars(event?.data)}`);
+    })),
     check("input and returned JSON are detached from stored heads and events", "json-isolation", (owner) => Effect.gen(function* () {
       const id = yield* freshId, header = headerOf(id, owner), expectedMeta = canonicalJson(header.meta), created = yield* log.create(header), change = (json, by) => {
         Reflect.set(json, "changed", by);