@poncho-ai/sdk 1.14.0 → 1.15.0

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.0 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 19ms
 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.27 KB

package/CHANGELOG.md

@@ -1,5 +1,32 @@
 # @poncho-ai/sdk
 
+## 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

@@ -713,6 +713,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 +807,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 +856,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 +869,7 @@ type AgentEvent = {
 } | {
     type: "tool:error";
     tool: string;
+    toolCallId: string;
     error: string;
     recoverable: boolean;
 } | {
@@ -918,19 +939,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.0",
   "description": "Core types and utilities for building Poncho skills",
   "repository": {
     "type": "git",

package/src/index.ts

@@ -76,6 +76,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 +188,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 +216,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 +269,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;