@namzu/sdk 3.2.0 → 3.3.0

package/src/runtime/query/iteration/index.ts

@@ -11,7 +11,6 @@ import {
 	GENAI,
 	NAMZU,
 	agentIterationSpanName,
-	chatSpanName,
 	parentContext,
 } from '../../../telemetry/attributes.js'
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
@@ -154,9 +153,6 @@ export class IterationOrchestrator {
 				{},
 				parentContext(this.ctx.rootSpan),
 			)
-			// Declared out here so the iteration's own finally can close it on
-			// any path that does not reach its success branch.
-			let chatSpan: Span | undefined
 			try {
 				// Tool spans for this turn belong under this iteration. Inside
 				// the try rather than before it: a throw from any of these left
@@ -282,27 +278,6 @@ export class IterationOrchestrator {
 				// aggregated `ChatCompletionResponse` for the legacy
 				// downstream paths (assistantMsg construction, working
 				// state extraction, telemetry attribute stamping).
-				// The model call gets its own span. There was none at all —
-				// `chatSpanName` shipped with zero call sites — so a run's traces
-				// carried no LLM latency whatsoever, and the one thing anybody
-				// opens a trace to find (which turn was slow, and why) was the
-				// one thing not in it.
-				chatSpan = tracer.startSpan(chatSpanName(stepModel), {}, parentContext(iterSpan))
-				chatSpan.setAttributes({
-					[GENAI.OPERATION_NAME]: 'chat',
-					[GENAI.SYSTEM]: this.ctx.provider.id,
-					[GENAI.REQUEST_MODEL]: stepModel,
-					...((step.temperature ?? runConfig.temperature) !== undefined
-						? { [GENAI.REQUEST_TEMPERATURE]: (step.temperature ?? runConfig.temperature) as number }
-						: {}),
-					...((step.maxResponseTokens ?? runConfig.maxResponseTokens) !== undefined
-						? {
-								[GENAI.REQUEST_MAX_TOKENS]: (step.maxResponseTokens ??
-									runConfig.maxResponseTokens) as number,
-							}
-						: {}),
-				})
-
 				const { response, messageId } = yield* streamProviderTurn(
 					this.ctx.provider,
 					{
@@ -339,27 +314,6 @@ export class IterationOrchestrator {
 					iterSpan,
 				)
 
-				// Stamped on the call that produced them. The token counts also
-				// stay on the iteration span below, where they have always been:
-				// moving them would silently break whatever reads them today,
-				// and one turn per iteration makes the two agree.
-				chatSpan.setAttributes({
-					[GENAI.RESPONSE_MODEL]: response.model || stepModel,
-					[GENAI.RESPONSE_ID]: response.id,
-					[GENAI.USAGE_INPUT_TOKENS]: response.usage.promptTokens,
-					[GENAI.USAGE_OUTPUT_TOKENS]: response.usage.completionTokens,
-					// An array, per the semantic convention: one call can finish
-					// several ways when a provider returns more than one choice.
-					[GENAI.RESPONSE_FINISH_REASONS]: [response.finishReason ?? 'stop'],
-					[NAMZU.CACHE_READ_TOKENS]: response.usage.cachedTokens ?? 0,
-					[NAMZU.CACHE_WRITE_TOKENS]: response.usage.cacheWriteTokens ?? 0,
-				})
-				chatSpan.setStatus({ code: SpanStatusCode.OK })
-				chatSpan.end()
-				// Closed here for an accurate duration, and cleared so the
-				// iteration finally does not close it a second time.
-				chatSpan = undefined
-
 				// Main-loop turn: also records the prompt size compaction reads.
 				runMgr.recordTurnUsage(response.usage)
 
@@ -794,8 +748,6 @@ export class IterationOrchestrator {
 				iterSpan.recordException(err instanceof Error ? err : new Error(String(err)))
 				throw err
 			} finally {
-				// A model call that threw never reached its own close above.
-				chatSpan?.end()
 				// The only place the iteration span ends. It used to be ended at each of
 				// seventeen exits, which is a rule every future edit has to
 				// remember; a generator abandoned by its consumer never reached

package/src/telemetry/__tests__/model-call-span.test.ts

@@ -109,10 +109,14 @@ describe('the model call has a span of its own', () => {
 	it('opens one named for the model', async () => {
 		await runOnce([{ text: 'done' }])
 
-		// One per model call. A run makes at least one, and a forced-final
-		// turn makes another — both are model calls and both deserve a span.
-		expect(chatSpans().length).toBeGreaterThanOrEqual(1)
-		for (const s of chatSpans()) expect(s.name).toBe('chat mock-model')
+		// EXACTLY one. This was written as `toHaveLength(1)`, failed with 2,
+		// and was relaxed to `>= 1` under a plausible-sounding explanation
+		// about forced-final turns. The 2 was real: a second span with the
+		// same name and the same parent had been added beside the one
+		// `stream-turn.ts` already opened, so a naive sum double-counted both
+		// latency and tokens. Relaxing the assertion is what let that ship.
+		expect(chatSpans()).toHaveLength(1)
+		expect(chatSpans()[0]?.name).toBe('chat mock-model')
 	})
 
 	it('closes it', async () => {
@@ -168,11 +172,13 @@ describe('the model call has a span of its own', () => {
 		expect(attrs).toHaveProperty('namzu.cache.write_tokens')
 	})
 
-	it('opens one per turn, not one per run', async () => {
+	it('opens exactly one per model call, however many turns a run takes', async () => {
 		await runOnce([{ text: 'first' }, { text: 'second' }])
 
-		// A run with several turns is exactly the case a trace is opened for.
-		expect(chatSpans().length).toBeGreaterThanOrEqual(1)
+		// The count has to track model calls, not runs and not iterations —
+		// which is the only way a duplicate is visible at all.
+		const calls = spans.filter((s) => s.name.includes('iteration')).length
+		expect(chatSpans().length).toBeLessThanOrEqual(calls)
 	})
 
 	it('nests under the iteration span rather than emitting as a root', async () => {

package/src/types/agent/base.ts

@@ -1,4 +1,5 @@
 import type { AgentStatus, CostInfo, TokenUsage } from '../common/index.js'
+import type { ResumeHandler } from '../hitl/index.js'
 import type { RunId, SessionId, TenantId } from '../ids/index.js'
 import type { InvocationState } from '../invocation/index.js'
 import type { Message } from '../message/index.js'
@@ -78,6 +79,32 @@ export interface BaseAgentConfig {
 
 	/** Span a delegated run hangs off. Absent for a top-level run. */
 	parentSpan?: import('@opentelemetry/api').Span
+
+	/**
+	 * Where this agent takes a decision it cannot make alone — a tool that
+	 * needs approval, a question for a human, a plan to sign off.
+	 *
+	 * Declared HERE, on the base config, rather than only on the agent
+	 * shapes that happened to want it. `AgentManager` builds a child as a
+	 * `BaseAgentConfig` and `SendMessageOptions.configOverrides` is a
+	 * `Partial` of it, so a field further down the hierarchy is one a
+	 * spawn cannot express AT THE TYPE LEVEL — and that is what happened:
+	 * every delegated child fell through to the SDK's `autoApproveHandler`
+	 * however carefully its parent had been wired.
+	 *
+	 * What that cost is narrower than "no gate in children" and worth
+	 * stating exactly. A `VerificationGate` DENY still bites inside a
+	 * child, because denials are threaded into the executor and no later
+	 * approval releases them. What was lost is the REVIEW tier: every call
+	 * the gate left undecided went to the resume handler, and for a child
+	 * that handler auto-approved. So a host running "ask before acting"
+	 * had a human review `write` at the top level and never see the same
+	 * `write` issued one hop down.
+	 *
+	 * Absent still means auto-approve, so a host that never wired one is
+	 * unaffected.
+	 */
+	resumeHandler?: ResumeHandler
 }
 
 export type RuntimeToolOverrides = Record<string, ToolAvailability | 'disabled'>

package/src/types/agent/task.ts

@@ -1,6 +1,7 @@
 import type { ActorRef } from '../../types/session/actor.js'
 import type { WorkspaceBackendKind } from '../../types/workspace/ref.js'
 import type { TokenUsage } from '../common/index.js'
+import type { ResumeHandler } from '../hitl/index.js'
 import type { RunId, SessionId, TaskId, TenantId } from '../ids/index.js'
 import type { Message } from '../message/index.js'
 import type { RunEventListener } from '../run/events.js'
@@ -41,6 +42,23 @@ export interface AgentTaskContext {
 
 	factoryOptions?: AgentFactoryOptions
 
+	/**
+	 * The parent's channel to whoever can answer a decision it cannot make
+	 * alone, handed down so a child asks the same person.
+	 *
+	 * Passed as the function itself, which works because delegation is
+	 * in-process: `LocalTaskGateway` is the only `TaskGateway` in the tree.
+	 * A gateway that dispatched across a process boundary could not carry a
+	 * closure and would have to proxy the request onto the parent's event
+	 * stream and route the answer back by request id — the upward half of
+	 * which already exists, since `wrapChildListener` stamps lineage on
+	 * every child event the parent sees.
+	 *
+	 * Absent means the child auto-approves, exactly as every child did
+	 * before this existed.
+	 */
+	resumeHandler?: ResumeHandler
+
 	/** Isolation boundary. Required per session-hierarchy.md §12.1. */
 	tenantId: TenantId