@xandreed/core 0.3.0 → 0.8.0-next.0

package/dist/turn/turn-bus.d.ts

@@ -0,0 +1,23 @@
+import { Effect } from "effect";
+import type { Scope } from "effect";
+import { HarnessError } from "../harness/plugin.entity.js";
+import type { TurnEventsService, TurnTasksService } from "../ports/turn-events.port.js";
+/**
+ * An ordered event bus. `publish` runs every inline subscriber in
+ * subscription order before it returns; a handler may publish in turn
+ * (depth-first) up to `maxDepth`, which catches reaction cycles. Background
+ * subscribers get the event on their own queue and handle it in order on
+ * their own fiber; `drain` waits for them. `activity` counts background
+ * deliveries so far, so a caller can tell whether a drain left new work.
+ */
+export declare const makeTurnEvents: (options: {
+    readonly maxDepth: number;
+}) => Effect.Effect<TurnEventsService, never, Scope.Scope>;
+/** Background work forked in `scope`: interrupted when it closes, joined on demand. `activity` counts tasks forked so far. */
+export declare const makeTurnTasks: (scope: Scope.Scope) => Effect.Effect<TurnTasksService>;
+/**
+ * Callbacks with a `never` error channel (the loop's, a tool wrapper's
+ * publish) carry a HarnessError as a defect; this restores it as a failure
+ * at the turn boundary so a subscriber failure fails the turn, typed.
+ */
+export declare const harnessDefectsAsFailures: <A, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E | HarnessError, R>;

package/dist/turn/turn-bus.js

@@ -0,0 +1,54 @@
+import { Cause, Context, Deferred, Effect, Fiber, Option, Queue, Ref } from "effect";
+import { HarnessError } from "../harness/plugin.entity.js";
+const failureOf = (cause) => Option.getOrElse(Cause.findErrorOption(cause), () => {
+  const defect = Cause.squash(cause);
+  return defect instanceof HarnessError ? defect : new HarnessError({ code: "events.background", message: Cause.pretty(cause).slice(0, 300) });
+}), defaultCapacity = 256;
+export const makeTurnEvents = (options) => Effect.gen(function* () {
+  const subscribers = yield* Ref.make([]), nextId = yield* Ref.make(0), depth = Context.Reference(`@xandreed/core/TurnEvents/depth/${yield* Effect.sync(() => crypto.randomUUID())}`, { defaultValue: () => 0 }), queued = yield* Ref.make(0), publish = (event) => Effect.gen(function* () {
+    const current = yield* Effect.service(depth);
+    if (current >= options.maxDepth)
+      return yield* Effect.fail(new HarnessError({ code: "events.depth", message: `${event._tag} published ${current} levels deep; a reaction cycle?` }));
+    const all = yield* Ref.get(subscribers);
+    yield* Effect.forEach(all, (subscriber) => subscriber.deliver(event), { discard: !0 }).pipe(Effect.provideService(depth, current + 1));
+  }), background = (handle, capacity) => Effect.gen(function* () {
+    const queue = yield* Queue.bounded(capacity), failed = yield* Ref.make(Option.none()), take = Queue.take(queue).pipe(Effect.flatMap((item) => Effect.gen(function* () {
+      const failure = yield* Ref.get(failed);
+      if (item._tag === "Marker") {
+        yield* Option.match(failure, { onNone: () => Deferred.succeed(item.done, void 0), onSome: (error) => Deferred.fail(item.done, error) });
+        return;
+      }
+      if (Option.isSome(failure))
+        return;
+      yield* handle(item.event).pipe(Effect.provideService(depth, item.depth), Effect.catchCause((cause) => Ref.set(failed, Option.some(failureOf(cause)))));
+    })));
+    yield* Effect.forkScoped(Effect.forever(take));
+    const deliver = (event) => Effect.gen(function* () {
+      const failure = yield* Ref.get(failed);
+      if (Option.isSome(failure))
+        return yield* Effect.fail(failure.value);
+      yield* Ref.update(queued, (value) => value + 1);
+      yield* Queue.offer(queue, { _tag: "Event", event, depth: yield* Effect.service(depth) });
+    }), drain = Deferred.make().pipe(Effect.flatMap((done) => Queue.offer(queue, { _tag: "Marker", done }).pipe(Effect.andThen(Deferred.await(done)))));
+    return { deliver, drain };
+  }), subscribe = (select, handle, subscribeOptions) => Effect.gen(function* () {
+    const context = yield* Effect.context(), id = yield* Ref.getAndUpdate(nextId, (value) => value + 1), handled = (selected) => handle(selected).pipe(Effect.provide(context)), lane = (subscribeOptions?.mode ?? "inline") === "background" ? yield* background(handled, subscribeOptions?.capacity ?? defaultCapacity) : { deliver: handled, drain: Effect.void }, deliver = (event) => Option.match(select(event), {
+      onNone: () => Effect.void,
+      onSome: lane.deliver
+    });
+    yield* Ref.update(subscribers, (all) => [...all, { id, deliver, drain: lane.drain }]);
+    yield* Effect.addFinalizer(() => Ref.update(subscribers, (all) => all.filter((subscriber) => subscriber.id !== id)));
+  }), drain = Effect.gen(function* () {
+    const before = yield* Ref.get(queued);
+    yield* Effect.forEach(yield* Ref.get(subscribers), (subscriber) => subscriber.drain, { discard: !0 });
+    if ((yield* Ref.get(queued)) !== before)
+      yield* Effect.suspend(() => drain);
+  });
+  return { publish, subscribe, drain, activity: Ref.get(queued) };
+}), makeTurnTasks = (scope) => Effect.gen(function* () {
+  const tasks = yield* Ref.make([]), fork = (tag, task) => Effect.gen(function* () {
+    const context = yield* Effect.context(), fiber = yield* Effect.forkIn(task.pipe(Effect.provide(context)), scope);
+    yield* Ref.update(tasks, (all) => [...all, { tag, fiber }]);
+  }), pending = (tag) => Ref.get(tasks).pipe(Effect.flatMap((all) => Effect.forEach(all.filter((task) => task.tag === tag), (task) => Effect.sync(() => task.fiber.pollUnsafe()))), Effect.map((polls) => polls.some((exit) => exit === void 0))), awaitFrom = (tags, from) => Ref.get(tasks).pipe(Effect.flatMap((all) => all.length === from ? Effect.void : Effect.forEach(all.slice(from).filter((task) => tags.length === 0 || tags.includes(task.tag)), (task) => Fiber.join(task.fiber), { discard: !0 }).pipe(Effect.andThen(Effect.suspend(() => awaitFrom(tags, all.length))))));
+  return { fork, pending, await: (tags) => awaitFrom(tags, 0), activity: Ref.get(tasks).pipe(Effect.map((all) => all.length)) };
+}), harnessDefectsAsFailures = (effect) => effect.pipe(Effect.catchDefect((defect) => defect instanceof HarnessError ? Effect.fail(defect) : Effect.die(defect)));

package/dist/turn/turn-bus.test.d.ts

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

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

@@ -0,0 +1,263 @@
+import { Schema } from "effect";
+import { UserMessage } from "./user-message.entity.js";
+/** What the host's completion policy decided after one step. */
+export declare const CompletionVerdict: Schema.Struct<{
+    readonly complete: Schema.Boolean;
+    /** Task tags to await before the verdict is evaluated once more. */
+    readonly awaiting: Schema.$Array<Schema.Trimmed>;
+    /** Host facts behind the verdict, journaled with it. */
+    readonly facts: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export type CompletionVerdict = typeof CompletionVerdict.Type;
+export declare const TurnStartedEvent: Schema.TaggedStruct<"turn.started", {
+    readonly runId: Schema.String;
+    readonly turn: Schema.Int;
+    readonly userMessage: typeof UserMessage;
+}>;
+export declare const StepStartedEvent: Schema.TaggedStruct<"step.started", {
+    readonly step: Schema.Int;
+    /** Step zero of a host-planned batch: no provider call. */
+    readonly planned: Schema.Boolean;
+    readonly activeTools: Schema.$Array<Schema.String>;
+}>;
+export declare const ToolStartedEvent: Schema.TaggedStruct<"tool.started", {
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly input: Schema.Unknown;
+    readonly labels: Schema.$Record<Schema.String, Schema.String>;
+    readonly stage: Schema.OptionFromNullOr<Schema.String>;
+}>;
+export declare const ToolCompletedEvent: Schema.TaggedStruct<"tool.completed", {
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly input: Schema.Unknown;
+    readonly ok: Schema.Boolean;
+    /** The decoded value the handler returned (or failed with). Not journaled. */
+    readonly result: Schema.Unknown;
+    /** The wire form of `result`, as the model receives it. */
+    readonly encoded: Schema.Unknown;
+    readonly durationMs: Schema.Number;
+    readonly labels: Schema.$Record<Schema.String, Schema.String>;
+    readonly stage: Schema.OptionFromNullOr<Schema.String>;
+}>;
+export declare const StepResult: Schema.Struct<{
+    readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+    readonly tool: Schema.String;
+    readonly ok: Schema.Boolean;
+}>;
+export type StepResult = typeof StepResult.Type;
+export declare const StepEndedEvent: Schema.TaggedStruct<"step.ended", {
+    readonly step: Schema.Int;
+    readonly status: Schema.Literals<readonly ["completed", "failed", "cancelled"]>;
+    /** The step's recorded tool results, in log order. */
+    readonly results: Schema.$Array<Schema.Struct<{
+        readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+        readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+        readonly tool: Schema.String;
+        readonly ok: Schema.Boolean;
+    }>>;
+}>;
+export declare const CompletionEvaluatedEvent: Schema.TaggedStruct<"completion.evaluated", {
+    readonly step: Schema.Int;
+    readonly verdict: Schema.Struct<{
+        readonly complete: Schema.Boolean;
+        /** Task tags to await before the verdict is evaluated once more. */
+        readonly awaiting: Schema.$Array<Schema.Trimmed>;
+        /** Host facts behind the verdict, journaled with it. */
+        readonly facts: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>;
+}>;
+export declare const SkillsActivatedEvent: Schema.TaggedStruct<"skills.activated", {
+    readonly skills: Schema.$Array<Schema.String>;
+    readonly tools: Schema.$Array<Schema.String>;
+    readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+}>;
+export declare const ContextBuiltEvent: Schema.TaggedStruct<"context.built", {
+    readonly step: Schema.Int;
+    readonly turn: Schema.Int;
+    readonly strategy: Schema.String;
+    readonly strategyVersion: Schema.String;
+    readonly fingerprint: Schema.String;
+    readonly systemFingerprint: Schema.String;
+    readonly estimatedTokens: Schema.Int;
+    readonly reservedTokens: Schema.Int;
+    readonly compactions: Schema.Int;
+    readonly activeTools: Schema.$Array<Schema.String>;
+}>;
+export declare const DecisionRecordedEvent: Schema.TaggedStruct<"decision.recorded", {
+    readonly record: Schema.Struct<{
+        readonly version: Schema.Literal<1>;
+        readonly id: Schema.brand<Schema.Trimmed, "DecisionId">;
+        readonly family: Schema.NonEmptyString;
+        readonly contextHash: Schema.String;
+        readonly candidateHash: Schema.String;
+        readonly policyVersion: Schema.String;
+        readonly candidates: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly description: Schema.String;
+        }>>;
+        readonly attempts: Schema.$Array<Schema.String>;
+        readonly selection: Schema.OptionFromNullOr<Schema.String>;
+        readonly validation: Schema.Literals<readonly ["accepted", "rejected", "abstained", "failed", "cancelled", "bypassed"]>;
+        readonly fallback: Schema.OptionFromNullOr<Schema.String>;
+        readonly applied: Schema.OptionFromNullOr<Schema.String>;
+        readonly probabilities: Schema.OptionFromNullOr<Schema.$Record<Schema.String, Schema.Number>>;
+    }>;
+}>;
+export declare const AssistantMessageEvent: Schema.TaggedStruct<"assistant.message", {
+    readonly step: Schema.Int;
+    readonly text: Schema.String;
+    readonly reasoning: Schema.String;
+    readonly model: Schema.OptionFromNullOr<Schema.String>;
+    readonly toolCalls: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly tool: Schema.String;
+        readonly input: Schema.Unknown;
+    }>>;
+    readonly usage: Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
+    }>;
+}>;
+/** A streamed increment — transient: never journaled, restated by assistant.message. */
+export declare const AssistantDeltaEvent: Schema.TaggedStruct<"assistant.delta", {
+    readonly step: Schema.Int;
+    readonly channel: Schema.Literals<readonly ["text", "reasoning", "tool-params"]>;
+    readonly id: Schema.String;
+    readonly delta: Schema.String;
+}>;
+export declare const TurnEndedEvent: Schema.TaggedStruct<"turn.ended", {
+    readonly runId: Schema.String;
+    readonly turn: Schema.Int;
+    readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
+    readonly reply: Schema.OptionFromNullOr<Schema.String>;
+}>;
+/** An application's own event (see `defineHostEvent`); `name` is the host's namespace. */
+export declare const HostEvent: Schema.TaggedStruct<"host", {
+    readonly name: Schema.Trimmed;
+    readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
+}>;
+export declare const TurnEvent: Schema.Union<readonly [Schema.TaggedStruct<"turn.started", {
+    readonly runId: Schema.String;
+    readonly turn: Schema.Int;
+    readonly userMessage: typeof UserMessage;
+}>, Schema.TaggedStruct<"step.started", {
+    readonly step: Schema.Int;
+    /** Step zero of a host-planned batch: no provider call. */
+    readonly planned: Schema.Boolean;
+    readonly activeTools: Schema.$Array<Schema.String>;
+}>, Schema.TaggedStruct<"tool.started", {
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly input: Schema.Unknown;
+    readonly labels: Schema.$Record<Schema.String, Schema.String>;
+    readonly stage: Schema.OptionFromNullOr<Schema.String>;
+}>, Schema.TaggedStruct<"tool.completed", {
+    readonly step: Schema.Int;
+    readonly invocationId: Schema.String;
+    readonly tool: Schema.String;
+    readonly input: Schema.Unknown;
+    readonly ok: Schema.Boolean;
+    /** The decoded value the handler returned (or failed with). Not journaled. */
+    readonly result: Schema.Unknown;
+    /** The wire form of `result`, as the model receives it. */
+    readonly encoded: Schema.Unknown;
+    readonly durationMs: Schema.Number;
+    readonly labels: Schema.$Record<Schema.String, Schema.String>;
+    readonly stage: Schema.OptionFromNullOr<Schema.String>;
+}>, Schema.TaggedStruct<"step.ended", {
+    readonly step: Schema.Int;
+    readonly status: Schema.Literals<readonly ["completed", "failed", "cancelled"]>;
+    /** The step's recorded tool results, in log order. */
+    readonly results: Schema.$Array<Schema.Struct<{
+        readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+        readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+        readonly tool: Schema.String;
+        readonly ok: Schema.Boolean;
+    }>>;
+}>, Schema.TaggedStruct<"completion.evaluated", {
+    readonly step: Schema.Int;
+    readonly verdict: Schema.Struct<{
+        readonly complete: Schema.Boolean;
+        /** Task tags to await before the verdict is evaluated once more. */
+        readonly awaiting: Schema.$Array<Schema.Trimmed>;
+        /** Host facts behind the verdict, journaled with it. */
+        readonly facts: Schema.$Record<Schema.String, Schema.Unknown>;
+    }>;
+}>, Schema.TaggedStruct<"skills.activated", {
+    readonly skills: Schema.$Array<Schema.String>;
+    readonly tools: Schema.$Array<Schema.String>;
+    readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+}>, Schema.TaggedStruct<"context.built", {
+    readonly step: Schema.Int;
+    readonly turn: Schema.Int;
+    readonly strategy: Schema.String;
+    readonly strategyVersion: Schema.String;
+    readonly fingerprint: Schema.String;
+    readonly systemFingerprint: Schema.String;
+    readonly estimatedTokens: Schema.Int;
+    readonly reservedTokens: Schema.Int;
+    readonly compactions: Schema.Int;
+    readonly activeTools: Schema.$Array<Schema.String>;
+}>, Schema.TaggedStruct<"decision.recorded", {
+    readonly record: Schema.Struct<{
+        readonly version: Schema.Literal<1>;
+        readonly id: Schema.brand<Schema.Trimmed, "DecisionId">;
+        readonly family: Schema.NonEmptyString;
+        readonly contextHash: Schema.String;
+        readonly candidateHash: Schema.String;
+        readonly policyVersion: Schema.String;
+        readonly candidates: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            readonly description: Schema.String;
+        }>>;
+        readonly attempts: Schema.$Array<Schema.String>;
+        readonly selection: Schema.OptionFromNullOr<Schema.String>;
+        readonly validation: Schema.Literals<readonly ["accepted", "rejected", "abstained", "failed", "cancelled", "bypassed"]>;
+        readonly fallback: Schema.OptionFromNullOr<Schema.String>;
+        readonly applied: Schema.OptionFromNullOr<Schema.String>;
+        readonly probabilities: Schema.OptionFromNullOr<Schema.$Record<Schema.String, Schema.Number>>;
+    }>;
+}>, Schema.TaggedStruct<"assistant.message", {
+    readonly step: Schema.Int;
+    readonly text: Schema.String;
+    readonly reasoning: Schema.String;
+    readonly model: Schema.OptionFromNullOr<Schema.String>;
+    readonly toolCalls: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        readonly tool: Schema.String;
+        readonly input: Schema.Unknown;
+    }>>;
+    readonly usage: Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
+    }>;
+}>, Schema.TaggedStruct<"assistant.delta", {
+    readonly step: Schema.Int;
+    readonly channel: Schema.Literals<readonly ["text", "reasoning", "tool-params"]>;
+    readonly id: Schema.String;
+    readonly delta: Schema.String;
+}>, Schema.TaggedStruct<"turn.ended", {
+    readonly runId: Schema.String;
+    readonly turn: Schema.Int;
+    readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
+    readonly reply: Schema.OptionFromNullOr<Schema.String>;
+}>, Schema.TaggedStruct<"host", {
+    readonly name: Schema.Trimmed;
+    readonly data: Schema.$Record<Schema.String, Schema.Unknown>;
+}>]>;
+export type TurnEvent = typeof TurnEvent.Type;
+export type TurnEventName = TurnEvent["_tag"];
+export type TurnEventOf<Name extends TurnEventName> = Extract<TurnEvent, {
+    readonly _tag: Name;
+}>;
+/** Events that exist only for live rendering and are never journaled. */
+export declare const TransientTurnEvents: ReadonlyArray<TurnEventName>;

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

@@ -0,0 +1,35 @@
+import { Effect, Option, Schema } from "effect";
+import { HarnessError } from "../harness/plugin.entity.js";
+import type { SubscribeOptions, Subscription, TurnEventsService } from "../ports/turn-events.port.js";
+import type { TurnEvent, TurnEventName, TurnEventOf } from "./turn-event.entity.js";
+/** Subscribe to one event kind by name, typed by the event's schema (inline unless `options.mode` says background). */
+export declare const onEvent: <Name extends TurnEventName, R>(name: Name, handle: (event: TurnEventOf<Name>) => Effect.Effect<void, HarnessError, R>, options?: SubscribeOptions) => Subscription<R>;
+/**
+ * React to one tool's successful calls, typed by the tool's own schemas:
+ * the input and result are narrowed with `Schema.is`, never cast.
+ */
+export interface ToolCall<Input, Result> {
+    readonly step: number;
+    readonly invocationId: string;
+    readonly input: Input;
+    readonly result: Result;
+}
+export declare const onTool: <Params extends Schema.Top, Success extends Schema.Top, R>(tool: {
+    readonly name: string;
+    readonly parametersSchema: Params;
+    readonly successSchema: Success;
+}, handle: (call: ToolCall<Params["Type"], Success["Type"]>) => Effect.Effect<void, HarnessError, R>, options?: SubscribeOptions) => Subscription<R>;
+/** Attach several subscriptions to one bus. */
+export declare const subscribeAll: <R>(events: TurnEventsService, subscriptions: ReadonlyArray<Subscription<R>>) => Effect.Effect<void, never, import("effect/Scope").Scope | R>;
+/**
+ * An application's own typed event. Its name is the host's namespace
+ * (e.g. `answer.published`); payloads are encoded with the schema, so a
+ * journal sink can persist them like any other event.
+ */
+export declare const defineHostEvent: <A, I extends Readonly<Record<string, unknown>>>(name: string, schema: Schema.Codec<A, I>) => {
+    name: string;
+    make: (data: A) => Effect.Effect<TurnEvent, HarnessError>;
+    select: (event: TurnEvent) => Option.Option<A>;
+    publish: (events: TurnEventsService, data: A) => Effect.Effect<void, HarnessError, never>;
+    on: <R>(handle: (data: A) => Effect.Effect<void, HarnessError, R>, options?: SubscribeOptions) => Subscription<R>;
+};

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

@@ -0,0 +1,21 @@
+import { Effect, Option, Schema } from "effect";
+import { HarnessError } from "../harness/plugin.entity.js";
+const isNamed = (name) => (event) => event._tag === name;
+export const onEvent = (name, handle, options) => (events) => events.subscribe((event) => Option.liftPredicate(event, isNamed(name)), handle, options), onTool = (tool, handle, options) => {
+  const isInput = Schema.is(tool.parametersSchema), isResult = Schema.is(tool.successSchema);
+  return (events) => events.subscribe((event) => {
+    if (event._tag !== "tool.completed" || event.tool !== tool.name || !event.ok)
+      return Option.none();
+    const { input, result } = event;
+    return isInput(input) && isResult(result) ? Option.some({ step: event.step, invocationId: event.invocationId, input, result }) : Option.none();
+  }, handle, options);
+}, subscribeAll = (events, subscriptions) => Effect.forEach(subscriptions, (subscription) => subscription(events), { discard: !0 }), defineHostEvent = (name, schema) => {
+  const select = (event) => event._tag === "host" && event.name === name ? Schema.decodeUnknownOption(schema)(event.data) : Option.none(), make = (data) => Schema.encodeEffect(schema)(data).pipe(Effect.map((encoded) => ({ _tag: "host", name, data: encoded })), Effect.mapError((error) => new HarnessError({ code: "events.encode", message: `${name}: ${error.message}` })));
+  return {
+    name,
+    make,
+    select,
+    publish: (events, data) => make(data).pipe(Effect.flatMap(events.publish)),
+    on: (handle, options) => (events) => events.subscribe(select, handle, options)
+  };
+};

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

@@ -0,0 +1,101 @@
+import { Schema } from "effect";
+import { DecisionRecord } from "../decision-record.entity.js";
+import { ToolCallId } from "../domain/message.entity.js";
+import { TokenUsage } from "../domain/token-usage.entity.js";
+import { ActivationSource, EntryId } from "../memory/memory-log.entity.js";
+import { UserMessage } from "./user-message.entity.js";
+const Labels = Schema.Record(Schema.String, Schema.String), Data = Schema.Record(Schema.String, Schema.Unknown);
+export const CompletionVerdict = Schema.Struct({
+  complete: Schema.Boolean,
+  awaiting: Schema.Array(Schema.Trimmed.check(Schema.isNonEmpty())),
+  facts: Data
+}), TurnStartedEvent = Schema.TaggedStruct("turn.started", {
+  runId: Schema.String,
+  turn: Schema.Int,
+  userMessage: UserMessage
+}), StepStartedEvent = Schema.TaggedStruct("step.started", {
+  step: Schema.Int,
+  planned: Schema.Boolean,
+  activeTools: Schema.Array(Schema.String)
+}), ToolStartedEvent = Schema.TaggedStruct("tool.started", {
+  step: Schema.Int,
+  invocationId: Schema.String,
+  tool: Schema.String,
+  input: Schema.Unknown,
+  labels: Labels,
+  stage: Schema.OptionFromNullOr(Schema.String)
+}), ToolCompletedEvent = Schema.TaggedStruct("tool.completed", {
+  step: Schema.Int,
+  invocationId: Schema.String,
+  tool: Schema.String,
+  input: Schema.Unknown,
+  ok: Schema.Boolean,
+  result: Schema.Unknown,
+  encoded: Schema.Unknown,
+  durationMs: Schema.Number,
+  labels: Labels,
+  stage: Schema.OptionFromNullOr(Schema.String)
+}), StepResult = Schema.Struct({
+  entry: EntryId,
+  toolCallId: ToolCallId,
+  tool: Schema.String,
+  ok: Schema.Boolean
+}), StepEndedEvent = Schema.TaggedStruct("step.ended", {
+  step: Schema.Int,
+  status: Schema.Literals(["completed", "failed", "cancelled"]),
+  results: Schema.Array(StepResult)
+}), CompletionEvaluatedEvent = Schema.TaggedStruct("completion.evaluated", {
+  step: Schema.Int,
+  verdict: CompletionVerdict
+}), SkillsActivatedEvent = Schema.TaggedStruct("skills.activated", {
+  skills: Schema.Array(Schema.String),
+  tools: Schema.Array(Schema.String),
+  source: ActivationSource
+}), ContextBuiltEvent = Schema.TaggedStruct("context.built", {
+  step: Schema.Int,
+  turn: Schema.Int,
+  strategy: Schema.String,
+  strategyVersion: Schema.String,
+  fingerprint: Schema.String,
+  systemFingerprint: Schema.String,
+  estimatedTokens: Schema.Int,
+  reservedTokens: Schema.Int,
+  compactions: Schema.Int,
+  activeTools: Schema.Array(Schema.String)
+}), DecisionRecordedEvent = Schema.TaggedStruct("decision.recorded", {
+  record: DecisionRecord
+}), AssistantMessageEvent = Schema.TaggedStruct("assistant.message", {
+  step: Schema.Int,
+  text: Schema.String,
+  reasoning: Schema.String,
+  model: Schema.OptionFromNullOr(Schema.String),
+  toolCalls: Schema.Array(Schema.Struct({ id: Schema.String, tool: Schema.String, input: Schema.Unknown })),
+  usage: TokenUsage
+}), AssistantDeltaEvent = Schema.TaggedStruct("assistant.delta", {
+  step: Schema.Int,
+  channel: Schema.Literals(["text", "reasoning", "tool-params"]),
+  id: Schema.String,
+  delta: Schema.String
+}), TurnEndedEvent = Schema.TaggedStruct("turn.ended", {
+  runId: Schema.String,
+  turn: Schema.Int,
+  outcome: Schema.Literals(["completed", "partial", "failed"]),
+  reply: Schema.OptionFromNullOr(Schema.String)
+}), HostEvent = Schema.TaggedStruct("host", {
+  name: Schema.Trimmed.check(Schema.isNonEmpty()),
+  data: Data
+}), TurnEvent = Schema.Union([
+  TurnStartedEvent,
+  StepStartedEvent,
+  ToolStartedEvent,
+  ToolCompletedEvent,
+  StepEndedEvent,
+  CompletionEvaluatedEvent,
+  SkillsActivatedEvent,
+  ContextBuiltEvent,
+  DecisionRecordedEvent,
+  AssistantMessageEvent,
+  AssistantDeltaEvent,
+  TurnEndedEvent,
+  HostEvent
+]), TransientTurnEvents = ["assistant.delta"];

package/dist/turn/turn-lifecycle.d.ts

@@ -0,0 +1,32 @@
+import { Effect } from "effect";
+import type { HarnessError } from "../harness/plugin.entity.js";
+import { RunContext } from "../ports/run-context.port.js";
+import type { StepLoop } from "../ports/step-loop.port.js";
+import type { RunTools } from "../ports/tool-registry.port.js";
+import { TurnEvents, TurnTasks } from "../ports/turn-events.port.js";
+import { TurnMemory, TurnToolbox } from "../ports/turn-scope.port.js";
+import type { TurnRunOptions } from "../ports/turn-scope.port.js";
+import type { Turn, TurnOutcome, TurnTools } from "../ports/turn.port.js";
+import type { TurnRunServices } from "./turn-run.js";
+/** Open the turn's tools (once). Their handlers run with the services of where this runs: open them inside the host's layer. */
+export declare const openTurnTools: Effect.Effect<RunTools, HarnessError, TurnToolbox>;
+/** The host's view of the open tools; skills the host activates are recorded as its own. */
+export declare const turnTools: Effect.Effect<TurnTools, HarnessError, TurnToolbox>;
+/** Await the tasks, then drain the background reactions, again until a round starts nothing new. */
+export declare const settleTurn: Effect.Effect<void, HarnessError, TurnEvents | TurnTasks>;
+/** Record the reply (`persistReply`), drain the reactions to it, and flush the journal. */
+export declare const finishTurn: (outcome: TurnOutcome) => Effect.Effect<void, HarnessError, TurnMemory | TurnEvents | RunContext>;
+/**
+ * Run a turn's body to its end: once it succeeds, the turn settles (tasks
+ * and background reactions) and finishes with its outcome. When it fails
+ * or is interrupted, the turn finishes as failed and keeps the body's
+ * cause. A HarnessError carried as a defect (a subscriber's failure behind
+ * a `never` error channel) fails the turn, typed.
+ */
+export declare const guardTurn: <E, R>(body: Effect.Effect<TurnOutcome, E, R>) => Effect.Effect<TurnOutcome, E | HarnessError, R | TurnMemory | TurnEvents | TurnTasks | RunContext>;
+/**
+ * The `Turn` a host's code works with, over the turn's services (the one
+ * `Agent.turn` hands to `use`): its `run` is `runTurnLoop` with `options`.
+ * The message must be persisted and the tools open.
+ */
+export declare const turnOf: (options?: TurnRunOptions) => Effect.Effect<Turn, HarnessError, TurnRunServices | RunContext | StepLoop>;

package/dist/turn/turn-lifecycle.js

@@ -0,0 +1,48 @@
+import { Effect, Exit, Option } from "effect";
+import { RunContext } from "../ports/run-context.port.js";
+import { TurnEvents, TurnTasks } from "../ports/turn-events.port.js";
+import { TurnMemory, TurnToolbox } from "../ports/turn-scope.port.js";
+import { harnessDefectsAsFailures } from "./turn-bus.js";
+import { runTurnLoop } from "./turn-run.js";
+const failed = { outcome: "failed", reply: Option.none() };
+export const openTurnTools = TurnToolbox.pipe(Effect.flatMap((toolbox) => toolbox.open)), turnTools = TurnToolbox.pipe(Effect.flatMap((toolbox) => toolbox.tools), Effect.map((tools) => ({
+  match: tools.match,
+  apply: tools.apply,
+  select: tools.select,
+  activate: (skills) => tools.activate(skills, "host"),
+  active: tools.active,
+  skills: tools.skills
+}))), settleTurn = Effect.gen(function* () {
+  const events = yield* TurnEvents, tasks = yield* TurnTasks, activity = Effect.zipWith(tasks.activity, events.activity, (forked, delivered) => forked + delivered), settle = Effect.gen(function* () {
+    const before = yield* activity;
+    yield* tasks.await([]);
+    yield* events.drain;
+    if ((yield* activity) !== before)
+      yield* Effect.suspend(() => settle);
+  });
+  yield* settle;
+}), finishTurn = (outcome) => Effect.gen(function* () {
+  yield* (yield* TurnMemory).persistReply(outcome);
+  yield* (yield* TurnEvents).drain;
+  yield* (yield* RunContext).flush;
+}), guardTurn = (body) => harnessDefectsAsFailures(body.pipe(Effect.tap(() => settleTurn))).pipe(Effect.onExit(Exit.match({
+  onSuccess: () => Effect.void,
+  onFailure: () => finishTurn(failed).pipe(Effect.catchCause(() => Effect.void))
+})), Effect.tap(finishTurn)), turnOf = (options = {}) => Effect.gen(function* () {
+  const services = yield* Effect.context(), run = yield* RunContext, memory = yield* TurnMemory;
+  return {
+    conversation: run.conversation,
+    runId: run.runId,
+    turn: yield* memory.number,
+    userMessage: run.userMessage,
+    memory: run.memory,
+    events: run.events,
+    tasks: run.tasks,
+    tools: yield* turnTools,
+    context: memory.context,
+    reply: (text) => Effect.succeed({ outcome: "completed", reply: Option.some(text) }),
+    run: (policy) => runTurnLoop(policy, options).pipe(Effect.provide(services)),
+    flush: run.flush,
+    write: run.write
+  };
+});

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

@@ -0,0 +1,26 @@
+import { Effect, Option } from "effect";
+import { HarnessError } from "../harness/plugin.entity.js";
+import { StepLoop } from "../ports/step-loop.port.js";
+import type { RunResult, StepRequest } from "../ports/step-loop.port.js";
+import type { RunTools } from "../ports/tool-registry.port.js";
+import { TurnEvents, TurnTasks } from "../ports/turn-events.port.js";
+import type { TurnPolicy } from "../ports/turn.port.js";
+import { TurnMemory, TurnPrompt, TurnToolbox } from "../ports/turn-scope.port.js";
+import type { TurnRunOptions } from "../ports/turn-scope.port.js";
+/** The turn services one run reads. */
+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. */
+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 policy's planned skills are activated, the turn-tier sections
+ * are recorded, and memory is maintained for the turn's start. 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.
+ */
+export declare const stepRequestOf: <P>(policy: TurnPolicy<P>, options?: TurnRunOptions) => Effect.Effect<StepRequest, HarnessError, P | TurnRunServices>;
+/** One run of the turn: `stepRequestOf`, then the StepLoop. */
+export declare const runTurnLoop: <P>(policy: TurnPolicy<P>, options?: TurnRunOptions) => Effect.Effect<RunResult, HarnessError, P | TurnRunServices | StepLoop>;