agent-lattice 0.21.0 → 0.23.0

package/README.md

@@ -578,6 +578,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.*
@@ -700,6 +720,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
@@ -1350,6 +1410,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

@@ -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 = {
@@ -605,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;
@@ -821,6 +834,12 @@ export type AgentToolInput = z.infer<typeof agentToolInputSchema>;
 export type AgentToolOptions = {
     description: string;
     targetMailboxId?: string;
+    /**
+     * 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
@@ -832,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;
     /**