agent-lattice 0.9.21 → 0.9.24

package/README.md

@@ -283,6 +283,47 @@ const result = await agent.prompt("What is 2+2?");
 console.log(result.result);
 ```
 
+## Tool Batch Policy
+
+Use `toolBatchPolicy` when some tools must not run in the same model response.
+The policy sees the complete batch before any tool executes. If it rejects the
+batch, no tool runs and every tool call receives a structured `is_error: true`
+result.
+
+```ts
+const lead = createAgent({
+  model: "claude-sonnet-4-6",
+  tools: [incrementRevision],
+  toolBatchPolicy: {
+    validate({ toolCalls }) {
+      const incrementsRevision = toolCalls.find(
+        call => call.name === "incrementRevision",
+      );
+      const handoff = toolCalls.find(
+        call => call.kind === "agent_tool" &&
+          (call.input as { mode?: string }).mode === "handoff",
+      );
+      if (incrementsRevision && handoff) {
+        return {
+          allowed: false,
+          code: "invalid_tool_batch",
+          message: "Update the revision before delegating dependent work.",
+          conflictingToolCallIds: [incrementsRevision.id, handoff.id],
+          suggestedNextStep: "Run incrementRevision first, then hand off the new revision.",
+        };
+      }
+      return { allowed: true };
+    },
+  },
+});
+```
+
+The policy may be synchronous or asynchronous. If it throws, the SDK rejects
+the whole batch with `tool_batch_policy_error`; no tool has executed. Without a
+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.
+
 ## Business Context For Tools
 
 Pass host application data through `context`. The SDK gives that context to
@@ -533,6 +574,13 @@ delivery: the runtime waits for the member's upstream reply, feeds it back to
 the lead, and keeps going until the root lead returns the final result or the
 run terminates.
 
+After one model response queues one or more handoffs, the SDK does not call the
+lead model again immediately. It first runs those members, collects their
+completed or failed reports, and only then calls the lead again. All handoffs
+from the current tool batch are queued before the lead pauses. The receipt keeps
+`status: "accepted"` for compatibility and also includes `phase: "queued"`,
+`completion_pending: true`, `message_id`, `work_item_id`, and `thread_id`.
+
 Accepted handoffs use work-item failure isolation by default. If one member
 returns an agent error such as `MaxTurnsError` or `APIError`, the runtime marks
 that work item `failed`, sends a failure report to the lead, and continues the
@@ -541,6 +589,25 @@ together and decides whether to retry, revise the task, accept a partial result,
 or finish. A run-wide `AbortError` still stops the runner; the runtime marks the
 current and remaining accepted work `cancelled` before propagating the abort.
 
+Handoff work is serial by default. Set a bounded concurrency limit on the team
+when independent members should run at the same time:
+
+```ts
+const team = createTeam({
+  name: "research",
+  lead,
+  members,
+  runner: { maxConcurrentWorkItems: 4 },
+});
+```
+
+You can also pass `maxConcurrentWorkItems` to `createTeamRunner()`. The limit
+must be a positive integer and defaults to `1`. It applies across different
+member mailboxes; work addressed to the same mailbox remains serial because an
+Agent may keep mutable conversation state. Runtime events are emitted as work
+actually progresses, while the reports injected back into the lead stay in the
+original handoff order.
+
 Team member tools can also request explicit shared workspace write grants:
 
 ```ts

package/dist/index.d.ts

@@ -100,6 +100,7 @@ export type AgentRuntimeContext = {
     permissions: RuntimePermissions;
     delegate(input: AgentRuntimeDelegateInput): Promise<AgentRuntimeDelegateResult>;
     emit(message: TeamRunnerMessage): void;
+    shouldPauseAfterToolBatch?(): boolean;
 };
 export type ContextTraceEventType = "run_start" | "user_message" | "model_request" | "assistant_message" | "tool_use" | "tool_result" | "team_message" | "result" | "error";
 export type ContextTraceEvent = {
@@ -176,6 +177,32 @@ export interface ModelClient {
 export type ToolResult = {
     content: string | ContentBlock[];
 };
+export type ToolKind = "tool" | "agent_tool";
+export type ToolBatchCall = {
+    id: string;
+    name: string;
+    input: unknown;
+    kind: ToolKind;
+};
+export type ToolBatchPolicyContext<TContext = unknown> = {
+    source?: AgentRuntimeSource;
+    toolCalls: ToolBatchCall[];
+    context?: TContext;
+    signal?: AbortSignal;
+};
+export type ToolBatchPolicyRejection = {
+    allowed: false;
+    code: string;
+    message: string;
+    conflictingToolCallIds?: string[];
+    suggestedNextStep?: string;
+};
+export type ToolBatchPolicyResult = {
+    allowed: true;
+} | ToolBatchPolicyRejection;
+export type ToolBatchPolicy<TContext = unknown> = {
+    validate(context: ToolBatchPolicyContext<TContext>): ToolBatchPolicyResult | Promise<ToolBatchPolicyResult>;
+};
 export type ToolExecutionContext<TContext = unknown> = {
     signal?: AbortSignal;
     toolUseId: string;
@@ -187,6 +214,7 @@ export type ToolHandler<TInput = unknown, TContext = unknown> = (input: TInput,
 export type ToolDefinition<TInput = unknown, TContext = unknown> = {
     name: string;
     description: string;
+    kind?: ToolKind;
     inputSchema: unknown;
     jsonSchema: Record<string, unknown>;
     parse(input: unknown): TInput;
@@ -312,12 +340,17 @@ export type SQLiteMailboxOptions = {
     database: SQLiteDatabaseLike;
     tableName?: string;
 };
+export type TeamRunnerConfig = {
+    maxDelegateDepth?: number;
+    maxConcurrentWorkItems?: number;
+};
 export type TeamOptions = {
     name: string;
     lead: Agent<any>;
     members: TeamMemberDefinition[];
     mailbox?: TeamMailbox;
     exposeLeadMailboxTools?: boolean;
+    runner?: TeamRunnerConfig;
 };
 export type Team = {
     name: string;
@@ -326,6 +359,7 @@ export type Team = {
     mailbox: TeamMailbox;
     tools: Array<ToolDefinition<any, any>>;
     memberTools: Record<string, Array<ToolDefinition<any, any>>>;
+    readonly runnerOptions?: TeamRunnerConfig;
     send(from: string, to: string, content: string, options?: TeamSendOptions): Promise<TeamMessage>;
     drain(options?: TeamDrainOptions): Promise<TeamDrainResult>;
     query(prompt: string | ContentBlock[], options?: QueryOptions): AsyncGenerator<TeamRunnerMessage>;
@@ -341,12 +375,11 @@ export type TeamDrainResult = {
     failed: number;
     rounds: number;
 };
-export type TeamRunnerOptions = {
+export type TeamRunnerOptions = TeamRunnerConfig & {
     team?: Team;
     root?: AgentLike<any>;
     mailbox?: TeamMailbox;
     source?: AgentRuntimeSource;
-    maxDelegateDepth?: number;
 };
 export type TeamRunner = {
     root: AgentLike<any>;
@@ -380,6 +413,7 @@ export type AgentOptions<TContext = unknown> = {
     maxTurns?: number;
     thinkingConfig?: ThinkingConfig;
     tools?: Array<ToolDefinition<any, TContext>>;
+    toolBatchPolicy?: ToolBatchPolicy<TContext>;
     skills?: SkillDefinition[];
     workspace?: AgentWorkspaceOptions;
     permission?: (request: PermissionRequest) => Promise<PermissionDecision> | PermissionDecision;
@@ -484,6 +518,10 @@ export declare class MaxTurnsError extends AgentSDKError {
 }
 export declare class AbortError extends AgentSDKError {
 }
+export declare class ToolBatchRejectedError extends AgentSDKError {
+    readonly rejection: ToolBatchPolicyRejection;
+    constructor(rejection: ToolBatchPolicyRejection);
+}
 export declare class ToolPermissionDeniedError extends AgentSDKError {
     readonly denial: PermissionDenial;
     constructor(denial: PermissionDenial);