agent-lattice 0.23.0 → 0.25.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.
 
@@ -528,6 +544,15 @@ The structure is enforced by the harness, not by prompt discipline:
 - The name is reserved: registering your own `submit_output` tool while
   `outputSchema` is set throws from `createAgent`/`addTools`.
 
+By default a valid submission ends the run immediately — the bounded, cheapest
+behavior for schema-delivering workers. For human-facing sessions that should
+close with a natural-language summary, set `submitOutputEndTurn: false`: the
+submission is recorded (re-submitting revises it, last one wins), the tool
+result goes back to the model, and the run ends when the model stops. A text
+ending after a submission succeeds with the last submission as
+`structuredResult`; ending without any submission still fails with
+`error_missing_output`. *Requires 0.25.0 or later.*
+
 Unlike `outputFormat` (which relies on the provider's
 `response_format`/`json_schema` support — DeepSeek ignores it, see
 [Provider Compatibility](https://docs.claude-code-sdk.com/reference/provider-compatibility/)),
@@ -668,6 +693,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

@@ -603,6 +603,19 @@ export type AgentOptions<TContext = unknown> = {
      * with the same name throws).
      */
     outputSchema?: OutputSchema;
+    /**
+     * Whether a validated `submit_output` call ends the run. Only meaningful with
+     * `outputSchema`; default `true` — submitting finishes the run immediately
+     * with subtype "success", the bounded and cheapest behavior for
+     * schema-delivering workers. Set `false` to keep the loop going after a
+     * submission (e.g. human-facing sessions that should close with a
+     * natural-language summary): the submission is recorded — re-submitting
+     * revises it, last one wins — the tool result goes back to the model, and
+     * the run ends when the model stops. A text ending after a submission
+     * succeeds with the last submission as `SDKResultMessage.structuredResult`;
+     * ending without any submission still fails with `error_missing_output`.
+     */
+    submitOutputEndTurn?: boolean;
     /** Lifecycle callbacks that rewrite tool results and outgoing model requests. */
     hooks?: AgentHooks<TContext>;
     /**
@@ -872,6 +885,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