@poncho-ai/harness 0.61.0 → 0.61.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.61.0 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.61.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            580.50 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            579.17 KB
-ESM ⚡️ Build success in 267ms
+ESM ⚡️ Build success in 227ms
 DTS Build start
-DTS ⚡️ Build success in 8217ms
-DTS dist/index.d.ts 108.62 KB
+DTS ⚡️ Build success in 7778ms
+DTS dist/index.d.ts 110.56 KB

package/CHANGELOG.md

@@ -1,5 +1,19 @@
 # @poncho-ai/harness
 
+## 0.61.1
+
+### Patch Changes
+
+- [`a16f4fa`](https://github.com/cesr/poncho-ai/commit/a16f4fa32f0809d6ff73f0041cb0e0a3fb980bb1) Thanks [@cesr](https://github.com/cesr)! - Fix: checkpoint-resume no longer drops a turn's user message from the model
+  transcript. Extract the checkpoint→transcript assembly the orchestrator's
+  `resumeRunFromCheckpoint` used into shared, exported helpers —
+  `assembleCheckpointMessages`, `buildToolResultMessage`, `buildResumeCheckpoints`
+  — so external embedders (which execute gated tools themselves) reconstruct the
+  canonical transcript identically instead of re-deriving the index arithmetic
+  and drifting. Add a transcript-integrity guard in `applyTurnMetadata` that
+  logs when a finalize would leave the latest user message out of the
+  model-facing transcript.
+
 ## 0.61.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -2222,6 +2222,40 @@ declare const buildApprovalCheckpoints: ({ approvals, runId, checkpointMessages,
     pendingToolCalls: PendingToolCall[];
     kind?: "approval" | "device";
 }) => NonNullable<Conversation["pendingApprovals"]>;
+/** Reconstruct the full canonical transcript a checkpoint resumes from: the
+ *  prior history (before the checkpointed turn) + the checkpoint delta.
+ *  Handles both storage conventions via `normalizeApprovalCheckpoint` — the
+ *  initial checkpoint (base = prior length, delta) and a resume-created one
+ *  (base 0, full canonical). */
+declare const assembleCheckpointMessages: (conversation: Conversation, checkpoint: StoredApproval) => Message[];
+/** Pair an assistant tool-call message's `tool_calls` with externally-computed
+ *  results into the single `role:"tool"` message a continuation reads.
+ *  Returns undefined when `assistantMsg` isn't an assistant message with
+ *  parseable tool calls. Used to persist the resume's canonical history so it
+ *  matches what `continueFromToolResult` fed the model. Missing results
+ *  default to the deferred-error marker (same text the run uses). */
+declare const buildToolResultMessage: (assistantMsg: Message | undefined, toolResults: Array<{
+    callId: string;
+    toolName: string;
+    result?: unknown;
+    error?: string;
+}>) => Message | undefined;
+/** Build the `pendingApprovals` rows for a checkpoint reached DURING a resume
+ *  continuation. Stores the WHOLE canonical history the continuation ran with
+ *  (`priorMessages` = prior + tool result + new delta) with
+ *  `baseMessageCount: 0`. Keeping the full history here — rather than a delta
+ *  + a base count into a different message array — is what lets the next
+ *  resume reconstruct with no index arithmetic. */
+declare const buildResumeCheckpoints: ({ priorMessages, checkpointEvent, runId, kind, }: {
+    priorMessages: Message[];
+    checkpointEvent: {
+        approvals: ApprovalEventItem[];
+        checkpointMessages: Message[];
+        pendingToolCalls: PendingToolCall[];
+    };
+    runId: string;
+    kind?: "approval" | "device";
+}) => NonNullable<Conversation["pendingApprovals"]>;
 declare const applyTurnMetadata: (conv: Conversation, meta: TurnResultMetadata, opts?: {
     clearContinuation?: boolean;
     clearApprovals?: boolean;
@@ -2503,4 +2537,4 @@ type NewEntryNoId = NewConversationEntry extends infer T ? T extends NewConversa
  */
 declare const appendEntriesSafe: (store: ConversationStore, conversation: Pick<Conversation, "conversationId" | "ownerId" | "tenantId">, entries: NewEntryNoId[], log: Logger) => Promise<ConversationEntry[]>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTaskOutcome, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildSkillContextWindow, buildToolCompletedText, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, findSafeSplitPointByTurns, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, stripPillMetaTokens, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };
+export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type ContinuationHooks, type Conversation, type ConversationCreateInit, type ConversationEntry, type ConversationState, type ConversationStatusSnapshot, type ConversationStore, type ConversationSummary, type CreateSkillToolsOptions, type CronJobConfig, DEFAULT_AGENT_DESCRIPTION, DEFAULT_AGENT_NAME, DEFAULT_MAX_STEPS, DEFAULT_MODEL_NAME, DEFAULT_MODEL_PROVIDER, DEFAULT_TAGLINE, DEFAULT_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type EventSink, type ExecuteTurnResult, type HarnessOptions, type HarnessRunOutput, type HistorySource, InMemoryConversationStore, InMemoryEngine, InMemoryStateStore, type IsolateBinding, type IsolateConfig, LocalMcpBridge, LocalUploadStore, MAX_CONCURRENT_SUBAGENTS, MAX_CONTINUATION_COUNT, MAX_SUBAGENT_CALLBACK_COUNT, MAX_SUBAGENT_NESTING, type MainMemory, type McpConfig, type MemoryConfig, type MemoryStore, type MessagingChannelConfig, type ModelProviderFactory, type MountProvider, type NetworkConfig, type NewConversationEntry, OPENAI_CODEX_CLIENT_ID, type OpenAICodexAuthConfig, type OpenAICodexDeviceAuthRequest, type OpenAICodexSession, type OrchestratorHooks, type OrchestratorOptions, type OtlpConfig, type OtlpOption, PONCHO_UPLOAD_SCHEME, type ParsedAgent, type PendingSubagentApproval, type PendingSubagentResult, type PendingToolCall, type PonchoConfig, PonchoFsAdapter, PostgresEngine, type ProviderConfig, type Recurrence, type RecurrenceType, type Reminder, type ReminderCreateInput, type ReminderStatus, type ReminderStore, type RemoteMcpServerConfig, type RunConversationTurnOpts, type RunConversationTurnResult, type RunOutcome, type RunRequest, type RuntimeRenderContext, S3UploadStore, STALE_SUBAGENT_THRESHOLD_MS, STORAGE_SCHEMA_VERSION, type SecretsStore, type SkillContextEntry, type SkillMetadata, type SkillSource, SqliteEngine, type StateConfig, type StateProviderName, type StateStore, type StorageConfig, type StorageEngine, type StorageFactoryOptions, type StorageProvider, type StoredApproval, type SubagentManager, type SubagentResult, type SubagentResultEntry, type SubagentSpawnResult, type SubagentSummary, type SubagentTaskOutcome, type SubagentTranscript, type SubagentTranscriptMode, TOOL_RESULT_ARCHIVE_PARAM, type TelemetryConfig, TelemetryEmitter, type TenantTokenPayload, type ToolAccess, type ToolCall, ToolDispatcher, type ToolExecutionResult, type TurnDraftState, type TurnResultMetadata, type TurnSection, type UploadStore, type UploadsConfig, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, assembleCheckpointMessages, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildResumeCheckpoints, buildSkillContextWindow, buildToolCompletedText, buildToolResultMessage, cloneSections, compactMessages, completeOpenAICodexDeviceAuth, computeNextOccurrence, createBashTool, createConversationStore, createConversationStoreFromEngine, createDefaultTools, createDeleteDirectoryTool, createDeleteTool, createEditTool, createMemoryStore, createMemoryStoreFromEngine, createMemoryTools, createModelProvider, createReminderStore, createReminderStoreFromEngine, createReminderTools, createSearchTools, createSecretsStore, createSkillTools, createStateStore, createStorageEngine, createSubagentTools, createTodoStoreFromEngine, createTurnDraftState, createUploadStore, createWriteTool, decodeFileInputData, defaultAgentDefinition, deleteOpenAICodexSession, deriveUploadKey, ensureAgentIdentity, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, findSafeSplitPointByTurns, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, stripPillMetaTokens, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };

package/dist/index.js

@@ -12772,6 +12772,7 @@ var resolveRunRequest = (conversation, request) => {
 };
 
 // src/orchestrator/turn.ts
+import { randomUUID as randomUUID6 } from "crypto";
 var createTurnDraftState = () => ({
   assistantResponse: "",
   toolTimeline: [],
@@ -12993,6 +12994,52 @@ var buildApprovalCheckpoints = ({
   pendingToolCalls,
   kind
 }));
+var assembleCheckpointMessages = (conversation, checkpoint) => {
+  const n = normalizeApprovalCheckpoint(checkpoint, conversation.messages);
+  const base = n.baseMessageCount != null ? conversation.messages.slice(0, n.baseMessageCount) : [];
+  return [...base, ...n.checkpointMessages ?? []];
+};
+var buildToolResultMessage = (assistantMsg, toolResults) => {
+  if (assistantMsg?.role !== "assistant") return void 0;
+  let toolCalls = [];
+  try {
+    const parsed = JSON.parse(typeof assistantMsg.content === "string" ? assistantMsg.content : "");
+    toolCalls = parsed.tool_calls ?? [];
+  } catch {
+    return void 0;
+  }
+  if (toolCalls.length === 0) return void 0;
+  const provided = new Map(toolResults.map((r) => [r.callId, r]));
+  return {
+    role: "tool",
+    content: JSON.stringify(
+      toolCalls.map((tc) => {
+        const r = provided.get(tc.id);
+        return {
+          type: "tool_result",
+          tool_use_id: tc.id,
+          tool_name: r?.toolName ?? tc.name,
+          content: r ? r.error ? `Tool error: ${r.error}` : JSON.stringify(r.result ?? null) : "Tool error: Tool execution deferred (pending approval checkpoint)"
+        };
+      })
+    ),
+    metadata: { timestamp: Date.now(), id: randomUUID6() }
+  };
+};
+var buildResumeCheckpoints = ({
+  priorMessages,
+  checkpointEvent,
+  runId,
+  kind = "approval"
+}) => buildApprovalCheckpoints({
+  approvals: checkpointEvent.approvals,
+  runId,
+  checkpointMessages: [...priorMessages, ...checkpointEvent.checkpointMessages],
+  baseMessageCount: 0,
+  pendingToolCalls: checkpointEvent.pendingToolCalls,
+  kind
+});
+var messageText = (m) => typeof m.content === "string" ? m.content : Array.isArray(m.content) ? m.content.map((p) => p.text ?? "").join("") : "";
 var applyTurnMetadata = (conv, meta, opts = {}) => {
   const {
     clearContinuation = true,
@@ -13011,6 +13058,20 @@ var applyTurnMetadata = (conv, meta, opts = {}) => {
   } else if (shouldRebuildCanonical) {
     conv._harnessMessages = conv.messages;
   }
+  if (isMessageArray(conv._harnessMessages) && conv._harnessMessages.length > 0) {
+    const canonical = conv._harnessMessages;
+    const summarized = canonical.some((m) => m.metadata?.isCompactionSummary);
+    const lastUser = [...conv.messages].reverse().find((m) => m.role === "user");
+    const lastUserText = lastUser ? messageText(lastUser).trim() : "";
+    if (!summarized && lastUserText) {
+      const present = canonical.some((m) => m.role === "user" && messageText(m).trim() === lastUserText);
+      if (!present) {
+        console.error(
+          `[transcript-guard] conversation ${conv.conversationId}: model-facing transcript is missing the latest user message \u2014 it diverged from the display transcript. This is a resume/finalize message-assembly bug; the model will not see that turn's input.`
+        );
+      }
+    }
+  }
   if (meta.toolResultArchive !== void 0) {
     conv._toolResultArchive = meta.toolResultArchive;
   }
@@ -13041,12 +13102,12 @@ var STALE_SUBAGENT_THRESHOLD_MS = 5 * 60 * 1e3;
 import { createLogger as createLogger8, getTextContent as getTextContent3 } from "@poncho-ai/sdk";
 
 // src/orchestrator/entries-dual-write.ts
-import { randomUUID as randomUUID6 } from "crypto";
+import { randomUUID as randomUUID7 } from "crypto";
 var appendEntriesSafe = async (store, conversation, entries, log2) => {
   if (entries.length === 0) return [];
   try {
     const withIds = entries.map(
-      (e) => ({ id: randomUUID6(), ...e })
+      (e) => ({ id: randomUUID7(), ...e })
     );
     return await store.appendEntries(
       conversation.conversationId,
@@ -13285,34 +13346,11 @@ var AgentOrchestrator = class {
     });
     let latestRunId = conversation.runtimeRunId ?? "";
     let checkpointedRun = false;
-    const normalizedCheckpoint = normalizeApprovalCheckpoint(checkpoint, conversation.messages);
-    const baseMessages = normalizedCheckpoint.baseMessageCount != null ? conversation.messages.slice(0, normalizedCheckpoint.baseMessageCount) : [];
-    const fullCheckpointMessages = [...baseMessages, ...normalizedCheckpoint.checkpointMessages];
-    let resumeToolResultMsg;
-    const lastCpMsg = fullCheckpointMessages[fullCheckpointMessages.length - 1];
-    if (lastCpMsg?.role === "assistant") {
-      try {
-        const parsed = JSON.parse(typeof lastCpMsg.content === "string" ? lastCpMsg.content : "");
-        const cpToolCalls = parsed.tool_calls ?? [];
-        if (cpToolCalls.length > 0) {
-          const providedMap = new Map(toolResults.map((r) => [r.callId, r]));
-          resumeToolResultMsg = {
-            role: "tool",
-            content: JSON.stringify(cpToolCalls.map((tc) => {
-              const provided = providedMap.get(tc.id);
-              return {
-                type: "tool_result",
-                tool_use_id: tc.id,
-                tool_name: provided?.toolName ?? tc.name,
-                content: provided ? provided.error ? `Tool error: ${provided.error}` : JSON.stringify(provided.result ?? null) : "Tool error: Tool execution deferred (pending approval checkpoint)"
-              };
-            })),
-            metadata: { timestamp: Date.now() }
-          };
-        }
-      } catch {
-      }
-    }
+    const fullCheckpointMessages = assembleCheckpointMessages(conversation, checkpoint);
+    const resumeToolResultMsg = buildToolResultMessage(
+      fullCheckpointMessages[fullCheckpointMessages.length - 1],
+      toolResults
+    );
     const fullCheckpointWithResults = resumeToolResultMsg ? [...fullCheckpointMessages, resumeToolResultMsg] : fullCheckpointMessages;
     let draftRef;
     let execution;
@@ -13357,12 +13395,10 @@ var AgentOrchestrator = class {
             const cpEvent = event;
             const conv = await this.conversationStore.get(conversationId);
             if (conv) {
-              conv.pendingApprovals = buildApprovalCheckpoints({
-                approvals: cpEvent.approvals,
-                runId: latestRunId,
-                checkpointMessages: [...fullCheckpointWithResults, ...cpEvent.checkpointMessages],
-                baseMessageCount: 0,
-                pendingToolCalls: cpEvent.pendingToolCalls
+              conv.pendingApprovals = buildResumeCheckpoints({
+                priorMessages: fullCheckpointWithResults,
+                checkpointEvent: cpEvent,
+                runId: latestRunId
               });
               conv.updatedAt = Date.now();
               await this.conversationStore.update(conv);
@@ -14610,7 +14646,7 @@ ${resultBody}`,
 };
 
 // src/orchestrator/run-conversation-turn.ts
-import { randomUUID as randomUUID7 } from "crypto";
+import { randomUUID as randomUUID8 } from "crypto";
 import { createLogger as createLogger9 } from "@poncho-ai/sdk";
 var log = createLogger9("orchestrator");
 var runConversationTurn = async (opts) => {
@@ -14650,9 +14686,9 @@ var runConversationTurn = async (opts) => {
   const userMessage = {
     role: "user",
     content: userContent,
-    metadata: { id: randomUUID7(), timestamp: turnTimestamp }
+    metadata: { id: randomUUID8(), timestamp: turnTimestamp }
   };
-  const assistantId = randomUUID7();
+  const assistantId = randomUUID8();
   const draft = createTurnDraftState();
   let latestRunId = conversation.runtimeRunId ?? "";
   let runCancelled = false;
@@ -15028,11 +15064,14 @@ export {
   abnormalEndResponse,
   appendEntriesSafe,
   applyTurnMetadata,
+  assembleCheckpointMessages,
   buildAgentDirectoryName,
   buildApprovalCheckpoints,
   buildAssistantMetadata,
+  buildResumeCheckpoints,
   buildSkillContextWindow,
   buildToolCompletedText,
+  buildToolResultMessage,
   cloneSections,
   compactMessages,
   completeOpenAICodexDeviceAuth,

package/package.json

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

package/src/orchestrator/index.ts

@@ -19,6 +19,9 @@ export {
   executeConversationTurn,
   normalizeApprovalCheckpoint,
   buildApprovalCheckpoints,
+  assembleCheckpointMessages,
+  buildToolResultMessage,
+  buildResumeCheckpoints,
   applyTurnMetadata,
   type StoredApproval,
   type PendingToolCall,

package/src/orchestrator/orchestrator.ts

@@ -10,6 +10,9 @@ import {
   applyTurnMetadata,
   normalizeApprovalCheckpoint,
   buildApprovalCheckpoints,
+  assembleCheckpointMessages,
+  buildToolResultMessage,
+  buildResumeCheckpoints,
   createTurnDraftState,
   recordStandardTurnEvent,
   type TurnDraftState,
@@ -421,38 +424,11 @@ export class AgentOrchestrator {
     let latestRunId = conversation.runtimeRunId ?? "";
     let checkpointedRun = false;
 
-    const normalizedCheckpoint = normalizeApprovalCheckpoint(checkpoint, conversation.messages);
-    const baseMessages = normalizedCheckpoint.baseMessageCount != null
-      ? conversation.messages.slice(0, normalizedCheckpoint.baseMessageCount)
-      : [];
-    const fullCheckpointMessages = [...baseMessages, ...normalizedCheckpoint.checkpointMessages!];
-
-    let resumeToolResultMsg: Message | undefined;
-    const lastCpMsg = fullCheckpointMessages[fullCheckpointMessages.length - 1];
-    if (lastCpMsg?.role === "assistant") {
-      try {
-        const parsed = JSON.parse(typeof lastCpMsg.content === "string" ? lastCpMsg.content : "");
-        const cpToolCalls: Array<{ id: string; name: string }> = parsed.tool_calls ?? [];
-        if (cpToolCalls.length > 0) {
-          const providedMap = new Map(toolResults.map(r => [r.callId, r]));
-          resumeToolResultMsg = {
-            role: "tool",
-            content: JSON.stringify(cpToolCalls.map(tc => {
-              const provided = providedMap.get(tc.id);
-              return {
-                type: "tool_result",
-                tool_use_id: tc.id,
-                tool_name: provided?.toolName ?? tc.name,
-                content: provided
-                  ? (provided.error ? `Tool error: ${provided.error}` : JSON.stringify(provided.result ?? null))
-                  : "Tool error: Tool execution deferred (pending approval checkpoint)",
-              };
-            })),
-            metadata: { timestamp: Date.now() },
-          };
-        }
-      } catch { /* last message is not a parseable assistant-with-tools -- skip */ }
-    }
+    const fullCheckpointMessages = assembleCheckpointMessages(conversation, checkpoint);
+    const resumeToolResultMsg = buildToolResultMessage(
+      fullCheckpointMessages[fullCheckpointMessages.length - 1],
+      toolResults,
+    );
     const fullCheckpointWithResults = resumeToolResultMsg
       ? [...fullCheckpointMessages, resumeToolResultMsg]
       : fullCheckpointMessages;
@@ -505,12 +481,10 @@ export class AgentOrchestrator {
             };
             const conv = await this.conversationStore.get(conversationId);
             if (conv) {
-              conv.pendingApprovals = buildApprovalCheckpoints({
-                approvals: cpEvent.approvals,
+              conv.pendingApprovals = buildResumeCheckpoints({
+                priorMessages: fullCheckpointWithResults,
+                checkpointEvent: cpEvent,
                 runId: latestRunId,
-                checkpointMessages: [...fullCheckpointWithResults, ...cpEvent.checkpointMessages],
-                baseMessageCount: 0,
-                pendingToolCalls: cpEvent.pendingToolCalls,
               });
               conv.updatedAt = Date.now();
               await this.conversationStore.update(conv);

package/src/orchestrator/turn.ts

@@ -1,3 +1,4 @@
+import { randomUUID } from "node:crypto";
 import type { AgentEvent, Message } from "@poncho-ai/sdk";
 import type { Conversation } from "../state.js";
 import type { AgentHarness } from "../harness.js";
@@ -341,6 +342,110 @@ export const buildApprovalCheckpoints = ({
     kind,
   }));
 
+// ── Checkpoint transcript reconstruction (single source of truth) ──
+//
+// Resuming a checkpointed turn requires rebuilding the FULL canonical model
+// transcript from what was stored at the pause. Getting this right — in the
+// canonical message space, not the display one — is subtle, and re-deriving
+// it by hand in each embedder is exactly how the model-facing transcript
+// drifted from the display transcript and silently dropped a turn's user
+// message after an approval. These helpers are that logic, exported so the
+// orchestrator's own resume AND external embedders (e.g. PonchOS, which
+// executes gated tools itself) share one implementation that can't drift.
+
+/** Reconstruct the full canonical transcript a checkpoint resumes from: the
+ *  prior history (before the checkpointed turn) + the checkpoint delta.
+ *  Handles both storage conventions via `normalizeApprovalCheckpoint` — the
+ *  initial checkpoint (base = prior length, delta) and a resume-created one
+ *  (base 0, full canonical). */
+export const assembleCheckpointMessages = (
+  conversation: Conversation,
+  checkpoint: StoredApproval,
+): Message[] => {
+  const n = normalizeApprovalCheckpoint(checkpoint, conversation.messages);
+  const base = n.baseMessageCount != null ? conversation.messages.slice(0, n.baseMessageCount) : [];
+  return [...base, ...(n.checkpointMessages ?? [])];
+};
+
+/** Pair an assistant tool-call message's `tool_calls` with externally-computed
+ *  results into the single `role:"tool"` message a continuation reads.
+ *  Returns undefined when `assistantMsg` isn't an assistant message with
+ *  parseable tool calls. Used to persist the resume's canonical history so it
+ *  matches what `continueFromToolResult` fed the model. Missing results
+ *  default to the deferred-error marker (same text the run uses). */
+export const buildToolResultMessage = (
+  assistantMsg: Message | undefined,
+  toolResults: Array<{ callId: string; toolName: string; result?: unknown; error?: string }>,
+): Message | undefined => {
+  if (assistantMsg?.role !== "assistant") return undefined;
+  let toolCalls: Array<{ id: string; name: string }> = [];
+  try {
+    const parsed = JSON.parse(typeof assistantMsg.content === "string" ? assistantMsg.content : "");
+    toolCalls = parsed.tool_calls ?? [];
+  } catch {
+    return undefined;
+  }
+  if (toolCalls.length === 0) return undefined;
+  const provided = new Map(toolResults.map((r) => [r.callId, r]));
+  return {
+    role: "tool",
+    content: JSON.stringify(
+      toolCalls.map((tc) => {
+        const r = provided.get(tc.id);
+        return {
+          type: "tool_result",
+          tool_use_id: tc.id,
+          tool_name: r?.toolName ?? tc.name,
+          content: r
+            ? (r.error ? `Tool error: ${r.error}` : JSON.stringify(r.result ?? null))
+            : "Tool error: Tool execution deferred (pending approval checkpoint)",
+        };
+      }),
+    ),
+    metadata: { timestamp: Date.now(), id: randomUUID() },
+  };
+};
+
+/** Build the `pendingApprovals` rows for a checkpoint reached DURING a resume
+ *  continuation. Stores the WHOLE canonical history the continuation ran with
+ *  (`priorMessages` = prior + tool result + new delta) with
+ *  `baseMessageCount: 0`. Keeping the full history here — rather than a delta
+ *  + a base count into a different message array — is what lets the next
+ *  resume reconstruct with no index arithmetic. */
+export const buildResumeCheckpoints = ({
+  priorMessages,
+  checkpointEvent,
+  runId,
+  kind = "approval",
+}: {
+  priorMessages: Message[];
+  checkpointEvent: {
+    approvals: ApprovalEventItem[];
+    checkpointMessages: Message[];
+    pendingToolCalls: PendingToolCall[];
+  };
+  runId: string;
+  kind?: "approval" | "device";
+}): NonNullable<Conversation["pendingApprovals"]> =>
+  buildApprovalCheckpoints({
+    approvals: checkpointEvent.approvals,
+    runId,
+    checkpointMessages: [...priorMessages, ...checkpointEvent.checkpointMessages],
+    baseMessageCount: 0,
+    pendingToolCalls: checkpointEvent.pendingToolCalls,
+    kind,
+  });
+
+/** Text of a message for the transcript-integrity guard — flattens the two
+ *  content shapes so a user message can be matched across the display and
+ *  canonical transcripts regardless of how each stored it. */
+const messageText = (m: Message): string =>
+  typeof m.content === "string"
+    ? m.content
+    : Array.isArray(m.content)
+      ? m.content.map((p) => (p as { text?: string }).text ?? "").join("")
+      : "";
+
 // ── Turn metadata persistence ──
 
 export const applyTurnMetadata = (
@@ -373,6 +478,31 @@ export const applyTurnMetadata = (
     conv._harnessMessages = conv.messages;
   }
 
+  // Invariant guard: the model-facing transcript must not drop the current
+  // turn's user message. A resume that reconstructed `_harnessMessages`
+  // incorrectly silently lost it (the display transcript kept it, the model
+  // didn't), so the agent second-guessed an approval it never saw. This is the
+  // one choke point every finalize flows through — assert the latest user
+  // message survived into canonical, and log loudly if not. Matched by content
+  // (robust across the display/canonical shapes) and skipped when compaction
+  // has legitimately summarized history. Log-only; never throws.
+  if (isMessageArray(conv._harnessMessages) && conv._harnessMessages.length > 0) {
+    const canonical = conv._harnessMessages;
+    const summarized = canonical.some((m) => m.metadata?.isCompactionSummary);
+    const lastUser = [...conv.messages].reverse().find((m) => m.role === "user");
+    const lastUserText = lastUser ? messageText(lastUser).trim() : "";
+    if (!summarized && lastUserText) {
+      const present = canonical.some((m) => m.role === "user" && messageText(m).trim() === lastUserText);
+      if (!present) {
+        console.error(
+          `[transcript-guard] conversation ${conv.conversationId}: model-facing transcript ` +
+            `is missing the latest user message — it diverged from the display transcript. ` +
+            `This is a resume/finalize message-assembly bug; the model will not see that turn's input.`,
+        );
+      }
+    }
+  }
+
   if (meta.toolResultArchive !== undefined) {
     conv._toolResultArchive = meta.toolResultArchive;
   }

package/test/resume-transcript-integrity.test.ts

@@ -0,0 +1,156 @@
+import { describe, expect, it, vi } from "vitest";
+import type { Message } from "@poncho-ai/sdk";
+import {
+  assembleCheckpointMessages,
+  buildToolResultMessage,
+  buildResumeCheckpoints,
+  applyTurnMetadata,
+  type StoredApproval,
+} from "../src/orchestrator/index.js";
+import type { Conversation } from "../src/state.js";
+
+const conv = (overrides: Partial<Conversation> & Pick<Conversation, "messages">): Conversation => ({
+  conversationId: "conv_test",
+  title: "test",
+  ownerId: "owner",
+  tenantId: null,
+  createdAt: Date.now(),
+  updatedAt: Date.now(),
+  ...overrides,
+});
+
+// An assistant tool-call message is JSON `{ text, tool_calls: [...] }` in the
+// canonical transcript.
+const assistantToolCall = (text: string, calls: Array<{ id: string; name: string }>): Message => ({
+  role: "assistant",
+  content: JSON.stringify({ text, tool_calls: calls.map((c) => ({ ...c, input: {} })) }),
+});
+
+const meta = (harnessMessages?: Message[]) => ({
+  latestRunId: "",
+  contextTokens: 0,
+  contextWindow: 0,
+  harnessMessages,
+});
+
+describe("assembleCheckpointMessages", () => {
+  it("initial checkpoint: prior history (sliced by base) + delta", () => {
+    const prior: Message[] = [
+      { role: "user", content: "hi" },
+      { role: "assistant", content: "hello" },
+    ];
+    // Task-bearing turn: the delta carries the turn's user message + the
+    // assistant preamble/tool-call. base = prior length.
+    const delta: Message[] = [
+      { role: "user", content: "yeah those are a lot better" },
+      assistantToolCall("I found the two PE events…", [{ id: "call_1", name: "update_event" }]),
+    ];
+    const checkpoint = { baseMessageCount: prior.length, checkpointMessages: delta } as StoredApproval;
+    const out = assembleCheckpointMessages(conv({ messages: prior }), checkpoint);
+
+    expect(out).toHaveLength(4);
+    expect(out.some((m) => m.role === "user" && m.content === "yeah those are a lot better")).toBe(true);
+    expect(out.some((m) => typeof m.content === "string" && m.content.includes("I found the two PE events"))).toBe(true);
+  });
+
+  it("resume convention: base 0 + full canonical returns the full canonical verbatim", () => {
+    const full: Message[] = [
+      { role: "user", content: "hi" },
+      { role: "user", content: "approve this" },
+      assistantToolCall("preamble", [{ id: "call_1", name: "t" }]),
+    ];
+    const checkpoint = { baseMessageCount: 0, checkpointMessages: full } as StoredApproval;
+    // Display messages are irrelevant when base is 0 — the reconstruction must
+    // NOT depend on them (this is what the old PonchOS hand-merge got wrong).
+    const out = assembleCheckpointMessages(conv({ messages: [{ role: "user", content: "unrelated display" }] }), checkpoint);
+    expect(out).toEqual(full);
+  });
+});
+
+describe("buildToolResultMessage", () => {
+  const asst = assistantToolCall("", [{ id: "call_1", name: "update_event" }]);
+
+  it("pairs a provided result by callId", () => {
+    const msg = buildToolResultMessage(asst, [{ callId: "call_1", toolName: "update_event", result: { ok: true } }]);
+    expect(msg?.role).toBe("tool");
+    expect(msg?.content).toContain("call_1");
+    expect(msg?.content).toContain("ok");
+  });
+
+  it("emits the deferred-error marker when a result is missing", () => {
+    const msg = buildToolResultMessage(asst, []);
+    expect(msg?.content).toContain("Tool execution deferred");
+  });
+
+  it("returns undefined for a non-assistant / non-tool-call message", () => {
+    expect(buildToolResultMessage({ role: "user", content: "hi" }, [])).toBeUndefined();
+    expect(buildToolResultMessage({ role: "assistant", content: "plain text" }, [])).toBeUndefined();
+  });
+});
+
+describe("buildResumeCheckpoints + round-trip (the regression)", () => {
+  it("stores full canonical (base 0) so the NEXT resume reconstructs without dropping the user turn", () => {
+    // The continuation ran with this full canonical (incl. the turn's user
+    // message + preamble) and appended a tool result.
+    const fullWithResults: Message[] = [
+      { role: "user", content: "hi" },
+      { role: "assistant", content: "hello" },
+      { role: "user", content: "approve this" },
+      assistantToolCall("preamble text", [{ id: "call_1", name: "t1" }]),
+      { role: "tool", content: JSON.stringify([{ type: "tool_result", tool_use_id: "call_1", content: "done" }]) },
+    ];
+    // It then gated again on a new tool (the re-checkpoint event delta).
+    const delta2: Message[] = [assistantToolCall("", [{ id: "call_2", name: "t2" }])];
+    const stored = buildResumeCheckpoints({
+      priorMessages: fullWithResults,
+      checkpointEvent: {
+        approvals: [{ approvalId: "a2", tool: "t2", toolCallId: "call_2", input: {} }],
+        checkpointMessages: delta2,
+        pendingToolCalls: [{ id: "call_2", name: "t2", input: {} }],
+      },
+      runId: "run_2",
+    });
+
+    expect(stored[0]!.baseMessageCount).toBe(0);
+    expect(stored[0]!.checkpointMessages).toEqual([...fullWithResults, ...delta2]);
+
+    // Next resume reconstructs from the stored checkpoint — display is
+    // deliberately unrelated to prove no dependence on it.
+    const reconstructed = assembleCheckpointMessages(
+      conv({ messages: [{ role: "user", content: "unrelated" }], pendingApprovals: stored }),
+      stored[0]!,
+    );
+    // The user turn + preamble that PonchOS used to drop MUST survive.
+    expect(reconstructed.some((m) => m.role === "user" && m.content === "approve this")).toBe(true);
+    expect(reconstructed.some((m) => typeof m.content === "string" && m.content.includes("preamble text"))).toBe(true);
+  });
+});
+
+describe("applyTurnMetadata transcript-integrity guard", () => {
+  const latestUser: Message = { role: "user", content: "the latest question", metadata: { id: "u_latest" } };
+
+  it("logs when the latest user message is missing from the canonical transcript", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const c = conv({ messages: [{ role: "assistant", content: "earlier" }, latestUser] });
+    // Canonical is missing "the latest question" — the exact divergence.
+    applyTurnMetadata(c, meta([{ role: "user", content: "hi" }, { role: "assistant", content: "x" }]));
+    expect(spy).toHaveBeenCalledWith(expect.stringContaining("[transcript-guard]"));
+    spy.mockRestore();
+  });
+
+  it("stays silent when the latest user message is present in canonical", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const c = conv({ messages: [latestUser] });
+    applyTurnMetadata(c, meta([{ role: "user", content: "the latest question" }, { role: "assistant", content: "reply" }]));
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+
+  it("skips the check when canonical was legitimately compacted", () => {
+    const spy = vi.spyOn(console, "error").mockImplementation(() => {});
+    const c = conv({ messages: [latestUser] });
+    applyTurnMetadata(c, meta([{ role: "assistant", content: "summary", metadata: { isCompactionSummary: true } }]));
+    expect(spy).not.toHaveBeenCalled();
+    spy.mockRestore();
+  });
+});