@namzu/sdk 62.12.0 → 62.14.0

package/src/registry/command/kernel-commands.ts

@@ -8,7 +8,7 @@ import {
 	StaleGoalError,
 } from '../../store/goal/index.js'
 import type { HostCommandDescriptor } from '../../types/command/index.js'
-import type { GoalRef, SessionGoal } from '../../types/goal/index.js'
+import type { GoalConfirmedBy, GoalRef, SessionGoal } from '../../types/goal/index.js'
 import type { SessionId, TenantId } from '../../types/ids/index.js'
 import type { Skill } from '../../types/skills/index.js'
 import { isInvocableBy, skillInvocation } from '../../types/skills/index.js'
@@ -48,9 +48,12 @@ export interface GoalCommandScope {
 	readonly tenantId: TenantId
 	/** Process-local permission for automatic continuation. */
 	readonly activation?: SessionGoalActivation
+	/** What a goal that does not choose is confirmed by; shown by `/goal status`. Default `model`. */
+	readonly defaultConfirmedBy?: GoalConfirmedBy
 }
 
-const GOAL_ARGUMENTS = '[status|set <objective>|<objective>|edit <objective>|pause|resume|clear]'
+const GOAL_ARGUMENTS =
+	'[status|set [--confirmed-by record|model] <objective>|<objective>|edit <objective>|pause|resume|clear]'
 const GOAL_USAGE = `Usage: /goal ${GOAL_ARGUMENTS}`
 
 type ParsedGoalCommand =
@@ -78,6 +81,60 @@ function parseGoalCommand(args: readonly string[]): ParsedGoalCommand {
 	return { kind: 'create', objective: input }
 }
 
+type ConfirmedByFlag =
+	| {
+			readonly kind: 'ok'
+			readonly args: readonly string[]
+			readonly confirmedBy?: GoalConfirmedBy
+	  }
+	| { readonly kind: 'invalid' }
+
+/**
+ * Takes `--confirmed-by <model|record>` (or `=`) out of the arguments, but only
+ * where a flag stands: at the front, right after `set`, or closing the command. In the middle the words
+ * belong to the objective, so a goal about the flag itself keeps its text.
+ */
+function takeConfirmedBy(args: readonly string[]): ConfirmedByFlag {
+	const head: string[] = []
+	let i = 0
+	if ((args[0] ?? '').toLowerCase() === 'set') {
+		head.push(args[0] ?? '')
+		i = 1
+	}
+	let found: GoalConfirmedBy | undefined
+	for (; i < args.length; i++) {
+		const arg = args[i] ?? ''
+		let value: string
+		if (arg === '--confirmed-by') {
+			value = args[i + 1] ?? ''
+			i++
+		} else if (arg.startsWith('--confirmed-by=')) {
+			value = arg.slice('--confirmed-by='.length)
+		} else {
+			break
+		}
+		if (value !== 'model' && value !== 'record') return { kind: 'invalid' }
+		found = value
+	}
+	let tail = args.slice(i)
+	// A flag may also close the command; in the middle its words are the objective's.
+	const last = tail[tail.length - 1] ?? ''
+	const beforeLast = tail[tail.length - 2] ?? ''
+	let closing: string | undefined
+	if (last.startsWith('--confirmed-by=')) {
+		closing = last.slice('--confirmed-by='.length)
+		tail = tail.slice(0, -1)
+	} else if (beforeLast === '--confirmed-by') {
+		closing = last
+		tail = tail.slice(0, -2)
+	}
+	if (closing !== undefined) {
+		if (closing !== 'model' && closing !== 'record') return { kind: 'invalid' }
+		found = closing
+	}
+	return { kind: 'ok', args: [...head, ...tail], ...(found ? { confirmedBy: found } : {}) }
+}
+
 function goalRef(goal: SessionGoal): GoalRef {
 	return { id: goal.id, revision: goal.revision }
 }
@@ -92,10 +149,19 @@ function goalCommands(goal: SessionGoal, armed: boolean): string {
 	return '/goal set <objective>, /goal clear'
 }
 
-function renderGoal(title: string, goal: SessionGoal, armed: boolean): string {
+function renderGoal(
+	title: string,
+	goal: SessionGoal,
+	armed: boolean,
+	defaultConfirmedBy: GoalConfirmedBy = 'model',
+): string {
 	return [
 		title,
 		`Status: ${goal.phase}`,
+		...(goal.confirmedBy === 'record' ||
+		(goal.confirmedBy === undefined && defaultConfirmedBy === 'record')
+			? ['Confirmed by: the record of the work']
+			: []),
 		`Automatic continuation: ${armed ? 'enabled' : 'paused'}`,
 		`Automatic turns: ${goal.roundsAdmitted} / ${goal.maxGoalRounds}`,
 		...(goal.blockedReason
@@ -108,7 +174,12 @@ function renderGoal(title: string, goal: SessionGoal, armed: boolean): string {
 }
 
 function renderScopedGoal(title: string, goal: SessionGoal, scope: GoalCommandScope): string {
-	return renderGoal(title, goal, scope.activation?.isArmed(scope.sessionId, goal) ?? false)
+	return renderGoal(
+		title,
+		goal,
+		scope.activation?.isArmed(scope.sessionId, goal) ?? false,
+		scope.defaultConfirmedBy,
+	)
 }
 
 function missingGoal(action: string) {
@@ -125,7 +196,20 @@ async function runGoalCommand(scope: GoalCommandScope | undefined, args: readonl
 			reason: 'Goals need a durable session. This host did not supply one for the current command.',
 		}
 	}
-	const command = parseGoalCommand(args)
+	const flag = takeConfirmedBy(args)
+	if (flag.kind === 'invalid') {
+		return {
+			kind: 'refused' as const,
+			reason: `--confirmed-by takes record or model.\n${GOAL_USAGE}`,
+		}
+	}
+	const command = parseGoalCommand(flag.args)
+	if (flag.confirmedBy !== undefined && command.kind !== 'create') {
+		return {
+			kind: 'refused' as const,
+			reason: `--confirmed-by is chosen when a goal is set.\n${GOAL_USAGE}`,
+		}
+	}
 	try {
 		const current = await scope.store.getGoal(scope.sessionId, scope.tenantId)
 		switch (command.kind) {
@@ -154,7 +238,11 @@ async function runGoalCommand(scope: GoalCommandScope | undefined, args: readonl
 					}
 				}
 				const created = await scope.store.createGoal(
-					{ sessionId: scope.sessionId, objective: command.objective },
+					{
+						sessionId: scope.sessionId,
+						objective: command.objective,
+						...(flag.confirmedBy !== undefined ? { confirmedBy: flag.confirmedBy } : {}),
+					},
 					scope.tenantId,
 				)
 				scope.activation?.arm(created)

package/src/runtime/query/cancelled-before-start.ts

@@ -1,5 +1,6 @@
 import type { TurnRecorder } from '../../manager/session/turn-recorder.js'
 import { GENAI, NAMZU, agentTurnSpanName, parentContext } from '../../telemetry/attributes.js'
+import { agentRunAttributes } from '../../telemetry/genai.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
 import type { MessageId } from '../../types/ids/index.js'
 import { type Message, createSystemMessage } from '../../types/message/index.js'
@@ -82,6 +83,7 @@ export async function* settlePreStartCancellation(
 		[GENAI.AGENT_ID]: params.agentId,
 		[GENAI.REQUEST_MODEL]: turnConfig.model,
 		[GENAI.SYSTEM]: params.provider.id,
+		...agentRunAttributes(params.provider.id),
 	})
 
 	const push = (message: Message, ids: ReadonlyMap<Message, MessageId>): void => {

package/src/runtime/query/index.ts

@@ -36,10 +36,16 @@ import {
 	parentContext,
 	serializeSpan,
 } from '../../telemetry/attributes.js'
+import { agentRunAttributes } from '../../telemetry/genai.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
 import { buildAdvisoryTools } from '../../tools/advisory/index.js'
 import { SearchToolsTool } from '../../tools/builtins/search-tools.js'
 import { createStructuredOutputTool } from '../../tools/builtins/structuredOutput.js'
+import {
+	HAND_BACK_GUIDANCE,
+	HAND_BACK_GUIDANCE_CONTRIBUTION_ID,
+	buildHandBackTool,
+} from '../../tools/hand-back/index.js'
 import { buildTaskTools } from '../../tools/task/index.js'
 import { ToolManager } from '../../toolsets/manager.js'
 import { toolset } from '../../toolsets/toolset.js'
@@ -1283,6 +1289,10 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 			for (const tool of taskTools) addRuntimeTool(tool, 'deferred')
 		}
 
+		// The way out of a task that cannot be done as specified. Only when the host
+		// turned it on; with it off the tool is absent and the prompt is as before.
+		if (turnConfig.handBack === true) addRuntimeTool(buildHandBackTool(), 'active')
+
 		// `search_tools` is added only when something could actually be
 		// deferred — one of the runtime tools above, or a caller toolset that
 		// declared itself `deferred(...)`. Nothing deferred means nothing for
@@ -1789,6 +1799,15 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 		// The turn's own registry when the host passed none, so a hook's
 		// annotation has somewhere to land.
 		const promptContributions = params.promptContributions ?? new PromptContributionRegistry()
+		if (turnConfig.handBack === true) {
+			promptContributions.replace({
+				id: HAND_BACK_GUIDANCE_CONTRIBUTION_ID,
+				placement: 'static',
+				render: () => HAND_BACK_GUIDANCE,
+			})
+		} else {
+			promptContributions.unregister(HAND_BACK_GUIDANCE_CONTRIBUTION_ID)
+		}
 
 		const promptBuilder = new PromptBuilder({
 			systemPrompt: params.systemPrompt,
@@ -2110,6 +2129,7 @@ export async function* query(params: QueryParams): AsyncGenerator<SessionEvent,
 				[GENAI.AGENT_ID]: params.agentId,
 				[GENAI.REQUEST_MODEL]: turnConfig.model,
 				[GENAI.SYSTEM]: params.provider.id,
+				...agentRunAttributes(params.provider.id),
 			})
 
 			let sandbox: Sandbox | undefined

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

@@ -29,6 +29,8 @@ import {
 } from '../../../telemetry/attributes.js'
 import { getTracer } from '../../../telemetry/runtime-accessors.js'
 import { STRUCTURED_OUTPUT_TOOL_NAME } from '../../../tools/builtins/structuredOutput.js'
+import { SESSION_GOAL_TOOL_NAMES } from '../../../tools/goal/index.js'
+import { HAND_BACK_TOOL_NAME, parseHandBack } from '../../../tools/hand-back/index.js'
 import type { ToolManager } from '../../../toolsets/manager.js'
 import { RECALLED_MEMORY_ENTRY_KEY, recalledMemoryIds } from '../../../turn/memory-recall.js'
 import { type CostInfo, type TokenUsage, promptSizeOf } from '../../../types/common/index.js'
@@ -48,6 +50,7 @@ import {
 import { classifyProviderError, readOutputOverflow } from '../../../types/provider/errors.js'
 import type { ChatCompletionResponse, ReasoningEffort } from '../../../types/provider/index.js'
 import type { AnswerReview, AnswerReviewContext } from '../../../types/session/answer-review.js'
+import type { HandBack } from '../../../types/session/hand-back.js'
 import type {
 	RecalledMemory,
 	SessionEvent,
@@ -136,6 +139,9 @@ import {
 } from './step-shaping.js'
 import { streamProviderTurn } from './stream-turn.js'
 
+/** Notes a host may add before a turn ends (`TurnConfig.outcome.beforeEnd`) in one turn. */
+const MAX_BEFORE_END_NOTES = 16
+
 /** Capped steps in a row after which the per-step cap stops applying for the turn's next step. */
 const MAX_CAPPED_STREAK = 3
 
@@ -339,6 +345,7 @@ export class IterationOrchestrator {
 	private readonly completionAudit?: CompletionAudit
 	/** What the turn changed and what checked it; see {@link OutcomeLedger}. Kept whether or not the host asked. */
 	private readonly outcomeLedger: OutcomeLedger
+	private beforeEndNotes = 0
 	private outcomeHydrated = false
 	/** The next step must call a tool, at low effort: set by the stall monitor or a capped step. */
 	private forceActionNextStep = false
@@ -2016,6 +2023,14 @@ export class IterationOrchestrator {
 							recorder.pushMessage(createRuntimeContextMessage(auditReminder, 'progress-nudge'))
 							continue
 						}
+						const endNote =
+							!forceFinalize && closingStopReason === undefined
+								? await this.askBeforeEnd()
+								: undefined
+						if (endNote !== undefined) {
+							recorder.pushMessage(createRuntimeContextMessage(endNote, 'progress-nudge'))
+							continue
+						}
 						if (!forceFinalize && closingStopReason === undefined) {
 							const feedback = yield* this.askStopHooks()
 							const stoppedByHook = this.ctx.toolExecutor.takeHalt?.()
@@ -2074,6 +2089,28 @@ export class IterationOrchestrator {
 					if (reviewOutcome.decision === 'stop') {
 						return
 					}
+
+					// The model handed the task back to a person. Nothing else ran in
+					// this step (its sibling calls were refused), and no further model
+					// call is made: the turn ends here, as a turn that ended on its own.
+					const handedBack = this.takeHandBack(reviewOutcome.results, response)
+					if (handedBack !== undefined) {
+						this.ctx.log.info('The model handed the task back — ending turn', {
+							[NAMZU.TURN_ID]: recorder.turnId,
+							[NAMZU.ITERATION]: iterationNum,
+							'namzu.hand_back.kind': handedBack.kind,
+						})
+						recorder.setHandedBack(handedBack)
+						recorder.setStopReason('end_turn')
+						await this.ctx.emitEvent({
+							type: 'iteration_completed',
+							turnId: recorder.turnId,
+							iteration: iterationNum,
+							hasToolCalls: true,
+						})
+						yield* this.ctx.drainPending()
+						break
+					}
 					const needsCorrection = await this.recordToolStructuredFailure(
 						reviewOutcome.results,
 						iterationNum,
@@ -3406,8 +3443,14 @@ export class IterationOrchestrator {
 		else this.outcomeLedger.restore(restored.snapshot)
 	}
 
-	/** Whether a call is one the outcome record may treat as only looking. */
+	/**
+	 * Whether a call is one the outcome record may treat as only looking. The
+	 * goal tools write the goal's own record, never the workspace; counting a
+	 * report of completion as a possible change would make every check before it
+	 * read as not known to be fresh.
+	 */
 	private lookedOnly(toolName: string, input: unknown): boolean {
+		if ((SESSION_GOAL_TOOL_NAMES as readonly string[]).includes(toolName)) return true
 		try {
 			return !callChangedState(toolName, this.ctx.tools.get(toolName)?.isReadOnly?.(input), false)
 		} catch {
@@ -3474,6 +3517,47 @@ export class IterationOrchestrator {
 		}
 	}
 
+	/**
+	 * The host's say before the turn ends (`TurnConfig.outcome.beforeEnd`): a note
+	 * for the model, or `undefined` to let the turn end. Bounded, and a hook that
+	 * fails never fails the turn.
+	 */
+	async askBeforeEnd(): Promise<string | undefined> {
+		const hook = this.ctx.turnConfig.outcome?.beforeEnd
+		if (hook === undefined || this.beforeEndNotes >= MAX_BEFORE_END_NOTES) return undefined
+		try {
+			const note = await hook(async () => {
+				this.hydrateOutcome()
+				return await this.outcomeLedger.preview()
+			})
+			if (typeof note !== 'string' || note.trim() === '') return undefined
+			this.beforeEndNotes += 1
+			return note
+		} catch (err) {
+			this.ctx.log.warn('The host hook before the turn ends failed; the turn ends', {
+				'exception.message': toErrorMessage(err),
+			})
+			return undefined
+		}
+	}
+
+	/**
+	 * The hand-back this step made, when the setting is on and `hand_back_task`
+	 * succeeded; the first one when the model made several (the rest were refused).
+	 */
+	private takeHandBack(
+		results: readonly ToolCallOutcome[],
+		response: ChatCompletionResponse,
+	): HandBack | undefined {
+		if (this.ctx.turnConfig.handBack !== true) return undefined
+		const hit = results.find(
+			(r) => r.toolName === HAND_BACK_TOOL_NAME && r.isError !== true && r.skipped !== true,
+		)
+		if (!hit) return undefined
+		const call = (response.message.toolCalls ?? []).find((c) => c.id === hit.toolCallId)
+		return call ? parseHandBack(call.function.arguments) : undefined
+	}
+
 	/** The outcome record as the turn leaves it; `undefined` when none was kept. */
 	async takeOutcome(): Promise<TurnOutcome | undefined> {
 		try {

package/src/runtime/query/iteration/phases/tool-review.ts

@@ -1,5 +1,10 @@
 import { allowRuleScope } from '../../../../authorization/gate.js'
 import type { AuthorizationGate } from '../../../../authorization/index.js'
+import {
+	HAND_BACK_SIBLING_REFUSAL,
+	HAND_BACK_TOOL_NAME,
+	parseHandBack,
+} from '../../../../tools/hand-back/index.js'
 import { isTrustedReadOnly } from '../../../../tools/trusted-read-only.js'
 import type { ToolSourceRef } from '../../../../toolsets/types.js'
 import type {
@@ -259,7 +264,25 @@ export async function* runToolReview(
 	 * with the tracker's refusal instead of being run — the one denial the
 	 * tracker makes, on top of whatever the caller already denied.
 	 */
-	const withRepeatRefusals = (denials?: ToolCallDenials): ToolCallDenials | undefined => {
+	const withRepeatRefusals = (given?: ToolCallDenials): ToolCallDenials | undefined => {
+		// A step that hands the task back runs nothing else: the first hand-back
+		// call is the step, every other call in it is refused.
+		let denials = given
+		if (ctx.turnConfig?.handBack === true) {
+			const handBack = toolCallSummaries.find(
+				(summary) =>
+					summary.name === HAND_BACK_TOOL_NAME && parseHandBack(summary.input) !== undefined,
+			)
+			if (handBack) {
+				let siblings: Map<string, string> | undefined
+				for (const summary of toolCallSummaries) {
+					if (summary.id === handBack.id || given?.has(summary.id)) continue
+					siblings ??= new Map(given ?? [])
+					siblings.set(summary.id, HAND_BACK_SIBLING_REFUSAL)
+				}
+				denials = siblings ?? given
+			}
+		}
 		const tracker = ctx.repeatCalls
 		if (!tracker) return denials
 		let merged: Map<string, string> | undefined

package/src/runtime/query/iteration/stream-turn.ts

@@ -15,6 +15,12 @@ import {
 	toolCallFramingViolation,
 } from '../../../provider/tool-call-framing.js'
 import { GENAI, NAMZU, chatSpanName, parentContext } from '../../../telemetry/attributes.js'
+import {
+	chatStartAttributes,
+	chatUsageAttributes,
+	errorTypeAttributes,
+	genAiErrorType,
+} from '../../../telemetry/genai.js'
 import {
 	recordModelDuration,
 	recordTimeToFirstToken,
@@ -200,6 +206,7 @@ async function settleCancelledTurn(args: {
 			[GENAI.USAGE_OUTPUT_TOKENS]: args.usage.completionTokens,
 			[NAMZU.CACHE_READ_TOKENS]: args.usage.cachedTokens ?? 0,
 			[NAMZU.CACHE_WRITE_TOKENS]: args.usage.cacheWriteTokens ?? 0,
+			...chatUsageAttributes(args.usage),
 		})
 		args.span.setStatus({ code: SpanStatusCode.OK })
 		args.span.end()
@@ -277,6 +284,7 @@ export async function* streamProviderTurn(
 			? { [GENAI.REQUEST_TEMPERATURE]: params.temperature }
 			: {}),
 		...(params.maxTokens !== undefined ? { [GENAI.REQUEST_MAX_TOKENS]: params.maxTokens } : {}),
+		...chatStartAttributes(provider.id),
 	})
 
 	const messageId = announceAs ?? generateMessageId()
@@ -1053,6 +1061,7 @@ export async function* streamProviderTurn(
 	yield* drainPending()
 
 	if (streamError && !recoveredToolInputFromStreamError) {
+		chatSpan.setAttributes(errorTypeAttributes(genAiErrorType(streamCause)))
 		chatSpan.setStatus({ code: SpanStatusCode.ERROR, message: streamError })
 		chatSpan.end()
 
@@ -1132,6 +1141,7 @@ export async function* streamProviderTurn(
 		[GENAI.USAGE_OUTPUT_TOKENS]: usage.completionTokens,
 		[NAMZU.CACHE_READ_TOKENS]: usage.cachedTokens ?? 0,
 		[NAMZU.CACHE_WRITE_TOKENS]: usage.cacheWriteTokens ?? 0,
+		...chatUsageAttributes(usage),
 	})
 	chatSpan.setStatus({ code: SpanStatusCode.OK })
 	chatSpan.end()

package/src/runtime/query/result.ts

@@ -5,6 +5,7 @@ import { isCallerAbortError, isProviderRequestError } from '../../provider/error
 import { TokenBudgetAdmissionError } from '../../provider/token-budget.js'
 import type { ActivityStore } from '../../store/activity/memory.js'
 import { GENAI, NAMZU } from '../../telemetry/attributes.js'
+import { errorTypeAttributes, genAiErrorType } from '../../telemetry/genai.js'
 import { explainError } from '../../types/errors/catalog.js'
 import { toPlatformError } from '../../types/errors/index.js'
 import type { CheckpointId } from '../../types/hitl/index.js'
@@ -211,6 +212,7 @@ export class ResultAssembler {
 		rootSpan.setAttributes({
 			[NAMZU.TURN_STATUS]: 'error',
 			[NAMZU.ITERATION]: recorder.currentIteration,
+			...errorTypeAttributes(genAiErrorType(err)),
 		})
 		rootSpan.setStatus({ code: SpanStatusCode.ERROR, message: errorMessage })
 		rootSpan.recordException(err instanceof Error ? err : new Error(errorMessage))