@namzu/sdk 30.2.0 → 31.1.0

package/src/compaction/summary.ts

@@ -16,10 +16,10 @@ export const COMPACTION_HEADER =
 /**
  * Identity check for a prior compaction summary in the leading floor.
  *
- * Used to REPLACE one in place, so at most one `[COMPACTED CONTEXT]` block
- * ever lives in the never-trimmed floor, and by the checkpoint-restore path
- * to PRESERVE the summary across a resume — it is the only surviving record
- * of the older history a run compacted away.
+ * Used to replace a summary produced by the SAME run in place, and by restore
+ * paths to preserve summaries whose state was produced elsewhere. A retained
+ * summary is deliberately not replaceable: it is the only surviving record
+ * of an opaque older span.
  */
 export function isCompactionMessage(content: string | null | undefined): boolean {
 	return typeof content === 'string' && content.startsWith(COMPACTION_HEADER)

package/src/compaction/verifier.ts

@@ -1,5 +1,6 @@
 import type { CompactionConfig } from '../config/runtime.js'
 import { collectChatCompletion } from '../provider/collect-chat-completion.js'
+import { resolveStreamIdleTimeoutMs, withStreamIdleTimeout } from '../provider/idle-timeout.js'
 import type { TokenUsage } from '../types/common/index.js'
 import type { Message } from '../types/message/index.js'
 import type { LLMProvider } from '../types/provider/interface.js'
@@ -54,6 +55,18 @@ function truncateMessages(messages: Message[], budget: number): string {
  */
 export type UsageSink = (usage: TokenUsage) => void
 
+/** Cancellation and stream-liveness policy for a compaction verifier call. */
+export interface CompactionVerificationOptions {
+	/** Stop before provider work starts, or close an in-flight verifier transport. */
+	readonly signal?: AbortSignal
+	/**
+	 * Milliseconds without a verifier chunk before the provider stream is
+	 * treated as stalled. Defaults to the SDK's finite shared bound. Set `0`
+	 * only for explicit unbounded compatibility.
+	 */
+	readonly streamIdleTimeoutMs?: number
+}
+
 export async function buildVerifiedSummary(
 	manager: WorkingStateManager,
 	olderMessages: Message[],
@@ -68,6 +81,58 @@ export async function buildVerifiedSummary(
 	 * failure surfaced as compaction killing the run it exists to save.
 	 */
 	model?: string,
+	options: CompactionVerificationOptions = {},
+): Promise<string> {
+	options.signal?.throwIfAborted()
+	const providerWithIdleBound = withStreamIdleTimeout(provider, {
+		idleTimeoutMs: resolveStreamIdleTimeoutMs(options.streamIdleTimeoutMs),
+	})
+	return await buildVerifiedSummaryWithProvider(
+		manager,
+		olderMessages,
+		providerWithIdleBound,
+		config,
+		onUsage,
+		model,
+		options.signal,
+	)
+}
+
+/**
+ * Query-only seam for a provider whose idle/retry/fallback order was already
+ * composed at run admission. Wrapping that chain again would put an idle
+ * timer around retry backoff and misclassify a healthy recovery pause as a
+ * stalled stream. This symbol is intentionally absent from the package barrel.
+ */
+export async function buildVerifiedSummaryWithBoundedProvider(
+	manager: WorkingStateManager,
+	olderMessages: Message[],
+	provider: LLMProvider,
+	config: CompactionConfig,
+	onUsage?: UsageSink,
+	model?: string,
+	signal?: AbortSignal,
+): Promise<string> {
+	signal?.throwIfAborted()
+	return await buildVerifiedSummaryWithProvider(
+		manager,
+		olderMessages,
+		provider,
+		config,
+		onUsage,
+		model,
+		signal,
+	)
+}
+
+async function buildVerifiedSummaryWithProvider(
+	manager: WorkingStateManager,
+	olderMessages: Message[],
+	provider: LLMProvider,
+	config: CompactionConfig,
+	onUsage?: UsageSink,
+	model?: string,
+	signal?: AbortSignal,
 ): Promise<string> {
 	const serialized = serializeState(manager.getState())
 
@@ -102,6 +167,7 @@ export async function buildVerifiedSummary(
 			messages: verificationMessages,
 			maxTokens: config.llmVerificationMaxTokens,
 			temperature: 0,
+			...(signal ? { signal } : {}),
 		}),
 	)
 

package/src/connector/BaseConnector.ts

@@ -2,21 +2,26 @@ import type { z } from 'zod'
 import { NAMZU } from '../constants/telemetry/index.js'
 import type {
 	AuthConfig,
+	AuthType,
 	ConnectionType,
 	ConnectorDefinition,
 	ConnectorExecuteResult,
 	ConnectorLifecycle,
 	ConnectorMethod,
+	ConnectorOperationOptions,
 } from '../types/connector/index.js'
 import type { ConnectorId } from '../types/ids/index.js'
 import { SCOPE_ATTRIBUTE } from '../utils/log/types.js'
 import { type Logger, resolveLogger } from '../utils/logger.js'
+import { hasManagerValidatedInput } from './execution-contract.js'
 
 export abstract class BaseConnector<TConfig = unknown> implements ConnectorLifecycle<TConfig> {
 	abstract readonly id: ConnectorId
 	abstract readonly name: string
 	abstract readonly description: string
 	abstract readonly connectionType: ConnectionType
+	/** Omit only when the connector intentionally accepts every auth scheme. */
+	readonly supportedAuth?: readonly AuthType[]
 	abstract readonly configSchema: z.ZodType<TConfig, z.ZodTypeDef, unknown>
 	abstract readonly methods: ConnectorMethod[]
 
@@ -33,8 +38,12 @@ export abstract class BaseConnector<TConfig = unknown> implements ConnectorLifec
 
 	abstract connect(config: TConfig, auth?: AuthConfig): Promise<void>
 	abstract disconnect(): Promise<void>
-	abstract healthCheck(): Promise<boolean>
-	abstract execute(method: string, input: unknown): Promise<ConnectorExecuteResult>
+	abstract healthCheck(options?: ConnectorOperationOptions): Promise<boolean>
+	abstract execute(
+		method: string,
+		input: unknown,
+		options?: ConnectorOperationOptions,
+	): Promise<ConnectorExecuteResult>
 
 	toDefinition(): ConnectorDefinition<TConfig> {
 		return {
@@ -42,6 +51,7 @@ export abstract class BaseConnector<TConfig = unknown> implements ConnectorLifec
 			name: this.name,
 			description: this.description,
 			connectionType: this.connectionType,
+			...(this.supportedAuth ? { supportedAuth: [...this.supportedAuth] } : {}),
 			configSchema: this.configSchema,
 			methods: this.methods,
 		}
@@ -62,8 +72,13 @@ export abstract class BaseConnector<TConfig = unknown> implements ConnectorLifec
 		return method
 	}
 
-	protected validateInput(method: ConnectorMethod, input: unknown): unknown {
-		const result = method.inputSchema.safeParse(input)
+	protected async validateInput(
+		method: ConnectorMethod,
+		input: unknown,
+		options?: ConnectorOperationOptions,
+	): Promise<unknown> {
+		if (hasManagerValidatedInput(options)) return input
+		const result = await method.inputSchema.safeParseAsync(input)
 		if (!result.success) {
 			const errors = result.error.issues.map((i) => `${i.path.join('.')}: ${i.message}`).join('; ')
 			throw new Error(`Invalid input for method "${method.name}": ${errors}`)

package/src/connector/builtins/http.ts

@@ -1,20 +1,52 @@
 import { z } from 'zod'
 import type {
 	AuthConfig,
+	AuthType,
 	ConnectionType,
 	ConnectorExecuteResult,
+	ConnectorExecutionMetadata,
 	ConnectorMethod,
+	ConnectorOperationOptions,
 	HttpConnectorConfig,
+	HttpMethod,
 	HttpRequestInput,
 	HttpResponseOutput,
 } 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 HttpConnectorConfigSchema = z.object({
-	baseUrl: z.string().url(),
+	baseUrl: z
+		.string()
+		.url()
+		.refine((value) => /^https?:/i.test(value), 'baseUrl must use http: or https:'),
 	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 HttpRequestInputSchema = z.object({
@@ -53,6 +85,14 @@ export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
 	readonly name = 'HTTP Connector'
 	readonly description = 'Generic HTTP/REST API connector for making HTTP requests'
 	readonly connectionType: ConnectionType = 'http'
+	override readonly supportedAuth: readonly AuthType[] = [
+		'none',
+		'api_key',
+		'bearer',
+		'basic',
+		'oauth2',
+		'custom',
+	]
 	readonly configSchema = HttpConnectorConfigSchema
 	readonly methods: ConnectorMethod[] = [
 		{
@@ -63,66 +103,95 @@ export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
 	]
 
 	private baseUrl = ''
+	private baseOrigin = ''
 	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: HttpConnectorConfig, auth?: AuthConfig): Promise<void> {
-		this.config = config
+		const validated = HttpConnectorConfigSchema.parse(config)
+		const baseUrl = stripTrailingSlashes(validated.baseUrl)
+		const parsedBase = requireHttpUrl(baseUrl, 'HttpConnector baseUrl')
+		this.config = validated
 		this.auth = auth
-		this.baseUrl = stripTrailingSlashes(config.baseUrl)
-		this.defaultHeaders = config.defaultHeaders ?? {}
-		this.timeoutMs = config.timeoutMs ?? 30_000
+		this.baseUrl = baseUrl
+		this.baseOrigin = parsedBase.origin
+		this.defaultHeaders = { ...(validated.defaultHeaders ?? {}) }
+		this.timeoutMs = validateConnectorTimeoutMs(validated.timeoutMs, 'HttpConnector timeoutMs')
+		this.maxResponseBytes = validateConnectorMaxResponseBytes(
+			validated.maxResponseBytes,
+			'HttpConnector maxResponseBytes',
+		)
 
 		if (auth) {
 			Object.assign(this.defaultHeaders, this.resolveAuthHeaders(auth))
 		}
 
-		this.log.info('HTTP connector connected', { 'namzu.connector.base_url': this.baseUrl })
+		this.log.info('HTTP connector connected', {
+			'namzu.connector.base_url': this.baseUrl,
+		})
 	}
 
 	async disconnect(): Promise<void> {
 		this.config = null
 		this.auth = undefined
 		this.baseUrl = ''
+		this.baseOrigin = ''
 		this.defaultHeaders = {}
 		this.log.info('HTTP connector disconnected')
 	}
 
-	async healthCheck(): Promise<boolean> {
+	async healthCheck(options?: ConnectorOperationOptions): Promise<boolean> {
 		if (!this.baseUrl) return false
+		let operation: ConnectorHttpOperation | undefined
 		try {
-			const controller = new AbortController()
-			const timeout = setTimeout(() => controller.abort(), 5_000)
-			const response = await fetch(this.baseUrl, {
-				method: 'HEAD',
-				signal: controller.signal,
-			})
-			clearTimeout(timeout)
+			operation = new ConnectorHttpOperation(
+				options?.signal,
+				CONNECTOR_HEALTH_TIMEOUT_MS,
+				'HTTP connector health check',
+			)
+			const activeOperation = operation
+			const response = await activeOperation.run(() =>
+				fetch(this.baseUrl, {
+					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 HttpRequestInput
-
-		const { result, durationMs } = await this.measureExecution(() => this.doRequest(validated))
-
-		return {
-			success: result.status >= 200 && result.status < 400,
-			output: result,
-			durationMs,
-			metadata: {
-				status: result.status,
-				statusText: result.statusText,
-			},
+		const validated = (await this.validateInput(
+			this.requireMethod(method),
+			input,
+			options,
+		)) as HttpRequestInput
+		const startedAt = performance.now()
+		if (options?.signal?.aborted) {
+			return this.notStarted(validated.method, options.signal.reason, startedAt)
 		}
+		return this.doRequest(validated, options, startedAt)
 	}
 
-	private async doRequest(input: HttpRequestInput): Promise<HttpResponseOutput> {
+	private async doRequest(
+		input: HttpRequestInput,
+		options: ConnectorOperationOptions | undefined,
+		startedAt: number,
+	): Promise<ConnectorExecuteResult> {
 		const url = new URL(input.path, `${this.baseUrl}/`)
+		requireSameOrigin(url.toString(), this.baseOrigin, 'HttpConnector request URL')
+		requireSafeConnectorInputHeaders(input.headers, 'HttpConnector request headers')
 		if (input.query) {
 			for (const [key, value] of Object.entries(input.query)) {
 				url.searchParams.set(key, value)
@@ -134,45 +203,166 @@ export class HttpConnector extends BaseConnector<HttpConnectorConfig> {
 			...input.headers,
 		}
 
-		if (input.body && !headers['content-type'] && !headers['Content-Type']) {
+		if (input.body !== undefined && !headers['content-type'] && !headers['Content-Type']) {
 			headers['Content-Type'] = 'application/json'
 		}
 
-		const controller = new AbortController()
-		const timeout = setTimeout(() => controller.abort(), this.timeoutMs)
+		let operation: ConnectorHttpOperation | undefined
 
 		try {
-			const response = await fetch(url.toString(), {
-				method: input.method,
-				headers,
-				body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
-				signal: controller.signal,
-			})
+			try {
+				operation = new ConnectorHttpOperation(
+					options?.signal,
+					this.timeoutMs,
+					`HTTP connector ${input.method}`,
+				)
+			} catch (error) {
+				return this.notStarted(input.method, error, startedAt)
+			}
+			let response: Response
+			try {
+				const activeOperation = operation
+				response = await activeOperation.run(() =>
+					fetch(url.toString(), {
+						method: input.method,
+						headers,
+						body: input.body !== undefined ? JSON.stringify(input.body) : undefined,
+						redirect: 'manual',
+						signal: activeOperation.signal,
+					}),
+				)
+			} catch (error) {
+				return this.unknownOutcome(input.method, error, startedAt)
+			}
 
 			const responseHeaders: Record<string, string> = {}
 			response.headers.forEach((value, key) => {
 				responseHeaders[key] = value
 			})
 
+			const retrySafety = this.retrySafety(input.method)
+			const metadata: ConnectorExecutionMetadata = {
+				status: response.status,
+				statusText: response.statusText,
+				remoteOutcome: 'response_received',
+				retrySafety,
+				bodyAvailable: true,
+			}
 			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 bodyError = `Response body unavailable: ${this.errorText(error)}`
+				const output: HttpResponseOutput = {
+					status: response.status,
+					statusText: response.statusText,
+					headers: responseHeaders,
+					body: null,
+					bodyAvailable: false,
+					bodyError,
+					remoteOutcome: 'response_received',
+					retrySafety,
+				}
+				metadata.bodyAvailable = false
+				return {
+					success: response.status >= 200 && response.status < 300,
+					output,
+					...(response.status < 200 || response.status >= 300
+						? { error: this.statusError(response, retrySafety, true) }
+						: {}),
+					durationMs: this.duration(startedAt),
+					metadata,
+				}
 			}
 
-			return {
+			const output: HttpResponseOutput = {
 				status: response.status,
 				statusText: response.statusText,
 				headers: responseHeaders,
 				body,
+				bodyAvailable: true,
+				remoteOutcome: 'response_received',
+				retrySafety,
+			}
+			return {
+				success: response.status >= 200 && response.status < 300,
+				output,
+				...(response.status < 200 || response.status >= 300
+					? { error: this.statusError(response, retrySafety, false) }
+					: {}),
+				durationMs: this.duration(startedAt),
+				metadata,
 			}
 		} finally {
-			clearTimeout(timeout)
+			operation?.close()
 		}
 	}
 
+	private notStarted(
+		method: HttpMethod,
+		reason: unknown,
+		startedAt: number,
+	): ConnectorExecuteResult {
+		return {
+			success: false,
+			output: null,
+			error: `HTTP ${method} 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(
+		method: HttpMethod,
+		error: unknown,
+		startedAt: number,
+	): ConnectorExecuteResult {
+		const retrySafety = this.retrySafety(method)
+		const advice =
+			retrySafety === 'safe'
+				? `Retry is safe because ${method} is a safe HTTP method.`
+				: 'Do not automatically retry this request; it may duplicate a remote side effect.'
+		return {
+			success: false,
+			output: null,
+			error: `HTTP ${method} produced no response: ${this.errorText(error)}. The remote outcome is unknown. ${advice}`,
+			durationMs: this.duration(startedAt),
+			metadata: { remoteOutcome: 'unknown', retrySafety, bodyAvailable: false },
+		}
+	}
+
+	private statusError(
+		response: Response,
+		retrySafety: 'safe' | 'unsafe',
+		bodyMissing: boolean,
+	): string {
+		const retry =
+			retrySafety === 'safe'
+				? 'Retry is safe for this HTTP method.'
+				: 'Do not automatically retry; the remote side effect may already have happened.'
+		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 connector requests cannot leave their configured origin.${location ? ` Location: ${location}.` : ''} ${retry}`
+		}
+		return `HTTP ${response.status}: ${response.statusText}.${bodyMissing ? ' The response body was unavailable.' : ''} ${retry}`
+	}
+
+	private retrySafety(method: HttpMethod): 'safe' | 'unsafe' {
+		return method === 'GET' || method === 'HEAD' ? 'safe' : 'unsafe'
+	}
+
+	private duration(startedAt: number): number {
+		return Math.round(performance.now() - startedAt)
+	}
+
+	private errorText(error: unknown): string {
+		return error instanceof Error ? error.message : String(error)
+	}
+
 	private resolveAuthHeaders(auth: AuthConfig): Record<string, string> {
 		const creds = auth.credentials ?? {}
 		switch (auth.type) {