@xandreed/core 0.12.0 → 0.14.0

package/dist/loop/cacheKey.d.ts

@@ -1,6 +1,6 @@
 import { Context, Option } from "effect";
 /**
- * The CURRENT conversation's cache identity, stamped by `runAgent` for the
+ * The CURRENT conversation's cache identity, stamped by the step loop for the
  * duration of a run. Adapters that can key server-side prompt caches on a
  * stable id (OpenAI-compatible `prompt_cache_key`) read it at call time —
  * one conversation, one cache lane, so parallel sessions stop evicting

package/dist/loop/mapping.d.ts

@@ -1,7 +1,7 @@
 import { Option } from "effect";
 import type { ToolCallSummary } from "../domain/loop-event.entity.js";
 import type { AgentMessage } from "../domain/message.entity.js";
-import type { TokenUsage } from "../domain/token-usage.entity.js";
+import { TokenUsage } from "../domain/token-usage.entity.js";
 /**
  * Bridges the persisted `AgentMessage` with `@effect/ai`'s `Prompt`/`Response`
  * encodings. The opaque provider blob is carried verbatim both ways —
@@ -11,7 +11,7 @@ import type { TokenUsage } from "../domain/token-usage.entity.js";
  * by hand and keeps the blob). Everything here is pure: no mutation, no IO.
  */
 /** Wrap a fold summary as the single user message standing in for the folded
- *  history — prepended by `runAgent` when the conversation has a checkpoint. */
+ *  history — prepended when memory replays a conversation from a checkpoint. */
 export declare const handoffToMessage: (summary: string) => AgentMessage;
 /**
  * The largest SAFE fold cut keeping at least `keepTurns` assistant turns
@@ -21,7 +21,7 @@ export declare const handoffToMessage: (summary: string) => AgentMessage;
  * small to fold at all.
  */
 export declare const safeKeepFrom: (messages: ReadonlyArray<AgentMessage>, keepTurns: number) => Option.Option<number>;
-/** `AgentMessage[]` → `@effect/ai` encoded prompt messages (spreadable). */
+/** `AgentMessage[]` → `@effect/ai` encoded prompt messages (spreadable). A text-only user message stays a string. */
 export declare const toPromptMessages: (messages: ReadonlyArray<AgentMessage>) => ReadonlyArray<unknown>;
 /**
  * Some providers (notably Gemini) return tool calls WITHOUT an id. An absent
@@ -58,9 +58,14 @@ export interface ToolResultSummary {
 export declare const responseToolResults: (content: ReadonlyArray<unknown>) => ReadonlyArray<ToolResultSummary>;
 /**
  * Token usage from a response's `usage` + the finish part's. Effect's
- * providers report the FULL input (cache reads and writes included, e.g.
- * Anthropic's `input_tokens` plus both cache counts) with the cache reads
- * beside it; Gemini's raw usage metadata is the last fallback.
+ * providers report the FULL input with the cache reads and writes inside it
+ * (Anthropic's `input_tokens` plus both cache counts; OpenAI's
+ * `input_tokens`, whose `input_tokens_details` give the cached and written
+ * shares) and the full output with the reasoning inside it. Each count is
+ * read from the response's usage, then the finish part's; the result holds
+ * the `TokenUsage` invariants (`tokenUsage`), so an output reported below
+ * its reasoning is raised to it. Gemini's raw usage metadata is the last
+ * fallback: its output is candidates plus thoughts, the thoughts as reasoning.
  */
 export declare const extractUsage: (usage: unknown, content: ReadonlyArray<unknown>) => TokenUsage;
 /**
@@ -72,7 +77,8 @@ export declare const extractUsage: (usage: unknown, content: ReadonlyArray<unkno
 export declare const withUsageOnAssistant: (messages: ReadonlyArray<AgentMessage>, usage: TokenUsage, model?: Option.Option<string>) => ReadonlyArray<AgentMessage>;
 /** The resolved `provider:modelId` the router stamped onto the finish part. */
 export declare const extractModel: (content: ReadonlyArray<unknown>) => Option.Option<string>;
-/** The turn usage embedded on a persisted assistant message, if any. */
+/** The turn usage embedded on a persisted assistant message, if any,
+ *  decoded: a stamp written before 0.14.0 reads 0 cache-write and reasoning tokens. */
 export declare const assistantUsage: (msg: AgentMessage) => Option.Option<TokenUsage>;
 /** The `provider:modelId` embedded alongside the usage stamp, if any. */
 export declare const assistantModel: (msg: AgentMessage) => Option.Option<string>;

package/dist/loop/mapping.js

@@ -1,5 +1,7 @@
-import { Option } from "effect";
+import { Option, Schema } from "effect";
 import { ToolCallId } from "../domain/message.entity.js";
+import { TokenUsage } from "../domain/token-usage.entity.js";
+import { tokenUsage } from "../domain/token-usage.entity.functions.js";
 export const handoffToMessage = (summary) => ({
   role: "user",
   content: `[System note: the earlier history of this conversation has been handed off into the summary below to free up context. Treat the summary as the source of truth for everything before this point.]
@@ -17,10 +19,15 @@ const hasKeys = (o) => typeof o === "object" && o !== null && Object.keys(o).len
     return blob;
   const { [USAGE_KEY]: _engine, ...rest } = blob;
   return rest;
+}, filePart = (media) => ({ type: "file", mediaType: media.mediaType, data: media.data, ...media.name === void 0 ? {} : { fileName: media.name } }), userPromptParts = (parts) => parts.flatMap((part) => part.type === "text" ? part.text.length === 0 ? [] : [{ type: "text", text: part.text, ...withOptions(part.providerOptions) }] : [filePart(part)]), toolModelOutput = (output, media) => {
+  if (media === void 0 || media.length === 0)
+    return {};
+  const text = typeof output === "string" ? output : JSON.stringify(output ?? null);
+  return { modelOutput: [...text.length === 0 ? [] : [{ type: "text", text }], ...media.map(filePart)] };
 };
 export const toPromptMessages = (messages) => messages.map((m) => {
   if (m.role === "user")
-    return { role: "user", content: m.content };
+    return { role: "user", content: typeof m.content === "string" ? m.content : userPromptParts(m.content) };
   if (m.role === "assistant")
     return {
       role: "assistant",
@@ -47,6 +54,7 @@ export const toPromptMessages = (messages) => messages.map((m) => {
       id: p.toolCallId,
       name: p.toolName,
       result: p.output,
+      ...toolModelOutput(p.output, p.media),
       isFailure: p.isError ?? !1,
       providerExecuted: !1,
       ...withOptions(p.providerOptions)
@@ -117,8 +125,22 @@ export const responseToolResults = (content) => content.filter((p) => p.type ===
 }));
 const carriesUsage = (usage) => usage?.inputTokens?.total !== void 0 || usage?.outputTokens?.total !== void 0;
 export const extractUsage = (usage, content) => {
-  const u = usage ?? {}, finishes = content.filter((p) => p.type === "finish"), finish = finishes.find((p) => carriesUsage(p.usage)) ?? finishes[0], gm = finish?.metadata?.google?.usageMetadata, fu = finish?.usage, inputTokens = u.inputTokens?.total ?? fu?.inputTokens?.total ?? gm?.promptTokenCount ?? 0, outputTokens = u.outputTokens?.total ?? fu?.outputTokens?.total ?? gm?.candidatesTokenCount ?? 0, totalTokens = carriesUsage(u) || carriesUsage(fu) ? inputTokens + outputTokens : gm?.totalTokenCount ?? 0, cacheReadTokens = u.inputTokens?.cacheRead ?? fu?.inputTokens?.cacheRead ?? gm?.cachedContentTokenCount ?? 0;
-  return { inputTokens, outputTokens, totalTokens, cacheReadTokens };
+  const u = usage ?? {}, finishes = content.filter((p) => p.type === "finish"), finish = finishes.find((p) => carriesUsage(p.usage)) ?? finishes[0], fu = finish?.usage;
+  if (carriesUsage(u) || carriesUsage(fu))
+    return tokenUsage({
+      inputTokens: u.inputTokens?.total ?? fu?.inputTokens?.total ?? 0,
+      outputTokens: u.outputTokens?.total ?? fu?.outputTokens?.total ?? 0,
+      cacheReadTokens: u.inputTokens?.cacheRead ?? fu?.inputTokens?.cacheRead ?? 0,
+      cacheWriteTokens: u.inputTokens?.cacheWrite ?? fu?.inputTokens?.cacheWrite ?? 0,
+      reasoningTokens: u.outputTokens?.reasoning ?? fu?.outputTokens?.reasoning ?? 0
+    });
+  const gm = finish?.metadata?.google?.usageMetadata, thoughts = gm?.thoughtsTokenCount ?? 0;
+  return tokenUsage({
+    inputTokens: gm?.promptTokenCount ?? 0,
+    outputTokens: (gm?.candidatesTokenCount ?? 0) + thoughts,
+    cacheReadTokens: gm?.cachedContentTokenCount ?? 0,
+    reasoningTokens: thoughts
+  });
 }, withUsageOnAssistant = (messages, usage, model = Option.none()) => {
   const at = messages.findIndex((m) => m.role === "assistant"), stamp = {
     ...usage,
@@ -133,11 +155,13 @@ export const extractUsage = (usage, content) => {
 }, extractModel = (content) => {
   const model = content.find((p) => p.type === "finish")?.metadata?.router?.model;
   return typeof model === "string" && model.length > 0 ? Option.some(model) : Option.none();
-}, assistantUsage = (msg) => {
+};
+const decodeUsage = Schema.decodeUnknownOption(TokenUsage);
+export const assistantUsage = (msg) => {
   if (msg.role !== "assistant")
     return Option.none();
   const usage = msg.providerOptions?.[USAGE_KEY];
-  return hasKeys(usage) ? Option.some(usage) : Option.none();
+  return hasKeys(usage) ? decodeUsage(usage) : Option.none();
 }, assistantModel = (msg) => {
   if (msg.role !== "assistant")
     return Option.none();

package/dist/loop/stepContext.d.ts

@@ -1,3 +1,11 @@
 import { Context, Option } from "effect";
 /** Correlation only; unset for work outside the agent loop. */
 export declare const CurrentAgentStep: Context.Reference<Option.Option<number>>;
+/** The tool call a handler is running for: the ids its `tool.started`, `tool.progress` and `tool.completed` events share. */
+export interface ToolInvocation {
+    readonly invocationId: string;
+    readonly tool: string;
+    readonly step: number;
+}
+/** Set by the tool registry around each handler call; none outside a tool. */
+export declare const CurrentToolInvocation: Context.Reference<Option.Option<ToolInvocation>>;

package/dist/loop/stepContext.js

@@ -1,2 +1,2 @@
 import { Context, Option } from "effect";
-export const CurrentAgentStep = Context.Reference("@xandreed/core/CurrentAgentStep", { defaultValue: () => Option.none() });
+export const CurrentAgentStep = Context.Reference("@xandreed/core/CurrentAgentStep", { defaultValue: () => Option.none() }), CurrentToolInvocation = Context.Reference("@xandreed/core/CurrentToolInvocation", { defaultValue: () => Option.none() });

package/dist/loop/traceContent.d.ts

@@ -0,0 +1,29 @@
+import { Context } from "effect";
+/**
+ * Whether spans may carry prompt and response content: the step loop's
+ * `engine.step.input` and `engine.step.output`, the models plugin's
+ * `llm.reasoning`. Off by default. Read per call, never when a layer is
+ * built: the step loop provides it for each run from
+ * `StepRequest.captureTraceContent` (the policy's `captureTraceContent`,
+ * else the agent's, else this reference where the run starts). Hosts own
+ * consent, masking and exporter retention.
+ *
+ * A context reference, like `CurrentPromptCacheKey`: ambient call metadata
+ * that flows through the loop's fibers without threading a parameter.
+ */
+export declare const CurrentTraceContent: Context.Reference<boolean>;
+/**
+ * A context captured to be provided again later (the services a layer was
+ * built with, the services where a turn's tools were opened), without the
+ * trace state of the place it was captured, so the work it runs is traced
+ * where that work runs:
+ * - the parent span (`Tracer.ParentSpan`): spans nest under the span current
+ *   where the work runs, not under the span current at capture;
+ * - the span annotations and links (`Effect.annotateSpans`,
+ *   `Effect.linkSpans`): providing the captured ones would replace those of
+ *   where the work runs, the turn's ids among them;
+ * - `CurrentTraceContent`, which is read per call.
+ * The work then runs with the values of the fiber it runs in. Removing
+ * these keys removes nothing the context's type names.
+ */
+export declare const replayableContext: <S>(context: Context.Context<S>) => Context.Context<S>;

package/dist/loop/traceContent.js

@@ -0,0 +1,4 @@
+import { Context, References, Tracer } from "effect";
+export const CurrentTraceContent = Context.Reference("@xandreed/core/CurrentTraceContent", {
+  defaultValue: () => !1
+}), replayableContext = (context) => Context.omit(Tracer.ParentSpan, References.TracerSpanAnnotations, References.TracerSpanLinks, CurrentTraceContent)(context);

package/dist/loop/traceContent.test.d.ts

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

package/dist/memory/memory-log.entity.d.ts

@@ -1,4 +1,5 @@
 import { Schema } from "effect";
+import { UserMessage } from "../turn/user-message.entity.js";
 /**
  * The conversation memory log — the single source every model request is
  * rebuilt from ("model-visible ⟺ logged"). Entries are appended, never edited:
@@ -16,7 +17,12 @@ export declare const Subject: Schema.Struct<{
     readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
 }>;
 export type Subject = typeof Subject.Type;
-/** A file or image a tool result carries, kept by reference (never inlined in the log). */
+/**
+ * A file or image a tool result points to by URL: the log keeps the
+ * reference, never the content, and every render shows it as a reference
+ * line, whatever the media mode. An image the model is to see is a `Media`
+ * value, stored inline.
+ */
 export declare const ArtifactRef: Schema.Struct<{
     readonly id: Schema.Trimmed;
     readonly kind: Schema.Literals<readonly ["image", "file"]>;
@@ -37,6 +43,9 @@ export declare const CompactionAction: Schema.Union<readonly [Schema.TaggedStruc
 }>, Schema.TaggedStruct<"Summarize", {
     readonly keepFromTurn: Schema.Int;
     readonly summary: Schema.String;
+}>, Schema.TaggedStruct<"OmitMedia", {
+    readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+    readonly reason: Schema.String;
 }>]>;
 export type CompactionAction = typeof CompactionAction.Type;
 export declare const ActivationSource: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
@@ -49,18 +58,40 @@ export declare const LogBody: Schema.Union<readonly [Schema.TaggedStruct<"System
         readonly version: Schema.String;
         readonly fingerprint: Schema.String;
     }>>;
-}>, Schema.encodeKeys<Schema.TaggedStruct<"TurnStarted", {
-    readonly userMessage: Schema.decodeTo<typeof import("@xandreed/sdk").UserMessage, Schema.String, never, never>;
-}>, {
-    readonly userMessage: "prompt";
-}>, Schema.TaggedStruct<"TurnContext", {
+}>, Schema.decodeTo<Schema.TaggedStruct<"TurnStarted", {
+    readonly userMessage: typeof UserMessage;
+}>, Schema.Struct<{
+    readonly _tag: Schema.Literal<"TurnStarted">;
+    readonly prompt: Schema.String;
+    readonly attachments: Schema.optionalKey<Schema.$Array<Schema.toEncoded<Schema.Struct<{
+        readonly type: Schema.Literal<"media">;
+        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+        readonly data: Schema.String;
+        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+        readonly bytes: Schema.Int;
+        readonly name: Schema.optionalKey<Schema.String>;
+        readonly alt: Schema.optionalKey<Schema.String>;
+    }>>>>;
+}>, never, never>, Schema.TaggedStruct<"TurnContext", {
     readonly sectionId: Schema.String;
     readonly version: Schema.String;
     readonly text: Schema.String;
 }>, Schema.TaggedStruct<"Message", {
     readonly message: Schema.Union<readonly [Schema.Struct<{
         readonly role: Schema.Literal<"user">;
-        readonly content: Schema.String;
+        readonly content: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"text">;
+            readonly text: Schema.String;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"media">;
+            readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+            readonly data: Schema.String;
+            readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+            readonly bytes: Schema.Int;
+            readonly name: Schema.optionalKey<Schema.String>;
+            readonly alt: Schema.optionalKey<Schema.String>;
+        }>]>>]>;
         readonly providerOptions: Schema.optional<Schema.Unknown>;
     }>, Schema.Struct<{
         readonly role: Schema.Literal<"assistant">;
@@ -90,6 +121,15 @@ export declare const LogBody: Schema.Union<readonly [Schema.TaggedStruct<"System
             readonly output: Schema.Unknown;
             readonly providerOptions: Schema.optional<Schema.Unknown>;
             readonly isError: Schema.optional<Schema.Boolean>;
+            readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly type: Schema.Literal<"media">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly data: Schema.String;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly bytes: Schema.Int;
+                readonly name: Schema.optionalKey<Schema.String>;
+                readonly alt: Schema.optionalKey<Schema.String>;
+            }>>>;
         }>>;
         readonly providerOptions: Schema.optional<Schema.Unknown>;
     }>]>;
@@ -117,6 +157,26 @@ export declare const LogBody: Schema.Union<readonly [Schema.TaggedStruct<"System
     }>>;
     /** Pinned results survive every compaction verbatim. */
     readonly pinned: Schema.Boolean;
+    /**
+     * The images the model is sent with the result, where they are in
+     * `encoded` (each stored once, there), checked when the result was
+     * written; only when there are some, so a result without images is
+     * stored as before.
+     */
+    readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+        readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+        readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+        readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+        readonly bytes: Schema.Int;
+    }>>>;
+    /**
+     * The lines `view` ends with for the images the result does not send (an
+     * `[image unavailable: …]` line, or the label line of one past the
+     * per-result caps); only when there are some. A result shown through
+     * other text (a compaction's, a digest's, a spill's preview) shows them
+     * after that text.
+     */
+    readonly mediaNotes: Schema.optionalKey<Schema.$Array<Schema.String>>;
 }>, Schema.TaggedStruct<"ToolDigest", {
     readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
     readonly version: Schema.String;
@@ -148,6 +208,9 @@ export declare const LogBody: Schema.Union<readonly [Schema.TaggedStruct<"System
     }>, Schema.TaggedStruct<"Summarize", {
         readonly keepFromTurn: Schema.Int;
         readonly summary: Schema.String;
+    }>, Schema.TaggedStruct<"OmitMedia", {
+        readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+        readonly reason: Schema.String;
     }>]>;
 }>, Schema.TaggedStruct<"TurnEnded", {
     readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
@@ -168,18 +231,40 @@ export declare const LogEntry: Schema.Struct<{
             readonly version: Schema.String;
             readonly fingerprint: Schema.String;
         }>>;
-    }>, Schema.encodeKeys<Schema.TaggedStruct<"TurnStarted", {
-        readonly userMessage: Schema.decodeTo<typeof import("@xandreed/sdk").UserMessage, Schema.String, never, never>;
-    }>, {
-        readonly userMessage: "prompt";
-    }>, Schema.TaggedStruct<"TurnContext", {
+    }>, Schema.decodeTo<Schema.TaggedStruct<"TurnStarted", {
+        readonly userMessage: typeof UserMessage;
+    }>, Schema.Struct<{
+        readonly _tag: Schema.Literal<"TurnStarted">;
+        readonly prompt: Schema.String;
+        readonly attachments: Schema.optionalKey<Schema.$Array<Schema.toEncoded<Schema.Struct<{
+            readonly type: Schema.Literal<"media">;
+            readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+            readonly data: Schema.String;
+            readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+            readonly bytes: Schema.Int;
+            readonly name: Schema.optionalKey<Schema.String>;
+            readonly alt: Schema.optionalKey<Schema.String>;
+        }>>>>;
+    }>, never, never>, Schema.TaggedStruct<"TurnContext", {
         readonly sectionId: Schema.String;
         readonly version: Schema.String;
         readonly text: Schema.String;
     }>, Schema.TaggedStruct<"Message", {
         readonly message: Schema.Union<readonly [Schema.Struct<{
             readonly role: Schema.Literal<"user">;
-            readonly content: Schema.String;
+            readonly content: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+                readonly type: Schema.Literal<"text">;
+                readonly text: Schema.String;
+                readonly providerOptions: Schema.optional<Schema.Unknown>;
+            }>, Schema.Struct<{
+                readonly type: Schema.Literal<"media">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly data: Schema.String;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly bytes: Schema.Int;
+                readonly name: Schema.optionalKey<Schema.String>;
+                readonly alt: Schema.optionalKey<Schema.String>;
+            }>]>>]>;
             readonly providerOptions: Schema.optional<Schema.Unknown>;
         }>, Schema.Struct<{
             readonly role: Schema.Literal<"assistant">;
@@ -209,6 +294,15 @@ export declare const LogEntry: Schema.Struct<{
                 readonly output: Schema.Unknown;
                 readonly providerOptions: Schema.optional<Schema.Unknown>;
                 readonly isError: Schema.optional<Schema.Boolean>;
+                readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                    readonly type: Schema.Literal<"media">;
+                    readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                    readonly data: Schema.String;
+                    readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                    readonly bytes: Schema.Int;
+                    readonly name: Schema.optionalKey<Schema.String>;
+                    readonly alt: Schema.optionalKey<Schema.String>;
+                }>>>;
             }>>;
             readonly providerOptions: Schema.optional<Schema.Unknown>;
         }>]>;
@@ -236,6 +330,26 @@ export declare const LogEntry: Schema.Struct<{
         }>>;
         /** Pinned results survive every compaction verbatim. */
         readonly pinned: Schema.Boolean;
+        /**
+         * The images the model is sent with the result, where they are in
+         * `encoded` (each stored once, there), checked when the result was
+         * written; only when there are some, so a result without images is
+         * stored as before.
+         */
+        readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+            readonly path: Schema.$Array<Schema.Union<readonly [Schema.String, Schema.Int]>>;
+            readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+            readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+            readonly bytes: Schema.Int;
+        }>>>;
+        /**
+         * The lines `view` ends with for the images the result does not send (an
+         * `[image unavailable: …]` line, or the label line of one past the
+         * per-result caps); only when there are some. A result shown through
+         * other text (a compaction's, a digest's, a spill's preview) shows them
+         * after that text.
+         */
+        readonly mediaNotes: Schema.optionalKey<Schema.$Array<Schema.String>>;
     }>, Schema.TaggedStruct<"ToolDigest", {
         readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
         readonly version: Schema.String;
@@ -267,6 +381,9 @@ export declare const LogEntry: Schema.Struct<{
         }>, Schema.TaggedStruct<"Summarize", {
             readonly keepFromTurn: Schema.Int;
             readonly summary: Schema.String;
+        }>, Schema.TaggedStruct<"OmitMedia", {
+            readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+            readonly reason: Schema.String;
         }>]>;
     }>, Schema.TaggedStruct<"TurnEnded", {
         readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
@@ -278,7 +395,19 @@ export type LogEntry = typeof LogEntry.Type;
 export declare const BuiltContext: Schema.Struct<{
     readonly messages: Schema.$Array<Schema.Union<readonly [Schema.Struct<{
         readonly role: Schema.Literal<"user">;
-        readonly content: Schema.String;
+        readonly content: Schema.Union<readonly [Schema.String, Schema.$Array<Schema.Union<readonly [Schema.Struct<{
+            readonly type: Schema.Literal<"text">;
+            readonly text: Schema.String;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"media">;
+            readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+            readonly data: Schema.String;
+            readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+            readonly bytes: Schema.Int;
+            readonly name: Schema.optionalKey<Schema.String>;
+            readonly alt: Schema.optionalKey<Schema.String>;
+        }>]>>]>;
         readonly providerOptions: Schema.optional<Schema.Unknown>;
     }>, Schema.Struct<{
         readonly role: Schema.Literal<"assistant">;
@@ -308,6 +437,15 @@ export declare const BuiltContext: Schema.Struct<{
             readonly output: Schema.Unknown;
             readonly providerOptions: Schema.optional<Schema.Unknown>;
             readonly isError: Schema.optional<Schema.Boolean>;
+            readonly media: Schema.optionalKey<Schema.$Array<Schema.Struct<{
+                readonly type: Schema.Literal<"media">;
+                readonly mediaType: Schema.Literals<readonly ["image/png", "image/jpeg", "image/gif", "image/webp"]>;
+                readonly data: Schema.String;
+                readonly fingerprint: Schema.brand<Schema.String, "MediaFingerprint">;
+                readonly bytes: Schema.Int;
+                readonly name: Schema.optionalKey<Schema.String>;
+                readonly alt: Schema.optionalKey<Schema.String>;
+            }>>>;
         }>>;
         readonly providerOptions: Schema.optional<Schema.Unknown>;
     }>]>>;

package/dist/memory/memory-log.entity.functions.d.ts

@@ -7,6 +7,10 @@ export declare const canonicalJson: (value: unknown) => string;
 export declare const fingerprintOf: (text: string) => string;
 /** A deliberately conservative estimate for mixed prose and JSON. */
 export declare const estimateTokens: (text: string) => number;
+/**
+ * The messages' tokens, estimated: each message's JSON as text, with an
+ * image counted as `IMAGE_TOKEN_ESTIMATE` tokens instead of its base64.
+ */
 export declare const estimateMessageTokens: (messages: ReadonlyArray<AgentMessage>) => number;
 export declare const entryId: (runId: string, index: number) => EntryId;
 export interface RenderOptions {
@@ -23,18 +27,40 @@ export interface RenderOptions {
     /** Show recorded tool digests in place of the results they digest. */
     readonly digests: boolean;
     /**
-     * How artifacts reach the model. `none`: a reference line after the
-     * result's text. `inline` is reserved for image parts; messages carry text
-     * only today, so it renders like `none`.
+     * How images reach the model: a user's attachments and the images tool
+     * results return (each result's slots, while it shows the view it was
+     * written with). The current turn's are sent as images first: its
+     * attachments in order, then its tool results' images, newest result
+     * first and a whole result at a time, while they fit. `none` shows every
+     * earlier turn's image as a `mediaLabel` line; `inline` sends earlier
+     * turns' images too, newest turn first and a whole turn at a time, while
+     * they fit. Together they stay within `maxImages` images (and never more
+     * than `MEDIA_LIMITS.requestImages`) and `maxChars` base64 characters; an
+     * image left out is a label line. With the memory plugins' defaults a
+     * message's own images always fit; `maxChars: 0` sends none (text only).
+     * An `ArtifactRef` is a reference line after its result's text in both
+     * modes, at most `maxImages` of them.
      */
     readonly media: {
         readonly mode: "none" | "inline";
         readonly maxImages: number;
+        readonly maxChars: number;
     };
 }
 /** The reference lines a result's artifacts add to its text. */
 export declare const artifactLines: (artifacts: ReadonlyArray<ArtifactRef>, maxImages: number) => string;
 export declare const renderLog: (entries: ReadonlyArray<LogEntry>, options: RenderOptions) => ReadonlyArray<AgentMessage>;
+/**
+ * The entries whose images a render sends as images (a user's attachments,
+ * a tool result's): what an `OmitMedia` compaction names after a provider
+ * refused that request. Empty when the render sends no image.
+ */
+export declare const entriesSendingMedia: (entries: ReadonlyArray<LogEntry>, options: RenderOptions) => ReadonlyArray<EntryId>;
+/**
+ * The rebuild of one request, with its fingerprint: the hash of the
+ * messages' canonical JSON, each image's `data` replaced by its fingerprint
+ * (`elideMediaData`), so a text-only context hashes as it always did.
+ */
 export declare const buildContext: (entries: ReadonlyArray<LogEntry>, options: RenderOptions) => BuiltContext;
 /** The latest step context recorded by this run, if any. */
 export declare const stepContextOf: (entries: ReadonlyArray<LogEntry>, runId: string) => Option.Option<string>;
@@ -47,9 +73,13 @@ export declare const activationsOf: (entries: ReadonlyArray<LogEntry>) => {
     readonly skills: ReadonlyArray<string>;
     readonly tools: ReadonlyArray<string>;
 };
-/** A compact user/assistant transcript for classifiers: user messages and replies only. */
+/** A compact user/assistant transcript for classifiers: user messages (an image as its label line) and replies only. */
 export declare const referenceTranscript: (entries: ReadonlyArray<LogEntry>) => ReadonlyArray<AgentMessage>;
-/** The full-fidelity transcript: messages with every tool result's encoded value. */
+/**
+ * The full-fidelity transcript: messages with every tool result's encoded
+ * value. Images are left out: a user's image is its label line, an image in
+ * an encoded value has its `data` replaced by its fingerprint.
+ */
 export declare const rawTranscript: (entries: ReadonlyArray<LogEntry>) => ReadonlyArray<AgentMessage>;
 export interface LogQuery {
     readonly kinds: ReadonlyArray<LogBody["_tag"]>;