@namzu/sdk 12.2.0 → 13.1.0

package/src/tools/coordinator/agent.ts

@@ -146,6 +146,13 @@ export function buildAgentTool(opts: AgentToolOptions): ToolDefinition {
 				// surface, and the one it exports as the canonical shape —
 				// did not.
 				...(context.parentSpan ? { parentSpan: context.parentSpan } : {}),
+				// The parent's environment, which is the whole point of setting
+				// one: a delegate that cannot see it runs against different
+				// services than the run that launched it, silently.
+				// `ToolContext.env` is the parent's own resolved map, per run.
+				...(Object.keys(context.env ?? {}).length > 0
+					? { configOverrides: { env: context.env } }
+					: {}),
 			})
 
 			onTaskLaunched?.(handle.taskId, {

package/src/tools/coordinator/index.ts

@@ -484,6 +484,12 @@ export function buildCoordinatorTools(opts: CoordinatorToolsOptions): ToolDefini
 				// Hang the child run off THIS tool's span, so the delegation
 				// shows up inside the turn that asked for it.
 				...(_context.parentSpan ? { parentSpan: _context.parentSpan } : {}),
+				// Same as the `Agent` tool: a delegate inherits the environment
+				// its parent was given, or it runs against different services
+				// than the run that asked for the work.
+				...(Object.keys(_context.env ?? {}).length > 0
+					? { configOverrides: { env: _context.env } }
+					: {}),
 			})
 
 			// Whose task this is. The inbox ignores completions for anything it

package/src/types/agent/base.ts

@@ -22,6 +22,29 @@ export interface BaseAgentConfig {
 	maxResponseTokens?: number
 	costLimitUsd?: number
 	permissionMode?: PermissionMode
+
+	/**
+	 * Extra environment variables for this agent's tools and sandboxed
+	 * commands, merged over whatever ambient environment the execution path
+	 * supplies. Inherited by every delegated descendant.
+	 *
+	 * **Configuration, not credentials** — and that is a property of the
+	 * CHANNEL rather than a judgement about any particular value. This map is
+	 * copied into every child, is readable by any tool that can run a command,
+	 * and enters a model's context and the run transcript the moment something
+	 * echoes it. Nothing here is scoped, redacted, or revocable.
+	 *
+	 * A value that authenticates to a host belongs on the brokered credential
+	 * path instead, where the process holds a placeholder and the real value is
+	 * attached per-host on egress — so it is never in the environment, never in
+	 * a transcript, and never inherited by a child that had no business with it.
+	 *
+	 * Inheritance was broken until it was not: a child built through a
+	 * `configBuilder` never received this at all, because the builder is
+	 * written by whoever registered the agent and cannot forward a field it was
+	 * never told about. It is stamped after the builder returns now, for the
+	 * same reason `parentSpan` and `resumeHandler` are.
+	 */
 	env?: Record<string, string>
 
 	/**

package/src/types/session/store.ts

@@ -65,9 +65,42 @@ export interface CreateSubSessionParams {
  * is out of scope for this phase (session-hierarchy.md §11 defers the project
  * store to a later phase).
  */
+/**
+ * The part of a Project's configuration a caller may actually set.
+ *
+ * **Exactly the fields something reads.** `ProjectConfig` declares eight; five
+ * enforcement sites read two of them, and the other six have zero readers in
+ * production — `maxInterventionDepth` included, whose three apparent hits are
+ * all comments claiming a wiring that does not exist. Exposing those here
+ * would make a dead field *easier to set*, which is worse than leaving it
+ * unreachable: a host would configure a retention policy, get no error, and
+ * believe retention was on.
+ *
+ * The rule is the repo's own: name the code that reads a declaration before
+ * shipping it. When a field gains a reader it gains a line here in the same
+ * change, and not before.
+ */
+export interface ProjectConfigInput {
+	/** Read by the spawn path and both handoff paths. Default 4. */
+	maxDelegationDepth?: number
+	/** Read by the spawn path and broadcast handoff. Default 8. */
+	maxDelegationWidth?: number
+}
+
 export interface CreateProjectParams {
 	tenantId: TenantId
 	name: string
+
+	/**
+	 * Per-workspace limits. Omitted fields keep the defaults.
+	 *
+	 * Until this existed every project in existence ran at depth 4 / width 8,
+	 * because the config was hardcoded identically in both stores and there was
+	 * no way to write one afterwards. A tenant with several workspaces could
+	 * not give them different limits, which is most of what having several
+	 * workspaces is for.
+	 */
+	config?: ProjectConfigInput
 }
 
 /**
@@ -99,13 +132,67 @@ export interface SessionStore {
 
 	getProject(projectId: ProjectId, tenantId: TenantId): Promise<Project | null>
 
+	/**
+	 * Change a Project's limits after it exists. OPTIONAL.
+	 *
+	 * Optional because widening a store interface is invisible to callers and
+	 * fatal to implementors: a host with its own `SessionStore` should not stop
+	 * compiling because the SDK grew a method. Callers check for it; the two
+	 * stores here implement it.
+	 *
+	 * Only the fields in {@link ProjectConfigInput} can move, and an omitted
+	 * field is left alone rather than reset — a caller raising the width is not
+	 * saying anything about the depth. Returns the updated Project, or `null`
+	 * if it does not exist.
+	 */
+	updateProject?(
+		projectId: ProjectId,
+		config: ProjectConfigInput,
+		tenantId: TenantId,
+	): Promise<Project | null>
+
+	/**
+	 * Every Project this tenant owns, oldest first. OPTIONAL, same reasoning.
+	 *
+	 * The tenant is the isolation boundary, so this is scoped to it and to
+	 * nothing else — there is no level above Project to filter by.
+	 */
+	listProjects?(tenantId: TenantId): Promise<readonly Project[]>
+
 	// Session CRUD ------------------------------------------------------------
 
 	createSession(params: CreateSessionParams, tenantId: TenantId): Promise<Session>
 
 	getSession(sessionId: SessionId, tenantId: TenantId): Promise<Session | null>
 
-	updateSession(session: Session, tenantId: TenantId): Promise<void>
+	/**
+	 * Write a Session back, optionally only if nobody else wrote it first.
+	 *
+	 * **`expectedOwnerVersion` is the single-writer lock this level is supposed
+	 * to own, and it did not exist.** `Session.ownerVersion` is documented as
+	 * the CAS counter for handoff, but nothing enforced it: both stores
+	 * overwrote unconditionally, and the handoff's own check compared a
+	 * snapshot it had read several awaits earlier against itself. Two
+	 * concurrent handoffs on one idle session both passed, both provisioned a
+	 * worktree, and one silently erased the other.
+	 *
+	 * Supply it and the store compares against the version it HAS STORED —
+	 * not against the payload, which is the caller's stale copy — and throws
+	 * {@link StaleSessionError} rather than writing. Omit it and the behaviour
+	 * is exactly what it always was, which is the compatibility promise: this
+	 * parameter is optional so that widening the interface stays invisible to
+	 * callers and harmless to hosts implementing their own store. A required
+	 * parameter would break every implementor for a guarantee they can opt
+	 * into.
+	 *
+	 * **In-process only, stated rather than implied.** `DiskSessionStore`
+	 * writes atomically, but its read-compare-write is not a critical section,
+	 * so two PROCESSES can still both pass the check. Closing that needs a
+	 * lease with an expiry — not a PID registry, because a Session is durable
+	 * and written from hosts where a PID is not a checkable fact. The same
+	 * honesty the spawn lock already carries.
+	 */
+	updateSession(session: Session, tenantId: TenantId, expectedOwnerVersion?: number): Promise<void>
 
 	/**
 	 * List every Session that belongs to the given Thread for the caller's