@poncho-ai/harness 0.53.0 → 0.57.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/harness",
-  "version": "0.53.0",
+  "version": "0.57.0",
   "description": "Agent execution runtime - conversation loop, tool dispatch, streaming",
   "repository": {
     "type": "git",

package/src/compaction.ts

@@ -26,6 +26,20 @@ const SUMMARIZATION_PROMPT = `Summarize the following conversation into a struct
 Be concise but preserve all information needed to continue the task.
 Omit any section that has no relevant content.`;
 
+/**
+ * Extra instruction appended when the first compacted message is itself a
+ * prior compaction summary. The model must treat that block as the existing
+ * working state and produce an updated, merged version rather than
+ * re-summarizing the (already lossy) summary from scratch.
+ */
+const CUMULATIVE_SUMMARY_PROMPT = `The FIRST message below (tagged [prior-summary]) is an existing working-state summary produced by an earlier compaction. Treat it as the authoritative prior working state: MERGE AND UPDATE it with the newer messages that follow it, carrying forward all still-relevant detail. Do NOT discard or re-compress information from the prior summary just because it is older — only drop it if the newer messages explicitly supersede it.`;
+
+/** Max chars of a subagent result text kept verbatim in the ledger digest. */
+const SUBAGENT_DIGEST_CHARS = 500;
+
+/** Heading used for the verbatim, model-proof subagent ledger block. */
+const SUBAGENT_LEDGER_HEADING = "## Subagents";
+
 export const resolveCompactionConfig = (
   explicit?: Partial<CompactionConfig>,
 ): CompactionConfig => {
@@ -78,11 +92,48 @@ export const estimateTotalTokens = (
   return tokens;
 };
 
+/**
+ * Whether an assistant message carries serialized tool_calls. Assistant
+ * tool-call turns serialize their content as a JSON string of the shape
+ * `{"text":...,"tool_calls":[...]}` (see the harness run loop). A plain-text
+ * assistant message returns false.
+ */
+const assistantHasToolCalls = (msg: Message): boolean => {
+  if (msg.role !== "assistant") return false;
+  if (typeof msg.content !== "string") return false;
+  if (!msg.content.includes('"tool_calls"')) return false;
+  try {
+    const parsed = JSON.parse(msg.content) as { tool_calls?: unknown };
+    return Array.isArray(parsed.tool_calls) && parsed.tool_calls.length > 0;
+  } catch {
+    return false;
+  }
+};
+
+/**
+ * Whether splitting at `idx` would orphan a tool-call relationship on the
+ * COMPACTED side — i.e. the last compacted message (`messages[idx-1]`) is an
+ * assistant message with tool_calls whose answering `role:"tool"` result
+ * lives on the PRESERVED side (`messages[idx]`). Folding only the assistant
+ * call into the summary strands the tool_calls with no matching result.
+ */
+const splitOrphansToolCalls = (messages: Message[], idx: number): boolean => {
+  if (idx <= 0 || idx >= messages.length) return false;
+  const lastCompacted = messages[idx - 1]!;
+  return assistantHasToolCalls(lastCompacted);
+};
+
 /**
  * Find the safe split index so that everything before it can be compacted
  * and everything from it onward is preserved. The split always lands just
  * before a `user` message to avoid breaking assistant+tool pairs.
  *
+ * Defensive guard: even at a `user` boundary, refuse a split whose compacted
+ * side would END on an assistant message with unanswered tool_calls (its
+ * `tool` result having moved to the preserved side). Such a split would
+ * orphan the tool_calls inside the summary boundary. When that happens we
+ * walk earlier to the next safe `user` boundary.
+ *
  * Returns -1 if no valid split point is found.
  */
 export const findSafeSplitPoint = (
@@ -92,16 +143,17 @@ export const findSafeSplitPoint = (
   const candidateIdx = messages.length - keepRecentMessages;
   if (candidateIdx < MIN_COMPACTABLE_MESSAGES) return -1;
 
-  // Walk backwards from candidate to find a user message boundary
+  // Walk backwards from candidate to find a user message boundary that does
+  // not orphan a tool-call relationship on the compacted side.
   for (let i = candidateIdx; i >= MIN_COMPACTABLE_MESSAGES; i--) {
-    if (messages[i]!.role === "user") {
+    if (messages[i]!.role === "user" && !splitOrphansToolCalls(messages, i)) {
       return i;
     }
   }
 
-  // Walk forwards from candidate as fallback
+  // Walk forwards from candidate as fallback.
   for (let i = candidateIdx + 1; i < messages.length - 1; i++) {
-    if (messages[i]!.role === "user") {
+    if (messages[i]!.role === "user" && !splitOrphansToolCalls(messages, i)) {
       if (i < MIN_COMPACTABLE_MESSAGES) return -1;
       return i;
     }
@@ -110,25 +162,46 @@ export const findSafeSplitPoint = (
   return -1;
 };
 
+/**
+ * Whether a message is itself a prior compaction summary.
+ */
+const isCompactionSummary = (msg: Message): boolean =>
+  msg.metadata?.isCompactionSummary === true;
+
 /**
  * Build the summarization messages for the generateText call.
+ *
+ * Cumulative behavior: when the FIRST compacted message is itself a prior
+ * compaction summary, it is passed in FULL (not truncated to
+ * SUMMARIZATION_MESSAGE_TRUNCATION_CHARS) and tagged `[prior-summary]`, and
+ * the prompt instructs the model to merge-and-update rather than
+ * re-summarize. All other messages keep the 1200-char truncation.
  */
 const buildSummarizationMessages = (
   messagesToCompact: Message[],
   instructions?: string,
 ): Array<{ role: "user"; content: string }> => {
+  const hasPriorSummary =
+    messagesToCompact.length > 0 && isCompactionSummary(messagesToCompact[0]!);
+
   const conversationLines: string[] = [];
-  for (const msg of messagesToCompact) {
+  for (let i = 0; i < messagesToCompact.length; i++) {
+    const msg = messagesToCompact[i]!;
     const text = getTextContent(msg);
-    const truncated = text.length > SUMMARIZATION_MESSAGE_TRUNCATION_CHARS
-      ? text.slice(0, SUMMARIZATION_MESSAGE_TRUNCATION_CHARS) + "\n...[truncated]"
-      : text;
-    conversationLines.push(`[${msg.role}]: ${truncated}`);
+    const isPrior = i === 0 && hasPriorSummary;
+    // The prior summary is the working state we must not lose — pass it whole.
+    const rendered =
+      isPrior || text.length <= SUMMARIZATION_MESSAGE_TRUNCATION_CHARS
+        ? text
+        : text.slice(0, SUMMARIZATION_MESSAGE_TRUNCATION_CHARS) +
+          "\n...[truncated]";
+    const tag = isPrior ? "prior-summary" : msg.role;
+    conversationLines.push(`[${tag}]: ${rendered}`);
   }
 
-  const prompt = instructions
-    ? `${SUMMARIZATION_PROMPT}\n\nAdditional focus: ${instructions}`
-    : SUMMARIZATION_PROMPT;
+  let prompt = SUMMARIZATION_PROMPT;
+  if (hasPriorSummary) prompt = `${prompt}\n\n${CUMULATIVE_SUMMARY_PROMPT}`;
+  if (instructions) prompt = `${prompt}\n\nAdditional focus: ${instructions}`;
 
   return [
     {
@@ -138,6 +211,121 @@ const buildSummarizationMessages = (
   ];
 };
 
+interface SubagentLedgerEntry {
+  subagentId: string;
+  task: string;
+  status: string;
+  digest: string;
+}
+
+/** Match the header line of an injected subagent callback message. */
+const SUBAGENT_RESULT_HEADER =
+  /^\[Subagent Result\] Subagent "([^"]*)" \(([^)]*)\) (\S+):/;
+
+/**
+ * Parse the metadata + text of a subagent-callback user message into a ledger
+ * entry. Returns null when the message is not a subagent callback.
+ */
+const parseSubagentCallback = (msg: Message): SubagentLedgerEntry | null => {
+  if (msg.role !== "user") return null;
+  const meta = (msg.metadata ?? {}) as Record<string, unknown>;
+  const text = getTextContent(msg);
+  const hasMetaFlag =
+    meta._subagentCallback === true || meta.subagentCallback === true;
+  const hasTextMarker = text.startsWith("[Subagent Result]");
+  if (!hasMetaFlag && !hasTextMarker) return null;
+
+  // Prefer structured metadata, fall back to parsing the header line.
+  const headerMatch = text.match(SUBAGENT_RESULT_HEADER);
+  const subagentId =
+    typeof meta.subagentId === "string" && meta.subagentId
+      ? meta.subagentId
+      : headerMatch?.[2] ?? "";
+  if (!subagentId) return null;
+  const task =
+    typeof meta.task === "string" && meta.task
+      ? meta.task
+      : headerMatch?.[1] ?? "";
+  const status = headerMatch?.[3] ?? "completed";
+
+  // Digest = the body after the header line (the result text), capped.
+  const bodyStart = text.indexOf("\n\n");
+  const body = bodyStart >= 0 ? text.slice(bodyStart + 2) : text;
+  const digest =
+    body.length > SUBAGENT_DIGEST_CHARS
+      ? body.slice(0, SUBAGENT_DIGEST_CHARS) + "…"
+      : body;
+
+  return { subagentId, task, status, digest };
+};
+
+/**
+ * Parse a prior `## Subagents` ledger block out of an existing compaction
+ * summary's content so it can be carried forward cumulatively. The block is
+ * rendered by `renderSubagentLedger`, so we parse that same shape.
+ */
+const parsePriorLedger = (summaryText: string): SubagentLedgerEntry[] => {
+  const headingIdx = summaryText.indexOf(SUBAGENT_LEDGER_HEADING);
+  if (headingIdx < 0) return [];
+  const block = summaryText.slice(headingIdx + SUBAGENT_LEDGER_HEADING.length);
+  const entries: SubagentLedgerEntry[] = [];
+  // Each entry: a bullet line "- **<task>** (<id>) — <status>" then a digest
+  // line. We tolerate missing digest lines.
+  const entryRe =
+    /^- \*\*(.*?)\*\* \((.+?)\) — (\S+)\n {2}(.*)$/gm;
+  let m: RegExpExecArray | null;
+  while ((m = entryRe.exec(block)) !== null) {
+    entries.push({
+      task: m[1]!,
+      subagentId: m[2]!,
+      status: m[3]!,
+      digest: m[4]!,
+    });
+  }
+  return entries;
+};
+
+/**
+ * Scan the messages being compacted for subagent-callback records and any
+ * prior ledger embedded in a compaction summary, returning a combined,
+ * deduped (by subagentId, last-write-wins) list in first-seen order.
+ */
+const collectSubagentLedger = (
+  messagesToCompact: Message[],
+): SubagentLedgerEntry[] => {
+  const byId = new Map<string, SubagentLedgerEntry>();
+  const order: string[] = [];
+  const upsert = (entry: SubagentLedgerEntry) => {
+    if (!byId.has(entry.subagentId)) order.push(entry.subagentId);
+    byId.set(entry.subagentId, entry);
+  };
+
+  for (const msg of messagesToCompact) {
+    if (isCompactionSummary(msg)) {
+      for (const prior of parsePriorLedger(getTextContent(msg))) upsert(prior);
+      continue;
+    }
+    const entry = parseSubagentCallback(msg);
+    if (entry) upsert(entry);
+  }
+
+  return order.map((id) => byId.get(id)!);
+};
+
+/**
+ * Render the subagent ledger as a verbatim markdown block appended to the
+ * summary AFTER the LLM text, so the model can never paraphrase it away.
+ * Returns "" when there are no subagents.
+ */
+const renderSubagentLedger = (entries: SubagentLedgerEntry[]): string => {
+  if (entries.length === 0) return "";
+  const lines = entries.map(
+    (e) =>
+      `- **${e.task}** (${e.subagentId}) — ${e.status}\n  ${e.digest.replace(/\n/g, " ")}`,
+  );
+  return `${SUBAGENT_LEDGER_HEADING}\n${lines.join("\n")}`;
+};
+
 /**
  * Build the continuation message that replaces compacted messages.
  */
@@ -217,7 +405,12 @@ export const compactMessages = async (
       };
     }
 
-    const continuationMessage = buildContinuationMessage(summary);
+    // Append the subagent ledger AFTER the LLM summary, verbatim, so the
+    // model's paraphrasing can never drop or truncate subagent results.
+    const ledger = renderSubagentLedger(collectSubagentLedger(toCompact));
+    const summaryWithLedger = ledger ? `${summary}\n\n${ledger}` : summary;
+
+    const continuationMessage = buildContinuationMessage(summaryWithLedger);
     const compactedMessages = [continuationMessage, ...toPreserve];
 
     return {

package/src/index.ts

@@ -21,6 +21,24 @@ export * from "./telemetry.js";
 export * from "./secrets-store.js";
 export * from "./storage/index.js";
 export * from "./storage/store-adapters.js";
+// Append-only conversation entries (Phase 3 substrate): types + rebuild fns.
+// appendEntries/readEntries are reachable on the ConversationStore /
+// StorageEngine.conversations surfaces already exported above.
+export {
+  buildLlmContext,
+  buildDisplaySnapshot,
+  getPendingSubagentResults,
+  type ConversationEntry,
+  type NewConversationEntry,
+  type UserMessageEntry,
+  type AssistantMessageEntry,
+  type AssistantAmendmentEntry,
+  type HarnessMessageEntry,
+  type CompactionEntry,
+  type SubagentResultEntry,
+  type CallbackStartedEntry,
+  type DisplaySnapshot,
+} from "./storage/entries.js";
 export {
   PonchoFsAdapter,
   type VirtualMount,

package/src/orchestrator/entries-dual-write.ts

@@ -0,0 +1,265 @@
+// ---------------------------------------------------------------------------
+// Phase 3b — dual-write + parity checker (instrumentation only)
+//
+// At each conversation WRITE site we ALSO append the corresponding
+// append-only `ConversationEntry`s alongside the existing mutable-blob write.
+// READ paths are untouched: nothing consumes these entries yet, so a bug here
+// can only mislog — it cannot corrupt behavior. The blob remains the source of
+// truth until the read-cutover PR (3c).
+//
+// Two public surfaces:
+//   - `appendEntriesSafe(...)` — fire-and-forget wrapper that swallows every
+//     error (so a dual-write failure never breaks a live turn) and stamps a
+//     uuid `id` on each entry (the engine inserts `entry.id` as a column).
+//   - `verifyEntriesParity(...)` — gated on `PONCHO_VERIFY_ENTRIES === "1"`,
+//     rebuilds LLM context + display snapshot from the entry log and diffs
+//     them against the blob's `_harnessMessages` / `messages`. Logs mismatches
+//     under `[entries-parity]`. Never throws.
+// ---------------------------------------------------------------------------
+
+import { randomUUID } from "node:crypto";
+import { getTextContent, type Message } from "@poncho-ai/sdk";
+import type { Logger } from "@poncho-ai/sdk";
+import type { Conversation, ConversationStore, PendingSubagentResult } from "../state.js";
+import {
+  buildDisplaySnapshot,
+  buildLlmContext,
+  type ConversationEntry,
+  type NewConversationEntry,
+} from "../storage/entries.js";
+
+/** True when dual-write parity verification is opted in via env. */
+export const entriesParityEnabled = (): boolean =>
+  process.env.PONCHO_VERIFY_ENTRIES === "1";
+
+// DISTRIBUTIVE omit (same reasoning as NewConversationEntry in entries.ts): a
+// plain Omit<NewConversationEntry, "id"> over a union collapses to the keys
+// common to every member, dropping `message`/`result`/etc. Distribute over the
+// union so each member keeps its own discriminant fields.
+type NewEntryNoId = NewConversationEntry extends infer T
+  ? T extends NewConversationEntry
+    ? Omit<T, "id">
+    : never
+  : never;
+
+/**
+ * Append entries to the conversation's append-only log, mirroring an existing
+ * blob write. Best-effort and non-blocking by contract:
+ *   - stamps a fresh uuid `id` on each entry (required input column),
+ *   - never throws (logs and returns [] on failure),
+ *   - is safe to `void` (callers needn't await).
+ *
+ * Returns the stored entries (with seq/createdAt) for callers that want them
+ * (e.g. to learn the assistant entry's id for a later amendment), or [] on
+ * empty input / failure.
+ */
+export const appendEntriesSafe = async (
+  store: ConversationStore,
+  conversation: Pick<Conversation, "conversationId" | "ownerId" | "tenantId">,
+  entries: NewEntryNoId[],
+  log: Logger,
+): Promise<ConversationEntry[]> => {
+  if (entries.length === 0) return [];
+  try {
+    const withIds = entries.map(
+      (e) => ({ id: randomUUID(), ...e }) as NewConversationEntry,
+    );
+    return await store.appendEntries(
+      conversation.conversationId,
+      conversation.ownerId,
+      conversation.tenantId ?? null,
+      withIds,
+    );
+  } catch (err) {
+    log.error(
+      `[entries-dual-write] append failed for ${conversation.conversationId}: ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+    return [];
+  }
+};
+
+// --- entry builders (pure; centralize the best-effort derivation) ----------
+
+export const userMessageEntry = (
+  message: Message,
+  turnId: string,
+  opts?: { hidden?: boolean },
+): NewEntryNoId => ({
+  type: "user_message",
+  message,
+  turnId,
+  ...(opts?.hidden ? { hidden: true } : {}),
+});
+
+export const assistantMessageEntry = (
+  message: Message,
+  turnId: string,
+  runId: string,
+): NewEntryNoId => ({
+  type: "assistant_message",
+  message,
+  turnId,
+  runId,
+});
+
+export const harnessMessageEntries = (
+  messages: Message[],
+  turnId: string,
+): NewEntryNoId[] =>
+  messages.map((message) => ({ type: "harness_message", message, turnId }));
+
+export const compactionEntry = (
+  summaryMessage: Message,
+  firstKeptSeq: number,
+  opts?: { tokensBefore?: number; tokensAfter?: number },
+): NewEntryNoId => ({
+  type: "compaction",
+  summaryMessage,
+  firstKeptSeq,
+  ...(opts?.tokensBefore !== undefined ? { tokensBefore: opts.tokensBefore } : {}),
+  ...(opts?.tokensAfter !== undefined ? { tokensAfter: opts.tokensAfter } : {}),
+});
+
+export const subagentResultEntry = (
+  result: PendingSubagentResult,
+): NewEntryNoId => ({ type: "subagent_result", result });
+
+export const callbackStartedEntry = (consumedSeqs: number[]): NewEntryNoId => ({
+  type: "callback_started",
+  consumedSeqs,
+});
+
+export const assistantAmendmentEntry = (
+  targetEntryId: string,
+  appendText: string,
+): NewEntryNoId => ({
+  type: "assistant_amendment",
+  targetEntryId,
+  ...(appendText ? { appendText } : {}),
+});
+
+// --- "new harness messages this turn" diff ---------------------------------
+
+/**
+ * The harness messages added during the just-finished turn — i.e. the suffix
+ * of the new `_harnessMessages` array beyond what was there before the turn.
+ *
+ * BEST-EFFORT: the blob replaces `_harnessMessages` wholesale (it's not an
+ * append log), so we recover "what's new" by length-diffing prev vs next.
+ * When a compaction collapsed history this turn, `next` can be SHORTER than
+ * `prev`; in that case there's no clean suffix and we return the whole `next`
+ * so the entry log still ends up with the model-visible context (parity will
+ * flag the over-count for review). The compaction entry (appended separately)
+ * is what makes rebuild correct in that case.
+ */
+export const newHarnessMessagesThisTurn = (
+  prev: Message[] | undefined,
+  next: Message[] | undefined,
+): { messages: Message[]; approximate: boolean } => {
+  const prevArr = prev ?? [];
+  const nextArr = next ?? [];
+  if (nextArr.length === 0) return { messages: [], approximate: false };
+  if (prevArr.length === 0) return { messages: nextArr, approximate: false };
+  if (nextArr.length >= prevArr.length) {
+    // Assume the new array is prev + appended suffix (the common case).
+    return { messages: nextArr.slice(prevArr.length), approximate: false };
+  }
+  // next shorter than prev — compaction or a rebuild reshaped the array.
+  return { messages: nextArr, approximate: true };
+};
+
+// --- parity checker ---------------------------------------------------------
+
+/** Normalized text projection for length-insensitive content comparison. */
+const projectText = (m: Message): string => {
+  const role = m.role;
+  const text = getTextContent(m).replace(/\s+/g, " ").trim();
+  return `${role}:${text}`;
+};
+
+const projectAll = (msgs: Message[]): string[] => msgs.map(projectText);
+
+const countMismatch = (label: string, a: number, b: number): string | null =>
+  a === b ? null : `${label} length ${a} (entries) vs ${b} (blob)`;
+
+/**
+ * Rebuild LLM context + display snapshot from the entry log and diff against
+ * the blob. Logs under `[entries-parity]` with the conversationId. Never
+ * throws. No-op unless PONCHO_VERIFY_ENTRIES === "1".
+ */
+export const verifyEntriesParity = async (
+  store: ConversationStore,
+  conversationId: string,
+  blob: { harnessMessages?: Message[]; displayMessages?: Message[] },
+  log: Logger,
+): Promise<void> => {
+  if (!entriesParityEnabled()) return;
+  try {
+    const entries = await store.readEntries(conversationId);
+    const mismatches: string[] = [];
+
+    if (blob.harnessMessages) {
+      const llm = buildLlmContext(entries);
+      const lenMismatch = countMismatch(
+        "llmContext",
+        llm.length,
+        blob.harnessMessages.length,
+      );
+      if (lenMismatch) mismatches.push(lenMismatch);
+      // Compare a trailing normalized text projection. We don't require
+      // byte-equality — metadata, tool-call framing, and exact whitespace
+      // differ by construction between the two representations.
+      const entriesProj = projectAll(llm);
+      const blobProj = projectAll(blob.harnessMessages);
+      const tail = Math.min(entriesProj.length, blobProj.length, 5);
+      for (let i = 1; i <= tail; i++) {
+        const ep = entriesProj[entriesProj.length - i];
+        const bp = blobProj[blobProj.length - i];
+        if (ep !== bp) {
+          mismatches.push(
+            `llmContext tail[-${i}] differs: entries=${JSON.stringify(ep).slice(0, 120)} blob=${JSON.stringify(bp).slice(0, 120)}`,
+          );
+        }
+      }
+    }
+
+    if (blob.displayMessages) {
+      // tailN large enough to cover the whole transcript for the diff.
+      const snap = buildDisplaySnapshot(entries, Number.MAX_SAFE_INTEGER);
+      const lenMismatch = countMismatch(
+        "display",
+        snap.totalMessages,
+        blob.displayMessages.length,
+      );
+      if (lenMismatch) mismatches.push(lenMismatch);
+      const entriesProj = projectAll(snap.messages);
+      const blobProj = projectAll(blob.displayMessages);
+      const tail = Math.min(entriesProj.length, blobProj.length, 5);
+      for (let i = 1; i <= tail; i++) {
+        const ep = entriesProj[entriesProj.length - i];
+        const bp = blobProj[blobProj.length - i];
+        if (ep !== bp) {
+          mismatches.push(
+            `display tail[-${i}] differs: entries=${JSON.stringify(ep).slice(0, 120)} blob=${JSON.stringify(bp).slice(0, 120)}`,
+          );
+        }
+      }
+    }
+
+    if (mismatches.length > 0) {
+      log.warn(
+        `[entries-parity] ${conversationId} MISMATCH (${mismatches.length}): ${mismatches.join(" | ")}`,
+      );
+    } else {
+      log.info(`[entries-parity] ${conversationId} OK`);
+    }
+  } catch (err) {
+    log.error(
+      `[entries-parity] ${conversationId} checker threw (ignored): ${
+        err instanceof Error ? err.message : String(err)
+      }`,
+    );
+  }
+};

package/src/orchestrator/index.ts

@@ -61,3 +61,10 @@ export {
   type RunConversationTurnOpts,
   type RunConversationTurnResult,
 } from "./run-conversation-turn.js";
+
+export {
+  appendEntriesSafe,
+  verifyEntriesParity,
+  entriesParityEnabled,
+  newHarnessMessagesThisTurn,
+} from "./entries-dual-write.js";