@namzu/sdk 38.1.0 → 38.2.1

package/src/manager/resident/outbox.ts

@@ -0,0 +1,307 @@
+import { randomUUID } from 'node:crypto'
+import { z } from 'zod'
+import type { ResidentAgendaState } from './agenda.js'
+import { ResidentConflictError } from './store.js'
+
+const time = z.number().int().nonnegative().safe().max(8_640_000_000_000_000)
+const label = z.string().trim().min(1).max(256)
+
+export const residentMessageInputSchema = z.object({
+	id: z.string().uuid(),
+	pursuitId: z.string().uuid(),
+	destination: label,
+	body: z
+		.string()
+		.min(1)
+		.max(8_000)
+		.refine((value) => value.trim().length > 0),
+	notBefore: time,
+})
+
+/** @experimental Host-approved content and an opaque destination route, never credentials. */
+export type ResidentMessageInput = Readonly<z.infer<typeof residentMessageInputSchema>>
+
+export const residentOutboxMessageSchema = residentMessageInputSchema
+	.extend({
+		tenantId: z.string().uuid(),
+		agentKey: z.string().min(1).max(200),
+		sourceClaimId: z.string().uuid().nullable(),
+		revision: z.number().int().positive().safe(),
+		attempts: z.number().int().nonnegative().safe(),
+		phase: z.enum(['pending', 'sending', 'acknowledged', 'cancelled']),
+		claimId: z.string().uuid().nullable(),
+		nextAttemptAt: time.nullable(),
+		receiptId: label.nullable(),
+		acknowledgedAt: time.nullable(),
+		lastReason: z.string().trim().min(1).max(1_000).nullable(),
+	})
+	.superRefine((message, context) => {
+		if (
+			(message.phase === 'sending') !== (message.claimId !== null) ||
+			(message.phase === 'pending') !== (message.nextAttemptAt !== null) ||
+			(message.phase === 'acknowledged') !== (message.receiptId !== null) ||
+			(message.phase === 'acknowledged') !== (message.acknowledgedAt !== null) ||
+			(message.nextAttemptAt !== null && message.nextAttemptAt < message.notBefore) ||
+			(message.phase !== 'pending' && message.attempts === 0)
+		)
+			context.addIssue({ code: z.ZodIssueCode.custom, message: 'Invalid outbox lifecycle.' })
+	})
+
+/** @experimental Acknowledgment proves transport acceptance, not human reading. */
+export type ResidentOutboxMessage = Readonly<z.infer<typeof residentOutboxMessageSchema>>
+
+export const residentDeliveryOutcomeSchema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('acknowledged'), receiptId: label }),
+	z.object({
+		kind: z.literal('not-accepted'),
+		retryAt: time.nullable(),
+		reason: z.string().trim().min(1).max(1_000),
+	}),
+])
+
+/** @experimental Retry only with evidence of non-acceptance; null retryAt ends delivery. */
+export type ResidentDeliveryOutcome = Readonly<z.infer<typeof residentDeliveryOutcomeSchema>>
+
+/** @experimental Atomic admission and exact-claim settlement, without automatic claim expiry. */
+export interface ResidentOutboxStore {
+	read(): Promise<ResidentAgendaState | null>
+	claimMessage(
+		expected: ResidentAgendaState,
+		id: string,
+		now: number,
+	): Promise<ResidentOutboxMessage>
+	settleMessage(
+		expected: ResidentOutboxMessage,
+		outcome: ResidentDeliveryOutcome,
+		now: number,
+	): Promise<ResidentOutboxMessage>
+}
+
+/** @experimental A synchronous host policy, evaluated before claiming and again before sending. */
+export type ResidentDeliveryGate = (
+	message: ResidentOutboxMessage,
+	now: number,
+) =>
+	| { readonly allow: true }
+	| {
+			readonly allow: false
+			readonly nextCheckAt: number | null
+			readonly reason: string
+	  }
+
+/** @experimental Bind an authorized route; forward message.id as the stable idempotency key. */
+export type ResidentMessageTransport = (
+	message: ResidentOutboxMessage,
+	signal: AbortSignal,
+) => Promise<ResidentDeliveryOutcome>
+
+/** @experimental One dispatch admission, with no model invocation, polling or implicit retries. */
+export interface ResidentDeliveryOptions {
+	readonly signal: AbortSignal
+	readonly gate: ResidentDeliveryGate
+	readonly now?: () => number
+}
+
+/** @experimental An idle result never asserts a message reached its destination. */
+export type ResidentDeliveryResult =
+	| { readonly status: 'settled'; readonly message: ResidentOutboxMessage }
+	| {
+			readonly status: 'idle'
+			readonly reason: 'paused' | 'unresolved' | 'empty' | 'not-due' | 'window' | 'contended'
+			readonly nextCheckAt: number | null
+	  }
+
+/** Internal pure enqueue used in the same revision transaction as pursuit settlement. */
+export function appendResidentMessage(
+	state: ResidentAgendaState,
+	input: ResidentMessageInput,
+	sourceClaimId: string | null = null,
+): readonly ResidentOutboxMessage[] {
+	const checked = residentMessageInputSchema.parse(input)
+	if (!state.pursuits.some((p) => p.id === checked.pursuitId))
+		throw new Error('Outbox message references an unknown pursuit.')
+	const messages = state.outbox ?? []
+	const existing = messages.find((message) => message.id === checked.id)
+	if (existing) {
+		if (
+			existing.pursuitId !== checked.pursuitId ||
+			existing.destination !== checked.destination ||
+			existing.body !== checked.body ||
+			existing.notBefore !== checked.notBefore ||
+			existing.sourceClaimId !== sourceClaimId
+		)
+			throw new Error('Outbox message ID already names a different immutable intent.')
+		return messages
+	}
+	if (messages.length >= 128) throw new Error('Resident outbox capacity reached (128 intents).')
+	return [
+		...messages,
+		Object.freeze(
+			residentOutboxMessageSchema.parse({
+				...checked,
+				tenantId: state.tenantId,
+				agentKey: state.agentKey,
+				sourceClaimId,
+				revision: 1,
+				attempts: 0,
+				phase: 'pending',
+				claimId: null,
+				nextAttemptAt: checked.notBefore,
+				receiptId: null,
+				acknowledgedAt: null,
+				lastReason: null,
+			}),
+		),
+	]
+}
+
+/** Internal exact-message transition; agenda storage owns exclusive admission. */
+export function claimResidentOutboxMessage(
+	message: ResidentOutboxMessage,
+	now: number,
+): ResidentOutboxMessage {
+	time.parse(now)
+	if (message.phase !== 'pending' || message.nextAttemptAt === null || message.nextAttemptAt > now)
+		throw new ResidentConflictError()
+	return Object.freeze(
+		residentOutboxMessageSchema.parse({
+			...message,
+			revision: message.revision + 1,
+			attempts: message.attempts + 1,
+			phase: 'sending',
+			claimId: randomUUID(),
+			nextAttemptAt: null,
+		}),
+	)
+}
+
+/** Internal settlement; unknown failures deliberately have no transition. */
+export function settleResidentOutboxMessage(
+	message: ResidentOutboxMessage,
+	outcome: ResidentDeliveryOutcome,
+	now: number,
+): ResidentOutboxMessage {
+	time.parse(now)
+	const checked = residentDeliveryOutcomeSchema.parse(outcome)
+	if (message.phase !== 'sending' || message.claimId === null) throw new ResidentConflictError()
+	if (checked.kind === 'not-accepted' && checked.retryAt !== null && checked.retryAt <= now)
+		throw new TypeError('A delivery retry must be scheduled in the future.')
+	return Object.freeze(
+		residentOutboxMessageSchema.parse({
+			...message,
+			revision: message.revision + 1,
+			claimId: null,
+			...(checked.kind === 'acknowledged'
+				? { phase: 'acknowledged', receiptId: checked.receiptId, acknowledgedAt: now }
+				: {
+						phase: checked.retryAt === null ? 'cancelled' : 'pending',
+						nextAttemptAt: checked.retryAt,
+						lastReason: checked.reason,
+					}),
+		}),
+	)
+}
+
+function admission(gate: ResidentDeliveryGate, message: ResidentOutboxMessage, now: number) {
+	const result = gate(message, now)
+	if (result.allow === true) return result
+	if (
+		result.allow !== false ||
+		typeof result.reason !== 'string' ||
+		!result.reason.trim() ||
+		result.reason.trim().length > 1_000
+	)
+		throw new TypeError('Invalid resident delivery gate result.')
+	if (result.nextCheckAt !== null) {
+		time.parse(result.nextCheckAt)
+		if (result.nextCheckAt <= now) throw new TypeError('Delivery gate must defer into the future.')
+	}
+	return result
+}
+
+/**
+ * @experimental Persist one send claim before calling a host-owned transport.
+ * Throws, malformed outcomes and cancellation keep the claim unresolved. Stop
+ * old executors and inspect effects before explicit settleMessage reconciliation.
+ */
+export async function deliverResidentMessage(
+	store: ResidentOutboxStore,
+	transport: ResidentMessageTransport,
+	options: ResidentDeliveryOptions,
+): Promise<ResidentDeliveryResult> {
+	const { signal, gate } = options
+	const clock = options.now ?? Date.now
+	const now = () => time.parse(clock())
+	signal.throwIfAborted()
+	const state = await store.read()
+	signal.throwIfAborted()
+	if (!state) throw new Error('Create the resident agenda before delivering messages.')
+	const idle = (
+		reason: Extract<ResidentDeliveryResult, { status: 'idle' }>['reason'],
+		nextCheckAt: number | null = null,
+	): ResidentDeliveryResult => ({ status: 'idle', reason, nextCheckAt })
+	if (state.paused) return idle('paused')
+	const messages = state.outbox ?? []
+	if (messages.some((message) => message.phase === 'sending')) return idle('unresolved')
+	const pending = messages.filter((message) => message.phase === 'pending')
+	if (!pending.length) return idle('empty')
+	let nextCheckAt: number | null = null
+	let gated = false
+	const at = now()
+	for (const message of pending.sort(
+		(a, b) => (a.nextAttemptAt ?? 0) - (b.nextAttemptAt ?? 0) || a.id.localeCompare(b.id),
+	)) {
+		if (message.nextAttemptAt !== null && message.nextAttemptAt > at) {
+			nextCheckAt = Math.min(nextCheckAt ?? Number.POSITIVE_INFINITY, message.nextAttemptAt)
+			continue
+		}
+		const permission = admission(gate, message, at)
+		signal.throwIfAborted()
+		if (!permission.allow) {
+			gated = true
+			if (permission.nextCheckAt !== null)
+				nextCheckAt = Math.min(nextCheckAt ?? Number.POSITIVE_INFINITY, permission.nextCheckAt)
+			continue
+		}
+		let claimed: ResidentOutboxMessage
+		try {
+			claimed = await store.claimMessage(state, message.id, now())
+		} catch (error) {
+			if (error instanceof ResidentConflictError) return idle('contended')
+			throw error
+		}
+		signal.throwIfAborted()
+		const fresh = await store.read()
+		signal.throwIfAborted()
+		const current = fresh?.outbox?.find((item) => item.id === claimed.id)
+		if (!current || current.revision !== claimed.revision || current.claimId !== claimed.claimId)
+			return idle('contended')
+		// A pause or closing window during admission must not start the transport.
+		const checkedAt = now()
+		const permissionNow = fresh?.paused
+			? {
+					allow: false as const,
+					nextCheckAt: checkedAt + 1,
+					reason: 'Resident agenda paused before send.',
+				}
+			: admission(gate, claimed, checkedAt)
+		if (!permissionNow.allow) {
+			// Transport has not been entered: scheduling another check has no remote effect.
+			await store.settleMessage(
+				claimed,
+				{
+					kind: 'not-accepted',
+					retryAt: permissionNow.nextCheckAt ?? checkedAt + 1,
+					reason: permissionNow.reason,
+				},
+				checkedAt,
+			)
+			return idle(fresh?.paused ? 'paused' : 'window', permissionNow.nextCheckAt)
+		}
+		signal.throwIfAborted()
+		const outcome = await transport(claimed, signal)
+		signal.throwIfAborted()
+		return { status: 'settled', message: await store.settleMessage(claimed, outcome, now()) }
+	}
+	return idle(gated ? 'window' : 'not-due', nextCheckAt)
+}

package/src/manager/resident/proposal.ts

@@ -0,0 +1,105 @@
+import { z } from 'zod'
+import type { ResidentAgendaState } from './agenda.js'
+
+const identifier = z.string().uuid()
+const revision = z.number().int().positive().safe()
+const domain = z
+	.string()
+	.min(1)
+	.max(120)
+	.refine((value) => value.trim().length > 0, 'A proposal domain must contain text.')
+const reason = z.string().trim().min(1).max(1_000)
+const evidenceKey = z.string().trim().min(1).max(256)
+
+export const residentProposalSchema = z.object({
+	id: identifier,
+	parentId: identifier,
+	parentRevision: revision,
+	domain,
+	objective: z.string().trim().min(1).max(8_000),
+	reason,
+	evidenceKey,
+})
+
+export const residentProposalLimitsSchema = z.object({
+	domains: z.array(domain).min(1),
+	maxChildrenPerParent: z.number().int().min(1).max(8),
+	maxDepth: z.number().int().min(1).max(4),
+})
+
+/** @experimental An inert subgoal proposal; creating it grants no execution authority. */
+export interface ResidentProposal {
+	readonly id: string
+	readonly parentId: string
+	readonly parentRevision: number
+	readonly domain: string
+	readonly objective: string
+	readonly reason: string
+	readonly evidenceKey: string
+}
+
+/** @experimental Host-approved routing domains and finite subgoal admission bounds. */
+export interface ResidentProposalLimits {
+	readonly domains: readonly string[]
+	readonly maxChildrenPerParent: number
+	readonly maxDepth: number
+}
+
+/** Persisted provenance shared with the agenda's schema validation. */
+export const residentProposalOriginSchema = z.object({
+	proposalId: identifier,
+	parentId: identifier,
+	parentRevision: revision,
+	domain,
+	reason,
+	evidenceKey,
+	depth: z.number().int().min(1).max(4),
+})
+
+/** @experimental Host-admitted ancestry and evidence for a resident subgoal. */
+export type ResidentProposalOrigin = Readonly<z.infer<typeof residentProposalOriginSchema>>
+
+/**
+ * @experimental Pure validation against one agenda snapshot. The host must
+ * atomically bind this snapshot to admission. Domains are routing metadata;
+ * this does not prove an objective fits its domain or authorize any tools.
+ */
+export function validateResidentProposal(
+	agenda: ResidentAgendaState,
+	input: ResidentProposal,
+	limits: ResidentProposalLimits,
+): ResidentProposalOrigin {
+	const proposal = residentProposalSchema.parse(input)
+	const policy = residentProposalLimitsSchema.parse(limits)
+	if (agenda.paused) throw new Error('A paused agenda cannot admit resident proposals.')
+	if (agenda.pursuits.length >= 32) throw new Error('Resident agenda pursuit bound reached.')
+	if (agenda.pursuits.some((pursuit) => pursuit.origin?.proposalId === proposal.id))
+		throw new Error('Resident proposal has already been admitted.')
+	const parent = agenda.pursuits.find((pursuit) => pursuit.id === proposal.parentId)
+	if (!parent) throw new Error('Unknown resident proposal parent.')
+	if (parent.state.revision !== proposal.parentRevision)
+		throw new Error('Resident proposal parent revision is stale.')
+	if (parent.state.phase !== 'waiting' && parent.state.phase !== 'complete')
+		throw new Error('Resident proposal parent must be waiting or complete.')
+	if (!policy.domains.includes(proposal.domain))
+		throw new Error('Resident proposal domain is not host-approved.')
+	if (
+		agenda.pursuits.filter((pursuit) => pursuit.origin?.parentId === parent.id).length +
+			(parent.retiredChildren ?? 0) >=
+		policy.maxChildrenPerParent
+	)
+		throw new Error('Resident proposal parent child bound reached.')
+	const depth = (parent.origin?.depth ?? 0) + 1
+	if (depth > policy.maxDepth) throw new Error('Resident proposal depth bound reached.')
+	return Object.freeze(
+		residentProposalOriginSchema.parse({
+			proposalId: proposal.id,
+			parentId: proposal.parentId,
+			parentRevision: proposal.parentRevision,
+			domain: proposal.domain,
+			reason: proposal.reason,
+			evidenceKey: proposal.evidenceKey,
+			depth,
+		}),
+	)
+}

package/src/manager/resident/store.ts

@@ -0,0 +1,229 @@
+import { createHash, randomUUID } from 'node:crypto'
+import { join } from 'node:path'
+import { z } from 'zod'
+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'
+
+const text = z.string().trim().min(1).max(8_000)
+const time = z.number().int().nonnegative().safe()
+export const residentDecisionSchema = z.discriminatedUnion('kind', [
+	z.object({ kind: z.literal('wait'), summary: text, wakeAt: time.nullable() }),
+	z.object({ kind: z.literal('complete'), summary: text }),
+	z.object({ kind: z.literal('blocked'), summary: text }),
+])
+
+/** @experimental One bounded step's durable disposition; silence is not completion. */
+export type ResidentDecision = z.infer<typeof residentDecisionSchema>
+
+export const residentStateSchema = z
+	.object({
+		tenantId: z.string().uuid(),
+		agentKey: z.string().min(1).max(200),
+		pursuitId: z.string().uuid().optional(),
+		identity: text,
+		objective: text,
+		revision: z.number().int().positive().safe(),
+		stepsAdmitted: time,
+		phase: z.enum(['waiting', 'running', 'complete', 'blocked']),
+		wakeAt: time.nullable(),
+		reason: text,
+		summary: text.nullable(),
+		claimId: z.string().uuid().nullable(),
+	})
+	.superRefine((state, context) => {
+		if ((state.phase === 'running') !== (state.claimId !== null)) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'Running state requires a claim.',
+			})
+		}
+		if (state.phase !== 'waiting' && state.wakeAt !== null) {
+			context.addIssue({
+				code: z.ZodIssueCode.custom,
+				message: 'Only waiting state may have a wake time.',
+			})
+		}
+	})
+
+/** @experimental Persisted identity and one pursuit, independent of a conversation. */
+export type ResidentState = Readonly<z.infer<typeof residentStateSchema>>
+
+/** Bounded addressing for local resident state. Stored scope is still validated. */
+export function residentKeySegment(key: string): string {
+	const encoded = revisionFileSegment(key)
+	return encoded.length <= 255
+		? encoded
+		: `~sha256-${createHash('sha256').update(encoded).digest('hex')}`
+}
+
+/** @experimental Minimal atomic contract needed to execute an existing pursuit. */
+export type ResidentExecutionStore = Pick<ResidentStore, 'read' | 'claim' | 'settle'>
+
+/** @experimental Backends must atomically compare revisions and publish admission before work. */
+export interface ResidentStore {
+	read(): Promise<ResidentState | null>
+	create(identity: string, objective: string): Promise<ResidentState>
+	claim(expected: ResidentState, now: number): Promise<ResidentState>
+	settle(expected: ResidentState, decision: ResidentDecision, now: number): Promise<ResidentState>
+	wake(expected: ResidentState, reason: string, now: number): Promise<ResidentState>
+}
+
+/** A competing owner advanced this resident's immutable revision. */
+export class ResidentConflictError extends Error {
+	constructor() {
+		super('Resident state changed; read the current state before retrying.')
+		this.name = 'ResidentConflictError'
+	}
+}
+
+/**
+ * @experimental Local-filesystem state for one tenant/agent key and one pursuit.
+ * A running claim never expires automatically: a crashed step may have effects.
+ * Uses exclusive immutable revision publication, not a read/rename lock.
+ */
+export class DiskResidentStore implements ResidentStore {
+	private readonly records = new DiskRevisionRecordStore<ResidentState>(
+		defineSchema({ kind: 'resident', current: 1, migrations: {} }),
+		'resident store',
+		(record) => record.revision,
+	)
+	private readonly location
+	private readonly tenantId: TenantId
+	private readonly agentKey: string
+
+	constructor(root: string, scope: { tenantId: TenantId; agentKey: string }) {
+		this.tenantId = asTenantId(scope.tenantId)
+		this.agentKey = z.string().min(1).max(200).parse(scope.agentKey)
+		const directory = join(root, this.tenantId, residentKeySegment(this.agentKey))
+		this.location = {
+			legacyPath: join(directory, 'state.json'),
+			revisionsDir: join(directory, 'revisions'),
+			publishLegacyProjection: false,
+		}
+	}
+
+	private checked(record: ResidentState): ResidentState {
+		const state = residentStateSchema.parse(record)
+		if (
+			state.pursuitId !== undefined ||
+			state.tenantId !== this.tenantId ||
+			state.agentKey !== this.agentKey
+		) {
+			throw new Error('Resident record does not match the bound tenant and agent.')
+		}
+		return Object.freeze(state)
+	}
+
+	async read(): Promise<ResidentState | null> {
+		const state = await this.records.read(this.location)
+		return state === null ? null : this.checked(state)
+	}
+
+	async create(identity: string, objective: string): Promise<ResidentState> {
+		const initial = this.checked({
+			tenantId: this.tenantId,
+			agentKey: this.agentKey,
+			identity,
+			objective,
+			revision: 1,
+			stepsAdmitted: 0,
+			phase: 'waiting',
+			wakeAt: 0,
+			reason: 'Initial pursuit',
+			summary: null,
+			claimId: null,
+		})
+		return this.records.transact(this.location, (current) => {
+			if (current !== null) throw new ResidentConflictError()
+			return { record: initial, result: initial }
+		})
+	}
+
+	private async change(
+		expected: ResidentState,
+		mutate: (current: ResidentState) => ResidentState,
+	): Promise<ResidentState> {
+		this.checked(expected)
+		return this.records.transact(this.location, (record) => {
+			if (record === null) throw new ResidentConflictError()
+			const current = this.checked(record)
+			if (current.revision !== expected.revision || current.claimId !== expected.claimId) {
+				throw new ResidentConflictError()
+			}
+			const next = this.checked({
+				...mutate(current),
+				revision: current.revision + 1,
+			})
+			return { record: next, result: next }
+		})
+	}
+
+	/** Persist admission before invoking a model, tool or developer callback. */
+	async claim(expected: ResidentState, now: number): Promise<ResidentState> {
+		return this.change(expected, (state) => claimResidentState(state, now))
+	}
+
+	/** Only the exact admitted revision may settle; late owners cannot overwrite recovery. */
+	async settle(
+		expected: ResidentState,
+		decision: ResidentDecision,
+		now: number,
+	): Promise<ResidentState> {
+		return this.change(expected, (state) => settleResidentState(state, decision, now))
+	}
+
+	/** Host-supplied new evidence can wake a waiting pursuit; terminal work stays terminal. */
+	async wake(expected: ResidentState, reason: string, now: number): Promise<ResidentState> {
+		return this.change(expected, (state) => wakeResidentState(state, reason, now))
+	}
+}
+
+/** Internal transitions shared by single-pursuit and whole-agent admission. */
+export function claimResidentState(state: ResidentState, now: number): ResidentState {
+	time.parse(now)
+	if (state.phase !== 'waiting' || state.wakeAt === null || state.wakeAt > now)
+		throw new Error('Resident is not due.')
+	return {
+		...state,
+		phase: 'running',
+		wakeAt: null,
+		claimId: randomUUID(),
+		stepsAdmitted: state.stepsAdmitted + 1,
+	}
+}
+
+export function settleResidentState(
+	state: ResidentState,
+	decision: ResidentDecision,
+	now: number,
+): ResidentState {
+	time.parse(now)
+	const outcome = residentDecisionSchema.parse(decision)
+	if (outcome.kind === 'wait' && outcome.wakeAt !== null && outcome.wakeAt <= now)
+		throw new Error('A scheduled continuation must be in the future.')
+	if (state.phase !== 'running') throw new Error('Resident has no admitted step to settle.')
+	return {
+		...state,
+		phase: outcome.kind === 'wait' ? 'waiting' : outcome.kind,
+		wakeAt: outcome.kind === 'wait' ? outcome.wakeAt : null,
+		summary: outcome.summary,
+		reason: 'Scheduled continuation',
+		claimId: null,
+	}
+}
+
+export function wakeResidentState(
+	state: ResidentState,
+	reason: string,
+	now: number,
+): ResidentState {
+	time.parse(now)
+	const evidence = text.parse(reason)
+	if (state.phase !== 'waiting') throw new Error('Only a waiting resident can be woken.')
+	return { ...state, wakeAt: now, reason: evidence }
+}

package/src/prompt/contributions.ts

@@ -41,7 +41,10 @@ export interface PromptContributionContext {
  *
  * Not cosmetic, and the wrong answer is expensive in a way nothing reports.
  * `static` is the segment the prompt cache keeps and a provider caches
- * across turns; `dynamic` is re-sent every iteration. A contributor whose
+ * across turns; `dynamic` is the uncached invocation snapshot. `query`
+ * assembles both once at invocation start and sends them on every iteration.
+ * Use `turn` for a renderer that must observe changes during the invocation.
+ * A contributor whose
  * text varies per turn but declares `static` either invalidates the cached
  * prefix on every iteration — paying full price for a cache that never
  * hits — or, worse, gets served the first turn's text forever.
@@ -55,7 +58,7 @@ export type PromptPlacement = 'static' | 'dynamic' | 'turn'
  * `turn` is a third thing, not a looser `dynamic`.
  *
  * `static` and `dynamic` are both parts of the SYSTEM PROMPT: assembled
- * once per request, sent as system messages, and — for `static` — cached by
+ * once per invocation, sent as system messages, and — for `static` — cached by
  * the provider across turns. `turn` is not in the system prompt at all. It
  * rides the ephemeral trailing message that a step's guidance, its skills
  * and the approval-policy notice already use: appended to the request,

package/src/prompt/index.ts

@@ -21,3 +21,5 @@ 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'