@xandreed/core 0.4.0 → 0.11.0

package/dist/mcp/bridge.js

@@ -1,18 +1,18 @@
-import { Tool, Toolkit } from "@effect/ai";
+import { Tool, Toolkit } from "effect/ai";
 import { Context, Effect, Option, Schema } from "effect";
 import { Failure } from "../domain/failure.entity.js";
 import { McpClient } from "../ports/mcp-client.port.js";
-const OUTPUT_CAP_CHARS = 16000, McpArgs = Schema.Record({ key: Schema.String, value: Schema.Unknown }), clipResult = (value) => {
+const OUTPUT_CAP_CHARS = 16000, McpArgs = Schema.Record(Schema.String, Schema.Unknown), clipResult = (value) => {
   const text = typeof value === "string" ? value : JSON.stringify(value) ?? "";
   return text.length <= OUTPUT_CAP_CHARS ? value : `${text.slice(0, OUTPUT_CAP_CHARS)}
 [\u2026clipped ${text.length - OUTPUT_CAP_CHARS} chars\u2026]`;
 };
 export const McpDescribe = Tool.make("mcp_describe", {
   description: "Reveal ONE external MCP tool's parameters. Pass the server + tool exactly as listed under 'External MCP tools'. Returns {server, tool, description, inputSchema} \u2014 the JSON Schema of the arguments mcp_call expects. Call this BEFORE mcp_call the first time you use a tool.",
-  parameters: {
-    server: Schema.String.annotations({ description: "The server name, as listed." }),
-    tool: Schema.String.annotations({ description: "The tool name, as listed." })
-  },
+  parameters: Schema.Struct({
+    server: Schema.String.annotate({ description: "The server name, as listed." }),
+    tool: Schema.String.annotate({ description: "The tool name, as listed." })
+  }),
   success: Schema.Struct({
     server: Schema.String,
     tool: Schema.String,
@@ -23,13 +23,13 @@ export const McpDescribe = Tool.make("mcp_describe", {
   failureMode: "return"
 }), McpCall = Tool.make("mcp_call", {
   description: "Invoke an external MCP tool. Pass server + tool (as listed) and args as a JSON object matching the schema mcp_describe returned. A tool-level failure comes back as data (read it and adapt), not a dead turn. Returns the tool's result (clipped past 16k chars).",
-  parameters: {
-    server: Schema.String.annotations({ description: "The server name, as listed." }),
-    tool: Schema.String.annotations({ description: "The tool name, as listed." }),
-    args: McpArgs.annotations({
+  parameters: Schema.Struct({
+    server: Schema.String.annotate({ description: "The server name, as listed." }),
+    tool: Schema.String.annotate({ description: "The tool name, as listed." }),
+    args: McpArgs.annotate({
       description: "The tool's arguments as a JSON object (see mcp_describe); {} if it takes none."
     })
-  },
+  }),
   success: Schema.Unknown,
   failure: Failure,
   failureMode: "return"
@@ -41,7 +41,7 @@ export const McpDescribe = Tool.make("mcp_describe", {
   const client = yield* McpClient, descriptors = yield* client.listTools;
   if (descriptors.length === 0)
     return emptyMcpBridge;
-  const find = (server, tool) => Option.fromNullable(descriptors.find((d) => d.server === server && d.name === tool)), tools = [McpDescribe, McpCall], toolkit = Toolkit.make(...tools), handlerRecord = {
+  const find = (server, tool) => Option.fromNullishOr(descriptors.find((d) => d.server === server && d.name === tool)), tools = [McpDescribe, McpCall], toolkit = Toolkit.make(...tools), handlerRecord = {
     mcp_describe: (params) => Option.match(find(params.server, params.tool), {
       onNone: () => Effect.fail({
         error: "UnknownMcpTool",
@@ -61,10 +61,10 @@ export const McpDescribe = Tool.make("mcp_describe", {
       error: "McpToolError",
       message: typeof outcome.result === "string" ? outcome.result.slice(0, 2000) : JSON.stringify(outcome.result).slice(0, 2000)
     }) : Effect.succeed(clipResult(outcome.result))), Effect.catchTag("McpError", (error) => Effect.fail({ error: "McpTransportError", message: error.message })))
-  }, handlers = yield* toolkit.toContext(handlerRecord);
+  }, handlers = yield* toolkit.toHandlers(handlerRecord);
   return {
     toolkit,
     handlers,
     descriptors
   };
-}).pipe(Effect.catchAllCause((cause) => Effect.logWarning(`MCP bridge unavailable \u2014 continuing without MCP tools: ${cause}`).pipe(Effect.as(emptyMcpBridge))));
+}).pipe(Effect.catchCause((cause) => Effect.logWarning(`MCP bridge unavailable \u2014 continuing without MCP tools: ${cause}`).pipe(Effect.as(emptyMcpBridge))));

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

@@ -0,0 +1,320 @@
+import { Schema } from "effect";
+/**
+ * The conversation memory log — the single source every model request is
+ * rebuilt from ("model-visible ⟺ logged"). Entries are appended, never edited:
+ * a compaction is itself an entry that carries the replacement bytes, so a
+ * replay reproduces exactly what the model saw.
+ */
+/** `<runId>:<index within the run>` — assigned by memory, independent of any journal. */
+export declare const EntryId: Schema.brand<Schema.Trimmed, "EntryId">;
+export type EntryId = typeof EntryId.Type;
+/** Something a tool result discovered, e.g. a record the next turn may cite. */
+export declare const Subject: Schema.Struct<{
+    readonly kind: Schema.Trimmed;
+    readonly id: Schema.Trimmed;
+    readonly label: Schema.OptionFromNullOr<Schema.String>;
+    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). */
+export declare const ArtifactRef: Schema.Struct<{
+    readonly id: Schema.Trimmed;
+    readonly kind: Schema.Literals<readonly ["image", "file"]>;
+    readonly mediaType: Schema.Trimmed;
+    readonly url: Schema.String;
+    readonly alt: Schema.OptionFromNullOr<Schema.String>;
+}>;
+export type ArtifactRef = typeof ArtifactRef.Type;
+export declare const CompactionAction: Schema.Union<readonly [Schema.TaggedStruct<"CompactViews", {
+    readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+    readonly texts: Schema.$Array<Schema.String>;
+}>, Schema.TaggedStruct<"Spill", {
+    readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+    readonly preview: Schema.String;
+}>, Schema.TaggedStruct<"DropTurns", {
+    readonly throughTurn: Schema.Int;
+    readonly ledger: Schema.String;
+}>, Schema.TaggedStruct<"Summarize", {
+    readonly keepFromTurn: Schema.Int;
+    readonly summary: Schema.String;
+}>]>;
+export type CompactionAction = typeof CompactionAction.Type;
+export declare const ActivationSource: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+export type ActivationSource = typeof ActivationSource.Type;
+export declare const LogBody: Schema.Union<readonly [Schema.TaggedStruct<"SystemPrepared", {
+    readonly fingerprint: Schema.String;
+    readonly text: Schema.String;
+    readonly sections: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.String;
+        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", {
+    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 providerOptions: Schema.optional<Schema.Unknown>;
+    }>, Schema.Struct<{
+        readonly role: Schema.Literal<"assistant">;
+        readonly content: 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<"reasoning">;
+            readonly text: Schema.String;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"tool-call">;
+            readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+            readonly toolName: Schema.String;
+            readonly input: Schema.Unknown;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+            readonly providerExecuted: Schema.optional<Schema.Boolean>;
+        }>]>>;
+        readonly providerOptions: Schema.optional<Schema.Unknown>;
+    }>, Schema.Struct<{
+        readonly role: Schema.Literal<"tool">;
+        readonly content: Schema.$Array<Schema.Struct<{
+            readonly type: Schema.Literal<"tool-result">;
+            readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+            readonly toolName: Schema.String;
+            readonly output: Schema.Unknown;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+            readonly isError: Schema.optional<Schema.Boolean>;
+        }>>;
+        readonly providerOptions: Schema.optional<Schema.Unknown>;
+    }>]>;
+}>, Schema.TaggedStruct<"ToolResult", {
+    readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+    readonly toolName: Schema.String;
+    readonly isError: Schema.Boolean;
+    /** Full fidelity: the tool's encoded result. */
+    readonly encoded: Schema.Unknown;
+    /** The exact text the model saw when the result was written. */
+    readonly view: Schema.String;
+    readonly viewVersion: Schema.String;
+    readonly subjects: Schema.$Array<Schema.Struct<{
+        readonly kind: Schema.Trimmed;
+        readonly id: Schema.Trimmed;
+        readonly label: Schema.OptionFromNullOr<Schema.String>;
+        readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
+    }>>;
+    readonly artifacts: Schema.$Array<Schema.Struct<{
+        readonly id: Schema.Trimmed;
+        readonly kind: Schema.Literals<readonly ["image", "file"]>;
+        readonly mediaType: Schema.Trimmed;
+        readonly url: Schema.String;
+        readonly alt: Schema.OptionFromNullOr<Schema.String>;
+    }>>;
+    /** Pinned results survive every compaction verbatim. */
+    readonly pinned: Schema.Boolean;
+}>, Schema.TaggedStruct<"ToolDigest", {
+    readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+    readonly version: Schema.String;
+    readonly mode: Schema.Literals<readonly ["select", "summarize"]>;
+    readonly keep: Schema.$Array<Schema.String>;
+    readonly text: Schema.String;
+    readonly digester: Schema.String;
+    readonly trigger: Schema.Literals<readonly ["write", "compaction"]>;
+}>, Schema.TaggedStruct<"StepContext", {
+    readonly step: Schema.Int;
+    readonly text: Schema.String;
+}>, Schema.TaggedStruct<"ToolsActivated", {
+    readonly skills: Schema.$Array<Schema.String>;
+    readonly tools: Schema.$Array<Schema.String>;
+    readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+    readonly decision: Schema.OptionFromNullOr<Schema.brand<Schema.Trimmed, "DecisionId">>;
+}>, Schema.TaggedStruct<"Compaction", {
+    readonly strategy: Schema.String;
+    readonly version: Schema.String;
+    readonly action: Schema.Union<readonly [Schema.TaggedStruct<"CompactViews", {
+        readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+        readonly texts: Schema.$Array<Schema.String>;
+    }>, Schema.TaggedStruct<"Spill", {
+        readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+        readonly preview: Schema.String;
+    }>, Schema.TaggedStruct<"DropTurns", {
+        readonly throughTurn: Schema.Int;
+        readonly ledger: Schema.String;
+    }>, Schema.TaggedStruct<"Summarize", {
+        readonly keepFromTurn: Schema.Int;
+        readonly summary: Schema.String;
+    }>]>;
+}>, Schema.TaggedStruct<"TurnEnded", {
+    readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
+    readonly reply: Schema.OptionFromNullOr<Schema.String>;
+}>]>;
+export type LogBody = typeof LogBody.Type;
+export declare const LogEntry: Schema.Struct<{
+    readonly id: Schema.brand<Schema.Trimmed, "EntryId">;
+    readonly runId: Schema.String;
+    readonly turn: Schema.Int;
+    readonly step: Schema.Int;
+    readonly at: Schema.Number;
+    readonly body: Schema.Union<readonly [Schema.TaggedStruct<"SystemPrepared", {
+        readonly fingerprint: Schema.String;
+        readonly text: Schema.String;
+        readonly sections: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.String;
+            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", {
+        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 providerOptions: Schema.optional<Schema.Unknown>;
+        }>, Schema.Struct<{
+            readonly role: Schema.Literal<"assistant">;
+            readonly content: 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<"reasoning">;
+                readonly text: Schema.String;
+                readonly providerOptions: Schema.optional<Schema.Unknown>;
+            }>, Schema.Struct<{
+                readonly type: Schema.Literal<"tool-call">;
+                readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                readonly toolName: Schema.String;
+                readonly input: Schema.Unknown;
+                readonly providerOptions: Schema.optional<Schema.Unknown>;
+                readonly providerExecuted: Schema.optional<Schema.Boolean>;
+            }>]>>;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+        }>, Schema.Struct<{
+            readonly role: Schema.Literal<"tool">;
+            readonly content: Schema.$Array<Schema.Struct<{
+                readonly type: Schema.Literal<"tool-result">;
+                readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+                readonly toolName: Schema.String;
+                readonly output: Schema.Unknown;
+                readonly providerOptions: Schema.optional<Schema.Unknown>;
+                readonly isError: Schema.optional<Schema.Boolean>;
+            }>>;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+        }>]>;
+    }>, Schema.TaggedStruct<"ToolResult", {
+        readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+        readonly toolName: Schema.String;
+        readonly isError: Schema.Boolean;
+        /** Full fidelity: the tool's encoded result. */
+        readonly encoded: Schema.Unknown;
+        /** The exact text the model saw when the result was written. */
+        readonly view: Schema.String;
+        readonly viewVersion: Schema.String;
+        readonly subjects: Schema.$Array<Schema.Struct<{
+            readonly kind: Schema.Trimmed;
+            readonly id: Schema.Trimmed;
+            readonly label: Schema.OptionFromNullOr<Schema.String>;
+            readonly data: Schema.OptionFromNullOr<Schema.Unknown>;
+        }>>;
+        readonly artifacts: Schema.$Array<Schema.Struct<{
+            readonly id: Schema.Trimmed;
+            readonly kind: Schema.Literals<readonly ["image", "file"]>;
+            readonly mediaType: Schema.Trimmed;
+            readonly url: Schema.String;
+            readonly alt: Schema.OptionFromNullOr<Schema.String>;
+        }>>;
+        /** Pinned results survive every compaction verbatim. */
+        readonly pinned: Schema.Boolean;
+    }>, Schema.TaggedStruct<"ToolDigest", {
+        readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+        readonly version: Schema.String;
+        readonly mode: Schema.Literals<readonly ["select", "summarize"]>;
+        readonly keep: Schema.$Array<Schema.String>;
+        readonly text: Schema.String;
+        readonly digester: Schema.String;
+        readonly trigger: Schema.Literals<readonly ["write", "compaction"]>;
+    }>, Schema.TaggedStruct<"StepContext", {
+        readonly step: Schema.Int;
+        readonly text: Schema.String;
+    }>, Schema.TaggedStruct<"ToolsActivated", {
+        readonly skills: Schema.$Array<Schema.String>;
+        readonly tools: Schema.$Array<Schema.String>;
+        readonly source: Schema.Literals<readonly ["always", "matcher", "load_skill", "host"]>;
+        readonly decision: Schema.OptionFromNullOr<Schema.brand<Schema.Trimmed, "DecisionId">>;
+    }>, Schema.TaggedStruct<"Compaction", {
+        readonly strategy: Schema.String;
+        readonly version: Schema.String;
+        readonly action: Schema.Union<readonly [Schema.TaggedStruct<"CompactViews", {
+            readonly entries: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+            readonly texts: Schema.$Array<Schema.String>;
+        }>, Schema.TaggedStruct<"Spill", {
+            readonly entry: Schema.brand<Schema.Trimmed, "EntryId">;
+            readonly preview: Schema.String;
+        }>, Schema.TaggedStruct<"DropTurns", {
+            readonly throughTurn: Schema.Int;
+            readonly ledger: Schema.String;
+        }>, Schema.TaggedStruct<"Summarize", {
+            readonly keepFromTurn: Schema.Int;
+            readonly summary: Schema.String;
+        }>]>;
+    }>, Schema.TaggedStruct<"TurnEnded", {
+        readonly outcome: Schema.Literals<readonly ["completed", "partial", "failed"]>;
+        readonly reply: Schema.OptionFromNullOr<Schema.String>;
+    }>]>;
+}>;
+export type LogEntry = typeof LogEntry.Type;
+/** The model-visible rebuild of the log for one request. */
+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 providerOptions: Schema.optional<Schema.Unknown>;
+    }>, Schema.Struct<{
+        readonly role: Schema.Literal<"assistant">;
+        readonly content: 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<"reasoning">;
+            readonly text: Schema.String;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+        }>, Schema.Struct<{
+            readonly type: Schema.Literal<"tool-call">;
+            readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+            readonly toolName: Schema.String;
+            readonly input: Schema.Unknown;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+            readonly providerExecuted: Schema.optional<Schema.Boolean>;
+        }>]>>;
+        readonly providerOptions: Schema.optional<Schema.Unknown>;
+    }>, Schema.Struct<{
+        readonly role: Schema.Literal<"tool">;
+        readonly content: Schema.$Array<Schema.Struct<{
+            readonly type: Schema.Literal<"tool-result">;
+            readonly toolCallId: Schema.brand<Schema.String, "ToolCallId">;
+            readonly toolName: Schema.String;
+            readonly output: Schema.Unknown;
+            readonly providerOptions: Schema.optional<Schema.Unknown>;
+            readonly isError: Schema.optional<Schema.Boolean>;
+        }>>;
+        readonly providerOptions: Schema.optional<Schema.Unknown>;
+    }>]>>;
+    readonly fingerprint: Schema.String;
+    readonly estimatedTokens: Schema.Int;
+    readonly compactions: Schema.$Array<Schema.brand<Schema.Trimmed, "EntryId">>;
+    /** The last entry folded: what a rebuild must stop at. */
+    readonly through: Schema.OptionFromNullOr<Schema.brand<Schema.Trimmed, "EntryId">>;
+}>;
+export type BuiltContext = typeof BuiltContext.Type;

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

@@ -0,0 +1,89 @@
+import { Option } from "effect";
+import type { AgentMessage } from "../domain/message.entity.js";
+import type { ArtifactRef, BuiltContext, CompactionAction, EntryId, LogBody, LogEntry, Subject } from "./memory-log.entity.js";
+/** Key-sorted JSON: identical values always serialize to identical bytes. */
+export declare const canonicalJson: (value: unknown) => string;
+/** FNV-1a (32 bit) plus length — pure, stable across processes and runtimes. */
+export declare const fingerprintOf: (text: string) => string;
+/** A deliberately conservative estimate for mixed prose and JSON. */
+export declare const estimateTokens: (text: string) => number;
+export declare const estimateMessageTokens: (messages: ReadonlyArray<AgentMessage>) => number;
+export declare const entryId: (runId: string, index: number) => EntryId;
+export interface RenderOptions {
+    /** Only this strategy's compaction entries apply. */
+    readonly strategy: string;
+    readonly currentTurn: number;
+    readonly currentRun: string;
+    /** Turn contexts are shown for the current turn only, or for every kept turn. */
+    readonly turnContext: "current" | "all";
+    /** Append the host's delivered reply when the model's own text differs. */
+    readonly replies: boolean;
+    /** The current step's context closes the messages ("tail") or rides in the system prompt ("none"). */
+    readonly stepContext: "tail" | "none";
+    /** 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`.
+     */
+    readonly media: {
+        readonly mode: "none" | "inline";
+        readonly maxImages: 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>;
+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>;
+/** The number of the latest started turn (turns count from 1). */
+export declare const currentTurnOf: (entries: ReadonlyArray<LogEntry>) => number;
+/** Latest-wins subjects of the given kinds (every kind when empty). */
+export declare const subjectsOf: (entries: ReadonlyArray<LogEntry>, kinds: ReadonlyArray<string>) => ReadonlyArray<Subject>;
+/** Skills and tools activated so far, in activation order (only ever grows). */
+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. */
+export declare const referenceTranscript: (entries: ReadonlyArray<LogEntry>) => ReadonlyArray<AgentMessage>;
+/** The full-fidelity transcript: messages with every tool result's encoded value. */
+export declare const rawTranscript: (entries: ReadonlyArray<LogEntry>) => ReadonlyArray<AgentMessage>;
+export interface LogQuery {
+    readonly kinds: ReadonlyArray<LogBody["_tag"]>;
+    readonly turns: Option.Option<{
+        readonly from: number;
+        readonly to: number;
+    }>;
+    readonly tool: Option.Option<string>;
+    readonly subject: Option.Option<{
+        readonly kind: string;
+        readonly id: Option.Option<string>;
+    }>;
+    readonly text: Option.Option<string>;
+    readonly limit: Option.Option<number>;
+}
+export declare const emptyQuery: LogQuery;
+export declare const queryLog: (entries: ReadonlyArray<LogEntry>, query: LogQuery) => ReadonlyArray<LogEntry>;
+/** Tool-call inputs by call id, from the log and an unrecorded tail. */
+export declare const toolInputsOf: (entries: ReadonlyArray<LogEntry>, tail: ReadonlyArray<AgentMessage>) => ReadonlyMap<string, unknown>;
+/** Entry ids this strategy already rewrote (compact views or spills). */
+export declare const rewrittenBy: (entries: ReadonlyArray<LogEntry>, strategy: string) => ReadonlySet<string>;
+/** A hypothetical compaction entry, for estimating a render before recording it. */
+export declare const pendingCompaction: (strategy: {
+    readonly id: string;
+    readonly version: string;
+}, action: CompactionAction, index: number) => LogEntry;
+/**
+ * A compact, human-readable transcript of the given turns for digests and
+ * ledgers: user messages, assistant text, each tool result clipped, and replies.
+ * The head (the first request) always survives the cap.
+ */
+export declare const digestTranscript: (entries: ReadonlyArray<LogEntry>, caps: {
+    readonly result: number;
+    readonly total: number;
+}) => string;
+/** A generic ledger of condensed turns: what was asked, what was replied, what was found. */
+export declare const ledgerOf: (entries: ReadonlyArray<LogEntry>, throughTurn: number, perTurnChars: number) => string;

package/dist/memory/memory-log.entity.functions.js

@@ -0,0 +1,180 @@
+import { Effect, Option, Schema } from "effect";
+import { handoffToMessage } from "../loop/mapping.js";
+import { EntryId as EntryIdSchema } from "./memory-log.entity.js";
+export const canonicalJson = (value) => JSON.stringify(sortKeys(value)) ?? "null";
+const sortKeys = (value) => Array.isArray(value) ? value.map(sortKeys) : typeof value === "object" && value !== null ? Object.fromEntries(Object.keys(value).sort().flatMap((key) => {
+  const field = value[key];
+  return field === void 0 ? [] : [[key, sortKeys(field)]];
+})) : value;
+export const fingerprintOf = (text) => {
+  return `${Array.from(text).reduce((h, ch) => Math.imul((h ^ ch.charCodeAt(0)) >>> 0, 16777619) >>> 0, 2166136261).toString(16).padStart(8, "0")}${text.length.toString(16)}`;
+}, estimateTokens = (text) => Math.ceil(text.length / 3), estimateMessageTokens = (messages) => messages.reduce((sum, message) => sum + estimateTokens(canonicalJson(message)), 0), entryId = (runId, index) => EntryIdSchema.make(`${runId}:${index}`);
+const digestsOf = (entries) => new Map(entries.flatMap((entry) => entry.body._tag === "ToolDigest" ? [[String(entry.body.entry), entry.body.text]] : [])), appliedCompactions = (entries, strategy) => entries.reduce((applied, entry) => {
+  if (entry.body._tag !== "Compaction" || entry.body.strategy !== strategy)
+    return applied;
+  const action = entry.body.action, ids = [...applied.ids, entry.id];
+  if (action._tag === "CompactViews")
+    return { ...applied, ids, views: new Map([...applied.views, ...action.entries.map((id, index) => [id, action.texts[index] ?? ""])]) };
+  if (action._tag === "Spill")
+    return { ...applied, ids, views: new Map([...applied.views, [action.entry, action.preview]]) };
+  if (action._tag === "DropTurns")
+    return action.throughTurn < applied.cutTurn ? { ...applied, ids } : {
+      ...applied,
+      ids,
+      cutTurn: action.throughTurn,
+      preamble: Option.some({ role: "user", content: `[Host note: earlier turns were condensed to free context.]
+
+${action.ledger}` })
+    };
+  return action.keepFromTurn - 1 < applied.cutTurn ? { ...applied, ids } : {
+    ...applied,
+    ids,
+    cutTurn: action.keepFromTurn - 1,
+    preamble: Option.some(handoffToMessage(action.summary))
+  };
+}, { views: new Map, cutTurn: 0, preamble: Option.none(), ids: [] }), toolCallIds = (message) => message.role === "assistant" ? message.content.flatMap((part) => part.type === "tool-call" ? [part.toolCallId] : []) : [], assistantText = (message) => {
+  if (message.role !== "assistant")
+    return Option.none();
+  const text = message.content.flatMap((part) => part.type === "text" ? [part.text] : []).join("");
+  return text.length === 0 ? Option.none() : Option.some(text);
+}, mergeToolMessages = (messages) => messages.reduce((merged, message) => {
+  const last = merged[merged.length - 1];
+  return last !== void 0 && last.role === "tool" && message.role === "tool" ? [...merged.slice(0, -1), { role: "tool", content: [...last.content, ...message.content] }] : [...merged, message];
+}, []);
+export const artifactLines = (artifacts, maxImages) => {
+  if (artifacts.length === 0)
+    return "";
+  const shown = artifacts.slice(0, Math.max(0, maxImages)), more = artifacts.length - shown.length;
+  return [
+    "",
+    "Artifacts:",
+    ...shown.map((artifact) => `- ${artifact.kind} ${artifact.id} (${artifact.mediaType})${Option.match(artifact.alt, { onNone: () => "", onSome: (alt) => `: ${alt}` })}`),
+    ...more > 0 ? [`- \u2026 ${more} more`] : []
+  ].join(`
+`);
+};
+const userRoleMessage = (content) => ({ role: "user", content }), assistantMessage = (text) => ({ role: "assistant", content: [{ type: "text", text }] });
+export const renderLog = (entries, options) => {
+  const applied = appliedCompactions(entries, options.strategy), digests = options.digests ? digestsOf(entries) : new Map, pinned = new Set(entries.flatMap((entry) => entry.body._tag === "ToolResult" && entry.body.pinned ? [String(entry.body.toolCallId)] : [])), kept = (entry) => entry.turn > applied.cutTurn, stepContext = options.stepContext === "none" ? [] : entries.filter((entry) => entry.body._tag === "StepContext" && entry.runId === options.currentRun).slice(-1), initial = { out: [], lastText: new Map }, body = entries.reduce((state, entry) => {
+    const b = entry.body;
+    if (b._tag === "TurnStarted")
+      return kept(entry) ? { ...state, out: [...state.out, userRoleMessage(b.userMessage.text)] } : state;
+    if (b._tag === "TurnContext")
+      return kept(entry) && (options.turnContext === "all" || entry.turn === options.currentTurn) ? { ...state, out: [...state.out, userRoleMessage(b.text)] } : state;
+    if (b._tag === "Message") {
+      const calls = toolCallIds(b.message), pinnedExchange = calls.length > 0 && calls.every((id) => pinned.has(id));
+      if (!kept(entry) && !pinnedExchange)
+        return state;
+      const text = assistantText(b.message);
+      return {
+        out: [...state.out, b.message],
+        lastText: Option.match(text, { onNone: () => state.lastText, onSome: (value) => new Map([...state.lastText, [entry.turn, value]]) })
+      };
+    }
+    if (b._tag === "ToolResult") {
+      if (!kept(entry) && !b.pinned)
+        return state;
+      const text = applied.views.get(entry.id) ?? digests.get(entry.id) ?? b.view, message = { role: "tool", content: [{
+        type: "tool-result",
+        toolCallId: b.toolCallId,
+        toolName: b.toolName,
+        output: `${text}${artifactLines(b.artifacts, options.media.maxImages)}`,
+        isError: b.isError
+      }] };
+      return { ...state, out: [...state.out, message] };
+    }
+    if (b._tag === "TurnEnded" && options.replies && kept(entry))
+      return Option.match(b.reply, {
+        onNone: () => state,
+        onSome: (reply) => reply.length === 0 || state.lastText.get(entry.turn) === reply ? state : { ...state, out: [...state.out, assistantMessage(reply)] }
+      });
+    return state;
+  }, initial).out, tail = stepContext.flatMap((entry) => entry.body._tag === "StepContext" ? [userRoleMessage(entry.body.text)] : []);
+  return mergeToolMessages([...Option.toArray(applied.preamble), ...body, ...tail]);
+}, buildContext = (entries, options) => {
+  const messages = renderLog(entries, options);
+  return {
+    messages,
+    fingerprint: fingerprintOf(canonicalJson(messages)),
+    estimatedTokens: estimateMessageTokens(messages),
+    compactions: appliedCompactions(entries, options.strategy).ids,
+    through: Option.fromNullishOr(entries.at(-1)?.id)
+  };
+}, stepContextOf = (entries, runId) => Option.fromNullishOr(entries.flatMap((entry) => entry.body._tag === "StepContext" && entry.runId === runId ? [entry.body.text] : []).at(-1)), currentTurnOf = (entries) => entries.reduce((turn, entry) => entry.body._tag === "TurnStarted" ? Math.max(turn, entry.turn) : turn, 0), subjectsOf = (entries, kinds) => {
+  const all = entries.flatMap((entry) => entry.body._tag === "ToolResult" ? entry.body.subjects : []).filter((subject) => kinds.length === 0 || kinds.includes(subject.kind));
+  return [...new Map(all.map((subject) => [`${subject.kind}\x00${subject.id}`, subject])).values()];
+}, activationsOf = (entries) => entries.reduce((active, entry) => entry.body._tag !== "ToolsActivated" ? active : {
+  skills: [...active.skills, ...entry.body.skills.filter((skill) => !active.skills.includes(skill))],
+  tools: [...active.tools, ...entry.body.tools.filter((tool) => !active.tools.includes(tool))]
+}, { skills: [], tools: [] }), referenceTranscript = (entries) => entries.flatMap((entry) => {
+  if (entry.body._tag === "TurnStarted")
+    return [userRoleMessage(entry.body.userMessage.text)];
+  if (entry.body._tag === "TurnEnded")
+    return Option.match(entry.body.reply, { onNone: () => [], onSome: (text) => text.length === 0 ? [] : [{ role: "assistant", content: [{ type: "text", text }] }] });
+  return [];
+}), rawTranscript = (entries) => mergeToolMessages(entries.flatMap((entry) => {
+  if (entry.body._tag === "TurnStarted")
+    return [userRoleMessage(entry.body.userMessage.text)];
+  if (entry.body._tag === "Message")
+    return [entry.body.message];
+  if (entry.body._tag === "ToolResult")
+    return [{ role: "tool", content: [{ type: "tool-result", toolCallId: entry.body.toolCallId, toolName: entry.body.toolName, output: entry.body.encoded, isError: entry.body.isError }] }];
+  return [];
+})), emptyQuery = {
+  kinds: [],
+  turns: Option.none(),
+  tool: Option.none(),
+  subject: Option.none(),
+  text: Option.none(),
+  limit: Option.none()
+}, queryLog = (entries, query) => {
+  const matches = entries.filter((entry) => (query.kinds.length === 0 || query.kinds.includes(entry.body._tag)) && Option.match(query.turns, { onNone: () => !0, onSome: (range) => entry.turn >= range.from && entry.turn <= range.to }) && Option.match(query.tool, { onNone: () => !0, onSome: (tool) => entry.body._tag === "ToolResult" && entry.body.toolName === tool }) && Option.match(query.subject, {
+    onNone: () => !0,
+    onSome: (wanted) => entry.body._tag === "ToolResult" && entry.body.subjects.some((subject) => subject.kind === wanted.kind && Option.match(wanted.id, { onNone: () => !0, onSome: (id) => subject.id === id }))
+  }) && Option.match(query.text, { onNone: () => !0, onSome: (text) => canonicalJson(entry.body).toLowerCase().includes(text.toLowerCase()) }));
+  return Option.match(query.limit, { onNone: () => matches, onSome: (limit) => matches.slice(-limit) });
+}, toolInputsOf = (entries, tail) => new Map([
+  ...entries.flatMap((entry) => entry.body._tag === "Message" ? [entry.body.message] : []),
+  ...tail
+].flatMap((message) => message.role === "assistant" ? message.content.flatMap((part) => part.type === "tool-call" ? [[String(part.toolCallId), part.input]] : []) : [])), rewrittenBy = (entries, strategy) => new Set(entries.flatMap((entry) => entry.body._tag !== "Compaction" || entry.body.strategy !== strategy ? [] : entry.body.action._tag === "CompactViews" ? entry.body.action.entries.map(String) : entry.body.action._tag === "Spill" ? [String(entry.body.action.entry)] : [])), pendingCompaction = (strategy, action, index) => ({
+  id: EntryIdSchema.make(`pending:${index}`),
+  runId: "",
+  turn: 0,
+  step: 0,
+  at: 0,
+  body: { _tag: "Compaction", strategy: strategy.id, version: strategy.version, action }
+});
+const clipText = (text, max) => text.length <= max ? text : `${text.slice(0, max)}\u2026`;
+export const digestTranscript = (entries, caps) => {
+  const lines = entries.flatMap((entry) => {
+    const body = entry.body;
+    if (body._tag === "TurnStarted")
+      return [`User: ${body.userMessage.text}`];
+    if (body._tag === "Message")
+      return Option.toArray(Option.map(assistantText(body.message), (text) => `Assistant: ${text}`));
+    if (body._tag === "ToolResult")
+      return [`Tool ${body.toolName}${body.isError ? " (failed)" : ""}: ${clipText(body.view, caps.result)}`];
+    if (body._tag === "TurnEnded")
+      return Option.toArray(Option.map(body.reply, (reply) => `Reply: ${reply}`));
+    return [];
+  }), joined = lines.join(`
+`);
+  if (joined.length <= caps.total)
+    return joined;
+  const head = lines[0] ?? "";
+  return `${head}
+[\u2026earlier transcript clipped\u2026]
+${lines.slice(1).join(`
+`).slice(-(caps.total - head.length))}`;
+}, ledgerOf = (entries, throughTurn, perTurnChars) => {
+  const kept = entries.filter((entry) => entry.turn <= throughTurn), lines = [...new Set(kept.map((entry) => entry.turn))].sort((left, right) => left - right).flatMap((turn) => {
+    const inTurn = kept.filter((entry) => entry.turn === turn), asked = inTurn.flatMap((entry) => entry.body._tag === "TurnStarted" ? [entry.body.userMessage.text] : []).at(0), reply = inTurn.flatMap((entry) => entry.body._tag === "TurnEnded" ? Option.toArray(entry.body.reply) : []).at(-1);
+    return asked === void 0 ? [] : [`- Asked: ${clipText(asked, perTurnChars)}${reply === void 0 ? "" : ` \u2014 replied: ${clipText(reply, perTurnChars)}`}`];
+  }), subjects = subjectsOf(kept, []).slice(-24).map((subject) => `${subject.kind} ${subject.id}${Option.match(subject.label, { onNone: () => "", onSome: (label) => ` (${label})` })}`);
+  return [
+    "Earlier in this conversation:",
+    ...lines,
+    ...subjects.length === 0 ? [] : [`Known subjects: ${subjects.join("; ")}`]
+  ].join(`
+`);
+};