@namzu/sdk 27.1.0 → 29.0.0

package/src/runtime/query/context.ts

@@ -1,10 +1,10 @@
 import { join } from 'node:path'
+import { GENAI, NAMZU } from '../../constants/telemetry/index.js'
 import { PlanManager } from '../../manager/plan/lifecycle.js'
 import { RunPersistence } from '../../manager/run/persistence.js'
 import {
 	DefaultFilesystemMigrator,
 	type FilesystemMigrationResult,
-	type FilesystemMigrationSink,
 	type FilesystemMigrator,
 	NOOP_FILESYSTEM_MIGRATION_SINK,
 } from '../../session/migration/index.js'
@@ -18,28 +18,56 @@ import type { LLMProvider } from '../../types/provider/index.js'
 import type { CheckpointStore } from '../../types/run/checkpoint-store.js'
 import type { AgentRunConfig } from '../../types/run/index.js'
 import type { RunStore } from '../../types/run/store.js'
-import type { ProjectId, ThreadId } from '../../types/session/ids.js'
+import type { ProjectId, TopicId } from '../../types/session/ids.js'
 import type { ModelPricing } from '../../utils/cost.js'
 import { generateRunId } from '../../utils/id.js'
-import { type Logger, getRootLogger } from '../../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 
 /**
  * Config accepted by {@link RunContextFactory.build}. `sessionId`,
- * `threadId`, `projectId`, and `tenantId` are required — runs carry the full
- * five-layer scope (Tenant → Project → Thread → Session → Run) per
+ * `topicId`, `projectId`, and `tenantId` are required — runs carry the full
+ * five-layer scope (Tenant → Project → Topic → Session → Run) per
  * Convention #17.
  *
  * `pathBuilder` is optional; when absent a {@link DefaultPathBuilder} is
  * constructed against `{workingDirectory}/.namzu`.
  *
- * `filesystemMigrator` + `migrationSink` are optional; when absent a
- * {@link DefaultFilesystemMigrator} wired to the
- * {@link NOOP_FILESYSTEM_MIGRATION_SINK} is used. Migration runs once per
- * process via {@link RunContextFactory.ensureMigrated}; the static `build`
- * method stays synchronous so existing call sites are not broken — async
- * callers (e.g. `query()`) invoke `ensureMigrated` themselves before build.
+ * `filesystemMigrator` is optional, but note what `build` actually does
+ * with it: nothing. Migration is not part of `build` — it runs once per
+ * process via {@link RunContextFactory.ensureMigrated}, kept out of `build`
+ * entirely so the static method stays synchronous for existing callers;
+ * `query()` calls `ensureMigrated` itself, with its own migrator, before it
+ * ever calls `build`. This field predates that split, and no code path
+ * threads it to `ensureMigrated` on `build`'s behalf. Its sibling
+ * `migrationSink` had the identical shape — declared, never read anywhere
+ * in the workspace — and NZ-BOOT-04 removed it
+ * (`docs/conventions/declared-but-undriven.md`) rather than invent a caller
+ * for a field nothing needed; `filesystemMigrator` is the same defect, left
+ * for a follow-up rather than folded into that change.
  */
 export interface RunContextConfig {
+	/**
+	 * The mode this conversation was left in, when the run config names none.
+	 *
+	 * Read from the Topic's state record by `query()`. An explicit
+	 * `RunConfig.permissionMode` outranks it, which is what keeps every
+	 * existing caller byte-identical.
+	 */
+	topicPermissionMode?: PermissionMode
+
+	/**
+	 * The live mode box, when the caller wants to hold it too.
+	 *
+	 * Supplied rather than created here so whoever builds the coordinator
+	 * tools — which is not this function — can flip the mode from an
+	 * approval hook and have the executor see it. Without a shared handle
+	 * the approval could persist the change and the RUNNING run would go on
+	 * refusing writes, which is the confusing half-state this whole task
+	 * exists to remove.
+	 */
+	permissionModeRef?: { current: PermissionMode }
+
 	agentId: string
 	agentName: string
 	runConfig: AgentRunConfig
@@ -51,7 +79,7 @@ export interface RunContextConfig {
 	signal?: AbortSignal
 
 	sessionId: SessionId
-	threadId: ThreadId
+	topicId: TopicId
 	projectId: ProjectId
 	tenantId: TenantId
 
@@ -72,21 +100,23 @@ export interface RunContextConfig {
 	 */
 	filesystemMigrator?: FilesystemMigrator
 
-	/** Optional sink for `filesystem.migrated` events. Defaults to no-op. */
-	migrationSink?: FilesystemMigrationSink
-
 	runId?: RunId
 
 	parentRunId?: RunId
 
 	depth?: number
+
+	/**
+	 * A pre-built, already-correlated logger — what {@link RunContextFactory.buildLogger} returns. When present, `build` uses this instead of constructing its own, which is what lets a caller hand the SAME logger to `withProviderRetry`/`withProviderFallback` (themselves inputs to `build` — see `runtime/query/index.ts`) and to the `RunContext` this config becomes, rather than each reaching for its own child of `getRootLogger()` and losing the guarantee that a retry warning and the run it retried for share one `namzu.run.id`. Absent means what it always meant: `build` derives its own via `buildLogger`.
+	 */
+	log?: Logger
 }
 
 /** Result of {@link RunContextFactory.build}. */
 export interface RunContext {
 	runId: RunId
 	sessionId: SessionId
-	threadId: ThreadId
+	topicId: TopicId
 	projectId: ProjectId
 	tenantId: TenantId
 	runMgr: RunPersistence
@@ -95,7 +125,15 @@ export interface RunContext {
 	abortController: AbortController
 	cwd: string
 	outputDir: string
-	permissionMode: PermissionMode
+	/**
+	 * The mode RIGHT NOW, not the one this run started in.
+	 *
+	 * A box rather than a value, because an approval inside a run can change
+	 * it and the executor reads through the same box — see
+	 * `ToolExecutorConfig.permissionMode`. The run used to freeze it at
+	 * start, so leaving plan mode meant ending the run.
+	 */
+	permissionMode: { current: PermissionMode }
 	log: Logger
 	trackingConfig: ActivityTrackingConfig
 }
@@ -133,6 +171,54 @@ export class RunContextFactory {
 		return promise
 	}
 
+	/**
+	 * The run's one correlated logger, built once and handed to every
+	 * consumer that used to construct its own. Split out of `build` because
+	 * `build` is not the first thing in `query()` that needs a logger: the
+	 * provider retry and fallback wrappers (`runtime/query/index.ts`) are
+	 * THEMSELVES inputs to `build` (`resilientProvider`), so a caller has to
+	 * be able to get a correlated logger BEFORE `build` runs, not after —
+	 * the reordering the design's own boundary table found does not
+	 * type-check when attempted the other way round.
+	 *
+	 * `runId` is a REQUIRED field here, not the `config.runId ??
+	 * generateRunId()` fallback `build` still does for its own direct
+	 * callers below. The whole reason to extract this is that the SAME id
+	 * ends up bound on the log and stamped onto the `RunContext` it is
+	 * later attached to — generating it twice, once here and once in
+	 * `build`, would silently hand the log and the run two different ids.
+	 * The caller (`query()`) resolves the id once and passes it to both
+	 * this and `build`.
+	 *
+	 * The base logger comes from `resolveLogger`, not `getRootLogger`
+	 * directly — the fallback-to-the-process-default read now lives there
+	 * instead of duplicated at every site that used to reach for the global
+	 * on its own. A host that set `runConfig.logger` gets ITS OWN logger as
+	 * the base `.child()` is called on, so every record this run's retry
+	 * and fallback wrappers write still reaches the host's destination:
+	 * `buildLogger` layers correlation on top, it does not replace the
+	 * source.
+	 */
+	static buildLogger(
+		config: Pick<
+			RunContextConfig,
+			'agentName' | 'runConfig' | 'sessionId' | 'topicId' | 'projectId' | 'tenantId' | 'parentRunId'
+		> & {
+			runId: RunId
+		},
+	): Logger {
+		return resolveLogger(config.runConfig.logger).child({
+			[SCOPE_ATTRIBUTE]: 'runtime/query',
+			[GENAI.AGENT_NAME]: config.agentName,
+			[NAMZU.RUN_ID]: config.runId,
+			...(config.parentRunId ? { [NAMZU.RUN_PARENT_ID]: config.parentRunId } : {}),
+			[NAMZU.SESSION_ID]: config.sessionId,
+			[NAMZU.THREAD_ID]: config.topicId,
+			[NAMZU.PROJECT_ID]: config.projectId,
+			[NAMZU.TENANT_ID]: config.tenantId,
+		})
+	}
+
 	static build(config: RunContextConfig): RunContext {
 		const abortController = new AbortController()
 		if (config.signal) {
@@ -155,22 +241,23 @@ export class RunContextFactory {
 		}
 
 		const cwd = config.workingDirectory ?? process.cwd()
-		const permissionMode = config.runConfig.permissionMode ?? 'auto'
+		// An explicit `RunConfig.permissionMode` still wins — this is the
+		// no-behaviour-change guarantee for every existing caller. The topic
+		// record supplies the mode only when the run config names none, and
+		// `resolveTopicPermissionMode` in `query()` is what reads it.
+		const seeded = config.runConfig.permissionMode ?? config.topicPermissionMode ?? 'auto'
+		const permissionMode = config.permissionModeRef ?? { current: seeded }
+		// Seeded even when supplied: the caller creates the box before it can
+		// know what the run config or the topic record say, so leaving its
+		// initial value in place would ignore both.
+		permissionMode.current = seeded
 		const runId = config.runId ?? generateRunId()
 
 		const pathBuilder = config.pathBuilder ?? new DefaultPathBuilder(join(cwd, '.namzu'))
 		const outputDir = pathBuilder.sessionDir(config.projectId, config.sessionId)
 		const runsDir = join(outputDir, 'runs')
 
-		const log = getRootLogger().child({
-			component: 'query',
-			agent: config.agentName,
-			runId,
-			sessionId: config.sessionId,
-			threadId: config.threadId,
-			projectId: config.projectId,
-			tenantId: config.tenantId,
-		})
+		const log = config.log ?? RunContextFactory.buildLogger({ ...config, runId })
 
 		const runMgr = new RunPersistence({
 			runId,
@@ -182,7 +269,7 @@ export class RunContextFactory {
 			pricing: config.pricing,
 			log,
 			sessionId: config.sessionId,
-			threadId: config.threadId,
+			topicId: config.topicId,
 			tenantId: config.tenantId,
 			projectId: config.projectId,
 			parentRunId: config.parentRunId,
@@ -191,14 +278,17 @@ export class RunContextFactory {
 			runStore: config.runStore,
 		})
 
-		const trackingConfig = resolveActivityTracking(permissionMode, config.enableActivityTracking)
+		const trackingConfig = resolveActivityTracking(
+			permissionMode.current,
+			config.enableActivityTracking,
+		)
 		const activityStore = new ActivityStore(runId, trackingConfig)
 		const planManager = new PlanManager(runId)
 
 		return {
 			runId,
 			sessionId: config.sessionId,
-			threadId: config.threadId,
+			topicId: config.topicId,
 			projectId: config.projectId,
 			tenantId: config.tenantId,
 			runMgr,

package/src/runtime/query/events.ts

@@ -1,14 +1,17 @@
+import { NAMZU } from '../../constants/telemetry/index.js'
 import type { PlanEvent, PlanManager } from '../../manager/plan/lifecycle.js'
 import type { RunPersistence } from '../../manager/run/persistence.js'
 import { buildProbeContext } from '../../probe/context.js'
-import { type ProbeRegistry, probe as defaultProbeRegistry } from '../../probe/registry.js'
+import { probe as defaultProbeRegistry } from '../../probe/registry.js'
+import type { ProbeObservation } from '../../probe/registry.js'
 import type { ActivityEvent, ActivityStore } from '../../store/activity/memory.js'
 import type { RunId } from '../../types/ids/index.js'
-import type { ClaimFence } from '../../types/run/checkpoint-store.js'
+import type { FencingToken } from '../../types/run/checkpoint-store.js'
 import { isEphemeralEvent } from '../../types/run/events.js'
 import type { RunEvent } from '../../types/run/index.js'
 import type { TaskEvent, TaskStore } from '../../types/task/index.js'
-import { getRootLogger } from '../../utils/logger.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import { type Logger, resolveLogger } from '../../utils/logger.js'
 
 export type EmitEvent = (event: RunEvent) => Promise<void>
 
@@ -29,13 +32,18 @@ const PENDING_EVENT_SOFT_CAP = 1000
 export class EventTranslator {
 	private pendingEvents: RunEvent[] = []
 	private runMgr: RunPersistence
-	private probes: ProbeRegistry
+	private probes: ProbeObservation
 	private droppedDeltaCount = 0
-	private readonly log = getRootLogger().child({ component: 'EventTranslator' })
+	private readonly log: Logger
 
-	constructor(runMgr: RunPersistence, probeRegistry: ProbeRegistry = defaultProbeRegistry) {
+	constructor(
+		runMgr: RunPersistence,
+		probeRegistry: ProbeObservation = defaultProbeRegistry,
+		log?: Logger,
+	) {
 		this.runMgr = runMgr
 		this.probes = probeRegistry
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'runtime/query/events' })
 	}
 
 	/**
@@ -45,12 +53,12 @@ export class EventTranslator {
 	 * cursor predates a takeover is told its sequence space changed instead of
 	 * being handed a splice from a different writer's log.
 	 */
-	private generation: ClaimFence | undefined
+	private generation: FencingToken | undefined
 
 	/** Serializes sequence assignment against the append. See {@link emitEvent}. */
 	private appendChain: Promise<void> = Promise.resolve()
 
-	setGeneration(fence: ClaimFence | undefined): void {
+	setGeneration(fence: FencingToken | undefined): void {
 		this.generation = fence
 	}
 
@@ -69,9 +77,9 @@ export class EventTranslator {
 				this.droppedDeltaCount += 1
 				if (this.droppedDeltaCount === 1 || this.droppedDeltaCount % 100 === 0) {
 					this.log.warn('Dropped ephemeral RunEvent under bus pressure', {
-						runId: event.runId,
-						droppedCount: this.droppedDeltaCount,
-						queueSize: this.pendingEvents.length,
+						[NAMZU.RUN_ID]: event.runId,
+						'namzu.runtime.dropped_count': this.droppedDeltaCount,
+						'namzu.runtime.queue_size': this.pendingEvents.length,
 					})
 				}
 			}