@namzu/sdk 27.0.0 → 28.0.0

package/src/agents/PipelineAgent.ts

@@ -1,3 +1,31 @@
+/**
+ * A developer-authored step list, and deliberately not a model-authored
+ * one.
+ *
+ * This distinction has been attributed to a `packages/sdk/src/agents/
+ * AGENTS.md` that does not exist, so it is written here instead. The
+ * proposal it answers is a model that emits an orchestration SCRIPT --
+ * `agent()`, `parallel()`, `pipeline()` as globals -- executed in an
+ * isolate, so that control flow between steps costs no model turns.
+ *
+ * The saving is real and this class already realises most of it: the steps
+ * below run with zero model turns between them, and `SupervisorAgent`
+ * delegates without one. What a script would add is orchestration a
+ * developer did not anticipate, invented at runtime -- which is also the
+ * case where a wrong one is hardest to review before it runs.
+ *
+ * The blocking question is the trust boundary, not the value. `bash` from
+ * a model is mediated by `packages/sandbox` because code from a model is
+ * untrusted; a model-authored script is the same input through another
+ * door, and a strictly more powerful one, since it can call back into the
+ * agent surface. Running it in-process would leave the kernel's one clear
+ * confinement boundary covering the weaker case and not the stronger. So
+ * an isolate is mandatory rather than an optimisation, and the capability
+ * costs a second execution surface to secure, audit and version.
+ *
+ * That is the bar a reopen has to clear.
+ */
+
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
 import type {
 	AgentInput,
@@ -10,22 +38,26 @@ import type {
 import type { RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
 import { toErrorMessage } from '../utils/error.js'
+import type { Logger } from '../utils/logger.js'
 import { AbstractAgent } from './AbstractAgent.js'
 
 export class PipelineAgent extends AbstractAgent<PipelineAgentConfig, PipelineAgentResult> {
 	readonly type = 'pipeline' as const
 
-	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>) {
-		super({
-			...metadata,
-			type: 'pipeline',
-			capabilities: {
-				supportsTools: false,
-				supportsStreaming: false,
-				supportsConcurrency: false,
-				supportsSubAgents: false,
+	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: 'pipeline',
+				capabilities: {
+					supportsTools: false,
+					supportsStreaming: false,
+					supportsConcurrency: false,
+					supportsSubAgents: false,
+				},
 			},
-		})
+			log,
+		)
 	}
 
 	/**
@@ -54,6 +86,7 @@ export class PipelineAgent extends AbstractAgent<PipelineAgentConfig, PipelineAg
 	): Promise<PipelineAgentResult> {
 		const startTime = Date.now()
 		const runId = this.createRunId()
+		this.bindRun(runId, config.logger)
 		const stepResults: PipelineStepResult[] = []
 		const previousResults = new Map<string, unknown>()
 		let completedSteps = 0
@@ -122,8 +155,9 @@ export class PipelineAgent extends AbstractAgent<PipelineAgentConfig, PipelineAg
 					try {
 						await step.rollback(currentInput, context)
 					} catch (rollbackErr) {
-						this.log.error(`Rollback failed for step "${step.name}"`, {
-							error: toErrorMessage(rollbackErr),
+						this.log.error('Rollback failed for a step', {
+							'namzu.pipeline.step_name': step.name,
+							'exception.message': toErrorMessage(rollbackErr),
 						})
 					}
 				}

package/src/agents/ReactiveAgent.ts

@@ -7,22 +7,26 @@ import type {
 } from '../types/agent/index.js'
 import type { AssistantMessage } from '../types/message/index.js'
 import type { RunEventListener } from '../types/run/index.js'
+import type { Logger } from '../utils/logger.js'
 import { AbstractAgent } from './AbstractAgent.js'
 
 export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAgentResult> {
 	readonly type = 'reactive' as const
 
-	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>) {
-		super({
-			...metadata,
-			type: 'reactive',
-			capabilities: {
-				supportsTools: true,
-				supportsStreaming: true,
-				supportsConcurrency: false,
-				supportsSubAgents: false,
+	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: 'reactive',
+				capabilities: {
+					supportsTools: true,
+					supportsStreaming: true,
+					supportsConcurrency: false,
+					supportsSubAgents: false,
+				},
 			},
-		})
+			log,
+		)
 	}
 
 	/**
@@ -50,10 +54,12 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 		listener?: RunEventListener,
 	): Promise<ReactiveAgentResult> {
 		const startTime = Date.now()
+		const runId = this.createRunId()
+		this.bindRun(runId, config.logger)
 
-		if (!config.sessionId || !config.threadId || !config.projectId || !config.tenantId) {
+		if (!config.sessionId || !config.topicId || !config.projectId || !config.tenantId) {
 			throw new Error(
-				'ReactiveAgent requires sessionId, threadId, projectId, and tenantId in config (session-hierarchy.md §12.1).',
+				'ReactiveAgent requires sessionId, topicId, projectId, and tenantId in config (session-hierarchy.md §12.1).',
 			)
 		}
 
@@ -66,6 +72,7 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 				provider: config.provider,
 				tools: config.tools,
 				...(config.verificationGate ? { verificationGate: config.verificationGate } : {}),
+				...(config.authorizationGate ? { authorizationGate: config.authorizationGate } : {}),
 				...(config.sandboxProvider ? { sandboxProvider: config.sandboxProvider } : {}),
 				// Working-memory / compaction seam (optional; absent => unchanged run path).
 				...(config.compactionConfig ? { compactionConfig: config.compactionConfig } : {}),
@@ -98,6 +105,11 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 				...(config.stopWhen ? { stopWhen: config.stopWhen } : {}),
 				...(config.onStepFinish ? { onStepFinish: config.onStepFinish } : {}),
 				...(config.prepareStep ? { prepareStep: config.prepareStep } : {}),
+				...(config.beforeStep ? { beforeStep: config.beforeStep } : {}),
+				...(config.allowedTools ? { allowedTools: [...config.allowedTools] } : {}),
+				...(config.deniedTools ? { deniedTools: [...config.deniedTools] } : {}),
+				...(config.inboundMessages ? { inboundMessages: config.inboundMessages } : {}),
+				...(config.steering ? { steering: config.steering } : {}),
 				...(config.structuredOutput ? { structuredOutput: config.structuredOutput } : {}),
 				...(config.inputGuardrails ? { inputGuardrails: config.inputGuardrails } : {}),
 				...(config.outputGuardrails ? { outputGuardrails: config.outputGuardrails } : {}),
@@ -113,6 +125,7 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 					costLimitUsd: config.costLimitUsd,
 					permissionMode: config.permissionMode,
 					env: config.env,
+					logger: this.log,
 					// Hand-listed, so anything not named here is dropped in silence.
 					// That is how both of these came to be unreachable from every
 					// entry point except the raw kernel one.
@@ -123,9 +136,10 @@ export class ReactiveAgent extends AbstractAgent<ReactiveAgentConfig, ReactiveAg
 				agentName: this.metadata.name,
 				workingDirectory: input.workingDirectory,
 				sessionId: config.sessionId,
-				threadId: config.threadId,
+				topicId: config.topicId,
 				projectId: config.projectId,
 				tenantId: config.tenantId,
+				runId,
 				parentRunId: config.parentRunId,
 				depth: config.depth,
 				contextLevel: config.contextLevel,

package/src/agents/RouterAgent.ts

@@ -1,5 +1,5 @@
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
-import { collect } from '../provider/collect.js'
+import { collectChatCompletion } from '../provider/collect-chat-completion.js'
 import { FallbackResolver } from '../runtime/decision/fallback.js'
 import { DecisionParser } from '../runtime/decision/parser.js'
 import type {
@@ -15,23 +15,26 @@ import { deriveChildState } from '../types/invocation/index.js'
 import { createSystemMessage, createUserMessage } from '../types/message/index.js'
 import type { RunEventListener } from '../types/run/index.js'
 import { ZERO_COST } from '../utils/cost.js'
-import { getRootLogger } from '../utils/logger.js'
+import type { Logger } from '../utils/logger.js'
 import { AbstractAgent } from './AbstractAgent.js'
 
 export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentResult> {
 	readonly type = 'router' as const
 
-	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>) {
-		super({
-			...metadata,
-			type: 'router',
-			capabilities: {
-				supportsTools: false,
-				supportsStreaming: true,
-				supportsConcurrency: false,
-				supportsSubAgents: true,
+	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: 'router',
+				capabilities: {
+					supportsTools: false,
+					supportsStreaming: true,
+					supportsConcurrency: false,
+					supportsSubAgents: true,
+				},
 			},
-		})
+			log,
+		)
 	}
 
 	/**
@@ -60,6 +63,7 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 	): Promise<RouterAgentResult> {
 		const startTime = Date.now()
 		const runId = this.createRunId()
+		this.bindRun(runId, config.logger)
 
 		await this.emitEvent({ type: 'run_started', runId }, listener)
 
@@ -146,7 +150,12 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 	}
 
 	private async route(input: AgentInput, config: RouterAgentConfig): Promise<RoutingDecision> {
-		const log = getRootLogger().child({ component: 'RouterAgent', agent: this.metadata.name })
+		// `this.log`, not a fresh `getRootLogger()` child — bound by `bindRun` in
+		// `runExclusive` before this is called, so a routing warning below
+		// carries the SAME `namzu.run.id` as the run it is routing. The old
+		// independent construction here is the exact bug LOG-10's acceptance
+		// criterion names: a route() log line with no run id at all.
+		const log = this.log
 
 		const validAgentIds = config.routes.map((r) => r.agentId)
 		const fallbackAgentId = config.fallbackAgentId ?? config.routes[0]?.agentId ?? ''
@@ -203,7 +212,7 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 
 		for (let attempt = 0; attempt < maxRetries; attempt++) {
 			try {
-				const response = await collect(
+				const response = await collectChatCompletion(
 					config.provider.chatStream({
 						model: config.model,
 						messages: [createSystemMessage(prompt), createUserMessage(userContent)],
@@ -227,9 +236,10 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 				}
 
 				if (parseResult.ok && parseResult.source === 'fallback') {
-					log.warn(`Routing attempt ${attempt + 1} fell back`, {
-						reason: parseResult.reason,
-						decision: parseResult.decision,
+					log.warn('Routing attempt fell back', {
+						'namzu.router.attempt': attempt + 1,
+						'namzu.agents.reason': parseResult.reason,
+						'namzu.agents.decision': parseResult.decision,
 					})
 
 					if (attempt === maxRetries - 1) {
@@ -246,16 +256,18 @@ export class RouterAgent extends AbstractAgent<RouterAgentConfig, RouterAgentRes
 				}
 
 				if (!parseResult.ok) {
-					log.warn(`Routing attempt ${attempt + 1} failed to parse`, {
-						error: parseResult.error,
+					log.warn('Routing attempt failed to parse', {
+						'namzu.router.attempt': attempt + 1,
+						'exception.message': parseResult.error,
 					})
 					if (attempt === maxRetries - 1) {
 						break
 					}
 				}
 			} catch (err) {
-				log.warn(`Routing LLM call failed on attempt ${attempt + 1}`, {
-					error: String(err),
+				log.warn('Routing LLM call failed', {
+					'namzu.router.attempt': attempt + 1,
+					'exception.message': String(err),
 				})
 				if (attempt === maxRetries - 1) {
 					break

package/src/agents/SupervisorAgent.ts

@@ -1,11 +1,10 @@
 import { EMPTY_TOKEN_USAGE } from '../constants/limits.js'
-import { CompletionInbox } from '../gateway/completion-inbox.js'
-import { LocalTaskGateway } from '../gateway/local.js'
 import { ToolNameCollisionError, ToolRegistry } from '../registry/tool/execute.js'
 import { drainQuery } from '../runtime/query/index.js'
 import { PendingAnswers, QuestionParkBinding } from '../runtime/query/question-park.js'
+import { CompletionInbox } from '../scheduler/completion-inbox.js'
+import { LocalTaskScheduler } from '../scheduler/local.js'
 import { buildCoordinatorTools } from '../tools/coordinator/index.js'
-import type { TaskGateway, TaskHandle } from '../types/agent/gateway.js'
 import type {
 	AgentInput,
 	AgentMetadata,
@@ -13,12 +12,15 @@ import type {
 	SupervisorAgentConfig,
 	SupervisorAgentResult,
 } from '../types/agent/index.js'
+import type { TaskHandle, TaskScheduler } from '../types/agent/scheduler.js'
 import type { AgentTaskContext } from '../types/agent/task.js'
-import type { AgentId, RunId } from '../types/ids/index.js'
+import type { RunId } from '../types/ids/index.js'
 import { deriveChildState } from '../types/invocation/index.js'
 import type { RunEventListener } from '../types/run/index.js'
 import type { ActorRef } from '../types/session/actor.js'
 import { ZERO_COST } from '../utils/cost.js'
+import type { Logger } from '../utils/logger.js'
+import { pickRenamed } from '../utils/renamed-field.js'
 import { AbstractAgent } from './AbstractAgent.js'
 
 /**
@@ -65,17 +67,20 @@ export function countCompletedTasks(taskResults: readonly AgentTaskResult[]): nu
 export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, SupervisorAgentResult> {
 	readonly type = 'supervisor' as const
 
-	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>) {
-		super({
-			...metadata,
-			type: 'supervisor',
-			capabilities: {
-				supportsTools: true,
-				supportsStreaming: true,
-				supportsConcurrency: true,
-				supportsSubAgents: true,
+	constructor(metadata: Omit<AgentMetadata, 'type' | 'capabilities'>, log?: Logger) {
+		super(
+			{
+				...metadata,
+				type: 'supervisor',
+				capabilities: {
+					supportsTools: true,
+					supportsStreaming: true,
+					supportsConcurrency: true,
+					supportsSubAgents: true,
+				},
 			},
-		})
+			log,
+		)
 	}
 
 	/**
@@ -104,26 +109,38 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 	): Promise<SupervisorAgentResult> {
 		const startTime = Date.now()
 		const runId = this.createRunId()
+		this.bindRun(runId, config.logger)
 
-		if (!config.sessionId || !config.threadId || !config.projectId || !config.tenantId) {
+		if (!config.sessionId || !config.topicId || !config.projectId || !config.tenantId) {
 			throw new Error(
-				'SupervisorAgent requires sessionId, threadId, projectId, and tenantId in config (session-hierarchy.md §12.1).',
+				'SupervisorAgent requires sessionId, topicId, projectId, and tenantId in config (session-hierarchy.md §12.1).',
 			)
 		}
 		const sessionId = config.sessionId
-		const threadId = config.threadId
+		const topicId = config.topicId
 		const projectId = config.projectId
 		const tenantId = config.tenantId
 
 		const parentActor: ActorRef = {
 			kind: 'agent',
-			agentId: this.metadata.id as AgentId,
+			agentId: this.metadata.id,
 			tenantId,
 		}
 
-		let gateway: TaskGateway
-		if (config.gateway) {
-			gateway = config.gateway
+		// One resolve for the two spellings. Read at each of the three sites
+		// instead, a host that set only `scheduler` would get a working one
+		// on one path and `undefined` on another — a half-migration that
+		// fails silently, which is worse than not renaming the field.
+		const configuredScheduler = pickRenamed(
+			'gateway',
+			config.gateway,
+			'scheduler',
+			config.scheduler,
+		)
+
+		let gateway: TaskScheduler
+		if (configuredScheduler) {
+			gateway = configuredScheduler
 		} else if (config.agentManager) {
 			const mergedFactoryOptions = config.factoryOptions
 				? {
@@ -153,7 +170,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				// human and the workers it launched approved themselves.
 				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
 				tenantId,
-				threadId,
+				topicId,
 				sessionId,
 				projectId,
 				parentActor,
@@ -161,13 +178,17 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 			// The only hop between the config and the gateway's policy. Omit it
 			// and the field is settable, documented, and read by nothing —
 			// which is exactly the state it was in before.
-			gateway = new LocalTaskGateway(config.agentManager, taskContext, listener, input, {
+			gateway = new LocalTaskScheduler(config.agentManager, taskContext, listener, input, {
 				...(config.siblingFailurePolicy
 					? { siblingFailurePolicy: config.siblingFailurePolicy }
 					: {}),
+				log: this.log,
 			})
 		} else {
-			throw new Error("SupervisorAgentConfig requires either 'gateway' or 'agentManager'")
+			// Names `scheduler`, not `gateway`. An error message is a piece of
+			// documentation delivered at the worst moment, and one that names
+			// a field being retired teaches the name on its way out.
+			throw new Error("SupervisorAgentConfig requires either 'scheduler' or 'agentManager'")
 		}
 
 		let planManagerRef: import('../manager/plan/lifecycle.js').PlanManager | undefined
@@ -186,7 +207,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 		//
 		// It attaches through `onTaskCompleted`, which every gateway already
 		// implements, so a host gateway needs no change to take part.
-		const completionInbox = new CompletionInbox()
+		const completionInbox = new CompletionInbox(this.log)
 		completionInbox.attach(gateway)
 
 		// From here to the return in a try/finally, so the listener is released
@@ -215,6 +236,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 				...(config.resumeHandler ? { resumeHandler: config.resumeHandler } : {}),
 				questionParks,
 				pendingAnswers,
+				...(config.onPlanApproved ? { onPlanApproved: config.onPlanApproved } : {}),
 			})
 
 			const tools = new ToolRegistry()
@@ -294,6 +316,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 						maxIterations: config.maxIterations,
 						temperature: config.temperature,
 						env: config.env,
+						logger: this.log,
 						// See ReactiveAgent: a hand-listed literal drops what nobody
 						// remembered to add, and reports nothing when it does.
 						...(config.thinking ? { thinking: config.thinking } : {}),
@@ -313,7 +336,7 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					messages: input.messages,
 					signal: input.signal,
 					sessionId,
-					threadId,
+					topicId,
 					projectId,
 					tenantId,
 					runId,
@@ -341,7 +364,9 @@ export class SupervisorAgent extends AbstractAgent<SupervisorAgentConfig, Superv
 					// use — which is the shape of defect this file has already been
 					// corrected for twice.
 					...(config.steering ? { steering: config.steering } : {}),
+					...(config.inboundMessages ? { inboundMessages: config.inboundMessages } : {}),
 					...(config.verificationGate ? { verificationGate: config.verificationGate } : {}),
+					...(config.authorizationGate ? { authorizationGate: config.authorizationGate } : {}),
 					// The one hop between the config and the tool. `drainQuery`
 					// registers `structured_output` from this and the loop
 					// captures it, so the kernel never cared which archetype it

package/src/agents/handle.ts

@@ -0,0 +1,149 @@
+import type { SteeringChannel } from '../runtime/query/steering.js'
+import type { TopicStateStore } from '../store/topic/state.js'
+import { NamzuError } from '../types/errors/index.js'
+import type { TenantId, TopicId } from '../types/ids/index.js'
+import type { Message } from '../types/message/index.js'
+
+/**
+ * The object a host holds between runs.
+ *
+ * There was none. A host could not ask whether the agent was running, and
+ * had nowhere to put "when you next run, start with this" — so it either
+ * held a steer until it observed a run starting, or carried the text itself
+ * and passed it manually on the next `run()` call.
+ *
+ * Two delivery targets, each with a stated lifetime, and no silent third
+ * state. `steer` reaches the run that is happening; `queueForNextRun`
+ * reaches the one that has not started. `steer` on an idle handle THROWS
+ * rather than accepting into a queue nothing will read — that refusal is
+ * the design, because the alternative is a host believing it redirected an
+ * agent that was not listening.
+ */
+
+/**
+ * Whether a run is in flight, as this handle sees it.
+ *
+ * NOT `AgentStatus` — that name is taken by a deprecated alias of
+ * `RunExecutionStatus` whose own test records that it never typed an agent
+ * and is being removed in the next major. Reusing it here would silently
+ * change what a consumer's `AgentStatus` MEANS rather than failing their
+ * build, which is the worse of the two outcomes and the one a deprecation
+ * window exists to avoid.
+ */
+export type AgentHandleStatus = 'idle' | 'running'
+
+/** A steer aimed at an agent that is not running. */
+export class AgentNotRunningError extends NamzuError {
+	constructor() {
+		super({
+			code: 'invalid_config',
+			message:
+				'steer() needs a run in flight — this agent is idle. Use queueForNextRun() to leave a message for the next one.',
+			details: {},
+			retryable: false,
+		})
+		this.name = 'AgentNotRunningError'
+	}
+}
+
+export interface AgentHandle {
+	readonly status: AgentHandleStatus
+	/**
+	 * Hand guidance to the run happening now.
+	 *
+	 * Reaches the model at the next turn boundary whether or not a tool is
+	 * in flight — the channel rides a settled tool result when there is one,
+	 * and the loop delivers the remainder otherwise.
+	 */
+	steer(text: string): void
+	/** Leave a message for the run that has not started yet. */
+	queueForNextRun(message: Message): Promise<void>
+}
+
+export interface AgentHandleOptions {
+	readonly steering: SteeringChannel
+	/** Where a queued message is persisted. Absent means it cannot be. */
+	readonly topicStateStore?: TopicStateStore
+	readonly topicId: TopicId
+	readonly tenantId: TenantId
+	/** Live, not captured — the status has to be true when it is asked. */
+	readonly isRunning: () => boolean
+}
+
+/**
+ * A host's handle on one agent.
+ *
+ * `status` is a function call rather than a stored boolean, because a
+ * stored one is only as current as whoever remembered to update it — and
+ * the whole value of this object is answering a question at the moment it
+ * is asked.
+ */
+export function createAgentHandle(options: AgentHandleOptions): AgentHandle {
+	return {
+		get status(): AgentHandleStatus {
+			return options.isRunning() ? 'running' : 'idle'
+		},
+
+		steer(text: string): void {
+			// Refused, not rerouted. Quietly forwarding to `queueForNextRun`
+			// would be a host asking to redirect what is happening now and
+			// getting a message delivered minutes later to a different run —
+			// which is worse than an error, because nothing says it happened.
+			if (!options.isRunning()) throw new AgentNotRunningError()
+			options.steering.steer(text)
+		},
+
+		async queueForNextRun(message: Message): Promise<void> {
+			if (!options.topicStateStore) {
+				throw new NamzuError({
+					code: 'invalid_config',
+					message:
+						'queueForNextRun() needs a topic state store; this handle was built without one, so there is nowhere to leave the message.',
+					details: { topicId: options.topicId },
+					retryable: false,
+				})
+			}
+			await appendQueuedMessage(options.topicStateStore, options.topicId, options.tenantId, message)
+		},
+	}
+}
+
+/**
+ * Add a message to the topic's next-run queue, under compare-and-set.
+ *
+ * Read-modify-write against the record's revision, so two hosts queueing
+ * for one conversation cannot silently drop each other's message — the
+ * loser gets the store's stale-revision error and can retry with what it
+ * now sees.
+ */
+export async function appendQueuedMessage(
+	store: TopicStateStore,
+	topicId: TopicId,
+	tenantId: TenantId,
+	message: Message,
+): Promise<void> {
+	const state = await store.getState(topicId, tenantId)
+	await store.setQueuedMessages(topicId, tenantId, [...(state?.queuedMessages ?? []), message], {
+		revision: state?.revision ?? 0,
+	})
+}
+
+/**
+ * Take whatever was queued for this topic, leaving the queue empty.
+ *
+ * Cleared as it is read, in the same compare-and-set write. A queue that
+ * was read and cleared separately would re-deliver on a crash between the
+ * two, and "start with this" arriving twice is a different instruction from
+ * the one that was left.
+ */
+export async function drainQueuedMessages(
+	store: TopicStateStore,
+	topicId: TopicId,
+	tenantId: TenantId,
+): Promise<readonly Message[]> {
+	const state = await store.getState(topicId, tenantId)
+	const queued = state?.queuedMessages ?? []
+	if (queued.length === 0) return []
+	await store.setQueuedMessages(topicId, tenantId, [], { revision: state?.revision ?? 0 })
+	return queued
+}