@namzu/sdk 3.0.0 → 3.2.0

package/src/tools/coordinator/plan-dependencies.ts

@@ -0,0 +1,175 @@
+/**
+ * Turn the dependencies a model described into the step ids a plan uses.
+ *
+ * The model is shown `depends_on: string[]` on every plan step, described to
+ * it as "Step descriptions this depends on" — descriptions, because that is
+ * the only handle it has. Step ids are minted at execute time (`step_1`,
+ * `step_2`, ...), so the model cannot name one and should not be asked to.
+ *
+ * The translation between the two was never written. `approve_plan` passed
+ * `dependsOn: []` for every step, so whatever ordering the model declared
+ * was dropped at the one place it entered the system. The visible cost is
+ * not scheduling — `PlanManager.getNextPendingStep` holds the dependency
+ * gate and currently has no callers — it is the APPROVAL: `dependsOn` is
+ * serialized into the `plan_approval` payload a human reads before saying
+ * yes, so a reviewer was shown a plan whose steps all looked independent
+ * however carefully the model had ordered them.
+ */
+
+/** What the model said, before ids exist. */
+export interface DescribedStep {
+	readonly description: string
+	readonly depends_on?: readonly string[]
+}
+
+export type ResolvedDependencies =
+	| { readonly ok: true; readonly dependsOn: readonly (readonly string[])[] }
+	| { readonly ok: false; readonly error: string }
+
+/**
+ * Resolve every step's declared dependencies to step ids, or refuse.
+ *
+ * Returns one id array per input step, positionally.
+ *
+ * **Refusing beats dropping.** Every failure here means the model expressed
+ * an ordering it cannot have and the plan does not mean what it says; the
+ * old behaviour — discard silently — is what put an empty dependency list in
+ * front of a human approver. The error text names the offending description
+ * so the model can correct it and call again, which is the same shape every
+ * other recoverable tool failure in this kernel uses.
+ */
+export function resolvePlanDependencies(
+	steps: readonly DescribedStep[],
+	idOf: (index: number) => string,
+): ResolvedDependencies {
+	const byDescription = new Map<string, number[]>()
+	for (let i = 0; i < steps.length; i++) {
+		const description = steps[i]?.description
+		if (description === undefined) continue
+		const key = normalize(description)
+		const at = byDescription.get(key)
+		if (at) at.push(i)
+		else byDescription.set(key, [i])
+	}
+
+	const resolved: string[][] = []
+
+	for (let i = 0; i < steps.length; i++) {
+		const step = steps[i]
+		const declared = step?.depends_on
+		if (!step || !declared || declared.length === 0) {
+			resolved.push([])
+			continue
+		}
+
+		const ids: string[] = []
+		const seen = new Set<number>()
+
+		for (const wanted of declared) {
+			const matches = byDescription.get(normalize(wanted))
+
+			if (!matches) {
+				return {
+					ok: false,
+					error: `Step ${i + 1} depends on "${wanted}", which is not the description of any step in this plan. A dependency has to name another step exactly. Fix the description or drop the dependency, then call approve_plan again.`,
+				}
+			}
+
+			// Two steps sharing a description make "depends on that one"
+			// unanswerable. Picking either is a coin flip whose result a human
+			// then approves as if it were the model's intent.
+			if (matches.length > 1) {
+				return {
+					ok: false,
+					error: `Step ${i + 1} depends on "${wanted}", but ${matches.length} steps share that description, so it does not identify one. Make the descriptions distinct, then call approve_plan again.`,
+				}
+			}
+
+			const target = matches[0] as number
+
+			if (target === i) {
+				return {
+					ok: false,
+					error: `Step ${i + 1} depends on itself. A step cannot wait for its own completion; remove the dependency and call approve_plan again.`,
+				}
+			}
+
+			// Duplicates in one step's list are harmless — same edge twice.
+			if (seen.has(target)) continue
+			seen.add(target)
+			ids.push(idOf(target))
+		}
+
+		resolved.push(ids)
+	}
+
+	// A cycle is the failure worth catching hardest. Every step in one waits
+	// for another that is waiting for it, so the dependency gate never
+	// releases any of them and a plan that reads as fine simply stops. There
+	// is no error to observe at that point — the run just makes no progress.
+	const cycle = findCycle(resolved, (index) => idOf(index))
+	if (cycle) {
+		return {
+			ok: false,
+			error: `These steps depend on each other in a loop: ${cycle.map((i) => `step ${i + 1} ("${steps[i]?.description ?? ''}")`).join(' -> ')}. No step in a loop can ever start, because each waits for another that is waiting for it. Break the loop and call approve_plan again.`,
+		}
+	}
+
+	return { ok: true, dependsOn: resolved }
+}
+
+/**
+ * Descriptions come from a model, so they carry incidental whitespace and
+ * casing differences between the step and the reference to it. Matching on
+ * the exact string would reject "Run the tests" against "run the tests " —
+ * a refusal the model cannot learn anything from, for a plan that was right.
+ */
+function normalize(description: string): string {
+	return description.trim().replace(/\s+/g, ' ').toLowerCase()
+}
+
+/** Indices forming a dependency cycle, in order, or undefined. */
+function findCycle(
+	dependsOn: readonly (readonly string[])[],
+	idOf: (index: number) => string,
+): number[] | undefined {
+	const indexOfId = new Map<string, number>()
+	for (let i = 0; i < dependsOn.length; i++) indexOfId.set(idOf(i), i)
+
+	const UNVISITED = 0
+	const ON_STACK = 1
+	const DONE = 2
+	const state = new Array<number>(dependsOn.length).fill(UNVISITED)
+	const stack: number[] = []
+
+	const walk = (node: number): number[] | undefined => {
+		state[node] = ON_STACK
+		stack.push(node)
+
+		for (const depId of dependsOn[node] ?? []) {
+			const next = indexOfId.get(depId)
+			if (next === undefined) continue
+			if (state[next] === ON_STACK) {
+				// Report the loop itself, not the path that reached it.
+				const from = stack.indexOf(next)
+				return [...stack.slice(from), next]
+			}
+			if (state[next] === UNVISITED) {
+				const found = walk(next)
+				if (found) return found
+			}
+		}
+
+		stack.pop()
+		state[node] = DONE
+		return undefined
+	}
+
+	for (let i = 0; i < dependsOn.length; i++) {
+		if (state[i] !== UNVISITED) continue
+		const found = walk(i)
+		if (found) return found
+	}
+
+	return undefined
+}

package/src/types/agent/supervisor.ts

@@ -26,6 +26,21 @@ export interface SupervisorAgentConfig extends BaseAgentConfig {
 
 	skills?: Skill[]
 
+	/**
+	 * **Not consulted. The limit lives on `AgentManagerConfig.maxDepth`.**
+	 *
+	 * A supervisor does not own the recursion bound: it is enforced in
+	 * `AgentManager.sendMessage`, against the manager's own config, and a
+	 * supervisor receives a manager rather than building one. So a host that
+	 * set this got the manager's value regardless — which for a safety limit
+	 * is the worst way to be wrong, because the number in front of the
+	 * reviewer is not the number in force.
+	 *
+	 * Stated rather than removed: it is reachable from the published
+	 * typings, so it goes in the next major. Set the bound where it is read.
+	 *
+	 * @deprecated Set `maxDepth` on the `AgentManagerConfig` instead.
+	 */
 	maxDepth?: number
 
 	taskRouter?: TaskRouterConfig

package/src/types/connector/core.ts

@@ -28,9 +28,43 @@ export interface ConnectorMethod<TInput = unknown, TOutput = unknown> {
 	name: string
 	description: string
 	inputSchema: z.ZodType<TInput, z.ZodTypeDef, unknown>
+	/**
+	 * **Not consulted.** Neither in-tree connector declares one, and nothing
+	 * validates a result against it or shows it to a model.
+	 *
+	 * The tool layer solved the same problem already: a remote tool's output
+	 * schema is appended to its description by `describeWithOutput`, because
+	 * no provider's tool wire format has a slot for one. A connector method
+	 * that reaches a model through that bridge should take the same route
+	 * rather than growing a second mechanism.
+	 */
 	outputSchema?: z.ZodType<TOutput, z.ZodTypeDef, unknown>
 }
 
+/**
+ * **Declared, not implemented.** Nothing reads a trigger and nothing emits
+ * a {@link ConnectorEvent}; no inbound event starts a run today.
+ *
+ * Said here rather than left to be discovered, because a connector author
+ * who declares triggers gets no error and no events — the worst combination
+ * to debug. The shape is kept because it is right: a trigger names an
+ * upstream event and the config a subscription needs.
+ *
+ * What is missing is not the type but the delivery half, and it is a larger
+ * piece than it looks. An inbound event has to be de-duplicated across
+ * processes, since the same webhook is retried and the same poll can
+ * overlap; that needs a compare-and-set claim, and the only durable write
+ * primitive here is an atomic file REPLACE, which is last-writer-wins and
+ * cannot express one. It also needs a release path for an event claimed by
+ * a process that then dies, or the first crash silently drops that event
+ * forever.
+ *
+ * Two of those parts already exist and should be reused rather than
+ * rebuilt when this is built: `AbstractAgent.underIdempotencyKey` is the
+ * in-process dedupe seam and names the cross-process half as its known
+ * gap, and `EditOwnershipTracker.claim` is the claim/refuse shape with
+ * same-owner idempotency already worked out.
+ */
 export interface ConnectorTrigger {
 	name: string
 	description: string

package/src/types/connector/definition.ts

@@ -17,9 +17,19 @@ export interface ConnectorDefinition<TConfig = unknown> {
 	version?: string
 	category?: ConnectorCategory
 	connectionType: ConnectionType
+	/**
+	 * **Not consulted.** A connector declaring this is not checked against
+	 * the auth an instance is actually configured with, so a mismatch
+	 * surfaces as a 401 from the upstream rather than as a refusal here.
+	 *
+	 * Worth wiring where instances are created, not at request time: the
+	 * point of declaring supported schemes is to reject a misconfiguration
+	 * before anything is sent.
+	 */
 	supportedAuth?: AuthType[]
 	configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>
 	methods: ConnectorMethod[]
+	/** Declared, not implemented — see {@link ConnectorTrigger}. */
 	triggers?: ConnectorTrigger[]
 }
 

package/src/types/connector/mcp.ts

@@ -145,6 +145,20 @@ export interface MCPPromptDefinition {
 	arguments?: MCPPromptArgument[]
 }
 
+/**
+ * One message of a prompt the server composed.
+ *
+ * Deliberately its own shape rather than the kernel's `Message`: this is
+ * what a remote server said, before anything decides whether to believe it.
+ * Converting at the boundary is what keeps a server's `role` from becoming
+ * a role in this agent's history by accident — a server that returns an
+ * `assistant` message is claiming the agent already said something.
+ */
+export interface MCPPromptMessage {
+	role: 'user' | 'assistant'
+	content: MCPContentBlock
+}
+
 export interface MCPClientCapabilities {
 	roots?: { listChanged?: boolean }
 	sampling?: Record<string, never>

package/src/types/rag/retrieval.ts

@@ -14,6 +14,22 @@ export interface RetrievalConfig {
 
 export interface RetrievalQuery {
 	text: string
+	/**
+	 * **Not consulted.** No chunk carries a project, so there is nothing to
+	 * match it against: ingestion stamps a tenant and a namespace, and
+	 * `KnowledgeBaseConfig` has no project field to stamp a third from.
+	 *
+	 * Left declared and said out loud rather than quietly filtering on it.
+	 * Wiring one end of an isolation dimension is worse than wiring
+	 * neither — a query that filters against a value nothing writes returns
+	 * zero rows, and "no results" reads as "nothing matched" rather than
+	 * "this scope does not exist". Partition with
+	 * {@link TenantScope.namespace}, which is stamped at ingest and matched
+	 * at search.
+	 *
+	 * @deprecated Use `TenantScope.namespace` until a project reaches
+	 * ingestion.
+	 */
 	projectId?: ProjectId
 	recentMessages?: string[]
 	config?: Partial<RetrievalConfig>

package/src/types/rag/storage.ts

@@ -16,6 +16,15 @@ export interface Chunk {
 	documentId: DocumentId
 	knowledgeBaseId: KnowledgeBaseId
 	tenantId: TenantId
+	/**
+	 * The partition this chunk was ingested into, from `TenantScope`.
+	 *
+	 * `TenantScope.namespace` and `KnowledgeBaseConfig.namespace` were both
+	 * declared from the start and neither reached storage: ingestion copied
+	 * `scope.tenantId` onto every chunk and dropped the namespace, so a
+	 * partition a host had asked for did not exist at all.
+	 */
+	namespace?: string
 	content: string
 	index: number
 	tokenCount: number

package/src/types/rag/vector.ts

@@ -11,6 +11,17 @@ export interface VectorStoreQuery {
 	topK: number
 	tenantId: TenantId
 	knowledgeBaseId?: KnowledgeBaseId
+	/**
+	 * The partition to search. Matched by equality, INCLUDING absence.
+	 *
+	 * An omitted namespace means "the default partition", not "no filter".
+	 * Reading it as "no filter" is how an isolation boundary leaks: a caller
+	 * who never asked for a namespace would see every namespaced chunk in
+	 * the tenant, which is the opposite of what partitioning is for. A
+	 * caller who genuinely wants everything asks the store for each
+	 * namespace it holds.
+	 */
+	namespace?: string
 	filter?: Record<string, unknown>
 	minScore?: number
 }

package/src/types/router/task-router.ts

@@ -8,6 +8,25 @@ export type TaskType =
 	| 'advisory'
 	| 'default'
 
+/**
+ * Send a particular kind of work to a particular model.
+ *
+ * **Which keys the runtime consults today: `compaction`, and `default` as its
+ * fallback.** That is stated because the rest are silently inert, and an
+ * inert key is worse than an absent one — a host who sets `coding` reads it
+ * as taking effect. The compaction summary is the call worth routing first
+ * regardless: it is the only model call a run makes that nobody asked for,
+ * it reads a transcript and writes a summary, and it fires on exactly the
+ * long runs where the primary model costs the most.
+ *
+ * The remaining keys describe sub-agent routing. `SupervisorAgent` already
+ * threads this config down to the agent factory, but nothing classifies a
+ * spawned task as exploration or coding, and guessing a classifier here
+ * would put a wrong model behind a right-looking config.
+ *
+ * `advisory` is deliberately not consulted: an advisor carries its own
+ * `model`, so routing would override an explicit choice with a general one.
+ */
 export interface TaskRouterConfig {
 	readonly compaction?: string | null
 	readonly summarization?: string | null

package/src/types/run/prepare-step.ts

@@ -1,5 +1,7 @@
 import type { RunId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
+import type { ToolChoice } from '../provider/chat.js'
+import type { Skill } from '../skills/index.js'
 import type { StepResult } from './step.js'
 
 /**
@@ -51,12 +53,65 @@ export interface PrepareStepResult {
 	 * it is worth doing when a phase boundary genuinely changes what the
 	 * agent should reach for — and not worth doing every step.
 	 *
-	 * Note it does NOT touch `tool_choice`. Not every provider has an `allowed_tools`
-	 * parameter, and moving `tool_choice` invalidates cached MESSAGE blocks
-	 * as well — a strictly worse trade for the same effect.
+	 * Note it does NOT imply a `tool_choice`. Not every provider has an
+	 * `allowed_tools` parameter, and moving `tool_choice` invalidates cached
+	 * MESSAGE blocks as well — a strictly worse trade for the same effect.
+	 * When a step genuinely needs the model FORCED rather than narrowed, ask
+	 * for it explicitly through {@link PrepareStepResult.toolChoice} and pay
+	 * that cost knowingly.
 	 */
 	readonly activeTools?: readonly string[]
 
+	/**
+	 * Force this step's tool use: `'required'` to make the model call
+	 * something, `'none'` to forbid it, or a named function to demand that
+	 * one. Absent leaves the provider's default.
+	 *
+	 * **It applies to this step only, by construction.** That is the whole
+	 * reason it lives here rather than on the run config. A forced choice
+	 * that persists makes the model call a tool, see the result, and be
+	 * forced again — an agent that cannot stop. The one peer SDK that puts
+	 * `tool_choice` on persistent model settings has to undo it with a
+	 * tool-use tracker, an opt-out flag and a reset applied at two call
+	 * sites; the flag defaults to on precisely because turning it off hangs
+	 * the agent. Here there is nothing to reset and no flag to get wrong:
+	 * the next step is prepared fresh, so the force cannot outlive the step
+	 * that asked for it.
+	 *
+	 * **It costs more cache than `activeTools`.** Narrowing tools
+	 * invalidates the tool prefix; moving `tool_choice` invalidates cached
+	 * message blocks too. Worth it at a real phase boundary — "this step
+	 * must produce the structured answer" — and not worth it as a habit.
+	 */
+	readonly toolChoice?: ToolChoice
+
+	/**
+	 * Put these skills in front of the model for this step only.
+	 *
+	 * A run's skills are fixed at `query()` time and rendered into the cached
+	 * system prefix, so every skill a run might ever need is paid for on
+	 * every single turn. A phased agent rarely needs them all at once —
+	 * research wants the search skill, writing wants the style guide, and
+	 * neither benefits from carrying the other.
+	 *
+	 * Rendered into the same ephemeral trailing system message `system`
+	 * uses, and for the same reason: appending leaves the cached prefix
+	 * intact, where rewriting the run's prompt would invalidate it every
+	 * iteration for what is usually one phase's worth of guidance.
+	 *
+	 * ADDITIVE to the run's skills, not a replacement. A skill the run
+	 * always carries is not something a step should be able to take away by
+	 * naming a different one — that would make every step's list a complete
+	 * restatement, and a phase that forgot one would silently lose it.
+	 *
+	 * Sub-agents are deliberately NOT per-step. Which agents `create_task`
+	 * can reach is baked into that tool's input schema, so varying it would
+	 * rebuild the tool catalogue every step — a worse prompt-cache trade
+	 * than moving tools, for a narrowing a step can already express by
+	 * withholding `create_task` through {@link PrepareStepResult.activeTools}.
+	 */
+	readonly skills?: readonly Skill[]
+
 	/** Use a different model for this step. */
 	readonly model?: string
 

package/src/types/tool/index.ts

@@ -19,8 +19,24 @@ export interface ToolRegistryRef {
  * is active, absolute (`workingDirectory`-resolved) otherwise.
  */
 export interface FileReadTracker {
-	recordRead(key: string): void
+	/**
+	 * `content` lets the tracker fingerprint what was read, which is what
+	 * makes drift detectable later. Optional so a host that only needs the
+	 * read-before-overwrite guard can keep its existing implementation.
+	 */
+	recordRead(key: string, content?: string): void
 	hasRead(key: string): boolean
+	/**
+	 * Fingerprint of the body captured at the last read, when one was.
+	 *
+	 * A file mutation is computed against what the agent READ, and between
+	 * that read and the write the file may have moved under it — a person
+	 * editing in an editor, another process, a second agent. The in-process
+	 * lock cannot see any of those. Comparing this against the body actually
+	 * on disk at mutation time is what turns a silent lost update into a
+	 * refusal the agent can act on by re-reading.
+	 */
+	fingerprint?(key: string): string | undefined
 }
 
 export interface ToolPauseOption {

package/src/types/toolset/index.ts

@@ -1,5 +1,21 @@
 import type { LLMToolSchema, ToolDefinition, ToolPermission } from '../tool/index.js'
 
+/**
+ * @deprecated Slated for removal in the next major. Nothing produces or
+ * reads it — no code constructs any member, and `ToolsetPolicy.surfaces`,
+ * the only field that carries it, is never consulted.
+ *
+ * It is also the wrong axis. Which tools a run may use is already
+ * expressible four ways, all of them per-run and dynamic where this is
+ * fixed at definition: `allowedTools` on the query, `ToolAvailability`
+ * (`active` / `deferred` / `suspended`) with mid-run activation,
+ * `runtimeToolOverrides`, and capability negotiation stripping tools a
+ * driver cannot carry. Prefer `allowedTools`.
+ *
+ * The member names encode deployment shapes this kernel does not own,
+ * which is the deeper reason not to keep them: a host's surfaces are the
+ * host's to name.
+ */
 export type ToolCatalogSurface = 'chat' | 'supervised' | 'managed-agent' | 'worker' | 'code'
 
 export type ToolSourceKind =
@@ -41,6 +57,12 @@ export interface ToolsetPolicy {
 	readonly enabled?: boolean
 	readonly loading?: ToolLoadingMode
 	readonly preferred?: boolean
+	/**
+	 * @deprecated Slated for removal in the next major. Never read by
+	 * anything — setting it has no effect today. Use `allowedTools` on the
+	 * query to bound which tools a run may use; it says the same thing per
+	 * run instead of per definition. See {@link ToolCatalogSurface}.
+	 */
 	readonly surfaces?: readonly ToolCatalogSurface[]
 	readonly providerConfig?: Record<string, unknown>
 }