@inflexa-ai/harness 0.40.0 → 0.41.0

package/dist/app/chat-turn.d.ts

@@ -1,14 +1,15 @@
 /**
- * The chat turn of a host: a turn is `runChatTurn`, and `prepareChatTurn` is its first step. The
- * host gives only its transport values, and the harness stores the opening, each round, and the outcome.
+ * The chat turn of a host: a turn is `runChatTurn`, which is `openChatTurn` and then the `run` of the
+ * open turn. `prepareChatTurn` is the first step of the open. The host gives only its transport
+ * values, and the harness stores the opening, each round, and the outcome.
  */
 import type { Pool } from "pg";
-import type { AgentSession } from "../auth/types.js";
+import type { RequestSession } from "../auth/types.js";
 import type { UsageRecorder } from "../billing/usage-recorder.js";
 import type { TokenUsageRollup } from "../contracts/usage.js";
 import type { DbError } from "../lib/db-result.js";
 import { type AgentFinish } from "../loop/run-agent.js";
-import type { EmitFn } from "../loop/types.js";
+import type { AgentDefinition, EmitFn } from "../loop/types.js";
 import { type ThreadType } from "../memory/thread-store.js";
 import type { AgentChat, PromptCachePolicy } from "../providers/types.js";
 import type { ThreadAgentResolver } from "../runtime/assemble.js";
@@ -54,12 +55,20 @@ export interface RunChatTurnDeps extends PrepareChatTurnDeps {
     /** The agent of a turn comes from the thread type, which only the preparation knows. */
     readonly agents: ThreadAgentResolver;
 }
-/** The transport values of one turn. */
-export interface RunChatTurnParams {
+/**
+ * The session of a turn without its provenance. The harness sets the provenance from the agent that
+ * it resolves, because only the preparation knows the thread type.
+ */
+export type ChatTurnSession = Omit<RequestSession, "provenance">;
+/** What opens a turn: the thread and the user input. */
+export interface OpenChatTurnParams {
     readonly analysisId: string;
     readonly threadId: string;
     readonly userInput: string;
-    readonly session: AgentSession;
+}
+/** The transport values of a turn that is open. */
+export interface RunOpenChatTurnParams {
+    readonly session: ChatTurnSession;
     /** Makes the provider of the turn over the emit sink of the display recorder. */
     readonly chat: (emit: EmitFn) => AgentChat;
     readonly emit: EmitFn;
@@ -69,13 +78,15 @@ export interface RunChatTurnParams {
     readonly ask?: (request: AskRequest, emit: EmitFn) => Promise<AskApproval>;
     /** Who sent the user message. */
     readonly author?: string;
-    /** When the host opened the turn. Absent counts from the call. */
+    /** When the host opened the turn. Absent counts from the call to {@link openChatTurn}. */
     readonly startedAtMs?: number;
     /** The cache policy of the root loop. Absent gives {@link CONVERSATION_PROMPT_CACHE}. */
     readonly promptCache?: PromptCachePolicy;
     /** The budget of the view of the root loop. Absent gives {@link DEFAULT_CONVERSATION_BUDGET}. */
     readonly conversationBudget?: number;
 }
+/** The values of one whole turn. */
+export type RunChatTurnParams = OpenChatTurnParams & RunOpenChatTurnParams;
 export type ChatTurnOutcome = {
     readonly status: "done";
     readonly finish: AgentFinish;
@@ -87,7 +98,8 @@ export type ChatTurnOutcome = {
     readonly reason: string;
     readonly cause: unknown;
 };
-export type ChatTurnResult = {
+/** A turn that ended before its run. It wrote no row and no turn record. */
+export type ChatTurnRefusal = {
     readonly kind: "prepare_failed";
     readonly cause: unknown;
 } | {
@@ -95,7 +107,8 @@ export type ChatTurnResult = {
 } | {
     readonly kind: "agent_unresolved";
     readonly threadType: ThreadType;
-} | {
+};
+export interface ChatTurnRan {
     readonly kind: "ran";
     readonly outcome: ChatTurnOutcome;
     /** True when the opening of the turn landed. */
@@ -106,9 +119,25 @@ export type ChatTurnResult = {
     readonly turnUsage?: TokenUsageRollup;
     /** The final text of a run that returned. */
     readonly fallbackText?: string;
-};
+}
+export type ChatTurnResult = ChatTurnRefusal | ChatTurnRan;
+/**
+ * A turn that is prepared, with its agent resolved. Call `run` one time: each call stores a new
+ * opening of the same user message.
+ */
+export interface OpenChatTurn {
+    readonly kind: "ready";
+    /** The agent that runs the turn. The harness stamps its provenance on the session of the run. */
+    readonly agent: AgentDefinition;
+    readonly run: (params: RunOpenChatTurnParams) => Promise<ChatTurnRan>;
+}
+/**
+ * Open one chat turn: prepare it and resolve its agent. A refusal comes back before any row of the
+ * turn exists, thus a host can answer it before it starts a stream.
+ */
+export declare function openChatTurn(deps: RunChatTurnDeps, params: OpenChatTurnParams): Promise<OpenChatTurn | ChatTurnRefusal>;
 /**
- * Run one chat turn: prepare it, resolve its agent, store its opening, run the root loop with a
- * round sink that stores each round, and close the turn with its outcome.
+ * Run one chat turn: open it, store its opening, run the root loop with a round sink that stores
+ * each round, and close the turn with its outcome.
  */
 export declare function runChatTurn(deps: RunChatTurnDeps, params: RunChatTurnParams): Promise<ChatTurnResult>;

package/dist/app/chat-turn.js

@@ -1,6 +1,7 @@
 /**
- * The chat turn of a host: a turn is `runChatTurn`, and `prepareChatTurn` is its first step. The
- * host gives only its transport values, and the harness stores the opening, each round, and the outcome.
+ * The chat turn of a host: a turn is `runChatTurn`, which is `openChatTurn` and then the `run` of the
+ * open turn. `prepareChatTurn` is the first step of the open. The host gives only its transport
+ * values, and the harness stores the opening, each round, and the outcome.
  */
 import { unwrapOrThrow } from "../lib/result.js";
 import { finalText, runAgent } from "../loop/run-agent.js";
@@ -100,15 +101,14 @@ async function readTurnContext(pool, analysisId) {
 /** The root loop of a chat turn compacts its view past this estimate, in tokens. */
 export const DEFAULT_CONVERSATION_BUDGET = 150_000;
 /**
- * Run one chat turn: prepare it, resolve its agent, store its opening, run the root loop with a
- * round sink that stores each round, and close the turn with its outcome.
+ * Open one chat turn: prepare it and resolve its agent. A refusal comes back before any row of the
+ * turn exists, thus a host can answer it before it starts a stream.
  */
-export async function runChatTurn(deps, params) {
-    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
-    const startedAtMs = params.startedAtMs ?? Date.now();
+export async function openChatTurn(deps, params) {
+    const openedAtMs = Date.now();
     let prepared;
     try {
-        prepared = await prepareChatTurn(deps, { analysisId: params.analysisId, threadId: params.threadId, userInput: params.userInput });
+        prepared = await prepareChatTurn(deps, params);
     }
     catch (cause) {
         return { kind: "prepare_failed", cause };
@@ -118,8 +118,33 @@ export async function runChatTurn(deps, params) {
     const agent = deps.agents.forThread(prepared.threadType);
     if (agent.isErr())
         return { kind: "agent_unresolved", threadType: prepared.threadType };
+    const ready = prepared;
+    return {
+        kind: "ready",
+        agent: agent.value,
+        run: (run) => runOpenTurn(deps, params, ready, agent.value, { ...run, startedAtMs: run.startedAtMs ?? openedAtMs }),
+    };
+}
+/**
+ * Run one chat turn: open it, store its opening, run the root loop with a round sink that stores
+ * each round, and close the turn with its outcome.
+ */
+export async function runChatTurn(deps, params) {
+    const { analysisId, threadId, userInput, ...run } = params;
+    const opened = await openChatTurn(deps, { analysisId, threadId, userInput });
+    if (opened.kind !== "ready")
+        return opened;
+    return opened.run(run);
+}
+async function runOpenTurn(deps, turn, prepared, agent, params) {
+    const logger = (deps.logger ?? createNoopLogger()).named("harness.chat");
+    const session = { ...params.session, provenance: { agentId: agent.id, callPath: [agent.id] } };
     const history = createThreadHistory(deps.pool, deps.logger);
-    const recorder = createConversationDisplayRecorder({ userText: params.userInput, topLevelCallPath: params.session.provenance.callPath, sink: params.emit });
+    const recorder = createConversationDisplayRecorder({
+        userText: userTextOf(prepared.userMessage),
+        topLevelCallPath: session.provenance.callPath,
+        sink: params.emit,
+    });
     // The groups that did not land yet, in the order of the turn. A failed write keeps them for the next write.
     let pending = [
         {
@@ -136,13 +161,13 @@ export async function runChatTurn(deps, params) {
             return;
         const closing = close === undefined ? {} : { close };
         const write = startSeq === undefined ? { opening: pending[0], rounds: pending.slice(1), ...closing } : { startSeq, rounds: pending, ...closing };
-        (await history.writeTurn(params.threadId, write)).match((written) => {
+        (await history.writeTurn(turn.threadId, write)).match((written) => {
             pending = [];
             startSeq = written.startSeq;
             storeError = undefined;
         }, (error) => {
             storeError = error;
-            logger.warn("chat turn write failed", { threadId: params.threadId, op: error.op, ...logger.errorFields(error.cause) });
+            logger.warn("chat turn write failed", { threadId: turn.threadId, op: error.op, ...logger.errorFields(error.cause) });
         });
     };
     await flush();
@@ -150,7 +175,7 @@ export async function runChatTurn(deps, params) {
     let outcome;
     let fallbackText;
     try {
-        const run = await runAgent(agent.value, prepared.messages, params.session, {
+        const run = await runAgent(agent, prepared.messages, session, {
             provider: params.chat(recorder.emit),
             signal: params.signal,
             emit: recorder.emit,
@@ -158,7 +183,7 @@ export async function runChatTurn(deps, params) {
             usageRecorder: params.usageRecorder,
             toolOutputStore: createToolOutputStore(deps.pool),
             promptCache: params.promptCache ?? CONVERSATION_PROMPT_CACHE,
-            compaction: compactionPolicy(deps, params, prepared.threadType, agent.value, recorder.emit),
+            compaction: compactionPolicy(deps, turn.analysisId, params, prepared.threadType, agent, recorder.emit),
             ...(deps.logger === undefined ? {} : { logger: deps.logger }),
             ...(ask === undefined ? {} : { ask: (request) => ask(request, recorder.emit) }),
             onRound: async (round) => {
@@ -175,7 +200,7 @@ export async function runChatTurn(deps, params) {
         const aborted = params.signal.aborted && cause instanceof Error && cause.name === "AbortError";
         outcome = aborted ? { status: "aborted" } : { status: "failed", reason: failureReasonOf(cause), cause };
     }
-    const durationMs = Date.now() - startedAtMs;
+    const durationMs = Date.now() - params.startedAtMs;
     const turnUsage = outcome.status === "failed" ? undefined : outcome.finish?.turnUsage;
     await flush({
         status: outcome.status,
@@ -193,8 +218,14 @@ export async function runChatTurn(deps, params) {
         ...(fallbackText === undefined ? {} : { fallbackText }),
     };
 }
+/** The sanitized text of the user message, thus the display never holds a secret that the model does not see. */
+function userTextOf(message) {
+    if (typeof message.content === "string")
+        return message.content;
+    return message.content.map((part) => (part.type === "text" ? part.text : "")).join("");
+}
 const WORKING_MEMORY_TOOL_ID = "update_working_memory";
-function compactionPolicy(deps, params, threadType, agent, emit) {
+function compactionPolicy(deps, analysisId, params, threadType, agent, emit) {
     // A report thread reads a frozen copy of the working memory, thus its agent declares no memory tool.
     const remembers = agent.tools.some((tool) => tool.id === WORKING_MEMORY_TOOL_ID);
     const workingMemory = createWorkingMemory(deps.pool);
@@ -205,7 +236,7 @@ function compactionPolicy(deps, params, threadType, agent, emit) {
         request: remembers ? MEMORY_COMPACTION_REQUEST : SUMMARY_COMPACTION_REQUEST,
         mask: remembers ? { allow: [WORKING_MEMORY_TOOL_ID] } : "none",
         keepFirstTurn: threadType === "report",
-        recordsAfter: async (view) => contextRecordsFor({ threadType, analysisId: params.analysisId, workingMemory, ...(await readTurnContext(deps.pool, params.analysisId)) }, view),
+        recordsAfter: async (view) => contextRecordsFor({ threadType, analysisId, workingMemory, ...(await readTurnContext(deps.pool, analysisId)) }, view),
     };
 }
 /** The reason of a failed turn. It never holds the error message, because each later turn sends the note to the vendor. */

package/dist/index.d.ts

@@ -82,8 +82,8 @@ export type { SuspendOn } from "./providers/errors.js";
 export { suspensionOfFailure } from "./workflows/suspension.js";
 export type { Suspension } from "./workflows/suspension.js";
 export { createStreamingChat } from "./providers/streaming-chat.js";
-export { DEFAULT_CONVERSATION_BUDGET, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
-export type { ChatTurnOutcome, ChatTurnResult, PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult, RunChatTurnDeps, RunChatTurnParams, } from "./app/chat-turn.js";
+export { DEFAULT_CONVERSATION_BUDGET, openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
+export type { ChatTurnOutcome, ChatTurnRan, ChatTurnRefusal, ChatTurnResult, ChatTurnSession, OpenChatTurn, OpenChatTurnParams, PrepareChatTurnDeps, PrepareChatTurnParams, PrepareChatTurnResult, RunChatTurnDeps, RunChatTurnParams, RunOpenChatTurnParams, } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export type { ThreadStore, Thread, ThreadType, ThreadInputError, CreateThreadInput, ListThreadsInput, ThreadPage } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";

package/dist/index.js

@@ -130,7 +130,7 @@ export { createStreamingChat } from "./providers/streaming-chat.js";
 // and gives only its transport values: the harness stores the opening, each round,
 // and the outcome. `appendTurn` stays for a record of a host. `createThreadStore`
 // owns thread metadata (create/list/title).
-export { DEFAULT_CONVERSATION_BUDGET, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
+export { DEFAULT_CONVERSATION_BUDGET, openChatTurn, prepareChatTurn, runChatTurn } from "./app/chat-turn.js";
 export { createThreadStore } from "./memory/thread-store.js";
 export { createThreadHistory, conversationRecordTurn } from "./memory/thread-history.js";
 // The synthetic-message primitives. A host appends a record of out-of-band work (an analysis run's

package/package.json

@@ -1,6 +1,6 @@
 {
     "name": "@inflexa-ai/harness",
-    "version": "0.40.0",
+    "version": "0.41.0",
     "description": "Host-agnostic bioinformatics agent harness — hand-rolled agent loop, DBOS-durable workflows, sandboxed compute.",
     "license": "Apache-2.0",
     "type": "module",