@namzu/sdk 62.12.0 → 62.14.0

package/src/telemetry/genai.ts

@@ -0,0 +1,202 @@
+import type { Attributes } from '@opentelemetry/api'
+import { isProviderRequestError } from '../provider/errors.js'
+import type { TokenUsage } from '../types/common/index.js'
+import { GENAI } from './attributes.js'
+
+/**
+ * The OpenTelemetry semantic conventions for generative AI, as far as the
+ * spans of this kernel follow them.
+ *
+ * The convention is still marked "Development", so its names can change
+ * between releases. What the kernel emits is therefore pinned to ONE released
+ * version, and says so: the instrumentation scope carries the schema URL of
+ * that version. The text of the convention was published in the
+ * `semantic-conventions` repository up to and including v1.41.1; later
+ * releases only point to a new repository. Moving the pin means reading the
+ * new text, changing {@link GENAI_SEMCONV_VERSION} and the table in
+ * `docs/sdk/telemetry-genai.md` together; a test fails when an attribute name
+ * is emitted that is not in {@link GENAI_SEMCONV_ATTRIBUTES}.
+ *
+ * Everything here is additive: the kernel's own names (`namzu.*`, and the
+ * `gen_ai.*` names it already wrote) are untouched. One process-wide switch
+ * turns the new names off for a backend that bills by attribute.
+ */
+export const GENAI_SEMCONV_VERSION = '1.41.1'
+
+/** Schema URL of the pinned version; set on the tracer's instrumentation scope. */
+export const GENAI_SEMCONV_SCHEMA_URL = `https://opentelemetry.io/schemas/${GENAI_SEMCONV_VERSION}`
+
+/** `gen_ai.operation.name` values this kernel uses; all three are in the pinned convention's list. */
+export const GENAI_OPERATION = {
+	CHAT: 'chat',
+	EXECUTE_TOOL: 'execute_tool',
+	INVOKE_AGENT: 'invoke_agent',
+} as const
+
+/** The convention's name for the error class of a failed operation (stable). */
+export const ERROR_TYPE = 'error.type'
+
+/** The convention's fallback `error.type` value. */
+export const ERROR_TYPE_OTHER = '_OTHER'
+
+/**
+ * Every attribute name the pinned convention version defines for the three
+ * span kinds this kernel emits (inference, execute tool, invoke agent) that
+ * the kernel may write, whether the kernel's own earlier code or the additions
+ * wrote it. A span's `gen_ai.*` / `error.type` keys must all be in here, with
+ * the one exception named in {@link GENAI_NON_CONVENTION_NAMES}.
+ */
+export const GENAI_SEMCONV_ATTRIBUTES: readonly string[] = [
+	GENAI.OPERATION_NAME,
+	GENAI.PROVIDER_NAME,
+	ERROR_TYPE,
+	GENAI.CONVERSATION_ID,
+	GENAI.AGENT_NAME,
+	GENAI.AGENT_ID,
+	GENAI.REQUEST_MODEL,
+	GENAI.REQUEST_STREAM,
+	GENAI.REQUEST_TEMPERATURE,
+	GENAI.REQUEST_MAX_TOKENS,
+	GENAI.RESPONSE_MODEL,
+	GENAI.RESPONSE_ID,
+	GENAI.RESPONSE_FINISH_REASONS,
+	GENAI.USAGE_INPUT_TOKENS,
+	GENAI.USAGE_OUTPUT_TOKENS,
+	GENAI.USAGE_CACHE_READ_INPUT_TOKENS,
+	GENAI.USAGE_CACHE_CREATION_INPUT_TOKENS,
+	GENAI.USAGE_REASONING_OUTPUT_TOKENS,
+	GENAI.TOOL_NAME,
+	GENAI.TOOL_CALL_ID,
+	GENAI.TOOL_TYPE,
+]
+
+/**
+ * `gen_ai.*` names the kernel writes that are NOT in the pinned convention.
+ * `gen_ai.system` is still in the 1.41.1 registry but deprecated, replaced by
+ * `gen_ai.provider.name`; the kernel emits it deliberately and
+ * it stays because it is existing output that nothing may remove.
+ */
+export const GENAI_NON_CONVENTION_NAMES: readonly string[] = [GENAI.SYSTEM]
+
+let enabled = true
+
+/**
+ * Turn the convention's attribute names (and the schema URL) on or off for
+ * every span the kernel starts from now on. On by default. `@namzu/telemetry`
+ * calls this from `TelemetryConfig.genAiAttributes`; a host that does not use
+ * that package can call it directly.
+ */
+export function setGenAiConventions(on: boolean): void {
+	enabled = on
+}
+
+export function genAiConventionsEnabled(): boolean {
+	return enabled
+}
+
+/**
+ * The value for `gen_ai.provider.name`, which the convention requires on every
+ * span that carries it.
+ *
+ * The convention (1.41.1) says: "If one of them applies, then the respective
+ * value MUST be used; otherwise, a custom value MAY be used." and states no
+ * further rule on the form of a custom value. So:
+ *
+ * - a listed value only when our provider IS that vendor's own API (the
+ *   cases below; `google` is `gcp.gen_ai`, "Any Google generative AI
+ *   endpoint", since our id does not say which one);
+ * - otherwise our own provider id, lower case, as the custom value. A gateway
+ *   that forwards to several vendors, a local runner and a custom HTTP
+ *   endpoint are never mapped to a vendor they are not.
+ *
+ * `undefined` only when there is no provider id at all.
+ */
+export function genAiProviderName(providerId: string | undefined): string | undefined {
+	switch (providerId) {
+		case 'anthropic':
+			return 'anthropic'
+		case 'bedrock':
+			return 'aws.bedrock'
+		case 'deepseek':
+			return 'deepseek'
+		case 'google':
+			return 'gcp.gen_ai'
+		case 'openai':
+		case 'codex':
+			return 'openai'
+		default: {
+			const own = providerId?.trim().toLowerCase()
+			return own ? own : undefined
+		}
+	}
+}
+
+/**
+ * A low-cardinality class for a failure, for `error.type`: the provider
+ * error kind for a classified provider failure, the error's own class name
+ * for an exception, `_OTHER` for anything else (a thrown string, a plain
+ * `Error`).
+ */
+export function genAiErrorType(err: unknown): string {
+	if (isProviderRequestError(err)) return err.kind
+	if (err instanceof Error) {
+		const name = err.name
+		return name && name !== 'Error' ? name : ERROR_TYPE_OTHER
+	}
+	return ERROR_TYPE_OTHER
+}
+
+/** Added when a turn (an agent run, a sub-agent included) starts. */
+export function agentRunAttributes(providerId: string | undefined): Attributes {
+	if (!enabled) return {}
+	const provider = genAiProviderName(providerId)
+	return {
+		[GENAI.OPERATION_NAME]: GENAI_OPERATION.INVOKE_AGENT,
+		...(provider !== undefined ? { [GENAI.PROVIDER_NAME]: provider } : {}),
+	}
+}
+
+/** Added when a model call starts. Every model call is streamed. */
+export function chatStartAttributes(providerId: string | undefined): Attributes {
+	if (!enabled) return {}
+	const provider = genAiProviderName(providerId)
+	return {
+		...(provider !== undefined ? { [GENAI.PROVIDER_NAME]: provider } : {}),
+		[GENAI.REQUEST_STREAM]: true,
+	}
+}
+
+/**
+ * Added when a model call answers. A count is written only when the driver
+ * reported a positive one: the record cannot tell "none" from "not
+ * reported", so a zero is left out rather than stated.
+ */
+export function chatUsageAttributes(usage: TokenUsage): Attributes {
+	if (!enabled) return {}
+	return {
+		...(usage.cachedTokens > 0
+			? { [GENAI.USAGE_CACHE_READ_INPUT_TOKENS]: usage.cachedTokens }
+			: {}),
+		...(usage.cacheWriteTokens > 0
+			? { [GENAI.USAGE_CACHE_CREATION_INPUT_TOKENS]: usage.cacheWriteTokens }
+			: {}),
+		...(usage.reasoningTokens !== undefined && usage.reasoningTokens > 0
+			? { [GENAI.USAGE_REASONING_OUTPUT_TOKENS]: usage.reasoningTokens }
+			: {}),
+	}
+}
+
+/** Added when a tool call starts. */
+export function toolCallAttributes(): Attributes {
+	if (!enabled) return {}
+	return { [GENAI.OPERATION_NAME]: GENAI_OPERATION.EXECUTE_TOOL }
+}
+
+/** The `error.type` of a tool call the kernel refused (not available, not allowed, plan mode); a custom low-cardinality value, which the convention allows. */
+export const PERMISSION_DENIED = 'permission_denied'
+
+/** Added to a span whose operation ended in an error. */
+export function errorTypeAttributes(errorType: string): Attributes {
+	if (!enabled) return {}
+	return { [ERROR_TYPE]: errorType }
+}

package/src/telemetry/runtime-accessors.ts

@@ -9,9 +9,19 @@
 // discarded — standard OTEL library behavior.
 
 import { type SpanContext, type Tracer, context, trace } from '@opentelemetry/api'
+import { GENAI_SEMCONV_SCHEMA_URL, genAiConventionsEnabled } from './genai.js'
 
+/**
+ * The kernel's tracer. While the GenAI convention names are on, its
+ * instrumentation scope carries the schema URL of the pinned convention
+ * version, which is how the convention says a producer states the version.
+ */
 export function getTracer(): Tracer {
-	return trace.getTracer('namzu')
+	return genAiConventionsEnabled()
+		? trace
+				.getTracerProvider()
+				.getTracer('namzu', undefined, { schemaUrl: GENAI_SEMCONV_SCHEMA_URL })
+		: trace.getTracer('namzu')
 }
 
 /**
@@ -57,3 +67,32 @@ export function getActiveSpanContext(): SpanContext | undefined {
 		return undefined
 	}
 }
+
+/**
+ * The active span as the W3C trace context an outgoing request can carry:
+ * `{ traceparent, tracestate? }`, or `{}` when no span is active.
+ *
+ * `{}` is what a host that never registered telemetry gets, for the same
+ * reason {@link getActiveSpanContext} returns `undefined` there: nothing is
+ * special-cased, the api's default context has no span. A span context that
+ * is not valid W3C (an all-zero id, a wrong length) also yields `{}`, since a
+ * malformed `traceparent` is worse than none.
+ */
+export function getTraceContextHeaders(): { traceparent?: string; tracestate?: string } {
+	const span = getActiveSpanContext()
+	if (!span) return {}
+	const { traceId, spanId } = span
+	if (!/^[0-9a-f]{32}$/.test(traceId) || /^0+$/.test(traceId)) return {}
+	if (!/^[0-9a-f]{16}$/.test(spanId) || /^0+$/.test(spanId)) return {}
+	const flags = (span.traceFlags & 0xff).toString(16).padStart(2, '0')
+	let tracestate: string | undefined
+	try {
+		tracestate = span.traceState?.serialize() || undefined
+	} catch {
+		tracestate = undefined
+	}
+	return {
+		traceparent: `00-${traceId}-${spanId}-${flags}`,
+		...(tracestate ? { tracestate } : {}),
+	}
+}

package/src/tools/goal/confirmation.ts

@@ -0,0 +1,375 @@
+import type { SessionGoalStore } from '../../store/goal/index.js'
+import { StaleGoalError } from '../../store/goal/index.js'
+import type { GoalConfirmedBy, GoalRoundAuthority, SessionGoal } from '../../types/goal/index.js'
+import type { HandBack } from '../../types/session/hand-back.js'
+import type { TurnOutcome } from '../../types/session/outcome.js'
+import { showCommand } from '../coordinator/outcome-record.js'
+import { handBackKindSentence, handBackReason } from '../hand-back/index.js'
+
+/**
+ * Ending a goal by the record of the work.
+ *
+ * Today the model's own report ends a goal. With `confirmedBy: 'record'` the
+ * kernel first reads the record it keeps of the work (`Turn.outcome`, built
+ * from what the tool calls did and never from what the model says) and the
+ * goal ends only as that record allows. There is no judge model and no model
+ * call beyond the turns themselves: the decision is a pure function over what
+ * the model reported, the record and the count of refusals so far.
+ */
+
+/**
+ * Times the record may send a goal back to the model before the goal ends as
+ * not confirmed. Three: a first refusal normally costs one fix and one rerun of
+ * the check, a second covers a fix that did not hold, a third a check that
+ * needed a second look; past that the model is looping, and every further
+ * refusal costs a model call that has stopped moving the work. The limit is
+ * per goal and a host can set its own.
+ */
+export const DEFAULT_GOAL_REFUSALS = 3
+
+/** The `reasonCode` that makes a `complete` report say that no check exists to run. */
+export const NO_CHECK_REASON_CODE = 'no-check-available'
+
+/** How a goal ended once the record had been read. */
+export type GoalEnding =
+	/** A check passed and nothing changed after it. */
+	| 'confirmed'
+	/** The model said it was done; the record cannot confirm or contradict it. */
+	| 'stated-not-checked'
+	/** The record disagrees and the model could not or would not put it right. */
+	| 'not-confirmed'
+
+/** What the model reported. */
+export type GoalStatement =
+	/** The goal is met. */
+	| 'met'
+	/** The goal is met, and no check exists to run. */
+	| 'no-check'
+	/** The goal is not met: the model could not make the check pass. */
+	| 'could-not'
+
+export type GoalDecision =
+	| { readonly kind: 'end'; readonly ending: GoalEnding; readonly sentence: string }
+	| { readonly kind: 'refuse'; readonly sentence: string; readonly note: string }
+
+export interface GoalDecisionInput {
+	readonly statement: GoalStatement
+	/** The record of the turn the report was made in; `undefined` when none was kept. */
+	readonly record: TurnOutcome | undefined
+	/** Refusals already given to this goal. */
+	readonly refusals: number
+	/** Most refusals this goal may be given. */
+	readonly maxRefusals: number
+	/**
+	 * An earlier round of this same goal changed files. Never makes a goal
+	 * confirmed; it only keeps a round that changed nothing and ran nothing from
+	 * being read as proof that nothing needed checking.
+	 */
+	readonly earlierRoundsChanged?: boolean
+}
+
+/** The record in plain words, without a lead and without a final stop. */
+export function recordSentence(record: TurnOutcome | undefined): string {
+	if (record === undefined) return 'there is no record of this work'
+	const named = (command: string | undefined): string =>
+		command === undefined ? 'a check' : (showCommand(command) ?? 'a command')
+	const passedCheck = [...record.checks].reverse().find((check) => check.result === 'passed')
+	switch (record.verdict) {
+		case 'checked':
+			return `${named(passedCheck?.command)} passed and nothing changed after it`
+		case 'unchanged':
+			return passedCheck
+				? `${named(passedCheck.command)} passed and nothing changed`
+				: 'nothing changed and no check ran'
+		case 'stale':
+			return 'files changed after the last passing check'
+		case 'failing': {
+			const failed = record.checks.filter((check) => check.result === 'failed')
+			const more = failed.length > 1 ? ` (and ${failed.length - 1} more)` : ''
+			return `${named(failed[0]?.command)} failed${more}`
+		}
+		case 'unchecked':
+			return 'files changed and no check ran'
+		case 'inconclusive': {
+			const masked = record.checks.find((check) => check.result === 'masked')
+			if (masked) {
+				const how = /(?<!\|)\|(?!\|)/.test(masked.command) ? 'the pipe' : 'the command line'
+				return `${named(masked.command)} ran, but ${how} hides whether it passed`
+			}
+			const unsettled = record.checks.find((check) => check.result === 'unsettled')
+			if (unsettled) return `${named(unsettled.command)} ran, but its result was not seen`
+			return 'files changed and no check gave a result that could be read'
+		}
+		case 'unknown':
+			return 'a command ran that may have changed files, and nothing could tell whether it did'
+	}
+}
+
+const HOW_TO_SAY_SO =
+	'To say so, call update_goal with status "blocked" and the reason if the check cannot be made to pass, or with status "complete", reasonCode "no-check-available" and the reason if no check exists here.'
+
+function refusalNote(record: TurnOutcome | undefined, earlierChanged: boolean): string {
+	switch (record?.verdict) {
+		case 'failing':
+			return `The record says ${recordSentence(record)}. Fix what it reports and run it again, or say plainly that you could not make it pass. ${HOW_TO_SAY_SO}`
+		case 'stale':
+			return `The record says ${recordSentence(record)}. Run the check again, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+		case 'unchecked':
+			return `The record says ${recordSentence(record)}. Run the project's check on the files as they are now, or say plainly that no check can be run here. ${HOW_TO_SAY_SO}`
+		case 'inconclusive':
+			return `The record says ${recordSentence(record)}. Run the check again on its own so that its result can be read, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+		default:
+			return earlierChanged
+				? `The record of this round says ${recordSentence(record)}, and an earlier round of this goal changed files. Run the project's check on the files as they are now, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+				: `The record says ${recordSentence(record)}. Run the check, or say plainly that you could not. ${HOW_TO_SAY_SO}`
+	}
+}
+
+/**
+ * What to do with the model's report of a goal, given the record.
+ *
+ * - The model says it could not: the goal ends `not-confirmed`; it is never
+ *   pushed again.
+ * - The model says no check exists: `stated-not-checked`, unless the record
+ *   holds a failing or stale check (`not-confirmed`) or a passing one
+ *   (`confirmed`).
+ * - The model says it is met: a passing check with nothing changed after it is
+ *   `confirmed`; a failing check, files changed after the last pass, files
+ *   changed and no check, or a check whose result could not be read are refused
+ *   while refusals remain and `not-confirmed` once they do not; nothing
+ *   changed, a command that may have changed files (`unknown`) or no record at
+ *   all is `stated-not-checked`. `unknown` is not refused on purpose: the
+ *   record keeps it for the whole turn, so no later check could clear it and a
+ *   refusal would only cost calls until the bound.
+ */
+export function decideGoalConfirmation(input: GoalDecisionInput): GoalDecision {
+	const { statement, record, refusals, maxRefusals } = input
+	const sentence = recordSentence(record)
+	if (statement === 'could-not') return { kind: 'end', ending: 'not-confirmed', sentence }
+
+	const verdict = record?.verdict
+	if (verdict === 'checked') return { kind: 'end', ending: 'confirmed', sentence }
+	if (
+		verdict === 'unchanged' &&
+		record?.checks.some((check) => check.result === 'passed' && check.fresh !== false)
+	) {
+		return { kind: 'end', ending: 'confirmed', sentence }
+	}
+
+	const contradicted = verdict === 'failing' || verdict === 'stale'
+	if (statement === 'no-check') {
+		return contradicted
+			? { kind: 'end', ending: 'not-confirmed', sentence }
+			: { kind: 'end', ending: 'stated-not-checked', sentence }
+	}
+
+	const earlierChanged = input.earlierRoundsChanged === true
+	const refusable =
+		contradicted ||
+		verdict === 'unchecked' ||
+		verdict === 'inconclusive' ||
+		(verdict === 'unchanged' && earlierChanged)
+	if (!refusable) return { kind: 'end', ending: 'stated-not-checked', sentence }
+	if (refusals >= Math.max(0, maxRefusals)) {
+		return { kind: 'end', ending: 'not-confirmed', sentence }
+	}
+	return { kind: 'refuse', sentence, note: refusalNote(record, earlierChanged) }
+}
+
+/** How a goal ended, for the line a person reads and for a machine reading the result. */
+export interface GoalEndingReport {
+	readonly goalId: string
+	readonly ending: GoalEnding
+	/** The record in plain words, as {@link recordSentence} writes it. */
+	readonly sentence: string
+	/** How many times the record sent this goal back before it ended. */
+	readonly refusals: number
+	/**
+	 * Set when the goal ended because the model handed the task back to a person
+	 * (`hand_back_task`). The ending is `not-confirmed` and `sentence` is the
+	 * kernel's sentence for the kind; the model's own words are in the hand-back.
+	 */
+	readonly handedBack?: HandBack
+}
+
+/** The closing line of a goal: which of the three endings it was and, always, what the record held. */
+export function describeGoalEnding(
+	report: Pick<GoalEndingReport, 'ending' | 'sentence' | 'handedBack'>,
+): string {
+	if (report.handedBack) {
+		return `Goal not confirmed: the model handed the task back to a person (${report.sentence}).`
+	}
+	switch (report.ending) {
+		case 'confirmed':
+			return `Goal confirmed by the record: ${report.sentence}.`
+		case 'stated-not-checked':
+			return `Goal stated, not checked: the record cannot confirm it (${report.sentence}).`
+		case 'not-confirmed':
+			return `Goal not confirmed: the record says ${report.sentence}.`
+	}
+}
+
+export interface GoalConfirmationOptions {
+	readonly store: SessionGoalStore
+	/** The same resolver the goal tools use: the authority of the turn, or none. */
+	readonly resolveAuthority: (turnId: string) => GoalRoundAuthority | null | undefined
+	/** What a goal that did not choose is confirmed by. Default `model`, the behaviour before this existed. */
+	readonly defaultConfirmedBy?: GoalConfirmedBy
+	/** Refusals a goal may be given. Default {@link DEFAULT_GOAL_REFUSALS}. */
+	readonly maxRefusals?: number
+}
+
+interface Claim {
+	readonly statement: GoalStatement
+	readonly reason?: string
+}
+
+/**
+ * Holds, for one session, what the model reported this turn, how many times a
+ * goal was sent back, and whether an earlier round of it changed files. All of
+ * it lives in memory: a restart begins the count again, which is the cautious
+ * side of the bound only in that the model gets its refusals again.
+ */
+export class GoalConfirmation {
+	private readonly claims = new Map<string, Claim>()
+	private readonly refusals = new Map<string, number>()
+	private readonly changed = new Set<string>()
+	private readonly endings = new Map<string, GoalEndingReport>()
+
+	constructor(private readonly options: GoalConfirmationOptions) {}
+
+	/** What decides this goal: its own choice, else the host's setting, else the model. */
+	confirmedByFor(goal: Pick<SessionGoal, 'confirmedBy'>): GoalConfirmedBy {
+		return goal.confirmedBy ?? this.options.defaultConfirmedBy ?? 'model'
+	}
+
+	get maxRefusals(): number {
+		return this.options.maxRefusals ?? DEFAULT_GOAL_REFUSALS
+	}
+
+	/** Refusals given to a goal so far. */
+	refusalsFor(goalId: string): number {
+		return this.refusals.get(goalId) ?? 0
+	}
+
+	/**
+	 * The model reported on the goal in the round now running; the record is read
+	 * when it finishes its answer. Held by goal, because only one round of a goal
+	 * runs at a time and a round that ends without an answer leaves the goal
+	 * active: the next report replaces this one.
+	 */
+	claim(goalId: string, statement: GoalStatement, reason?: string): void {
+		this.claims.set(goalId, { statement, ...(reason !== undefined ? { reason } : {}) })
+	}
+
+	/** The ending the turn's goal came to, once; `undefined` when it did not end here. */
+	takeEnding(turnId: string): GoalEndingReport | undefined {
+		const ending = this.endings.get(turnId)
+		this.endings.delete(turnId)
+		return ending
+	}
+
+	/**
+	 * The model handed this round's task back to a person: the goal, when this
+	 * turn is a round of an active one, ends as not confirmed and is left blocked
+	 * with the reason, whatever it was confirmed by. Nothing for any other turn.
+	 */
+	async handBack(turnId: string, handBack: HandBack): Promise<GoalEndingReport | undefined> {
+		const authority = this.options.resolveAuthority(turnId)
+		if (!authority) return undefined
+		const goal = await this.options.store.getGoal(authority.sessionId, authority.tenantId)
+		if (!goal || goal.id !== authority.id || goal.phase !== 'active') return undefined
+		const ref = { id: authority.id, revision: authority.revision }
+		try {
+			await this.options.store.blockGoal(authority.sessionId, authority.tenantId, ref, {
+				code: 'handed-back-to-a-person',
+				message: handBackReason(handBack),
+			})
+		} catch (error) {
+			if (error instanceof StaleGoalError) return undefined
+			throw error
+		}
+		const report: GoalEndingReport = {
+			goalId: goal.id,
+			ending: 'not-confirmed',
+			sentence: handBackKindSentence(handBack.kind),
+			refusals: this.refusalsFor(goal.id),
+			handedBack: handBack,
+		}
+		this.claims.delete(goal.id)
+		this.refusals.delete(goal.id)
+		this.changed.delete(goal.id)
+		return report
+	}
+
+	/** Drop a report that was never answered for, when its round ends without the turn finishing an answer. */
+	forget(goalId: string): void {
+		this.claims.delete(goalId)
+	}
+
+	/**
+	 * For `TurnConfig.outcome.beforeEnd`: the note that sends the model back to
+	 * the work, or `undefined` when the turn may end. A turn that is not a round
+	 * of a goal confirmed by the record is never touched.
+	 */
+	beforeEnd(
+		turnId: string,
+	): (read: () => Promise<TurnOutcome | undefined>) => Promise<string | undefined> {
+		return async (read) => {
+			const authority = this.options.resolveAuthority(turnId)
+			if (!authority) return undefined
+			const goal = await this.options.store.getGoal(authority.sessionId, authority.tenantId)
+			if (!goal || goal.id !== authority.id || goal.phase !== 'active') return undefined
+			if (this.confirmedByFor(goal) !== 'record') return undefined
+
+			const record = await read()
+			const claim = this.claims.get(goal.id)
+			this.claims.delete(goal.id)
+			const changedHere = (record?.changes.total ?? 0) > 0 || record?.changes.outsideKnownTools
+			if (!claim) {
+				if (changedHere) this.changed.add(goal.id)
+				return undefined
+			}
+
+			const decision = decideGoalConfirmation({
+				statement: claim.statement,
+				record,
+				refusals: this.refusalsFor(goal.id),
+				maxRefusals: this.maxRefusals,
+				earlierRoundsChanged: this.changed.has(goal.id),
+			})
+			if (changedHere) this.changed.add(goal.id)
+			if (decision.kind === 'refuse') {
+				this.refusals.set(goal.id, this.refusalsFor(goal.id) + 1)
+				return decision.note
+			}
+
+			const ref = { id: authority.id, revision: authority.revision }
+			try {
+				if (decision.ending === 'not-confirmed') {
+					const said = claim.reason ? ` The model said: ${claim.reason}` : ''
+					await this.options.store.blockGoal(authority.sessionId, authority.tenantId, ref, {
+						code: 'not-confirmed-by-record',
+						message: `The record says ${decision.sentence}.${said}`,
+					})
+				} else {
+					await this.options.store.completeGoal(authority.sessionId, authority.tenantId, ref)
+				}
+			} catch (error) {
+				// The person changed the goal while the model was answering; what they
+				// did stands, and nothing is said about an ending that did not happen.
+				if (error instanceof StaleGoalError) return undefined
+				throw error
+			}
+			this.endings.set(turnId, {
+				goalId: goal.id,
+				ending: decision.ending,
+				sentence: decision.sentence,
+				refusals: this.refusalsFor(goal.id),
+			})
+			this.refusals.delete(goal.id)
+			this.changed.delete(goal.id)
+			return undefined
+		}
+	}
+}

package/src/tools/goal/index.ts

@@ -5,6 +5,7 @@ import type { GoalRoundAuthority, SessionGoal } from '../../types/goal/index.js'
 import type { TurnId } from '../../types/ids/index.js'
 import type { ToolDefinition } from '../../types/tool/index.js'
 import { defineTool } from '../defineTool.js'
+import { type GoalConfirmation, NO_CHECK_REASON_CODE } from './confirmation.js'
 
 export const SESSION_GOAL_TOOL_NAMES = ['get_goal', 'update_goal'] as const
 export const MIN_GOAL_BLOCK_ROUND = 3
@@ -58,6 +59,7 @@ function authorityFor(
 export function buildSessionGoalTools(
 	store: SessionGoalStore,
 	resolveAuthority: ResolveGoalRoundAuthority,
+	options: { readonly confirmation?: GoalConfirmation } = {},
 ): ToolDefinition[] {
 	const getGoal = defineTool({
 		name: 'get_goal',
@@ -106,8 +108,42 @@ export function buildSessionGoalTools(
 		concurrencySafe: false,
 		async execute({ status, reasonCode, reason }, context) {
 			const authority = authorityFor(resolveAuthority, context.turnId)
-			await currentGoal(store, authority)
+			const current = await currentGoal(store, authority)
 			const ref = { id: authority.id, revision: authority.revision }
+			const confirmation = options.confirmation
+			if (confirmation && confirmation.confirmedByFor(current) === 'record') {
+				// The report is held until the model finishes its answer; the kernel then
+				// reads the record of the work and the goal ends as the record allows.
+				if (status === 'complete') {
+					confirmation.claim(
+						authority.id,
+						reasonCode === NO_CHECK_REASON_CODE ? 'no-check' : 'met',
+						reason,
+					)
+					return {
+						success: true,
+						output:
+							'Completion reported. This goal is confirmed by the record: when you finish your answer the kernel reads the record of the work done, and the goal ends as that record allows. Give your final answer now.',
+					}
+				}
+				if (
+					authority.round < MIN_GOAL_BLOCK_ROUND &&
+					confirmation.refusalsFor(authority.id) === 0
+				) {
+					throw new Error(
+						`A goal cannot be marked blocked before admitted round ${MIN_GOAL_BLOCK_ROUND}, unless the record has already sent it back once; this is round ${authority.round}.`,
+					)
+				}
+				if (!reasonCode || !reason) {
+					throw new TypeError('Blocked goal updates require reasonCode and reason.')
+				}
+				confirmation.claim(authority.id, 'could-not', reason)
+				return {
+					success: true,
+					output:
+						'Reported as not met. The goal ends as not confirmed when you finish your answer, and the record of the work is shown with your reason. Give your final answer now.',
+				}
+			}
 			if (status === 'complete') {
 				const goal = await store.completeGoal(authority.sessionId, authority.tenantId, ref)
 				return { success: true, output: 'Goal marked complete.', data: goal }