agent-lattice 0.20.0 → 0.22.0

package/README.md

@@ -534,9 +534,15 @@ Unlike `outputFormat` (which relies on the provider's
 `submit_output` only requires a model that can call tools, so it ports to any
 tool-capable provider.
 
-The same schema composes with `agentTool()` for parent/child delegation: pass
-it to the child agent and to `AgentToolOptions.outputSchema` on the parent
-side, and an `ask` call returns the child's validated output as a JSON string:
+The same schema composes with `agentTool()` for parent/child delegation: give
+it to the child agent, and an `ask` call returns the child's validated output
+as a JSON string. Since 0.21.0 the parent side inherits the child's declared
+schema, so the `agentTool()` copy can be omitted. Passing
+`AgentToolOptions.outputSchema` explicitly is still allowed, but it must match
+the target's declaration (compared by reference, then by derived JSON Schema
+structure) — a mismatch throws at assembly time, so drift fails fast instead
+of at call time. The error message suggests sharing one schema instance or
+omitting the `agentTool()` copy:
 
 ```ts
 import { agentTool, createAgent } from "agent-lattice";
@@ -552,16 +558,66 @@ const parent = createAgent({
   tools: [
     agentTool("review", child, {
       description: "Ask the reviewer to audit a change.",
-      outputSchema: reviewSchema, // validates the child's submission
+      // outputSchema is inherited from the child (0.21.0+); an explicit copy
+      // must match the child's declaration or agentTool() throws.
     }),
   ],
 });
 ```
 
 If the child ends without submitting or submits a payload that fails the
-parent's schema, the tool returns an `is_error` `tool_result` starting with
+schema, the tool returns an `is_error` `tool_result` starting with
 `child_output_invalid:`, so the parent model sees the failure and can retry.
 
+*Behavior change in 0.21.0:* where the child declares an `outputSchema` and
+the parent does not, the `ask` tool result changed from the fixed text
+`"Structured output submitted."` to the validated JSON. That is the intended
+fix and ships in a minor under 0.x. Host-defined `AgentLike` adapters carry no
+readable declaration, so nothing is inherited or cross-checked for them; an
+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.
+
+### Typed delegation
+
+*Requires 0.21.0 or later.*
+
+`AgentToolOptions.inputSchema` replaces the default `{mode, task,
+expectedOutput, acceptanceCriteria, workspaceGrants}` input shape with your
+own schema (a zod schema works directly), and `mapInput` projects the
+validated input into the child prompt:
+
+```ts
+const judge = createAgent({
+  model: "claude-sonnet-4-5",
+  systemPrompt: "You judge a case and submit a structured verdict.",
+  outputSchema: verdictSchema,
+});
+
+const judgeTool = agentTool("judge", judge, {
+  description: "Judge a case from its summary and documents.",
+  inputSchema: z.object({
+    caseSummary: z.string(),
+    documents: z.array(z.object({ title: z.string(), content: z.string() })),
+  }),
+  mapInput: input => renderJudgeTask(input.caseSummary, input.documents),
+});
+```
+
+- The parent's arguments are parsed against `inputSchema` before anything
+  runs; invalid input is rejected as an error `tool_result` in the parent's
+  loop — the same semantics as a plain `tool()` call — and the child is never
+  invoked.
+- `inputSchema` and `mapInput` must come as a pair: `agentTool()` throws at
+  assembly time when one is missing.
+- Typed delegation is ask-only: there is no `mode` field and no
+  `workspaceGrants`.
+- `mapInput` may return a string or `ContentBlock[]`; `ContentBlock[]` is only
+  supported for direct `ask` calls — inside a team runtime the projected
+  prompt must be a string, or the call fails at runtime.
+- Because typed input no longer matches `AgentToolInput`, `agentTool()` now
+  returns `ToolDefinition<any>`.
+
 ## Concurrent Tool Calls
 
 The model requests concurrency by returning multiple `tool_use` blocks in one
@@ -644,6 +700,46 @@ policy, tool execution is unchanged. A policy prevents known bad combinations
 inside one model response, but it does not replace database transactions or
 revision checks against concurrent external updates.
 
+## Strict Option Validation And Tool Metadata
+
+*Requires 0.22.0 or later.*
+
+The option objects of `createAgent()`/`createBareAgent()`/`defineAgent()`
+(`AgentOptions`), `agentTool()` (`AgentToolOptions`), `delegateTool()`
+(`DelegateToolOptions`), and `tool()` (`ToolOptions`) are validated strictly:
+an unknown key throws at assembly time —
+
+```
+AgentOptions: unknown option "bogusOption". Check for a typo, or upgrade the SDK if this option was added in a newer version.
+```
+
+(`agentTool()`/`delegateTool()` prefix the message with `agentTool("<name>"):` /
+`delegateTool("<name>"):` instead.) The point is to fail fast on the old-SDK +
+new-API combination: before 0.22.0 an unknown option was silently ignored, so
+calling a newer API on an older install "worked" with the feature absent.
+
+*Behavior change in 0.22.0:* extra keys that used to be silently ignored —
+for example host fields spread into an options object — now throw. If your
+host assembles options by spreading wider objects, strip the extra fields when
+upgrading.
+
+Separately, `ToolOptions.metadata` and `AgentToolOptions.metadata` accept a
+`Record<string, unknown>` that is passed through to `ToolDefinition.metadata`:
+
+```ts
+const search = tool(
+  "search",
+  "Search documents",
+  z.object({ query: z.string() }),
+  async ({ query }) => ({ content: await documentIndex.search(query) }),
+  { metadata: { contractVersion: 3 } },
+);
+```
+
+The SDK never reads or interprets `metadata`, and it is never shown to the
+model — it is host-owned, machine-readable annotation (for example a contract
+version). When not passed, the key is absent from the `ToolDefinition`.
+
 ## Automatic Context Compaction
 
 History only grows, so a long-running agent eventually exceeds the model's

package/dist/index.d.ts

@@ -369,6 +369,11 @@ export type AgentHooks<TContext = unknown> = {
 export type ToolHandler<TInput = unknown, TContext = unknown> = (input: TInput, context: ToolExecutionContext<TContext>) => Promise<ToolResult> | ToolResult;
 export type ToolOptions<TInput = unknown> = {
     isConcurrencySafe?: (input: TInput) => boolean;
+    /**
+     * Host-owned, machine-readable annotations carried on the tool definition.
+     * The SDK never reads or interprets it; it is never shown to the model.
+     */
+    metadata?: Record<string, unknown>;
 };
 export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     name: string;
@@ -379,6 +384,8 @@ export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     parse(input: unknown): TInput;
     handler: ToolHandler<TInput, TContext>;
     isConcurrencySafe?: (input: TInput) => boolean;
+    /** Host-owned annotations passed through from `ToolOptions.metadata`. */
+    metadata?: Record<string, unknown>;
 };
 export type ToolConcurrencyMode = "safe" | "all" | "sequential";
 export type ToolConcurrencyOptions = {
@@ -822,13 +829,40 @@ export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
     /**
-     * Expected structured output of the target, declared with the same schema
-     * the target uses for its own `AgentOptions.outputSchema`. With mode "ask"
-     * the tool result is the target's validated structured output as JSON; a
-     * target that ends without submitting — or submits a payload that fails this
-     * schema — produces a `child_output_invalid` tool error the parent can retry.
+     * Host-owned, machine-readable annotations carried on the tool definition
+     * (e.g. a contract version). The SDK never reads or interprets it; it is
+     * never shown to the model.
+     */
+    metadata?: Record<string, unknown>;
+    /**
+     * Expected structured output of the target. When omitted, the declaration is
+     * inherited from the target itself (an Agent's or AgentSpec's
+     * `AgentOptions.outputSchema`); when passed explicitly it must match the
+     * target's declaration or `agentTool()` throws at assembly time. Host-defined
+     * AgentLike adapters carry no readable declaration, so nothing is inherited
+     * or cross-checked for them.
+     *
+     * 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.
      */
     outputSchema?: OutputSchema;
+    /**
+     * Typed delegation: replaces the default `{mode, task, ...}` input shape
+     * with this schema (same structural shape as OutputSchema; a zod schema
+     * works directly). The parent's arguments are validated before the child is
+     * invoked, and `mapInput` projects the validated input into the child
+     * prompt. Typed delegation is ask-only: there is no `mode` field and no
+     * `workspaceGrants`. Requires `mapInput`.
+     */
+    inputSchema?: OutputSchema;
+    /**
+     * Projects validated `inputSchema` input into the child prompt. Returning
+     * `ContentBlock[]` is only supported for direct ask calls; inside a team
+     * runtime the projected prompt must be a string.
+     */
+    mapInput?: (input: any) => string | ContentBlock[];
 };
 /**
  * An AgentLike is a live session: it keeps its conversation history across
@@ -837,7 +871,7 @@ export type AgentToolOptions = {
  * continuity.
  */
 export type AgentToolTarget = AgentLike<any> | AgentSpec<any>;
-export declare function agentTool(name: string, agent: AgentToolTarget, options: AgentToolOptions): ToolDefinition<AgentToolInput>;
+export declare function agentTool(name: string, agent: AgentToolTarget, options: AgentToolOptions): ToolDefinition<any>;
 export declare function delegateTool(name: string, description: string, agent: AgentToolTarget, options?: DelegateToolOptions): ToolDefinition<{
     task: string;
 }>;
@@ -987,6 +1021,8 @@ declare class Agent<TContext = unknown> {
      */
     replaceHistory(messages: ModelMessage[]): Promise<void>;
     addTools(tools: Array<ToolDefinition<any, TContext>>): void;
+    /** The structured output contract declared via `AgentOptions.outputSchema`, if any. */
+    get outputSchema(): OutputSchema | undefined;
     private initMessage;
     private resultMessage;
     private modelTools;