@namzu/sdk 27.1.0 → 28.0.0

package/src/store/topic/objective.ts

@@ -0,0 +1,290 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { TenantId, TopicId } from '../../types/ids/index.js'
+import {
+	type ObjectivePhase,
+	type ObjectiveRoundVerdict,
+	StaleObjectiveError,
+	type TopicObjective,
+} from '../../types/topic/objective.js'
+import { DiskRecordStore } from '../kv/record-store.js'
+import { defineSchema } from '../schema.js'
+
+/**
+ * Where an objective lives between runs.
+ *
+ * Beside `TopicStateStore` rather than inside it, for the reason that store
+ * gives for living beside the Topic: permission mode and the next-run queue
+ * change several times inside one conversation, and an objective's phase
+ * changes once per round. Sharing a `revision` would make a round
+ * completing conflict with a mode toggle — two facts about one topic that
+ * have nothing to say to each other.
+ */
+
+const SCHEMA = defineSchema({ kind: 'topic-objective', current: 1, migrations: {} })
+const records = new DiskRecordStore<TopicObjective>(SCHEMA)
+
+export interface CreateObjectiveParams {
+	readonly id: string
+	readonly topicId: TopicId
+	readonly objective: string
+	/** Rounds this objective may BEGIN before it blocks itself. */
+	readonly maxRounds: number
+}
+
+export interface TopicObjectiveStore {
+	/** `null` when this id has never been written, or belongs to another tenant. */
+	getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>
+
+	/**
+	 * Refuses an id that already exists, rather than overwriting.
+	 *
+	 * A create that silently replaced would reset `roundsStarted` — the one
+	 * field whose whole job is to be un-resettable by the thing it caps.
+	 */
+	createObjective(params: CreateObjectiveParams, tenantId: TenantId): Promise<TopicObjective>
+
+	/**
+	 * Debit one round, under compare-and-set on `revision`.
+	 *
+	 * Returns the record with `roundsStarted` already incremented, so the
+	 * caller cannot run the round and then fail to record that it did.
+	 * Throws `ObjectiveExhaustedError` when the cap is reached, having first
+	 * written the `blocked` phase — so a reader that never sees the throw
+	 * still finds the objective stopped for a stated reason.
+	 */
+	beginRound(id: string, tenantId: TenantId, opts: { revision: number }): Promise<TopicObjective>
+
+	/** Record what a round decided, under the same compare-and-set. */
+	settleRound(
+		id: string,
+		tenantId: TenantId,
+		verdict: ObjectiveRoundVerdict,
+		opts: { revision: number },
+	): Promise<TopicObjective>
+
+	/** Move between `active` and `paused`, under the same compare-and-set. */
+	setPhase(
+		id: string,
+		tenantId: TenantId,
+		phase: ObjectivePhase,
+		opts: { revision: number },
+	): Promise<TopicObjective>
+}
+
+/** A round asked for beyond the cap. */
+export class ObjectiveExhaustedError extends Error {
+	readonly details: { id: string; maxRounds: number }
+
+	constructor(details: { id: string; maxRounds: number }) {
+		super(`Objective ${details.id} has used all ${details.maxRounds} of its rounds.`)
+		this.name = 'ObjectiveExhaustedError'
+		this.details = details
+	}
+}
+
+/** An id that already exists. */
+export class ObjectiveExistsError extends Error {
+	readonly details: { id: string }
+
+	constructor(details: { id: string }) {
+		super(`Objective ${details.id} already exists.`)
+		this.name = 'ObjectiveExistsError'
+		this.details = details
+	}
+}
+
+function assertFresh(id: string, existing: TopicObjective, revision: number): void {
+	if (revision !== existing.revision) {
+		throw new StaleObjectiveError({
+			id,
+			expectedRevision: revision,
+			actualRevision: existing.revision,
+		})
+	}
+}
+
+function missing(id: string): Error {
+	return new Error(`No objective ${id}.`)
+}
+
+/**
+ * The shared write logic.
+ *
+ * Both implementations differ only in where the record lands, so the rules
+ * — what a round costs, when the cap bites, which phases accept a write —
+ * are written once. Two copies of a compare-and-set is two chances to have
+ * one of them drift, and the drift would be invisible until a host used the
+ * other implementation.
+ */
+abstract class ObjectiveStoreBase implements TopicObjectiveStore {
+	protected constructor(protected readonly now: () => number) {}
+
+	abstract getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null>
+	protected abstract put(record: TopicObjective): Promise<void>
+
+	async createObjective(
+		params: CreateObjectiveParams,
+		tenantId: TenantId,
+	): Promise<TopicObjective> {
+		if (await this.getObjective(params.id, tenantId)) {
+			throw new ObjectiveExistsError({ id: params.id })
+		}
+		if (params.maxRounds < 1) {
+			// A cap of zero is an objective that can never run. Accepting it
+			// would produce a record that blocks on its own first round, which
+			// reads as a runaway that was stopped rather than a caller mistake.
+			throw new Error(`maxRounds must be at least 1, got ${params.maxRounds}.`)
+		}
+		const record: TopicObjective = {
+			id: params.id,
+			topicId: params.topicId,
+			tenantId,
+			revision: 1,
+			objective: params.objective,
+			phase: 'active',
+			maxRounds: params.maxRounds,
+			roundsStarted: 0,
+			updatedAt: this.now(),
+		}
+		await this.put(record)
+		return record
+	}
+
+	async beginRound(
+		id: string,
+		tenantId: TenantId,
+		opts: { revision: number },
+	): Promise<TopicObjective> {
+		const existing = await this.getObjective(id, tenantId)
+		if (!existing) throw missing(id)
+		assertFresh(id, existing, opts.revision)
+		if (existing.phase !== 'active') {
+			throw new Error(`Objective ${id} is ${existing.phase}, not active.`)
+		}
+		if (existing.roundsStarted >= existing.maxRounds) {
+			// Blocked BEFORE the throw. A caller that swallows this error, or a
+			// process that dies on it, must not leave a record that still says
+			// `active` — the next reader would start the round this refused.
+			await this.put({
+				...existing,
+				revision: existing.revision + 1,
+				phase: 'blocked',
+				blockedReason: {
+					code: 'round_cap',
+					message: `Reached the ${existing.maxRounds}-round cap.`,
+				},
+				updatedAt: this.now(),
+			})
+			throw new ObjectiveExhaustedError({ id, maxRounds: existing.maxRounds })
+		}
+		const record: TopicObjective = {
+			...existing,
+			revision: existing.revision + 1,
+			roundsStarted: existing.roundsStarted + 1,
+			updatedAt: this.now(),
+		}
+		await this.put(record)
+		return record
+	}
+
+	async settleRound(
+		id: string,
+		tenantId: TenantId,
+		verdict: ObjectiveRoundVerdict,
+		opts: { revision: number },
+	): Promise<TopicObjective> {
+		const existing = await this.getObjective(id, tenantId)
+		if (!existing) throw missing(id)
+		assertFresh(id, existing, opts.revision)
+		const record: TopicObjective = {
+			...existing,
+			revision: existing.revision + 1,
+			phase: verdict.phase ?? existing.phase,
+			...(verdict.blockedReason ? { blockedReason: verdict.blockedReason } : {}),
+			...(verdict.runId ? { lastRunId: verdict.runId } : {}),
+			updatedAt: this.now(),
+		}
+		await this.put(record)
+		return record
+	}
+
+	async setPhase(
+		id: string,
+		tenantId: TenantId,
+		phase: ObjectivePhase,
+		opts: { revision: number },
+	): Promise<TopicObjective> {
+		const existing = await this.getObjective(id, tenantId)
+		if (!existing) throw missing(id)
+		assertFresh(id, existing, opts.revision)
+		if (existing.phase === 'complete' && phase !== 'complete') {
+			// One-way. Reopening a finished objective by writing a phase would
+			// let a stale caller restart work somebody already signed off, and
+			// the round counter it would run against is the one already spent.
+			throw new Error(`Objective ${id} is complete; it cannot be moved to ${phase}.`)
+		}
+		// A move off `blocked` drops the reason. Carrying it would describe a
+		// running objective as blocked by something it no longer is, and that
+		// stale sentence is what an operator reads to decide whether to
+		// intervene.
+		const { blockedReason, ...rest } = existing
+		const record: TopicObjective = {
+			...rest,
+			revision: existing.revision + 1,
+			phase,
+			...(phase === 'blocked' && blockedReason ? { blockedReason } : {}),
+			updatedAt: this.now(),
+		}
+		await this.put(record)
+		return record
+	}
+}
+
+export class InMemoryTopicObjectiveStore extends ObjectiveStoreBase {
+	private readonly objectives = new Map<string, TopicObjective>()
+
+	constructor(now: () => number = Date.now) {
+		super(now)
+	}
+
+	async getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null> {
+		const found = this.objectives.get(id)
+		// Another tenant's record reads as absent rather than as an error, for
+		// the reason the project listing gives: refusing confirms it is there.
+		return found && found.tenantId === tenantId ? found : null
+	}
+
+	protected async put(record: TopicObjective): Promise<void> {
+		this.objectives.set(record.id, record)
+	}
+}
+
+export interface DiskTopicObjectiveStoreConfig {
+	/** The session root. Objectives live under `<rootDir>/objectives/`. */
+	readonly rootDir: string
+}
+
+export class DiskTopicObjectiveStore extends ObjectiveStoreBase {
+	constructor(
+		private readonly config: DiskTopicObjectiveStoreConfig,
+		now: () => number = Date.now,
+	) {
+		super(now)
+	}
+
+	private path(id: string): string {
+		return join(this.config.rootDir, 'objectives', `${id}.json`)
+	}
+
+	async getObjective(id: string, tenantId: TenantId): Promise<TopicObjective | null> {
+		const found = await records.read(this.path(id))
+		return found && found.tenantId === tenantId ? found : null
+	}
+
+	protected async put(record: TopicObjective): Promise<void> {
+		await mkdir(join(this.config.rootDir, 'objectives'), { recursive: true })
+		await records.write(this.path(record.id), record)
+	}
+}

package/src/store/topic/state.ts

@@ -0,0 +1,204 @@
+import { mkdir } from 'node:fs/promises'
+import { join } from 'node:path'
+
+import type { TenantId, TopicId } from '../../types/ids/index.js'
+import type { Message } from '../../types/message/index.js'
+import type { PermissionMode } from '../../types/permission/index.js'
+import { StaleTopicStateError, type TopicState } from '../../types/topic/state.js'
+import { DiskRecordStore } from '../kv/record-store.js'
+import { defineSchema } from '../schema.js'
+
+/**
+ * Where a conversation's mutable state lives between runs.
+ *
+ * Its own store rather than a field on the Topic record, and its own file
+ * rather than a column: the Topic is identity and ownership, this is
+ * session state that changes several times inside one conversation. Merging
+ * them would make every mode toggle a compare-and-set conflict against a
+ * title rename.
+ *
+ * A separate store rather than an extension of `TopicStore` because there
+ * is no disk `TopicStore` to extend — topics are in-memory everywhere in
+ * this tree today. Persisting the state on its own is what the durability
+ * this exists for actually needs; building a whole topic disk store to
+ * carry one field would be a much larger change nobody asked for, and this
+ * record is designed to be folded into one if that arrives.
+ */
+
+const SCHEMA = defineSchema({ kind: 'topic-state', current: 1, migrations: {} })
+const records = new DiskRecordStore<TopicState>(SCHEMA)
+
+export interface TopicStateStore {
+	/** `null` when this topic has never had state written. */
+	getState(topicId: TopicId, tenantId: TenantId): Promise<TopicState | null>
+	/**
+	 * Compare-and-set on `revision`, `0` for a first write.
+	 *
+	 * Rejects a stale revision the way `updateTopic` rejects a stale
+	 * `ownerVersion`. Two hosts toggling one conversation's mode is not
+	 * hypothetical — a TUI and a webhook on the same topic — and
+	 * last-write-wins there silently reopens a mode somebody just closed.
+	 */
+	setPermissionMode(
+		topicId: TopicId,
+		tenantId: TenantId,
+		mode: PermissionMode,
+		opts: { readonly revision: number },
+	): Promise<TopicState>
+
+	/**
+	 * Replace the next-run queue, under the same compare-and-set.
+	 *
+	 * Replace rather than append, so the caller that read the list is the
+	 * one that decides what the new one is — an append primitive would let
+	 * a caller add to a list it had never seen.
+	 */
+	setQueuedMessages(
+		topicId: TopicId,
+		tenantId: TenantId,
+		messages: readonly Message[],
+		opts: { readonly revision: number },
+	): Promise<TopicState>
+}
+
+/** The record after one accepted write. */
+function next(
+	topicId: TopicId,
+	tenantId: TenantId,
+	previous: TopicState | null,
+	patch: { permissionMode?: PermissionMode; queuedMessages?: readonly Message[] },
+	now: number,
+): TopicState {
+	return {
+		topicId,
+		tenantId,
+		revision: (previous?.revision ?? 0) + 1,
+		permissionMode: patch.permissionMode ?? previous?.permissionMode ?? 'auto',
+		...(patch.queuedMessages !== undefined
+			? { queuedMessages: patch.queuedMessages }
+			: previous?.queuedMessages
+				? { queuedMessages: previous.queuedMessages }
+				: {}),
+		updatedAt: now,
+	}
+}
+
+export class InMemoryTopicStateStore implements TopicStateStore {
+	private readonly states = new Map<TopicId, TopicState>()
+
+	constructor(private readonly now: () => number = Date.now) {}
+
+	async getState(topicId: TopicId, tenantId: TenantId): Promise<TopicState | null> {
+		const found = this.states.get(topicId)
+		// A record from another tenant reads as absent rather than as an
+		// error, for the reason the project listing gives: refusing would
+		// confirm that somebody else's topic is there.
+		return found && found.tenantId === tenantId ? found : null
+	}
+
+	async setPermissionMode(
+		topicId: TopicId,
+		tenantId: TenantId,
+		mode: PermissionMode,
+		opts: { revision: number },
+	): Promise<TopicState> {
+		const existing = await this.getState(topicId, tenantId)
+		const actual = existing?.revision ?? 0
+		if (opts.revision !== actual) {
+			throw new StaleTopicStateError({
+				topicId,
+				expectedRevision: opts.revision,
+				actualRevision: actual,
+			})
+		}
+		const record = next(topicId, tenantId, existing, { permissionMode: mode }, this.now())
+		this.states.set(topicId, record)
+		return record
+	}
+
+	async setQueuedMessages(
+		topicId: TopicId,
+		tenantId: TenantId,
+		messages: readonly Message[],
+		opts: { revision: number },
+	): Promise<TopicState> {
+		const existing = await this.getState(topicId, tenantId)
+		const actual = existing?.revision ?? 0
+		if (opts.revision !== actual) {
+			throw new StaleTopicStateError({
+				topicId,
+				expectedRevision: opts.revision,
+				actualRevision: actual,
+			})
+		}
+		const record = next(topicId, tenantId, existing, { queuedMessages: messages }, this.now())
+		this.states.set(topicId, record)
+		return record
+	}
+}
+
+export interface DiskTopicStateStoreConfig {
+	/** The session root. State lives under `<rootDir>/topic-state/`. */
+	readonly rootDir: string
+}
+
+export class DiskTopicStateStore implements TopicStateStore {
+	constructor(
+		private readonly config: DiskTopicStateStoreConfig,
+		private readonly now: () => number = Date.now,
+	) {}
+
+	private path(topicId: TopicId): string {
+		return join(this.config.rootDir, 'topic-state', `${topicId}.json`)
+	}
+
+	async getState(topicId: TopicId, tenantId: TenantId): Promise<TopicState | null> {
+		const found = await records.read(this.path(topicId))
+		return found && found.tenantId === tenantId ? found : null
+	}
+
+	async setPermissionMode(
+		topicId: TopicId,
+		tenantId: TenantId,
+		mode: PermissionMode,
+		opts: { revision: number },
+	): Promise<TopicState> {
+		const existing = await this.getState(topicId, tenantId)
+		const actual = existing?.revision ?? 0
+		if (opts.revision !== actual) {
+			throw new StaleTopicStateError({
+				topicId,
+				expectedRevision: opts.revision,
+				actualRevision: actual,
+			})
+		}
+		const record = next(topicId, tenantId, existing, { permissionMode: mode }, this.now())
+		await this.persist(record)
+		return record
+	}
+
+	async setQueuedMessages(
+		topicId: TopicId,
+		tenantId: TenantId,
+		messages: readonly Message[],
+		opts: { revision: number },
+	): Promise<TopicState> {
+		const existing = await this.getState(topicId, tenantId)
+		const actual = existing?.revision ?? 0
+		if (opts.revision !== actual) {
+			throw new StaleTopicStateError({
+				topicId,
+				expectedRevision: opts.revision,
+				actualRevision: actual,
+			})
+		}
+		const record = next(topicId, tenantId, existing, { queuedMessages: messages }, this.now())
+		await this.persist(record)
+		return record
+	}
+
+	private async persist(record: TopicState): Promise<void> {
+		await mkdir(join(this.config.rootDir, 'topic-state'), { recursive: true })
+		await records.write(this.path(record.topicId), record)
+	}
+}

package/src/streaming/coalesce.ts

@@ -1,7 +1,12 @@
 import type { ToolUseId } from '../types/ids/index.js'
 import type { RunEvent } from '../types/run/events.js'
 
-interface CoalesceOptions {
+export interface CoalesceOptions {
+	/**
+	 * Sliding merge window. 16ms is roughly one animation frame at 60fps,
+	 * which is the point past which a human cannot see the difference and
+	 * below which the consumer pays for deltas nobody perceives.
+	 */
 	windowMs: number
 }
 
@@ -16,10 +21,19 @@ interface CoalesceOptions {
  * All other event types pass through immediately and flush any buffered
  * deltas first to preserve ordering.
  *
- * The orchestrator does NOT use this — it emits raw deltas. SSE adapters
- * and other slow consumers opt in. A 16ms window roughly aligns with one
- * UI animation frame at 60fps, which is the empirically derived default
- * for a live stream route.
+ * The orchestrator does NOT use this — it emits raw deltas, and nothing
+ * inside the kernel calls this function. That is deliberate and is why it
+ * is exported: the consumer this exists for is a host's HTTP route, and a
+ * kernel with no UI and no hosted service has no in-process caller to
+ * offer. `bridge/sse/` maps an event to the wire; deciding how OFTEN to
+ * write to a slow client is the host's policy, because only the host
+ * knows what is on the other end of its socket.
+ *
+ * `streaming/` owns coalescing and nothing else. SSE mapping lives in
+ * `bridge/sse/`, provider chunk assembly in the provider drivers, and the
+ * run event stream in `runtime/query/` — none of them belong here, and a
+ * second occupant of this directory should be another rate policy or
+ * nothing.
  *
  * Backpressure semantics: this helper does not drop events. If the
  * upstream produces faster than the consumer drains, the helper still

package/src/telemetry/runtime-accessors.ts

@@ -8,8 +8,52 @@
 // return the no-op defaults and every span/meter write is silently
 // discarded — standard OTEL library behavior.
 
-import { type Tracer, trace } from '@opentelemetry/api'
+import { type SpanContext, type Tracer, context, trace } from '@opentelemetry/api'
 
 export function getTracer(): Tracer {
 	return trace.getTracer('namzu')
 }
+
+/**
+ * The active span's context, read fresh on every call — nothing here is
+ * ever cached. `utils/log/create-logger.ts`'s `emit` calls this once per
+ * ACCEPTED record (after the level check, never before) so a logger built
+ * before any tracer provider registers still picks up spans started after
+ * registration. Caching this at logger construction would repeat the exact
+ * mistake `telemetry/metrics.ts` documents for a meter: a bag that
+ * captured the no-op instance once stayed no-op for the rest of the
+ * process even after a real provider registered later.
+ *
+ * `undefined` whenever nothing is active — the DEFAULT, not an edge case
+ * this function has to detect. `@opentelemetry/api` ships a
+ * `NoopContextManager` until something registers a real one
+ * (`@namzu/telemetry`'s `registerTelemetry` does, via
+ * `NodeTracerProvider.register()`), and that default's `active()`
+ * unconditionally returns `ROOT_CONTEXT` — it does not even remember what a
+ * caller set with `context.with()`. So a host that never configures
+ * telemetry gets `undefined` here on every call, for free, with nothing in
+ * this function special-casing "telemetry not configured": that behaviour
+ * is the api's own default, not a check performed here. Which is also why
+ * this can only ever ADD information to a record — reading the active
+ * context can never make an unconfigured host fail a check that would
+ * otherwise pass (`an-optional-dependency-may-not-degrade-a-check`, in
+ * reverse).
+ */
+export function getActiveSpanContext(): SpanContext | undefined {
+	// Wrapped for the same reason `createLogger` wraps `sink.emit`: everything
+	// this touches past the api boundary is a HOST's object. A third-party
+	// `ContextManager` whose `active()` throws would otherwise raise that
+	// exception inside every log call in the kernel — turning a logging
+	// integration bug into a run failure, at a call site nobody reading it
+	// would suspect of being able to throw.
+	//
+	// Swallowed rather than reported, unlike a dropped record: this cannot
+	// lose a record. The record still emits, just without correlation, which
+	// is exactly the state of every host that has not configured telemetry at
+	// all. Degrading the correlation is not degrading the check.
+	try {
+		return trace.getSpan(context.active())?.spanContext()
+	} catch {
+		return undefined
+	}
+}