@xandreed/sdk 0.13.0 → 0.15.0

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

@@ -0,0 +1,135 @@
+import { Effect } from "effect";
+import { RunContext, TurnEvents, TurnMemory, TurnTasks, TurnToolbox } from "@xandreed/core";
+import type { AdmittedTurn, ConversationId, RunId, RunTools, StepLoop, Turn, TurnError, TurnOutcome, TurnResult, TurnRunOptions, TurnTools, TurnWriter } from "@xandreed/core";
+import type { TurnRunServices } from "./turn-run.usecase.functions.js";
+/**
+ * Open the turn's tools (once). Their handlers run with the services of where this runs: open them inside the host's layer.
+ *
+ * @public
+ */
+export declare const openTurnTools: Effect.Effect<RunTools, TurnError, TurnToolbox>;
+/**
+ * The host's view of the open tools; skills the host activates are recorded
+ * as its own.
+ *
+ * @public
+ */
+export declare const turnTools: Effect.Effect<TurnTools, TurnError, TurnToolbox>;
+/**
+ * Await the tasks, then drain the background reactions, again until a round starts nothing new.
+ *
+ * @public
+ */
+export declare const settleTurn: Effect.Effect<void, TurnError, TurnEvents | TurnTasks>;
+/**
+ * Record the reply (`persistReply`), drain the reactions to it, and flush
+ * the journal. The reply is recorded and the journal flushed even when the
+ * fiber is interrupted meanwhile; only the drain can be cut. The reply is
+ * stored with the turn's end; when the drain or the flush fails, or the
+ * drain is cut, it is downgraded to failed first.
+ *
+ * @public
+ */
+export declare const finishTurn: (outcome: TurnOutcome) => Effect.Effect<void, TurnError, TurnMemory | TurnEvents | RunContext>;
+/**
+ * Run a turn's body to its end: once it succeeds, the turn settles (tasks
+ * and background reactions) and finishes with its outcome, returned with
+ * the turn's usage (`RunContext.usage`, the same total `turn.ended`
+ * carries). Once the body has returned, its reply is recorded and the
+ * journal flushed even when the turn is interrupted then; an interruption
+ * cuts only the drain of the reactions to the reply. The reply is stored
+ * with the turn's end (`TurnWriter.closing`): when that finishing fails or
+ * is cut, the turn fails with its cause and the reply is downgraded to
+ * failed, so the end never stores a completed reply. When the body fails or
+ * is interrupted, the turn finishes as failed and keeps the body's cause:
+ * the failed reply is recorded, the reactions to it are waited for at most
+ * ten seconds (not at all once interrupted), a failure of that finishing is
+ * logged, and the usage its provider calls spent so far goes on the current
+ * span as `efferent.usage.*_tokens` (the turn's `agent.turn` when
+ * `guardTurn` runs under `traceTurn` with no span between, as in
+ * `Agent.turn`; `traceTurn` records it itself when the turn returns). A
+ * `TurnError` carried as a defect (a subscriber's or the writer's failure
+ * behind a `never` error channel) fails the turn, typed.
+ *
+ * @public
+ */
+export declare const guardTurn: <E, R>(body: Effect.Effect<TurnOutcome, E, R>) => Effect.Effect<TurnResult, E | TurnError, R | TurnMemory | TurnEvents | TurnTasks | RunContext>;
+/**
+ * The `Turn` a host's code works with, over the turn's services (the one
+ * `Agent.turn` hands to `use`): its `run` is `runTurnLoop` with `options`,
+ * its spans under the span current where `run` is called. The message must
+ * be persisted and the tools open.
+ *
+ * @public
+ */
+export declare const turnOf: (options?: TurnRunOptions | undefined) => Effect.Effect<Turn, TurnError, RunContext | StepLoop | TurnRunServices>;
+/**
+ * What a turn's span (`traceTurn`) shows besides the turn's ids.
+ *
+ * @public
+ */
+export interface TurnTraceOptions {
+    /**
+     * The keys of the turn's metadata (`AdmittedTurn.meta`) whose values the
+     * span carries, as `efferent.meta.<key>`: none by default, since metadata
+     * may hold what a trace backend should not (a user, a tenant). A string,
+     * number or boolean is kept as it is, anything else as its JSON; a key the
+     * turn's metadata lacks is left out.
+     */
+    readonly spanMeta?: ReadonlyArray<string>;
+}
+/**
+ * Run a turn under its span, `agent.turn`, the root of everything the turn
+ * does (under the caller's span, if any). It starts once the turn is
+ * admitted (`writer`), with `efferent.session.id`, `efferent.run.id`,
+ * `efferent.turn`, `gen_ai.conversation.id` (the session), `efferent.origin`,
+ * `efferent.resumes` (on a resume) and `options.spanMeta`'s
+ * `efferent.meta.<key>`; every span under it
+ * carries the first three too. It ends with `efferent.outcome` (the
+ * `TurnEnding` reason of the turn's exit: completed, partial, failed or
+ * interrupted; a turn cancelled or reaped while it ran shows as failed with
+ * `turn.closed`, its `TurnClosed`'s code), `efferent.failure.code` when the turn failed or was
+ * interrupted, and the turn's usage
+ * (`efferent.usage.{input,output,cache_read,cache_write,reasoning,total}_tokens`):
+ * when it returned, from its result; when it failed, what `guardTurn`
+ * records, so `guardTurn` runs under this span with no span between.
+ * `Agent.turn` encloses everything after `Sessions.begin`
+ * in it: the turn-dependent plugins, the host's layer, the tools opened, `use`,
+ * the reply and the end; a host composing its own turn wraps the same. The
+ * begin itself has its own span beside this one (`traceTurnBegin`).
+ *
+ * @public
+ */
+export declare const traceTurn: (writer: TurnWriter, options?: TurnTraceOptions) => <E, R>(effect: Effect.Effect<TurnResult, E, R>) => Effect.Effect<TurnResult, E, R>;
+/**
+ * A turn about to begin, as its begin span (`traceTurnBegin`) names it.
+ *
+ * @public
+ */
+export interface TurnBeginTrace {
+    readonly session: ConversationId;
+    readonly runId: RunId;
+    /** Who begins it: a user (a `User` begin), the inbox (an `Inbox` begin) or a background task (a `Task` begin). */
+    readonly origin: AdmittedTurn["origin"];
+}
+/**
+ * Run the work that begins a turn under its span, `agent.turn.begin`, a
+ * sibling of the turn's `agent.turn` under the caller's span (if any). It
+ * starts with `efferent.session.id`, `efferent.run.id` and `efferent.origin`,
+ * and ends with `efferent.turn` once the turn begins, or with
+ * `efferent.failure.code` when it cannot (the refusal's code, as
+ * `harnessCodeOf` gives it: `session.busy`, `turn.duplicate`…; else
+ * `turn.failed`, `turn.defect` or `turn.interrupted`). The work's logs carry
+ * the session and run ids as annotations. The work returns what names the
+ * admitted turn: its `TurnWriter` (`Sessions.begin`), or a value holding the
+ * admitted turn under `admitted`. `Agent.turn` encloses the session-scoped
+ * plugins' activation and `Sessions.begin` in it when it begins the turn
+ * itself; a turn the host began (its writer passed in) has no begin span. A
+ * host composing its own turn wraps its begin the same way, then the rest
+ * in `traceTurn`.
+ *
+ * @public
+ */
+export declare const traceTurnBegin: (begin: TurnBeginTrace) => <A extends {
+    readonly admitted: AdmittedTurn;
+}, E, R>(effect: Effect.Effect<A, E, R>) => Effect.Effect<A, E, R>;

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

@@ -0,0 +1,131 @@
+import { Cause, Context, Effect, Exit, Option } from "effect";
+import { CurrentToolResultReceipt } from "@xandreed/core/internal";
+import {
+  harnessDefectsAsFailures,
+  replayableContext,
+  RunContext,
+  sessionAttributes,
+  turnAttributes,
+  turnEndingOf,
+  TurnEvents,
+  TurnMemory,
+  TurnTasks,
+  TurnToolbox
+} from "@xandreed/core";
+import { runTurnLoop } from "./turn-run.usecase.functions.js";
+const failed = { outcome: "failed", reply: Option.none() };
+export const openTurnTools = TurnToolbox.pipe(Effect.flatMap((toolbox) => toolbox.open)), turnTools = TurnToolbox.pipe(Effect.flatMap((toolbox) => toolbox.tools), Effect.map((tools) => ({
+  match: tools.match,
+  apply: tools.apply,
+  select: tools.select,
+  activate: (skills) => tools.activate(skills, "host"),
+  active: tools.active,
+  skills: tools.skills
+}))), settleTurn = Effect.gen(function* () {
+  const events = yield* TurnEvents, tasks = yield* TurnTasks, activity = Effect.zipWith(tasks.activity, events.activity, (forked, delivered) => forked + delivered), settle = Effect.gen(function* () {
+    const before = yield* activity;
+    yield* tasks.await([]);
+    yield* events.drain;
+    if ((yield* activity) !== before)
+      yield* Effect.suspend(() => settle);
+  });
+  yield* settle;
+});
+const logFailure = (message) => (effect) => effect.pipe(Effect.exit, Effect.flatMap(Exit.match({
+  onSuccess: () => Effect.void,
+  onFailure: (cause) => Cause.hasInterruptsOnly(cause) ? Effect.void : Effect.logWarning(message, cause)
+}))), finishing = (restore, outcome) => Effect.gen(function* () {
+  const memory = yield* TurnMemory, finished = yield* Effect.exit(Effect.gen(function* () {
+    yield* memory.persistReply(outcome);
+    const drained = yield* Effect.exit(restore((yield* TurnEvents).drain));
+    yield* (yield* RunContext).flush;
+    return yield* drained;
+  }));
+  if (Exit.isFailure(finished)) {
+    yield* memory.persistReply(failed).pipe(logFailure("the turn's reply was not downgraded to failed"));
+    return yield* Effect.failCause(finished.cause);
+  }
+  if (outcome.outcome !== "completed" && outcome.outcome !== "partial")
+    return;
+  const after = yield* Effect.exit(restore(memory.afterReply));
+  if (Exit.isFailure(after) && !Cause.hasInterruptsOnly(after.cause))
+    return yield* Effect.failCause(after.cause);
+});
+export const finishTurn = (outcome) => Effect.uninterruptibleMask((restore) => finishing(restore, outcome));
+const failedReactionsWait = "10 seconds", finishFailed = Effect.gen(function* () {
+  const run = yield* RunContext;
+  yield* (yield* TurnMemory).persistReply(failed).pipe(logFailure("the failed turn's reply was not recorded"));
+  const settled = yield* (yield* TurnEvents).drain.pipe(Effect.timeoutOption(failedReactionsWait), Effect.interruptible, Effect.exit);
+  yield* Exit.match(settled, {
+    onSuccess: Option.match({
+      onSome: () => Effect.void,
+      onNone: () => Effect.logWarning(`the reactions to the failed turn's reply did not settle within ${failedReactionsWait}; the turn ends without them`)
+    }),
+    onFailure: (cause) => Cause.hasInterruptsOnly(cause) ? Effect.void : Effect.logWarning("the reactions to the failed turn's reply failed", cause)
+  });
+  yield* run.flush.pipe(logFailure("the failed turn's journal was not flushed"));
+  yield* Effect.annotateCurrentSpan(turnUsageAttributes(yield* run.usage));
+});
+export const guardTurn = (body) => Effect.uninterruptibleMask((restore) => Effect.gen(function* () {
+  const exit = yield* Effect.exit(restore(harnessDefectsAsFailures(body.pipe(Effect.tap(() => settleTurn)))));
+  if (Exit.isFailure(exit)) {
+    yield* finishFailed;
+    return yield* Effect.failCause(exit.cause);
+  }
+  const outcome = exit.value;
+  yield* finishing(restore, outcome);
+  const usage = yield* (yield* RunContext).usage;
+  return { outcome: outcome.outcome, reply: outcome.reply, usage };
+})), turnOf = Effect.fnUntraced(function* (options = {}) {
+  const services = Context.omit(CurrentToolResultReceipt)(replayableContext(yield* Effect.context())), run = yield* RunContext, memory = yield* TurnMemory;
+  return {
+    conversation: run.conversation,
+    runId: run.runId,
+    turn: yield* memory.number,
+    userMessage: run.userMessage,
+    admitted: run.admitted,
+    memory: run.memory,
+    events: run.events,
+    tasks: run.tasks,
+    tools: yield* turnTools,
+    context: memory.context,
+    reply: (text) => Effect.succeed({ outcome: "completed", reply: Option.some(text) }),
+    run: (policy) => runTurnLoop(policy, options).pipe(Effect.provide(services)),
+    usage: run.usage,
+    flush: run.flush,
+    write: run.write
+  };
+});
+const metaAttribute = (value) => typeof value === "string" || typeof value === "number" || typeof value === "boolean" ? value : JSON.stringify(value), turnSpanAttributes = (admitted, spanMeta) => ({
+  ...turnAttributes(admitted),
+  "gen_ai.conversation.id": admitted.session.id,
+  "efferent.origin": admitted.origin,
+  ...admitted.resumes === void 0 ? {} : { "efferent.resumes": admitted.resumes },
+  ...Object.fromEntries(spanMeta.filter((key) => Object.hasOwn(admitted.meta, key)).map((key) => [`efferent.meta.${key}`, metaAttribute(admitted.meta[key])]))
+}), turnUsageAttributes = (usage) => ({
+  "efferent.usage.input_tokens": usage.inputTokens,
+  "efferent.usage.output_tokens": usage.outputTokens,
+  "efferent.usage.cache_read_tokens": usage.cacheReadTokens,
+  "efferent.usage.cache_write_tokens": usage.cacheWriteTokens,
+  "efferent.usage.reasoning_tokens": usage.reasoningTokens,
+  "efferent.usage.total_tokens": usage.totalTokens
+}), turnEndAttributes = (exit) => {
+  const ending = turnEndingOf(exit);
+  return {
+    "efferent.outcome": ending.reason,
+    ...Option.match(ending.failure, { onNone: () => ({}), onSome: (failure) => ({ "efferent.failure.code": failure.code }) }),
+    ...Exit.match(exit, { onSuccess: (result) => turnUsageAttributes(result.usage), onFailure: () => ({}) })
+  };
+};
+export const traceTurn = (writer, options = {}) => (effect) => effect.pipe(Effect.onExit((exit) => Effect.annotateCurrentSpan(turnEndAttributes(exit))), Effect.annotateSpans(turnAttributes(writer.admitted)), Effect.withSpan("agent.turn", { attributes: turnSpanAttributes(writer.admitted, options.spanMeta ?? []) }));
+const beginAttributes = (begin) => ({
+  ...sessionAttributes(begin.session),
+  "efferent.run.id": begin.runId
+}), beginEndAttributes = (exit) => Exit.match(exit, {
+  onSuccess: (begun) => ({ "efferent.turn": begun.admitted.turn }),
+  onFailure: (cause) => Option.match(turnEndingOf(Exit.failCause(cause)).failure, {
+    onNone: () => ({}),
+    onSome: (failure) => ({ "efferent.failure.code": failure.code })
+  })
+});
+export const traceTurnBegin = (begin) => (effect) => effect.pipe(Effect.onExit((exit) => Effect.annotateCurrentSpan(beginEndAttributes(exit))), Effect.annotateLogs(beginAttributes(begin)), Effect.withSpan("agent.turn.begin", { attributes: { ...beginAttributes(begin), "efferent.origin": begin.origin } }));

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

@@ -0,0 +1,28 @@
+import { Schema } from "effect";
+/** The last accepted response of one prepared run, independent of billing. */
+export declare const TurnObservation: Schema.Struct<{
+    readonly observed: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly model: typeof import("@xandreed/core").ModelSelection;
+        readonly inputTokens: Schema.Int;
+        readonly estimatedTokens: Schema.Int;
+        readonly reservedTokens: Schema.Int;
+    }>>;
+    readonly usage: Schema.OptionFromNullOr<Schema.Struct<{
+        readonly inputTokens: Schema.Number;
+        readonly outputTokens: Schema.Number;
+        readonly totalTokens: Schema.Number;
+        readonly cacheReadTokens: Schema.Number;
+        readonly cacheWriteTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+        readonly reasoningTokens: Schema.withDecodingDefaultKey<Schema.Number, never>;
+    }>>;
+    readonly baseReservedTokens: Schema.OptionFromNullOr<Schema.Int>;
+}>;
+export type TurnObservation = typeof TurnObservation.Type;
+/** What a stored `context.built` froze of its request: the step it planned, its message estimate and reserve. */
+export declare const StoredRequestMeasure: Schema.Struct<{
+    readonly step: Schema.Int;
+    readonly run: Schema.withDecodingDefaultKey<Schema.brand<Schema.Int, "RunOrdinal">, never>;
+    readonly estimatedTokens: Schema.Int;
+    readonly reservedTokens: Schema.Int;
+}>;
+export type StoredRequestMeasure = typeof StoredRequestMeasure.Type;

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

@@ -0,0 +1,15 @@
+import { Option } from "effect";
+import { MemoryObservation } from "@xandreed/core";
+import type { AcceptedModelInput, ModelSelection, SessionLogEvent } from "@xandreed/core";
+export declare const matchingObservation: (model: Option.Option<ModelSelection>, observed: Option.Option<MemoryObservation>) => Option.Option<MemoryObservation>;
+export declare const observeAcceptedInput: (measurement: {
+    readonly estimatedTokens: number;
+    readonly reservedTokens: number;
+}, accepted: AcceptedModelInput) => Option.Option<MemoryObservation>;
+/**
+ * The last selected response among these stored events (`step.usage` with a
+ * model and a positive input), with the estimate and reserve its step's last
+ * `context.built` before it froze: accepted-input evidence that outlives the
+ * run that measured it. Rows that do not decode tell nothing.
+ */
+export declare const acceptedInputOf: (events: ReadonlyArray<SessionLogEvent>) => Option.Option<MemoryObservation>;

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

@@ -0,0 +1,17 @@
+import { Option, Schema } from "effect";
+import { MemoryObservation, parseModelSelection, StepUsageData } from "@xandreed/core";
+import { StoredRequestMeasure } from "./turn-observation.entity.js";
+export const matchingObservation = (model, observed) => Option.filter(observed, (value) => Option.exists(model, (expected) => expected.provider === value.model.provider && expected.modelId === value.model.modelId)), observeAcceptedInput = (measurement, accepted) => Option.flatMap(Option.all({ model: accepted.model, inputTokens: accepted.inputTokens }), (actual) => Schema.decodeUnknownOption(MemoryObservation)({ ...actual, ...measurement }));
+const decodeUsage = Schema.decodeUnknownOption(StepUsageData), decodeMeasure = Schema.decodeUnknownOption(StoredRequestMeasure);
+export const acceptedInputOf = (events) => {
+  const usages = events.flatMap((event) => event.kind === "step.usage" ? Option.toArray(Option.map(decodeUsage(event.data), (data) => ({ event, data }))) : []), measures = events.flatMap((event) => event.kind === "context.built" ? Option.toArray(Option.map(decodeMeasure(event.data), (data) => ({ event, data }))) : []);
+  return Option.flatMap(Option.fromNullishOr(usages.filter(({ data }) => Option.isSome(data.model) && data.usage.inputTokens > 0).at(-1)), (last) => {
+    const measure = Option.fromNullishOr(measures.filter(({ event, data }) => event.seq < last.event.seq && Option.getOrElse(event.turn, () => -1) === Option.getOrElse(last.event.turn, () => -2) && data.run === last.data.run && data.step === last.data.step).at(-1)), model = Option.flatMap(last.data.model, parseModelSelection);
+    return Option.flatMap(Option.all({ measure, model }), ({ measure, model }) => Schema.decodeUnknownOption(MemoryObservation)({
+      model,
+      inputTokens: last.data.usage.inputTokens,
+      estimatedTokens: measure.data.estimatedTokens,
+      reservedTokens: measure.data.reservedTokens
+    }));
+  });
+};

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

@@ -0,0 +1,12 @@
+import { Schema } from "effect";
+import { MemoryObservation, RunKey, TokenUsage } from "@xandreed/core";
+export const TurnObservation = Schema.Struct({
+  observed: Schema.OptionFromNullOr(MemoryObservation),
+  usage: Schema.OptionFromNullOr(TokenUsage),
+  baseReservedTokens: Schema.OptionFromNullOr(Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)))
+}), StoredRequestMeasure = Schema.Struct({
+  step: Schema.Int,
+  run: RunKey,
+  estimatedTokens: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0)),
+  reservedTokens: Schema.Int.check(Schema.isGreaterThanOrEqualTo(0))
+});

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

@@ -0,0 +1,7 @@
+import { Schema } from "effect";
+/** A strictly tighter input ceiling and the messages' share after fixed reserves. */
+export declare const OverflowBudget: Schema.Struct<{
+    readonly inputCeiling: Schema.Int;
+    readonly messageBudget: Schema.Int;
+}>;
+export type OverflowBudget = typeof OverflowBudget.Type;

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

@@ -0,0 +1,11 @@
+import { Option } from "effect";
+import type { ModelCallPolicy, ModelLimits } from "@xandreed/core";
+import { OverflowBudget } from "./turn-overflow.entity.js";
+/** Output is an actual attempted cap when known; an absent cap stays unknown. */
+export declare const tighterOverflowBudget: (previous: number, reserved: number, failedComparable: number, limits: ModelLimits) => Option.Option<OverflowBudget>;
+/**
+ * A model's known input bound before any request: its catalog window less
+ * the output the request will reserve (the call policy's cap, else the
+ * catalog's). None without a known window or when nothing would remain.
+ */
+export declare const windowBound: (limits: Option.Option<ModelLimits>, policy: Option.Option<ModelCallPolicy>) => Option.Option<number>;

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

@@ -0,0 +1,12 @@
+import { Option, Schema } from "effect";
+import { OverflowBudget } from "./turn-overflow.entity.js";
+const positive = (value) => value !== void 0 && Number.isSafeInteger(value) && value > 0 ? Option.some(value) : Option.none();
+export const tighterOverflowBudget = (previous, reserved, failedComparable, limits) => {
+  if (!Number.isSafeInteger(previous) || previous < 1 || !Number.isSafeInteger(reserved) || reserved < 0 || !Number.isSafeInteger(failedComparable) || failedComparable < 1)
+    return Option.none();
+  const context = positive(limits.contextWindow), output = positive(limits.maxOutputTokens), bound = Option.map(context, (window) => window - Option.getOrElse(output, () => 0)), applicable = Math.min(previous, Option.getOrElse(bound, () => previous)), messages = Math.floor(0.8 * Math.min(applicable - reserved, failedComparable));
+  return messages > 0 && messages < failedComparable && reserved + messages < previous ? Schema.decodeUnknownOption(OverflowBudget)({ inputCeiling: reserved + messages, messageBudget: messages }) : Option.none();
+}, windowBound = (limits, policy) => {
+  const context = Option.flatMap(limits, (value) => positive(value.contextWindow)), output = Option.orElse(Option.flatMap(policy, (value) => positive(value.maxOutputTokens)), () => Option.flatMap(limits, (value) => positive(value.maxOutputTokens)));
+  return Option.filter(Option.map(context, (window) => window - Option.getOrElse(output, () => 0)), (bound) => bound > 0);
+};

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

@@ -0,0 +1,5 @@
+import { Schema } from "effect";
+export const OverflowBudget = Schema.Struct({
+  inputCeiling: Schema.Int.check(Schema.isGreaterThan(0)),
+  messageBudget: Schema.Int.check(Schema.isGreaterThan(0))
+});