@poncho-ai/sdk 1.14.0 → 1.15.1

package/.turbo/turbo-build.log

@@ -1,5 +1,5 @@
 
-> @poncho-ai/sdk@1.14.0 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
+> @poncho-ai/sdk@1.15.1 build /home/runner/work/poncho-ai/poncho-ai/packages/sdk
 > tsup src/index.ts --format esm --dts
 
 CLI Building entry: src/index.ts
@@ -8,7 +8,7 @@
 CLI Target: es2022
 ESM Build start
 ESM dist/index.js 17.24 KB
-ESM ⚡️ Build success in 20ms
+ESM ⚡️ Build success in 18ms
 DTS Build start
-DTS ⚡️ Build success in 1320ms
-DTS dist/index.d.ts 30.03 KB
+DTS ⚡️ Build success in 1324ms
+DTS dist/index.d.ts 31.79 KB

package/CHANGELOG.md

@@ -1,5 +1,49 @@
 # @poncho-ai/sdk
 
+## 1.15.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.
+
+## 1.15.0
+
+### Minor Changes
+
+- [#145](https://github.com/cesr/poncho-ai/pull/145) [`bfa4976`](https://github.com/cesr/poncho-ai/commit/bfa4976ac8b05a300e22271e23c3bae4aadae2a8) Thanks [@cesr](https://github.com/cesr)! - events: add stable identity so streaming clients match instead of guess
+
+  Additive fields that let a streaming client reconstruct view-state by
+  identity rather than inferring structure from event order (the source of a
+  class of reconnect/subagent rendering bugs):
+  - `tool:started` / `tool:completed` / `tool:error` now carry `toolCallId`
+    (already in scope as `call.id` / `result.callId`). Clients match tool
+    pills by id instead of by tool name.
+  - `subagent:spawned|completed|error|stopped` now carry `parentToolCallId`
+    (the `spawn_subagent` tool call's id) and `task`; `completed`/`error`
+    also carry `resultText`. Clients attach subagent state to the spawning
+    tool's pill and render the result inline — no header-regex or
+    sequential-cursor pairing needed.
+  - `ToolContext` gains `toolCallId` so the `spawn_subagent` handler can
+    record which call produced the subagent (plumbed: tool-dispatcher →
+    spawn handler → `SubagentSpawnOptions.parentToolCallId` →
+    `subagentMeta.parentToolCallId` → the events above).
+  - `run:started` gains an optional `cause` field in the type
+    (`user|continuation|subagent_callback|approval_resume`); emission is
+    deferred to a later pass.
+
+  All fields are additive; older clients ignore them.
+
 ## 1.14.0
 
 ### Minor Changes

package/dist/index.d.ts

@@ -680,6 +680,14 @@ interface Message {
             content: string | string[];
         }>;
         isCompactionSummary?: boolean;
+        /** True while this assistant message is an in-flight DRAFT (the turn
+         *  hasn't finished). Set by the orchestrator's per-step draft persist and
+         *  cleared at finalize. Consumers that reconcile a persisted snapshot with
+         *  a live event stream (e.g. PonchOS's WS layer) strip `incomplete`
+         *  messages from the snapshot and rebuild the in-flight turn from the
+         *  event log instead — so the two never both carry it (no reconnect
+         *  duplication). */
+        incomplete?: boolean;
     };
 }
 /** Extract the text content from a message, regardless of content format. */
@@ -713,6 +721,11 @@ interface ToolContext {
     parameters: Record<string, unknown>;
     abortSignal?: AbortSignal;
     conversationId?: string;
+    /** The id of the tool call currently executing. Lets a tool that spawns
+     *  further work (spawn_subagent) record which call produced it, so the
+     *  resulting subagent events can carry `parentToolCallId` and the client
+     *  can attach subagent state to the spawning tool's pill. */
+    toolCallId?: string;
     /** The tenant ID when running in multi-tenant mode. */
     tenantId?: string;
     /** Telemetry is suppressed for this run (e.g. an incognito turn). Tools
@@ -802,6 +815,19 @@ type AgentEvent = {
     runId: string;
     agentId: string;
     contextWindow?: number;
+    /**
+     * Why this run began. Lets a streaming client render the run
+     * deterministically instead of inferring from event order:
+     *  - "user": a fresh user-message turn.
+     *  - "continuation": the harness continued a long turn past a
+     *    checkpoint (same logical turn).
+     *  - "subagent_callback": a turn injecting a finished subagent's
+     *    result back into the parent.
+     *  - "approval_resume": resuming after a tool-approval decision
+     *    (continues the existing assistant turn).
+     * Absent on older harness versions.
+     */
+    cause?: "user" | "continuation" | "subagent_callback" | "approval_resume";
 } | {
     type: "run:completed";
     runId: string;
@@ -838,10 +864,12 @@ type AgentEvent = {
 } | {
     type: "tool:started";
     tool: string;
+    toolCallId: string;
     input: unknown;
 } | {
     type: "tool:completed";
     tool: string;
+    toolCallId: string;
     input?: unknown;
     output: unknown;
     duration: number;
@@ -849,6 +877,7 @@ type AgentEvent = {
 } | {
     type: "tool:error";
     tool: string;
+    toolCallId: string;
     error: string;
     recoverable: boolean;
 } | {
@@ -918,19 +947,28 @@ type AgentEvent = {
     subagentId: string;
     conversationId: string;
     task: string;
+    parentToolCallId?: string;
 } | {
     type: "subagent:completed";
     subagentId: string;
     conversationId: string;
+    task?: string;
+    parentToolCallId?: string;
+    resultText?: string;
 } | {
     type: "subagent:error";
     subagentId: string;
     conversationId: string;
     error: string;
+    task?: string;
+    parentToolCallId?: string;
+    resultText?: string;
 } | {
     type: "subagent:stopped";
     subagentId: string;
     conversationId: string;
+    task?: string;
+    parentToolCallId?: string;
 } | {
     type: "subagent:approval_needed";
     subagentId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@poncho-ai/sdk",
-  "version": "1.14.0",
+  "version": "1.15.1",
   "description": "Core types and utilities for building Poncho skills",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -38,6 +38,14 @@ export interface Message {
     toolActivity?: string[];
     sections?: Array<{ type: "text" | "tools"; content: string | string[] }>;
     isCompactionSummary?: boolean;
+    /** True while this assistant message is an in-flight DRAFT (the turn
+     *  hasn't finished). Set by the orchestrator's per-step draft persist and
+     *  cleared at finalize. Consumers that reconcile a persisted snapshot with
+     *  a live event stream (e.g. PonchOS's WS layer) strip `incomplete`
+     *  messages from the snapshot and rebuild the in-flight turn from the
+     *  event log instead — so the two never both carry it (no reconnect
+     *  duplication). */
+    incomplete?: boolean;
   };
 }
 
@@ -76,6 +84,11 @@ export interface ToolContext {
   parameters: Record<string, unknown>;
   abortSignal?: AbortSignal;
   conversationId?: string;
+  /** The id of the tool call currently executing. Lets a tool that spawns
+   *  further work (spawn_subagent) record which call produced it, so the
+   *  resulting subagent events can carry `parentToolCallId` and the client
+   *  can attach subagent state to the spawning tool's pill. */
+  toolCallId?: string;
   /** The tenant ID when running in multi-tenant mode. */
   tenantId?: string;
   /** Telemetry is suppressed for this run (e.g. an incognito turn). Tools
@@ -183,7 +196,25 @@ export interface AgentFailure {
 }
 
 export type AgentEvent =
-  | { type: "run:started"; runId: string; agentId: string; contextWindow?: number }
+  | {
+      type: "run:started";
+      runId: string;
+      agentId: string;
+      contextWindow?: number;
+      /**
+       * Why this run began. Lets a streaming client render the run
+       * deterministically instead of inferring from event order:
+       *  - "user": a fresh user-message turn.
+       *  - "continuation": the harness continued a long turn past a
+       *    checkpoint (same logical turn).
+       *  - "subagent_callback": a turn injecting a finished subagent's
+       *    result back into the parent.
+       *  - "approval_resume": resuming after a tool-approval decision
+       *    (continues the existing assistant turn).
+       * Absent on older harness versions.
+       */
+      cause?: "user" | "continuation" | "subagent_callback" | "approval_resume";
+    }
   | { type: "run:completed"; runId: string; result: RunResult; pendingSubagents?: boolean }
   | { type: "run:cancelled"; runId: string; messages?: Message[] }
   | { type: "run:error"; runId: string; error: AgentFailure }
@@ -193,9 +224,9 @@ export type AgentEvent =
   | { type: "model:chunk"; content: string }
   | { type: "model:response"; usage: TokenUsage }
   | { type: "tool:generating"; tool: string; toolCallId: string }
-  | { type: "tool:started"; tool: string; input: unknown }
-  | { type: "tool:completed"; tool: string; input?: unknown; output: unknown; duration: number; outputTokenEstimate?: number }
-  | { type: "tool:error"; tool: string; error: string; recoverable: boolean }
+  | { type: "tool:started"; tool: string; toolCallId: string; input: unknown }
+  | { type: "tool:completed"; tool: string; toolCallId: string; input?: unknown; output: unknown; duration: number; outputTokenEstimate?: number }
+  | { type: "tool:error"; tool: string; toolCallId: string; error: string; recoverable: boolean }
   | {
       type: "tool:approval:required";
       tool: string;
@@ -246,10 +277,10 @@ export type AgentEvent =
       url?: string;
       interactionAllowed: boolean;
     }
-  | { type: "subagent:spawned"; subagentId: string; conversationId: string; task: string }
-  | { type: "subagent:completed"; subagentId: string; conversationId: string }
-  | { type: "subagent:error"; subagentId: string; conversationId: string; error: string }
-  | { type: "subagent:stopped"; subagentId: string; conversationId: string }
+  | { type: "subagent:spawned"; subagentId: string; conversationId: string; task: string; parentToolCallId?: string }
+  | { type: "subagent:completed"; subagentId: string; conversationId: string; task?: string; parentToolCallId?: string; resultText?: string }
+  | { type: "subagent:error"; subagentId: string; conversationId: string; error: string; task?: string; parentToolCallId?: string; resultText?: string }
+  | { type: "subagent:stopped"; subagentId: string; conversationId: string; task?: string; parentToolCallId?: string }
   | {
       type: "subagent:approval_needed";
       subagentId: string;