agent-lattice 0.9.20 → 0.9.23

package/README.md

@@ -533,6 +533,40 @@ 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
+other accepted handoffs. The lead receives successful and failed reports
+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

@@ -53,13 +53,19 @@ export type AgentRuntimeDelegateInput = {
     workspaceGrants?: WorkspaceGrantInput[];
 };
 export type AgentRuntimeDelegateResult = {
-    status: "completed" | "accepted";
+    status: "completed" | "accepted" | "failed";
     content: string;
     request: TeamMessage;
     reply?: TeamMessage;
     result?: SDKResultMessage;
+    error?: AgentRuntimeFailure;
     workspaceGrants?: WorkspaceGrant[];
 };
+export type AgentRuntimeFailure = {
+    code: "max_turns_exceeded" | "api_error" | "tool_execution_error" | "permission_denied" | "agent_error";
+    message: string;
+    name: string;
+};
 export type WorkspaceAccess = "read" | "write" | "execute";
 export type WorkspaceGrantInput = {
     root: string;
@@ -94,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 = {
@@ -306,12 +313,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;
@@ -320,6 +332,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>;
@@ -335,12 +348,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>;
@@ -442,10 +454,11 @@ export type SDKMessage = SDKSystemInitMessage | SDKStreamEventMessage | SDKAssis
 export type TeamRunnerSource = AgentRuntimeSource;
 export type TeamRunnerTeamMessage = {
     type: "team_message";
-    subtype: "sent" | "claimed" | "replied" | "followup" | "done" | "failed";
+    subtype: "sent" | "claimed" | "replied" | "followup" | "done" | "failed" | "cancelled";
     source: TeamRunnerSource;
     mailbox: string;
     message: TeamMessage;
+    error?: AgentRuntimeFailure;
 };
 export type TeamRunnerAgentMessage = {
     type: "agent_message";