@namzu/sdk 61.4.0 → 62.1.0

package/src/learning/guidance.ts

@@ -0,0 +1,339 @@
+import { createHash } from 'node:crypto'
+import { readdir } from 'node:fs/promises'
+import { join } from 'node:path'
+import { isDeepStrictEqual } from 'node:util'
+import { z } from 'zod'
+import { DiskRecordStore } from '../store/kv/record-store.js'
+import { DiskRevisionRecordStore, revisionFileSegment } from '../store/kv/revision-record-store.js'
+import { defineSchema } from '../store/schema.js'
+import type { TenantId } from '../types/ids/index.js'
+import { asTenantId } from '../utils/id.js'
+import {
+	type LearningEvidence,
+	type LearningProfileUpdate,
+	type LearningSkillCandidate,
+	type LearningSkillEvaluation,
+	type LearningState,
+	freezeLearning,
+	learningEvidenceSchema,
+	learningSchema,
+	promoteLearningSkill,
+	restoreLearningSkill,
+	reviseLearningProfile,
+} from './skill.js'
+
+/**
+ * @experimental One immutable revision of the guidance a learning target has
+ * earned. `learning` is absent until the first profile change or activation.
+ */
+export interface LearningGuidanceState {
+	readonly tenantId: string
+	readonly agentKey: string
+	readonly revision: number
+	readonly learning?: LearningState
+}
+
+/** @experimental A competing writer advanced the guidance revision; read it again before retrying. */
+export class LearningGuidanceConflictError extends Error {
+	constructor() {
+		super('Learning guidance changed; read the current guidance before retrying.')
+		this.name = 'LearningGuidanceConflictError'
+	}
+}
+
+const guidanceSchema = z.object({
+	tenantId: z.string().uuid(),
+	agentKey: z.string().min(1).max(200),
+	revision: z.number().int().positive().safe(),
+	learning: learningSchema.optional(),
+})
+
+const guidanceRecordSchema = defineSchema({
+	kind: 'learning-guidance',
+	current: 1,
+	migrations: {},
+})
+
+/**
+ * The record format learning guidance was kept in before it had a store of its
+ * own. Its `kind` is the identifier stamped into those files, so it keeps its
+ * spelling; only the fields learning used are read from it.
+ */
+const earlierRecordSchema = defineSchema({
+	kind: 'resident-agenda',
+	current: 6,
+	migrations: {
+		1: (record) => record,
+		2: (record) => record,
+		3: (record) => record,
+		4: (record) => record,
+		5: (record) => record,
+	},
+})
+
+const earlierFieldsSchema = z.object({
+	tenantId: z.string().uuid(),
+	agentKey: z.string().min(1).max(200),
+	revision: z.number().int().positive().safe(),
+	learning: learningSchema.optional(),
+})
+
+/** Marker written beside the revisions once an earlier store has been carried over. */
+const ADOPTED_MARKER = 'adopted.json'
+const REVISION_FILE = /^([1-9][0-9]{0,15})\.json$/
+
+/** A key as one bounded path segment, the way the earlier store addressed it. */
+function keySegment(key: string): string {
+	const encoded = revisionFileSegment(key)
+	return encoded.length <= 255
+		? encoded
+		: `~sha256-${createHash('sha256').update(encoded).digest('hex')}`
+}
+
+/**
+ * Where guidance was kept before it had a store of its own, for one scope:
+ * `<root>/<tenant>/<key>/agenda`. Pass the result as `adoptFrom` to carry it over.
+ */
+export function earlierGuidanceDirectory(
+	root: string,
+	scope: { readonly tenantId: string; readonly agentKey: string },
+): string {
+	return join(root, asTenantId(scope.tenantId), keySegment(scope.agentKey), 'agenda')
+}
+
+/** @experimental Where a guidance store lives and what it may carry over on first use. */
+export interface DiskLearningGuidanceOptions {
+	/**
+	 * A directory holding guidance in the earlier record format
+	 * (see {@link earlierGuidanceDirectory}). On the first use of this store,
+	 * every revision found there is copied into it with its revision number, and
+	 * a marker is written beside them. The earlier files are only read, never
+	 * changed or removed, so an older version keeps working on them.
+	 */
+	readonly adoptFrom?: string
+}
+
+/**
+ * @experimental Revisioned, evaluated guidance for one tenant and one scope key,
+ * on a trusted local filesystem. Every change is an immutable revision published
+ * exclusively, so two processes cannot both commit the same one, and an older
+ * revision stays readable to roll one skill back.
+ */
+export class DiskLearningGuidance {
+	private readonly records = new DiskRevisionRecordStore<LearningGuidanceState>(
+		guidanceRecordSchema,
+		'learning guidance',
+		(record) => record.revision,
+	)
+	private readonly historyRecords = new DiskRecordStore<LearningGuidanceState>(guidanceRecordSchema)
+	private readonly location
+	private readonly tenantId: TenantId
+	private readonly agentKey: string
+	private readonly directory: string
+	private readonly adoptFrom: string | undefined
+	private adopting: Promise<void> | undefined
+
+	constructor(
+		directory: string,
+		scope: { tenantId: TenantId | string; agentKey: string },
+		options: DiskLearningGuidanceOptions = {},
+	) {
+		this.tenantId = asTenantId(scope.tenantId)
+		this.agentKey = z.string().min(1).max(200).parse(scope.agentKey)
+		this.directory = directory
+		this.adoptFrom = options.adoptFrom
+		this.location = {
+			legacyPath: join(directory, 'state.json'),
+			revisionsDir: join(directory, 'revisions'),
+			publishLegacyProjection: false,
+		}
+	}
+
+	private checked(record: LearningGuidanceState): LearningGuidanceState {
+		const state = guidanceSchema.parse(record)
+		if (state.tenantId !== this.tenantId || state.agentKey !== this.agentKey)
+			throw new Error('Guidance does not match the bound tenant and scope key.')
+		return Object.freeze({
+			...state,
+			...(state.learning ? { learning: freezeLearning(state.learning) } : {}),
+		})
+	}
+
+	/** Carry an earlier store over once per process, and once ever per directory. */
+	private ready(): Promise<void> {
+		if (!this.adoptFrom) return Promise.resolve()
+		this.adopting ??= this.adopt(this.adoptFrom).catch((error) => {
+			this.adopting = undefined
+			throw error
+		})
+		return this.adopting
+	}
+
+	private async adopt(from: string): Promise<void> {
+		const marker = new DiskRecordStore<unknown>(guidanceRecordSchema)
+		if ((await marker.read(join(this.directory, ADOPTED_MARKER))) !== null) return
+		const earlier = new DiskRecordStore<unknown>(earlierRecordSchema)
+		let names: string[]
+		try {
+			names = await readdir(join(from, 'revisions'))
+		} catch (error) {
+			if ((error as NodeJS.ErrnoException).code === 'ENOENT') return
+			throw error
+		}
+		const revisions = names
+			.flatMap((name) => {
+				const match = REVISION_FILE.exec(name)
+				return match ? [Number(match[1])] : []
+			})
+			.sort((a, b) => a - b)
+		if (!revisions.length) return
+		const head = revisions[revisions.length - 1] as number
+		if (revisions.length !== head)
+			throw new Error(
+				`Earlier guidance in ${from} has gaps between revisions 1 and ${head}; it was not carried over.`,
+			)
+		for (const revision of revisions) {
+			const current = await this.records.read(this.location)
+			if ((current?.revision ?? 0) >= revision) continue
+			const raw = await earlier.read(join(from, 'revisions', `${revision}.json`))
+			const fields = earlierFieldsSchema.parse(raw)
+			if (
+				fields.revision !== revision ||
+				fields.tenantId !== this.tenantId ||
+				fields.agentKey !== this.agentKey
+			)
+				throw new Error(
+					`Earlier guidance revision ${revision} in ${from} does not match this tenant and scope key; it was not carried over.`,
+				)
+			const record = this.checked({
+				tenantId: fields.tenantId,
+				agentKey: fields.agentKey,
+				revision,
+				...(fields.learning ? { learning: fields.learning } : {}),
+			})
+			try {
+				await this.records.transact(this.location, (latest) => {
+					if ((latest?.revision ?? 0) !== revision - 1) throw new LearningGuidanceConflictError()
+					return { record, result: undefined }
+				})
+			} catch (error) {
+				// A concurrent process carrying over the same revision wins identically.
+				const after = await this.records.read(this.location)
+				if ((after?.revision ?? 0) < revision) throw error
+			}
+		}
+		await marker.write(join(this.directory, ADOPTED_MARKER), {
+			from,
+			revisions: head,
+			adoptedAt: new Date().toISOString(),
+		})
+	}
+
+	async read(): Promise<LearningGuidanceState | null> {
+		await this.ready()
+		const record = await this.records.read(this.location)
+		return record === null ? null : this.checked(record)
+	}
+
+	/** One immutable revision, as it was committed. */
+	async readRevision(revision: number): Promise<LearningGuidanceState | null> {
+		z.number().int().positive().safe().parse(revision)
+		await this.ready()
+		const record = await this.historyRecords.read(
+			join(this.location.revisionsDir, `${revision}.json`),
+		)
+		if (record === null) return null
+		const state = this.checked(record)
+		if (state.revision !== revision)
+			throw new Error('Guidance revision filename and body disagree.')
+		return state
+	}
+
+	/** Create the empty first revision. A second creator gets a conflict. */
+	async create(): Promise<LearningGuidanceState> {
+		await this.ready()
+		const record = this.checked({
+			tenantId: this.tenantId,
+			agentKey: this.agentKey,
+			revision: 1,
+		})
+		return this.records.transact(this.location, (current) => {
+			if (current !== null) throw new LearningGuidanceConflictError()
+			return { record, result: record }
+		})
+	}
+
+	/** The current guidance, created empty when none exists yet. Safe to race. */
+	async open(): Promise<LearningGuidanceState> {
+		const existing = await this.read()
+		if (existing) return existing
+		try {
+			return await this.create()
+		} catch (error) {
+			const raced = await this.read()
+			if (!raced) throw error
+			return raced
+		}
+	}
+
+	private async learn(
+		expected: LearningGuidanceState,
+		learning: LearningState,
+	): Promise<LearningGuidanceState> {
+		await this.ready()
+		const snapshot = this.checked(expected)
+		return this.records.transact(this.location, (record) => {
+			if (record === null) throw new LearningGuidanceConflictError()
+			const current = this.checked(record)
+			if (current.revision !== snapshot.revision) throw new LearningGuidanceConflictError()
+			if (!isDeepStrictEqual(current.learning, snapshot.learning))
+				throw new LearningGuidanceConflictError()
+			const next = this.checked({ ...current, learning, revision: current.revision + 1 })
+			return { record: next, result: next }
+		})
+	}
+
+	/** Append a host-evidenced correction to identity or preferences. */
+	async updateProfile(
+		expected: LearningGuidanceState,
+		input: LearningProfileUpdate,
+	): Promise<LearningGuidanceState> {
+		const snapshot = this.checked(expected)
+		return this.learn(snapshot, reviseLearningProfile(snapshot.learning, input))
+	}
+
+	/** Bind evaluated guidance to the current learning version. */
+	async promoteSkill(
+		expected: LearningGuidanceState,
+		candidate: LearningSkillCandidate,
+		evaluation: LearningSkillEvaluation,
+		evidence: LearningEvidence,
+	): Promise<LearningGuidanceState> {
+		const snapshot = this.checked(expected)
+		return this.learn(
+			snapshot,
+			promoteLearningSkill(snapshot.learning, candidate, evaluation, evidence),
+		)
+	}
+
+	/** Restore one skill from an immutable earlier revision while keeping the current profile. */
+	async rollbackSkill(
+		expected: LearningGuidanceState,
+		name: string,
+		fromRevision: number,
+		evidence: LearningEvidence,
+	): Promise<LearningGuidanceState> {
+		const snapshot = this.checked(expected)
+		const checkedEvidence = learningEvidenceSchema.parse(evidence)
+		z.number().int().positive().safe().max(snapshot.revision).parse(fromRevision)
+		z.string()
+			.regex(/^[a-z0-9][a-z0-9_-]{0,63}$/)
+			.parse(name)
+		const historical = await this.readRevision(fromRevision)
+		if (!historical) throw new Error('Skill rollback revision is missing.')
+		return this.learn(
+			snapshot,
+			restoreLearningSkill(snapshot.learning, historical.learning, name, checkedEvidence),
+		)
+	}
+}

package/src/learning/skill.ts

@@ -119,11 +119,11 @@ export const learningSchema = z
 		)
 			context.addIssue({
 				code: z.ZodIssueCode.custom,
-				message: 'Invalid resident learning identity or content digest.',
+				message: 'Invalid learning identity or content digest.',
 			})
 	})
 
-/** @experimental Versioned behavioral overlay; the original resident mandate remains unchanged. */
+/** @experimental Versioned behavioral overlay; the original identity remains unchanged. */
 export interface LearningState {
 	readonly revision: number
 	readonly identity?: { readonly text: string; readonly evidence: LearningEvidence }
@@ -219,7 +219,7 @@ function base(current: LearningState | undefined, evidence: LearningEvidence): L
 	}
 }
 
-/** Internal pure profile transition; storage owns exact agenda CAS and idle admission. */
+/** Internal pure profile transition; storage owns the exact-revision check. */
 export function reviseLearningProfile(
 	current: LearningState | undefined,
 	input: LearningProfileUpdate,
@@ -306,7 +306,7 @@ export function promoteLearningSkill(
 			batch.candidate.length > 128 ||
 			batch.attributions.length > 128
 		)
-			throw new Error('Resident skill evaluation is bounded to 64 tasks per round.')
+			throw new Error('Skill evaluation is bounded to 64 tasks per round.')
 		// Recorded evidence must consistently identify success and complete measurements.
 		for (const trial of [...batch.baseline, ...batch.candidate]) {
 			if (
@@ -322,7 +322,7 @@ export function promoteLearningSkill(
 		protection,
 	)
 	if (review.decision !== 'accept')
-		throw new Error(`Resident skill promotion ${review.decision}: ${review.reason}`)
+		throw new Error(`Skill promotion ${review.decision}: ${review.reason}`)
 	const skill: LearnedSkill = {
 		...candidate,
 		hash,
@@ -358,7 +358,7 @@ export function restoreLearningSkill(
 ): LearningState {
 	name.parse(skillName)
 	if (!current?.skills.some((s) => s.name === skillName))
-		throw new Error('No active resident skill to roll back.')
+		throw new Error('No active skill to roll back.')
 	const next = base(current, evidenceFor(current, inputEvidence))
 	const previous = historical
 		? freezeLearning(historical).skills.find((s) => s.name === skillName)
@@ -398,7 +398,7 @@ export function projectLearning(
 	options: LearningProjectionOptions,
 ): LearningProjection {
 	if (!Number.isSafeInteger(options.maxChars) || options.maxChars < 0 || options.maxChars > 64_000)
-		throw new TypeError('Resident learning context requires maxChars between 0 and 64000.')
+		throw new TypeError('Learning context requires maxChars between 0 and 64000.')
 	const selected = z.array(name).max(16).parse(options.skillNames)
 	const purpose = z.enum(['task', 'exploration']).parse(options.purpose ?? 'task')
 	if (new Set(selected).size !== selected.length) throw new Error('Duplicate selected skill names.')

package/src/learning/store.ts

@@ -286,7 +286,7 @@ export class SqliteLearningStore {
 			row.project_id !== this.scope.projectId ||
 			row.agent_key !== this.scope.agentKey
 		)
-			throw new Error('Learning cycle does not belong to this tenant, project and resident.')
+			throw new Error('Learning cycle does not belong to this tenant, project and scope key.')
 		return row
 	}
 
@@ -524,7 +524,7 @@ export class SqliteLearningStore {
 					(event.data.tenantId !== this.scope.tenantId ||
 						event.data.agentKey !== this.scope.agentKey)
 				)
-					throw new Error('Learning start does not match the bound resident.')
+					throw new Error('Learning start does not match the bound scope key.')
 				const parent =
 					event.data.parentCycleId === undefined ? null : uuid.parse(event.data.parentCycleId)
 				if (parent && !this.owned(db, parent))
@@ -843,11 +843,10 @@ export async function runStoredLearningFromObservations(
 	options: LearningDiscoveryOptions,
 ): Promise<LearningDiscoveryResult> {
 	options.signal.throwIfAborted()
-	const agenda = await options.agenda.read()
-	if (!agenda || agenda.paused || agenda.pursuits.some((p) => p.state.phase === 'running'))
-		throw new Error('Learning discovery requires an unpaused agenda without running pursuits.')
+	const guidance = await options.guidance.read()
+	if (!guidance) throw new Error('Learning discovery requires existing learning guidance.')
 	const targets = options.evaluators.map((target) => {
-		const skill = agenda.learning?.skills.find((s) => s.name === target.skillName)
+		const skill = guidance.learning?.skills.find((s) => s.name === target.skillName)
 		return { ...target, baselineRevision: skill ? hashLearningSkill(skill) : 'none' }
 	})
 	const observation = await store.selectObservation(targets)

package/src/peers/client.ts

@@ -1,9 +1,8 @@
 /**
  * A client for one connection of `namzu-peer/1`: connect, write one request
  * line, read one response line, close. Mirrors the shape of this
- * repository's other local control clients (`queryRunner` in
- * `packages/cli/src/integrations/resident/runner-control.ts`,
- * `callEndpoint` in `packages/cli/src/schedule/daemon/endpoint.ts`): an
+ * repository's other local control clients (`callEndpoint` in
+ * `packages/cli/src/schedule/daemon/endpoint.ts`): an
  * authenticated response PROVES responsiveness, and its absence never proves
  * the peer is dead — only that this attempt could not reach it.
  *

package/src/peers/endpoint.ts

@@ -3,8 +3,7 @@
  * session, newline-delimited JSON framing, a closed op set (design §1.1,
  * §1.3). Mirrors the shape of this repository's other local control
  * endpoints (`startEndpoint` in
- * `packages/cli/src/schedule/daemon/endpoint.ts`, `createRunnerControlServer`
- * in `packages/cli/src/integrations/resident/runner-control.ts`): a total
+ * `packages/cli/src/schedule/daemon/endpoint.ts`): a total
  * read deadline per connection (not an inactivity timer a slow sender can
  * reset), a bounded connection count, and a destroyed socket rather than an
  * error response for anything malformed — request bytes and tokens are

package/src/peers/protocol.ts

@@ -36,6 +36,7 @@ export const DEFAULT_PEER_READ_DEADLINE_MS = 2_000
 /** Concurrent connections a `createPeerEndpoint` server accepts before refusing new ones. */
 export const MAX_PEER_CONNECTIONS = 16
 
+// 'resident' is no longer announced; it stays so an older peer's record still parses.
 export const PeerSessionKindSchema = z.enum(['tui', 'exec', 'resident', 'scheduled'])
 export type PeerSessionKind = z.infer<typeof PeerSessionKindSchema>
 

package/src/prompt/coding-agent-doctrine.ts

@@ -21,7 +21,7 @@
  * `CODING_AGENT_WORKING_DOCTRINE` names only the builtins and is meant for the
  * parent and for every delegated sub-agent, because a delegated task edits the
  * same repository under the same rules. `CODING_AGENT_DELEGATION_DOCTRINE`
- * names `task_create` and `Agent`, which a sub-agent does not have, and so is
+ * names `Agent` and speaks of the task list, which a sub-agent does not have, and so is
  * for the parent only. An adversarial review caught a draft ordering children
  * to plan with a tool they could not call; a rule about a tool the reader does
  * not have is not guidance, it is an instruction to fail.
@@ -38,6 +38,7 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 
 ### Delivering work
 - Act when you have enough information. Take established facts and the user's decisions as settled.
+- Begin editing once you know the first change, and refine as you go. If you stop before changing anything, the next step starts from the same code.
 - The requested scope is the deliverable: deliver it at the size and on the subject it was asked. Read ambiguity the way a careful colleague would; make the routine judgment calls yourself and check in only when different readings would produce materially different work.
 - Finish the whole task, not just the easy parts. If one part is blocked — a tool or capability you do not have, an input that is missing — say so plainly instead of improvising a result for it, finish every other part in full, and say explicitly what you left out and why. Scaling the work down is the user's call.
 - If you find a real problem with the task as stated, say so in a sentence or two, then keep going under a stated assumption. Reserve blocking questions for cases where proceeding under any assumption would be unsafe or would make the work useless if wrong.
@@ -59,6 +60,7 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 - Before editing, use the relevant file content already available from a successful read or write; if it is unavailable or may be stale, read the needed portion. Read additional surrounding code when needed to match its naming and idiom. Respect project instructions and tool-specific prerequisites even when they require a fresh read.
 - Prefer the dedicated tools over shell equivalents (\`read\` over \`cat\`, \`grep\` over a shell grep, \`glob\` over \`find\`, \`edit\` over \`sed -i\`, \`write\` over a shell redirect), because their structured inputs and focused results are easier to check. Use \`bash\` when the task needs a shell; permissions apply the same way.
 - Independent tool calls go in one response: reading three files, or running a grep and a glob, does not need three turns. Wait for a mutation to finish before an observation or another action that depends on it; runtime ordering and concurrency limits remain authoritative.
+- For a defect, reproduce it first with a small script or a failing test, and keep it. Make the change, then rerun that reproduction. Afterwards run the project's tests and its lint or format check, add tests for behaviour you introduced, and say where any throwaway file you made is. Say in your report what you ran and what you did not run.
 - Match verification to the task and its risk. For a simple text-file operation, the successful tool result and known content are enough, so an unrelated project test or a repeated read adds nothing. For code changes, run the relevant tests, typecheck or lint that would catch a mistake, and follow required project checks. Claim only the checks you ran.
 - Describe the state you leave the working tree in: say where scratch files are, and which files outside the request you touched.
 
@@ -74,11 +76,11 @@ export const CODING_AGENT_WORKING_DOCTRINE = `## How you work
 - Keep the final reply short and specific: what changed, what was verified, what is left.`
 
 /**
- * Parent-only: rules about `task_create` / `task_update` and `Agent`, which a
+ * Parent-only: rules about the task list and `Agent`, which a
  * delegated sub-agent does not have. See the module comment for the split.
  */
 export const CODING_AGENT_DELEGATION_DOCTRINE = `### Planning and delegating
-- For work of three or more steps — several files, several distinct stages, anything you would write a checklist for — open a task list with \`task_create\` and keep it current with \`task_update\`, marking each step done when it is done rather than at the end. Skip it for a single inspect-edit-test cycle or a two-step job: the list is for the user to follow, and a list of one or two items tells them nothing.
+- A task list is optional. For work of three or more distinct steps — several files, several separate stages — you may keep one: exactly one step marked in progress at a time, each marked done when it is done rather than at the end, and the list cleared away once everything is done. Do not make one for a single inspect-edit-test cycle or a two-step job; a list of one or two items tells the user nothing. Keeping a list is not progress on the task itself.
 - When the \`Agent\` tool is available, delegate independent work through it and give each delegation a short, specific description; the user watches those descriptions, not the prompts. Brief each sub-agent with four things: the objective; what is out of bounds; which tools and sources to use; and the shape of the reply you want, such as a short summary with a file path for anything long. A fresh sub-agent starts with none of your context and returns what you ask for.
 - When the \`Agent\` tool lists a \`fork\` type, use \`subagent_type: "fork"\` when a side task would fill your context with output you will not need again, such as an open-ended survey. A fork starts from this conversation under your own instructions, so its prompt is only the directive: what to do and where its scope ends, without the background. Never write or guess what a fork will find before its report arrives. A fork cannot start forks of its own.
 - When delegated agents finish, tell the user what each one found in your next message. Their results reach you and not the user, so a result you do not pass on stays unseen.

package/src/prompt/index.ts

@@ -23,7 +23,3 @@ export {
 	codingAgentDoctrineContribution,
 } from './coding-agent-doctrine.js'
 export type { CodingAgentDoctrineOptions } from './coding-agent-doctrine.js'
-export { createResidentStepContributions } from './resident-step.js'
-export type { ResidentStepPromptOptions } from './resident-step.js'
-export { createResidentStepContext } from './resident-learning.js'
-export type { ResidentStepContextOptions, ResidentStepContextBundle } from './resident-learning.js'

package/src/provider/fallback.ts

@@ -554,6 +554,13 @@ export function withProviderFallback(
 			const serving = members[cursor] ?? first
 			return serving.provider.supportsImageInputFor?.(serving.model ?? model) ?? true
 		},
+		// A chain takes a forced choice only if every member does: the request may
+		// be served by any of them, and the one that refuses would fail the step.
+		acceptsForcedToolChoiceFor: (model: string, thinking?: ThinkingConfig) =>
+			members.every(
+				(member) =>
+					member.provider.acceptsForcedToolChoiceFor?.(member.model ?? model, thinking) ?? true,
+			),
 		reasoningEffortLevelsFor: (model: string, thinking?: ThinkingConfig) =>
 			commonReasoningEffortLevels(members, model, thinking),
 		// Present on the chain wrapper for the same reason the menu method is:

package/src/provider/idle-timeout.ts

@@ -223,6 +223,14 @@ export function withStreamIdleTimeout(
 					supportsImageInputFor: (model: string) => provider.supportsImageInputFor?.(model) ?? true,
 				}
 			: {}),
+		...(provider.acceptsForcedToolChoiceFor
+			? {
+					acceptsForcedToolChoiceFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['acceptsForcedToolChoiceFor']>>[1],
+					) => provider.acceptsForcedToolChoiceFor?.(model, thinking) ?? true,
+				}
+			: {}),
 		...(provider.reasoningEffortLevelsFor
 			? {
 					reasoningEffortLevelsFor: (

package/src/provider/model-window-suffix.ts

@@ -18,6 +18,7 @@ const MODEL_FIRST_METHODS: ReadonlySet<string> = new Set([
 	'supportsImageInputFor',
 	'reasoningEffortLevelsFor',
 	'reasoningEffortDefaultFor',
+	'acceptsForcedToolChoiceFor',
 	'effortLevelsFor',
 	'resolveContextWindow',
 	'refusalFallbackFor',

package/src/provider/retry.ts

@@ -384,6 +384,14 @@ export function withProviderRetry(
 					supportsImageInputFor: (model: string) => provider.supportsImageInputFor?.(model) ?? true,
 				}
 			: {}),
+		...(provider.acceptsForcedToolChoiceFor
+			? {
+					acceptsForcedToolChoiceFor: (
+						model: string,
+						thinking?: Parameters<NonNullable<LLMProvider['acceptsForcedToolChoiceFor']>>[1],
+					) => provider.acceptsForcedToolChoiceFor?.(model, thinking) ?? true,
+				}
+			: {}),
 		...(provider.reasoningEffortLevelsFor
 			? {
 					reasoningEffortLevelsFor: (

package/src/provider/step-stopped.ts

@@ -0,0 +1,27 @@
+/**
+ * The reason a step is stopped on purpose, by the loop that is reading it.
+ *
+ * A step that has spent its whole reasoning allowance is cut short: the loop
+ * stops reading the stream and aborts the request it opened. That abort is the
+ * loop's own decision, not a caller's stop and not a transport failure, so it
+ * carries this class as its reason. A provider wrapper that sees an aborted
+ * request can tell the two apart with {@link isStepStopped} and must not retry
+ * it, fail over from it, or report it as an error.
+ */
+export class StepStopped extends Error {
+	override readonly name = 'StepStopped'
+
+	constructor() {
+		super('the step was stopped by the loop that was reading it')
+	}
+}
+
+/** Whether an abort reason, or an error that carries one, is a deliberate step stop. */
+export function isStepStopped(value: unknown): value is StepStopped {
+	return value instanceof StepStopped
+}
+
+/** Whether a request signal was aborted by a deliberate step stop. */
+export function stepWasStopped(signal: AbortSignal | undefined): boolean {
+	return signal?.aborted === true && isStepStopped(signal.reason)
+}

package/src/provider/token-budget.ts

@@ -6,6 +6,7 @@ import { ProviderError, classifyProviderError } from '../types/provider/errors.j
 import type { LLMProvider, StreamChunk } from '../types/provider/index.js'
 import { cancelCauseOf } from '../types/session/cancel-cause.js'
 import { isProviderRequestError } from './errors.js'
+import { isStepStopped } from './step-stopped.js'
 
 export class TokenBudgetAdmissionError extends ProviderError {
 	constructor() {
@@ -117,6 +118,7 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 				}
 				if (Object.keys(chunk.delta).length > 0) outputObserved = true
 				if (typeof chunk.delta.content === 'string') streamedChars += chunk.delta.content.length
+				streamedChars += chunk.delta.reasoning?.text?.length ?? 0
 				if (chunk.error) throw new Error(chunk.error)
 				yield chunk
 			}
@@ -161,10 +163,13 @@ export function withTokenBudget(provider: LLMProvider, budget: SessionTokenBudge
 				// because of work somebody chose to stop. The estimate can under-count
 				// what the provider billed for the part it never reported; a failure
 				// that was not a cancellation keeps its marker as before.
+				//
+				// A step the loop stopped on purpose (it reached its reasoning cap) is
+				// closed the same way: nobody chose to lose track of that spend.
 				if (
 					usage === undefined &&
 					signal?.aborted === true &&
-					cancelCauseOf(signal.reason) === 'user' &&
+					(cancelCauseOf(signal.reason) === 'user' || isStepStopped(signal.reason)) &&
 					!uncertainRetry
 				) {
 					const prompt = estimateMessagesTokens(params.messages)