@flowy-agent-store/client 0.1.0-beta.2

package/dist/index.cjs

@@ -0,0 +1,1216 @@
+Object.defineProperty(exports, Symbol.toStringTag, { value: "Module" });
+let _flowy_agent_store_protocol = require("@flowy-agent-store/protocol");
+//#region src/transport.ts
+/**
+* JSON-RPC 2.0 transport over WebSocket for the App Server protocol.
+*
+* Works in browsers and in Node 22+/Bun (global `WebSocket`). The browser
+* WebSocket API cannot set custom headers, so an optional bearer token is
+* appended as a query parameter (`?token=...`) when provided; HTTP calls in
+* the SDK use the `Authorization` header instead.
+*/
+/**
+* True for loopback-only URLs (`127.0.0.0/8`, `::1`, `localhost`).
+* SDK spawn contract (docs/agent-store/12-sdk-packaging.md P0-4): an SDK
+* must only speak the local-trusted mode over loopback; anything else is
+* rejected before connecting.
+*/
+function isLoopbackUrl(raw) {
+	try {
+		const host = new URL(raw).hostname.toLowerCase();
+		if (host === "localhost" || host === "::1") return true;
+		if (host.startsWith("[") && host.endsWith("]")) return host === "[::1]";
+		const parts = host.split(".").map(Number);
+		return parts.length === 4 && parts[0] === 127 && parts.every((n) => Number.isInteger(n) && n >= 0 && n <= 255);
+	} catch {
+		return false;
+	}
+}
+var WebSocketTransport = class {
+	socket = null;
+	nextId = 1;
+	pending = /* @__PURE__ */ new Map();
+	listeners = /* @__PURE__ */ new Set();
+	connectResolvers = [];
+	connectRejecters = [];
+	closedByCaller = false;
+	requestTimeoutMs;
+	url;
+	token;
+	constructor(url, options = {}) {
+		this.url = url;
+		this.token = options.token;
+		this.requestTimeoutMs = options.requestTimeoutMs ?? 3e4;
+	}
+	get connected() {
+		return this.socket?.readyState === WebSocket.OPEN;
+	}
+	connect() {
+		if (this.connected) return Promise.resolve();
+		this.closedByCaller = false;
+		const target = this.token ? `${this.url}${this.url.includes("?") ? "&" : "?"}token=${encodeURIComponent(this.token)}` : this.url;
+		const socket = new WebSocket(target);
+		this.socket = socket;
+		socket.onopen = () => {
+			for (const resolve of this.connectResolvers.splice(0)) resolve();
+		};
+		socket.onmessage = (event) => {
+			this.handleMessage(event.data);
+		};
+		socket.onclose = (event) => {
+			this.failAllPending(new _flowy_agent_store_protocol.TransportError("close", `app-server connection closed (code ${event.code})`, { retryable: !this.closedByCaller }));
+			this.socket = null;
+			for (const reject of this.connectRejecters.splice(0)) reject(new _flowy_agent_store_protocol.TransportError("connect", "app-server connection closed before opening"));
+		};
+		socket.onerror = () => {
+			this.socket?.close();
+		};
+		return new Promise((resolve, reject) => {
+			this.connectResolvers.push(resolve);
+			this.connectRejecters.push(reject);
+		});
+	}
+	request(method, params) {
+		const socket = this.requireSocket();
+		const id = this.nextId++;
+		const payload = {
+			jsonrpc: "2.0",
+			id,
+			method,
+			params
+		};
+		return new Promise((resolve, reject) => {
+			const timer = setTimeout(() => {
+				this.pending.delete(id);
+				reject(new _flowy_agent_store_protocol.RequestTimeoutError(method, this.requestTimeoutMs));
+			}, this.requestTimeoutMs);
+			this.pending.set(id, {
+				resolve,
+				reject,
+				timer,
+				method
+			});
+			try {
+				socket.send(JSON.stringify(payload));
+			} catch (error) {
+				clearTimeout(timer);
+				this.pending.delete(id);
+				reject(new _flowy_agent_store_protocol.TransportError("send", `failed to send ${method}`, { cause: error }));
+			}
+		});
+	}
+	notify(method, params) {
+		const socket = this.requireSocket();
+		const payload = {
+			jsonrpc: "2.0",
+			method,
+			params
+		};
+		try {
+			socket.send(JSON.stringify(payload));
+		} catch (error) {
+			throw new _flowy_agent_store_protocol.TransportError("send", `failed to send notification ${method}`, { cause: error });
+		}
+	}
+	onNotification(listener) {
+		this.listeners.add(listener);
+		return () => {
+			this.listeners.delete(listener);
+		};
+	}
+	close() {
+		this.closedByCaller = true;
+		this.socket?.close();
+		this.socket = null;
+		for (const [, pending] of this.pending) {
+			clearTimeout(pending.timer);
+			pending.reject(new _flowy_agent_store_protocol.TransportError("close", "app-server transport closed by caller"));
+		}
+		this.pending.clear();
+	}
+	requireSocket() {
+		if (!this.socket || this.socket.readyState !== WebSocket.OPEN) throw new _flowy_agent_store_protocol.TransportError("send", "app-server transport is not connected", { retryable: true });
+		return this.socket;
+	}
+	handleMessage(raw) {
+		let message;
+		try {
+			message = JSON.parse(String(raw));
+		} catch {
+			return;
+		}
+		if ("id" in message && message.id !== void 0) {
+			const response = message;
+			const pending = response.id === null ? void 0 : this.pending.get(Number(response.id));
+			if (!pending) return;
+			clearTimeout(pending.timer);
+			this.pending.delete(Number(response.id));
+			if (response.error) pending.reject(new _flowy_agent_store_protocol.AppServerError(response.error));
+			else pending.resolve(response.result);
+			return;
+		}
+		if ("method" in message) {
+			const notification = message;
+			for (const listener of [...this.listeners]) try {
+				listener(notification);
+			} catch {}
+			return;
+		}
+	}
+	failAllPending(error) {
+		for (const [, pending] of this.pending) {
+			clearTimeout(pending.timer);
+			pending.reject(error);
+		}
+		this.pending.clear();
+	}
+};
+//#endregion
+//#region src/agents.ts
+var AgentClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/** List Agent Store AgentDefinitions (public summaries only). */
+	list() {
+		return this.transport.request("agent/list", {});
+	}
+	/** Fetch one AgentDefinition; raw prompts never cross the wire. */
+	get(agentId) {
+		return this.transport.request("agent/get", { agent_id: agentId });
+	}
+};
+//#endregion
+//#region src/conversations.ts
+var ConversationClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	create(input) {
+		const model = input.model ? {
+			provider_id: input.model.provider_id,
+			model: input.model.model
+		} : void 0;
+		return this.transport.request("conversation/create", {
+			name: input.name,
+			model,
+			workspace: input.workspaceId ? { id: input.workspaceId } : void 0,
+			reasoning_effort: input.reasoningEffort || void 0
+		});
+	}
+	update(conversationId, input) {
+		return this.transport.request("conversation/update", {
+			conversation_id: conversationId,
+			name: input.name,
+			model: input.model ? {
+				provider_id: input.model.provider_id,
+				model: input.model.model
+			} : void 0,
+			reasoning_effort: input.reasoningEffort || void 0
+		});
+	}
+	modelOptions() {
+		return this.transport.request("conversation/model-options", {});
+	}
+	list(limit = 100) {
+		return this.transport.request("conversation/list", { limit });
+	}
+	get(conversationId) {
+		return this.transport.request("conversation/get", { conversation_id: conversationId });
+	}
+	messages(query) {
+		return this.transport.request("conversation/messages", {
+			conversation_id: query.conversationId,
+			page: query.page,
+			page_size: query.pageSize,
+			cursor: query.cursor
+		});
+	}
+	send(conversationId, content, idempotencyKey) {
+		return this.transport.request("conversation/send", {
+			conversation_id: conversationId,
+			content,
+			idempotency_key: idempotencyKey
+		});
+	}
+	cancel(conversationId) {
+		return this.transport.request("conversation/cancel", { conversation_id: conversationId });
+	}
+	delete(conversationId) {
+		return this.transport.request("conversation/delete", { conversation_id: conversationId });
+	}
+	async follow(conversationId) {
+		await this.transport.request("conversation/subscribe", { conversation_id: conversationId });
+		return new ConversationSubscription(this.transport, conversationId);
+	}
+};
+var ConversationSubscription = class {
+	transport;
+	conversationId;
+	events = /* @__PURE__ */ new Set();
+	resyncs = /* @__PURE__ */ new Set();
+	closed = false;
+	lastSeenSequence = 0;
+	removeListener;
+	constructor(transport, conversationId) {
+		this.transport = transport;
+		this.conversationId = conversationId;
+		this.removeListener = transport.onNotification((notification) => this.dispatch(notification));
+	}
+	get lastSequence() {
+		return this.lastSeenSequence;
+	}
+	onEvent(listener) {
+		this.events.add(listener);
+		return () => this.events.delete(listener);
+	}
+	onResync(listener) {
+		this.resyncs.add(listener);
+		return () => this.resyncs.delete(listener);
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.removeListener?.();
+		this.removeListener = null;
+		this.events.clear();
+		this.resyncs.clear();
+		try {
+			await this.transport.request("conversation/unsubscribe", { conversation_id: this.conversationId });
+		} catch {}
+	}
+	dispatch(notification) {
+		if (notification.method === "conversation/event") {
+			const event = notification.params;
+			if (event.conversation_id !== this.conversationId || event.sequence <= this.lastSeenSequence) return;
+			this.lastSeenSequence = event.sequence;
+			for (const listener of [...this.events]) try {
+				listener(event);
+			} catch {}
+			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 {}
+		}
+	}
+};
+//#endregion
+//#region src/connectors.ts
+var ConnectorClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/** List the Agent Store Connector catalog (public summaries only). */
+	list() {
+		return this.transport.request("connector/list", {});
+	}
+	/** Fetch one Connector detail: namespaced tools + auth state. */
+	get(connectorId) {
+		return this.transport.request("connector/get", { connector_id: connectorId });
+	}
+	/** Combined auth × probe status. `connected` only when auth is ready AND the last probe succeeded. */
+	status(connectorId) {
+		return this.transport.request("connector/status", { connector_id: connectorId });
+	}
+	/** Run a connection probe; the server persists the result. */
+	test(connectorId) {
+		return this.transport.request("connector/test", { connector_id: connectorId });
+	}
+	/** Check the current OAuth state for a connector. */
+	authStatus(connectorId) {
+		return this.transport.request("connector/auth/status", { connector_id: connectorId });
+	}
+	/**
+	* Kick off the OAuth browser flow on the trusted host. Returns the start
+	* acknowledgement immediately; poll `authStatus` until `authenticated`.
+	*/
+	authStart(connectorId) {
+		return this.transport.request("connector/auth/start", { connector_id: connectorId });
+	}
+	/** Revoke the OAuth token for a connector. */
+	logout(connectorId) {
+		return this.transport.request("connector/auth/logout", { connector_id: connectorId }).then(() => void 0);
+	}
+};
+//#endregion
+//#region src/runs.ts
+/**
+* Run client: agent/run, run/get, run/result, run/events, run/cancel plus the
+* realtime `follow` subscription over the WebSocket transport.
+*/
+var RunClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/** Start an Agent run and return its asynchronous receipt. */
+	agent(input) {
+		return this.transport.request("agent/run", toWire(input));
+	}
+	/** Read the authoritative run state. */
+	get(runId) {
+		return this.transport.request("run/get", { run_id: runId });
+	}
+	/** Read the terminal result (fails until the run reaches a terminal state). */
+	result(runId) {
+		return this.transport.request("run/result", { run_id: runId });
+	}
+	/** Replay persisted events after a cursor. */
+	events(query) {
+		return this.transport.request("run/events", {
+			run_id: query.runId,
+			after_sequence: query.afterSequence,
+			limit: query.limit
+		});
+	}
+	/** Request cancellation; the terminal state is confirmed by events/run/get. */
+	cancel(input) {
+		return this.transport.request("run/cancel", {
+			run_id: input.runId,
+			expected_version: input.expectedVersion,
+			command_id: input.commandId,
+			idempotency_key: input.idempotencyKey
+		});
+	}
+	/**
+	* Inject steering text into the currently active step of a running Agent
+	* (runtime durable conversation effect; server resolves the opaque step).
+	*/
+	steer(input) {
+		return this.transport.request("run/steer", {
+			run_id: input.runId,
+			text: input.text,
+			expected_version: input.expectedVersion,
+			command_id: input.commandId,
+			idempotency_key: input.idempotencyKey
+		});
+	}
+	/** Subscribe to best-effort realtime events for one run. */
+	async follow(runId, options) {
+		const params = { run_id: runId };
+		await this.transport.request("run/subscribe", params);
+		const subscription = new EventSubscription(this.transport, runId, (afterSequence) => this.events({
+			runId,
+			afterSequence
+		}), options);
+		if (options?.catchUp !== false) await subscription.catchUp().catch(() => void 0);
+		return subscription;
+	}
+};
+/** Upper bound for the silent catch-up page (cursor baseline, not delivery). */
+const CATCH_UP_LIMIT = 500;
+/** Prune the dedup set past this size (sequences are per-run monotonic). */
+const SEEN_SET_PRUNE_AT = 2e3;
+const SEEN_SET_KEEP_BELOW_MAX = 500;
+var EventSubscription = class {
+	transport;
+	runId;
+	fetchAfter;
+	eventListeners = /* @__PURE__ */ new Set();
+	resyncListeners = /* @__PURE__ */ new Set();
+	errorListeners = /* @__PURE__ */ new Set();
+	closed = false;
+	unsubscribeNotification = null;
+	lastSeenSequence = 0;
+	seenSequences = /* @__PURE__ */ new Set();
+	resyncInFlight = null;
+	autoResync;
+	constructor(transport, runId, fetchAfter, options) {
+		this.transport = transport;
+		this.runId = runId;
+		this.fetchAfter = fetchAfter;
+		this.autoResync = options?.autoResync !== false;
+		this.unsubscribeNotification = transport.onNotification((notification) => {
+			this.dispatch(notification);
+		});
+	}
+	onEvent(listener) {
+		this.eventListeners.add(listener);
+		return () => {
+			this.eventListeners.delete(listener);
+		};
+	}
+	onResync(listener) {
+		this.resyncListeners.add(listener);
+		return () => {
+			this.resyncListeners.delete(listener);
+		};
+	}
+	onError(listener) {
+		this.errorListeners.add(listener);
+		return () => {
+			this.errorListeners.delete(listener);
+		};
+	}
+	get lastSequence() {
+		return this.lastSeenSequence;
+	}
+	async close() {
+		if (this.closed) return;
+		this.closed = true;
+		this.unsubscribeNotification?.();
+		this.eventListeners.clear();
+		this.resyncListeners.clear();
+		this.errorListeners.clear();
+		try {
+			await this.transport.request("run/unsubscribe", { run_id: this.runId });
+		} catch {}
+	}
+	dispatch(notification) {
+		if (this.closed) return;
+		if (notification.method === "event") {
+			const event = notification.params;
+			if (event.run_id !== this.runId) return;
+			if (!Number.isFinite(event.sequence) || this.seenSequences.has(event.sequence)) return;
+			this.markSeen(event.sequence);
+			this.emitEvent(event);
+			return;
+		}
+		if (notification.method === "run/resync-required") {
+			const params = notification.params;
+			if (params.run_ids.length > 0 && !params.run_ids.includes(this.runId)) return;
+			for (const listener of [...this.resyncListeners]) try {
+				listener(params);
+			} catch {}
+			if (this.autoResync && this.fetchAfter) this.resync().catch((error) => this.emitError(error));
+			return;
+		}
+	}
+	/**
+	* Silent cursor baseline: mark already-persisted events seen WITHOUT
+	* dispatching, so the first resync never replays history as "new".
+	* For explicit history use `RunClient.events({ afterSequence: 0 })`.
+	*/
+	async catchUp() {
+		if (this.closed || !this.fetchAfter) return;
+		const history = await this.fetchAfter(0);
+		const page = Array.isArray(history) ? history.slice(0, CATCH_UP_LIMIT) : [];
+		for (const event of page) if (event.run_id === this.runId && Number.isFinite(event.sequence)) this.markSeen(event.sequence);
+	}
+	/**
+	*追平 missed events via `run/events` after the cursor. Returned (and
+	* dispatched) in sequence order, deduplicated against live delivery.
+	* Concurrent calls share one flight.
+	*/
+	async resync() {
+		if (this.closed) return [];
+		if (this.resyncInFlight) return this.resyncInFlight;
+		if (!this.fetchAfter) return [];
+		const fetchAfter = this.fetchAfter;
+		const task = (async () => {
+			const missed = await fetchAfter(this.lastSeenSequence);
+			const fresh = (Array.isArray(missed) ? [...missed] : []).filter((event) => event.run_id === this.runId && Number.isFinite(event.sequence)).sort((left, right) => left.sequence - right.sequence).filter((event) => {
+				if (this.seenSequences.has(event.sequence)) return false;
+				this.markSeen(event.sequence);
+				return true;
+			});
+			for (const event of fresh) this.emitEvent(event);
+			return fresh;
+		})();
+		this.resyncInFlight = task;
+		try {
+			return await task;
+		} finally {
+			if (this.resyncInFlight === task) this.resyncInFlight = null;
+		}
+	}
+	markSeen(sequence) {
+		this.seenSequences.add(sequence);
+		if (sequence > this.lastSeenSequence) this.lastSeenSequence = sequence;
+		if (this.seenSequences.size > SEEN_SET_PRUNE_AT) {
+			const floor = this.lastSeenSequence - SEEN_SET_KEEP_BELOW_MAX;
+			for (const seen of this.seenSequences) if (seen < floor) this.seenSequences.delete(seen);
+		}
+	}
+	emitEvent(event) {
+		for (const listener of [...this.eventListeners]) try {
+			listener(event);
+		} catch {}
+	}
+	emitError(error) {
+		for (const listener of [...this.errorListeners]) try {
+			listener(error);
+		} catch {}
+	}
+	/** Forward transport-level errors into subscription error listeners. */
+	deliverError(error) {
+		if (error instanceof _flowy_agent_store_protocol.TransportError) for (const listener of [...this.errorListeners]) try {
+			listener(error);
+		} catch {}
+	}
+};
+function toWire(input) {
+	return {
+		agent_id: input.agentId,
+		agent_version: input.agentVersion,
+		goal: input.goal,
+		input: input.input,
+		workspace: input.workspaceId ? { id: input.workspaceId } : void 0,
+		steps: input.steps,
+		command_id: input.commandId,
+		idempotency_key: input.idempotencyKey,
+		mentions: input.mentions
+	};
+}
+//#endregion
+//#region src/skills.ts
+var SkillClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/** List the Agent Store Skill catalog (public summaries only). */
+	list() {
+		return this.transport.request("skill/list", {});
+	}
+	/** Fetch one Skill detail; instructions are a bounded public summary. */
+	get(skillId) {
+		return this.transport.request("skill/get", { skill_id: skillId });
+	}
+};
+//#endregion
+//#region src/teams.ts
+var TeamClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/** List AgentTeamDefinitions (fixed-member rosters). */
+	list() {
+		return this.transport.request("team/list", {});
+	}
+	/** Fetch one TeamDefinition; planning-context bodies are never returned. */
+	get(teamId) {
+		return this.transport.request("team/get", { team_id: teamId });
+	}
+};
+//#endregion
+//#region src/models.ts
+var ModelClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	/** Enabled providers' models; `is_default` marks the `agent/run` fallback. */
+	async list() {
+		return (await this.transport.request("models/list", {})).items;
+	}
+};
+//#endregion
+//#region src/workspaces.ts
+var WorkspaceClient = class {
+	transport;
+	constructor(transport) {
+		this.transport = transport;
+	}
+	list() {
+		return this.transport.request("workspace/list", {});
+	}
+	/**
+	* Validate + register (idempotently per canonical root) an absolute local
+	* directory chosen by the owner. The server canonicalizes the path and
+	* rejects links/reparse points; the returned view only carries the
+	* canonical path back to this same authenticated connection.
+	*/
+	create(path) {
+		return this.transport.request("workspace/create", { path });
+	}
+	/**
+	* Revoke (soft-delete) an owner's active workspace. Its conversations are
+	* kept and their `workspace_id` reference is preserved, so re-registering
+	* the same path re-activates the same workspace and those conversations
+	* become visible again.
+	*/
+	revoke(workspaceId) {
+		return this.transport.request("workspace/revoke", { workspace_id: workspaceId });
+	}
+};
+//#endregion
+//#region src/client.ts
+/**
+* Typed App Server client (`@flowy-agent-store/client`).
+*
+* Transport-agnostic: all business methods go through the injected
+* `Transport` (07 §2.3). Web-only helpers (asset URLs, `/api/fs/browse`,
+* one-shot HTTP registration) live in the host app, not here.
+*
+* Connection lifecycle: transport connect → `initialize` → protocol version
+* check → `initialized` notification → ready. Business methods require a
+* ready client; the server rejects them with `not_initialized` otherwise.
+*/
+var AppServerClient = class {
+	transport;
+	/** Legacy preset/execution workflow client. */
+	runs;
+	/** Persistent presetless Nomi chat client. */
+	conversations;
+	/** Owner-scoped workspace registry client (user-chosen paths). */
+	workspaces;
+	/** Agent Store Skill catalog client (`skill/list`, `skill/get`). */
+	skills;
+	/** Agent Store Connector catalog/status/probe/OAuth client. */
+	connectors;
+	/** Agent Store AgentDefinition catalog client (`agent/list`, `agent/get`). */
+	agents;
+	/** Agent Store Team catalog client (`team/list`, `team/get`). */
+	teams;
+	/** Public model directory (`models/list`, REQ-PAR-05b). */
+	models;
+	clientInfo;
+	capabilities;
+	initializeResult = null;
+	notificationListeners = /* @__PURE__ */ new Set();
+	constructor(options) {
+		this.clientInfo = options.client;
+		this.capabilities = options.capabilities;
+		this.transport = options.transport;
+		this.runs = new RunClient(this.transport);
+		this.conversations = new ConversationClient(this.transport);
+		this.workspaces = new WorkspaceClient(this.transport);
+		this.skills = new SkillClient(this.transport);
+		this.connectors = new ConnectorClient(this.transport);
+		this.agents = new AgentClient(this.transport);
+		this.teams = new TeamClient(this.transport);
+		this.models = new ModelClient(this.transport);
+		this.transport.onNotification((notification) => {
+			for (const listener of [...this.notificationListeners]) try {
+				listener(notification);
+			} catch {}
+		});
+	}
+	get ready() {
+		return this.initializeResult !== null;
+	}
+	get initializeInfo() {
+		return this.initializeResult;
+	}
+	/** Connect and perform the initialize/initialized handshake. */
+	async connect() {
+		await this.transport.connect();
+		const request = {
+			protocol_version: _flowy_agent_store_protocol.APP_SERVER_PROTOCOL_VERSION,
+			client: this.clientInfo,
+			capabilities: this.capabilities
+		};
+		const result = await this.transport.request("initialize", request);
+		if (result.protocol_version !== _flowy_agent_store_protocol.APP_SERVER_PROTOCOL_VERSION) throw new _flowy_agent_store_protocol.ProtocolError("version_mismatch", `server protocol version ${result.protocol_version} is not supported (client ${_flowy_agent_store_protocol.APP_SERVER_PROTOCOL_VERSION})`);
+		this.transport.notify("initialized", {});
+		this.initializeResult = result;
+		return result;
+	}
+	onNotification(listener) {
+		this.notificationListeners.add(listener);
+		return () => {
+			this.notificationListeners.delete(listener);
+		};
+	}
+	/** Close the transport; the server revokes the connection immediately. */
+	close() {
+		this.transport.close();
+		this.initializeResult = null;
+		this.notificationListeners.clear();
+	}
+	/** Import a local CodeBuddy/WorkBuddy source directory (roadmap Phase 1). */
+	async runImport(input) {
+		return this.transport.request("import/run", input);
+	}
+	async listImports() {
+		return this.transport.request("import/list", {});
+	}
+	/** One immutable snapshot with its standardized components. */
+	async getImport(snapshotId) {
+		return this.transport.request("import/get", { snapshot_id: snapshotId });
+	}
+	/** Install a snapshot into the runtime (roadmap Phase 2). */
+	async runInstall(input) {
+		return this.transport.request("install/run", input);
+	}
+	/** Per-component installation state of a snapshot. */
+	async getInstallStatus(snapshotId) {
+		return this.transport.request("install/status", { snapshot_id: snapshotId });
+	}
+	/** Disable installed components (runtime artifacts stay). */
+	async disableInstall(snapshotId, componentIds) {
+		return this.transport.request("install/disable", {
+			snapshot_id: snapshotId,
+			component_ids: componentIds
+		});
+	}
+	/** Re-enable previously disabled components. */
+	async enableInstall(snapshotId, componentIds) {
+		return this.transport.request("install/enable", {
+			snapshot_id: snapshotId,
+			component_ids: componentIds
+		});
+	}
+	/** Uninstall: remove runtime artifacts and clear the state (snapshot kept). */
+	async uninstallInstall(snapshotId, componentIds) {
+		return this.transport.request("install/uninstall", {
+			snapshot_id: snapshotId,
+			component_ids: componentIds
+		});
+	}
+	/** Register a marketplace source on the trusted host. */
+	async addMarketplace(input) {
+		return this.transport.request("market/add", input);
+	}
+	/** All active marketplaces. */
+	async listMarketplaces() {
+		return this.transport.request("market/list", {});
+	}
+	/** One marketplace with its discovered entries. */
+	async getMarketplace(marketplaceId) {
+		return this.transport.request("market/get", { marketplace_id: marketplaceId });
+	}
+	/** Remove a marketplace (`cascade` uninstalls snapshots installed from it). */
+	async removeMarketplace(marketplaceId, cascade) {
+		return this.transport.request("market/remove", {
+			marketplace_id: marketplaceId,
+			cascade
+		});
+	}
+	/** Toggle auto-update for a marketplace. */
+	async setMarketplaceAutoUpdate(marketplaceId, enabled) {
+		return this.transport.request("market/auto-update", {
+			marketplace_id: marketplaceId,
+			enabled
+		});
+	}
+	/** Re-fetch a marketplace source and rebuild entries when the revision changed. */
+	async refreshMarketplace(marketplaceId) {
+		return this.transport.request("market/refresh", { marketplace_id: marketplaceId });
+	}
+	/** Import one discovered marketplace entry (provenance linked). */
+	async importMarketplaceEntry(marketplaceId, entryName) {
+		return this.transport.request("market/entry-import", {
+			marketplace_id: marketplaceId,
+			entry_name: entryName
+		});
+	}
+	/** All store items across enabled marketplaces (display + install state). */
+	async listStore() {
+		return this.transport.request("store/list", {});
+	}
+	/** One-click install: import (when missing) + register in one call. */
+	async installStoreEntry(marketplaceId, entryName) {
+		return this.transport.request("store/install-entry", {
+			marketplace_id: marketplaceId,
+			entry_name: entryName
+		});
+	}
+};
+//#endregion
+//#region src/conversation-handle.ts
+/** How long `send` waits for a terminal event before returning a still-open turn. */
+const TURN_TIMEOUT_MS = 6e5;
+function stringValue(value) {
+	return typeof value === "string" ? value : void 0;
+}
+/** Aggregate assistant text from `message.delta` events (fallback path). */
+function aggregateAssistantText(events) {
+	const byId = /* @__PURE__ */ new Map();
+	for (const event of events) {
+		if (event.event_type !== "message.delta") continue;
+		if (typeof event.payload["content"] !== "string") continue;
+		const id = stringValue(event.payload["message_id"]) ?? "";
+		if (!id) continue;
+		byId.set(id, (byId.get(id) ?? "") + event.payload["content"]);
+	}
+	let last = null;
+	for (const value of byId.values()) if (value) last = value;
+	return last;
+}
+function lastUsage(events) {
+	for (let index = events.length - 1; index >= 0; index -= 1) if (events[index].event_type === "context.usage") {
+		const value = events[index].payload["context_usage"];
+		return value && typeof value === "object" ? value : null;
+	}
+}
+var ConversationHandle = class ConversationHandle {
+	conversationId;
+	conversations;
+	subscription;
+	constructor(conversations, conversationId, subscription) {
+		this.conversations = conversations;
+		this.conversationId = conversationId;
+		this.subscription = subscription;
+	}
+	/** Create a new conversation and subscribe to its live event stream. */
+	static async open(conversations, input) {
+		const view = await conversations.create(input ?? {});
+		const subscription = await conversations.follow(view.conversation_id);
+		return new ConversationHandle(conversations, view.conversation_id, subscription);
+	}
+	/** Attach to an existing conversation (by id) and subscribe. */
+	static async attach(conversations, conversationId) {
+		const subscription = await conversations.follow(conversationId);
+		return new ConversationHandle(conversations, conversationId, subscription);
+	}
+	/** Register a listener for every conversation event (returns an unsubscribe). */
+	onEvent(listener) {
+		return this.subscription.onEvent(listener);
+	}
+	/**
+	* Send a message (a "turn") and await its terminal state. The event collector
+	* is installed before the send so streaming deltas / usage are captured even
+	* when they arrive before the send acknowledgment is parsed.
+	*/
+	async send(content, options = {}) {
+		const collected = [];
+		let terminalResolve;
+		let terminal = false;
+		const terminalPromise = new Promise((resolve) => {
+			terminalResolve = resolve;
+		});
+		const markTerminal = () => {
+			if (terminal) return;
+			terminal = true;
+			terminalResolve();
+		};
+		const off = this.subscription.onEvent((event) => {
+			collected.push(event);
+			if (event.event_type === "turn.status" && stringValue(event.payload["status"]) === "completed") markTerminal();
+			else if (event.event_type === "message.error") markTerminal();
+		});
+		let receipt;
+		try {
+			receipt = await this.conversations.send(this.conversationId, content, options.idempotencyKey ?? crypto.randomUUID());
+			if (!receipt.completed && !terminal) await Promise.race([terminalPromise, new Promise((resolve) => setTimeout(resolve, TURN_TIMEOUT_MS))]);
+		} finally {
+			off();
+		}
+		return {
+			conversation_id: this.conversationId,
+			content,
+			message_id: receipt.message_id,
+			turn_id: receipt.turn_id,
+			accepted: receipt.accepted,
+			completed: receipt.completed || terminal,
+			events: collected,
+			assistant_text: receipt.result_text ?? aggregateAssistantText(collected),
+			isError: Boolean(receipt.result_error) || collected.some((event) => event.event_type === "message.error"),
+			result_error: receipt.result_error ?? null,
+			result_error_code: receipt.result_error_code ?? null,
+			usage: lastUsage(collected)
+		};
+	}
+	/** Cancel the in-flight turn (idempotent; erases the current transcript row). */
+	cancel() {
+		return this.conversations.cancel(this.conversationId).then(() => void 0);
+	}
+	/** Fetch the transcript (paginated). */
+	messages(query) {
+		return this.conversations.messages({
+			conversationId: this.conversationId,
+			...query
+		});
+	}
+	/** Unsubscribe and release the handle. */
+	close() {
+		return this.subscription.close();
+	}
+};
+/** Convenience: simple transcript snapshot (all roles, newest last). */
+function conversationMessages(page) {
+	return page.items;
+}
+//#endregion
+//#region src/turn-result.ts
+const KIND_BY_EVENT = {
+	"run.plan_changed": "plan",
+	"task.updated": "task",
+	"attempt.updated": "attempt",
+	"run.status_changed": "status",
+	"approval.requested": "approval",
+	"approval.responded": "approval"
+};
+function asRecord(payload) {
+	return payload && typeof payload === "object" ? payload : {};
+}
+function pickString(source, key) {
+	const value = source[key];
+	return typeof value === "string" ? value : void 0;
+}
+function toItem(event) {
+	const payload = asRecord(event.payload);
+	return {
+		sequence: event.sequence,
+		event_type: event.event_type,
+		kind: KIND_BY_EVENT[event.event_type] ?? "other",
+		ref_id: pickString(payload, "attempt_id") ?? pickString(payload, "step_id"),
+		status: pickString(payload, "status"),
+		reason: pickString(payload, "reason") ?? pickString(payload, "change")
+	};
+}
+function extractUsage(events) {
+	for (const event of events) {
+		const payload = asRecord(event.payload);
+		const candidate = asRecord(payload["usage"] ?? payload["context_usage"]);
+		const input = candidate["input_tokens"] ?? candidate["inputTokens"];
+		const output = candidate["output_tokens"] ?? candidate["outputTokens"];
+		const total = candidate["total_tokens"] ?? candidate["totalTokens"];
+		if (typeof input === "number" || typeof output === "number" || typeof total === "number") return {
+			...typeof input === "number" ? { input_tokens: input } : {},
+			...typeof output === "number" ? { output_tokens: output } : {},
+			...typeof total === "number" ? { total_tokens: total } : {}
+		};
+	}
+}
+/** Build the terminal turn result from the authoritative view + event stream. */
+function aggregateTurnResult(view, events) {
+	const ordered = [...events].sort((left, right) => left.sequence - right.sequence);
+	const usage = extractUsage(ordered);
+	return {
+		run_id: view.run_id,
+		status: view.status,
+		version: view.version,
+		final_response: view.summary ?? null,
+		output_files: view.output_files ?? [],
+		preset_revision: view.preset_revision ?? null,
+		content_digest: view.content_digest ?? null,
+		events: ordered,
+		items: ordered.map(toItem),
+		...usage ? { usage } : {}
+	};
+}
+//#endregion
+//#region src/run-handle.ts
+/** Poll cadence while waiting for a terminal state (authoritative backstop). */
+const POLL_INTERVAL_MS = 3e3;
+/** Absolute cap so a wedged run cannot hang `finished` forever. */
+const FINISHED_TIMEOUT_MS = 18e5;
+/** Live events kept for the terminal aggregation (bounded). */
+const MAX_BUFFERED_EVENTS = 2e3;
+const TERMINAL = [
+	"completed",
+	"failed",
+	"cancelled"
+];
+/**
+* A launched Agent run. Async-iterable over live events; await `.finished`
+* for the blocking Codex `thread.run()` shape.
+*/
+var AgentRunHandle = class {
+	runId;
+	receipt;
+	runClient;
+	poll;
+	subscription;
+	terminalView = null;
+	terminalResult = null;
+	finishWaiters = [];
+	iteratorQueue = [];
+	iteratorWaiters = [];
+	iteratorClosed = false;
+	bufferedEvents = [];
+	bufferedSequences = /* @__PURE__ */ new Set();
+	constructor(runClient, receipt, subscription, poll) {
+		this.runId = receipt.run_id;
+		this.receipt = receipt;
+		this.runClient = runClient;
+		this.subscription = subscription;
+		this.poll = poll;
+		subscription?.onEvent((event) => this.pushEvent(event));
+		subscription?.onError(() => void 0);
+	}
+	/**
+	* Resolves with the aggregated terminal turn result (≈ `thread.run()`):
+	* authoritative status/version plus `final_response`, output files, the
+	* persisted event stream and derived items.
+	*/
+	get finished() {
+		if (this.terminalResult) return Promise.resolve(this.terminalResult);
+		return new Promise((resolve, reject) => {
+			this.finishWaiters.push((error, result) => {
+				if (error) {
+					reject(error);
+					return;
+				}
+				resolve(result);
+			});
+			this.ensureTerminalWatch();
+		});
+	}
+	/** Latest live cursor (proxied from the subscription when attached). */
+	get lastSequence() {
+		return this.subscription?.lastSequence ?? 0;
+	}
+	/** Ask the server to cancel; terminal confirmation still arrives via events/get. */
+	async cancel() {
+		await this.runClient.cancel({
+			runId: this.runId,
+			expectedVersion: this.receipt.version
+		});
+	}
+	/**
+	* Inject steering text into the currently active step (≈ Codex turn steer).
+	* Throws `conflict` when the run already changed or has no active step —
+	* refresh `receipt`-level state via `runClient.get()` and retry.
+	*/
+	async steer(text) {
+		return this.runClient.steer({
+			runId: this.runId,
+			text,
+			expectedVersion: this.receipt.version
+		});
+	}
+	/** Detach the live subscription (events may still be polled via run/events). */
+	async close() {
+		this.iteratorClosed = true;
+		const waiters = this.iteratorWaiters;
+		this.iteratorWaiters = [];
+		for (const waiter of waiters) waiter({
+			value: void 0,
+			done: true
+		});
+		const subscription = this.subscription;
+		this.subscription = null;
+		await subscription?.close();
+	}
+	/** Async iterator over live events (≈ `thread.runStreamed()`). */
+	[Symbol.asyncIterator]() {
+		return { next: () => {
+			if (this.iteratorQueue.length > 0) {
+				const event = this.iteratorQueue.shift();
+				return Promise.resolve({
+					value: event,
+					done: false
+				});
+			}
+			if (this.iteratorClosed) return Promise.resolve({
+				value: void 0,
+				done: true
+			});
+			return new Promise((resolve) => {
+				this.iteratorWaiters.push(resolve);
+			});
+		} };
+	}
+	pushEvent(event) {
+		if (!this.bufferedSequences.has(event.sequence)) {
+			this.bufferedSequences.add(event.sequence);
+			this.bufferedEvents.push(event);
+			if (this.bufferedEvents.length > MAX_BUFFERED_EVENTS) {
+				const dropped = this.bufferedEvents.shift();
+				if (dropped) this.bufferedSequences.delete(dropped.sequence);
+			}
+		}
+		const waiter = this.iteratorWaiters.shift();
+		if (waiter) {
+			waiter({
+				value: event,
+				done: false
+			});
+			return;
+		}
+		this.iteratorQueue.push(event);
+	}
+	/**
+	* Authoritative backfill for `finished`: `run/result` (terminal summary)
+	* plus the persisted `run/events` stream, falling back to the live buffer
+	* when the query fails.
+	*/
+	async aggregate(view) {
+		const result = await this.runClient.result(this.runId).catch(() => null);
+		const events = await this.runClient.events({
+			runId: this.runId,
+			afterSequence: 0,
+			limit: MAX_BUFFERED_EVENTS
+		}).catch(() => this.bufferedEvents);
+		const source = events.length > 0 ? events : this.bufferedEvents;
+		return aggregateTurnResult(result ?? view, source);
+	}
+	/** Poll run/get until terminal, then resolve all `finished` waiters once. */
+	ensureTerminalWatch() {
+		(async () => {
+			const deadline = Date.now() + FINISHED_TIMEOUT_MS;
+			try {
+				while (!this.terminalView && Date.now() < deadline) {
+					const view = await this.poll(this.runId);
+					if (TERMINAL.includes(view.status)) this.terminalView = view;
+					else await new Promise((resolve) => setTimeout(resolve, POLL_INTERVAL_MS));
+				}
+				const waiters = this.finishWaiters;
+				this.finishWaiters = [];
+				if (!this.terminalView) {
+					const timeout = /* @__PURE__ */ new Error(`run ${this.runId} did not reach a terminal state in time`);
+					for (const waiter of waiters) waiter(timeout);
+					return;
+				}
+				this.terminalResult = await this.aggregate(this.terminalView);
+				for (const waiter of waiters) waiter(void 0, this.terminalResult);
+			} catch (error) {
+				const waiters = this.finishWaiters;
+				this.finishWaiters = [];
+				for (const waiter of waiters) waiter(error);
+			}
+		})();
+	}
+};
+/** Codex-parity launch: start the run and return a live handle immediately. */
+async function launchRun(runClient, input, options = {}) {
+	const receipt = await runClient.agent(input);
+	return new AgentRunHandle(runClient, receipt, options.follow === false ? null : await runClient.follow(receipt.run_id), (runId) => runClient.get(runId));
+}
+//#endregion
+//#region src/retry.ts
+/**
+* Retry helper (REQ-PAR-05e, ≈ Codex `retry_on_overload`): exponential backoff
+* with jitter, driven by the protocol's stable `retryable` hint.
+*
+* Only errors the server/transport marks retryable are retried; protocol
+* errors that carry `retryable: false` (validation, not_found, ...) surface
+* immediately. `command_id` / `idempotency_key` callers stay safe because the
+* App Server deduplicates replayed mutations.
+*/
+/** Run `operation`, retrying retryable failures with exponential backoff. */
+async function withRetry(operation, options = {}) {
+	const maxAttempts = Math.max(1, options.maxAttempts ?? 3);
+	const baseDelayMs = Math.max(0, options.baseDelayMs ?? 500);
+	const maxDelayMs = Math.max(baseDelayMs, options.maxDelayMs ?? 8e3);
+	const jitter = Math.min(1, Math.max(0, options.jitter ?? .25));
+	const sleep = options.sleep ?? ((ms) => new Promise((resolve) => setTimeout(resolve, ms)));
+	const shouldRetry = options.shouldRetry ?? ((error) => (0, _flowy_agent_store_protocol.isRetryableError)(error));
+	let lastError;
+	for (let attempt = 1; attempt <= maxAttempts; attempt += 1) try {
+		return await operation();
+	} catch (error) {
+		lastError = error;
+		if (attempt >= maxAttempts || !shouldRetry(error, attempt)) throw error;
+		const ceiling = Math.min(maxDelayMs, baseDelayMs * 2 ** (attempt - 1));
+		const delayMs = Math.round(ceiling * (1 - jitter) + Math.random() * ceiling * jitter);
+		options.onRetry?.({
+			attempt,
+			delayMs,
+			error
+		});
+		await sleep(delayMs);
+	}
+	throw lastError;
+}
+//#endregion
+exports.AgentClient = AgentClient;
+exports.AgentRunHandle = AgentRunHandle;
+exports.AppServerClient = AppServerClient;
+exports.ConnectorClient = ConnectorClient;
+exports.ConversationClient = ConversationClient;
+exports.ConversationHandle = ConversationHandle;
+exports.ConversationSubscription = ConversationSubscription;
+exports.EventSubscription = EventSubscription;
+exports.ModelClient = ModelClient;
+exports.RunClient = RunClient;
+exports.SkillClient = SkillClient;
+exports.TeamClient = TeamClient;
+exports.WebSocketTransport = WebSocketTransport;
+exports.WorkspaceClient = WorkspaceClient;
+exports.aggregateTurnResult = aggregateTurnResult;
+exports.conversationMessages = conversationMessages;
+exports.isLoopbackUrl = isLoopbackUrl;
+exports.launchRun = launchRun;
+exports.withRetry = withRetry;