@namzu/sdk 48.3.1 → 50.0.0

package/src/bridge/acp/server.ts

@@ -8,9 +8,11 @@ import {
 	ACP_METHODS,
 	ACP_PERMISSION_CAPABILITY,
 	ACP_PROTOCOL_VERSION,
+	ACP_TASK_CAPABILITY,
 } from '../../constants/acp/index.js'
 import type { HostCommandRegistry } from '../../registry/command/index.js'
 import type { ToolPresenter } from '../../registry/tool/presentation.js'
+import { isReviewMode } from '../../runtime/query/review-policy.js'
 import type {
 	AcpFsReadResult,
 	AcpInitializeParams,
@@ -23,6 +25,7 @@ import type {
 	AcpSessionPromptParams,
 	AcpSessionPromptResult,
 	AcpSessionUpdate,
+	AcpTaskUpdate,
 } from '../../types/acp/index.js'
 import type { MCPJsonRpcMessage, MCPTransport } from '../../types/connector/mcp.js'
 import type { SessionEvent } from '../../types/session/events.js'
@@ -35,6 +38,7 @@ import type {
 	AcpPermissionOutcome,
 	AcpPermissionRequest,
 } from './permission.js'
+import { toAcpTaskUpdate } from './tasks.js'
 import { toAcpSessionUpdate, toAcpStopReason } from './update.js'
 
 /**
@@ -80,6 +84,8 @@ export interface AcpAgentGateway {
 	prompt(request: {
 		readonly sessionId: string
 		readonly prompt: string
+		readonly attachments?: AcpSessionPromptParams['attachments']
+		readonly options?: AcpSessionPromptParams['options']
 		readonly cwd: string
 		readonly onEvent: (event: SessionEvent) => void
 		readonly signal: AbortSignal
@@ -121,10 +127,23 @@ export interface AcpAgentGateway {
 	 * client's and may be any string: a namzu session id, or one the gateway
 	 * maps to a session through the index's `acp` / `session` refs.
 	 */
-	load?(sessionId: string): Promise<readonly unknown[] | undefined>
+	load?(sessionId: string, cwd?: string): Promise<readonly unknown[] | undefined>
+	/** Explicit host retry of one durable pause; never a new operator prompt. */
+	retry?(
+		request: Omit<Parameters<AcpAgentGateway['prompt']>[0], 'prompt' | 'attachments'> & {
+			readonly turnId: string
+			readonly checkpointId: string
+		},
+	): ReturnType<AcpAgentGateway['prompt']>
 }
 
 export interface AcpServerOptions {
+	/** Declare that the gateway preserves user attachment bytes in its model messages. */
+	readonly supportsPromptAttachments?: boolean
+	/** The host applies optional effort and permission settings to the exact turn. */
+	readonly supportsPromptOptions?: boolean
+	/** Emit planning notifications only to clients declaring namzu/tasks. */
+	readonly supportsTaskNotifications?: boolean
 	readonly transport: MCPTransport
 	readonly gateway: AcpAgentGateway
 	/**
@@ -143,6 +162,11 @@ export interface AcpServerOptions {
 	 * and injecting it also keeps a test off a random id.
 	 */
 	readonly newSessionId?: () => string
+	/** Explicit host extensions. Names must begin with `namzu/`; core methods
+	 * cannot be replaced. Called only after initialization and permission negotiation. */
+	readonly extensions?: Readonly<
+		Record<string, (params: Record<string, unknown>) => unknown | Promise<unknown>>
+	>
 	readonly log?: Logger
 }
 
@@ -212,12 +236,50 @@ export class ACPServer {
 	private requestSeq = 0
 
 	constructor(private readonly options: AcpServerOptions) {
-		this.log = resolveLogger(options.log).child({ 'namzu.log.scope': 'bridge/acp' })
+		this.log = resolveLogger(options.log).child({
+			'namzu.log.scope': 'bridge/acp',
+		})
+		for (const name of Object.keys(options.extensions ?? {})) {
+			if (!/^namzu\/[a-z][a-z0-9_/-]*$/.test(name)) {
+				throw new Error(`Invalid ACP host extension name: ${name}`)
+			}
+		}
 	}
 
 	/** The method names this server answers. For the drift test. */
 	methodNames(): readonly string[] {
-		return Object.keys(this.handlers).sort()
+		return [...Object.keys(this.handlers), ...Object.keys(this.options.extensions ?? {})].sort()
+	}
+
+	/** Published connection-owned workspace, absent while loading or after shutdown. */
+	getSessionCwd(sessionId: string): string | undefined {
+		return this.stopped ? undefined : this.sessions.get(sessionId)?.cwd
+	}
+
+	/** Host extensions can reuse the prompt's ordering, cancellation and review owner. */
+	async retrySession(
+		sessionId: string,
+		turnId: string,
+		checkpointId: string,
+		options?: AcpSessionPromptParams['options'],
+	): Promise<AcpSessionPromptResult> {
+		this.requireInitialized()
+		this.requirePermissionCapability()
+		if (this.stopped) throw new Error('The ACP server is stopped.')
+		if (
+			![turnId, checkpointId].every((id) => typeof id === 'string' && id.trim() && id.length <= 400)
+		)
+			throw new AcpError(ACP_ERROR_CODES.INVALID_PARAMS, 'Invalid retry turn or checkpoint.')
+		const retry = this.options.gateway.retry
+		if (!retry)
+			throw new AcpError(ACP_ERROR_CODES.INVALID_REQUEST, 'This agent cannot retry paused turns.')
+		return this.onSessionPrompt(
+			{ sessionId, prompt: '', ...(options ? { options } : {}) },
+			(request) => {
+				const { prompt: _prompt, attachments: _attachments, ...context } = request
+				return retry.call(this.options.gateway, { ...context, turnId, checkpointId })
+			},
+		)
 	}
 
 	async start(): Promise<void> {
@@ -282,7 +344,7 @@ export class ACPServer {
 			}
 			this.pending.set(id, entry)
 			signal?.addEventListener('abort', onAbort, { once: true })
-			void this.send({ jsonrpc: '2.0', id, method, params }).catch((err: unknown) => {
+			void this.send({ jsonrpc: '2.0', id, method, params }, true).catch((err: unknown) => {
 				entry.reject(err instanceof Error ? err : new Error(String(err)))
 			})
 		})
@@ -305,7 +367,21 @@ export class ACPServer {
 			return
 		}
 
-		const handler = this.handlers[message.method]
+		const extension = Object.hasOwn(this.options.extensions ?? {}, message.method)
+			? this.options.extensions?.[message.method]
+			: undefined
+		const core = Object.hasOwn(this.handlers, message.method)
+			? this.handlers[message.method]
+			: undefined
+		const handler =
+			core ??
+			(extension
+				? (params: Record<string, unknown>) => {
+						this.requireInitialized()
+						this.requirePermissionCapability()
+						return extension(params)
+					}
+				: undefined)
 		if (!handler) {
 			// Answered, and the CONNECTION STAYS OPEN. A client probing for a
 			// feature must not lose its session because this agent does not have
@@ -347,24 +423,39 @@ export class ACPServer {
 		await this.send({ jsonrpc: '2.0', id, error: { code, message } })
 	}
 
-	private async send(message: MCPJsonRpcMessage): Promise<void> {
+	private async send(message: MCPJsonRpcMessage, requireDelivery = false): Promise<void> {
 		try {
 			await this.options.transport.send(message)
 		} catch (err) {
-			// The client hung up mid-write. Nothing to recover; a throw here
-			// would escape into whichever handler happened to be running.
+			// Terminal responses have no caller waiting on their delivery. A
+			// request or ordered update does, so its owning promise must fail.
 			this.log.warn('acp send failed', {
 				'namzu.acp.error_message': err instanceof Error ? err.message : String(err),
 			})
+			if (requireDelivery) throw err
 		}
 	}
 
 	private async notifyUpdate(sessionId: string, update: AcpSessionUpdate): Promise<void> {
-		await this.send({
-			jsonrpc: '2.0',
-			method: ACP_CLIENT_NOTIFICATIONS.SESSION_UPDATE,
-			params: { sessionId, update } as unknown as Record<string, unknown>,
-		})
+		await this.send(
+			{
+				jsonrpc: '2.0',
+				method: ACP_CLIENT_NOTIFICATIONS.SESSION_UPDATE,
+				params: { sessionId, update } as unknown as Record<string, unknown>,
+			},
+			true,
+		)
+	}
+
+	private async notifyTaskUpdate(update: AcpTaskUpdate): Promise<void> {
+		await this.send(
+			{
+				jsonrpc: '2.0',
+				method: ACP_CLIENT_NOTIFICATIONS.TASK_UPDATE,
+				params: update as unknown as Record<string, unknown>,
+			},
+			true,
+		)
 	}
 
 	private onInitialize(params: AcpInitializeParams): AcpInitializeResult {
@@ -372,6 +463,8 @@ export class ACPServer {
 		this.clientCapabilities = params.capabilities ?? []
 		return {
 			protocolVersion: ACP_PROTOCOL_VERSION,
+			...(this.options.supportsPromptAttachments ? { promptAttachments: true } : {}),
+			...(this.options.supportsPromptOptions ? { promptOptions: true } : {}),
 			agentInfo: this.options.agentInfo,
 			// From the registry, per call. A hard-coded list here would be a
 			// second definition of the command surface.
@@ -381,7 +474,13 @@ export class ACPServer {
 			// from `required` on purpose: a peer that is not an editor has no
 			// buffers, and demanding this of it would refuse a session that is
 			// perfectly able to run.
-			optionalClientCapabilities: [ACP_FILESYSTEM_CAPABILITY],
+			optionalClientCapabilities: [
+				ACP_FILESYSTEM_CAPABILITY,
+				...(this.options.supportsTaskNotifications ? [ACP_TASK_CAPABILITY] : []),
+			],
+			...(this.options.extensions
+				? { extensions: Object.keys(this.options.extensions).sort() }
+				: {}),
 		}
 	}
 
@@ -417,7 +516,7 @@ export class ACPServer {
 		const cwd = this.requireAbsoluteCwd(params.cwd)
 		const token = this.reserveSessionId(params.sessionId)
 		try {
-			const history = await this.options.gateway.load(params.sessionId)
+			const history = await this.options.gateway.load(params.sessionId, cwd)
 			if (history === undefined) {
 				throw new AcpError(
 					ACP_ERROR_CODES.INVALID_PARAMS,
@@ -451,7 +550,10 @@ export class ACPServer {
 		return resolved
 	}
 
-	private reserveGeneratedSessionId(): { readonly sessionId: string; readonly token: symbol } {
+	private reserveGeneratedSessionId(): {
+		readonly sessionId: string
+		readonly token: symbol
+	} {
 		if (this.options.newSessionId) {
 			const sessionId = this.options.newSessionId()
 			return { sessionId, token: this.reserveSessionId(sessionId) }
@@ -531,8 +633,23 @@ export class ACPServer {
 		}
 	}
 
-	private async onSessionPrompt(params: AcpSessionPromptParams): Promise<AcpSessionPromptResult> {
+	private async onSessionPrompt(
+		params: AcpSessionPromptParams,
+		run: AcpAgentGateway['prompt'] = (request) => this.options.gateway.prompt(request),
+	): Promise<AcpSessionPromptResult> {
 		const session = this.requireSession(params.sessionId)
+		if (
+			typeof params.prompt !== 'string' ||
+			(params.attachments !== undefined && params.prompt.length > 400_000)
+		)
+			throw new AcpError(ACP_ERROR_CODES.INVALID_PARAMS, 'Invalid prompt text.')
+		const attachments = this.readPromptAttachments(params.attachments)
+		const options = this.readPromptOptions(params.options)
+		if (attachments.length && this.options.supportsPromptAttachments !== true)
+			throw new AcpError(
+				ACP_ERROR_CODES.INVALID_REQUEST,
+				'This agent does not accept prompt attachments.',
+			)
 		if (session.promptInFlight) {
 			throw new AcpError(
 				ACP_ERROR_CODES.INVALID_REQUEST,
@@ -545,18 +662,47 @@ export class ACPServer {
 		// already cancelled.
 		const controller = new AbortController()
 		session.controller = controller
+		let updates = Promise.resolve()
+		let terminalReason: string | undefined
+		let updateFailure: Error | undefined
 
 		try {
-			const outcome = await this.options.gateway.prompt({
+			const outcome = await run({
 				sessionId: params.sessionId,
 				prompt: params.prompt,
+				...(attachments.length ? { attachments } : {}),
+				...(options ? { options } : {}),
 				cwd: session.cwd,
 				signal: controller.signal,
 				onEvent: (event) => {
+					const taskUpdate =
+						this.options.supportsTaskNotifications &&
+						this.clientCapabilities.includes(ACP_TASK_CAPABILITY)
+							? toAcpTaskUpdate(event, params.sessionId)
+							: null
 					const update = toAcpSessionUpdate(event, this.options.presenter)
-					if (update) void this.notifyUpdate(params.sessionId, update)
+					if (!update && !taskUpdate) return
+					if (update?.kind === 'turn_ended') terminalReason = update.reason
+					// A transport can complete writes asynchronously. Preserve admission
+					// order and finish every update before the prompt response settles.
+					updates = updates
+						.then(() => {
+							if (taskUpdate) return this.notifyTaskUpdate(taskUpdate)
+							if (update) return this.notifyUpdate(params.sessionId, update)
+							return undefined
+						})
+						.catch((error: unknown) => {
+							// Catch immediately, even while the gateway is still running.
+							// Keep later deliveries ordered without replacing the first failure.
+							updateFailure ??= error instanceof Error ? error : new Error(String(error))
+						})
+				},
+				ask: async (request) => {
+					const admittedUpdates = updates
+					await admittedUpdates
+					if (updateFailure) throw updateFailure
+					return this.askPermission(params.sessionId, session, request, controller.signal)
 				},
-				ask: (request) => this.askPermission(params.sessionId, session, request, controller.signal),
 				filesystem: this.clientFilesystem(),
 				history: session.history,
 			})
@@ -570,11 +716,19 @@ export class ACPServer {
 				session.history = [...outcome.history]
 			}
 
+			await updates
+			if (updateFailure) throw updateFailure
+			const reason = controller.signal.aborted
+				? 'cancelled'
+				: (terminalReason ?? outcome.stopReason)
 			return {
-				stopReason: controller.signal.aborted ? 'cancelled' : toAcpStopReason(outcome.stopReason),
+				stopReason: toAcpStopReason(reason),
+				...(reason === undefined ? {} : { reason }),
 			}
 		} catch (error) {
-			if (controller.signal.aborted) return { stopReason: 'cancelled' }
+			await updates
+			if (updateFailure) throw updateFailure
+			if (controller.signal.aborted) return { stopReason: 'cancelled', reason: 'cancelled' }
 			// The session log refused the turn: another one is active, perhaps
 			// started by another process on the same session. A client error, not
 			// an internal one, and it says what to do.
@@ -586,7 +740,11 @@ export class ACPServer {
 			}
 			throw error
 		} finally {
-			session.promptInFlight = false
+			try {
+				await updates
+			} finally {
+				session.promptInFlight = false
+			}
 		}
 	}
 
@@ -630,8 +788,17 @@ export class ACPServer {
 			case 'approve_all':
 				session.approveAll = true
 				return { kind: 'approve_all' }
-			case 'reject':
-				return { kind: 'reject', ...(answer.feedback ? { feedback: answer.feedback } : {}) }
+			case 'reject': {
+				// Only a client that says so is reporting a person's No: older clients
+				// send a bare `reject`, which stays exactly what it was.
+				const declined = answer.declined
+				const note = typeof declined?.note === 'string' ? declined.note.trim() : ''
+				return {
+					kind: 'reject',
+					...(answer.feedback ? { feedback: answer.feedback } : {}),
+					...(declined && typeof declined === 'object' ? { declined: note ? { note } : {} } : {}),
+				}
+			}
 			default:
 				// An answer this side cannot read is not an approval. A client that
 				// sent something unrecognised has not said yes, and treating
@@ -663,6 +830,85 @@ export class ACPServer {
 		}
 	}
 
+	private readPromptOptions(value: unknown): AcpSessionPromptParams['options'] {
+		if (value === undefined) return undefined
+		if (this.options.supportsPromptOptions !== true)
+			throw new AcpError(
+				ACP_ERROR_CODES.INVALID_REQUEST,
+				'This agent does not accept prompt settings.',
+			)
+		if (!value || typeof value !== 'object' || Array.isArray(value))
+			throw new AcpError(ACP_ERROR_CODES.INVALID_PARAMS, 'Invalid prompt settings.')
+		const { effort, permissionMode } = value as Record<string, unknown>
+		if (
+			Object.keys(value).some((key) => key !== 'effort' && key !== 'permissionMode') ||
+			(effort !== undefined &&
+				(typeof effort !== 'string' ||
+					!['none', 'minimal', 'low', 'medium', 'high', 'xhigh', 'max', 'ultra'].includes(
+						effort,
+					))) ||
+			(permissionMode !== undefined && !isReviewMode(permissionMode))
+		)
+			throw new AcpError(ACP_ERROR_CODES.INVALID_PARAMS, 'Invalid prompt settings.')
+		return {
+			...(effort
+				? { effort: effort as NonNullable<AcpSessionPromptParams['options']>['effort'] }
+				: {}),
+			...(permissionMode
+				? {
+						permissionMode: permissionMode as NonNullable<
+							AcpSessionPromptParams['options']
+						>['permissionMode'],
+					}
+				: {}),
+		}
+	}
+	private readPromptAttachments(
+		value: unknown,
+	): NonNullable<AcpSessionPromptParams['attachments']> {
+		if (value === undefined) return []
+		if (!Array.isArray(value) || value.length > 8)
+			throw new AcpError(ACP_ERROR_CODES.INVALID_PARAMS, 'Attach at most eight files.')
+		let bytes = 0
+		return value.map((item) => {
+			if (!item || typeof item !== 'object' || Array.isArray(item))
+				throw new AcpError(ACP_ERROR_CODES.INVALID_PARAMS, 'Invalid attachment.')
+			const { type, data, mediaType, name, citations } = item
+			if (
+				(type !== undefined && type !== 'image' && type !== 'document') ||
+				typeof data !== 'string' ||
+				!data.length ||
+				data.length > 4 * 1024 * 1024 ||
+				data.length % 4 !== 0 ||
+				!/^[A-Za-z0-9+/]+={0,2}$/.test(data) ||
+				typeof mediaType !== 'string' ||
+				(type === 'document'
+					? !['application/pdf', 'text/plain'].includes(mediaType)
+					: !['image/png', 'image/jpeg', 'image/webp', 'image/gif'].includes(mediaType)) ||
+				(name !== undefined && (typeof name !== 'string' || name.length > 180)) ||
+				(citations !== undefined && typeof citations !== 'boolean')
+			)
+				throw new AcpError(
+					ACP_ERROR_CODES.INVALID_PARAMS,
+					'Invalid attachment bytes or media type.',
+				)
+			bytes += Buffer.from(data, 'base64').byteLength
+			if (bytes > 3 * 1024 * 1024)
+				throw new AcpError(
+					ACP_ERROR_CODES.INVALID_PARAMS,
+					'Keep attachments under 3 MiB per message.',
+				)
+			return type === 'document'
+				? {
+						type,
+						data,
+						mediaType,
+						...(name ? { name } : {}),
+						...(citations !== undefined ? { citations } : {}),
+					}
+				: { type: 'image' as const, data, mediaType }
+		})
+	}
 	private requireSession(sessionId: string): Session {
 		const session = this.sessions.get(sessionId)
 		if (!session) {

package/src/bridge/acp/tasks.ts

@@ -0,0 +1,23 @@
+import type { AcpTaskUpdate } from '../../types/acp/index.js'
+import type { SessionEvent } from '../../types/session/events.js'
+
+/** Project only the addressed session's planning rows, without task descriptions or metadata. */
+export function toAcpTaskUpdate(event: SessionEvent, sessionId: string): AcpTaskUpdate | null {
+	if (
+		(event.type !== 'task_created' && event.type !== 'task_updated') ||
+		event.sessionId !== sessionId
+	)
+		return null
+	return {
+		sessionId,
+		task: {
+			taskId: event.taskId,
+			subject: event.subject,
+			status: event.status,
+			blockedBy: [...(event.blockedBy ?? [])],
+			...(event.owner === undefined ? {} : { owner: event.owner }),
+			...(event.activeForm ? { activeForm: event.activeForm } : {}),
+		},
+		...(event.type === 'task_updated' && event.deleted === true ? { deleted: true } : {}),
+	}
+}