@xandreed/sdk 0.13.0 → 0.14.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.14.0. Node 24 or Bun.
 
 Documentation: https://github.com/xandreeddev/efferent

package/dist/activity.test.d.ts

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

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/agent.trace.test.d.ts

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

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,3 +1,3 @@
 export * from "@xandreed/core";
-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,2 +1,2 @@
 export * from "@xandreed/core";
-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,6 @@
 {
   "name": "@xandreed/sdk",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "engines": {
     "node": ">=24",
     "bun": ">=1.3.0"
@@ -14,9 +14,9 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.13.0",
+    "@xandreed/core": "0.14.0",
     "effect": "4.0.7",
-    "@xandreed/runtime": "0.13.0"
+    "@xandreed/runtime": "0.14.0"
   },
   "private": false,
   "types": "./dist/index.d.ts",