@namzu/sdk 27.1.0 → 28.0.0

package/src/compaction/plan.ts

@@ -0,0 +1,226 @@
+import type { CompactionConfig } from '../config/runtime.js'
+import { CHARS_PER_TOKEN } from '../constants/limits.js'
+import type { Message } from '../types/message/index.js'
+import { findSafeTrimIndex } from './dangling.js'
+import { clearStaleToolResults } from './tool-result-editing.js'
+
+/**
+ * The compaction decision, with no run attached.
+ *
+ * The whole algorithm — the leading-system floor scan, the tool-result
+ * pre-pass, the boundary search, the guards — lived inside
+ * `runCompactionCheck` and read everything off the iteration context — the
+ * live message array, the logger, the event emitter, the working-state
+ * manager. Nothing outside a live iteration could run it, so the pass was
+ * testable only through a full run harness and unreachable from any
+ * host-callable entry point.
+ *
+ * This file therefore holds NO reference to that context, and a test greps
+ * for one: reintroducing a single field read would quietly re-couple the
+ * arithmetic to a run and nothing else would fail.
+ *
+ * What stayed behind is everything with an effect: the model call, the
+ * working-memory re-pin, the array install, the logging, every
+ * `emitEvent`. What moved here is the arithmetic. The split is the
+ * question "what should happen" separated from "make it happen", and only
+ * the first half can be asked without a run.
+ */
+
+/** Why a pass decided to do nothing. */
+export type CompactionSkipReason =
+	/** Fewer messages than the recent window plus a floor — nothing to move. */
+	| 'too_few_messages'
+	/** No leading `system` message, so there is no permanent floor to keep. */
+	| 'no_system_floor'
+	/** Every candidate boundary would split a tool-call pair. */
+	| 'no_safe_cut'
+	/** A safe cut exists but leaves nothing older worth summarising. */
+	| 'too_few_older'
+
+export type CompactionPlan =
+	| { readonly kind: 'skip'; readonly reason: CompactionSkipReason }
+	| {
+			readonly kind: 'cleared'
+			readonly messages: readonly Message[]
+			readonly clearedCount: number
+			readonly charsReclaimed: number
+			readonly reclaimedTokens: number
+			readonly reliefWasEnough: boolean
+	  }
+	| {
+			readonly kind: 'plan'
+			readonly systemMessages: readonly Message[]
+			readonly olderMessages: readonly Message[]
+			readonly recentMessages: readonly Message[]
+			readonly keepStart: number
+	  }
+
+export interface CompactionPlanInput {
+	readonly messages: readonly Message[]
+	readonly config: CompactionConfig
+	readonly contextWindowTokens: number
+	readonly estimatedTokens: number
+	readonly force?: boolean
+	/**
+	 * Skip the tool-result pre-pass and go straight to the boundary search.
+	 *
+	 * The two steps are sequential in a real pass: clear first, install the
+	 * result, and if that was not enough relief, plan a cut over the history
+	 * you just edited. Returning both from one call would mean nesting a
+	 * union inside a union and computing a boundary the caller may never
+	 * use; asking twice says what is happening.
+	 */
+	readonly skipToolResultClear?: boolean
+}
+
+/**
+ * How many characters a message's content is worth.
+ *
+ * An image costs far fewer tokens than its base64 length divided by four —
+ * but under-counting it to zero is the worse error: it let a run full of
+ * screenshots read as an empty context.
+ */
+function measureContentChars(content: unknown): number {
+	if (typeof content === 'string') return content.length
+	if (!Array.isArray(content)) return 0
+	let total = 0
+	for (const block of content as readonly Record<string, unknown>[]) {
+		if (block.type === 'text' && typeof block.text === 'string') total += block.text.length
+		else if (block.type === 'image' && typeof block.data === 'string') total += block.data.length
+	}
+	return total
+}
+
+/**
+ * The last index whose tail fits in `budgetTokens`, walking backwards.
+ *
+ * Replaces the naive count boundary and nothing else — the caller runs the
+ * existing `findSafeTrimIndex` search downward from whatever this returns,
+ * so the `tool_use` ↔ `tool_result` pairing guarantee is untouched by
+ * construction rather than by care.
+ *
+ * Floored at one message. A single final message larger than the whole
+ * budget still has to be kept: it is the live turn, and dropping it to
+ * satisfy a size preference would delete the thing the run is answering.
+ *
+ * Exported for its own tests. There used to be a second copy of this in the
+ * phase file with a `__forTests` export beside it; two implementations of
+ * one boundary calculation is the failure this extraction exists to end, so
+ * the phase's copy is gone and its tests point here.
+ */
+export function naiveKeepStartByTokens(messages: readonly Message[], budgetTokens: number): number {
+	let tokens = 0
+	let start = messages.length
+	for (let index = messages.length - 1; index >= 0; index--) {
+		const cost = Math.ceil(measureContentChars(messages[index]?.content) / CHARS_PER_TOKEN)
+		// Checked BEFORE adding, so the boundary never includes a message
+		// that pushes the tail over. Adding first and trimming after would
+		// admit one oversized message on every run.
+		if (start < messages.length && tokens + cost > budgetTokens) break
+		tokens += cost
+		start = index
+	}
+	return start
+}
+
+export function planCompaction(input: CompactionPlanInput): CompactionPlan {
+	const { config, estimatedTokens, contextWindowTokens: budget } = input
+
+	if (!input.skipToolResultClear && config.clearToolResults !== false) {
+		const edit = clearStaleToolResults(input.messages, {
+			...(config.keepRecentToolResults !== undefined
+				? { keepRecentToolResults: config.keepRecentToolResults }
+				: {}),
+			...(config.minToolResultCharsToClear !== undefined
+				? { minCharsToClear: config.minToolResultCharsToClear }
+				: {}),
+			...(config.preserveToolResultsFrom ? { preserveTools: config.preserveToolResultsFrom } : {}),
+		})
+
+		if (edit.clearedCount > 0) {
+			const reclaimedTokens = Math.ceil(edit.charsReclaimed / CHARS_PER_TOKEN)
+			// NOT on a forced pass. A forced pass runs because the provider
+			// REJECTED the prompt as too long, which is a measurement — and
+			// answering it with the same estimate the provider just refuted
+			// would declare success after clearing one result and hand back a
+			// history that overflows again on the retry.
+			const reliefWasEnough =
+				!input.force && (estimatedTokens - reclaimedTokens) / budget < config.triggerThreshold
+			return {
+				kind: 'cleared',
+				messages: edit.messages,
+				clearedCount: edit.clearedCount,
+				charsReclaimed: edit.charsReclaimed,
+				reclaimedTokens,
+				reliefWasEnough,
+			}
+		}
+	}
+
+	const messages = input.messages
+	if (messages.length < config.keepRecentMessages + 2) {
+		return { kind: 'skip', reason: 'too_few_messages' }
+	}
+
+	const systemMessages: Message[] = []
+	for (const msg of messages) {
+		if (msg.role !== 'system') break
+		systemMessages.push(msg)
+	}
+	if (systemMessages.length === 0) return { kind: 'skip', reason: 'no_system_floor' }
+
+	// Tool-pair atomicity. A naive cut at `length - keepRecentMessages` can
+	// land BETWEEN an assistant-with-toolCalls (dropped into `older`) and its
+	// `tool` results (kept in `recent`), leaving orphaned `tool_result`
+	// blocks at the head of the recent window. The provider then emits a
+	// `tool_result` with no matching `tool_use` and the API rejects the next
+	// turn — so compaction, whose whole job is to keep a long run alive,
+	// kills it instead. Snap the boundary backward to a safe point.
+	const naiveKeepStart =
+		config.keepRecentTokens === undefined
+			? messages.length - config.keepRecentMessages
+			: naiveKeepStartByTokens(messages, config.keepRecentTokens)
+	let keepStart = -1
+	for (let candidate = naiveKeepStart; candidate > systemMessages.length; candidate--) {
+		if (findSafeTrimIndex(messages as Message[], candidate) === candidate) {
+			keepStart = candidate
+			break
+		}
+	}
+
+	// No safe boundary at or below naive. Either every candidate splits a
+	// pair-set — one assistant fanning out more calls than the recent window
+	// holds — or naive itself sits inside the leading system prefix, which
+	// would duplicate those prompts into `recent`. Skipping costs one
+	// iteration's headroom; cutting anyway costs the live turn, and the
+	// condition is self-clearing.
+	if (keepStart < 0) return { kind: 'skip', reason: 'no_safe_cut' }
+
+	const recentMessages = messages.slice(keepStart)
+	const olderMessages = messages.slice(systemMessages.length, keepStart)
+
+	// Nothing meaningful to compact — skip rather than thrash the permanent
+	// leading floor every iteration, and avoid a model call with no older
+	// history to summarise.
+	//
+	// UNREACHABLE at the current constant, and kept anyway. The loop above
+	// requires `candidate > systemMessages.length`, so `keepStart` is at
+	// least one past the floor and `olderMessages` is never shorter than
+	// one — which is exactly the threshold. Moved here verbatim with the
+	// rest of the pass and left in place because it is the guard that stops
+	// the pass paying for a summary of nothing, and the two constants it
+	// relates are independent: raise this to 2, or relax the loop bound to
+	// `>=`, and it starts firing. Said out loud so nobody reads the branch
+	// as covered, and so nobody deletes it as dead.
+	if (olderMessages.length < MIN_OLDER_MESSAGES_TO_COMPACT) {
+		return { kind: 'skip', reason: 'too_few_older' }
+	}
+
+	return { kind: 'plan', systemMessages, olderMessages, recentMessages, keepStart }
+}
+
+/**
+ * Below this, a pass would summarise almost nothing and pay a model call to
+ * do it.
+ */
+export const MIN_OLDER_MESSAGES_TO_COMPACT = 1

package/src/compaction/summary.ts

@@ -0,0 +1,31 @@
+import { createSystemMessage } from '../types/message/index.js'
+import type { Message } from '../types/message/index.js'
+
+/**
+ * The one marker that says a message is a compaction summary.
+ *
+ * It lived in the iteration phase, which is a layer above this module, so
+ * anything down here that needed it — a host-callable compaction, for one —
+ * either could not reach it or would have had to import upward. Two copies
+ * of the string is the other way that goes, and then a rename in one of
+ * them makes every prior summary invisible to the check that drops it.
+ */
+export const COMPACTION_HEADER =
+	'[COMPACTED CONTEXT] The following is a structured summary of the conversation so far.'
+
+/**
+ * Identity check for a prior compaction summary in the leading floor.
+ *
+ * Used to REPLACE one in place, so at most one `[COMPACTED CONTEXT]` block
+ * ever lives in the never-trimmed floor, and by the checkpoint-restore path
+ * to PRESERVE the summary across a resume — it is the only surviving record
+ * of the older history a run compacted away.
+ */
+export function isCompactionMessage(content: string | null | undefined): boolean {
+	return typeof content === 'string' && content.startsWith(COMPACTION_HEADER)
+}
+
+/** The summary, as the system message that replaces what it summarises. */
+export function buildCompactionMessage(body: string): Message {
+	return createSystemMessage(`${COMPACTION_HEADER}\n\n${body}`)
+}

package/src/compaction/verifier.ts

@@ -1,5 +1,5 @@
 import type { CompactionConfig } from '../config/runtime.js'
-import { collect } from '../provider/collect.js'
+import { collectChatCompletion } from '../provider/collect-chat-completion.js'
 import type { TokenUsage } from '../types/common/index.js'
 import type { Message } from '../types/message/index.js'
 import type { LLMProvider } from '../types/provider/interface.js'
@@ -96,7 +96,7 @@ export async function buildVerifiedSummary(
 		},
 	]
 
-	const response = await collect(
+	const response = await collectChatCompletion(
 		provider.chatStream({
 			model: model ?? '',
 			messages: verificationMessages,

package/src/config/registry.ts

@@ -0,0 +1,208 @@
+import type { ZodType, ZodTypeDef } from 'zod'
+
+import { type ConfigOverrideStore, InMemoryConfigOverrideStore } from '../store/config/index.js'
+import { type Logger, resolveLogger } from '../utils/logger.js'
+
+/**
+ * Configuration a plugin declares and an operator retunes while a run is
+ * live.
+ *
+ * `config/runtime.ts` is one Zod schema parsed once into `RUNTIME_DEFAULTS`
+ * and threaded around as a frozen object. Every section in it is one the SDK
+ * author anticipated — taskRouter, compaction, agentBus, plugins, sandbox —
+ * and nothing in `config/` watches, subscribes or changes. So a plugin has
+ * no way to expose an operator-editable section of its own, and retuning one
+ * knob means rebuilding the config object and restarting whatever consumed
+ * it.
+ *
+ * **Live is the whole point.** A registry that resolved a value once and
+ * handed it out would be the frozen object again with more ceremony. The
+ * driver in this same change is the MCP reconnect supervisor, which reads
+ * `get()` on every attempt — so raising `maxAttempts` during an outage takes
+ * effect on the next retry rather than on the next process.
+ *
+ * Programmatic surface only: no JSON-schema export for a UI, and no
+ * redaction. A secret in a config value is the vault's problem, and a
+ * redactor here would be a second, weaker one.
+ */
+
+export interface ConfigScope<T> {
+	/**
+	 * The resolved value, now.
+	 *
+	 * Synchronous and cheap: consumers read it inside loops and timers, and
+	 * an async read would make every one of them async for a value already in
+	 * memory.
+	 */
+	get(): T
+	/**
+	 * Merge a patch over the override layer and re-validate.
+	 *
+	 * Throws on a schema-invalid result, leaving the previous value in place
+	 * and firing no watcher — validate then assign, never the reverse.
+	 * `refuse-do-not-degrade`: a config that accepted a bad value and clamped
+	 * it would leave an operator believing they had set something they had
+	 * not.
+	 */
+	update(patch: Partial<T> | Record<string, unknown>): T
+	/** Called after a successful update. Returns an unsubscribe. */
+	watch(listener: (next: T, previous: T) => void): () => void
+}
+
+export class ConfigNamespaceCollisionError extends Error {
+	constructor(readonly namespace: string) {
+		super(
+			`Configuration namespace "${namespace}" is already registered. Two owners of one namespace means whichever registered second silently decides the schema, so this refuses instead.`,
+		)
+		this.name = 'ConfigNamespaceCollisionError'
+	}
+}
+
+export interface ConfigRegistryOptions {
+	/**
+	 * Where overrides persist. Defaults to memory, which is honest for a
+	 * process that has not been told where to keep them.
+	 */
+	readonly store?: ConfigOverrideStore
+	readonly log?: Logger
+	/**
+	 * Prefix for this registry's store keys. Set by {@link ConfigRegistry.scope}.
+	 *
+	 * Two concurrent runs share a process and a store; without a prefix the
+	 * second would read the first's overrides and retune it.
+	 */
+	readonly scopeId?: string
+}
+
+/**
+ * Output first, input pinned to `unknown` — the shape every other schema
+ * field in this tree uses (`ConnectorDefinition.configSchema`,
+ * `ToolDefinition.inputSchema`).
+ *
+ * Not decoration. `ZodType<T>` alone leaves the input parameter free, so `T`
+ * infers from the schema's INPUT as well as its output, and every `.default()`
+ * field comes back optional: `get().attempts` types as `number | undefined`
+ * for a field that always has a value. What is parsed here really is
+ * `unknown` — a persisted override is whatever was on disk.
+ */
+type ConfigSchema<T> = ZodType<T, ZodTypeDef, unknown>
+
+interface Entry<T> {
+	readonly schema: ConfigSchema<T>
+	readonly base: Record<string, unknown>
+	override: Record<string, unknown>
+	resolved: T
+	readonly watchers: Set<(next: T, previous: T) => void>
+}
+
+export class ConfigRegistry {
+	private readonly entries = new Map<string, Entry<unknown>>()
+	private readonly store: ConfigOverrideStore
+	private readonly persisted: Record<string, unknown>
+	private readonly log: Logger
+	private readonly scopeId: string | undefined
+
+	constructor(options: ConfigRegistryOptions = {}) {
+		this.store = options.store ?? new InMemoryConfigOverrideStore()
+		this.persisted = this.store.load()
+		this.log = resolveLogger(options.log).child({ 'namzu.log.scope': 'config/registry' })
+		this.scopeId = options.scopeId
+	}
+
+	/**
+	 * A registry for one run, sharing this one's store.
+	 *
+	 * Namespaces and watchers are per scope — two concurrent runs cannot see
+	 * or retune each other — while the store is shared so an operator's
+	 * override written under one scope is not lost when it ends. The same
+	 * arrangement `ScopedConnectorRegistry` uses, keyed the same way.
+	 */
+	scope(scopeId: string): ConfigRegistry {
+		return new ConfigRegistry({
+			store: this.store,
+			log: this.log,
+			scopeId: this.scopeId ? `${this.scopeId}:${scopeId}` : scopeId,
+		})
+	}
+
+	register<T>(
+		namespace: string,
+		schema: ConfigSchema<T>,
+		options: { readonly base?: Record<string, unknown> } = {},
+	): ConfigScope<T> {
+		if (this.entries.has(namespace)) throw new ConfigNamespaceCollisionError(namespace)
+
+		const base = options.base ?? {}
+		const override = asRecord(this.persisted[this.storeKey(namespace)])
+		// Schema defaults, then the plugin's declared base, then the operator's
+		// override — and the whole thing through the schema, so a persisted
+		// override written against an older shape is refused at registration
+		// rather than at the first read.
+		const entry: Entry<T> = {
+			schema,
+			base,
+			override,
+			resolved: schema.parse({ ...base, ...override }),
+			watchers: new Set(),
+		}
+		this.entries.set(namespace, entry as Entry<unknown>)
+
+		return {
+			get: () => entry.resolved,
+			update: (patch) => this.applyUpdate(namespace, entry, patch),
+			watch: (listener) => {
+				entry.watchers.add(listener)
+				return () => entry.watchers.delete(listener)
+			},
+		}
+	}
+
+	/** Namespaces registered on THIS scope. */
+	namespaces(): readonly string[] {
+		return [...this.entries.keys()].sort()
+	}
+
+	private applyUpdate<T>(
+		namespace: string,
+		entry: Entry<T>,
+		patch: Record<string, unknown> | Partial<T>,
+	): T {
+		const candidateOverride = { ...entry.override, ...(patch as Record<string, unknown>) }
+		// Parsed BEFORE anything is assigned. An implementation that assigned
+		// and then validated would leave the bad value readable through
+		// `get()` for the duration of the throw, and would have already told
+		// every watcher about it.
+		const next = entry.schema.parse({ ...entry.base, ...candidateOverride })
+
+		const previous = entry.resolved
+		entry.override = candidateOverride
+		entry.resolved = next
+		this.store.save(this.storeKey(namespace), candidateOverride)
+
+		for (const watcher of entry.watchers) {
+			try {
+				watcher(next, previous)
+			} catch (err) {
+				// Caught, not propagated — the same trade `MCPClient.emitLifecycle`
+				// already makes. A watcher is host-supplied code, and letting one
+				// throw out of `update` would roll a successful configuration
+				// change back into an exception for every other watcher too.
+				this.log.warn('a config watcher threw', {
+					'namzu.config.namespace': namespace,
+					'exception.message': err instanceof Error ? err.message : String(err),
+				})
+			}
+		}
+		return next
+	}
+
+	private storeKey(namespace: string): string {
+		return this.scopeId ? `${this.scopeId}:${namespace}` : namespace
+	}
+}
+
+function asRecord(value: unknown): Record<string, unknown> {
+	return typeof value === 'object' && value !== null && !Array.isArray(value)
+		? { ...(value as Record<string, unknown>) }
+		: {}
+}

package/src/config/runtime.ts

@@ -45,6 +45,21 @@ export const CompactionConfigSchema = z.object({
 	 */
 	resetThreshold: z.number().min(0).max(1).default(0.4),
 	keepRecentMessages: z.number().int().positive().default(4),
+	/**
+	 * Size the retained tail by TOKENS instead of by message count.
+	 *
+	 * A count cannot express what the tail costs. Four messages is four
+	 * short turns or three short turns and a 200 KB tool result, and in the
+	 * second case the tail alone can approach `resetThreshold` — the pass
+	 * completes, reports it did not reach the threshold, leaves the trigger
+	 * armed, and the next iteration pays another summarization call and
+	 * busts the prompt-cache prefix again.
+	 *
+	 * Absent means the count is used, exactly as before. Set, it replaces
+	 * only the NAIVE boundary; the safe-cut search that keeps a `tool_use`
+	 * with its `tool_result` runs from there unchanged.
+	 */
+	keepRecentTokens: z.number().int().positive().optional(),
 
 	/**
 	 * Before summarizing destructively, clear the OUTPUT of old, large tool
@@ -64,6 +79,18 @@ export const CompactionConfigSchema = z.object({
 	 * summarization.
 	 */
 	clearToolResults: z.boolean().default(true),
+	/**
+	 * Record what each pass removes, as a `compaction_shed` event.
+	 *
+	 * On by default: without it the shed content exists nowhere afterwards
+	 * — not in memory, not in `messages.json`, not in the transcript — and
+	 * "what did the agent decide three compactions ago" is unanswerable.
+	 *
+	 * Off is for an operator with a transcript-size constraint, and it is a
+	 * real trade: the transcript grows by roughly what the compaction saved
+	 * in context, since the whole point is that the bodies are kept.
+	 */
+	recordShedHistory: z.boolean().default(true),
 	/** Most recent tool results left alone — the agent is likely still using them. */
 	keepRecentToolResults: z.number().min(0).default(3),
 	/**

package/src/connector/BaseConnector.ts

@@ -1,4 +1,5 @@
 import type { z } from 'zod'
+import { NAMZU } from '../constants/telemetry/index.js'
 import type {
 	AuthConfig,
 	ConnectionType,
@@ -8,7 +9,8 @@ import type {
 	ConnectorMethod,
 } from '../types/connector/index.js'
 import type { ConnectorId } from '../types/ids/index.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'
 
 export abstract class BaseConnector<TConfig = unknown> implements ConnectorLifecycle<TConfig> {
 	abstract readonly id: ConnectorId
@@ -22,8 +24,11 @@ export abstract class BaseConnector<TConfig = unknown> implements ConnectorLifec
 	protected config: TConfig | null = null
 	protected auth: AuthConfig | undefined
 
-	constructor() {
-		this.log = getRootLogger().child({ component: this.constructor.name })
+	constructor(log?: Logger) {
+		this.log = resolveLogger(log).child({
+			[SCOPE_ATTRIBUTE]: 'connector/base',
+			[NAMZU.CONNECTOR_TYPE]: this.constructor.name,
+		})
 	}
 
 	abstract connect(config: TConfig, auth?: AuthConfig): Promise<void>

package/src/connector/builtins/http.ts

@@ -8,6 +8,7 @@ import type {
 	HttpRequestInput,
 	HttpResponseOutput,
 } from '../../types/connector/index.js'
+import { asConnectorId } from '../../utils/id.js'
 import { BaseConnector } from '../BaseConnector.js'
 
 const HttpConnectorConfigSchema = z.object({
@@ -38,8 +39,17 @@ function stripTrailingSlashes(value: string): string {
 	return value.slice(0, end)
 }
 
+/**
+ * Checked once at module load, not per instance.
+ *
+ * `'conn_http' as const` typed this as its own literal, which satisfied
+ * `ConnectorId` only because the id types are still structural. The
+ * constructor is what makes the prefix a fact rather than a spelling.
+ */
+const HTTP_CONNECTOR_ID = asConnectorId('conn_http')
+
 export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
-	readonly id = 'conn_http' as const
+	readonly id = HTTP_CONNECTOR_ID
 	readonly name = 'HTTP Connector'
 	readonly description = 'Generic HTTP/REST API connector for making HTTP requests'
 	readonly connectionType: ConnectionType = 'http'
@@ -67,7 +77,7 @@ export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
 			Object.assign(this.defaultHeaders, this.resolveAuthHeaders(auth))
 		}
 
-		this.log.info(`HTTP connector connected to ${this.baseUrl}`)
+		this.log.info('HTTP connector connected', { 'namzu.connector.base_url': this.baseUrl })
 	}
 
 	async disconnect(): Promise<void> {

package/src/connector/builtins/webhook.ts

@@ -9,6 +9,7 @@ import type {
 	WebhookSendInput,
 	WebhookSendOutput,
 } from '../../types/connector/index.js'
+import { asConnectorId } from '../../utils/id.js'
 import { BaseConnector } from '../BaseConnector.js'
 
 const WebhookConnectorConfigSchema = z.object({
@@ -24,8 +25,11 @@ const WebhookSendInputSchema = z.object({
 	url: z.string().url().optional(),
 })
 
+/** Checked once at module load — see `HttpConnector`'s own constant. */
+const WEBHOOK_CONNECTOR_ID = asConnectorId('conn_webhook')
+
 export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
-	readonly id = 'conn_webhook' as const
+	readonly id = WEBHOOK_CONNECTOR_ID
 	readonly name = 'Webhook Connector'
 	readonly description = 'Send webhook payloads to configured endpoints with optional HMAC signing'
 	readonly connectionType: ConnectionType = 'webhook'
@@ -55,7 +59,7 @@ export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
 			this.defaultHeaders.Authorization = `Bearer ${auth.credentials.token}`
 		}
 
-		this.log.info(`Webhook connector connected to ${this.url}`)
+		this.log.info('Webhook connector connected', { 'namzu.connector.url': this.url })
 	}
 
 	async disconnect(): Promise<void> {