@xandreed/sdk 0.12.0 → 0.14.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/sdk
 
-Efferent composable agent framework, 0.12.0. Node 24 or Bun.
+Efferent composable agent framework, 0.14.0. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/agent.adapter.d.ts

@@ -1,7 +1,7 @@
 import { Context, Effect } from "effect";
 import type { Scope } from "effect";
 import { HarnessError } from "@xandreed/core";
-import type { Capability, LoopLimits, Plugin, Turn, TurnInput, TurnOutcome, TurnServices } from "@xandreed/core";
+import type { Capability, LoopLimits, Plugin, ProcessActivity, Turn, TurnInput, TurnOutcome, TurnResult, TurnServices } from "@xandreed/core";
 /** One plugin instance of an agent: the definition, its options and (optionally) an instance id. */
 export interface AgentPluginEntry {
     readonly plugin: Plugin;
@@ -17,7 +17,11 @@ export interface AgentConfig {
     readonly bindings?: Readonly<Record<string, string>>;
     /** The host's own tools, views, skills and prompt sections. */
     readonly capabilities?: ReadonlyArray<Capability>;
-    /** Process-lifetime host services plugins may require. */
+    /**
+     * Process-lifetime host services plugins may require. Their trace state
+     * is not replayed into turns (`replayableContext`): a parent span, span
+     * annotations or `CurrentTraceContent` among them are ignored.
+     */
     readonly services?: Context.Context<never>;
     /** Keys every turn's services must carry; session plugins may require them. */
     readonly turnServices?: ReadonlyArray<{
@@ -30,14 +34,52 @@ export interface AgentConfig {
     readonly workspace?: string;
     /** Defaults for every run; a turn's policy overrides them. */
     readonly limits?: Partial<LoopLimits>;
-    /** Input tokens one request may use (system, tool schemas and messages). */
+    /**
+     * Every run's token budget unless its policy gives one; 64 000 by default.
+     * An integer of at least 1, checked here (`config.budget`). It is the
+     * target memory compaction keeps each request under (system prompt, tool
+     * schemas and messages, estimated), not a provider limit. Memory is given
+     * the whole budget at the turn's start, and at each step what the system
+     * prompt and tool schemas leave of it (`context.budget` when they leave
+     * nothing). The window strategy compacts, spills and drops older turns to
+     * fit the budget it is given, and fails with `context.budget` when the
+     * current turn alone does not; the summary strategy summarizes once the
+     * messages pass its `triggerRatio` of it; the digester ignores it. Each
+     * step's `context.built` records it.
+     */
     readonly budgetTokens?: number;
     /** How deep event reactions may nest before the bus fails the publisher. */
     readonly maxEventDepth?: number;
+    /**
+     * Whether runs' spans may carry prompt and response content
+     * (`engine.step.input`, `engine.step.output`, the models plugin's
+     * `llm.reasoning`) when a policy does not say (`TurnPolicy.captureTraceContent`).
+     * Off by default, unless `CurrentTraceContent` is provided where a run
+     * starts: around `Agent.turn`, inside `use`, or in the turn's
+     * `TurnInput.services` (one in `services` is ignored: set this instead).
+     * Hosts own consent, masking and exporter retention.
+     */
+    readonly captureTraceContent?: boolean;
+    /**
+     * The keys of a turn's metadata (`NewTurn.meta`, `AdmittedTurn.meta`) its
+     * `agent.turn` span carries, as `efferent.meta.<key>`; none by default
+     * (see `TurnTraceOptions`).
+     */
+    readonly spanMeta?: ReadonlyArray<string>;
 }
 /** A defined agent: its graph is built; each turn is composed by the host. */
 export interface Agent {
     readonly fingerprint: string;
+    /**
+     * What this process is busy with (`processActivity`), as the agent's
+     * runtime services see it: the `TurnActivity` of a runtime-scoped
+     * sessions plugin in its graph (or one in `services`), and the
+     * `TaskActivity` of a task runner in `services` (`InProcessTaskRunnerLive`
+     * built into them). A probe that is not there counts nothing: a Sessions
+     * the host passes only in a turn's services is not seen here (read
+     * `processActivity` with the host's own services instead).
+     */
+    readonly activity: Effect.Effect<ProcessActivity>;
     /**
      * Run one turn: one the host began (its `TurnWriter`; the host ends it),
      * or one begun and ended here through the `Sessions` in the turn's
@@ -45,14 +87,40 @@ export interface Agent {
      * On success, tasks and background subscriptions settle as the scopes
      * close in dependency order, before the reply is recorded exactly once.
      * Failures and interruptions record a failed reply and cancel remaining
-     * scoped work; recorded events are stored before the turn returns. A turn closed
+     * scoped work; recorded events are stored before the turn returns. A turn
+     * begun here ends with `turnEndingOf` its exit: its outcome, or failed
+     * with the error's code (`turn.failed` for an error without one,
+     * `turn.defect`), or interrupted (`turn.interrupted`); on success, a
+     * failure to store that end fails the turn. A turn closed
      * elsewhere (cancelled, reaped) fails with `turn.closed`. `use` runs in
      * the turn's scope with the turn's services (RunContext, TurnEvents,
      * TurnTasks and the input's `layer`) provided: the same instances the
-     * tools, policy and subscriptions see.
+     * tools, policy and subscriptions see. It returns `use`'s outcome with
+     * the turn's usage (every run's provider calls, summed). From the moment
+     * the turn is admitted it runs under its `agent.turn` span (`traceTurn`),
+     * and is counted in the `efferent.turns` and `efferent.turn.duration`
+     * metrics by its `efferent.outcome`.
      */
-    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>>;
+    readonly turn: <A = never, E = never, R = never>(input: TurnInput<A, E>, use: (turn: Turn) => Effect.Effect<TurnOutcome, HarnessError, R>) => Effect.Effect<TurnResult, HarnessError | E, Exclude<R, A | TurnServices | Scope.Scope>>;
 }
+/**
+ * Why a turn could not begin (`Sessions.begin` failed, or, for
+ * `AttachmentRejected`, the attachments' check before it), as the code of
+ * the `HarnessError` `Agent.turn` fails with: keyed by the begin error's
+ * tag. An `AttachmentRejected`'s `reason` is in the message only; a host
+ * that branches on it runs `normalizeUserMessage` itself before the turn.
+ */
+export declare const turnBeginCodes: {
+    readonly AttachmentRejected: "turn.attachment-rejected";
+    readonly SessionBusy: "session.busy";
+    readonly TurnDuplicate: "turn.duplicate";
+    readonly KeyConflict: "turn.key-conflict";
+    readonly NothingPending: "session.nothing-pending";
+    readonly NotResumable: "turn.not-resumable";
+    readonly TurnRefused: "turn.refused";
+    readonly SessionMissing: "session.missing";
+    readonly SessionLogError: "session.log";
+};
 export declare const Agent: {
     define: (config: AgentConfig) => Effect.Effect<Agent, HarnessError, Scope.Scope>;
 };

package/dist/agent.adapter.js

@@ -1,6 +1,7 @@
-import { Context, Effect, Option, Schema } from "effect";
+import { Clock, Context, Duration, Effect, Exit, Metric, Option, Schema } from "effect";
 import {
   cacheKeyOf,
+  CurrentTraceContent,
   CapabilitiesLive,
   Capabilities,
   ConversationMemory,
@@ -8,37 +9,63 @@ import {
   guardTurn,
   harnessDefectsAsFailures,
   HarnessError,
+  isBudgetTokens,
+  normalizeUserMessage,
   openTurnTools,
+  processActivity,
+  replayableContext,
   SessionEnvironment,
   Sessions,
   StepLoop,
+  TaskActivity,
   ToolRegistry,
   RunContext,
   settleTurn,
+  TurnActivity,
   TurnEvents,
   TurnTasks,
   TurnLive,
   TurnMemory,
   TurnPrompt,
   TurnToolbox,
+  traceTurn,
+  turnEndingOf,
   turnOf
 } from "@xandreed/core";
 import { activateGraph, graphFingerprint, resolveGraph } from "@xandreed/runtime";
-const failure = (code, message) => new HarnessError({ code, message }), missing = (key) => failure("service.missing", `The agent's plugins do not provide ${key}`), entryOf = (item) => ("plugin" in item) ? item : { plugin: item }, isWriter = (turn) => ("admitted" in turn), beginCodes = {
+const failure = (code, message) => new HarnessError({ code, message }), missing = (key) => failure("service.missing", `The agent's plugins do not provide ${key}`), turnCount = Metric.counter("efferent.turns", {
+  description: "turns run by Agent.turn, by outcome",
+  incremental: !0
+}), turnDuration = Metric.timer("efferent.turn.duration", {
+  description: "how long each turn Agent.turn ran took, by outcome"
+}), measureTurn = (effect) => Clock.currentTimeMillis.pipe(Effect.flatMap((started) => effect.pipe(Effect.onExit((exit) => Effect.gen(function* () {
+  const outcome = { "efferent.outcome": turnEndingOf(exit).reason }, ended = yield* Clock.currentTimeMillis;
+  yield* Metric.update(Metric.withAttributes(turnCount, outcome), 1);
+  yield* Metric.update(Metric.withAttributes(turnDuration, outcome), Duration.millis(ended - started));
+}))))), entryOf = (item) => ("plugin" in item) ? item : { plugin: item }, isWriter = (turn) => ("admitted" in turn);
+export const turnBeginCodes = {
+  AttachmentRejected: "turn.attachment-rejected",
   SessionBusy: "session.busy",
   TurnDuplicate: "turn.duplicate",
   KeyConflict: "turn.key-conflict",
   NothingPending: "session.nothing-pending",
+  NotResumable: "turn.not-resumable",
   TurnRefused: "turn.refused",
   SessionMissing: "session.missing",
   SessionLogError: "session.log"
-}, beginTurn = (context, turn) => required(context, Sessions).pipe(Effect.flatMap((sessions) => sessions.begin(turn.session, {
-  _tag: "User",
-  userMessage: turn.userMessage,
-  runId: turn.runId,
-  key: turn.key ?? turn.runId,
-  command: turn.command ?? {}
-})), Effect.mapError((error) => error instanceof HarnessError ? error : failure(beginCodes[error._tag], `the turn could not begin (${error._tag}) in session ${turn.session.id}`))), untilClosed = (writer) => (body) => Effect.raceFirst(body, writer.closed.pipe(Effect.flatMap((closed) => Effect.fail(failure("turn.closed", `turn ${closed.turn} was ${closed.reason}`))))), required = (context, tag) => Option.match(Context.getOption(context, tag), { onNone: () => Effect.fail(missing(tag.key)), onSome: Effect.succeed }), provideHostLayer = (layer) => (effect) => Option.match(layer, { onNone: () => effect, onSome: (hostLayer) => effect.pipe(Effect.provide(hostLayer, { local: !0 })) }), hostCapabilities = (capabilities) => definePlugin({
+};
+const keyOf = (turn) => turn.key ?? (turn.resumes === void 0 ? turn.runId : `resume:${turn.resumes}`), beginTurn = (context, turn) => Effect.gen(function* () {
+  const sessions = yield* required(context, Sessions), userMessage = yield* normalizeUserMessage(turn.userMessage);
+  return yield* sessions.begin(turn.session, {
+    _tag: "User",
+    userMessage,
+    runId: turn.runId,
+    key: keyOf(turn),
+    command: turn.command ?? {},
+    ...turn.meta === void 0 ? {} : { meta: turn.meta },
+    ...turn.resumes === void 0 ? {} : { resumes: turn.resumes }
+  });
+}).pipe(Effect.mapError((error) => error instanceof HarnessError ? error : failure(turnBeginCodes[error._tag], error._tag === "NotResumable" ? `turn ${error.turn} of session ${turn.session.id} cannot be resumed (${error.reason})` : error._tag === "AttachmentRejected" ? `the turn could not begin (AttachmentRejected, ${error.reason}: ${error.message}) in session ${turn.session.id}` : `the turn could not begin (${error._tag}) in session ${turn.session.id}`))), untilClosed = (writer) => (body) => Effect.raceFirst(body, writer.closed.pipe(Effect.flatMap((closed) => Effect.fail(failure("turn.closed", `turn ${closed.turn} was ${closed.reason}`))))), required = (context, tag) => Option.match(Context.getOption(context, tag), { onNone: () => Effect.fail(missing(tag.key)), onSome: Effect.succeed }), provideHostLayer = (layer) => (effect) => Option.match(layer, { onNone: () => effect, onSome: (hostLayer) => effect.pipe(Effect.provide(hostLayer, { local: !0 })) }), hostCapabilities = (capabilities) => definePlugin({
   id: "@xandreed/sdk/host-contributions",
   version: "1",
   scope: "runtime",
@@ -50,6 +77,8 @@ const failure = (code, message) => new HarnessError({ code, message }), missing
 }), builtInTurnKeys = [RunContext, TurnEvents, TurnTasks, TurnMemory, TurnPrompt, TurnToolbox].map((tag) => tag.key), turnDependentNodes = (graph) => graph.nodes.reduce((late, node) => {
   return [...node.plugin.requires, ...node.plugin.optional ?? []].some((key) => builtInTurnKeys.includes(key) || late.some((source) => source.plugin.provides.includes(key) || (source.plugin.contributes ?? []).includes(key))) ? [...late, node] : late;
 }, []), makeAgent = (config) => Effect.gen(function* () {
+  if (config.budgetTokens !== void 0 && !isBudgetTokens(config.budgetTokens))
+    return yield* Effect.fail(failure("config.budget", `budgetTokens must be an integer of at least 1, not ${config.budgetTokens}`));
   const parent = yield* Effect.scope, entries = config.plugins.map(entryOf), hosted = config.capabilities ?? [], host = hostCapabilities(hosted), withHost = hosted.length > 0, plugins = [...withHost ? [host] : [], ...entries.map((entry) => entry.plugin)], harness = {
     version: 1,
     plugins: [
@@ -65,7 +94,7 @@ const failure = (code, message) => new HarnessError({ code, message }), missing
     const scope = yield* Effect.scope, absent = turnKeys.filter((key) => !input.services.mapUnsafe.has(key));
     if (absent.length > 0)
       return yield* Effect.fail(failure("service.missing", `The turn does not provide ${absent.join(", ")}`));
-    const merged = Context.merge(runtime, input.services), context = perTurn ? yield* activateGraph(beforeTurn, "session", merged, scope) : merged, memory = yield* required(context, ConversationMemory), registry = yield* required(context, ToolRegistry), loop = yield* required(context, StepLoop), own = !isWriter(input.turn), writer = isWriter(input.turn) ? input.turn : yield* beginTurn(context, input.turn), system = input.system ?? config.system, live = {
+    const merged = Context.merge(replayableContext(Context.merge(runtime, input.services)), Context.pick(CurrentTraceContent)(input.services)), context = perTurn ? yield* activateGraph(beforeTurn, "session", merged, scope) : merged, memory = yield* required(context, ConversationMemory), registry = yield* required(context, ToolRegistry), loop = yield* required(context, StepLoop), own = !isWriter(input.turn), writer = isWriter(input.turn) ? input.turn : yield* beginTurn(context, input.turn), system = input.system ?? config.system, live = {
       turn: writer,
       ...system === void 0 ? {} : { system },
       ...config.maxEventDepth === void 0 ? {} : { maxEventDepth: config.maxEventDepth }
@@ -73,7 +102,8 @@ const failure = (code, message) => new HarnessError({ code, message }), missing
       ...config.limits === void 0 ? {} : { limits: config.limits },
       ...config.budgetTokens === void 0 ? {} : { budgetTokens: config.budgetTokens },
       cacheKey: Option.orElse(Option.fromNullishOr(input.cacheKey), () => cacheKeyOf(config.cacheKeyPrefix ?? "", writer.admitted.session.id)),
-      ...input.steering === void 0 ? {} : { steering: input.steering }
+      ...input.steering === void 0 ? {} : { steering: input.steering },
+      ...config.captureTraceContent === void 0 ? {} : { captureTraceContent: config.captureTraceContent }
     }, body = Effect.gen(function* () {
       yield* (yield* TurnMemory).persistMessage;
       yield* openTurnTools;
@@ -84,11 +114,16 @@ const failure = (code, message) => new HarnessError({ code, message }), missing
         const activated = yield* activateGraph(afterTurn, "session", Context.merge(context, liveContext), yield* Effect.scope);
         return yield* effect.pipe(Effect.provide(activated));
       }));
-    }), outcome = yield* body.pipe(Effect.tap(() => settleTurn), Effect.scoped, Effect.tap(() => settleTurn), provideHostLayer(Option.fromNullishOr(input.layer)), Effect.tap(() => settleTurn), provideTurnPlugins, guardTurn, Effect.provide(TurnLive(live), { local: !0 }), Effect.provideService(ConversationMemory, memory), Effect.provideService(ToolRegistry, registry), Effect.provideService(StepLoop, loop), Effect.provide(context), untilClosed(writer));
-    if (own)
-      yield* writer.end({ reason: outcome.outcome, failure: Option.none() });
-    return outcome;
-  })));
-  return { fingerprint: graphFingerprint(graph), turn };
+    });
+    return yield* Effect.gen(function* () {
+      const exit = yield* body.pipe(Effect.tap(() => settleTurn), Effect.scoped, Effect.tap(() => settleTurn), provideHostLayer(Option.fromNullishOr(input.layer)), Effect.tap(() => settleTurn), provideTurnPlugins, guardTurn, Effect.provide(TurnLive(live), { local: !0 }), Effect.provideService(ConversationMemory, memory), Effect.provideService(ToolRegistry, registry), Effect.provideService(StepLoop, loop), Effect.provide(context), untilClosed(writer), harnessDefectsAsFailures, Effect.exit);
+      if (own && Exit.isSuccess(exit))
+        yield* writer.end(turnEndingOf(exit));
+      if (own && Exit.isFailure(exit))
+        yield* writer.end(turnEndingOf(exit)).pipe(Effect.ignore);
+      return yield* exit;
+    }).pipe(measureTurn, traceTurn(writer, { spanMeta: config.spanMeta ?? [] }));
+  }))), activity = processActivity.pipe(Effect.updateContext((current) => Context.merge(Context.omit(TurnActivity, TaskActivity)(current), Context.pick(TurnActivity, TaskActivity)(runtime))));
+  return { fingerprint: graphFingerprint(graph), activity, turn };
 });
 export const Agent = { define: makeAgent };

package/dist/agent.golden.test.d.ts

@@ -68,6 +68,15 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
         } | {
             readonly _tag: "TurnStarted";
             readonly prompt: string;
+            readonly attachments?: readonly {
+                readonly type: "media";
+                readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+                readonly data: string;
+                readonly fingerprint: string;
+                readonly bytes: number;
+                readonly name?: string;
+                readonly alt?: string;
+            }[];
         } | {
             readonly _tag: "TurnContext";
             readonly sectionId: string;
@@ -77,7 +86,19 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
             readonly _tag: "Message";
             readonly message: {
                 readonly role: "user";
-                readonly content: string;
+                readonly content: string | readonly ({
+                    readonly type: "media";
+                    readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+                    readonly data: string;
+                    readonly fingerprint: string;
+                    readonly bytes: number;
+                    readonly name?: string;
+                    readonly alt?: string;
+                } | {
+                    readonly type: "text";
+                    readonly text: string;
+                    readonly providerOptions?: unknown;
+                })[];
                 readonly providerOptions?: unknown;
             } | {
                 readonly role: "assistant";
@@ -91,9 +112,9 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
                     readonly providerOptions?: unknown;
                 } | {
                     readonly type: "tool-call";
+                    readonly input: unknown;
                     readonly toolCallId: string;
                     readonly toolName: string;
-                    readonly input: unknown;
                     readonly providerOptions?: unknown;
                     readonly providerExecuted?: boolean | undefined;
                 })[];
@@ -102,9 +123,18 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
                 readonly role: "tool";
                 readonly content: readonly {
                     readonly type: "tool-result";
+                    readonly output: unknown;
                     readonly toolCallId: string;
                     readonly toolName: string;
-                    readonly output: unknown;
+                    readonly media?: readonly {
+                        readonly type: "media";
+                        readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+                        readonly data: string;
+                        readonly fingerprint: string;
+                        readonly bytes: number;
+                        readonly name?: string;
+                        readonly alt?: string;
+                    }[];
                     readonly providerOptions?: unknown;
                     readonly isError?: boolean | undefined;
                 }[];
@@ -115,9 +145,6 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
             readonly toolCallId: string;
             readonly toolName: string;
             readonly isError: boolean;
-            readonly encoded: unknown;
-            readonly view: string;
-            readonly viewVersion: string;
             readonly subjects: readonly {
                 readonly kind: string;
                 readonly id: string;
@@ -131,7 +158,17 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
                 readonly url: string;
                 readonly alt: string | null;
             }[];
+            readonly encoded: unknown;
+            readonly view: string;
+            readonly viewVersion: string;
             readonly pinned: boolean;
+            readonly media?: readonly {
+                readonly path: readonly (string | number)[];
+                readonly fingerprint: string;
+                readonly mediaType: "image/png" | "image/jpeg" | "image/gif" | "image/webp";
+                readonly bytes: number;
+            }[];
+            readonly mediaNotes?: readonly string[];
         } | {
             readonly _tag: "ToolDigest";
             readonly entry: string;
@@ -171,6 +208,10 @@ export declare const runGolden: (runner: Effect.Effect<Pick<Agent, "turn">, Harn
                 readonly _tag: "Summarize";
                 readonly keepFromTurn: number;
                 readonly summary: string;
+            } | {
+                readonly _tag: "OmitMedia";
+                readonly entries: readonly string[];
+                readonly reason: string;
             };
         } | {
             readonly _tag: "TurnEnded";

package/dist/events-guide.test.d.ts

@@ -0,0 +1,207 @@
+import { Context, Duration, Effect, Layer, Option, Schema, Scope, Stream } from "effect";
+import { LanguageModel, Tool } from "effect/ai";
+import { Agent, ConversationId, HarnessError, Sessions, TurnEvents } from "@xandreed/sdk";
+import type { Capability, SessionAddress, SessionLog, Turn, TurnEvent, TurnEventOf, TurnEventsService, TurnOutcome } from "@xandreed/sdk";
+import type { FeedOptions, FeedProjection, SsePeer } from "@xandreed/plugin-render";
+/** What a server instance is built from. */
+export interface HostOptions {
+    /** The session store every instance shares (your database; `SessionLogMemoryLive` is one process's). */
+    readonly log: Layer.Layer<SessionLog>;
+    /** From `@xandreed/plugin-models`, or any effect/ai provider. */
+    readonly model: LanguageModel.LanguageModel;
+    readonly capabilities?: ReadonlyArray<Capability>;
+    readonly feed?: FeedOptions;
+}
+/**
+ * One server instance: the agent, the services it was given (the Sessions
+ * it writes through, and their activity probe), the journal feed and the model.
+ */
+export declare const makeHost: (options: HostOptions) => Effect.Effect<{
+    agent: Agent;
+    services: Context.Context<Sessions | import("@xandreed/core").TurnActivity>;
+    sessions: {
+        readonly create: (input: {
+            readonly owner: string;
+            readonly id?: ConversationId;
+            readonly origin?: string;
+            readonly meta?: import("@xandreed/core").JsonObject;
+        }) => Effect.Effect<import("@xandreed/core").SessionView, import("@xandreed/core").SessionExists | import("@xandreed/core").SessionLogError>;
+        readonly fork: (parent: SessionAddress, input: {
+            readonly id?: ConversationId;
+            readonly origin: string;
+            readonly meta?: import("@xandreed/core").JsonObject;
+            readonly inherit: boolean;
+        }) => Effect.Effect<import("@xandreed/core").SessionView, import("@xandreed/core").SessionExists | import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly get: (address: SessionAddress) => Effect.Effect<import("@xandreed/core").SessionView, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly list: (query: {
+            readonly owner: string;
+            readonly limit?: number;
+            readonly before?: import("@xandreed/core").SessionListCursor;
+            readonly parent?: ConversationId;
+        }) => Effect.Effect<import("@xandreed/core").SessionPage, import("@xandreed/core").SessionLogError>;
+        readonly remove: (address: SessionAddress) => Effect.Effect<void, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly read: (address: SessionAddress, query?: {
+            readonly after?: number;
+            readonly kinds?: ReadonlyArray<string>;
+            readonly limit?: number;
+        }) => Effect.Effect<ReadonlyArray<import("@xandreed/core").SessionLogEvent>, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly changes: (address: SessionAddress) => Stream.Stream<void>;
+        readonly lookup: (address: SessionAddress, key: string) => Effect.Effect<Option.Option<number>, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly transact: <A, E>(address: SessionAddress, decide: (view: import("@xandreed/core").SessionView) => Effect.Effect<import("@xandreed/core").Decision<A>, E>) => Effect.Effect<import("@xandreed/core").Decided<A>, E | import("@xandreed/core").ReservedKind | import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly cancel: (address: SessionAddress, turn: number) => Effect.Effect<{
+            readonly cancelled: boolean;
+            readonly pending: number;
+        }, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly begin: (address: SessionAddress, input: import("@xandreed/core").BeginTurn) => Effect.Effect<import("@xandreed/core").TurnWriter, import("@xandreed/core").AttachmentRejected | import("@xandreed/core").SessionBusy | import("@xandreed/core").TurnDuplicate | import("@xandreed/core").KeyConflict | import("@xandreed/core").NothingPending | import("@xandreed/core").NotResumable | import("@xandreed/core").TurnRefused | import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError, Scope.Scope>;
+        readonly deliver: (address: SessionAddress, item: import("@xandreed/core").InboxItem) => Effect.Effect<{
+            readonly delivered: boolean;
+            readonly pending: number;
+        }, import("@xandreed/core").InboxFull | import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError>;
+        readonly drain: <E, R>(address: SessionAddress, run: (writer: import("@xandreed/core").TurnWriter) => Effect.Effect<void, E, R>, options?: {
+            readonly maxTurns?: number;
+            readonly meta?: import("@xandreed/core").JsonObject;
+        }) => Effect.Effect<{
+            readonly turns: number;
+        }, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError, R>;
+    };
+    feed: {
+        readonly frames: (feed: import("@xandreed/plugin-render").FeedScope, after: number, project: FeedProjection) => Stream.Stream<import("@xandreed/plugin-render").FeedFrame, import("@xandreed/plugin-render").RenderError>;
+    };
+    model: LanguageModel.LanguageModel;
+}, HarnessError, Scope.Scope>;
+export type Host = Effect.Success<ReturnType<typeof makeHost>>;
+/** Built once per server instance (a module-level promise in Next.js); its scope is never closed. */
+export declare const startHost: (options: HostOptions) => Promise<Host>;
+/** One SSE frame for the client: an event name and its JSON data. */
+export interface Frame {
+    readonly event: string;
+    readonly data: Readonly<Record<string, unknown>>;
+}
+/** The bus events a client is shown, as frames; `None` skips one. Tool input and output stay on the server. */
+export declare const progressOf: (event: TurnEvent) => Option.Option<Frame>;
+/** Sends one frame to the client. It must never fail (see `clientPush`). */
+export type Push = (frame: Frame) => Effect.Effect<void>;
+/**
+ * `use` for a turn streamed to a client: one background subscription (one
+ * ordered lane, off the loop's path) for every frame, each tagged with the
+ * turn's number, then the run.
+ */
+export declare const streamTo: (push: Push) => (turn: Turn) => Effect.Effect<TurnOutcome, HarnessError, Scope.Scope>;
+/** Whether the client took `bytes` within `timeout`: a write still waiting then, or one that failed (the client left), was not. */
+export declare const writeWithin: (writer: WritableStreamDefaultWriter<Uint8Array>, bytes: Uint8Array, timeout: Duration.Input) => Effect.Effect<boolean, never, never>;
+/**
+ * Ends a client's stream without waiting: a stream aborted while a write
+ * still waits settles neither until the client reads again or leaves.
+ */
+export declare const closeStream: (writer: WritableStreamDefaultWriter<Uint8Array>) => Effect.Effect<Promise<undefined>, never, never>;
+/**
+ * A client's stream as a `Push` that never fails and never holds the turn
+ * up: a write the client has not taken within `timeout` marks it gone and
+ * aborts the stream, and every later frame is dropped. A handler that fails
+ * fails the turn; one that never returns keeps it from recording its reply.
+ */
+export declare const clientPush: (writer: WritableStreamDefaultWriter<Uint8Array>, timeout?: Duration.Input) => Effect.Effect<Push, never, never>;
+/** For the turn's `layer`: a subscription there sees `turn.started` (with `meta` and `resumes`), which `use` never does. */
+export declare const onTurnStarted: (handle: (event: TurnEventOf<"turn.started">) => Effect.Effect<void>) => Layer.Layer<never, never, TurnEvents>;
+/**
+ * From `use`: a subscription moved into `outer`, a scope the caller keeps
+ * open past the turn, the only kind that sees `turn.ended`. Its handler runs
+ * after the turn's own scopes have closed, and must not fail.
+ */
+export declare const onTurnEnded: (outer: Scope.Scope, handle: (event: TurnEventOf<"turn.ended">) => Effect.Effect<void>) => (turn: Turn) => Effect.Effect<void, never, never>;
+export declare const Lookup: Tool.Tool<"lookup", {
+    readonly parameters: Schema.Struct<{
+        readonly query: Schema.String;
+    }>;
+    readonly success: Schema.Struct<{
+        readonly found: Schema.Number;
+    }>;
+    readonly failure: Schema.Struct<{
+        readonly error: Schema.String;
+        readonly message: Schema.String;
+    }>;
+    readonly failureMode: "return";
+}, never>;
+/** Typed reactions to `lookup`'s successful calls, and a line for every call refused or failed. */
+export declare const watchTools: (turn: Turn, report: (line: string) => Effect.Effect<void>) => Effect.Effect<void, never, Scope.Scope>;
+/** The application's own event: typed by its schema, journaled under its name, seen by the session's followers. */
+export declare const Progress: {
+    name: string;
+    make: (data: {
+        readonly stage: string;
+        readonly done: number;
+    }) => Effect.Effect<TurnEvent, HarnessError>;
+    select: (event: TurnEvent) => Option.Option<{
+        readonly stage: string;
+        readonly done: number;
+    }>;
+    publish: (events: TurnEventsService, data: {
+        readonly stage: string;
+        readonly done: number;
+    }) => Effect.Effect<void, HarnessError, never>;
+    on: <R>(handle: (data: {
+        readonly stage: string;
+        readonly done: number;
+    }) => Effect.Effect<void, HarnessError, R>, options?: import("@xandreed/core").SubscribeOptions) => import("@xandreed/core").Subscription<R>;
+};
+/** Publish it from `use` (`turn.events`), a task, a tool (`RunContext.events`) or a session plugin (`TurnEvents`). */
+export declare const reportStage: (events: TurnEventsService, stage: string, done: number) => Effect.Effect<void, HarnessError, never>;
+/** The events stored after `cursor`, oldest first, and the cursor to read from next. */
+export declare const readAfter: (sessions: typeof Sessions.Service, address: SessionAddress, cursor: number) => Effect.Effect<{
+    events: readonly {
+        readonly session: string & import("effect/Brand").Brand<"ConversationId">;
+        readonly seq: number;
+        readonly turn: Option.Option<number>;
+        readonly kind: string;
+        readonly at: number;
+        readonly data: {
+            readonly [x: string]: unknown;
+        };
+    }[];
+    cursor: number;
+}, import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError, never>;
+/** How each turn of a session ended, as stored: the reason and, when it failed, the failing error's code. */
+export declare const endingsOf: (sessions: typeof Sessions.Service, address: SessionAddress) => Effect.Effect<{
+    turn: number | null;
+    reason: "partial" | "completed" | "failed" | "cancelled" | "interrupted";
+    code: string | null;
+}[], Schema.SchemaError | import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError, never>;
+/** How a turn ended and what it replied, as the journal has it. */
+export interface StoredAnswer {
+    readonly turn: number;
+    readonly reason: string;
+    readonly reply: string | null;
+}
+/** What the turn begun with `key` answered, from the journal: none until that turn has ended. */
+export declare const storedAnswer: (sessions: typeof Sessions.Service, address: SessionAddress, key: string) => Effect.Effect<Option.None<StoredAnswer> | Option.Some<StoredAnswer>, Schema.SchemaError | import("@xandreed/core").SessionMissing | import("@xandreed/core").SessionLogError, never>;
+/** The journal as a client sees it: each shown record with its turn, and the app's own `app.*` events as they are. */
+export declare const clientProjection: FeedProjection;
+export declare const statusOf: (code: string) => number;
+export declare const problem: (status: number, code: string) => Response;
+/**
+ * POST /sessions/:id/turns, `{ text, resumes? }` with an `Idempotency-Key`
+ * header: the turn as SSE frames, `started` first and `done` last. A turn
+ * that cannot begin is answered with its code's status before anything
+ * streams. `waitUntil` keeps the turn running after the client leaves.
+ */
+export declare const turnRoute: (host: Host, owner: string, id: string, request: Request, waitUntil: (work: Promise<unknown>) => void) => Promise<Response>;
+/**
+ * POST /sessions, `{ id? }`: a new session, 201. A client that names the id
+ * may retry: its own session again is 200, an id another owner holds is 409.
+ */
+export declare const createSessionRoute: (host: Host, owner: string, request: Request) => Promise<Response>;
+/**
+ * An SSE peer over a Web stream: a write never fails, and `closed` completes
+ * when the client leaves, or once a write has waited `timeout` on a client
+ * that stopped reading: the stream is then aborted, and the feed stops.
+ */
+export declare const webSsePeer: (writer: WritableStreamDefaultWriter<Uint8Array>, signal: AbortSignal, timeout?: Duration.Input) => SsePeer;
+/**
+ * GET /sessions/:id/events: the session's journal from the client's cursor
+ * as SSE (`id: <seq>`, `event: <kind>`), polled, and woken by this
+ * instance's own commits, until the feed's `maxDurationMs` or a client that
+ * stopped reading is dropped; EventSource then reconnects with `Last-Event-ID`.
+ */
+export declare const eventsRoute: (host: Host, owner: string, id: string, request: Request, waitUntil: (work: Promise<unknown>) => void) => Promise<Response>;
+/** GET /ping: what this instance has in flight, for a load balancer, or a deploy waiting to stop it. */
+export declare const pingRoute: (host: Host) => Promise<Response>;

package/dist/index.d.ts

@@ -1,6 +1,3 @@
 export * from "@xandreed/core";
-export * from "./harness.js";
-export * from "./approval.adapter.js";
-export { domainLoop, domainSession } from "./domain-session.adapter.js";
-export { Agent } from "./agent.adapter.js";
+export { Agent, turnBeginCodes } from "./agent.adapter.js";
 export type { AgentConfig, AgentPluginEntry } from "./agent.adapter.js";

package/dist/index.js

@@ -1,5 +1,2 @@
 export * from "@xandreed/core";
-export * from "./harness.js";
-export * from "./approval.adapter.js";
-export { domainLoop, domainSession } from "./domain-session.adapter.js";
-export { Agent } from "./agent.adapter.js";
+export { Agent, turnBeginCodes } from "./agent.adapter.js";

package/dist/journal-compat.test.d.ts

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

package/dist/models-plugin.test.d.ts

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

package/dist/resume.journey.test.d.ts

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

package/package.json

@@ -1,6 +1,10 @@
 {
   "name": "@xandreed/sdk",
-  "version": "0.12.0",
+  "version": "0.14.0",
+  "engines": {
+    "node": ">=24",
+    "bun": ">=1.3.0"
+  },
   "type": "module",
   "main": "./dist/index.js",
   "exports": {
@@ -10,11 +14,9 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.12.0",
-    "effect": "4.0.0-rc.118",
-    "@xandreed/runtime": "0.12.0",
-    "@xandreed/plugin-memory": "0.12.0",
-    "@xandreed/plugin-session-sqlite": "0.12.0"
+    "@xandreed/core": "0.14.0",
+    "effect": "4.0.7",
+    "@xandreed/runtime": "0.14.0"
   },
   "private": false,
   "types": "./dist/index.d.ts",
@@ -25,9 +27,5 @@
     "README.md",
     "LICENSE"
   ],
-  "engines": {
-    "node": ">=24",
-    "bun": ">=1.3.0"
-  },
   "license": "MIT"
 }

package/dist/approval.adapter.d.ts

@@ -1,5 +0,0 @@
-import { Effect } from "effect";
-import { Approval } from "@xandreed/core";
-import type { HarnessError } from "@xandreed/core";
-/** A host supplies interaction; unattended hosts deny requests by default. */
-export declare const approvalPlugin: (request?: (description: string) => Effect.Effect<boolean, HarnessError>) => import("@xandreed/core").TypedPlugin<{}, {}, Approval, never, never>;

package/dist/approval.adapter.js

@@ -1,11 +0,0 @@
-import { Effect, Layer, Schema } from "effect";
-import { Approval, definePlugin } from "@xandreed/core";
-export const approvalPlugin = (request = () => Effect.succeed(!1)) => definePlugin({
-  id: "efferent/approval-host",
-  version: "0.12.0",
-  scope: "runtime",
-  config: Schema.Struct({}),
-  defaults: {},
-  provides: [Approval],
-  layer: () => Layer.succeed(Approval, { request })
-});

package/dist/domain-session.adapter.d.ts

@@ -1,27 +0,0 @@
-import { Effect, Option } from "effect";
-import { HarnessError, SessionStore } from "@xandreed/core";
-import type { ConversationId, Session, SessionHandle } from "@xandreed/core";
-/**
- * Adapt a domain session's event protocol to the durable harness lifecycle.
- * When the host provides a ConversationStore, the domain session's writes to
- * its conversation are bound to the harness run (see `turnBound`). They are
- * recorded beside the turn, not through its writer.
- */
-export declare const domainLoop: <E extends {
-    readonly type: string;
-}, R>(options: {
-    readonly create: (id: ConversationId) => Effect.Effect<Session<E>, never, R>;
-    readonly snapshot?: (id: ConversationId) => Effect.Effect<Readonly<Record<string, unknown>>, HarnessError, R>;
-    readonly restore?: (id: ConversationId, data: Readonly<Record<string, unknown>>) => Effect.Effect<void, HarnessError, R>;
-    readonly result: (event: E) => Option.Option<{
-        readonly text: string;
-        readonly outcome: "completed" | "partial";
-    }>;
-}) => Effect.Effect<{
-    readonly run: (input: import("@xandreed/core").LoopInput) => Effect.Effect<{
-        readonly text: string;
-        readonly outcome: "completed" | "partial";
-    }, HarnessError>;
-}, HarnessError, import("effect/Scope").Scope | SessionStore | R>;
-/** Preserve a domain host's public stream vocabulary while the SDK owns lifecycle. */
-export declare const domainSession: <E>(handle: SessionHandle, decode: (value: unknown) => Option.Option<E>, onError: (message: string) => E) => Session<E>;

package/dist/domain-session.adapter.js

@@ -1,56 +0,0 @@
-import { Context, Effect, Fiber, Filter, Option, Ref, Stream } from "effect";
-import { AgentLoop, ConversationStore, HarnessError, SessionEnvironment, SessionStore, StoreError } from "@xandreed/core";
-const turnBound = (store, id, active, current) => {
-  const guard = (target, write) => target !== id ? write : Effect.gen(function* () {
-    const origin = yield* current, running = yield* Ref.get(active);
-    return yield* Option.isSome(origin) && Option.contains(running, origin.value) ? write : Effect.fail(new StoreError({ message: `conversation ${id}: its turn is over, so the write is refused` }));
-  });
-  return ConversationStore.of({
-    ...store,
-    append: (target, message) => guard(target, store.append(target, message)),
-    appendAll: (target, messages) => guard(target, store.appendAll(target, messages)),
-    checkpoint: (target, summary) => guard(target, store.checkpoint(target, summary)),
-    checkpointAt: (target, summary, position) => guard(target, store.checkpointAt(target, summary, position)),
-    setTitle: (target, title) => guard(target, store.setTitle(target, title)),
-    recordOutcome: (target, outcome, reason) => guard(target, store.recordOutcome(target, outcome, reason))
-  });
-};
-export const domainLoop = (options) => Effect.gen(function* () {
-  const context = yield* Effect.context(), store = yield* SessionStore, environment = yield* Effect.serviceOption(SessionEnvironment), conversations = yield* Effect.serviceOption(ConversationStore), currentDomainRun = Context.Reference(`@xandreed/sdk/domainRun/${yield* Effect.sync(() => crypto.randomUUID())}`, { defaultValue: () => Option.none() }), running = yield* Ref.make(Option.none()), acquire = (id) => Effect.gen(function* () {
-    if (options.restore !== void 0) {
-      const snapshot = (yield* store.read(id, -1)).filter((event) => event.name === "domain.snapshot").at(-1);
-      if (snapshot !== void 0)
-        yield* options.restore(id, snapshot.data).pipe(Effect.provide(context));
-    }
-    const created = options.create(id);
-    return yield* Option.match(conversations, {
-      onNone: () => created,
-      onSome: (conversation) => created.pipe(Effect.provideService(ConversationStore, turnBound(conversation, id, running, currentDomainRun)))
-    }).pipe(Effect.provide(context));
-  }), record = Option.isSome(environment) ? environment.value.session : void 0, active = yield* Ref.make(record === void 0 ? Option.none() : Option.some(yield* acquire(record.id)));
-  yield* Effect.addFinalizer(() => Ref.get(active).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (session) => session.shutdown }))));
-  return AgentLoop.of({ run: (input) => Effect.scoped(Effect.gen(function* () {
-    const token = yield* Effect.sync(() => crypto.randomUUID());
-    yield* Ref.set(running, Option.some(token));
-    const found = yield* Ref.get(active), session = Option.isSome(found) ? found.value : yield* acquire(input.session.id).pipe(Effect.tap((value) => Ref.set(active, Option.some(value)))), cursor = (yield* session.state).cursor, result = yield* Ref.make(Option.none()), collector = yield* Effect.forkScoped(session.subscribe(cursor).pipe(Stream.tap(({ event }) => input.publish({ name: "domain.event", runId: input.runId, data: { event } })), Stream.tap(({ event }) => Ref.update(result, (current) => Option.orElse(options.result(event), () => current))), Stream.takeUntil(({ event }) => Option.isSome(options.result(event))), Stream.runDrain));
-    yield* Effect.forkScoped(session.transient.pipe(Stream.runForEach((event) => input.transient({ name: "domain.delta", runId: input.runId, data: { event } }))));
-    yield* session.send(input.userMessage.text).pipe(Effect.provideService(currentDomainRun, Option.some(token)));
-    if (!(yield* session.state).log.filter((entry) => entry.seq >= cursor).some(({ event }) => Option.isSome(options.result(event))))
-      return yield* Effect.fail(new HarnessError({ code: "domain.unsettled", message: "The domain turn ended without a terminal event" }));
-    yield* Fiber.join(collector);
-    if (options.snapshot !== void 0)
-      yield* options.snapshot(input.session.id).pipe(Effect.provide(context), Effect.flatMap((data) => input.publish({ name: "domain.snapshot", runId: input.runId, data })));
-    return yield* Ref.get(result).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.fail(new HarnessError({ code: "domain.result", message: "The domain session ended without a result" })), onSome: Effect.succeed })));
-  })).pipe(Effect.ensuring(Ref.set(running, Option.none())), Effect.onInterrupt(() => Ref.get(active).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (session) => session.interrupt }))))) });
-}), domainSession = (handle, decode, onError) => {
-  const event = (name, data) => name === "domain.event" ? decode(data.event) : ["run.failed", "run.cancelled"].includes(name) ? Option.some(onError(String(data.message))) : Option.none();
-  return {
-    conversationId: handle.record.id,
-    send: (text) => handle.send(text).pipe(Effect.ignore),
-    interrupt: handle.interrupt,
-    shutdown: handle.close,
-    state: handle.history.pipe(Effect.map((events) => ({ cursor: (events.at(-1)?.seq ?? -1) + 1, log: events.flatMap((entry) => Option.toArray(Option.map(event(entry.name, entry.data), (value) => ({ seq: entry.seq, event: value })))) })), Effect.orDie),
-    subscribe: (since) => handle.events(since - 1).pipe(Stream.map((entry) => Option.map(event(entry.name, entry.data), (value) => ({ seq: entry.seq, event: value }))), Stream.filterMap(Filter.fromPredicateOption((value) => value)), Stream.orDie),
-    transient: handle.transient.pipe(Stream.filterMap(Filter.fromPredicateOption((entry) => entry.name === "domain.delta" ? decode(entry.data.event) : Option.none())))
-  };
-};

package/dist/harness.d.ts

@@ -1,43 +0,0 @@
-import { Effect, Scope } from "effect";
-import { HarnessError } from "@xandreed/core";
-import type { ConversationId, HarnessConfig, Plugin, SessionHandle } from "@xandreed/core";
-import type { PluginGraph } from "@xandreed/runtime";
-export declare const makeHarness: (options: {
-    readonly config: HarnessConfig;
-    readonly plugins: ReadonlyArray<Plugin>;
-    readonly workspace: string;
-}) => Effect.Effect<{
-    create: () => Effect.Effect<SessionHandle, HarnessError, never>;
-    resume: (id: ConversationId) => Effect.Effect<SessionHandle, HarnessError, never>;
-    fork: (id: ConversationId, through: number) => Effect.Effect<SessionHandle, HarnessError, never>;
-    list: Effect.Effect<readonly {
-        readonly createdAt: number;
-        readonly id: string & import("effect/Brand").Brand<"ConversationId">;
-        readonly profile: string;
-        readonly workspace: string;
-        readonly parent?: (string & import("effect/Brand").Brand<"ConversationId">) | undefined;
-    }[], HarnessError, never>;
-    graph: Effect.Effect<PluginGraph, never, never>;
-    reconfigure: (config: HarnessConfig, plugins?: ReadonlyArray<Plugin>) => Effect.Effect<"applied" | "restart-required", HarnessError, never>;
-}, HarnessError, Scope.Scope>;
-export declare const Harness: {
-    make: (options: {
-        readonly config: HarnessConfig;
-        readonly plugins: ReadonlyArray<Plugin>;
-        readonly workspace: string;
-    }) => Effect.Effect<{
-        create: () => Effect.Effect<SessionHandle, HarnessError, never>;
-        resume: (id: ConversationId) => Effect.Effect<SessionHandle, HarnessError, never>;
-        fork: (id: ConversationId, through: number) => Effect.Effect<SessionHandle, HarnessError, never>;
-        list: Effect.Effect<readonly {
-            readonly createdAt: number;
-            readonly id: string & import("effect/Brand").Brand<"ConversationId">;
-            readonly profile: string;
-            readonly workspace: string;
-            readonly parent?: (string & import("effect/Brand").Brand<"ConversationId">) | undefined;
-        }[], HarnessError, never>;
-        graph: Effect.Effect<PluginGraph, never, never>;
-        reconfigure: (config: HarnessConfig, plugins?: ReadonlyArray<Plugin>) => Effect.Effect<"applied" | "restart-required", HarnessError, never>;
-    }, HarnessError, Scope.Scope>;
-};
-export type Harness = Effect.Success<ReturnType<typeof makeHarness>>;

package/dist/harness.js

@@ -1,186 +0,0 @@
-import { Cause, Clock, Context, Effect, Exit, Fiber, Option, PubSub, Ref, Scope, Stream, Semaphore } from "effect";
-import { AgentLoop, HarnessError, SessionEnvironment, SessionStore, Sessions, TurnHooks, UserMessage } from "@xandreed/core";
-import { activateGraph, graphFingerprint, resolveGraph } from "@xandreed/runtime";
-const failure = (code, message) => new HarnessError({ code, message }), pendingAfter = (queue, events) => events.reduce((pending, event) => {
-  if (event.name === "input.queued" && typeof event.data.id === "string" && typeof event.data.text === "string") {
-    const id = event.data.id;
-    return pending.some((input) => input.id === id) ? pending : [...pending, { id, text: event.data.text, kind: event.data.kind === "steer" ? "steer" : "turn" }];
-  }
-  return event.name === "input.claimed" ? pending.filter((input) => input.id !== event.data.id) : pending;
-}, queue), advance = (state, events) => {
-  const fresh = events.filter((event) => event.seq > state.seen);
-  return fresh.length === 0 ? state : { seen: fresh.reduce((last, event) => Math.max(last, event.seq), state.seen), queue: pendingAfter(state.queue, fresh) };
-}, isClosed = (error) => error.code === "turn.closed", service = (context, tag) => Option.match(Context.getOption(context, tag), {
-  onNone: () => Effect.fail(failure("service.missing", `The profile does not provide ${tag.key}`)),
-  onSome: Effect.succeed
-});
-export const makeHarness = (options) => Effect.gen(function* () {
-  const parent = yield* Effect.scope, initial = yield* resolveGraph(options.config, options.plugins, [SessionEnvironment.key]), graphRef = yield* Ref.make(initial), registryRef = yield* Ref.make(options.plugins), seed = Context.make(SessionEnvironment, { workspace: options.workspace }), runtime = yield* activateGraph(initial, "runtime", Context.makeUnsafe(seed.mapUnsafe), parent), store = yield* service(runtime, SessionStore), sessions = yield* Option.match(Context.getOption(runtime, Sessions), {
-    onNone: () => Effect.fail(failure("service.missing", `Harness requires ${Sessions.key}: add sessionsPlugin (@xandreed/plugin-sessions) to the configuration beside the session storage plugin`)),
-    onSome: Effect.succeed
-  }), handles = yield* Ref.make(new Map), open = (record) => Effect.gen(function* () {
-    const existing = (yield* Ref.get(handles)).get(record.id);
-    if (existing !== void 0)
-      return existing;
-    const journal = yield* store.read(record.id, -1), durable = yield* sessions.get({ id: record.id, owner: options.workspace }).pipe(Effect.mapError((error) => failure("session.log", String(error)))), abandoned = journal.reduce((runs, event) => {
-      if (event.runId === void 0)
-        return runs;
-      return event.name === "run.started" ? [...runs, event.runId] : ["run.completed", "run.cancelled", "run.failed"].includes(event.name) ? runs.filter((id) => id !== event.runId) : runs;
-    }, []);
-    yield* Effect.forEach(abandoned.filter((runId) => !Option.exists(durable.open, (open) => open.runId === runId)), (runId) => store.append(record.id, { name: "run.cancelled", runId, data: { reason: "process interrupted before settlement; tool effects may be incomplete" } }));
-    const pending = yield* Ref.make(advance({ seen: -1, queue: [] }, journal)), notifications = yield* PubSub.sliding(1), transientHub = yield* PubSub.sliding(128), running = yield* Ref.make(Option.none()), busy = yield* Ref.make(!1), closed = yield* Ref.make(!1), writing = yield* Ref.make(Option.none()), position = yield* Ref.make(-1), publishing = yield* Semaphore.make(1), gate = yield* Semaphore.make(1), acquire = (graph) => Effect.gen(function* () {
-      const scope = yield* Scope.make(), sessionSeed = Context.add(runtime, SessionEnvironment, { workspace: options.workspace, session: record }), context = yield* activateGraph(graph, "session", Context.makeUnsafe(sessionSeed.mapUnsafe), scope).pipe(Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))));
-      yield* service(context, AgentLoop).pipe(Effect.onError((cause) => Scope.close(scope, Exit.failCause(cause))));
-      return { context, scope, graph, fingerprint: graphFingerprint(graph) };
-    }), mounted = yield* Ref.make(yield* acquire(yield* Ref.get(graphRef))), publishUnlocked = (body, outside = !1) => Ref.get(writing).pipe(Effect.flatMap(Option.match({
-      onNone: () => store.append(record.id, body),
-      onSome: (writer) => writer.transact((foreign) => Effect.gen(function* () {
-        const foreignPosition = foreign.reduce((max, entry) => entry.kind === "harness.event" && typeof entry.data.event === "object" && entry.data.event !== null && ("seq" in entry.data.event) && typeof entry.data.event.seq === "number" ? Math.max(max, entry.data.event.seq) : max, -1), seq = Math.max(yield* Ref.get(position), foreignPosition) + 1, event = { ...body, version: 1, id: yield* Effect.sync(() => crypto.randomUUID()), sessionId: record.id, seq, at: yield* Clock.currentTimeMillis };
-        return { drafts: [{ kind: "harness.event", data: { event } }], result: event };
-      })).pipe(Effect.map((done) => done.result), Effect.tap((event) => Ref.set(position, event.seq)), Effect.catchTag("HarnessError", (error) => outside && isClosed(error) ? store.append(record.id, body) : Effect.fail(error)))
-    })), Effect.tap(() => PubSub.publish(notifications, void 0))), publish = (body) => publishing.withPermits(1)(publishUnlocked(body)), refreshPending = Ref.get(pending).pipe(Effect.flatMap((state) => store.read(record.id, state.seen)), Effect.flatMap((events) => Ref.update(pending, (state) => advance(state, events)))), assertOpen = Ref.get(closed).pipe(Effect.flatMap((value) => value ? Effect.fail(failure("session.closed", "Session is closed")) : Effect.void)), refresh = Effect.gen(function* () {
-      if (yield* Ref.get(busy))
-        return;
-      const graph = yield* Ref.get(graphRef), previous = yield* Ref.get(mounted);
-      if (graphFingerprint(graph) === previous.fingerprint)
-        return;
-      const next = yield* acquire(graph);
-      yield* Ref.set(mounted, next);
-      yield* Scope.close(previous.scope, Exit.void);
-      yield* publish({ name: "config.applied", data: { fingerprint: next.fingerprint } });
-    }), endedElsewhere = (writer) => sessions.read({ id: record.id, owner: options.workspace }, { after: writer.started.seq, kinds: ["turn.ended"] }).pipe(Effect.map((events) => Option.map(Option.fromNullishOr(events.find((event) => Option.contains(event.turn, writer.admitted.turn))), (event) => event.data.reason === "cancelled" ? "cancelled" : "interrupted")), Effect.catchTag("SessionMissing", () => Effect.succeed(Option.some("removed"))), Effect.mapError((error) => failure("session.log", error.message))), claim = (input) => publish({ name: "input.claimed", data: { id: input.id } }).pipe(Effect.andThen(refreshPending)), steering = Effect.gen(function* () {
-      yield* refreshPending;
-      const inputs = (yield* Ref.get(pending)).queue.filter((input) => input.kind === "steer");
-      yield* Effect.forEach(inputs, claim);
-      return inputs.length === 0 ? Option.none() : Option.some(inputs.map((input) => input.text).join(`
-
-`));
-    }), run = (input) => Effect.scoped(Effect.gen(function* () {
-      yield* refresh;
-      const current = yield* Ref.get(mounted), loop = yield* service(current.context, AgentLoop), hooks = Context.getOption(current.context, TurnHooks), runId = crypto.randomUUID(), begun = yield* Effect.result(sessions.begin({ id: record.id, owner: options.workspace }, {
-        _tag: "User",
-        userMessage: new UserMessage({ text: input.text }),
-        runId,
-        key: input.id,
-        command: { kind: input.kind }
-      }));
-      if (begun._tag === "Failure") {
-        if (begun.failure._tag === "TurnDuplicate") {
-          yield* claim(input);
-          return !0;
-        }
-        return yield* Effect.fail(failure(begun.failure._tag === "SessionBusy" ? "session.busy" : "session.begin", `The turn could not begin (${begun.failure._tag})`));
-      }
-      const writer = begun.success;
-      yield* refreshPending;
-      if (!(yield* Ref.get(pending)).queue.some((item) => item.id === input.id)) {
-        yield* writer.end({ reason: "cancelled", failure: Option.some({ code: "input.consumed", message: "the input was consumed by an earlier turn" }) }).pipe(Effect.catchTag("HarnessError", (error) => isClosed(error) ? Effect.void : Effect.fail(error)));
-        return !0;
-      }
-      yield* Ref.set(position, (yield* Ref.get(pending)).seen);
-      yield* Ref.set(writing, Option.some(writer));
-      yield* Effect.addFinalizer(() => Ref.set(writing, Option.none()));
-      yield* claim(input);
-      const started = yield* publish({ name: "run.started", runId, data: { config: current.fingerprint } });
-      if (!(yield* store.read(record.id, started.seq - 1)).some((event) => event.id === started.id))
-        return yield* Effect.fail(failure("session.store", "The SessionStore does not read the events Sessions writes: it must be the projection over the same SessionLog"));
-      const args = {
-        session: record,
-        runId,
-        userMessage: new UserMessage({ text: input.text }),
-        system: current.graph.config.system ?? "You are a helpful agent.",
-        publish,
-        transient: (event) => PubSub.publish(transientHub, event).pipe(Effect.asVoid),
-        steering,
-        history: (after, names) => store.read(record.id, after).pipe(Effect.map((events) => names.length === 0 ? events : events.filter((event) => names.includes(event.name)))),
-        services: Context.empty()
-      }, task = Effect.gen(function* () {
-        const prepared = Option.isSome(hooks) ? yield* hooks.value.before(args) : args, result = yield* loop.run(prepared);
-        if (Option.isSome(hooks))
-          yield* hooks.value.after(prepared);
-        return result;
-      }).pipe(Effect.interruptible, Effect.raceFirst(writer.closed.pipe(Effect.flatMap((ended) => Effect.fail(failure("turn.closed", `The turn was ${ended.reason}`))))));
-      yield* Ref.set(busy, !0);
-      yield* Effect.addFinalizer(() => Ref.set(busy, !1));
-      const fiber = yield* Effect.forkIn(task, parent);
-      yield* Ref.set(running, Option.some(fiber));
-      const exit = yield* Fiber.await(fiber);
-      yield* Ref.set(running, Option.none());
-      const elsewhere = yield* endedElsewhere(writer), completed = Exit.isSuccess(exit) && Option.isNone(elsewhere), cancelled = Option.isSome(elsewhere) || Exit.isFailure(exit) && Cause.hasInterruptsOnly(exit.cause), message = Option.match(elsewhere, {
-        onNone: () => Exit.isFailure(exit) ? Cause.hasInterruptsOnly(exit.cause) ? "Cancelled; unfinished tool effects are not replayed" : Cause.pretty(exit.cause) : "",
-        onSome: (reason) => `The turn was ${reason} elsewhere; unfinished tool effects are not replayed`
-      });
-      if (!Option.contains(elsewhere, "removed"))
-        yield* publishing.withPermits(1)(publishUnlocked(completed && Exit.isSuccess(exit) ? { name: "run.completed", runId, data: { ...exit.value } } : { name: cancelled ? "run.cancelled" : "run.failed", runId, data: { message } }, !0));
-      yield* writer.end({
-        reason: completed && Exit.isSuccess(exit) ? exit.value.outcome : cancelled ? "cancelled" : "failed",
-        failure: completed ? Option.none() : Option.some({ code: "run.failed", message })
-      }).pipe(Effect.catchTag("HarnessError", (error) => isClosed(error) ? Effect.void : Effect.fail(error)));
-      if (Option.isSome(elsewhere) && elsewhere.value !== "cancelled")
-        return yield* Effect.fail(failure("turn.closed", `The turn was ${elsewhere.value} elsewhere`));
-      if (Exit.isFailure(exit) && !cancelled)
-        return yield* Effect.fail(failure("run.failed", Cause.pretty(exit.cause)));
-      return completed;
-    })).pipe(Effect.uninterruptible), runPending = () => Effect.gen(function* () {
-      if (yield* Ref.get(closed))
-        return;
-      yield* refreshPending;
-      const next = (yield* Ref.get(pending)).queue[0];
-      if (next !== void 0 && (yield* run(next)))
-        yield* runPending();
-    }), drain = gate.withPermits(1)(assertOpen.pipe(Effect.andThen(runPending()))), enqueue = (text, kind) => Effect.gen(function* () {
-      yield* assertOpen;
-      if (text.trim().length === 0)
-        return yield* Effect.fail(failure("input.empty", "Enter a message"));
-      const input = { id: crypto.randomUUID(), text, kind };
-      yield* publishing.withPermits(1)(publishUnlocked({ name: "input.queued", data: input }, !0));
-      yield* refreshPending;
-    }), interrupt = Ref.get(running).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (fiber) => Fiber.interrupt(fiber).pipe(Effect.asVoid) }))), close = Ref.getAndSet(closed, !0).pipe(Effect.flatMap((already) => already ? Effect.void : Effect.gen(function* () {
-      yield* interrupt;
-      yield* gate.withPermits(1)(Ref.get(mounted).pipe(Effect.flatMap((current) => Scope.close(current.scope, Exit.void))));
-      yield* PubSub.shutdown(notifications);
-      yield* PubSub.shutdown(transientHub);
-      yield* Ref.update(handles, (all) => new Map([...all].filter(([id]) => id !== record.id)));
-    }))), handle = {
-      record,
-      use: (tag, run) => gate.withPermits(1)(assertOpen.pipe(Effect.andThen(Ref.get(mounted)), Effect.flatMap((current) => service(current.context, tag)), Effect.flatMap(run))),
-      send: (text) => enqueue(text, "turn").pipe(Effect.andThen(drain)),
-      steer: (text) => enqueue(text, "steer"),
-      continue: drain,
-      interrupt,
-      close,
-      busy: Ref.get(busy),
-      pending: Ref.get(pending).pipe(Effect.map((state) => state.queue)),
-      refresh: gate.withPermits(1)(refresh),
-      history: store.read(record.id, -1),
-      transient: Stream.fromPubSub(transientHub),
-      events: (after = -1) => Stream.unwrap(Effect.gen(function* () {
-        const subscription = yield* PubSub.subscribe(notifications), cursor = yield* Ref.make(after);
-        return Stream.concat(Stream.make(void 0), Stream.fromSubscription(subscription)).pipe(Stream.mapEffect(() => Ref.get(cursor).pipe(Effect.flatMap((position) => store.read(record.id, position)), Effect.tap((events) => events.length === 0 ? Effect.void : Ref.set(cursor, events[events.length - 1].seq)))), Stream.flatMap(Stream.fromIterable));
-      }))
-    };
-    yield* Scope.addFinalizer(parent, close);
-    yield* Ref.update(handles, (all) => new Map([...all, [record.id, handle]]));
-    return handle;
-  }), opening = yield* Semaphore.make(1), ownRecord = (id) => store.get(id).pipe(Effect.flatMap((record) => record.workspace !== options.workspace ? Effect.fail(failure("session.workspace", "This session belongs to a different workspace")) : Effect.succeed(record)));
-  return {
-    create: () => Ref.get(graphRef).pipe(Effect.flatMap((graph) => store.create(options.workspace, graph.config.profile ?? "smith")), Effect.flatMap((record) => opening.withPermits(1)(open(record)))),
-    resume: (id) => ownRecord(id).pipe(Effect.flatMap((record) => opening.withPermits(1)(open(record)))),
-    fork: (id, through) => ownRecord(id).pipe(Effect.andThen(store.fork(id, through)), Effect.flatMap((record) => opening.withPermits(1)(open(record)))),
-    list: store.list(options.workspace),
-    graph: Ref.get(graphRef),
-    reconfigure: (config, plugins) => Effect.gen(function* () {
-      const registry = plugins ?? (yield* Ref.get(registryRef)), next = yield* resolveGraph(config, registry, [SessionEnvironment.key]);
-      if (graphFingerprint(next, "runtime") !== graphFingerprint(initial, "runtime"))
-        return "restart-required";
-      yield* Effect.forEach([...(yield* Ref.get(handles)).values()], (handle) => Effect.scoped(Effect.gen(function* () {
-        const scope = yield* Effect.scope, seed = Context.add(runtime, SessionEnvironment, { workspace: options.workspace, session: handle.record }), context = yield* activateGraph(next, "session", Context.makeUnsafe(seed.mapUnsafe), scope);
-        yield* service(context, AgentLoop);
-      })));
-      yield* Ref.set(registryRef, registry);
-      yield* Ref.set(graphRef, next);
-      yield* Effect.forEach([...(yield* Ref.get(handles)).values()], (handle) => handle.busy.pipe(Effect.flatMap((active) => active ? Effect.void : handle.refresh)));
-      return "applied";
-    })
-  };
-}), Harness = { make: makeHarness };