@poncho-ai/harness 0.58.0 → 0.59.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.58.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.59.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
 > node scripts/embed-docs.js && tsup src/index.ts --format esm --dts
 
 [embed-docs] Generated poncho-docs.ts with 4 topics
@@ -8,9 +8,9 @@
 CLI tsup v8.5.1
 CLI Target: es2022
 ESM Build start
-ESM dist/index.js            567.32 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM ⚡️ Build success in 177ms
+ESM dist/index.js            567.42 KB
+ESM ⚡️ Build success in 233ms
 DTS Build start
-DTS ⚡️ Build success in 7320ms
+DTS ⚡️ Build success in 7196ms
 DTS dist/index.d.ts 104.68 KB

package/CHANGELOG.md

@@ -1,5 +1,43 @@
 # @poncho-ai/harness
 
+## 0.59.1
+
+### Patch Changes
+
+- [`299f574`](https://github.com/cesr/poncho-ai/commit/299f574a2f2f0d4873f42bbcffdf604e9cc4c29c) Thanks [@cesr](https://github.com/cesr)! - Mark in-flight assistant drafts with `metadata.incomplete = true`.
+
+  The orchestrator's per-step draft persist (`persistDraft`) and the
+  approval/device checkpoint and continuation writes now stamp the trailing
+  assistant message `metadata.incomplete = true`; the three terminal writes
+  (normal finalize, cancelled, errored) clear it. This lets a consumer that
+  reconciles a persisted snapshot against a live event stream (e.g. a
+  WebSocket layer) strip the in-flight draft from the authoritative snapshot
+  and rebuild that turn from the event log instead — so the snapshot and the
+  replayed events never both carry the in-flight turn, eliminating
+  reconnect-time duplication. Additive + backwards-compatible: consumers that
+  ignore the flag are unaffected.
+
+- Updated dependencies [[`299f574`](https://github.com/cesr/poncho-ai/commit/299f574a2f2f0d4873f42bbcffdf604e9cc4c29c)]:
+  - @poncho-ai/sdk@1.15.1
+
+## 0.59.0
+
+### Minor Changes
+
+- [#157](https://github.com/cesr/poncho-ai/pull/157) [`3f65382`](https://github.com/cesr/poncho-ai/commit/3f653820c9e0c66a12b544842c1ad3ddefdfd4a6) Thanks [@cesr](https://github.com/cesr)! - storage: scope the entry read-cutover to pendingSubagentResults only
+
+  The append-only read rebuild now overrides ONLY `pendingSubagentResults`
+  from the entry log — the single conversation field with a write race (a
+  subagent finishing mid-turn vs. the parent turn's whole-blob write). Each
+  result is a race-free INSERT (subagent_result entry) and consumption is a
+  callback_started entry, so reading it from entries means the parent
+  clobbering the blob copy is harmless — that's the clobber-race kill.
+
+  Message history (`messages` / `_harnessMessages`) is written solely by the
+  serialized turn finalize and is never raced, so it stays on the blob
+  (known-good; far simpler than faithfully rebuilding the LLM transcript
+  from entries, which the callback path did not capture correctly).
+
 ## 0.58.0
 
 ### Minor Changes

package/dist/index.js

@@ -2838,19 +2838,16 @@ function getPendingSubagentResults(entries) {
   }
   return entries.filter((e) => e.type === "subagent_result").filter((e) => !consumed.has(e.seq)).map((e) => e.result);
 }
-var FULL_TRANSCRIPT_TAIL = 1e5;
 async function rebuildConversationFromEntries(conversation, readEntries) {
   if (process.env.PONCHO_READ_ENTRIES === "0") return conversation;
   try {
     const entries = await readEntries(conversation.conversationId);
     if (entries.length === 0) return conversation;
-    conversation._harnessMessages = buildLlmContext(entries);
-    conversation.messages = buildDisplaySnapshot(entries, FULL_TRANSCRIPT_TAIL).messages;
     conversation.pendingSubagentResults = getPendingSubagentResults(entries);
     return conversation;
   } catch (err) {
     entriesReadLog.warn(
-      `[entries-read] ${conversation.conversationId} rebuild failed, using blob: ${err instanceof Error ? err.message : String(err)}`
+      `[entries-read] ${conversation.conversationId} pendingSubagentResults rebuild failed, using blob: ${err instanceof Error ? err.message : String(err)}`
     );
     return conversation;
   }
@@ -14480,7 +14477,7 @@ var runConversationTurn = async (opts) => {
   let runContinuationMessages;
   let cancelHarnessMessages;
   let checkpointedRun = false;
-  const buildMessages = () => {
+  const buildMessages = (incomplete = true) => {
     const draftSections = cloneSections(draft.sections);
     if (draft.currentTools.length > 0) {
       draftSections.push({ type: "tools", content: [...draft.currentTools] });
@@ -14499,10 +14496,15 @@ var runConversationTurn = async (opts) => {
       {
         role: "assistant",
         content: draft.assistantResponse,
-        metadata: buildAssistantMetadata(draft, draftSections, {
-          id: assistantId,
-          timestamp: turnTimestamp
-        })
+        metadata: {
+          ...buildAssistantMetadata(draft, draftSections, {
+            id: assistantId,
+            timestamp: turnTimestamp
+          }),
+          // Only stamp the flag when true; finalize omits it so completed
+          // assistants stay clean (no `incomplete: false` noise on the row).
+          ...incomplete ? { incomplete: true } : {}
+        }
       }
     ];
   };
@@ -14724,7 +14726,7 @@ var runConversationTurn = async (opts) => {
     flushTurnDraft(draft);
     latestRunId = execution.latestRunId || latestRunId;
     if (!checkpointedRun && !runContinuationMessages) {
-      conversation.messages = buildMessages();
+      conversation.messages = buildMessages(false);
       applyTurnMetadata(
         conversation,
         {
@@ -14782,7 +14784,7 @@ var runConversationTurn = async (opts) => {
     const aborted = opts.abortSignal?.aborted === true;
     if (aborted || runCancelled) {
       if (draft.assistantResponse.length > 0 || draft.toolTimeline.length > 0 || draft.sections.length > 0) {
-        conversation.messages = buildMessages();
+        conversation.messages = buildMessages(false);
         applyTurnMetadata(
           conversation,
           {
@@ -14831,7 +14833,7 @@ var runConversationTurn = async (opts) => {
       }
     }
     if (draft.assistantResponse.length > 0 || draft.toolTimeline.length > 0 || draft.sections.length > 0) {
-      conversation.messages = buildMessages();
+      conversation.messages = buildMessages(false);
       conversation.updatedAt = Date.now();
       await opts.conversationStore.update(conversation);
     }

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.58.0",
+  "version": "0.59.1",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",
@@ -34,7 +34,7 @@
     "mustache": "^4.2.0",
     "yaml": "^2.4.0",
     "zod": "^3.22.0",
-    "@poncho-ai/sdk": "1.15.0"
+    "@poncho-ai/sdk": "1.15.1"
   },
   "peerDependencies": {
     "esbuild": ">=0.17.0",

package/src/orchestrator/run-conversation-turn.ts

@@ -157,7 +157,15 @@ export const runConversationTurn = async (
   let cancelHarnessMessages: Message[] | undefined;
   let checkpointedRun = false;
 
-  const buildMessages = (): Message[] => {
+  // `incomplete: true` (the default) marks the trailing assistant message as
+  // an in-flight DRAFT — content for a turn that hasn't finished. A consumer
+  // (e.g. PonchOS's WS snapshot) uses this to strip the draft from the
+  // authoritative snapshot: the in-flight turn is delivered by the event
+  // stream instead, so the snapshot and the event log never both carry it
+  // (no reconnect duplication). The three TERMINAL writes (normal finalize,
+  // cancelled, errored) pass `incomplete: false` — at that point the turn is
+  // done and the assistant message is authoritative.
+  const buildMessages = (incomplete = true): Message[] => {
     const draftSections = cloneSections(draft.sections);
     if (draft.currentTools.length > 0) {
       draftSections.push({ type: "tools", content: [...draft.currentTools] });
@@ -179,10 +187,15 @@ export const runConversationTurn = async (
       {
         role: "assistant" as const,
         content: draft.assistantResponse,
-        metadata: buildAssistantMetadata(draft, draftSections, {
-          id: assistantId,
-          timestamp: turnTimestamp,
-        }),
+        metadata: {
+          ...buildAssistantMetadata(draft, draftSections, {
+            id: assistantId,
+            timestamp: turnTimestamp,
+          }),
+          // Only stamp the flag when true; finalize omits it so completed
+          // assistants stay clean (no `incomplete: false` noise on the row).
+          ...(incomplete ? { incomplete: true } : {}),
+        },
       },
     ];
   };
@@ -442,7 +455,7 @@ export const runConversationTurn = async (
     latestRunId = execution.latestRunId || latestRunId;
 
     if (!checkpointedRun && !runContinuationMessages) {
-      conversation.messages = buildMessages();
+      conversation.messages = buildMessages(false); // terminal: turn complete
       applyTurnMetadata(
         conversation,
         {
@@ -515,7 +528,7 @@ export const runConversationTurn = async (
         draft.toolTimeline.length > 0 ||
         draft.sections.length > 0
       ) {
-        conversation.messages = buildMessages();
+        conversation.messages = buildMessages(false); // terminal: cancelled
         applyTurnMetadata(
           conversation,
           {
@@ -571,7 +584,7 @@ export const runConversationTurn = async (
       draft.toolTimeline.length > 0 ||
       draft.sections.length > 0
     ) {
-      conversation.messages = buildMessages();
+      conversation.messages = buildMessages(false); // terminal: errored
       conversation.updatedAt = Date.now();
       await opts.conversationStore.update(conversation);
     }

package/src/storage/entries.ts

@@ -218,10 +218,6 @@ export function getPendingSubagentResults(
     .map((e) => e.result);
 }
 
-// A very large tail so the rebuilt display snapshot is the full transcript.
-// Display callers slice to whatever window they actually render.
-const FULL_TRANSCRIPT_TAIL = 100_000;
-
 /**
  * Phase 3c read cutover: rebuild a conversation's reader-facing fields from
  * the append-only entry log, with a blob fallback for conversations that
@@ -251,19 +247,25 @@ export async function rebuildConversationFromEntries(
   conversation: Conversation,
   readEntries: (conversationId: string) => Promise<ConversationEntry[]>,
 ): Promise<Conversation> {
-  // Kill-switch: ON by default; PONCHO_READ_ENTRIES="0" reverts to blob reads.
+  // Targeted append-only: only `pendingSubagentResults` is read from the
+  // entry log, because it's the ONLY conversation field with a write race
+  // (a subagent finishing mid-turn vs. the parent turn's whole-blob write).
+  // The message history (`messages` / `_harnessMessages`) is written solely
+  // by the turn finalize, which the orchestrator serializes per
+  // conversation — never raced — so it stays on the blob (known-good, and
+  // far simpler than faithfully rebuilding the LLM transcript from entries).
+  //
+  // Kill-switch: ON by default; PONCHO_READ_ENTRIES="0" reverts to the blob.
   if (process.env.PONCHO_READ_ENTRIES === "0") return conversation;
 
   try {
     const entries = await readEntries(conversation.conversationId);
     if (entries.length === 0) return conversation; // fallback: pre-dual-write
-    conversation._harnessMessages = buildLlmContext(entries);
-    conversation.messages = buildDisplaySnapshot(entries, FULL_TRANSCRIPT_TAIL).messages;
     conversation.pendingSubagentResults = getPendingSubagentResults(entries);
     return conversation;
   } catch (err) {
     entriesReadLog.warn(
-      `[entries-read] ${conversation.conversationId} rebuild failed, using blob: ${
+      `[entries-read] ${conversation.conversationId} pendingSubagentResults rebuild failed, using blob: ${
         err instanceof Error ? err.message : String(err)
       }`,
     );

package/test/entries-read-cutover.test.ts

@@ -1,96 +1,80 @@
 import { describe, it, expect, afterEach } from "vitest";
 import { InMemoryConversationStore } from "../src/state.js";
-import {
-  buildLlmContext,
-  buildDisplaySnapshot,
-  type NewConversationEntry,
-} from "../src/storage/entries.js";
+import type { NewConversationEntry } from "../src/storage/entries.js";
 import type { Message } from "@poncho-ai/sdk";
 
 const msg = (role: Message["role"], content: string): Message => ({ role, content });
 
-// A turn's worth of entries: a user display message, the harness (LLM
-// transcript) messages for that turn, and the final assistant bubble.
-function turnEntries(): NewConversationEntry[] {
+// Targeted cutover: ONLY pendingSubagentResults is read from entries. Two
+// subagent results; one later consumed by a callback_started entry.
+function subagentEntries(): NewConversationEntry[] {
   return [
-    { type: "user_message", id: "u1", message: msg("user", "hello"), turnId: "t1" },
-    { type: "harness_message", id: "h1", message: msg("user", "hello"), turnId: "t1" },
-    { type: "harness_message", id: "h2", message: msg("assistant", "hi there"), turnId: "t1" },
-    {
-      type: "assistant_message",
-      id: "a1",
-      message: msg("assistant", "hi there"),
-      turnId: "t1",
-      runId: "r1",
-    },
+    { type: "subagent_result", id: "sr1", result: { subagentId: "s1", task: "a", status: "completed", timestamp: 1 } },
+    { type: "subagent_result", id: "sr2", result: { subagentId: "s2", task: "b", status: "completed", timestamp: 2 } },
   ];
 }
 
-describe("Phase 3c read cutover", () => {
+describe("Phase 3 targeted read cutover (pendingSubagentResults only)", () => {
   const prevFlag = process.env.PONCHO_READ_ENTRIES;
-
   afterEach(() => {
     if (prevFlag === undefined) delete process.env.PONCHO_READ_ENTRIES;
     else process.env.PONCHO_READ_ENTRIES = prevFlag;
   });
 
-  it("get() rebuilds _harnessMessages/messages from entries when present", async () => {
+  it("rebuilds pendingSubagentResults from entries, leaving message history on the blob", async () => {
     delete process.env.PONCHO_READ_ENTRIES; // ON by default
     const store = new InMemoryConversationStore();
     const conv = await store.create("owner", "title", null);
-
-    // Seed the blob with stale messages so we can prove the override happened.
-    conv.messages = [msg("assistant", "STALE BLOB")];
-    conv._harnessMessages = [msg("assistant", "STALE BLOB HARNESS")];
+    // Blob message history must be preserved (never raced, stays authoritative).
+    conv.messages = [msg("user", "hi"), msg("assistant", "hello")];
+    conv._harnessMessages = [msg("user", "hi"), msg("assistant", "hello")];
+    conv.pendingSubagentResults = []; // stale blob value
     await store.update(conv);
 
-    const entries = await store.appendEntries(conv.conversationId, "agent", null, turnEntries());
+    await store.appendEntries(conv.conversationId, "agent", null, subagentEntries());
 
     const loaded = await store.get(conv.conversationId);
     expect(loaded).toBeDefined();
-    expect(loaded!._harnessMessages).toEqual(buildLlmContext(entries));
-    expect(loaded!.messages).toEqual(buildDisplaySnapshot(entries, 100000).messages);
-    // Display transcript drops the harness-only messages; keeps user + assistant bubble.
-    expect(loaded!.messages.map((m) => m.content)).toEqual(["hello", "hi there"]);
+    // pendingSubagentResults comes from entries
+    expect(loaded!.pendingSubagentResults?.map((r) => r.subagentId)).toEqual(["s1", "s2"]);
+    // message history is UNTOUCHED (still the blob)
+    expect(loaded!.messages.map((m) => m.content)).toEqual(["hi", "hello"]);
+    expect(loaded!._harnessMessages?.map((m) => m.content)).toEqual(["hi", "hello"]);
   });
 
-  it("get() falls back to the blob when there are no entries", async () => {
+  it("excludes results consumed by a callback_started entry", async () => {
     delete process.env.PONCHO_READ_ENTRIES;
     const store = new InMemoryConversationStore();
     const conv = await store.create("owner", "title", null);
-    conv.messages = [msg("user", "blob only")];
-    conv._harnessMessages = [msg("user", "blob only harness")];
-    await store.update(conv);
+    const stored = await store.appendEntries(conv.conversationId, "agent", null, subagentEntries());
+    await store.appendEntries(conv.conversationId, "agent", null, [
+      { type: "callback_started", id: "cb1", consumedSeqs: [stored[0]!.seq] },
+    ]);
 
     const loaded = await store.get(conv.conversationId);
-    expect(loaded!.messages).toEqual([msg("user", "blob only")]);
-    expect(loaded!._harnessMessages).toEqual([msg("user", "blob only harness")]);
+    expect(loaded!.pendingSubagentResults?.map((r) => r.subagentId)).toEqual(["s2"]);
   });
 
-  it("kill-switch PONCHO_READ_ENTRIES=0 reverts to blob reads even with entries", async () => {
-    process.env.PONCHO_READ_ENTRIES = "0";
+  it("falls back to the blob pendingSubagentResults when there are no entries", async () => {
+    delete process.env.PONCHO_READ_ENTRIES;
     const store = new InMemoryConversationStore();
     const conv = await store.create("owner", "title", null);
-    conv.messages = [msg("user", "blob wins")];
+    conv.pendingSubagentResults = [{ subagentId: "blob", task: "x", status: "completed", timestamp: 0 }];
     await store.update(conv);
-    await store.appendEntries(conv.conversationId, "agent", null, turnEntries());
 
     const loaded = await store.get(conv.conversationId);
-    expect(loaded!.messages).toEqual([msg("user", "blob wins")]);
+    expect(loaded!.pendingSubagentResults?.map((r) => r.subagentId)).toEqual(["blob"]);
   });
 
-  it("get() does not mutate the stored blob conversation (clone)", async () => {
-    delete process.env.PONCHO_READ_ENTRIES;
+  it("kill-switch PONCHO_READ_ENTRIES=0 reverts to blob even with entries", async () => {
+    process.env.PONCHO_READ_ENTRIES = "0";
     const store = new InMemoryConversationStore();
     const conv = await store.create("owner", "title", null);
-    conv.messages = [msg("assistant", "STALE BLOB")];
+    conv.pendingSubagentResults = [{ subagentId: "blobwins", task: "x", status: "completed", timestamp: 0 }];
     await store.update(conv);
-    await store.appendEntries(conv.conversationId, "agent", null, turnEntries());
+    await store.appendEntries(conv.conversationId, "agent", null, subagentEntries());
 
-    await store.get(conv.conversationId);
-    // Re-read with the kill-switch on: should still see the untouched blob.
-    process.env.PONCHO_READ_ENTRIES = "0";
-    const blob = await store.get(conv.conversationId);
-    expect(blob!.messages).toEqual([msg("assistant", "STALE BLOB")]);
+    const loaded = await store.get(conv.conversationId);
+    expect(loaded!.pendingSubagentResults?.map((r) => r.subagentId)).toEqual(["blobwins"]);
   });
 });