@xandreed/sdk 0.14.0 → 0.15.0

package/dist/turn/turn-phase.entity.d.ts

@@ -0,0 +1,462 @@
+import { Schema } from "effect";
+import type { UserMessage } from "@xandreed/core";
+/**
+ * Where one turn stands in `TurnLive`: its message not taken by memory yet
+ * (`Waiting`, with the context entries waiting for it), being taken
+ * (`Taking`: `persistMessage` is recording it, and context entries still
+ * wait), taken as turn `number` (`Taken`; `sectioned` once its turn-tier
+ * sections are due; `runs`, the ordinal its next run of the step loop
+ * takes), or replied (`Replied`, with the outcome recorded, and `held`, the
+ * memory entries held for the turn's closing commit: its reply, and what
+ * memory recorded after it, in order). Its transitions are the pure
+ * functions of `turn-phase.entity.functions.ts`.
+ */
+export declare const TurnPhase: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Waiting", {
+    readonly early: Schema.$Array<Schema.TaggedStruct<"TurnContext", {
+        readonly sectionId: Schema.brand<Schema.String, "SectionId">;
+        readonly version: Schema.String;
+        readonly text: Schema.String;
+    }>>;
+}>, Schema.TaggedStruct<"Taking", {
+    readonly early: Schema.$Array<Schema.TaggedStruct<"TurnContext", {
+        readonly sectionId: Schema.brand<Schema.String, "SectionId">;
+        readonly version: Schema.String;
+        readonly text: Schema.String;
+    }>>;
+}>, Schema.TaggedStruct<"Taken", {
+    readonly number: Schema.Int;
+    readonly sectioned: Schema.Boolean;
+    readonly runs: Schema.brand<Schema.Int, "RunOrdinal">;
+}>, Schema.TaggedStruct<"Replied", {
+    readonly number: Schema.Int;
+    readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed", "waiting"]>;
+    readonly held: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.brand<Schema.Trimmed, "EntryId">;
+        readonly runId: Schema.brand<Schema.String, "RunId">;
+        readonly turn: Schema.Int;
+        readonly step: Schema.Int;
+        readonly at: Schema.Number;
+        readonly body: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"SystemPrepared", {
+            readonly fingerprint: Schema.String;
+            readonly text: Schema.String;
+            readonly sections: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.brand<Schema.String, "SectionId">;
+                readonly version: Schema.String;
+                readonly fingerprint: Schema.String;
+            }>>;
+        }>, Schema.decodeTo<Schema.TaggedStruct<"TurnStarted", {
+            readonly userMessage: typeof UserMessage;
+        }>, Schema.Struct<{
+            readonly _tag: Schema.Literal<"TurnStarted">;
+            readonly prompt: Schema.String;
+            readonly attachments: Schema.optionalKey<Schema.$Array<Schema.toEncoded<Schema.Struct<{
+                readonly type: Schema.Literal<"media">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly data: Schema.String;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly bytes: Schema.Int;
+                readonly name: Schema.optionalKey<Schema.String>;
+                readonly alt: Schema.optionalKey<Schema.String>;
+            }>>>>;
+        }>, never, never>, Schema.TaggedStruct<"TurnContext", {
+            readonly sectionId: Schema.brand<Schema.String, "SectionId">;
+            readonly version: Schema.String;
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly _tag: Schema.tag<"Message">;
+            readonly message: Schema.Union<readonly [Schema.Struct<{
+                readonly role: Schema.Literal<"user">;
+                readonly content: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+                    readonly type: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"media">;
+                    readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                    readonly data: Schema.String;
+                    readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                    readonly bytes: Schema.Int;
+                    readonly name: Schema.optionalKey<Schema.String>;
+                    readonly alt: Schema.optionalKey<Schema.String>;
+                }>]>>]>;
+                readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>, Schema.Struct<{
+                readonly role: Schema.Literal<"assistant">;
+                readonly content: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+                    readonly type: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"reasoning">;
+                    readonly text: Schema.String;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"tool-call">;
+                    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                    readonly toolName: Schema.String;
+                    readonly input: Schema.Unknown;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly providerExecuted: Schema.optional<Schema.Boolean>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"tool-result">;
+                    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                    readonly toolName: Schema.String;
+                    readonly output: Schema.Unknown;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly isError: Schema.optional<Schema.Boolean>;
+                    readonly providerExecuted: Schema.optionalKey<Schema.Boolean>;
+                    readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                        readonly type: Schema.Literal<"media">;
+                        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                        readonly data: Schema.String;
+                        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                        readonly bytes: Schema.Int;
+                        readonly name: Schema.optionalKey<Schema.String>;
+                        readonly alt: Schema.optionalKey<Schema.String>;
+                    }>>>;
+                }>]>>;
+                readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>, Schema.Struct<{
+                readonly role: Schema.Literal<"tool">;
+                readonly content: Schema.$Array<Schema.Struct<{
+                    readonly type: Schema.Literal<"tool-result">;
+                    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                    readonly toolName: Schema.String;
+                    readonly output: Schema.Unknown;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly isError: Schema.optional<Schema.Boolean>;
+                    readonly providerExecuted: Schema.optionalKey<Schema.Boolean>;
+                    readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                        readonly type: Schema.Literal<"media">;
+                        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                        readonly data: Schema.String;
+                        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                        readonly bytes: Schema.Int;
+                        readonly name: Schema.optionalKey<Schema.String>;
+                        readonly alt: Schema.optionalKey<Schema.String>;
+                    }>>>;
+                }>>;
+                readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>]>;
+            readonly run: Schema.optionalKey<Schema.brand<Schema.Int, "RunOrdinal">>;
+            readonly inbox: Schema.optionalKey<Schema.brand<Schema.Trimmed, "InboxItemId">>;
+        }>, Schema.TaggedStruct<"ToolResult", {
+            readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+            readonly run: Schema.optionalKey<Schema.brand<Schema.Int, "RunOrdinal">>;
+            readonly toolName: Schema.String;
+            readonly isError: Schema.Boolean;
+            readonly encoded: Schema.Unknown;
+            readonly interception: Schema.optionalKey<Schema.Struct<{
+                readonly invocationId: Schema.brand<Schema.String, "InvocationId">;
+                readonly effectiveInput: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            }>>;
+            readonly view: Schema.String;
+            readonly viewVersion: Schema.String;
+            readonly subjects: Schema.$Array<Schema.Struct<{
+                readonly kind: Schema.Trimmed;
+                readonly id: Schema.brand<Schema.Trimmed, "SubjectId">;
+                readonly label: Schema.OptionFromNullOr<Schema.String>;
+                readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
+            }>>;
+            readonly artifacts: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.brand<Schema.Trimmed, "ArtifactId">;
+                readonly kind: Schema.Literals<readonly ["image", "file"]>;
+                readonly mediaType: Schema.Trimmed;
+                readonly url: Schema.String;
+                readonly alt: Schema.OptionFromNullOr<Schema.String>;
+            }>>;
+            readonly pinned: Schema.Boolean;
+            readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly bytes: Schema.Int;
+            }>>>;
+            readonly mediaNotes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        }>, Schema.TaggedStruct<"ToolDigest", {
+            readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+            readonly version: Schema.String;
+            readonly mode: Schema.Literals<readonly ["select", "summarize"]>;
+            readonly keep: Schema.$Array<Schema.String>;
+            readonly text: Schema.String;
+            readonly digester: Schema.String;
+            readonly trigger: Schema.Literals<readonly ["write", "compaction"]>;
+        }>, Schema.TaggedStruct<"StepContext", {
+            readonly step: Schema.Int;
+            readonly run: Schema.withDecodingDefaultKey<Schema.brand<Schema.Int, "RunOrdinal">, never>;
+            readonly text: Schema.String;
+        }>, Schema.TaggedStruct<"ToolsActivated", {
+            readonly skills: Schema.$Array<Schema.String>;
+            readonly tools: Schema.$Array<Schema.String>;
+            readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+            readonly decision: Schema.OptionFromNullOr<Schema.brand<Schema.Trimmed, "DecisionId">>;
+        }>, Schema.TaggedStruct<"Compaction", {
+            readonly strategy: Schema.String;
+            readonly version: Schema.String;
+            readonly action: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"CompactViews", {
+                readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+                readonly texts: Schema.$Array<Schema.String>;
+            }>, Schema.TaggedStruct<"Spill", {
+                readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+                readonly preview: Schema.String;
+            }>, Schema.TaggedStruct<"DropTurns", {
+                readonly throughTurn: Schema.Int;
+                readonly ledger: Schema.String;
+            }>, Schema.TaggedStruct<"Summarize", {
+                readonly keepFromTurn: Schema.Int;
+                readonly summary: Schema.String;
+            }>, Schema.TaggedStruct<"OmitMedia", {
+                readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+                readonly reason: Schema.String;
+            }>]>;
+        }>, Schema.TaggedStruct<"TurnEnded", {
+            readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed", "waiting"]>;
+            readonly reply: Schema.OptionFromNullOr<Schema.String>;
+        }>, Schema.TaggedStruct<"ToolPresentation", {
+            readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+            readonly view: Schema.String;
+            readonly viewVersion: Schema.String;
+            readonly subjects: Schema.$Array<Schema.Struct<{
+                readonly kind: Schema.Trimmed;
+                readonly id: Schema.brand<Schema.Trimmed, "SubjectId">;
+                readonly label: Schema.OptionFromNullOr<Schema.String>;
+                readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
+            }>>;
+            readonly artifacts: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.brand<Schema.Trimmed, "ArtifactId">;
+                readonly kind: Schema.Literals<readonly ["image", "file"]>;
+                readonly mediaType: Schema.Trimmed;
+                readonly url: Schema.String;
+                readonly alt: Schema.OptionFromNullOr<Schema.String>;
+            }>>;
+            readonly pinned: Schema.Boolean;
+            readonly media: Schema.$Array<Schema.Struct<{
+                readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly bytes: Schema.Int;
+            }>>;
+            readonly mediaNotes: Schema.$Array<Schema.String>;
+        }>]>;
+    }>>;
+}>]>;
+export type TurnPhase = typeof TurnPhase.Type;
+/**
+ * What a reply does (`reply`): `Record` the turn's reply (TurnEnded) as
+ * turn `number` and publish `turn.ended`; `Hold` these entries again for the
+ * closing commit, the reply among them downgraded to failed; or nothing.
+ */
+export declare const ReplyStep: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"Record", {
+    readonly number: Schema.Int;
+}>, Schema.TaggedStruct<"Hold", {
+    readonly held: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.brand<Schema.Trimmed, "EntryId">;
+        readonly runId: Schema.brand<Schema.String, "RunId">;
+        readonly turn: Schema.Int;
+        readonly step: Schema.Int;
+        readonly at: Schema.Number;
+        readonly body: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"SystemPrepared", {
+            readonly fingerprint: Schema.String;
+            readonly text: Schema.String;
+            readonly sections: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.brand<Schema.String, "SectionId">;
+                readonly version: Schema.String;
+                readonly fingerprint: Schema.String;
+            }>>;
+        }>, Schema.decodeTo<Schema.TaggedStruct<"TurnStarted", {
+            readonly userMessage: typeof UserMessage;
+        }>, Schema.Struct<{
+            readonly _tag: Schema.Literal<"TurnStarted">;
+            readonly prompt: Schema.String;
+            readonly attachments: Schema.optionalKey<Schema.$Array<Schema.toEncoded<Schema.Struct<{
+                readonly type: Schema.Literal<"media">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly data: Schema.String;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly bytes: Schema.Int;
+                readonly name: Schema.optionalKey<Schema.String>;
+                readonly alt: Schema.optionalKey<Schema.String>;
+            }>>>>;
+        }>, never, never>, Schema.TaggedStruct<"TurnContext", {
+            readonly sectionId: Schema.brand<Schema.String, "SectionId">;
+            readonly version: Schema.String;
+            readonly text: Schema.String;
+        }>, Schema.Struct<{
+            readonly _tag: Schema.tag<"Message">;
+            readonly message: Schema.Union<readonly [Schema.Struct<{
+                readonly role: Schema.Literal<"user">;
+                readonly content: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+                    readonly type: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"media">;
+                    readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                    readonly data: Schema.String;
+                    readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                    readonly bytes: Schema.Int;
+                    readonly name: Schema.optionalKey<Schema.String>;
+                    readonly alt: Schema.optionalKey<Schema.String>;
+                }>]>>]>;
+                readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>, Schema.Struct<{
+                readonly role: Schema.Literal<"assistant">;
+                readonly content: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+                    readonly type: Schema.Literal<"text">;
+                    readonly text: Schema.String;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"reasoning">;
+                    readonly text: Schema.String;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"tool-call">;
+                    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                    readonly toolName: Schema.String;
+                    readonly input: Schema.Unknown;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly providerExecuted: Schema.optional<Schema.Boolean>;
+                }>, Schema.Struct<{
+                    readonly type: Schema.Literal<"tool-result">;
+                    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                    readonly toolName: Schema.String;
+                    readonly output: Schema.Unknown;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly isError: Schema.optional<Schema.Boolean>;
+                    readonly providerExecuted: Schema.optionalKey<Schema.Boolean>;
+                    readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                        readonly type: Schema.Literal<"media">;
+                        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                        readonly data: Schema.String;
+                        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                        readonly bytes: Schema.Int;
+                        readonly name: Schema.optionalKey<Schema.String>;
+                        readonly alt: Schema.optionalKey<Schema.String>;
+                    }>>>;
+                }>]>>;
+                readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>, Schema.Struct<{
+                readonly role: Schema.Literal<"tool">;
+                readonly content: Schema.$Array<Schema.Struct<{
+                    readonly type: Schema.Literal<"tool-result">;
+                    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                    readonly toolName: Schema.String;
+                    readonly output: Schema.Unknown;
+                    readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+                    readonly isError: Schema.optional<Schema.Boolean>;
+                    readonly providerExecuted: Schema.optionalKey<Schema.Boolean>;
+                    readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                        readonly type: Schema.Literal<"media">;
+                        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                        readonly data: Schema.String;
+                        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                        readonly bytes: Schema.Int;
+                        readonly name: Schema.optionalKey<Schema.String>;
+                        readonly alt: Schema.optionalKey<Schema.String>;
+                    }>>>;
+                }>>;
+                readonly providerOptions: Schema.optionalKey<Schema.$Record<Schema.String, Schema.Codec<Schema.Json, Schema.Json, never, never>>>;
+            }>]>;
+            readonly run: Schema.optionalKey<Schema.brand<Schema.Int, "RunOrdinal">>;
+            readonly inbox: Schema.optionalKey<Schema.brand<Schema.Trimmed, "InboxItemId">>;
+        }>, Schema.TaggedStruct<"ToolResult", {
+            readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+            readonly run: Schema.optionalKey<Schema.brand<Schema.Int, "RunOrdinal">>;
+            readonly toolName: Schema.String;
+            readonly isError: Schema.Boolean;
+            readonly encoded: Schema.Unknown;
+            readonly interception: Schema.optionalKey<Schema.Struct<{
+                readonly invocationId: Schema.brand<Schema.String, "InvocationId">;
+                readonly effectiveInput: Schema.optionalKey<Schema.Codec<Schema.Json, Schema.Json, never, never>>;
+            }>>;
+            readonly view: Schema.String;
+            readonly viewVersion: Schema.String;
+            readonly subjects: Schema.$Array<Schema.Struct<{
+                readonly kind: Schema.Trimmed;
+                readonly id: Schema.brand<Schema.Trimmed, "SubjectId">;
+                readonly label: Schema.OptionFromNullOr<Schema.String>;
+                readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
+            }>>;
+            readonly artifacts: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.brand<Schema.Trimmed, "ArtifactId">;
+                readonly kind: Schema.Literals<readonly ["image", "file"]>;
+                readonly mediaType: Schema.Trimmed;
+                readonly url: Schema.String;
+                readonly alt: Schema.OptionFromNullOr<Schema.String>;
+            }>>;
+            readonly pinned: Schema.Boolean;
+            readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly bytes: Schema.Int;
+            }>>>;
+            readonly mediaNotes: Schema.optionalKey<Schema.$Array<Schema.String>>;
+        }>, Schema.TaggedStruct<"ToolDigest", {
+            readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+            readonly version: Schema.String;
+            readonly mode: Schema.Literals<readonly ["select", "summarize"]>;
+            readonly keep: Schema.$Array<Schema.String>;
+            readonly text: Schema.String;
+            readonly digester: Schema.String;
+            readonly trigger: Schema.Literals<readonly ["write", "compaction"]>;
+        }>, Schema.TaggedStruct<"StepContext", {
+            readonly step: Schema.Int;
+            readonly run: Schema.withDecodingDefaultKey<Schema.brand<Schema.Int, "RunOrdinal">, never>;
+            readonly text: Schema.String;
+        }>, Schema.TaggedStruct<"ToolsActivated", {
+            readonly skills: Schema.$Array<Schema.String>;
+            readonly tools: Schema.$Array<Schema.String>;
+            readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+            readonly decision: Schema.OptionFromNullOr<Schema.brand<Schema.Trimmed, "DecisionId">>;
+        }>, Schema.TaggedStruct<"Compaction", {
+            readonly strategy: Schema.String;
+            readonly version: Schema.String;
+            readonly action: Schema.toTaggedUnion<"_tag", readonly [Schema.TaggedStruct<"CompactViews", {
+                readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+                readonly texts: Schema.$Array<Schema.String>;
+            }>, Schema.TaggedStruct<"Spill", {
+                readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+                readonly preview: Schema.String;
+            }>, Schema.TaggedStruct<"DropTurns", {
+                readonly throughTurn: Schema.Int;
+                readonly ledger: Schema.String;
+            }>, Schema.TaggedStruct<"Summarize", {
+                readonly keepFromTurn: Schema.Int;
+                readonly summary: Schema.String;
+            }>, Schema.TaggedStruct<"OmitMedia", {
+                readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+                readonly reason: Schema.String;
+            }>]>;
+        }>, Schema.TaggedStruct<"TurnEnded", {
+            readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed", "waiting"]>;
+            readonly reply: Schema.OptionFromNullOr<Schema.String>;
+        }>, Schema.TaggedStruct<"ToolPresentation", {
+            readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+            readonly view: Schema.String;
+            readonly viewVersion: Schema.String;
+            readonly subjects: Schema.$Array<Schema.Struct<{
+                readonly kind: Schema.Trimmed;
+                readonly id: Schema.brand<Schema.Trimmed, "SubjectId">;
+                readonly label: Schema.OptionFromNullOr<Schema.String>;
+                readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
+            }>>;
+            readonly artifacts: Schema.$Array<Schema.Struct<{
+                readonly id: Schema.brand<Schema.Trimmed, "ArtifactId">;
+                readonly kind: Schema.Literals<readonly ["image", "file"]>;
+                readonly mediaType: Schema.Trimmed;
+                readonly url: Schema.String;
+                readonly alt: Schema.OptionFromNullOr<Schema.String>;
+            }>>;
+            readonly pinned: Schema.Boolean;
+            readonly media: Schema.$Array<Schema.Struct<{
+                readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly bytes: Schema.Int;
+            }>>;
+            readonly mediaNotes: Schema.$Array<Schema.String>;
+        }>]>;
+    }>>;
+}>, Schema.TaggedStruct<"Nothing", {}>]>;
+export type ReplyStep = typeof ReplyStep.Type;

package/dist/turn/turn-phase.entity.functions.d.ts

@@ -0,0 +1,44 @@
+import { Option, Result } from "effect";
+import type { HarnessError, LogEntry, RunId, RunRef, TurnContextBody, TurnOutcomeKind } from "@xandreed/core";
+import type { ReplyStep, TurnPhase } from "./turn-phase.entity.js";
+/** What a transition returns, with the phase it moves to; or why the phase refuses it, which leaves the phase as it was. */
+export type Transition<A> = Result.Result<readonly [A, TurnPhase], HarnessError>;
+/** Start taking the message (`persistMessage`): only a waiting turn's, so once; `turn.persisted` otherwise. */
+export declare const claim: (phase: TurnPhase) => Transition<void>;
+/** The message was not recorded: it waits again, with its context entries, to be taken. */
+export declare const release: (phase: TurnPhase) => TurnPhase;
+/** The message is recorded as turn `number`: the turn is taken, and the context entries that waited for it are returned, to record next. */
+export declare const take: (number: number) => (phase: TurnPhase) => Transition<ReadonlyArray<TurnContextBody>>;
+/** A context entry: it waits for the message while the message is not taken, and is returned, to record now, once it is. */
+export declare const addContext: (body: TurnContextBody) => (phase: TurnPhase) => Transition<ReadonlyArray<TurnContextBody>>;
+/** Whether the turn-tier sections are due: once, after the message is taken and before the reply; `turn.unstarted` before. */
+export declare const sectionsDue: (phase: TurnPhase) => Transition<boolean>;
+/**
+ * A run of the step loop starts (`TurnMemory.startRun`): the turn's next
+ * run, under the turn's run id and number, its ordinal counting from 0.
+ * `turn.unstarted` before the message is taken; `turn.closed` once the
+ * reply is recorded, which ends the turn's runs.
+ */
+export declare const startRun: (id: RunId) => (phase: TurnPhase) => Transition<RunRef>;
+/**
+ * The reply, with its outcome: recorded once, after the message is taken
+ * (`Record`, the turn's number); nothing before. Once replied, a failed
+ * reply downgrades a completed or partial one (a finish that failed after
+ * it): the entries held for the closing commit are held again, the reply
+ * failed under its own id (`Hold`), or, when memory never held it, the reply
+ * is recorded again, failed. Anything else does nothing: a reply is never
+ * upgraded.
+ */
+export declare const reply: (outcome: TurnOutcomeKind) => (phase: TurnPhase) => Transition<ReplyStep>;
+/**
+ * Where entries memory records now go: once the turn replied, they are held
+ * for its closing commit after everything held before them (returned: the
+ * writer's `closing` takes them all, and `hold` keeps them once it did);
+ * before it, a reply (TurnEnded) recorded on its own is held alone, and
+ * anything else is stored as it is recorded (none).
+ */
+export declare const heldWith: (entries: ReadonlyArray<LogEntry>) => (phase: TurnPhase) => Option.Option<ReadonlyArray<LogEntry>>;
+/** The entries the writer now holds for the closing commit (`heldWith`'s), kept by a replied turn. */
+export declare const hold: (held: ReadonlyArray<LogEntry>) => (phase: TurnPhase) => TurnPhase;
+/** The turn's number, once the message is taken. */
+export declare const numberOf: (phase: TurnPhase) => Option.Option<number>;

package/dist/turn/turn-phase.entity.functions.js

@@ -0,0 +1,49 @@
+import { Match, Option, Result } from "effect";
+import { harnessError, RunOrdinal } from "@xandreed/core";
+const moved = (value, next) => Result.succeed([value, next]), persisted = Result.fail(harnessError("turn.persisted", "The user's message is already persisted")), unstarted = (what) => Result.fail(harnessError("turn.unstarted", what));
+export const claim = (phase) => Match.valueTags(phase, {
+  Waiting: ({ early }) => moved(void 0, { _tag: "Taking", early }),
+  Taking: () => persisted,
+  Taken: () => persisted,
+  Replied: () => persisted
+}), release = (phase) => phase._tag === "Taking" ? { _tag: "Waiting", early: phase.early } : phase, take = (number) => (phase) => Match.valueTags(phase, {
+  Waiting: () => unstarted("The user's message is not being persisted"),
+  Taking: ({ early }) => moved(early, { _tag: "Taken", number, sectioned: !1, runs: RunOrdinal.make(0) }),
+  Taken: () => persisted,
+  Replied: () => persisted
+}), addContext = (body) => (phase) => Match.valueTags(phase, {
+  Waiting: ({ early }) => moved([], { _tag: "Waiting", early: [...early, body] }),
+  Taking: ({ early }) => moved([], { _tag: "Taking", early: [...early, body] }),
+  Taken: () => moved([body], phase),
+  Replied: () => moved([body], phase)
+}), sectionsDue = (phase) => Match.valueTags(phase, {
+  Waiting: () => unstarted("The turn's sections are recorded after the user's message is persisted"),
+  Taking: () => unstarted("The turn's sections are recorded after the user's message is persisted"),
+  Taken: (taken) => moved(!taken.sectioned, { ...taken, sectioned: !0 }),
+  Replied: () => moved(!1, phase)
+}), startRun = (id) => (phase) => Match.valueTags(phase, {
+  Waiting: () => unstarted("A run starts after the user's message is persisted"),
+  Taking: () => unstarted("A run starts after the user's message is persisted"),
+  Taken: (taken) => moved({ id, turn: taken.number, ordinal: taken.runs }, { ...taken, runs: RunOrdinal.make(taken.runs + 1) }),
+  Replied: () => Result.fail(harnessError("turn.closed", "The turn's reply is recorded: no run starts after it"))
+});
+const nothing = { _tag: "Nothing" }, isReply = (entry) => entry.body._tag === "TurnEnded", downgraded = (held) => held.map((entry) => entry.body._tag === "TurnEnded" ? { ...entry, body: { ...entry.body, outcome: "failed" } } : entry), downgrade = (replied) => replied.held.some(isReply) ? moved({ _tag: "Hold", held: downgraded(replied.held) }, { ...replied, outcome: "failed", held: downgraded(replied.held) }) : moved({ _tag: "Record", number: replied.number }, { ...replied, outcome: "failed" });
+export const reply = (outcome) => (phase) => Match.valueTags(phase, {
+  Waiting: () => moved(nothing, phase),
+  Taking: () => moved(nothing, phase),
+  Taken: ({ number }) => moved({ _tag: "Record", number }, { _tag: "Replied", number, outcome, held: [] }),
+  Replied: (replied) => outcome === "failed" && replied.outcome !== "failed" ? downgrade(replied) : moved(nothing, phase)
+}), heldWith = (entries) => (phase) => {
+  const alone = () => Option.liftPredicate(entries, (all) => all.some(isReply));
+  return Match.valueTags(phase, {
+    Waiting: alone,
+    Taking: alone,
+    Taken: alone,
+    Replied: ({ held }) => Option.some([...held, ...entries])
+  });
+}, hold = (held) => (phase) => phase._tag === "Replied" ? { ...phase, held } : phase, numberOf = (phase) => Match.valueTags(phase, {
+  Waiting: () => Option.none(),
+  Taking: () => Option.none(),
+  Taken: ({ number }) => Option.some(number),
+  Replied: ({ number }) => Option.some(number)
+});

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

@@ -0,0 +1,13 @@
+import { Schema } from "effect";
+import { LogEntry, RunOrdinal, TurnContextBody, TurnOutcomeKind } from "@xandreed/core";
+const Early = Schema.Array(TurnContextBody);
+export const TurnPhase = Schema.Union([
+  Schema.TaggedStruct("Waiting", { early: Early }),
+  Schema.TaggedStruct("Taking", { early: Early }),
+  Schema.TaggedStruct("Taken", { number: Schema.Int, sectioned: Schema.Boolean, runs: RunOrdinal }),
+  Schema.TaggedStruct("Replied", { number: Schema.Int, outcome: TurnOutcomeKind, held: Schema.Array(LogEntry) })
+]).pipe(Schema.toTaggedUnion("_tag")), ReplyStep = Schema.Union([
+  Schema.TaggedStruct("Record", { number: Schema.Int }),
+  Schema.TaggedStruct("Hold", { held: Schema.Array(LogEntry) }),
+  Schema.TaggedStruct("Nothing", {})
+]).pipe(Schema.toTaggedUnion("_tag"));

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

@@ -0,0 +1,72 @@
+import { Effect, Option } from "effect";
+import { StepLoop, TurnEvents, TurnMemory, TurnPrompt, TurnTasks, TurnToolbox } from "@xandreed/core";
+import type { RunResult, RunTools, StepRequest, TurnError, TurnPolicy, TurnRunOptions } from "@xandreed/core";
+/**
+ * The turn services one run reads.
+ *
+ * @public
+ */
+export type TurnRunServices = TurnMemory | TurnToolbox | TurnPrompt | TurnEvents | TurnTasks;
+/** The tokens the active tools' descriptions and parameter schemas take in a request. */
+export declare const schemaTokens: (tools: RunTools, active: ReadonlyArray<string>) => number;
+/**
+ * The prompt-cache key of a conversation: `<prefix>:<conversation>`, none without a prefix.
+ *
+ * @public
+ */
+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 run is started (`TurnMemory.startRun`: its ordinal is on the
+ * run's step contexts, request headers and step events, and its dispatch
+ * check reads the header of its own run and step, so each run of a turn
+ * rebuilds its own requests), 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, 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. An optional `ModelRequestHook` runs after each
+ * fresh policy decision, before the single combined StepContext, reserves,
+ * maintenance and durable header. Its accepted patch is saved as `header.hook`;
+ * media replanning and same-step overflow reuse the frozen effective controls
+ * without invoking it again. 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. The
+ * request's `cacheKey` is the turn's (`options.cacheKey`), its `callPolicy`
+ * the `CurrentModelCallPolicy` where this runs, read once; each request
+ * header records both, and the dispatch check compares them with what the
+ * model call will read, `CurrentPromptCacheKey` and `CurrentModelCallPolicy`
+ * where the loop dispatches, so a loop that does not provide the request's
+ * `cacheKey` and `callPolicy` (`StepLoopReferences`) fails with
+ * `request.diverged` before the provider is called. Each accepted response
+ * hands the run's memory maintenance to `TurnMemory.deferAfterReply`: the
+ * turn runs it once its reply is final and sealed (`TurnMemory.afterReply`,
+ * from `finishTurn`), on the run's last accepted input, so nothing it meets
+ * can cost the reply. The run's start (`turn-start`) is its safety net,
+ * calibrated by the last stored selected response (`acceptedBefore`): what
+ * a cut or never sealed maintenance left is maintained there. A step's
+ * ceiling is the run's input ceiling, lowered to the resolved model's
+ * catalog window less its output cap (the call policy's `maxOutputTokens`,
+ * else the catalog's) when a `ModelCatalog` knows that window.
+ *
+ * @public
+ */
+export declare const stepRequestOf: <P = never>(policy: TurnPolicy<P>, options?: TurnRunOptions | undefined) => Effect.Effect<StepRequest, TurnError, TurnRunServices | P>;
+/**
+ * One run of the turn: yield first when waiting; otherwise `stepRequestOf`,
+ * then the StepLoop. Nothing runs after the loop returns: its result goes
+ * straight back to the host, and the run's maintenance waits for the turn's
+ * sealed reply (`TurnMemory.afterReply`).
+ *
+ * @public
+ */
+export declare const runTurnLoop: <P = never>(policy: TurnPolicy<P>, options?: TurnRunOptions) => Effect.Effect<RunResult, TurnError, P | TurnRunServices | StepLoop>;