@namzu/sdk 57.1.0 → 58.0.0

package/src/connector/mcp/client.ts

@@ -6,6 +6,8 @@ import type {
 	MCPConnectionStatus,
 	MCPContentBlock,
 	MCPDiscoverResult,
+	MCPElicitationRequest,
+	MCPElicitationResult,
 	MCPEraCache,
 	MCPEventListener,
 	MCPInitializeResult,
@@ -58,6 +60,7 @@ import { type McpParamHeaderBinding, validateMcpHeaderAnnotations } from './x-mc
 import {
 	DEFAULT_MCP_ERA_PROBE_TIMEOUT_MS,
 	DEFAULT_MCP_REQUEST_TIMEOUT_MS,
+	JSON_RPC_INVALID_PARAMS,
 	JSON_RPC_METHOD_NOT_FOUND,
 	MCP_DISCOVER_METHOD,
 	MCP_LEGACY_VERSIONS,
@@ -243,6 +246,8 @@ export class MCPClient {
 	private subscriptionFailures = 0
 	/** Best-effort protocol cancellations still belong to this connection generation. */
 	private cancellationControllers = new Set<AbortController>()
+	/** Elicitations waiting on the person, by the server's request id. */
+	private elicitationControllers = new Map<string | number, AbortController>()
 	private log: Logger
 	private readonly config: MCPClientConfig
 	private readonly requestTimeoutMs: number
@@ -383,7 +388,10 @@ export class MCPClient {
 		const offered = MCP_LEGACY_VERSIONS[0]
 		const result = (await this.request('initialize', {
 			protocolVersion: offered,
-			capabilities: this.config.capabilities ?? {},
+			capabilities: {
+				...(this.config.capabilities ?? {}),
+				...(this.config.onElicitation ? { elicitation: {} } : {}),
+			},
 			clientInfo: this.config.clientInfo ?? NAMZU_CLIENT_INFO,
 		})) as MCPInitializeResult
 
@@ -1555,6 +1563,13 @@ export class MCPClient {
 			}
 		}
 
+		if (message.method === 'notifications/cancelled' && message.id === undefined) {
+			const requestId = message.params?.requestId
+			if (typeof requestId === 'string' || typeof requestId === 'number') {
+				this.elicitationControllers.get(requestId)?.abort(new Error('Withdrawn by the server'))
+			}
+		}
+
 		if (message.method && message.id === undefined) {
 			for (const handler of this.notificationHandlers) {
 				handler(message.method, message.params)
@@ -1568,6 +1583,15 @@ export class MCPClient {
 		// dropped on the floor, so a spec-current server sat waiting for a
 		// reply that would never come, which looks exactly like a hang.
 		// Answer honestly: we do not implement these yet.
+		if (
+			message.method === 'elicitation/create' &&
+			message.id !== undefined &&
+			this.config.onElicitation &&
+			this.era?.kind === 'legacy'
+		) {
+			void this.answerElicitation(message.id, message.params)
+			return
+		}
 		if (message.method && message.id !== undefined) {
 			this.log.warn('Declining unsupported server-initiated MCP request', {
 				'namzu.connector.server': this.config.serverName,
@@ -1590,6 +1614,68 @@ export class MCPClient {
 		}
 	}
 
+	/**
+	 * Answer one `elicitation/create`: form mode goes to the host's handler,
+	 * anything else is refused as invalid params so the server is never left
+	 * waiting. Only the action is logged, never the values the person typed.
+	 */
+	private async answerElicitation(
+		id: string | number,
+		params: Record<string, unknown> | undefined,
+	): Promise<void> {
+		const handler = this.config.onElicitation
+		const reply = (body: { result: unknown } | { error: { code: number; message: string } }) =>
+			this.transport.send({ jsonrpc: '2.0', id, ...body }).catch((err) => {
+				this.log.debug('Failed to send elicitation reply', {
+					'exception.message': toErrorMessage(err),
+				})
+			})
+		const schema = params?.requestedSchema
+		const isForm = params?.mode === undefined || params.mode === 'form'
+		if (
+			!handler ||
+			!isForm ||
+			typeof params?.message !== 'string' ||
+			typeof schema !== 'object' ||
+			schema === null
+		) {
+			await reply({
+				error: {
+					code: JSON_RPC_INVALID_PARAMS,
+					message: isForm ? 'Invalid elicitation request' : 'Only form elicitation is supported',
+				},
+			})
+			return
+		}
+		const controller = new AbortController()
+		this.elicitationControllers.set(id, controller)
+		this.cancellationControllers.add(controller)
+		let result: MCPElicitationResult
+		try {
+			result = await handler(
+				{
+					serverName: this.config.serverName,
+					message: params.message,
+					requestedSchema: schema as MCPElicitationRequest['requestedSchema'],
+				},
+				{ signal: controller.signal },
+			)
+		} catch (err) {
+			this.log.warn('Elicitation handler failed', { 'exception.message': toErrorMessage(err) })
+			result = { action: 'cancel' }
+		} finally {
+			this.elicitationControllers.delete(id)
+			this.cancellationControllers.delete(controller)
+		}
+		// The server withdrew the request: it is no longer listening.
+		if (controller.signal.aborted) return
+		this.log.info('Elicitation answered', {
+			'namzu.connector.server': this.config.serverName,
+			'namzu.connector.elicitation.action': result.action,
+		})
+		await reply({ result: result.action === 'accept' ? result : { action: result.action } })
+	}
+
 	private handleProgressNotification(params: Record<string, unknown> | undefined): void {
 		const token = params?.progressToken
 		if (typeof token !== 'string') return

package/src/constants/mcp/index.ts

@@ -70,6 +70,9 @@ export const MCP_SUPPORTED_PROTOCOL_VERSIONS: readonly string[] = [
  */
 export const DEFAULT_MCP_REQUEST_TIMEOUT_MS = 30_000
 
+/** JSON-RPC 2.0 reserved code for parameters the receiver cannot accept. */
+export const JSON_RPC_INVALID_PARAMS = -32602
+
 /** JSON-RPC 2.0 reserved code for an unimplemented method. */
 export const JSON_RPC_METHOD_NOT_FOUND = -32601
 

package/src/constants/plugin/index.ts

@@ -32,6 +32,8 @@ export const MAX_MCP_SERVERS_PER_PLUGIN = 5
 export const MAX_SKILLS_PER_PLUGIN = 20
 export const MAX_CONNECTORS_PER_PLUGIN = 10
 export const MAX_PERSONAS_PER_PLUGIN = 5
+export const MAX_COMMAND_DIRS_PER_PLUGIN = 10
+export const MAX_AGENT_DIRS_PER_PLUGIN = 10
 
 /** Hook execution */
 export const HOOK_TIMEOUT_MS = 600_000

package/src/manager/agent/lifecycle.ts

@@ -170,7 +170,7 @@ interface ChildSpawnRecord {
 	/** Removes the child's log from the process-local lookup. */
 	releaseLog?: () => void
 	workspaceRef?: WorkspaceRef
-	workspaceRetention?: 'retain'
+	workspaceRetention?: 'retain' | 'retain-changed'
 	/**
 	 * What this child was actually granted, after the ancestor union.
 	 *
@@ -1739,8 +1739,9 @@ export class AgentManager {
 				subSession = {
 					...subSession,
 					workspaceId: workspaceRef.id,
-					...(request?.mode === 'isolated' && request.retention === 'retain'
-						? { workspaceRetention: 'retain' as const }
+					...(request?.mode === 'isolated' &&
+					(request.retention === 'retain' || request.retention === 'retain-changed')
+						? { workspaceRetention: request.retention }
 						: {}),
 				}
 				await store.updateSubSession(subSession, context.tenantId)
@@ -1781,8 +1782,9 @@ export class AgentManager {
 			childDepth,
 			childOwnerVersion: childSession.ownerVersion,
 			workspaceRef,
-			...(options.workspace?.mode === 'isolated' && options.workspace.retention === 'retain'
-				? { workspaceRetention: 'retain' as const }
+			...(options.workspace?.mode === 'isolated' &&
+			(options.workspace.retention === 'retain' || options.workspace.retention === 'retain-changed')
+				? { workspaceRetention: options.workspace.retention }
 				: {}),
 		}
 	}
@@ -2394,6 +2396,23 @@ export class AgentManager {
 		if (!spawnRecord.workspaceRef) return
 		const backend = spawnRecord.workspaceRef.meta.backend
 		if (!this.deps.workspaceRegistry.has(backend)) return
+		if (spawnRecord.workspaceRetention === 'retain-changed') {
+			// Keep the checkout unless it provably holds nothing. A look that fails,
+			// or a backend that cannot say whether it moved, keeps it too.
+			const seen = await this.deps.workspaceRegistry
+				.get(backend)
+				.inspect(spawnRecord.workspaceRef)
+				.catch((inspectErr) => {
+					this.log.warn('Workspace inspect failed; keeping it', {
+						'namzu.manager.backend': backend,
+						'namzu.sub_session.id': spawnRecord.subSessionId,
+						'exception.message': toErrorMessage(inspectErr),
+					})
+					return undefined
+				})
+			if (!seen) return
+			if (seen.exists && (seen.isDirty || seen.hasNewCommits !== false)) return
+		}
 		await this.deps.workspaceRegistry
 			.get(backend)
 			.dispose(spawnRecord.workspaceRef)

package/src/manager/session/turn-recorder.ts

@@ -228,7 +228,8 @@ export class TurnRecorder {
 	#chain: Promise<void> = Promise.resolve()
 	#failure: unknown = undefined
 	#view: ViewEntry[] = []
-	readonly #ids = new Map<Message, MessageId>()
+	// Identity bookkeeping must not keep messages removed by compaction alive.
+	readonly #ids = new WeakMap<Message, MessageId>()
 	/** Every message's record id, kept after a compaction drops it from the fold. */
 	readonly #recorded = new WeakMap<Message, MessageId>()
 	readonly #transient = new WeakSet<Message>()

package/src/persona/assembler.ts

@@ -1,5 +1,5 @@
 import type { AgentPersona, OutputDiscipline } from '../types/persona/index.js'
-import { type Skill, isInvocableBy } from '../types/skills/index.js'
+import { type Skill, isInvocableBy, skillModelDescription } from '../types/skills/index.js'
 
 export function assembleSystemPrompt(persona: AgentPersona, skills?: Skill[]): string {
 	const sections: string[] = []
@@ -58,7 +58,7 @@ export function renderSkillsSection(skills?: Skill[]): string | null {
 			const lines = [
 				'<skill>',
 				`<name>${s.metadata.name}</name>`,
-				`<description>${s.metadata.description.trim()}</description>`,
+				`<description>${skillModelDescription(s.metadata)}</description>`,
 				`<location>${s.dirPath}/SKILL.md</location>`,
 			]
 			if (s.metadata.compatibility) {

package/src/plugin/index.ts

@@ -17,8 +17,13 @@ export {
 	shellHookVerdict,
 } from './shell-hook.js'
 export type {
+	HttpHookEntry,
+	PromptHookEntry,
 	ShellHookEntry,
 	ShellHookEvent,
+	ShellHookHandler,
+	ShellHookJudge,
+	ShellHookOnFailure,
 	ShellHookInput,
 	ShellHookOptions,
 	ShellHookOutcome,

package/src/plugin/lifecycle.ts

@@ -180,6 +180,8 @@ function immutableManifest(manifest: PluginDefinition['manifest']): PluginDefini
 		...(mcpServers ? { mcpServers: Object.freeze(mcpServers) } : {}),
 		...(manifest.connectors ? { connectors: Object.freeze([...manifest.connectors]) } : {}),
 		...(manifest.personas ? { personas: Object.freeze([...manifest.personas]) } : {}),
+		...(manifest.commands ? { commands: Object.freeze([...manifest.commands]) } : {}),
+		...(manifest.agents ? { agents: Object.freeze([...manifest.agents]) } : {}),
 	})
 }
 
@@ -438,11 +440,23 @@ export class PluginLifecycleManager {
 		if (index >= 0) this.listeners.splice(index, 1)
 	}
 
-	async install(pluginDir: string, scope: PluginScope): Promise<PluginDefinition> {
+	/**
+	 * `options.authorityRoot` names the folder the plugin must stay inside when
+	 * it is not the scope's own root: a plugin a person points at directly for
+	 * one session is its own authority. It applies to this admission only.
+	 */
+	async install(
+		pluginDir: string,
+		scope: PluginScope,
+		options: { readonly authorityRoot?: string } = {},
+	): Promise<PluginDefinition> {
 		// Admission and enable read the same constructor-owned capability. The
 		// loader defaults this to false for direct callers; a manager that really
 		// owns the registry is the authority that can opt the manifest in.
-		const rootDir = await resolveWithinReal(this.scopeRoots[scope], pluginDir)
+		const rootDir = await resolveWithinReal(
+			options.authorityRoot ?? this.scopeRoots[scope],
+			pluginDir,
+		)
 		const manifest = immutableManifest(
 			await loadPluginManifest(rootDir, {
 				skillsSupported: Boolean(this.skillRegistry),

package/src/plugin/shell-hook-http.ts

@@ -0,0 +1,181 @@
+/**
+ * An HTTP hook: the event as a JSON POST, the response as the hook's answer.
+ *
+ * A 2xx response is exit `0` with the body as stdout, so the JSON answer is
+ * read exactly as a command's is. Any other status, a network error and a
+ * deadline are the hook's own failure. The address is checked where the
+ * connection is made, not before it: a name that resolves to a private or
+ * link-local address (a cloud metadata service, a router) is refused, so a
+ * hook cannot be pointed at the machine's neighbours and a name cannot be
+ * re-resolved between the check and the connect. Loopback stays allowed for
+ * local development. Redirects are not followed.
+ */
+
+import { type LookupAddress, lookup } from 'node:dns'
+import { request as httpRequest } from 'node:http'
+import { request as httpsRequest } from 'node:https'
+import { isIP } from 'node:net'
+
+/** Captured response bound. */
+const MAX_BODY_BYTES = 64 * 1024
+
+export interface HttpHookRequest {
+	readonly url: string
+	readonly body: string
+	readonly headers?: Readonly<Record<string, string>> | undefined
+	readonly allowedEnvVars?: readonly string[] | undefined
+	readonly timeoutMs: number
+	readonly env?: Readonly<Record<string, string | undefined>> | undefined
+	readonly signal?: AbortSignal | undefined
+}
+
+export interface HttpHookResponse {
+	readonly status: number | null
+	readonly body: string
+	readonly timedOut: boolean
+	readonly error?: string
+}
+
+/**
+ * Replace `$NAME` and `${NAME}` in a header value with the environment's
+ * value, but only for names the hook listed. Any other reference becomes the
+ * empty string, so a header can never carry a variable its author did not
+ * name. Line breaks and NUL are removed from the result, so a value cannot add
+ * a header of its own.
+ */
+export function interpolateHookHeader(
+	value: string,
+	allowed: ReadonlySet<string>,
+	env: Readonly<Record<string, string | undefined>>,
+): string {
+	return value
+		.replace(/\$\{([A-Za-z_][A-Za-z0-9_]*)\}|\$([A-Za-z_][A-Za-z0-9_]*)/g, (_all, braced, bare) => {
+			const name = (braced ?? bare) as string
+			return allowed.has(name) ? (env[name] ?? '') : ''
+		})
+		.replace(/[\r\n\0]/g, '')
+}
+
+/** Whether an address may be connected to: public, or loopback. */
+export function isReachableHookAddress(address: string): boolean {
+	const family = isIP(address)
+	if (family === 4) {
+		const [a = 0, b = 0] = address.split('.').map(Number)
+		if (a === 127) return true
+		if (a === 0 || a === 10) return false
+		if (a === 169 && b === 254) return false
+		if (a === 172 && b >= 16 && b <= 31) return false
+		if (a === 192 && b === 168) return false
+		if (a === 100 && b >= 64 && b <= 127) return false
+		if (a >= 224) return false
+		return true
+	}
+	if (family === 6) {
+		const lower = address.toLowerCase()
+		if (lower === '::1') return true
+		if (lower === '::') return false
+		const mapped = /^::ffff:(\d+\.\d+\.\d+\.\d+)$/.exec(lower)
+		if (mapped?.[1]) return isReachableHookAddress(mapped[1])
+		if (/^f[cd]/.test(lower) || /^fe[89ab]/.test(lower)) return false
+		return true
+	}
+	return false
+}
+
+/** `dns.lookup` that refuses an address a hook may not reach. */
+function guardedLookup(
+	hostname: string,
+	options: { all?: boolean; family?: number | 'IPv4' | 'IPv6' },
+	callback: (error: Error | null, address?: string | LookupAddress[], family?: number) => void,
+): void {
+	lookup(hostname, { ...options, all: true }, (error: Error | null, addresses: LookupAddress[]) => {
+		if (error) {
+			callback(error)
+			return
+		}
+		const list = addresses
+		const refused = list.find((entry) => !isReachableHookAddress(entry.address))
+		if (refused || list.length === 0) {
+			callback(
+				new Error(
+					`${hostname} resolves to ${refused?.address ?? 'nothing'}, a private or link-local address`,
+				),
+			)
+			return
+		}
+		if (options.all) {
+			callback(null, list)
+			return
+		}
+		const first = list[0] as LookupAddress
+		callback(null, first.address, first.family)
+	})
+}
+
+export function postHookJson(input: HttpHookRequest): Promise<HttpHookResponse> {
+	return new Promise((resolve) => {
+		let url: URL
+		try {
+			url = new URL(input.url)
+		} catch {
+			resolve({ status: null, body: '', timedOut: false, error: 'the url is not valid' })
+			return
+		}
+		if (url.protocol !== 'http:' && url.protocol !== 'https:') {
+			resolve({ status: null, body: '', timedOut: false, error: 'the url must be http or https' })
+			return
+		}
+		// A literal address never reaches the resolver, so it is checked here.
+		const literal = url.hostname.replace(/^\[|\]$/g, '')
+		if (isIP(literal) !== 0 && !isReachableHookAddress(literal)) {
+			resolve({
+				status: null,
+				body: '',
+				timedOut: false,
+				error: `${literal} is a private or link-local address`,
+			})
+			return
+		}
+		const allowed = new Set(input.allowedEnvVars ?? [])
+		const env = input.env ?? process.env
+		const headers: Record<string, string> = {
+			'Content-Type': 'application/json',
+			'Content-Length': String(Buffer.byteLength(input.body)),
+		}
+		for (const [name, value] of Object.entries(input.headers ?? {})) {
+			headers[name] = interpolateHookHeader(value, allowed, env)
+		}
+		let settled = false
+		let timedOut = false
+		const finish = (response: HttpHookResponse) => {
+			if (settled) return
+			settled = true
+			clearTimeout(timer)
+			input.signal?.removeEventListener('abort', onAbort)
+			resolve(response)
+		}
+		const onAbort = () => {
+			req.destroy()
+			finish({ status: null, body: '', timedOut: false, error: 'cancelled' })
+		}
+		const send = url.protocol === 'https:' ? httpsRequest : httpRequest
+		const req = send(url, { method: 'POST', headers, lookup: guardedLookup as never }, (res) => {
+			let body = ''
+			res.setEncoding('utf8')
+			res.on('data', (chunk: string) => {
+				if (body.length < MAX_BODY_BYTES) body = (body + chunk).slice(0, MAX_BODY_BYTES)
+			})
+			res.on('end', () => finish({ status: res.statusCode ?? null, body, timedOut: false }))
+			res.on('error', (error) => finish({ status: null, body, timedOut, error: error.message }))
+		})
+		const timer = setTimeout(() => {
+			timedOut = true
+			req.destroy()
+			finish({ status: null, body: '', timedOut: true })
+		}, input.timeoutMs)
+		req.on('error', (error) => finish({ status: null, body: '', timedOut, error: error.message }))
+		if (input.signal?.aborted) onAbort()
+		else input.signal?.addEventListener('abort', onAbort, { once: true })
+		req.end(input.body)
+	})
+}