@xandreed/sdk 0.13.0 → 0.15.0

package/README.md

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

package/dist/agent.adapter.d.ts

@@ -1,15 +1,23 @@
 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";
-/** One plugin instance of an agent: the definition, its options and (optionally) an instance id. */
+import type { Capability, LoopLimits, Plugin, ProcessActivity, SessionLogError, ShutdownOptions, ShutdownReport, Turn, TurnBeginError, TurnError, TurnInput, TurnOutcome, TurnResult, TurnServices } from "@xandreed/core";
+/**
+ * One plugin instance of an agent: the definition, its options and (optionally) an instance id.
+ *
+ * @public
+ */
 export interface AgentPluginEntry {
     readonly plugin: Plugin;
     /** Defaults to the plugin id. */
     readonly id?: string;
     readonly options?: Readonly<Record<string, unknown>>;
 }
-/** Everything an agent is made of. Swapping a strategy is swapping one entry. */
+/**
+ * Everything an agent is made of. Swapping a strategy is swapping one entry.
+ *
+ * @public
+ */
 export interface AgentConfig {
     /** Memory log and strategy, tool registry, step loop, and any capability plugins. */
     readonly plugins: ReadonlyArray<Plugin | AgentPluginEntry>;
@@ -17,7 +25,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<{
@@ -28,30 +40,118 @@ export interface AgentConfig {
     /** The prompt-cache key is `<prefix>:<conversation>`; none is sent without a prefix. */
     readonly cacheKeyPrefix?: string;
     readonly workspace?: string;
-    /** Defaults for every run; a turn's policy overrides them. */
+    /**
+     * Defaults for every run; a turn's policy overrides them. Its loop
+     * protection (`degenerate`, `malformedLimit`) is decoded here
+     * (`config.limits`), and a run's merged limits again (`turn.limits`).
+     */
     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 after the
+     * turn's sealed reply (and, as a safety net, at a run's start) when
+     * messages pass its `triggerRatio`; the digester ignores it. A model whose `ModelCatalog` window (less its output cap) is
+     * smaller lowers a step's ceiling to 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 graceful shutdown when the scope `Agent.define` ran in closes: before
+     * the agent's plugins close (its sessions plugin and its log with them),
+     * `Agent.shutdown` runs with these options and waits for it. Without it,
+     * closing that scope stops no turn first.
+     */
+    readonly shutdown?: ShutdownOptions;
 }
 /** 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), owner-observed `WaitingInput`, and active `DrainActivity`:
+     * an inbox drainer (`InboxDrainLive`) runs the agent, so it is built beside
+     * it and never in its runtime, and the `DrainActivity` provided where this
+     * is read counts instead (so does `shutdown`'s).
+     * Queue storage failures remain SessionLogError. A missing probe 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, SessionLogError>;
+    /**
+     * Stop this agent's turns within a deadline, while its services are open
+     * (`shutdownGracefully` over the same runtime services `activity` reads):
+     * refuse every new begin (`TurnRefused`, reason `shutdown`), wait for the
+     * turns and tasks running, then close the turns still running at the
+     * deadline less its reserve as interrupted with `turn.shutdown`
+     * (resumable) and wait out the reserve. `options` default to
+     * `AgentConfig.shutdown`, else a deadline of `DEFAULT_SHUTDOWN_DEADLINE`.
+     * Begins stay refused afterwards: call it when the process is about to
+     * stop (a SIGTERM), then stop the host's request fibers and close the
+     * agent's scope.
+     */
+    readonly shutdown: (options?: ShutdownOptions) => Effect.Effect<ShutdownReport>;
     /**
      * 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
-     * services. The turn is scoped: its subscriptions and tasks end with it.
+     * services. A turn to begin here that cannot begin fails with the refusal
+     * itself (`TurnBeginError`: `SessionBusy`, `TurnDuplicate`,
+     * `NotResumable`…; match it with `Effect.catchTag`, `harnessCodeOf` gives
+     * its code), before anything is opened, run or counted.
+     * The turn is scoped: its subscriptions and tasks end with it.
      * 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
-     * elsewhere (cancelled, reaped) fails with `turn.closed`. `use` runs in
+     * 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, and on failure one is logged.
+     * A turn closed
+     * elsewhere (cancelled, reaped, its session removed) fails with that
+     * `TurnClosed` (stored as `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) and, for a turn
+     * begun here, `pending`: the inbox items its end left waiting (results
+     * delivered while it ran), which the caller drains (`Sessions.drain`).
+     * From the moment
+     * the turn is admitted it runs under its `agent.turn` span (`traceTurn`),
+     * its logs annotated with the turn's ids (`turnAttributes`), and is
+     * counted in the `efferent.turns` and `efferent.turn.duration` metrics by
+     * its `efferent.outcome`. A turn begun here begins under its own
+     * `agent.turn.begin` span beside it (`traceTurnBegin`), which ends with
+     * the refusal's code when the turn cannot begin.
      */
-    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, TurnError, R>) => Effect.Effect<TurnResult, TurnBeginError | TurnError | E, Exclude<R, A | TurnServices | Scope.Scope>>;
 }
 export declare const Agent: {
     define: (config: AgentConfig) => Effect.Effect<Agent, HarnessError, Scope.Scope>;

package/dist/agent.adapter.js

@@ -1,44 +1,66 @@
-import { Context, Effect, Option, Schema } from "effect";
+import { Cause, Clock, Context, Duration, Effect, Exit, Metric, Option, Schema } from "effect";
 import {
-  cacheKeyOf,
+  CurrentTraceContent,
+  DrainActivity,
+  WaitingInput,
   CapabilitiesLive,
+  DEFAULT_SHUTDOWN_DEADLINE,
   Capabilities,
   ConversationMemory,
   definePlugin,
-  guardTurn,
   harnessDefectsAsFailures,
   HarnessError,
-  openTurnTools,
+  LoopProtection,
+  isBudgetTokens,
+  normalizeUserMessage,
+  PluginInstanceId,
+  processActivity,
+  reasonOf,
+  replayableContext,
   SessionEnvironment,
   Sessions,
+  shutdownGracefully,
   StepLoop,
+  TaskActivity,
   ToolRegistry,
   RunContext,
-  settleTurn,
+  TurnActivity,
   TurnEvents,
+  TurnShutdown,
   TurnTasks,
-  TurnLive,
   TurnMemory,
   TurnPrompt,
   TurnToolbox,
-  turnOf
+  turnAttributes,
+  turnEndingOf
 } 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 = {
-  SessionBusy: "session.busy",
-  TurnDuplicate: "turn.duplicate",
-  KeyConflict: "turn.key-conflict",
-  NothingPending: "session.nothing-pending",
-  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({
+import { guardTurn, openTurnTools, settleTurn, traceTurn, traceTurnBegin, turnOf } from "./turn/turn-lifecycle.usecase.functions.js";
+import { cacheKeyOf } from "./turn/turn-run.usecase.functions.js";
+import { TurnLive } from "./turn/turn.adapter.js";
+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), 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 },
+    ...turn.takeOver === !0 ? { takeOver: !0 } : {},
+    ...turn.timeLimitMs === void 0 ? {} : { timeLimitMs: turn.timeLimitMs }
+  });
+}), untilClosed = (writer) => (body) => Effect.raceFirst(body, writer.closed.pipe(Effect.flatMap((closed) => Effect.fail(closed)))), 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",
@@ -47,25 +69,34 @@ const failure = (code, message) => new HarnessError({ code, message }), missing
   provides: [],
   contributes: [Capabilities],
   layer: () => CapabilitiesLive(...capabilities)
-}), builtInTurnKeys = [RunContext, TurnEvents, TurnTasks, TurnMemory, TurnPrompt, TurnToolbox].map((tag) => tag.key), turnDependentNodes = (graph) => graph.nodes.reduce((late, node) => {
+}), builtInTurnKeys = [RunContext, TurnEvents, TurnTasks, TurnMemory, TurnPrompt, TurnToolbox].map((tag) => tag.key), turnPorts = [ConversationMemory, ToolRegistry, StepLoop].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}`));
+  yield* Schema.decodeUnknownEffect(LoopProtection)(config.limits ?? {}).pipe(Effect.mapError((cause) => new HarnessError({ code: "config.limits", message: "the agent's limits carry a degenerate policy or malformedLimit that does not decode", cause })));
   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: [
-      ...withHost ? [{ id: host.id, use: host.id }] : [],
-      ...entries.map((entry) => ({ id: entry.id ?? entry.plugin.id, use: entry.plugin.id, options: { ...entry.options } }))
+      ...withHost ? [{ id: PluginInstanceId.make(host.id), use: host.id }] : [],
+      ...entries.map((entry) => ({ id: PluginInstanceId.make(entry.id ?? entry.plugin.id), use: entry.plugin.id, options: { ...entry.options } }))
     ],
     ...config.bindings === void 0 ? {} : { bindings: { ...config.bindings } },
     system: config.system ?? ""
-  }, services = config.services ?? Context.empty(), turnKeys = (config.turnServices ?? []).map((tag) => tag.key), external = [SessionEnvironment.key, ...services.mapUnsafe.keys(), ...turnKeys, ...builtInTurnKeys], graph = yield* resolveGraph(harness, plugins, external), late = turnDependentNodes(graph), invalidLate = late.find((node) => node.plugin.scope === "runtime" || node.plugin.provides.some((key) => [ConversationMemory.key, ToolRegistry.key, StepLoop.key].includes(key)));
+  }, services = config.services ?? Context.empty(), turnKeys = (config.turnServices ?? []).map((tag) => tag.key), external = [SessionEnvironment.key, ...services.mapUnsafe.keys(), ...turnKeys, ...builtInTurnKeys], graph = yield* resolveGraph(harness, plugins, external), late = turnDependentNodes(graph), invalidLate = late.find((node) => node.plugin.scope === "runtime" || node.plugin.provides.some((key) => turnPorts.includes(key)));
   if (invalidLate !== void 0)
     return yield* Effect.fail(failure("config.graph", `${invalidLate.entry.id}: a plugin requiring turn services must be session-scoped and cannot supply the turn's memory, registry or loop`));
+  const unprovided = turnPorts.filter((key) => graph.providers[key] === void 0 && !services.mapUnsafe.has(key) && !turnKeys.includes(key));
+  if (unprovided.length > 0)
+    return yield* Effect.fail(failure("config.graph", `the agent has no ${unprovided.join(", ")}: no plugin provides it, and neither services nor turnServices carry it`));
   const beforeTurn = { ...graph, nodes: graph.nodes.filter((node) => !late.includes(node)) }, afterTurn = { ...graph, nodes: late }, workspace = config.workspace ?? ".", seed = Context.add(services, SessionEnvironment, { workspace }), runtime = yield* activateGraph(beforeTurn, "runtime", Context.makeUnsafe(seed.mapUnsafe), parent), perTurn = beforeTurn.nodes.some((node) => node.plugin.scope === "session"), turn = (input, use) => harnessDefectsAsFailures(Effect.scoped(Effect.gen(function* () {
     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)), open = (begin) => Effect.gen(function* () {
+      const context = perTurn ? yield* activateGraph(beforeTurn, "session", merged, scope) : merged, memory = yield* required(context, ConversationMemory), registry = yield* required(context, ToolRegistry), loop = yield* required(context, StepLoop), writer = yield* begin(context);
+      return { admitted: writer.admitted, writer, context, memory, registry, loop };
+    }), requested = input.turn, own = !isWriter(requested), { writer, context, memory, registry, loop } = yield* isWriter(requested) ? open(() => Effect.succeed(requested)) : open((context) => beginTurn(context, requested)).pipe(traceTurnBegin({ session: requested.session.id, runId: requested.runId, origin: "user" })), system = input.system ?? config.system, live = {
       turn: writer,
       ...system === void 0 ? {} : { system },
       ...config.maxEventDepth === void 0 ? {} : { maxEventDepth: config.maxEventDepth }
@@ -73,7 +104,9 @@ 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 },
+      ...input.waiting === void 0 ? {} : { waiting: input.waiting },
+      ...config.captureTraceContent === void 0 ? {} : { captureTraceContent: config.captureTraceContent }
     }, body = Effect.gen(function* () {
       yield* (yield* TurnMemory).persistMessage;
       yield* openTurnTools;
@@ -84,11 +117,24 @@ 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)
+        return yield* exit;
+      if (Exit.isFailure(exit)) {
+        yield* writer.end(turnEndingOf(exit)).pipe(Effect.catchTag("TurnClosed", (closed) => Effect.logDebug(`the failed turn's end was not stored: the turn was ${closed.reason}`)), Effect.catch((error) => Effect.logWarning(`the failed turn's end was not stored: ${reasonOf(Cause.fail(error))}`)));
+        return yield* Effect.failCause(exit.cause);
+      }
+      const { pending } = yield* writer.end(turnEndingOf(exit));
+      return { ...exit.value, pending };
+    }).pipe(Effect.annotateLogs(turnAttributes(writer.admitted)), measureTurn, traceTurn(writer, { spanMeta: config.spanMeta ?? [] }));
+  }))), runtimeProbes = (effect) => effect.pipe(Effect.updateContext((current) => {
+    const probes = Context.merge(Context.omit(TurnActivity, TaskActivity, TurnShutdown, WaitingInput, DrainActivity)(current), Context.pick(TurnActivity, TaskActivity, TurnShutdown, WaitingInput, DrainActivity)(runtime)), drains = Option.orElse(Context.getOption(runtime, DrainActivity), () => Context.getOption(current, DrainActivity));
+    return Option.match(drains, { onNone: () => probes, onSome: (probe) => Context.add(probes, DrainActivity, probe) });
+  })), activity = runtimeProbes(processActivity), shutdown = (options) => runtimeProbes(shutdownGracefully(options ?? config.shutdown ?? { deadline: DEFAULT_SHUTDOWN_DEADLINE })).pipe(Effect.tap((report) => report.left.inFlight ? Effect.logWarning(`the agent stopped with ${report.left.openTurns.length + report.left.beginningTurns} turns and ${report.left.runningTasks} tasks still in flight`) : Effect.void)), configured = config.shutdown;
+  if (configured !== void 0)
+    yield* Effect.addFinalizer(() => shutdown(configured).pipe(Effect.asVoid));
+  return { fingerprint: graphFingerprint(graph), activity, shutdown, turn };
 });
 export const Agent = { define: makeAgent };

package/dist/conformance/index.d.ts

@@ -0,0 +1,2 @@
+export { toolRegistryConformance } from "../turn/tool-registry.conformance.js";
+export type { ToolRegistryLimits } from "../turn/tool-registry.conformance.js";

package/dist/conformance/index.js

@@ -0,0 +1 @@
+export { toolRegistryConformance } from "../turn/tool-registry.conformance.js";

package/dist/inbox-runner.adapter.d.ts

@@ -0,0 +1,18 @@
+import { Context, Effect, Layer } from "effect";
+import type { Scope } from "effect";
+import { InboxRunner, Sessions } from "@xandreed/core";
+import type { Turn, TurnError, TurnOutcome, TurnRunner, TurnServices } from "@xandreed/core";
+/**
+ * Execute a prebegun inbox or resumed turn through the agent. Build beside
+ * the agent and provide the same Sessions that the drainer uses. Its captured
+ * Sessions takes precedence over per-turn services. The caller owns the
+ * writer's scope and end; this bridge only executes it.
+ *
+ * By default select skills for the admitted message, run the loop once, and
+ * return its outcome and text. A custom use has Agent.turn's turn services.
+ * @public
+ */
+export declare const agentInboxRunner: (agent: TurnRunner, options: {
+    readonly services: Context.Context<never>;
+    readonly use?: (turn: Turn) => Effect.Effect<TurnOutcome, TurnError, TurnServices | Scope.Scope>;
+}) => Layer.Layer<InboxRunner, never, Sessions>;

package/dist/inbox-runner.adapter.js

@@ -0,0 +1,8 @@
+import { Context, Effect, Layer, Option } from "effect";
+import { InboxRunner, isTurnError, Sessions } from "@xandreed/core";
+export const agentInboxRunner = (agent, options) => Layer.effect(InboxRunner, Effect.gen(function* () {
+  const sessions = yield* Sessions, services = Context.add(options.services, Sessions, sessions), use = options.use ?? ((turn) => turn.tools.select(turn.userMessage).pipe(Effect.andThen(turn.run({})), Effect.map((result) => ({ outcome: result.outcome, reply: result.outcome === "waiting" ? Option.none() : Option.some(result.text) }))));
+  return InboxRunner.of({
+    run: Effect.fn("inbox_runner.run")((writer) => agent.turn({ turn: writer, services }, use).pipe(Effect.catch((error) => isTurnError(error) ? Effect.fail(error) : Effect.die(error)), Effect.map((result) => ({ outcome: result.outcome, reply: result.reply }))))
+  });
+}));

package/dist/index.d.ts

@@ -1,3 +1,36 @@
-export * from "@xandreed/core";
 export { Agent } from "./agent.adapter.js";
 export type { AgentConfig, AgentPluginEntry } from "./agent.adapter.js";
+export { agentInboxRunner } from "./inbox-runner.adapter.js";
+export { taskInboxRunner } from "./task-inbox-runner.adapter.js";
+export { agentTaskExecutor } from "./task-executor.adapter.js";
+export { TurnLive } from "./turn/turn.adapter.js";
+export { cacheKeyOf, runTurnLoop, stepRequestOf } from "./turn/turn-run.usecase.functions.js";
+export type { TurnRunServices } from "./turn/turn-run.usecase.functions.js";
+export { finishTurn, guardTurn, openTurnTools, settleTurn, traceTurn, traceTurnBegin, turnOf, turnTools, } from "./turn/turn-lifecycle.usecase.functions.js";
+export type { TurnBeginTrace, TurnTraceOptions } from "./turn/turn-lifecycle.usecase.functions.js";
+export { ConversationId, mediaFromBase64, mediaFromBytes, RunId, SessionAddress, UserMessage } from "@xandreed/core";
+export type { /** @public */ NewTurn, /** @public */ TurnInput } from "@xandreed/core";
+export type { Turn, TurnOutcome, /** @public */ TurnPolicy, /** @public */ TurnResult } from "@xandreed/core";
+export { SessionLog, SessionLogMemoryLive, Sessions, /** @public */ TurnAdmission, TurnAdmissionOpen, /** @public */ TurnRefused } from "@xandreed/core";
+export { 
+/** @public */ defineCapability, definePlugin, definePromptSection, 
+/** @public */ defineSkill, defineTool, Failure, Media, 
+/** @public */ publishToolProgress, SessionEnvironment, 
+/** @public */ ActionPolicy, 
+/** @public */ PermissionGrants, } from "@xandreed/core";
+export type { Capability } from "@xandreed/core";
+export { AssistantMessage, defineHostEvent, onEvent, onTool, subscribeAll, TurnEndedData, turnEndedOf, TurnEvent, TurnEvents, } from "@xandreed/core";
+export type { TurnEventOf, TurnEventsService } from "@xandreed/core";
+export { harnessCodeOf, 
+/** @public */ HarnessError, 
+/** @public */ isHarnessError, 
+/** @public */ isTurnError, TurnBeginError, turnBeginCodes, turnEndingOf, } from "@xandreed/core";
+export type { TurnError } from "@xandreed/core";
+export { 
+/** @public */ awaitIdle, 
+/** @public */ DEFAULT_SHUTDOWN_DEADLINE, 
+/** @public */ isShutdownRefusal, 
+/** @public */ processActivity, 
+/** @public */ shutdownGracefully, 
+/** @public */ TurnShutdown, } from "@xandreed/core";
+export type { ShutdownOptions, /** @public */ ShutdownReport } from "@xandreed/core";

package/dist/index.js

@@ -1,2 +1,59 @@
-export * from "@xandreed/core";
 export { Agent } from "./agent.adapter.js";
+export { agentInboxRunner } from "./inbox-runner.adapter.js";
+export { taskInboxRunner } from "./task-inbox-runner.adapter.js";
+export { agentTaskExecutor } from "./task-executor.adapter.js";
+export { TurnLive } from "./turn/turn.adapter.js";
+export { cacheKeyOf, runTurnLoop, stepRequestOf } from "./turn/turn-run.usecase.functions.js";
+export {
+  finishTurn,
+  guardTurn,
+  openTurnTools,
+  settleTurn,
+  traceTurn,
+  traceTurnBegin,
+  turnOf,
+  turnTools
+} from "./turn/turn-lifecycle.usecase.functions.js";
+export { ConversationId, mediaFromBase64, mediaFromBytes, RunId, SessionAddress, UserMessage } from "@xandreed/core";
+export { SessionLog, SessionLogMemoryLive, Sessions, TurnAdmission, TurnAdmissionOpen, TurnRefused } from "@xandreed/core";
+export {
+  defineCapability,
+  definePlugin,
+  definePromptSection,
+  defineSkill,
+  defineTool,
+  Failure,
+  Media,
+  publishToolProgress,
+  SessionEnvironment,
+  ActionPolicy,
+  PermissionGrants
+} from "@xandreed/core";
+export {
+  AssistantMessage,
+  defineHostEvent,
+  onEvent,
+  onTool,
+  subscribeAll,
+  TurnEndedData,
+  turnEndedOf,
+  TurnEvent,
+  TurnEvents
+} from "@xandreed/core";
+export {
+  harnessCodeOf,
+  HarnessError,
+  isHarnessError,
+  isTurnError,
+  TurnBeginError,
+  turnBeginCodes,
+  turnEndingOf
+} from "@xandreed/core";
+export {
+  awaitIdle,
+  DEFAULT_SHUTDOWN_DEADLINE,
+  isShutdownRefusal,
+  processActivity,
+  shutdownGracefully,
+  TurnShutdown
+} from "@xandreed/core";

package/dist/task-executor.adapter.d.ts

@@ -0,0 +1,32 @@
+import { Context, Effect, Layer } from "effect";
+import type { Scope } from "effect";
+import { TaskExecutor } from "@xandreed/core";
+import type { TaskView, Turn, TurnError, TurnInput, TurnOutcome, TurnRunner, TurnServices } from "@xandreed/core";
+/** What a task's turn runs once it is composed: a `use` of `Agent.turn`, with the turn's services. */
+type TurnUse = (turn: Turn) => Effect.Effect<TurnOutcome, TurnError, TurnServices | Scope.Scope>;
+/**
+ * The `TaskExecutor` that runs a task's turns through an agent (`Agent.turn`,
+ * or any `TurnRunner`) with the turn's `services` (its model, the host's
+ * per-turn ports) and the `Tasks` it is called with (the tasks plugin's
+ * own), so a turn's `start_task` and `task_status` work: the child's one
+ * turn with `child` and the parent's
+ * reaction to a result with `react`, each by default the turn's skills
+ * selected for its message, then one run of the step loop, whose text is the
+ * reply. The tasks plugin begins and ends those turns; this only runs them.
+ * Build `Tasks` beside the agent, not inside it:
+ * `TasksLive(config).pipe(Layer.provide(agentTaskExecutor(agent, { services })))`
+ * (a `tasksPlugin` among the agent's own plugins would need the executor
+ * before the agent exists).
+ *
+ * @public
+ */
+export declare const agentTaskExecutor: (agent: TurnRunner, options: {
+    readonly services: Context.Context<never>;
+    /** Optional in-memory steering for both turns; durable input uses their writers' queued steers. */
+    readonly steering?: TurnInput["steering"];
+    /** The child's turn, given the task it runs. */
+    readonly child?: (turn: Turn, task: TaskView) => Effect.Effect<TurnOutcome, TurnError, TurnServices | Scope.Scope>;
+    /** The parent's turn that answers the results waiting in its inbox. */
+    readonly react?: TurnUse;
+}) => Layer.Layer<TaskExecutor>;
+export {};

package/dist/task-executor.adapter.js

@@ -0,0 +1,10 @@
+import { Context, Effect, Layer, Option } from "effect";
+import { isTurnError, TaskExecutor, Tasks } from "@xandreed/core";
+const oneRun = (turn) => turn.tools.select(turn.userMessage).pipe(Effect.andThen(turn.run({})), Effect.map((result) => ({ outcome: result.outcome, reply: result.outcome === "waiting" ? Option.none() : Option.some(result.text) }))), runOn = (agent, services, writer, use, steering, waiting) => Tasks.pipe(Effect.flatMap((tasks) => agent.turn({ turn: writer, services: Context.add(services, Tasks, tasks), ...steering === void 0 ? {} : { steering }, ...waiting === void 0 ? {} : { waiting } }, use)), Effect.catch((error) => isTurnError(error) ? Effect.fail(error) : Effect.die(error)), Effect.map((result) => ({ outcome: result.outcome, reply: result.reply })));
+export const agentTaskExecutor = (agent, options) => {
+  const child = options.child ?? oneRun, react = options.react ?? oneRun;
+  return Layer.succeed(TaskExecutor, TaskExecutor.of({
+    turn: (writer, task, controls) => runOn(agent, options.services, writer, (turn) => child(turn, task), options.steering, controls?.waiting),
+    react: (writer) => runOn(agent, options.services, writer, react, options.steering).pipe(Effect.asVoid)
+  }));
+};

package/dist/task-inbox-runner.adapter.d.ts

@@ -0,0 +1,11 @@
+import { Context, Layer } from "effect";
+import { InboxRunner, Sessions, Tasks } from "@xandreed/core";
+/**
+ * Route a task child's queued follow-ups through Tasks.execute on the supplied
+ * borrowed writer. Other sessions use base. After an acknowledged end, repair
+ * task delivery and hand parent notices to the existing task runner. The hook
+ * can be skipped on process death; startup Tasks.reconcile repairs the outbox.
+ * Build beside the agent with the drainer's own Sessions and Tasks.
+ * @public
+ */
+export declare const taskInboxRunner: (base: Context.Service.Shape<typeof InboxRunner>) => Layer.Layer<InboxRunner, never, Sessions | Tasks>;

package/dist/task-inbox-runner.adapter.js

@@ -0,0 +1,22 @@
+import { Context, Effect, Layer, Option } from "effect";
+import { harnessError, InboxRunner, Sessions, Tasks } from "@xandreed/core";
+export const taskInboxRunner = (base) => Layer.effect(InboxRunner, Effect.gen(function* () {
+  const sessions = yield* Sessions, tasks = yield* Tasks, sessionOf = (writer) => sessions.get(writer.admitted.session).pipe(Effect.catchTag("SessionMissing", (cause) => Effect.fail(harnessError("task.turn", "The inbox session is unavailable.", cause))));
+  return InboxRunner.of({
+    run: Effect.fn("task_inbox_runner.run")(function* (writer) {
+      return yield* (yield* sessionOf(writer)).header.origin === "task" ? tasks.execute(writer) : base.run(writer);
+    }),
+    afterEnd: Effect.fn("task_inbox_runner.after_end")(function* (writer, ending) {
+      const view = yield* sessionOf(writer);
+      if (view.header.origin === "task") {
+        const parent = yield* Option.match(view.header.parent, {
+          onNone: () => Effect.fail(harnessError("task.turn", "The task session has no parent.")),
+          onSome: (lineage) => Effect.succeed({ id: lineage.id, owner: writer.admitted.session.owner })
+        });
+        yield* tasks.reconcile(parent, { react: !0 }).pipe(Effect.catchTag("SessionMissing", (cause) => Effect.fail(harnessError("task.turn", "The inbox session is unavailable.", cause))));
+      }
+      if (base.afterEnd !== void 0)
+        yield* base.afterEnd(writer, ending);
+    })
+  });
+}));

package/dist/turn/memory-checkpoint.adapter.d.ts

@@ -0,0 +1,17 @@
+import { Effect, Option, Schema } from "effect";
+import { MemorySnapshotCandidate } from "@xandreed/core";
+import type { TurnError, TurnWriter } from "@xandreed/core";
+/** The journal-aware bridge is initialized before a custom memory opener can call it. */
+export declare const makeMemoryCheckpoint: (writer: TurnWriter, history: Effect.Effect<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]: Schema.Json;
+    };
+}[], TurnError, never>) => Effect.Effect<{
+    readonly load: Effect.Effect<Option.Option<MemorySnapshotCandidate>, TurnError>;
+    readonly save: (candidate: MemorySnapshotCandidate) => Effect.Effect<void, TurnError>;
+}, never, never>;