@tencent-ai/cloud-agent-sdk 0.3.0 → 0.3.1

package/dist/index.mjs

@@ -1,3 +1,94 @@
+//#region src/v1/internal/log.ts
+/** 级别数值：越大越详细；方法级别 > 当前级别时，该方法变成 noop。 */
+const LEVEL_NUMBER = {
+	off: 0,
+	error: 200,
+	warn: 300,
+	info: 400,
+	debug: 500
+};
+/** 默认级别（不配置时）。 */
+const DEFAULT_LEVEL = "warn";
+/** 真正的空函数。替换被关闭的级别，避免字符串拼接开销。 */
+const noop = () => {};
+/** 全 noop 的 logger（内部单例）。 */
+const noopLogger = {
+	error: noop,
+	warn: noop,
+	info: noop,
+	debug: noop
+};
+/**
+* 缓存 `[baseLogger, logLevel] -> wrappedLogger`。
+*
+* 用 WeakMap<Logger, ...>：只要 user 传的 logger 引用不变、level 不变，就复用。
+*/
+const cache = /* @__PURE__ */ new WeakMap();
+/**
+* 解析级别字符串；非法值返回 undefined（调用方自行回退）。
+*/
+function parseLogLevel(value) {
+	if (typeof value !== "string") return void 0;
+	const lower = value.toLowerCase();
+	if (lower in LEVEL_NUMBER) return lower;
+}
+/**
+* 读取环境变量 `CLOUD_AGENT_SDK_LOG`（仅 Node.js 环境，浏览器返回 undefined）。
+*
+* 用 `globalThis` 方式访问避免对 `@types/node` 的强依赖。
+*/
+function readEnvLogLevel() {
+	const env = globalThis.process?.env;
+	if (!env) return void 0;
+	return parseLogLevel(env.CLOUD_AGENT_SDK_LOG);
+}
+/**
+* 按 ConnectionOpts 决定最终的 LogLevel。
+*
+* 优先级：`opts.logLevel` > env `CLOUD_AGENT_SDK_LOG` > `'warn'`。
+*/
+function resolveLogLevel(opts) {
+	return parseLogLevel(opts.logLevel) ?? readEnvLogLevel() ?? DEFAULT_LEVEL;
+}
+/**
+* 返回按 `opts` 过滤后的 Logger。
+*
+* - `opts.logger` 为空时使用 `globalThis.console`
+* - 级别关闭时返回 noop，开启时返回 `baseLogger[fn].bind(baseLogger)`
+* - 相同入参多次调用复用同一对象（WeakMap 缓存）
+*/
+function loggerFor(opts) {
+	const base = opts.logger ?? console;
+	const level = resolveLogLevel(opts);
+	if (level === "off") return noopLogger;
+	let byLevel = cache.get(base);
+	if (!byLevel) {
+		byLevel = /* @__PURE__ */ new Map();
+		cache.set(base, byLevel);
+	}
+	const cached = byLevel.get(level);
+	if (cached) return cached;
+	const wrapped = makeLeveledLogger(base, level);
+	byLevel.set(level, wrapped);
+	return wrapped;
+}
+/**
+* 按级别构造 Logger：开放的级别直接 bind，关闭的级别替换为 noop。
+*
+* bind 而非 wrap 是为了保留调用点的 stack trace（开发者看日志能点回 SDK 行号）。
+*/
+function makeLeveledLogger(base, level) {
+	const threshold = LEVEL_NUMBER[level];
+	const enable = (fn) => LEVEL_NUMBER[fn] <= threshold && typeof base[fn] === "function" ? base[fn].bind(base) : noop;
+	return {
+		error: enable("error"),
+		warn: enable("warn"),
+		info: enable("info"),
+		debug: enable("debug")
+	};
+}
+
+//#endregion
 //#region src/v1/errors.ts
 var CloudAgentError = class extends Error {
 	constructor(message, opts = {}) {
@@ -5,7 +96,6 @@ var CloudAgentError = class extends Error {
 		this.name = "CloudAgentError";
 		this.code = opts.code ?? -1;
 		this.httpStatus = opts.httpStatus;
-		this.logId = opts.logId;
 		this.requestId = opts.requestId;
 		this.originalCause = opts.cause;
 		if (opts.cause && !("cause" in this)) Object.defineProperty(this, "cause", {
@@ -52,72 +142,433 @@ var AcpProtocolError = class extends CloudAgentError {
 };
 
 //#endregion
-//#region src/v1/acp/vendor/sdk.ts
-const PROTOCOL_VERSION = 1;
-async function loadAcpSdk() {
-	return import("@agentclientprotocol/sdk");
+//#region src/v1/internal/redact.ts
+/**
+* 敏感信息脱敏
+*
+* 范围：headers + 特定已知的 body 字段（白名单 path，非启发式猜测）。
+* 脱敏仅作用于日志打印和钩子回调，不影响实际发送的请求。
+*
+* 详见 docs/agentos/sdk/07-error-retry.md § 4.5。
+*/
+/** 需要脱敏的 header 名（小写）。 */
+const SENSITIVE_HEADER_NAMES = new Set([
+	"authorization",
+	"cookie",
+	"set-cookie",
+	"x-api-key"
+]);
+/** 脱敏替换值。 */
+const REDACTED = "***";
+/**
+* 返回脱敏后的 headers 副本。
+*
+* - 键按原样保留（大小写不变）
+* - 值按键名（小写后）匹配敏感列表时替换为 `'***'`
+* - **纯函数**，不修改入参
+*/
+function redactHeaders(headers) {
+	if (!headers) return {};
+	const out = {};
+	for (const [name, value] of Object.entries(headers)) out[name] = SENSITIVE_HEADER_NAMES.has(name.toLowerCase()) ? REDACTED : value;
+	return out;
+}
+/** 判断 value 是否是对象数组（`Array<Record<string, unknown>>`）。 */
+function isObjectArray(v) {
+	return Array.isArray(v) && v.every((x) => x !== null && typeof x === "object" && !Array.isArray(x));
+}
+/**
+* Body 脱敏器：对给定对象做**浅复制 + 定向脱敏**，返回安全的日志副本。
+*
+* 不修改入参。若入参不是对象（string / number / ...），原样返回。
+*
+* 已处理字段：
+* - `agentManifest.secrets[].value` → `'***'`（保留 name，只脱 value）
+*/
+function redactBody(body) {
+	if (body === null || body === void 0) return body;
+	if (typeof body !== "object" || Array.isArray(body)) return body;
+	const input = body;
+	const out = { ...input };
+	const manifest = input.agentManifest;
+	if (manifest && typeof manifest === "object" && !Array.isArray(manifest)) {
+		const secrets = manifest.secrets;
+		if (isObjectArray(secrets)) out.agentManifest = {
+			...manifest,
+			secrets: secrets.map((s) => "value" in s ? {
+				...s,
+				value: REDACTED
+			} : s)
+		};
+	}
+	return out;
 }
 
 //#endregion
-//#region src/v1/acp/transport.ts
+//#region src/v1/rest/client.ts
+/** 默认 baseUrl */
+const DEFAULT_BASE_URL = "https://www.codebuddy.cn/v2/agentos";
 /**
-* 创建 Streamable HTTP transport。
-* 返回的对象实现 Stream 接口（readable + writable），可直接传给 ClientSideConnection。
+* SDK 内置的默认重试判定。
+*
+* 传 `retry: { retryOn: ... }` 会**完全替换**这里的规则（不叠加）。
+* 公开这个函数是为了让用户在自定义 `retryOn` 里可以手动调用回落到默认：
+*
+* ```ts
+* retry: {
+*     retryOn: (err, ctx) => {
+*         if (err instanceof TimeoutError && ctx.url.includes('/upload')) return false;
+*         return DEFAULT_RETRY_ON(err, ctx);
+*     },
+* }
+* ```
 */
-function createStreamableHttpTransport(options) {
-	const { endpoint, authToken, headers: customHeaders = {}, reconnect = {}, signal: externalSignal, fetch: customFetch = globalThis.fetch, onConnect, onDisconnect, onError, heartbeatTimeout = 6e4, connectionTimeout = 3e4, postTimeout = 3e4, backpressure = {} } = options;
-	const { enabled: reconnectEnabled = true, initialDelay = 1e3, maxDelay = 3e4, maxRetries = Infinity, jitter: jitterEnabled = true } = reconnect;
-	const { highWaterMark = 100, lowWaterMark = 50, pauseTimeout = 5e3 } = backpressure;
-	let connectionId;
-	let lastEventId;
-	let reconnectAttempts = 0;
-	let closed = false;
-	let isClosing = false;
-	let connectionVersion = 0;
-	let connectionReady;
-	let resolveConnection;
-	let rejectConnection;
-	connectionReady = new Promise((resolve, reject) => {
-		resolveConnection = resolve;
-		rejectConnection = reject;
-	});
-	const abortController = new AbortController();
-	function isAborted() {
-		return abortController.signal.aborted || (externalSignal?.aborted ?? false);
-	}
-	const messageQueue = [];
-	const messageResolvers = [];
-	let streamError = null;
-	let isPaused = false;
-	let resumeReading = null;
-	let lastActivity = Date.now();
-	let heartbeatCheckTimer;
-	function enqueueMessage(message) {
-		if (messageResolvers.length > 0) messageResolvers.shift()(message);
-		else {
-			messageQueue.push(message);
-			if (messageQueue.length >= highWaterMark) isPaused = true;
-		}
+const DEFAULT_RETRY_ON = (err, ctx) => {
+	if (err.name === "AbortError") return false;
+	if (err instanceof AuthError) return false;
+	if (err instanceof NotFoundError) return false;
+	if (err instanceof ValidationError) return false;
+	if (err instanceof AcpProtocolError) return false;
+	if (err instanceof TimeoutError) return ctx.method === "GET";
+	if (err instanceof NetworkError) return true;
+	return true;
+};
+/** 默认重试配置。 */
+const DEFAULT_RETRY = {
+	maxAttempts: 3,
+	backoffMs: 300,
+	backoffFactor: 2,
+	jitter: true,
+	retryOn: DEFAULT_RETRY_ON
+};
+var RestClient = class {
+	constructor(opts) {
+		this.opts = opts;
+		this.logger = loggerFor(opts);
+		this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
 	}
-	function dequeueMessage() {
-		if (closed) return Promise.resolve(null);
-		if (streamError) return Promise.reject(streamError);
-		if (messageQueue.length > 0) {
-			const message = messageQueue.shift();
-			if (isPaused && messageQueue.length <= lowWaterMark) {
-				isPaused = false;
-				if (resumeReading) queueMicrotask(() => resumeReading());
-			}
-			return Promise.resolve(message);
-		}
-		return new Promise((resolve) => {
-			messageResolvers.push(resolve);
-		});
+	/** GET 请求。 */
+	async get(path, query, opts) {
+		const url = this.buildUrl(path, query);
+		return this.request("GET", url, void 0, opts);
 	}
-	function updateLastActivity() {
-		lastActivity = Date.now();
+	/** POST 请求。 */
+	async post(path, body, opts) {
+		const url = this.buildUrl(path);
+		return this.request("POST", url, body, opts);
 	}
-	function startHeartbeatCheck(triggerReconnect) {
+	/** PATCH 请求。 */
+	async patch(path, body, opts) {
+		const url = this.buildUrl(path);
+		return this.request("PATCH", url, body, opts);
+	}
+	/** DELETE 请求。 */
+	async delete(path, opts) {
+		const url = this.buildUrl(path);
+		return this.request("DELETE", url, void 0, opts);
+	}
+	/** 构建完整 URL。 */
+	buildUrl(path, query) {
+		const base = (this.opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
+		const fullPath = path.startsWith("/") ? path : `/${path}`;
+		const url = new URL(`${base}${fullPath}`);
+		if (query) {
+			for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== "") url.searchParams.set(k, v);
+		}
+		return url.toString();
+	}
+	/** 构建请求 headers（含认证、身份、trace、自定义）。 */
+	buildHeaders(opts) {
+		const headers = {
+			"Content-Type": "application/json",
+			"Accept": "application/json"
+		};
+		if (this.opts.apiKey) headers["x-api-key"] = this.opts.apiKey;
+		if (this.opts.sourceApp) headers["X-Source-App"] = this.opts.sourceApp;
+		if (this.opts.sourceTenantId) headers["X-Source-Tenant-Id"] = this.opts.sourceTenantId;
+		if (this.opts.userId) headers["X-User-Id"] = this.opts.userId;
+		if (this.opts.headers) Object.assign(headers, this.opts.headers);
+		if (opts?.headers) Object.assign(headers, opts.headers);
+		headers["X-Request-Id"] = opts?.requestId ?? generateRequestId();
+		return headers;
+	}
+	/** 发起请求（含超时 + 重试 + 日志 + 脱敏 + hooks）。 */
+	async request(method, url, body, opts) {
+		const shouldRetry = opts?.retry !== void 0 ? opts.retry : this.opts.retry ?? DEFAULT_RETRY;
+		const ctx = {
+			attempt: 1,
+			startTimeMs: 0
+		};
+		const doRequest = async () => {
+			ctx.startTimeMs = Date.now();
+			const timeoutMs = opts?.timeoutMs ?? this.opts.timeoutMs ?? 3e4;
+			const headers = this.buildHeaders(opts);
+			const requestId = headers["X-Request-Id"];
+			const controller = new AbortController();
+			let timeoutId;
+			if (timeoutMs > 0) timeoutId = setTimeout(() => controller.abort(), timeoutMs);
+			if (opts?.signal) if (opts.signal.aborted) controller.abort();
+			else opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
+			const redactedReqHeaders = redactHeaders(headers);
+			this.opts.onRequest?.({
+				method,
+				url,
+				headers: { ...redactedReqHeaders }
+			});
+			this.logger.debug(`Sending HTTP Request: ${method} ${url}`, {
+				headers: redactedReqHeaders,
+				body: body !== void 0 ? truncate(redactBody(body)) : void 0
+			});
+			try {
+				const response = await this.fetchImpl(url, {
+					method,
+					headers,
+					body: body !== void 0 ? JSON.stringify(body) : void 0,
+					signal: controller.signal
+				});
+				const durationMs = Date.now() - ctx.startTimeMs;
+				const responseHeaders = {};
+				response.headers.forEach((v, k) => {
+					responseHeaders[k] = v;
+				});
+				const redactedResHeaders = redactHeaders(responseHeaders);
+				this.opts.onResponse?.({
+					status: response.status,
+					headers: { ...redactedResHeaders },
+					url
+				});
+				const serverReqId = response.headers.get("x-request-id") ?? requestId;
+				this.logger.debug(`HTTP Response: ${method} ${url} "${response.status} ${response.statusText}" durationMs=${durationMs}`, { headers: redactedResHeaders });
+				if (serverReqId) this.logger.debug(`request_id: ${serverReqId}`);
+				return await this.unwrap(response, serverReqId);
+			} catch (err) {
+				if (timeoutId) clearTimeout(timeoutId);
+				const durationMs = Date.now() - ctx.startTimeMs;
+				if (err instanceof Error && err.name === "AbortError") {
+					if (opts?.signal?.aborted) {
+						this.logger.debug(`Request cancelled by caller after ${durationMs}ms: ${method} ${url}`);
+						throw err;
+					}
+					const msg = `Request timed out after ${timeoutMs}ms: ${method} ${url}`;
+					this.logger.debug(msg);
+					throw new TimeoutError(msg, { cause: err });
+				}
+				if (err instanceof TypeError || err instanceof Error && isNetworkError(err)) {
+					const msg = `Network error: ${method} ${url} - ${err.message}`;
+					this.logger.debug(msg);
+					throw new NetworkError(msg, { cause: err });
+				}
+				if (err instanceof CloudAgentError) throw err;
+				const msg = `Unexpected error: ${method} ${url} - ${err.message}`;
+				this.logger.error(msg);
+				throw new NetworkError(msg, { cause: err });
+			} finally {
+				if (timeoutId) clearTimeout(timeoutId);
+			}
+		};
+		if (shouldRetry === false) return doRequest();
+		return this.withRetry(doRequest, shouldRetry, ctx, method, url);
+	}
+	/** 解包响应 `{ code, msg, data }` → `data` 或抛错。 */
+	async unwrap(response, serverReqId) {
+		if (response.status === 204) return;
+		let body;
+		let rawText;
+		try {
+			rawText = await response.text();
+			const safeText = rawText.replace(/:\s*(\d{17,})/g, (match, num) => match.replace(num, `"${num}"`));
+			body = JSON.parse(safeText);
+		} catch {
+			if (!response.ok) throw this.httpStatusToError(response.status, `HTTP ${response.status}`, { requestId: serverReqId });
+			return rawText;
+		}
+		const effectiveRequestId = body.requestId || serverReqId;
+		if (!response.ok) throw this.httpStatusToError(response.status, body.msg || `HTTP ${response.status}`, {
+			requestId: effectiveRequestId,
+			code: body.code
+		});
+		if (body.code !== 0) throw this.codeToError(body.code, body.msg, {
+			requestId: effectiveRequestId,
+			httpStatus: response.status
+		});
+		return body.data;
+	}
+	/** HTTP 状态码映射为错误。 */
+	httpStatusToError(status, message, ctx) {
+		const opts = {
+			httpStatus: status,
+			requestId: ctx.requestId,
+			code: ctx.code
+		};
+		switch (status) {
+			case 400: return new ValidationError(message, opts);
+			case 401:
+			case 403: return new AuthError(message, opts);
+			case 404: return new NotFoundError(message, opts);
+			case 408:
+			case 504: return new TimeoutError(message, opts);
+			case 429: return new NetworkError(message, opts);
+			default:
+				if (status >= 500) return new NetworkError(message, opts);
+				return new CloudAgentError(message, opts);
+		}
+	}
+	/** 业务 code 映射为错误。 */
+	codeToError(code, message, ctx) {
+		const opts = {
+			code,
+			httpStatus: ctx.httpStatus,
+			requestId: ctx.requestId
+		};
+		switch (code) {
+			case 10001: return new ValidationError(message, opts);
+			case 10034:
+			case 10085: return new AuthError(message, opts);
+			case 10064:
+			case 10065:
+			case 10067: return new NetworkError(message, opts);
+			case 10084: return new NotFoundError(message, opts);
+			case 10094: return new TimeoutError(message, opts);
+			case 1e4: return new NetworkError(message, opts);
+			default: return new CloudAgentError(message, opts);
+		}
+	}
+	/**
+	* 重试逻辑。
+	*
+	* 是否重试只看 `opts.retryOn(err, ctx)`。用户传的 retryOn **完全替换** SDK
+	* 默认判定（不叠加、不 fallback 到 error 类上的任何字段）。
+	*/
+	async withRetry(fn, retryOpts, reqCtx, method, url) {
+		const opts = {
+			...DEFAULT_RETRY,
+			...retryOpts
+		};
+		let lastError;
+		for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) {
+			reqCtx.attempt = attempt;
+			try {
+				return await fn();
+			} catch (err) {
+				lastError = err;
+				const retryCtx = {
+					attempt,
+					method,
+					url
+				};
+				if (!opts.retryOn(err, retryCtx)) throw err;
+				if (attempt >= opts.maxAttempts) break;
+				const delayMs = this.getBackoffMs(attempt, opts);
+				this.logger.warn(`Retrying request to ${method} ${url} in ${delayMs}ms (attempt ${attempt}/${opts.maxAttempts}): ${err.name}: ${err.message}`);
+				await sleep(delayMs);
+			}
+		}
+		throw lastError;
+	}
+	/** 计算退避时间。 */
+	getBackoffMs(attempt, opts) {
+		const baseDelay = Math.min(opts.backoffMs * Math.pow(opts.backoffFactor, attempt - 1), 3e4);
+		if (!opts.jitter) return Math.round(baseDelay);
+		const jitterFactor = .2 * (Math.random() * 2 - 1);
+		return Math.round(baseDelay * (1 + jitterFactor));
+	}
+};
+function sleep(ms) {
+	return new Promise((resolve) => setTimeout(resolve, ms));
+}
+function isNetworkError(err) {
+	const msg = err.message.toLowerCase();
+	return msg.includes("failed to fetch") || msg.includes("fetch failed") || msg.includes("network") || msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("enotfound") || msg.includes("socket hang up");
+}
+function generateRequestId() {
+	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
+	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
+		const r = Math.random() * 16 | 0;
+		return (c === "x" ? r : r & 3 | 8).toString(16);
+	});
+}
+/**
+* 截断超长 body 用于 debug 日志，避免刷屏。
+*
+* 调用方应先通过 `redactBody()` 做敏感字段脱敏，此函数只负责序列化 + 截断。
+*/
+function truncate(body, maxChars = 500) {
+	try {
+		const str = typeof body === "string" ? body : JSON.stringify(body);
+		if (str.length <= maxChars) return str;
+		return str.slice(0, maxChars) + `…(truncated, total ${str.length} chars)`;
+	} catch {
+		return "[unserializable]";
+	}
+}
+
+//#endregion
+//#region src/v1/acp/vendor/sdk.ts
+const PROTOCOL_VERSION = 1;
+async function loadAcpSdk() {
+	return import("@agentclientprotocol/sdk");
+}
+
+//#endregion
+//#region src/v1/acp/transport.ts
+/**
+* 创建 Streamable HTTP transport。
+* 返回的对象实现 Stream 接口（readable + writable），可直接传给 ClientSideConnection。
+*/
+function createStreamableHttpTransport(options) {
+	const { endpoint, authToken, headers: customHeaders = {}, reconnect = {}, signal: externalSignal, fetch: customFetch = globalThis.fetch, onConnect, onDisconnect, onError, heartbeatTimeout = 6e4, connectionTimeout = 3e4, postTimeout = 3e4, backpressure = {} } = options;
+	const { enabled: reconnectEnabled = true, initialDelay = 1e3, maxDelay = 3e4, maxRetries = Infinity, jitter: jitterEnabled = true } = reconnect;
+	const { highWaterMark = 100, lowWaterMark = 50, pauseTimeout = 5e3 } = backpressure;
+	let connectionId;
+	let lastEventId;
+	let reconnectAttempts = 0;
+	let closed = false;
+	let isClosing = false;
+	let connectionVersion = 0;
+	let connectionReady;
+	let resolveConnection;
+	let rejectConnection;
+	connectionReady = new Promise((resolve, reject) => {
+		resolveConnection = resolve;
+		rejectConnection = reject;
+	});
+	const abortController = new AbortController();
+	function isAborted() {
+		return abortController.signal.aborted || (externalSignal?.aborted ?? false);
+	}
+	const messageQueue = [];
+	const messageResolvers = [];
+	let streamError = null;
+	let isPaused = false;
+	let resumeReading = null;
+	let lastActivity = Date.now();
+	let heartbeatCheckTimer;
+	function enqueueMessage(message) {
+		if (messageResolvers.length > 0) messageResolvers.shift()(message);
+		else {
+			messageQueue.push(message);
+			if (messageQueue.length >= highWaterMark) isPaused = true;
+		}
+	}
+	function dequeueMessage() {
+		if (closed) return Promise.resolve(null);
+		if (streamError) return Promise.reject(streamError);
+		if (messageQueue.length > 0) {
+			const message = messageQueue.shift();
+			if (isPaused && messageQueue.length <= lowWaterMark) {
+				isPaused = false;
+				if (resumeReading) queueMicrotask(() => resumeReading());
+			}
+			return Promise.resolve(message);
+		}
+		return new Promise((resolve) => {
+			messageResolvers.push(resolve);
+		});
+	}
+	function updateLastActivity() {
+		lastActivity = Date.now();
+	}
+	function startHeartbeatCheck(triggerReconnect) {
 		if (heartbeatTimeout <= 0) return;
 		heartbeatCheckTimer = setInterval(() => {
 			if (Date.now() - lastActivity > heartbeatTimeout) triggerReconnect();
@@ -597,2004 +1048,1580 @@ var InvalidStateError = class extends ACPClientError {
 	constructor(operation, currentState, expectedStates) {
 		super(`Cannot perform '${operation}' in state '${currentState}'. Expected: ${expectedStates.join(" or ")}`, "INVALID_STATE_ERROR");
 		this.name = "InvalidStateError";
-		this.currentState = currentState;
-		this.expectedStates = expectedStates;
-	}
-};
-
-//#endregion
-//#region src/v1/acp/vendor/events.ts
-/**
-* Type-safe event emitter implementation
-*/
-var EventEmitter = class {
-	constructor() {
-		this.listeners = /* @__PURE__ */ new Map();
-		this.onceListeners = /* @__PURE__ */ new Map();
-	}
-	/**
-	* Add an event listener
-	*/
-	on(event, listener) {
-		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
-		this.listeners.get(event).add(listener);
-		return this;
-	}
-	/**
-	* Remove an event listener
-	*/
-	off(event, listener) {
-		const eventListeners = this.listeners.get(event);
-		if (eventListeners) eventListeners.delete(listener);
-		const onceEventListeners = this.onceListeners.get(event);
-		if (onceEventListeners) onceEventListeners.delete(listener);
-		return this;
-	}
-	/**
-	* Add a one-time event listener
-	*/
-	once(event, listener) {
-		if (!this.onceListeners.has(event)) this.onceListeners.set(event, /* @__PURE__ */ new Set());
-		this.onceListeners.get(event).add(listener);
-		return this;
-	}
-	/**
-	* Emit an event to all registered listeners
-	* Returns true if any listeners were invoked
-	*/
-	emit(event, data) {
-		const regularListeners = this.listeners.get(event);
-		const onceEventListeners = this.onceListeners.get(event);
-		let hasListeners = false;
-		if (regularListeners && regularListeners.size > 0) {
-			hasListeners = true;
-			for (const listener of regularListeners) try {
-				const result = listener(data);
-				if (result instanceof Promise) result.catch((err) => {
-					console.error(`Error in async event listener for '${String(event)}':`, err);
-				});
-			} catch (err) {
-				console.error(`Error in event listener for '${String(event)}':`, err);
-			}
-		}
-		if (onceEventListeners && onceEventListeners.size > 0) {
-			hasListeners = true;
-			const listenersToCall = Array.from(onceEventListeners);
-			this.onceListeners.delete(event);
-			for (const listener of listenersToCall) try {
-				const result = listener(data);
-				if (result instanceof Promise) result.catch((err) => {
-					console.error(`Error in async once event listener for '${String(event)}':`, err);
-				});
-			} catch (err) {
-				console.error(`Error in once event listener for '${String(event)}':`, err);
-			}
-		}
-		return hasListeners;
-	}
-	/**
-	* Remove all listeners for an event, or all listeners if no event specified
-	*/
-	removeAllListeners(event) {
-		if (event !== void 0) {
-			this.listeners.delete(event);
-			this.onceListeners.delete(event);
-		} else {
-			this.listeners.clear();
-			this.onceListeners.clear();
-		}
-		return this;
-	}
-	/**
-	* Get the number of listeners for an event
-	*/
-	listenerCount(event) {
-		return (this.listeners.get(event)?.size ?? 0) + (this.onceListeners.get(event)?.size ?? 0);
-	}
-	/**
-	* Get all event names that have listeners
-	*/
-	eventNames() {
-		const names = /* @__PURE__ */ new Set();
-		for (const event of this.listeners.keys()) names.add(event);
-		for (const event of this.onceListeners.keys()) names.add(event);
-		return Array.from(names);
-	}
-};
-
-//#endregion
-//#region src/v1/acp/vendor/extensions.ts
-/**
-* Extension Method Handler for Streamable HTTP ACP Client
-* Routes and handles custom extension notifications
-*/
-/**
-* Manages extension methods and notifications
-*/
-var ExtensionManager = class {
-	constructor(config = {}) {
-		this.handlers = /* @__PURE__ */ new Map();
-		this.config = config;
-	}
-	/**
-	* Register a handler for a specific extension method
-	*/
-	registerHandler(method, handler) {
-		this.handlers.set(method, handler);
-		return () => {
-			this.handlers.delete(method);
-		};
-	}
-	/**
-	* Set a fallback handler for unknown extensions
-	*/
-	setFallbackHandler(handler) {
-		this.fallbackHandler = handler;
-	}
-	/**
-	* Handle an extension notification
-	*/
-	async handleNotification(method, params) {
-		this.config.logger?.debug(`Extension notification: ${method}`);
-		const handler = this.handlers.get(method);
-		if (handler) {
-			await handler(method, params);
-			return;
-		}
-		if (this.fallbackHandler) {
-			await this.fallbackHandler(method, params);
-			return;
-		}
-		if (!this.isKnownExtension(method)) this.config.logger?.warn(`Unknown extension notification: ${method}`);
-	}
-	/**
-	* Check if a method is a known extension
-	*/
-	isKnownExtension(method) {
-		return KNOWN_EXTENSIONS.includes(method);
-	}
-	/**
-	* Check if method is the artifact extension
-	*/
-	isArtifactExtension(method) {
-		return method === ExtensionMethod.ARTIFACT;
-	}
-	/**
-	* Clear all handlers
-	*/
-	clear() {
-		this.handlers.clear();
-		this.fallbackHandler = void 0;
+		this.currentState = currentState;
+		this.expectedStates = expectedStates;
 	}
 };
 
 //#endregion
-//#region src/v1/acp/vendor/permissions.ts
+//#region src/v1/acp/vendor/events.ts
 /**
-* Manages permission requests from the agent
+* Type-safe event emitter implementation
 */
-var PermissionManager = class {
-	constructor(config = {}) {
-		this.pending = /* @__PURE__ */ new Map();
-		this.callbacks = {};
-		this.config = {
-			timeout: DEFAULT_PERMISSION_TIMEOUT,
-			autoRejectOnTimeout: true,
-			autoApprove: false,
-			...config
-		};
-	}
-	/**
-	* Set event callbacks
-	*/
-	setCallbacks(callbacks) {
-		this.callbacks = callbacks;
+var EventEmitter = class {
+	constructor() {
+		this.listeners = /* @__PURE__ */ new Map();
+		this.onceListeners = /* @__PURE__ */ new Map();
 	}
 	/**
-	* Handle a permission request from the agent
+	* Add an event listener
 	*/
-	async handleRequest(params) {
-		const requestId = params.toolCall.toolCallId;
-		this.config.logger?.debug(`Permission request received: ${requestId}`);
-		if (this.config.autoApprove) {
-			const firstOption = params.options[0];
-			this.config.logger?.debug(`Auto-approving permission: ${requestId}`);
-			return { outcome: {
-				outcome: "selected",
-				optionId: firstOption?.optionId ?? "approve"
-			} };
-		}
-		if (this.config.handler) return this.config.handler(params);
-		return new Promise((resolve, reject) => {
-			const pending = {
-				params,
-				resolve,
-				reject,
-				createdAt: Date.now()
-			};
-			if (this.config.timeout && this.config.timeout > 0) pending.timeoutId = setTimeout(() => {
-				this.handleTimeout(requestId);
-			}, this.config.timeout);
-			this.pending.set(requestId, pending);
-			this.callbacks.onRequest?.(requestId, params);
-		});
+	on(event, listener) {
+		if (!this.listeners.has(event)) this.listeners.set(event, /* @__PURE__ */ new Set());
+		this.listeners.get(event).add(listener);
+		return this;
 	}
 	/**
-	* Handle timeout for a permission request
+	* Remove an event listener
 	*/
-	handleTimeout(requestId) {
-		const pending = this.pending.get(requestId);
-		if (!pending) return;
-		this.config.logger?.warn(`Permission request timed out: ${requestId}`);
-		this.callbacks.onTimeout?.(requestId);
-		if (this.config.autoRejectOnTimeout) pending.resolve({ outcome: { outcome: "cancelled" } });
-		else pending.reject(new TimeoutError$1("permission", this.config.timeout ?? DEFAULT_PERMISSION_TIMEOUT));
-		this.pending.delete(requestId);
+	off(event, listener) {
+		const eventListeners = this.listeners.get(event);
+		if (eventListeners) eventListeners.delete(listener);
+		const onceEventListeners = this.onceListeners.get(event);
+		if (onceEventListeners) onceEventListeners.delete(listener);
+		return this;
 	}
 	/**
-	* Resolve a permission request with a selected option
-	* Returns true if the permission was found and resolved
+	* Add a one-time event listener
 	*/
-	resolve(requestId, optionId) {
-		const pending = this.pending.get(requestId);
-		if (!pending) {
-			this.config.logger?.warn(`Permission request not found: ${requestId}`);
-			return false;
-		}
-		if (pending.timeoutId) clearTimeout(pending.timeoutId);
-		this.config.logger?.debug(`Permission resolved: ${requestId} -> ${optionId}`);
-		pending.resolve({ outcome: {
-			outcome: "selected",
-			optionId
-		} });
-		this.pending.delete(requestId);
-		this.callbacks.onResolved?.(requestId, optionId);
-		return true;
+	once(event, listener) {
+		if (!this.onceListeners.has(event)) this.onceListeners.set(event, /* @__PURE__ */ new Set());
+		this.onceListeners.get(event).add(listener);
+		return this;
 	}
 	/**
-	* Reject (cancel) a permission request
-	* Returns true if the permission was found and rejected
+	* Emit an event to all registered listeners
+	* Returns true if any listeners were invoked
 	*/
-	reject(requestId, reason) {
-		const pending = this.pending.get(requestId);
-		if (!pending) {
-			this.config.logger?.warn(`Permission request not found: ${requestId}`);
-			return false;
+	emit(event, data) {
+		const regularListeners = this.listeners.get(event);
+		const onceEventListeners = this.onceListeners.get(event);
+		let hasListeners = false;
+		if (regularListeners && regularListeners.size > 0) {
+			hasListeners = true;
+			for (const listener of regularListeners) try {
+				const result = listener(data);
+				if (result instanceof Promise) result.catch((err) => {
+					console.error(`Error in async event listener for '${String(event)}':`, err);
+				});
+			} catch (err) {
+				console.error(`Error in event listener for '${String(event)}':`, err);
+			}
 		}
-		if (pending.timeoutId) clearTimeout(pending.timeoutId);
-		this.config.logger?.debug(`Permission rejected: ${requestId}${reason ? ` - ${reason}` : ""}`);
-		pending.resolve({ outcome: { outcome: "cancelled" } });
-		this.pending.delete(requestId);
-		this.callbacks.onRejected?.(requestId, reason);
-		return true;
-	}
-	/**
-	* Get all pending permissions
-	*/
-	getPending() {
-		const result = /* @__PURE__ */ new Map();
-		for (const [id, pending] of this.pending) result.set(id, {
-			params: pending.params,
-			createdAt: pending.createdAt
-		});
-		return result;
-	}
-	/**
-	* Get a specific pending permission
-	*/
-	getPendingById(requestId) {
-		const pending = this.pending.get(requestId);
-		if (!pending) return;
-		return {
-			params: pending.params,
-			createdAt: pending.createdAt
-		};
-	}
-	/**
-	* Check if there are any pending permissions
-	*/
-	hasPending() {
-		return this.pending.size > 0;
-	}
-	/**
-	* Get the count of pending permissions
-	*/
-	get pendingCount() {
-		return this.pending.size;
-	}
-	/**
-	* Clear all pending permissions (reject all)
-	*/
-	clear() {
-		for (const [requestId, pending] of this.pending) {
-			if (pending.timeoutId) clearTimeout(pending.timeoutId);
-			pending.resolve({ outcome: { outcome: "cancelled" } });
-			this.callbacks.onRejected?.(requestId, "cleared");
+		if (onceEventListeners && onceEventListeners.size > 0) {
+			hasListeners = true;
+			const listenersToCall = Array.from(onceEventListeners);
+			this.onceListeners.delete(event);
+			for (const listener of listenersToCall) try {
+				const result = listener(data);
+				if (result instanceof Promise) result.catch((err) => {
+					console.error(`Error in async once event listener for '${String(event)}':`, err);
+				});
+			} catch (err) {
+				console.error(`Error in once event listener for '${String(event)}':`, err);
+			}
 		}
-		this.pending.clear();
-		this.config.logger?.debug("Cleared all pending permissions");
-	}
-	/**
-	* Update configuration
-	*/
-	updateConfig(config) {
-		this.config = {
-			...this.config,
-			...config
-		};
-	}
-};
-
-//#endregion
-//#region src/v1/acp/vendor/questions.ts
-/**
-* Manages question requests from the agent (ask_followup_question tool)
-*/
-var QuestionManager = class {
-	constructor(config = {}) {
-		this.pending = /* @__PURE__ */ new Map();
-		this.callbacks = {};
-		this.config = {
-			timeout: DEFAULT_QUESTION_TIMEOUT,
-			autoCancelOnTimeout: true,
-			...config
-		};
-	}
-	/**
-	* Set event callbacks
-	*/
-	setCallbacks(callbacks) {
-		this.callbacks = callbacks;
-	}
-	/**
-	* Handle a question request from the agent
-	* Called when receiving _codebuddy.ai/question extMethod
-	*/
-	async handleRequest(request) {
-		const toolCallId = request.toolCallId;
-		this.config.logger?.debug(`Question request received: ${toolCallId}`);
-		return new Promise((resolve, reject) => {
-			const pending = {
-				request,
-				resolve,
-				reject,
-				createdAt: Date.now()
-			};
-			const timeout = request.timeout ?? this.config.timeout;
-			if (timeout && timeout > 0) pending.timeoutId = setTimeout(() => {
-				this.handleTimeout(toolCallId);
-			}, timeout);
-			this.pending.set(toolCallId, pending);
-			this.callbacks.onRequest?.(toolCallId, request);
-		});
+		return hasListeners;
 	}
 	/**
-	* Handle timeout for a question request
+	* Remove all listeners for an event, or all listeners if no event specified
 	*/
-	handleTimeout(toolCallId) {
-		const pending = this.pending.get(toolCallId);
-		if (!pending) return;
-		this.config.logger?.warn(`Question request timed out: ${toolCallId}`);
-		this.callbacks.onTimeout?.(toolCallId);
-		if (this.config.autoCancelOnTimeout) pending.resolve({
-			outcome: "cancelled",
-			reason: "timeout"
-		});
-		else pending.reject(new TimeoutError$1("question", this.config.timeout ?? DEFAULT_QUESTION_TIMEOUT));
-		this.pending.delete(toolCallId);
+	removeAllListeners(event) {
+		if (event !== void 0) {
+			this.listeners.delete(event);
+			this.onceListeners.delete(event);
+		} else {
+			this.listeners.clear();
+			this.onceListeners.clear();
+		}
+		return this;
 	}
 	/**
-	* Answer a question request with user's selections
-	* Returns true if the request was found and answered
+	* Get the number of listeners for an event
 	*/
-	answer(toolCallId, answers) {
-		const pending = this.pending.get(toolCallId);
-		if (!pending) {
-			this.config.logger?.warn(`Question request not found: ${toolCallId}`);
-			return false;
-		}
-		if (pending.timeoutId) clearTimeout(pending.timeoutId);
-		this.config.logger?.debug(`Question answered: ${toolCallId}`);
-		pending.resolve({
-			outcome: "submitted",
-			answers
-		});
-		this.pending.delete(toolCallId);
-		this.callbacks.onAnswered?.(toolCallId, answers);
-		return true;
+	listenerCount(event) {
+		return (this.listeners.get(event)?.size ?? 0) + (this.onceListeners.get(event)?.size ?? 0);
 	}
 	/**
-	* Cancel a question request
-	* Returns true if the request was found and cancelled
+	* Get all event names that have listeners
 	*/
-	cancel(toolCallId, reason) {
-		const pending = this.pending.get(toolCallId);
-		if (!pending) {
-			this.config.logger?.warn(`Question request not found: ${toolCallId}`);
-			return false;
-		}
-		if (pending.timeoutId) clearTimeout(pending.timeoutId);
-		this.config.logger?.debug(`Question cancelled: ${toolCallId}${reason ? ` - ${reason}` : ""}`);
-		pending.resolve({
-			outcome: "cancelled",
-			reason
-		});
-		this.pending.delete(toolCallId);
-		this.callbacks.onCancelled?.(toolCallId, reason);
-		return true;
+	eventNames() {
+		const names = /* @__PURE__ */ new Set();
+		for (const event of this.listeners.keys()) names.add(event);
+		for (const event of this.onceListeners.keys()) names.add(event);
+		return Array.from(names);
+	}
+};
+
+//#endregion
+//#region src/v1/acp/vendor/extensions.ts
+/**
+* Extension Method Handler for Streamable HTTP ACP Client
+* Routes and handles custom extension notifications
+*/
+/**
+* Manages extension methods and notifications
+*/
+var ExtensionManager = class {
+	constructor(config = {}) {
+		this.handlers = /* @__PURE__ */ new Map();
+		this.config = config;
 	}
 	/**
-	* Get all pending question requests
+	* Register a handler for a specific extension method
 	*/
-	getPending() {
-		const result = /* @__PURE__ */ new Map();
-		for (const [id, pending] of this.pending) result.set(id, {
-			request: pending.request,
-			createdAt: pending.createdAt
-		});
-		return result;
+	registerHandler(method, handler) {
+		this.handlers.set(method, handler);
+		return () => {
+			this.handlers.delete(method);
+		};
 	}
 	/**
-	* Get a specific pending question request
+	* Set a fallback handler for unknown extensions
 	*/
-	getPendingById(toolCallId) {
-		const pending = this.pending.get(toolCallId);
-		if (!pending) return;
-		return {
-			request: pending.request,
-			createdAt: pending.createdAt
-		};
+	setFallbackHandler(handler) {
+		this.fallbackHandler = handler;
 	}
 	/**
-	* Check if there are any pending question requests
+	* Handle an extension notification
 	*/
-	hasPending() {
-		return this.pending.size > 0;
+	async handleNotification(method, params) {
+		this.config.logger?.debug(`Extension notification: ${method}`);
+		const handler = this.handlers.get(method);
+		if (handler) {
+			await handler(method, params);
+			return;
+		}
+		if (this.fallbackHandler) {
+			await this.fallbackHandler(method, params);
+			return;
+		}
+		if (!this.isKnownExtension(method)) this.config.logger?.warn(`Unknown extension notification: ${method}`);
 	}
 	/**
-	* Get the count of pending question requests
+	* Check if a method is a known extension
 	*/
-	get pendingCount() {
-		return this.pending.size;
+	isKnownExtension(method) {
+		return KNOWN_EXTENSIONS.includes(method);
 	}
 	/**
-	* Clear all pending question requests (cancel all)
+	* Check if method is the artifact extension
 	*/
-	clear() {
-		for (const [toolCallId, pending] of this.pending) {
-			if (pending.timeoutId) clearTimeout(pending.timeoutId);
-			pending.resolve({
-				outcome: "cancelled",
-				reason: "cleared"
-			});
-			this.callbacks.onCancelled?.(toolCallId, "cleared");
-		}
-		this.pending.clear();
-		this.config.logger?.debug("Cleared all pending question requests");
+	isArtifactExtension(method) {
+		return method === ExtensionMethod.ARTIFACT;
 	}
 	/**
-	* Update configuration
+	* Clear all handlers
 	*/
-	updateConfig(config) {
-		this.config = {
-			...this.config,
-			...config
-		};
+	clear() {
+		this.handlers.clear();
+		this.fallbackHandler = void 0;
 	}
 };
 
 //#endregion
-//#region src/v1/acp/vendor/client.ts
-/**
-* Streamable HTTP ACP Client
-* Production-grade client for connecting to cloud-hosted ACP agents
-*/
+//#region src/v1/acp/vendor/permissions.ts
 /**
-* Production-grade Streamable HTTP ACP Client
-*
-* Features:
-* - Full ACP protocol support (initialize, session, prompt, cancel)
-* - Artifact notification handling
-* - Permission handling with timeout support
-* - Extension method support
-* - Type-safe event system
-* - Configurable logging
+* Manages permission requests from the agent
 */
-var StreamableHttpClient = class {
-	constructor(options) {
-		this.state = "disconnected";
-		this.emitter = new EventEmitter();
-		this.options = options;
-		this.artifactManager = new ArtifactManager({ logger: options.logger });
-		this.permissionManager = new PermissionManager({
-			timeout: options.permissionTimeout,
-			autoRejectOnTimeout: options.permissionAutoRejectOnTimeout ?? true,
-			autoApprove: options.autoApprove,
-			handler: options.requestPermissionHandler,
-			logger: options.logger
-		});
-		this.permissionManager.setCallbacks({
-			onRequest: (requestId, params) => {
-				this.emitter.emit("permissionRequest", {
-					requestId,
-					params
-				});
-			},
-			onResolved: (requestId, optionId) => {
-				this.emitter.emit("permissionResolved", {
-					requestId,
-					optionId
-				});
-			},
-			onRejected: (requestId, reason) => {
-				this.emitter.emit("permissionRejected", {
-					requestId,
-					reason
-				});
-			},
-			onTimeout: (requestId) => {
-				this.emitter.emit("permissionTimeout", { requestId });
-			}
-		});
-		this.questionManager = new QuestionManager({
-			timeout: options.questionTimeout,
-			autoCancelOnTimeout: options.questionAutoCancelOnTimeout ?? true,
-			logger: options.logger
-		});
-		this.questionManager.setCallbacks({
-			onRequest: (toolCallId, request) => {
-				this.emitter.emit("questionRequest", {
-					toolCallId,
-					request
-				});
-				options.onQuestionRequest?.(toolCallId, request);
-			},
-			onAnswered: (toolCallId, answers) => {
-				this.emitter.emit("questionAnswered", {
-					toolCallId,
-					answers
-				});
-			},
-			onCancelled: (toolCallId, reason) => {
-				this.emitter.emit("questionCancelled", {
-					toolCallId,
-					reason
-				});
-			},
-			onTimeout: (toolCallId) => {
-				this.emitter.emit("questionTimeout", { toolCallId });
-			}
+var PermissionManager = class {
+	constructor(config = {}) {
+		this.pending = /* @__PURE__ */ new Map();
+		this.callbacks = {};
+		this.config = {
+			timeout: DEFAULT_PERMISSION_TIMEOUT,
+			autoRejectOnTimeout: true,
+			autoApprove: false,
+			...config
+		};
+	}
+	/**
+	* Set event callbacks
+	*/
+	setCallbacks(callbacks) {
+		this.callbacks = callbacks;
+	}
+	/**
+	* Handle a permission request from the agent
+	*/
+	async handleRequest(params) {
+		const requestId = params.toolCall.toolCallId;
+		this.config.logger?.debug(`Permission request received: ${requestId}`);
+		if (this.config.autoApprove) {
+			const firstOption = params.options[0];
+			this.config.logger?.debug(`Auto-approving permission: ${requestId}`);
+			return { outcome: {
+				outcome: "selected",
+				optionId: firstOption?.optionId ?? "approve"
+			} };
+		}
+		if (this.config.handler) return this.config.handler(params);
+		return new Promise((resolve, reject) => {
+			const pending = {
+				params,
+				resolve,
+				reject,
+				createdAt: Date.now()
+			};
+			if (this.config.timeout && this.config.timeout > 0) pending.timeoutId = setTimeout(() => {
+				this.handleTimeout(requestId);
+			}, this.config.timeout);
+			this.pending.set(requestId, pending);
+			this.callbacks.onRequest?.(requestId, params);
 		});
-		this.extensionManager = new ExtensionManager({ logger: options.logger });
 	}
 	/**
-	* Get current client state
+	* Handle timeout for a permission request
 	*/
-	get currentState() {
-		return this.state;
+	handleTimeout(requestId) {
+		const pending = this.pending.get(requestId);
+		if (!pending) return;
+		this.config.logger?.warn(`Permission request timed out: ${requestId}`);
+		this.callbacks.onTimeout?.(requestId);
+		if (this.config.autoRejectOnTimeout) pending.resolve({ outcome: { outcome: "cancelled" } });
+		else pending.reject(new TimeoutError$1("permission", this.config.timeout ?? DEFAULT_PERMISSION_TIMEOUT));
+		this.pending.delete(requestId);
 	}
 	/**
-	* Check if client is initialized
+	* Resolve a permission request with a selected option
+	* Returns true if the permission was found and resolved
 	*/
-	get isInitialized() {
-		return this.state === "initialized";
+	resolve(requestId, optionId) {
+		const pending = this.pending.get(requestId);
+		if (!pending) {
+			this.config.logger?.warn(`Permission request not found: ${requestId}`);
+			return false;
+		}
+		if (pending.timeoutId) clearTimeout(pending.timeoutId);
+		this.config.logger?.debug(`Permission resolved: ${requestId} -> ${optionId}`);
+		pending.resolve({ outcome: {
+			outcome: "selected",
+			optionId
+		} });
+		this.pending.delete(requestId);
+		this.callbacks.onResolved?.(requestId, optionId);
+		return true;
 	}
 	/**
-	* Check if client is connected (but maybe not initialized)
+	* Reject (cancel) a permission request
+	* Returns true if the permission was found and rejected
 	*/
-	get isConnected() {
-		return this.state === "connected" || this.state === "initialized";
+	reject(requestId, reason) {
+		const pending = this.pending.get(requestId);
+		if (!pending) {
+			this.config.logger?.warn(`Permission request not found: ${requestId}`);
+			return false;
+		}
+		if (pending.timeoutId) clearTimeout(pending.timeoutId);
+		this.config.logger?.debug(`Permission rejected: ${requestId}${reason ? ` - ${reason}` : ""}`);
+		pending.resolve({ outcome: { outcome: "cancelled" } });
+		this.pending.delete(requestId);
+		this.callbacks.onRejected?.(requestId, reason);
+		return true;
 	}
 	/**
-	* Get agent capabilities from initialization response
+	* Get all pending permissions
 	*/
-	get agentCapabilities() {
-		return this.initializeResponse?.agentCapabilities;
+	getPending() {
+		const result = /* @__PURE__ */ new Map();
+		for (const [id, pending] of this.pending) result.set(id, {
+			params: pending.params,
+			createdAt: pending.createdAt
+		});
+		return result;
 	}
 	/**
-	* Get full initialization response
+	* Get a specific pending permission
 	*/
-	get initializeResult() {
-		return this.initializeResponse;
+	getPendingById(requestId) {
+		const pending = this.pending.get(requestId);
+		if (!pending) return;
+		return {
+			params: pending.params,
+			createdAt: pending.createdAt
+		};
 	}
 	/**
-	* Get current transport connection ID
+	* Check if there are any pending permissions
 	*/
-	get connectionId() {
-		return this.transport?.connectionId;
-	}
-	setState(newState) {
-		const previous = this.state;
-		this.state = newState;
-		this.options.logger?.debug(`State change: ${previous} -> ${newState}`);
-		this.emitter.emit("stateChange", {
-			previous,
-			current: newState
-		});
-		switch (newState) {
-			case "connecting":
-				this.emitter.emit("connecting", void 0);
-				break;
-			case "connected":
-				this.emitter.emit("connected", void 0);
-				break;
-			case "disconnected":
-				this.emitter.emit("disconnected", void 0);
-				break;
-			case "error": break;
-		}
+	hasPending() {
+		return this.pending.size > 0;
 	}
 	/**
-	* Connect and initialize the client
+	* Get the count of pending permissions
 	*/
-	async connect() {
-		if (this.state !== "disconnected") await this.disconnect();
-		if (this.state === "initialized") return this.initializeResponse;
-		if (this.state === "connecting") throw new ConnectionError("Connection already in progress");
-		this.setState("connecting");
-		try {
-			this.transport = createStreamableHttpTransport({
-				endpoint: this.options.endpoint,
-				authToken: this.options.authToken,
-				headers: this.options.headers,
-				reconnect: this.options.reconnect,
-				fetch: this.options.fetch,
-				heartbeatTimeout: this.options.heartbeatTimeout,
-				postTimeout: this.options.postTimeout,
-				connectionTimeout: this.options.connectionTimeout,
-				onConnect: (connectionId) => {
-					this.options.logger?.debug(`Transport connected: ${connectionId}`);
-				},
-				onDisconnect: (connectionId) => {
-					this.options.logger?.debug(`Transport disconnected: ${connectionId}`);
-				},
-				onError: (error) => {
-					this.options.logger?.error("Transport error:", error);
-					this.emitter.emit("error", error);
-				}
-			});
-			const { ClientSideConnection } = await loadAcpSdk();
-			this.connection = new ClientSideConnection(() => this.createClientHandler(), this.transport);
-			this.setState("connected");
-			const timeout = this.options.initializeTimeout ?? DEFAULT_INITIALIZE_TIMEOUT;
-			const mergedCapabilities = {
-				...this.options.clientCapabilities,
-				...CLOUD_CLIENT_CAPABILITIES,
-				_meta: {
-					...this.options.clientCapabilities?._meta,
-					...CLOUD_CLIENT_CAPABILITIES._meta
-				}
-			};
-			const initPromise = this.connection.initialize({
-				protocolVersion: PROTOCOL_VERSION,
-				clientCapabilities: mergedCapabilities
-			});
-			const timeoutPromise = new Promise((_, reject) => {
-				setTimeout(() => {
-					reject(new InitializationError(`Initialize timed out after ${timeout}ms`));
-				}, timeout);
-			});
-			const initializeResponse = await Promise.race([initPromise, timeoutPromise]);
-			this.initializeResponse = initializeResponse;
-			this.setState("initialized");
-			this.options.logger?.info("Client initialized successfully");
-			return initializeResponse;
-		} catch (err) {
-			this.setState("error");
-			const error = err instanceof Error ? err : new Error(String(err));
-			this.emitter.emit("error", error);
-			if (err instanceof InitializationError || err instanceof ConnectionError) throw err;
-			throw new ConnectionError("Failed to connect", error);
-		}
+	get pendingCount() {
+		return this.pending.size;
 	}
 	/**
-	* Disconnect the client gracefully
-	* Sends DELETE request to server before closing local resources
+	* Clear all pending permissions (reject all)
 	*/
-	async disconnect() {
-		if (this.state === "disconnected") return;
-		this.options.logger?.info("Disconnecting client");
-		if (this.transport) {
-			try {
-				await this.transport.close();
-			} catch (err) {
-				this.options.logger?.warn("Error closing transport:", err);
-			}
-			this.transport = void 0;
+	clear() {
+		for (const [requestId, pending] of this.pending) {
+			if (pending.timeoutId) clearTimeout(pending.timeoutId);
+			pending.resolve({ outcome: { outcome: "cancelled" } });
+			this.callbacks.onRejected?.(requestId, "cleared");
 		}
-		this.permissionManager.clear();
-		this.questionManager.clear();
-		this.artifactManager.clear();
-		this.initializeResponse = void 0;
-		this.setState("disconnected");
+		this.pending.clear();
+		this.config.logger?.debug("Cleared all pending permissions");
 	}
 	/**
-	* Create the client handler for the connection
+	* Update configuration
 	*/
-	createClientHandler() {
-		return {
-			sessionUpdate: async (params) => {
-				await this.handleSessionUpdate(params);
-			},
-			requestPermission: async (params) => this.handleRequestPermission(params),
-			extNotification: async (method, params) => {
-				await this.handleExtNotification(method, params);
-			},
-			extMethod: async (method, params) => this.handleExtMethod(method, params)
+	updateConfig(config) {
+		this.config = {
+			...this.config,
+			...config
 		};
 	}
-	/**
-	* Create a new session
-	*
-	* Retries on transient network errors (e.g., proxy connection reset)
-	* since session/new is idempotent and safe to retry.
-	*
-	* A timeout (`options.sessionTimeout`, default 30 s) guards against the
-	* SSE response never arriving — the POST returns 202 immediately and the
-	* sessionId comes back via GET SSE, which can hang indefinitely.
-	* On timeout a `SessionError` is thrown.
-	*/
-	async createSession(cwd) {
-		this.ensureInitialized("createSession");
-		const maxRetries = 2;
-		const timeout = this.options.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT;
-		let lastError;
-		for (let attempt = 0; attempt <= maxRetries; attempt++) try {
-			const sessionPromise = this.connection.newSession({
-				cwd,
-				mcpServers: []
-			});
-			let response;
-			if (timeout > 0) {
-				const timeoutPromise = new Promise((_, reject) => {
-					setTimeout(() => {
-						reject(new SessionError(`session/new timed out after ${timeout}ms`));
-					}, timeout);
-				});
-				response = await Promise.race([sessionPromise, timeoutPromise]);
-			} else response = await sessionPromise;
-			this.options.logger?.info(`Session created: ${response.sessionId}`);
-			return response;
-		} catch (err) {
-			lastError = err instanceof Error ? err : new Error(String(err));
-			if (attempt < maxRetries && isRetryableNetworkError(err)) {
-				const delay = 500 * Math.pow(2, attempt);
-				this.options.logger?.warn(`session/new network error, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries}): ${lastError.message}`);
-				await new Promise((resolve) => setTimeout(resolve, delay));
-				continue;
-			}
-			throw new SessionError(`Failed to create session: ${lastError.message}`, void 0, lastError);
-		}
-		throw new SessionError(`Failed to create session: ${lastError?.message}`, void 0, lastError);
+};
+
+//#endregion
+//#region src/v1/acp/vendor/questions.ts
+/**
+* Manages question requests from the agent (ask_followup_question tool)
+*/
+var QuestionManager = class {
+	constructor(config = {}) {
+		this.pending = /* @__PURE__ */ new Map();
+		this.callbacks = {};
+		this.config = {
+			timeout: DEFAULT_QUESTION_TIMEOUT,
+			autoCancelOnTimeout: true,
+			...config
+		};
 	}
 	/**
-	* Load an existing session
-	* Requires agent to support loadSession capability
+	* Set event callbacks
 	*/
-	async loadSession(sessionId, cwd) {
-		this.ensureInitialized("loadSession");
-		if (!this.agentCapabilities?.loadSession) throw new SessionError("Agent does not support session loading", sessionId);
-		try {
-			const response = await this.connection.loadSession({
-				sessionId,
-				cwd,
-				mcpServers: []
-			});
-			this.options.logger?.info(`Session loaded: ${sessionId}`);
-			return response;
-		} catch (err) {
-			throw new SessionError(`Failed to load session: ${err instanceof Error ? err.message : String(err)}`, sessionId, err instanceof Error ? err : void 0);
-		}
+	setCallbacks(callbacks) {
+		this.callbacks = callbacks;
 	}
 	/**
-	* Set the session mode
+	* Handle a question request from the agent
+	* Called when receiving _codebuddy.ai/question extMethod
 	*/
-	async setSessionMode(params) {
-		this.ensureInitialized("setSessionMode");
-		this.options.logger?.debug(`Setting session mode: ${params.sessionId} -> ${params.modeId}`);
-		return this.connection.setSessionMode(params);
+	async handleRequest(request) {
+		const toolCallId = request.toolCallId;
+		this.config.logger?.debug(`Question request received: ${toolCallId}`);
+		return new Promise((resolve, reject) => {
+			const pending = {
+				request,
+				resolve,
+				reject,
+				createdAt: Date.now()
+			};
+			const timeout = request.timeout ?? this.config.timeout;
+			if (timeout && timeout > 0) pending.timeoutId = setTimeout(() => {
+				this.handleTimeout(toolCallId);
+			}, timeout);
+			this.pending.set(toolCallId, pending);
+			this.callbacks.onRequest?.(toolCallId, request);
+		});
 	}
 	/**
-	* Set the session model
-	* @experimental This API is unstable and may change
+	* Handle timeout for a question request
 	*/
-	async setSessionModel(params) {
-		this.ensureInitialized("setSessionModel");
-		this.options.logger?.debug(`Setting session model: ${params.sessionId} -> ${params.modelId}`);
-		return this.connection.unstable_setSessionModel(params);
+	handleTimeout(toolCallId) {
+		const pending = this.pending.get(toolCallId);
+		if (!pending) return;
+		this.config.logger?.warn(`Question request timed out: ${toolCallId}`);
+		this.callbacks.onTimeout?.(toolCallId);
+		if (this.config.autoCancelOnTimeout) pending.resolve({
+			outcome: "cancelled",
+			reason: "timeout"
+		});
+		else pending.reject(new TimeoutError$1("question", this.config.timeout ?? DEFAULT_QUESTION_TIMEOUT));
+		this.pending.delete(toolCallId);
 	}
 	/**
-	* Send a prompt to the agent
+	* Answer a question request with user's selections
+	* Returns true if the request was found and answered
 	*/
-	async prompt(sessionId, prompt, options) {
-		this.ensureInitialized("prompt");
-		this.options.logger?.debug(`Sending prompt to session: ${sessionId}`);
-		return this.connection.prompt({
-			sessionId,
-			prompt,
-			_meta: options?.planMode ? {
-				planMode: true,
-				...options._meta
-			} : options?._meta
+	answer(toolCallId, answers) {
+		const pending = this.pending.get(toolCallId);
+		if (!pending) {
+			this.config.logger?.warn(`Question request not found: ${toolCallId}`);
+			return false;
+		}
+		if (pending.timeoutId) clearTimeout(pending.timeoutId);
+		this.config.logger?.debug(`Question answered: ${toolCallId}`);
+		pending.resolve({
+			outcome: "submitted",
+			answers
 		});
+		this.pending.delete(toolCallId);
+		this.callbacks.onAnswered?.(toolCallId, answers);
+		return true;
 	}
 	/**
-	* Cancel ongoing operations for a session
+	* Cancel a question request
+	* Returns true if the request was found and cancelled
 	*/
-	async cancel(sessionId) {
-		this.ensureInitialized("cancel");
-		this.options.logger?.debug(`Cancelling session: ${sessionId}`);
-		await this.connection.cancel({ sessionId });
+	cancel(toolCallId, reason) {
+		const pending = this.pending.get(toolCallId);
+		if (!pending) {
+			this.config.logger?.warn(`Question request not found: ${toolCallId}`);
+			return false;
+		}
+		if (pending.timeoutId) clearTimeout(pending.timeoutId);
+		this.config.logger?.debug(`Question cancelled: ${toolCallId}${reason ? ` - ${reason}` : ""}`);
+		pending.resolve({
+			outcome: "cancelled",
+			reason
+		});
+		this.pending.delete(toolCallId);
+		this.callbacks.onCancelled?.(toolCallId, reason);
+		return true;
 	}
 	/**
-	* Resolve a pending permission request
+	* Get all pending question requests
 	*/
-	resolvePermission(requestId, optionId) {
-		return this.permissionManager.resolve(requestId, optionId);
+	getPending() {
+		const result = /* @__PURE__ */ new Map();
+		for (const [id, pending] of this.pending) result.set(id, {
+			request: pending.request,
+			createdAt: pending.createdAt
+		});
+		return result;
 	}
 	/**
-	* Reject a pending permission request
+	* Get a specific pending question request
 	*/
-	rejectPermission(requestId, reason) {
-		return this.permissionManager.reject(requestId, reason);
+	getPendingById(toolCallId) {
+		const pending = this.pending.get(toolCallId);
+		if (!pending) return;
+		return {
+			request: pending.request,
+			createdAt: pending.createdAt
+		};
 	}
 	/**
-	* Get all pending permissions
+	* Check if there are any pending question requests
 	*/
-	getPendingPermissions() {
-		return this.permissionManager.getPending();
+	hasPending() {
+		return this.pending.size > 0;
 	}
 	/**
-	* Check if there are pending permissions
+	* Get the count of pending question requests
 	*/
-	hasPendingPermissions() {
-		return this.permissionManager.hasPending();
+	get pendingCount() {
+		return this.pending.size;
+	}
+	/**
+	* Clear all pending question requests (cancel all)
+	*/
+	clear() {
+		for (const [toolCallId, pending] of this.pending) {
+			if (pending.timeoutId) clearTimeout(pending.timeoutId);
+			pending.resolve({
+				outcome: "cancelled",
+				reason: "cleared"
+			});
+			this.callbacks.onCancelled?.(toolCallId, "cleared");
+		}
+		this.pending.clear();
+		this.config.logger?.debug("Cleared all pending question requests");
+	}
+	/**
+	* Update configuration
+	*/
+	updateConfig(config) {
+		this.config = {
+			...this.config,
+			...config
+		};
+	}
+};
+
+//#endregion
+//#region src/v1/acp/vendor/client.ts
+/**
+* Streamable HTTP ACP Client
+* Production-grade client for connecting to cloud-hosted ACP agents
+*/
+/**
+* Production-grade Streamable HTTP ACP Client
+*
+* Features:
+* - Full ACP protocol support (initialize, session, prompt, cancel)
+* - Artifact notification handling
+* - Permission handling with timeout support
+* - Extension method support
+* - Type-safe event system
+* - Configurable logging
+*/
+var StreamableHttpClient = class {
+	constructor(options) {
+		this.state = "disconnected";
+		this.emitter = new EventEmitter();
+		this.options = options;
+		this.artifactManager = new ArtifactManager({ logger: options.logger });
+		this.permissionManager = new PermissionManager({
+			timeout: options.permissionTimeout,
+			autoRejectOnTimeout: options.permissionAutoRejectOnTimeout ?? true,
+			autoApprove: options.autoApprove,
+			handler: options.requestPermissionHandler,
+			logger: options.logger
+		});
+		this.permissionManager.setCallbacks({
+			onRequest: (requestId, params) => {
+				this.emitter.emit("permissionRequest", {
+					requestId,
+					params
+				});
+			},
+			onResolved: (requestId, optionId) => {
+				this.emitter.emit("permissionResolved", {
+					requestId,
+					optionId
+				});
+			},
+			onRejected: (requestId, reason) => {
+				this.emitter.emit("permissionRejected", {
+					requestId,
+					reason
+				});
+			},
+			onTimeout: (requestId) => {
+				this.emitter.emit("permissionTimeout", { requestId });
+			}
+		});
+		this.questionManager = new QuestionManager({
+			timeout: options.questionTimeout,
+			autoCancelOnTimeout: options.questionAutoCancelOnTimeout ?? true,
+			logger: options.logger
+		});
+		this.questionManager.setCallbacks({
+			onRequest: (toolCallId, request) => {
+				this.emitter.emit("questionRequest", {
+					toolCallId,
+					request
+				});
+				options.onQuestionRequest?.(toolCallId, request);
+			},
+			onAnswered: (toolCallId, answers) => {
+				this.emitter.emit("questionAnswered", {
+					toolCallId,
+					answers
+				});
+			},
+			onCancelled: (toolCallId, reason) => {
+				this.emitter.emit("questionCancelled", {
+					toolCallId,
+					reason
+				});
+			},
+			onTimeout: (toolCallId) => {
+				this.emitter.emit("questionTimeout", { toolCallId });
+			}
+		});
+		this.extensionManager = new ExtensionManager({ logger: options.logger });
 	}
 	/**
-	* Answer a pending question request with user's selections
+	* Get current client state
 	*/
-	answerQuestion(toolCallId, answers) {
-		return this.questionManager.answer(toolCallId, answers);
+	get currentState() {
+		return this.state;
 	}
 	/**
-	* Cancel a pending question request
+	* Check if client is initialized
 	*/
-	cancelQuestion(toolCallId, reason) {
-		return this.questionManager.cancel(toolCallId, reason);
+	get isInitialized() {
+		return this.state === "initialized";
 	}
 	/**
-	* Get all pending question requests
+	* Check if client is connected (but maybe not initialized)
 	*/
-	getPendingQuestions() {
-		return this.questionManager.getPending();
+	get isConnected() {
+		return this.state === "connected" || this.state === "initialized";
 	}
 	/**
-	* Check if there are pending question requests
+	* Get agent capabilities from initialization response
 	*/
-	hasPendingQuestions() {
-		return this.questionManager.hasPending();
+	get agentCapabilities() {
+		return this.initializeResponse?.agentCapabilities;
 	}
 	/**
-	* Send an extension method request
+	* Get full initialization response
 	*/
-	async extMethod(method, params) {
-		this.ensureInitialized("extMethod");
-		return this.connection.extMethod(method, params);
+	get initializeResult() {
+		return this.initializeResponse;
 	}
 	/**
-	* Send an extension notification
+	* Get current transport connection ID
 	*/
-	async extNotification(method, params) {
-		this.ensureInitialized("extNotification");
-		return this.connection.extNotification(method, params);
-	}
-	on(event, listener) {
-		this.emitter.on(event, listener);
-		return this;
-	}
-	off(event, listener) {
-		this.emitter.off(event, listener);
-		return this;
-	}
-	once(event, listener) {
-		this.emitter.once(event, listener);
-		return this;
-	}
-	emit(event, data) {
-		return this.emitter.emit(event, data);
-	}
-	removeAllListeners(event) {
-		this.emitter.removeAllListeners(event);
-		return this;
-	}
-	async handleSessionUpdate(params) {
-		await this.options.onSessionUpdate?.(params);
-		this.emitter.emit("sessionUpdate", params);
-	}
-	async handleRequestPermission(params) {
-		return this.permissionManager.handleRequest(params);
-	}
-	async handleExtNotification(method, params) {
-		if (method === ExtensionMethod.ARTIFACT) {
-			const notification = params;
-			const artifactData = notification.artifact;
-			this.options.logger?.debug("[ACP-Client] Received artifact notification:", {
-				event: notification.event,
-				artifactUri: artifactData?.uri,
-				artifactType: artifactData?.type
-			});
-			if (notification.event === "deleted") {
-				const existing = this.artifactManager.get(notification.artifact.uri);
-				this.artifactManager.handleNotification(notification);
-				if (existing) {
-					await this.options.onArtifact?.(existing, "deleted");
-					this.emitter.emit("artifactDeleted", existing);
-				}
-			} else {
-				const { artifact, event } = notification;
-				this.artifactManager.handleNotification(notification);
-				const storedArtifact = this.artifactManager.get(artifact.uri) || artifact;
-				this.options.logger?.debug("[ACP-Client] Stored artifact:", {
-					event,
-					artifactUri: storedArtifact.uri,
-					artifactType: storedArtifact.type,
-					hasText: storedArtifact.type === "plan" ? !!storedArtifact.text : void 0
-				});
-				await this.options.onArtifact?.(storedArtifact, event);
-				if (event === "created") {
-					this.options.logger?.debug("[ACP-Client] Emitting artifactCreated event");
-					this.emitter.emit("artifactCreated", storedArtifact);
-					if (storedArtifact.type === "plan") await this.options.onPlanReady?.(storedArtifact);
-				} else {
-					this.options.logger?.debug("[ACP-Client] Emitting artifactUpdated event");
-					this.emitter.emit("artifactUpdated", storedArtifact);
-				}
-			}
-			return;
-		}
-		if (method === ExtensionMethod.CHECKPOINT) {
-			const notification = params;
-			if (notification.event === "created") this.emitter.emit("checkpointCreated", notification.checkpoint);
-			else if (notification.event === "updated") this.emitter.emit("checkpointUpdated", notification.checkpoint);
-			return;
-		}
-		await this.options.onExtNotification?.(method, params);
-		await this.extensionManager.handleNotification(method, params);
-	}
-	async handleExtMethod(method, params) {
-		if (method === ExtensionMethod.QUESTION) {
-			const response = await this.questionManager.handleRequest(params);
-			if (response.outcome === "submitted" && response.answers) return { outcome: {
-				outcome: "submitted",
-				data: { answers: response.answers }
-			} };
-			else return { outcome: {
-				outcome: "cancelled",
-				reason: response.reason
-			} };
-		}
-		this.options.logger?.warn(`Unknown extension method: ${method}`);
-		return { outcome: {
-			outcome: "cancelled",
-			reason: "unknown method"
-		} };
-	}
-	ensureInitialized(operation) {
-		if (this.state !== "initialized") throw new InvalidStateError(operation, this.state, ["initialized"]);
-	}
-};
-/**
-* Check if an error is a retryable network-level error.
-* Only network failures (TypeError from fetch) are retried, NOT HTTP errors (4xx/5xx).
-*/
-function isRetryableNetworkError(error) {
-	if (error instanceof TypeError) return true;
-	if (error instanceof Error) {
-		const msg = error.message.toLowerCase();
-		return msg.includes("failed to fetch") || msg.includes("fetch failed") || msg.includes("network request failed") || msg.includes("econnreset") || msg.includes("econnrefused") || msg.includes("socket hang up");
-	}
-	return false;
-}
-
-//#endregion
-//#region src/v1/acp/client.ts
-let _consolePatched = false;
-function patchAcpSdkNoiseLogsOnce() {
-	if (_consolePatched) return;
-	_consolePatched = true;
-	const origError = console.error.bind(console);
-	console.error = (...args) => {
-		if (args.length >= 3 && args[0] === "Error handling notification") {
-			const err = args[2];
-			if (err && typeof err === "object" && err.code === -32602) return;
-		}
-		origError(...args);
-	};
-}
-var AcpClient = class {
-	constructor(opts) {
-		this._state = "INITIAL";
-		this._initialized = false;
-		this._sessionIds = /* @__PURE__ */ new Set();
-		this._subscribers = /* @__PURE__ */ new Map();
-		this._connListeners = {
-			open: /* @__PURE__ */ new Set(),
-			error: /* @__PURE__ */ new Set(),
-			close: /* @__PURE__ */ new Set()
-		};
-		this._activePrompts = /* @__PURE__ */ new Set();
-		this._promptQueues = /* @__PURE__ */ new Map();
-		this._logger = opts?.logger;
-		this._fetch = opts?.fetch;
-		this._exposeVendorLogs = opts?.logLevel === "debug";
-	}
-	get state() {
-		return this._state;
-	}
 	get connectionId() {
-		return this._client?.connectionId;
-	}
-	get sessionIds() {
-		return Array.from(this._sessionIds);
-	}
-	get initialized() {
-		return this._initialized;
+		return this.transport?.connectionId;
 	}
-	setTokenRefresher(fn) {
-		this.tokenRefresher = fn;
+	setState(newState) {
+		const previous = this.state;
+		this.state = newState;
+		this.options.logger?.debug(`State change: ${previous} -> ${newState}`);
+		this.emitter.emit("stateChange", {
+			previous,
+			current: newState
+		});
+		switch (newState) {
+			case "connecting":
+				this.emitter.emit("connecting", void 0);
+				break;
+			case "connected":
+				this.emitter.emit("connected", void 0);
+				break;
+			case "disconnected":
+				this.emitter.emit("disconnected", void 0);
+				break;
+			case "error": break;
+		}
 	}
-	async connect(acpUrl, token, opts) {
-		if (this._state === "OPEN" || this._state === "CONNECTING") return;
-		this._state = "CONNECTING";
-		patchAcpSdkNoiseLogsOnce();
-		this._logger?.info(`[acp] connecting to ${acpUrl}`);
+	/**
+	* Connect and initialize the client
+	*/
+	async connect() {
+		if (this.state !== "disconnected") await this.disconnect();
+		if (this.state === "initialized") return this.initializeResponse;
+		if (this.state === "connecting") throw new ConnectionError("Connection already in progress");
+		this.setState("connecting");
 		try {
-			this._client = new StreamableHttpClient({
-				endpoint: acpUrl,
-				authToken: token,
-				reconnect: {
-					enabled: true,
-					initialDelay: opts?.reconnectBackoffMs ?? 1e3,
-					maxDelay: opts?.reconnectMaxBackoffMs ?? 3e4,
-					maxRetries: opts?.reconnectMaxAttempts ?? Infinity
+			this.transport = createStreamableHttpTransport({
+				endpoint: this.options.endpoint,
+				authToken: this.options.authToken,
+				headers: this.options.headers,
+				reconnect: this.options.reconnect,
+				fetch: this.options.fetch,
+				heartbeatTimeout: this.options.heartbeatTimeout,
+				postTimeout: this.options.postTimeout,
+				connectionTimeout: this.options.connectionTimeout,
+				onConnect: (connectionId) => {
+					this.options.logger?.debug(`Transport connected: ${connectionId}`);
 				},
-				heartbeatTimeout: opts?.heartbeatTimeoutMs ?? 6e4,
-				initializeTimeout: 3e4,
-				postTimeout: 3e4,
-				logger: this._exposeVendorLogs ? this._logger : void 0,
-				fetch: this._fetch,
-				onSessionUpdate: (notification) => this.dispatchNotification(notification)
+				onDisconnect: (connectionId) => {
+					this.options.logger?.debug(`Transport disconnected: ${connectionId}`);
+				},
+				onError: (error) => {
+					this.options.logger?.error("Transport error:", error);
+					this.emitter.emit("error", error);
+				}
 			});
-			this._client.on("connected", () => {
-				this._logger?.info(`[acp] connected (connectionId=${this._client?.connectionId ?? "n/a"})`);
-				this.emitConnEvent("open");
+			const { ClientSideConnection } = await loadAcpSdk();
+			this.connection = new ClientSideConnection(() => this.createClientHandler(), this.transport);
+			this.setState("connected");
+			const timeout = this.options.initializeTimeout ?? DEFAULT_INITIALIZE_TIMEOUT;
+			const mergedCapabilities = {
+				...this.options.clientCapabilities,
+				...CLOUD_CLIENT_CAPABILITIES,
+				_meta: {
+					...this.options.clientCapabilities?._meta,
+					...CLOUD_CLIENT_CAPABILITIES._meta
+				}
+			};
+			const initPromise = this.connection.initialize({
+				protocolVersion: PROTOCOL_VERSION,
+				clientCapabilities: mergedCapabilities
 			});
-			this._client.on("error", (err) => {
-				this._logger?.warn(`[acp] error: ${err.message}`);
-				this.emitConnEvent("error", err);
+			const timeoutPromise = new Promise((_, reject) => {
+				setTimeout(() => {
+					reject(new InitializationError(`Initialize timed out after ${timeout}ms`));
+				}, timeout);
 			});
-			await this._client.connect();
-			this._state = "OPEN";
-			this._initialized = true;
+			const initializeResponse = await Promise.race([initPromise, timeoutPromise]);
+			this.initializeResponse = initializeResponse;
+			this.setState("initialized");
+			this.options.logger?.info("Client initialized successfully");
+			return initializeResponse;
 		} catch (err) {
-			this._state = "CLOSED";
-			this._logger?.debug(`[acp] connect failed: ${err.message}`);
-			throw new NetworkError(`ACP connect failed: ${err.message}`, { cause: err });
+			this.setState("error");
+			const error = err instanceof Error ? err : new Error(String(err));
+			this.emitter.emit("error", error);
+			if (err instanceof InitializationError || err instanceof ConnectionError) throw err;
+			throw new ConnectionError("Failed to connect", error);
 		}
 	}
+	/**
+	* Disconnect the client gracefully
+	* Sends DELETE request to server before closing local resources
+	*/
 	async disconnect() {
-		if (this._state === "CLOSED" || this._state === "CLOSING") return;
-		this._state = "CLOSING";
-		if (this._client) {
+		if (this.state === "disconnected") return;
+		this.options.logger?.info("Disconnecting client");
+		if (this.transport) {
 			try {
-				await this._client.disconnect();
-			} catch {}
-			this._client = void 0;
+				await this.transport.close();
+			} catch (err) {
+				this.options.logger?.warn("Error closing transport:", err);
+			}
+			this.transport = void 0;
 		}
-		this._initialized = false;
-		this._state = "CLOSED";
-		this._subscribers.clear();
-		this._activePrompts.clear();
-		this._promptQueues.clear();
-		this._logger?.info("[acp] disconnected");
-		this.emitConnEvent("close");
-	}
-	/** initialize 由 connect() 内部完成，这里只取缓存结果。 */
-	async initialize() {
-		if (!this._client) throw new AcpProtocolError("Not connected");
-		return this._client.initializeResult;
-	}
-	async sessionNew(sessionId) {
-		if (!this._client) throw new AcpProtocolError("Not connected");
-		const newId = (await this._client.createSession("/workspace")).sessionId || sessionId || "";
-		this._sessionIds.add(newId);
-		return newId;
+		this.permissionManager.clear();
+		this.questionManager.clear();
+		this.artifactManager.clear();
+		this.initializeResponse = void 0;
+		this.setState("disconnected");
 	}
-	async sessionLoad(sessionId) {
-		if (!this._client) throw new AcpProtocolError("Not connected");
-		await this._client.loadSession(sessionId, "/workspace");
-		this._sessionIds.add(sessionId);
+	/**
+	* Create the client handler for the connection
+	*/
+	createClientHandler() {
+		return {
+			sessionUpdate: async (params) => {
+				await this.handleSessionUpdate(params);
+			},
+			requestPermission: async (params) => this.handleRequestPermission(params),
+			extNotification: async (method, params) => {
+				await this.handleExtNotification(method, params);
+			},
+			extMethod: async (method, params) => this.handleExtMethod(method, params)
+		};
 	}
 	/**
-	* 发 prompt。纯 Promise，直接转发上游 `session/prompt` RPC。
+	* Create a new session
 	*
-	* - **不聚合 notification**：本次 prompt 期间的 notifications 由
-	*   `subscribe()` 订阅器独立接收，与此 Promise 并行。
-	* - **串行化**：同 sessionId 的多次 `prompt()` 会**排队**等前一个完成再发出
-	*   （ACP 协议要求），保证顺序一致。
-	* - **signal 支持**：`opts.signal` abort 时向服务端发 `session/cancel`。
-	*   本 Promise 会以 `AbortError` reject。
+	* Retries on transient network errors (e.g., proxy connection reset)
+	* since session/new is idempotent and safe to retry.
+	*
+	* A timeout (`options.sessionTimeout`, default 30 s) guards against the
+	* SSE response never arriving — the POST returns 202 immediately and the
+	* sessionId comes back via GET SSE, which can hang indefinitely.
+	* On timeout a `SessionError` is thrown.
 	*/
-	async prompt(sessionId, input, opts) {
-		if (!this._client) throw new AcpProtocolError("Not connected");
-		return new Promise((resolve, reject) => {
-			this.enqueuePrompt(sessionId, async () => {
-				let aborted = false;
-				const onAbort = () => {
-					aborted = true;
-					this._client?.cancel(sessionId).catch(() => {});
-					const err = /* @__PURE__ */ new Error("Prompt aborted");
-					err.name = "AbortError";
-					reject(err);
-				};
-				if (opts?.signal) {
-					if (opts.signal.aborted) {
-						onAbort();
-						return;
-					}
-					opts.signal.addEventListener("abort", onAbort, { once: true });
-				}
-				try {
-					const response = await this._client.prompt(sessionId, input);
-					if (!aborted) resolve(response);
-				} catch (err) {
-					if (!aborted) reject(err);
-				} finally {
-					opts?.signal?.removeEventListener("abort", onAbort);
-				}
+	async createSession(cwd) {
+		this.ensureInitialized("createSession");
+		const maxRetries = 2;
+		const timeout = this.options.sessionTimeout ?? DEFAULT_SESSION_TIMEOUT;
+		let lastError;
+		for (let attempt = 0; attempt <= maxRetries; attempt++) try {
+			const sessionPromise = this.connection.newSession({
+				cwd,
+				mcpServers: []
+			});
+			let response;
+			if (timeout > 0) {
+				const timeoutPromise = new Promise((_, reject) => {
+					setTimeout(() => {
+						reject(new SessionError(`session/new timed out after ${timeout}ms`));
+					}, timeout);
+				});
+				response = await Promise.race([sessionPromise, timeoutPromise]);
+			} else response = await sessionPromise;
+			this.options.logger?.info(`Session created: ${response.sessionId}`);
+			return response;
+		} catch (err) {
+			lastError = err instanceof Error ? err : new Error(String(err));
+			if (attempt < maxRetries && isRetryableNetworkError(err)) {
+				const delay = 500 * Math.pow(2, attempt);
+				this.options.logger?.warn(`session/new network error, retrying in ${delay}ms (attempt ${attempt + 1}/${maxRetries}): ${lastError.message}`);
+				await new Promise((resolve) => setTimeout(resolve, delay));
+				continue;
+			}
+			throw new SessionError(`Failed to create session: ${lastError.message}`, void 0, lastError);
+		}
+		throw new SessionError(`Failed to create session: ${lastError?.message}`, void 0, lastError);
+	}
+	/**
+	* Load an existing session
+	* Requires agent to support loadSession capability
+	*/
+	async loadSession(sessionId, cwd) {
+		this.ensureInitialized("loadSession");
+		if (!this.agentCapabilities?.loadSession) throw new SessionError("Agent does not support session loading", sessionId);
+		try {
+			const response = await this.connection.loadSession({
+				sessionId,
+				cwd,
+				mcpServers: []
 			});
+			this.options.logger?.info(`Session loaded: ${sessionId}`);
+			return response;
+		} catch (err) {
+			throw new SessionError(`Failed to load session: ${err instanceof Error ? err.message : String(err)}`, sessionId, err instanceof Error ? err : void 0);
+		}
+	}
+	/**
+	* Set the session mode
+	*/
+	async setSessionMode(params) {
+		this.ensureInitialized("setSessionMode");
+		this.options.logger?.debug(`Setting session mode: ${params.sessionId} -> ${params.modeId}`);
+		return this.connection.setSessionMode(params);
+	}
+	/**
+	* Set the session model
+	* @experimental This API is unstable and may change
+	*/
+	async setSessionModel(params) {
+		this.ensureInitialized("setSessionModel");
+		this.options.logger?.debug(`Setting session model: ${params.sessionId} -> ${params.modelId}`);
+		return this.connection.unstable_setSessionModel(params);
+	}
+	/**
+	* Send a prompt to the agent
+	*/
+	async prompt(sessionId, prompt, options) {
+		this.ensureInitialized("prompt");
+		this.options.logger?.debug(`Sending prompt to session: ${sessionId}`);
+		return this.connection.prompt({
+			sessionId,
+			prompt,
+			_meta: options?.planMode ? {
+				planMode: true,
+				...options._meta
+			} : options?._meta
 		});
 	}
-	/** 发 session/cancel 通知（幂等，尽力而为）。 */
-	async sessionCancel(sessionId) {
-		if (!this._client) throw new AcpProtocolError("Not connected");
-		await this._client.cancel(sessionId);
+	/**
+	* Cancel ongoing operations for a session
+	*/
+	async cancel(sessionId) {
+		this.ensureInitialized("cancel");
+		this.options.logger?.debug(`Cancelling session: ${sessionId}`);
+		await this.connection.cancel({ sessionId });
+	}
+	/**
+	* Resolve a pending permission request
+	*/
+	resolvePermission(requestId, optionId) {
+		return this.permissionManager.resolve(requestId, optionId);
+	}
+	/**
+	* Reject a pending permission request
+	*/
+	rejectPermission(requestId, reason) {
+		return this.permissionManager.reject(requestId, reason);
+	}
+	/**
+	* Get all pending permissions
+	*/
+	getPendingPermissions() {
+		return this.permissionManager.getPending();
+	}
+	/**
+	* Check if there are pending permissions
+	*/
+	hasPendingPermissions() {
+		return this.permissionManager.hasPending();
+	}
+	/**
+	* Answer a pending question request with user's selections
+	*/
+	answerQuestion(toolCallId, answers) {
+		return this.questionManager.answer(toolCallId, answers);
+	}
+	/**
+	* Cancel a pending question request
+	*/
+	cancelQuestion(toolCallId, reason) {
+		return this.questionManager.cancel(toolCallId, reason);
 	}
 	/**
-	* 订阅指定 sessionId 的上游 notifications。
-	*
-	* Listener 收到的是上游 `SessionNotification` 原样（`{ sessionId, update, _meta? }`）。
-	* 同一 session 可以有任意多个 listener，彼此独立；每条 notification 都会
-	* 按注册顺序调用所有 listener（同步调用，异常被吞）。
-	*
-	* @returns unsubscribe 函数，调用即退订。
+	* Get all pending question requests
 	*/
-	subscribe(sessionId, listener) {
-		if (!this._subscribers.has(sessionId)) this._subscribers.set(sessionId, /* @__PURE__ */ new Set());
-		this._subscribers.get(sessionId).add(listener);
-		return () => {
-			this._subscribers.get(sessionId)?.delete(listener);
-		};
+	getPendingQuestions() {
+		return this.questionManager.getPending();
 	}
-	on(event, handler) {
-		this._connListeners[event].add(handler);
+	/**
+	* Check if there are pending question requests
+	*/
+	hasPendingQuestions() {
+		return this.questionManager.hasPending();
 	}
-	off(event, handler) {
-		this._connListeners[event].delete(handler);
+	/**
+	* Send an extension method request
+	*/
+	async extMethod(method, params) {
+		this.ensureInitialized("extMethod");
+		return this.connection.extMethod(method, params);
 	}
 	/**
-	* 把上游 notification 按 sessionId 分发给订阅者。不做任何转换。
-	*
-	* 上游保证 `SessionNotification` 的 `sessionId` / `update` 字段都有值
-	* （vendor 的 `SessionUpdateCallback` 签名即如此），无需再做类型守卫。
+	* Send an extension notification
 	*/
-	dispatchNotification(notification) {
-		const subs = this._subscribers.get(notification.sessionId);
-		if (!subs || subs.size === 0) return;
-		for (const listener of subs) try {
-			listener(notification);
-		} catch {}
+	async extNotification(method, params) {
+		this.ensureInitialized("extNotification");
+		return this.connection.extNotification(method, params);
 	}
-	emitConnEvent(event, ...args) {
-		for (const handler of this._connListeners[event]) try {
-			handler(...args);
-		} catch {}
+	on(event, listener) {
+		this.emitter.on(event, listener);
+		return this;
 	}
-	enqueuePrompt(sid, exec) {
-		if (!this._promptQueues.has(sid)) this._promptQueues.set(sid, []);
-		const runThenDequeue = () => {
-			this._activePrompts.add(sid);
-			exec().finally(() => this.dequeuePrompt(sid));
-		};
-		if (this._activePrompts.has(sid)) this._promptQueues.get(sid).push(runThenDequeue);
-		else runThenDequeue();
+	off(event, listener) {
+		this.emitter.off(event, listener);
+		return this;
 	}
-	dequeuePrompt(sid) {
-		this._activePrompts.delete(sid);
-		const q = this._promptQueues.get(sid);
-		if (q && q.length > 0) q.shift()();
+	once(event, listener) {
+		this.emitter.once(event, listener);
+		return this;
 	}
-};
-
-//#endregion
-//#region src/v1/internal/log.ts
-/** 级别数值：越大越详细；方法级别 > 当前级别时，该方法变成 noop。 */
-const LEVEL_NUMBER = {
-	off: 0,
-	error: 200,
-	warn: 300,
-	info: 400,
-	debug: 500
-};
-/** 默认级别（不配置时）。 */
-const DEFAULT_LEVEL = "warn";
-/** 真正的空函数。替换被关闭的级别，避免字符串拼接开销。 */
-const noop = () => {};
-/** 全 noop 的 logger（内部单例）。 */
-const noopLogger = {
-	error: noop,
-	warn: noop,
-	info: noop,
-	debug: noop
-};
-/**
-* 缓存 `[baseLogger, logLevel] -> wrappedLogger`。
-*
-* 用 WeakMap<Logger, ...>：只要 user 传的 logger 引用不变、level 不变，就复用。
-*/
-const cache = /* @__PURE__ */ new WeakMap();
-/**
-* 解析级别字符串；非法值返回 undefined（调用方自行回退）。
-*/
-function parseLogLevel(value) {
-	if (typeof value !== "string") return void 0;
-	const lower = value.toLowerCase();
-	if (lower in LEVEL_NUMBER) return lower;
-}
-/**
-* 读取环境变量 `CLOUD_AGENT_SDK_LOG`（仅 Node.js 环境，浏览器返回 undefined）。
-*
-* 用 `globalThis` 方式访问避免对 `@types/node` 的强依赖。
-*/
-function readEnvLogLevel() {
-	const env = globalThis.process?.env;
-	if (!env) return void 0;
-	return parseLogLevel(env.CLOUD_AGENT_SDK_LOG);
-}
-/**
-* 按 ConnectionOpts 决定最终的 LogLevel。
-*
-* 优先级：`opts.logLevel` > env `CLOUD_AGENT_SDK_LOG` > `'warn'`。
-*/
-function resolveLogLevel(opts) {
-	return parseLogLevel(opts.logLevel) ?? readEnvLogLevel() ?? DEFAULT_LEVEL;
-}
-/**
-* 返回按 `opts` 过滤后的 Logger。
-*
-* - `opts.logger` 为空时使用 `globalThis.console`
-* - 级别关闭时返回 noop，开启时返回 `baseLogger[fn].bind(baseLogger)`
-* - 相同入参多次调用复用同一对象（WeakMap 缓存）
-*/
-function loggerFor(opts) {
-	const base = opts.logger ?? console;
-	const level = resolveLogLevel(opts);
-	if (level === "off") return noopLogger;
-	let byLevel = cache.get(base);
-	if (!byLevel) {
-		byLevel = /* @__PURE__ */ new Map();
-		cache.set(base, byLevel);
+	emit(event, data) {
+		return this.emitter.emit(event, data);
 	}
-	const cached = byLevel.get(level);
-	if (cached) return cached;
-	const wrapped = makeLeveledLogger(base, level);
-	byLevel.set(level, wrapped);
-	return wrapped;
-}
+	removeAllListeners(event) {
+		this.emitter.removeAllListeners(event);
+		return this;
+	}
+	async handleSessionUpdate(params) {
+		await this.options.onSessionUpdate?.(params);
+		this.emitter.emit("sessionUpdate", params);
+	}
+	async handleRequestPermission(params) {
+		return this.permissionManager.handleRequest(params);
+	}
+	async handleExtNotification(method, params) {
+		if (method === ExtensionMethod.ARTIFACT) {
+			const notification = params;
+			const artifactData = notification.artifact;
+			this.options.logger?.debug("[ACP-Client] Received artifact notification:", {
+				event: notification.event,
+				artifactUri: artifactData?.uri,
+				artifactType: artifactData?.type
+			});
+			if (notification.event === "deleted") {
+				const existing = this.artifactManager.get(notification.artifact.uri);
+				this.artifactManager.handleNotification(notification);
+				if (existing) {
+					await this.options.onArtifact?.(existing, "deleted");
+					this.emitter.emit("artifactDeleted", existing);
+				}
+			} else {
+				const { artifact, event } = notification;
+				this.artifactManager.handleNotification(notification);
+				const storedArtifact = this.artifactManager.get(artifact.uri) || artifact;
+				this.options.logger?.debug("[ACP-Client] Stored artifact:", {
+					event,
+					artifactUri: storedArtifact.uri,
+					artifactType: storedArtifact.type,
+					hasText: storedArtifact.type === "plan" ? !!storedArtifact.text : void 0
+				});
+				await this.options.onArtifact?.(storedArtifact, event);
+				if (event === "created") {
+					this.options.logger?.debug("[ACP-Client] Emitting artifactCreated event");
+					this.emitter.emit("artifactCreated", storedArtifact);
+					if (storedArtifact.type === "plan") await this.options.onPlanReady?.(storedArtifact);
+				} else {
+					this.options.logger?.debug("[ACP-Client] Emitting artifactUpdated event");
+					this.emitter.emit("artifactUpdated", storedArtifact);
+				}
+			}
+			return;
+		}
+		if (method === ExtensionMethod.CHECKPOINT) {
+			const notification = params;
+			if (notification.event === "created") this.emitter.emit("checkpointCreated", notification.checkpoint);
+			else if (notification.event === "updated") this.emitter.emit("checkpointUpdated", notification.checkpoint);
+			return;
+		}
+		await this.options.onExtNotification?.(method, params);
+		await this.extensionManager.handleNotification(method, params);
+	}
+	async handleExtMethod(method, params) {
+		if (method === ExtensionMethod.QUESTION) {
+			const response = await this.questionManager.handleRequest(params);
+			if (response.outcome === "submitted" && response.answers) return { outcome: {
+				outcome: "submitted",
+				data: { answers: response.answers }
+			} };
+			else return { outcome: {
+				outcome: "cancelled",
+				reason: response.reason
+			} };
+		}
+		this.options.logger?.warn(`Unknown extension method: ${method}`);
+		return { outcome: {
+			outcome: "cancelled",
+			reason: "unknown method"
+		} };
+	}
+	ensureInitialized(operation) {
+		if (this.state !== "initialized") throw new InvalidStateError(operation, this.state, ["initialized"]);
+	}
+};
 /**
-* 按级别构造 Logger：开放的级别直接 bind，关闭的级别替换为 noop。
-*
-* bind 而非 wrap 是为了保留调用点的 stack trace（开发者看日志能点回 SDK 行号）。
-*/
-function makeLeveledLogger(base, level) {
-	const threshold = LEVEL_NUMBER[level];
-	const enable = (fn) => LEVEL_NUMBER[fn] <= threshold && typeof base[fn] === "function" ? base[fn].bind(base) : noop;
-	return {
-		error: enable("error"),
-		warn: enable("warn"),
-		info: enable("info"),
-		debug: enable("debug")
-	};
+* Check if an error is a retryable network-level error.
+* Only network failures (TypeError from fetch) are retried, NOT HTTP errors (4xx/5xx).
+*/
+function isRetryableNetworkError(error) {
+	if (error instanceof TypeError) return true;
+	if (error instanceof Error) {
+		const msg = error.message.toLowerCase();
+		return msg.includes("failed to fetch") || msg.includes("fetch failed") || msg.includes("network request failed") || msg.includes("econnreset") || msg.includes("econnrefused") || msg.includes("socket hang up");
+	}
+	return false;
 }
+
+//#endregion
+//#region src/v1/acp/client.ts
 /**
-* 生成短本地日志 ID，用于在用户日志里串联一次 HTTP 请求（含重试链）。
+* ACP 客户端 — 订阅模型
+*
+* 设计：直接映射到 ACP 协议的两条独立通道：
 *
-* 形态：`log_` + 6 位十六进制（24 bit 随机，单进程内冲突概率可忽略）。
+* - **RPC 通道（POST）**：`prompt` / `sessionCancel` 等是纯 `Promise`，转发上游。
+* - **Notification 通道（SSE）**：`subscribe(sessionId, listener)` 给用户注册
+*   监听器，每条上游 `SessionNotification` 多路分发给所有订阅者。
 *
-* 对齐 Anthropic SDK 的做法（详见 docs/agentos/sdk/07-error-retry.md § 4.3）。
+* 不做聚合、不建队列。上游 `SessionNotification` / `PromptResponse` 等类型原封
+* 不动透给上层（`Session` 类）。
+*
+* 具体实现基于 vendor 的 `StreamableHttpClient`，它内部管理一条 SSE + POST 复合
+* 通道。用户侧看到的只是"一个 session 对应一个 AcpClient"。
 */
-function makeLogId() {
-	return "log_" + (Math.random() * (1 << 24) | 0).toString(16).padStart(6, "0");
+let _consolePatched = false;
+function patchAcpSdkNoiseLogsOnce() {
+	if (_consolePatched) return;
+	_consolePatched = true;
+	const origError = console.error.bind(console);
+	console.error = (...args) => {
+		if (args.length >= 3 && args[0] === "Error handling notification") {
+			const err = args[2];
+			if (err && typeof err === "object" && err.code === -32602) return;
+		}
+		origError(...args);
+	};
 }
-
-//#endregion
-//#region src/v1/session.ts
-var Session = class {
-	/** @internal */
-	constructor(id, runtime, restClient) {
-		this.id = id;
-		this.runtimeId = runtime.id;
-		this._runtime = runtime;
-		this._restClient = restClient;
+var AcpClient = class {
+	constructor(opts) {
+		this._state = "INITIAL";
+		this._initialized = false;
+		this._sessionIds = /* @__PURE__ */ new Set();
+		this._subscribers = /* @__PURE__ */ new Map();
+		this._connListeners = {
+			open: /* @__PURE__ */ new Set(),
+			error: /* @__PURE__ */ new Set(),
+			close: /* @__PURE__ */ new Set()
+		};
+		this._activePrompts = /* @__PURE__ */ new Set();
+		this._promptQueues = /* @__PURE__ */ new Map();
+		this._logger = opts?.logger;
+		this._fetch = opts?.fetch;
+		this._exposeVendorLogs = opts?.logLevel === "debug";
 	}
-	get status() {
-		return this._status;
+	get state() {
+		return this._state;
 	}
-	/** ACP 连接是否已建立 */
-	get connected() {
-		return this._acpClient?.state === "OPEN";
+	get connectionId() {
+		return this._client?.connectionId;
 	}
-	/** 拉最新元数据 */
-	async info(opts) {
-		const info = await this._restClient.get(`/runtimes/${this.runtimeId}/sessions/${this.id}`, void 0, opts);
-		this._status = info.sessionStatus;
-		return info;
+	get sessionIds() {
+		return Array.from(this._sessionIds);
 	}
-	/** 更新 name / manifest */
-	async update(req, opts) {
-		const info = await this._restClient.post(`/runtimes/${this.runtimeId}/sessions/${this.id}/update`, req, opts);
-		this._status = info.sessionStatus;
-		return info;
+	get initialized() {
+		return this._initialized;
 	}
-	/** 软删除 */
-	async delete(opts) {
-		if (this._acpClient) {
-			await this._acpClient.disconnect();
-			this._acpClient = void 0;
-		}
-		return this._restClient.post(`/runtimes/${this.runtimeId}/sessions/${this.id}/delete`, void 0, opts);
+	setTokenRefresher(fn) {
+		this.tokenRefresher = fn;
 	}
-	/**
-	* 建立到沙箱的 ACP 连接。
-	*
-	* 内部流程：GET SSE → 获取 connectionId → initialize → session/load。
-	* 调用后 `prompt` / `subscribe` / `cancel` 才可用。
-	*
-	* 幂等：已连接时直接返回；并发调用时后来的等前者完成。
-	*/
-	async connect(opts) {
-		if (this._acpClient && this._acpClient.state === "OPEN") return;
-		const acpUrl = this._runtime.acpUrl;
-		let acpToken = this._runtime.acpToken;
-		if (!acpUrl || !acpToken) {
-			acpToken = await this._runtime.refreshToken();
-			if (!this._runtime.acpUrl || !acpToken) throw new ValidationError("Runtime does not have ACP link. Is it in RUNNING state?");
+	async connect(acpUrl, token, opts) {
+		if (this._state === "OPEN" || this._state === "CONNECTING") return;
+		this._state = "CONNECTING";
+		patchAcpSdkNoiseLogsOnce();
+		this._logger?.debug(`[acp conn=-] connecting to ${acpUrl}`);
+		try {
+			this._client = new StreamableHttpClient({
+				endpoint: acpUrl,
+				authToken: token,
+				headers: opts?.headers,
+				reconnect: {
+					enabled: true,
+					initialDelay: opts?.reconnectBackoffMs ?? 1e3,
+					maxDelay: opts?.reconnectMaxBackoffMs ?? 3e4,
+					maxRetries: opts?.reconnectMaxAttempts ?? Infinity
+				},
+				heartbeatTimeout: opts?.heartbeatTimeoutMs ?? 6e4,
+				initializeTimeout: 3e4,
+				postTimeout: 3e4,
+				logger: this._exposeVendorLogs ? this._logger : void 0,
+				fetch: this._fetch,
+				onSessionUpdate: (notification) => this.dispatchNotification(notification)
+			});
+			this._client.on("connected", () => {
+				this._logger?.debug(`[acp conn=${this._client?.connectionId ?? "-"}] connected`);
+				this.emitConnEvent("open");
+			});
+			this._client.on("error", (err) => {
+				this._logger?.warn(`[acp conn=${this._client?.connectionId ?? "-"}] error: ${err.message}`);
+				this.emitConnEvent("error", err);
+			});
+			await this._client.connect();
+			this._state = "OPEN";
+			this._initialized = true;
+		} catch (err) {
+			this._state = "CLOSED";
+			this._logger?.debug(`[acp conn=-] connect failed: ${err.message}`);
+			throw new NetworkError(`ACP connect failed: ${err.message}`, { cause: err });
 		}
-		const connOpts = this._runtime._connectionOpts;
-		const client = new AcpClient({
-			logger: loggerFor(connOpts),
-			logLevel: resolveLogLevel(connOpts),
-			fetch: connOpts.fetch
-		});
-		client.setTokenRefresher(async () => this._runtime.refreshToken());
-		await client.connect(this._runtime.acpUrl, acpToken, {
-			...opts,
-			heartbeatTimeoutMs: opts?.heartbeatTimeoutMs ?? 45e3,
-			reconnectMaxAttempts: opts?.reconnectMaxAttempts ?? Infinity,
-			reconnectBackoffMs: opts?.reconnectBackoffMs ?? 300,
-			reconnectMaxBackoffMs: opts?.reconnectMaxBackoffMs ?? 3e4,
-			lastEventId: opts?.lastEventId
-		});
-		if (opts?.initialize !== false) await client.initialize();
-		await client.sessionLoad(this.id);
-		this._acpClient = client;
 	}
-	/** 断开 ACP 连接。所有订阅器被自动清除。 */
 	async disconnect() {
-		if (this._acpClient) {
-			await this._acpClient.disconnect();
-			this._acpClient = void 0;
+		if (this._state === "CLOSED" || this._state === "CLOSING") return;
+		this._state = "CLOSING";
+		const lastConnId = this._client?.connectionId ?? "-";
+		if (this._client) {
+			try {
+				await this._client.disconnect();
+			} catch {}
+			this._client = void 0;
 		}
+		this._initialized = false;
+		this._state = "CLOSED";
+		this._subscribers.clear();
+		this._activePrompts.clear();
+		this._promptQueues.clear();
+		this._logger?.debug(`[acp conn=${lastConnId}] disconnected`);
+		this.emitConnEvent("close");
+	}
+	/** initialize 由 connect() 内部完成，这里只取缓存结果。 */
+	async initialize() {
+		if (!this._client) throw new AcpProtocolError("Not connected");
+		return this._client.initializeResult;
+	}
+	async sessionNew(sessionId) {
+		if (!this._client) throw new AcpProtocolError("Not connected");
+		const newId = (await this._client.createSession("/workspace")).sessionId || sessionId || "";
+		this._sessionIds.add(newId);
+		return newId;
+	}
+	async sessionLoad(sessionId) {
+		if (!this._client) throw new AcpProtocolError("Not connected");
+		await this._client.loadSession(sessionId, "/workspace");
+		this._sessionIds.add(sessionId);
 	}
 	/**
-	* 发送 prompt 并等待 `PromptResponse`。
-	*
-	* @param input 纯文本字符串（自动包装成 text block）或 `ContentBlock[]`（多模态）
-	* @param opts 见 `PromptOpts`，支持 `signal` 取消、`onChunk` 便利钩子等
-	*
-	* @returns `PromptResponse`（当前只含 `stopReason`）
-	*
-	* **时序**：
-	* - 如果未 connect，会自动 connect
-	* - RPC 发出期间，上游会通过 **SSE notification 通道**推送 `session/update`，
-	*   这些消息**不会进 Promise 的结果**，需要通过 `subscribe()` 或 `onChunk`
-	*   回调接收
-	* - 同 session 并发 prompt 会被内部**串行化**（ACP 协议要求）
-	*
-	* @example
-	* ```ts
-	* // 最简：只要结果
-	* const r = await session.prompt('2+2?');
-	*
-	* // 流式打印 + 结果
-	* const r = await session.prompt('write a poem', {
-	*   onChunk: (n) => {
-	*     if (n.update.sessionUpdate === 'agent_message_chunk' &&
-	*         n.update.content.type === 'text') {
-	*       process.stdout.write(n.update.content.text);
-	*     }
-	*   },
-	* });
+	* 发 prompt。纯 Promise，直接转发上游 `session/prompt` RPC。
 	*
-	* // 取消
-	* const ctrl = new AbortController();
-	* setTimeout(() => ctrl.abort(), 5000);
-	* const r = await session.prompt('long task', { signal: ctrl.signal });
-	* ```
+	* - **不聚合 notification**：本次 prompt 期间的 notifications 由
+	*   `subscribe()` 订阅器独立接收，与此 Promise 并行。
+	* - **串行化**：同 sessionId 的多次 `prompt()` 会**排队**等前一个完成再发出
+	*   （ACP 协议要求），保证顺序一致。
+	* - **signal 支持**：`opts.signal` abort 时向服务端发 `session/cancel`。
+	*   本 Promise 会以 `AbortError` reject。
 	*/
-	async prompt(input, opts) {
-		if (!this._acpClient || this._acpClient.state !== "OPEN") await this.connect();
-		const content = typeof input === "string" ? [{
-			type: "text",
-			text: input
-		}] : input;
-		const unsubChunk = opts?.onChunk ? this._acpClient.subscribe(this.id, opts.onChunk) : void 0;
-		let timeoutCtrl;
-		let signal = opts?.signal;
-		if (opts?.timeoutMs !== void 0 && opts.timeoutMs > 0) {
-			timeoutCtrl = new AbortController();
-			const timer = setTimeout(() => timeoutCtrl.abort(), opts.timeoutMs);
-			signal?.addEventListener("abort", () => {
-				clearTimeout(timer);
-				timeoutCtrl.abort();
-			}, { once: true });
-			if (!signal) signal = timeoutCtrl.signal;
-			else signal = mergeAbortSignals(signal, timeoutCtrl.signal);
-		}
-		opts?.onTurnStart?.();
-		try {
-			const response = await this._acpClient.prompt(this.id, content, { signal });
-			opts?.onTurnEnd?.(response);
-			return response;
-		} finally {
-			unsubChunk?.();
-		}
+	async prompt(sessionId, input, opts) {
+		if (!this._client) throw new AcpProtocolError("Not connected");
+		return new Promise((resolve, reject) => {
+			this.enqueuePrompt(sessionId, async () => {
+				let aborted = false;
+				const onAbort = () => {
+					aborted = true;
+					this._client?.cancel(sessionId).catch(() => {});
+					const err = /* @__PURE__ */ new Error("Prompt aborted");
+					err.name = "AbortError";
+					reject(err);
+				};
+				if (opts?.signal) {
+					if (opts.signal.aborted) {
+						onAbort();
+						return;
+					}
+					opts.signal.addEventListener("abort", onAbort, { once: true });
+				}
+				try {
+					const response = await this._client.prompt(sessionId, input);
+					if (!aborted) resolve(response);
+				} catch (err) {
+					if (!aborted) reject(err);
+				} finally {
+					opts?.signal?.removeEventListener("abort", onAbort);
+				}
+			});
+		});
+	}
+	/** 发 session/cancel 通知（幂等，尽力而为）。 */
+	async sessionCancel(sessionId) {
+		if (!this._client) throw new AcpProtocolError("Not connected");
+		await this._client.cancel(sessionId);
 	}
 	/**
-	* 订阅该 session 所有上游 notifications。
+	* 订阅指定 sessionId 的上游 notifications。
 	*
 	* Listener 收到的是上游 `SessionNotification` 原样（`{ sessionId, update, _meta? }`）。
-	* `update` 是上游 11-tag 判别联合，在 switch 分支里类型自动收窄。
-	*
-	* 订阅独立于 prompt 生命周期——connect 之后注册，直到 unsubscribe 或
-	* disconnect 为止。一个 session 支持任意多个订阅者。
+	* 同一 session 可以有任意多个 listener，彼此独立；每条 notification 都会
+	* 按注册顺序调用所有 listener（同步调用，异常被吞）。
 	*
 	* @returns unsubscribe 函数，调用即退订。
-	*
-	* @example
-	* ```ts
-	* const unsub = session.subscribe((n) => {
-	*   switch (n.update.sessionUpdate) {
-	*     case 'agent_message_chunk':
-	*       if (n.update.content.type === 'text') print(n.update.content.text);
-	*       break;
-	*     case 'tool_call':
-	*       console.log('tool:', n.update.title);
-	*       break;
-	*   }
-	* });
-	* // ...
-	* unsub();
-	* ```
 	*/
-	subscribe(listener) {
-		if (!this._acpClient || this._acpClient.state !== "OPEN") throw new ValidationError("Session not connected. Call connect() first.");
-		return this._acpClient.subscribe(this.id, listener);
+	subscribe(sessionId, listener) {
+		if (!this._subscribers.has(sessionId)) this._subscribers.set(sessionId, /* @__PURE__ */ new Set());
+		this._subscribers.get(sessionId).add(listener);
+		return () => {
+			this._subscribers.get(sessionId)?.delete(listener);
+		};
+	}
+	on(event, handler) {
+		this._connListeners[event].add(handler);
+	}
+	off(event, handler) {
+		this._connListeners[event].delete(handler);
 	}
 	/**
-	* 取消当前运行的 prompt（如果有）。
-	*
-	* 向服务端发 `session/cancel` notification，服务端会以 `stopReason: 'cancelled'`
-	* 结束当前 prompt，对应的 `prompt()` Promise 正常 resolve（不 reject）。
+	* 把上游 notification 按 sessionId 分发给订阅者。不做任何转换。
 	*
-	* **尽力而为**：服务端 RPC 失败时打 warn 日志吞掉，不抛给调用方——
-	* 因为"用户点了取消按钮"的 UX 契约就是"本地能返回"。
+	* 上游保证 `SessionNotification` 的 `sessionId` / `update` 字段都有值
+	* （vendor 的 `SessionUpdateCallback` 签名即如此），无需再做类型守卫。
 	*/
-	async cancel() {
-		if (!this._acpClient) return;
-		try {
-			await this._acpClient.sessionCancel(this.id);
-		} catch (err) {
-			loggerFor(this._runtime._connectionOpts).warn(`[session ${this.id}] cancel failed: ${err.message}`);
-		}
+	dispatchNotification(notification) {
+		const subs = this._subscribers.get(notification.sessionId);
+		if (!subs || subs.size === 0) return;
+		for (const listener of subs) try {
+			listener(notification);
+		} catch {}
 	}
-};
-/**
-* 合并两个 AbortSignal：任一 abort 时返回的 signal 也 abort。
-*
-* 用原生 `AbortSignal.any()` 不行——Node 18 没有。这里用最小 polyfill。
-*/
-function mergeAbortSignals(a, b) {
-	if (typeof AbortSignal.any === "function") return AbortSignal.any([a, b]);
-	const ctrl = new AbortController();
-	const onAbort = () => ctrl.abort();
-	if (a.aborted || b.aborted) ctrl.abort();
-	else {
-		a.addEventListener("abort", onAbort, { once: true });
-		b.addEventListener("abort", onAbort, { once: true });
+	emitConnEvent(event, ...args) {
+		for (const handler of this._connListeners[event]) try {
+			handler(...args);
+		} catch {}
 	}
-	return ctrl.signal;
-}
-
-//#endregion
-//#region src/v1/runtime.ts
-var Runtime = class {
-	/** @internal */
-	constructor(restClient, connectionOpts, info) {
-		this.sessions = {
-			create: async (opts) => {
-				const body = {
-					sessionId: opts.sessionId,
-					sessionName: opts.sessionName,
-					agentManifest: opts.agentManifest
-				};
-				return new Session((await this._restClient.post(`/runtimes/${this.id}/sessions`, body, {
-					timeoutMs: opts.timeoutMs,
-					headers: opts.headers,
-					signal: opts.signal,
-					requestId: opts.requestId
-				})).sessionId, this, this._restClient);
-			},
-			get: async (sessionId, opts) => {
-				await this._restClient.get(`/runtimes/${this.id}/sessions/${sessionId}`, void 0, opts);
-				return new Session(sessionId, this, this._restClient);
-			},
-			list: async (opts) => {
-				const params = {};
-				if (opts?.page !== void 0) params.page = String(opts.page);
-				if (opts?.pageSize !== void 0) params.pageSize = String(opts.pageSize);
-				if (opts?.sessionStatus) params.sessionStatus = opts.sessionStatus;
-				return this._restClient.get(`/runtimes/${this.id}/sessions`, params, opts);
-			},
-			default: () => {
-				return new Session(this._defaultSessionId || this.id, this, this._restClient);
-			}
+	enqueuePrompt(sid, exec) {
+		if (!this._promptQueues.has(sid)) this._promptQueues.set(sid, []);
+		const runThenDequeue = () => {
+			this._activePrompts.add(sid);
+			exec().finally(() => this.dequeuePrompt(sid));
 		};
-		this.id = info.id;
-		this._info = info;
-		this._restClient = restClient;
-		this._connectionOpts = connectionOpts;
-		this.sandboxId = info.links?.sandboxLink?.sandboxId;
-		this.sandboxDomain = info.links?.sandboxLink?.endpoint;
-		this._acpUrl = info.links?.acpLink?.url;
-		this._acpToken = info.links?.acpLink?.token;
-		if (info.sessions && info.sessions.length > 0) this._defaultSessionId = info.sessions[0].sessionId;
-	}
-	get runtimeInfo() {
-		return this._info;
-	}
-	get acpUrl() {
-		return this._acpUrl;
-	}
-	get acpToken() {
-		return this._acpToken;
-	}
-	/** 更新 Runtime 元数据 */
-	async update(req, opts) {
-		const info = await this._restClient.post(`/runtimes/${this.id}/update`, req, opts);
-		this._info = info;
-		return info;
-	}
-	/** 软删除 */
-	async delete(opts) {
-		return this._restClient.post(`/runtimes/${this.id}/delete`, void 0, opts);
+		if (this._activePrompts.has(sid)) this._promptQueues.get(sid).push(runThenDequeue);
+		else runThenDequeue();
 	}
-	/** 刷新 token（拉最新 RuntimeInfo，更新 acpLink） */
-	async refreshToken(opts) {
-		const info = await this._restClient.get(`/runtimes/${this.id}`, void 0, opts);
-		this._info = info;
-		if (info.links?.acpLink) {
-			this._acpUrl = info.links.acpLink.url;
-			this._acpToken = info.links.acpLink.token;
-		}
-		return this._acpToken || "";
+	dequeuePrompt(sid) {
+		this._activePrompts.delete(sid);
+		const q = this._promptQueues.get(sid);
+		if (q && q.length > 0) q.shift()();
 	}
 };
 
 //#endregion
-//#region src/v1/internal/redact.ts
-/**
-* 敏感信息脱敏
-*
-* 范围：headers + 特定已知的 body 字段（白名单 path，非启发式猜测）。
-* 脱敏仅作用于日志打印和钩子回调，不影响实际发送的请求。
-*
-* 详见 docs/agentos/sdk/07-error-retry.md § 4.5。
-*/
-/** 需要脱敏的 header 名（小写）。 */
-const SENSITIVE_HEADER_NAMES = new Set([
-	"authorization",
-	"cookie",
-	"set-cookie",
-	"x-api-key"
-]);
-/** 脱敏替换值。 */
-const REDACTED = "***";
-/**
-* 返回脱敏后的 headers 副本。
-*
-* - 键按原样保留（大小写不变）
-* - 值按键名（小写后）匹配敏感列表时替换为 `'***'`
-* - **纯函数**，不修改入参
-*/
-function redactHeaders(headers) {
-	if (!headers) return {};
-	const out = {};
-	for (const [name, value] of Object.entries(headers)) out[name] = SENSITIVE_HEADER_NAMES.has(name.toLowerCase()) ? REDACTED : value;
-	return out;
-}
-/** 判断 value 是否是对象数组（`Array<Record<string, unknown>>`）。 */
-function isObjectArray(v) {
-	return Array.isArray(v) && v.every((x) => x !== null && typeof x === "object" && !Array.isArray(x));
-}
-/**
-* Body 脱敏器：对给定对象做**浅复制 + 定向脱敏**，返回安全的日志副本。
-*
-* 不修改入参。若入参不是对象（string / number / ...），原样返回。
-*
-* 已处理字段：
-* - `agentManifest.secrets[].value` → `'***'`（保留 name，只脱 value）
-*/
-function redactBody(body) {
-	if (body === null || body === void 0) return body;
-	if (typeof body !== "object" || Array.isArray(body)) return body;
-	const input = body;
-	const out = { ...input };
-	const manifest = input.agentManifest;
-	if (manifest && typeof manifest === "object" && !Array.isArray(manifest)) {
-		const secrets = manifest.secrets;
-		if (isObjectArray(secrets)) out.agentManifest = {
-			...manifest,
-			secrets: secrets.map((s) => "value" in s ? {
-				...s,
-				value: REDACTED
-			} : s)
-		};
-	}
-	return out;
-}
-
-//#endregion
-//#region src/v1/rest/client.ts
-/** 默认 baseUrl */
-const DEFAULT_BASE_URL = "https://www.codebuddy.cn/v2/agentos";
+//#region src/v1/session.ts
 /**
-* SDK 内置的默认重试判定。
+* Session — 对话上下文
 *
-* 传 `retry: { retryOn: ... }` 会**完全替换**这里的规则（不叠加）。
-* 公开这个函数是为了让用户在自定义 `retryOn` 里可以手动调用回落到默认：
+* 控制面（REST）：`info` / `update` / `delete`
+* 数据面（ACP）：`connect` / `prompt` / `subscribe` / `disconnect`
 *
+* **订阅模型**（对齐 ACP 协议原生形态）：
+* - `prompt(input)` 返回 `Promise<PromptResponse>` —— 一轮的终局
+* - `subscribe(listener)` —— 流式 notifications 由 listener 异步接收
+* - 两条通道独立、不聚合、无队列
+*
+* 典型用法：
 * ```ts
-* retry: {
-*     retryOn: (err, ctx) => {
-*         if (err instanceof TimeoutError && ctx.url.includes('/upload')) return false;
-*         return DEFAULT_RETRY_ON(err, ctx);
-*     },
-* }
+* await session.connect();
+*
+* // 场景 A：只要最终结果
+* const response = await session.prompt('hello');
+* console.log(response.stopReason);
+*
+* // 场景 B：流式打印 + 最终结果
+* const unsub = session.subscribe((n) => {
+*   if (n.update.sessionUpdate === 'agent_message_chunk' &&
+*       n.update.content.type === 'text') {
+*     process.stdout.write(n.update.content.text);
+*   }
+* });
+* const response = await session.prompt('hello');
+* unsub();
+*
+* // 场景 C：便利钩子（等价于 B 但不需手动 unsub）
+* const response = await session.prompt('hello', {
+*   onChunk: (n) => { ... },
+* });
 * ```
 */
-const DEFAULT_RETRY_ON = (err, ctx) => {
-	if (err.name === "AbortError") return false;
-	if (err instanceof AuthError) return false;
-	if (err instanceof NotFoundError) return false;
-	if (err instanceof ValidationError) return false;
-	if (err instanceof AcpProtocolError) return false;
-	if (err instanceof TimeoutError) return ctx.method === "GET";
-	if (err instanceof NetworkError) return true;
-	return true;
-};
-/** 默认重试配置。 */
-const DEFAULT_RETRY = {
-	maxAttempts: 3,
-	backoffMs: 300,
-	backoffFactor: 2,
-	jitter: true,
-	retryOn: DEFAULT_RETRY_ON
-};
-var RestClient = class {
-	constructor(opts) {
-		this.opts = opts;
-		this.logger = loggerFor(opts);
-		this.fetchImpl = opts.fetch ?? fetch.bind(globalThis);
+var Session = class {
+	/** @internal */
+	constructor(id, runtime, restClient) {
+		this.id = id;
+		this.runtimeId = runtime.id;
+		this._runtime = runtime;
+		this._restClient = restClient;
 	}
-	/** GET 请求。 */
-	async get(path, query, opts) {
-		const url = this.buildUrl(path, query);
-		return this.request("GET", url, void 0, opts);
+	get status() {
+		return this._status;
 	}
-	/** POST 请求。 */
-	async post(path, body, opts) {
-		const url = this.buildUrl(path);
-		return this.request("POST", url, body, opts);
+	/** ACP 连接是否已建立 */
+	get connected() {
+		return this._acpClient?.state === "OPEN";
 	}
-	/** PATCH 请求。 */
-	async patch(path, body, opts) {
-		const url = this.buildUrl(path);
-		return this.request("PATCH", url, body, opts);
+	/** 拉最新元数据 */
+	async info(opts) {
+		const info = await this._restClient.get(`/runtimes/${this.runtimeId}/sessions/${this.id}`, void 0, opts);
+		this._status = info.sessionStatus;
+		return info;
 	}
-	/** DELETE 请求。 */
-	async delete(path, opts) {
-		const url = this.buildUrl(path);
-		return this.request("DELETE", url, void 0, opts);
+	/** 更新 name / manifest */
+	async update(req, opts) {
+		const info = await this._restClient.post(`/runtimes/${this.runtimeId}/sessions/${this.id}/update`, req, opts);
+		this._status = info.sessionStatus;
+		return info;
 	}
-	/** 构建完整 URL。 */
-	buildUrl(path, query) {
-		const base = (this.opts.baseUrl || DEFAULT_BASE_URL).replace(/\/+$/, "");
-		const fullPath = path.startsWith("/") ? path : `/${path}`;
-		const url = new URL(`${base}${fullPath}`);
-		if (query) {
-			for (const [k, v] of Object.entries(query)) if (v !== void 0 && v !== "") url.searchParams.set(k, v);
+	/** 软删除 */
+	async delete(opts) {
+		if (this._acpClient) {
+			await this._acpClient.disconnect();
+			this._acpClient = void 0;
 		}
-		return url.toString();
+		return this._restClient.post(`/runtimes/${this.runtimeId}/sessions/${this.id}/delete`, void 0, opts);
 	}
-	/** 构建请求 headers（含认证、身份、trace、自定义）。 */
-	buildHeaders(opts) {
-		const headers = {
-			"Content-Type": "application/json",
-			"Accept": "application/json"
-		};
-		if (this.opts.apiKey) headers["x-api-key"] = this.opts.apiKey;
-		if (this.opts.sourceApp) headers["X-Source-App"] = this.opts.sourceApp;
-		if (this.opts.sourceTenantId) headers["X-Source-Tenant-Id"] = this.opts.sourceTenantId;
-		if (this.opts.userId) headers["X-User-Id"] = this.opts.userId;
-		if (this.opts.headers) Object.assign(headers, this.opts.headers);
-		if (opts?.headers) Object.assign(headers, opts.headers);
-		headers["X-Request-Id"] = opts?.requestId ?? generateRequestId();
-		return headers;
+	/**
+	* 建立到沙箱的 ACP 连接。
+	*
+	* 内部流程：GET SSE → 获取 connectionId → initialize → session/load。
+	* 调用后 `prompt` / `subscribe` / `cancel` 才可用。
+	*
+	* 幂等：已连接时直接返回；并发调用时后来的等前者完成。
+	*/
+	async connect(opts) {
+		if (this._acpClient && this._acpClient.state === "OPEN") return;
+		const acpUrl = this._runtime.acpUrl;
+		let acpToken = this._runtime.acpToken;
+		if (!acpUrl || !acpToken) {
+			acpToken = await this._runtime.refreshToken();
+			if (!this._runtime.acpUrl || !acpToken) throw new ValidationError("Runtime does not have ACP link. Is it in RUNNING state?");
+		}
+		const connOpts = this._runtime._connectionOpts;
+		const client = new AcpClient({
+			logger: loggerFor(connOpts),
+			logLevel: resolveLogLevel(connOpts),
+			fetch: connOpts.fetch
+		});
+		client.setTokenRefresher(async () => this._runtime.refreshToken());
+		await client.connect(this._runtime.acpUrl, acpToken, {
+			...opts,
+			heartbeatTimeoutMs: opts?.heartbeatTimeoutMs ?? 45e3,
+			reconnectMaxAttempts: opts?.reconnectMaxAttempts ?? Infinity,
+			reconnectBackoffMs: opts?.reconnectBackoffMs ?? 300,
+			reconnectMaxBackoffMs: opts?.reconnectMaxBackoffMs ?? 3e4,
+			lastEventId: opts?.lastEventId
+		});
+		if (opts?.initialize !== false) await client.initialize();
+		await client.sessionLoad(this.id);
+		this._acpClient = client;
 	}
-	/** 发起请求（含超时 + 重试 + 日志 + 脱敏 + hooks）。 */
-	async request(method, url, body, opts) {
-		const shouldRetry = opts?.retry !== void 0 ? opts.retry : this.opts.retry ?? DEFAULT_RETRY;
-		const ctx = {
-			logId: makeLogId(),
-			retryOfLogId: void 0,
-			startTimeMs: 0
-		};
-		const doRequest = async () => {
-			ctx.startTimeMs = Date.now();
-			const timeoutMs = opts?.timeoutMs ?? this.opts.timeoutMs ?? 3e4;
-			const headers = this.buildHeaders(opts);
-			const requestId = headers["X-Request-Id"];
-			const controller = new AbortController();
-			let timeoutId;
-			if (timeoutMs > 0) timeoutId = setTimeout(() => controller.abort(), timeoutMs);
-			if (opts?.signal) if (opts.signal.aborted) controller.abort();
-			else opts.signal.addEventListener("abort", () => controller.abort(), { once: true });
-			const retryTag = ctx.retryOfLogId ? `, retryOf: ${ctx.retryOfLogId}` : "";
-			const redactedReqHeaders = redactHeaders(headers);
-			this.opts.onRequest?.({
-				method,
-				url,
-				headers: { ...redactedReqHeaders }
-			});
-			this.logger.debug(`[${ctx.logId}${retryTag}] sending request ${method} ${url}`, {
-				headers: redactedReqHeaders,
-				body: body !== void 0 ? truncate(redactBody(body)) : void 0
-			});
-			try {
-				const response = await this.fetchImpl(url, {
-					method,
-					headers,
-					body: body !== void 0 ? JSON.stringify(body) : void 0,
-					signal: controller.signal
-				});
-				const durationMs = Date.now() - ctx.startTimeMs;
-				const responseHeaders = {};
-				response.headers.forEach((v, k) => {
-					responseHeaders[k] = v;
-				});
-				const redactedResHeaders = redactHeaders(responseHeaders);
-				this.opts.onResponse?.({
-					status: response.status,
-					headers: { ...redactedResHeaders },
-					url
-				});
-				const serverReqId = response.headers.get("x-request-id") ?? requestId;
-				const reqIdTag = serverReqId ? `, request-id: "${serverReqId}"` : "";
-				const summary = `[${ctx.logId}${retryTag}${reqIdTag}] ${method} ${url} ${response.ok ? "succeeded" : "failed"} with status ${response.status} in ${durationMs}ms`;
-				this.logger.info(summary);
-				this.logger.debug(`[${ctx.logId}${retryTag}] response received`, {
-					status: response.status,
-					headers: redactedResHeaders,
-					durationMs
-				});
-				return await this.unwrap(response, ctx.logId, serverReqId);
-			} catch (err) {
-				if (timeoutId) clearTimeout(timeoutId);
-				const durationMs = Date.now() - ctx.startTimeMs;
-				if (err instanceof Error && err.name === "AbortError") {
-					if (opts?.signal?.aborted) {
-						this.logger.debug(`[${ctx.logId}${retryTag}] request cancelled by caller after ${durationMs}ms`);
-						throw err;
-					}
-					const msg = `Request timed out after ${timeoutMs}ms: ${method} ${url}`;
-					this.logger.debug(`[${ctx.logId}${retryTag}] ${msg}`);
-					throw new TimeoutError(msg, {
-						logId: ctx.logId,
-						cause: err
-					});
-				}
-				if (err instanceof TypeError || err instanceof Error && isNetworkError(err)) {
-					const msg = `Network error: ${method} ${url} - ${err.message}`;
-					this.logger.debug(`[${ctx.logId}${retryTag}] ${msg}`);
-					throw new NetworkError(msg, {
-						logId: ctx.logId,
-						cause: err
-					});
-				}
-				if (err instanceof CloudAgentError) throw err;
-				const msg = `Unexpected error: ${method} ${url} - ${err.message}`;
-				this.logger.error(`[${ctx.logId}${retryTag}] ${msg}`);
-				throw new NetworkError(msg, {
-					logId: ctx.logId,
-					cause: err
-				});
-			} finally {
-				if (timeoutId) clearTimeout(timeoutId);
-			}
-		};
-		if (shouldRetry === false) return doRequest();
-		return this.withRetry(doRequest, shouldRetry, ctx, method, url);
+	/** 断开 ACP 连接。所有订阅器被自动清除。 */
+	async disconnect() {
+		if (this._acpClient) {
+			await this._acpClient.disconnect();
+			this._acpClient = void 0;
+		}
 	}
-	/** 解包响应 `{ code, msg, data }` → `data` 或抛错。 */
-	async unwrap(response, logId, serverReqId) {
-		if (response.status === 204) return;
-		let body;
-		let rawText;
-		try {
-			rawText = await response.text();
-			const safeText = rawText.replace(/:\s*(\d{17,})/g, (match, num) => match.replace(num, `"${num}"`));
-			body = JSON.parse(safeText);
-		} catch {
-			if (!response.ok) throw this.httpStatusToError(response.status, `HTTP ${response.status}`, {
-				logId,
-				requestId: serverReqId
-			});
-			return rawText;
+	/**
+	* 发送 prompt 并等待 `PromptResponse`。
+	*
+	* @param input 纯文本字符串（自动包装成 text block）或 `ContentBlock[]`（多模态）
+	* @param opts 见 `PromptOpts`，支持 `signal` 取消、`onChunk` 便利钩子等
+	*
+	* @returns `PromptResponse`（当前只含 `stopReason`）
+	*
+	* **时序**：
+	* - 如果未 connect，会自动 connect
+	* - RPC 发出期间，上游会通过 **SSE notification 通道**推送 `session/update`，
+	*   这些消息**不会进 Promise 的结果**，需要通过 `subscribe()` 或 `onChunk`
+	*   回调接收
+	* - 同 session 并发 prompt 会被内部**串行化**（ACP 协议要求）
+	*
+	* @example
+	* ```ts
+	* // 最简：只要结果
+	* const r = await session.prompt('2+2?');
+	*
+	* // 流式打印 + 结果
+	* const r = await session.prompt('write a poem', {
+	*   onChunk: (n) => {
+	*     if (n.update.sessionUpdate === 'agent_message_chunk' &&
+	*         n.update.content.type === 'text') {
+	*       process.stdout.write(n.update.content.text);
+	*     }
+	*   },
+	* });
+	*
+	* // 取消
+	* const ctrl = new AbortController();
+	* setTimeout(() => ctrl.abort(), 5000);
+	* const r = await session.prompt('long task', { signal: ctrl.signal });
+	* ```
+	*/
+	async prompt(input, opts) {
+		if (!this._acpClient || this._acpClient.state !== "OPEN") await this.connect();
+		const content = typeof input === "string" ? [{
+			type: "text",
+			text: input
+		}] : input;
+		const unsubChunk = opts?.onChunk ? this._acpClient.subscribe(this.id, opts.onChunk) : void 0;
+		let timeoutCtrl;
+		let signal = opts?.signal;
+		if (opts?.timeoutMs !== void 0 && opts.timeoutMs > 0) {
+			timeoutCtrl = new AbortController();
+			const timer = setTimeout(() => timeoutCtrl.abort(), opts.timeoutMs);
+			signal?.addEventListener("abort", () => {
+				clearTimeout(timer);
+				timeoutCtrl.abort();
+			}, { once: true });
+			if (!signal) signal = timeoutCtrl.signal;
+			else signal = mergeAbortSignals(signal, timeoutCtrl.signal);
 		}
-		const effectiveRequestId = body.requestId || serverReqId;
-		if (!response.ok) throw this.httpStatusToError(response.status, body.msg || `HTTP ${response.status}`, {
-			logId,
-			requestId: effectiveRequestId,
-			code: body.code
-		});
-		if (body.code !== 0) throw this.codeToError(body.code, body.msg, {
-			logId,
-			requestId: effectiveRequestId,
-			httpStatus: response.status
-		});
-		return body.data;
-	}
-	/** HTTP 状态码映射为错误。 */
-	httpStatusToError(status, message, ctx) {
-		const opts = {
-			httpStatus: status,
-			logId: ctx.logId,
-			requestId: ctx.requestId,
-			code: ctx.code
-		};
-		switch (status) {
-			case 400: return new ValidationError(message, opts);
-			case 401:
-			case 403: return new AuthError(message, opts);
-			case 404: return new NotFoundError(message, opts);
-			case 408:
-			case 504: return new TimeoutError(message, opts);
-			case 429: return new NetworkError(message, opts);
-			default:
-				if (status >= 500) return new NetworkError(message, opts);
-				return new CloudAgentError(message, opts);
+		opts?.onTurnStart?.();
+		try {
+			const response = await this._acpClient.prompt(this.id, content, { signal });
+			opts?.onTurnEnd?.(response);
+			return response;
+		} finally {
+			unsubChunk?.();
 		}
 	}
-	/** 业务 code 映射为错误。 */
-	codeToError(code, message, ctx) {
-		const opts = {
-			code,
-			httpStatus: ctx.httpStatus,
-			logId: ctx.logId,
-			requestId: ctx.requestId
-		};
-		switch (code) {
-			case 10001: return new ValidationError(message, opts);
-			case 10034:
-			case 10085: return new AuthError(message, opts);
-			case 10064:
-			case 10065:
-			case 10067: return new NetworkError(message, opts);
-			case 10084: return new NotFoundError(message, opts);
-			case 10094: return new TimeoutError(message, opts);
-			case 1e4: return new NetworkError(message, opts);
-			default: return new CloudAgentError(message, opts);
-		}
+	/**
+	* 订阅该 session 所有上游 notifications。
+	*
+	* Listener 收到的是上游 `SessionNotification` 原样（`{ sessionId, update, _meta? }`）。
+	* `update` 是上游 11-tag 判别联合，在 switch 分支里类型自动收窄。
+	*
+	* 订阅独立于 prompt 生命周期——connect 之后注册，直到 unsubscribe 或
+	* disconnect 为止。一个 session 支持任意多个订阅者。
+	*
+	* @returns unsubscribe 函数，调用即退订。
+	*
+	* @example
+	* ```ts
+	* const unsub = session.subscribe((n) => {
+	*   switch (n.update.sessionUpdate) {
+	*     case 'agent_message_chunk':
+	*       if (n.update.content.type === 'text') print(n.update.content.text);
+	*       break;
+	*     case 'tool_call':
+	*       console.log('tool:', n.update.title);
+	*       break;
+	*   }
+	* });
+	* // ...
+	* unsub();
+	* ```
+	*/
+	subscribe(listener) {
+		if (!this._acpClient || this._acpClient.state !== "OPEN") throw new ValidationError("Session not connected. Call connect() first.");
+		return this._acpClient.subscribe(this.id, listener);
 	}
 	/**
-	* 重试逻辑。
+	* 取消当前运行的 prompt（如果有）。
 	*
-	* 是否重试只看 `opts.retryOn(err, ctx)`。用户传的 retryOn **完全替换** SDK
-	* 默认判定（不叠加、不 fallback 到 error 类上的任何字段）。
+	* 向服务端发 `session/cancel` notification，服务端会以 `stopReason: 'cancelled'`
+	* 结束当前 prompt，对应的 `prompt()` Promise 正常 resolve（不 reject）。
+	*
+	* **尽力而为**：服务端 RPC 失败时打 warn 日志吞掉，不抛给调用方——
+	* 因为"用户点了取消按钮"的 UX 契约就是"本地能返回"。
 	*/
-	async withRetry(fn, retryOpts, reqCtx, method, url) {
-		const opts = {
-			...DEFAULT_RETRY,
-			...retryOpts
-		};
-		let lastError;
-		for (let attempt = 1; attempt <= opts.maxAttempts; attempt++) try {
-			return await fn();
+	async cancel() {
+		if (!this._acpClient) return;
+		try {
+			await this._acpClient.sessionCancel(this.id);
 		} catch (err) {
-			lastError = err;
-			const retryCtx = {
-				attempt,
-				method,
-				url
-			};
-			if (!opts.retryOn(err, retryCtx)) throw err;
-			if (attempt >= opts.maxAttempts) break;
-			const delayMs = this.getBackoffMs(attempt, opts);
-			this.logger.warn(`[${reqCtx.logId}] retrying (attempt ${attempt}/${opts.maxAttempts}) in ${delayMs}ms — ${err.name}: ${err.message}`);
-			await sleep(delayMs);
-			reqCtx.retryOfLogId = reqCtx.logId;
-			reqCtx.logId = makeLogId();
+			loggerFor(this._runtime._connectionOpts).warn(`[session ${this.id}] cancel failed: ${err.message}`);
 		}
-		throw lastError;
-	}
-	/** 计算退避时间。 */
-	getBackoffMs(attempt, opts) {
-		const baseDelay = Math.min(opts.backoffMs * Math.pow(opts.backoffFactor, attempt - 1), 3e4);
-		if (!opts.jitter) return Math.round(baseDelay);
-		const jitterFactor = .2 * (Math.random() * 2 - 1);
-		return Math.round(baseDelay * (1 + jitterFactor));
 	}
 };
-function sleep(ms) {
-	return new Promise((resolve) => setTimeout(resolve, ms));
-}
-function isNetworkError(err) {
-	const msg = err.message.toLowerCase();
-	return msg.includes("failed to fetch") || msg.includes("fetch failed") || msg.includes("network") || msg.includes("econnrefused") || msg.includes("econnreset") || msg.includes("enotfound") || msg.includes("socket hang up");
-}
-function generateRequestId() {
-	if (typeof crypto !== "undefined" && typeof crypto.randomUUID === "function") return crypto.randomUUID();
-	return "xxxxxxxx-xxxx-4xxx-yxxx-xxxxxxxxxxxx".replace(/[xy]/g, (c) => {
-		const r = Math.random() * 16 | 0;
-		return (c === "x" ? r : r & 3 | 8).toString(16);
-	});
-}
 /**
-* 截断超长 body 用于 debug 日志，避免刷屏。
+* 合并两个 AbortSignal：任一 abort 时返回的 signal 也 abort。
 *
-* 调用方应先通过 `redactBody()` 做敏感字段脱敏，此函数只负责序列化 + 截断。
+* 用原生 `AbortSignal.any()` 不行——Node 18 没有。这里用最小 polyfill。
 */
-function truncate(body, maxChars = 500) {
-	try {
-		const str = typeof body === "string" ? body : JSON.stringify(body);
-		if (str.length <= maxChars) return str;
-		return str.slice(0, maxChars) + `…(truncated, total ${str.length} chars)`;
-	} catch {
-		return "[unserializable]";
+function mergeAbortSignals(a, b) {
+	if (typeof AbortSignal.any === "function") return AbortSignal.any([a, b]);
+	const ctrl = new AbortController();
+	const onAbort = () => ctrl.abort();
+	if (a.aborted || b.aborted) ctrl.abort();
+	else {
+		a.addEventListener("abort", onAbort, { once: true });
+		b.addEventListener("abort", onAbort, { once: true });
 	}
+	return ctrl.signal;
 }
 
+//#endregion
+//#region src/v1/runtime.ts
+var Runtime = class {
+	/** @internal */
+	constructor(restClient, connectionOpts, info) {
+		this.sessions = {
+			create: async (opts) => {
+				const body = {
+					sessionId: opts.sessionId,
+					sessionName: opts.sessionName,
+					agentManifest: opts.agentManifest
+				};
+				return new Session((await this._restClient.post(`/runtimes/${this.id}/sessions`, body, {
+					timeoutMs: opts.timeoutMs,
+					headers: opts.headers,
+					signal: opts.signal,
+					requestId: opts.requestId
+				})).sessionId, this, this._restClient);
+			},
+			get: async (sessionId, opts) => {
+				await this._restClient.get(`/runtimes/${this.id}/sessions/${sessionId}`, void 0, opts);
+				return new Session(sessionId, this, this._restClient);
+			},
+			list: async (opts) => {
+				const params = {};
+				if (opts?.page !== void 0) params.page = String(opts.page);
+				if (opts?.pageSize !== void 0) params.pageSize = String(opts.pageSize);
+				if (opts?.sessionStatus) params.sessionStatus = opts.sessionStatus;
+				return this._restClient.get(`/runtimes/${this.id}/sessions`, params, opts);
+			},
+			default: () => {
+				return new Session(this._defaultSessionId || this.id, this, this._restClient);
+			}
+		};
+		this.id = info.id;
+		this._info = info;
+		this._restClient = restClient;
+		this._connectionOpts = connectionOpts;
+		this.sandboxId = info.links?.sandboxLink?.sandboxId;
+		this.sandboxDomain = info.links?.sandboxLink?.endpoint;
+		this._acpUrl = info.links?.acpLink?.url;
+		this._acpToken = info.links?.acpLink?.token;
+		if (info.sessions && info.sessions.length > 0) this._defaultSessionId = info.sessions[0].sessionId;
+	}
+	get runtimeInfo() {
+		return this._info;
+	}
+	get acpUrl() {
+		return this._acpUrl;
+	}
+	get acpToken() {
+		return this._acpToken;
+	}
+	/** 更新 Runtime 元数据 */
+	async update(req, opts) {
+		const info = await this._restClient.post(`/runtimes/${this.id}/update`, req, opts);
+		this._info = info;
+		return info;
+	}
+	/** 软删除 */
+	async delete(opts) {
+		return this._restClient.post(`/runtimes/${this.id}/delete`, void 0, opts);
+	}
+	/** 刷新 token（拉最新 RuntimeInfo，更新 acpLink） */
+	async refreshToken(opts) {
+		const info = await this._restClient.get(`/runtimes/${this.id}`, void 0, opts);
+		this._info = info;
+		if (info.links?.acpLink) {
+			this._acpUrl = info.links.acpLink.url;
+			this._acpToken = info.links.acpLink.token;
+		}
+		return this._acpToken || "";
+	}
+};
+
 //#endregion
 //#region src/v1/client.ts
+/**
+* CloudAgentClient — SDK 顶层入口
+*
+* 持有 ConnectionOpts，提供 runtimes 子命名空间（仅控制面集合操作）。
+* 本身不发起网络请求、不持有连接。
+*/
+/** Secret key 名（服务端 `constants.CodebuddyAPIKey`）。 */
+const CODEBUDDY_API_KEY = "CODEBUDDY_API_KEY";
 var CloudAgentClient = class CloudAgentClient {
 	/** 构造（同步，不发网络请求） */
 	constructor(opts = {}) {
 		this.runtimes = {
 			create: async (opts) => {
+				const agentManifest = withInjectedApiKeySecret(opts.agentManifest, this.opts.apiKey, this.opts);
 				const body = {
 					runtimeName: opts.runtimeName,
-					agentManifest: opts.agentManifest,
+					agentManifest,
 					sandboxTemplateId: opts.sandboxTemplateId,
 					sandboxSpec: opts.sandboxSpec,
 					sandboxType: opts.sandboxType,
@@ -2632,6 +2659,38 @@ var CloudAgentClient = class CloudAgentClient {
 		});
 	}
 };
+/**
+* 按需注入 `CODEBUDDY_API_KEY` secret 的兜底逻辑。
+*
+* SDK 只负责一件事：**把 `ConnectionOpts.apiKey` 透传到沙箱 agent** —— 这个
+* credential 本来就是调用方已经提供过的，用户不应该被迫在 manifest 里再写一遍。
+*
+* 规则（按优先级）：
+* 1. `userManifest.secrets[CODEBUDDY_API_KEY]` 已显式声明 → 保留用户值，不覆盖
+* 2. `userManifest` 根本没传 → 原样返回 `undefined`，让服务端按"manifest 必填字段缺失"
+*    报明确错误（SDK 不编造 `id/name/manifestVersion` 等用户的业务语义）
+* 3. `ConnectionOpts.apiKey` 为空 → 无从兜底，原样返回
+* 4. 其他情况（用户传了 manifest 但没 `CODEBUDDY_API_KEY`，且 Client 有 apiKey）
+*    → 追加 secrets，不 mutate 入参
+*
+* 设计取舍：SDK 不探查 `opts.metadata.CODEBUDDY_API_KEY` —— metadata 是
+* AgentOS 与上游网关之间的内部协议（见服务端 `sandbox_builder.go` 的优先级逻辑），
+* 不是 SDK 用户的常规使用通道。即便用户显式在 metadata 里塞了一个 key，服务端
+* 自身的优先级会用 metadata 值覆盖 manifest 里注入的那条，行为正确。
+*/
+function withInjectedApiKeySecret(userManifest, apiKey, connectionOpts) {
+	if (userManifest?.secrets?.some((s) => s.key === CODEBUDDY_API_KEY)) return userManifest;
+	if (!userManifest) return;
+	if (!apiKey) return userManifest;
+	loggerFor(connectionOpts).debug(`[runtimes.create] auto-injected ${CODEBUDDY_API_KEY} secret from ConnectionOpts.apiKey (no explicit value in agentManifest.secrets)`);
+	return {
+		...userManifest,
+		secrets: [...userManifest.secrets ?? [], {
+			key: CODEBUDDY_API_KEY,
+			value: apiKey
+		}]
+	};
+}
 
 //#endregion
 //#region src/v1/manifest.ts