@xandreed/core 0.3.0 → 0.8.0-next.0

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

@@ -0,0 +1,59 @@
+import { Context } from "effect";
+import type { Effect, Option } from "effect";
+import type { ConversationId } from "../domain/message.entity.js";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { JsonObject, SessionExists, SessionLogError, SessionMissing } from "../session/session-log.entity.js";
+import type { SessionAddress } from "../session/sessions.entity.js";
+import type { TaskMissing, TaskMode, TaskRefused, TaskView } from "../session/tasks.entity.js";
+import type { TurnWriter } from "./sessions.port.js";
+import type { TurnOutcome } from "./turn.port.js";
+declare const Tasks_base: Context.ServiceClass<Tasks, "efferent/Tasks", {
+    readonly start: (parent: SessionAddress, input: {
+        /** Stable across retries: starting the same task twice starts it once. */
+        readonly taskId?: ConversationId;
+        readonly instructions: string;
+        readonly mode: TaskMode;
+        readonly meta?: JsonObject;
+    }) => Effect.Effect<TaskView, TaskRefused | SessionExists | SessionMissing | SessionLogError>;
+    readonly status: (parent: SessionAddress, taskId: string) => Effect.Effect<TaskView, TaskMissing | SessionMissing | SessionLogError>;
+    readonly list: (parent: SessionAddress) => Effect.Effect<ReadonlyArray<TaskView>, SessionMissing | SessionLogError>;
+    /** Stop a task: its child's turn is cancelled and nothing is delivered. */
+    readonly cancel: (parent: SessionAddress, taskId: string) => Effect.Effect<boolean, TaskMissing | SessionMissing | SessionLogError>;
+    /** Deliver finished results a runner lost, and start tasks that never ran. */
+    readonly reconcile: (parent: SessionAddress) => Effect.Effect<{
+        readonly delivered: number;
+        readonly started: number;
+    }, SessionMissing | SessionLogError>;
+}>;
+/**
+ * Background tasks of a session. A task is one turn of a child session: a
+ * fork (its history is the conversation so far) or a spawn (it starts
+ * empty); the child's id is the task's. Starting records `task.started` in
+ * the parent and hands the work to the host's TaskRunner; when the child's
+ * turn ends, its result is delivered to the parent's inbox (once) and the
+ * parent is drained, so it reacts after the answer in flight. `reconcile`
+ * finishes what a lost runner left undone; its caller drains.
+ */
+export declare class Tasks extends Tasks_base {
+}
+declare const TaskRunner_base: Context.ServiceClass<TaskRunner, "efferent/TaskRunner", {
+    readonly run: (work: (deadline: Option.Option<number>) => Effect.Effect<void>) => Effect.Effect<void>;
+}>;
+/**
+ * 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.
+ */
+export declare class TaskRunner extends TaskRunner_base {
+}
+declare const TaskExecutor_base: Context.ServiceClass<TaskExecutor, "efferent/TaskExecutor", {
+    /** Run the child's turn on its writer (the tasks plugin ends it). */
+    readonly turn: (writer: TurnWriter, task: TaskView) => Effect.Effect<TurnOutcome, HarnessError>;
+    /** Run the parent's inbox turn on its writer. */
+    readonly react: (writer: TurnWriter) => Effect.Effect<void, HarnessError>;
+}>;
+/** How the host runs the turns tasks need: the child's one turn, and the parent's reaction to results. */
+export declare class TaskExecutor extends TaskExecutor_base {
+}
+export {};

package/dist/ports/tasks.port.js

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+
+export class Tasks extends Context.Service()("efferent/Tasks") {
+}
+
+export class TaskRunner extends Context.Service()("efferent/TaskRunner") {
+}
+
+export class TaskExecutor extends Context.Service()("efferent/TaskExecutor") {
+}

package/dist/ports/tool-registry.port.d.ts

@@ -0,0 +1,53 @@
+import { Context } from "effect";
+import type { Effect, Option, Scope } from "effect";
+import type { Tool, Toolkit } from "effect/ai";
+import type { DecisionRecord } from "../decision-record.entity.js";
+import type { CapabilityCatalog } from "../harness/capability.entity.js";
+import type { SkillDefinition } from "../harness/capability.entity.js";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { ActivationSource } from "../memory/memory-log.entity.js";
+import type { UserMessage } from "../turn/user-message.entity.js";
+import type { MemorySession, ToolViews } from "./memory.port.js";
+import type { RunContext } from "./run-context.port.js";
+/**
+ * What the pre-turn matcher chose, before anything is recorded: `match`
+ * writes nothing, so it can run beside other pre-turn work (and be dropped
+ * when the turn ends early); `apply` activates, records and publishes it.
+ */
+export interface SkillMatch {
+    readonly userMessage: UserMessage;
+    /** Skills the matcher chose that are not loaded yet. */
+    readonly skills: ReadonlyArray<string>;
+    readonly probabilities: Option.Option<Readonly<Record<string, number>>>;
+    /** The decision as matched; None without a matcher. `apply` records it with its final validation. */
+    readonly record: Option.Option<DecisionRecord>;
+}
+/** The tools of one run: the full set is fixed at run start; the active set only grows. */
+export interface RunTools {
+    readonly toolkit: Toolkit.Toolkit<Record<string, Tool.Any>>;
+    readonly handlers: Context.Context<never>;
+    /** Active tool names in activation order. */
+    readonly active: Effect.Effect<ReadonlyArray<string>>;
+    readonly activate: (skills: ReadonlyArray<string>, source: ActivationSource) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    /** Ask the matcher, without writing anything. */
+    readonly match: (userMessage: UserMessage) => Effect.Effect<SkillMatch, HarnessError>;
+    /** Always-on skills plus a match: activated, recorded as a decision, seeded as a load_skill exchange. */
+    readonly apply: (match: SkillMatch) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    /** `match` then `apply`. */
+    readonly select: (userMessage: UserMessage) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    readonly views: ToolViews;
+    readonly pollable: ReadonlyArray<string>;
+    readonly skills: ReadonlyArray<SkillDefinition>;
+}
+declare const ToolRegistry_base: Context.ServiceClass<ToolRegistry, "efferent/ToolRegistry", {
+    readonly catalog: CapabilityCatalog;
+    /**
+     * Open the tools of one run. The handlers run with the services of where
+     * it is opened (host services, run layers, RunContext), captured at open;
+     * an IntentMatcher, ActionPolicy and PermissionGrants there are used.
+     */
+    readonly open: (session: MemorySession) => Effect.Effect<RunTools, HarnessError, RunContext | Scope.Scope>;
+}>;
+export declare class ToolRegistry extends ToolRegistry_base {
+}
+export {};

package/dist/ports/tool-registry.port.js

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

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

@@ -0,0 +1,23 @@
+import { Context } from "effect";
+import type { Effect } from "effect";
+import type { SessionAddress, TurnRefused } from "../session/sessions.entity.js";
+/** The turn a host is asked to admit. */
+export interface TurnToAdmit {
+    readonly session: SessionAddress;
+    readonly origin: "user" | "inbox";
+    readonly runId: string;
+    readonly key: string;
+}
+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>;
+}>;
+/**
+ * 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.
+ */
+export declare class TurnAdmission extends TurnAdmission_base {
+}
+export {};

package/dist/ports/turn-admission.port.js

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

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

@@ -0,0 +1,55 @@
+import { Context } from "effect";
+import type { Effect, Option, Scope } from "effect";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { TurnEvent } from "../turn/turn-event.entity.js";
+/**
+ * How a subscription receives events.
+ * - `inline` (default): the handler runs before `publish` returns, so the
+ *   state it changes is visible to the next step; its failure fails the publisher.
+ * - `background`: events are queued (bounded, in order) for the handler's own
+ *   fiber, so the publisher never waits on it. The turn drains every
+ *   background subscription before it ends; a handler failure fails the
+ *   next delivery to it and the drain.
+ */
+export interface SubscribeOptions {
+    readonly mode?: "inline" | "background";
+    /** Background queue size; publishing waits when it is full. */
+    readonly capacity?: number;
+}
+/**
+ * The turn's event bus. Publication is ordered: subscribers are served in
+ * subscription order, depth-first (a handler may publish in turn, up to a
+ * depth cap). Inline handlers run before `publish` returns; background ones
+ * are queued. Background work that is not a reaction belongs in `TurnTasks`.
+ */
+export interface TurnEventsService {
+    readonly publish: (event: TurnEvent) => Effect.Effect<void, HarnessError>;
+    /** Active until the caller's scope closes. `select` narrows and decodes. */
+    readonly subscribe: <E, R>(select: (event: TurnEvent) => Option.Option<E>, handle: (event: E) => Effect.Effect<void, HarnessError, R>, options?: SubscribeOptions) => Effect.Effect<void, never, R | Scope.Scope>;
+    /** Wait until every background subscription has handled what was published to it. */
+    readonly drain: Effect.Effect<void, HarnessError>;
+    /** Background deliveries so far: a caller can tell whether a drain left new work. */
+    readonly activity: Effect.Effect<number>;
+}
+/**
+ * Background work of one turn. Tasks run in the turn's scope: the turn
+ * awaits them before it ends and interrupts them when it fails.
+ */
+export interface TurnTasksService {
+    readonly fork: <R>(tag: string, task: Effect.Effect<void, HarnessError, R>) => Effect.Effect<void, never, R>;
+    /** True while any task with this tag is still running. */
+    readonly pending: (tag: string) => Effect.Effect<boolean>;
+    /** Join every task with one of these tags (all tasks when empty). */
+    readonly await: (tags: ReadonlyArray<string>) => Effect.Effect<void, HarnessError>;
+    /** Tasks forked so far: a caller can tell whether joining them started more. */
+    readonly activity: Effect.Effect<number>;
+}
+declare const TurnEvents_base: Context.ServiceClass<TurnEvents, "efferent/TurnEvents", TurnEventsService>;
+export declare class TurnEvents extends TurnEvents_base {
+}
+declare const TurnTasks_base: Context.ServiceClass<TurnTasks, "efferent/TurnTasks", TurnTasksService>;
+export declare class TurnTasks extends TurnTasks_base {
+}
+/** One subscription, ready to attach to a turn's bus (see `onTool`, `onEvent`). */
+export type Subscription<R> = (events: TurnEventsService) => Effect.Effect<void, never, R | Scope.Scope>;
+export {};

package/dist/ports/turn-events.port.js

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

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

@@ -0,0 +1,101 @@
+import { Context } from "effect";
+import type { Effect, Option } from "effect";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { MemoryReader, MemorySession } from "./memory.port.js";
+import type { TurnWriter } from "./sessions.port.js";
+import type { LoopLimits } from "./step-loop.port.js";
+import type { RunTools } from "./tool-registry.port.js";
+import type { TurnOutcome } from "./turn.port.js";
+import type { LogEntry } from "../memory/memory-log.entity.js";
+import type { ModelRequestHeader } from "../turn/model-request.entity.js";
+import type { SessionLogEvent } from "../session/session-log.entity.js";
+/** A turn-context message the model sees this turn (e.g. the user's intent). */
+export interface TurnContextEntry {
+    readonly id: string;
+    readonly version: string;
+    readonly text: string;
+}
+/** What storage holds of a turn's requests: what a dispatch is checked against. */
+export interface RequestSnapshot {
+    /** The memory entries, in log order (a fork's inherited history first), decoded from the stored memory events. */
+    readonly entries: ReadonlyArray<LogEntry>;
+    /** This run's stored request headers (`request.prepared`), in log order. */
+    readonly requests: ReadonlyArray<SessionLogEvent>;
+}
+declare const TurnMemory_base: Context.ServiceClass<TurnMemory, "efferent/TurnMemory", MemoryReader & {
+    readonly strategy: {
+        readonly id: string;
+        readonly version: string;
+    };
+    readonly session: MemorySession;
+    /** Record and flush a request's reconstruction header before dispatch. */
+    readonly prepareRequest: (header: ModelRequestHeader) => Effect.Effect<void, HarnessError>;
+    /**
+     * Flush, then read what storage holds, never the memory session's state:
+     * the history memory was opened over (read once, at open), and this
+     * turn's events from its start, each read taking only the events stored
+     * after the last one read.
+     */
+    readonly requestSnapshot: Effect.Effect<RequestSnapshot, HarnessError>;
+    /** The turn's number; fails with `turn.unstarted` before `persistMessage`. */
+    readonly number: Effect.Effect<number, HarnessError>;
+    /**
+     * Record TurnStarted, then publish `turn.started`, and return the turn's
+     * number. Once: a second call fails. Anything built before it (a host
+     * layer, a matcher's history) sees only earlier turns.
+     */
+    readonly persistMessage: Effect.Effect<number, HarnessError>;
+    /**
+     * Record a TurnContext entry. Before `persistMessage` (a plugin or a host
+     * layer built with the turn) it waits, and is recorded right after the
+     * message: the turn's entries follow its TurnStarted.
+     */
+    readonly context: (entry: TurnContextEntry) => Effect.Effect<void, HarnessError>;
+    /** Record TurnEnded, then publish `turn.ended`. Once; a no-op when the message was never persisted. */
+    readonly persistReply: (outcome: TurnOutcome) => Effect.Effect<void, HarnessError>;
+}>;
+/** The turn's memory session, and the records that open and close the turn. */
+export declare class TurnMemory extends TurnMemory_base {
+}
+declare const TurnToolbox_base: Context.ServiceClass<TurnToolbox, "efferent/TurnToolbox", {
+    /** Open the tools. Once: a second call fails. The handlers run with the services of the opener. */
+    readonly open: Effect.Effect<RunTools, HarnessError>;
+    /** The open tools; fails with `tools.unavailable` before `open`. */
+    readonly tools: Effect.Effect<RunTools, HarnessError>;
+}>;
+/** The turn's tools: registry-opened once, then shared by the loop, the host and RunContext.activate. */
+export declare class TurnToolbox extends TurnToolbox_base {
+}
+declare const TurnPrompt_base: Context.ServiceClass<TurnPrompt, "efferent/TurnPrompt", {
+    /**
+     * The system prompt of one variant: the prefix and the static and session
+     * sections, rendered once per turn in the caller's services and recorded
+     * (SystemPrepared) when it differs from the last one recorded.
+     */
+    readonly system: (variant: Option.Option<string>) => Effect.Effect<string, HarnessError>;
+    /** Render the turn-tier sections once, as TurnContext entries (later calls do nothing). */
+    readonly turnSections: Effect.Effect<void, HarnessError>;
+}>;
+/** The turn's prompt assembly: the system prompt per variant, and the turn-tier sections. */
+export declare class TurnPrompt extends TurnPrompt_base {
+}
+/** What `TurnLive` builds one turn from. */
+export interface TurnLiveInput {
+    /** The admitted turn's writer (see `Sessions.begin`): the session, the message, and where everything is stored. */
+    readonly turn: TurnWriter;
+    /** The system prompt prefix, before the contributed sections. */
+    readonly system?: string;
+    /** How deep event reactions may nest before the bus fails the publisher (8). */
+    readonly maxEventDepth?: number;
+}
+/** The agent-level defaults of one run; a policy overrides limits and budget. */
+export interface TurnRunOptions {
+    readonly limits?: Partial<LoopLimits>;
+    /** Input tokens one request may use (system, tool schemas and messages); 64 000 by default. */
+    readonly budgetTokens?: number;
+    /** The provider prompt-cache key (see `cacheKeyOf`); none by default. */
+    readonly cacheKey?: Option.Option<string>;
+    /** A mid-run user message, consulted between steps. */
+    readonly steering?: Effect.Effect<Option.Option<string>, HarnessError>;
+}
+export {};

package/dist/ports/turn-scope.port.js

@@ -0,0 +1,10 @@
+import { Context } from "effect";
+
+export class TurnMemory extends Context.Service()("efferent/TurnMemory") {
+}
+
+export class TurnToolbox extends Context.Service()("efferent/TurnToolbox") {
+}
+
+export class TurnPrompt extends Context.Service()("efferent/TurnPrompt") {
+}

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

@@ -0,0 +1,113 @@
+import type { Context, Effect, Layer, Option, Scope } from "effect";
+import type { ConversationId } from "../domain/message.entity.js";
+import type { SkillDefinition } from "../harness/capability.entity.js";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import type { CompletionVerdict } from "../turn/turn-event.entity.js";
+import type { UserMessage } from "../turn/user-message.entity.js";
+import type { InitialBatch, ModelChoice, StepDirective, StepInfo } from "./capability.port.js";
+import type { MemoryReader } from "./memory.port.js";
+import type { RunContext } from "./run-context.port.js";
+import type { TurnWriter } from "./sessions.port.js";
+import type { JsonObject } from "../session/session-log.entity.js";
+import type { SessionAddress } from "../session/sessions.entity.js";
+import type { Correctives, LoopLimits, RunResult } from "./step-loop.port.js";
+import type { SkillMatch } from "./tool-registry.port.js";
+import type { TurnEvents, TurnEventsService, TurnTasks, TurnTasksService } from "./turn-events.port.js";
+/**
+ * The host's policy for one run: plain functions, not plugins. The step
+ * loop implementation is the plugin; what a step says, which model it uses
+ * and when the turn is complete are the application's decisions.
+ */
+export interface TurnPolicy<R = never> {
+    readonly initial?: InitialBatch;
+    readonly model?: (step: StepInfo) => Effect.Effect<Option.Option<ModelChoice>, HarnessError, R>;
+    readonly step?: (step: StepInfo) => Effect.Effect<StepDirective, HarnessError, R>;
+    /** Read-only by contract: react to events, decide here. */
+    readonly completion?: (step: StepInfo) => Effect.Effect<CompletionVerdict, HarnessError, R>;
+    readonly limits?: Partial<LoopLimits>;
+    /** Input tokens one request may use (system, tool schemas and messages). */
+    readonly budgetTokens?: number;
+    /** Where the step context goes: closing the messages, or appended to the system prompt. */
+    readonly stepContext?: "tail" | "system";
+    readonly correctives?: Correctives;
+}
+export interface TurnOutcome {
+    readonly outcome: "completed" | "partial" | "failed";
+    /** The reply follow-up turns remember. */
+    readonly reply: Option.Option<string>;
+}
+export interface TurnTools {
+    /** Ask the matcher without writing anything (run it beside other pre-turn work). */
+    readonly match: (userMessage: UserMessage) => Effect.Effect<SkillMatch, HarnessError>;
+    /** Activate the always-on skills and a match; recorded as a decision. */
+    readonly apply: (match: SkillMatch) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    /** `match` then `apply`. */
+    readonly select: (userMessage: UserMessage) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    readonly activate: (skills: ReadonlyArray<string>) => Effect.Effect<ReadonlyArray<string>, HarnessError>;
+    readonly active: Effect.Effect<ReadonlyArray<string>>;
+    readonly skills: ReadonlyArray<SkillDefinition>;
+}
+/** One admitted turn, composed by the host (see `Agent.turn`). */
+export interface Turn {
+    readonly conversation: ConversationId;
+    readonly runId: string;
+    readonly turn: number;
+    readonly userMessage: UserMessage;
+    readonly memory: MemoryReader;
+    readonly events: TurnEventsService;
+    readonly tasks: TurnTasksService;
+    readonly tools: TurnTools;
+    /** Record a turn-context message (e.g. the user's intent) the model sees this turn. */
+    readonly context: (entry: {
+        readonly id: string;
+        readonly version: string;
+        readonly text: string;
+    }) => Effect.Effect<void, HarnessError>;
+    /** Answer without the loop; still a recorded turn. */
+    readonly reply: (text: string) => Effect.Effect<TurnOutcome>;
+    readonly run: <R = never>(policy: TurnPolicy<R>) => Effect.Effect<RunResult, HarnessError, R>;
+    /** Wait until every journal write queued so far is stored (e.g. before delivering an answer). */
+    readonly flush: Effect.Effect<void, HarnessError>;
+    /** Run a host store write in journal order and return its result. */
+    readonly write: <A, E>(op: Effect.Effect<A, E>) => Effect.Effect<A, E | HarnessError>;
+}
+/** What every turn provides to the host's code, its per-turn layer and its tools. */
+export type TurnServices = RunContext | TurnEvents | TurnTasks;
+/** A turn to begin: the session (through the `Sessions` in the turn's services), the message and the run. */
+export interface NewTurn {
+    readonly session: SessionAddress;
+    readonly userMessage: UserMessage;
+    readonly runId: string;
+    /** The idempotency key; the run id by default. */
+    readonly key?: string;
+    /** The host's input beside the message, part of the key's fingerprint. */
+    readonly command?: JsonObject;
+}
+/**
+ * One turn's input. `turn` is either a turn the host already began (its
+ * writer: the host ends it) or one to begin and end here. `layer` is the
+ * host's per-turn services (state stores, adapters for this user
+ * message…): built after RunContext, it is provided to the host's `use`, to
+ * the tools, the policy, subscriptions and tasks alike.
+ */
+export interface TurnInput<A = never, E = never> {
+    readonly turn: TurnWriter | NewTurn;
+    /** This turn's services: the model, per-turn budgets, data ports… */
+    readonly services: Context.Context<never>;
+    /** A system prompt prefix before the contributed sections. */
+    readonly system?: string;
+    /** Per-conversation prompt-cache key for providers that support one. */
+    readonly cacheKey?: string;
+    /** A mid-run user message, consulted between steps. */
+    readonly steering?: Effect.Effect<Option.Option<string>, HarnessError>;
+    /** The host's per-turn services; its requirements are met by the turn's services. */
+    readonly layer?: Layer.Layer<A, E, unknown>;
+}
+/**
+ * Anything that runs one admitted turn the way `Agent.turn` does: an
+ * agent, or a host's own composition of the turn's steps (see
+ * `turnConformance`).
+ */
+export interface TurnRunner {
+    readonly turn: <A = never, E = never, R = never>(input: TurnInput<A, E>, use: (turn: Turn) => Effect.Effect<TurnOutcome, HarnessError, R>) => Effect.Effect<TurnOutcome, HarnessError | E, Exclude<R, A | TurnServices | Scope.Scope>>;
+}

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

@@ -1,41 +1,22 @@
 import { Context, Schema } from "effect";
 import type { Effect } from "effect";
-declare const UtilityError_base: Schema.TaggedErrorClass<UtilityError, "UtilityError", {
-    readonly _tag: Schema.tag<"UtilityError">;
-} & {
-    message: typeof Schema.String;
-}>;
+declare const UtilityError_base: Schema.Class<UtilityError, Schema.TaggedStruct<"UtilityError", {
+    readonly message: Schema.String;
+}>, import("effect/Cause").YieldableError>;
 export declare class UtilityError extends UtilityError_base {
 }
-declare const UtilityCompletion_base: Schema.Class<UtilityCompletion, {
-    text: typeof Schema.String;
-    usage: Schema.Struct<{
-        inputTokens: typeof Schema.Number;
-        outputTokens: typeof Schema.Number;
-        totalTokens: typeof Schema.Number;
-        cacheReadTokens: typeof Schema.Number;
-    }>;
-}, Schema.Struct.Encoded<{
-    text: typeof Schema.String;
-    usage: Schema.Struct<{
-        inputTokens: typeof Schema.Number;
-        outputTokens: typeof Schema.Number;
-        totalTokens: typeof Schema.Number;
-        cacheReadTokens: typeof Schema.Number;
+declare const UtilityCompletion_base: Schema.Class<UtilityCompletion, Schema.Struct<{
+    readonly text: Schema.String;
+    readonly usage: Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
     }>;
-}>, never, {
-    readonly text: string;
-} & {
-    readonly usage: {
-        readonly inputTokens: number;
-        readonly outputTokens: number;
-        readonly totalTokens: number;
-        readonly cacheReadTokens: number;
-    };
-}, {}, {}>;
+}>, {}>;
 export declare class UtilityCompletion extends UtilityCompletion_base {
 }
-declare const UtilityLlm_base: Context.TagClass<UtilityLlm, "@xandreed/core/UtilityLlm", {
+declare const UtilityLlm_base: Context.ServiceClass<UtilityLlm, "@xandreed/core/UtilityLlm", {
     readonly complete: (prompt: string) => Effect.Effect<UtilityCompletion, UtilityError>;
 }>;
 /**

package/dist/ports/utility-llm.port.js

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

package/dist/session/chassis.js

@@ -1,24 +1,24 @@
-import { Effect, Exit, Fiber, Option, PubSub, Ref, Stream } from "effect";
+import { Effect, Exit, Fiber, Option, PubSub, Ref, Stream, Semaphore } from "effect";
 export const makeSession = (args) => Effect.gen(function* () {
-  const context = yield* Effect.context(), log = yield* Ref.make([]), hub = yield* PubSub.sliding(512), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), gate = yield* Effect.makeSemaphore(1), publish = (event) => args.isTransient?.(event) === !0 ? PubSub.publish(transientHub, event).pipe(Effect.asVoid) : Ref.modify(log, (entries) => {
+  const context = yield* Effect.context(), log = yield* Ref.make([]), hub = yield* PubSub.sliding(512), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), gate = yield* Semaphore.make(1), publish = (event) => args.isTransient?.(event) === !0 ? PubSub.publish(transientHub, event).pipe(Effect.asVoid) : Ref.modify(log, (entries) => {
     const entry = { seq: entries.length, event };
     return [entry, [...entries, entry]];
-  }).pipe(Effect.flatMap((entry) => PubSub.publish(hub, entry)), Effect.asVoid), runContained = (text) => args.runTurn(text, publish).pipe(Effect.provide(context), Effect.catchAll((error) => publish(args.onError(String(error)))), Effect.catchAllDefect((defect) => publish(args.onError(`turn crashed: ${String(defect)}`)))), send = (text) => gate.withPermits(1)(Effect.gen(function* () {
-    const fiber = yield* Effect.fork(runContained(text));
+  }).pipe(Effect.flatMap((entry) => PubSub.publish(hub, entry)), Effect.asVoid), runContained = (text) => args.runTurn(text, publish).pipe(Effect.provide(context), Effect.catch((error) => publish(args.onError(String(error)))), Effect.catchDefect((defect) => publish(args.onError(`turn crashed: ${String(defect)}`)))), send = (text) => gate.withPermits(1)(Effect.gen(function* () {
+    const fiber = yield* Effect.forkChild(runContained(text));
     yield* Ref.set(running, Option.some(fiber));
     yield* Fiber.await(fiber).pipe(Effect.asVoid);
     yield* Ref.set(running, Option.none());
   })), interrupt = Ref.get(running).pipe(Effect.flatMap(Option.match({
     onNone: () => Effect.void,
-    onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.flatMap((exit) => Exit.isInterrupted(exit) && args.onInterrupt !== void 0 ? publish(args.onInterrupt()) : Effect.void))
+    onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.andThen(Fiber.await(fiber)), Effect.flatMap((exit) => Exit.hasInterrupts(exit) && args.onInterrupt !== void 0 ? publish(args.onInterrupt()) : Effect.void))
   })));
   return {
     conversationId: args.conversationId,
     send,
     interrupt,
     state: Ref.get(log).pipe(Effect.map((entries) => ({ log: entries, cursor: entries.length }))),
-    subscribe: (since) => Stream.unwrapScoped(Effect.gen(function* () {
-      const sub = yield* PubSub.subscribe(hub), entries = yield* Ref.get(log), replay = Stream.fromIterable(entries.filter((e) => e.seq >= since)), seenThrough = entries.length, live = Stream.fromQueue(sub).pipe(Stream.filter((e) => e.seq >= Math.max(since, seenThrough)));
+    subscribe: (since) => Stream.unwrap(Effect.gen(function* () {
+      const sub = yield* PubSub.subscribe(hub), entries = yield* Ref.get(log), replay = Stream.fromIterable(entries.filter((e) => e.seq >= since)), seenThrough = entries.length, live = Stream.fromSubscription(sub).pipe(Stream.filter((e) => e.seq >= Math.max(since, seenThrough)));
       return Stream.concat(replay, live);
     })),
     transient: Stream.fromPubSub(transientHub),

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

@@ -0,0 +1,55 @@
+import { Schema } from "effect";
+import { UserMessage } from "../turn/user-message.entity.js";
+/** Opens a turn: who asked, what they said, the host's command and the inbox items it claims. */
+export declare const TurnStartedData: Schema.Struct<{
+    readonly runId: Schema.String;
+    /** The host's idempotency key: a second begin with it is the same turn. */
+    readonly key: Schema.String;
+    readonly origin: Schema.Literals<readonly ["user", "inbox"]>;
+    readonly userMessage: typeof UserMessage;
+    /** The host's own input beside the message (an attachment, a reference), part of the key's fingerprint. */
+    readonly command: Schema.$Record<Schema.String, Schema.Unknown>;
+    /** The inbox items this turn answers (an inbox turn only). */
+    readonly claimed: Schema.$Array<Schema.String>;
+    /** The memory entry the message is to the model, and when memory took it. */
+    readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+    readonly at: Schema.Number;
+}>;
+export type TurnStartedData = typeof TurnStartedData.Type;
+export declare const TurnEndReason: Schema.Literals<readonly ["completed", "partial", "failed", "cancelled", "interrupted"]>;
+export type TurnEndReason = typeof TurnEndReason.Type;
+/** Closes a turn. Not model-visible: what later turns remember is `turn.reply`. */
+export declare const TurnEndedData: Schema.Struct<{
+    readonly reason: Schema.Literals<readonly ["completed", "partial", "failed", "cancelled", "interrupted"]>;
+    readonly failure: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly code: Schema.String;
+        readonly message: Schema.String;
+    }>>;
+}>;
+export type TurnEndedData = typeof TurnEndedData.Type;
+/** The kind each memory entry is stored under. `TurnStarted` is the turn's own `turn.started`. */
+export declare const MemoryKindOf: {
+    readonly SystemPrepared: "memory.system";
+    readonly TurnContext: "memory.section";
+    readonly StepContext: "memory.step";
+    readonly Message: "memory.message";
+    readonly ToolResult: "memory.tool-result";
+    readonly ToolDigest: "memory.digest";
+    readonly ToolsActivated: "memory.skills";
+    readonly Compaction: "memory.compaction";
+    readonly TurnEnded: "turn.reply";
+};
+/** Every kind a memory session is rebuilt from. */
+export declare const MEMORY_KINDS: ReadonlyArray<string>;
+/** The turn's observable events stored from its bus (a host's records keep their own names). */
+export declare const TURN_EVENT_KINDS: ReadonlyArray<string>;
+/** The inbox and the session's own records. */
+export declare const SESSION_KINDS: ReadonlyArray<string>;
+/**
+ * Kinds only Efferent writes: a host record under one of these names is refused.
+ * `request.prepared` holds each request's full system text and tool
+ * declarations (and step context in "system" mode), next to the memory
+ * events: a host that redacts memory, or exports or streams session events,
+ * handles it the same way.
+ */
+export declare const RESERVED_KINDS: ReadonlyArray<string>;

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

@@ -0,0 +1,31 @@
+import { Effect, Option, Schema } from "effect";
+import { LogEntry } from "../memory/memory-log.entity.js";
+import type { TurnEvent as TurnEventType } from "../turn/turn-event.entity.js";
+import type { TurnEndedData as TurnEnded, TurnStartedData as TurnStarted } from "./session-event.entity.js";
+import type { SessionDraft, SessionLogEvent } from "./session-log.entity.js";
+/**
+ * One memory entry → the draft it is stored as: its own kind, the entry's
+ * id, run, step and time, and the body. TurnStarted has none: the turn's
+ * `turn.started` (written when the turn begins) is that entry.
+ */
+export declare const draftOfEntry: (entry: LogEntry) => Effect.Effect<Option.Option<SessionDraft>, Schema.SchemaError>;
+export declare const draftsOfEntries: (entries: ReadonlyArray<LogEntry>) => Effect.Effect<ReadonlyArray<SessionDraft>, Schema.SchemaError>;
+/** The draft that opens a turn. */
+export declare const turnStartedDraft: (turn: number, data: TurnStarted) => Effect.Effect<SessionDraft, Schema.SchemaError>;
+/** The draft that closes a turn. */
+export declare const turnEndedDraft: (turn: number, data: TurnEnded) => Effect.Effect<SessionDraft, Schema.SchemaError>;
+/** A stored `turn.started`, decoded. */
+export declare const turnStartedOf: (event: SessionLogEvent) => Effect.Effect<TurnStarted, Schema.SchemaError>;
+/** A stored `turn.ended`, decoded. */
+export declare const turnEndedOf: (event: SessionLogEvent) => Effect.Effect<TurnEnded, Schema.SchemaError>;
+/** One stored event → the memory entry it is, if it is one. */
+export declare const entryOfEvent: (event: SessionLogEvent) => Effect.Effect<Option.Option<LogEntry>, Schema.SchemaError>;
+/** The memory log held in a session's events, in log order. */
+export declare const entriesOfEvents: (events: ReadonlyArray<SessionLogEvent>) => Effect.Effect<ReadonlyArray<LogEntry>, Schema.SchemaError>;
+/**
+ * The stored form of one bus event of turn `turn`: its name and encoded
+ * payload. Transient events are not stored; a host's event keeps its name
+ * and data; an assistant message is stored only as the step's model and
+ * usage (its content is memory's `memory.message`).
+ */
+export declare const draftOfTurnEvent: (turn: number, event: TurnEventType) => Option.Option<SessionDraft>;