@roj-ai/sdk 0.1.35 → 0.2.1

package/src/core/agents/agent.ts

@@ -9,8 +9,9 @@
 
 import z from 'zod/v4'
 import { DebounceCallback } from '~/core/agents/debounce.js'
-import type { AgentId } from '~/core/agents/schema.js'
-import type { AgentState, HandlerResult } from '~/core/agents/state.js'
+import { AgentId } from '~/core/agents/schema.js'
+import { agentWakeKey, type AgentWakeKind } from '~/core/wake-key.js'
+import type { AgentState, HandlerResult, ReasoningDetails, ThinkingBlocks } from '~/core/agents/state.js'
 import { agentEvents } from '~/core/agents/state.js'
 import { withSessionId } from '~/core/events/test-helpers.js'
 import type { FileStore } from '~/core/file-store/types.js'
@@ -43,12 +44,14 @@ import type { ToolDefinition } from '~/core/tools/definition.js'
 import type { ToolCall } from '~/core/tools/schema.js'
 import { ToolCallId } from '~/core/tools/schema.js'
 import { toolEvents } from '~/core/tools/state.js'
+import type { Scheduler } from '~/platform/scheduler.js'
 import { getAgentUnconsumedMailbox, selectMailboxState } from '~/plugins/mailbox/query.js'
 import { AGENT_BASE_BRIEFING } from '~/prompts/base.js'
 import { buildEnvironmentSection } from '~/prompts/builder.js'
 import { Err, Ok, type Result } from '~/lib/utils/result.js'
 import type { Logger } from '../../lib/logger/logger.js'
 import type { SessionContext } from '../sessions/context.js'
+import { isValidSessionId, SessionId } from '../sessions/schema.js'
 import type { SessionStore } from '../sessions/session-store.js'
 import type { SessionState } from '../sessions/state.js'
 import { resolveAgentOverrides } from '../sessions/state.js'
@@ -102,7 +105,7 @@ export interface AgentConfig<TInput = unknown> {
  */
 export interface AgentDependencies {
 	id: AgentId
-	sessionContext: SessionContext
+	getSessionContext: () => SessionContext
 	store: SessionStore
 	llmProvider: LLMProvider
 	/** Named provider instances, passed to InferenceContext for middleware routing */
@@ -141,7 +144,7 @@ export interface AgentDependencies {
 export class Agent {
 	readonly id: AgentId
 	private readonly config: AgentConfig
-	private readonly sessionContext: SessionContext
+	private readonly getSessionContext: () => SessionContext
 	private readonly store: SessionStore
 	private readonly logger: Logger
 	private readonly llmProvider: LLMProvider
@@ -159,20 +162,24 @@ export class Agent {
 	private tools: Map<string, ToolDefinition>
 
 	// Scheduler state (embedded)
-	private debounceTimer?: ReturnType<typeof setTimeout>
-	private errorRetryTimer?: ReturnType<typeof setTimeout>
+	/** Poll timer for the debounceCallback path only — see scheduleProcessing(). */
+	private debounceCheckTimer?: ReturnType<typeof setTimeout>
+	/** Whether a retry wake is armed. In-memory: a fresh process re-arms from replayed state. */
+	private errorRetryArmed = false
+	private releaseScheduledLease?: () => void
+	/** Host scheduler, resolved once — the platform never changes for a session. */
+	private scheduler?: Scheduler
 	private processing = false
 	private scheduled = false
 	private pendingReschedule = false
+	/** In-flight continue() calls, so disposal can drain a turn instead of racing it. */
+	private readonly inFlightContinues = new Set<Promise<void>>()
 	private readonly abortController = new AbortController()
 
-	/** Track conversation turn number for handler context */
-	private turnNumber = 0
-
 	constructor(deps: AgentDependencies) {
 		this.id = deps.id
 		this.config = deps.config
-		this.sessionContext = deps.sessionContext
+		this.getSessionContext = deps.getSessionContext
 		this.store = deps.store
 		this.logger = deps.logger
 		this.llmProvider = deps.llmProvider
@@ -186,12 +193,14 @@ export class Agent {
 		this.pluginMethodCaller = deps.pluginMethodCaller
 		this.scheduleCallback = deps.schedule
 		this.tools = this.buildToolsMap()
+	}
 
-		// Initialize turn number from conversation history
-		const state = this.state
-		if (state) {
-			this.turnNumber = state.conversationHistory.filter((m) => m.role === 'assistant').length
-		}
+	/**
+	 * Turn the agent is working on: committed turns plus the one in flight.
+	 * Read from persisted state so a reload or a compaction can't reset it.
+	 */
+	private get turnNumber(): number {
+		return (this.state?.turnNumber ?? 0) + 1
 	}
 
 	/**
@@ -221,13 +230,49 @@ export class Agent {
 	// Public API
 	// ============================================================================
 
+	/** Drop the scheduled lease. Idempotent — the release closure self-guards. */
+	private dropScheduledLease(): void {
+		this.releaseScheduledLease?.()
+		this.releaseScheduledLease = undefined
+	}
+
 	/**
 	 * Unified processing entry point - decides what to do next.
 	 * Safe to call multiple times; skips if already processing.
 	 */
-	async continue(): Promise<void> {
+	continue(): Promise<void> {
+		const pending = this.runContinue().finally(() => {
+			this.inFlightContinues.delete(pending)
+		})
+		this.inFlightContinues.add(pending)
+		return pending
+	}
+
+	/**
+	 * Await the turn that is currently running, if any — including work it starts
+	 * while draining. Never rejects: callers use it to drain before teardown, not
+	 * to observe processing errors.
+	 */
+	async waitForIdle(): Promise<void> {
+		while (this.inFlightContinues.size > 0) {
+			await Promise.allSettled([...this.inFlightContinues])
+		}
+	}
+
+	private async runContinue(): Promise<void> {
+		// Release before the guards: both early-return paths are reachable from a
+		// fired timer, and the lease would otherwise outlive the schedule forever.
+		// The retry lease is not touched here — it only ever exists inside the
+		// retry callback, which releases it itself.
+		this.dropScheduledLease()
 		if (this.processing) return
 		if (this.store.isClosed()) return
+		let releaseProcessingLease: (() => void) | undefined
+		try {
+			releaseProcessingLease = this.getSessionContext().runtimeActivity.acquire(`agent:${this.id}:processing`)
+		} catch {
+			return
+		}
 		this.processing = true
 		this.scheduled = false
 
@@ -317,6 +362,7 @@ export class Agent {
 				this.pendingReschedule = false
 				this.scheduleProcessing()
 			}
+			releaseProcessingLease()
 		}
 	}
 
@@ -327,82 +373,119 @@ export class Agent {
 	scheduleProcessing(): void {
 		if (this.scheduled) return
 		if (this.store.isClosed()) return
+		// After shutdown() a fresh schedule would outlive the drain and fire against
+		// a session that already cleared its agents and plugin contexts.
+		if (this.abortController.signal.aborted) return
 		if (this.processing) {
 			this.pendingReschedule = true
 			return
 		}
 
 		this.cancelSchedule()
+		try {
+			this.releaseScheduledLease = this.getSessionContext().runtimeActivity.acquire(`agent:${this.id}:scheduled`)
+		} catch {
+			return
+		}
 		this.scheduled = true
 
 		const agentState = this.state
-		if (!agentState) return
+		if (!agentState) {
+			this.cancelSchedule()
+			return
+		}
 
 		if (this.config.debounceCallback) {
-			// Callback-based debounce using recursive setTimeout
+			// Stays a plain timer: the poll re-enters with a closure and its own
+			// in-memory `scheduled` guard, neither of which a resumed wake can carry.
 			const checkInterval = this.config.checkIntervalMs ?? 100
 
 			const scheduleCheck = () => {
-				this.debounceTimer = setTimeout(async () => {
-					// Re-read state fresh each check — no stale data
-					const currentState = this.state
-					if (!currentState) {
-						this.cancelSchedule()
-						return
-					}
+				this.debounceCheckTimer = setTimeout(() => {
+					// A throw here (hasPluginPendingMessages, or the preset-supplied
+					// debounceCallback — user code) must not strand the scheduled lease.
+					void this.runDebounceCheck(scheduleCheck)
+				}, checkInterval)
+			}
 
-					// Guard: schedule could be cancelled between timer fire and here
-					if (!this.scheduled) return
+			scheduleCheck()
+		} else {
+			// Debounce by wake (default: 500ms) — nothing but the key is needed to resume.
+			this.armWake('debounce', this.config.debounceMs ?? 500)
+		}
+	}
 
-					const sessionState = this.store.getState()
-					const unconsumed = getUnconsumedMessages(sessionState, this.id)
-					const pendingToolResults = currentState.pendingToolResults
+	/**
+	 * Run the continuation a due wake stands for — the one entry point for a host,
+	 * whether this process armed the delay or an alarm held it across an eviction.
+	 */
+	async deliverWake(kind: AgentWakeKind): Promise<void> {
+		if (this.abortController.signal.aborted) return
 
-					// If no messages, no pending tool results, and no plugin pending, nothing to do
-					if (unconsumed.length === 0 && pendingToolResults.length === 0 && !this.hasPluginPendingMessages()) {
-						this.cancelSchedule()
-						return
-					}
+		switch (kind) {
+			case 'debounce':
+				// Not scheduleProcessing(): that arms a fresh delay and the turn never runs.
+				this.scheduled = false
+				await this.continue()
+				return
 
-					const oldestTimestamp = unconsumed.length > 0
-						? Math.min(...unconsumed.map((m) => m.timestamp))
-						: Date.now()
-					const oldestWaitingMs = Date.now() - oldestTimestamp
+			case 'retry':
+				this.errorRetryArmed = false
+				this.scheduleProcessing()
+				return
+		}
+	}
 
-					const decision = await this.config.debounceCallback!({
-						messages: unconsumed,
-						oldestWaitingMs,
-						totalPending: unconsumed.length,
-						pendingToolResults,
-					})
+	/** One debounce-callback check. Never rejects: on error it cancels the schedule. */
+	private async runDebounceCheck(scheduleNext: () => void): Promise<void> {
+		try {
+			// Re-read state fresh each check — no stale data
+			const currentState = this.state
+			if (!currentState) {
+				this.cancelSchedule()
+				return
+			}
 
-					// Re-check after async callback — schedule could be cancelled during await
-					if (!this.scheduled) return
+			// Guard: schedule could be cancelled between timer fire and here
+			if (!this.scheduled) return
 
-					if (decision === 'process_now') {
-						this.cancelSchedule()
-						this.continue().catch((err) => {
-							this.logger.error('Unhandled error in continue()', err instanceof Error ? err : undefined, { agentId: this.id })
-						})
-					} else {
-						// Callback said "wait" — schedule next check.
-						// Fresh state will be read on next iteration.
-						scheduleCheck()
-					}
-				}, checkInterval)
+			const sessionState = this.store.getState()
+			const unconsumed = getUnconsumedMessages(sessionState, this.id)
+			const pendingToolResults = currentState.pendingToolResults
+
+			// If no messages, no pending tool results, and no plugin pending, nothing to do
+			if (unconsumed.length === 0 && pendingToolResults.length === 0 && !this.hasPluginPendingMessages()) {
+				this.cancelSchedule()
+				return
 			}
 
-			scheduleCheck()
-		} else {
-			// Timer-based debounce (default: 500ms)
-			const debounceMs = this.config.debounceMs ?? 500
-			this.debounceTimer = setTimeout(() => {
-				this.scheduled = false
-				this.debounceTimer = undefined
+			const oldestTimestamp = unconsumed.length > 0
+				? Math.min(...unconsumed.map((m) => m.timestamp))
+				: Date.now()
+			const oldestWaitingMs = Date.now() - oldestTimestamp
+
+			const decision = await this.config.debounceCallback!({
+				messages: unconsumed,
+				oldestWaitingMs,
+				totalPending: unconsumed.length,
+				pendingToolResults,
+			})
+
+			// Re-check after async callback — schedule could be cancelled during await
+			if (!this.scheduled) return
+
+			if (decision === 'process_now') {
+				this.cancelSchedule()
 				this.continue().catch((err) => {
 					this.logger.error('Unhandled error in continue()', err instanceof Error ? err : undefined, { agentId: this.id })
 				})
-			}, debounceMs)
+			} else {
+				// Callback said "wait" — schedule next check. Fresh state next iteration.
+				scheduleNext()
+			}
+		} catch (err) {
+			this.logger.error('Debounce check failed', err instanceof Error ? err : undefined, { agentId: this.id })
+			this.cancelSchedule()
 		}
 	}
 
@@ -416,10 +499,8 @@ export class Agent {
 			// AbortError may be thrown synchronously by abort signal listeners
 		}
 		this.cancelSchedule()
-		if (this.errorRetryTimer) {
-			clearTimeout(this.errorRetryTimer)
-			this.errorRetryTimer = undefined
-		}
+		this.errorRetryArmed = false
+		this.cancelWake('retry')
 	}
 
 	/**
@@ -545,12 +626,16 @@ export class Agent {
 	 * remaining backoff and re-arms if it hasn't elapsed yet.
 	 */
 	private scheduleErrorRetry(delayMs: number): void {
-		if (this.errorRetryTimer) return
+		if (this.errorRetryArmed) return
 		if (this.store.isClosed()) return
-		this.errorRetryTimer = setTimeout(() => {
-			this.errorRetryTimer = undefined
-			this.scheduleProcessing()
-		}, delayMs)
+		// Nothing cancels a wake armed after shutdown(), and delivering it would
+		// reload a session this host has already torn down.
+		if (this.abortController.signal.aborted) return
+		this.errorRetryArmed = true
+		// The backoff itself is unleased: a provider that keeps failing would
+		// otherwise pin the runtime resident forever, and the preserved dequeue
+		// token is in the event log, so a rebuilt runtime still has the work.
+		this.armWake('retry', delayMs)
 	}
 
 	private static readonly MAX_INFERENCE_RETRIES = 3
@@ -572,8 +657,6 @@ export class Agent {
 		// Need either tool results or plugin messages to process
 		if (!hasToolResults && pluginDequeued.length === 0) return
 
-		this.turnNumber++
-
 		// 0. beforeInference handler - can skip LLM entirely or pause
 		const beforeResult = await this.executeBeforeInference(agentState)
 		if (beforeResult !== null) {
@@ -810,7 +893,7 @@ export class Agent {
 		if (afterResult !== null) {
 			if (afterResult.action === 'pause') {
 				// Commit the turn before pausing so pendingMessages move to conversationHistory.
-				await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics)
+				await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics, llmResponse.value.reasoningDetails, llmResponse.value.thinkingBlocks)
 				await this.consumeDequeuedTokens(pluginDequeued)
 				await this.emitHandlerPause(afterResult.reason)
 				return
@@ -830,8 +913,7 @@ export class Agent {
 						this.store.sessionId,
 						llmEvents.create('inference_retried', { agentId: this.id }),
 					))
-					// Retry inference - decrement turn number and recursively call with fresh state
-					this.turnNumber--
+					// Retry inference — the turn never committed, so it keeps its number.
 					const freshState = this.state
 					if (!freshState) return
 					await this.runInference(freshState, retryCount + 1)
@@ -844,7 +926,9 @@ export class Agent {
 
 		// 4d. Inference completed
 		// Tool calls will be executed in the next continue() cycle
-		await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics)
+		// Reasoning travels beside `response`, not inside it: an afterInference handler may
+		// rewrite the text, but the blocks stay the model's own and go back untouched.
+		await this.emitInferenceCompleted(response, llmCallId, llmResponse.value.metrics, llmResponse.value.reasoningDetails, llmResponse.value.thinkingBlocks)
 
 		// Consume dequeue tokens after the commit: a crash in the gap re-delivers the
 		// message on restart (at-least-once) instead of dropping it (consume-first
@@ -869,6 +953,8 @@ export class Agent {
 			cachedTokens?: number
 			cacheWriteTokens?: number
 		},
+		reasoningDetails?: ReasoningDetails,
+		thinkingBlocks?: ThinkingBlocks,
 	): Promise<void> {
 		await this.store.emit(withSessionId(
 			this.store.sessionId,
@@ -882,6 +968,8 @@ export class Agent {
 						name: tc.name,
 						input: tc.input,
 					})),
+					reasoningDetails,
+					thinkingBlocks,
 				},
 				metrics: metrics ?? {
 					promptTokens: 0,
@@ -903,12 +991,42 @@ export class Agent {
 	 * Cancel any scheduled processing.
 	 */
 	private cancelSchedule(): void {
-		if (this.debounceTimer) {
-			clearTimeout(this.debounceTimer)
-			this.debounceTimer = undefined
+		if (this.debounceCheckTimer) {
+			clearTimeout(this.debounceCheckTimer)
+			this.debounceCheckTimer = undefined
 		}
+		this.cancelWake('debounce')
 		this.scheduled = false
 		this.pendingReschedule = false
+		this.releaseScheduledLease?.()
+		this.releaseScheduledLease = undefined
+	}
+
+	/** The host scheduler, or null once the runtime is gone — a disposed session builds no context. */
+	private tryGetScheduler(): Scheduler | null {
+		if (this.scheduler) return this.scheduler
+		try {
+			this.scheduler = this.getSessionContext().platform.scheduler
+			return this.scheduler
+		} catch {
+			return null
+		}
+	}
+
+	/**
+	 * Arm a wake without awaiting the host: scheduleProcessing() and shutdown() are
+	 * synchronous, while a host may persist the wake asynchronously.
+	 */
+	private armWake(kind: AgentWakeKind, delayMs: number): void {
+		this.tryGetScheduler()?.wake(agentWakeKey(this.store.sessionId, this.id, kind), delayMs).catch((err: unknown) => {
+			this.logger.error('Failed to arm scheduler wake', err instanceof Error ? err : undefined, { agentId: this.id, kind })
+		})
+	}
+
+	private cancelWake(kind: AgentWakeKind): void {
+		this.tryGetScheduler()?.cancel(agentWakeKey(this.store.sessionId, this.id, kind)).catch((err: unknown) => {
+			this.logger.error('Failed to cancel scheduler wake', err instanceof Error ? err : undefined, { agentId: this.id, kind })
+		})
 	}
 
 	/**
@@ -1062,20 +1180,26 @@ export class Agent {
 	 * Build base AgentContext for handler/hook calls.
 	 */
 	private buildAgentContext(agentState: AgentState): AgentContext {
+		const sessionContext = this.getSessionContext()
 		return {
-			// SessionContext fields (refreshed from store for up-to-date state)
-			sessionId: this.sessionContext.sessionId,
+			// SessionContext fields are rebuilt for up-to-date state.
+			sessionId: sessionContext.sessionId,
 			sessionState: this.store.getState(),
-			sessionInput: this.sessionContext.sessionInput,
-			environment: this.sessionContext.environment,
-			llm: this.sessionContext.llm,
-			files: this.sessionContext.files,
-			eventStore: this.sessionContext.eventStore,
-			llmLogger: this.sessionContext.llmLogger,
-			platform: this.sessionContext.platform,
+			getSessionState: sessionContext.getSessionState,
+			sessionInput: sessionContext.sessionInput,
+			environment: sessionContext.environment,
+			llm: sessionContext.llm,
+			files: sessionContext.files,
+			eventStore: sessionContext.eventStore,
+			llmLogger: sessionContext.llmLogger,
+			platform: sessionContext.platform,
 			logger: this.logger,
-			emitEvent: this.sessionContext.emitEvent,
-			notify: this.sessionContext.notify,
+			runtimeActivity: sessionContext.runtimeActivity,
+			reserveSequence: sessionContext.reserveSequence,
+			reserveMailboxMessageSequence: sessionContext.reserveMailboxMessageSequence,
+			emitEvent: sessionContext.emitEvent,
+			emitEvents: sessionContext.emitEvents,
+			notify: sessionContext.notify,
 			// AgentContext fields
 			agentId: this.id,
 			agentState,

package/src/core/agents/config.ts

@@ -23,6 +23,12 @@ import type { ServiceConfig } from '~/plugins/services/schema.js'
  */
 export type UserCommunicationMode = 'tool' | 'xml' | 'both'
 
+/**
+ * Key holding the object refs behind `agents: string[]`. A symbol so it rides
+ * along on a spread or a clone without ever showing up in JSON or Object.keys.
+ */
+export const childAgentRefs = Symbol('roj.childAgentRefs')
+
 /**
  * Base configuration shared by all agent types.
  */
@@ -37,6 +43,8 @@ export interface BaseAgentConfig<TInput = unknown> {
 	tools?: ToolDefinition<any>[]
 	/** Names of agents this agent can spawn */
 	agents?: string[]
+	/** Object refs behind `agents`, set by defineAgent/createOrchestrator. */
+	readonly [childAgentRefs]?: readonly AnyAgentDefinition[]
 	/** Per-plugin agent-level configs */
 	plugins?: AgentPluginConfig[]
 	/** Debounce time in ms before processing mailbox. Default: 500ms */

package/src/core/agents/retry.ts

@@ -2,6 +2,7 @@ import type { LLMError } from '~/core/llm/provider.js'
 import type { Result } from '~/lib/utils/result.js'
 import { Err } from '~/lib/utils/result.js'
 import type { Logger } from '../../lib/logger/logger.js'
+import { sleep } from '~/lib/utils/sleep.js'
 
 // ============================================================================
 // Retry Options
@@ -26,7 +27,7 @@ export const DEFAULT_RETRY_OPTIONS: Required<RetryOptions> = {
 export interface WithRetryOptions<E> extends RetryOptions {
 	isRetryable: (error: E) => boolean
 	getRetryDelay?: (error: E) => number | undefined
-	/** Error to return when aborted before first attempt */
+	/** Error to return when the caller's signal aborts, whichever attempt that happens on. */
 	abortError?: E
 	logger?: Logger
 	context?: string
@@ -51,8 +52,13 @@ export async function withRetry<T, E>(
 
 	while (attempt < opts.maxAttempts) {
 		if (options.signal?.aborted) {
-			const error = lastError ?? options.abortError
-			if (error !== undefined) {
+			// abortError wins over lastError: the caller cancelled, and that is what
+			// the cancellation means regardless of how the previous attempt failed.
+			// Returning the previous failure instead makes a cancel indistinguishable
+			// from a genuine one — Agent.runInference then emits inference_failed and
+			// notifies the parent for what was really a shutdown.
+			const error = options.abortError ?? lastError
+			if (error !== null && error !== undefined) {
 				return Err(error)
 			}
 			break
@@ -71,12 +77,16 @@ export async function withRetry<T, E>(
 		}
 
 		lastError = result.error
+		attempt++
+
+		if (options.signal?.aborted) {
+			return Err(options.abortError ?? lastError)
+		}
 
-		if (!options.isRetryable(lastError)) {
+		if (attempt >= opts.maxAttempts || !options.isRetryable(lastError)) {
 			return result
 		}
 
-		attempt++
 		const delay = calculateDelay(attempt, lastError, opts, options.getRetryDelay)
 
 		if (options.logger) {
@@ -114,17 +124,6 @@ function calculateDelay<E>(
 	return Math.min(exponentialDelay + jitter, opts.maxDelayMs)
 }
 
-function sleep(ms: number, signal?: AbortSignal): Promise<void> {
-	if (signal?.aborted) return Promise.resolve()
-	return new Promise<void>((resolve) => {
-		const timer = setTimeout(resolve, ms)
-		signal?.addEventListener('abort', () => {
-			clearTimeout(timer)
-			resolve()
-		}, { once: true })
-	})
-}
-
 // ============================================================================
 // LLM-specific helpers
 // ============================================================================
@@ -158,7 +157,7 @@ export async function withLLMRetry<T>(
 		...options,
 		isRetryable: isRetryableLLMError,
 		getRetryDelay: getLLMRetryDelay,
-		abortError: { type: 'aborted', message: 'Aborted before first attempt' },
+		abortError: { type: 'aborted', message: 'Request was aborted' },
 		context: 'LLM inference',
 	})
 }

package/src/core/agents/state.ts

@@ -136,6 +136,28 @@ export interface UserLLMMessage {
 	cacheControl?: LLMMessageCacheControl
 }
 
+/**
+ * Provider chain-of-thought blocks, kept opaque (OpenRouter `reasoning_details`).
+ *
+ * The provider requires the exact sequence it produced to come back verbatim, so
+ * these are never parsed, reordered or normalized — only stored and echoed. The
+ * shape is provider- and model-specific and changes without notice; nothing in
+ * the SDK may depend on it.
+ */
+export type ReasoningDetails = unknown[]
+
+/**
+ * Anthropic extended-thinking blocks (`thinking` and `redacted_thinking`), kept opaque
+ * for the same reason as {@link ReasoningDetails}: each carries a `signature` the API
+ * verifies, so an edited block is worse than a missing one.
+ *
+ * Deliberately a separate field rather than sharing `reasoningDetails`. A session can
+ * change model mid-conversation, so one field would eventually put Anthropic-shaped
+ * blocks in front of OpenRouter or the reverse. Two fields make that case degrade to
+ * "absent", which both providers accept, instead of "wrong shape", which neither does.
+ */
+export type ThinkingBlocks = unknown[]
+
 /**
  * Assistant message - LLM response.
  */
@@ -143,6 +165,10 @@ export interface AssistantLLMMessage {
 	role: 'assistant'
 	content: string
 	toolCalls?: ToolCall[]
+	/** Reasoning blocks to echo back on later requests, so the model keeps its chain of thought across tool calls. */
+	reasoningDetails?: ReasoningDetails
+	/** Anthropic thinking blocks to replay on later requests. Required by the API during tool use. */
+	thinkingBlocks?: ThinkingBlocks
 	/** Marks this message as a prompt cache breakpoint. */
 	cacheControl?: LLMMessageCacheControl
 }
@@ -210,6 +236,8 @@ export interface AgentState {
 	typedInput?: unknown
 	/** Whether onStart handler has been executed (for first-run initialization) */
 	onStartCalled?: boolean
+	/** Inference turns committed so far — persisted, so compaction can't erase it. */
+	turnNumber?: number
 	/** Reason for pause (set when status is 'paused') */
 	pauseReason?: AgentPauseReason
 	/** Human-readable pause message */

package/src/core/context/state.ts

@@ -56,6 +56,10 @@ export const compactedConversationMessageSchema: z4.ZodType<LLMMessage> = z4.dis
 			name: z4.string(),
 			input: z4.unknown(),
 		})).optional(),
+		/** Opaque provider reasoning blocks — retained turns keep them, see ReasoningDetails. */
+		reasoningDetails: z4.array(z4.unknown()).optional(),
+		/** Anthropic thinking blocks — same. */
+		thinkingBlocks: z4.array(z4.unknown()).optional(),
 		cacheControl: cacheControlSchema.optional(),
 	}),
 	z4.object({