@namzu/sdk 8.0.0 → 10.0.0

package/src/types/agent/supervisor.ts

@@ -10,7 +10,7 @@ import type { ToolRegistryContract } from '../tool/index.js'
 import type { VerificationGateConfig } from '../verification/index.js'
 import type { BaseAgentConfig, BaseAgentResult } from './base.js'
 import type { AgentFactoryOptions } from './factory.js'
-import type { TaskGateway } from './gateway.js'
+import type { SiblingFailurePolicy, TaskGateway } from './gateway.js'
 import type { AgentManagerContract } from './manager.js'
 import type { WorkingMemoryProvider } from './working-memory.js'
 
@@ -72,6 +72,45 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 	 */
 	maxDepth?: number
 
+	/**
+	 * How many tools may execute at once in one turn — which, for a
+	 * supervisor, is how wide a fan-out actually runs.
+	 *
+	 * The kernel has honoured this all along and `ReactiveAgent` forwards it.
+	 * It was missing here, so the agent whose entire job is delegation could
+	 * not set the gate that bounds delegation, while the agent that does not
+	 * delegate could. A host wanting a narrower fan-out had to reach past the
+	 * supervisor to `drainQuery`.
+	 *
+	 * Absent leaves the kernel default. Note what it does and does not bound:
+	 * it limits how many delegated children run CONCURRENTLY, not how many a
+	 * turn may launch — a model that emits twenty `create_task` blocks still
+	 * launches twenty, and they queue.
+	 */
+	maxToolConcurrency?: number
+
+	/**
+	 * What a failed child means for the siblings still running. Defaults to
+	 * `'continue'`.
+	 *
+	 * `LocalTaskGateway` has honoured this since it was written, and the
+	 * cancellation machinery behind `'cancel-siblings'` is complete — but the
+	 * policy was a constructor argument on a gateway the supervisor builds
+	 * itself, and the supervisor passed nothing. So every host in existence
+	 * ran `'continue'`, and the only way to reach the other value was to
+	 * construct the gateway by hand and hand it in. A policy nobody can select
+	 * is not a policy.
+	 *
+	 * `'continue'` stays the default deliberately: partial results are usually
+	 * worth having, and tearing down healthy siblings on any failure lets one
+	 * flaky child waste four good ones. `'cancel-siblings'` is for a fan-out
+	 * whose parts only mean something together — if one leg of a comparison
+	 * dies, the others are spending budget on an answer nobody can use.
+	 *
+	 * Ignored when the host supplies its own `gateway`, which owns its policy.
+	 */
+	siblingFailurePolicy?: SiblingFailurePolicy
+
 	taskRouter?: TaskRouterConfig
 
 	factoryOptions?: AgentFactoryOptions

package/src/types/plan/index.ts

@@ -18,7 +18,36 @@ export interface PlanStep {
 	id: string
 	description: string
 	toolName?: string
+
+	/**
+	 * Which agent this step is to be delegated to, when it is delegated at all.
+	 *
+	 * `approve_plan` invites the model to name an agent per step, and that
+	 * answer was reduced to a boolean: the step got `toolName: 'create_task'`
+	 * if any agent was named and nothing if not. So the human approving the
+	 * plan was shown THAT a step delegates and never TO WHOM — while the model
+	 * had said, and the approval is the one moment where the difference can
+	 * still be acted on. Approving "delegate this" is not approving "delegate
+	 * this to the agent with shell access".
+	 *
+	 * Typed rather than folded into {@link estimatedInput}, which is `unknown`:
+	 * an approval gate's whole job is being readable, and a field a host has to
+	 * cast before it can render is one a host renders wrong or not at all.
+	 *
+	 * Absent means the step is the orchestrator's own work, which is what
+	 * omitting `agent_id` in `approve_plan` says.
+	 */
+	agentId?: string
+
+	/**
+	 * **No producer and no reader.** Nothing in the SDK writes this and
+	 * nothing reads it; it is declared here and that is all. Noted rather
+	 * than removed because it is on the published typings — see
+	 * {@link agentId}, which is the field the plan approval path actually
+	 * needed and did not have.
+	 */
 	estimatedInput?: unknown
+
 	dependsOn: string[]
 	status: 'pending' | 'running' | 'completed' | 'skipped' | 'failed'
 	error?: string

package/src/types/run/events.ts

@@ -461,6 +461,21 @@ type CoreRunEvent =
 			taskId: TaskId
 			subject: string
 			status: TaskStatus
+			/**
+			 * What this unit waits on, and who claims it.
+			 *
+			 * The store maintains a full dependency graph — `blocks` and
+			 * `blockedBy` are mirrored on both ends, written under a lock, and
+			 * deadlock-avoided — and none of it reached the wire. So a host
+			 * could show a flat list of units and nothing about their order,
+			 * while the model was already maintaining the order.
+			 *
+			 * Absent rather than empty when the unit depends on nothing, so a
+			 * reader can tell "no dependencies" from an emitter that predates
+			 * these fields.
+			 */
+			blockedBy?: readonly TaskId[]
+			owner?: string
 	  }
 	| {
 			type: 'task_updated'
@@ -469,6 +484,8 @@ type CoreRunEvent =
 			subject: string
 			status: TaskStatus
 			owner?: string
+			/** See `task_created`. Carried on updates because an edge can be added later. */
+			blockedBy?: readonly TaskId[]
 	  }
 	| {
 			type: 'plugin_hook_executing'

package/src/types/task/index.ts

@@ -1,9 +1,27 @@
 import type { RunId, TaskId, TenantId } from '../ids/index.js'
 
-export type TaskStatus = 'pending' | 'in_progress' | 'completed'
-
+/**
+ * `failed` exists because a unit that did not succeed had nowhere to say so.
+ *
+ * Delegation wrote a failed worker's task as `completed` with the failure
+ * encoded as prose in `description` — so a reader scanning statuses saw work
+ * that had been done, and only a reader of every description saw otherwise. A
+ * status nobody can set is a status nobody can act on: a dependent unit cannot
+ * decide whether to wait or give up, and a plan cannot report that it did not
+ * finish.
+ */
+export type TaskStatus = 'pending' | 'in_progress' | 'completed' | 'failed'
+
+/**
+ * Terminal means "will not change on its own", not "succeeded".
+ *
+ * `failed` is terminal for the same reason `completed` is: nothing downstream
+ * should wait on it. That matters most to the blocker check in the task
+ * listing — a dependent unit blocked on something that failed would otherwise
+ * wait forever for a status that will never arrive.
+ */
 export function isTerminalTaskStatus(status: TaskStatus): boolean {
-	return status === 'completed'
+	return status === 'completed' || status === 'failed'
 }
 
 export function assertTaskStatus(status: TaskStatus): void {
@@ -11,6 +29,7 @@ export function assertTaskStatus(status: TaskStatus): void {
 		case 'pending':
 		case 'in_progress':
 		case 'completed':
+		case 'failed':
 			return
 		default: {
 			const _exhaustive: never = status