@nhtio/adk 1.20260601.0 → 1.20260603.0

package/CHANGELOG.md

@@ -5,6 +5,29 @@ All notable changes to `@nhtio/adk` are documented in this file.
 The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/),
 and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html).
 
+## 2026-06-03
+
+### Changed
+
+- **MCP install examples now render the current package version at docs build time.** The ADK MCP
+  guide uses a `{{ADK_VERSION}}` token for pinned `@nhtio/adk@...` examples, and the docs build
+  rewrites it from `package.json` for VitePress pages, LLM artifacts, the Ask ADK index, and the
+  packaged MCP corpus. Release docs now stay aligned with the published package version without
+  hand-editing install snippets before every tag.
+
+## 2026-06-02
+
+### Fixed
+
+- **Corrected the `callId` documentation on the tool-execution events.** `ToolExecutionStartEvent.callId`
+  and `ToolExecutionEndEvent.callId` were documented as correlating with `ToolCall.id`. They do not:
+  `callId` is `sha256({ tool, args })` — the same value as `TurnToolCallContent.checksum` and
+  `ToolCall.checksum`. The two buses join on **`toolCall.checksum === toolExecution*.callId`**, never
+  on `toolCall.id`. The hash collides by design for identical `(tool, args)` (that is what
+  `DispatchContext.toolCallCount` counts), so order or disambiguate repeated calls by the `DateTime`
+  fields (`createdAt` / `updatedAt`, `startedAt` / `endedAt`). TSDoc and the Events guides now state
+  this contract; no runtime behavior changed.
+
 ## 2026-06-01
 
 ### Added

package/index.cjs

@@ -5,7 +5,6 @@ const require_tool_registry = require("./tool_registry-CoM6fy7F.js");
 const require_runtime = require("./runtime-MFFcJrRv.js");
 const require_dispatch_runner = require("./dispatch_runner-D_EIoEwR.js");
 require("./dispatch_runner.cjs");
-require("./exceptions.cjs");
 const require_thought = require("./thought-pxBGk4lN.js");
 const require_tool = require("./tool-CxIEutdk.js");
 const require_spooled_artifact = require("./spooled_artifact-Chp6PEr8.js");
@@ -13,8 +12,9 @@ const require_common = require("./common-Bfqzwdpd.js");
 const require_tool_call = require("./tool_call-BPPa_KYu.js");
 const require_spooled_markdown_artifact = require("./spooled_markdown_artifact-b72JfMYo.js");
 const require_turn_runner = require("./turn_runner-DFW9OuBj.js");
-require("./turn_runner.cjs");
 const require_guards = require("./guards.cjs");
+require("./exceptions.cjs");
+require("./turn_runner.cjs");
 //#region src/index.ts
 /**
 * Root convenience barrel for the ADK's core runtime values and public TypeScript contracts.
@@ -26,7 +26,7 @@ const require_guards = require("./guards.cjs");
 *
 * @tip This is a constant that is replaced during the build process with the actual version of the package.
 */
-var version = "1.20260601.0";
+var version = "1.20260603.0";
 //#endregion
 exports.ArtifactTool = require_spooled_artifact.ArtifactTool;
 exports.DispatchRunner = require_dispatch_runner.DispatchRunner;

package/index.mjs

@@ -3,7 +3,6 @@ import { c as isObject, i as Registry, n as TokenEncoding, o as isError, r as To
 import { C as E_NOT_A_SPOOL_READER, D as E_TOOL_DOWNSTREAM_ERROR, E as E_TOOL_ALREADY_REGISTERED, O as E_TURN_GATE_ABORTED, T as E_PIPELINE_SHORT_CIRCUITED, _ as E_INVALID_TURN_GATE_RESOLUTION, a as E_INVALID_INITIAL_MEMORY_VALUE, b as E_LLM_EXECUTION_EXECUTOR_ERROR, d as E_INVALID_INITIAL_TOOL_VALUE, f as E_INVALID_INITIAL_TURN_GATE_VALUE, g as E_INVALID_TURN_CONTEXT, h as E_INVALID_TOOL_ARGS, k as E_TURN_GATE_TIMEOUT, l as E_INVALID_INITIAL_THOUGHT_VALUE, m as E_INVALID_LLM_EXECUTION_CONTEXT, n as E_INPUT_PIPELINE_ERROR, o as E_INVALID_INITIAL_MESSAGE_VALUE, p as E_INVALID_LLM_DISPATCH_INPUT, r as E_INVALID_INITIAL_IDENTITY_VALUE, s as E_INVALID_INITIAL_REGISTRY_VALUE, t as E_DISPATCH_PIPELINE_ERROR, u as E_INVALID_INITIAL_TOOL_CALL_VALUE, v as E_INVALID_TURN_RUNNER_CONFIG, w as E_OUTPUT_PIPELINE_ERROR, x as E_LLM_EXECUTION_GATE_NOT_SUPPORTED, y as E_LLM_EXECUTION_ALREADY_SIGNALLED } from "./runtime-j92CNi5z.mjs";
 import { t as DispatchRunner } from "./dispatch_runner-DNy8EuK2.mjs";
 import "./dispatch_runner.mjs";
-import "./exceptions.mjs";
 import { i as Identity, n as Message, r as Memory, t as Thought } from "./thought-BhoBfz9K.mjs";
 import { t as Tool } from "./tool-C381-NLO.mjs";
 import { i as ArtifactTool, r as implementsSpoolReader, t as SpooledArtifact } from "./spooled_artifact-xpzZicMR.mjs";
@@ -11,8 +10,9 @@ import { n as fromWebFile, o as Retrievable, r as inMemoryMediaReader, t as from
 import { a as mediaReaderSchema, i as implementsMediaReader, n as Media, r as isMedia, t as ToolCall } from "./tool_call-H02gzSIs.mjs";
 import { n as SpooledJsonArtifact, t as SpooledMarkdownArtifact } from "./spooled_markdown_artifact-CigJMNOl.mjs";
 import { t as TurnRunner } from "./turn_runner-CJke8_wy.mjs";
-import "./turn_runner.mjs";
 import { isArtifactTool, isBaseException, isDispatchContext, isDispatchRunner, isIdentity, isMemory, isMessage, isRegistry, isSpooledArtifact, isSpooledArtifactConstructor, isSpooledJsonArtifact, isSpooledMarkdownArtifact, isThought, isTokenizable, isTool, isToolCall, isToolRegistry, isTurnContext, isTurnGate, isTurnRunner } from "./guards.mjs";
+import "./exceptions.mjs";
+import "./turn_runner.mjs";
 //#region src/index.ts
 /**
 * Root convenience barrel for the ADK's core runtime values and public TypeScript contracts.
@@ -24,7 +24,7 @@ import { isArtifactTool, isBaseException, isDispatchContext, isDispatchRunner, i
 *
 * @tip This is a constant that is replaced during the build process with the actual version of the package.
 */
-var version = "1.20260601.0";
+var version = "1.20260603.0";
 //#endregion
 export { ArtifactTool, DispatchRunner, E_DISPATCH_PIPELINE_ERROR, E_INPUT_PIPELINE_ERROR, E_INVALID_INITIAL_IDENTITY_VALUE, E_INVALID_INITIAL_MEMORY_VALUE, E_INVALID_INITIAL_MESSAGE_VALUE, E_INVALID_INITIAL_REGISTRY_VALUE, E_INVALID_INITIAL_THOUGHT_VALUE, E_INVALID_INITIAL_TOOL_CALL_VALUE, E_INVALID_INITIAL_TOOL_VALUE, E_INVALID_INITIAL_TURN_GATE_VALUE, E_INVALID_LLM_DISPATCH_INPUT, E_INVALID_LLM_EXECUTION_CONTEXT, E_INVALID_TOOL_ARGS, E_INVALID_TURN_CONTEXT, E_INVALID_TURN_GATE_RESOLUTION, E_INVALID_TURN_RUNNER_CONFIG, E_LLM_EXECUTION_ALREADY_SIGNALLED, E_LLM_EXECUTION_EXECUTOR_ERROR, E_LLM_EXECUTION_GATE_NOT_SUPPORTED, E_NOT_A_SPOOL_READER, E_OUTPUT_PIPELINE_ERROR, E_PIPELINE_SHORT_CIRCUITED, E_TOOL_ALREADY_REGISTERED, E_TOOL_DOWNSTREAM_ERROR, E_TURN_GATE_ABORTED, E_TURN_GATE_TIMEOUT, Identity, Media, Memory, Message, Registry, Retrievable, SpooledArtifact, SpooledJsonArtifact, SpooledMarkdownArtifact, Thought, TokenEncoding, Tokenizable, Tool, ToolCall, ToolRegistry, TurnRunner, ValidationException, fromFetch, fromWebFile, implementsMediaReader, implementsSpoolReader, inMemoryMediaReader, isArtifactTool, isBaseException, isDispatchContext, isDispatchRunner, isError, isIdentity, isInstanceOf, isMedia, isMemory, isMessage, isObject, isRegistry, isSpooledArtifact, isSpooledArtifactConstructor, isSpooledJsonArtifact, isSpooledMarkdownArtifact, isThought, isTokenizable, isTool, isToolCall, isToolRegistry, isTurnContext, isTurnGate, isTurnRunner, mediaReaderSchema, version };
 

package/lib/types/turn_runner.d.ts

@@ -45,13 +45,23 @@ export interface TurnStreamableContent {
  * execution fails, `isError` is `true` and `results` contains the error detail.
  */
 export interface TurnToolCallContent {
-    /** Stable identifier for this tool call; correlates the initial request with its result. */
+    /**
+     * Stable stream id for this tool call; ties the initial request to its result on **this** bus
+     * (the announce emission and the completion emission share it). This is the model/stream id, not
+     * a cross-bus key — to correlate with the observability `toolExecution*` events, use `checksum`.
+     */
     id: string;
     /** Name of the tool the model has requested. */
     tool: string;
     /** Arguments the model supplied for the tool call. */
     args: unknown;
-    /** Integrity checksum over `tool` and `args`; can be used to detect tampering before execution. */
+    /**
+     * `sha256({ tool, args })` over the raw arguments. Doubles as the **cross-bus join key**: equal to
+     * {@link ToolExecutionStartEvent.callId} / {@link ToolExecutionEndEvent.callId} and to
+     * {@link @nhtio/adk!ToolCall.checksum}. Collides by design for identical `(tool, args)` within a
+     * turn — that is what {@link @nhtio/adk!DispatchContext.toolCallCount} counts — so order or
+     * disambiguate repeated calls by `createdAt` / `updatedAt`, not by `checksum` alone.
+     */
     checksum: string;
     /** Timestamp when this tool call was first emitted. */
     createdAt: DateTime;
@@ -109,16 +119,22 @@ export interface TurnEndEvent {
  *
  * @remarks
  * Fired after arg validation passes and immediately before the handler is called.
- * `callId` correlates the event with the {@link @nhtio/adk!ToolCall} record if one is being tracked. Fires
- * for both {@link @nhtio/adk!Tool} and
- * {@link @nhtio/adk!ArtifactTool} invocations — the payload is identical.
+ * `callId` is the cross-bus join key — equal to {@link TurnToolCallContent.checksum} and
+ * {@link @nhtio/adk!ToolCall.checksum}, **not** {@link @nhtio/adk!ToolCall.id}. Fires for both
+ * {@link @nhtio/adk!Tool} and {@link @nhtio/adk!ArtifactTool} invocations — the payload is identical.
  */
 export interface ToolExecutionStartEvent {
     /** Name of the tool being executed. */
     toolName: string;
     /** ID of the turn in which the tool is being executed. */
     turnId: string;
-    /** Correlates with the associated ToolCall id, if known. Empty string when not provided. */
+    /**
+     * Cross-bus join key: `sha256({ tool, args })`, identical to {@link TurnToolCallContent.checksum}
+     * and {@link @nhtio/adk!ToolCall.checksum}. This is **not** {@link @nhtio/adk!ToolCall.id}. It
+     * collides by design for identical `(tool, args)` within a turn — that is what
+     * {@link @nhtio/adk!DispatchContext.toolCallCount} counts. Order or disambiguate repeated calls by
+     * `startedAt`. Empty string when not provided.
+     */
     callId: string;
     /** The validated arguments that will be passed to the handler. */
     args: unknown;
@@ -130,16 +146,22 @@ export interface ToolExecutionStartEvent {
  *
  * @remarks
  * Fired after the handler returns or throws. When `isError` is `true`, the handler threw and the
- * error has been wrapped in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. Fires for both
- * {@link @nhtio/adk!Tool} and
- * {@link @nhtio/adk!ArtifactTool} invocations — the payload is identical.
+ * error has been wrapped in {@link @nhtio/adk!E_TOOL_DOWNSTREAM_ERROR}. `callId` carries the same
+ * cross-bus join key as {@link ToolExecutionStartEvent.callId}. Fires for both
+ * {@link @nhtio/adk!Tool} and {@link @nhtio/adk!ArtifactTool} invocations — the payload is identical.
  */
 export interface ToolExecutionEndEvent {
     /** Name of the tool that was executed. */
     toolName: string;
     /** ID of the turn in which the tool was executed. */
     turnId: string;
-    /** Correlates with the associated ToolCall id, if known. Empty string when not provided. */
+    /**
+     * Cross-bus join key: `sha256({ tool, args })`, identical to {@link TurnToolCallContent.checksum}
+     * and {@link @nhtio/adk!ToolCall.checksum}. This is **not** {@link @nhtio/adk!ToolCall.id}. It
+     * collides by design for identical `(tool, args)` within a turn — that is what
+     * {@link @nhtio/adk!DispatchContext.toolCallCount} counts. Order or disambiguate repeated calls by
+     * `startedAt` / `endedAt`. Empty string when not provided.
+     */
     callId: string;
     /** When execution started. */
     startedAt: DateTime;