@poncho-ai/harness 0.59.1 → 0.59.3

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/harness@0.59.1 build /home/runner/work/poncho-ai/poncho-ai/packages/harness
+> @poncho-ai/harness@0.59.3 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            556.92 KB
 ESM dist/isolate-F2PPSUL6.js 53.82 KB
-ESM dist/index.js            567.42 KB
-ESM ⚡️ Build success in 233ms
+ESM ⚡️ Build success in 268ms
 DTS Build start
-DTS ⚡️ Build success in 7196ms
-DTS dist/index.d.ts 104.68 KB
+DTS ⚡️ Build success in 8081ms
+DTS dist/index.d.ts 101.11 KB

package/CHANGELOG.md

@@ -1,5 +1,33 @@
 # @poncho-ai/harness
 
+## 0.59.3
+
+### Patch Changes
+
+- [`c9f7331`](https://github.com/cesr/poncho-ai/commit/c9f733190103bcb1ec1b0173c6760a8ef4bea2f3) Thanks [@cesr](https://github.com/cesr)! - Reframe `conversation_entries` as the subagent delivery queue and delete the
+  abandoned transcript dual-write. The entry log now carries exactly two types
+  — `subagent_result` (race-free delivery of a finished subagent's result) and
+  `callback_started` (consumption marker) — which is the one conversation
+  field with concurrent writers. The unread transcript entry types
+  (user/assistant/harness messages, compaction overlays), their dual-write
+  call sites, and the parity checker were groundwork for a full blob
+  replacement that was deliberately abandoned after the 0.58.0 cutover
+  incident; they were already unfaithful for callback turns and are deleted
+  rather than maintained as drift-prone dead weight. Read paths now filter the
+  queue types explicitly, so legacy transcript rows are ignored. Also fixes
+  `conversations.rename` to update the title inside the `data` blob (via an
+  atomic in-database JSON set) — the 0.59.2 column-only update didn't surface
+  on reads, which parse the blob.
+
+## 0.59.2
+
+### Patch Changes
+
+- [`ac0faae`](https://github.com/cesr/poncho-ai/commit/ac0faae54365afda5ef518b0a306a8cde5978ca8) Thanks [@cesr](https://github.com/cesr)! - conversations.rename now does a targeted title-column UPDATE instead of a
+  whole-row get→mutate→update. The read-modify-write raced a streaming turn's
+  per-step draft persist: a rename landing mid-run wrote the stale blob back
+  and silently reverted the turn's persisted progress.
+
 ## 0.59.1
 
 ### Patch Changes

package/dist/index.d.ts

@@ -127,24 +127,39 @@ interface CompactResult {
 declare const compactMessages: (model: LanguageModel, messages: Message[], config: CompactionConfig, options?: CompactMessagesOptions) => Promise<CompactResult>;
 
 /**
- * Append-only conversation entries (Phase 3 substrate).
+ * The subagent delivery queue: append-only `conversation_entries` rows that
+ * carry a finished subagent's result to its parent conversation.
  *
- * The eventual replacement for the mutable per-conversation JSON blob: a
- * conversation becomes an ordered, append-only list of entries, and the
- * mutable-blob clobber race (two writers serializing a stale whole-blob
- * snapshot over each other — the root cause behind lost subagent results)
- * stops being expressible.
+ * Why this exists: subagent results are the ONE conversation field with
+ * concurrent writers. A subagent finishes whenever it finishes — possibly
+ * while the parent turn is mid-stream doing whole-blob writes — so a
+ * read-modify-write on the mutable conversation row could serialize a stale
+ * snapshot over the result (the historical "lost subagent result" clobber).
+ * An append-only INSERT can't express that race. Everything single-writer
+ * (message history, metadata) stays on the conversation row, where the
+ * orchestrator's per-conversation turn serialization already makes mutation
+ * safe.
  *
- * This module is intentionally PURE: it defines the entry shapes and the
- * functions that rebuild a conversation's LLM context / display transcript
- * / pending-subagent-results from an entry list. No storage engine, no DB,
- * no wiring into the live run loop yet — so it deploys nothing and is
- * fully unit-testable. The engine implementations (append/read on
- * postgres/sqlite/memory) and the write-site conversions come in later PRs
- * once this rebuild logic is proven.
+ * Two entry types:
+ *   - `subagent_result`: a finished subagent's result, appended by the
+ *     orchestrator's result-delivery path.
+ *   - `callback_started`: marks which result entries a callback turn
+ *     consumed (by seq). Consumption is an append, never a delete — a
+ *     result is "pending" until a later callback_started lists its seq.
  *
- * Ordering: every entry carries a monotonic per-conversation `seq`. Entries
- * are assumed sorted by `seq` ascending when passed to the rebuild fns.
+ * Historical note: this module once defined a full transcript's worth of
+ * entry types (user/assistant/harness messages, compaction overlays) as
+ * groundwork for replacing the conversation blob entirely. The full read
+ * cutover shipped briefly (harness 0.58.0), proved unfaithful for callback
+ * turns, and was reverted; the unread types + dual-writes were then deleted
+ * rather than maintained as drift-prone dead weight. If a future feature
+ * needs real history semantics (editing, branching, audit), design that
+ * migration fresh — and remember the 0.58.0 lesson: an append-only log is
+ * only as good as the completeness of its writers.
+ *
+ * Ordering: every entry carries a monotonic per-conversation `seq`,
+ * assigned by the engine at append time. Entries are sorted by `seq`
+ * ascending when passed to the rebuild fn.
  */
 interface BaseEntry {
     /** Stable cross-reference id (uuid). */
@@ -153,48 +168,6 @@ interface BaseEntry {
     seq: number;
     createdAt: number;
 }
-/** A user-role display message (incl. typed subagent-callback messages). */
-interface UserMessageEntry extends BaseEntry {
-    type: "user_message";
-    message: Message;
-    turnId: string;
-    /** Hidden from the display transcript (e.g. a framed job prompt, an
-     *  onboarding seed, or an injected subagent-result message). Still part
-     *  of the record; just not rendered as a chat bubble. */
-    hidden?: boolean;
-}
-/** The final assistant bubble for a completed/cancelled/errored turn. */
-interface AssistantMessageEntry extends BaseEntry {
-    type: "assistant_message";
-    message: Message;
-    turnId: string;
-    runId: string;
-}
-/** A post-hoc edit to an already-emitted assistant message — replaces the
- *  orchestrator/resume "mutate the last assistant message in place" writes
- *  with an append. Applied at rebuild time. */
-interface AssistantAmendmentEntry extends BaseEntry {
-    type: "assistant_amendment";
-    targetEntryId: string;
-    appendText?: string;
-}
-/** One LLM-transcript message (the model-visible form). Appended from the
- *  run loop per step — never diffed from an array. */
-interface HarnessMessageEntry extends BaseEntry {
-    type: "harness_message";
-    message: Message;
-    turnId: string;
-}
-/** Compaction overlay: nothing is deleted. At rebuild, the LLM context is
- *  the latest compaction's `summaryMessage` followed by the harness
- *  messages from `firstKeptSeq` onward. */
-interface CompactionEntry extends BaseEntry {
-    type: "compaction";
-    summaryMessage: Message;
-    firstKeptSeq: number;
-    tokensBefore?: number;
-    tokensAfter?: number;
-}
 /** A finished subagent's result arriving for the parent. Pending = a
  *  subagent_result whose seq is not listed in any later callback_started. */
 interface SubagentResultEntry extends BaseEntry {
@@ -207,38 +180,15 @@ interface CallbackStartedEntry extends BaseEntry {
     type: "callback_started";
     consumedSeqs: number[];
 }
-type ConversationEntry = UserMessageEntry | AssistantMessageEntry | AssistantAmendmentEntry | HarnessMessageEntry | CompactionEntry | SubagentResultEntry | CallbackStartedEntry;
+type ConversationEntry = SubagentResultEntry | CallbackStartedEntry;
 /**
  * An entry to append, before the engine assigns `seq` and `createdAt`. This
  * is a DISTRIBUTIVE omit — `Omit<ConversationEntry, K>` over a union would
- * collapse to only the keys common to every member (dropping `message`,
- * `summaryMessage`, etc.), so we distribute over the union with a
- * conditional type to omit those fields from each member individually.
+ * collapse to only the keys common to every member, so we distribute over
+ * the union with a conditional type to omit those fields from each member
+ * individually.
  */
 type NewConversationEntry = ConversationEntry extends infer T ? T extends ConversationEntry ? Omit<T, "seq" | "createdAt"> : never : never;
-/**
- * Rebuild the LLM-visible message context from the entry log.
- *
- * If a compaction overlay exists, the context is its summary message
- * followed by every harness message with seq >= firstKeptSeq (a later
- * compaction's firstKeptSeq can point at an earlier summary that was
- * itself appended as a harness message, so layered compactions just work).
- * With no compaction, it's every harness message in order.
- */
-declare function buildLlmContext(entries: ConversationEntry[]): Message[];
-interface DisplaySnapshot {
-    messages: Message[];
-    /** Total display messages available (for pagination UIs). */
-    totalMessages: number;
-    /** seq of the first message returned (a `beforeSeq` pagination cursor). */
-    headSeq: number | null;
-}
-/**
- * Rebuild the display transcript (the user-visible chat) from the entry
- * log, returning the trailing `tailN` messages. Amendments are folded into
- * their target assistant message; hidden user messages are dropped.
- */
-declare function buildDisplaySnapshot(entries: ConversationEntry[], tailN: number): DisplaySnapshot;
 /**
  * Subagent results that have arrived but not yet been consumed by a
  * callback turn — the append-only replacement for the mutable
@@ -2403,45 +2353,16 @@ interface RunConversationTurnResult {
 }
 declare const runConversationTurn: (opts: RunConversationTurnOpts) => Promise<RunConversationTurnResult>;
 
-/** True when dual-write parity verification is opted in via env. */
-declare const entriesParityEnabled: () => boolean;
 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:
+ * Append entries to the conversation's queue. Best-effort 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).
+ *   - safe to `void` when the caller doesn't need the stored rows.
  *
- * 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.
+ * Returns the stored entries (with seq/createdAt) — the callback path needs
+ * the seqs to record consumption.
  */
 declare const appendEntriesSafe: (store: ConversationStore, conversation: Pick<Conversation, "conversationId" | "ownerId" | "tenantId">, entries: NewEntryNoId[], log: Logger) => Promise<ConversationEntry[]>;
-/**
- * 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.
- */
-declare const newHarnessMessagesThisTurn: (prev: Message[] | undefined, next: Message[] | undefined) => {
-    messages: Message[];
-    approximate: boolean;
-};
-/**
- * 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".
- */
-declare const verifyEntriesParity: (store: ConversationStore, conversationId: string, blob: {
-    harnessMessages?: Message[];
-    displayMessages?: Message[];
-}, log: Logger) => Promise<void>;
 
-export { type ActiveConversationRun, type ActiveSubagentRun, type AgentFrontmatter, AgentHarness, type AgentIdentity, type AgentLimitsConfig, type AgentModelConfig, AgentOrchestrator, type ApprovalEventItem, type ArchivedToolResult$1 as ArchivedToolResult, type AssistantAmendmentEntry, type AssistantMessageEntry, type BashConfig, BashEnvironmentManager, type BashExecutionLimits, type BuiltInToolToggles, CALLBACK_LOCK_STALE_MS, type CallbackStartedEntry, type CompactMessagesOptions, type CompactResult, type CompactionConfig, type CompactionEntry, 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_TEMPERATURE, DEFAULT_TIMEOUT, type DefaultAgentDefinitionOptions, type DisplaySnapshot, type EventSink, type ExecuteTurnResult, type HarnessMessageEntry, 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 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, type UserMessageEntry, VFS_SCHEME, VercelBlobUploadStore, type VfsDirEntry, type VfsStat, type VirtualMount, abnormalEndResponse, appendEntriesSafe, applyTurnMetadata, buildAgentDirectoryName, buildApprovalCheckpoints, buildAssistantMetadata, buildDisplaySnapshot, buildLlmContext, 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, entriesParityEnabled, estimateTokens, estimateTotalTokens, executeConversationTurn, findSafeSplitPoint, flushTurnDraft, generateAgentId, getAgentStoreDirectory, getModelContextWindow, getOpenAICodexAccessToken, getOpenAICodexAuthFilePath, getOpenAICodexRequiredScopes, getPendingSubagentResults, getPonchoStoreRoot, isMessageArray, jsonSchemaToZod, lastAssistantText, loadCanonicalHistory, loadPonchoConfig, loadRunHistory, loadSkillContext, loadSkillInstructions, loadSkillMetadata, loadSkillMetadataFromDirs, loadVfsSkillMetadata, mergeSkills, newHarnessMessagesThisTurn, normalizeApprovalCheckpoint, normalizeOtlp, normalizeScriptPolicyPath, normalizeToolAccess, parseAgentFile, parseAgentMarkdown, parseSkillFrontmatter, ponchoDocsTool, readOpenAICodexSession, readSkillResource, realResponseText, recordStandardTurnEvent, renderAgentPrompt, resolveAgentIdentity, resolveCompactionConfig, resolveEnv, resolveMemoryConfig, resolveRunRequest, resolveSkillDirs, resolveStateConfig, runConversationTurn, slugifyStorageComponent, startOpenAICodexDeviceAuth, verifyEntriesParity, 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_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 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, 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, verifyTenantToken, withToolResultArchiveParam, writeOpenAICodexSession };