@xandreed/core 0.3.0 → 0.8.0-next.0

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

@@ -0,0 +1,116 @@
+import { Context } from "effect";
+import type { Effect, Option, Scope } from "effect";
+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";
+import type { LogQuery } from "../memory/memory-log.entity.functions.js";
+import type { ArtifactRef, BuiltContext, EntryId, LogBody, LogEntry, Subject } from "../memory/memory-log.entity.js";
+import type { UserMessage } from "../turn/user-message.entity.js";
+import type { MemoryRenderRecipe } from "../turn/model-request.entity.js";
+/** A conversation's memory log for one turn: the entries stored before it, and one atomic append. */
+export interface LogHandle {
+    readonly read: Effect.Effect<ReadonlyArray<LogEntry>, HarnessError>;
+    readonly append: (entries: ReadonlyArray<LogEntry>) => Effect.Effect<void, HarnessError>;
+}
+/** One tool result as the model sees it, supplied by whoever owns the tools. */
+export interface ToolView {
+    readonly text: string;
+    readonly version: string;
+    readonly subjects: ReadonlyArray<Subject>;
+    readonly artifacts: ReadonlyArray<ArtifactRef>;
+    readonly pinned: boolean;
+}
+/** What the digester returns: the item keys to keep, or a summary. */
+export interface DigestOutcome {
+    readonly keep: ReadonlyArray<string>;
+    readonly summary: Option.Option<string>;
+}
+/** One result prepared for digestion by the tool that produced it. */
+export interface DigestTask {
+    readonly tool: string;
+    readonly version: string;
+    readonly mode: "select" | "summarize";
+    /** The tool's own digest prompt. */
+    readonly instructions: string;
+    /** The user message the digest must serve. */
+    readonly userMessage: UserMessage;
+    /** Select mode: the keyed items the digester chooses from. */
+    readonly items: ReadonlyArray<{
+        readonly key: string;
+        readonly text: string;
+    }>;
+    /** The full rendered result (summarize mode's input). */
+    readonly source: string;
+    /** The text the model will see for this outcome; None keeps the original view. */
+    readonly apply: (outcome: DigestOutcome) => Option.Option<string>;
+}
+/** Tool views by name — the memory strategy applies them without knowing any tool. */
+export interface ToolViews {
+    readonly view: (tool: string, encoded: unknown, params: unknown, isError: boolean) => Effect.Effect<ToolView>;
+    /** The older-turn form; None keeps the write-time view. */
+    readonly compact: (tool: string, encoded: unknown, params: unknown) => Effect.Effect<Option.Option<string>>;
+    /** The tool's digest of this result, when it declares one. */
+    readonly digest: (tool: string, encoded: unknown, params: unknown, userMessage: UserMessage) => Effect.Effect<Option.Option<DigestTask>>;
+}
+declare const ResultDigester_base: Context.ServiceClass<ResultDigester, "efferent/ResultDigester", {
+    readonly id: string;
+    readonly version: string;
+    readonly digest: (task: DigestTask) => Effect.Effect<DigestOutcome, HarnessError>;
+}>;
+/** Runs a tool's digest prompt (see `DigestDefinition`). Read, when present, from where the session is opened. */
+export declare class ResultDigester extends ResultDigester_base {
+}
+/** Read-only memory for tools, sections, matchers and reactions. */
+export interface MemoryReader {
+    readonly turn: Effect.Effect<number>;
+    readonly entries: Effect.Effect<ReadonlyArray<LogEntry>>;
+    readonly query: (query: LogQuery) => Effect.Effect<ReadonlyArray<LogEntry>>;
+    readonly subjects: (kinds: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<Subject>>;
+    readonly resolve: (id: EntryId) => Effect.Effect<Option.Option<LogEntry>>;
+    readonly transcript: (fidelity: "raw" | "model" | "reference") => Effect.Effect<ReadonlyArray<AgentMessage>>;
+}
+export interface MaintainSignal {
+    readonly phase: "turn-start" | "step";
+    readonly lastUsage: Option.Option<TokenUsage>;
+    /** Tokens available to the messages (system and tool schemas already deducted). */
+    readonly budgetTokens: number;
+    readonly views: ToolViews;
+}
+export interface MemorySession extends MemoryReader {
+    readonly strategy: {
+        readonly id: string;
+        readonly version: string;
+    };
+    /** The pure render recipe of this session, saved with every outgoing request for version-independent replay. */
+    readonly renderRecipe: (stepContext: "tail" | "none") => Effect.Effect<MemoryRenderRecipe>;
+    readonly record: (bodies: ReadonlyArray<LogBody>, step: number) => Effect.Effect<ReadonlyArray<LogEntry>, HarnessError>;
+    /** The loop's appended messages → Message and ToolResult entries (views, and digests the strategy asks for, at write time). */
+    readonly recordTail: (tail: ReadonlyArray<AgentMessage>, views: ToolViews, step: number) => Effect.Effect<ReadonlyArray<LogEntry>, HarnessError>;
+    /** The only place compaction is decided; the decision is recorded before it applies. */
+    readonly maintain: (signal: MaintainSignal) => Effect.Effect<ReadonlyArray<LogEntry>, HarnessError>;
+    /** A pure fold of the log: what the next request sends. */
+    readonly build: (request: {
+        readonly stepContext: "tail" | "none";
+    }) => Effect.Effect<BuiltContext, HarnessError>;
+}
+declare const ConversationMemory_base: Context.ServiceClass<ConversationMemory, "efferent/ConversationMemory", {
+    readonly strategy: {
+        readonly id: string;
+        readonly version: string;
+    };
+    /**
+     * Open the conversation's session for one run over its log (the turn's
+     * memory events). A strategy reads what it needs per turn (a
+     * ResultDigester, a summarizer's UtilityLlm) with `Effect.serviceOption`
+     * from the environment it is opened in.
+     */
+    readonly open: (scope: {
+        readonly conversation: ConversationId;
+        readonly runId: string;
+        readonly log: LogHandle;
+    }) => Effect.Effect<MemorySession, HarnessError, Scope.Scope>;
+}>;
+/** STRATEGY: how memory is kept, compacted and rebuilt. Swap this plugin to swap memory. */
+export declare class ConversationMemory extends ConversationMemory_base {
+}
+export {};

package/dist/ports/memory.port.js

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

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

@@ -1,7 +1,7 @@
 import { Context } from "effect";
 import type { Effect } from "effect";
 import type { ModelCatalogEntry } from "../domain/model-catalog.entity.js";
-declare const ModelCatalog_base: Context.TagClass<ModelCatalog, "@xandreed/core/ModelCatalog", {
+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. */

package/dist/ports/model-catalog.port.js

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

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

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { HarnessError } from "../harness/plugin.entity.js";
+declare const PermissionGrants_base: Context.ServiceClass<PermissionGrants, "efferent/PermissionGrants", {
+    readonly grants: Effect.Effect<ReadonlySet<string>, HarnessError>;
+}>;
+/** The permissions a run holds; skills and tools needing others are never activated. */
+export declare class PermissionGrants extends PermissionGrants_base {
+}
+export {};

package/dist/ports/permission.port.js

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

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

@@ -0,0 +1,28 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { ConversationId } from "../domain/message.entity.js";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { 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";
+declare const RunContext_base: Context.ServiceClass<RunContext, "efferent/RunContext", {
+    readonly conversation: ConversationId;
+    /** The session the turn runs in, as its owner names it. */
+    readonly session: SessionAddress;
+    readonly runId: string;
+    readonly userMessage: UserMessage;
+    readonly memory: MemoryReader;
+    readonly events: TurnEventsService;
+    readonly tasks: TurnTasksService;
+    /** Host-initiated skill activation (e.g. a handler that needs another skill next step). */
+    readonly activate: (skills: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    /** Wait until every journal write queued so far is stored (before an externally visible action). */
+    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 current run, as tools, sections and run layers see it. Provided by the turn. */
+export declare class RunContext extends RunContext_base {
+}
+export {};

package/dist/ports/run-context.port.js

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

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

@@ -0,0 +1,25 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { ConversationId } from "../domain/message.entity.js";
+import type { LeaseExpired, RevisionConflict, SessionCommit, SessionCommitted, SessionExists, SessionHead, SessionHeader, SessionListQuery, SessionLogError, SessionLogEvent, SessionMissing, SessionReadQuery } from "../session/session-log.entity.js";
+declare const SessionLog_base: Context.ServiceClass<SessionLog, "efferent/SessionLog", {
+    /** Create an empty session (seq 0, revision 0). A child's parent must exist. */
+    readonly create: (header: SessionHeader) => Effect.Effect<SessionHead, SessionExists | SessionMissing | SessionLogError>;
+    readonly head: (id: ConversationId) => Effect.Effect<SessionHead, SessionMissing | SessionLogError>;
+    readonly list: (query: SessionListQuery) => Effect.Effect<ReadonlyArray<SessionHead>, SessionLogError>;
+    readonly read: (id: ConversationId, query: SessionReadQuery) => Effect.Effect<ReadonlyArray<SessionLogEvent>, SessionMissing | SessionLogError>;
+    /** Append events and/or replace the state, atomically, when the revision and the clock allow. */
+    readonly commit: (id: ConversationId, commit: SessionCommit) => Effect.Effect<SessionCommitted, RevisionConflict | LeaseExpired | SessionMissing | SessionLogError>;
+    /** Remove a session, its events and its children. Removing a missing session does nothing. */
+    readonly remove: (id: ConversationId) => Effect.Effect<void, SessionLogError>;
+}>;
+/**
+ * STORAGE: the session log a host provides — one append-only log per
+ * 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`.
+ */
+export declare class SessionLog extends SessionLog_base {
+}
+export {};

package/dist/ports/session-log.port.js

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

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

@@ -0,0 +1,141 @@
+import { Context } from "effect";
+import type { Effect, Option, Scope, Stream } from "effect";
+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";
+/** One event to record; the writer stamps the turn (or none, outside a turn). */
+export interface TurnDraft {
+    readonly kind: string;
+    readonly data: JsonObject;
+}
+/** What a check-then-append decides: the events to record and the caller's result. */
+export interface Decision<A> {
+    readonly drafts: ReadonlyArray<TurnDraft>;
+    readonly result: A;
+}
+/** A decision's result and the events it recorded, as stored. */
+export interface Decided<A> {
+    readonly result: A;
+    readonly events: ReadonlyArray<SessionLogEvent>;
+}
+/**
+ * The open turn's only way to write. Writes are queued and stored in queue
+ * order by one writer, consecutive appends in one commit, each commit
+ * guarded by the session's revision and the turn's lease: a write the
+ * session no longer accepts (cancelled, reaped, removed) closes the writer,
+ * and every later write fails with `turn.closed`.
+ */
+export interface TurnWriter {
+    readonly admitted: AdmittedTurn;
+    /** The `turn.started` event that opened the turn. */
+    readonly started: SessionLogEvent;
+    /** The session's events before this turn (a fork's parent first), of the given kinds: what memory is rebuilt from. */
+    readonly history: (kinds: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<SessionLogEvent>, HarnessError>;
+    /**
+     * A fresh durable snapshot including this turn (a fork's inherited history first). Flush queued writes before reading.
+     * With `after`, only this session's own events stored after that seq: the inherited history precedes them all.
+     */
+    readonly snapshot: (kinds: ReadonlyArray<string>, after?: number) => Effect.Effect<ReadonlyArray<SessionLogEvent>, HarnessError>;
+    /** Queue events; returns once queued. */
+    readonly append: (drafts: ReadonlyArray<TurnDraft>) => Effect.Effect<void, HarnessError>;
+    /**
+     * Run `op` in queue order (after everything queued before it). When
+     * someone else closes the turn meanwhile, `op` is interrupted and the
+     * write fails with `turn.closed`.
+     */
+    readonly write: <A, E>(op: Effect.Effect<A, E>) => Effect.Effect<A, E | HarnessError>;
+    /**
+     * Check, then append, atomically: `decide` sees the events others wrote
+     * during this turn and says what to record. When someone else writes
+     * before the commit, it decides again with their events.
+     */
+    readonly transact: <A, E>(decide: (foreign: ReadonlyArray<SessionLogEvent>) => Effect.Effect<Decision<A>, E>) => Effect.Effect<Decided<A>, E | HarnessError>;
+    /** Wait until everything queued so far is stored. */
+    readonly flush: Effect.Effect<void, HarnessError>;
+    /**
+     * Close the turn: `turn.ended` is committed after every write queued
+     * before it. It is admitted like a write (so it waits while one waits for
+     * room in a full queue); from then on `append`, `write` and `transact` are
+     * 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.
+     */
+    readonly end: (ending: TurnEnding) => Effect.Effect<{
+        readonly pending: number;
+    }, HarnessError>;
+    /** Completes when someone else closed the turn; never when it ends by `end`. */
+    readonly closed: Effect.Effect<TurnClosed>;
+}
+declare const Sessions_base: Context.ServiceClass<Sessions, "efferent/Sessions", {
+    readonly create: (input: {
+        readonly owner: string;
+        readonly id?: ConversationId;
+        readonly origin?: string;
+        readonly meta?: JsonObject;
+    }) => Effect.Effect<SessionView, SessionExists | SessionLogError>;
+    /**
+     * A child session: with `inherit`, its history starts from the parent's
+     * last closed turn (a fork); without, it starts empty (a spawn).
+     */
+    readonly fork: (parent: SessionAddress, input: {
+        readonly id?: ConversationId;
+        readonly origin: string;
+        readonly meta?: JsonObject;
+        readonly inherit: boolean;
+    }) => Effect.Effect<SessionView, SessionExists | SessionMissing | SessionLogError>;
+    readonly get: (address: SessionAddress) => Effect.Effect<SessionView, SessionMissing | SessionLogError>;
+    readonly list: (query: {
+        readonly owner: string;
+        readonly limit?: number;
+        readonly before?: SessionListCursor;
+        readonly parent?: ConversationId;
+    }) => Effect.Effect<SessionPage, SessionLogError>;
+    /** Remove a session and its children; an open turn on this instance is closed. */
+    readonly remove: (address: SessionAddress) => Effect.Effect<void, SessionMissing | SessionLogError>;
+    readonly read: (address: SessionAddress, query?: {
+        readonly after?: number;
+        readonly kinds?: ReadonlyArray<string>;
+        readonly limit?: number;
+    }) => Effect.Effect<ReadonlyArray<SessionLogEvent>, SessionMissing | SessionLogError>;
+    /** A signal after each commit this instance makes to the session (followers poll for the others). */
+    readonly changes: (address: SessionAddress) => Stream.Stream<void>;
+    /** The turn begun with this key, if any. */
+    readonly lookup: (address: SessionAddress, key: string) => Effect.Effect<Option.Option<number>, SessionMissing | SessionLogError>;
+    /** Check, then append outside a turn (a user's action on a page, a setting): decided again on a conflict. */
+    readonly transact: <A, E>(address: SessionAddress, decide: (view: SessionView) => Effect.Effect<Decision<A>, E>) => Effect.Effect<Decided<A>, E | ReservedKind | SessionMissing | SessionLogError>;
+    /** End exactly `turn` as cancelled, if it is the open one. */
+    readonly cancel: (address: SessionAddress, turn: number) => Effect.Effect<{
+        readonly cancelled: boolean;
+        readonly pending: number;
+    }, 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).
+     */
+    readonly begin: (address: SessionAddress, input: BeginTurn) => Effect.Effect<TurnWriter, SessionBusy | TurnDuplicate | KeyConflict | NothingPending | 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). */
+    readonly drain: <E, R>(address: SessionAddress, run: (writer: TurnWriter) => Effect.Effect<void, E, R>, options?: {
+        readonly maxTurns?: number;
+    }) => Effect.Effect<{
+        readonly turns: number;
+    }, SessionMissing | SessionLogError, R>;
+}>;
+/**
+ * CONSUMPTION: sessions as hosts and turns use them, over the SessionLog a
+ * host provides. One turn is open per session at a time — a second begin is
+ * `SessionBusy` — and a turn's writes are refused once it is closed, on any
+ * instance. The inbox holds deliveries (a background task's result) for the
+ * turns that follow: whoever closes a turn, and whoever delivers, drains it.
+ * Reads never write: loading or following a session runs nothing.
+ */
+export declare class Sessions extends Sessions_base {
+}
+export {};

package/dist/ports/sessions.port.js

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

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

@@ -1,61 +1,23 @@
-import { Context, Option, Schema } from "effect";
-import type { Effect } from "effect";
-declare const EngineSettings_base: Schema.Class<EngineSettings, {
-    model: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    codeModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    fastModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    fallbackModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    sandbox: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
-    viMode: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
-    maxAttempts: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
-    budgetMillis: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
+import { Context, Effect, Option, Schema } from "effect";
+declare const EngineSettings_base: Schema.Class<EngineSettings, Schema.Struct<{
+    readonly model: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly codeModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly fastModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly fallbackModel: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<string, string, never, never>>>;
+    readonly sandbox: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<boolean, boolean, never, never>>>;
+    readonly viMode: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<boolean, boolean, never, never>>>;
+    readonly maxAttempts: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<number, number, never, never>>>;
+    readonly budgetMillis: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<number, number, never, never>>>;
     /** Selected after the model because the accepted levels are model-specific. */
-    reasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
-    codeReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
-    fastReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
-}, Schema.Struct.Encoded<{
-    model: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    codeModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    fastModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    fallbackModel: Schema.PropertySignature<":", Option.Option<string>, never, "?:", string | undefined, true, never>;
-    sandbox: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
-    viMode: Schema.PropertySignature<":", Option.Option<boolean>, never, "?:", boolean | undefined, true, never>;
-    maxAttempts: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
-    budgetMillis: Schema.PropertySignature<":", Option.Option<number>, never, "?:", number | undefined, true, never>;
-    /** Selected after the model because the accepted levels are model-specific. */
-    reasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
-    codeReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
-    fastReasoningEffort: Schema.PropertySignature<":", Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">, never, "?:", "none" | "low" | "medium" | "high" | "xhigh" | "max" | undefined, true, never>;
-}>, never, {
-    readonly model?: Option.Option<string>;
-} & {
-    readonly codeModel?: Option.Option<string>;
-} & {
-    readonly fastModel?: Option.Option<string>;
-} & {
-    readonly fallbackModel?: Option.Option<string>;
-} & {
-    readonly sandbox?: Option.Option<boolean>;
-} & {
-    readonly viMode?: Option.Option<boolean>;
-} & {
-    readonly maxAttempts?: Option.Option<number>;
-} & {
-    readonly budgetMillis?: Option.Option<number>;
-} & {
-    readonly reasoningEffort?: Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">;
-} & {
-    readonly codeReasoningEffort?: Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">;
-} & {
-    readonly fastReasoningEffort?: Option.Option<"none" | "low" | "medium" | "high" | "xhigh" | "max">;
-}, {}, {}>;
+    readonly reasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+    readonly codeReasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+    readonly fastReasoningEffort: Schema.withConstructorDefault<Schema.OptionFromOptional<Schema.Codec<"none" | "low" | "medium" | "high" | "xhigh" | "max", "none" | "low" | "medium" | "high" | "xhigh" | "max", never, never>>>;
+}>, {}>;
 export declare class EngineSettings extends EngineSettings_base {
 }
-declare const SettingsError_base: Schema.TaggedErrorClass<SettingsError, "SettingsError", {
-    readonly _tag: Schema.tag<"SettingsError">;
-} & {
-    message: typeof Schema.String;
-}>;
+declare const SettingsError_base: Schema.Class<SettingsError, Schema.TaggedStruct<"SettingsError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
 export declare class SettingsError extends SettingsError_base {
 }
 /** The three model roles a selection can be persisted under. */
@@ -64,7 +26,7 @@ export type ModelRole = "general" | "code" | "fast";
  *  typo can never land a dead key in the user's config. */
 export declare const SETTINGS_KEYS: readonly ["fallbackModel", "sandbox", "viMode", "maxAttempts", "budgetMillis", "reasoningEffort", "codeReasoningEffort", "fastReasoningEffort"];
 export type SettingsKey = (typeof SETTINGS_KEYS)[number];
-declare const SettingsStore_base: Context.TagClass<SettingsStore, "@xandreed/core/SettingsStore", {
+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. */

package/dist/ports/settings-store.port.js

@@ -1,6 +1,6 @@
-import { Context, Option, Schema } from "effect";
+import { Context, Effect, Option, Schema } from "effect";
 import { ReasoningEffort } from "../domain/model-call-policy.entity.js";
-const optionField = (schema) => Schema.optionalWith(schema, { as: "Option" }).pipe(Schema.withConstructorDefault(Option.none));
+const optionField = (schema) => Schema.OptionFromOptional(schema).pipe(Schema.withConstructorDefault(Effect.succeed(Option.none())));
 
 export class EngineSettings extends Schema.Class("EngineSettings")({
   model: optionField(Schema.String),
@@ -32,5 +32,5 @@ export const SETTINGS_KEYS = [
   "fastReasoningEffort"
 ];
 
-export class SettingsStore extends Context.Tag("@xandreed/core/SettingsStore")() {
+export class SettingsStore extends Context.Service()("@xandreed/core/SettingsStore") {
 }

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

@@ -1,30 +1,18 @@
 import { Context, Schema } from "effect";
 import type { Effect } from "effect";
-declare const ShellError_base: Schema.TaggedErrorClass<ShellError, "ShellError", {
-    readonly _tag: Schema.tag<"ShellError">;
-} & {
-    message: typeof Schema.String;
-}>;
+declare const ShellError_base: Schema.Class<ShellError, Schema.TaggedStruct<"ShellError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
 export declare class ShellError extends ShellError_base {
 }
-declare const ShellResult_base: Schema.Class<ShellResult, {
-    stdout: typeof Schema.String;
-    stderr: typeof Schema.String;
-    exitCode: typeof Schema.Number;
-}, Schema.Struct.Encoded<{
-    stdout: typeof Schema.String;
-    stderr: typeof Schema.String;
-    exitCode: typeof Schema.Number;
-}>, never, {
-    readonly stdout: string;
-} & {
-    readonly stderr: string;
-} & {
-    readonly exitCode: number;
-}, {}, {}>;
+declare const ShellResult_base: Schema.Class<ShellResult, Schema.Struct<{
+    readonly stdout: Schema.String;
+    readonly stderr: Schema.String;
+    readonly exitCode: Schema.Number;
+}>, {}>;
 export declare class ShellResult extends ShellResult_base {
 }
-declare const Shell_base: Context.TagClass<Shell, "@xandreed/core/Shell", {
+declare const Shell_base: Context.ServiceClass<Shell, "@xandreed/core/Shell", {
     readonly exec: (command: string, options?: {
         readonly cwd?: string;
         readonly timeoutMs?: number;

package/dist/ports/shell.port.js

@@ -12,5 +12,5 @@ export class ShellResult extends Schema.Class("ShellResult")({
 }) {
 }
 
-export class Shell extends Context.Tag("@xandreed/core/Shell")() {
+export class Shell extends Context.Service()("@xandreed/core/Shell") {
 }

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

@@ -0,0 +1,85 @@
+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 { HarnessError } from "../harness/plugin.entity.js";
+import type { LogEntry } from "../memory/memory-log.entity.js";
+import type { CompletionVerdict } from "../turn/turn-event.entity.js";
+import type { InitialBatch, StepInfo, ToolChoice } from "./capability.port.js";
+import type { RunTools } from "./tool-registry.port.js";
+import type { TurnEventsService, TurnTasksService } from "./turn-events.port.js";
+export interface LoopLimits {
+    /** A ceiling, not a target: a run ends when the model stops calling tools. */
+    readonly maxSteps: number;
+    readonly toolConcurrency: number;
+    readonly streaming: boolean;
+    /** A model stop does not end the run while the completion verdict is incomplete. */
+    readonly requireCompletion: boolean;
+}
+/** Host wording for the loop's own corrective turns. */
+export interface Correctives {
+    readonly malformed: (tools: ReadonlyArray<string>, description: string) => string;
+    readonly incomplete: string;
+}
+/** Everything one provider request needs, prepared by the turn. */
+export interface StepPlan {
+    /** The step's model, resolved once for the step (`resolveModelRequest`); None: the LanguageModel in the turn's services. */
+    readonly model: Option.Option<LanguageModel.LanguageModel>;
+    readonly system: string;
+    readonly messages: ReadonlyArray<AgentMessage>;
+    readonly toolChoice: Option.Option<ToolChoice>;
+}
+export interface StepRequest {
+    readonly tools: RunTools;
+    /** What the tool handlers run with: the turn's services (its LanguageModel included) and the registry's handlers. */
+    readonly handlers: Context.Context<never>;
+    readonly limits: LoopLimits;
+    /** A host-planned first batch, run as step zero without a provider call. */
+    readonly initial: Option.Option<InitialBatch>;
+    readonly plan: (step: StepInfo) => Effect.Effect<StepPlan, HarnessError>;
+    /**
+     * Validate an actual dispatch against a fresh durable derivation. Run immediately before each provider attempt,
+     * including a streaming fallback; a failed check fails the step (a streamed step does not fall back).
+     */
+    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>;
+    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>;
+}
+export interface ModelDispatch {
+    readonly prompt: Prompt.Prompt;
+    readonly tools: ReadonlyArray<Tool.Any>;
+    readonly toolChoice: unknown;
+    readonly model: LanguageModel.LanguageModel;
+}
+export interface RunResult {
+    readonly outcome: "completed" | "partial";
+    readonly reason: "completed" | "step-cap" | "degenerate-loop";
+    readonly text: string;
+    readonly steps: number;
+}
+declare const StepLoop_base: Context.ServiceClass<StepLoop, "efferent/StepLoop", {
+    readonly id: string;
+    readonly version: string;
+    readonly run: (request: StepRequest) => Effect.Effect<RunResult, HarnessError>;
+}>;
+/**
+ * THE step loop: iterate provider steps until the model stops, the
+ * completion verdict holds, or a limit is hit. Contract (see
+ * `stepLoopConformance`): per step `step.started` < `tool.*` < `step.ended`
+ * (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.
+ * 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.
+ */
+export declare class StepLoop extends StepLoop_base {
+}
+export {};

package/dist/ports/step-loop.port.js

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