@namzu/sdk 45.1.0 → 48.0.0

package/src/public-types.ts

@@ -39,6 +39,23 @@ export type {
 	SupervisorPlan,
 } from './directory/derive-supervisor.js'
 export type * from './types/toolset/index.js'
+// The toolset layer (plan.md §1): the unit every tool comes from, and its
+// composable wrappers. `ToolSource`/`ToolSourceKind` above are the ones
+// `Toolset.source` and `toolset()` use — this only adds what is new.
+export type {
+	ToolFilterSelector,
+	ToolPredicate,
+	Toolset,
+	ToolsetAvailability,
+	ToolSourceRef,
+} from './toolsets/types.js'
+export type {
+	AgentCapability,
+	Capability,
+	CapabilityModelSettings,
+	CapabilityRunContext,
+	DynamicCapability,
+} from './capabilities/index.js'
 export type * from './types/permission/index.js'
 export type * from './types/errors/index.js'
 export type * from './types/provider/index.js'
@@ -183,11 +200,7 @@ export type {
 	Timestamped,
 } from './store/index.js'
 
-export type {
-	ManagedRegistryConfig,
-	ToolExecutionResult,
-	ToolRegistryForkOptions,
-} from './registry/index.js'
+export type { ManagedRegistryConfig } from './registry/index.js'
 
 export type { PluginLifecycleManagerConfig } from './plugin/lifecycle.js'
 export type {
@@ -242,7 +255,7 @@ export type {
 export type {
 	ConnectorRouterInput,
 	ConnectorToolConfig,
-	ConnectorToolRouterConfig,
+	ConnectorTools,
 	ConnectorToolStrategy,
 } from './connector/tools/index.js'
 
@@ -272,6 +285,7 @@ export type { PermissionPreset } from './authorization/index.js'
 export type { EvaluateRuleOptions } from './authorization/rules.js'
 export type {
 	ShellCommand,
+	NestedShellCommand,
 	ShellLexOptions,
 	ShellLexResult,
 	ShellRedirection,
@@ -403,6 +417,7 @@ export type {
 	ReviewExemption,
 	ReviewMode,
 	ReviewPolicyOptions,
+	ScreenConsentRecord,
 	ToolReviewAnswer,
 	ToolReviewPrompt,
 	ToolReviewRequest,
@@ -671,11 +686,55 @@ export type {
 	ScheduleBrowserSiteLevel,
 	ScheduleConfirmAnswer,
 	ScheduleConfirmRequest,
+	ScheduleJobChanges,
 	ScheduleJobDraft,
 	ScheduleJobPreview,
 	ScheduleJobSummary,
+	ScheduleJobUpdateProposal,
 	ScheduleRuleEffect,
 	ScheduleToolHost,
+	ScheduleUpdateRequest,
 	SessionLoop,
 	SessionLoopHost,
 } from './tools/schedules/index.js'
+
+// ─── system events + peer messaging (@experimental) ───────────────────────
+
+export type {
+	FormatSystemEventOptions,
+	SystemEvent,
+	SystemEventBody,
+	SystemEventKind,
+	SystemEventStatus,
+	SystemEventUsage,
+} from './runtime/system-events.js'
+
+export type { PeerAddress } from './peers/address.js'
+export type {
+	HardenPeerDirectory,
+	PeerRuntimeDir,
+	ResolvePeerRuntimeDirOptions,
+} from './peers/dir.js'
+export type { PeerRecord } from './peers/record.js'
+export type { ListLivePeersOptions, PeerLivenessOptions } from './peers/registry.js'
+export type {
+	DeliverRequest,
+	DeliverResponse,
+	DeliverStatus,
+	NoticeRequest,
+	NoticeResponse,
+	PeerFrom,
+	PeerNoticeAbout,
+	PeerNoticePayload,
+	PeerRequest,
+	PeerResponse,
+	PeerSessionKind,
+	PeerSessionState,
+	PingRequest,
+	PingResponse,
+	SubscribeIdleRequest,
+	SubscribeIdleResponse,
+} from './peers/protocol.js'
+export type { CreatePeerEndpointOptions, PeerEndpoint } from './peers/endpoint.js'
+export type { PeerClientOptions, PeerClientResult } from './peers/client.js'
+export type { PeerMessageEnvelopeInput } from './peers/envelope.js'

package/src/read-model/registry.ts

@@ -1,3 +1,4 @@
+import { RegistryCollisionError } from '../registry/collision.js'
 import type { SessionRecord } from '../types/session/index.js'
 
 /**
@@ -70,11 +71,15 @@ export class UnknownReadModelError extends Error {
 }
 
 /** Two models claiming one id. */
-export class ReadModelCollisionError extends Error {
+export class ReadModelCollisionError extends RegistryCollisionError {
 	readonly details: { id: string }
 
 	constructor(details: { id: string }) {
-		super(`A read model with id "${details.id}" is already registered.`)
+		super(
+			'ReadModelRegistry',
+			details.id,
+			`A read model with id "${details.id}" is already registered.`,
+		)
 		this.name = 'ReadModelCollisionError'
 		this.details = details
 	}

package/src/registry/ManagedRegistry.ts

@@ -2,6 +2,7 @@ import { NAMZU } from '../constants/telemetry/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
 import { BaseRegistry } from './BaseRegistry.js'
+import { RegistryCollisionError, type RegistryCollisionPolicy } from './collision.js'
 
 export interface ManagedRegistryConfig<TDefinition> {
 	componentName: string
@@ -12,17 +13,31 @@ export interface ManagedRegistryConfig<TDefinition> {
 	 */
 	computeId?: (item: TDefinition) => string
 	logger?: Logger
+	/**
+	 * What to do when `register` is given an id already present.
+	 *
+	 * Defaults to `'throw'`. Pass `'warn-overwrite'` or `'warn-skip'` only for
+	 * a registry that genuinely means one of those (see
+	 * {@link RegistryCollisionPolicy}). A single call that needs to replace
+	 * one entry on an otherwise-`'throw'` registry calls {@link ManagedRegistry.replace}
+	 * instead of changing the registry's policy.
+	 */
+	onCollision?: RegistryCollisionPolicy
 }
 
 export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 	protected log: Logger
 	private idField?: keyof TDefinition & string
 	private computeId?: (item: TDefinition) => string
+	private componentName: string
+	private onCollision: RegistryCollisionPolicy
 
 	constructor(config: ManagedRegistryConfig<TDefinition>) {
 		super()
 		this.idField = config.idField
 		this.computeId = config.computeId
+		this.componentName = config.componentName
+		this.onCollision = config.onCollision ?? 'throw'
 		this.log = resolveLogger(config.logger).child({
 			[SCOPE_ATTRIBUTE]: 'registry',
 			[NAMZU.REGISTRY_NAME]: config.componentName,
@@ -46,8 +61,8 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 			}
 			const id = idOrItem
 			const item = maybeItem
-			if (this.has(id)) {
-				this.log.warn('Already registered, overwriting', { 'namzu.registry.item_id': id })
+			if (this.has(id) && !this.applyCollisionPolicy(id)) {
+				return
 			}
 			super.register(id, item)
 			this.log.debug('Registered', { 'namzu.registry.item_id': id })
@@ -64,8 +79,8 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 			throw new Error('register(item) requires idField or computeId to be configured')
 		}
 
-		if (this.has(id)) {
-			this.log.warn('Already registered, overwriting', { 'namzu.registry.item_id': id })
+		if (this.has(id) && !this.applyCollisionPolicy(id)) {
+			return
 		}
 		super.register(id, item)
 		// `debug`, not `info`. Registration is the startup path doing exactly
@@ -75,8 +90,8 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 		// failure as silence with the sign flipped — the interesting lines are
 		// there, and nobody can find them.
 		//
-		// The overwrite case above stays at `warn`, because a second
-		// registration under a live id IS news.
+		// The overwrite case above stays at `warn` (or throws), because a
+		// second registration under a live id IS news.
 		//
 		// Found by running the CLI against a real provider rather than a mock.
 		// Every unit test here asserts on a logger stub, so the LEVEL was
@@ -85,6 +100,42 @@ export class ManagedRegistry<TDefinition> extends BaseRegistry<TDefinition> {
 		this.log.debug('Registered', { 'namzu.registry.item_id': id })
 	}
 
+	/**
+	 * Register `item` under `id`, replacing whatever is already there —
+	 * regardless of this registry's {@link RegistryCollisionPolicy}.
+	 *
+	 * For the one call site that legitimately supersedes an earlier
+	 * registration under the same id (a plugin's status transition, a
+	 * reload) — not a registry-wide escape hatch. A registry whose intended
+	 * behaviour IS overwrite-by-default declares `onCollision: 'warn-overwrite'`
+	 * instead of routing every caller through this method.
+	 */
+	replace(id: string, item: TDefinition): void {
+		const existed = this.has(id)
+		super.register(id, item)
+		this.log.debug(existed ? 'Replaced' : 'Registered', { 'namzu.registry.item_id': id })
+	}
+
+	/**
+	 * Runs this registry's {@link RegistryCollisionPolicy} for an id already
+	 * present. Returns `true` when the caller should proceed to overwrite,
+	 * `false` when it should leave the existing item alone.
+	 */
+	private applyCollisionPolicy(id: string): boolean {
+		switch (this.onCollision) {
+			case 'throw':
+				throw new RegistryCollisionError(this.componentName, id)
+			case 'warn-skip':
+				this.log.warn('Already registered, keeping existing', {
+					'namzu.registry.item_id': id,
+				})
+				return false
+			default:
+				this.log.warn('Already registered, overwriting', { 'namzu.registry.item_id': id })
+				return true
+		}
+	}
+
 	getOrThrow(id: string): TDefinition {
 		const item = this.get(id)
 		if (!item) {

package/src/registry/collision.ts

@@ -0,0 +1,64 @@
+/**
+ * What a registry does when a second item claims an id it already holds.
+ *
+ * Nine `*CollisionError` classes existed across the SDK before this file did
+ * (tool, host command, config namespace, prompt contribution, read model,
+ * invariant, probe, provider — see `RegistryCollisionError` below), each
+ * hand-rolled, and a handful of registries never threw at all —
+ * `ManagedRegistry.register` warned and overwrote by default, `AdvisorRegistry`
+ * and the two connector managers (`manager/connector/environment.ts`,
+ * `tenant.ts`) warned and kept the original, and `SkillRegistry.add` did
+ * neither, in total silence. This file gives the concept a shared
+ * vocabulary, and every one of those registries now throws on a duplicate id
+ * by default (`RegistryCollisionError` or a domain-specific subclass); a
+ * caller that genuinely means to replace an existing entry says so
+ * explicitly at the call site.
+ */
+
+/**
+ * A named collision policy for a `ManagedRegistry`.
+ *
+ * - `'throw'` (default): raise a {@link RegistryCollisionError} naming this
+ *   registry and the id, and leave the existing item in place. Right for
+ *   every registry here unless a caller can name a reason a second
+ *   registration under one id should not be a bug.
+ * - `'warn-overwrite'`: log a warning and replace the existing item.
+ *   `ToolRegistry` used to keep this policy for its own `register`, so a
+ *   host mounting the same tool twice (once a legitimate, common shape)
+ *   kept working unchanged; that class is gone now (plan.md v3 §2) — a
+ *   `ToolManager`'s toolsets throw `ToolsetConflictError` on any collision
+ *   instead, naming both sources, with no overwrite mode at all.
+ * - `'warn-skip'`: log a warning and keep the existing item — the one being
+ *   registered is discarded.
+ *
+ * A single call that needs to replace an existing entry on a registry whose
+ * policy is `'throw'` passes `{ replace: true }` to that call instead of
+ * changing the registry's policy — see `ManagedRegistry.register`.
+ */
+export type RegistryCollisionPolicy = 'throw' | 'warn-overwrite' | 'warn-skip'
+
+/**
+ * A second item claiming an id a registry already holds.
+ *
+ * The base class every SDK `*CollisionError` extends, so a host that wants
+ * to catch "some registry collided" without naming every concrete error
+ * class can catch this one instead. Each concrete subclass keeps its own
+ * `name`, message and fields exactly as before — this only adds
+ * `registryName` and `collidingId`, which every collision shares by
+ * definition — and `ManagedRegistry`'s own `'throw'` policy (see
+ * {@link RegistryCollisionPolicy}) raises this class directly when a
+ * registry has no domain-specific subclass of its own.
+ */
+export class RegistryCollisionError extends Error {
+	/** Which registry raised this, e.g. `"ToolRegistry"`. */
+	readonly registryName: string
+	/** The id or name two registrations collided on. */
+	readonly collidingId: string
+
+	constructor(registryName: string, collidingId: string, message?: string) {
+		super(message ?? `"${collidingId}" is already registered in ${registryName}.`)
+		this.name = 'RegistryCollisionError'
+		this.registryName = registryName
+		this.collidingId = collidingId
+	}
+}

package/src/registry/command/index.ts

@@ -5,6 +5,7 @@ import type {
 	SerializableHostCommand,
 } from '../../types/command/index.js'
 import { ManagedRegistry } from '../ManagedRegistry.js'
+import { RegistryCollisionError } from '../collision.js'
 
 /**
  * A second command claiming a name that is already taken.
@@ -14,11 +15,13 @@ import { ManagedRegistry } from '../ManagedRegistry.js'
  * skip, rename, refuse to boot — has to catch it narrowly instead of
  * matching on message text.
  */
-export class HostCommandNameCollisionError extends Error {
+export class HostCommandNameCollisionError extends RegistryCollisionError {
 	readonly commandName: string
 
 	constructor(commandName: string) {
 		super(
+			'HostCommandRegistry',
+			commandName,
 			`Host command "/${commandName}" is already registered. Two commands answering to one name shadow each other silently, and which one wins depends on registration order.`,
 		)
 		this.name = 'HostCommandNameCollisionError'
@@ -35,8 +38,9 @@ export class HostCommandNameCollisionError extends Error {
  * right for a tool roster a host assembles deliberately and wrong here.
  * These are operator-facing, and a shadowed command is invisible — it does
  * not fail, it simply never runs, and the one that wins depends on
- * registration order. `ToolRegistry` reaches the same conclusion for the
- * same reason one directory over.
+ * registration order. `ToolManager` (`toolsets/manager.ts`) reaches the
+ * same conclusion for the same reason one directory over — a toolset
+ * collision throws rather than shadowing silently.
  */
 export class HostCommandRegistry extends ManagedRegistry<HostCommandDescriptor> {
 	constructor(logger?: ConstructorParameters<typeof ManagedRegistry>[0]['logger']) {

package/src/registry/index.ts

@@ -1,16 +1,10 @@
 export { BaseRegistry } from './BaseRegistry.js'
+export { RegistryCollisionError } from './collision.js'
+export type { RegistryCollisionPolicy } from './collision.js'
 export { ManagedRegistry } from './ManagedRegistry.js'
 export type { ManagedRegistryConfig } from './ManagedRegistry.js'
 
-export { ToolNameCollisionError, ToolRegistry } from './tool/execute.js'
-export type { ToolExecutionResult, ToolRegistryForkOptions } from './tool/execute.js'
-export {
-	ToolCatalog,
-	createToolCatalogFromRegistry,
-	loadingFromAvailability,
-	toolDefinitionToCatalogEntry,
-} from './toolset/catalog.js'
-export type { ToolCatalogFromRegistryOptions, ToolCatalogSearchOptions } from './toolset/catalog.js'
+export { ToolNameCollisionError, TOOL_NAME_PATTERN, assertToolName } from './tool/execute.js'
 
 export { ConnectorRegistry } from './connector/definitions.js'
 export { ScopedConnectorRegistry } from './connector/scoped.js'

package/src/registry/plugin/index.ts

@@ -3,7 +3,20 @@ import { ManagedRegistry } from '../ManagedRegistry.js'
 
 export class PluginRegistry extends ManagedRegistry<PluginDefinition> {
 	constructor() {
-		super({ componentName: 'PluginRegistry', idField: 'id' })
+		super({
+			componentName: 'PluginRegistry',
+			idField: 'id',
+			// A public projection a host is meant to be able to overwrite —
+			// `PluginLifecycleManager` itself re-registers the same id under
+			// a new status on every enable/disable/error transition, and a
+			// host may write its own record here directly (executable
+			// contribution ownership, not this registry, is the lifecycle's
+			// real guard against a forged status — see `enable()`'s comment
+			// in `plugin/lifecycle.ts`). `ManagedRegistry`'s own default is
+			// `'throw'` now (see `registry/collision.ts`); this registry is
+			// one of the named exceptions.
+			onCollision: 'warn-overwrite',
+		})
 	}
 
 	listByScope(scope: PluginScope): PluginDefinition[] {

package/src/registry/tool/callable.ts

@@ -0,0 +1,36 @@
+import type { ToolManager } from '../../toolsets/manager.js'
+
+/**
+ * The tools a call on this step can reach: present in the manager now,
+ * active, and on the step's allow-list when it has one. In toolset order.
+ *
+ * This is what every "Available: …" a model is shown must say, because a
+ * model takes it literally and calls the next name on it. Two answers used
+ * to build that list separately and disagreed. A refusal echoed the step's
+ * allow-list, which is a snapshot taken when the request was built and so
+ * can name a tool removed since — a connector that disconnected — or
+ * one that is deferred, which the executor refuses. An
+ * unknown-tool error listed the whole roster, which on a narrowed step is
+ * mostly tools the step refuses. Each sent the model to a name the other
+ * one answered, and a run went round between them until it was stopped.
+ *
+ * `allowed` absent means the step is not narrowed. An EMPTY list is a step
+ * that may call nothing, and the answer is then empty too.
+ */
+export function callableToolNames(
+	tools: Pick<ToolManager, 'listNames' | 'availability'>,
+	allowed: readonly string[] | undefined,
+): string[] {
+	const permitted = allowed === undefined ? undefined : new Set(allowed)
+	return tools
+		.listNames()
+		.filter(
+			(name) =>
+				(permitted === undefined || permitted.has(name)) && tools.availability(name) === 'active',
+		)
+}
+
+/** The list as a model reads it: comma-separated, or `(none)`. */
+export function formatToolNames(names: readonly string[]): string {
+	return names.length > 0 ? names.join(', ') : '(none)'
+}