agent-lattice 0.23.0 → 0.24.0

package/README.md

@@ -227,8 +227,10 @@ await agent.prompt("Remember that my name is Ada.");
 Each JSONL entry includes `session_id`, `run_id`, `seq`, `source`, `type`, and
 `data`. Agent runs record transcript and context events such as `run_start`,
 `user_message`, `model_request`, `assistant_message`, `tool_use`,
-`tool_result`, and `result`. For team runners, pass the tracer per query to
-propagate it into delegated agents:
+`tool_result`, and `result`. When the model client reports token usage,
+`assistant_message` events carry it as `data.message.usage`, and the `result`
+event carries the query's summed usage as `data.usage` (since 0.23.1). For
+team runners, pass the tracer per query to propagate it into delegated agents:
 
 ```ts
 for await (const event of team.query("Ask engineering to investigate.", {
@@ -316,6 +318,13 @@ root and share one trace session. Each Agent keeps its own SDK session identity,
 recorded as `agent_session_id` metadata, so tracing does not change Agent state
 or returned SDK messages.
 
+When the model client reports token usage, each `llm` run ends with
+`usage_metadata` in its outputs (`input_tokens`, `output_tokens`,
+`total_tokens`, plus cache buckets under `input_token_details`), so LangSmith
+shows token consumption and inferred cost per model turn. Anthropic cache
+tokens are additive, so they are summed into `input_tokens` the same way
+LangSmith's own Anthropic wrapper does. *Requires 0.23.1 or later.*
+
 ## Langfuse Context Tracing
 
 *Requires 0.19.0 or later.*
@@ -389,6 +398,13 @@ as child `generation` observations and SDK tool calls as child `tool`
 observations. For a `Team` query, delegated runs nest as child `chain`
 observations under the team root, so one handoff invocation stays one trace.
 
+When the model client reports token usage, each `generation` observation ends
+with `usageDetails` (`input`, `output`, `cache_creation_input_tokens`,
+`cache_read_input_tokens`, `total`), so Langfuse shows token consumption and
+inferred cost per model turn. Anthropic `input_tokens` already excludes cache
+tokens, matching Langfuse's mutually-exclusive usage buckets. *Requires 0.23.1
+or later.*
+
 `startObservation` defaults to the bundled `@langfuse/tracing` function; pass
 `startObservation` only to inject a custom runtime or a test fake.
 
@@ -668,6 +684,14 @@ an `isConcurrencySafe` declaration stay sequential. Use `mode: "all"` only when
 every tool in the Agent is safe to overlap. Use `mode: "sequential"` to disable
 tool concurrency even for tools marked safe.
 
+`agentTool()` accepts the same declaration as `AgentToolOptions.isConcurrencySafe`,
+so a supervisor can fan out independent delegations in one turn. The input the
+predicate receives is the tool's parsed input — the `inputSchema`-validated
+value for typed delegation, the `AgentToolInput` shape otherwise. Keep in mind
+the target's lifecycle: an `AgentSpec` spawns a fresh session per call, while an
+`AgentLike` target keeps history across calls and is usually not safe to call
+concurrently. *Requires 0.24.0 or later.*
+
 When concurrency is available, the SDK tells the model to batch independent
 calls and to use separate assistant responses when a later call needs an earlier
 result. Runtime safety checks and `toolBatchPolicy` remain authoritative.

package/dist/index.d.ts

@@ -872,6 +872,17 @@ export type AgentToolOptions = {
      * runtime the projected prompt must be a string.
      */
     mapInput?: (input: any) => string | ContentBlock[];
+    /**
+     * Same contract as `ToolOptions.isConcurrencySafe`: under
+     * `toolConcurrency.mode: "safe"` (the default), only calls whose declaration
+     * returns true here run in parallel; omitted means sequential. For typed
+     * delegation the input is the `inputSchema`-validated value (the same value
+     * `mapInput` receives); for default delegation it is the `AgentToolInput`
+     * shape. Note the target matters: an AgentSpec spawns a fresh session per
+     * call, while an AgentLike target keeps history across calls and is usually
+     * not safe to call concurrently.
+     */
+    isConcurrencySafe?: (input: any) => boolean;
 };
 /**
  * An AgentLike is a live session: it keeps its conversation history across