@inflexa-ai/harness 0.15.1 → 0.17.0

package/dist/memory/thread-history.js

@@ -20,17 +20,36 @@
  * is the atomic unit; `appendTurn` writes one atomically and `loadRecent`
  * rounds the budget walk to turn boundaries.
  */
+import { randomUUID } from "node:crypto";
 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";
+import { HARNESS_PROVIDER_NAMESPACE, SYNTHETIC_MESSAGE_KEY, envelopeMessage, isSyntheticUserMessage, parseStoredMessageEnvelope, syntheticRecordMessage, } from "./ai-sdk-message-storage.js";
+import { envelopeDisplayMessages, parseStoredDisplayEnvelope } from "./conversation-display-storage.js";
 /** A resolved `ok(undefined)` ResultAsync — the empty/seed transaction step. */
 function okVoid() {
     return new ResultAsync(Promise.resolve(ok(undefined)));
 }
+/**
+ * The append a host uses to record out-of-band work in a thread — an analysis
+ * run's outcome, typically.
+ *
+ * Both projections are built here because a record has no live turn behind it:
+ * no recorder observed it, so nothing else would produce its display projection,
+ * and a record appended without one would be stored, read by the model, and
+ * never shown. The harness owns the record-to-`system` mapping for the same
+ * reason it owns the marker — a host that hand-assembled either could produce a
+ * message the turn-boundary predicates fail to recognise.
+ */
+export function conversationRecordTurn(text) {
+    return {
+        modelMessages: [syntheticRecordMessage(text)],
+        displayMessages: [{ id: randomUUID(), role: "system", parts: [{ type: "text", text, state: "done" }] }],
+    };
+}
 /**
  * A turn starts on a `user` message that a human actually sent. Two kinds of
  * message carry the `user` role without opening a turn, and both are excluded
@@ -156,9 +175,16 @@ export const EVICTION_BLOCK_TURNS = 4;
  * provisioned by the project's state-init DDL.
  */
 export function createThreadHistory(pool) {
-    function appendTurn(threadId, messages, turnUsage) {
+    function appendTurn(threadId, turn) {
+        const { modelMessages: messages, displayMessages, turnUsage } = turn;
         if (messages.length === 0)
             return okVoid();
+        // The display projection rides the append's FIRST row, so one SELECT of a
+        // thread's rows yields every envelope in order with no join and no grouping.
+        // Whichever row that is — a genuine user message opening a turn, or the lone
+        // record row of an out-of-band append — is the row a tail retraction removes
+        // the envelope with, because it is the row the projection describes.
+        const displayEnvelope = displayMessages.length > 0 ? JSON.stringify(envelopeDisplayMessages(displayMessages)) : null;
         // 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,
@@ -185,14 +211,23 @@ 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(
-        // `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)
+        // `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)
                      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`, [threadId, startSeq + i, serializeEnvelope(message), countTokens(message.content), i === rollupRow ? rollup : null])).map(() => undefined)), okVoid()))
+                           reported_usage = EXCLUDED.reported_usage`, [
+            threadId,
+            startSeq + i,
+            serializeEnvelope(message),
+            i === 0 ? displayEnvelope : null,
+            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
@@ -311,15 +346,22 @@ 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, reported_usage
+            `SELECT seq::text AS seq, message_envelope, display_envelope, reported_usage
          FROM messages WHERE thread_id = $1
          ORDER BY messages.seq ASC`, [threadId]);
-            const stored = rows.map((r) => {
+            // 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.
+            const stored = await Promise.all(rows.map(async (r) => {
                 const envelope = parseStoredMessageEnvelope(r.message_envelope, `${threadId}/${r.seq}`);
-                // 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 displayEnvelope = r.display_envelope == null ? undefined : await parseStoredDisplayEnvelope(r.display_envelope, `${threadId}/${r.seq}/display`);
+                return {
+                    seq: Number(r.seq),
+                    envelope,
+                    message: envelope.message,
+                    ...(displayEnvelope ? { displayEnvelope } : {}),
+                    ...(r.reported_usage === null ? {} : { usage: r.reported_usage }),
+                };
+            }));
             const turns = groupTurns(stored, (row) => isGenuineUserStart(row.message));
             const total = turns.length;
             const offset = safePage * safePerPage;

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

@@ -10,20 +10,24 @@
  * the vocabulary is conversation-shaped on purpose — reaching for it inside
  * a workflow step feels immediately wrong.
  *
- * Three lifecycle verbs with distinct guarantees. `archiveThread` is
- * recoverable: it stamps `deleted_at`, and because `getThread` and the default
+ * A thread may name another as its parent, so the rows under one analysis form
+ * a forest rather than a flat list. The three lifecycle verbs each answer that
+ * edge differently, and the differences are the substance of this module.
+ *
+ * `archiveThread` is recoverable: it stamps `deleted_at` on the named thread
+ * and on every descendant, 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.
+ * `messages` rows stay in storage. `unarchiveThread` clears the stamp on ONE
+ * row 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.
+ * metadata rows of the whole subtree 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 subtree's.
  *
  * A purge creates no orphan of its own, but it is NOT serialized against a
  * concurrent `appendTurn`: `messages` carries no foreign key to
@@ -31,17 +35,51 @@
  * 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.
+ * to every thread in the subtree — unbind each from any live conversation —
+ * before purging its root; 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";
 import { type DbError } from "../lib/db-result.js";
+/**
+ * The kind of session a thread holds. `conversation` is the analysis
+ * conversation the product has always had; `report` is a report session spawned
+ * from one.
+ *
+ * The set is closed rather than free-form because a thread's type is what
+ * selects the agent that runs it. That resolution is a separate capability, and
+ * it can only be exhaustive over a membership something can enumerate — a
+ * free-form column pushes an unmatched value into a fallback no reader has the
+ * list to write.
+ *
+ * The array is the single declaration and the union is derived from it, so the
+ * run-time check `createThread` needs — for a value that reached the store from
+ * outside the compiler's reach — cannot drift from the type callers program
+ * against.
+ */
+declare const THREAD_TYPES: readonly ["conversation", "report"];
+export type ThreadType = (typeof THREAD_TYPES)[number];
 /** One conversation thread's metadata, as returned by the store. */
 export interface Thread {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title: string | null;
+    /** Which kind of session this row holds. A thread created without one is a `conversation`. */
+    readonly threadType: ThreadType;
+    /** The thread this one was spawned from — `null` on a thread that stands on its own. */
+    readonly parentThreadId: string | null;
+    /**
+     * The parent's `messages.seq` at the moment of the spawn: the frozen point
+     * in the parent's transcript this thread was built on. `null` exactly when
+     * `parentThreadId` is — half the pair names nothing a consumer can resolve.
+     *
+     * It records the spawn point, not a promise that the prefix still reads the
+     * same: `retractLastTurn` can cut the parent's tail behind an anchor, so a
+     * reader must treat an anchor past the parent's current end as a normal
+     * state rather than a corruption.
+     */
+    readonly parentSeq: number | null;
     readonly createdAt: Date;
     readonly updatedAt: Date;
     /**
@@ -56,7 +94,51 @@ export interface CreateThreadInput {
     readonly threadId: string;
     readonly analysisId: string;
     readonly title?: string | null;
+    /** Omitted is `conversation` — what a thread is when nothing says otherwise. */
+    readonly type?: ThreadType;
+    /**
+     * The thread this one is spawned from. It must belong to the same analysis
+     * as the child; whether it exists at all is the foreign key's verdict, not
+     * this store's.
+     */
+    readonly parentThreadId?: string;
+    /**
+     * The parent's `messages.seq` at the spawn. Supply it with `parentThreadId`
+     * or neither: the two are one fact — which transcript, and how much of it —
+     * and either half alone describes no place.
+     */
+    readonly parentSeq?: number;
 }
+/**
+ * A create the store refuses on its own, before any row is written. Distinct
+ * from `DbError`: nothing failed at the driver — the request described a thread
+ * the store will not write, and each variant carries the identifiers that say
+ * which values disagreed.
+ *
+ * Only the rules the store enforces itself live here. A `parentThreadId` naming
+ * no row is not one of them: the foreign key refuses that insert and
+ * `tryMutation` classifies the refusal as the `constraint_violation` variant of
+ * `DbError`.
+ */
+export type ThreadInputError = {
+    readonly type: "parent_analysis_mismatch";
+    readonly op: string;
+    readonly threadId: string;
+    readonly analysisId: string;
+    readonly parentThreadId: string;
+    readonly parentAnalysisId: string;
+} | {
+    readonly type: "parent_anchor_unpaired";
+    readonly op: string;
+    readonly threadId: string;
+    readonly parentThreadId: string | null;
+    readonly parentSeq: number | null;
+} | {
+    readonly type: "unknown_thread_type";
+    readonly op: string;
+    readonly threadId: string;
+    readonly threadType: string;
+};
 export interface ListThreadsInput {
     readonly analysisId: string;
     readonly page?: number;
@@ -68,6 +150,20 @@ export interface ListThreadsInput {
      * widened back out of.
      */
     readonly includeArchived?: boolean;
+    /**
+     * Narrow to one kind of session, exact match. Omitting it narrows NOTHING —
+     * a caller that supplies no filter receives every type, which is what a
+     * session picker wants: a user browsing an analysis expects to reach a
+     * report session directly.
+     *
+     * That is the opposite polarity to `includeArchived`, which widens a listing
+     * that is narrow by default, and the difference is deliberate. An archived
+     * thread is hidden state — showing it takes an explicit ask. A report
+     * session is not hidden state, so nothing has to ask for it.
+     */
+    readonly type?: ThreadType;
+    /** Narrow to one thread's direct children, exact match. Same polarity as `type`: omitting it narrows nothing. */
+    readonly parentThreadId?: string;
 }
 export interface ThreadPage {
     readonly threads: Thread[];
@@ -80,9 +176,16 @@ export interface ThreadStore {
     /**
      * Create a thread row. Idempotent on `thread_id` — a second create for an
      * existing id is a no-op that preserves the existing row (including its
-     * `created_at`). Returns the live row.
+     * `created_at`) and reads none of the supplied type, parent, or anchor. A
+     * caller that needs those persisted compares them against the returned row.
+     * Returns the live row.
+     *
+     * Refused with a `ThreadInputError`, no row written: a parent belonging to
+     * another analysis, a parent supplied without its anchor or an anchor
+     * without its parent, and a type outside the closed set. A parent naming no
+     * row is the foreign key's refusal and arrives as a `DbError`.
      */
-    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError>;
+    createThread(input: CreateThreadInput): ResultAsync<Thread, DbError | ThreadInputError>;
     /** The live thread by id, or `null` if absent or archived. */
     getThread(threadId: string): ResultAsync<Thread | null, DbError>;
     /**
@@ -91,26 +194,39 @@ export interface ThreadStore {
      */
     updateTitle(threadId: string, title: string): ResultAsync<Thread | null, DbError>;
     /**
-     * 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.
+     * Soft-delete the subtree: stamp `deleted_at` on the named thread and on
+     * every descendant reachable through `parent_thread_id`, at any depth, so a
+     * hidden thread never leaves a visible child behind. Every row and every one
+     * of their messages remain, and any thread in the subtree that was already
+     * archived 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.
+     * Clear `deleted_at` on the named thread ALONE, returning it and its
+     * messages to view exactly as they read before the archive; every descendant
+     * is left as it was found. No-op on a live or absent thread.
+     *
+     * The asymmetry against `archiveThread` is what keeps the schema honest. A
+     * symmetric cascade would restore a child the user had archived on its own
+     * beforehand, so a row would have to record whether a cascade or a
+     * deliberate action set its tombstone — a fourth column carrying nothing
+     * else. With the asymmetry no row needs that distinction, and every archived
+     * thread is recovered the same way: by naming it, which a listing widened
+     * with `includeArchived` supplies.
      */
     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.
+     * Reclaim the subtree's whole footprint: the named thread, every descendant
+     * reachable through `parent_thread_id` at any depth, and the `messages` rows
+     * 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.
      */
     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`
+     * only unless `includeArchived` widens the set, and every type under every
+     * parent unless `type` / `parentThreadId` narrow it; `total` and `hasMore`
      * always describe whichever set the page was drawn from.
      */
     listThreads(input: ListThreadsInput): ResultAsync<ThreadPage, DbError>;
@@ -121,3 +237,4 @@ export interface ThreadStore {
  * `cortex_analysis_threads` table is provisioned by the state-init DDL.
  */
 export declare function createThreadStore(pool: Pool): ThreadStore;
+export {};