@namzu/sdk 27.1.0 → 28.0.0

package/src/registry/command/kernel-commands.ts

@@ -0,0 +1,110 @@
+import type { HostCommandDescriptor } from '../../types/command/index.js'
+import type { Skill } from '../../types/skills/index.js'
+import { isInvocableBy, skillInvocation } from '../../types/skills/index.js'
+import type { TaskStore } from '../../types/task/index.js'
+
+/**
+ * The commands whose facts the kernel already owns.
+ *
+ * A registry with nothing in it is a declaration, and this repo has a rule
+ * about those. These two are the ones a host currently has to reach into
+ * kernel internals to answer: what work is tracked, and who this run may
+ * delegate to. Both were already computed here and had no way out that did
+ * not go through a specific host's UI code.
+ *
+ * Deliberately NOT here: anything that would need a decision the kernel
+ * cannot make. `/clear` is about a transcript a host owns, `/login` about
+ * credentials a host stores, `/model` about a picker a host draws. Adding
+ * them would mean the SDK either rendering or refusing, and both are worse
+ * than leaving the command with the host that can actually do it.
+ */
+
+export interface KernelCommandOptions {
+	/** Absent is a real state — not every run tracks tasks. */
+	readonly taskStore?: TaskStore
+	readonly allowedAgentIds?: readonly string[]
+	/**
+	 * The run's skills, for the operator-facing half of the listing.
+	 *
+	 * Absent is a real state: a run with no skills registry has none, which
+	 * is different from having none registered.
+	 */
+	readonly skills?: readonly Skill[]
+}
+
+export function kernelHostCommands(options: KernelCommandOptions): HostCommandDescriptor[] {
+	return [
+		{
+			name: 'tasks',
+			description: 'List the work this run is tracking.',
+			hint: 'id, status, owner and subject for every task in the store',
+			async handler() {
+				// REFUSED rather than an empty report. "There are no tasks" and
+				// "this run has no task store" are different answers, and a host
+				// that shows the first for the second gives an operator a
+				// confident zero nobody computed.
+				if (!options.taskStore) {
+					return {
+						kind: 'refused',
+						reason: 'This run has no task store, so there is nothing to list.',
+					}
+				}
+				const tasks = await options.taskStore.list()
+				return {
+					kind: 'report',
+					title: 'Tasks',
+					rows: tasks.map((task) => ({
+						id: task.id,
+						status: task.status,
+						owner: task.owner ?? null,
+						subject: task.subject,
+					})),
+				}
+			},
+		},
+		{
+			name: 'skills',
+			description: 'List the skills an operator may invoke.',
+			hint: 'name, description and policy for every operator-invocable skill',
+			handler() {
+				// Operator-invocable only, which is the point of the split: the
+				// model's manifest and the operator's menu are different lists
+				// drawn from one registry, and a `/skills` that showed
+				// model-only guidance would offer an operator something there
+				// is no way to run.
+				if (!options.skills) {
+					return {
+						kind: 'refused',
+						reason: 'This run has no skills registry, so there is nothing to list.',
+					}
+				}
+				return {
+					kind: 'report',
+					title: 'Skills',
+					rows: options.skills
+						.filter((skill) => isInvocableBy(skill, 'operator'))
+						.map((skill) => ({
+							name: skill.metadata.name,
+							description: skill.metadata.description,
+							invocation: skillInvocation(skill),
+						})),
+				}
+			},
+		},
+		{
+			name: 'agents',
+			description: 'List the agents this run may delegate to.',
+			hint: 'the roster, as the delegation tools see it',
+			handler() {
+				// An empty roster IS the answer here, unlike the store above: the
+				// question is "who may I call", and "nobody" is a complete and
+				// correct reply that a run with delegation off should get.
+				return {
+					kind: 'report',
+					title: 'Agents',
+					rows: (options.allowedAgentIds ?? []).map((id) => ({ id })),
+				}
+			},
+		},
+	]
+}

package/src/registry/connector/scoped.ts

@@ -9,7 +9,8 @@ import type {
 } from '../../types/connector/index.js'
 import { CONNECTOR_SCOPE_ORDER } 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'
 
 function scopeKey(scope: ConnectorScope, scopeId: string, connectorId: ConnectorId): string {
 	return `${scope}:${scopeId}:${connectorId}`
@@ -19,21 +20,21 @@ export class ScopedConnectorRegistry {
 	private configs: Map<string, ScopedConnectorConfig> = new Map()
 	private log: Logger
 
-	constructor() {
-		this.log = getRootLogger().child({ component: 'ScopedConnectorRegistry' })
+	constructor(log?: Logger) {
+		this.log = resolveLogger(log).child({ [SCOPE_ATTRIBUTE]: 'registry/connector/scoped' })
 	}
 
 	set(config: ScopedConnectorConfig): void {
 		const key = scopeKey(config.scope.scope, config.scope.scopeId, config.connectorId)
 		this.configs.set(key, config)
-		this.log.info(`Scoped config set: ${key}`)
+		this.log.info('Scoped config set', { 'namzu.connector.scope_key': key })
 	}
 
 	remove(scope: ScopeRef, connectorId: ConnectorId): boolean {
 		const key = scopeKey(scope.scope, scope.scopeId, connectorId)
 		const removed = this.configs.delete(key)
 		if (removed) {
-			this.log.info(`Scoped config removed: ${key}`)
+			this.log.info('Scoped config removed', { 'namzu.connector.scope_key': key })
 		}
 		return removed
 	}

package/src/registry/index.ts

@@ -1,4 +1,4 @@
-export { Registry } from './Registry.js'
+export { BaseRegistry } from './BaseRegistry.js'
 export { ManagedRegistry } from './ManagedRegistry.js'
 export type { ManagedRegistryConfig } from './ManagedRegistry.js'
 
@@ -17,3 +17,9 @@ export { ScopedConnectorRegistry } from './connector/scoped.js'
 
 export { AgentRegistry } from './agent/definitions.js'
 export { PluginRegistry } from './plugin/index.js'
+
+// Commands a HOST offers its operator — never model-visible, and not tools.
+// The whole vocabulary used to be a literal array in one host's TUI module.
+export { HostCommandNameCollisionError, HostCommandRegistry } from './command/index.js'
+export { kernelHostCommands } from './command/kernel-commands.js'
+export type { KernelCommandOptions } from './command/kernel-commands.js'

package/src/registry/tool/execute.ts

@@ -224,7 +224,7 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 		for (const name of names) {
 			this.getOrThrow(name)
 			this.availability.set(name, 'active')
-			this.log.debug(`Tool activated: ${name}`)
+			this.log.debug('Tool activated', { 'namzu.tool.name': name })
 		}
 	}
 
@@ -232,7 +232,7 @@ export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 		for (const name of names) {
 			this.getOrThrow(name)
 			this.availability.set(name, 'deferred')
-			this.log.debug(`Tool deferred: ${name}`)
+			this.log.debug('Tool deferred', { 'namzu.tool.name': name })
 		}
 	}
 
@@ -474,8 +474,8 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				if (allowed !== undefined && !allowed.includes(toolName)) {
 					const msg = `Tool "${toolName}" is not available on this step. Available: ${allowed.length > 0 ? allowed.join(', ') : '(none)'}`
 					this.log.warn('Blocked a tool outside the step allow-list', {
-						tool: toolName,
-						allowed: allowed.length,
+						[GENAI.TOOL_NAME]: toolName,
+						'namzu.registry.allowed': allowed.length,
 					})
 					span.setAttributes({
 						[NAMZU.TOOL_SUCCESS]: false,
@@ -546,9 +546,10 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						? `Tool "${toolName}" was called with no arguments. ${requiredHint}${recoveryHint} Retry the call with the required parameters populated.`
 						: `Validation failed for "${toolName}": ${errorMessage}. ${requiredHint}${recoveryHint}`
 
-					this.log.error(`Tool input validation failed: ${toolName}`, {
-						errors: errorMessage,
-						empty: isEmptyInput,
+					this.log.error('Tool input validation failed', {
+						'namzu.tool.name': toolName,
+						'namzu.registry.errors': errorMessage,
+						'namzu.registry.empty': isEmptyInput,
 					})
 
 					span.setAttributes({
@@ -567,7 +568,7 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 				const finalInput = parseResult.data
 
 				try {
-					this.log.debug(`Executing tool: ${toolName}`)
+					this.log.debug('Executing tool', { 'namzu.tool.name': toolName })
 					const startedAt = Date.now()
 					const produced = await tool.execute(finalInput, context)
 					// Screened here, which is the only place a result can be
@@ -589,8 +590,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						this.log,
 					)
 					const durationMs = Date.now() - startedAt
-					this.log.debug(`Tool completed: ${toolName}`, {
-						success: result.success,
+					this.log.debug('Tool completed', {
+						'namzu.tool.name': toolName,
+						'namzu.registry.success': result.success,
 					})
 
 					span.setAttribute(NAMZU.TOOL_SUCCESS, result.success)
@@ -624,8 +626,9 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 						throw err
 					}
 					const errorMessage = toErrorMessage(err)
-					this.log.error(`Tool execution error: ${toolName}`, {
-						error: errorMessage,
+					this.log.error('Tool execution error', {
+						'namzu.tool.name': toolName,
+						'exception.message': errorMessage,
 					})
 
 					span.setAttributes({

package/src/registry/tool/presentation.ts

@@ -0,0 +1,116 @@
+import type { ToolRegistryContract, ToolResult } from '../../types/tool/index.js'
+import type { ToolCallView, ToolResultView } from '../../types/tool/presentation.js'
+import { toErrorMessage } from '../../utils/error.js'
+import { SCOPE_ATTRIBUTE } from '../../utils/log/types.js'
+import type { Logger } from '../../utils/logger.js'
+import { resolveLogger } from '../../utils/logger.js'
+
+/**
+ * Asks a tool how it should be shown, and falls back when it has no
+ * opinion.
+ *
+ * The fallback is not a placeholder — it is the exact behaviour one host
+ * had already converged on, moved to where every host can reach it. What
+ * changes is that a tool the host never heard of can now override it.
+ */
+export interface ToolPresenter {
+	presentCall(toolName: string, input: unknown): ToolCallView
+	presentResult(toolName: string, input: unknown, result: ToolResult): ToolResultView
+}
+
+const MAX_LABEL = 120
+
+function truncate(value: string, max = MAX_LABEL): string {
+	const oneLine = value.replace(/\s+/g, ' ')
+	return oneLine.length > max ? `${oneLine.slice(0, max - 1)}…` : oneLine
+}
+
+/**
+ * The label a tool with no opinion gets.
+ *
+ * The pick order is load-bearing and was arrived at by use. `description`
+ * is LAST so it only speaks for a tool none of the others describe — those
+ * tools were falling through to a truncated `JSON.stringify`, which is how
+ * a delegation tool came to show a blob of its own arguments while
+ * requiring the model to write a label nothing then read.
+ */
+export function genericLabel(input: unknown): string {
+	if (input && typeof input === 'object') {
+		const obj = input as Record<string, unknown>
+		const pick = (k: string): string | undefined =>
+			typeof obj[k] === 'string' ? (obj[k] as string) : undefined
+		const primary =
+			pick('command') ??
+			pick('path') ??
+			pick('file_path') ??
+			pick('pattern') ??
+			pick('query') ??
+			pick('description')
+		if (primary) return truncate(primary)
+	}
+	if (typeof input === 'string') return truncate(input)
+	return truncate(JSON.stringify(input ?? {}))
+}
+
+/**
+ * `registry` is the `ToolRegistryContract` a run already holds, so a
+ * presenter never needs its own copy of what is registered — and a tool
+ * added at runtime by a plugin is presentable the moment it is registered.
+ */
+export function createToolPresenter(
+	registry: ToolRegistryContract,
+	logger?: Logger,
+): ToolPresenter {
+	// `SCOPE_ATTRIBUTE`, not a bare `component` key. The 40 bare ones are a
+	// frozen inventory the log gate counts; a new binding has no reason to
+	// join it, and the ratchet caught this one before it did.
+	const log = resolveLogger(logger).child({ [SCOPE_ATTRIBUTE]: 'registry/tool/presentation' })
+
+	/**
+	 * A tool's presenter is host-supplied code running inside a render
+	 * path. A throw here must not take down the surface that was only
+	 * trying to draw a line, so it is caught and reported once — the same
+	 * trade a log sink already makes.
+	 */
+	const guard = <T>(toolName: string, hook: string, fn: () => T | undefined): T | undefined => {
+		try {
+			return fn()
+		} catch (err) {
+			log.warn('a tool presenter threw — falling back to the generic view', {
+				'namzu.tool.name': toolName,
+				'namzu.tool.presenter_hook': hook,
+				'namzu.error.message': toErrorMessage(err),
+			})
+			return undefined
+		}
+	}
+
+	return {
+		presentCall(toolName, input) {
+			const definition = registry.get(toolName)
+			const view = definition?.presentCall
+				? guard(toolName, 'presentCall', () => definition.presentCall?.(input))
+				: undefined
+			return view ?? { kind: 'generic', label: genericLabel(input) }
+		},
+
+		presentResult(toolName, input, result) {
+			const definition = registry.get(toolName)
+			const view = definition?.presentResult
+				? guard(toolName, 'presentResult', () => definition.presentResult?.(input, result))
+				: undefined
+			// Falls back to the RESULT's own text, not the input's label: a
+			// caller asking how to show what came back and getting a
+			// description of what went in is worse than a plain string.
+			//
+			// `terminal` rather than a truncated `generic`, and the whole
+			// output rather than its first 120 characters. A host renders a
+			// result across many rows and does its own clamping — how many
+			// lines fit is a property of a terminal, not of a tool — and
+			// truncating here destroys text no host can then recover. A tool
+			// that wants the one-line form says so by returning a `generic`
+			// view itself, which `edit` and `write` both do.
+			return view ?? { kind: 'terminal', output: result.output ?? '' }
+		},
+	}
+}

package/src/registry/tool/screen.ts

@@ -1,3 +1,4 @@
+import { GENAI } from '../../constants/telemetry/index.js'
 import type {
 	ToolResultGuardrailContext,
 	ToolResultGuardrailSpec,
@@ -53,8 +54,8 @@ async function safely(
 	} catch (err) {
 		const reason = `guardrail "${name}" threw: ${toErrorMessage(err)}`
 		log.error('Tool-result guardrail threw — failing closed', {
-			guardrail: name,
-			error: toErrorMessage(err),
+			'namzu.guardrail.name': name,
+			'exception.message': toErrorMessage(err),
 		})
 		return { action: 'refuse', reason }
 	}
@@ -96,18 +97,18 @@ export async function screenToolResult(
 
 		if (verdict.action === 'halt') {
 			log.error('Tool-result guardrail halted the run', {
-				tool: ctx.toolName,
-				guardrail: label,
-				reason: verdict.reason,
+				[GENAI.TOOL_NAME]: ctx.toolName,
+				'namzu.guardrail.name': label,
+				'namzu.registry.reason': verdict.reason,
 			})
 			throw new ToolResultHalted(label, verdict.reason)
 		}
 
 		if (verdict.action === 'refuse') {
 			log.warn('Tool-result guardrail refused the result', {
-				tool: ctx.toolName,
-				guardrail: label,
-				reason: verdict.reason,
+				[GENAI.TOOL_NAME]: ctx.toolName,
+				'namzu.guardrail.name': label,
+				'namzu.registry.reason': verdict.reason,
 			})
 			return {
 				success: false,
@@ -118,9 +119,9 @@ export async function screenToolResult(
 
 		if (verdict.action === 'rewrite') {
 			log.info('Tool-result guardrail rewrote the result', {
-				tool: ctx.toolName,
-				guardrail: label,
-				reason: verdict.reason,
+				[GENAI.TOOL_NAME]: ctx.toolName,
+				'namzu.guardrail.name': label,
+				'namzu.registry.reason': verdict.reason,
 			})
 			current = verdict.output
 			rewritten = true

package/src/run/drain.ts

@@ -21,6 +21,16 @@
  * per-platform supervisor is the same trade the deployment-adapter matrix
  * was rejected for: one seam beats N adapters.
  *
+ * Read the scope of that narrowly. This paragraph has been cited as the
+ * kernel's refusal of a model-facing "remind me tomorrow" capability, and
+ * it is not one: it says a HOST brings the timer, which presumes the host
+ * has one rather than ruling the capability out. Whether such a capability
+ * should exist -- and if so, as a store plus a host-driven sweep rather
+ * than a daemon here -- is open. `directory/types.ts` records the adjacent
+ * decision that cut a declarative `schedules/` slot, on grounds of
+ * double-fire and timezone; that is a different question from a runtime
+ * tool, and neither text settles the other.
+ *
  * The unit of work is a callback, so this module never needs a provider, a
  * tool registry or a sandbox — the half of a run that cannot be serialized
  * stays with the caller, exactly as `resumeRun` already splits it.
@@ -35,7 +45,7 @@ import type {
 	CheckpointStore,
 	DurableRunEntry,
 	ParkState,
-	RunClaim,
+	RunLease,
 } from '../types/run/checkpoint-store.js'
 
 /** Runs handled per pass when the caller names no page size. */
@@ -55,7 +65,7 @@ export const DEFAULT_DRAIN_PAGE_SIZE = 100
  * onRun: (entry, claim) =>
  *   resumeRun({
  *     ...yourQueryParams,
- *     scope: { ...entry, threadId },
+ *     scope: { ...entry, topicId },
  *     checkpointStore: store,
  *     claimFence: claim.fence,
  *   })
@@ -69,7 +79,7 @@ export const DEFAULT_DRAIN_PAGE_SIZE = 100
  * that died on the first bad run would leave the rest of the queue
  * untouched, which is the failure a queue exists to spread out.
  */
-export type DrainRun = (entry: DurableRunEntry, claim: RunClaim) => void | Promise<void>
+export type DrainRun = (entry: DurableRunEntry, claim: RunLease) => void | Promise<void>
 
 export interface DrainRunsParams {
 	/** Backend to list, claim and release against. Must support all three. */