@flowy-agent-store/client 0.1.0-beta.7 → 0.1.0-beta.8

package/dist/index.cjs

@@ -276,7 +276,7 @@ var WebSocketTransport = class {
 /** 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-8";
+const PROTOCOL_VERSION = "fp-12";
 /**
 * Protocol method → REST route. Verified from handler bodies, not from the
 * route list (a route existing does not prove which method it mirrors).
@@ -471,6 +471,26 @@ const HTTP_ROUTES = {
 		path: "/connectors/:connector_id/auth-logout",
 		source: "connector_auth_logout_route() -> connector_auth_logout_impl"
 	},
+	"connector/credential/get": {
+		verb: "GET",
+		path: "/connectors/:connector_id/credential",
+		source: "connector_credential_get_route() -> connector_credential_get_impl"
+	},
+	"connector/credential/set": {
+		verb: "POST",
+		path: "/connectors/:connector_id/credential",
+		source: "connector_credential_set_route() -> connector_credential_set_impl"
+	},
+	"connector/credential/clear": {
+		verb: "POST",
+		path: "/connectors/:connector_id/credential/clear",
+		source: "connector_credential_clear_route() -> connector_credential_clear_impl"
+	},
+	"connector/register": {
+		verb: "POST",
+		path: "/connectors",
+		source: "register_connector_route() -> register_connector_impl"
+	},
 	"import/run": {
 		verb: "POST",
 		path: "/imports",
@@ -560,6 +580,11 @@ const HTTP_ROUTES = {
 		verb: "POST",
 		path: "/store/:marketplace_id/entries/:entry_name/install",
 		source: "store_install_entry_route() -> store_install_entry_impl"
+	},
+	"store/update-entry": {
+		verb: "POST",
+		path: "/store/:marketplace_id/entries/:entry_name/update",
+		source: "store_update_entry_route() -> store_update_entry_impl"
 	}
 };
 /** Methods that are WebSocket-only by design — named so the error explains itself. */
@@ -1080,6 +1105,13 @@ var ConversationSubscription = class {
 };
 //#endregion
 //#region src/connectors.ts
+/**
+* How long {@link ConnectorClient.waitForAuth} waits by default: the host's own
+* callback window is 120s, so a shorter client budget would give up on flows the
+* host is still willing to finish.
+*/
+const DEFAULT_AUTH_TIMEOUT_MS = 12e4;
+const DEFAULT_AUTH_POLL_MS = 500;
 var ConnectorClient = class {
 	transport;
 	constructor(transport) {
@@ -1113,17 +1145,117 @@ var ConnectorClient = class {
 	test(connectorId) {
 		return this.transport.request("connector/test", { connector_id: connectorId });
 	}
-	/** Check the current OAuth state for a connector. */
+	/**
+	* Check the current OAuth state for a connector.
+	*
+	* Read `error` too: a flow that failed after the browser step is reported as
+	* `state: "not_authenticated"` **plus** `error`, because the wire has no
+	* failing state to flip to. {@link waitForAuth} is the loop that does this.
+	*/
 	authStatus(connectorId) {
 		return this.transport.request("connector/auth/status", { connector_id: connectorId });
 	}
 	/**
+	* The credential form a connector needs filled in, as **this caller** sees it
+	* (doc `34` §6.1).
+	*
+	* `mode` says which kind of authentication applies (`none` / `oauth` / `token`),
+	* `status` whether anything is still missing, and `missing` names the keys.
+	* `fields` is everything needed to render the form — labels, placeholders,
+	* descriptions and the marketplace's "where do I get a key" link, in both
+	* languages. No secret ever comes back: only `plain` fields carry a `value`.
+	*/
+	credentials(connectorId) {
+		return this.transport.request("connector/credential/get", { connector_id: connectorId });
+	}
+	/**
+	* Store what the user typed and get the new state back.
+	*
+	* Only keys the connector's own declaration names are accepted — the form is
+	* the whole write surface. `secret` fields go to the host's credential store
+	* under the caller's own namespace, `plain` fields into the connector's
+	* configuration, so a shared host never resolves one user's token for another.
+	*/
+	setCredentials(connectorId, values) {
+		return this.transport.request("connector/credential/set", {
+			connector_id: connectorId,
+			values
+		});
+	}
+	/**
+	* Forget stored credentials. `keys` omitted = every secret field of this
+	* connector. Idempotent: clearing what is not there succeeds.
+	*/
+	clearCredentials(connectorId, keys) {
+		return this.transport.request("connector/credential/clear", {
+			connector_id: connectorId,
+			...keys ? { keys } : {}
+		});
+	}
+	/**
+	* Register a connector this host never imported — your own MCP server, handed
+	* over together with the template that says what it needs (doc `34` §6.5).
+	*
+	* The **template is the whole declaration**: whatever `${secret:NAME}` the URL,
+	* headers or env name becomes that connector's credential form, so there is no
+	* `token-schema.json` to ship and nothing to install from a marketplace. The
+	* connector's own non-secret settings travel in `values`.
+	*
+	* Secrets do **not** travel here: hand them over with {@link setCredentials},
+	* which keeps exactly one write surface for values. The returned detail already
+	* carries the credential block, so `missing` tells you which keys are still
+	* needed.
+	*
+	* Re-registering the same name updates it; a builtin server's name is refused.
+	* The row is created **disabled** — enabling it still requires a probe that
+	* passes — and this method is on the installation-owner-only surface, because
+	* choosing where the host reaches is the owner's call.
+	*/
+	register(registration) {
+		return this.transport.request("connector/register", registration);
+	}
+	/**
 	* Kick off the OAuth browser flow on the trusted host. Returns the start
-	* acknowledgement immediately; poll `authStatus` until `authenticated`.
+	* acknowledgement immediately; follow it with {@link waitForAuth}.
+	*
+	* `state: "error"` here is a failure that happened **before** the browser was
+	* opened (endpoint discovery, client identity, binding the callback, launching
+	* the browser): nothing was shown to the user, so `error` is the whole story
+	* and there is nothing to wait for.
 	*/
 	authStart(connectorId) {
 		return this.transport.request("connector/auth/start", { connector_id: connectorId });
 	}
+	/**
+	* Wait for an authorization that was started (in the browser, or by a
+	* previous `authStart`) to finish — and **report why** when it does not.
+	*
+	* A hand-rolled `while (state !== "authenticated") poll()` loop ends in "it
+	* never became authenticated", with the reason sitting unread in the status it
+	* already fetched: a token exchange the authorization server refused (a
+	* throttling gateway answers `slow_down`), a callback timeout, a CSRF/path
+	* mismatch. Those land in `authStatus().error` *only*, and the state stays
+	* `not_authenticated` — there is no failing state on the wire.
+	*
+	* Resolves for every domain outcome (`authenticated` / `error` / `timeout`);
+	* rejects only when the status read itself fails (transport or protocol), the
+	* same rule as `connector/call`. The wait is bounded by `timeoutMs`; a caller
+	* that needs to stop earlier can race the returned promise.
+	*/
+	async waitForAuth(connectorId, options = {}) {
+		const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS);
+		const pollMs = options.pollMs ?? DEFAULT_AUTH_POLL_MS;
+		for (;;) {
+			const status = await this.authStatus(connectorId);
+			if (status.state === "authenticated") return { state: "authenticated" };
+			if (status.error) return {
+				state: "error",
+				error: status.error
+			};
+			if (Date.now() >= deadline) return { state: "timeout" };
+			await new Promise((resolve) => setTimeout(resolve, pollMs));
+		}
+	}
 	/** Revoke the OAuth token for a connector. */
 	logout(connectorId) {
 		return this.transport.request("connector/auth/logout", { connector_id: connectorId }).then(() => void 0);
@@ -1543,6 +1675,7 @@ var StoreError = class extends Error {
 const DEFAULT_READY_TIMEOUT_MS = 3e4;
 const DEFAULT_READY_POLL_MS = 400;
 const DEFAULT_READY_POLL_MAX_MS = 4e3;
+const DEFAULT_READY_PROBE_MS = 5e3;
 /** Every string a `LocalizedText` carries, for haystack building. */
 function localizedValues(text) {
 	if (typeof text === "string") return [text];
@@ -1584,11 +1717,13 @@ var StoreClient = class {
 	readyTimeoutMs;
 	readyPollMs;
 	readyPollMaxMs;
+	readyProbeMs;
 	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;
+		this.readyProbeMs = options.readyProbeMs ?? DEFAULT_READY_PROBE_MS;
 	}
 	/** Every item across enabled marketplaces, with install state. */
 	async list() {
@@ -1620,15 +1755,45 @@ var StoreClient = class {
 	/**
 	* 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.
+	* `"none"` means there is nothing to do; `"update"` means the entry is
+	* installed at a different version and `update()` is the action that lands it
+	* (`store/update-entry`, `36` D3); `"unknown"` is returned rather than
+	* guessing when the item carries no snapshot to replace.
 	*/
 	updateHint(item) {
 		if (!item.installed || !item.update_available) return "none";
-		return item.snapshot_id ? "uninstall_reinstall" : "unknown";
+		return item.snapshot_id ? "update" : "unknown";
+	}
+	/**
+	* Upgrade an installed item to the version its marketplace advertises.
+	*
+	* The host does the ordering: new version installed first, previous one
+	* released only when that succeeded. So a failure resolves `ok: false` with
+	* the previous installation still in place (`releasedCount === 0`) — the
+	* caller never has to reason about a half-upgraded item.
+	*
+	* Refuses before the round trip when there is nothing to replace: an item that
+	* is not installed (`not_installed`) or is already current is not a failure of
+	* *this* call, and `updateHint()` is the way to ask first.
+	*/
+	async update(item, options = {}) {
+		this.assertUsable(item, options.signal);
+		this.requireSnapshot(item);
+		const result = await this.host.updateStoreEntry(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),
+			errors: result.errors,
+			warnings: result.warnings,
+			fromVersion: result.previous_version ?? void 0,
+			toVersion: result.version,
+			releasedCount: result.released_count ?? 0
+		};
+		if (options.waitForReady === false) return outcome;
+		return this.awaitReady(outcome, options);
 	}
 	/**
 	* Import (when needed) and install one store item, then wait until it is
@@ -1642,7 +1807,9 @@ var StoreClient = class {
 			snapshotId: result.snapshot_id,
 			reused: result.reused,
 			components,
-			ok: result.errors.length === 0 && components.every((component) => component.ok)
+			ok: result.errors.length === 0 && components.every((component) => component.ok),
+			errors: result.errors,
+			warnings: result.warnings
 		};
 		if (options.waitForReady === false) return outcome;
 		return this.awaitReady(outcome, options);
@@ -1661,7 +1828,9 @@ var StoreClient = class {
 			snapshotId,
 			reused: true,
 			components: [],
-			ok: true
+			ok: true,
+			errors: [],
+			warnings: []
 		};
 		const status = await this.host.uninstallInstall(snapshotId, componentIds);
 		return this.outcomeFromStatus(snapshotId, status, false);
@@ -1681,7 +1850,9 @@ var StoreClient = class {
 			snapshotId,
 			reused: true,
 			components: [],
-			ok: true
+			ok: true,
+			errors: [],
+			warnings: []
 		};
 		const status = enabled ? await this.host.enableInstall(snapshotId, componentIds) : await this.host.disableInstall(snapshotId, componentIds);
 		return this.outcomeFromStatus(snapshotId, status, false);
@@ -1700,11 +1871,14 @@ var StoreClient = class {
 	}
 	outcomeFromStatus(snapshotId, status, reused) {
 		const components = status.outcomes ?? [];
+		const errors = status.errors ?? [];
 		return {
 			snapshotId,
 			reused,
 			components,
-			ok: (status.errors ?? []).length === 0 && components.every((component) => component.ok)
+			ok: errors.length === 0 && components.every((component) => component.ok),
+			errors,
+			warnings: []
 		};
 	}
 	/**
@@ -1722,11 +1896,15 @@ var StoreClient = class {
 		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 nextProbeAt = 0;
 		let last = status.components;
 		for (;;) {
+			const now = Date.now();
+			const allowProbe = now >= nextProbeAt;
+			if (allowProbe) nextProbeAt = now + this.readyProbeMs;
 			const blocked = (await Promise.all(last.filter((component) => component.state !== "not-installed").map(async (component) => ({
 				component,
-				verdict: await this.readiness(component)
+				verdict: await this.readiness(component, allowProbe)
 			})))).find((entry) => !entry.verdict.ready);
 			if (!blocked) return {
 				...outcome,
@@ -1756,8 +1934,12 @@ var StoreClient = class {
 	* 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.
+	*
+	* `allowProbe` gates the one kind whose readiness needs a real connection (a
+	* connector); the other kinds answer from local reads, so the cadence does not
+	* apply to them.
 	*/
-	async readiness(component) {
+	async readiness(component, allowProbe) {
 		try {
 			switch (component.kind) {
 				case "skill": return (await this.host.skills.list()).some((skill) => skill.name === component.name) ? { ready: true } : { ready: false };
@@ -1766,8 +1948,9 @@ var StoreClient = class {
 					await this.host.teams.get(component.id);
 					return { ready: true };
 				case "connector": {
-					if ((await this.host.connectors.test(component.id)).success) return { ready: true };
+					if (allowProbe && (await this.host.connectors.test(component.id)).success) return { ready: true };
 					const status = await this.host.connectors.status(component.id);
+					if (status.status === "connected") return { ready: true };
 					if (status.status === "authorization_required" || status.status === "reauthorization_required") return {
 						ready: false,
 						terminal: "authorization_required"
@@ -2054,6 +2237,20 @@ var AppServerClient = class {
 			entry_name: entryName
 		});
 	}
+	/**
+	* Upgrade an installed entry to the version its marketplace advertises.
+	*
+	* The host installs the new version before releasing the old one, so a failure
+	* leaves the previous installation usable (`released_count: 0` is the machine
+	* readable form of that). Refused for an entry that is not installed — this is
+	* never a second way to install something.
+	*/
+	async updateStoreEntry(marketplaceId, entryName) {
+		return this.transport.request("store/update-entry", {
+			marketplace_id: marketplaceId,
+			entry_name: entryName
+		});
+	}
 };
 //#endregion
 //#region src/conversation-handle.ts

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { AgentDetail, AgentRunInput, AgentSummary, AnswerDecisionInput, CancelRunInput, ClientCapabilities, ClientInfo, ConnectorCallResult, ConnectorDetail, ConnectorProbeResult, ConnectorStatusView, ConnectorSummary, ContextUsage, ConversationCreateInput, ConversationEvent, ConversationMessage, ConversationMessagesPage, ConversationMessagesQuery, ConversationModelOptions, ConversationSendReceipt, ConversationUpdateInput, ConversationView, ExpertPack, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallOutcome, InstallRequest, InstallResult, InstallStatus, MarketplaceAddRequest, MarketplaceDetail, MarketplaceRefreshResult, MarketplaceRemoveResult, MarketplaceSummary, MentionRef, ModelSummary, OAuthStartResult, OAuthStatusView, ProviderWithModel, RunEvent, RunEventsQuery, RunPlan, RunReceipt, RunResult, RunStatus, RunView, ServerNotification, SkillDetail, SkillFileContent, SkillFileList, SkillSummary, SteerRunInput, StoreInstallResult, StoreItem, StoreItemKind, StoreList, TeamDetail, TeamRunInput, TeamRunReceipt, TeamSummary, WorkspaceRevokeResult, WorkspaceView } from "@flowy-agent-store/protocol";
+import { AgentDetail, AgentRunInput, AgentSummary, AnswerDecisionInput, CancelRunInput, ClientCapabilities, ClientInfo, ConnectorCallResult, ConnectorCredential, ConnectorDetail, ConnectorProbeResult, ConnectorRegistration, ConnectorStatusView, ConnectorSummary, ContextUsage, ConversationCreateInput, ConversationEvent, ConversationMessage, ConversationMessagesPage, ConversationMessagesQuery, ConversationModelOptions, ConversationSendReceipt, ConversationUpdateInput, ConversationView, ExpertPack, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallOutcome, InstallRequest, InstallResult, InstallStatus, MarketplaceAddRequest, MarketplaceDetail, MarketplaceRefreshResult, MarketplaceRemoveResult, MarketplaceSummary, MentionRef, ModelSummary, OAuthStartResult, OAuthStatusView, ProviderWithModel, RunEvent, RunEventsQuery, RunPlan, RunReceipt, RunResult, RunStatus, RunView, ServerNotification, SkillDetail, SkillFileContent, SkillFileList, SkillSummary, SteerRunInput, StoreInstallResult, StoreItem, StoreItemKind, StoreList, TeamDetail, TeamRunInput, TeamRunReceipt, TeamSummary, WorkspaceRevokeResult, WorkspaceView } from "@flowy-agent-store/protocol";
 //#region src/transport.d.ts
 export type NotificationListener = (notification: ServerNotification) => void;
 /**
@@ -374,6 +374,28 @@ export declare class ConversationSubscription {
 }
 //#endregion
 //#region src/connectors.d.ts
+export interface WaitForAuthOptions {
+  /** Overall budget in ms; defaults to `DEFAULT_AUTH_TIMEOUT_MS` (120s). */
+  timeoutMs?: number;
+  /** Poll interval in ms; defaults to 500. The read is a local DB projection. */
+  pollMs?: number;
+}
+/**
+ * How a completed wait ended.
+ *
+ * `error` carries the host's own sentence. It is the shape of every failure that
+ * happens *after* `authStart` acknowledged the browser step — the state stays
+ * `not_authenticated` (there is no "failed" state on the wire), so the reason is
+ * the only signal there is.
+ */
+export type WaitForAuthOutcome = {
+  state: "authenticated";
+} | {
+  state: "error";
+  error: string;
+} | {
+  state: "timeout";
+};
 export declare class ConnectorClient {
   private readonly transport;
   constructor(transport: Transport);
@@ -397,13 +419,86 @@ export declare class ConnectorClient {
    * the last segment of its wire method.
    */
   test(connectorId: string): Promise<ConnectorProbeResult>;
-  /** Check the current OAuth state for a connector. */
+  /**
+   * Check the current OAuth state for a connector.
+   *
+   * Read `error` too: a flow that failed after the browser step is reported as
+   * `state: "not_authenticated"` **plus** `error`, because the wire has no
+   * failing state to flip to. {@link waitForAuth} is the loop that does this.
+   */
   authStatus(connectorId: string): Promise<OAuthStatusView>;
+  /**
+   * The credential form a connector needs filled in, as **this caller** sees it
+   * (doc `34` §6.1).
+   *
+   * `mode` says which kind of authentication applies (`none` / `oauth` / `token`),
+   * `status` whether anything is still missing, and `missing` names the keys.
+   * `fields` is everything needed to render the form — labels, placeholders,
+   * descriptions and the marketplace's "where do I get a key" link, in both
+   * languages. No secret ever comes back: only `plain` fields carry a `value`.
+   */
+  credentials(connectorId: string): Promise<ConnectorCredential>;
+  /**
+   * Store what the user typed and get the new state back.
+   *
+   * Only keys the connector's own declaration names are accepted — the form is
+   * the whole write surface. `secret` fields go to the host's credential store
+   * under the caller's own namespace, `plain` fields into the connector's
+   * configuration, so a shared host never resolves one user's token for another.
+   */
+  setCredentials(connectorId: string, values: Record<string, string>): Promise<ConnectorCredential>;
+  /**
+   * Forget stored credentials. `keys` omitted = every secret field of this
+   * connector. Idempotent: clearing what is not there succeeds.
+   */
+  clearCredentials(connectorId: string, keys?: string[]): Promise<ConnectorCredential>;
+  /**
+   * Register a connector this host never imported — your own MCP server, handed
+   * over together with the template that says what it needs (doc `34` §6.5).
+   *
+   * The **template is the whole declaration**: whatever `${secret:NAME}` the URL,
+   * headers or env name becomes that connector's credential form, so there is no
+   * `token-schema.json` to ship and nothing to install from a marketplace. The
+   * connector's own non-secret settings travel in `values`.
+   *
+   * Secrets do **not** travel here: hand them over with {@link setCredentials},
+   * which keeps exactly one write surface for values. The returned detail already
+   * carries the credential block, so `missing` tells you which keys are still
+   * needed.
+   *
+   * Re-registering the same name updates it; a builtin server's name is refused.
+   * The row is created **disabled** — enabling it still requires a probe that
+   * passes — and this method is on the installation-owner-only surface, because
+   * choosing where the host reaches is the owner's call.
+   */
+  register(registration: ConnectorRegistration): Promise<ConnectorDetail>;
   /**
    * Kick off the OAuth browser flow on the trusted host. Returns the start
-   * acknowledgement immediately; poll `authStatus` until `authenticated`.
+   * acknowledgement immediately; follow it with {@link waitForAuth}.
+   *
+   * `state: "error"` here is a failure that happened **before** the browser was
+   * opened (endpoint discovery, client identity, binding the callback, launching
+   * the browser): nothing was shown to the user, so `error` is the whole story
+   * and there is nothing to wait for.
    */
   authStart(connectorId: string): Promise<OAuthStartResult>;
+  /**
+   * Wait for an authorization that was started (in the browser, or by a
+   * previous `authStart`) to finish — and **report why** when it does not.
+   *
+   * A hand-rolled `while (state !== "authenticated") poll()` loop ends in "it
+   * never became authenticated", with the reason sitting unread in the status it
+   * already fetched: a token exchange the authorization server refused (a
+   * throttling gateway answers `slow_down`), a callback timeout, a CSRF/path
+   * mismatch. Those land in `authStatus().error` *only*, and the state stays
+   * `not_authenticated` — there is no failing state on the wire.
+   *
+   * Resolves for every domain outcome (`authenticated` / `error` / `timeout`);
+   * rejects only when the status read itself fails (transport or protocol), the
+   * same rule as `connector/call`. The wait is bounded by `timeoutMs`; a caller
+   * that needs to stop earlier can race the returned promise.
+   */
+  waitForAuth(connectorId: string, options?: WaitForAuthOptions): Promise<WaitForAuthOutcome>;
   /** Revoke the OAuth token for a connector. */
   logout(connectorId: string): Promise<void>;
   /**
@@ -621,6 +716,20 @@ export interface StoreClientOptions {
   /** First readiness poll interval in ms; doubles up to `readyPollMaxMs`. */
   readyPollMs?: number;
   readyPollMaxMs?: number;
+  /**
+   * Minimum gap between two *real probes* of the same connector while waiting
+   * for readiness, in ms. Defaults to `DEFAULT_READY_PROBE_MS`.
+   *
+   * A connector's readiness cannot be read: the status is derived from the last
+   * probe, so someone has to run one — but a probe is a real connection
+   * (`initialize` + `tools/list`) that also resolves the stored token, which
+   * means a refresh request when that token is near expiry, plus one more on a
+   * 401. Probing once per poll (the poll starts at `readyPollMs` = 400ms) turned
+   * a 30s readiness budget into ~10 connections and up to ~20 token requests
+   * against the connector's authorization server — with nobody having asked for
+   * anything. Between probes the loop reads the (free, local) status instead.
+   */
+  readyProbeMs?: number;
 }
 export interface StoreOperationOutcome {
   /** The snapshot the operation acted on; `null` when nothing was imported. */
@@ -634,6 +743,18 @@ export interface StoreOperationOutcome {
   components: InstallOutcome[];
   /** Every reported component reached the requested state. */
   ok: boolean;
+  /**
+   * The server's own failure lines, verbatim.
+   *
+   * `ok: false` alone is not an answer: the host explains *why* (a digest
+   * conflict means the market changed content without raising the version; a
+   * `preset_update_failed` names the component). Dropping these is what made a
+   * refused import unexplainable in the UI (`18` §11 D10), so they are carried
+   * rather than folded into `ok`.
+   */
+  errors: string[];
+  /** The server's non-fatal notes, verbatim (e.g. a component left disabled). */
+  warnings: string[];
   /**
    * `undefined` when readiness was not checked. `true` when every component is
    * usable now; `false` when it is not (see `readyIssue`).
@@ -642,6 +763,16 @@ export interface StoreOperationOutcome {
   readyIssue?: StoreReadyIssue;
   /** The component that needs attention, when `readyIssue` is set. */
   readyComponentId?: string;
+  /** `update()` only: the version that was installed before this call. */
+  fromVersion?: string;
+  /** `update()` only: the version now installed. */
+  toVersion?: string;
+  /**
+   * `update()` only: how many components of the replaced snapshot were actually
+   * released. `0` means the previous installation was not touched — an update
+   * that failed, or a no-op.
+   */
+  releasedCount?: number;
 }
 /**
  * The slice of `AppServerClient` this layer orchestrates.
@@ -653,6 +784,7 @@ export interface StoreOperationOutcome {
 export interface StoreHost {
   listStore(): Promise<StoreList>;
   installStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
+  updateStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
   getInstallStatus(snapshotId: string): Promise<InstallStatus>;
   disableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
   enableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
@@ -676,6 +808,7 @@ export declare class StoreClient {
   private readonly readyTimeoutMs;
   private readonly readyPollMs;
   private readonly readyPollMaxMs;
+  private readonly readyProbeMs;
   constructor(host: StoreHost, options?: StoreClientOptions);
   /** Every item across enabled marketplaces, with install state. */
   list(): Promise<StoreItem[]>;
@@ -696,13 +829,25 @@ export declare class StoreClient {
   /**
    * 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.
+   * `"none"` means there is nothing to do; `"update"` means the entry is
+   * installed at a different version and `update()` is the action that lands it
+   * (`store/update-entry`, `36` D3); `"unknown"` is returned rather than
+   * guessing when the item carries no snapshot to replace.
+   */
+  updateHint(item: StoreItem): "none" | "update" | "unknown";
+  /**
+   * Upgrade an installed item to the version its marketplace advertises.
+   *
+   * The host does the ordering: new version installed first, previous one
+   * released only when that succeeded. So a failure resolves `ok: false` with
+   * the previous installation still in place (`releasedCount === 0`) — the
+   * caller never has to reason about a half-upgraded item.
+   *
+   * Refuses before the round trip when there is nothing to replace: an item that
+   * is not installed (`not_installed`) or is already current is not a failure of
+   * *this* call, and `updateHint()` is the way to ask first.
    */
-  updateHint(item: StoreItem): "none" | "uninstall_reinstall" | "unknown";
+  update(item: StoreItem, options?: InstallOptions): Promise<StoreOperationOutcome>;
   /**
    * Import (when needed) and install one store item, then wait until it is
    * usable.
@@ -744,6 +889,10 @@ export declare class StoreClient {
    * 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.
+   *
+   * `allowProbe` gates the one kind whose readiness needs a real connection (a
+   * connector); the other kinds answer from local reads, so the cadence does not
+   * apply to them.
    */
   private readiness;
 }
@@ -890,6 +1039,15 @@ export declare class AppServerClient {
   listStore(): Promise<StoreList>;
   /** One-click install: import (when missing) + register in one call. */
   installStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
+  /**
+   * Upgrade an installed entry to the version its marketplace advertises.
+   *
+   * The host installs the new version before releasing the old one, so a failure
+   * leaves the previous installation usable (`released_count: 0` is the machine
+   * readable form of that). Refused for an entry that is not installed — this is
+   * never a second way to install something.
+   */
+  updateStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
 }
 //#endregion
 //#region src/conversation-handle.d.ts

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AgentDetail, AgentRunInput, AgentSummary, AnswerDecisionInput, CancelRunInput, ClientCapabilities, ClientInfo, ConnectorCallResult, ConnectorDetail, ConnectorProbeResult, ConnectorStatusView, ConnectorSummary, ContextUsage, ConversationCreateInput, ConversationEvent, ConversationMessage, ConversationMessagesPage, ConversationMessagesQuery, ConversationModelOptions, ConversationSendReceipt, ConversationUpdateInput, ConversationView, ExpertPack, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallOutcome, InstallRequest, InstallResult, InstallStatus, MarketplaceAddRequest, MarketplaceDetail, MarketplaceRefreshResult, MarketplaceRemoveResult, MarketplaceSummary, MentionRef, ModelSummary, OAuthStartResult, OAuthStatusView, ProviderWithModel, RunEvent, RunEventsQuery, RunPlan, RunReceipt, RunResult, RunStatus, RunView, ServerNotification, SkillDetail, SkillFileContent, SkillFileList, SkillSummary, SteerRunInput, StoreInstallResult, StoreItem, StoreItemKind, StoreList, TeamDetail, TeamRunInput, TeamRunReceipt, TeamSummary, WorkspaceRevokeResult, WorkspaceView } from "@flowy-agent-store/protocol";
+import { AgentDetail, AgentRunInput, AgentSummary, AnswerDecisionInput, CancelRunInput, ClientCapabilities, ClientInfo, ConnectorCallResult, ConnectorCredential, ConnectorDetail, ConnectorProbeResult, ConnectorRegistration, ConnectorStatusView, ConnectorSummary, ContextUsage, ConversationCreateInput, ConversationEvent, ConversationMessage, ConversationMessagesPage, ConversationMessagesQuery, ConversationModelOptions, ConversationSendReceipt, ConversationUpdateInput, ConversationView, ExpertPack, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallOutcome, InstallRequest, InstallResult, InstallStatus, MarketplaceAddRequest, MarketplaceDetail, MarketplaceRefreshResult, MarketplaceRemoveResult, MarketplaceSummary, MentionRef, ModelSummary, OAuthStartResult, OAuthStatusView, ProviderWithModel, RunEvent, RunEventsQuery, RunPlan, RunReceipt, RunResult, RunStatus, RunView, ServerNotification, SkillDetail, SkillFileContent, SkillFileList, SkillSummary, SteerRunInput, StoreInstallResult, StoreItem, StoreItemKind, StoreList, TeamDetail, TeamRunInput, TeamRunReceipt, TeamSummary, WorkspaceRevokeResult, WorkspaceView } from "@flowy-agent-store/protocol";
 //#region src/transport.d.ts
 export type NotificationListener = (notification: ServerNotification) => void;
 /**
@@ -374,6 +374,28 @@ export declare class ConversationSubscription {
 }
 //#endregion
 //#region src/connectors.d.ts
+export interface WaitForAuthOptions {
+  /** Overall budget in ms; defaults to `DEFAULT_AUTH_TIMEOUT_MS` (120s). */
+  timeoutMs?: number;
+  /** Poll interval in ms; defaults to 500. The read is a local DB projection. */
+  pollMs?: number;
+}
+/**
+ * How a completed wait ended.
+ *
+ * `error` carries the host's own sentence. It is the shape of every failure that
+ * happens *after* `authStart` acknowledged the browser step — the state stays
+ * `not_authenticated` (there is no "failed" state on the wire), so the reason is
+ * the only signal there is.
+ */
+export type WaitForAuthOutcome = {
+  state: "authenticated";
+} | {
+  state: "error";
+  error: string;
+} | {
+  state: "timeout";
+};
 export declare class ConnectorClient {
   private readonly transport;
   constructor(transport: Transport);
@@ -397,13 +419,86 @@ export declare class ConnectorClient {
    * the last segment of its wire method.
    */
   test(connectorId: string): Promise<ConnectorProbeResult>;
-  /** Check the current OAuth state for a connector. */
+  /**
+   * Check the current OAuth state for a connector.
+   *
+   * Read `error` too: a flow that failed after the browser step is reported as
+   * `state: "not_authenticated"` **plus** `error`, because the wire has no
+   * failing state to flip to. {@link waitForAuth} is the loop that does this.
+   */
   authStatus(connectorId: string): Promise<OAuthStatusView>;
+  /**
+   * The credential form a connector needs filled in, as **this caller** sees it
+   * (doc `34` §6.1).
+   *
+   * `mode` says which kind of authentication applies (`none` / `oauth` / `token`),
+   * `status` whether anything is still missing, and `missing` names the keys.
+   * `fields` is everything needed to render the form — labels, placeholders,
+   * descriptions and the marketplace's "where do I get a key" link, in both
+   * languages. No secret ever comes back: only `plain` fields carry a `value`.
+   */
+  credentials(connectorId: string): Promise<ConnectorCredential>;
+  /**
+   * Store what the user typed and get the new state back.
+   *
+   * Only keys the connector's own declaration names are accepted — the form is
+   * the whole write surface. `secret` fields go to the host's credential store
+   * under the caller's own namespace, `plain` fields into the connector's
+   * configuration, so a shared host never resolves one user's token for another.
+   */
+  setCredentials(connectorId: string, values: Record<string, string>): Promise<ConnectorCredential>;
+  /**
+   * Forget stored credentials. `keys` omitted = every secret field of this
+   * connector. Idempotent: clearing what is not there succeeds.
+   */
+  clearCredentials(connectorId: string, keys?: string[]): Promise<ConnectorCredential>;
+  /**
+   * Register a connector this host never imported — your own MCP server, handed
+   * over together with the template that says what it needs (doc `34` §6.5).
+   *
+   * The **template is the whole declaration**: whatever `${secret:NAME}` the URL,
+   * headers or env name becomes that connector's credential form, so there is no
+   * `token-schema.json` to ship and nothing to install from a marketplace. The
+   * connector's own non-secret settings travel in `values`.
+   *
+   * Secrets do **not** travel here: hand them over with {@link setCredentials},
+   * which keeps exactly one write surface for values. The returned detail already
+   * carries the credential block, so `missing` tells you which keys are still
+   * needed.
+   *
+   * Re-registering the same name updates it; a builtin server's name is refused.
+   * The row is created **disabled** — enabling it still requires a probe that
+   * passes — and this method is on the installation-owner-only surface, because
+   * choosing where the host reaches is the owner's call.
+   */
+  register(registration: ConnectorRegistration): Promise<ConnectorDetail>;
   /**
    * Kick off the OAuth browser flow on the trusted host. Returns the start
-   * acknowledgement immediately; poll `authStatus` until `authenticated`.
+   * acknowledgement immediately; follow it with {@link waitForAuth}.
+   *
+   * `state: "error"` here is a failure that happened **before** the browser was
+   * opened (endpoint discovery, client identity, binding the callback, launching
+   * the browser): nothing was shown to the user, so `error` is the whole story
+   * and there is nothing to wait for.
    */
   authStart(connectorId: string): Promise<OAuthStartResult>;
+  /**
+   * Wait for an authorization that was started (in the browser, or by a
+   * previous `authStart`) to finish — and **report why** when it does not.
+   *
+   * A hand-rolled `while (state !== "authenticated") poll()` loop ends in "it
+   * never became authenticated", with the reason sitting unread in the status it
+   * already fetched: a token exchange the authorization server refused (a
+   * throttling gateway answers `slow_down`), a callback timeout, a CSRF/path
+   * mismatch. Those land in `authStatus().error` *only*, and the state stays
+   * `not_authenticated` — there is no failing state on the wire.
+   *
+   * Resolves for every domain outcome (`authenticated` / `error` / `timeout`);
+   * rejects only when the status read itself fails (transport or protocol), the
+   * same rule as `connector/call`. The wait is bounded by `timeoutMs`; a caller
+   * that needs to stop earlier can race the returned promise.
+   */
+  waitForAuth(connectorId: string, options?: WaitForAuthOptions): Promise<WaitForAuthOutcome>;
   /** Revoke the OAuth token for a connector. */
   logout(connectorId: string): Promise<void>;
   /**
@@ -621,6 +716,20 @@ export interface StoreClientOptions {
   /** First readiness poll interval in ms; doubles up to `readyPollMaxMs`. */
   readyPollMs?: number;
   readyPollMaxMs?: number;
+  /**
+   * Minimum gap between two *real probes* of the same connector while waiting
+   * for readiness, in ms. Defaults to `DEFAULT_READY_PROBE_MS`.
+   *
+   * A connector's readiness cannot be read: the status is derived from the last
+   * probe, so someone has to run one — but a probe is a real connection
+   * (`initialize` + `tools/list`) that also resolves the stored token, which
+   * means a refresh request when that token is near expiry, plus one more on a
+   * 401. Probing once per poll (the poll starts at `readyPollMs` = 400ms) turned
+   * a 30s readiness budget into ~10 connections and up to ~20 token requests
+   * against the connector's authorization server — with nobody having asked for
+   * anything. Between probes the loop reads the (free, local) status instead.
+   */
+  readyProbeMs?: number;
 }
 export interface StoreOperationOutcome {
   /** The snapshot the operation acted on; `null` when nothing was imported. */
@@ -634,6 +743,18 @@ export interface StoreOperationOutcome {
   components: InstallOutcome[];
   /** Every reported component reached the requested state. */
   ok: boolean;
+  /**
+   * The server's own failure lines, verbatim.
+   *
+   * `ok: false` alone is not an answer: the host explains *why* (a digest
+   * conflict means the market changed content without raising the version; a
+   * `preset_update_failed` names the component). Dropping these is what made a
+   * refused import unexplainable in the UI (`18` §11 D10), so they are carried
+   * rather than folded into `ok`.
+   */
+  errors: string[];
+  /** The server's non-fatal notes, verbatim (e.g. a component left disabled). */
+  warnings: string[];
   /**
    * `undefined` when readiness was not checked. `true` when every component is
    * usable now; `false` when it is not (see `readyIssue`).
@@ -642,6 +763,16 @@ export interface StoreOperationOutcome {
   readyIssue?: StoreReadyIssue;
   /** The component that needs attention, when `readyIssue` is set. */
   readyComponentId?: string;
+  /** `update()` only: the version that was installed before this call. */
+  fromVersion?: string;
+  /** `update()` only: the version now installed. */
+  toVersion?: string;
+  /**
+   * `update()` only: how many components of the replaced snapshot were actually
+   * released. `0` means the previous installation was not touched — an update
+   * that failed, or a no-op.
+   */
+  releasedCount?: number;
 }
 /**
  * The slice of `AppServerClient` this layer orchestrates.
@@ -653,6 +784,7 @@ export interface StoreOperationOutcome {
 export interface StoreHost {
   listStore(): Promise<StoreList>;
   installStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
+  updateStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
   getInstallStatus(snapshotId: string): Promise<InstallStatus>;
   disableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
   enableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
@@ -676,6 +808,7 @@ export declare class StoreClient {
   private readonly readyTimeoutMs;
   private readonly readyPollMs;
   private readonly readyPollMaxMs;
+  private readonly readyProbeMs;
   constructor(host: StoreHost, options?: StoreClientOptions);
   /** Every item across enabled marketplaces, with install state. */
   list(): Promise<StoreItem[]>;
@@ -696,13 +829,25 @@ export declare class StoreClient {
   /**
    * 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.
+   * `"none"` means there is nothing to do; `"update"` means the entry is
+   * installed at a different version and `update()` is the action that lands it
+   * (`store/update-entry`, `36` D3); `"unknown"` is returned rather than
+   * guessing when the item carries no snapshot to replace.
+   */
+  updateHint(item: StoreItem): "none" | "update" | "unknown";
+  /**
+   * Upgrade an installed item to the version its marketplace advertises.
+   *
+   * The host does the ordering: new version installed first, previous one
+   * released only when that succeeded. So a failure resolves `ok: false` with
+   * the previous installation still in place (`releasedCount === 0`) — the
+   * caller never has to reason about a half-upgraded item.
+   *
+   * Refuses before the round trip when there is nothing to replace: an item that
+   * is not installed (`not_installed`) or is already current is not a failure of
+   * *this* call, and `updateHint()` is the way to ask first.
    */
-  updateHint(item: StoreItem): "none" | "uninstall_reinstall" | "unknown";
+  update(item: StoreItem, options?: InstallOptions): Promise<StoreOperationOutcome>;
   /**
    * Import (when needed) and install one store item, then wait until it is
    * usable.
@@ -744,6 +889,10 @@ export declare class StoreClient {
    * 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.
+   *
+   * `allowProbe` gates the one kind whose readiness needs a real connection (a
+   * connector); the other kinds answer from local reads, so the cadence does not
+   * apply to them.
    */
   private readiness;
 }
@@ -890,6 +1039,15 @@ export declare class AppServerClient {
   listStore(): Promise<StoreList>;
   /** One-click install: import (when missing) + register in one call. */
   installStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
+  /**
+   * Upgrade an installed entry to the version its marketplace advertises.
+   *
+   * The host installs the new version before releasing the old one, so a failure
+   * leaves the previous installation usable (`released_count: 0` is the machine
+   * readable form of that). Refused for an entry that is not installed — this is
+   * never a second way to install something.
+   */
+  updateStoreEntry(marketplaceId: string, entryName: string): Promise<StoreInstallResult>;
 }
 //#endregion
 //#region src/conversation-handle.d.ts

package/dist/index.mjs

@@ -275,7 +275,7 @@ var WebSocketTransport = class {
 /** 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-8";
+const PROTOCOL_VERSION = "fp-12";
 /**
 * Protocol method → REST route. Verified from handler bodies, not from the
 * route list (a route existing does not prove which method it mirrors).
@@ -470,6 +470,26 @@ const HTTP_ROUTES = {
 		path: "/connectors/:connector_id/auth-logout",
 		source: "connector_auth_logout_route() -> connector_auth_logout_impl"
 	},
+	"connector/credential/get": {
+		verb: "GET",
+		path: "/connectors/:connector_id/credential",
+		source: "connector_credential_get_route() -> connector_credential_get_impl"
+	},
+	"connector/credential/set": {
+		verb: "POST",
+		path: "/connectors/:connector_id/credential",
+		source: "connector_credential_set_route() -> connector_credential_set_impl"
+	},
+	"connector/credential/clear": {
+		verb: "POST",
+		path: "/connectors/:connector_id/credential/clear",
+		source: "connector_credential_clear_route() -> connector_credential_clear_impl"
+	},
+	"connector/register": {
+		verb: "POST",
+		path: "/connectors",
+		source: "register_connector_route() -> register_connector_impl"
+	},
 	"import/run": {
 		verb: "POST",
 		path: "/imports",
@@ -559,6 +579,11 @@ const HTTP_ROUTES = {
 		verb: "POST",
 		path: "/store/:marketplace_id/entries/:entry_name/install",
 		source: "store_install_entry_route() -> store_install_entry_impl"
+	},
+	"store/update-entry": {
+		verb: "POST",
+		path: "/store/:marketplace_id/entries/:entry_name/update",
+		source: "store_update_entry_route() -> store_update_entry_impl"
 	}
 };
 /** Methods that are WebSocket-only by design — named so the error explains itself. */
@@ -1079,6 +1104,13 @@ var ConversationSubscription = class {
 };
 //#endregion
 //#region src/connectors.ts
+/**
+* How long {@link ConnectorClient.waitForAuth} waits by default: the host's own
+* callback window is 120s, so a shorter client budget would give up on flows the
+* host is still willing to finish.
+*/
+const DEFAULT_AUTH_TIMEOUT_MS = 12e4;
+const DEFAULT_AUTH_POLL_MS = 500;
 var ConnectorClient = class {
 	transport;
 	constructor(transport) {
@@ -1112,17 +1144,117 @@ var ConnectorClient = class {
 	test(connectorId) {
 		return this.transport.request("connector/test", { connector_id: connectorId });
 	}
-	/** Check the current OAuth state for a connector. */
+	/**
+	* Check the current OAuth state for a connector.
+	*
+	* Read `error` too: a flow that failed after the browser step is reported as
+	* `state: "not_authenticated"` **plus** `error`, because the wire has no
+	* failing state to flip to. {@link waitForAuth} is the loop that does this.
+	*/
 	authStatus(connectorId) {
 		return this.transport.request("connector/auth/status", { connector_id: connectorId });
 	}
 	/**
+	* The credential form a connector needs filled in, as **this caller** sees it
+	* (doc `34` §6.1).
+	*
+	* `mode` says which kind of authentication applies (`none` / `oauth` / `token`),
+	* `status` whether anything is still missing, and `missing` names the keys.
+	* `fields` is everything needed to render the form — labels, placeholders,
+	* descriptions and the marketplace's "where do I get a key" link, in both
+	* languages. No secret ever comes back: only `plain` fields carry a `value`.
+	*/
+	credentials(connectorId) {
+		return this.transport.request("connector/credential/get", { connector_id: connectorId });
+	}
+	/**
+	* Store what the user typed and get the new state back.
+	*
+	* Only keys the connector's own declaration names are accepted — the form is
+	* the whole write surface. `secret` fields go to the host's credential store
+	* under the caller's own namespace, `plain` fields into the connector's
+	* configuration, so a shared host never resolves one user's token for another.
+	*/
+	setCredentials(connectorId, values) {
+		return this.transport.request("connector/credential/set", {
+			connector_id: connectorId,
+			values
+		});
+	}
+	/**
+	* Forget stored credentials. `keys` omitted = every secret field of this
+	* connector. Idempotent: clearing what is not there succeeds.
+	*/
+	clearCredentials(connectorId, keys) {
+		return this.transport.request("connector/credential/clear", {
+			connector_id: connectorId,
+			...keys ? { keys } : {}
+		});
+	}
+	/**
+	* Register a connector this host never imported — your own MCP server, handed
+	* over together with the template that says what it needs (doc `34` §6.5).
+	*
+	* The **template is the whole declaration**: whatever `${secret:NAME}` the URL,
+	* headers or env name becomes that connector's credential form, so there is no
+	* `token-schema.json` to ship and nothing to install from a marketplace. The
+	* connector's own non-secret settings travel in `values`.
+	*
+	* Secrets do **not** travel here: hand them over with {@link setCredentials},
+	* which keeps exactly one write surface for values. The returned detail already
+	* carries the credential block, so `missing` tells you which keys are still
+	* needed.
+	*
+	* Re-registering the same name updates it; a builtin server's name is refused.
+	* The row is created **disabled** — enabling it still requires a probe that
+	* passes — and this method is on the installation-owner-only surface, because
+	* choosing where the host reaches is the owner's call.
+	*/
+	register(registration) {
+		return this.transport.request("connector/register", registration);
+	}
+	/**
 	* Kick off the OAuth browser flow on the trusted host. Returns the start
-	* acknowledgement immediately; poll `authStatus` until `authenticated`.
+	* acknowledgement immediately; follow it with {@link waitForAuth}.
+	*
+	* `state: "error"` here is a failure that happened **before** the browser was
+	* opened (endpoint discovery, client identity, binding the callback, launching
+	* the browser): nothing was shown to the user, so `error` is the whole story
+	* and there is nothing to wait for.
 	*/
 	authStart(connectorId) {
 		return this.transport.request("connector/auth/start", { connector_id: connectorId });
 	}
+	/**
+	* Wait for an authorization that was started (in the browser, or by a
+	* previous `authStart`) to finish — and **report why** when it does not.
+	*
+	* A hand-rolled `while (state !== "authenticated") poll()` loop ends in "it
+	* never became authenticated", with the reason sitting unread in the status it
+	* already fetched: a token exchange the authorization server refused (a
+	* throttling gateway answers `slow_down`), a callback timeout, a CSRF/path
+	* mismatch. Those land in `authStatus().error` *only*, and the state stays
+	* `not_authenticated` — there is no failing state on the wire.
+	*
+	* Resolves for every domain outcome (`authenticated` / `error` / `timeout`);
+	* rejects only when the status read itself fails (transport or protocol), the
+	* same rule as `connector/call`. The wait is bounded by `timeoutMs`; a caller
+	* that needs to stop earlier can race the returned promise.
+	*/
+	async waitForAuth(connectorId, options = {}) {
+		const deadline = Date.now() + (options.timeoutMs ?? DEFAULT_AUTH_TIMEOUT_MS);
+		const pollMs = options.pollMs ?? DEFAULT_AUTH_POLL_MS;
+		for (;;) {
+			const status = await this.authStatus(connectorId);
+			if (status.state === "authenticated") return { state: "authenticated" };
+			if (status.error) return {
+				state: "error",
+				error: status.error
+			};
+			if (Date.now() >= deadline) return { state: "timeout" };
+			await new Promise((resolve) => setTimeout(resolve, pollMs));
+		}
+	}
 	/** Revoke the OAuth token for a connector. */
 	logout(connectorId) {
 		return this.transport.request("connector/auth/logout", { connector_id: connectorId }).then(() => void 0);
@@ -1542,6 +1674,7 @@ var StoreError = class extends Error {
 const DEFAULT_READY_TIMEOUT_MS = 3e4;
 const DEFAULT_READY_POLL_MS = 400;
 const DEFAULT_READY_POLL_MAX_MS = 4e3;
+const DEFAULT_READY_PROBE_MS = 5e3;
 /** Every string a `LocalizedText` carries, for haystack building. */
 function localizedValues(text) {
 	if (typeof text === "string") return [text];
@@ -1583,11 +1716,13 @@ var StoreClient = class {
 	readyTimeoutMs;
 	readyPollMs;
 	readyPollMaxMs;
+	readyProbeMs;
 	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;
+		this.readyProbeMs = options.readyProbeMs ?? DEFAULT_READY_PROBE_MS;
 	}
 	/** Every item across enabled marketplaces, with install state. */
 	async list() {
@@ -1619,15 +1754,45 @@ var StoreClient = class {
 	/**
 	* 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.
+	* `"none"` means there is nothing to do; `"update"` means the entry is
+	* installed at a different version and `update()` is the action that lands it
+	* (`store/update-entry`, `36` D3); `"unknown"` is returned rather than
+	* guessing when the item carries no snapshot to replace.
 	*/
 	updateHint(item) {
 		if (!item.installed || !item.update_available) return "none";
-		return item.snapshot_id ? "uninstall_reinstall" : "unknown";
+		return item.snapshot_id ? "update" : "unknown";
+	}
+	/**
+	* Upgrade an installed item to the version its marketplace advertises.
+	*
+	* The host does the ordering: new version installed first, previous one
+	* released only when that succeeded. So a failure resolves `ok: false` with
+	* the previous installation still in place (`releasedCount === 0`) — the
+	* caller never has to reason about a half-upgraded item.
+	*
+	* Refuses before the round trip when there is nothing to replace: an item that
+	* is not installed (`not_installed`) or is already current is not a failure of
+	* *this* call, and `updateHint()` is the way to ask first.
+	*/
+	async update(item, options = {}) {
+		this.assertUsable(item, options.signal);
+		this.requireSnapshot(item);
+		const result = await this.host.updateStoreEntry(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),
+			errors: result.errors,
+			warnings: result.warnings,
+			fromVersion: result.previous_version ?? void 0,
+			toVersion: result.version,
+			releasedCount: result.released_count ?? 0
+		};
+		if (options.waitForReady === false) return outcome;
+		return this.awaitReady(outcome, options);
 	}
 	/**
 	* Import (when needed) and install one store item, then wait until it is
@@ -1641,7 +1806,9 @@ var StoreClient = class {
 			snapshotId: result.snapshot_id,
 			reused: result.reused,
 			components,
-			ok: result.errors.length === 0 && components.every((component) => component.ok)
+			ok: result.errors.length === 0 && components.every((component) => component.ok),
+			errors: result.errors,
+			warnings: result.warnings
 		};
 		if (options.waitForReady === false) return outcome;
 		return this.awaitReady(outcome, options);
@@ -1660,7 +1827,9 @@ var StoreClient = class {
 			snapshotId,
 			reused: true,
 			components: [],
-			ok: true
+			ok: true,
+			errors: [],
+			warnings: []
 		};
 		const status = await this.host.uninstallInstall(snapshotId, componentIds);
 		return this.outcomeFromStatus(snapshotId, status, false);
@@ -1680,7 +1849,9 @@ var StoreClient = class {
 			snapshotId,
 			reused: true,
 			components: [],
-			ok: true
+			ok: true,
+			errors: [],
+			warnings: []
 		};
 		const status = enabled ? await this.host.enableInstall(snapshotId, componentIds) : await this.host.disableInstall(snapshotId, componentIds);
 		return this.outcomeFromStatus(snapshotId, status, false);
@@ -1699,11 +1870,14 @@ var StoreClient = class {
 	}
 	outcomeFromStatus(snapshotId, status, reused) {
 		const components = status.outcomes ?? [];
+		const errors = status.errors ?? [];
 		return {
 			snapshotId,
 			reused,
 			components,
-			ok: (status.errors ?? []).length === 0 && components.every((component) => component.ok)
+			ok: errors.length === 0 && components.every((component) => component.ok),
+			errors,
+			warnings: []
 		};
 	}
 	/**
@@ -1721,11 +1895,15 @@ var StoreClient = class {
 		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 nextProbeAt = 0;
 		let last = status.components;
 		for (;;) {
+			const now = Date.now();
+			const allowProbe = now >= nextProbeAt;
+			if (allowProbe) nextProbeAt = now + this.readyProbeMs;
 			const blocked = (await Promise.all(last.filter((component) => component.state !== "not-installed").map(async (component) => ({
 				component,
-				verdict: await this.readiness(component)
+				verdict: await this.readiness(component, allowProbe)
 			})))).find((entry) => !entry.verdict.ready);
 			if (!blocked) return {
 				...outcome,
@@ -1755,8 +1933,12 @@ var StoreClient = class {
 	* 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.
+	*
+	* `allowProbe` gates the one kind whose readiness needs a real connection (a
+	* connector); the other kinds answer from local reads, so the cadence does not
+	* apply to them.
 	*/
-	async readiness(component) {
+	async readiness(component, allowProbe) {
 		try {
 			switch (component.kind) {
 				case "skill": return (await this.host.skills.list()).some((skill) => skill.name === component.name) ? { ready: true } : { ready: false };
@@ -1765,8 +1947,9 @@ var StoreClient = class {
 					await this.host.teams.get(component.id);
 					return { ready: true };
 				case "connector": {
-					if ((await this.host.connectors.test(component.id)).success) return { ready: true };
+					if (allowProbe && (await this.host.connectors.test(component.id)).success) return { ready: true };
 					const status = await this.host.connectors.status(component.id);
+					if (status.status === "connected") return { ready: true };
 					if (status.status === "authorization_required" || status.status === "reauthorization_required") return {
 						ready: false,
 						terminal: "authorization_required"
@@ -2053,6 +2236,20 @@ var AppServerClient = class {
 			entry_name: entryName
 		});
 	}
+	/**
+	* Upgrade an installed entry to the version its marketplace advertises.
+	*
+	* The host installs the new version before releasing the old one, so a failure
+	* leaves the previous installation usable (`released_count: 0` is the machine
+	* readable form of that). Refused for an entry that is not installed — this is
+	* never a second way to install something.
+	*/
+	async updateStoreEntry(marketplaceId, entryName) {
+		return this.transport.request("store/update-entry", {
+			marketplace_id: marketplaceId,
+			entry_name: entryName
+		});
+	}
 };
 //#endregion
 //#region src/conversation-handle.ts

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@flowy-agent-store/client",
-  "version": "0.1.0-beta.7",
+  "version": "0.1.0-beta.8",
   "description": "Transport-agnostic App Server client (docs/agent-store/07 §2.2)",
   "type": "module",
   "license": "Apache-2.0",
@@ -25,7 +25,7 @@
     "dist"
   ],
   "dependencies": {
-    "@flowy-agent-store/protocol": "0.1.0-beta.7"
+    "@flowy-agent-store/protocol": "0.1.0-beta.8"
   },
   "scripts": {
     "build": "tsdown",