@xandreed/sdk 0.13.0 → 0.15.0

package/dist/turn/turn-run.usecase.functions.js

@@ -0,0 +1,329 @@
+import { Context, Deferred, Effect, Exit, Option, Ref, Schema } from "effect";
+import { LanguageModel } from "effect/ai";
+import {
+  AcceptedModelInput as AcceptedInputSchema,
+  assistantUsage,
+  canonicalJson,
+  CurrentAgentRun,
+  CurrentAgentStep,
+  CurrentModelCallPolicy,
+  CurrentPromptCacheKey,
+  CurrentTraceContent,
+  fingerprintOf,
+  formatModelSelection,
+  freezeModelRequest,
+  HarnessError,
+  LoopProtection,
+  harnessDefectsAsFailures,
+  isBudgetTokens,
+  ModelCatalog,
+  ModelOverflowEvidence,
+  modelRequestDescriptorOf,
+  parseModelSelection,
+  replayableContext,
+  resolveModelRequest,
+  scaledTokens,
+  StepLoop,
+  TurnEvents,
+  TurnMemory,
+  TurnPrompt,
+  TurnTasks,
+  TurnToolbox,
+  zeroUsage
+} from "@xandreed/core";
+import {
+  applyModelRequestHook,
+  checkModelRequest,
+  CurrentToolResultReceipt,
+  entriesSendingMedia,
+  estimateTokens,
+  markVolatileContext,
+  modelRequestHeaderOf,
+  modelRequestTools,
+  reconstructModelRequest,
+  toolParametersSchema
+} from "@xandreed/core/internal";
+import { TurnObservation } from "./turn-observation.entity.js";
+import { matchingObservation, observeAcceptedInput } from "./turn-observation.entity.functions.js";
+import { tighterOverflowBudget, windowBound } from "./turn-overflow.entity.functions.js";
+const MEDIA_REJECTION_CHARS = 500, defaultLimits = { maxSteps: 50, toolConcurrency: 1, streaming: !0, requireCompletion: !1 }, defaultBudgetTokens = 64000, incomplete = { complete: !1, awaiting: [], facts: {} }, noDirective = { context: Option.none(), toolChoice: Option.none() }, normalVerdict = (verdict) => ({
+  ...verdict,
+  awaiting: verdict.awaiting.map((tag) => tag.trim()).filter((tag) => tag.length > 0)
+}), failure = (code, message) => new HarnessError({ code, message });
+export const schemaTokens = (tools, active) => active.reduce((sum, name) => {
+  const tool = tools.toolkit.tools[name];
+  return tool === void 0 ? sum : sum + estimateTokens(`${tool.description ?? ""}${canonicalJson(toolParametersSchema(tool))}`);
+}, 0), cacheKeyOf = (prefix, conversation) => Option.map(Option.filter(Option.some(prefix), (value) => value.length > 0), (value) => `${value}:${conversation}`), stepRequestOf = Effect.fnUntraced(function* (policy, options = {}) {
+  const runServices = Context.omit(CurrentToolResultReceipt)(replayableContext(yield* Effect.context())), memory = yield* TurnMemory, prompt = yield* TurnPrompt, events = yield* TurnEvents, tasks = yield* TurnTasks, tools = yield* (yield* TurnToolbox).tools, session = memory.session, run = yield* memory.startRun, inRun = (effect, step = Option.none()) => effect.pipe(Effect.provideService(CurrentAgentRun, Option.some(run)), Effect.provideService(CurrentAgentStep, step), Effect.provide(runServices)), defaultModel = Context.getOption(runServices, LanguageModel.LanguageModel), limits = { ...defaultLimits, ...options.limits, ...policy.limits };
+  yield* Schema.decodeUnknownEffect(LoopProtection)(limits).pipe(Effect.mapError((cause) => new HarnessError({ code: "turn.limits", message: "the run's limits carry a degenerate policy or malformedLimit that does not decode", cause })));
+  const budget = policy.budgetTokens ?? options.budgetTokens ?? defaultBudgetTokens;
+  if (!isBudgetTokens(budget))
+    return yield* Effect.fail(failure("turn.budget", `budgetTokens must be an integer of at least 1, not ${budget}`));
+  const stepContext = policy.stepContext ?? "tail", cacheKey = options.cacheKey ?? Option.none(), callPolicy = yield* Effect.service(CurrentModelCallPolicy);
+  yield* Option.match(Option.fromNullishOr(policy.initial), {
+    onNone: () => Effect.void,
+    onSome: (batch) => batch.skills.length === 0 ? Effect.void : tools.activate(batch.skills, "host").pipe(Effect.asVoid)
+  });
+  yield* inRun(prompt.turnSections);
+  const renderScope = { run: run.ordinal, stepContext: stepContext === "tail" ? "tail" : "none" }, before = yield* memory.acceptedBefore;
+  yield* inRun(session.maintain({
+    phase: "turn-start",
+    lastUsage: Option.none(),
+    budgetTokens: budget,
+    views: tools.views,
+    render: renderScope,
+    ...Option.match(before, { onNone: () => ({}), onSome: (observed) => ({ observed }) })
+  }));
+  const planned = yield* Ref.make(Option.none()), replanning = yield* Ref.make(Option.none()), privatePlans = yield* Ref.make(new Map), dispatched = yield* Ref.make(new Map), recovery = yield* Ref.make(Option.none()), recoveryClaims = yield* Ref.make(new Map), inputCeiling = yield* Ref.make(budget), observed = yield* Ref.make({ observed: Option.none(), usage: Option.none(), baseReservedTokens: Option.none() }), windows = yield* Ref.make(new Map), windowBoundOf = (identity) => Option.match(identity, {
+    onNone: () => Effect.succeed(Option.none()),
+    onSome: (selection) => Effect.gen(function* () {
+      const key = formatModelSelection(selection), known = (yield* Ref.get(windows)).get(key);
+      if (known !== void 0)
+        return known;
+      const catalog = yield* Option.match(Context.getOption(runServices, ModelCatalog), { onNone: () => Effect.succeed([]), onSome: (service) => service.list }), bound = windowBound(Option.fromNullishOr(catalog.find((entry) => entry.selection === key)?.limits), callPolicy);
+      yield* Ref.update(windows, (all) => new Map([...all, [key, bound]]));
+      return bound;
+    })
+  }), recoveryOutcome = Effect.fnUntraced(function* (done) {
+    if (!(yield* Deferred.isDone(done)))
+      return !1;
+    const terminal = yield* Deferred.await(done).pipe(Effect.interruptible, Effect.exit);
+    return Exit.isFailure(terminal) ? yield* terminal : !1;
+  }), decide = (info) => Effect.gen(function* () {
+    const choice = policy.model === void 0 ? Option.none() : yield* inRun(policy.model(info), Option.some(info.stepIndex)), baseSystem = yield* inRun(prompt.system(Option.flatMap(choice, (value) => value.variant)), Option.some(info.stepIndex)), baseDirective = policy.step === void 0 ? noDirective : yield* inRun(policy.step(info), Option.some(info.stepIndex)), prepared = yield* inRun(applyModelRequestHook({
+      run,
+      step: info.stepIndex,
+      activeTools: info.activeTools,
+      system: baseSystem,
+      context: baseDirective.context,
+      toolChoice: baseDirective.toolChoice
+    }), Option.some(info.stepIndex)), directive = { context: prepared.context, toolChoice: prepared.toolChoice };
+    yield* Option.match(directive.context, {
+      onNone: () => Effect.void,
+      onSome: (text) => session.record([{ _tag: "StepContext", step: info.stepIndex, run: run.ordinal, text }], info.stepIndex).pipe(Effect.asVoid)
+    });
+    return { choice, system: prepared.system, directive, hook: prepared.hook };
+  }).pipe(Effect.provideService(CurrentAgentRun, Option.some(run)), Effect.provideService(CurrentAgentStep, Option.some(info.stepIndex))), plan = (info) => Effect.gen(function* () {
+    const ready = Option.filter(yield* Ref.get(recovery), (candidate) => candidate.step === info.stepIndex);
+    if (Option.isSome(ready)) {
+      yield* Ref.set(recovery, Option.none());
+      yield* Ref.set(planned, ready);
+      return ready.value.outgoing;
+    }
+    const runCeiling = yield* Ref.get(inputCeiling), again = Option.filter(yield* Ref.getAndSet(replanning, Option.none()), (last) => last.step === info.stepIndex), { choice, system, directive, hook } = Option.isSome(again) ? again.value.decision : yield* decide(info), stepText = stepContext === "system" ? Option.getOrElse(directive.context, () => "") : "", finalSystem = [system, stepText].filter((part) => part.length > 0).join(`
+
+`), toolTokens = schemaTokens(tools, info.activeTools), reserved = estimateTokens(finalSystem) + toolTokens, baseReserved = estimateTokens(system) + toolTokens, noRoom = (ceiling) => failure("context.budget", `The system prompt and tool schemas take ${reserved} tokens, all of the ${ceiling}-token context budget: raise budgetTokens or offer fewer tools`);
+    if (runCeiling <= reserved)
+      return yield* Effect.fail(noRoom(runCeiling));
+    const model = Option.isSome(again) ? again.value.model : yield* Option.match(Option.orElse(Option.map(choice, (value) => value.model), () => defaultModel), {
+      onNone: () => Effect.succeed(Option.none()),
+      onSome: (chosen) => resolveModelRequest(chosen).pipe(Effect.map(Option.some))
+    }), descriptor = yield* Option.match(model, { onNone: () => Effect.succeed(Option.none()), onSome: modelRequestDescriptorOf }), identity = Option.flatMap(descriptor, (value) => parseModelSelection(`${value.provider}:${value.model}`)), ceiling = Option.match(yield* windowBoundOf(identity), { onNone: () => runCeiling, onSome: (bound) => Math.min(runCeiling, bound) });
+    if (ceiling <= reserved)
+      return yield* Effect.fail(noRoom(ceiling));
+    const prior = matchingObservation(identity, (yield* Ref.get(observed)).observed);
+    yield* session.maintain({
+      phase: "step",
+      lastUsage: info.lastUsage,
+      budgetTokens: ceiling - reserved,
+      views: tools.views,
+      render: renderScope,
+      ...Option.match(prior, { onNone: () => ({}), onSome: (observed) => ({ observed }) })
+    });
+    const built = yield* session.build({ stepContext: stepContext === "tail" ? "tail" : "none", run: run.ordinal }), render = yield* session.renderRecipe(stepContext === "tail" ? "tail" : "none", run.ordinal), header = {
+      version: 1,
+      runId: run.id,
+      run: run.ordinal,
+      step: info.stepIndex,
+      strategyVersion: session.strategy.version,
+      system: finalSystem,
+      render,
+      through: built.through,
+      contextFingerprint: built.fingerprint,
+      stableMessages: built.stableMessages,
+      tools: modelRequestTools(info.activeTools.flatMap((name) => tools.toolkit.tools[name] === void 0 ? [] : [tools.toolkit.tools[name]])),
+      toolChoice: Option.getOrElse(directive.toolChoice, () => "auto"),
+      model: descriptor,
+      cacheKey,
+      callPolicy,
+      ...Option.match(hook, { onNone: () => ({}), onSome: (hook) => ({ hook }) })
+    }, outgoing = { model, system: finalSystem, messages: markVolatileContext(built.messages, built.stableMessages), toolChoice: directive.toolChoice }, frozen = {
+      run,
+      step: info.stepIndex,
+      decision: { choice, system, directive, hook },
+      model,
+      identity,
+      through: built.through,
+      render,
+      fingerprint: built.fingerprint,
+      estimatedTokens: built.estimatedTokens,
+      reservedTokens: reserved,
+      baseReservedTokens: baseReserved,
+      header,
+      outgoing
+    };
+    yield* events.publish({
+      _tag: "context.built",
+      step: info.stepIndex,
+      turn: run.turn,
+      run: run.ordinal,
+      strategy: session.strategy.id,
+      strategyVersion: session.strategy.version,
+      fingerprint: built.fingerprint,
+      systemFingerprint: fingerprintOf(system),
+      estimatedTokens: built.estimatedTokens,
+      reservedTokens: reserved,
+      budgetTokens: ceiling,
+      compactions: built.compactions.length,
+      activeTools: info.activeTools
+    });
+    yield* memory.prepareRequest(header);
+    yield* Ref.update(privatePlans, (all) => new Map([...all, [canonicalJson(header), frozen]]));
+    yield* Ref.set(planned, Option.some(frozen));
+    return outgoing;
+  }).pipe(Effect.provideService(CurrentAgentRun, Option.some(run)), Effect.provideService(CurrentAgentStep, Option.some(info.stepIndex))), request = {
+    run,
+    tools,
+    handlers: Context.merge(runServices, tools.handlers),
+    limits,
+    initial: Option.fromNullishOr(policy.initial),
+    plan,
+    dispatch: Effect.fnUntraced(function* (step, actual) {
+      const stored = yield* memory.requestSnapshot, header = yield* modelRequestHeaderOf(stored.requestEvents ?? stored.requests, run.id, step, run.ordinal), expected = yield* reconstructModelRequest(header, stored.entries);
+      yield* checkModelRequest(expected, {
+        prompt: actual.prompt,
+        tools: modelRequestTools(actual.tools),
+        toolChoice: actual.toolChoice,
+        model: yield* modelRequestDescriptorOf(actual.model),
+        cacheKey: yield* Effect.service(CurrentPromptCacheKey),
+        callPolicy: yield* Effect.service(CurrentModelCallPolicy)
+      });
+      const frozen = (yield* Ref.get(privatePlans)).get(canonicalJson(header));
+      yield* Ref.update(dispatched, (all) => {
+        const next = new Map(all);
+        if (frozen === void 0)
+          next.delete(step);
+        else
+          next.set(step, { ...frozen, header });
+        return next;
+      });
+    }),
+    record: (step, tail, accepted) => Effect.gen(function* () {
+      const sent = Option.fromNullishOr((yield* Ref.get(dispatched)).get(step)), prepared = Option.fromNullishOr([...(yield* Ref.get(privatePlans)).values()].findLast((plan) => plan.step === step)), frozen = Option.filter(Option.orElse(sent, () => prepared), (plan) => plan.run.id === run.id && plan.run.ordinal === run.ordinal), usage = Option.flatMap(Option.fromNullishOr(tail.find((message) => message.role === "assistant")), assistantUsage), candidate = accepted === void 0 ? Option.none() : yield* Schema.encodeEffect(Schema.fromJsonString(AcceptedInputSchema))(accepted).pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(AcceptedInputSchema))), Effect.map((fact) => ({
+        observed: Option.flatMap(frozen, (plan) => observeAcceptedInput({ estimatedTokens: plan.estimatedTokens, reservedTokens: plan.reservedTokens }, fact)),
+        usage,
+        baseReservedTokens: Option.map(frozen, (plan) => plan.baseReservedTokens)
+      })), Effect.flatMap((state) => Schema.encodeEffect(Schema.fromJsonString(TurnObservation))(state)), Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(TurnObservation))), Effect.map(Option.some), Effect.mapError((cause) => new HarnessError({ code: "request.diverged", message: "accepted model input did not encode", cause }))), recorded = yield* session.recordTail(tail, tools.views, step, run.ordinal);
+      yield* Option.match(candidate, { onNone: () => Effect.void, onSome: (state) => Ref.set(observed, state).pipe(Effect.andThen(memory.deferAfterReply(afterRun))) });
+      return recorded;
+    }).pipe(Effect.provideService(CurrentAgentRun, Option.some(run)), Effect.provideService(CurrentAgentStep, Option.some(step))),
+    onContextOverflow: Effect.fnUntraced(function* (step, evidence) {
+      const known = (yield* Ref.get(recoveryClaims)).get(step);
+      if (known !== void 0)
+        return yield* recoveryOutcome(known);
+      const failed = (yield* Ref.get(dispatched)).get(step);
+      if (failed === void 0)
+        return !1;
+      return yield* Effect.uninterruptible(Effect.gen(function* () {
+        const fresh = yield* Deferred.make(), previous = yield* Ref.modify(recoveryClaims, (all) => [Option.fromNullishOr(all.get(step)), all.has(step) ? all : new Map([...all, [step, fresh]])]);
+        if (Option.isSome(previous))
+          return yield* recoveryOutcome(previous.value);
+        const terminal = yield* inRun(harnessDefectsAsFailures(Effect.gen(function* () {
+          const facts = yield* Option.match(Option.fromNullishOr(evidence), {
+            onNone: () => Effect.succeed(Option.none()),
+            onSome: (fact) => Schema.encodeEffect(Schema.fromJsonString(ModelOverflowEvidence))(fact).pipe(Effect.flatMap(Schema.decodeUnknownEffect(Schema.fromJsonString(ModelOverflowEvidence))), Effect.map(Option.some), Effect.mapError((cause) => new HarnessError({ code: "request.diverged", message: "overflow evidence did not encode", cause })))
+          });
+          yield* memory.requestSnapshot;
+          const identity = Option.orElse(Option.map(facts, (fact) => fact.model), () => failed.identity), catalog = yield* Option.match(Context.getOption(runServices, ModelCatalog), { onNone: () => Effect.succeed([]), onSome: (service) => service.list }), limits = Option.flatMap(identity, (selection) => Option.fromNullishOr(catalog.find((entry) => entry.selection === formatModelSelection(selection))?.limits)), contextWindow = Option.orElse(Option.flatMap(facts, (fact) => Option.fromNullishOr(fact.limits.contextWindow)), () => Option.flatMap(limits, (value) => Option.fromNullishOr(value.contextWindow))), output = Option.flatMap(facts, (fact) => Option.fromNullishOr(fact.limits.maxOutputTokens)), bounds = {
+            ...Option.match(contextWindow, { onNone: () => ({}), onSome: (contextWindow) => ({ contextWindow }) }),
+            ...Option.match(output, { onNone: () => ({}), onSome: (maxOutputTokens) => ({ maxOutputTokens }) })
+          }, sameObservation = freezeModelRequest(matchingObservation(identity, (yield* Ref.get(observed)).observed)), failedComparable = scaledTokens(failed.estimatedTokens, sameObservation), tighter = tighterOverflowBudget(yield* Ref.get(inputCeiling), failed.reservedTokens, failedComparable, bounds);
+          if (Option.isNone(tighter))
+            return !1;
+          yield* Ref.update(inputCeiling, (previous) => Math.min(previous, tighter.value.inputCeiling));
+          yield* session.maintain({
+            phase: "overflow",
+            lastUsage: (yield* Ref.get(observed)).usage,
+            budgetTokens: tighter.value.messageBudget,
+            views: tools.views,
+            render: { run: run.ordinal, stepContext: failed.render.stepContext },
+            ...Option.match(sameObservation, { onNone: () => ({}), onSome: (observed) => ({ observed }) })
+          });
+          const built = yield* session.build({ run: run.ordinal, stepContext: failed.render.stepContext }), comparable = scaledTokens(built.estimatedTokens, sameObservation), ceiling = yield* Ref.get(inputCeiling);
+          if (comparable >= failedComparable || comparable > Math.min(tighter.value.messageBudget, ceiling - failed.reservedTokens))
+            return !1;
+          const render = yield* session.renderRecipe(failed.render.stepContext, run.ordinal), header = { ...failed.header, render, through: built.through, contextFingerprint: built.fingerprint, stableMessages: built.stableMessages }, outgoing = { ...failed.outgoing, messages: freezeModelRequest(markVolatileContext(built.messages, built.stableMessages)) }, candidate = { ...failed, through: built.through, render, fingerprint: built.fingerprint, estimatedTokens: built.estimatedTokens, header, outgoing };
+          yield* events.publish({
+            _tag: "context.built",
+            step,
+            turn: run.turn,
+            run: run.ordinal,
+            strategy: session.strategy.id,
+            strategyVersion: session.strategy.version,
+            fingerprint: built.fingerprint,
+            systemFingerprint: fingerprintOf(failed.decision.system),
+            estimatedTokens: built.estimatedTokens,
+            reservedTokens: failed.reservedTokens,
+            budgetTokens: ceiling,
+            compactions: built.compactions.length,
+            activeTools: failed.header.tools.map((tool) => tool.name)
+          });
+          yield* memory.prepareRequest(header);
+          yield* Ref.update(privatePlans, (all) => new Map([...all, [canonicalJson(header), candidate]]));
+          yield* Ref.set(planned, Option.some(candidate));
+          yield* Ref.set(recovery, Option.some(candidate));
+          return !0;
+        })), Option.some(step)).pipe(Effect.interruptible, Effect.exit);
+        yield* Deferred.done(fresh, terminal);
+        return yield* terminal;
+      }));
+    }),
+    pendingSteers: memory.pendingSteers,
+    steer: (step) => memory.steer(step, run.ordinal),
+    recorded: (step) => memory.requestSnapshot.pipe(Effect.map(({ entries }) => entries.filter((entry) => entry.runId === run.id && entry.turn === run.turn && entry.step === step && (entry.body._tag === "Message" || entry.body._tag === "ToolResult") && entry.body.run === run.ordinal))),
+    onMediaRejected: Effect.fnUntraced(function* (reason) {
+      const last = yield* Ref.get(planned);
+      if (Option.isNone(last))
+        return !1;
+      const entries = yield* session.entries, through = last.value.through, built = Option.isNone(through) ? [] : entries.slice(0, entries.findIndex((entry) => entry.id === through.value) + 1), sent = entriesSendingMedia(built, last.value.render);
+      if (sent.length === 0)
+        return !1;
+      yield* session.record([{
+        _tag: "Compaction",
+        strategy: session.strategy.id,
+        version: session.strategy.version,
+        action: { _tag: "OmitMedia", entries: sent, reason: reason.slice(0, MEDIA_REJECTION_CHARS) }
+      }], last.value.step);
+      yield* Ref.set(replanning, last);
+      return !0;
+    }),
+    completion: (info) => policy.completion === void 0 ? Effect.succeed(incomplete) : inRun(policy.completion(info), Option.some(info.stepIndex)).pipe(Effect.map(normalVerdict)),
+    steering: options.steering ?? Effect.succeed(Option.none()),
+    ...options.waiting === void 0 ? {} : { waiting: inRun(options.waiting) },
+    correctives: Option.fromNullishOr(policy.correctives),
+    events,
+    tasks,
+    cacheKey,
+    callPolicy,
+    captureTraceContent: policy.captureTraceContent ?? options.captureTraceContent ?? (yield* Effect.service(CurrentTraceContent))
+  }, maintenance = inRun(harnessDefectsAsFailures(Effect.gen(function* () {
+    yield* memory.requestSnapshot;
+    const last = yield* Ref.get(planned), accepted = yield* Ref.get(observed), reserve = Option.orElse(accepted.baseReservedTokens, () => Option.map(last, (plan) => plan.baseReservedTokens)), remaining = (yield* Ref.get(inputCeiling)) - Option.getOrElse(reserve, () => 0);
+    yield* session.maintain({
+      phase: "turn-end",
+      lastUsage: accepted.usage,
+      budgetTokens: Math.max(1, remaining),
+      views: tools.views,
+      render: { run: run.ordinal, stepContext: "none" },
+      ...Option.match(accepted.observed, { onNone: () => ({}), onSome: (observed) => ({ observed }) })
+    });
+  }))), terminal = yield* Ref.make(Option.none()), afterRun = Effect.uninterruptible(Effect.gen(function* () {
+    const fresh = yield* Deferred.make(), previous = yield* Ref.modify(terminal, (existing) => [existing, Option.orElse(existing, () => Option.some(fresh))]);
+    if (Option.isSome(previous))
+      return yield* Deferred.await(previous.value).pipe(Effect.interruptible);
+    const exit = yield* maintenance.pipe(Effect.interruptible, Effect.exit);
+    yield* Deferred.done(fresh, exit);
+    return yield* exit;
+  }));
+  return request;
+}), runTurnLoop = (policy, options = {}) => (options.waiting ?? Effect.succeed(!1)).pipe(Effect.flatMap((waiting) => waiting ? Effect.succeed({ outcome: "waiting", reason: "waiting", text: "", steps: 0, usage: zeroUsage }) : stepRequestOf(policy, options).pipe(Effect.flatMap((request) => StepLoop.pipe(Effect.flatMap((loop) => loop.run(request)))))));

package/dist/turn/turn.adapter.d.ts

@@ -0,0 +1,26 @@
+import { Layer } from "effect";
+import { ConversationMemory, RunContext, ToolRegistry, TurnEvents, TurnMemory, TurnPrompt, TurnTasks, TurnToolbox } from "@xandreed/core";
+import type { TurnError, TurnLiveInput } from "@xandreed/core";
+/**
+ * One admitted turn's services, over the turn's writer, built in this order:
+ * the event bus and the tasks, with the writer as the bus's FIRST
+ * subscriber (every stored event is queued before any reaction runs) and
+ * the turn's usage (`RunContext.usage`) as the second; then the memory
+ * session, opened over the session's earlier memory events where this
+ * layer is built (a digester or summarizer there is used), and RunContext.
+ * It also holds the tools slot (`TurnToolbox`) and the prompt state
+ * (`TurnPrompt`). Where the turn stands is one `TurnPhase`, moved by the
+ * pure transitions of `turn-phase.entity.functions.ts`; what a transition
+ * plans (a record, a publish) runs after it. The message was stored when
+ * the turn began; memory takes it at `TurnMemory.persistMessage`, and
+ * records nothing before it (`TurnMemory.context` waits for it). Its
+ * reply, and what memory records after it, the writer holds for the turn's
+ * closing commit (`TurnWriter.closing`), stored with `turn.ended`; a failed
+ * reply after a completed one holds it again, failed, under its own id.
+ * Tasks run in the layer's scope: they are interrupted when it closes.
+ * `TurnMemory.persistReply` runs under its span, `turn.persist_reply`
+ * (inline `turn.ended` subscribers' spans nest under it).
+ *
+ * @public
+ */
+export declare const TurnLive: (input: TurnLiveInput) => Layer.Layer<RunContext | TurnEvents | TurnTasks | TurnMemory | TurnToolbox | TurnPrompt, TurnError, ConversationMemory | ToolRegistry>;

package/dist/turn/turn.adapter.js

@@ -0,0 +1,225 @@
+import { Context, Effect, Layer, Match, Option, Ref, Result, Schema, Scope, Semaphore } from "effect";
+import {
+  addUsage,
+  canonicalJson,
+  Capabilities,
+  ConversationMemory,
+  CurrentAgentRun,
+  CurrentAgentStep,
+  CurrentModelCallRecorder,
+  entriesOfEvents,
+  fingerprintOf,
+  frameworkDraft,
+  HarnessError,
+  makeTurnEvents,
+  makeTurnTasks,
+  MEMORY_KINDS,
+  RequestPartData,
+  RequestPartHash,
+  readStoredKeys,
+  RESERVED_KINDS,
+  RunContext,
+  SectionId,
+  storedJson,
+  ToolRegistry,
+  TurnEvents,
+  TurnMemory,
+  TurnPrompt,
+  TurnTasks,
+  TurnToolbox,
+  userRoleMessageOf,
+  zeroUsage
+} from "@xandreed/core";
+import { draftOfTurnEvent, draftsOfEntries, encodeRequestPart, prepareRequestParts, readerOf, renderSections } from "@xandreed/core/internal";
+import { ReplyStep } from "./turn-phase.entity.js";
+import { addContext, claim, heldWith, hold, numberOf, release, reply, sectionsDue, startRun, take } from "./turn-phase.entity.functions.js";
+import { makeTurnModelCallRecorder } from "./model-call-recorder.adapter.js";
+import { acceptedInputOf } from "./turn-observation.entity.functions.js";
+import { isWriterCause } from "./turn-after-reply.entity.functions.js";
+import { makeMemoryCheckpoint } from "./memory-checkpoint.adapter.js";
+const failure = (code, message) => new HarnessError({ code, message }), storedDraft = (turn) => (event) => event._tag === "host" && RESERVED_KINDS.includes(event.name) ? Effect.fail(failure("events.reserved", `${event.name} is the framework's kind`)) : draftOfTurnEvent(turn, event).pipe(Effect.mapError((error) => failure("events.encode", `${event._tag} does not encode: ${error.message}`)), Effect.map(Option.map((draft) => frameworkDraft(draft.kind, draft.data)))), contextBody = (entry) => ({ _tag: "TurnContext", sectionId: SectionId.make(entry.id), version: entry.version, text: entry.text });
+export const TurnLive = (input) => Layer.effectContext(Effect.gen(function* () {
+  const scope = yield* Effect.scope, memory = yield* ConversationMemory, registry = yield* ToolRegistry, sections = Option.getOrElse(yield* Effect.serviceOption(Capabilities), () => []).flatMap((capability) => capability.promptSections), writer = input.turn, admitted = writer.admitted, events = yield* makeTurnEvents({ maxDepth: input.maxEventDepth ?? 8 }), modelCalls = yield* makeTurnModelCallRecorder(writer, (data) => events.publish({ _tag: "model.called", ...data }));
+  yield* Effect.addFinalizer(() => modelCalls.close);
+  const tasks = yield* makeTurnTasks(scope);
+  yield* events.subscribe(Option.some, (event) => storedDraft(admitted.turn)(event).pipe(Effect.flatMap(Option.match({ onNone: () => Effect.void, onSome: (draft) => writer.append([draft]) }))));
+  const usage = yield* Ref.make(zeroUsage);
+  yield* events.subscribe((event) => event._tag === "assistant.message" ? Option.some(event) : Option.none(), (step) => Ref.update(usage, (total) => addUsage(total, step.usage)).pipe(Effect.andThen(modelCalls.legacy({ model: step.model, usage: step.usage, run: step.run, step: step.step, replayed: !1 }))));
+  const phase = yield* Ref.make({ _tag: "Waiting", early: [] }), transition = (decide) => Ref.modify(phase, (current) => Result.match(decide(current), {
+    onFailure: (error) => [Result.fail(error), current],
+    onSuccess: ([value, next]) => [Result.succeed(value), next]
+  })).pipe(Effect.flatMap(Effect.fromResult)), history = yield* Ref.make(Option.none()), rawHistory = yield* Ref.make(Option.none()), decoded = (stored) => entriesOfEvents(stored).pipe(Effect.mapError((error) => failure("memory.log", `undecodable memory events: ${error.message}`))), historicalRows = Ref.get(rawHistory).pipe(Effect.flatMap(Option.match({
+    onNone: () => writer.history(MEMORY_KINDS).pipe(Effect.tap((rows) => Ref.set(rawHistory, Option.some(rows)))),
+    onSome: Effect.succeed
+  }))), readHistory = historicalRows.pipe(Effect.flatMap(decoded)), checkpoint = writer.memorySnapshot === void 0 ? void 0 : yield* makeMemoryCheckpoint(writer, historicalRows), storedEntry = readStoredKeys("turn.started", [writer.started]).pipe(Effect.map((starts) => starts.map((started) => started.keys.entry)), Effect.mapError((error) => failure("memory.log", `undecodable turn.started: ${error.message}`))), draftsOf = (entries) => draftsOfEntries(entries).pipe(Effect.mapError((error) => failure("memory.log", error.message)), Effect.map((drafts) => drafts.map((draft) => frameworkDraft(draft.kind, draft.data)))), holding = yield* Semaphore.make(1), holdNow = (held) => draftsOf(held).pipe(Effect.flatMap(writer.closing), Effect.andThen(Ref.update(phase, hold(held)))), log = {
+    read: readHistory.pipe(Effect.tap((entries) => Ref.set(history, Option.some(entries)))),
+    ...checkpoint === void 0 ? {} : { checkpoint },
+    snapshot: writer.snapshot(MEMORY_KINDS).pipe(Effect.flatMap(decoded), Effect.flatMap((entries) => Ref.get(phase).pipe(Effect.map((current) => Option.isNone(numberOf(current)) ? entries.filter((entry) => entry.body._tag !== "TurnStarted" || entry.runId !== admitted.runId) : entries)))),
+    append: Effect.fnUntraced(function* (entries) {
+      if (Option.isNone(numberOf(yield* Ref.get(phase))) && entries.some((entry) => entry.body._tag !== "TurnStarted"))
+        return yield* Effect.fail(failure("turn.unstarted", "memory records nothing before the turn's message is taken (persistMessage); TurnMemory.context waits for it"));
+      const started = entries.filter((entry) => entry.body._tag === "TurnStarted"), stored = started.length === 0 ? [] : yield* storedEntry;
+      if (started.some((entry) => entry.turn !== admitted.turn || !stored.includes(entry.id)))
+        return yield* Effect.fail(failure("turn.numbering", `memory took the message as ${started.map((entry) => `${entry.id} of turn ${entry.turn}`).join()}, the session stored ${stored.join()} of turn ${admitted.turn}`));
+      yield* holding.withPermits(1)(Ref.get(phase).pipe(Effect.flatMap((current) => Option.match(heldWith(entries)(current), {
+        onNone: () => draftsOf(entries).pipe(Effect.flatMap(writer.append), Effect.andThen(writer.flush)),
+        onSome: holdNow
+      }))));
+    })
+  }, session = yield* memory.open({ conversation: admitted.session.id, runId: admitted.runId, log }).pipe(Effect.provideService(CurrentModelCallRecorder, modelCalls.recorder), Effect.provideService(CurrentAgentRun, Option.none()), Effect.provideService(CurrentAgentStep, Option.none())), reader = readerOf(session), slot = yield* Ref.make({ _tag: "Closed" }), unavailable = Effect.fail(failure("tools.unavailable", "Tools are not open yet")), openTools = Ref.get(slot).pipe(Effect.flatMap((current) => Match.valueTags(current, {
+    Closed: () => unavailable,
+    Opening: () => unavailable,
+    Open: ({ tools }) => Effect.succeed(tools)
+  }))), run = RunContext.of({
+    conversation: admitted.session.id,
+    session: admitted.session,
+    runId: admitted.runId,
+    userMessage: admitted.userMessage,
+    admitted,
+    memory: reader,
+    events,
+    tasks,
+    activate: (skills) => openTools.pipe(Effect.flatMap((tools) => tools.activate(skills, "host"))),
+    flush: writer.flush,
+    write: writer.write,
+    usage: Ref.get(usage)
+  }), requestKinds = [...MEMORY_KINDS, "request.part", "request.prepared"], snapshots = yield* Semaphore.make(1), snapshot = yield* Ref.make(Option.none()), refreshRequests = Effect.gen(function* () {
+    const known = yield* Option.match(yield* Ref.get(snapshot), {
+      onNone: () => Effect.gen(function* () {
+        const entries = yield* Ref.get(history).pipe(Effect.flatMap(Option.match({ onNone: () => readHistory, onSome: Effect.succeed }))), requestEvents = yield* writer.history(["request.part"]);
+        return { entries, requests: [], requestEvents, cursor: writer.started.seq - 1 };
+      }),
+      onSome: Effect.succeed
+    }), stored = (yield* writer.snapshot(requestKinds, known.cursor)).filter((event) => event.session === writer.started.session && event.seq > known.cursor), ownHeaders = (yield* readStoredKeys("request.prepared", stored).pipe(Effect.mapError((error) => failure("request.decode", error.message)))).flatMap((header) => header.keys.runId === admitted.runId ? [header.event] : []), selected = new Set(ownHeaders), next = {
+      entries: [...known.entries, ...yield* decoded(stored.filter((event) => MEMORY_KINDS.includes(event.kind)))],
+      requests: [...known.requests, ...ownHeaders],
+      requestEvents: [...known.requestEvents, ...stored.filter((event) => event.kind === "request.part" || selected.has(event))],
+      cursor: stored.reduce((last, event) => Math.max(last, event.seq), known.cursor)
+    };
+    yield* Ref.set(snapshot, Option.some(next));
+    return next;
+  }), requestSnapshot = snapshots.withPermits(1)(refreshRequests).pipe(Effect.map(({ entries, requests, requestEvents }) => ({ entries, requests, requestEvents }))), partKey = Schema.Struct({ hash: RequestPartHash }), prepareRequest = Effect.fnUntraced(function* (header) {
+    const encoded = yield* prepareRequestParts(header).pipe(Effect.flatMap((prepared) => Effect.all({
+      header: storedJson(prepared.header),
+      parts: Effect.forEach(prepared.parts, (expected) => storedJson(expected).pipe(Effect.map((data) => ({ expected, data }))), { concurrency: 1 })
+    }, { concurrency: 1 })), Effect.mapError((cause) => new HarnessError({ code: "request.encode", message: "request parts did not encode", cause })));
+    yield* snapshots.withPermits(1)(Effect.gen(function* () {
+      const visible = (yield* refreshRequests).requestEvents.filter((event) => event.kind === "request.part"), keyed = yield* Effect.forEach(visible, (event) => Schema.decodeUnknownEffect(partKey)(event.data).pipe(Effect.map((keys) => ({ keys, event })), Effect.mapError((cause) => new HarnessError({ code: "request.decode", message: "request part lookup keys did not decode", cause }))), { concurrency: 1 }), missing = yield* Effect.forEach(encoded.parts, ({ expected, data }) => Effect.gen(function* () {
+        const category = Match.valueTags(expected.part, { System: () => "system", Tool: () => "tools" }), prior = keyed.filter(({ keys }) => keys.hash === expected.hash);
+        yield* Effect.forEach(prior, ({ event }) => Schema.decodeUnknownEffect(RequestPartData)(event.data).pipe(Effect.mapError((cause) => new HarnessError({ code: "request.diverged", message: `${category}: stored request part did not decode`, cause })), Effect.flatMap((part) => encodeRequestPart(part.part).pipe(Effect.mapError((cause) => new HarnessError({ code: "request.diverged", message: `${category}: stored request part did not encode`, cause })))), Effect.flatMap((part) => part.hash === expected.hash && canonicalJson(part.part) === canonicalJson(expected.part) ? Effect.void : Effect.fail(new HarnessError({ code: "request.diverged", message: `${category}: stored request part content does not match its hash` })))), { concurrency: 1, discard: !0 });
+        return prior.length === 0 ? [frameworkDraft("request.part", data)] : [];
+      }), { concurrency: 1 });
+      yield* writer.append([...missing.flat(), frameworkDraft("request.prepared", encoded.header)]);
+      yield* writer.flush;
+    }));
+  }), recordContext = (bodies) => bodies.length === 0 ? Effect.void : session.record(bodies, 0).pipe(Effect.asVoid), acceptingSteers = Ref.get(phase).pipe(Effect.flatMap((current) => Match.valueTags(current, {
+    Waiting: () => Effect.fail(failure("turn.unstarted", "The user's message is not persisted yet")),
+    Taking: () => Effect.fail(failure("turn.unstarted", "The user's message is not persisted yet")),
+    Taken: () => Effect.void,
+    Replied: () => Effect.fail(failure("turn.closed", "The turn's reply is recorded: no steering is accepted after it"))
+  }))), afterReplyWork = yield* Ref.make(Option.none()), turnMemory = TurnMemory.of({
+    ...reader,
+    strategy: session.strategy,
+    session,
+    pendingSteers: acceptingSteers.pipe(Effect.andThen(writer.steers), Effect.map((inputs) => inputs.length > 0)),
+    steer: Effect.fnUntraced(function* (step, ordinal) {
+      yield* acceptingSteers;
+      const bodies = (yield* writer.steers).map((input) => ({
+        _tag: "Message",
+        inbox: input.id,
+        run: ordinal,
+        message: userRoleMessageOf(input.userMessage)
+      })), gateFailure = yield* Ref.make(Option.none()), recorded = yield* session.record(bodies, step, (entries) => holding.withPermits(1)(acceptingSteers.pipe(Effect.result, Effect.flatMap((result) => Result.match(result, {
+        onFailure: (error) => Ref.set(gateFailure, Option.some(error)).pipe(Effect.as(!1)),
+        onSuccess: () => writer.take(entries)
+      })))));
+      yield* Option.match(yield* Ref.get(gateFailure), { onNone: () => Effect.void, onSome: Effect.fail });
+      return recorded.flatMap((entry) => entry.body._tag === "Message" ? [entry.body.message] : []);
+    }),
+    prepareRequest,
+    requestSnapshot,
+    number: Ref.get(phase).pipe(Effect.flatMap((current) => Option.match(numberOf(current), {
+      onNone: () => Effect.fail(failure("turn.unstarted", "The user's message is not persisted yet")),
+      onSome: (number) => Effect.succeed(number)
+    }))),
+    startRun: transition(startRun(admitted.runId)),
+    deferAfterReply: (work) => Ref.set(afterReplyWork, Option.some(work)),
+    afterReply: Effect.gen(function* () {
+      const work = yield* Ref.getAndSet(afterReplyWork, Option.none());
+      if (Option.isNone(work) || writer.seal === void 0)
+        return;
+      const sealed = yield* writer.seal;
+      if (Option.isNone(sealed))
+        return;
+      yield* work.value.pipe(Effect.raceFirst(sealed.value), Effect.catchCause((cause) => isWriterCause(cause) ? Effect.failCause(cause) : Effect.logWarning("the work after the turn's reply did not finish; the next run's start maintains what it left", cause)));
+    }).pipe(Effect.withSpan("turn.after_reply")),
+    acceptedBefore: Effect.gen(function* () {
+      const starts = (yield* historicalRows).filter((event) => event.session === admitted.session.id && event.kind === "turn.started"), after = Option.match(Option.fromNullishOr(starts.at(-1)), { onNone: () => writer.started.seq - 1, onSome: (last) => last.seq - 1 });
+      return acceptedInputOf(yield* writer.snapshot(["step.usage", "context.built"], after));
+    }),
+    persistMessage: Effect.gen(function* () {
+      yield* transition(claim);
+      const number = admitted.turn;
+      yield* session.record([{ _tag: "TurnStarted", userMessage: admitted.userMessage }], 0).pipe(Effect.onError(() => Ref.update(phase, release)));
+      yield* recordContext(yield* transition(take(number)));
+      yield* events.publish({
+        _tag: "turn.started",
+        runId: admitted.runId,
+        turn: number,
+        userMessage: admitted.userMessage,
+        meta: admitted.meta,
+        ...admitted.resumes === void 0 ? {} : { resumes: admitted.resumes }
+      });
+      return number;
+    }),
+    context: (entry) => transition(addContext(contextBody(entry))).pipe(Effect.flatMap(recordContext)),
+    persistReply: Effect.fn("turn.persist_reply")(function* (outcome) {
+      const step = yield* holding.withPermits(1)(transition(reply(outcome.outcome)).pipe(Effect.tap((next) => ReplyStep.guards.Hold(next) ? holdNow(next.held) : Effect.void)));
+      if (!ReplyStep.guards.Record(step))
+        return;
+      yield* session.record([{ _tag: "TurnEnded", outcome: outcome.outcome, reply: outcome.reply }], 0);
+      yield* events.publish({ _tag: "turn.ended", runId: admitted.runId, turn: step.number, outcome: outcome.outcome, reply: outcome.reply, usage: yield* Ref.get(usage) });
+    })
+  }), toolbox = TurnToolbox.of({
+    open: Effect.gen(function* () {
+      if (!(yield* Ref.modify(slot, (current) => current._tag === "Closed" ? [!0, { _tag: "Opening" }] : [!1, current])))
+        return yield* Effect.fail(failure("tools.opened", "The turn's tools are already open"));
+      const tools = yield* registry.open(session).pipe(Effect.provideService(RunContext, run), Scope.provide(scope), Effect.onError(() => Ref.set(slot, { _tag: "Closed" })));
+      yield* Ref.set(slot, { _tag: "Open", tools });
+      return tools;
+    }),
+    tools: openTools
+  }), promptContext = (tools, variant) => tools.active.pipe(Effect.map((active) => ({ variant, active, skills: tools.skills }))), rendered = (tools, variant, tiers) => promptContext(tools, variant).pipe(Effect.flatMap((context) => renderSections(sections.filter(tiers), context))), lastSystem = yield* Ref.make(Option.fromNullishOr((yield* session.entries).flatMap((entry) => entry.body._tag === "SystemPrepared" ? [entry.body.fingerprint] : []).at(-1))), systems = yield* Ref.make(new Map), prompt = TurnPrompt.of({
+    system: Effect.fnUntraced(function* (variant) {
+      const key = Option.getOrElse(variant, () => ""), known = (yield* Ref.get(systems)).get(key);
+      if (known !== void 0)
+        return known;
+      const parts = yield* rendered(yield* openTools, variant, (section) => section.tier !== "turn"), text = [input.system ?? "", ...parts.map((part) => part.text)].filter((part) => part.trim().length > 0).join(`
+
+`), fingerprint = fingerprintOf(text);
+      if (!Option.contains(yield* Ref.get(lastSystem), fingerprint)) {
+        yield* session.record([{
+          _tag: "SystemPrepared",
+          fingerprint,
+          text,
+          sections: parts.map((part) => ({ id: SectionId.make(part.section.id), version: part.section.version, fingerprint: fingerprintOf(part.text) }))
+        }], 0);
+        yield* Ref.set(lastSystem, Option.some(fingerprint));
+      }
+      yield* Ref.update(systems, (all) => new Map([...all, [key, text]]));
+      return text;
+    }),
+    turnSections: Effect.gen(function* () {
+      if (!(yield* transition(sectionsDue)))
+        return;
+      const parts = yield* rendered(yield* openTools, Option.none(), (section) => section.tier === "turn");
+      yield* parts.length === 0 ? Effect.void : session.record(parts.map(({ section, text }) => ({
+        _tag: "TurnContext",
+        sectionId: SectionId.make(section.id),
+        version: section.version,
+        text
+      })), 0);
+    })
+  });
+  return Context.make(RunContext, run).pipe(Context.add(CurrentModelCallRecorder, modelCalls.recorder), Context.add(CurrentAgentRun, Option.none()), Context.add(CurrentAgentStep, Option.none()), Context.add(TurnEvents, events), Context.add(TurnTasks, tasks), Context.add(TurnMemory, turnMemory), Context.add(TurnToolbox, toolbox), Context.add(TurnPrompt, prompt));
+}));

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xandreed/sdk",
-  "version": "0.13.0",
+  "version": "0.15.0",
   "engines": {
     "node": ">=24",
     "bun": ">=1.3.0"
@@ -11,15 +11,21 @@
     ".": {
       "types": "./dist/index.d.ts",
       "default": "./dist/index.js"
+    },
+    "./conformance": {
+      "types": "./dist/conformance/index.d.ts",
+      "default": "./dist/conformance/index.js"
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.13.0",
-    "effect": "4.0.7",
-    "@xandreed/runtime": "0.13.0"
+    "@xandreed/runtime": "^0.15.0"
   },
   "private": false,
   "types": "./dist/index.d.ts",
+  "peerDependencies": {
+    "@xandreed/core": "^0.15.0",
+    "effect": "^4.0.7"
+  },
   "files": [
     "dist",
     "skills",

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

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

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

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