@flowy-agent-store/client 0.1.0-beta.3 → 0.1.0-beta.4

package/dist/index.mjs

@@ -237,6 +237,532 @@ var WebSocketTransport = class {
 	}
 };
 //#endregion
+//#region src/http-transport.ts
+/**
+* HTTP transport binding (doc `16` R2 / `05` §2.1.1).
+*
+* ## What this is
+*
+* The App Server exposes one method semantics over two bindings. This class is
+* the **request/response** binding: it maps a protocol method name onto the
+* server's hand-written REST route and returns the same result body the
+* WebSocket binding would.
+*
+* ## What this is not
+*
+* - **No server push.** HTTP has no notification channel, so `onNotification`
+*   hands back a no-op unsubscribe and `notify` throws. Live conversation / run
+*   events and subscription methods (`conversation/subscribe`, `run/subscribe`)
+*   exist **only** over `WebSocketTransport`; an `HttpTransport` is not a
+*   drop-in replacement for it. Consumers that need events must connect over
+*   WS (or run both).
+* - **One-shot handshake per call.** `05` §2.1.1: *each* HTTP call performs its
+*   own `POST /initialize` → `POST /initialized` → business call, after which
+*   the connection id expires. `connect()` therefore has nothing to hold open
+*   and is a no-op; it does not warm anything up.
+* - **Host file services stay out.** `/api/fs/*` (browse / list / read /
+*   metadata) is a host file service on the server *root*, explicitly not a
+*   protocol method (`05` §2.1.1), so it is not reachable through this class.
+*
+* ## The route table
+*
+* Every entry was read out of the handler bodies in
+* `crates/backend/nomifun-app-server/src/lib.rs` — the `source` field records
+* which handler (and, where one exists, which shared `*_impl`) proves the two
+* bindings run the same operation. Methods with no entry throw
+* `TransportError("send", …)` instead of silently degrading.
+*/
+/** Header the server mints the per-call connection id under. */
+const CONNECTION_HEADER = "x-app-server-connection-id";
+/** Protocol version this binding announces on the one-shot handshake. */
+const PROTOCOL_VERSION = "fp-1";
+/**
+* Protocol method → REST route. Verified from handler bodies, not from the
+* route list (a route existing does not prove which method it mirrors).
+*/
+const HTTP_ROUTES = {
+	ping: {
+		verb: "POST",
+		path: "/ping",
+		source: "ping() -> registry.require_ready"
+	},
+	"workspace/list": {
+		verb: "GET",
+		path: "/workspaces",
+		source: "workspace_list() -> owner-scoped active rows"
+	},
+	"workspace/revoke": {
+		verb: "DELETE",
+		path: "/workspaces/:workspace_id",
+		source: "workspace_delete() -> workspace_revoke_impl (shared with the WS arm)"
+	},
+	"conversation/create": {
+		verb: "POST",
+		path: "/conversations",
+		source: "conversation_create() -> create_conversation_for_user (shared)"
+	},
+	"conversation/list": {
+		verb: "GET",
+		path: "/conversations",
+		query: ["limit"],
+		source: "conversation_list() -> list_app_server_chats (shared); Query<limit>"
+	},
+	"conversation/get": {
+		verb: "GET",
+		path: "/conversations/:conversation_id",
+		source: "conversation_get() -> project_conversation_view (shared)"
+	},
+	"conversation/delete": {
+		verb: "DELETE",
+		path: "/conversations/:conversation_id",
+		source: "conversation_delete() -> conversation/delete arm semantics"
+	},
+	"conversation/messages": {
+		verb: "GET",
+		path: "/conversations/:conversation_id/messages",
+		query: [
+			"page",
+			"page_size",
+			"cursor"
+		],
+		source: "conversation_messages() -> list_conversation_messages_for_user (shared)"
+	},
+	"conversation/send": {
+		verb: "POST",
+		path: "/conversations/:conversation_id/messages",
+		body: [
+			"content",
+			"idempotency_key",
+			"attachments"
+		],
+		source: "conversation_send() -> send_conversation_message_for_user (shared with the WS arm)"
+	},
+	"conversation/cancel": {
+		verb: "POST",
+		path: "/conversations/:conversation_id/cancel",
+		source: "conversation_cancel() -> cancel arm semantics"
+	},
+	"agent/run": {
+		verb: "POST",
+		path: "/agent/run",
+		source: "agent_run() -> same request/receipt as the `agent/run` arm"
+	},
+	"team/run": {
+		verb: "POST",
+		path: "/team/run",
+		source: "team_run() -> execute_team_run() (same as the WS arm); Leader Conversation + planned delegation, `TeamRunReceipt`"
+	},
+	"run/get": {
+		verb: "GET",
+		path: "/run/:run_id",
+		source: "run_get()"
+	},
+	"run/result": {
+		verb: "GET",
+		path: "/run/:run_id/result",
+		source: "run_result()"
+	},
+	"run/plan": {
+		verb: "GET",
+		path: "/run/:run_id/plan",
+		source: "run_plan() -> get_run_plan_for_user() (same as the WS arm)"
+	},
+	"run/events": {
+		verb: "GET",
+		path: "/run/:run_id/events",
+		query: ["after_sequence", "limit"],
+		source: "run_events() -> runtime.list_events(after_sequence, limit) (same as the WS arm)"
+	},
+	"run/cancel": {
+		verb: "POST",
+		path: "/run/:run_id/cancel",
+		body: [
+			"expected_version",
+			"reason",
+			"idempotency_key"
+		],
+		source: "run_cancel() -> same CancelRunRequest as the WS arm"
+	},
+	"run/steer": {
+		verb: "POST",
+		path: "/run/:run_id/steer",
+		body: [
+			"text",
+			"expected_version",
+			"command_id",
+			"idempotency_key"
+		],
+		source: "run_steer() -> execute_steer_run (shared with the WS arm)"
+	},
+	"run/answer-decision": {
+		verb: "POST",
+		path: "/run/:run_id/answer-decision",
+		body: [
+			"step_id",
+			"attempt_id",
+			"answer",
+			"expected_execution_version",
+			"expected_step_version",
+			"expected_attempt_version"
+		],
+		source: "run_answer_decision() -> execute_answer_decision (shared with the WS arm; engine answer gate, no always_allow)"
+	},
+	"skill/list": {
+		verb: "GET",
+		path: "/skills",
+		source: "list_skills_route() -> list_skills_impl"
+	},
+	"skill/get": {
+		verb: "GET",
+		path: "/skills/:skill_id",
+		source: "get_skill_route() -> get_skill_impl"
+	},
+	"skill/files": {
+		verb: "GET",
+		path: "/skills/:skill_id/files",
+		source: "list_skill_files_route() -> list_skill_files_impl"
+	},
+	"connector/list": {
+		verb: "GET",
+		path: "/connectors",
+		source: "list_connectors_route() -> list_connectors_impl"
+	},
+	"models/list": {
+		verb: "GET",
+		path: "/models",
+		source: "list_models_route() -> list_models_impl"
+	},
+	"connector/get": {
+		verb: "GET",
+		path: "/connectors/:connector_id",
+		source: "get_connector_route() -> get_connector_impl"
+	},
+	"connector/status": {
+		verb: "GET",
+		path: "/connectors/:connector_id/status",
+		source: "connector_status_route() -> connector_status_impl"
+	},
+	"connector/test": {
+		verb: "POST",
+		path: "/connectors/:connector_id/test",
+		source: "connector_test_route() -> connector_test_impl"
+	},
+	"connector/call": {
+		verb: "POST",
+		path: "/connectors/:connector_id/call",
+		source: "connector_call_route() -> connector_call_impl"
+	},
+	"connector/auth/start": {
+		verb: "POST",
+		path: "/connectors/:connector_id/auth-start",
+		source: "connector_auth_start_route() -> connector_auth_start_impl (WS name uses slashes)"
+	},
+	"connector/auth/status": {
+		verb: "GET",
+		path: "/connectors/:connector_id/auth-status",
+		source: "connector_auth_status_route() -> connector_auth_status_impl"
+	},
+	"connector/auth/logout": {
+		verb: "POST",
+		path: "/connectors/:connector_id/auth-logout",
+		source: "connector_auth_logout_route() -> connector_auth_logout_impl"
+	},
+	"import/run": {
+		verb: "POST",
+		path: "/imports",
+		source: "run_import_route() -> run_import_impl"
+	},
+	"import/list": {
+		verb: "GET",
+		path: "/imports",
+		source: "list_imports_route() -> list_imports_impl"
+	},
+	"import/get": {
+		verb: "GET",
+		path: "/imports/:snapshot_id",
+		source: "get_import_route() -> get_import_impl"
+	},
+	"install/run": {
+		verb: "POST",
+		path: "/installs",
+		source: "run_install_route() -> install_impl"
+	},
+	"install/status": {
+		verb: "GET",
+		path: "/installs/:snapshot_id",
+		source: "install_status_route() -> install_status_impl"
+	},
+	"install/disable": {
+		verb: "POST",
+		path: "/installs/:snapshot_id/disable",
+		body: ["component_ids"],
+		source: "install_disable_route() -> install_disable_impl; body `component_ids`"
+	},
+	"install/enable": {
+		verb: "POST",
+		path: "/installs/:snapshot_id/enable",
+		body: ["component_ids"],
+		source: "install_enable_route() -> install_enable_impl; body `component_ids`"
+	},
+	"install/uninstall": {
+		verb: "POST",
+		path: "/installs/:snapshot_id/uninstall",
+		body: ["component_ids"],
+		source: "install_uninstall_route() -> install_uninstall_impl; body `component_ids`"
+	},
+	"market/add": {
+		verb: "POST",
+		path: "/markets",
+		source: "market_add_route() -> market_add_impl"
+	},
+	"market/list": {
+		verb: "GET",
+		path: "/markets",
+		source: "market_list_route() -> market_list_impl"
+	},
+	"market/get": {
+		verb: "GET",
+		path: "/markets/:marketplace_id",
+		source: "market_get_route() -> market_get_impl"
+	},
+	"market/remove": {
+		verb: "POST",
+		path: "/markets/:marketplace_id/remove",
+		body: ["cascade"],
+		source: "market_remove_route() -> market_remove_impl; body `cascade` defaults to true"
+	},
+	"market/auto-update": {
+		verb: "POST",
+		path: "/markets/:marketplace_id/auto-update",
+		body: ["enabled"],
+		source: "market_auto_update_route() -> market_auto_update_impl; body `enabled` defaults to true"
+	},
+	"market/refresh": {
+		verb: "POST",
+		path: "/markets/:marketplace_id/refresh",
+		source: "market_refresh_route() -> market_refresh_impl"
+	},
+	"market/entry-import": {
+		verb: "POST",
+		path: "/markets/:marketplace_id/entries/:entry_name/import",
+		source: "market_entry_import_route() -> market_entry_import_impl"
+	},
+	"store/list": {
+		verb: "GET",
+		path: "/store",
+		source: "store_list_route() -> store_list_impl"
+	},
+	"store/install-entry": {
+		verb: "POST",
+		path: "/store/:marketplace_id/entries/:entry_name/install",
+		source: "store_install_entry_route() -> store_install_entry_impl"
+	}
+};
+/** Methods that are WebSocket-only by design — named so the error explains itself. */
+const WS_ONLY_METHODS = /* @__PURE__ */ new Set([
+	"initialize",
+	"initialized",
+	"conversation/subscribe",
+	"conversation/unsubscribe",
+	"run/subscribe",
+	"run/unsubscribe"
+]);
+var HttpTransport = class {
+	routes;
+	options;
+	closed = false;
+	constructor(options, routes = HTTP_ROUTES) {
+		this.options = options;
+		this.routes = routes;
+	}
+	/**
+	* No-op: the HTTP binding handshakes per call (`05` §2.1.1), so there is no
+	* connection to open. Kept for `Transport` compatibility.
+	*/
+	async connect() {
+		this.closed = false;
+	}
+	/**
+	* Perform one business call over its own handshake.
+	*
+	* Throws `TransportError("send", …)` for a method with no HTTP binding —
+	* never a silent fallback to another binding.
+	*/
+	async request(method, params) {
+		if (this.closed) throw new TransportError("connect", "http transport is closed");
+		const route = this.routes[method];
+		if (!route) {
+			const reason = WS_ONLY_METHODS.has(method) ? `"${method}" is WebSocket-only (doc 05 §2.1.1); use WebSocketTransport for subscriptions and live events` : `"${method}" has no HTTP binding in this SDK (doc 16 R2 route table)`;
+			throw new TransportError("send", reason);
+		}
+		const { path, query, body } = this.splitParams(route, params);
+		const connectionId = await this.openConnection();
+		const response = await this.fetchWithTimeout(route.verb, path, {
+			query,
+			body,
+			connectionId
+		});
+		return await this.readResult(response, method);
+	}
+	/**
+	* Not supported: HTTP carries no server-push. Throws instead of pretending.
+	*/
+	notify(method, _params) {
+		throw new TransportError("send", `HTTP binding cannot notify ("${method}"): notifications are WebSocket-only (doc 05 §2.1.1)`);
+	}
+	/**
+	* Returns a no-op unsubscribe: this binding receives **no** notifications.
+	*
+	* Not equivalent to the WebSocket binding — callers that need live events
+	* must use `WebSocketTransport` (or run both).
+	*/
+	onNotification(_listener) {
+		return () => void 0;
+	}
+	/** No-op: every call is independent, so nothing is held open. */
+	close() {
+		this.closed = true;
+	}
+	/**
+	* One-shot handshake: `POST /initialize` (connection id header) →
+	* `POST /initialized`. Returns the connection id.
+	*
+	* Public because host-side services that sit *outside* the protocol surface
+	* (`/api/fs/*`, the HTTP-only `POST /workspaces` register route) still need a
+	* ready connection id; they are not protocol methods, so they cannot go
+	* through `request()`.
+	*/
+	async openConnection() {
+		const connectionId = (await this.fetchWithTimeout("POST", "/initialize", { body: {
+			protocol_version: PROTOCOL_VERSION,
+			client: this.options.client ?? {
+				name: "flowy-agent-store-client",
+				version: "0.1.0"
+			},
+			...this.options.capabilities === void 0 ? {} : { capabilities: this.options.capabilities }
+		} })).headers.get(CONNECTION_HEADER);
+		if (!connectionId) throw new TransportError("connect", `handshake response is missing the ${CONNECTION_HEADER} header`, { retryable: true });
+		await this.fetchWithTimeout("POST", "/initialized", { connectionId });
+		return connectionId;
+	}
+	splitParams(route, params) {
+		const source = isRecord(params) ? params : {};
+		const pathParams = [...route.path.matchAll(/:([A-Za-z0-9_]+)/g)].map((match) => match[1]);
+		const path = route.path.replace(/:([A-Za-z0-9_]+)/g, (_full, name) => {
+			const value = source[name];
+			if (value === void 0 || value === null) throw new TransportError("send", `missing required path param "${name}" for ${route.verb} ${route.path}`);
+			return encodeURIComponent(String(value));
+		});
+		const query = {};
+		for (const key of route.query ?? []) {
+			const value = source[key];
+			if (value !== void 0 && value !== null) query[key] = String(value);
+		}
+		if (route.verb === "GET" || route.verb === "DELETE") return {
+			path,
+			query,
+			body: void 0
+		};
+		const carried = route.body ?? [];
+		const body = {};
+		for (const key of Object.keys(source)) {
+			if (pathParams.includes(key) || (route.query ?? []).includes(key)) continue;
+			if (carried.length > 0 && !carried.includes(key)) continue;
+			body[key] = source[key];
+		}
+		return {
+			path,
+			query,
+			body
+		};
+	}
+	async fetchWithTimeout(verb, path, request) {
+		const url = new URL(`${this.baseUrl()}${path}`);
+		for (const [key, value] of Object.entries(request.query ?? {})) url.searchParams.set(key, value);
+		const headers = { accept: "application/json" };
+		if (request.body !== void 0) headers["content-type"] = "application/json";
+		if (request.connectionId) headers[CONNECTION_HEADER] = request.connectionId;
+		if (this.options.token) headers.authorization = `Bearer ${this.options.token}`;
+		const controller = new AbortController();
+		const timeoutMs = this.options.requestTimeoutMs ?? 3e4;
+		const timer = setTimeout(() => controller.abort(), timeoutMs);
+		try {
+			const fetchImpl = this.options.fetch ?? globalThis.fetch;
+			if (!fetchImpl) throw new TransportError("connect", "no fetch implementation available");
+			return await fetchImpl(url.toString(), {
+				method: verb,
+				headers,
+				body: request.body === void 0 ? void 0 : JSON.stringify(request.body),
+				signal: controller.signal
+			});
+		} catch (error) {
+			if (error instanceof TransportError) throw error;
+			const aborted = error?.name === "AbortError";
+			throw new TransportError("send", aborted ? `${verb} ${path} timed out after ${timeoutMs}ms` : `${verb} ${path} failed: ${String(error)}`, {
+				retryable: true,
+				cause: error
+			});
+		} finally {
+			clearTimeout(timer);
+		}
+	}
+	/** 2xx → result body; otherwise the server's wire error becomes an `AppServerError`. */
+	async readResult(response, method) {
+		let payload = void 0;
+		const text = await response.text();
+		if (text.length > 0) try {
+			payload = JSON.parse(text);
+		} catch {
+			if (response.ok) throw new TransportError("receive", `${method}: response is not JSON`, { retryable: true });
+		}
+		if (response.ok) return payload;
+		throw appServerErrorFromWire(payload, response.status, method);
+	}
+	baseUrl() {
+		return this.options.baseUrl.replace(/\/+$/, "").replace(/\/ws$/, "");
+	}
+};
+function isRecord(value) {
+	return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+/**
+* Turn an HTTP failure body into the SDK error model.
+*
+* Shared by this transport and by host-side helpers (webui `lib/client.ts`) so
+* a second spelling of the wire-error mapping cannot drift. Two wire contracts
+* reach this function, both of them `AppError` on the server:
+*
+* - the App Server emits `{code, message, retryable, details, request_id}`
+*   (`into_wire_error`), which is exactly the `AppServerError` shape;
+* - the standalone host file service (`/api/fs/*`) emits the `ErrorResponse`
+*   envelope `{success: false, error, code, details?}` — same error, another
+*   spelling: `error` carries the human message, and there is no retry hint, so
+*   a 5xx status stays the retry signal.
+*
+* Anything else becomes a retryable-on-5xx `TransportError`.
+*/
+function appServerErrorFromWire(payload, status, context = "request") {
+	if (isRecord(payload) && typeof payload.code === "string" && typeof payload.message === "string") return new AppServerError({
+		code: payload.code,
+		message: payload.message,
+		retryable: payload.retryable === true,
+		request_id: payload.request_id ?? null,
+		details: isRecord(payload.details) ? payload.details : {}
+	});
+	if (isRecord(payload) && payload.success === false && typeof payload.code === "string" && typeof payload.error === "string") return new AppServerError({
+		code: payload.code,
+		message: payload.error,
+		retryable: status >= 500,
+		request_id: null,
+		details: isRecord(payload.details) ? payload.details : {}
+	});
+	return new TransportError("receive", `${context}: HTTP ${status} without a wire error body`, { retryable: status >= 500 });
+}
+/** Exposed for tests and docs (R5): the verified method → route table. */
+function httpRouteTable() {
+	return HTTP_ROUTES;
+}
+//#endregion
 //#region src/agents.ts
 var AgentClient = class {
 	transport;
@@ -299,11 +825,19 @@ var ConversationClient = class {
 			cursor: query.cursor
 		});
 	}
-	send(conversationId, content, idempotencyKey) {
+	/**
+	* R15（W10）：`attachments` 是**会话工作区内的绝对路径**（图片附件）。
+	*
+	* 缺省不传，保持老调用方的 wire 形状逐字不变；服务端只接受会话工作区内的真实
+	* 文件（越界 / 相对路径 / 不存在一律拒），具体准入见
+	* `nomifun-app-server` 的 `resolve_conversation_attachments`。
+	*/
+	send(conversationId, content, idempotencyKey, attachments = []) {
 		return this.transport.request("conversation/send", {
 			conversation_id: conversationId,
 			content,
-			idempotency_key: idempotencyKey
+			idempotency_key: idempotencyKey,
+			...attachments.length > 0 ? { attachments } : {}
 		});
 	}
 	cancel(conversationId) {
@@ -312,35 +846,92 @@ var ConversationClient = class {
 	delete(conversationId) {
 		return this.transport.request("conversation/delete", { conversation_id: conversationId });
 	}
-	async follow(conversationId) {
+	/**
+	* Subscribe to one conversation's realtime stream (doc `16` R1).
+	*
+	* `options.fetchMessages` is what makes auto catch-up possible: a detected
+	* sequence gap or a `conversation/resync-required` triggers one transcript
+	* fetch whose result is handed to `onBackfill`. Conversations have no event
+	* replay API (`05` §「V1 不提供 after_cursor 事件追平」), so the transcript is
+	* the recovery medium — unlike Runs, where `run/events` replays the events
+	* themselves.
+	*/
+	async follow(conversationId, options = {}) {
 		await this.transport.request("conversation/subscribe", { conversation_id: conversationId });
-		return new ConversationSubscription(this.transport, conversationId);
+		return new ConversationSubscription(this.transport, conversationId, {
+			fetchMessages: (id) => this.messages({
+				conversationId: id,
+				pageSize: 50
+			}),
+			...options
+		});
 	}
 };
+/** Events held before the first listener attaches (see `pendingLimit`). */
+const DEFAULT_PENDING_LIMIT = 256;
 var ConversationSubscription = class {
 	transport;
 	conversationId;
+	options;
 	events = /* @__PURE__ */ new Set();
 	resyncs = /* @__PURE__ */ new Set();
+	errors = /* @__PURE__ */ new Set();
+	backfills = /* @__PURE__ */ new Set();
 	closed = false;
 	lastSeenSequence = 0;
 	removeListener;
-	constructor(transport, conversationId) {
+	/**
+	* `follow()` resolves as soon as the server acknowledged the subscription,
+	* but the caller attaches listeners one tick later. Events landing in that
+	* window used to be dropped silently; they are held here (oldest first) and
+	* flushed to the first `onEvent` listener.
+	*/
+	pending = [];
+	pendingDropped = 0;
+	backfillInFlight = null;
+	constructor(transport, conversationId, options = {}) {
 		this.transport = transport;
 		this.conversationId = conversationId;
+		this.options = options;
 		this.removeListener = transport.onNotification((notification) => this.dispatch(notification));
 	}
 	get lastSequence() {
 		return this.lastSeenSequence;
 	}
+	/** Events dropped because nobody was listening and the buffer was full. */
+	get droppedPendingCount() {
+		return this.pendingDropped;
+	}
 	onEvent(listener) {
 		this.events.add(listener);
+		if (this.events.size === 1 && this.pending.length > 0) {
+			const queued = this.pending;
+			this.pending = [];
+			for (const event of queued) this.deliver(event);
+		}
 		return () => this.events.delete(listener);
 	}
 	onResync(listener) {
 		this.resyncs.add(listener);
 		return () => this.resyncs.delete(listener);
 	}
+	/**
+	* Auto catch-up result (R1). Fires only when `autoResync` is on and the
+	* transcript fetch succeeded; the listener owns replacing the transcript.
+	*/
+	onBackfill(listener) {
+		this.backfills.add(listener);
+		return () => this.backfills.delete(listener);
+	}
+	/**
+	* Failures that used to be swallowed: the catch-up fetch, and a failed
+	* re-subscribe during `rearm()`. Listener isolation keeps one bad listener
+	* from hiding the error from the others.
+	*/
+	onError(listener) {
+		this.errors.add(listener);
+		return () => this.errors.delete(listener);
+	}
 	async close() {
 		if (this.closed) return;
 		this.closed = true;
@@ -348,6 +939,9 @@ var ConversationSubscription = class {
 		this.removeListener = null;
 		this.events.clear();
 		this.resyncs.clear();
+		this.errors.clear();
+		this.backfills.clear();
+		this.pending = [];
 		try {
 			await this.transport.request("conversation/unsubscribe", { conversation_id: this.conversationId });
 		} catch {}
@@ -355,35 +949,99 @@ var ConversationSubscription = class {
 	/**
 	* Re-arm after a reconnect (docs/agent-store/16 T8): re-register the
 	* notification listener, reset the cursor and re-issue
-	* `conversation/subscribe`. This subscription has no event-replay API, so the
-	* caller must still backfill the transcript for the outage window
-	* (`conversation/messages`). Call it once the handshake completed; a no-op
-	* once closed.
+	* `conversation/subscribe`. The server restarts a conversation's sequence at
+	* 1 for a fresh subscription, which is exactly why the cursor resets. On a
+	* failed re-subscribe the error reaches `onError` and the caller can still
+	* backfill the outage window via `conversation/messages`.
 	*/
 	async rearm() {
 		if (this.closed) return;
 		this.removeListener?.();
 		this.removeListener = this.transport.onNotification((notification) => this.dispatch(notification));
 		this.lastSeenSequence = 0;
-		await this.transport.request("conversation/subscribe", { conversation_id: this.conversationId });
+		try {
+			await this.transport.request("conversation/subscribe", { conversation_id: this.conversationId });
+		} catch (error) {
+			this.emitError(error);
+			throw error;
+		}
 	}
 	dispatch(notification) {
 		if (notification.method === "conversation/event") {
 			const event = notification.params;
-			if (event.conversation_id !== this.conversationId || event.sequence <= this.lastSeenSequence) return;
+			if (event.conversation_id !== this.conversationId) return;
+			if (!Number.isFinite(event.sequence)) return;
+			if (event.sequence <= this.lastSeenSequence) return;
+			const gap = this.lastSeenSequence > 0 && event.sequence > this.lastSeenSequence + 1;
 			this.lastSeenSequence = event.sequence;
-			for (const listener of [...this.events]) try {
-				listener(event);
-			} catch {}
+			if (this.events.size === 0) this.buffer(event);
+			else this.deliver(event);
+			if (gap) {
+				this.emitResync("gap");
+				this.requestBackfill("gap");
+			}
 			return;
 		}
 		if (notification.method === "conversation/resync-required") {
 			if (!notification.params.conversation_ids.includes(this.conversationId)) return;
-			for (const listener of [...this.resyncs]) try {
-				listener(notification.params.reason);
-			} catch {}
+			this.emitResync(notification.params.reason);
+			this.requestBackfill(notification.params.reason);
 		}
 	}
+	buffer(event) {
+		const limit = this.options.pendingLimit ?? DEFAULT_PENDING_LIMIT;
+		this.pending.push(event);
+		while (this.pending.length > limit) {
+			this.pending.shift();
+			this.pendingDropped += 1;
+		}
+	}
+	deliver(event) {
+		for (const listener of [...this.events]) try {
+			listener(event);
+		} catch {}
+	}
+	emitResync(reason) {
+		for (const listener of [...this.resyncs]) try {
+			listener(reason);
+		} catch {}
+	}
+	emitError(error) {
+		for (const listener of [...this.errors]) try {
+			listener(error);
+		} catch {}
+	}
+	/**
+	* One in-flight catch-up at a time: a burst of resync signals collapses into
+	* a single transcript fetch (the fetch itself returns the newest page, so the
+	* result supersedes every signal that arrived before it).
+	*/
+	requestBackfill(reason) {
+		if (this.closed || this.options.autoResync === false) return;
+		const fetchMessages = this.options.fetchMessages;
+		if (!fetchMessages || this.backfillInFlight) return;
+		const task = (async () => {
+			try {
+				const page = await fetchMessages(this.conversationId);
+				if (this.closed) return;
+				const backfill = {
+					conversationId: this.conversationId,
+					reason,
+					messages: page?.items ?? [],
+					hasMore: page?.has_more === true
+				};
+				for (const listener of [...this.backfills]) try {
+					listener(backfill);
+				} catch {}
+			} catch (error) {
+				this.emitError(error);
+			}
+		})();
+		this.backfillInFlight = task;
+		task.finally(() => {
+			if (this.backfillInFlight === task) this.backfillInFlight = null;
+		});
+	}
 };
 //#endregion
 //#region src/connectors.ts
@@ -423,6 +1081,28 @@ var ConnectorClient = class {
 	logout(connectorId) {
 		return this.transport.request("connector/auth/logout", { connector_id: connectorId }).then(() => void 0);
 	}
+	/**
+	* Run one tool on a registered connector, through the host's own connection.
+	*
+	* The host holds the transport, its headers and its OAuth token; this sends a
+	* tool name and an argument object and nothing else — you cannot name a URL,
+	* a command or a header. Whether the pair is callable at all is the host's
+	* `[connector_proxy]` allowlist, so expect `policy_denied` on a host whose
+	* operator has not listed this tool (that is the default, not a
+	* misconfiguration).
+	*
+	* Resolves even when the tool itself failed — check `is_error`. It rejects
+	* only when the call never reached the tool: `connector_call_timeout`,
+	* `connector_call_failed`, `response_too_large`, `connector_unavailable`,
+	* `policy_denied`, `not_found`.
+	*/
+	call(connectorId, tool, args = {}) {
+		return this.transport.request("connector/call", {
+			connector_id: connectorId,
+			tool,
+			arguments: args
+		});
+	}
 };
 //#endregion
 //#region src/runs.ts
@@ -439,6 +1119,18 @@ var RunClient = class {
 	agent(input) {
 		return this.transport.request("agent/run", toWire(input));
 	}
+	/**
+	* Start a Team run (`16` §7 决策 3): the server creates the Leader
+	* Conversation, materializes/binds the Team's execution template and returns
+	* the public run id of the execution the Leader started.
+	*
+	* The receipt is `TeamRunReceipt`, not `RunReceipt` — a Team Run has no lead
+	* preset revision/digest to report. Member pool and concurrency limits are not
+	* inputs; sending `planning` is rejected as `invalid_request`.
+	*/
+	team(input) {
+		return this.transport.request("team/run", toTeamWire(input));
+	}
 	/** Read the authoritative run state. */
 	get(runId) {
 		return this.transport.request("run/get", { run_id: runId });
@@ -447,6 +1139,14 @@ var RunClient = class {
 	result(runId) {
 		return this.transport.request("run/result", { run_id: runId });
 	}
+	/**
+	* Read the authoritative plan / step snapshot (W4 / W6, resolves D-W6-1):
+	* titles, statuses, retries with their reason, errors and timings — none of
+	* which the append-only event log carries.
+	*/
+	plan(runId) {
+		return this.transport.request("run/plan", { run_id: runId });
+	}
 	/** Replay persisted events after a cursor. */
 	events(query) {
 		return this.transport.request("run/events", {
@@ -477,6 +1177,26 @@ var RunClient = class {
 			idempotency_key: input.idempotencyKey
 		});
 	}
+	/**
+	* Answer the pending decision of a `waiting_input` attempt.
+	*
+	* The three `expected*Version` tokens are mandatory CAS inputs, normally the
+	* ones projected on the pending `approval.requested` event. The server passes
+	* them straight to the engine's single answer gate, so a stale token is a
+	* `conflict`, never a silent overwrite. There is no `always_allow` here: the
+	* desktop confirmation route's approve-all flag is not part of this protocol.
+	*/
+	answerDecision(input) {
+		return this.transport.request("run/answer-decision", {
+			run_id: input.runId,
+			step_id: input.stepId,
+			attempt_id: input.attemptId,
+			answer: input.answer,
+			expected_execution_version: input.expectedExecutionVersion,
+			expected_step_version: input.expectedStepVersion,
+			expected_attempt_version: input.expectedAttemptVersion
+		});
+	}
 	/** Subscribe to best-effort realtime events for one run. */
 	async follow(runId, options) {
 		const params = { run_id: runId };
@@ -671,6 +1391,17 @@ function toWire(input) {
 		mentions: input.mentions
 	};
 }
+function toTeamWire(input) {
+	return {
+		team_id: input.teamId,
+		team_version: input.teamVersion,
+		goal: input.goal,
+		input: input.input,
+		workspace: input.workspaceId ? { id: input.workspaceId } : void 0,
+		command_id: input.commandId,
+		idempotency_key: input.idempotencyKey
+	};
+}
 //#endregion
 //#region src/skills.ts
 var SkillClient = class {
@@ -686,6 +1417,309 @@ var SkillClient = class {
 	get(skillId) {
 		return this.transport.request("skill/get", { skill_id: skillId });
 	}
+	/**
+	* Every readable file inside a Skill's directory, with a tree digest.
+	*
+	* This is the only way to learn what a Skill actually ships: `get()` returns
+	* a bounded summary of `SKILL.md` and says nothing about the `references/`,
+	* `scripts/`, `templates/` and `assets/` beside it. Check
+	* `capabilities.skill_files` first — a host may wire the catalog without
+	* this face, in which case it answers `unsupported_operation`.
+	*/
+	files(skillId) {
+		return this.transport.request("skill/files", { skill_id: skillId });
+	}
+	/**
+	* One skill file's bytes, over the WebSocket binding.
+	*
+	* The wire carries base64 because JSON has no byte string, so this decodes
+	* back to `Uint8Array` for you. The HTTP route
+	* (`GET /api/app-server/skills/{id}/files/{path}`) returns the raw body
+	* instead, but that is deliberately not on the typed client's JSON
+	* transport — use this method, or `fetch` the route directly if you are on a
+	* host token.
+	*/
+	async readFile(skillId, path) {
+		return decodeBase64((await this.transport.request("skill/file", {
+			skill_id: skillId,
+			path
+		})).content);
+	}
+	/** Same as {@link readFile}, but also returns the server's content type. */
+	readFileWithType(skillId, path) {
+		return this.transport.request("skill/file", {
+			skill_id: skillId,
+			path
+		});
+	}
+};
+/**
+* Decode base64 to bytes.
+*
+* `atob` is used when present (browsers, Bun, Node 16+) and a manual decode
+* otherwise, so the package keeps working on a bare Node without a DOM lib.
+*/
+function decodeBase64(content) {
+	if (typeof atob === "function") {
+		const binary = atob(content);
+		const bytes = new Uint8Array(binary.length);
+		for (let index = 0; index < binary.length; index += 1) bytes[index] = binary.charCodeAt(index);
+		return bytes;
+	}
+	const bufferCtor = globalThis.Buffer;
+	if (bufferCtor) return bufferCtor.from(content, "base64");
+	throw new Error("no base64 decoder available in this environment");
+}
+//#endregion
+//#region src/store.ts
+var StoreError = class extends Error {
+	code;
+	constructor(code, message) {
+		super(message);
+		this.code = code;
+		this.name = "StoreError";
+	}
+};
+const DEFAULT_READY_TIMEOUT_MS = 3e4;
+const DEFAULT_READY_POLL_MS = 400;
+const DEFAULT_READY_POLL_MAX_MS = 4e3;
+/** Every string a `LocalizedText` carries, for haystack building. */
+function localizedValues(text) {
+	if (typeof text === "string") return [text];
+	if (!text || typeof text !== "object") return [];
+	return Object.values(text).filter((value) => typeof value === "string");
+}
+function haystack(item) {
+	return [
+		item.entry_name,
+		item.name,
+		item.id,
+		item.description ?? "",
+		item.version,
+		...localizedValues(item.display_name),
+		...localizedValues(item.display_description),
+		...localizedValues(item.profession),
+		...(item.tags ?? []).flatMap(localizedValues)
+	].join("\n").toLowerCase();
+}
+function abortableDelay(ms, signal) {
+	return new Promise((resolve, reject) => {
+		if (signal?.aborted) {
+			reject(new StoreError("aborted", "the operation was aborted"));
+			return;
+		}
+		const timer = setTimeout(() => {
+			signal?.removeEventListener("abort", onAbort);
+			resolve();
+		}, ms);
+		const onAbort = () => {
+			clearTimeout(timer);
+			reject(new StoreError("aborted", "the operation was aborted"));
+		};
+		signal?.addEventListener("abort", onAbort, { once: true });
+	});
+}
+var StoreClient = class {
+	host;
+	readyTimeoutMs;
+	readyPollMs;
+	readyPollMaxMs;
+	constructor(host, options = {}) {
+		this.host = host;
+		this.readyTimeoutMs = options.readyTimeoutMs ?? DEFAULT_READY_TIMEOUT_MS;
+		this.readyPollMs = options.readyPollMs ?? DEFAULT_READY_POLL_MS;
+		this.readyPollMaxMs = options.readyPollMaxMs ?? DEFAULT_READY_POLL_MAX_MS;
+	}
+	/** Every item across enabled marketplaces, with install state. */
+	async list() {
+		return (await this.host.listStore()).items;
+	}
+	/** Case-insensitive substring search over the fields a user can see. */
+	async search(query, filter = {}) {
+		const needle = query.trim().toLowerCase();
+		return (await this.list()).filter((item) => {
+			if (filter.kind && item.kind !== filter.kind) return false;
+			if (!needle) return true;
+			return haystack(item).includes(needle);
+		});
+	}
+	/** Items currently installed on this host. */
+	async installed() {
+		return (await this.list()).filter((item) => item.installed);
+	}
+	/**
+	* Installed items whose marketplace offers a different version.
+	*
+	* Both conditions matter: `update_available` is computed from the imported
+	* snapshot even when nothing is installed, so filtering on it alone would
+	* report an "update" for an entry the user has never installed.
+	*/
+	async checkUpdates() {
+		return (await this.list()).filter((item) => item.installed && item.update_available);
+	}
+	/**
+	* What a caller can offer for an item's pending update.
+	*
+	* `"none"` means there is nothing to do; `"uninstall_reinstall"` means the
+	* entry is installed at a different version and the only path the wire offers
+	* is to release it and install again (the version-aware re-import then picks
+	* up the current version). `"unknown"` is returned rather than guessing when
+	* the item carries no snapshot to release.
+	*/
+	updateHint(item) {
+		if (!item.installed || !item.update_available) return "none";
+		return item.snapshot_id ? "uninstall_reinstall" : "unknown";
+	}
+	/**
+	* Import (when needed) and install one store item, then wait until it is
+	* usable.
+	*/
+	async install(item, options = {}) {
+		this.assertUsable(item, options.signal);
+		const result = await this.host.installStoreEntry(item.marketplace_id, item.entry_name);
+		const components = result.outcomes ?? [];
+		const outcome = {
+			snapshotId: result.snapshot_id,
+			reused: result.reused,
+			components,
+			ok: result.errors.length === 0 && components.every((component) => component.ok)
+		};
+		if (options.waitForReady === false) return outcome;
+		return this.awaitReady(outcome, options);
+	}
+	/**
+	* Release an item's runtime artifacts and clear its install record.
+	*
+	* The server only clears the record for components it actually released, so a
+	* partial failure leaves `ok: false` with the failing component named — and
+	* the item stays installed, which is what makes a retry meaningful.
+	*/
+	async uninstall(item, options = {}) {
+		const snapshotId = this.requireSnapshot(item);
+		const componentIds = options.componentIds ?? await this.installedComponentIds(snapshotId);
+		if (componentIds.length === 0) return {
+			snapshotId,
+			reused: true,
+			components: [],
+			ok: true
+		};
+		const status = await this.host.uninstallInstall(snapshotId, componentIds);
+		return this.outcomeFromStatus(snapshotId, status, false);
+	}
+	/**
+	* Switch an item's components on or off.
+	*
+	* Idempotent: the server sets the state it is asked for instead of toggling.
+	* A skill reports `skill_disable_flag_only` because the skill corpus has no
+	* enable state — that code is passed through, not swallowed, so a caller can
+	* tell "switched off" from "marked in the catalogue".
+	*/
+	async setEnabled(item, enabled, options = {}) {
+		const snapshotId = this.requireSnapshot(item);
+		const componentIds = options.componentIds ?? await this.installedComponentIds(snapshotId);
+		if (componentIds.length === 0) return {
+			snapshotId,
+			reused: true,
+			components: [],
+			ok: true
+		};
+		const status = enabled ? await this.host.enableInstall(snapshotId, componentIds) : await this.host.disableInstall(snapshotId, componentIds);
+		return this.outcomeFromStatus(snapshotId, status, false);
+	}
+	assertUsable(item, signal) {
+		if (signal?.aborted) throw new StoreError("aborted", "the operation was aborted before it started");
+		if (item.blocked_reason) throw new StoreError("item_blocked", item.blocked_reason);
+	}
+	requireSnapshot(item) {
+		const snapshotId = item.snapshot_id;
+		if (!snapshotId) throw new StoreError("not_installed", `store item ${item.id} has no imported snapshot to act on`);
+		return snapshotId;
+	}
+	async installedComponentIds(snapshotId) {
+		return (await this.host.getInstallStatus(snapshotId)).components.filter((component) => component.state !== "not-installed").map((component) => component.id);
+	}
+	outcomeFromStatus(snapshotId, status, reused) {
+		const components = status.outcomes ?? [];
+		return {
+			snapshotId,
+			reused,
+			components,
+			ok: (status.errors ?? []).length === 0 && components.every((component) => component.ok)
+		};
+	}
+	/**
+	* Poll until every component of the snapshot is usable.
+	*
+	* A timeout does **not** discard the install: the caller gets the successful
+	* install plus `ready: false` and `readyIssue: "ready_timeout"`, so a slow
+	* connector never turns into "the install failed".
+	*/
+	async awaitReady(outcome, options) {
+		const snapshotId = outcome.snapshotId;
+		if (!snapshotId) return outcome;
+		const status = await this.host.getInstallStatus(snapshotId);
+		const connectors = status.components.filter((component) => component.kind === "connector" && component.state !== "not-installed");
+		if (connectors.length > 0) await this.host.enableInstall(snapshotId, connectors.map((component) => component.id));
+		const deadline = Date.now() + (options.timeoutMs ?? this.readyTimeoutMs);
+		let interval = this.readyPollMs;
+		let last = status.components;
+		for (;;) {
+			const blocked = (await Promise.all(last.filter((component) => component.state !== "not-installed").map(async (component) => ({
+				component,
+				verdict: await this.readiness(component)
+			})))).find((entry) => !entry.verdict.ready);
+			if (!blocked) return {
+				...outcome,
+				ready: true
+			};
+			if (!blocked.verdict.ready && blocked.verdict.terminal) return {
+				...outcome,
+				ready: false,
+				readyIssue: blocked.verdict.terminal,
+				readyComponentId: blocked.component.id
+			};
+			if (Date.now() >= deadline) return {
+				...outcome,
+				ready: false,
+				readyIssue: "ready_timeout",
+				readyComponentId: blocked.component.id
+			};
+			await abortableDelay(interval, options.signal);
+			interval = Math.min(interval * 2, this.readyPollMaxMs);
+			last = (await this.host.getInstallStatus(snapshotId)).components;
+		}
+	}
+	/**
+	* Is this one component usable yet?
+	*
+	* Each kind answers with the narrowest read the protocol already offers. An
+	* unknown kind is reported ready rather than blocking: this layer cannot judge
+	* a component it does not understand, and a false timeout on a future kind
+	* would be worse than passing it through.
+	*/
+	async readiness(component) {
+		try {
+			switch (component.kind) {
+				case "skill": return (await this.host.skills.list()).some((skill) => skill.name === component.name) ? { ready: true } : { ready: false };
+				case "agent": return (await this.host.agents.get(component.id)).preset_id ? { ready: true } : { ready: false };
+				case "team":
+					await this.host.teams.get(component.id);
+					return { ready: true };
+				case "connector": {
+					if ((await this.host.connectors.test(component.id)).success) return { ready: true };
+					const status = await this.host.connectors.status(component.id);
+					if (status.status === "authorization_required" || status.status === "reauthorization_required") return {
+						ready: false,
+						terminal: "authorization_required"
+					};
+					return { ready: false };
+				}
+				default: return { ready: true };
+			}
+		} catch {
+			return { ready: false };
+		}
+	}
 };
 //#endregion
 //#region src/teams.ts
@@ -775,6 +1809,12 @@ var AppServerClient = class {
 	teams;
 	/** Public model directory (`models/list`, REQ-PAR-05b). */
 	models;
+	/**
+	* Agent Store lifecycle as one state machine: search → install (wait until
+	* usable) → enable/disable → uninstall. Composes the flat methods below; it
+	* adds no wire surface.
+	*/
+	store;
 	clientInfo;
 	capabilities;
 	initializeResult = null;
@@ -793,6 +1833,7 @@ var AppServerClient = class {
 		this.agents = new AgentClient(this.transport);
 		this.teams = new TeamClient(this.transport);
 		this.models = new ModelClient(this.transport);
+		this.store = new StoreClient(this, options.store);
 		this.bridgeNotifications();
 	}
 	/**
@@ -862,7 +1903,14 @@ var AppServerClient = class {
 	async getInstallStatus(snapshotId) {
 		return this.transport.request("install/status", { snapshot_id: snapshotId });
 	}
-	/** Disable installed components (runtime artifacts stay). */
+	/**
+	* Disable installed components.
+	*
+	* The runtime state moves with the flag — a connector's MCP server is switched
+	* off, an expert's Preset is disabled — while the artifacts stay on disk. A
+	* skill is the documented exception: the corpus has no enable state, so it
+	* reports `skill_disable_flag_only` and the flag stays a catalogue marker.
+	*/
 	async disableInstall(snapshotId, componentIds) {
 		return this.transport.request("install/disable", {
 			snapshot_id: snapshotId,
@@ -1322,4 +2370,4 @@ async function withRetry(operation, options = {}) {
 	throw lastError;
 }
 //#endregion
-export { AgentClient, AgentRunHandle, AppServerClient, ConnectorClient, ConversationClient, ConversationHandle, ConversationSubscription, EventSubscription, ModelClient, RunClient, SkillClient, TeamClient, WebSocketTransport, WorkspaceClient, aggregateTurnResult, conversationMessages, isLoopbackUrl, launchRun, withRetry };
+export { AgentClient, AgentRunHandle, AppServerClient, ConnectorClient, ConversationClient, ConversationHandle, ConversationSubscription, EventSubscription, HttpTransport, ModelClient, RunClient, SkillClient, StoreClient, StoreError, TeamClient, WebSocketTransport, WorkspaceClient, aggregateTurnResult, appServerErrorFromWire, conversationMessages, httpRouteTable, isLoopbackUrl, launchRun, withRetry };