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

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, 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;
 /**
@@ -193,6 +193,17 @@ export declare class AgentClient {
   list(): Promise<AgentSummary[]>;
   /** Fetch one AgentDefinition; raw prompts never cross the wire. */
   get(agentId: string): Promise<AgentDetail>;
+  /**
+   * Export one AgentDefinition as a portable {@link ExpertPack}.
+   *
+   * Requires WebSocket: like the rest of this family, `agent/export` has no HTTP
+   * route. The expert must be installed and enabled, or the host answers
+   * `agent_not_installed` / `agent_disabled`; a host whose `[expert_export]`
+   * table refuses the id answers `policy_denied`. Check
+   * `capabilities.expert_export` for the *seam* — it does not promise this id is
+   * exportable.
+   */
+  export(agentId: string): Promise<ExpertPack>;
 }
 //#endregion
 //#region src/conversations.d.ts
@@ -363,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);
@@ -386,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>;
   /**
@@ -610,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. */
@@ -623,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`).
@@ -631,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.
@@ -642,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>;
@@ -665,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[]>;
@@ -685,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.
@@ -733,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;
 }
@@ -745,6 +905,16 @@ export declare class TeamClient {
   list(): Promise<TeamSummary[]>;
   /** Fetch one TeamDefinition; planning-context bodies are never returned. */
   get(teamId: string): Promise<TeamDetail>;
+  /**
+   * Export one TeamDefinition as a portable {@link ExpertPack}, with every member
+   * expanded and the **leader first**.
+   *
+   * All-or-nothing: if any member is uninstalled, disabled, or refused by the
+   * host's `[expert_export]` table, the whole call fails rather than returning a
+   * partial roster — the same posture `team/run` takes before it creates
+   * anything. `teamVersion` is an optional pin; a mismatch is `version_mismatch`.
+   */
+  export(teamId: string, teamVersion?: string): Promise<ExpertPack>;
 }
 //#endregion
 //#region src/models.d.ts
@@ -869,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, 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;
 /**
@@ -193,6 +193,17 @@ export declare class AgentClient {
   list(): Promise<AgentSummary[]>;
   /** Fetch one AgentDefinition; raw prompts never cross the wire. */
   get(agentId: string): Promise<AgentDetail>;
+  /**
+   * Export one AgentDefinition as a portable {@link ExpertPack}.
+   *
+   * Requires WebSocket: like the rest of this family, `agent/export` has no HTTP
+   * route. The expert must be installed and enabled, or the host answers
+   * `agent_not_installed` / `agent_disabled`; a host whose `[expert_export]`
+   * table refuses the id answers `policy_denied`. Check
+   * `capabilities.expert_export` for the *seam* — it does not promise this id is
+   * exportable.
+   */
+  export(agentId: string): Promise<ExpertPack>;
 }
 //#endregion
 //#region src/conversations.d.ts
@@ -363,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);
@@ -386,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>;
   /**
@@ -610,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. */
@@ -623,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`).
@@ -631,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.
@@ -642,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>;
@@ -665,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[]>;
@@ -685,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.
@@ -733,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;
 }
@@ -745,6 +905,16 @@ export declare class TeamClient {
   list(): Promise<TeamSummary[]>;
   /** Fetch one TeamDefinition; planning-context bodies are never returned. */
   get(teamId: string): Promise<TeamDetail>;
+  /**
+   * Export one TeamDefinition as a portable {@link ExpertPack}, with every member
+   * expanded and the **leader first**.
+   *
+   * All-or-nothing: if any member is uninstalled, disabled, or refused by the
+   * host's `[expert_export]` table, the whole call fails rather than returning a
+   * partial roster — the same posture `team/run` takes before it creates
+   * anything. `teamVersion` is an optional pin; a mismatch is `version_mismatch`.
+   */
+  export(teamId: string, teamVersion?: string): Promise<ExpertPack>;
 }
 //#endregion
 //#region src/models.d.ts
@@ -869,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