@xandreed/plugin-agent-loop 0.13.0 → 0.14.0

package/README.md

@@ -1,5 +1,5 @@
 # @xandreed/plugin-agent-loop
 
-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/loop.d.ts

@@ -46,6 +46,13 @@ export interface RunLoopOptions<Tools extends Record<string, Tool.Any>, R> {
     }, AiError.AiError, R>;
     /** Validate independently reconstructed durable input immediately before a provider dispatch. */
     readonly beforeDispatch?: (step: number, request: ModelDispatch) => Effect.Effect<void, never, R>;
+    /**
+     * A provider refused a step's request over an image (an `InvalidRequestError`
+     * that names one; the argument is what it said). True: the images are
+     * dealt with (memory omits them), and the loop renders the step again and
+     * sends it once more; false, or absent: the step fails with the refusal.
+     */
+    readonly onMediaRejected?: (reason: string) => Effect.Effect<boolean, never, R>;
     readonly system: string | Prompt.Prompt;
     /** The READ side of memory: when present, each provider step sends these
      * messages instead of the loop's own buffer. Persistence still flows through
@@ -60,8 +67,11 @@ export interface RunLoopOptions<Tools extends Record<string, Tool.Any>, R> {
         readonly malformed?: (tools: ReadonlyArray<string>, description: string) => string;
         readonly incomplete?: string;
     };
-    /** Explicit opt-in: export prompt and result content on step spans.
-     * Hosts own consent, redaction and exporter retention. Disabled by default. */
+    /** Explicit opt-in: export prompt and result content on step spans
+     * (`engine.step.input`, `engine.step.output`), and to the model calls
+     * through `CurrentTraceContent`, which the loop provides for the run.
+     * Hosts own consent, redaction and exporter retention. Defaults to
+     * `CurrentTraceContent` where the run starts: off unless provided. */
     readonly captureTraceContent?: boolean;
     readonly messages: ReadonlyArray<AgentMessage>;
     readonly toolkit: Toolkit.Toolkit<Tools>;
@@ -108,7 +118,8 @@ export interface RunLoopOptions<Tools extends Record<string, Tool.Any>, R> {
      * settled turn shape while fanning `assistant_delta` events as tokens
      * flow. Default FALSE. A stream that fails before its first part
      * (scripted providers' `Stream.die` included) falls back to
-     * `generateText` transparently — for the REST of the run, not per turn.
+     * `generateText` — for the REST of the run, not per turn — and emits one
+     * `stream_fallback` event with the stream's error.
      */
     readonly streaming?: boolean;
     /**
@@ -164,7 +175,19 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
     finalText: string;
     messages: readonly ({
         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 & import("effect/Brand").Brand<"MediaFingerprint">;
+            readonly bytes: number;
+            readonly name?: string;
+            readonly alt?: string;
+        } | {
+            readonly type: "text";
+            readonly text: string;
+            readonly providerOptions?: unknown;
+        })[];
         readonly providerOptions?: unknown;
     } | {
         readonly role: "assistant";
@@ -178,9 +201,9 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
             readonly providerOptions?: unknown;
         } | {
             readonly type: "tool-call";
+            readonly input: unknown;
             readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
             readonly toolName: string;
-            readonly input: unknown;
             readonly providerOptions?: unknown;
             readonly providerExecuted?: boolean | undefined;
         })[];
@@ -189,9 +212,18 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
         readonly role: "tool";
         readonly content: readonly {
             readonly type: "tool-result";
+            readonly output: unknown;
             readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
             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 & import("effect/Brand").Brand<"MediaFingerprint">;
+                readonly bytes: number;
+                readonly name?: string;
+                readonly alt?: string;
+            }[];
             readonly providerOptions?: unknown;
             readonly isError?: boolean | undefined;
         }[];
@@ -199,7 +231,19 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
     })[];
     newTail: readonly ({
         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 & import("effect/Brand").Brand<"MediaFingerprint">;
+            readonly bytes: number;
+            readonly name?: string;
+            readonly alt?: string;
+        } | {
+            readonly type: "text";
+            readonly text: string;
+            readonly providerOptions?: unknown;
+        })[];
         readonly providerOptions?: unknown;
     } | {
         readonly role: "assistant";
@@ -213,9 +257,9 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
             readonly providerOptions?: unknown;
         } | {
             readonly type: "tool-call";
+            readonly input: unknown;
             readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
             readonly toolName: string;
-            readonly input: unknown;
             readonly providerOptions?: unknown;
             readonly providerExecuted?: boolean | undefined;
         })[];
@@ -224,9 +268,18 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
         readonly role: "tool";
         readonly content: readonly {
             readonly type: "tool-result";
+            readonly output: unknown;
             readonly toolCallId: string & import("effect/Brand").Brand<"ToolCallId">;
             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 & import("effect/Brand").Brand<"MediaFingerprint">;
+                readonly bytes: number;
+                readonly name?: string;
+                readonly alt?: string;
+            }[];
             readonly providerOptions?: unknown;
             readonly isError?: boolean | undefined;
         }[];
@@ -234,4 +287,12 @@ export declare const runLoop: <Tools extends Record<string, Tool.Any>, R = never
     })[];
     outcome: "ok" | "partial";
     reason: "completed" | "step-cap" | "degenerate-loop";
+    usage: {
+        readonly inputTokens: number;
+        readonly outputTokens: number;
+        readonly totalTokens: number;
+        readonly cacheReadTokens: number;
+        readonly cacheWriteTokens: number;
+        readonly reasoningTokens: number;
+    };
 }, AiError.AiError, LanguageModel.LanguageModel | Exclude<R, import("effect/Tracer").ParentSpan> | Exclude<Tool.HandlersFor<Tools>, import("effect/Tracer").ParentSpan>>;

package/dist/loop.js

@@ -1,9 +1,9 @@
 import { AiError, LanguageModel, Prompt } from "effect/ai";
-import { Cause, Effect, Exit, Match, Metric, Option, Ref, Stream } from "effect";
-import { foldStreamParts, freezeModelRequest } from "@xandreed/core";
+import { Cause, Effect, Exit, Formatter, Match, Metric, Option, Ref, Result, Stream } from "effect";
+import { CurrentTraceContent, foldStreamParts, freezeModelRequest, replayableContext } from "@xandreed/core";
 import { CurrentAgentStep } from "@xandreed/core";
 import { CurrentEmptyResponseTolerance } from "@xandreed/core";
-import { addUsage, zeroUsage } from "@xandreed/core";
+import { addUsage, elideMediaData, isMediaValue, zeroUsage } from "@xandreed/core";
 import { extractModel, extractUsage, handoffToMessage, responseReasoning, responseText, responseToAgentMessages, responseToolCalls, responseToolResults, toPromptMessages, withToolCallIds, withUsageOnAssistant } from "@xandreed/core";
 export const DEFAULT_MAX_STEPS = 100, DEFAULT_TOOL_CONCURRENCY = 4;
 const engineRuns = Metric.counter("engine.runs", {
@@ -13,11 +13,24 @@ const engineRuns = Metric.counter("engine.runs", {
   description: "tool calls by tool name and result",
   incremental: !0
 }), engineCorrections = Metric.counter("engine.corrections", {
-  description: "self-corrections by kind (malformed recovery, degenerate nudge)",
+  description: "self-corrections by kind (malformed recovery, degenerate nudge, stream fallback, image refused and resent)",
   incremental: !0
-}), tagged = (metric, tags) => Metric.withAttributes(metric, tags), malformedReasons = new Set(["InvalidOutputError", "ToolParameterValidationError", "ToolNotFoundError"]), isMalformed = (error) => AiError.isAiError(error) && malformedReasons.has(error.reason._tag), MAX_MALFORMED = 3, REPEAT_NUDGE_AT = 3, REPEAT_BREAK_AT = 5;
+}), tagged = (metric, tags) => Metric.withAttributes(metric, tags), stepUsageAttributes = (usage) => ({
+  "gen_ai.usage.input_tokens": usage.inputTokens,
+  "gen_ai.usage.output_tokens": usage.outputTokens,
+  "gen_ai.usage.cache_read.input_tokens": usage.cacheReadTokens,
+  "gen_ai.usage.cache_creation.input_tokens": usage.cacheWriteTokens,
+  "gen_ai.usage.reasoning.output_tokens": usage.reasoningTokens
+}), runUsageAttributes = (usage) => ({
+  "engine.usage.input_tokens": usage.inputTokens,
+  "engine.usage.output_tokens": usage.outputTokens,
+  "engine.usage.cache_read_tokens": usage.cacheReadTokens,
+  "engine.usage.cache_write_tokens": usage.cacheWriteTokens,
+  "engine.usage.reasoning_tokens": usage.reasoningTokens,
+  "engine.usage.total_tokens": usage.totalTokens
+}), malformedReasons = new Set(["InvalidOutputError", "ToolParameterValidationError", "ToolNotFoundError"]), isMalformed = (error) => AiError.isAiError(error) && malformedReasons.has(error.reason._tag), isImageRejection = (error) => AiError.isAiError(error) && error.reason._tag === "InvalidRequestError" && /image/i.test(error.reason.message), MAX_MALFORMED = 3, REPEAT_NUDGE_AT = 3, REPEAT_BREAK_AT = 5;
 export const DEGENERATE_REPEAT_NUDGE = "You've called the same tool(s) and gotten the same result several times in " + "a row \u2014 you're looping without making progress. STOP repeating that call. " + "Take a DIFFERENT concrete action toward the task; if you're genuinely stuck, say what's blocking you and stop.", DEGENERATE_LOOP_STOP = "[stopped: repeated the same tool call with no progress \u2014 the run was looping]";
-const clip = (s, max) => s.length <= max ? s : `${s.slice(0, max)}\u2026`, progressSignature = (content, pollable) => {
+const clip = (s, max) => s.length <= max ? s : `${s.slice(0, max)}\u2026`, FALLBACK_MESSAGE_CHARS = 300, failureText = (failure) => typeof failure === "string" ? failure : Formatter.format(failure), progressSignature = (content, pollable) => {
   const calls = responseToolCalls(content);
   if (calls.length === 0)
     return "";
@@ -33,86 +46,93 @@ export const foldProgress = (state, sig) => {
     nudge: sig !== "" && stale === REPEAT_NUDGE_AT,
     broke: sig !== "" && stale >= REPEAT_BREAK_AT
   };
-}, nextPhase = (facts) => facts.broke ? "degenerate-loop" : !facts.wantsMore ? "completed" : facts.turnIndex >= facts.maxSteps ? "step-cap" : "continue", runLoop = (options) => Effect.gen(function* () {
+}, nextPhase = (facts) => facts.broke ? "degenerate-loop" : !facts.wantsMore ? "completed" : facts.turnIndex >= facts.maxSteps ? "step-cap" : "continue";
+const tracedJson = (value) => JSON.stringify(value, (_key, field) => isMediaValue(field) ? elideMediaData(field) : typeof field === "object" && field !== null && ("type" in field) && field.type === "file" && ("data" in field) && typeof field.data === "string" ? { ...field, data: `[${field.data.length} base64 characters]` } : field);
+export const runLoop = (options) => Effect.gen(function* () {
   yield* Effect.annotateCurrentSpan({ "engine.input.messages": options.messages.length });
-  const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS, pollable = new Set(options.pollableTools ?? []), eventContext = yield* Effect.context(), onEvent = (event) => Effect.gen(function* () {
-    const parent = yield* Effect.currentSpan.pipe(Effect.orDie);
-    yield* (options.onEvent?.(event) ?? Effect.void).pipe(Effect.withParentSpan(parent), Effect.provide(eventContext));
-  }), toolkit = yield* options.toolkit, step = (state) => Effect.gen(function* () {
+  const maxSteps = options.maxSteps ?? DEFAULT_MAX_STEPS, pollable = new Set(options.pollableTools ?? []), captureTraceContent = options.captureTraceContent ?? (yield* Effect.service(CurrentTraceContent)), eventContext = replayableContext(yield* Effect.context()), onEvent = (event) => (options.onEvent?.(event) ?? Effect.void).pipe(Effect.provide(eventContext)), toolkit = yield* options.toolkit, step = (state) => Effect.gen(function* () {
     yield* onEvent({ type: "turn_start", turnIndex: state.turnIndex });
     const active = options.activeTools === void 0 ? Object.keys(toolkit.tools) : (yield* options.activeTools().pipe(Effect.provide(eventContext))).map(String), selectedTools = Object.fromEntries(active.flatMap((name) => Object.hasOwn(toolkit.tools, name) ? [[name, toolkit.tools[name]]] : [])), toolNames = Object.keys(selectedTools), planned = state.turnIndex === 0 && options.initialStep !== void 0, stepView = { stepIndex: state.turnIndex, activeTools: toolNames, lastUsage: state.lastUsage };
     yield* Effect.annotateCurrentSpan({ "engine.tools.active": toolNames });
-    const prepared = state.turnIndex === 0 && options.initialStep !== void 0 ? Option.none() : options.prepareModel === void 0 ? Option.none() : Option.some(yield* options.prepareModel({ stepIndex: state.turnIndex, messages: state.messages, activeTools: toolNames }).pipe(Effect.provide(eventContext))), baseSystem = Option.match(prepared, { onNone: () => options.system, onSome: (value) => value.system }), instructions = typeof baseSystem === "string" ? Prompt.make([{ role: "system", content: baseSystem }]) : baseSystem, visible = options.render === void 0 ? state.messages : yield* options.render(stepView).pipe(Effect.provide(eventContext)), prompt = freezeModelRequest(Prompt.concat(instructions, Prompt.make(toPromptMessages(visible)))), directive = options.stepDirective === void 0 ? Option.none() : (yield* options.stepDirective(stepView).pipe(Effect.provide(eventContext))).toolChoice;
-    if (options.captureTraceContent === !0)
-      yield* Effect.annotateCurrentSpan({
-        "engine.step.input": JSON.stringify({ messages: prompt.content, activeTools: toolNames })
-      });
-    const toolSequence = yield* Ref.make(0), callOptions = Object.freeze({
-      prompt,
-      toolkit: {
-        tools: selectedTools,
-        handle: (name, params, providerCallId, parseOptions) => Effect.gen(function* () {
-          const sequence = yield* Ref.getAndUpdate(toolSequence, (value) => value + 1), toolCallId = `execution:${state.turnIndex}:${sequence}`;
-          yield* onEvent({ type: "tool_start", turnIndex: state.turnIndex, toolCallId, toolName: String(name), args: params });
-          return (yield* toolkit.handle(name, params, providerCallId, parseOptions)).pipe(Stream.mapEffect((result) => result.isFailure && result.failureOrigin === "parameters" ? Effect.fail(result.result) : Effect.succeed(result)), Stream.tap((result) => result.preliminary ? Effect.void : onEvent({
-            type: "tool_end",
-            turnIndex: state.turnIndex,
-            toolCallId,
-            toolName: String(name),
-            args: params,
-            ok: !result.isFailure,
-            result: result.result,
-            encoded: result.encodedResult
-          })));
-        })
-      },
-      concurrency: options.toolConcurrency ?? DEFAULT_TOOL_CONCURRENCY,
-      ...Option.match(directive, { onNone: () => ({}), onSome: (toolChoice) => ({ toolChoice }) })
-    }), dispatchModel = Option.isSome(prepared) ? prepared.value.model : yield* LanguageModel.LanguageModel, beforeDispatch = options.beforeDispatch === void 0 ? Effect.void : options.beforeDispatch(state.turnIndex, {
-      prompt,
-      tools: Object.values(selectedTools),
-      toolChoice: Option.getOrElse(directive, () => "auto"),
-      model: dispatchModel
-    }).pipe(Effect.provide(eventContext)), generated = planned ? LanguageModel.generateText(callOptions) : beforeDispatch.pipe(Effect.andThen(Effect.suspend(() => dispatchModel.generateText(callOptions)))), settled = (streamingHealthy) => generated.pipe(Effect.map((res) => ({
-      _tag: "ok",
-      content: res.content,
-      finishReason: res.finishReason,
-      usage: res.usage,
-      streamingHealthy
-    }))), streamed = Effect.gen(function* () {
-      yield* beforeDispatch;
-      const partSeen = yield* Ref.make(!1), folded = yield* foldStreamParts(Stream.unwrap(Effect.sync(() => dispatchModel.streamText(callOptions))).pipe(Stream.tap(() => Ref.set(partSeen, !0))), (delta) => onEvent({
-        type: "assistant_delta",
-        turnIndex: state.turnIndex,
-        channel: delta.channel,
-        id: delta.id,
-        delta: delta.delta,
-        ...delta.toolName === void 0 ? {} : { toolName: delta.toolName }
-      })).pipe(Effect.map((turn) => Option.some({
+    const prepared = state.turnIndex === 0 && options.initialStep !== void 0 ? Option.none() : options.prepareModel === void 0 ? Option.none() : Option.some(yield* options.prepareModel({ stepIndex: state.turnIndex, messages: state.messages, activeTools: toolNames }).pipe(Effect.provide(eventContext))), baseSystem = Option.match(prepared, { onNone: () => options.system, onSome: (value) => value.system }), instructions = typeof baseSystem === "string" ? Prompt.make([{ role: "system", content: baseSystem }]) : baseSystem, directive = options.stepDirective === void 0 ? Option.none() : (yield* options.stepDirective(stepView).pipe(Effect.provide(eventContext))).toolChoice, partSeen = yield* Ref.make(!1), attempt = Effect.gen(function* () {
+      const visible = options.render === void 0 ? state.messages : yield* options.render(stepView).pipe(Effect.provide(eventContext)), prompt = freezeModelRequest(Prompt.concat(instructions, Prompt.make(toPromptMessages(visible))));
+      if (captureTraceContent)
+        yield* Effect.annotateCurrentSpan({
+          "engine.step.input": tracedJson({ messages: prompt.content, activeTools: toolNames })
+        });
+      const toolSequence = yield* Ref.make(0), callOptions = Object.freeze({
+        prompt,
+        toolkit: {
+          tools: selectedTools,
+          handle: (name, params, providerCallId, parseOptions) => Effect.gen(function* () {
+            const sequence = yield* Ref.getAndUpdate(toolSequence, (value) => value + 1), toolCallId = `execution:${state.turnIndex}:${sequence}`;
+            yield* onEvent({ type: "tool_start", turnIndex: state.turnIndex, toolCallId, toolName: String(name), args: params });
+            return (yield* toolkit.handle(name, params, providerCallId, parseOptions)).pipe(Stream.mapEffect((result) => result.isFailure && result.failureOrigin === "parameters" ? Effect.fail(result.result) : Effect.succeed(result)), Stream.tap((result) => result.preliminary ? Effect.void : onEvent({
+              type: "tool_end",
+              turnIndex: state.turnIndex,
+              toolCallId,
+              toolName: String(name),
+              args: params,
+              ok: !result.isFailure,
+              result: result.result,
+              encoded: result.encodedResult
+            })));
+          })
+        },
+        concurrency: options.toolConcurrency ?? DEFAULT_TOOL_CONCURRENCY,
+        ...Option.match(directive, { onNone: () => ({}), onSome: (toolChoice) => ({ toolChoice }) })
+      }), dispatchModel = Option.isSome(prepared) ? prepared.value.model : yield* LanguageModel.LanguageModel, beforeDispatch = options.beforeDispatch === void 0 ? Effect.void : options.beforeDispatch(state.turnIndex, {
+        prompt,
+        tools: Object.values(selectedTools),
+        toolChoice: Option.getOrElse(directive, () => "auto"),
+        model: dispatchModel
+      }).pipe(Effect.provide(eventContext)), generated = planned ? LanguageModel.generateText(callOptions) : beforeDispatch.pipe(Effect.andThen(Effect.suspend(() => dispatchModel.generateText(callOptions)))), settled = (streamingHealthy) => generated.pipe(Effect.map((res) => ({
         _tag: "ok",
-        content: turn.content,
-        finishReason: turn.finishReason,
-        usage: turn.usage,
-        streamingHealthy: !0
-      })), Effect.catch((err) => Ref.get(partSeen).pipe(Effect.flatMap((armed) => armed ? Effect.fail(err) : Effect.succeed(Option.none())))), Effect.catchDefect((defect) => Ref.get(partSeen).pipe(Effect.flatMap((armed) => armed ? Effect.die(defect) : Effect.succeed(Option.none())))));
-      return yield* Option.match(folded, {
-        onSome: Effect.succeed,
-        onNone: () => Effect.logWarning("streaming failed before any part arrived \u2014 falling back to generateText for this run").pipe(Effect.andThen(settled(!1)))
-      });
-    }), initial = Effect.gen(function* () {
-      const provider = yield* LanguageModel.make({
-        generateText: () => Effect.succeed([...(options.initialStep ?? []).map((call, index) => ({
-          type: "tool-call",
-          id: `planned:0:${index}`,
-          name: call.name,
-          params: call.params,
-          providerExecuted: !1
-        })), { type: "finish", reason: "tool-calls", usage: { inputTokens: {}, outputTokens: {} } }]),
-        streamText: () => Stream.empty
-      });
-      yield* Effect.annotateCurrentSpan("engine.step.host_planned", !0);
-      return yield* settled(state.streamingHealthy).pipe(Effect.provideService(LanguageModel.LanguageModel, provider));
-    }), useStreaming = options.streaming === !0 && state.streamingHealthy, outcome = yield* (planned ? initial : useStreaming ? streamed : settled(state.streamingHealthy)).pipe(Effect.catch((err) => isMalformed(err) ? Effect.succeed({ _tag: "malformed", err }) : Effect.fail(err)), Effect.provideService(CurrentEmptyResponseTolerance, state.toolCalls > 0));
+        content: res.content,
+        finishReason: res.finishReason,
+        usage: res.usage,
+        streamingHealthy
+      }))), streamed = Effect.gen(function* () {
+        yield* beforeDispatch;
+        const folded = yield* foldStreamParts(Stream.unwrap(Effect.sync(() => dispatchModel.streamText(callOptions))).pipe(Stream.tap(() => Ref.set(partSeen, !0))), (delta) => onEvent({
+          type: "assistant_delta",
+          turnIndex: state.turnIndex,
+          channel: delta.channel,
+          id: delta.id,
+          delta: delta.delta,
+          ...delta.toolName === void 0 ? {} : { toolName: delta.toolName }
+        })).pipe(Effect.map((turn) => Result.succeed({
+          _tag: "ok",
+          content: turn.content,
+          finishReason: turn.finishReason,
+          usage: turn.usage,
+          streamingHealthy: !0
+        })), Effect.catch((err) => Ref.get(partSeen).pipe(Effect.flatMap((armed) => armed || isImageRejection(err) ? Effect.fail(err) : Effect.succeed(Result.fail(failureText(err)))))), Effect.catchDefect((defect) => Ref.get(partSeen).pipe(Effect.flatMap((armed) => armed ? Effect.die(defect) : Effect.succeed(Result.fail(failureText(defect)))))));
+        return yield* Result.match(folded, {
+          onSuccess: Effect.succeed,
+          onFailure: (failure) => Effect.logWarning("streaming failed before any part arrived \u2014 falling back to generateText for this run").pipe(Effect.andThen(onEvent({ type: "stream_fallback", turnIndex: state.turnIndex, message: failure.slice(0, FALLBACK_MESSAGE_CHARS) })), Effect.andThen(Metric.update(tagged(engineCorrections, { "engine.kind": "stream-fallback" }), 1)), Effect.andThen(settled(!1)))
+        });
+      }), initial = Effect.gen(function* () {
+        const provider = yield* LanguageModel.make({
+          generateText: () => Effect.succeed([...(options.initialStep ?? []).map((call, index) => ({
+            type: "tool-call",
+            id: `planned:0:${index}`,
+            name: call.name,
+            params: call.params,
+            providerExecuted: !1
+          })), { type: "finish", reason: "tool-calls", usage: { inputTokens: {}, outputTokens: {} } }]),
+          streamText: () => Stream.empty
+        });
+        yield* Effect.annotateCurrentSpan("engine.step.host_planned", !0);
+        return yield* settled(state.streamingHealthy).pipe(Effect.provideService(LanguageModel.LanguageModel, provider));
+      }), useStreaming = options.streaming === !0 && state.streamingHealthy;
+      return yield* planned ? initial : useStreaming ? streamed : settled(state.streamingHealthy);
+    }), outcome = yield* attempt.pipe(Effect.catch((err) => Effect.gen(function* () {
+      const onMediaRejected = options.onMediaRejected, armed = yield* Ref.get(partSeen);
+      if (planned || armed || onMediaRejected === void 0 || !isImageRejection(err))
+        return yield* Effect.fail(err);
+      return yield* onMediaRejected(clip(err.reason.message, 600)).pipe(Effect.provide(eventContext), Effect.flatMap((retry) => retry ? Effect.logWarning(`the provider refused an image; sending the step again with its images as labels: ${clip(err.reason.message, 300)}`).pipe(Effect.andThen(Metric.update(tagged(engineCorrections, { "engine.kind": "media-rejected" }), 1)), Effect.andThen(attempt)) : Effect.fail(err)));
+    })), Effect.catch((err) => isMalformed(err) ? Effect.succeed({ _tag: "malformed", err }) : Effect.fail(err)), Effect.provideService(CurrentEmptyResponseTolerance, state.toolCalls > 0));
     if (outcome._tag === "malformed") {
       const streak = state.malformedStreak + 1;
       if (streak >= MAX_MALFORMED)
@@ -143,8 +163,8 @@ This usually means you called a tool that doesn't exist or used the wrong argume
     yield* Effect.annotateCurrentSpan({
       "engine.step.finish_reason": outcome.finishReason,
       "engine.step.usage_available": !planned,
-      ...!planned ? { "engine.step.usage": JSON.stringify(usage) } : {},
-      ...options.captureTraceContent === !0 ? { "engine.step.output": JSON.stringify({ content, usage, finishReason: outcome.finishReason }) } : {}
+      ...!planned ? { "engine.step.usage": JSON.stringify(usage), ...stepUsageAttributes(usage) } : {},
+      ...captureTraceContent ? { "engine.step.output": tracedJson({ content, usage, finishReason: outcome.finishReason }) } : {}
     });
     const model = extractModel(content), tail = planned ? responseToAgentMessages(content) : withUsageOnAssistant(responseToAgentMessages(content), usage, model), positions = yield* options.onTail?.(tail) ?? Effect.succeed([]), assistantAt = tail.findIndex((m) => m.role === "assistant"), assistantPosition = assistantAt >= 0 ? Option.fromNullishOr(positions[assistantAt]) : Option.none(), text = responseText(content), toolCalls = responseToolCalls(content);
     yield* onEvent({
@@ -226,7 +246,7 @@ This usually means you called a tool that doesn't exist or used the wrong argume
     toolFailures: 0,
     corrections: 0,
     streamingHealthy: !0
-  }, final = yield* runSteps(initial), { outcome, reason } = Match.value(final.phase).pipe(Match.when("completed", () => ({ outcome: "ok", reason: "completed" })), Match.when("step-cap", () => ({
+  }, final = yield* runSteps(initial).pipe(Effect.provideService(CurrentTraceContent, captureTraceContent)), { outcome, reason } = Match.value(final.phase).pipe(Match.when("completed", () => ({ outcome: "ok", reason: "completed" })), Match.when("step-cap", () => ({
     outcome: "partial",
     reason: "step-cap"
   })), Match.when("degenerate-loop", () => ({
@@ -239,7 +259,7 @@ This usually means you called a tool that doesn't exist or used the wrong argume
     "engine.outcome": outcome,
     "engine.reason": reason,
     "engine.turns": final.turnIndex,
-    "engine.usage.total_tokens": final.usage.totalTokens,
+    ...runUsageAttributes(final.usage),
     "engine.tool_calls": final.toolCalls,
     "engine.tool_calls.failed": final.toolFailures,
     "engine.corrections": final.corrections,
@@ -250,6 +270,7 @@ This usually means you called a tool that doesn't exist or used the wrong argume
     messages: final.messages,
     newTail: final.newTail,
     outcome,
-    reason
+    reason,
+    usage: final.usage
   };
 }).pipe(Effect.withSpan("engine.run"));

package/dist/step-loop.adapter.d.ts

@@ -12,7 +12,12 @@ export declare const STEP_LOOP: {
  * evaluates the host's completion (`completion.evaluated`). A verdict that
  * awaits tasks joins them and is evaluated once more. The plan for a step is
  * computed once and serves the model, the messages and the tool choice; a
- * host-planned first batch runs without a provider call or a plan.
+ * host-planned first batch runs without a provider call or a plan. A stream
+ * that fails before its first part publishes `stream.fallback` once, and the
+ * run goes on without streaming. The run's `captureTraceContent` is
+ * `CurrentTraceContent` for its model calls. A request a provider refuses
+ * over an image goes to `request.onMediaRejected`; when it records an
+ * `OmitMedia`, the step is planned again and sent once more.
  */
 export declare const runSteps: (request: StepRequest) => Effect.Effect<RunResult, HarnessError>;
 export declare const StepLoopLive: Layer.Layer<StepLoop, never, never>;

package/dist/step-loop.adapter.js

@@ -40,6 +40,8 @@ export const runSteps = (request) => Effect.gen(function* () {
           usage: event.usage
         });
       }).pipe(Effect.orDie);
+    if (event.type === "stream_fallback")
+      return request.events.publish({ _tag: "stream.fallback", step: event.turnIndex, message: event.message }).pipe(Effect.orDie);
     if (event.type === "turn_end") {
       const ending = endStep(event.turnIndex, event.status);
       return event.status === "completed" ? ending.pipe(Effect.orDie) : ending.pipe(Effect.catchCause(() => Effect.void));
@@ -53,6 +55,7 @@ export const runSteps = (request) => Effect.gen(function* () {
     toolConcurrency: request.limits.toolConcurrency,
     streaming: request.limits.streaming,
     requireCompletion: request.limits.requireCompletion,
+    captureTraceContent: request.captureTraceContent,
     pollableTools: request.tools.pollable,
     ...Option.match(request.correctives, { onNone: () => ({}), onSome: (correctives) => ({ correctives }) }),
     ...Option.match(request.initial, { onNone: () => ({}), onSome: (batch) => ({ initialStep: batch.calls }) }),
@@ -66,6 +69,7 @@ export const runSteps = (request) => Effect.gen(function* () {
     render: (view) => isPlanned(view.stepIndex) ? Effect.succeed([]) : planFor(view).pipe(Effect.map((plan) => plan.messages), Effect.orDie),
     stepDirective: (view) => isPlanned(view.stepIndex) ? Effect.succeed({ toolChoice: Option.none() }) : planFor(view).pipe(Effect.map((plan) => ({ toolChoice: plan.toolChoice })), Effect.orDie),
     beforeDispatch: (step, actual) => request.dispatch(step, actual).pipe(Effect.orDie),
+    onMediaRejected: (reason) => request.onMediaRejected(reason).pipe(Effect.tap((retry) => retry ? Ref.set(cached, Option.none()) : Effect.void), Effect.orDie),
     isComplete,
     pendingInput: () => request.steering.pipe(Effect.orDie),
     onTail: (messages) => Effect.gen(function* () {
@@ -79,11 +83,12 @@ export const runSteps = (request) => Effect.gen(function* () {
     outcome: result.outcome === "ok" ? "completed" : "partial",
     reason: result.reason,
     text: result.finalText,
-    steps: yield* Ref.get(steps)
+    steps: yield* Ref.get(steps),
+    usage: result.usage
   };
 }), StepLoopLive = Layer.succeed(StepLoop, StepLoop.of({ ...STEP_LOOP, run: runSteps })), stepLoopPlugin = definePlugin({
   id: "@xandreed/plugin-agent-loop/steps",
-  version: "0.13.0",
+  version: "0.14.0",
   scope: "runtime",
   config: Schema.Struct({}),
   defaults: {},

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@xandreed/plugin-agent-loop",
-  "version": "0.13.0",
+  "version": "0.14.0",
   "engines": {
     "node": ">=24",
     "bun": ">=1.3.0"
@@ -14,7 +14,7 @@
     }
   },
   "dependencies": {
-    "@xandreed/core": "0.13.0",
+    "@xandreed/core": "0.14.0",
     "effect": "4.0.7"
   },
   "private": false,