@inflexa-ai/harness 0.39.2 → 0.40.0

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

@@ -3,8 +3,9 @@
  *
  * Conversation-scoped store with an explicit two-method interface and
  * nothing else bundled in (no semantic recall, no working memory, no title
- * generation). It is also the home of context-window management — the read
- * side, `loadRecent`, returns a token-bounded window.
+ * generation). The read side, `loadRecent`, gives the view of the latest
+ * compaction marker: the stored markers decide what a turn sends, and the store
+ * deletes no row.
  *
  * Scope (see the harness-thread-store spec): conversation threads only. A `threadId` is the
  * UI-generated id of one conversation thread (a random UUID — an analysis
@@ -14,11 +15,10 @@
  * conversation-turn shaped on purpose, so reaching for it inside a
  * workflow step feels immediately wrong.
  *
- * The window is always a valid AI SDK model-message sequence: it begins on a
- * `user` message that is genuine user input — never a `tool`-role
- * continuation — and never splits a tool-call/tool-result pair. The turn
- * is the atomic unit; `appendTurn` writes one atomically and `loadRecent`
- * rounds the budget walk to turn boundaries.
+ * The view is always a valid AI SDK model-message sequence: it begins on a
+ * `user` message — never a `tool`-role continuation — and never splits a
+ * tool-call/tool-result pair. A compaction starts only between two rounds, a
+ * drop keeps whole turns, and each write of a group is atomic.
  */
 import type { ModelMessage } from "ai";
 import { ResultAsync } from "neverthrow";
@@ -34,27 +34,26 @@ export interface StoredMessage {
     readonly envelope: StoredMessageEnvelope;
     readonly message: ModelMessage;
     /**
-     * The display projection of the append this row OPENED — present on the first
-     * row of each `appendTurn` and absent on every other row. A conversation turn
-     * and a host-appended record are both appends, so both carry one.
+     * The display projection of the group this row OPENED — present on the first
+     * row of each written group and absent on every other row. The opening of a
+     * turn, a round, a failure note, and a host-appended record are all groups.
      */
     readonly displayEnvelope?: StoredDisplayEnvelope;
     /**
      * What providers reported for the whole TURN this row completed — present
-     * only on the last assistant row of a turn appended with a rollup, absent
-     * everywhere else. Not a per-row figure, and unrelated to the `tokens` count
-     * `loadRecent` windows by: that is an offline estimate stamped on every row,
-     * this is a provider's own report (see the `reported_usage` column comment in
-     * the state-init DDL).
+     * only on the last assistant row of an older turn that stored a rollup on its
+     * rows. A later turn keeps its rollup on its {@link StoredMessage.turn}. Not a
+     * per-row figure, and unrelated to the `tokens` count of the row
+     * (see the `reported_usage` column comment in 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.
+     * present only beside {@link StoredMessage.usage}, on the row of an older turn.
      */
     readonly durationMs?: number;
+    /** The record of the chat turn that this user row opens. Present only on that row. */
+    readonly turn?: StoredTurnRecord;
     /**
      * Who sent the user message of the append this row OPENED — present only on a
      * genuine-user-start row of a turn appended with one. A row written before the
@@ -71,8 +70,8 @@ export interface StoredMessage {
     readonly createdAt?: Date;
 }
 /**
- * One atomic append: the exact provider-facing history, the display projection of
- * what the user was shown, and what the turn reported spending.
+ * One atomic group of rows: the exact provider-facing history, and the display
+ * projection of what the user was shown.
  *
  * The two message projections are independent by design. `modelMessages` is what
  * the provider sees and the only input to token accounting; `displayMessages` is
@@ -84,22 +83,6 @@ export interface ConversationTurn {
     readonly modelMessages: readonly ModelMessage[];
     /** Complete ordered AI SDK UI messages recorded from the live display event stream. */
     readonly displayMessages: readonly ConversationUIMessage[];
-    /**
-     * The turn's reported rollup, as `AgentFinish.turnUsage` carries it out of the
-     * loop. Stored on the LAST assistant message of the turn — the row a reader
-     * associates with the reply. Omitting it, and supplying one that reports no
-     * quantity at all, both leave the row without one: a turn that reported nothing
-     * 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;
     /**
      * Who sent the user message of this turn — the identity the host holds at the
      * append site. Stored on the FIRST row of the append, and only when that row
@@ -123,6 +106,45 @@ export interface ConversationTurn {
  * message the turn-boundary predicates fail to recognise.
  */
 export declare function conversationRecordTurn(text: string): ConversationTurn;
+/** The status of a chat turn: `open` while it runs, then its outcome. */
+export type TurnStatus = "open" | "done" | "aborted" | "failed";
+/** The close of a chat turn. It sets the outcome on the turn record, one time. */
+export interface TurnClose {
+    readonly status: Exclude<TurnStatus, "open">;
+    /** The reason of a failure. */
+    readonly reason?: string;
+    /** A rollup that reports no quantity is stored as absent. */
+    readonly turnUsage?: TokenUsageRollup;
+    readonly turnDurationMs?: number;
+    /** The failure note, stored after the rounds. */
+    readonly note?: ConversationTurn;
+}
+/**
+ * One write of a chat turn. The opening adds the turn record, and a later write names the turn by
+ * `startSeq`. The `never` members make a write with both keys fail to compile.
+ */
+export type TurnWrite = {
+    readonly opening: ConversationTurn;
+    readonly startSeq?: never;
+    readonly rounds: readonly ConversationTurn[];
+    readonly close?: TurnClose;
+} | {
+    readonly startSeq: number;
+    readonly opening?: never;
+    readonly rounds: readonly ConversationTurn[];
+    readonly close?: TurnClose;
+};
+export interface TurnWriteResult {
+    /** The `seq` of the user row that opens the turn, which keys its turn record. */
+    readonly startSeq: number;
+}
+/** The turn record of a chat turn, as the display read gives it. */
+export interface StoredTurnRecord {
+    readonly status: TurnStatus;
+    readonly reason?: string;
+    readonly usage?: TokenUsageRollup;
+    readonly durationMs?: number;
+}
 /**
  * The result of `retractLastTurn`. `retracted` carries `messages` — the number
  * of rows removed — so a caller can assert exactly what came off the tail. The
@@ -138,16 +160,9 @@ export type RetractOutcome = {
 } | {
     kind: "no-user-turn";
 };
-/**
- * The read options of {@link ThreadHistory.loadRecent}. An absent option gives
- * the default window.
- */
+/** The read options of {@link ThreadHistory.loadRecent}. */
 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.
-     */
+    /** Keep the first turn of the thread, the seed of a report thread, in front of the latest summary. */
     readonly keepFirstTurn?: boolean;
 }
 /**
@@ -156,36 +171,23 @@ export interface LoadRecentOptions {
  */
 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 neither the rollup nor the
-     * duration and still succeeds: there is no row on which the two figures
-     * would mean anything.
+     * Append one group, for example a record of a host — every message written in a
+     * single transaction with a `seq` monotonically increasing per thread.
      */
     appendTurn(threadId: string, turn: ConversationTurn): ResultAsync<void, DbError>;
     /**
-     * Return a recent-turns window that fits `tokenBudget`, oldest-first,
-     * snapped to a valid AI SDK model-message sequence. The window START advances
-     * 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.
+     * Write the groups of one chat turn in one transaction, after the rows that the thread holds.
+     * A write with the opening adds the turn record, and a close changes only an `open` record.
+     */
+    writeTurn(threadId: string, write: TurnWrite): ResultAsync<TurnWriteResult, DbError>;
+    /**
+     * The view of the thread: the stored markers decide which rows a turn sends, and a thread with no
+     * marker gives each row. The loop computes each request with the same rule.
      */
-    loadRecent(threadId: string, tokenBudget: number, options?: LoadRecentOptions): ResultAsync<ModelMessage[], DbError>;
+    loadRecent(threadId: string, options?: LoadRecentOptions): ResultAsync<ModelMessage[], DbError>;
     /**
      * Return a thread's messages oldest-first for UI display, grouped into turns.
-     * NOT token-windowed — that is `loadRecent`'s job for the agent loop — and no
-     * eviction.
+     * It gives each row, and the view of the agent loop is `loadRecent`'s job.
      *
      * There is no paginated form, because a page could never cost less: the read
      * selects and parses every row of the thread and would slice only afterwards,
@@ -202,18 +204,10 @@ export interface ThreadHistory {
     loadAll(threadId: string): ResultAsync<StoredMessage[][], DbError>;
     /**
      * Remove the thread's most recent turn — every row from the last
-     * genuine-user-start `seq` onward — in a single transaction.
+     * genuine-user-start `seq` onward, and its turn record — in a single transaction.
      *
-     * Tail-only by design: removal cuts at the last genuine-user-start `seq` —
-     * a turn boundary, not the last append. Because every conversation turn
-     * opens with the user's message, that boundary starts the most recent turn,
-     * so removing it restores the row set the thread held before that turn and
-     * leaves `loadRecent`'s byte-stable prompt-cache prefix untouched; an
-     * out-of-contract assistant-only follow-up append carries no user-start row
-     * and so folds into the removed tail, exactly as the read side's turn
-     * grouping folds it. Deleting mid-history would shift the window head and
-     * rewrite that prefix, so it is deliberately not offered — only the tail
-     * can come off.
+     * When the last turn goes, each earlier prefix stays byte-identical. A later
+     * request never sees a changed earlier record, and only the last turn can go.
      *
      * Callers are assumed single-writer per thread (the host serializes turns);
      * the outcome's `messages` count lets a caller assert exactly what was
@@ -264,28 +258,6 @@ export interface ThreadHistory {
  * freshly-registered `MeterProvider`. Test-only.
  */
 export declare function __resetThreadHistoryMetricsForTest(): void;
-/**
- * Chunked-eviction block size, in whole turns — the granularity at which
- * `loadRecent`'s retained window may advance its START turn.
- *
- * `loadRecent` snaps its eviction count UP to a multiple of this block, so the
- * window's first turn — hence `messages[0]` and the whole tools+system+history
- * prompt-cache prefix — stays byte-identical across a run of appends and shifts
- * only once per block instead of once per turn. That single shift is the only
- * message-cache miss the block costs.
- *
- * The block is at once (a) the cache-miss cadence — one prefix shift per
- * `EVICTION_BLOCK_TURNS` appends once a thread is over budget — and (b) the most
- * extra context ever sacrificed: snapping up drops up to `EVICTION_BLOCK_TURNS -
- * 1` oldest turns the budget alone would have kept, trading a little history for
- * a still prefix. 4 holds the prefix for ~4 turns at a cost of at most 3 turns of
- * headroom — negligible against a ~120k-token budget that spans far more turns,
- * while cutting cache misses on a long thread roughly fourfold. A turn-count
- * block (not a token block) is deliberate: a cache miss is triggered by the START
- * turn moving, a per-turn event, so counting in turns makes the miss cadence
- * exact and independent of how large any individual turn is.
- */
-export declare const EVICTION_BLOCK_TURNS = 4;
 /**
  * Create a `ThreadHistory` bound to a Postgres pool — a factory closure
  * capturing `pool` (dependency injection per the harness-durable-runtime spec). The `messages` table is