@xandreed/core 0.12.0 → 0.14.0

package/dist/ports/activity.port.js

@@ -0,0 +1,7 @@
+import { Context } from "effect";
+
+export class TurnActivity extends Context.Service()("efferent/TurnActivity") {
+}
+
+export class TaskActivity extends Context.Service()("efferent/TaskActivity") {
+}

package/dist/ports/auth-store.port.d.ts

@@ -32,16 +32,18 @@ declare const AuthStore_base: Context.ServiceClass<AuthStore, "@xandreed/core/Au
     readonly all: Effect.Effect<ReadonlyMap<string, Credential>, AuthError>;
     readonly get: (p: ProviderId) => Effect.Effect<Option.Option<Credential>, AuthError>;
     readonly resolveKey: (p: ProviderId) => Effect.Effect<Option.Option<Redacted.Redacted<string>>, AuthError>;
-    /** Persist a credential (the human's `:login` action). */
+    /** Persist a credential (a login). */
     readonly set: (p: ProviderId, credential: Credential) => Effect.Effect<void, AuthError>;
-    /** Remove a provider's credential everywhere it is stored (`:logout`). */
+    /** Remove a provider's credential everywhere it is stored (a logout). */
     readonly remove: (p: ProviderId) => Effect.Effect<void, AuthError>;
 }>;
 /**
  * The credential store, read lazily per request: `resolveKey` returns a
- * usable secret (refreshing + persisting a near-expiry OAuth token first),
- * so a credential added mid-session takes effect on the next call with no
- * restart. `None` means the provider is not configured.
+ * usable secret (refreshing a near-expiry OAuth token first, and persisting
+ * it where the store keeps credentials), so a credential added mid-session
+ * takes effect on the next call with no restart. `None` means the provider
+ * is not configured. `authStoreConformance` checks a store against this
+ * contract.
  */
 export declare class AuthStore extends AuthStore_base {
 }

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

@@ -0,0 +1,22 @@
+import { Context } from "effect";
+import type { Effect, Stream } from "effect";
+import type { BashError, BashEvent, BashOptions, BashResult } from "../domain/bash.entity.js";
+declare const Bash_base: Context.ServiceClass<Bash, "@xandreed/core/Bash", {
+    /** Output chunks as they arrive, then exactly one `BashExit`. */
+    readonly stream: (command: string, options: BashOptions) => Stream.Stream<BashEvent, BashError>;
+    /** The whole output and how the command ended (`collectBashResult` over `stream`). */
+    readonly exec: (command: string, options: BashOptions) => Effect.Effect<BashResult, BashError>;
+}>;
+/**
+ * Commands run with `bash -c`, each in a process group of its own. A
+ * non-zero exit, a signal and a timeout are results the caller reads,
+ * never errors: `BashError` means the command could not run at all. When a
+ * command times out or its caller stops waiting (the stream or the `exec`
+ * is interrupted), the adapter kills its whole process group, so what it
+ * started in the background goes with it; an adapter may also do that when
+ * the command exits. The environment is built with `resolveBashEnv`.
+ * `bashConformance` is the contract as runnable checks.
+ */
+export declare class Bash extends Bash_base {
+}
+export {};

package/dist/ports/bash.port.js

@@ -0,0 +1,4 @@
+import { Context } from "effect";
+
+export class Bash extends Context.Service()("@xandreed/core/Bash") {
+}

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

@@ -1,6 +1,7 @@
 import { Context } from "effect";
 import type { Effect, Option } from "effect";
 import type { LanguageModel, Tool } from "effect/ai";
+import type { Media } from "../domain/media.entity.js";
 import type { AgentMessage } from "../domain/message.entity.js";
 import type { TokenUsage } from "../domain/token-usage.entity.js";
 import type { PromptTier, SkillDefinition, ToolAnnotations } from "../harness/capability.entity.js";
@@ -38,9 +39,16 @@ export interface ToolViewDefinition<Result, Params> {
     /** The older-turn form; None keeps `render`'s text. */
     readonly compact: Option.Option<(result: Result, params: Params) => string>;
     readonly subjects: (result: Result, params: Params) => ReadonlyArray<Subject>;
-    /** Files and images the result carries, kept by reference. */
+    /** Files and images the result points to by URL, kept by reference (shown as reference lines). */
     readonly artifacts: (result: Result, params: Params) => ReadonlyArray<ArtifactRef>;
     readonly digest: Option.Option<DigestDefinition<Result, Params>>;
+    /**
+     * The images the model is sent with the result: `Media` values the result
+     * holds (one it does not hold is ignored). None: every image it holds.
+     * A tool returns images as `Media` values in its success value;
+     * `Tool.toModelOutput` is not used.
+     */
+    readonly media: Option.Option<(result: Result, params: Params) => ReadonlyArray<Media>>;
 }
 /** The view as an author writes it; optional parts default in `defineTool`. */
 export interface ToolViewInput<Result, Params> {
@@ -50,6 +58,8 @@ export interface ToolViewInput<Result, Params> {
     readonly subjects?: (result: Result, params: Params) => ReadonlyArray<Subject>;
     readonly artifacts?: (result: Result, params: Params) => ReadonlyArray<ArtifactRef>;
     readonly digest?: DigestDefinition<Result, Params>;
+    /** The images among the result's the model is sent with it; omitted: every image the result holds. */
+    readonly media?: (result: Result, params: Params) => ReadonlyArray<Media>;
 }
 /** A typed tool definition as its author writes it (see `defineTool`). */
 export interface ToolDefinition<T extends Tool.Any, R> {

package/dist/ports/file-system.port.d.ts

@@ -1,24 +1,53 @@
-import { Context, Schema } from "effect";
+import { Context } from "effect";
 import type { Effect } from "effect";
-declare const FsError_base: Schema.Class<FsError, Schema.TaggedStruct<"FsError", {
-    readonly path: Schema.String;
-    readonly message: Schema.String;
-}>, import("effect/Cause").YieldableError>;
-export declare class FsError extends FsError_base {
-}
+import type { DirEntry, FileInfo, FsError, GlobOptions, GlobResult, ReadRange, RecursiveOptions, StatOptions, WriteOptions } from "../domain/file-system.entity.js";
 declare const FileSystem_base: Context.ServiceClass<FileSystem, "@xandreed/core/FileSystem", {
+    /** A file's text, decoded as UTF-8. */
     readonly read: (path: string) => Effect.Effect<string, FsError>;
-    readonly write: (path: string, content: string) => Effect.Effect<void, FsError>;
+    /** A file's bytes, or a range of them; a range past the end returns what there is. */
+    readonly readBytes: (path: string, range?: ReadRange) => Effect.Effect<Uint8Array, FsError>;
+    /** Create or replace a file (text is written as UTF-8). Without `createParents`, a missing parent fails with `NotFound`. */
+    readonly write: (path: string, content: string | Uint8Array, options?: WriteOptions) => Effect.Effect<void, FsError>;
+    /** Add to the end of a file, creating it when missing. */
+    readonly append: (path: string, content: string | Uint8Array, options?: WriteOptions) => Effect.Effect<void, FsError>;
+    /**
+     * Move a file, directory or link (the link itself, not its target); an
+     * existing file at `to` is replaced. A failure names the side that caused
+     * it: `from` when it is missing, `to` for a missing parent there or what
+     * is in the way (`IsDirectory`, `NotDirectory`, `NotEmpty`).
+     */
+    readonly rename: (from: string, to: string) => Effect.Effect<void, FsError>;
+    readonly stat: (path: string, options?: StatOptions) => Effect.Effect<FileInfo, FsError>;
+    /** Whether the path exists (a link whose target is missing does not). A missing path is `false`, not an error. */
     readonly exists: (path: string) => Effect.Effect<boolean, FsError>;
-    readonly list: (dir: string) => Effect.Effect<ReadonlyArray<string>, FsError>;
-    readonly mkdir: (dir: string) => Effect.Effect<void, FsError>;
-    /** Resolve symlinks to the canonical absolute path. */
+    /** A directory's entries, sorted by name (code-unit order), links not followed. */
+    readonly list: (dir: string) => Effect.Effect<ReadonlyArray<DirEntry>, FsError>;
+    /** The paths under `options.cwd` the pattern matches (`*`, `**`, `?`, `[...]`, `{a,b}`); links are never entered. */
+    readonly glob: (pattern: string, options: GlobOptions) => Effect.Effect<GlobResult, FsError>;
+    /** Create a directory. Without `recursive`, an existing path fails with `Exists` and a missing parent with `NotFound`; with it, existing directories are fine. */
+    readonly mkdir: (dir: string, options?: RecursiveOptions) => Effect.Effect<void, FsError>;
+    /** The canonical absolute path, every symbolic link resolved. */
     readonly realPath: (path: string) => Effect.Effect<string, FsError>;
-    /** Delete a file. A missing path is a no-op (idempotent), not an error. */
-    readonly remove: (path: string) => Effect.Effect<void, FsError>;
+    /**
+     * Delete a file, a link (not its target) or a directory. A missing path
+     * is a no-op. Without `recursive`, an empty directory is removed and one
+     * with entries fails with `NotEmpty`. Links in the parent are followed
+     * and the last name never is, trailing slash or not (`link/` removes
+     * the link). The root, and a path whose last segment is `.` or `..`,
+     * fail with `Invalid`.
+     */
+    readonly remove: (path: string, options?: RecursiveOptions) => Effect.Effect<void, FsError>;
 }>;
-/** Minimal filesystem port for agent tools. Paths are absolute or
- *  caller-resolved — the port does no cwd magic. */
+/**
+ * The file system agent tools work through. Paths are absolute (the port
+ * does no cwd magic) and POSIX; every failure is an `FsError` whose
+ * `reason` is the same on every backend. Calls follow symbolic links,
+ * except `list` (which reports links as `symlink`), `remove` (which removes
+ * the link), `rename` (which moves the link, not its target) and `stat`
+ * with `followSymlinks: false`. `fileSystemConformance`
+ * is the contract as runnable checks; `FileSystemMemoryLive` is the
+ * in-memory backend.
+ */
 export declare class FileSystem extends FileSystem_base {
 }
 export {};

package/dist/ports/file-system.port.js

@@ -1,10 +1,4 @@
-import { Context, Schema } from "effect";
-
-export class FsError extends Schema.TaggedError()("FsError", {
-  path: Schema.String,
-  message: Schema.String
-}) {
-}
+import { Context } from "effect";
 
 export class FileSystem extends Context.Service()("@xandreed/core/FileSystem") {
 }

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

@@ -1,112 +1,14 @@
 import { Context } from "effect";
-import type { Effect, Option, Stream } from "effect";
-import type { Tool, Toolkit } from "effect/ai";
-import type { AgentMessage, ConversationId } from "../domain/message.entity.js";
+import type { Effect } from "effect";
 import type { HarnessError } from "../harness/plugin.entity.js";
-import type { EventBody, MemoryEntry, SessionEvent, SessionRecord } from "../harness/session.entity.js";
-import type { UserMessage } from "../turn/user-message.entity.js";
-declare const SessionStore_base: Context.ServiceClass<SessionStore, "efferent/SessionStore", {
-    readonly create: (workspace: string, profile: string) => Effect.Effect<SessionRecord, HarnessError>;
-    readonly get: (id: ConversationId) => Effect.Effect<SessionRecord, HarnessError>;
-    readonly list: (workspace: string) => Effect.Effect<ReadonlyArray<SessionRecord>, HarnessError>;
-    readonly read: (id: ConversationId, after: number) => Effect.Effect<ReadonlyArray<SessionEvent>, HarnessError>;
-    readonly append: (id: ConversationId, body: EventBody) => Effect.Effect<SessionEvent, HarnessError>;
-    readonly fork: (id: ConversationId, through: number) => Effect.Effect<SessionRecord, HarnessError>;
-}>;
-/** @deprecated Historical event vocabulary; live adapters project it over SessionLog. New hosts use Sessions and TurnWriter. */
-export declare class SessionStore extends SessionStore_base {
-}
-export interface LoopInput {
-    readonly session: SessionRecord;
-    readonly runId: string;
-    readonly userMessage: UserMessage;
-    readonly system: string;
-    readonly publish: (event: EventBody) => Effect.Effect<SessionEvent, HarnessError>;
-    readonly transient: (event: EventBody) => Effect.Effect<void>;
-    readonly steering: Effect.Effect<Option.Option<string>, HarnessError>;
-    /** Journal reads for memory plugins: events after `after`, filtered by name (all when empty). */
-    readonly history: (after: number, names: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<SessionEvent>, HarnessError>;
-    /** Host services the run's tools and hooks may require (data ports, per-turn models). */
-    readonly services: Context.Context<never>;
-}
-declare const AgentLoop_base: Context.ServiceClass<AgentLoop, "efferent/AgentLoop", {
-    readonly run: (input: LoopInput) => Effect.Effect<{
-        readonly text: string;
-        readonly outcome: "completed" | "partial";
-    }, HarnessError>;
-}>;
-export declare class AgentLoop extends AgentLoop_base {
-}
-declare const DelegateLoop_base: Context.ServiceClass<DelegateLoop, "efferent/DelegateLoop", {
-    readonly run: (input: LoopInput) => Effect.Effect<{
-        readonly text: string;
-        readonly outcome: "completed" | "partial";
-    }, HarnessError>;
-}>;
-/** A workflow can delegate coding while retaining its own outer loop. */
-export declare class DelegateLoop extends DelegateLoop_base {
-}
-declare const AgentTools_base: Context.ServiceClass<AgentTools, "efferent/AgentTools", {
-    readonly toolkit: Toolkit.Toolkit<Record<string, Tool.Any>>;
-    readonly handlers: Context.Context<Tool.HandlersFor<Record<string, Tool.Any>>>;
-    readonly prompt: string;
-}>;
-export declare class AgentTools extends AgentTools_base {
-}
 declare const ActionPolicy_base: Context.ServiceClass<ActionPolicy, "efferent/ActionPolicy", {
     readonly authorize: (tool: string, input: unknown) => Effect.Effect<void, HarnessError>;
 }>;
 export declare class ActionPolicy extends ActionPolicy_base {
 }
-declare const Approval_base: Context.ServiceClass<Approval, "efferent/Approval", {
-    readonly request: (description: string) => Effect.Effect<boolean, HarnessError>;
-}>;
-export declare class Approval extends Approval_base {
-}
-declare const ContextManager_base: Context.ServiceClass<ContextManager, "efferent/ContextManager", {
-    readonly compact: (messages: ReadonlyArray<AgentMessage>, tokens: number) => Effect.Effect<Option.Option<{
-        readonly summary: string;
-        readonly keepFrom: number;
-    }>, HarnessError>;
-}>;
-export declare class ContextManager extends ContextManager_base {
-}
-declare const Memory_base: Context.ServiceClass<Memory, "efferent/Memory", {
-    readonly recall: (workspace: string, query: string) => Effect.Effect<ReadonlyArray<MemoryEntry>, HarnessError>;
-    readonly remember: (workspace: string, text: string) => Effect.Effect<MemoryEntry, HarnessError>;
-    readonly forget: (workspace: string, id: string) => Effect.Effect<void, HarnessError>;
-}>;
-export declare class Memory extends Memory_base {
-}
 declare const SessionEnvironment_base: Context.ServiceClass<SessionEnvironment, "efferent/SessionEnvironment", {
     readonly workspace: string;
-    readonly session?: SessionRecord;
 }>;
 export declare class SessionEnvironment extends SessionEnvironment_base {
 }
-declare const TurnHooks_base: Context.ServiceClass<TurnHooks, "efferent/TurnHooks", {
-    readonly before: (input: LoopInput) => Effect.Effect<LoopInput, HarnessError>;
-    readonly after: (input: LoopInput) => Effect.Effect<void, HarnessError>;
-}>;
-/** Ordered hooks alter a turn; observers subscribe to the journal separately. */
-export declare class TurnHooks extends TurnHooks_base {
-}
-export interface SessionHandle {
-    readonly record: SessionRecord;
-    readonly use: <I, A, B, E, R>(tag: Context.Service<I, A>, run: (service: A) => Effect.Effect<B, E, R>) => Effect.Effect<B, E | HarnessError, R>;
-    readonly send: (text: string) => Effect.Effect<void, HarnessError>;
-    readonly steer: (text: string) => Effect.Effect<void, HarnessError>;
-    readonly interrupt: Effect.Effect<void>;
-    readonly events: (after?: number) => Stream.Stream<SessionEvent, HarnessError>;
-    readonly transient: Stream.Stream<EventBody>;
-    readonly history: Effect.Effect<ReadonlyArray<SessionEvent>, HarnessError>;
-    readonly busy: Effect.Effect<boolean>;
-    readonly pending: Effect.Effect<ReadonlyArray<{
-        readonly id: string;
-        readonly text: string;
-    }>>;
-    readonly continue: Effect.Effect<void, HarnessError>;
-    readonly refresh: Effect.Effect<void, HarnessError>;
-    readonly close: Effect.Effect<void>;
-}
 export {};

package/dist/ports/harness.port.js

@@ -1,31 +1,7 @@
 import { Context } from "effect";
 
-export class SessionStore extends Context.Service()("efferent/SessionStore") {
-}
-
-export class AgentLoop extends Context.Service()("efferent/AgentLoop") {
-}
-
-export class DelegateLoop extends Context.Service()("efferent/DelegateLoop") {
-}
-
-export class AgentTools extends Context.Service()("efferent/AgentTools") {
-}
-
 export class ActionPolicy extends Context.Service()("efferent/ActionPolicy") {
 }
 
-export class Approval extends Context.Service()("efferent/Approval") {
-}
-
-export class ContextManager extends Context.Service()("efferent/ContextManager") {
-}
-
-export class Memory extends Context.Service()("efferent/Memory") {
-}
-
 export class SessionEnvironment extends Context.Service()("efferent/SessionEnvironment") {
 }
-
-export class TurnHooks extends Context.Service()("efferent/TurnHooks") {
-}

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

@@ -1,5 +1,6 @@
 import { Context } from "effect";
 import type { Effect, Option, Scope } from "effect";
+import type { MediaSlot } from "../domain/media.entity.js";
 import type { AgentMessage, ConversationId } from "../domain/message.entity.js";
 import type { TokenUsage } from "../domain/token-usage.entity.js";
 import type { HarnessError } from "../harness/plugin.entity.js";
@@ -19,6 +20,13 @@ export interface ToolView {
     readonly subjects: ReadonlyArray<Subject>;
     readonly artifacts: ReadonlyArray<ArtifactRef>;
     readonly pinned: boolean;
+    /**
+     * The images of the encoded result the model is sent with it, where they
+     * are in it (`mediaSlotsOf`). Memory checks each one when it records the
+     * result (`toolResultMedia`): an image that fails, or one over
+     * `MEDIA_LIMITS.toolResultImages`, is a label line in the stored view.
+     */
+    readonly media?: ReadonlyArray<MediaSlot>;
 }
 /** What the digester returns: the item keys to keep, or a summary. */
 export interface DigestOutcome {
@@ -72,7 +80,11 @@ export interface MemoryReader {
 export interface MaintainSignal {
     readonly phase: "turn-start" | "step";
     readonly lastUsage: Option.Option<TokenUsage>;
-    /** Tokens available to the messages (system and tool schemas already deducted). */
+    /**
+     * Tokens available to the messages, at least 1: at `step`, what the system
+     * prompt and the active tool schemas leave of the run's budget; at
+     * `turn-start`, the run's whole budget (nothing is built yet).
+     */
     readonly budgetTokens: number;
     readonly views: ToolViews;
 }

package/dist/ports/model-catalog.port.d.ts

@@ -4,7 +4,10 @@ import type { ModelCatalogEntry } from "../domain/model-catalog.entity.js";
 declare const ModelCatalog_base: Context.ServiceClass<ModelCatalog, "@xandreed/core/ModelCatalog", {
     readonly list: Effect.Effect<ReadonlyArray<ModelCatalogEntry>>;
 }>;
-/** Provider-neutral discovery of models usable by configured adapters. */
+/**
+ * Provider-neutral discovery of models usable by configured adapters.
+ * `modelCatalogConformance` checks a catalog against this contract.
+ */
 export declare class ModelCatalog extends ModelCatalog_base {
 }
 export {};

package/dist/ports/run-context.port.d.ts

@@ -1,8 +1,9 @@
 import { Context } from "effect";
 import type { Effect } from "effect";
 import type { ConversationId } from "../domain/message.entity.js";
+import type { TokenUsage } from "../domain/token-usage.entity.js";
 import type { HarnessError } from "../harness/plugin.entity.js";
-import type { SessionAddress } from "../session/sessions.entity.js";
+import type { AdmittedTurn, SessionAddress } from "../session/sessions.entity.js";
 import type { UserMessage } from "../turn/user-message.entity.js";
 import type { MemoryReader } from "./memory.port.js";
 import type { TurnEventsService, TurnTasksService } from "./turn-events.port.js";
@@ -12,6 +13,8 @@ declare const RunContext_base: Context.ServiceClass<RunContext, "efferent/RunCon
     readonly session: SessionAddress;
     readonly runId: string;
     readonly userMessage: UserMessage;
+    /** The admitted turn as the session began it: its number, key, origin, command, claimed inbox items and the host's `meta`. */
+    readonly admitted: AdmittedTurn;
     readonly memory: MemoryReader;
     readonly events: TurnEventsService;
     readonly tasks: TurnTasksService;
@@ -21,6 +24,8 @@ declare const RunContext_base: Context.ServiceClass<RunContext, "efferent/RunCon
     readonly flush: Effect.Effect<void, HarnessError>;
     /** Run a host store write in journal order (after everything queued before it). */
     readonly write: <A, E>(op: Effect.Effect<A, E>) => Effect.Effect<A, E | HarnessError>;
+    /** The turn's usage so far: the usage of every `assistant.message` published in the turn, summed. */
+    readonly usage: Effect.Effect<TokenUsage>;
 }>;
 /** The current run, as tools, sections and run layers see it. Provided by the turn. */
 export declare class RunContext extends RunContext_base {

package/dist/ports/session-log.port.d.ts

@@ -18,7 +18,10 @@ declare const SessionLog_base: Context.ServiceClass<SessionLog, "efferent/Sessio
  * session plus its head (see `session-log.entity.ts`). Everything above it
  * (turns, leases, the inbox, memory) is the sessions plugin's; a backend
  * only keeps the log, the head and the compare-and-swap, and passes
- * `sessionLogConformance`.
+ * `sessionLogConformance`. One event can be large: a user's images are
+ * stored inline in its `turn.started`, up to `MEDIA_LIMITS.requestChars`
+ * base64 characters together, so a backend must hold an event of that size
+ * (the kit checks one).
  */
 export declare class SessionLog extends SessionLog_base {
 }

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

@@ -1,9 +1,10 @@
 import { Context } from "effect";
 import type { Effect, Option, Scope, Stream } from "effect";
+import type { AttachmentRejected } from "../domain/media.entity.js";
 import type { ConversationId } from "../domain/message.entity.js";
 import type { HarnessError } from "../harness/plugin.entity.js";
 import type { JsonObject, SessionExists, SessionListCursor, SessionLogError, SessionLogEvent, SessionMissing } from "../session/session-log.entity.js";
-import type { AdmittedTurn, BeginTurn, InboxFull, InboxItem, KeyConflict, NothingPending, ReservedKind, SessionAddress, SessionBusy, SessionPage, SessionView, TurnClosed, TurnDuplicate, TurnEnding, TurnRefused } from "../session/sessions.entity.js";
+import type { AdmittedTurn, BeginTurn, InboxFull, InboxItem, KeyConflict, NothingPending, NotResumable, ReservedKind, SessionAddress, SessionBusy, SessionPage, SessionView, TurnClosed, TurnDuplicate, TurnEnding, TurnRefused } from "../session/sessions.entity.js";
 /** One event to record; the writer stamps the turn (or none, outside a turn). */
 export interface TurnDraft {
     readonly kind: string;
@@ -60,8 +61,9 @@ export interface TurnWriter {
      * refused, and `flush` still waits for what is queued. Calls while it runs
      * share its result. A stored end, or a turn closed elsewhere, is final;
      * after any other failure (a store error) writes are admitted again and a
-     * later end, the scope's own at the latest, tries again. Returns how many
-     * inbox items wait.
+     * later end, the scope's own at the latest, tries again: the scope's with
+     * the last ending whose commit was tried. Returns how many inbox items
+     * wait.
      */
     readonly end: (ending: TurnEnding) => Effect.Effect<{
         readonly pending: number;
@@ -113,17 +115,44 @@ declare const Sessions_base: Context.ServiceClass<Sessions, "efferent/Sessions",
     }, SessionMissing | SessionLogError>;
     /**
      * Open a turn, through the host's TurnAdmission. Its writer lives in the
-     * scope; a writer the scope closes unended ends as failed (or interrupted).
+     * scope; a writer the scope closes unended ends with the last ending it
+     * tried to store, or, when none was tried, as failed (`turn.unended`), or
+     * as interrupted (`turn.interrupted`) when the scope was interrupted.
+     * The input's `meta` is stored in `turn.started` and shown on the writer's
+     * `admitted`; it is not part of the key's fingerprint.
+     * A user's turn with `resumes: n` resumes turn `n`: it must be the
+     * session's last turn begun by a user (only inbox turns, and resumes of it
+     * that failed, were cancelled or were interrupted, may have run since) and
+     * have ended cancelled or interrupted (reaped included), or the begin
+     * fails with `NotResumable` and opens nothing. The check runs after the
+     * key's (a retried resume is `TurnDuplicate`) and after `SessionBusy`, in
+     * the opening commit; an `n` that is not a whole number of at least 1 is
+     * `NotResumable` (`missing`) before anything else, the admission included.
+     * `resumes` is stored in `turn.started`, shown on `admitted` and part of
+     * the key's fingerprint.
+     * A user message is normalised first (`normalizeUserMessage`), before
+     * anything else: an image its bytes do not support fails with
+     * `AttachmentRejected`, and the normalised message is what is stored,
+     * admitted and compared with an earlier turn of the same key.
      */
-    readonly begin: (address: SessionAddress, input: BeginTurn) => Effect.Effect<TurnWriter, SessionBusy | TurnDuplicate | KeyConflict | NothingPending | TurnRefused | SessionMissing | SessionLogError, Scope.Scope>;
+    readonly begin: (address: SessionAddress, input: BeginTurn) => Effect.Effect<TurnWriter, AttachmentRejected | SessionBusy | TurnDuplicate | KeyConflict | NothingPending | NotResumable | TurnRefused | SessionMissing | SessionLogError, Scope.Scope>;
     /** Put an item in the inbox (once per id); `pending` counts what waits after it. */
     readonly deliver: (address: SessionAddress, item: InboxItem) => Effect.Effect<{
         readonly delivered: boolean;
         readonly pending: number;
     }, InboxFull | SessionMissing | SessionLogError>;
-    /** Run inbox turns while items wait, the session is free and the host admits them, at most `maxTurns` (3). */
+    /**
+     * Run inbox turns while items wait, the session is free and the host
+     * admits them, at most `maxTurns` (3), each begun with `meta`. A turn whose
+     * `run` succeeds ends completed; one whose `run` fails ends with its
+     * error's code (`turnEndingOf`, a `HarnessError` carried as a defect
+     * included): `turn.failed`, `turn.defect` or `turn.interrupted` when it has
+     * none. A `run` that interrupts itself counts an attempt for the items it
+     * took, even when it wrote nothing.
+     */
     readonly drain: <E, R>(address: SessionAddress, run: (writer: TurnWriter) => Effect.Effect<void, E, R>, options?: {
         readonly maxTurns?: number;
+        readonly meta?: JsonObject;
     }) => Effect.Effect<{
         readonly turns: number;
     }, SessionMissing | SessionLogError, R>;

package/dist/ports/settings-store.port.d.ts

@@ -28,19 +28,23 @@ export declare const SETTINGS_KEYS: readonly ["fallbackModel", "sandbox", "viMod
 export type SettingsKey = (typeof SETTINGS_KEYS)[number];
 declare const SettingsStore_base: Context.ServiceClass<SettingsStore, "@xandreed/core/SettingsStore", {
     readonly load: Effect.Effect<EngineSettings, SettingsError>;
-    /** Persist one role's model selection (the human's `:model` action);
-     *  `None` clears the role so it falls back to its default again. */
+    /** Persist one role's model selection (a role choice); `None` clears
+     *  the role so it falls back to its default again. A selection that is
+     *  not `"<provider>:<modelId>"` fails with a `SettingsError` and writes
+     *  nothing. */
     readonly setRole: (role: ModelRole, selection: Option.Option<string>) => Effect.Effect<void, SettingsError>;
-    /** Persist one non-role key from its STRING form (the `:settings`
-     *  action): the adapter validates + coerces per key ("true", "3",
-     *  "provider:model") and rejects a value that doesn't parse; `None`
-     *  clears the key. */
+    /** Persist one non-role key from its STRING form (a settings edit): the
+     *  adapter validates + coerces per key ("true", "3", "provider:model")
+     *  and rejects a value that doesn't parse with a `SettingsError`,
+     *  writing nothing; `None` clears the key. */
     readonly set: (key: SettingsKey, value: Option.Option<string>) => Effect.Effect<void, SettingsError>;
 }>;
 /**
  * Read-through settings port. `load` re-reads the backing store on every call
  * so a value changed mid-session takes effect on the next turn — callers must
- * not cache the result across turns.
+ * not cache the result across turns. A store may be read-only: then
+ * `setRole` and `set` fail with a `SettingsError` and write nothing.
+ * `settingsStoreConformance` checks a store against this contract.
  */
 export declare class SettingsStore extends SettingsStore_base {
 }

package/dist/ports/step-loop.port.d.ts

@@ -2,6 +2,7 @@ import { Context } from "effect";
 import type { Effect, Option } from "effect";
 import type { LanguageModel, Prompt, Tool } from "effect/ai";
 import type { AgentMessage } from "../domain/message.entity.js";
+import type { TokenUsage } from "../domain/token-usage.entity.js";
 import type { HarnessError } from "../harness/plugin.entity.js";
 import type { LogEntry } from "../memory/memory-log.entity.js";
 import type { CompletionVerdict } from "../turn/turn-event.entity.js";
@@ -44,12 +45,31 @@ export interface StepRequest {
     readonly dispatch: (step: number, request: ModelDispatch) => Effect.Effect<void, HarnessError>;
     /** Persist a step's appended messages; returns their log entries. */
     readonly record: (step: number, tail: ReadonlyArray<AgentMessage>) => Effect.Effect<ReadonlyArray<LogEntry>, HarnessError>;
+    /**
+     * A provider refused the step's request over an image (an `InvalidRequestError`
+     * that names one; `reason` is what it said). Records an `OmitMedia`
+     * compaction of the entries whose images that request sent and answers
+     * true, so the loop plans the step again and sends it once more, the
+     * images as label lines; false when the request sent no image, and the
+     * step fails. The step's next `plan`, that one only, keeps the model
+     * choice, system prompt and directive the refused request was planned
+     * with; any other `plan` of a step asks the policy again.
+     */
+    readonly onMediaRejected: (reason: string) => Effect.Effect<boolean, HarnessError>;
     readonly completion: (step: StepInfo) => Effect.Effect<CompletionVerdict, HarnessError>;
     readonly steering: Effect.Effect<Option.Option<string>, HarnessError>;
     readonly correctives: Option.Option<Correctives>;
     readonly events: TurnEventsService;
     readonly tasks: TurnTasksService;
     readonly cacheKey: Option.Option<string>;
+    /**
+     * Whether the run's spans may carry prompt and response content: the loop
+     * must provide it as `CurrentTraceContent` to the model calls it makes,
+     * whatever the caller's (`stepLoopConformance` checks it), so they read it
+     * too. The policy's `captureTraceContent`, else the agent's, else
+     * `CurrentTraceContent` where the run starts (off by default).
+     */
+    readonly captureTraceContent: boolean;
 }
 export interface ModelDispatch {
     readonly prompt: Prompt.Prompt;
@@ -62,6 +82,8 @@ export interface RunResult {
     readonly reason: "completed" | "step-cap" | "degenerate-loop";
     readonly text: string;
     readonly steps: number;
+    /** The run's provider calls summed: exactly the usage its `assistant.message` events carried. */
+    readonly usage: TokenUsage;
 }
 declare const StepLoop_base: Context.ServiceClass<StepLoop, "efferent/StepLoop", {
     readonly id: string;
@@ -75,10 +97,16 @@ declare const StepLoop_base: Context.ServiceClass<StepLoop, "efferent/StepLoop",
  * (after the tail is recorded) < `completion.evaluated`; a planned batch
  * makes no provider call; a forced tool choice is honoured; a verdict
  * awaiting tasks joins them and is evaluated once more; no provider call
- * follows a complete verdict.
+ * follows a complete verdict; `RunResult.usage` is the sum of the usage
+ * the run's `assistant.message` events carried; the model calls read the
+ * request's `captureTraceContent` as `CurrentTraceContent`. A loop that streams and
+ * falls back to a non-streamed call publishes `stream.fallback`; the kit
+ * does not stream, so it does not check that.
  * Every real provider attempt runs `request.dispatch` immediately before
  * invoking the model; a failed durable check prevents the call. Planned
- * batches skip that hook because they make no provider request.
+ * batches skip that hook because they make no provider request. A request
+ * a provider refuses over an image is sent once more after
+ * `request.onMediaRejected` answers true, planned again first.
  */
 export declare class StepLoop extends StepLoop_base {
 }

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

@@ -43,7 +43,11 @@ declare const TaskRunner_base: Context.ServiceClass<TaskRunner, "efferent/TaskRu
  * Where background work runs: a fiber of this process, or the host's own
  * mechanism (e.g. a serverless waitUntil). `run` returns once the work is
  * handed over; the work is told when it must be done by (Clock time), if
- * the runner has a limit, so a task ends interrupted rather than lost.
+ * the runner has a limit, so a task ends interrupted rather than lost. The
+ * work goes on after its caller (the turn that started a task) ends, and
+ * runs without the caller's services; on fibers of this process, it is
+ * interrupted when the runner's scope closes. `taskRunnerConformance`
+ * checks a runner.
  */
 export declare class TaskRunner extends TaskRunner_base {
 }

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

@@ -1,5 +1,6 @@
 import { Context } from "effect";
 import type { Effect } from "effect";
+import type { JsonObject } from "../session/session-log.entity.js";
 import type { SessionAddress, TurnRefused } from "../session/sessions.entity.js";
 /** The turn a host is asked to admit. */
 export interface TurnToAdmit {
@@ -7,6 +8,10 @@ export interface TurnToAdmit {
     readonly origin: "user" | "inbox";
     readonly runId: string;
     readonly key: string;
+    /** The host's metadata the turn is begun with (`{}` when none was given): a tenant or a quota key to count by. */
+    readonly meta: JsonObject;
+    /** The earlier turn a user's turn resumes (a whole number of at least 1), only when it resumes one. */
+    readonly resumes?: number;
 }
 declare const TurnAdmission_base: Context.ServiceClass<TurnAdmission, "efferent/TurnAdmission", {
     readonly admit: <A, E>(turn: TurnToAdmit, open: Effect.Effect<A, E>) => Effect.Effect<A, E | TurnRefused>;
@@ -15,8 +20,9 @@ declare const TurnAdmission_base: Context.ServiceClass<TurnAdmission, "efferent/
  * The host's say on every turn before it opens: a user's, the inbox's, a
  * background task's. `admit` runs around the one commit that opens the turn,
  * never around the turn's later writes, so a host can count and open in one
- * transaction; a duplicate or a busy session fails inside it and counts
- * nothing. A refusal opens nothing.
+ * transaction; a duplicate, a key conflict, a busy session or a turn that
+ * cannot be resumed (`NotResumable`) fails inside it and counts nothing. A
+ * refusal opens nothing.
  */
 export declare class TurnAdmission extends TurnAdmission_base {
 }