@inflexa-ai/harness 0.8.0 → 0.10.0

package/dist/agents/conversation-agent.js

@@ -32,7 +32,7 @@ import { createWorkingMemory } from "../memory/working-memory.js";
 import { conversationPrompt } from "../prompts/conversation.js";
 import { composeSystemPrompt } from "./system-prompt.js";
 // Bio-lookup leaf tools (pure — no dependencies).
-import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, createSearchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
+import { searchGeneTool, searchPathwayTool, lookupGoTermTool, searchInteractionsTool, chemblTool, pubchemTool, openTargetsTool, searchGwasCatalogTool, searchPharmgkbTool, searchFaersTool, searchClinicalTrialsTool, searchGeoDatasetsTool, createSearchDgidbTool, searchBgeeExpressionTool, getImpcKoProfileTool, checkSafetyPanelTool, } from "../tools/bio/index.js";
 import { createNcbiTools, createChemDbTools } from "../tools/bio/keys.js";
 // Dependency-bearing tool factories.
 import { createGeneratePlanTool, createLiteratureReviewerTool, createInspectRunTool, createInspectDataProfileTool, createGenerateAnalogyReportTool, } from "../tools/research/index.js";
@@ -68,6 +68,8 @@ export function createConversationAgent(deps) {
         pubchemTool,
         // Translational medicine.
         openTargetsTool,
+        // Genetic evidence — SNP-trait associations for target validation / MR support.
+        searchGwasCatalogTool,
         searchPharmgkbTool,
         searchFaersTool,
         searchClinicalTrialsTool,

package/dist/contracts/message.d.ts

@@ -33,4 +33,10 @@ export interface CortexMessage {
     id: string;
     role: "user" | "assistant" | "system";
     parts: CortexPart[];
+    /**
+     * Set when this message's production was cut off by a client abort, so the UI
+     * can badge it. Absent means not interrupted — the field is optional so every
+     * existing consumer is unaffected.
+     */
+    interrupted?: boolean;
 }

package/dist/execution/report-runner.d.ts

@@ -60,7 +60,12 @@ export interface ReportRunnerOptions {
     readonly previewId: string;
     /** Base version to iterate from. Defaults to latest. */
     readonly baseVersion?: number;
-    /** Report format. */
+    /**
+     * Format the preview was built as. The tool boundary admits only `"html"`,
+     * so no other value can reach a live iteration; the union stays wide because
+     * previews persisted with a broader vocabulary must still parse. Read this
+     * field as a record of what a preview is, not as a request for a renderer.
+     */
     readonly format: "html" | "pdf";
     /** Prompt for the report-builder agent. */
     readonly prompt: string;

package/dist/execution/report-runner.js

@@ -128,6 +128,7 @@ export async function runReportIteration(deps, opts) {
                 previews: opts.previews,
                 urlCell,
                 chrome: deps.chrome,
+                logger,
             }),
             ...createVersionFsTools({ versionDir: versionDirAbs }),
             ...Object.values(createSkillTools({ skillsDir: deps.skillsDir, skills: [...REPORT_BUILDER_SKILLS] })),

package/dist/execution/run-synthesis.d.ts

@@ -30,6 +30,13 @@ import type { ChatProvider } from "../providers/types.js";
 import type { RunSession } from "../auth/types.js";
 import { type Tool } from "../tools/define-tool.js";
 import type { BioToolKeys } from "../tools/bio/keys.js";
+/**
+ * The synthesizer's agent identity — the `source.agentId` on its loop events
+ * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
+ * to `cortex_step_executions`. One definition so the ledger row and the stream
+ * events can never disagree about who did the work.
+ */
+export declare const SYNTHESIS_AGENT_ID = "run-synthesizer";
 type SynthesizerOutcome = {
     kind: "submitted";
     synthesis: RunSynthesis;

package/dist/execution/run-synthesis.js

@@ -39,7 +39,13 @@ import { defineTool } from "../tools/define-tool.js";
 import { createReportBlockerToolFor } from "../tools/sandbox/report-blocker.js";
 import { createLiteratureReviewerTool } from "../tools/research/literature-reviewer.js";
 // ── Agent identity / budgets ────────────────────────────────────────
-const AGENT_ID = "run-synthesizer";
+/**
+ * The synthesizer's agent identity — the `source.agentId` on its loop events
+ * and the `agent_id` of the run-phase `synthesis` row `executeAnalysis` writes
+ * to `cortex_step_executions`. One definition so the ledger row and the stream
+ * events can never disagree about who did the work.
+ */
+export const SYNTHESIS_AGENT_ID = "run-synthesizer";
 /**
  * Budget for the synthesizer loop: read summaries + 1–3 reviewer delegations
  * + draft + 1–2 submit/fix cycles + headroom.
@@ -349,7 +355,7 @@ export async function generateRunSynthesis(input) {
     const blockerTool = buildBlockerTool(holder);
     const tools = [validateTool, submitTool, blockerTool, reviewer];
     const agent = {
-        id: AGENT_ID,
+        id: SYNTHESIS_AGENT_ID,
         systemPrompt: composeSystemPrompt(synthesisAgentPrompt),
         model: input.model,
         tools,

package/dist/index.d.ts

@@ -53,7 +53,7 @@ export type { PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult
 export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory } from "./memory/thread-history.js";
-export type { ThreadHistory, StoredMessage, MessagePage } from "./memory/thread-history.js";
+export type { ThreadHistory, StoredMessage, MessagePage, RetractOutcome } from "./memory/thread-history.js";
 export { contentToCortexMessages } from "./memory/content-to-cortex.js";
 export { createCardResolver } from "./memory/reconstruct-cards.js";
 export type { ToolCardResolver, StoredToolCallForCard } from "./memory/reconstruct-cards.js";

package/dist/loop/run-agent.d.ts

@@ -4,7 +4,7 @@ import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
 import { type AskApproval, type AskRequest } from "../tools/approval/contract.js";
 import type { AgentDefinition, EmitFn, LoopMessage, RunStep } from "./types.js";
 export interface AgentFinish {
-    readonly reason: FinishReason | "max_iterations" | "denied";
+    readonly reason: FinishReason | "aborted" | "max_iterations" | "denied";
     readonly cappedOut: boolean;
     readonly truncationRecoveries: number;
 }

package/dist/loop/run-agent.js

@@ -1,5 +1,6 @@
 import { jsonSchema, tool as aiTool } from "ai";
 import { hintForZodIssue, repairToolInput } from "../lib/zod-issues.js";
+import { markInterruptedMessage, syntheticUserMessage } from "../memory/ai-sdk-message-storage.js";
 import { classifyProviderError } from "../providers/errors.js";
 import { DEFAULT_PROMPT_CACHE, promptCacheProviderOptions } from "../providers/prompt-cache.js";
 import { resultStep } from "./run-step.js";
@@ -72,13 +73,31 @@ export async function runAgent(agent, initial, session, opts) {
         };
         const reply = await resultStep(runStep)(formatStepName.llm(i), () => provider.chat(request, session, signal));
         addChatUsage(usage, reply.usage);
-        messages.push(reply.message);
+        if (reply.finishReason === "aborted") {
+            // An interrupted turn keeps whatever the model produced before the cut, but
+            // never an empty shell: a partial with no content adds no message, so a
+            // no-output abort leaves the transcript at the initial prefix. The marker
+            // then rides the last assistant message this run produced — the partial when
+            // it has content, or the tool-calling step when the abort landed mid-dispatch
+            // — an assistant role no turn-boundary reader observes. "aborted" is not
+            // "tool-calls", so this falls into the terminal return below.
+            if (assistantHasContent(reply.message))
+                messages.push(reply.message);
+            markLastLoopAssistant(messages, initial.length);
+        }
+        else {
+            messages.push(reply.message);
+        }
         const toolCalls = toolCallParts(reply.message);
         if (reply.finishReason === "length") {
             truncationRecoveries++;
             await emit({ type: "iteration", source, index: i, final: false });
             if (toolCalls.length === 0) {
-                messages.push({ role: "user", content: TRUNCATED_PROSE_STEER });
+                // Stamped synthetic, not left as a bare `user` message: the wire format needs a user turn
+                // after a truncated assistant message, but this one is the loop's own nudge, and thread
+                // storage treats a genuine `user` message as the start of a conversation turn. Unmarked, it
+                // would split this turn in two everywhere that boundary is read.
+                messages.push(syntheticUserMessage(TRUNCATED_PROSE_STEER));
                 continue;
             }
             const trailing = toolCalls[toolCalls.length - 1];
@@ -135,6 +154,20 @@ export async function runAgent(agent, initial, session, opts) {
     // cache_write_tokens counter is what makes that waste visible.
     const wrapUp = await resultStep(runStep)(formatStepName.llm(agent.maxIterations), () => provider.chat({ system: agent.systemPrompt, messages, tools: {}, toolChoice: "none", providerOptions }, session, signal));
     addChatUsage(usage, wrapUp.usage);
+    if (wrapUp.finishReason === "aborted") {
+        // An abort during the tool-less wrap-up is still the user cutting the turn — the
+        // same event the in-loop path handles — so it gets the identical treatment: keep a
+        // partial only when it carries content, and stamp the marker on the last assistant
+        // this run produced. Reporting it as a plain cap-out would hide the interruption
+        // from every downstream reader; `cappedOut` stays true because the loop genuinely
+        // exhausted its iterations, while the reason carries the abort.
+        if (assistantHasContent(wrapUp.message))
+            messages.push(wrapUp.message);
+        markLastLoopAssistant(messages, initial.length);
+        await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
+        recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
+        return { messages, finish: { reason: "aborted", cappedOut: true, truncationRecoveries } };
+    }
     messages.push(wrapUp.message);
     await emit({ type: "iteration", source, index: agent.maxIterations, final: true });
     recordAgentRun({ agentId: agent.id, iterations, cappedOut: true, usage });
@@ -145,6 +178,26 @@ function toolCallParts(message) {
         return [];
     return message.content.filter((part) => part.type === "tool-call");
 }
+/** Whether an aborted partial carries any content worth persisting — an empty partial contributes no message. */
+function assistantHasContent(message) {
+    return message.content.length > 0;
+}
+/**
+ * Stamp the interruption marker on the last assistant message the loop produced
+ * this run — an index at or beyond the `initial` prefix — replacing the slot with
+ * a marked copy so the mark rides into `appendTurn` and the stored row. When the
+ * turn produced no assistant message beyond `initial` (a no-output abort on a
+ * fresh turn), there is nothing to mark and the transcript is left untouched.
+ */
+function markLastLoopAssistant(messages, initialCount) {
+    for (let idx = messages.length - 1; idx >= initialCount; idx--) {
+        const message = messages[idx];
+        if (message.role === "assistant") {
+            messages[idx] = markInterruptedMessage(message);
+            return;
+        }
+    }
+}
 async function dispatchTools(toolUses, toolsById, toolCtx, isFatalLoopError, runStep, toolStepName) {
     const results = new Array(toolUses.length);
     const stepTools = [];

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

@@ -9,6 +9,48 @@ export declare const StoredMessageEnvelopeSchema: z.ZodObject<{
 export type StoredMessageEnvelope = z.infer<typeof StoredMessageEnvelopeSchema>;
 export declare function envelopeMessage(message: ModelMessage): StoredMessageEnvelope;
 export declare function parseStoredMessageEnvelope(value: unknown, identity: string): StoredMessageEnvelope;
+/**
+ * The `providerOptions` namespace the harness stamps its OWN message metadata into.
+ *
+ * A provider SDK reads only its own namespace (`anthropic`, `openai`, …) and ignores every other key, so
+ * a harness-owned namespace rides to the wire and back untouched; `modelMessageSchema` validates
+ * `providerOptions` structurally rather than against a list of known namespaces, so it also survives the
+ * storage envelope round-trip. That round-trip is the whole reason the marker lives here rather than on
+ * the envelope: readers of STORED rows need it, and `ModelMessage` offers no other field able to carry a
+ * harness fact from the loop, through `appendTurn`, into a row.
+ */
+export declare const HARNESS_PROVIDER_NAMESPACE = "cortex";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key marking a message the loop synthesized rather than one a human sent. */
+export declare const SYNTHETIC_MESSAGE_KEY = "synthetic";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key marking an assistant message whose production a client abort cut off. */
+export declare const INTERRUPTED_MESSAGE_KEY = "interrupted";
+/**
+ * Return a copy of `message` carrying the interruption marker in the harness namespace.
+ *
+ * The marker lives in {@link HARNESS_PROVIDER_NAMESPACE} for the same reason the synthetic marker does:
+ * it is the only field of a `ModelMessage` that survives the loop → {@link envelopeMessage} → stored-row
+ * round trip, so a reader of stored rows can still tell an interrupted reply apart. It rides the
+ * **assistant** role, which is not a turn boundary, so no boundary reader (`isGenuineUserStart`, the
+ * tail-retract predicate, window snapping) can observe it. Any existing `providerOptions` namespace is
+ * preserved — a signed thinking signature or cache directive on the same message must not be dropped — so
+ * this merges into the harness namespace rather than replacing the whole `providerOptions`.
+ */
+export declare function markInterruptedMessage(message: ModelMessage): ModelMessage;
+/** Whether a client abort cut off this message's production (see {@link markInterruptedMessage}); an absent key reads as not interrupted. */
+export declare function isInterruptedMessage(message: ModelMessage): boolean;
+/**
+ * Build a `user` message the agent loop synthesized — today, the nudge that continues a reply the model
+ * truncated at its output-token limit.
+ *
+ * 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
+ * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
+ */
+export declare function syntheticUserMessage(text: string): ModelMessage;
+/** Whether the loop synthesized this message (see {@link syntheticUserMessage}) rather than a human sending it. */
+export declare function isSyntheticUserMessage(message: ModelMessage): boolean;
 type LegacyContent = string | Array<Record<string, unknown>>;
 export interface LegacyMessageRow {
     readonly threadId: string;

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

@@ -20,6 +20,68 @@ export function parseStoredMessageEnvelope(value, identity) {
     }
     return parsed.data;
 }
+/**
+ * The `providerOptions` namespace the harness stamps its OWN message metadata into.
+ *
+ * A provider SDK reads only its own namespace (`anthropic`, `openai`, …) and ignores every other key, so
+ * a harness-owned namespace rides to the wire and back untouched; `modelMessageSchema` validates
+ * `providerOptions` structurally rather than against a list of known namespaces, so it also survives the
+ * storage envelope round-trip. That round-trip is the whole reason the marker lives here rather than on
+ * the envelope: readers of STORED rows need it, and `ModelMessage` offers no other field able to carry a
+ * harness fact from the loop, through `appendTurn`, into a row.
+ */
+export const HARNESS_PROVIDER_NAMESPACE = "cortex";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key marking a message the loop synthesized rather than one a human sent. */
+export const SYNTHETIC_MESSAGE_KEY = "synthetic";
+/** The {@link HARNESS_PROVIDER_NAMESPACE} key marking an assistant message whose production a client abort cut off. */
+export const INTERRUPTED_MESSAGE_KEY = "interrupted";
+/**
+ * Return a copy of `message` carrying the interruption marker in the harness namespace.
+ *
+ * The marker lives in {@link HARNESS_PROVIDER_NAMESPACE} for the same reason the synthetic marker does:
+ * it is the only field of a `ModelMessage` that survives the loop → {@link envelopeMessage} → stored-row
+ * round trip, so a reader of stored rows can still tell an interrupted reply apart. It rides the
+ * **assistant** role, which is not a turn boundary, so no boundary reader (`isGenuineUserStart`, the
+ * tail-retract predicate, window snapping) can observe it. Any existing `providerOptions` namespace is
+ * preserved — a signed thinking signature or cache directive on the same message must not be dropped — so
+ * this merges into the harness namespace rather than replacing the whole `providerOptions`.
+ */
+export function markInterruptedMessage(message) {
+    const existingOptions = message.providerOptions ?? {};
+    const existingHarness = existingOptions[HARNESS_PROVIDER_NAMESPACE] ?? {};
+    return {
+        ...message,
+        providerOptions: {
+            ...existingOptions,
+            [HARNESS_PROVIDER_NAMESPACE]: { ...existingHarness, [INTERRUPTED_MESSAGE_KEY]: true },
+        },
+    };
+}
+/** Whether a client abort cut off this message's production (see {@link markInterruptedMessage}); an absent key reads as not interrupted. */
+export function isInterruptedMessage(message) {
+    return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[INTERRUPTED_MESSAGE_KEY] === true;
+}
+/**
+ * Build a `user` message the agent loop synthesized — today, the nudge that continues a reply the model
+ * truncated at its output-token limit.
+ *
+ * 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
+ * the middle of a turn. Marking it is what lets {@link isSyntheticUserMessage} keep those readers honest.
+ */
+export function syntheticUserMessage(text) {
+    return {
+        role: "user",
+        content: text,
+        providerOptions: { [HARNESS_PROVIDER_NAMESPACE]: { [SYNTHETIC_MESSAGE_KEY]: true } },
+    };
+}
+/** Whether the loop synthesized this message (see {@link syntheticUserMessage}) rather than a human sending it. */
+export function isSyntheticUserMessage(message) {
+    return message.providerOptions?.[HARNESS_PROVIDER_NAMESPACE]?.[SYNTHETIC_MESSAGE_KEY] === true;
+}
 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/content-to-cortex.d.ts

@@ -25,9 +25,11 @@ import type { ToolCardResolver } from "./reconstruct-cards.js";
 import type { StoredMessage } from "./thread-history.js";
 /**
  * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
- * no renderable parts are dropped, and consecutive same-role rows are coalesced
+ * no renderable parts are dropped, and consecutive assistant rows are coalesced
  * into one message. The first row's `seq` becomes the stable message id.
  * `resolveCard` (optional) reconstructs display cards from `tool_use` blocks.
+ * A row carrying the interruption marker sets `interrupted: true` on the message
+ * it lands in, including when coalesced into an assistant run.
  *
  * Coalescing mirrors the live SSE shape. The agent loop persists each assistant
  * step (typically a single `tool_use`) as its own row, and the `tool_result`
@@ -38,5 +40,10 @@ import type { StoredMessage } from "./thread-history.js";
  * tool call, which the UI renders as a stack of single-tool boxes. Merging the
  * run restores the one-bubble-per-turn shape (and lets the UI collapse the tool
  * calls into one group) regardless of how the loop split the turn into rows.
+ *
+ * Coalescing is assistant-only. User rows never legitimately split into a run —
+ * adjacent `user` rows arise only from turns that persisted no reply (an aborted
+ * turn's lone user message followed by the next turn's), and merging them would
+ * fabricate one bubble from two messages the user sent separately.
  */
 export declare function contentToCortexMessages(messages: readonly StoredMessage[], resolveCard?: ToolCardResolver): Promise<CortexMessage[]>;

package/dist/memory/content-to-cortex.js

@@ -20,6 +20,7 @@
  * only tool-result continuation parts) is omitted entirely, so the rendered
  * conversation has no empty bubbles. Storage is never mutated.
  */
+import { isInterruptedMessage, isSyntheticUserMessage } from "./ai-sdk-message-storage.js";
 function genericToolCall(block) {
     return {
         type: "tool-call",
@@ -53,9 +54,11 @@ async function rowToParts(message, resolveCard) {
 }
 /**
  * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
- * no renderable parts are dropped, and consecutive same-role rows are coalesced
+ * no renderable parts are dropped, and consecutive assistant rows are coalesced
  * into one message. The first row's `seq` becomes the stable message id.
  * `resolveCard` (optional) reconstructs display cards from `tool_use` blocks.
+ * A row carrying the interruption marker sets `interrupted: true` on the message
+ * it lands in, including when coalesced into an assistant run.
  *
  * Coalescing mirrors the live SSE shape. The agent loop persists each assistant
  * step (typically a single `tool_use`) as its own row, and the `tool_result`
@@ -66,20 +69,49 @@ async function rowToParts(message, resolveCard) {
  * tool call, which the UI renders as a stack of single-tool boxes. Merging the
  * run restores the one-bubble-per-turn shape (and lets the UI collapse the tool
  * calls into one group) regardless of how the loop split the turn into rows.
+ *
+ * Coalescing is assistant-only. User rows never legitimately split into a run —
+ * adjacent `user` rows arise only from turns that persisted no reply (an aborted
+ * turn's lone user message followed by the next turn's), and merging them would
+ * fabricate one bubble from two messages the user sent separately.
  */
 export async function contentToCortexMessages(messages, resolveCard) {
     const out = [];
     for (const message of messages) {
+        // The loop's truncation nudge carries the `user` role only for the wire
+        // format; rendering it would show words the user never typed, so drop it.
+        // Skipping first is safe: a synthetic user message can never carry the
+        // interruption marker — that rides assistant rows — so this cannot interact
+        // with the marker-fold logic below. The assistant rows it separated then
+        // become adjacent and coalesce into one bubble, which is the shape we want.
+        if (isSyntheticUserMessage(message.message))
+            continue;
         const parts = await rowToParts(message.message, resolveCard);
-        if (parts.length === 0)
+        // The marker is read before the zero-parts drop so the flag can never be lost to it:
+        // a marked row carries an interruption fact regardless of whether it renders any parts.
+        // When such a row contributes no bubble of its own, the interruption belongs to the
+        // assistant run it trailed, so fold the flag onto the previous emitted assistant.
+        const interrupted = isInterruptedMessage(message.message);
+        if (parts.length === 0) {
+            if (interrupted) {
+                const prev = out[out.length - 1];
+                if (prev && prev.role === "assistant")
+                    prev.interrupted = true;
+            }
             continue;
+        }
         const role = message.message.role === "tool" ? "assistant" : message.message.role;
         const prev = out[out.length - 1];
-        if (prev && prev.role === role) {
+        if (prev && prev.role === role && role === "assistant") {
             prev.parts.push(...parts);
+            if (interrupted)
+                prev.interrupted = true;
             continue;
         }
-        out.push({ id: String(message.seq), role, parts });
+        const cortex = { id: String(message.seq), role, parts };
+        if (interrupted)
+            cortex.interrupted = true;
+        out.push(cortex);
     }
     return out;
 }

package/dist/memory/thread-history.d.ts

@@ -43,6 +43,21 @@ export interface MessagePage {
     readonly perPage: number;
     readonly hasMore: boolean;
 }
+/**
+ * The result of `retractLastTurn`. `retracted` carries `messages` — the number
+ * of rows removed — so a caller can assert exactly what came off the tail. The
+ * other two variants delete nothing and are distinct on purpose: `empty-thread`
+ * had no rows at all, while `no-user-turn` had rows but none opening a turn —
+ * anomalous data refused rather than silently emptied.
+ */
+export type RetractOutcome = {
+    kind: "retracted";
+    messages: number;
+} | {
+    kind: "empty-thread";
+} | {
+    kind: "no-user-turn";
+};
 /**
  * The conversation message store. Two methods, by design — no generic row
  * insert (see the harness-thread-store spec). `threadId` is the conversation scope — one UI thread.
@@ -69,6 +84,28 @@ export interface ThreadHistory {
      * holds the flattened rows of the selected turns.
      */
     loadPage(threadId: string, page: number, perPage: number): ResultAsync<MessagePage, DbError>;
+    /**
+     * Remove the thread's most recent turn — every row from the last
+     * genuine-user-start `seq` onward — in a single transaction.
+     *
+     * Tail-only by design: removal cuts at the last genuine-user-start `seq` —
+     * a turn boundary, not the last append. Because every conversation turn
+     * opens with the user's message, that boundary starts the most recent turn,
+     * so removing it restores the row set the thread held before that turn and
+     * leaves `loadRecent`'s byte-stable prompt-cache prefix untouched; an
+     * out-of-contract assistant-only follow-up append carries no user-start row
+     * and so folds into the removed tail, exactly as the read side's turn
+     * grouping folds it. Deleting mid-history would shift the window head and
+     * rewrite that prefix, so it is deliberately not offered — only the tail
+     * can come off.
+     *
+     * Callers are assumed single-writer per thread (the host serializes turns);
+     * the outcome's `messages` count lets a caller assert exactly what was
+     * removed. A thread that has rows but no genuine-user-start row is anomalous
+     * data — refused as `no-user-turn` with nothing deleted, never emptied. An
+     * empty thread reports `empty-thread`.
+     */
+    retractLastTurn(threadId: string): ResultAsync<RetractOutcome, DbError>;
 }
 /**
  * Drop the memoized instruments so the next `loadRecent` rebinds to a

package/dist/memory/thread-history.js

@@ -21,22 +21,46 @@
  * rounds the budget walk to turn boundaries.
  */
 import { metrics } from "@opentelemetry/api";
-import { ResultAsync, ok } from "neverthrow";
+import { ResultAsync, ok, okAsync } from "neverthrow";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
 import { countTokens } from "./count-tokens.js";
-import { envelopeMessage, parseStoredMessageEnvelope } from "./ai-sdk-message-storage.js";
+import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, isSyntheticUserMessage, parseStoredMessageEnvelope, } from "./ai-sdk-message-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
 function okVoid() {
     return new ResultAsync(Promise.resolve(ok(undefined)));
 }
 /**
- * A turn starts on a `user` message. In AI SDK message terms tool results
- * are `tool`-role messages, so a mid-turn tool continuation never carries
- * the `user` role and cannot open a turn.
+ * A turn starts on a `user` message that a human actually sent. Two kinds of
+ * message carry the `user` role without opening a turn, and both are excluded
+ * here:
+ *
+ * - a tool result, which in AI SDK terms is a `tool`-role message, so a mid-turn
+ *   tool continuation never matches in the first place;
+ * - a message the LOOP synthesized mid-turn — the truncated-reply nudge
+ *   (`syntheticUserMessage`) — which must carry the `user` role for the wire
+ *   format but is not user input. Reading it as a boundary would split one turn
+ *   into two: the token window would evict half a turn, and `retractLastTurn`
+ *   would cut its tail in the middle of a turn rather than at its head.
+ *
+ * {@link GENUINE_USER_START_SQL} is the twin of this predicate over stored
+ * envelopes; the two are built from the same constants so they cannot drift.
  */
 function isGenuineUserStart(message) {
-    return message.role === "user";
+    return message.role === "user" && !isSyntheticUserMessage(message);
 }
+/**
+ * {@link isGenuineUserStart} expressed over a stored `message_envelope` — the
+ * boundary predicate `retractLastTurn` cuts on.
+ *
+ * Interpolating here, and only here, is safe: both interpolated values are
+ * module constants shared with the TypeScript predicate, never caller input, so
+ * there is no injection surface — and a bound parameter cannot express a JSON
+ * path anyway. `IS DISTINCT FROM` (not `<> 'true'`) because `->>` yields NULL on
+ * every message that carries no `providerOptions` at all, which is nearly all of
+ * them; a plain inequality would discard them.
+ */
+const GENUINE_USER_START_SQL = `message_envelope->'message'->>'role' = 'user'
+                         AND message_envelope->'message'->'providerOptions'->'${HARNESS_PROVIDER_NAMESPACE}'->>'${SYNTHETIC_MESSAGE_KEY}' IS DISTINCT FROM 'true'`;
 /**
  * Group rows (oldest-first) into turns at genuine-user-start boundaries.
  * Generic over the row shape so the token-windowed read (`loadRecent`) and
@@ -223,5 +247,48 @@ export function createThreadHistory(pool) {
             };
         });
     }
-    return { appendTurn, loadRecent, loadPage };
+    function retractLastTurn(threadId) {
+        return withTransaction(pool, "thread-history.retractLastTurn", (client) => 
+        // Take the SAME per-thread advisory lock `appendTurn` takes, and take it
+        // FIRST — a retract and an append on one thread must never interleave, or
+        // the retract could read a boundary mid-append and delete only part of a
+        // turn still being written. Serialized on this lock it always sees a whole
+        // turn or none of one. Released automatically at COMMIT/ROLLBACK.
+        tryQuery("thread-history.retractLastTurn.lock", () => client.query("SELECT pg_advisory_xact_lock(hashtext($1))", [threadId]))
+            .andThen(() => 
+        // Locate the tail turn's opening row and, in the same read, learn
+        // whether the thread has any rows at all. The boundary is the greatest
+        // `seq` matching `GENUINE_USER_START_SQL` — the stored-envelope twin of
+        // `isGenuineUserStart`, so a `tool`-role continuation and a
+        // loop-synthesized nudge are both excluded and the cut lands on a real
+        // turn head. The coupling is test-guarded: an append-then-retract
+        // round-trip fails loudly (the just-appended turn reads back as
+        // `no-user-turn` instead of `retracted`) the moment this envelope path
+        // drifts from what `isGenuineUserStart` reads on the live message.
+        // `has_rows` separates the two nothing-to-delete cases: an empty thread
+        // (`empty-thread`) from one holding no turn-opening row at all
+        // (`no-user-turn`, anomalous data we refuse rather than empty).
+        // `MAX(seq)` aggregates the bigint column; the `::text` cast is
+        // transport only, so no comparison ever runs against a text projection —
+        // and the boundary rides back as text so a seq beyond 2^53 survives
+        // without float rounding.
+        tryQuery("thread-history.retractLastTurn.boundary", async () => {
+            const { rows } = await client.query(`SELECT EXISTS(SELECT 1 FROM messages WHERE thread_id = $1) AS has_rows,
+                    (SELECT MAX(seq)::text FROM messages
+                       WHERE thread_id = $1
+                         AND ${GENUINE_USER_START_SQL}) AS boundary`, [threadId]);
+            return rows[0];
+        }))
+            .andThen(({ has_rows, boundary }) => {
+            if (!has_rows)
+                return okAsync({ kind: "empty-thread" });
+            if (boundary === null)
+                return okAsync({ kind: "no-user-turn" });
+            // Delete the whole tail turn: every row at or past the boundary seq.
+            // `$2::bigint` compares the bigint column against a bigint, never a
+            // text projection, keeping the comparison exact for large seqs.
+            return tryMutation("thread-history.retractLastTurn.delete", () => client.query("DELETE FROM messages WHERE thread_id = $1 AND seq >= $2::bigint", [threadId, boundary])).map((res) => ({ kind: "retracted", messages: res.rowCount ?? 0 }));
+        }));
+    }
+    return { appendTurn, loadRecent, loadPage, retractLastTurn };
 }