@namzu/sdk 30.2.0 → 31.1.0

package/src/connector/builtins/webhook.ts

@@ -2,21 +2,52 @@ import { createHmac } from 'node:crypto'
 import { z } from 'zod'
 import type {
 	AuthConfig,
+	AuthType,
 	ConnectionType,
 	ConnectorExecuteResult,
+	ConnectorExecutionMetadata,
 	ConnectorMethod,
+	ConnectorOperationOptions,
 	WebhookConnectorConfig,
 	WebhookSendInput,
 	WebhookSendOutput,
 } from '../../types/connector/index.js'
 import { asConnectorId } from '../../utils/id.js'
 import { BaseConnector } from '../BaseConnector.js'
+import {
+	CONNECTOR_HEALTH_TIMEOUT_MS,
+	ConnectorHttpOperation,
+	DEFAULT_CONNECTOR_MAX_RESPONSE_BYTES,
+	DEFAULT_CONNECTOR_REQUEST_TIMEOUT_MS,
+	readConnectorResponseBody,
+	requireHttpUrl,
+	requireSafeConnectorInputHeaders,
+	requireSameOrigin,
+	validateConnectorMaxResponseBytes,
+	validateConnectorTimeoutMs,
+} from '../http-operation.js'
 
 const WebhookConnectorConfigSchema = z.object({
-	url: z.string().url(),
+	url: z
+		.string()
+		.url()
+		.refine((value) => /^https?:/i.test(value), 'url must use http: or https:'),
 	secret: z.string().optional(),
 	defaultHeaders: z.record(z.string()).optional(),
-	timeoutMs: z.number().positive().optional().default(30_000),
+	maxResponseBytes: z
+		.number()
+		.int()
+		.positive()
+		.max(2_147_483_647)
+		.optional()
+		.default(DEFAULT_CONNECTOR_MAX_RESPONSE_BYTES),
+	timeoutMs: z
+		.number()
+		.int()
+		.positive()
+		.max(2_147_483_647)
+		.optional()
+		.default(DEFAULT_CONNECTOR_REQUEST_TIMEOUT_MS),
 })
 
 const WebhookSendInputSchema = z.object({
@@ -33,6 +64,7 @@ export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
 	readonly name = 'Webhook Connector'
 	readonly description = 'Send webhook payloads to configured endpoints with optional HMAC signing'
 	readonly connectionType: ConnectionType = 'webhook'
+	override readonly supportedAuth: readonly AuthType[] = ['none', 'bearer']
 	readonly configSchema = WebhookConnectorConfigSchema
 	readonly methods: ConnectorMethod[] = [
 		{
@@ -43,69 +75,97 @@ export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
 	]
 
 	private url = ''
+	private origin = ''
 	private secret: string | undefined
 	private defaultHeaders: Record<string, string> = {}
-	private timeoutMs = 30_000
+	private timeoutMs = DEFAULT_CONNECTOR_REQUEST_TIMEOUT_MS
+	private maxResponseBytes = DEFAULT_CONNECTOR_MAX_RESPONSE_BYTES
 
 	async connect(config: WebhookConnectorConfig, auth?: AuthConfig): Promise<void> {
-		this.config = config
+		const validated = WebhookConnectorConfigSchema.parse(config)
+		const parsedUrl = requireHttpUrl(validated.url, 'WebhookConnector url')
+		this.config = validated
 		this.auth = auth
-		this.url = config.url
-		this.secret = config.secret
-		this.defaultHeaders = config.defaultHeaders ?? {}
-		this.timeoutMs = config.timeoutMs ?? 30_000
+		this.url = validated.url
+		this.origin = parsedUrl.origin
+		this.secret = validated.secret
+		this.defaultHeaders = { ...(validated.defaultHeaders ?? {}) }
+		this.timeoutMs = validateConnectorTimeoutMs(validated.timeoutMs, 'WebhookConnector timeoutMs')
+		this.maxResponseBytes = validateConnectorMaxResponseBytes(
+			validated.maxResponseBytes,
+			'WebhookConnector maxResponseBytes',
+		)
 
 		if (auth?.type === 'bearer' && auth.credentials?.token) {
 			this.defaultHeaders.Authorization = `Bearer ${auth.credentials.token}`
 		}
 
-		this.log.info('Webhook connector connected', { 'namzu.connector.url': this.url })
+		this.log.info('Webhook connector connected', {
+			'namzu.connector.url': this.url,
+		})
 	}
 
 	async disconnect(): Promise<void> {
 		this.config = null
 		this.auth = undefined
 		this.url = ''
+		this.origin = ''
 		this.secret = undefined
 		this.defaultHeaders = {}
 		this.log.info('Webhook connector disconnected')
 	}
 
-	async healthCheck(): Promise<boolean> {
+	async healthCheck(options?: ConnectorOperationOptions): Promise<boolean> {
 		if (!this.url) return false
+		let operation: ConnectorHttpOperation | undefined
 		try {
-			const controller = new AbortController()
-			const timeout = setTimeout(() => controller.abort(), 5_000)
-			const response = await fetch(this.url, {
-				method: 'HEAD',
-				signal: controller.signal,
-			})
-			clearTimeout(timeout)
+			operation = new ConnectorHttpOperation(
+				options?.signal,
+				CONNECTOR_HEALTH_TIMEOUT_MS,
+				'Webhook connector health check',
+			)
+			const activeOperation = operation
+			const response = await activeOperation.run(() =>
+				fetch(this.url, {
+					method: 'HEAD',
+					redirect: 'manual',
+					signal: activeOperation.signal,
+				}),
+			)
 			return response.ok || response.status < 500
 		} catch {
 			return false
+		} finally {
+			operation?.close()
 		}
 	}
 
-	async execute(method: string, input: unknown): Promise<ConnectorExecuteResult> {
+	async execute(
+		method: string,
+		input: unknown,
+		options?: ConnectorOperationOptions,
+	): Promise<ConnectorExecuteResult> {
 		this.requireMethod(method)
-		const validated = this.validateInput(this.requireMethod(method), input) as WebhookSendInput
-
-		const { result, durationMs } = await this.measureExecution(() => this.doSend(validated))
-
-		return {
-			success: result.status >= 200 && result.status < 400,
-			output: result,
-			durationMs,
-			metadata: {
-				status: result.status,
-				deliveredAt: result.deliveredAt,
-			},
+		const validated = (await this.validateInput(
+			this.requireMethod(method),
+			input,
+			options,
+		)) as WebhookSendInput
+		const startedAt = performance.now()
+		if (options?.signal?.aborted) {
+			return this.notStarted(options.signal.reason, startedAt)
 		}
+		return this.doSend(validated, options, startedAt)
 	}
 
-	private async doSend(input: WebhookSendInput): Promise<WebhookSendOutput> {
+	private async doSend(
+		input: WebhookSendInput,
+		options: ConnectorOperationOptions | undefined,
+		startedAt: number,
+	): Promise<ConnectorExecuteResult> {
 		const targetUrl = input.url ?? this.url
+		requireSameOrigin(targetUrl, this.origin, 'WebhookConnector request URL')
+		requireSafeConnectorInputHeaders(input.headers, 'WebhookConnector request headers')
 		const bodyStr = JSON.stringify(input.payload)
 
 		const headers: Record<string, string> = {
@@ -119,32 +179,132 @@ export class WebhookConnector extends BaseConnector<WebhookConnectorConfig> {
 			headers['X-Webhook-Signature'] = `sha256=${signature}`
 		}
 
-		const controller = new AbortController()
-		const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
+		let operation: ConnectorHttpOperation | undefined
 
 		try {
-			const response = await fetch(targetUrl, {
-				method: 'POST',
-				headers,
-				body: bodyStr,
-				signal: controller.signal,
-			})
+			try {
+				operation = new ConnectorHttpOperation(
+					options?.signal,
+					this.timeoutMs,
+					'Webhook connector POST',
+				)
+			} catch (error) {
+				return this.notStarted(error, startedAt)
+			}
+			let response: Response
+			try {
+				const activeOperation = operation
+				response = await activeOperation.run(() =>
+					fetch(targetUrl, {
+						method: 'POST',
+						headers,
+						body: bodyStr,
+						redirect: 'manual',
+						signal: activeOperation.signal,
+					}),
+				)
+			} catch (error) {
+				return this.unknownOutcome(error, startedAt)
+			}
 
+			const deliveredAt = Date.now()
+			const metadata: ConnectorExecutionMetadata = {
+				status: response.status,
+				deliveredAt,
+				remoteOutcome: 'response_received',
+				retrySafety: 'unsafe',
+				bodyAvailable: true,
+			}
+			const redirectLocation = response.headers.get('location')
+			if (redirectLocation) metadata.redirectLocation = redirectLocation
 			let body: unknown
-			const contentType = response.headers.get('content-type') ?? ''
-			if (contentType.includes('application/json')) {
-				body = await response.json()
-			} else {
-				body = await response.text()
+			try {
+				body = await readConnectorResponseBody(response, operation, this.maxResponseBytes)
+			} catch (error) {
+				const output: WebhookSendOutput = {
+					status: response.status,
+					body: null,
+					deliveredAt,
+					bodyAvailable: false,
+					bodyError: `Response body unavailable: ${this.errorText(error)}`,
+					remoteOutcome: 'response_received',
+					retrySafety: 'unsafe',
+				}
+				metadata.bodyAvailable = false
+				return {
+					success: response.status >= 200 && response.status < 300,
+					output,
+					...(response.status < 200 || response.status >= 300
+						? { error: this.statusError(response, true) }
+						: {}),
+					durationMs: this.duration(startedAt),
+					metadata,
+				}
 			}
 
-			return {
+			const output: WebhookSendOutput = {
 				status: response.status,
 				body,
-				deliveredAt: Date.now(),
+				deliveredAt,
+				bodyAvailable: true,
+				remoteOutcome: 'response_received',
+				retrySafety: 'unsafe',
+			}
+			return {
+				success: response.status >= 200 && response.status < 300,
+				output,
+				...(response.status < 200 || response.status >= 300
+					? { error: this.statusError(response, false) }
+					: {}),
+				durationMs: this.duration(startedAt),
+				metadata,
 			}
 		} finally {
-			clearTimeout(timeout)
+			operation?.close()
+		}
+	}
+
+	private notStarted(reason: unknown, startedAt: number): ConnectorExecuteResult {
+		return {
+			success: false,
+			output: null,
+			error: `Webhook POST was cancelled before it started: ${this.errorText(reason)}. No remote request was started; retry is safe.`,
+			durationMs: this.duration(startedAt),
+			metadata: {
+				remoteOutcome: 'not_started',
+				retrySafety: 'safe',
+				bodyAvailable: false,
+			},
+		}
+	}
+
+	private unknownOutcome(error: unknown, startedAt: number): ConnectorExecuteResult {
+		return {
+			success: false,
+			output: null,
+			error: `Webhook POST produced no response: ${this.errorText(error)}. The remote outcome is unknown. Do not automatically retry this request; it may duplicate a delivery.`,
+			durationMs: this.duration(startedAt),
+			metadata: {
+				remoteOutcome: 'unknown',
+				retrySafety: 'unsafe',
+				bodyAvailable: false,
+			},
+		}
+	}
+
+	private statusError(response: Response, bodyMissing: boolean): string {
+		if (response.status >= 300 && response.status < 400) {
+			const location = response.headers.get('location')
+			return `HTTP ${response.status}: ${response.statusText}. The redirect was not followed because webhook requests cannot leave their configured origin.${location ? ` Location: ${location}.` : ''} Do not automatically retry; the webhook may already have been applied.`
 		}
+		return `HTTP ${response.status}: ${response.statusText}.${bodyMissing ? ' The response body was unavailable.' : ''} Do not automatically retry; the webhook may already have been applied.`
+	}
+
+	private duration(startedAt: number): number {
+		return Math.round(performance.now() - startedAt)
+	}
+
+	private errorText(error: unknown): string {
+		return error instanceof Error ? error.message : String(error)
 	}
 }

package/src/connector/execution-contract.ts

@@ -0,0 +1,27 @@
+import type { ConnectorOperationOptions } from '../types/connector/index.js'
+
+const MANAGER_VALIDATED_INPUT = Symbol('namzu.connector.manager-validated-input')
+
+export type ManagedConnectorOperationOptions = ConnectorOperationOptions & {
+	readonly [MANAGER_VALIDATED_INPUT]: true
+}
+
+/** Internal hand-off: the manager already produced the method's canonical input. */
+export function managedConnectorOptions(
+	options: ConnectorOperationOptions,
+): ManagedConnectorOperationOptions {
+	return {
+		...options,
+		[MANAGER_VALIDATED_INPUT]: true,
+	}
+}
+
+/** Used by BaseConnector helpers so direct calls still validate exactly once. */
+export function hasManagerValidatedInput(
+	options: ConnectorOperationOptions | undefined,
+): options is ManagedConnectorOperationOptions {
+	return Boolean(
+		options &&
+			(options as Partial<ManagedConnectorOperationOptions>)[MANAGER_VALIDATED_INPUT] === true,
+	)
+}

package/src/connector/http-operation.ts

@@ -0,0 +1,238 @@
+const MAX_TIMER_DELAY_MS = 2_147_483_647
+const MAX_RESPONSE_BYTES = 2_147_483_647
+
+// These headers can change where an already-validated URL is routed. Connector
+// method input is commonly model-authored, while the base URL and credentials
+// are host-configured. Letting the former supply `Host` would attach the
+// latter's bearer/cookie headers to a different virtual host on the same
+// socket. Proxy credentials are equally outside method-input authority.
+const FORBIDDEN_CONNECTOR_INPUT_HEADERS = new Set([
+	'host',
+	'proxy-authorization',
+	'proxy-connection',
+])
+
+export const DEFAULT_CONNECTOR_REQUEST_TIMEOUT_MS = 30_000
+export const CONNECTOR_HEALTH_TIMEOUT_MS = 5_000
+export const DEFAULT_CONNECTOR_MAX_RESPONSE_BYTES = 2 * 1024 * 1024
+
+export function validateConnectorTimeoutMs(value: number, label: string): number {
+	if (!Number.isInteger(value) || value < 1 || value > MAX_TIMER_DELAY_MS) {
+		throw new Error(
+			`${label} must be an integer from 1 to ${MAX_TIMER_DELAY_MS}; received ${String(value)}`,
+		)
+	}
+	return value
+}
+
+export function validateConnectorMaxResponseBytes(value: number, label: string): number {
+	if (!Number.isInteger(value) || value < 1 || value > MAX_RESPONSE_BYTES) {
+		throw new Error(
+			`${label} must be an integer from 1 to ${MAX_RESPONSE_BYTES}; received ${String(value)}`,
+		)
+	}
+	return value
+}
+
+export function requireSafeConnectorInputHeaders(
+	headers: Readonly<Record<string, string>> | undefined,
+	label: string,
+): void {
+	if (!headers) return
+	for (const name of Object.keys(headers)) {
+		if (FORBIDDEN_CONNECTOR_INPUT_HEADERS.has(name.toLowerCase())) {
+			throw new Error(`${label} cannot set routing header "${name}"`)
+		}
+	}
+}
+
+export function requireHttpUrl(value: string, label: string): URL {
+	const parsed = new URL(value)
+	if (parsed.protocol !== 'http:' && parsed.protocol !== 'https:') {
+		throw new Error(`${label} must use http: or https:; received ${parsed.protocol}`)
+	}
+	return parsed
+}
+
+export function requireSameOrigin(value: string, configuredOrigin: string, label: string): URL {
+	const parsed = requireHttpUrl(value, label)
+	if (parsed.origin !== configuredOrigin) {
+		throw new Error(
+			`${label} must stay on the configured connector origin ${configuredOrigin}; received ${parsed.origin}`,
+		)
+	}
+	return parsed
+}
+
+function timeoutError(label: string, timeoutMs: number): Error {
+	const error = new Error(`${label} timed out after ${timeoutMs}ms`)
+	error.name = 'TimeoutError'
+	return error
+}
+
+function responseSizeError(maxBytes: number): Error {
+	const error = new Error(`Response body exceeded the configured ${maxBytes}-byte limit`)
+	error.name = 'ResponseSizeError'
+	return error
+}
+
+/**
+ * Read a platform response without allocating beyond the connector's byte
+ * budget. `Content-Length` is only an early refusal; the streaming count is
+ * authoritative because chunked and dishonest responses omit or understate it.
+ */
+export async function readConnectorResponseBody(
+	response: Response,
+	operation: ConnectorHttpOperation,
+	maxBytes: number,
+): Promise<unknown> {
+	const contentType = response.headers.get('content-type') ?? ''
+	const contentLength = response.headers.get('content-length')
+	if (contentLength !== null) {
+		const declaredBytes = Number(contentLength)
+		if (Number.isFinite(declaredBytes) && declaredBytes > maxBytes) {
+			const error = responseSizeError(maxBytes)
+			operation.cancel(error)
+			throw error
+		}
+	}
+
+	// A real fetch Response has a byte stream whenever it has a body. The
+	// fallback preserves compatibility with body-less responses and injected
+	// Response-shaped test doubles; there are no remote bytes to stream when
+	// the platform reports `body === null`.
+	if (!response.body) {
+		return operation.run(() =>
+			contentType.includes('application/json') ? response.json() : response.text(),
+		)
+	}
+
+	const reader = response.body.getReader()
+	const chunks: Uint8Array[] = []
+	let totalBytes = 0
+	try {
+		while (true) {
+			const { done, value } = await operation.run(() => reader.read())
+			if (done) break
+			totalBytes += value.byteLength
+			if (totalBytes > maxBytes) {
+				const error = responseSizeError(maxBytes)
+				void reader.cancel(error).catch(() => undefined)
+				operation.cancel(error)
+				throw error
+			}
+			chunks.push(value)
+		}
+	} finally {
+		reader.releaseLock()
+	}
+
+	const bytes = new Uint8Array(totalBytes)
+	let offset = 0
+	for (const chunk of chunks) {
+		bytes.set(chunk, offset)
+		offset += chunk.byteLength
+	}
+	const text = new TextDecoder().decode(bytes)
+	return contentType.includes('application/json') ? JSON.parse(text) : text
+}
+
+/**
+ * One whole HTTP operation boundary: fetch and body reads share one clock.
+ *
+ * The promise race is intentional. Forwarding a signal cannot settle a custom
+ * fetch/body implementation that ignores it, and a connector lifecycle is a
+ * public entry point independent of the run executor's own tool deadline.
+ */
+export class ConnectorHttpOperation {
+	readonly signal: AbortSignal
+	private readonly controller = new AbortController()
+	private readonly aborted: Promise<never>
+	private readonly callerSignal: AbortSignal | undefined
+	private readonly onCallerAbort: (() => void) | undefined
+	private readonly timer: ReturnType<typeof setTimeout>
+	private rejectAbort!: (reason: unknown) => void
+	private hasCause = false
+	private firstCause: unknown
+
+	constructor(callerSignal: AbortSignal | undefined, timeoutMs: number, label: string) {
+		callerSignal?.throwIfAborted()
+		this.signal = this.controller.signal
+		this.callerSignal = callerSignal
+		this.aborted = new Promise<never>((_resolve, reject) => {
+			this.rejectAbort = reject
+		})
+		// Cancellation may arrive between construction and the first `wait`.
+		// Keep that owned rejection observed even when the next `run` refuses
+		// before attaching a race handler.
+		void this.aborted.catch(() => undefined)
+		this.onCallerAbort = callerSignal ? () => this.stop(callerSignal.reason) : undefined
+		callerSignal?.addEventListener('abort', this.onCallerAbort as () => void, {
+			once: true,
+		})
+		this.timer = setTimeout(() => this.stop(timeoutError(label, timeoutMs)), timeoutMs)
+	}
+
+	get cause(): unknown {
+		return this.firstCause
+	}
+
+	async wait<T>(operation: Promise<T>): Promise<T> {
+		this.throwIfStopped()
+		try {
+			const result = await Promise.race([operation, this.aborted])
+			// A foreign promise and caller abort can settle in the same turn. The
+			// promise race may pick the value first even though authority has
+			// already been withdrawn; never publish that late value as success.
+			this.throwIfStopped()
+			return result
+		} catch (error) {
+			if (
+				this.hasCause &&
+				error instanceof Error &&
+				(error.name === 'AbortError' || error.name === 'TimeoutError')
+			) {
+				throw this.firstCause
+			}
+			throw error
+		}
+	}
+
+	/**
+	 * Check authority before starting foreign work, then again after it wins.
+	 *
+	 * Passing an already-created promise to `wait()` cannot prevent the work
+	 * that created it from starting. Callers use this thunk form at every
+	 * network, resolver and stream boundary where admission matters.
+	 */
+	async run<T>(start: () => Promise<T>): Promise<T> {
+		this.throwIfStopped()
+		return this.wait(start())
+	}
+
+	throwIfStopped(): void {
+		this.signal.throwIfAborted()
+	}
+
+	close(): void {
+		clearTimeout(this.timer)
+		if (this.callerSignal && this.onCallerAbort) {
+			this.callerSignal.removeEventListener('abort', this.onCallerAbort)
+		}
+	}
+
+	cancel(reason: unknown): void {
+		this.stop(reason)
+	}
+
+	private stop(reason: unknown): void {
+		if (this.hasCause) return
+		this.hasCause = true
+		this.firstCause = reason
+		// Reject the owned wait before aborting transport. A fetch implementation
+		// may synchronously translate transport abort into a generic AbortError;
+		// that fallout must not erase the caller/deadline cause that won first.
+		this.rejectAbort(reason)
+		this.controller.abort(reason)
+	}
+}

package/src/connector/mcp/adapter.ts

@@ -452,8 +452,10 @@ export function mcpToolToToolDefinition(
 		isConcurrencySafe: () => true,
 		provenance: { server: serverName, readOnlyHintTrusted },
 
-		async execute(input: unknown, _context: ToolContext): Promise<ToolResult> {
-			const result = await client.callTool(tool.name, input as Record<string, unknown>)
+		async execute(input: unknown, context: ToolContext): Promise<ToolResult> {
+			const result = await client.callTool(tool.name, input as Record<string, unknown>, {
+				signal: context.abortSignal,
+			})
 			return frameServerResult(mcpToolResultToToolResult(result), serverName, tool.name)
 		},
 	}
@@ -463,7 +465,10 @@ export function toolDefinitionToMCPTool(tool: ToolDefinition): MCPToolDefinition
 	return {
 		name: tool.name,
 		description: tool.description,
-		inputSchema: zodToMCPJsonSchema(tool.inputSchema),
+		inputSchema: tool.modelInputSchema
+			? (inlineSchemaRefs(tool.modelInputSchema) as MCPJsonSchema)
+			: zodToMCPJsonSchema(tool.inputSchema),
+		...(tool.outputSchema ? { outputSchema: inlineSchemaRefs(tool.outputSchema) } : {}),
 		annotations: {
 			readOnlyHint: tool.isReadOnly?.(undefined as never),
 			destructiveHint: tool.isDestructive?.(undefined as never),