agent-lattice 0.22.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.
 
@@ -578,6 +594,26 @@ explicit `outputSchema` still applies. Whenever a schema is in effect, the
 generated tool description states that the tool returns the target's
 validated structured output as JSON.
 
+Two more contract combinations are pinned down since 0.23.0:
+
+- **Target declares no `outputSchema`, `agentTool()` declares one
+  explicitly.** Assembly allows it (nothing to cross-check against), and an
+  `ask` call validates the child's `structuredResult` against the parent-side
+  schema and returns it as JSON. This fits children that end through a custom
+  `endTurn` + `structuredResult` tool performing domain validation beyond the
+  schema (for example reference truthfulness), with the contract declared by
+  the parent alone.
+- **Neither side declares a schema.** When the child ends with a
+  `structuredResult`, the `ask` tool result is its JSON as-is (unvalidated)
+  instead of falling back to the text content and dropping it. The trust
+  level is the same as the text result; the schema's job is validation only,
+  not gating the structured channel. This applies on both the direct path and
+  the team runtime delegate path.
+
+*Behavior change in 0.23.0:* existing code where the child ends with
+`endTurn` + `structuredResult` and the parent declares no schema now receives
+the structured JSON from `ask` instead of the text content.
+
 ### Typed delegation
 
 *Requires 0.21.0 or later.*
@@ -648,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.
@@ -1390,6 +1434,14 @@ production hosts should pair write and shell access with a permission callback.
 Shell redirects to `/dev/null` are treated as discard targets, not workspace
 writes.
 
+Pass `workspace: false` to opt out of the built-in workspace entirely — no
+built-in file/shell tools and no workspace prompt section, equivalent to
+`createBareAgent()` (*requires 0.23.0 or later*). Unlike `createBareAgent()`,
+the option also works through `defineAgent()`, so
+`defineAgent({ workspace: false })` spawns bare sessions — handy for
+typed-delegation specialists that should have no filesystem or shell surface
+at all.
+
 ## Multi-turn Session
 
 ```ts

package/dist/index.d.ts

@@ -612,7 +612,13 @@ export type AgentOptions<TContext = unknown> = {
     autoCompact?: boolean | AutoCompactOptions;
     toolConcurrency?: ToolConcurrencyOptions;
     skills?: SkillDefinition[];
-    workspace?: AgentWorkspaceOptions;
+    /**
+     * Workspace root for the built-in file/shell tools. `false` disables the
+     * built-in workspace entirely: no workspace tools, no workspace prompt
+     * section — equivalent to `createBareAgent`, and the way to make
+     * `defineAgent` spawn bare sessions.
+     */
+    workspace?: AgentWorkspaceOptions | false;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
     modelClient?: ModelClient;
     tracer?: ContextTracer;
@@ -845,7 +851,10 @@ export type AgentToolOptions = {
      * With the schema in effect, the tool result is the target's validated
      * structured output as JSON; a target that ends without submitting — or
      * submits a payload that fails the schema — produces a `child_output_invalid`
-     * tool error the parent can retry.
+     * tool error the parent can retry. Without any schema, a `structuredResult`
+     * the target produced is still passed through as JSON (same trust level as
+     * the text result); schema only adds validation, it does not gate the
+     * structured channel.
      */
     outputSchema?: OutputSchema;
     /**
@@ -863,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