@inflexa-ai/harness 0.39.2 → 0.41.0

package/dist/loop/run-to-terminal.d.ts

@@ -4,17 +4,17 @@
  * Some agents communicate their result EXCLUSIVELY through a terminal tool
  * (`submit_plan`, `submit_profile`, `submit_synthesis`, …):
  * the loop's text reply is discarded and the outcome is read from a closure
- * cell the terminal tool writes. Plain `runAgent` ends a capped run on a
- * tool-LESS wrap-up turn, so an agent that burns its whole iteration budget —
- * or simply stops on prose — without ever submitting leaves that cell empty
- * and forces the caller to hard-fail.
+ * cell the terminal tool writes. The wrap-up of a capped run lets no tool run,
+ * so an agent that burns its whole iteration budget — or simply stops on
+ * prose — without ever submitting leaves that cell empty and forces the caller
+ * to hard-fail.
  *
  * `runToTerminal` runs the agent, then — if the outcome cell is still empty
- * and the run was not aborted — grants ONE focused salvage continuation whose
- * only tools are the terminal tools, opened by a corrective nudge. Restricting
- * the surface to the terminal tools removes every distraction; a small
- * `maxIterations` lets the model fix a single validation rejection and
- * resubmit.
+ * and the run was not aborted — runs ONE salvage continuation of the same
+ * conversation (`continueAgent`), opened by a corrective nudge. The salvage
+ * still declares every tool of the agent, masked to the terminal tools only,
+ * because the tool set is part of the prefix a signed thinking block and the
+ * prompt cache bind to.
  *
  * Salvage steps are namespaced (`salvage:…`) so a durable (DBOS) caller does
  * not collide the continuation's `llm-*` / `tool-*` cache keys with the first
@@ -50,18 +50,17 @@ export interface RunToTerminalResult extends RunAgentResult {
 }
 /** Describes how to salvage a run that never reached its terminal tool. */
 export interface TerminalSalvage {
-    /** Terminal tools offered on the salvage turn (submit / blocker / …). Must be
-     *  the same instances the first run used — they close over the outcome cell. */
+    /** Their ids become the mask of the salvage continuation, so each must already be a declared tool of the agent. */
     readonly tools: readonly Tool[];
-    /** Corrective user message that opens the salvage continuation. */
+    /** Opens the salvage continuation as a synthetic user message. */
     readonly nudge: string;
-    /** Salvage iteration budget. Defaults to {@link DEFAULT_SALVAGE_ITERATIONS}. */
+    /** The cap of salvage requests. Defaults to {@link DEFAULT_SALVAGE_ITERATIONS}. */
     readonly maxIterations?: number;
 }
 /**
- * Drive `agent` to its terminal tool, salvaging once if it doesn't get there.
- * Returns the salvage run's result when a salvage occurred (its message array
- * already includes the first run's, and its token rollups are summed across both
- * attempts), otherwise the first run's result.
+ * Drive `agent` to its terminal tool, salvaging once if it does not get there.
+ * A salvage result carries both runs' messages and summed rollups, with the
+ * salvage's own finish. Throws first if a terminal tool is not declared on the
+ * agent.
  */
 export declare function runToTerminal(agent: AgentDefinition, initial: readonly LoopMessage[], session: AgentSession, opts: RunAgentOptions, salvage: TerminalSalvage): Promise<RunToTerminalResult>;

package/dist/loop/run-to-terminal.js

@@ -4,46 +4,45 @@
  * Some agents communicate their result EXCLUSIVELY through a terminal tool
  * (`submit_plan`, `submit_profile`, `submit_synthesis`, …):
  * the loop's text reply is discarded and the outcome is read from a closure
- * cell the terminal tool writes. Plain `runAgent` ends a capped run on a
- * tool-LESS wrap-up turn, so an agent that burns its whole iteration budget —
- * or simply stops on prose — without ever submitting leaves that cell empty
- * and forces the caller to hard-fail.
+ * cell the terminal tool writes. The wrap-up of a capped run lets no tool run,
+ * so an agent that burns its whole iteration budget — or simply stops on
+ * prose — without ever submitting leaves that cell empty and forces the caller
+ * to hard-fail.
  *
  * `runToTerminal` runs the agent, then — if the outcome cell is still empty
- * and the run was not aborted — grants ONE focused salvage continuation whose
- * only tools are the terminal tools, opened by a corrective nudge. Restricting
- * the surface to the terminal tools removes every distraction; a small
- * `maxIterations` lets the model fix a single validation rejection and
- * resubmit.
+ * and the run was not aborted — runs ONE salvage continuation of the same
+ * conversation (`continueAgent`), opened by a corrective nudge. The salvage
+ * still declares every tool of the agent, masked to the terminal tools only,
+ * because the tool set is part of the prefix a signed thinking block and the
+ * prompt cache bind to.
  *
  * Salvage steps are namespaced (`salvage:…`) so a durable (DBOS) caller does
  * not collide the continuation's `llm-*` / `tool-*` cache keys with the first
  * run's — replaying them would silently return the first run's cached results.
  */
 import { createNoopLogger } from "../lib/console-logger.js";
+import { continueAgent } from "./continue-agent.js";
 import { addChatUsage } from "./metrics.js";
-import { DEFAULT_STEP_NAME_FORMATTER, runAgent } from "./run-agent.js";
+import { runAgent } from "./run-agent.js";
 /** Default salvage budget: one submit plus a validation-fix retry or two. */
 export const DEFAULT_SALVAGE_ITERATIONS = 3;
-function salvageStepNames(base) {
-    return {
-        llm: (i) => `salvage:${base.llm(i)}`,
-        tool: (name, id) => `salvage:${base.tool(name, id)}`,
-    };
-}
 /**
- * Drive `agent` to its terminal tool, salvaging once if it doesn't get there.
- * Returns the salvage run's result when a salvage occurred (its message array
- * already includes the first run's, and its token rollups are summed across both
- * attempts), otherwise the first run's result.
+ * Drive `agent` to its terminal tool, salvaging once if it does not get there.
+ * A salvage result carries both runs' messages and summed rollups, with the
+ * salvage's own finish. Throws first if a terminal tool is not declared on the
+ * agent.
  */
 export async function runToTerminal(agent, initial, session, opts, salvage) {
+    const undeclared = salvage.tools.find((terminal) => !agent.tools.some((tool) => tool.id === terminal.id));
+    if (undeclared !== undefined) {
+        throw new Error(`The terminal tool "${undeclared.id}" is not a declared tool of the agent "${agent.id}", thus the salvage mask cannot let it run.`);
+    }
     const first = await runAgent(agent, initial, session, opts);
     if (opts.resolved?.() || opts.signal.aborted)
         return { ...first, salvage: null };
     const salvageBudget = salvage.maxIterations ?? DEFAULT_SALVAGE_ITERATIONS;
     // Reported here rather than in `runAgent` because the loop cannot know it is being
-    // salvaged: it sees an ordinary run with a small budget and a restricted tool set.
+    // salvaged: it sees a continuation with a small cap and a mask.
     // Only this wrapper holds the fact that a first attempt ended without its outcome.
     // The first run's finish rides along because it is the whole diagnosis of WHY a
     // salvage was needed, and it is the field the second run's result overwrites.
@@ -55,26 +54,16 @@ export async function runToTerminal(agent, initial, session, opts, salvage) {
         salvageTools: salvage.tools.map((t) => t.id),
         salvageMaxIterations: salvageBudget,
     });
-    const salvageAgent = {
-        ...agent,
-        tools: [...salvage.tools],
-        maxIterations: salvageBudget,
-    };
-    const salvageOpts = {
-        ...opts,
-        formatStepName: salvageStepNames(opts.formatStepName ?? DEFAULT_STEP_NAME_FORMATTER),
-    };
-    const salvaged = await runAgent(salvageAgent, [...first.messages, { role: "user", content: salvage.nudge }], session, salvageOpts);
-    // The continuation is the same logical run as the first attempt — its
-    // message array already carries the first run's — so its rollups must too,
-    // or the caller reads the salvage turn's tokens as the whole cost.
+    const salvaged = await continueAgent(agent, first.messages, { text: salvage.nudge, mask: { allow: salvage.tools.map((t) => t.id) }, maxRequests: salvageBudget, stepNamespace: "salvage" }, session, opts);
+    // The continuation is the same logical run as the first attempt, so its
+    // rollups must cover both, or the caller reads the salvage's tokens as the whole cost.
     //
     // `salvage` deliberately keeps each attempt's OWN finish, unsummed: it is the
     // per-attempt diagnosis, not a second accounting of the same tokens. The two
     // views are therefore NOT additive — `finish` is the run's total and already
     // covers everything `salvage.firstFinish` and `salvage.finish` report.
     return {
-        ...salvaged,
+        messages: [...first.messages, ...salvaged.messages],
         finish: {
             ...salvaged.finish,
             ...sumUsage("usage", first.finish, salvaged.finish),

package/dist/loop/tool-mask.d.ts

@@ -0,0 +1,23 @@
+/**
+ * A signed thinking block is bound to the exact prefix of its request, so a
+ * request always declares the full tool set
+ * of its agent; the mask and the budget act at dispatch instead. Provider-native
+ * masking is out of scope, because the vendors do it differently and an
+ * OpenAI-compatible endpoint has neither form.
+ */
+import type { ToolCallPart } from "ai";
+import type { Tool } from "../tools/define-tool.js";
+/** An absent mask lets each declared tool run. */
+export type ToolMask = "none" | {
+    readonly allow: readonly string[];
+};
+/** A tool with no entry has no limit. */
+export type ToolBudget = Readonly<Record<string, number>>;
+export declare function maskExcept(tools: readonly Tool[], ids: readonly string[]): ToolMask;
+/**
+ * `undefined` for a call that passes, otherwise the model-visible refusal
+ * text. A passing call takes one unit from `used` regardless of its later
+ * result, because the check reads only the mask, the budget, and the run's
+ * calls — so a durable replay refuses the same calls again.
+ */
+export declare function refusalsFor(calls: readonly ToolCallPart[], mask: ToolMask | undefined, budget: ToolBudget | undefined, used: Map<string, number>): (string | undefined)[];

package/dist/loop/tool-mask.js

@@ -0,0 +1,46 @@
+/**
+ * A signed thinking block is bound to the exact prefix of its request, so a
+ * request always declares the full tool set
+ * of its agent; the mask and the budget act at dispatch instead. Provider-native
+ * masking is out of scope, because the vendors do it differently and an
+ * OpenAI-compatible endpoint has neither form.
+ */
+export function maskExcept(tools, ids) {
+    return { allow: tools.map((t) => t.id).filter((id) => !ids.includes(id)) };
+}
+function maskLets(mask, toolName) {
+    if (mask === undefined)
+        return true;
+    if (mask === "none")
+        return false;
+    return mask.allow.includes(toolName);
+}
+/** Matches the `{ error, retryable }` shape of every other tool error. */
+function refusal(error) {
+    return JSON.stringify({ error, retryable: false });
+}
+function maskRefusal(mask, toolName) {
+    if (mask === "none")
+        return refusal(`No tool can run for this request, thus ${toolName} did not run. Answer in text.`);
+    const available = mask.allow.length === 0 ? "none" : mask.allow.join(", ");
+    return refusal(`The tool ${toolName} is not available for this request, thus it did not run. The tools that can run now: ${available}.`);
+}
+/**
+ * `undefined` for a call that passes, otherwise the model-visible refusal
+ * text. A passing call takes one unit from `used` regardless of its later
+ * result, because the check reads only the mask, the budget, and the run's
+ * calls — so a durable replay refuses the same calls again.
+ */
+export function refusalsFor(calls, mask, budget, used) {
+    return calls.map((call) => {
+        if (mask !== undefined && !maskLets(mask, call.toolName))
+            return maskRefusal(mask, call.toolName);
+        const limit = budget?.[call.toolName];
+        const count = used.get(call.toolName) ?? 0;
+        if (limit !== undefined && count >= limit) {
+            return refusal(`The tool ${call.toolName} reached its limit of ${limit} calls in this run, thus this call did not run.`);
+        }
+        used.set(call.toolName, count + 1);
+        return undefined;
+    });
+}

package/dist/loop/tool-output.d.ts

@@ -0,0 +1,48 @@
+/**
+ * The cut of a long tool result: the excerpt that the model reads, and the store that keeps the whole text.
+ * Each length and each offset counts UTF-16 code units, the unit of a JavaScript string length.
+ */
+import type { ToolResultPart } from "ai";
+import type { ResultAsync } from "neverthrow";
+import type { DomainError } from "../lib/result.js";
+/** Keeps each skill file whole, because the largest one gives about 29,300 characters. */
+export declare const TOOL_RESULT_CAP: number;
+/** The start of an excerpt holds the shape of a result: its status, its first keys, or a header row. */
+export declare const EXCERPT_HEAD_CHARS: number;
+/** The end of an excerpt holds the errors and the stream flags of a command, thus it gets two times the start. */
+export declare const EXCERPT_TAIL_CHARS: number;
+/** The bound of a file that `grep` reads, thus a pattern search over a kept text costs no more than a `grep`. */
+export declare const TOOL_OUTPUT_KEEP_MAX: number;
+export declare const READ_TOOL_OUTPUT_TOOL_ID = "read_tool_output";
+export interface KeptToolOutput {
+    readonly analysisId: string;
+    readonly ref: string;
+    readonly toolName: string;
+    readonly toolCallId: string;
+    /** Absent for a loop of a run, because a run belongs to its analysis and not to a thread. */
+    readonly threadId?: string;
+    /** The whole text, or its two halves with a marker line between them. */
+    readonly content: string;
+    /** The length of the whole text of the result. */
+    readonly totalLength: number;
+}
+/** Keeps the text of each cut tool result for `read_tool_output`. */
+export interface ToolOutputStore {
+    /** A second put of the same analysis id and reference replaces the text. */
+    put(output: KeptToolOutput): ResultAsync<void, DomainError>;
+    get(analysisId: string, ref: string): ResultAsync<KeptToolOutput | null, DomainError>;
+}
+/** The reference of one kept text. It is short, because the model copies it. */
+export declare function toolOutputRef(key: string): string;
+/** The text that the model reads for a result, or `undefined` for a denial, which is never cut. */
+export declare function resultTextOf(output: ToolResultPart["output"]): string | undefined;
+/** Move `index` by one unit toward `direction` when it falls between the two halves of a surrogate pair. */
+export declare function pairSafeIndex(text: string, index: number, direction: -1 | 1): number;
+export declare function keptTextOf(text: string): string;
+/** The excerpt of a text longer than `TOOL_RESULT_CAP`. `kept` is absent when the loop kept no text. */
+export declare function excerptOf(text: string, kept: {
+    readonly ref: string;
+    readonly keptLength: number;
+} | undefined): string;
+/** The result with `excerpt` in place of its text. A part of a JSON text is not valid JSON, thus a JSON result becomes text. */
+export declare function withExcerpt(part: ToolResultPart, excerpt: string): ToolResultPart;

package/dist/loop/tool-output.js

@@ -0,0 +1,79 @@
+/**
+ * The cut of a long tool result: the excerpt that the model reads, and the store that keeps the whole text.
+ * Each length and each offset counts UTF-16 code units, the unit of a JavaScript string length.
+ */
+import { createHash } from "node:crypto";
+/** Keeps each skill file whole, because the largest one gives about 29,300 characters. */
+export const TOOL_RESULT_CAP = 32 * 1024;
+/** The start of an excerpt holds the shape of a result: its status, its first keys, or a header row. */
+export const EXCERPT_HEAD_CHARS = 4 * 1024;
+/** The end of an excerpt holds the errors and the stream flags of a command, thus it gets two times the start. */
+export const EXCERPT_TAIL_CHARS = 8 * 1024;
+/** The bound of a file that `grep` reads, thus a pattern search over a kept text costs no more than a `grep`. */
+export const TOOL_OUTPUT_KEEP_MAX = 1024 * 1024;
+export const READ_TOOL_OUTPUT_TOOL_ID = "read_tool_output";
+/** The reference of one kept text. It is short, because the model copies it. */
+export function toolOutputRef(key) {
+    return `to_${createHash("sha256").update(key).digest("hex").slice(0, 20)}`;
+}
+/** The text that the model reads for a result, or `undefined` for a denial, which is never cut. */
+export function resultTextOf(output) {
+    switch (output.type) {
+        case "json":
+        case "error-json":
+            return JSON.stringify(output.value);
+        case "text":
+        case "error-text":
+            return output.value;
+        case "content":
+            return output.value.map((part) => (part.type === "text" ? part.text : "")).join("");
+        case "execution-denied":
+            return undefined;
+    }
+}
+/** Move `index` by one unit toward `direction` when it falls between the two halves of a surrogate pair. */
+export function pairSafeIndex(text, index, direction) {
+    if (index <= 0 || index >= text.length)
+        return index;
+    const before = text.charCodeAt(index - 1);
+    const after = text.charCodeAt(index);
+    const splitsPair = before >= 0xd800 && before <= 0xdbff && after >= 0xdc00 && after <= 0xdfff;
+    return splitsPair ? index + direction : index;
+}
+export function keptTextOf(text) {
+    if (text.length <= TOOL_OUTPUT_KEEP_MAX)
+        return text;
+    const headEnd = pairSafeIndex(text, TOOL_OUTPUT_KEEP_MAX / 2, -1);
+    const tailStart = pairSafeIndex(text, text.length - TOOL_OUTPUT_KEEP_MAX / 2, 1);
+    return `${text.slice(0, headEnd)}\n[... ${tailStart - headEnd} characters not kept ...]\n${text.slice(tailStart)}`;
+}
+/** The excerpt of a text longer than `TOOL_RESULT_CAP`. `kept` is absent when the loop kept no text. */
+export function excerptOf(text, kept) {
+    const headEnd = pairSafeIndex(text, EXCERPT_HEAD_CHARS, -1);
+    const tailStart = pairSafeIndex(text, text.length - EXCERPT_TAIL_CHARS, 1);
+    const shown = `Shown: the first ${headEnd} and the last ${text.length - tailStart} characters.`;
+    const lines = [
+        `[Tool result cut: ${text.length} characters, over the limit of ${TOOL_RESULT_CAP}. ${shown}${kept === undefined ? " The rest is not kept." : ""}]`,
+    ];
+    if (kept !== undefined) {
+        lines.push(`[The harness kept ${kept.keptLength} characters as reference "${kept.ref}". Call ${READ_TOOL_OUTPUT_TOOL_ID} with this reference and an offset and a limit, or with a pattern. Offsets start at 0.]`);
+    }
+    lines.push(text.slice(0, headEnd), `[... ${tailStart - headEnd} characters not shown ...]`, text.slice(tailStart));
+    return lines.join("\n");
+}
+/** The result with `excerpt` in place of its text. A part of a JSON text is not valid JSON, thus a JSON result becomes text. */
+export function withExcerpt(part, excerpt) {
+    const { output } = part;
+    switch (output.type) {
+        case "json":
+        case "text":
+            return { ...part, output: { type: "text", value: excerpt } };
+        case "error-json":
+        case "error-text":
+            return { ...part, output: { type: "error-text", value: excerpt } };
+        case "content":
+            return { ...part, output: { type: "content", value: [{ type: "text", text: excerpt }, ...output.value.filter((p) => p.type !== "text")] } };
+        case "execution-denied":
+            return part;
+    }
+}

package/dist/loop/types.d.ts

@@ -26,7 +26,7 @@ export interface AgentDefinition {
     readonly systemPrompt: string;
     readonly model: string;
     readonly tools: readonly Tool[];
-    /** Runaway guard — at the cap the loop forces a wrap-up call that forbids tools. */
+    /** Runaway guard: at the cap the loop runs up to two masked wrap-up requests, until it gets a text answer. */
     readonly maxIterations: number;
 }
 /**
@@ -52,9 +52,12 @@ export interface EventSource {
 export type EmitEvent = {
     readonly type: "iteration";
     readonly source: EventSource;
-    /** Zero-based iteration index; equals `maxIterations` for the wrap-up. */
+    /** Zero-based. Wrap-up request `k` has index `maxIterations + k`; a continuation counts from 0. */
     readonly index: number;
-    /** True when this iteration produced the loop's terminal reply. */
+    /**
+     * True when this iteration produced the loop's terminal reply, including
+     * the last wrap-up even when its reply called a tool.
+     */
     readonly final: boolean;
 } | {
     readonly type: "tool-started";

package/dist/memory/ai-sdk-message-storage.d.ts

@@ -35,6 +35,23 @@ export declare const SYNTHETIC_MESSAGE_KEY = "synthetic";
 export declare const SYNTHETIC_RECORD_KEY = "syntheticRecord";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key marking an assistant message whose production a client abort cut off. */
 export declare const INTERRUPTED_MESSAGE_KEY = "interrupted";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the kind of a context record. */
+export declare const CONTEXT_KIND_KEY = "contextKind";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the SHA-256 hex hash of the text of a context record. */
+export declare const CONTEXT_HASH_KEY = "contextHash";
+declare const CONTEXT_KINDS: readonly ["analysis-context", "run-activity", "working-memory"];
+/** The kinds of per-turn context that a chat turn stores after its user message. */
+export type ContextKind = (typeof CONTEXT_KINDS)[number];
+/**
+ * A context record: a synthetic `user` message, and no host record, thus it opens no turn and the
+ * display does not show it.
+ */
+export declare function contextRecordMessage(kind: ContextKind, text: string): ModelMessage;
+/** The kind and the hash of a context record, or `undefined` for a message that is no record. */
+export declare function contextRecordOf(message: ModelMessage): {
+    readonly kind: ContextKind;
+    readonly hash: string;
+} | undefined;
 /**
  * Return a copy of `message` carrying the interruption marker in the harness namespace.
  *
@@ -57,7 +74,7 @@ export declare function isInterruptedMessage(message: ModelMessage): boolean;
  * It has to carry the `user` role because the wire format requires a user turn after a truncated
  * assistant message, but it is not user input, and the difference is load-bearing: a `user` message is
  * what OPENS a conversation turn, so an unmarked synthetic one reads as a spurious turn boundary —
- * splitting one turn into two for the token window and, worse, giving a tail-turn removal a cut point in
+ * splitting one turn into two for the view and, worse, giving a tail-turn removal a cut point in
  * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
  *
  * `content` takes prose or the parts of a user message, because a picture rides a file part and no
@@ -74,7 +91,7 @@ export declare function syntheticUserMessage(content: UserContent): ModelMessage
  * outcome, which the model should read on its next turn but which nobody said.
  *
  * Synthetic in every sense that matters to a turn-boundary reader ({@link isSyntheticUserMessage} is
- * true of it), so it cannot split a turn for the token window nor hand a tail retraction a mid-turn
+ * true of it), so it cannot split a turn for the view nor hand a tail retraction a mid-turn
  * cut point. It differs from {@link syntheticUserMessage} in exactly one respect, and it is the
  * decisive one: this is a fact the reader is entitled to see, so the display reconstruction emits it
  * — as a `system` message, which is what it is — rather than dropping it as loop machinery.
@@ -89,6 +106,36 @@ export declare function syntheticRecordMessage(text: string): ModelMessage;
 export declare function isSyntheticUserMessage(message: ModelMessage): boolean;
 /** Whether this is a host-appended record of out-of-band work (see {@link syntheticRecordMessage}) — synthetic, but displayed. */
 export declare function isSyntheticRecordMessage(message: ModelMessage): boolean;
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the compaction id on each message of its exchange, which the view rule skips. */
+export declare const COMPACTION_EXCHANGE_KEY = "compactionExchange";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the figures of a compaction marker, which the view rule reads. */
+export declare const COMPACTION_MARKER_KEY = "compactionMarker";
+declare const CompactionMarkerSchema: z.ZodDiscriminatedUnion<[z.ZodObject<{
+    id: z.ZodString;
+    tokensBefore: z.ZodNumber;
+    tokensAfter: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"summary">;
+}, z.core.$strip>, z.ZodObject<{
+    keptTurns: z.ZodNumber;
+    id: z.ZodString;
+    tokensBefore: z.ZodNumber;
+    tokensAfter: z.ZodNumber;
+    durationMs: z.ZodNumber;
+    kind: z.ZodLiteral<"drop">;
+}, z.core.$strip>], "kind">;
+export type CompactionMarker = z.infer<typeof CompactionMarkerSchema>;
+/** A copy of `message` whose harness namespace, which no provider reads, holds the compaction id. */
+export declare function markCompactionExchange(message: ModelMessage, id: string): ModelMessage;
+export declare function compactionExchangeOf(message: ModelMessage): string | undefined;
+export declare function summaryMarkerMessage(summary: string, marker: Extract<CompactionMarker, {
+    kind: "summary";
+}>): ModelMessage;
+/** The marker of a compaction that gave no summary. No view holds it. */
+export declare function dropMarkerMessage(marker: Extract<CompactionMarker, {
+    kind: "drop";
+}>): ModelMessage;
+export declare function compactionMarkerOf(message: ModelMessage): CompactionMarker | undefined;
 type LegacyContent = string | Array<Record<string, unknown>>;
 export interface LegacyMessageRow {
     readonly threadId: string;

package/dist/memory/ai-sdk-message-storage.js

@@ -1,3 +1,4 @@
+import { createHash } from "node:crypto";
 import { modelMessageSchema } from "ai";
 import { z } from "zod";
 export const SUPPORTED_AI_SDK_MAJOR = 7;
@@ -46,6 +47,35 @@ export const SYNTHETIC_MESSAGE_KEY = "synthetic";
 export const SYNTHETIC_RECORD_KEY = "syntheticRecord";
 /** The {@link HARNESS_PROVIDER_NAMESPACE} key marking an assistant message whose production a client abort cut off. */
 export const INTERRUPTED_MESSAGE_KEY = "interrupted";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the kind of a context record. */
+export const CONTEXT_KIND_KEY = "contextKind";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the SHA-256 hex hash of the text of a context record. */
+export const CONTEXT_HASH_KEY = "contextHash";
+const CONTEXT_KINDS = ["analysis-context", "run-activity", "working-memory"];
+/**
+ * A context record: a synthetic `user` message, and no host record, thus it opens no turn and the
+ * display does not show it.
+ */
+export function contextRecordMessage(kind, text) {
+    const hash = createHash("sha256").update(text).digest("hex");
+    return {
+        role: "user",
+        content: text,
+        providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true, [CONTEXT_KIND_KEY]: kind, [CONTEXT_HASH_KEY]: hash } },
+    };
+}
+function isContextKind(value) {
+    return CONTEXT_KINDS.some((kind) => kind === value);
+}
+/** The kind and the hash of a context record, or `undefined` for a message that is no record. */
+export function contextRecordOf(message) {
+    const harness = message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE];
+    const kind = harness?.[CONTEXT_KIND_KEY];
+    const hash = harness?.[CONTEXT_HASH_KEY];
+    if (typeof hash !== "string" || !isContextKind(kind))
+        return undefined;
+    return { kind, hash };
+}
 /**
  * Return a copy of `message` carrying the interruption marker in the harness namespace.
  *
@@ -80,7 +110,7 @@ export function isInterruptedMessage(message) {
  * It has to carry the `user` role because the wire format requires a user turn after a truncated
  * assistant message, but it is not user input, and the difference is load-bearing: a `user` message is
  * what OPENS a conversation turn, so an unmarked synthetic one reads as a spurious turn boundary —
- * splitting one turn into two for the token window and, worse, giving a tail-turn removal a cut point in
+ * splitting one turn into two for the view and, worse, giving a tail-turn removal a cut point in
  * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
  *
  * `content` takes prose or the parts of a user message, because a picture rides a file part and no
@@ -103,7 +133,7 @@ export function syntheticUserMessage(content) {
  * outcome, which the model should read on its next turn but which nobody said.
  *
  * Synthetic in every sense that matters to a turn-boundary reader ({@link isSyntheticUserMessage} is
- * true of it), so it cannot split a turn for the token window nor hand a tail retraction a mid-turn
+ * true of it), so it cannot split a turn for the view nor hand a tail retraction a mid-turn
  * cut point. It differs from {@link syntheticUserMessage} in exactly one respect, and it is the
  * decisive one: this is a fact the reader is entitled to see, so the display reconstruction emits it
  * — as a `system` message, which is what it is — rather than dropping it as loop machinery.
@@ -128,6 +158,52 @@ export function isSyntheticUserMessage(message) {
 export function isSyntheticRecordMessage(message) {
     return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[SYNTHETIC_RECORD_KEY] === true;
 }
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the compaction id on each message of its exchange, which the view rule skips. */
+export const COMPACTION_EXCHANGE_KEY = "compactionExchange";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key that holds the figures of a compaction marker, which the view rule reads. */
+export const COMPACTION_MARKER_KEY = "compactionMarker";
+const compactionFigures = { id: z.string(), tokensBefore: z.number(), tokensAfter: z.number(), durationMs: z.number() };
+const CompactionMarkerSchema = z.discriminatedUnion("kind", [
+    z.object({ kind: z.literal("summary"), ...compactionFigures }),
+    z.object({ kind: z.literal("drop"), ...compactionFigures, keptTurns: z.number() }),
+]);
+/** A copy of `message` whose harness namespace, which no provider reads, holds the compaction id. */
+export function markCompactionExchange(message, id) {
+    const existingOptions = message.providerOptions ?? {};
+    return {
+        ...message,
+        providerOptions: {
+            ...existingOptions,
+            [HARNESS_PROVIDER_NAMESPACE]: { ...existingOptions[HARNESS_PROVIDER_NAMESPACE], [COMPACTION_EXCHANGE_KEY]: id },
+        },
+    };
+}
+export function compactionExchangeOf(message) {
+    const id = message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[COMPACTION_EXCHANGE_KEY];
+    return typeof id === "string" ? id : undefined;
+}
+// A marker is synthetic, thus it opens no turn. It is no host record, because its divider shows it.
+function compactionMarkerMessage(text, marker) {
+    return {
+        role: "user",
+        content: text,
+        providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true, [COMPACTION_MARKER_KEY]: marker } },
+    };
+}
+export function summaryMarkerMessage(summary, marker) {
+    return compactionMarkerMessage(`[Conversation Summary]\n${summary}`, marker);
+}
+/** The marker of a compaction that gave no summary. No view holds it. */
+export function dropMarkerMessage(marker) {
+    return compactionMarkerMessage("[Compaction Failed]", marker);
+}
+export function compactionMarkerOf(message) {
+    const value = message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[COMPACTION_MARKER_KEY];
+    if (value === undefined)
+        return undefined;
+    const parsed = CompactionMarkerSchema.safeParse(value);
+    return parsed.success ? parsed.data : undefined;
+}
 function providerOptionsFromLegacy(block) {
     // A block may carry both a signed thinking signature and cache_control;
     // both are required for valid continuation, so both must survive.

package/dist/memory/conversation-display-recorder.d.ts

@@ -1,7 +1,13 @@
+import type { ModelMessage } from "ai";
 import type { EmitFn } from "../loop/types.js";
 import { type ConversationUIMessage } from "./conversation-display-storage.js";
 export interface ConversationDisplayRecorder {
     readonly emit: EmitFn;
+    /** The user message of the turn. */
+    takeOpening(): ConversationUIMessage[];
+    /** The assistant message of one round, when the recorder got parts after the last take, and the divider of a marker of the round. */
+    takeRound(messages: readonly ModelMessage[]): ConversationUIMessage[];
+    /** The whole turn in one projection. `runChatTurn` stores each round with `takeOpening` and `takeRound` instead. */
     finish(options?: {
         readonly fallbackText?: string;
         readonly interrupted?: boolean;