@namzu/sdk 12.0.0 → 12.1.0

package/src/types/agent/core.ts

@@ -17,6 +17,28 @@ export interface Agent<
 
 	run(input: AgentInput, config: TConfig, listener?: RunEventListener): Promise<TResult>
 
+	/**
+	 * A shell of this agent that one run may have to itself.
+	 *
+	 * An agent instance holds per-run state — an abort controller, the id of
+	 * the run in flight — and refuses a second concurrent `run` because of it.
+	 * That refusal is correct for a host calling `run` twice on purpose: two
+	 * overlapping runs would share one abort controller, so cancelling either
+	 * kills both.
+	 *
+	 * It is wrong for delegation, which is why this exists. `AgentRegistry`
+	 * hands out ONE instance per registered id, so a fan-out naming the same
+	 * `agent_id` four times drove four runs at one shell: one worked and three
+	 * died with `ConcurrentInvocationError`. The prescribed remedy — "construct
+	 * a second instance" — was unreachable from there, because the definition
+	 * owns the instance and the caller only has an id.
+	 *
+	 * OPTIONAL, and absence is safe: a manager that cannot get a fresh shell
+	 * falls back to the shared one and the refusal stands, which is loud rather
+	 * than wrong. `AbstractAgent` implements it for every agent built on it.
+	 */
+	forRun?(): Agent<TConfig, TResult>
+
 	cancel(): Promise<void>
 	getCapabilities(): AgentCapabilities
 }

package/src/types/agent/factory.ts

@@ -8,6 +8,26 @@ export type { AgentContextLevel } from './base.js'
 export interface AgentDefinition {
 	info: AgentInfo
 	typedAgent: Agent<BaseAgentConfig, BaseAgentResult>
+
+	/**
+	 * Build a fresh agent for a single spawn.
+	 *
+	 * `typedAgent` is ONE instance, and an instance refuses a second
+	 * concurrent run because it holds per-run state. So a delegation fan-out
+	 * naming the same `agent_id` four times ran one child and lost three to
+	 * `ConcurrentInvocationError` — while `create_task`'s own description tells
+	 * a model that exactly this fan-out is the thing to do.
+	 *
+	 * The manager prefers this over `typedAgent` for every spawn. Supply it
+	 * when your agent needs real construction arguments; agents built on
+	 * `AbstractAgent` already get a working default from `Agent.forRun`, so
+	 * most hosts need nothing here.
+	 *
+	 * `configBuilder` is not a substitute: it produces a fresh CONFIG per
+	 * spawn, and the config was never the part being shared.
+	 */
+	createAgent?: () => Agent<BaseAgentConfig, BaseAgentResult>
+
 	configBuilder?: (options: AgentFactoryOptions) => BaseAgentConfig | Promise<BaseAgentConfig>
 
 	contextLevel?: AgentContextLevel