@inflexa-ai/harness 0.14.2 → 0.15.1

package/dist/memory/content-to-cortex.d.ts

@@ -14,22 +14,46 @@
  *
  * Display cards are emitted live over the chat SSE stream but never persisted
  * (storage holds only the AI SDK model-message transcript). `resolveCard`
- * rebuilds them from the persisted tool-call part so they reappear on reload.
+ * rebuilds them from the persisted tool-call part so they reappear on reload,
+ * and `resolveDetail` rebuilds each call's one-line detail the same way.
+ *
+ * A `tool-result` block is not rendered, but it is not ignored either: it is the
+ * only record of how its call ended. The blocks are indexed by `toolCallId`
+ * before conversion so each tool-call part can report its own outcome — without
+ * that pass every reloaded call reported success, including the failed ones.
  *
  * A row that yields no renderable parts (e.g. a `tool`-role message carrying
  * only tool-result continuation parts) is omitted entirely, so the rendered
  * conversation has no empty bubbles. Storage is never mutated.
  */
 import type { CortexMessage } from "@inflexa-ai/harness/contracts/message.js";
+import type { ToolDetailResolver } from "../tools/detail-resolver.js";
 import type { ToolCardResolver } from "./reconstruct-cards.js";
 import type { StoredMessage } from "./thread-history.js";
+/**
+ * The resolvers a caller may supply, as one object.
+ *
+ * An options bag rather than a growing positional list: both are optional, both
+ * are function-typed, and a second positional parameter of the same shape is a
+ * call site that silently does the wrong thing when the two are swapped.
+ */
+export interface ContentToCortexOptions {
+    /** Rebuilds a display card (`data-plan`, `data-presentation`) from a persisted tool call. */
+    readonly resolveCard?: ToolCardResolver;
+    /** Rebuilds a call's one-line detail from its tool name and persisted input. */
+    readonly resolveDetail?: ToolDetailResolver;
+}
 /**
  * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
  * 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.
+ * `options.resolveCard` reconstructs display cards from `tool_use` blocks and
+ * `options.resolveDetail` reconstructs each call's one-line detail; both are
+ * optional and each tool-call part reports its outcome either way.
  * A row carrying the interruption marker sets `interrupted: true` on the message
- * it lands in, including when coalesced into an assistant run.
+ * it lands in, including when coalesced into an assistant run; a row carrying a
+ * stored turn rollup sets `usage` the same way, so a reloaded conversation shows
+ * the cost the live turn showed without a second query.
  *
  * 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`
@@ -46,4 +70,4 @@ import type { StoredMessage } from "./thread-history.js";
  * 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[]>;
+export declare function contentToCortexMessages(messages: readonly StoredMessage[], options?: ContentToCortexOptions): Promise<CortexMessage[]>;

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

@@ -14,39 +14,74 @@
  *
  * Display cards are emitted live over the chat SSE stream but never persisted
  * (storage holds only the AI SDK model-message transcript). `resolveCard`
- * rebuilds them from the persisted tool-call part so they reappear on reload.
+ * rebuilds them from the persisted tool-call part so they reappear on reload,
+ * and `resolveDetail` rebuilds each call's one-line detail the same way.
+ *
+ * A `tool-result` block is not rendered, but it is not ignored either: it is the
+ * only record of how its call ended. The blocks are indexed by `toolCallId`
+ * before conversion so each tool-call part can report its own outcome — without
+ * that pass every reloaded call reported success, including the failed ones.
  *
  * A row that yields no renderable parts (e.g. a `tool`-role message carrying
  * only tool-result continuation parts) is omitted entirely, so the rendered
  * conversation has no empty bubbles. Storage is never mutated.
  */
+import { toolOutcomeForOutputType } from "../loop/tool-outcome.js";
 import { isInterruptedMessage, isSyntheticRecordMessage, isSyntheticUserMessage } from "./ai-sdk-message-storage.js";
-function genericToolCall(block) {
+/**
+ * How each stored call ended, keyed by tool-call id.
+ *
+ * A whole page is indexed before conversion because the pairing crosses rows: a
+ * call rides an `assistant` row and its result rides the `tool` row after it.
+ */
+function indexOutcomes(messages) {
+    const outcomes = new Map();
+    for (const { message } of messages) {
+        const content = message.content;
+        if (typeof content === "string")
+            continue;
+        for (const block of content) {
+            if (block.type !== "tool-result")
+                continue;
+            outcomes.set(block.toolCallId, toolOutcomeForOutputType(block.output.type));
+        }
+    }
+    return outcomes;
+}
+function genericToolCall(block, outcomes, resolveDetail) {
+    // No paired result is the shape of a transcript whose `tool` row was never
+    // appended (an aborted turn). Nothing failed, so `ok` is the honest report.
+    const outcome = outcomes.get(block.toolCallId) ?? "ok";
+    const detail = resolveDetail?.(block.toolName, block.input);
     return {
         type: "tool-call",
         toolCallId: block.toolCallId,
         toolName: block.toolName,
         status: "finished",
+        outcome,
+        ...(detail === undefined ? {} : { detail }),
     };
 }
-async function blockToPart(block, resolveCard) {
+async function blockToPart(block, outcomes, options) {
     if (block.type === "text")
         return { type: "text", text: block.text };
     if (block.type === "tool-call") {
-        const card = resolveCard ? await resolveCard({ type: "tool_use", id: block.toolCallId, name: block.toolName, input: block.input }) : null;
-        return card ?? genericToolCall(block);
+        const card = options.resolveCard
+            ? await options.resolveCard({ type: "tool_use", id: block.toolCallId, name: block.toolName, input: block.input })
+            : null;
+        return card ?? genericToolCall(block, outcomes, options.resolveDetail);
     }
     // reasoning, tool_result, file, and any other block — not rendered.
     return null;
 }
-async function rowToParts(message, resolveCard) {
+async function rowToParts(message, outcomes, options) {
     const content = message.content;
     if (typeof content === "string") {
         return content.length > 0 ? [{ type: "text", text: content }] : [];
     }
     const parts = [];
     for (const block of content) {
-        const part = await blockToPart(block, resolveCard);
+        const part = await blockToPart(block, outcomes, options);
         if (part)
             parts.push(part);
     }
@@ -56,9 +91,13 @@ async function rowToParts(message, resolveCard) {
  * Map stored messages (oldest-first) to `CortexMessage[]`. Rows that produce
  * 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.
+ * `options.resolveCard` reconstructs display cards from `tool_use` blocks and
+ * `options.resolveDetail` reconstructs each call's one-line detail; both are
+ * optional and each tool-call part reports its outcome either way.
  * A row carrying the interruption marker sets `interrupted: true` on the message
- * it lands in, including when coalesced into an assistant run.
+ * it lands in, including when coalesced into an assistant run; a row carrying a
+ * stored turn rollup sets `usage` the same way, so a reloaded conversation shows
+ * the cost the live turn showed without a second query.
  *
  * 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`
@@ -75,7 +114,8 @@ async function rowToParts(message, resolveCard) {
  * 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) {
+export async function contentToCortexMessages(messages, options = {}) {
+    const outcomes = indexOutcomes(messages);
     const out = [];
     for (const message of messages) {
         // The loop's truncation nudge carries the `user` role only for the wire
@@ -94,17 +134,25 @@ export async function contentToCortexMessages(messages, resolveCard) {
         const isRecord = isSyntheticRecordMessage(message.message);
         if (isSyntheticUserMessage(message.message) && !isRecord)
             continue;
-        const parts = await rowToParts(message.message, resolveCard);
+        const parts = await rowToParts(message.message, outcomes, options);
         // 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")
+            // A row's stored rollup is a fact about the turn, not about what the row
+            // renders — so like the interruption marker it is read before the
+            // zero-parts drop and folded onto the assistant run it trailed. Without
+            // this, a turn whose last assistant row held only unrendered blocks
+            // (reasoning alone) would lose the figure to the drop, which is the exact
+            // disappearance persisting it exists to fix.
+            const prev = out[out.length - 1];
+            if (prev && prev.role === "assistant") {
+                if (interrupted)
                     prev.interrupted = true;
+                if (message.usage)
+                    prev.usage = message.usage;
             }
             continue;
         }
@@ -122,11 +170,19 @@ export async function contentToCortexMessages(messages, resolveCard) {
             prev.parts.push(...parts);
             if (interrupted)
                 prev.interrupted = true;
+            // Coalescing is what rebuilds the one-bubble-per-turn shape, and the rollup
+            // rides the turn's LAST assistant row — so the run keeps whichever of its
+            // rows carried one. Assigning rather than merging is deliberate: two rollups
+            // in one run would mean two turns were merged, which coalescing never does.
+            if (message.usage)
+                prev.usage = message.usage;
             continue;
         }
         const cortex = { id: String(message.seq), role, parts };
         if (interrupted)
             cortex.interrupted = true;
+        if (message.usage)
+            cortex.usage = message.usage;
         out.push(cortex);
     }
     return out;

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

@@ -23,6 +23,7 @@
 import type { ModelMessage } from "ai";
 import { ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
+import type { TokenUsageRollup } from "../contracts/usage.js";
 import { type DbError } from "../lib/db-result.js";
 import { type StoredMessageEnvelope } from "./ai-sdk-message-storage.js";
 /** One stored message, as returned by the display read (`loadPage`). */
@@ -30,6 +31,15 @@ export interface StoredMessage {
     readonly seq: number;
     readonly envelope: StoredMessageEnvelope;
     readonly message: ModelMessage;
+    /**
+     * What providers reported for the whole TURN this row completed — present
+     * only on the last assistant row of a turn appended with a rollup, absent
+     * everywhere else. Not a per-row figure, and unrelated to the `tokens` count
+     * `loadRecent` windows by: that is an offline estimate stamped on every row,
+     * this is a provider's own report (see the `reported_usage` column comment in
+     * the state-init DDL).
+     */
+    readonly usage?: TokenUsageRollup;
 }
 /**
  * A page of stored messages plus pagination metadata. Pagination is
@@ -66,8 +76,18 @@ export interface ThreadHistory {
     /**
      * Append one conversation turn — every message written in a single
      * transaction with a `seq` monotonically increasing per thread.
+     *
+     * `turnUsage` is the turn's reported rollup, as `AgentFinish.turnUsage`
+     * carries it out of the loop and the `finish` event carries it to a live
+     * surface. It is stored on the LAST assistant message of the turn — the row a
+     * reader associates with the reply — so a reloaded transcript renders the
+     * figure the live turn showed. Optional at every layer: omitting it, and
+     * supplying one that reports no quantity at all, both leave the row without
+     * one, because a turn that reported nothing must not read back as a turn that
+     * cost zero. A turn writing no assistant message stores none and still
+     * succeeds — there is no row on which the figure would mean anything.
      */
-    appendTurn(threadId: string, messages: readonly ModelMessage[]): ResultAsync<void, DbError>;
+    appendTurn(threadId: string, messages: readonly ModelMessage[], turnUsage?: TokenUsageRollup): ResultAsync<void, DbError>;
     /**
      * Return a recent-turns window that fits `tokenBudget`, oldest-first,
      * snapped to a valid AI SDK model-message sequence. The window START advances

package/dist/memory/thread-history.js

@@ -24,6 +24,7 @@ import { metrics } from "@opentelemetry/api";
 import { ResultAsync, ok, okAsync } from "neverthrow";
 import { stripNulCharacters } from "../input-sanitization.js";
 import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
+import { hasReportedUsage } from "../loop/metrics.js";
 import { countTokens } from "./count-tokens.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. */
@@ -155,9 +156,20 @@ export const EVICTION_BLOCK_TURNS = 4;
  * provisioned by the project's state-init DDL.
  */
 export function createThreadHistory(pool) {
-    function appendTurn(threadId, messages) {
+    function appendTurn(threadId, messages, turnUsage) {
         if (messages.length === 0)
             return okVoid();
+        // A rollup that reports no quantity is stored as absent, not as a rollup of
+        // absences, so "no figure" has exactly one representation in storage.
+        // `hasReportedUsage` is the loop's own predicate for the same question,
+        // reused rather than restated so the write and the loop cannot drift.
+        const rollup = hasReportedUsage(turnUsage) ? JSON.stringify(turnUsage) : null;
+        // The rollup describes the turn, and the assistant reply is the row a reader
+        // associates with the answer. The LAST assistant row, not any of them: a
+        // serial-tool turn writes one assistant row per step and only the last ends
+        // the turn. -1 (a turn that persisted no reply — an abort before any output)
+        // matches no index below, so nothing is written and the append still succeeds.
+        const rollupRow = messages.reduce((last, m, i) => (m.role === "assistant" ? i : last), -1);
         return withTransaction(pool, "thread-history.appendTurn", (client) => 
         // Serialize concurrent appends on this thread — without the lock, two
         // transactions can both read the same MAX(seq) and collide on the
@@ -173,12 +185,14 @@ export function createThreadHistory(pool) {
         // re-throws it to force ROLLBACK (a returned `err` that does not
         // reach `withTransaction` would COMMIT silently).
         messages.reduce((chain, message, i) => chain.andThen(() => tryMutation("thread-history.appendTurn.insert", () => client.query(
-        // `::json`, never `::jsonb` — see the column comment in the state-init DDL.
-        `INSERT INTO messages (thread_id, seq, message_envelope, tokens)
-                     VALUES ($1, $2, $3::json, $4)
+        // `message_envelope::json`, never `::jsonb`, and `reported_usage::jsonb`,
+        // never `::json` — see the column comments in the state-init DDL.
+        `INSERT INTO messages (thread_id, seq, message_envelope, tokens, reported_usage)
+                     VALUES ($1, $2, $3::json, $4, $5::jsonb)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
-                           tokens = EXCLUDED.tokens`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content)])).map(() => undefined)), okVoid()))
+                           tokens = EXCLUDED.tokens,
+                           reported_usage = EXCLUDED.reported_usage`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content), i === rollupRow ? rollup : null])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
         // the only other writer of it is the title update — so without this
@@ -226,6 +240,12 @@ export function createThreadHistory(pool) {
             // ORDER BY name to the output column), sorting the bigint as text:
             // "10" before "2". Scrambled order splits a tool-call/tool-result pair
             // across an intervening turn. The qualified name forces the bigint column.
+            //
+            // `reported_usage` is deliberately NOT selected. Windowing budgets on
+            // `tokens` — an offline estimate every row carries — and a turn that
+            // reported nothing has no rollup at all, so budgeting on the rollup
+            // would silently stop evicting on exactly those threads. The two are
+            // different measurements sharing a unit; see the column comments.
             `SELECT seq::text AS seq, message_envelope, tokens
          FROM messages WHERE thread_id = $1 ORDER BY messages.seq ASC`, [threadId]);
             const parsed = rows.map((row) => ({
@@ -291,12 +311,14 @@ export function createThreadHistory(pool) {
             // `seq::text AS seq` output alias (Postgres resolves an unqualified
             // ORDER BY name to the output column), sorting the bigint as text:
             // "10" before "2". The qualified name forces the bigint column.
-            `SELECT seq::text AS seq, message_envelope
+            `SELECT seq::text AS seq, message_envelope, reported_usage
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
             const stored = rows.map((r) => {
                 const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-                return { seq: Number(r.seq), envelope, message: envelope.message };
+                // Spread rather than `usage: r.reported_usage ?? undefined`, so a row with
+                // no rollup carries no `usage` KEY at all — absent, not present-and-undefined.
+                return { seq: Number(r.seq), envelope, message: envelope.message, ...(r.reported_usage === null ? {} : { usage: r.reported_usage }) };
             });
             const turns = groupTurns(stored, (row) => isGenuineUserStart(row.message));
             const total = turns.length;

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

@@ -10,9 +10,29 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Delete is soft: `deleteThread` sets `deleted_at`; `getThread` and
- * `listThreads` filter `deleted_at IS NULL`, so the row (and its messages)
- * survive a delete and a tombstoned thread is indistinguishable from absent.
+ * Three lifecycle verbs with distinct guarantees. `archiveThread` is
+ * recoverable: it stamps `deleted_at`, and because `getThread` and the default
+ * `listThreads` filter `deleted_at IS NULL` an archived thread is
+ * indistinguishable from an absent one while its row and every one of its
+ * `messages` rows stay in storage. `unarchiveThread` clears the stamp and the
+ * thread reads as it did; a listing widened with `includeArchived` is the only
+ * way to obtain the id it takes, so the recovery is reachable by a host that
+ * holds no thread ids it obtained elsewhere.
+ * `purgeThread` is not recoverable: it removes the `messages` rows and the
+ * metadata row in one transaction, so a failure partway leaves both — never a
+ * thread stripped of its transcript, nor a transcript with nothing naming it.
+ * It is the thread-scoped member of this package's reclamation vocabulary —
+ * `purgeAnalysis` reclaims an analysis's whole persisted footprint,
+ * `purgeThread` one thread's.
+ *
+ * A purge creates no orphan of its own, but it is NOT serialized against a
+ * concurrent `appendTurn`: `messages` carries no foreign key to
+ * `cortex_analysis_threads`, and the append deliberately tolerates a missing
+ * metadata row. A turn committing after the purge therefore persists messages
+ * under a `thread_id` that no longer resolves to an analysis, leaving them
+ * unreachable by any later thread- or analysis-scoped reclamation. Stop writes
+ * to a thread — unbind it from any live conversation — before purging it; this
+ * store cannot observe a host's in-flight turns, so it does not enforce that.
  */
 import { type ResultAsync } from "neverthrow";
 import type { Pool } from "pg";
@@ -24,6 +44,13 @@ export interface Thread {
     readonly title: string | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;
+    /**
+     * The archive tombstone — `null` on a live thread, the moment it left view
+     * on an archived one. Required rather than optional: a row is always one or
+     * the other, so a caller listing archived threads has no `undefined` case to
+     * fall through and render a tombstoned conversation as live.
+     */
+    readonly deletedAt: Date | null;
 }
 export interface CreateThreadInput {
     readonly threadId: string;
@@ -34,6 +61,13 @@ export interface ListThreadsInput {
     readonly analysisId: string;
     readonly page?: number;
     readonly perPage?: number;
+    /**
+     * Widen the listing to archived threads alongside live ones. It widens, it
+     * does not switch: a caller wanting only the archived rows filters the
+     * result on `deletedAt`, which an archived-only listing could not be
+     * widened back out of.
+     */
+    readonly includeArchived?: boolean;
 }
 export interface ThreadPage {
     readonly threads: Thread[];
@@ -49,13 +83,36 @@ export interface ThreadStore {
      * `created_at`). Returns the live row.
      */
     createThread(input: CreateThreadInput): ResultAsync<Thread, DbError>;
-    /** The live thread by id, or `null` if absent or soft-deleted. */
+    /** The live thread by id, or `null` if absent or archived. */
     getThread(threadId: string): ResultAsync<Thread | null, DbError>;
-    /** Set only the title (and bump `updated_at`). No-op on a missing/deleted row. */
+    /**
+     * Set only the title, bumping `updated_at` forward — never behind the stamp
+     * the row already carries. No-op on a missing/archived row.
+     */
     updateTitle(threadId: string, title: string): ResultAsync<Thread | null, DbError>;
-    /** Soft-delete: set `deleted_at`. The row and its messages remain. */
-    deleteThread(threadId: string): ResultAsync<void, DbError>;
-    /** Live threads for one analysis, newest-updated first, paginated. */
+    /**
+     * Soft-delete: stamp `deleted_at` so the thread leaves `getThread` and
+     * `listThreads`. The row and every one of its messages remain, and an
+     * already-archived thread keeps the stamp it got the first time.
+     */
+    archiveThread(threadId: string): ResultAsync<void, DbError>;
+    /**
+     * Clear `deleted_at`, returning the thread and its messages to view exactly
+     * as they read before the archive. No-op on a live or absent thread.
+     */
+    unarchiveThread(threadId: string): ResultAsync<void, DbError>;
+    /**
+     * Reclaim the thread's whole footprint: its `messages` rows and its
+     * `cortex_analysis_threads` row, removed together in one transaction.
+     * Unrecoverable — nothing of the thread survives, and no tombstone marks
+     * that it existed. A `thread_id` with no row succeeds as a no-op.
+     */
+    purgeThread(threadId: string): ResultAsync<void, DbError>;
+    /**
+     * Threads for one analysis, newest-updated first, paginated. Live threads
+     * only unless `includeArchived` widens the set; `total` and `hasMore`
+     * always describe whichever set the page was drawn from.
+     */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
 }
 /**

package/dist/memory/thread-store.js

@@ -10,12 +10,32 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Delete is soft: `deleteThread` sets `deleted_at`; `getThread` and
- * `listThreads` filter `deleted_at IS NULL`, so the row (and its messages)
- * survive a delete and a tombstoned thread is indistinguishable from absent.
+ * Three lifecycle verbs with distinct guarantees. `archiveThread` is
+ * recoverable: it stamps `deleted_at`, and because `getThread` and the default
+ * `listThreads` filter `deleted_at IS NULL` an archived thread is
+ * indistinguishable from an absent one while its row and every one of its
+ * `messages` rows stay in storage. `unarchiveThread` clears the stamp and the
+ * thread reads as it did; a listing widened with `includeArchived` is the only
+ * way to obtain the id it takes, so the recovery is reachable by a host that
+ * holds no thread ids it obtained elsewhere.
+ * `purgeThread` is not recoverable: it removes the `messages` rows and the
+ * metadata row in one transaction, so a failure partway leaves both — never a
+ * thread stripped of its transcript, nor a transcript with nothing naming it.
+ * It is the thread-scoped member of this package's reclamation vocabulary —
+ * `purgeAnalysis` reclaims an analysis's whole persisted footprint,
+ * `purgeThread` one thread's.
+ *
+ * A purge creates no orphan of its own, but it is NOT serialized against a
+ * concurrent `appendTurn`: `messages` carries no foreign key to
+ * `cortex_analysis_threads`, and the append deliberately tolerates a missing
+ * metadata row. A turn committing after the purge therefore persists messages
+ * under a `thread_id` that no longer resolves to an analysis, leaving them
+ * unreachable by any later thread- or analysis-scoped reclamation. Stop writes
+ * to a thread — unbind it from any live conversation — before purging it; this
+ * store cannot observe a host's in-flight turns, so it does not enforce that.
  */
 import { okAsync } from "neverthrow";
-import { tryMutation, tryQuery } from "../lib/db-result.js";
+import { tryMutation, tryQuery, withTransaction } from "../lib/db-result.js";
 function toThread(row) {
     return {
         threadId: row.thread_id,
@@ -23,6 +43,7 @@ function toThread(row) {
         title: row.title,
         createdAt: row.created_at,
         updatedAt: row.updated_at,
+        deletedAt: row.deleted_at,
     };
 }
 const DEFAULT_PER_PAGE = 100;
@@ -37,43 +58,86 @@ export function createThreadStore(pool) {
         return tryMutation("thread-store.createThread.insert", () => pool.query(`INSERT INTO cortex_analysis_threads (thread_id, analysis_id, title)
          VALUES ($1, $2, $3)
          ON CONFLICT (thread_id) DO NOTHING
-         RETURNING thread_id, analysis_id, title, created_at, updated_at`, [input.threadId, input.analysisId, input.title ?? null])).andThen(({ rows }) => {
+         RETURNING thread_id, analysis_id, title, created_at, updated_at, deleted_at`, [input.threadId, input.analysisId, input.title ?? null])).andThen(({ rows }) => {
             if (rows[0])
                 return okAsync(toThread(rows[0]));
             // Row already existed — ON CONFLICT DO NOTHING returns nothing. Read it
-            // back (it may be soft-deleted; return it regardless so the caller sees
+            // back (it may be archived; return it regardless so the caller sees
             // the existing row's identity).
-            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+            return tryQuery("thread-store.createThread.readback", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
            FROM cortex_analysis_threads WHERE thread_id = $1`, [input.threadId])).map(({ rows: existing }) => toThread(existing[0]));
         });
     }
     function getThread(threadId) {
-        return tryQuery("thread-store.getThread", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+        return tryQuery("thread-store.getThread", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
          FROM cortex_analysis_threads
          WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
     }
     function updateTitle(threadId, title) {
-        return tryMutation("thread-store.updateTitle", () => pool.query(`UPDATE cortex_analysis_threads
-         SET title = $2, updated_at = NOW()
+        return tryMutation("thread-store.updateTitle", () => pool.query(
+        // `updated_at` is the listing's activity clock, and a rename is not its
+        // only writer — a turn append touches the same column, and a rename that
+        // starts before one can still reach the row after it. Taking the LATER of
+        // the two makes the bump forward-only, so a rename can never pull the
+        // column back behind a stamp the row already carries, no matter which
+        // writer set it or how long this statement waited to run. `NOW()` cannot
+        // give that: it reads this transaction's START time, not the moment the
+        // row is actually written.
+        `UPDATE cortex_analysis_threads
+         SET title = $2, updated_at = GREATEST(updated_at, clock_timestamp())
          WHERE thread_id = $1 AND deleted_at IS NULL
-         RETURNING thread_id, analysis_id, title, created_at, updated_at`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
+         RETURNING thread_id, analysis_id, title, created_at, updated_at, deleted_at`, [threadId, title])).map(({ rows }) => (rows[0] ? toThread(rows[0]) : null));
     }
-    function deleteThread(threadId) {
-        return tryMutation("thread-store.deleteThread", () => pool.query(`UPDATE cortex_analysis_threads
+    function archiveThread(threadId) {
+        return tryMutation("thread-store.archiveThread", () => pool.query(
+        // The tombstone guard is what makes a second archive change nothing:
+        // the stamp records when the thread left view, and re-stamping it
+        // would push that moment forward on every repeat.
+        `UPDATE cortex_analysis_threads
          SET deleted_at = NOW()
          WHERE thread_id = $1 AND deleted_at IS NULL`, [threadId])).map(() => undefined);
     }
+    function unarchiveThread(threadId) {
+        return tryMutation("thread-store.unarchiveThread", () => pool.query(
+        // `updated_at` is untouched on purpose: it orders the listing by
+        // conversation activity, and restoring a thread to view is not
+        // activity — a restored thread lands back where its last turn left it.
+        `UPDATE cortex_analysis_threads
+         SET deleted_at = NULL
+         WHERE thread_id = $1 AND deleted_at IS NOT NULL`, [threadId])).map(() => undefined);
+    }
+    function purgeThread(threadId) {
+        // One transaction for both statements: `messages` is attributable to an
+        // analysis only by joining through `cortex_analysis_threads`, so a metadata
+        // row removed without its messages strands them beyond the reach of any
+        // later reclamation. Either the pair goes or neither does.
+        return withTransaction(pool, "thread-store.purgeThread", (client) => tryMutation("thread-store.purgeThread.messages", () => client.query("DELETE FROM messages WHERE thread_id = $1", [threadId]))
+            .andThen(() => tryMutation("thread-store.purgeThread.thread", () => client.query("DELETE FROM cortex_analysis_threads WHERE thread_id = $1", [threadId])))
+            .map(() => undefined));
+    }
     function listThreads(input) {
         const perPage = Math.min(Math.max(input.perPage ?? DEFAULT_PER_PAGE, 1), MAX_PER_PAGE);
         const page = Math.max(input.page ?? 0, 0);
         const offset = page * perPage;
+        // The count and the page are two statements over what has to be one set:
+        // a total drawn from a different predicate than the page's would report a
+        // size the caller can never page to. Writing the row scope once — one of
+        // two fixed fragments, never caller text — makes them unable to disagree.
+        //
+        // The widened scope is the one that cannot use the table's index, which is
+        // partial on `deleted_at IS NULL`: dropping the predicate drops the index
+        // with it, so an archived-inclusive listing scans. Deliberate — the live
+        // listing is the hot path and keeps its index, while widening is a rare,
+        // user-initiated recovery. A deployment that made it routine would want a
+        // plain `analysis_id` index beside the partial one, not this listing changed.
+        const scope = input.includeArchived ? "analysis_id = $1" : "analysis_id = $1 AND deleted_at IS NULL";
         return tryQuery("thread-store.listThreads.count", () => pool.query(`SELECT COUNT(*)::text AS count
          FROM cortex_analysis_threads
-         WHERE analysis_id = $1 AND deleted_at IS NULL`, [input.analysisId])).andThen((totalResult) => {
+         WHERE ${scope}`, [input.analysisId])).andThen((totalResult) => {
             const total = Number(totalResult.rows[0].count);
-            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at
+            return tryQuery("thread-store.listThreads.page", () => pool.query(`SELECT thread_id, analysis_id, title, created_at, updated_at, deleted_at
            FROM cortex_analysis_threads
-           WHERE analysis_id = $1 AND deleted_at IS NULL
+           WHERE ${scope}
            ORDER BY updated_at DESC, thread_id
            LIMIT $2 OFFSET $3`, [input.analysisId, perPage, offset])).map(({ rows }) => ({
                 threads: rows.map(toThread),
@@ -84,5 +148,5 @@ export function createThreadStore(pool) {
             }));
         });
     }
-    return { createThread, getThread, updateTitle, deleteThread, listThreads };
+    return { createThread, getThread, updateTitle, archiveThread, unarchiveThread, purgeThread, listThreads };
 }

package/dist/prompts/sandbox/bulk-transcriptomics-agent.d.ts

@@ -1 +1 @@
-export declare const bulkTranscriptomicsAgentPrompt = "# Bulk Transcriptomics Agent\n\nYou are a bulk RNA-seq and microarray analysis specialist. You cover the\nfull pipeline: alignment/quantification, QC, filtering, normalization,\nbatch correction, differential expression, cell-type deconvolution, and\nresult visualization. You select the statistically appropriate method for\neach dataset based on data type, sample size, and experimental design \u2014\nand you justify that choice.\n\n## Skills\n\nYour skills: `bulk-transcriptomics`, `shared/omics-general`.\n\nAPI references in `bulk-transcriptomics`: PyDESeq2, DESeq2 via rpy2, edgeR,\nlimma/voom, sva, oligo/affy. Check contrast syntax there before writing it.\n\n## Method Selection (Summary)\n\n- **FASTQ** \u2014 STAR (splice-aware) or salmon/kallisto (pseudoalignment).\n  featureCounts for gene-level counts. fastqc + multiqc for read QC.\n- **Raw counts, simple design, n=3-50 per group** \u2014 PyDESeq2 (default).\n- **Raw counts, complex design (interactions, >2 factors)** \u2014 DESeq2 via rpy2.\n- **Raw counts, n > 50 per group** \u2014 limma-voom via rpy2 (scales better).\n- **Raw counts, n < 3 per group** \u2014 edgeR QLF via rpy2.\n- **Pre-normalized (TPM, FPKM, log-CPM)** \u2014 limma via rpy2.\n- **Microarray CEL** \u2014 oligo/affy RMA via rpy2, then limma.\n- **Batch effects** \u2014 ComBat_seq on raw counts (include biological\n  covariates), or svaseq surrogate variables as model covariates.\n  Correct after filtering, before DE.\n- **Longitudinal / repeated measures** \u2014 dream via rpy2.\n- **Cell-type deconvolution** \u2014 xCell2 via rpy2.\n\n## Domain Standards\n\n- Store results in AnnData: samples in `.obs`, genes in `.var`,\n  counts/expression in `.X`, raw counts in `.layers[\"counts\"]` when\n  normalization is applied.\n- Gene filter: keep genes with >= 10 counts in >= n samples where n =\n  smallest group size.\n- Each DE method normalizes internally \u2014 do NOT pre-normalize before\n  DESeq2/edgeR/voom.\n- Always inspect library sizes and PCA by batch before DE.\n\n## Required Figures (DE analysis)\n\n- **PCA** \u2014 sample-level, top 500 variable genes. Color by condition,\n  shape by batch if present. The single most important QC figure.\n- **Sample distance heatmap** \u2014 Euclidean distances with hierarchical\n  clustering, annotated by condition and batch.\n- **Volcano plot** \u2014 log2FC vs -log10(padj). Label top genes. Threshold\n  lines.\n- **MA plot** \u2014 baseMean vs log2FC.\n- **Top gene heatmap** \u2014 top 50 DE genes, z-scored, with column\n  annotation.\n\nFor alignment/QC runs, include multiqc summary figures. For\ndeconvolution, include cell-type proportion bar plots per sample.\n\n## Domain Anti-Patterns\n\n- DESeq2, PyDESeq2, or edgeR on TPM/FPKM/RPKM \u2014 these model raw counts.\n- voom on already-normalized or log-transformed data.\n- ComBat_seq without biological covariates in the model.\n- Using svaseq-adjusted counts directly \u2014 add SVs as model covariates.\n- Arbitrary gene filters \u2014 base thresholds on smallest group size.\n- Skipping batch assessment \u2014 always check PCA colored by batch.\n\n## Required Output Files\n\n- DE results CSV: columns `gene`, `log2_fold_change`, `pvalue`,\n  `adjusted_pvalue`, `base_mean`. One file per contrast.\n- Normalized counts: AnnData `.h5ad` (and CSV for cross-agent use).\n";
+export declare const bulkTranscriptomicsAgentPrompt = "# Bulk Transcriptomics Agent\n\nYou are a bulk RNA-seq and microarray analysis specialist. You work from\na **count or expression matrix**: QC, filtering, normalization, batch\ncorrection, differential expression, cell-type deconvolution, and result\nvisualization. Quantification from reads is upstream work and out of\nscope \u2014 no aligner or quantifier is installed. If you are handed FASTQ,\nsay you need the count matrix and stop. You select the statistically\nappropriate method for each dataset based on data type, sample size, and\nexperimental design \u2014 and you justify that choice.\n\n## Skills\n\nYour skills: `bulk-transcriptomics`, `shared/omics-general`.\n\nAPI references in `bulk-transcriptomics`: PyDESeq2, DESeq2 via rpy2, edgeR,\nlimma/voom, sva. Check contrast syntax there before writing it.\n\n## Method Selection (Summary)\n\n- **Raw counts, simple design, n=3-50 per group** \u2014 PyDESeq2 (default).\n- **Raw counts, complex design (interactions, >2 factors)** \u2014 DESeq2 via rpy2.\n- **Raw counts, n > 50 per group** \u2014 limma-voom via rpy2 (scales better).\n- **Raw counts, n < 3 per group** \u2014 edgeR QLF via rpy2.\n- **Pre-normalized (TPM, FPKM, log-CPM, microarray intensities)** \u2014 limma\n  via rpy2.\n- **Raw microarray CEL** \u2014 out of scope: reading them needs a per-design\n  platform annotation package that cannot be staged or installed. Say so\n  and ask for the normalized matrix.\n- **Batch effects** \u2014 ComBat_seq on raw counts (include biological\n  covariates), or svaseq surrogate variables as model covariates.\n  Correct after filtering, before DE.\n- **Longitudinal / repeated measures** \u2014 dream via rpy2.\n- **Cell-type deconvolution** \u2014 xCell2 via rpy2.\n\n## Domain Standards\n\n- Store results in AnnData: samples in `.obs`, genes in `.var`,\n  counts/expression in `.X`, raw counts in `.layers[\"counts\"]` when\n  normalization is applied.\n- Gene filter: keep genes with >= 10 counts in >= n samples where n =\n  smallest group size.\n- Each DE method normalizes internally \u2014 do NOT pre-normalize before\n  DESeq2/edgeR/voom.\n- Always inspect library sizes and PCA by batch before DE.\n\n## Required Figures (DE analysis)\n\n- **PCA** \u2014 sample-level, top 500 variable genes. Color by condition,\n  shape by batch if present. The single most important QC figure.\n- **Sample distance heatmap** \u2014 Euclidean distances with hierarchical\n  clustering, annotated by condition and batch.\n- **Volcano plot** \u2014 log2FC vs -log10(padj). Label top genes. Threshold\n  lines.\n- **MA plot** \u2014 baseMean vs log2FC.\n- **Top gene heatmap** \u2014 top 50 DE genes, z-scored, with column\n  annotation.\n\nFor deconvolution, include cell-type proportion bar plots per sample.\n\n## Domain Anti-Patterns\n\n- Attempting to quantify from reads, or hand-rolling a pseudoaligner.\n  The count matrix is an input; report what you need instead.\n- DESeq2, PyDESeq2, or edgeR on TPM/FPKM/RPKM \u2014 these model raw counts.\n- voom on already-normalized or log-transformed data.\n- ComBat_seq without biological covariates in the model.\n- Using svaseq-adjusted counts directly \u2014 add SVs as model covariates.\n- Arbitrary gene filters \u2014 base thresholds on smallest group size.\n- Skipping batch assessment \u2014 always check PCA colored by batch.\n\n## Required Output Files\n\n- DE results CSV: columns `gene`, `log2_fold_change`, `pvalue`,\n  `adjusted_pvalue`, `base_mean`. One file per contrast.\n- Normalized counts: AnnData `.h5ad` (and CSV for cross-agent use).\n";