@namzu/sdk 27.0.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

@@ -4,6 +4,7 @@ import { GENAI, NAMZU, toolSpanName } from '../../telemetry/attributes.js'
 import { recordToolCall } from '../../telemetry/metrics.js'
 import { getTracer } from '../../telemetry/runtime-accessors.js'
 import { isTrustedReadOnly } from '../../tools/trusted-read-only.js'
+import type { ToolResultGuardrailSpec } from '../../types/guardrail/index.js'
 import type {
 	LLMToolSchema,
 	ToolAvailability,
@@ -16,6 +17,7 @@ import type {
 import { toErrorMessage } from '../../utils/error.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
 import { renderToolSchema } from './schema.js'
+import { ToolResultHalted, screenToolResult } from './screen.js'
 
 export type { ToolExecutionResult }
 
@@ -133,10 +135,12 @@ export function describeWithOutput(
 export class ToolRegistry extends ManagedRegistry<ToolDefinition> {
 	private availability: Map<string, ToolAvailability> = new Map()
 	private tierConfig?: ToolTierConfig
+	private resultGuardrails?: readonly ToolResultGuardrailSpec[]
 
 	constructor(config?: ToolRegistryConfig) {
 		super({ componentName: 'ToolRegistry', idField: 'name', logger: config?.logger })
 		this.tierConfig = config?.tierConfig
+		this.resultGuardrails = config?.resultGuardrails
 	}
 
 	override register(id: string, tool: ToolDefinition): void
@@ -220,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 })
 		}
 	}
 
@@ -228,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 })
 		}
 	}
 
@@ -470,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,
@@ -542,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({
@@ -563,12 +568,31 @@ 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 result = await tool.execute(finalInput, context)
+					const produced = await tool.execute(finalInput, context)
+					// Screened here, which is the only place a result can be
+					// examined before anything acts on it: the executor applies
+					// the output budget to what this returns, and compaction
+					// summarises later still. `provenance` is carried in so a
+					// screen can tell a connected server's words from a
+					// first-party tool's — a connector's result is framed with
+					// the server's name, and a screen reading only the value
+					// cannot use that.
+					const result = await screenToolResult(
+						this.resultGuardrails,
+						produced,
+						{
+							toolName,
+							input: finalInput,
+							...(tool.provenance ? { provenance: tool.provenance } : {}),
+						},
+						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)
@@ -587,9 +611,24 @@ Executable tool names, descriptions, and JSON input schemas are attached through
 
 					return result
 				} catch (err) {
+					// A terminal refusal must not be converted into a failed
+					// tool call. Everything below turns an exception into a
+					// result the model reads and works around, which is what
+					// `refuse` is for — doing it to a `halt` would silently
+					// demote the one verdict that says the run must not
+					// continue.
+					if (err instanceof ToolResultHalted) {
+						span.setAttributes({
+							[NAMZU.TOOL_SUCCESS]: false,
+							[NAMZU.TOOL_ERROR]: err.message,
+						})
+						span.setStatus({ code: SpanStatusCode.ERROR, message: err.message })
+						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

@@ -0,0 +1,132 @@
+import { GENAI } from '../../constants/telemetry/index.js'
+import type {
+	ToolResultGuardrailContext,
+	ToolResultGuardrailSpec,
+	ToolResultVerdict,
+} from '../../types/guardrail/index.js'
+import type { ToolResult } from '../../types/tool/index.js'
+import { toErrorMessage } from '../../utils/error.js'
+import type { Logger } from '../../utils/logger.js'
+
+/**
+ * A tool result was refused terminally.
+ *
+ * Thrown rather than returned because the caller's failure path turns every
+ * exception into an ordinary tool failure the model then reads and works
+ * around — which is exactly what a terminal refusal must not become. The
+ * distinct type is what lets that path re-throw this one and convert the
+ * rest. A `halt` reported as a failed tool call would be a `refuse` with
+ * extra steps.
+ */
+export class ToolResultHalted extends Error {
+	readonly guardrail: string
+
+	constructor(guardrail: string, reason: string) {
+		super(`Tool result halted by guardrail "${guardrail}": ${reason}`)
+		this.name = 'ToolResultHalted'
+		this.guardrail = guardrail
+	}
+}
+
+function nameOf(spec: { name?: string }, index: number): string {
+	return spec.name ?? `tool-result-guardrail[${index}]`
+}
+
+function normalize<T>(spec: T | { name: string; check: T }): { name?: string; check: T } {
+	return typeof spec === 'function' ? { check: spec as T } : (spec as { name: string; check: T })
+}
+
+/**
+ * A guardrail that throws FAILS CLOSED, as the run-level ones do.
+ *
+ * `refuse` rather than `halt` for the same reason the tool boundary has a
+ * recoverable refusal at all: a broken screen means this result's safety is
+ * unknown, not that the run is unsalvageable. The model is told and can
+ * choose differently.
+ */
+async function safely(
+	run: () => ToolResultVerdict | Promise<ToolResultVerdict>,
+	name: string,
+	log: Logger,
+): Promise<ToolResultVerdict> {
+	try {
+		return await run()
+	} catch (err) {
+		const reason = `guardrail "${name}" threw: ${toErrorMessage(err)}`
+		log.error('Tool-result guardrail threw — failing closed', {
+			'namzu.guardrail.name': name,
+			'exception.message': toErrorMessage(err),
+		})
+		return { action: 'refuse', reason }
+	}
+}
+
+/**
+ * Screen a tool's result before anything downstream reads it.
+ *
+ * Runs every guardrail in order and stops at the first refusal. Rewrites
+ * compose — each guardrail sees what the previous one produced — matching
+ * the output-guardrail path, so a redaction chain behaves the same at both
+ * boundaries.
+ *
+ * Returns the result to use. A refusal comes back as a failed `ToolResult`
+ * carrying the reason, because that is the shape the model already knows
+ * how to read: it is the same thing a tool that could not do its job
+ * returns, and the alternative — a blank result — tells the model the tool
+ * found nothing, which is a different claim and a false one.
+ */
+export async function screenToolResult(
+	guardrails: readonly ToolResultGuardrailSpec[] | undefined,
+	result: ToolResult,
+	ctx: Omit<ToolResultGuardrailContext, 'output' | 'success'>,
+	log: Logger,
+): Promise<ToolResult> {
+	if (!guardrails || guardrails.length === 0) return result
+
+	let current = result.output
+	let rewritten = false
+
+	for (const [index, spec] of guardrails.entries()) {
+		const { name, check } = normalize(spec)
+		const label = nameOf({ name }, index)
+		const verdict = await safely(
+			() => check({ ...ctx, output: current, success: result.success }),
+			label,
+			log,
+		)
+
+		if (verdict.action === 'halt') {
+			log.error('Tool-result guardrail halted the run', {
+				[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', {
+				[GENAI.TOOL_NAME]: ctx.toolName,
+				'namzu.guardrail.name': label,
+				'namzu.registry.reason': verdict.reason,
+			})
+			return {
+				success: false,
+				output: '',
+				error: `Tool "${ctx.toolName}" produced a result that was refused by guardrail "${label}": ${verdict.reason}`,
+			}
+		}
+
+		if (verdict.action === 'rewrite') {
+			log.info('Tool-result guardrail rewrote the result', {
+				[GENAI.TOOL_NAME]: ctx.toolName,
+				'namzu.guardrail.name': label,
+				'namzu.registry.reason': verdict.reason,
+			})
+			current = verdict.output
+			rewritten = true
+		}
+	}
+
+	return rewritten ? { ...result, output: current } : result
+}

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. */