@inflexa-ai/harness 0.19.2 → 0.21.0

package/dist/loop/tool-detail.js

@@ -2,8 +2,10 @@
  * The call detail: one line naming what a tool call is doing.
  *
  * A tool states it through its own `describeCall` hook, colocated with the Zod
- * `inputSchema` the compiler checks it against. Everything else about the
- * detail happens here, once, for every tool: validate, guard, normalize.
+ * `inputSchema` the compiler checks it against, and through its optional
+ * `describeResult` hook, which names what the call produced. Everything else
+ * about the detail happens here, once, for every tool: validate, guard,
+ * normalize.
  *
  * Two rules make this the only place that matters:
  *
@@ -135,3 +137,34 @@ export function computeDetail(tool, rawInput, log) {
         return undefined;
     }
 }
+/**
+ * Compute a tool call's result detail, best-effort.
+ *
+ * `parsedInput` is the value the dispatch already validated, and `result` is the
+ * ok value the tool returned one line above. Thus neither is re-parsed here: a
+ * second parse of the input would repeat work the dispatch did, and the result
+ * satisfies no schema at all — the tool's own `Output` type is what the hook
+ * declares, and the tool is the author of both.
+ *
+ * The guard is the whole difference from a bare call. A hook that throws, returns
+ * a non-string, or returns nothing usable yields no result detail, and the
+ * finished event falls back on the call detail. A description must never be able
+ * to fail a call that already succeeded.
+ */
+export function computeResultDetail(tool, parsedInput, result, log) {
+    // The guard tests for a function, not for presence, for the same reason as in
+    // `computeDetail`: a packaged tool comes from an open list, thus a
+    // `describeResult` that is not callable is reachable.
+    const describeResult = tool.describeResult;
+    if (typeof describeResult !== "function")
+        return undefined;
+    try {
+        return normalizeDetail(describeResult(parsedInput, result));
+    }
+    catch (err) {
+        // `debug`, not `warn`: a broken description is a cosmetic defect in one
+        // tool, and the call it happened on succeeded.
+        log.debug("describeResult failed", { tool: tool.id, ...log.errorFields(err) });
+        return undefined;
+    }
+}

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

@@ -53,8 +53,9 @@ export interface ContentToCortexOptions {
  * 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; 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.
+ * stored turn rollup sets `usage` the same way. A row that carries a stored turn
+ * duration sets `durationMs` the same way too. Thus a reloaded conversation shows
+ * the cost and the time that the live turn showed, with no 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`

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

@@ -99,8 +99,9 @@ async function rowToParts(message, outcomes, options) {
  * 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; 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.
+ * stored turn rollup sets `usage` the same way. A row that carries a stored turn
+ * duration sets `durationMs` the same way too. Thus a reloaded conversation shows
+ * the cost and the time that the live turn showed, with no 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`
@@ -144,18 +145,20 @@ export async function contentToCortexMessages(messages, options = {}) {
         // assistant run it trailed, so fold the flag onto the previous emitted assistant.
         const interrupted = isInterruptedMessage(message.message);
         if (parts.length === 0) {
-            // 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.
+            // The stored rollup of a row and its stored duration are facts about the turn,
+            // and not about what the row renders. Thus the read of both comes before the
+            // zero-parts drop, exactly as the read of the interruption marker does. The
+            // fold then puts them on the assistant run that they trailed. Without the fold,
+            // a turn whose last assistant row held unrendered blocks alone would lose the
+            // two figures to the drop. That loss is the one that the stored figures end.
             const prev = out[out.length - 1];
             if (prev && prev.role === "assistant") {
                 if (interrupted)
                     prev.interrupted = true;
                 if (message.usage)
                     prev.usage = message.usage;
+                if (message.durationMs !== undefined)
+                    prev.durationMs = message.durationMs;
             }
             continue;
         }
@@ -173,12 +176,16 @@ export async function contentToCortexMessages(messages, options = {}) {
             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.
+            // Coalescing rebuilds the one-bubble-per-turn shape, and the two figures ride
+            // the LAST assistant row of the turn. Thus the run keeps the figures of
+            // whichever row carried them. An assignment, and not a merge, is deliberate:
+            // two rollups in one run would mean that coalescing merged two turns, and it
+            // never does. The duration reads against `undefined`, because a measured zero
+            // is a figure and an absent value alone means that nobody measured the turn.
             if (message.usage)
                 prev.usage = message.usage;
+            if (message.durationMs !== undefined)
+                prev.durationMs = message.durationMs;
             continue;
         }
         const cortex = { id: String(message.seq), role, parts };
@@ -186,6 +193,8 @@ export async function contentToCortexMessages(messages, options = {}) {
             cortex.interrupted = true;
         if (message.usage)
             cortex.usage = message.usage;
+        if (message.durationMs !== undefined)
+            cortex.durationMs = message.durationMs;
         out.push(cortex);
     }
     return out;

package/dist/memory/conversation-display-replay.js

@@ -25,14 +25,21 @@ export function storedMessagesToCortex(messages) {
             append = conversationUIToCortexMessages(row.displayEnvelope.messages);
             out.push(...append);
         }
-        // The turn's reported rollup rides the model row that ENDED the turn, not the
-        // display projection — it is a fact about what the turn cost, not about what it
-        // showed, and persisting it in both places would let the two disagree. Fold it
-        // onto the assistant reply a reader associates with the figure.
-        if (row.usage && append) {
+        // The reported rollup of the turn and its duration both ride the model row that
+        // ENDED the turn, and not the display projection. Each one is a fact about what the
+        // turn cost, and not about what the turn showed. A write in both places would let
+        // the two disagree. Thus the replay folds them onto the assistant reply that a
+        // reader ties to the figures. The duration reads against `undefined`, and never
+        // against falsiness: a measured zero is a figure, and an absent value alone means
+        // that nobody measured the turn.
+        if (append && (row.usage || row.durationMs !== undefined)) {
             const last = append.at(-1);
-            if (last?.role === "assistant")
-                last.usage = row.usage;
+            if (last?.role === "assistant") {
+                if (row.usage)
+                    last.usage = row.usage;
+                if (row.durationMs !== undefined)
+                    last.durationMs = row.durationMs;
+            }
         }
     }
     return out;

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

@@ -47,6 +47,13 @@ export interface StoredMessage {
      * the state-init DDL).
      */
     readonly usage?: TokenUsageRollup;
+    /**
+     * The time that the whole TURN this row completed took, in milliseconds —
+     * present only on the last assistant row of a turn appended with a duration,
+     * absent everywhere else. It has a column of its own, thus a turn that
+     * reported no quantity still reads back with the duration that it took.
+     */
+    readonly durationMs?: number;
 }
 /**
  * One atomic append: the exact provider-facing history, the display projection of
@@ -70,6 +77,14 @@ export interface ConversationTurn {
      * must not read back as a turn that cost zero.
      */
     readonly turnUsage?: TokenUsageRollup;
+    /**
+     * The time that the turn took, in milliseconds, as the live header measured
+     * it. Stored beside the rollup, on the same last assistant message. A caller
+     * that supplies none leaves the row without one, and nothing reconstructs a
+     * value later. The duration keeps a column of its own, thus a turn that
+     * reported no quantity still keeps the duration that it took.
+     */
+    readonly turnDurationMs?: number;
 }
 /**
  * The append a host uses to record out-of-band work in a thread — an analysis
@@ -110,6 +125,18 @@ export type RetractOutcome = {
 } | {
     kind: "no-user-turn";
 };
+/**
+ * The read options of {@link ThreadHistory.loadRecent}. An absent option gives
+ * the default window.
+ */
+export interface LoadRecentOptions {
+    /**
+     * Keep the first turn of the thread in the window, past the eviction. The
+     * default is `false`, and the eviction then drops the first turn with the
+     * rest of the oldest block.
+     */
+    readonly keepFirstTurn?: boolean;
+}
 /**
  * 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.
@@ -119,8 +146,9 @@ export interface ThreadHistory {
      * Append one {@link ConversationTurn} — every message written in a single
      * transaction with a `seq` monotonically increasing per thread.
      *
-     * A turn writing no assistant message stores no rollup and still succeeds:
-     * there is no row on which the figure would mean anything.
+     * A turn writing no assistant message stores neither the rollup nor the
+     * duration and still succeeds: there is no row on which the two figures
+     * would mean anything.
      */
     appendTurn(threadId: string, turn: ConversationTurn): ResultAsync<void, DbError>;
     /**
@@ -129,8 +157,18 @@ export interface ThreadHistory {
      * in whole `EVICTION_BLOCK_TURNS` blocks (see the constant) so the prompt-cache
      * prefix stays byte-stable across appends; the window may therefore carry a
      * little less than the budget would strictly allow, but never more.
+     *
+     * `keepFirstTurn` keeps the first turn of the thread. The eviction then drops
+     * the oldest turns after it, and the window holds the first turn and that
+     * retained suffix. The first turn appears one time only.
+     *
+     * The retained turn can carry the window past `tokenBudget`. The cost is
+     * bounded. A report session seeds one turn, its brief carries a length bound,
+     * and its copy of the working-memory render is one row. The retained head also
+     * holds `messages[0]` byte-identical for the life of the thread, thus the
+     * prompt-cache prefix of the provider stays still.
      */
-    loadRecent(threadId: string, tokenBudget: number): ResultAsync<ModelMessage[], DbError>;
+    loadRecent(threadId: string, tokenBudget: number, options?: LoadRecentOptions): ResultAsync<ModelMessage[], DbError>;
     /**
      * Return one page of a thread's messages oldest-first for UI display —
      * NOT token-windowed (that is `loadRecent`'s job for the agent loop). No
@@ -171,6 +209,25 @@ export interface ThreadHistory {
      * no guarantee, because the tail can move one append later without it.
      */
     latestSeq(threadId: string): ResultAsync<number | null, DbError>;
+    /**
+     * The count of the thread turns that a person opened past `seq`. A caller
+     * reads it as the new work of the thread past an anchor.
+     *
+     * The unit is a turn, not a row. One turn writes a user row, an assistant
+     * row for each step, and a tool row for each result. Thus a row count of one
+     * span reports the shape of a turn, not the count of the asks.
+     *
+     * A seq comparison alone reports even less. An anchor taken during a turn
+     * sits below the rows of that same turn, thus the difference never reads as
+     * zero again.
+     *
+     * The count reads {@link GENUINE_USER_START_SQL}, the one predicate the turn
+     * grouping and the tail retraction already cut on. Thus the count and the
+     * grouping cannot drift. A synthetic nudge of the loop and a record of the
+     * host both carry the `user` role, and neither one is new work. Thus neither
+     * one adds to the count.
+     */
+    countUserTurnsAfter(threadId: string, seq: number): ResultAsync<number, DbError>;
 }
 /**
  * Drop the memoized instruments so the next `loadRecent` rebinds to a

package/dist/memory/thread-history.js

@@ -176,7 +176,7 @@ export const EVICTION_BLOCK_TURNS = 4;
  */
 export function createThreadHistory(pool) {
     function appendTurn(threadId, turn) {
-        const { modelMessages: messages, displayMessages, turnUsage } = turn;
+        const { modelMessages: messages, displayMessages, turnUsage, turnDurationMs } = turn;
         if (messages.length === 0)
             return okVoid();
         // The display projection rides the append's FIRST row, so one SELECT of a
@@ -190,12 +190,17 @@ export function createThreadHistory(pool) {
         // `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
+        // The duration takes no predicate of its own, and it keeps its own column.
+        // A measured zero is a figure, thus only an absent value means that nobody
+        // measured the turn. The rollup goes absent under its own predicate above,
+        // and the duration does not go with it.
+        const duration = turnDurationMs ?? null;
+        // The two figures describe 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);
+        const lastAssistantRow = 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
@@ -214,19 +219,21 @@ export function createThreadHistory(pool) {
         // `message_envelope::json`, never `::jsonb`; `display_envelope` and
         // `reported_usage::jsonb`, never `::json` — see the column comments
         // in the state-init DDL.
-        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage)
-                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb)
+        `INSERT INTO messages (thread_id, seq, message_envelope, display_envelope, tokens, reported_usage, turn_duration_ms)
+                     VALUES ($1, $2, $3::json, $4::jsonb, $5, $6::jsonb, $7)
                      ON CONFLICT (thread_id, seq) DO UPDATE
                        SET message_envelope = EXCLUDED.message_envelope,
                            display_envelope = EXCLUDED.display_envelope,
                            tokens = EXCLUDED.tokens,
-                           reported_usage = EXCLUDED.reported_usage`, [
+                           reported_usage = EXCLUDED.reported_usage,
+                           turn_duration_ms = EXCLUDED.turn_duration_ms`, [
             threadId,
             startSeq + i,
             serializeEnvelope(message),
             i === 0 ? displayEnvelope : null,
             countTokens(message.content),
-            i === rollupRow ? rollup : null,
+            i === lastAssistantRow ? rollup : null,
+            i === lastAssistantRow ? duration : null,
         ])).map(() => undefined)), okVoid()))
             .andThen(() => 
         // Thread listings sort on `cortex_analysis_threads.updated_at`, and
@@ -267,7 +274,7 @@ export function createThreadHistory(pool) {
             .map(() => undefined)
             .orElse(() => okVoid()))));
     }
-    function loadRecent(threadId, tokenBudget) {
+    function loadRecent(threadId, tokenBudget, options) {
         return tryQuery("thread-history.loadRecent", async () => {
             const { rows } = await pool.query(
             // ORDER BY must qualify `messages.seq` — a bare `seq` would bind to the
@@ -320,14 +327,28 @@ export function createThreadHistory(pool) {
             // >= `minimalEvicted`, so `turnsEvicted >= minimalEvicted`: the retained
             // suffix is a subset of the budget-minimal one and stays within budget.
             const turnsEvicted = turns.length === 0 ? 0 : Math.min(Math.ceil(minimalEvicted / EVICTION_BLOCK_TURNS) * EVICTION_BLOCK_TURNS, turns.length - 1);
+            // The retained head. The first turn of a report session carries the
+            // brief and the copy of the working-memory render, and no tail message
+            // replaces them. Thus `keepFirstTurn` puts that turn in front of the
+            // retained suffix, and `messages[0]` never moves again. An eviction of
+            // zero already holds the first turn at the head, thus the option adds
+            // nothing there and the window never carries the turn two times.
+            const keepsFirstTurn = options?.keepFirstTurn === true && turnsEvicted > 0;
             const { totalTokens, turnsEvicted: turnsEvictedHist } = getInstruments();
+            // A retained head gives one evicted turn back to the window, thus the
+            // histogram reports one turn less than the budget walk cut.
+            const turnsDropped = keepsFirstTurn ? turnsEvicted - 1 : turnsEvicted;
+            // The flag reads the cut of the budget walk, and never the count that
+            // the retained head reduced. The two answer different questions: the
+            // flag says that the window lost a turn, and the histogram says how
+            // many. A walk that cut one block, under a block size of one, drops
+            // its whole cut back into the window. The flag must still report the
+            // eviction, because the thread crossed its budget.
             const attributes = { eviction: turnsEvicted > 0 };
             totalTokens.record(threadTotal, attributes);
-            turnsEvictedHist.record(turnsEvicted, attributes);
-            return turns
-                .slice(turnsEvicted)
-                .flat()
-                .map((row) => row.message);
+            turnsEvictedHist.record(turnsDropped, attributes);
+            const retained = turns.slice(turnsEvicted);
+            return (keepsFirstTurn ? [turns[0], ...retained] : retained).flat().map((row) => row.message);
         });
     }
     function loadPage(threadId, page, perPage) {
@@ -346,11 +367,12 @@ 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, display_envelope, reported_usage
+            `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage, turn_duration_ms::text AS turn_duration_ms
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
             // 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.
+            // The duration obeys the same rule, and it reads from its own column.
             const stored = await Promise.all(rows.map(async (r) => {
                 const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
                 const displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`);
@@ -360,6 +382,7 @@ export function createThreadHistory(pool) {
                     message: envelope.message,
                     ...(displayEnvelope ? { displayEnvelope } : {}),
                     ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
+                    ...(r.turn_duration_ms === null ? {} : { durationMs: Number(r.turn_duration_ms) }),
                 };
             }));
             const turns = groupTurns(stored, (row) => isGenuineUserStart(row.message));
@@ -429,5 +452,21 @@ export function createThreadHistory(pool) {
             return maxSeq === null ? null : Number(maxSeq);
         });
     }
-    return { appendTurn, loadRecent, loadPage, retractLastTurn, latestSeq };
+    function countUserTurnsAfter(threadId, seq) {
+        // `GENUINE_USER_START_SQL` is the stored-envelope twin of
+        // `isGenuineUserStart`, and the tail retraction cuts on the same text.
+        // Thus one row matches for each turn that a person opened, and a
+        // synthetic nudge of the loop or a record of the host matches none.
+        //
+        // `$2::bigint` compares the bigint column against a bigint, never against
+        // a text projection, thus an anchor past 2^53 still compares exactly.
+        // `COUNT(*)` is a bigint as well, and the driver hands a bigint back as
+        // text. The explicit cast says so, and `Number` makes the crossing in one
+        // place — the way every other read of this column does.
+        return tryQuery("thread-history.countUserTurnsAfter", () => pool.query(`SELECT COUNT(*)::text AS turns FROM messages
+              WHERE thread_id = $1
+                AND seq > $2::bigint
+                AND ${GENUINE_USER_START_SQL}`, [threadId, seq])).map(({ rows }) => Number(rows[0].turns));
+    }
+    return { appendTurn, loadRecent, loadPage, retractLastTurn, latestSeq, countUserTurnsAfter };
 }

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

@@ -29,6 +29,10 @@
  * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
  * persisted footprint, `purgeThread` one subtree's.
  *
+ * The directory of a report session takes the name of its thread id. Thus
+ * `purgeThread` gives back the ids that it erased, because a host that reclaims
+ * those directories has no other source for the set.
+ *
  * 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
@@ -221,8 +225,14 @@ export interface ThreadStore {
      * of every one of them, removed together in one transaction. Unrecoverable —
      * nothing survives, and no tombstone marks that any of it existed. A
      * `thread_id` with no row succeeds as a no-op.
+     *
+     * The value holds the id of each thread that the purge erased, the named one
+     * and every descendant, in no promised order. A purge that erases nothing
+     * gives back an empty array. The directory of a report session takes the
+     * name of its thread id, thus a host that reclaims those directories has no
+     * other source for the set that went.
      */
-    purgeThread(threadId: string): ResultAsync<void, DbError>;
+    purgeThread(threadId: string): ResultAsync<readonly string[], DbError>;
     /**
      * Threads for one analysis, newest-updated first, paginated. Live threads
      * only unless `includeArchived` widens the set, and every type under every

package/dist/memory/thread-store.js

@@ -29,6 +29,10 @@
  * reclamation vocabulary — `purgeAnalysis` reclaims an analysis's whole
  * persisted footprint, `purgeThread` one subtree's.
  *
+ * The directory of a report session takes the name of its thread id. Thus
+ * `purgeThread` gives back the ids that it erased, because a host that reclaims
+ * those directories has no other source for the set.
+ *
  * 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
@@ -284,13 +288,19 @@ export function createThreadStore(pool) {
         // shares reads the very rows the last one removes. Thus a thread delete before
         // the others leaves the subtree unresolvable before a later statement names its
         // transcripts and its drafts.
+        //
+        // The last statement names the exact set of erased threads through the
+        // same walk, thus `RETURNING` is the whole source of the ids. A separate
+        // read cannot supply them: before the delete it costs a round trip on a
+        // set that can still change, and after it the rows are gone.
         return withTransaction(pool, "thread-store.purgeThread", (client) => tryMutation("thread-store.purgeThread.messages", () => client.query(`${SUBTREE_CTE}
          DELETE FROM messages WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId]))
             .andThen(() => tryMutation("thread-store.purgeThread.reportSessionState", () => client.query(`${SUBTREE_CTE}
          DELETE FROM cortex_report_session_state WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
             .andThen(() => tryMutation("thread-store.purgeThread.thread", () => client.query(`${SUBTREE_CTE}
-         DELETE FROM cortex_analysis_threads WHERE thread_id IN (SELECT thread_id FROM subtree)`, [threadId])))
-            .map(() => undefined));
+         DELETE FROM cortex_analysis_threads WHERE thread_id IN (SELECT thread_id FROM subtree)
+         RETURNING thread_id`, [threadId])))
+            .map(({ rows }) => rows.map((row) => row.thread_id)));
     }
     function listThreads(input) {
         const perPage = Math.min(Math.max(input.perPage ?? DEFAULT_PER_PAGE, 1), MAX_PER_PAGE);

package/dist/prompts/conversation.d.ts

@@ -1 +1 @@
-export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via\n   `execute_analysis`. For an explicitly requested targeted computation, use\n   `execute_analysis` in ad hoc mode without generating a plan.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do NOT\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. The authoritative record:\n   domain, organism, tissue, condition, experimental design, quality concerns,\n   and the per-file data types and dimensions. There is no data-profile file \u2014\n   this tool is the only way to read it. Do not go looking for one, and do not\n   re-derive these facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`. Semantic search over the indexed\n   workspace; it returns ranked paths with descriptions and metadata, not\n   contents.\n3. **What is inside a file** \u2192 `read_file` (or `list_files`) on a path a search\n   returned.\n\nDo not start with filesystem exploration for general data questions.\nDo not tell the user you cannot access their files \u2014 you can.\n\nWhen the user points to data by name or location that is not yet an input of\nthis analysis, adding it as an input may be available to you as a host tool.\nIf so: list the candidates, confirm with the user, and add them so they get\nprofiled. Never tell the user to copy files into a folder to make them\nvisible \u2014 reach for the input tool if you have one, or say plainly that the\ndata must be added as an input and let the host handle how.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do NOT summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call\n   `execute_analysis({ mode: \"plan\", planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. On validation failure, regenerate via `generate_plan`.\n6. **Plan stale / invalid?** If `execute_analysis` returns `status: not_found`\n   (or `invalid_plan`), or `show_plan` returns `error: plan_not_found`,\n   the `planId` is no longer valid \u2014 regenerate via `generate_plan` and\n   present the new plan for approval. Do NOT retry the same `planId`.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it. A launch\nresult with `status: \"in_progress\"` means exactly that; do not infer\ncompletion from the tool call returning.\n\n## Ad Hoc Analysis\n\nWhen the user explicitly asks you to run, compute, test, compare, or otherwise\nexecute one targeted computation, call\n`execute_analysis({ mode: \"adhoc\", request })` with their exact request. Their\nexplicit computational instruction is consent: do not generate or present a\nsynthetic plan and do not ask for a second approval. The tool automatically\nselects the sandbox specialist and resources; never add or invent an agent id.\n\nIf computation is only your suggestion \u2014 the user asked a conceptual question\nand did not ask you to execute anything \u2014 ask for consent before calling the\ntool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve\ntheir results later with `inspect_run`. If the user explicitly asks you to\nwait or check whether a run finishes, you may make one bounded\n`inspect_run({ runId, waitForTerminalSeconds })` call in that turn (maximum\n30 seconds). If it returns `inspectionState: \"in_progress\"` at the cutoff,\nstop polling and tell the user it is still running. Never loop on\n`inspect_run`; otherwise inspect on a later turn.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **Step summaries** (`summary.md` per step) \u2014 computational findings,\n  method choices, quality assessment. Pure facts, no literature.\n- **Run synthesis** (`synthesis.json` at run level) \u2014 integrated\n  interpretation of the run: conclusions, selective key findings\n  (novel/contradicted/high-impact only), biological themes, limitations,\n  and literature references with PMIDs. Produced only when the run had\n  summaries to integrate and hit no blocker \u2014 `synthesis.json` exists\n  for that run alone; a skipped or failed synthesis writes no file.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the run's `synthesisStatus` and gives a `synthesisPath` only when it\n   is `produced`. When the run produced a synthesis,\n   `workspace_search(\"synthesis conclusions interpretation\")` also finds\n   `synthesis.json` \u2014 that integrated interpretation, with conclusions and\n   literature grounding, is your primary source. When synthesis was skipped or\n   failed, no synthesis file exists \u2014 fall back to the per-step `summary.md`\n   files as your source and integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the corresponding step's `summary.md` for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use bio-lookup\n   tools directly or delegate to `literature_reviewer` for additional investigation\n   beyond what the synthesis already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYou have bio-lookup tools for quick lookups AND a `literature_reviewer`\nagent for deep batch investigation. Route appropriately:\n\n**Handle directly** (1-2 targets, quick answer):\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `lookup_annotation`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**Delegate to `literature_reviewer`** (3+ targets, systematic investigation):\n- \"Investigate these top DE genes against literature\"\n- \"Build evidence profiles for these enriched pathways\"\n- \"Validate these findings \u2014 are they novel or established?\"\n\nIt returns a structured evidence report. Use it to ground your hypotheses,\ngrade evidence, or present validated findings.\n\n### Which bio database to enter from\n\nEach tool states its own contract; these are the comparisons no single one\ncan make:\n\n- **Target assessment** \u2192 `opentargets({action:\"target\"})` first: one call returns\n  genetic evidence, tractability, and the drug landscape, already scored. De-risk\n  from there with `target_safety` and `gene_preclinical_profile`. Reach for\n  `gene_disease_evidence` when you need the underlying records rather than the\n  scores \u2014 the individual SNPs, GDA scores and variant classifications.\n- **Compounds** \u2192 ChEMBL (`chembl({action:\"compounds\"})`) for curated potency, mechanism,\n  and approved drugs. `pubchem({action:\"compound\"})` when ChEMBL misses it \u2014 then\n  bridge back to curated data with `pubchem({action:\"crossrefs\"})`.\n- **Safety** \u2192 `target_safety` is mechanism-based (the target);\n  `search_faers` is post-market (a specific marketed drug). EPA CTX for\n  environmental and industrial chemicals.\n\nAll of these are lightweight API calls \u2014 never spin up a sandbox for a lookup.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, follow the scientist process\nas one continuous thought process. Do not skip phases.\n\n### 1. Orient \u2014 Understand What Exists\n- `inspect_data_profile` for the dataset's design and per-file facts.\n- Search the workspace for analysis results, DE results, QC summaries.\n- Read key files \u2014 result tables, summaries, metadata. Don't stop at search\n  results \u2014 read the files to see specific values.\n- Check run history via `inspect_run`.\n- If refining prior hypotheses, read them from conversation context.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nDelegate to the `literature_reviewer` with the genes, pathways, and\nfeatures you identified in orientation. Include fold changes, condition\nnames, and what you need to know. The reviewer systematically investigates\neach target and returns structured evidence.\n\nFor quick follow-ups on specific targets during ideation, use your\nown bio-lookup tools directly.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo complementary tools serve hypothesis exploration: the\n`literature_reviewer` for in-domain biology evidence (used here), and\n`generate_analogy_report` for cross-domain inspiration (used in the\nIdeate step below). Treat them as a pair \u2014 biology evidence anchors\nhypotheses to reality, analogies broaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Limit to top 5-10.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders `generate_analogy_report`'s result as an inline card\nautomatically. Your job is to STEER, not re-present:\n\n- 3-6 lines of plain prose. No bullets. No headers. No `show_user`.\n- Reference 2-3 analogies by their `analogyTitle` (not by re-stating\n  their content). Example: \"The *critical slowing down* angle is the\n  most actionable here \u2014 it gives you a variance-based statistic that\n  doesn't require new data.\"\n- End with one concrete steering question. Examples: \"Want me to draft\n  a plan around the DNB index?\" / \"Should we dig into the percolation\n  framing or pursue the bet-hedging entropy angle?\"\n- Never embed analogies into `generate_plan`, `execute_analysis`, or any\n  workflow input. The planner and sandbox agents are unaware of\n  analogy reports by design \u2014 they're for conversation only.\n- Never call `show_user` to re-present the report. The card is the\n  presentation; your prose is the steering. Restating the analogies\n  in prose creates a duplicate rendering.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation \u2014 state briefly what you'll build (audience, sections)\nin the same turn you begin.\n\nThe flow: call `plan_report` to get the report-brief schema and authoring\nrules, compose the brief from what it returns, then call `submit_report` with\nit. To revise an existing report, skip `plan_report` and call `submit_report`\nwith `modifications` + the existing `previewId` (never a fresh brief).\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience matters\nand has not been established.\n\nDo NOT create reports unprompted. Suggest one after a run completes, or\nwhen the user asks for a summary or presentation of results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing, `show_plan` for a stored `planId`, `show_file` for an\nexisting artifact path. Cards render in the order you emit them.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it to 2-3 sentences.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Synthesize from summaries alone.** When interpreting results, search\n  the workspace and read actual output files. If you cannot find the data\n  behind a claim, say so.\n- **Generate hypotheses disconnected from data.** Every hypothesis must\n  reference specific results you verified by reading files.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Trigger unrequested computation.** Planned analyses require an approved plan.\n  A targeted ad hoc analysis requires the user's explicit computational intent;\n  if execution is merely your suggestion, ask first.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs whenever the analysis\n  has inputs \u2014 at init, and again when inputs are added or removed during the\n  conversation. Never propose \"explore data structure\" or \"initial\n  assessment\" steps.\n- **Split one targeted request into multiple ad hoc runs.** Keep one explicit\n  computational request in one ad hoc call. Use a user-approved plan when the\n  work genuinely requires multiple dependent steps.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- Use bio-lookup tools to provide biological context for key findings,\n  but keep tool usage focused \u2014 look up the most important genes and\n  pathways, not every result.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";
+export declare const conversationPrompt = "# Conversation Agent\n\nYou are the user-facing companion for a bioinformatics analysis platform.\nYou help researchers explore their data, plan and execute analyses, interpret\nresults, and generate testable hypotheses. You handle everything\nconversational \u2014 from simple lookups to multi-step scientific exploration.\n\n## Your Role\n\n1. **Answer directly** \u2014 data questions, bio-lookups, file exploration,\n   general bioinformatics questions. Use your tools.\n2. **Plan and execute analyses** \u2014 orient in the workspace, generate plans\n   via `generate_plan`, present plans via `show_plan`, execute via\n   `execute_analysis`. For an explicitly requested targeted computation, use\n   `execute_analysis` in ad hoc mode without generating a plan.\n3. **Interpret results** \u2014 after runs complete, read summaries and artifacts,\n   synthesize findings, grade evidence, flag novelty.\n4. **Explore hypotheses** \u2014 investigate data, cross-reference with biology,\n   generate testable hypotheses, refine through discussion.\n\n## Context Continuity\n\nYou are one agent handling the full conversation. Your tool call results\npersist across turns. If you searched the workspace, read a file, or\ngenerated a plan \u2014 those results are still in your context. Do NOT\nrepeat searches or re-orient when the information is already available\nfrom a prior turn.\n\nRe-orient only when:\n- Starting a conversation with no prior workspace exploration\n- The user asks about something not covered by prior searches\n- A new workflow run has completed since your last search\n\n## Data Discovery \u2014 Search First\n\nRoute by what you are asking for:\n\n1. **What the dataset IS** \u2192 `inspect_data_profile`. The authoritative record:\n   domain, organism, tissue, condition, experimental design, quality concerns,\n   and the per-file data types and dimensions. There is no data-profile file \u2014\n   this tool is the only way to read it. Do not go looking for one, and do not\n   re-derive these facts by reading the raw inputs.\n2. **Which files exist** \u2192 `workspace_search`. Semantic search over the indexed\n   workspace; it returns ranked paths with descriptions and metadata, not\n   contents.\n3. **What is inside a file** \u2192 `read_file` (or `list_files`) on a path a search\n   returned.\n\nDo not start with filesystem exploration for general data questions.\nDo not tell the user you cannot access their files \u2014 you can.\n\nWhen the user points to data by name or location that is not yet an input of\nthis analysis, adding it as an input may be available to you as a host tool.\nIf so: list the candidates, confirm with the user, and add them so they get\nprofiled. Never tell the user to copy files into a folder to make them\nvisible \u2014 reach for the input tool if you have one, or say plainly that the\ndata must be added as an input and let the host handle how.\n\n## Analysis Planning\n\nWhen the user wants to run an analysis:\n\n1. **Orient** \u2014 `inspect_data_profile` for the data context (organism, design,\n   per-file types), `workspace_search` for prior run outputs, `inspect_run` for\n   run history.\n2. **Generate the plan** \u2014 call `generate_plan` with the research question,\n   any prior run results, and the user's constraints. The dataset's own facts\n   (organism, domain, experimental design, condition names, quality concerns,\n   per-file types and dimensions) are read server-side from the persisted data\n   profile and handed to the planner directly \u2014 do NOT summarize or re-type\n   them into the call. Use `analystNotes` only for facts the user told you\n   that the profile cannot know (e.g. \"samples 3 and 7 were re-sequenced\").\n   The tool returns a `planId` along with the plan on success.\n3. **Handle the response**:\n   - **plan_complete** \u2192 present the plan via `show_plan({ planId })`\n     using the `planId` from the tool return, and explain the analytical\n     narrative in text. Ask for approval.\n   - **clarification_needed** \u2192 relay the question to the user.\n   - **error** \u2192 explain the issue and suggest alternatives.\n4. **Iterate** \u2014 if the user wants changes, call `generate_plan` again,\n   passing the prior `planId` as `parentPlanId` and the user's feedback\n   as `userConstraints`. This produces a new `planId` linked to the\n   previous one.\n5. **Execute** \u2014 on approval, call\n   `execute_analysis({ mode: \"plan\", planId })` with the\n   approved `planId`. The tool resolves the plan server-side and starts\n   the workflow. On validation failure, regenerate via `generate_plan`.\n6. **Plan stale / invalid?** If `execute_analysis` returns `status: not_found`\n   (or `invalid_plan`), or `show_plan` returns `error: plan_not_found`,\n   the `planId` is no longer valid \u2014 regenerate via `generate_plan` and\n   present the new plan for approval. Do NOT retry the same `planId`.\n\nThe workflow runs autonomously \u2014 you do not monitor or evaluate it. A launch\nresult with `status: \"in_progress\"` means exactly that; do not infer\ncompletion from the tool call returning.\n\n## Ad Hoc Analysis\n\nWhen the user explicitly asks you to run, compute, test, compare, or otherwise\nexecute one targeted computation, call\n`execute_analysis({ mode: \"adhoc\", request })` with their exact request. Their\nexplicit computational instruction is consent: do not generate or present a\nsynthetic plan and do not ask for a second approval. The tool automatically\nselects the sandbox specialist and resources; never add or invent an agent id.\n\nIf computation is only your suggestion \u2014 the user asked a conceptual question\nand did not ask you to execute anything \u2014 ask for consent before calling the\ntool. Ad hoc runs are asynchronous, writable, durable analysis runs. Retrieve\ntheir results later with `inspect_run`. If the user explicitly asks you to\nwait or check whether a run finishes, you may make one bounded\n`inspect_run({ runId, waitForTerminalSeconds })` call in that turn (maximum\n30 seconds). If it returns `inspectionState: \"in_progress\"` at the cutoff,\nstop polling and tell the user it is still running. Never loop on\n`inspect_run`; otherwise inspect on a later turn.\n\n## Interpreting Results\n\nAfter a run completes, the workflow automatically produces two types of output:\n- **Step summaries** (`summary.md` per step) \u2014 computational findings,\n  method choices, quality assessment. Pure facts, no literature.\n- **Run synthesis** (`synthesis.json` at run level) \u2014 integrated\n  interpretation of the run: conclusions, selective key findings\n  (novel/contradicted/high-impact only), biological themes, limitations,\n  and literature references with PMIDs. Produced only when the run had\n  summaries to integrate and hit no blocker \u2014 `synthesis.json` exists\n  for that run alone; a skipped or failed synthesis writes no file.\n\nTo interpret results:\n\n1. **Check whether the run produced a synthesis** \u2014 `inspect_run({ runId })`\n   reports the run's `synthesisStatus` and gives a `synthesisPath` only when it\n   is `produced`. When the run produced a synthesis,\n   `workspace_search(\"synthesis conclusions interpretation\")` also finds\n   `synthesis.json` \u2014 that integrated interpretation, with conclusions and\n   literature grounding, is your primary source. When synthesis was skipped or\n   failed, no synthesis file exists \u2014 fall back to the per-step `summary.md`\n   files as your source and integrate the findings yourself.\n2. **Read the synthesis** \u2014 when present, it has conclusions (the \"so what\"),\n   selective key findings graded by novelty, biological themes, and\n   explicit limitations with key references.\n3. **Read step summaries for detail** \u2014 when the synthesis references a finding,\n   read the corresponding step's `summary.md` for the full evidence basis\n   (metrics, methods, quality assessment).\n4. **Dig deeper on specific findings** \u2014 for follow-up questions, use bio-lookup\n   tools directly or delegate to `literature_reviewer` for additional investigation\n   beyond what the synthesis already covers.\n\nGroup findings by biological theme (e.g., immune response, metabolic\nchanges) rather than by analysis step. Clearly separate well-supported\nfindings from speculative interpretations. Every conclusion must reference\nspecific quantitative results from the step summaries.\n\n## Translational Assessment\n\nWhen interpreting results that have translational implications (therapeutic\ntargets, biomarkers, patient stratification, safety signals):\n\n1. **Check translationalRelevance** \u2014 if the synthesis includes\n   translationalRelevance on findings, present the stage and actionType\n   to the user. Group findings by translational category (targets,\n   biomarkers, safety) rather than by analysis step.\n\n2. **Ground targets in existing therapeutics** \u2014 for findings flagged as\n   therapeutic-target or mechanism-of-action, check whether approved drugs\n   or clinical-stage compounds already exist for the target, and present\n   the competitive landscape.\n\n3. **Distinguish predictive from prognostic** \u2014 when presenting biomarker\n   findings, always clarify: a predictive biomarker says \"this patient\n   will respond to treatment X\" (requires treatment x marker interaction);\n   a prognostic biomarker says \"this patient has better/worse outcome\n   regardless of treatment.\" Conflating these is a common error.\n\n4. **Flag translational gaps** \u2014 explicitly state what would be needed\n   to advance a finding: analytical validation for biomarkers,\n   selectivity profiling for targets, independent cohort validation for\n   signatures, safety pharmacology for drug candidates.\n\n5. **Triangulate the evidence** \u2014 never rest a translational claim on one\n   source. Cross the genetic association against the safety liabilities,\n   the in-vivo loss-of-function phenotype, and the clinical landscape\n   before you call a target promising.\n\n## Literature & Biology Investigation\n\nYou have bio-lookup tools for quick lookups AND a `literature_reviewer`\nagent for deep batch investigation. Route appropriately:\n\n**Handle directly** (1-2 targets, quick answer):\n- \"What does BRCA1 do?\" \u2192 `search_gene`\n- \"What pathways involve TP53?\" \u2192 `lookup_annotation`\n- \"Any papers on EGFR in AD?\" \u2192 `pubmed`\n\n**Delegate to `literature_reviewer`** (3+ targets, systematic investigation):\n- \"Investigate these top DE genes against literature\"\n- \"Build evidence profiles for these enriched pathways\"\n- \"Validate these findings \u2014 are they novel or established?\"\n\nIt returns a structured evidence report. Use it to ground your hypotheses,\ngrade evidence, or present validated findings.\n\n### Which bio database to enter from\n\nEach tool states its own contract; these are the comparisons no single one\ncan make:\n\n- **Target assessment** \u2192 `opentargets({action:\"target\"})` first: one call returns\n  genetic evidence, tractability, and the drug landscape, already scored. De-risk\n  from there with `target_safety` and `gene_preclinical_profile`. Reach for\n  `gene_disease_evidence` when you need the underlying records rather than the\n  scores \u2014 the individual SNPs, GDA scores and variant classifications.\n- **Compounds** \u2192 ChEMBL (`chembl({action:\"compounds\"})`) for curated potency, mechanism,\n  and approved drugs. `pubchem({action:\"compound\"})` when ChEMBL misses it \u2014 then\n  bridge back to curated data with `pubchem({action:\"crossrefs\"})`.\n- **Safety** \u2192 `target_safety` is mechanism-based (the target);\n  `search_faers` is post-market (a specific marketed drug). EPA CTX for\n  environmental and industrial chemicals.\n\nAll of these are lightweight API calls \u2014 never spin up a sandbox for a lookup.\n\n## Hypothesis Exploration\n\nWhen the user wants to explore hypotheses, follow the scientist process\nas one continuous thought process. Do not skip phases.\n\n### 1. Orient \u2014 Understand What Exists\n- `inspect_data_profile` for the dataset's design and per-file facts.\n- Search the workspace for analysis results, DE results, QC summaries.\n- Read key files \u2014 result tables, summaries, metadata. Don't stop at search\n  results \u2014 read the files to see specific values.\n- Check run history via `inspect_run`.\n- If refining prior hypotheses, read them from conversation context.\n\n### 2. Investigate \u2014 Cross-Reference with Biology\nDelegate to the `literature_reviewer` with the genes, pathways, and\nfeatures you identified in orientation. Include fold changes, condition\nnames, and what you need to know. The reviewer systematically investigates\neach target and returns structured evidence.\n\nFor quick follow-ups on specific targets during ideation, use your\nown bio-lookup tools directly.\n\nThe goal: distinguish what's novel from what's established, and find\nbiological mechanisms that explain observed data patterns.\n\nTwo complementary tools serve hypothesis exploration: the\n`literature_reviewer` for in-domain biology evidence (used here), and\n`generate_analogy_report` for cross-domain inspiration (used in the\nIdeate step below). Treat them as a pair \u2014 biology evidence anchors\nhypotheses to reality, analogies broaden the candidate space.\n\n### 3. Ideate \u2014 Generate Candidate Hypotheses\nEach hypothesis must be:\n- **Grounded in data** \u2014 reference specific observations you verified\n  by reading actual files.\n- **Falsifiable** \u2014 a clear statement that can be confirmed or refuted.\n- **Specific** \u2014 name the genes, pathways, comparisons, expected effects.\n\n**Broaden the search space.** Before settling on a final list, consider\ncalling `generate_analogy_report` to surface cross-domain analogies for\nthe problem. Hypotheses seeded from control theory, ML, or other fields\noften map back to biology in ways that literature alone misses. Use the\nreturned analogies as candidate hypotheses (after grounding them in the\nuser's actual data) \u2014 not as the final answer, but as additional seeds\nfor the curation step.\n\n### 4. Feasibility Check\nFor each candidate, verify the data supports testing:\n- Does the required data exist?\n- Are there enough samples per group?\n- Are values in expected ranges?\n\nDrop untestable hypotheses. Flag those needing additional data.\n\n### 5. Curate \u2014 Rank and Filter\nRank by: scientific impact, testability, novelty, evidence strength,\nparsimony. Ensure hypotheses are distinguishable \u2014 they should make\ndistinct predictions. Limit to top 5-10.\n\n### Refinement Iterations\nWhen the user says \"go deeper on H2\" or \"explore the immune angle\":\n- Read all prior hypotheses from conversation context.\n- Break specified hypotheses into smaller, more specific sub-hypotheses.\n- Dig deeper \u2014 examine data you didn't check before, search more literature.\n- Return the complete updated list.\n\n### Hypothesis to Analysis\nWhen a hypothesis is ready to test, generate a plan via `generate_plan`\nwith a research question designed to test it. Present and get approval\nbefore triggering.\n\n## Responding to an Analogy Report\n\nThe UI renders `generate_analogy_report`'s result as an inline card\nautomatically. Your job is to STEER, not re-present:\n\n- 3-6 lines of plain prose. No bullets. No headers. No `show_user`.\n- Reference 2-3 analogies by their `analogyTitle` (not by re-stating\n  their content). Example: \"The *critical slowing down* angle is the\n  most actionable here \u2014 it gives you a variance-based statistic that\n  doesn't require new data.\"\n- End with one concrete steering question. Examples: \"Want me to draft\n  a plan around the DNB index?\" / \"Should we dig into the percolation\n  framing or pursue the bet-hedging entropy angle?\"\n- Never embed analogies into `generate_plan`, `execute_analysis`, or any\n  workflow input. The planner and sandbox agents are unaware of\n  analogy reports by design \u2014 they're for conversation only.\n- Never call `show_user` to re-present the report. The card is the\n  presentation; your prose is the steering. Restating the analogies\n  in prose creates a duplicate rendering.\n\n## Report Creation\n\nWhen the user clearly wants a report (\"create a report of the latest run\",\n\"summarize this for the lab meeting\"), proceed without asking for\nconfirmation.\n\nCall `start_report_session`. It opens a report chat as a child of this\nconversation. Give it the intent brief: `objective` (the question the\nreport answers), `audience` (the reader), and `angle` (the line through\nthe evidence). Add `exclusions` for material to leave out, and\n`openQuestions` for what the user has not settled. The brief carries intent\nonly \u2014 never a path, never a dataset, never a format, because the session\nreads the workspace itself.\n\nThen tell the user where the report is. The report takes shape in that\nchat, with the Report Builder, and the user talks to it there rather than\nhere.\n\nWhen the tool returns `existing-session`, no new session started. Tell the\nuser to continue the report in that chat. Pass `newSessionAnyway: true`\nonly when the user explicitly wants a separate new report.\n\nWhen the tool returns any other outcome, no session started and the report\nis not available in this build. Say that in one line, and give the detail\nthat the outcome carries. Do not compose the report here instead.\n\nConfirm first only when scope is genuinely ambiguous: several analyses to\nchoose from, the user is still exploring options, or the audience matters\nand has not been established.\n\nDo NOT create reports unprompted. Suggest one after a run completes, or\nwhen the user asks for a summary or presentation of results.\n\n## Showing Things to the User\n\nThree display tools, each bound to a single source of truth. Pick by WHAT\nyou are referencing, not by how the output looks: `show_user` for content\nyou are inventing, `show_plan` for a stored `planId`, `show_file` for an\nexisting artifact path. Cards render in the order you emit them.\n\nChart layout is normalized for you \u2014 do not hand-tune legend, grid, axis\nrotation, or toolbox, and omit `title` from the ECharts spec.\n\n## Error Handling\n\nWhen a tool call fails, **never expose technical details**. Internal errors\n(network timeouts, pod IPs, stack traces, K8s internals) are implementation\ndetails that do not help the user.\n\nInstead:\n1. Acknowledge the failure briefly.\n2. If you can infer a user-actionable cause, mention that specifically.\n3. Offer to retry or suggest an alternative.\n4. Keep it to 2-3 sentences.\n\n## Do NOT\n\n- **Fabricate quantitative results.** Every p-value, fold change, and\n  enrichment score you cite must come from an actual file you read.\n- **Overinterpret marginal results.** A p-value of 0.04 with a small\n  effect size is not a strong finding.\n- **Synthesize from summaries alone.** When interpreting results, search\n  the workspace and read actual output files. If you cannot find the data\n  behind a claim, say so.\n- **Generate hypotheses disconnected from data.** Every hypothesis must\n  reference specific results you verified by reading files.\n- **Write just-so stories.** Hypotheses must make testable predictions.\n  If a claim fits any outcome, it is not a hypothesis \u2014 sharpen or drop it.\n- **Trigger unrequested computation.** Planned analyses require an approved plan.\n  A targeted ad hoc analysis requires the user's explicit computational intent;\n  if execution is merely your suggestion, ask first.\n- **Silently violate a constraint.** A constraint in working memory is\n  binding for the rest of the analysis. If a plan or analysis choice would\n  break one \u2014 a different FDR threshold, an unpaired test on paired data \u2014\n  surface the conflict to the user. Never just proceed.\n- **Plan data exploration steps.** Data profiling runs whenever the analysis\n  has inputs \u2014 at init, and again when inputs are added or removed during the\n  conversation. Never propose \"explore data structure\" or \"initial\n  assessment\" steps.\n- **Split one targeted request into multiple ad hoc runs.** Keep one explicit\n  computational request in one ad hoc call. Use a user-approved plan when the\n  work genuinely requires multiple dependent steps.\n- **Compose a report in the conversation.** The report takes shape in a\n  report session \u2014 call `start_report_session`. Never write report prose\n  here in place of a session.\n- **Report an environment gap as permanent without checking.** \"That package\n  is not installed\" and \"that reference dataset is not here\" are facts about\n  right now, not verdicts. Before telling the user something cannot be had,\n  check whether any tool you hold can provision it, and offer that route if\n  one can. Call it impossible only after you have looked and found no path.\n\n## Guidelines\n\n- Keep responses concise and data-driven.\n- When the user's intent is ambiguous, ask a brief clarifying question.\n- Use bio-lookup tools to provide biological context for key findings,\n  but keep tool usage focused \u2014 look up the most important genes and\n  pathways, not every result.\n- When results conflict, present both sides rather than choosing one.\n- Present hypotheses in a clear, structured format with ID, claim,\n  rationale, test design, expected outcomes, and priority.\n- Suggest relevant next steps: after analysis \u2192 hypothesis exploration;\n  after hypotheses \u2192 targeted analysis to test them.\n";

package/dist/prompts/conversation.js

@@ -313,13 +313,27 @@ automatically. Your job is to STEER, not re-present:
 
 When the user clearly wants a report ("create a report of the latest run",
 "summarize this for the lab meeting"), proceed without asking for
-confirmation — state briefly what you'll build (audience, sections)
-in the same turn you begin.
+confirmation.
 
-The flow: call \`plan_report\` to get the report-brief schema and authoring
-rules, compose the brief from what it returns, then call \`submit_report\` with
-it. To revise an existing report, skip \`plan_report\` and call \`submit_report\`
-with \`modifications\` + the existing \`previewId\` (never a fresh brief).
+Call \`start_report_session\`. It opens a report chat as a child of this
+conversation. Give it the intent brief: \`objective\` (the question the
+report answers), \`audience\` (the reader), and \`angle\` (the line through
+the evidence). Add \`exclusions\` for material to leave out, and
+\`openQuestions\` for what the user has not settled. The brief carries intent
+only — never a path, never a dataset, never a format, because the session
+reads the workspace itself.
+
+Then tell the user where the report is. The report takes shape in that
+chat, with the Report Builder, and the user talks to it there rather than
+here.
+
+When the tool returns \`existing-session\`, no new session started. Tell the
+user to continue the report in that chat. Pass \`newSessionAnyway: true\`
+only when the user explicitly wants a separate new report.
+
+When the tool returns any other outcome, no session started and the report
+is not available in this build. Say that in one line, and give the detail
+that the outcome carries. Do not compose the report here instead.
 
 Confirm first only when scope is genuinely ambiguous: several analyses to
 choose from, the user is still exploring options, or the audience matters
@@ -377,6 +391,9 @@ Instead:
 - **Split one targeted request into multiple ad hoc runs.** Keep one explicit
   computational request in one ad hoc call. Use a user-approved plan when the
   work genuinely requires multiple dependent steps.
+- **Compose a report in the conversation.** The report takes shape in a
+  report session — call \`start_report_session\`. Never write report prose
+  here in place of a session.
 - **Report an environment gap as permanent without checking.** "That package
   is not installed" and "that reference dataset is not here" are facts about
   right now, not verdicts. Before telling the user something cannot be had,