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

package/dist/index.d.mts

@@ -0,0 +1,1303 @@
+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, ImportAssetList, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallOutcome, InstallRequest, InstallResult, InstallStatus, MarketSettings, MarketSettingsPatch, 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;
+/**
+ * True for loopback-only URLs (`127.0.0.0/8`, `::1`, `localhost`).
+ * SDK spawn contract (docs/agent-store/12-sdk-packaging.md P0-4): an SDK
+ * must only speak the local-trusted mode over loopback; anything else is
+ * rejected before connecting.
+ */
+export declare function isLoopbackUrl(raw: string): boolean;
+/**
+ * Transport abstraction (docs/agent-store/07-typescript-sdk.md §2.3).
+ * A transport only frames JSON-RPC over some channel; the
+ * initialize → initialized → ready lifecycle lives in `AppServerClient`,
+ * so business code never knows whether it runs over WebSocket (browser),
+ * stdio (Node/CLI, future) or a one-shot HTTP binding.
+ */
+/**
+ * Lifecycle of the underlying channel. `open` is emitted on every successful
+ * dial (the first one included), `closed` only when an established connection
+ * is lost — so `closed` → `open` is exactly a reconnect.
+ */
+export type TransportLifecycle = "open" | "closed";
+export type TransportLifecycleListener = (state: TransportLifecycle) => void;
+export interface Transport {
+  connect(): Promise<void>;
+  request<T>(method: string, params: unknown): Promise<T>;
+  notify(method: string, params: unknown): void;
+  onNotification(listener: NotificationListener): () => void;
+  close(): void;
+  /**
+   * Optional: observe the channel lifecycle so a host can show a disconnect
+   * banner and re-arm subscriptions on reconnect (docs/agent-store/16 T8/W8).
+   * Custom transports may omit it.
+   */
+  onLifecycle?(listener: TransportLifecycleListener): () => void;
+}
+export interface TransportOptions {
+  requestTimeoutMs?: number;
+  /** Max time `connect()` may stay unopened before failing (default 10s). */
+  connectTimeoutMs?: number;
+  token?: string;
+}
+export declare class WebSocketTransport implements Transport {
+  private socket;
+  private nextId;
+  private pending;
+  private listeners;
+  private lifecycleListeners;
+  private lifecycle;
+  private closedByCaller;
+  /** Single in-flight connect shared by concurrent callers; null once settled. */
+  private connecting;
+  readonly requestTimeoutMs: number;
+  readonly connectTimeoutMs: number;
+  readonly url: string;
+  readonly token?: string;
+  constructor(url: string, options?: TransportOptions);
+  get connected(): boolean;
+  connect(): Promise<void>;
+  request<T>(method: string, params: unknown): Promise<T>;
+  notify(method: string, params: unknown): void;
+  onNotification(listener: NotificationListener): () => void;
+  /**
+   * Observe the channel lifecycle. `closed` is only reported when an
+   * established connection is lost (a failed first dial is not a disconnect),
+   * and `open` follows it on the next successful dial — that pair is what a
+   * host should treat as a reconnect. Unlike `onNotification`, these listeners
+   * survive `close()`, since they exist to drive the reconnection itself.
+   */
+  onLifecycle(listener: TransportLifecycleListener): () => void;
+  close(): void;
+  private setLifecycle;
+  /** Detach the current socket (if any) and close it; its later events are ignored. */
+  private detachSocket;
+  /** Settle the in-flight `connect()` successfully, when there is one. */
+  private resolveConnect;
+  /** Fail the in-flight `connect()`, when there is one. */
+  private rejectConnect;
+  private requireSocket;
+  private handleMessage;
+  private failAllPending;
+}
+//#endregion
+//#region src/http-transport.d.ts
+type Verb = "GET" | "POST" | "DELETE";
+interface HttpRoute {
+  verb: Verb;
+  /** `:name` segments are filled from the same-named param and dropped from the body/query. */
+  path: string;
+  /** Params carried in the query string (GET, and the query-configured POSTs). */
+  query?: readonly string[];
+  /** Params carried in the JSON body; every other param goes here for POST. */
+  body?: readonly string[];
+  /** Where this mapping was verified in the server source. */
+  source: string;
+}
+export interface HttpTransportOptions {
+  /**
+   * App Server base URL. Either the full `…/api/app-server` root or a
+   * `ws(s)://…/api/app-server/ws` endpoint (the `/ws` segment is stripped).
+   */
+  baseUrl: string;
+  /** Bearer token for the handshake (optional; hosts may inject auth instead). */
+  token?: string;
+  /** Injected `fetch` (defaults to the global); tests pass a stub. */
+  fetch?: typeof fetch;
+  /** Per-call budget covering handshake + business call (default 30s). */
+  requestTimeoutMs?: number;
+  /** Client name/version announced on `initialize`. */
+  client?: {
+    name: string;
+    version: string;
+  };
+  /** Client capabilities block echoed on `initialize` (hosts pass their own). */
+  capabilities?: unknown;
+}
+export declare class HttpTransport implements Transport {
+  private readonly routes;
+  private readonly options;
+  private closed;
+  constructor(options: HttpTransportOptions, routes?: Record<string, HttpRoute>);
+  /**
+   * No-op: the HTTP binding handshakes per call (`05` §2.1.1), so there is no
+   * connection to open. Kept for `Transport` compatibility.
+   */
+  connect(): Promise<void>;
+  /**
+   * Perform one business call over its own handshake.
+   *
+   * Throws `TransportError("send", …)` for a method with no HTTP binding —
+   * never a silent fallback to another binding.
+   */
+  request<T>(method: string, params: unknown): Promise<T>;
+  /**
+   * Not supported: HTTP carries no server-push. Throws instead of pretending.
+   */
+  notify(method: string, _params: unknown): void;
+  /**
+   * Returns a no-op unsubscribe: this binding receives **no** notifications.
+   *
+   * Not equivalent to the WebSocket binding — callers that need live events
+   * must use `WebSocketTransport` (or run both).
+   */
+  onNotification(_listener: NotificationListener): () => void;
+  /** No-op: every call is independent, so nothing is held open. */
+  close(): void;
+  /**
+   * One-shot handshake: `POST /initialize` (connection id header) →
+   * `POST /initialized`. Returns the connection id.
+   *
+   * Public because host-side services that sit *outside* the protocol surface
+   * (`/api/fs/*`, the HTTP-only `POST /workspaces` register route) still need a
+   * ready connection id; they are not protocol methods, so they cannot go
+   * through `request()`.
+   */
+  openConnection(): Promise<string>;
+  private splitParams;
+  private fetchWithTimeout;
+  /** 2xx → result body; otherwise the server's wire error becomes an `AppServerError`. */
+  private readResult;
+  private baseUrl;
+}
+/**
+ * Turn an HTTP failure body into the SDK error model.
+ *
+ * Shared by this transport and by host-side helpers (webui `lib/client.ts`) so
+ * a second spelling of the wire-error mapping cannot drift. Two wire contracts
+ * reach this function, both of them `AppError` on the server:
+ *
+ * - the App Server emits `{code, message, retryable, details, request_id}`
+ *   (`into_wire_error`), which is exactly the `AppServerError` shape;
+ * - the standalone host file service (`/api/fs/*`) emits the `ErrorResponse`
+ *   envelope `{success: false, error, code, details?}` — same error, another
+ *   spelling: `error` carries the human message, and there is no retry hint, so
+ *   a 5xx status stays the retry signal.
+ *
+ * Anything else becomes a retryable-on-5xx `TransportError`.
+ */
+export declare function appServerErrorFromWire(payload: unknown, status: number, context?: string): unknown;
+/** Exposed for tests and docs (R5): the verified method → route table. */
+export declare function httpRouteTable(): Readonly<Record<string, {
+  verb: string;
+  path: string;
+  source: string;
+}>>;
+//#endregion
+//#region src/agents.d.ts
+export declare class AgentClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List Agent Store AgentDefinitions (public summaries only). */
+  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
+/**
+ * Options for `send()`.
+ *
+ * Two scopes, deliberately different (doc `27` §4.1 and doc `29` §5.1):
+ *
+ * - **per turn** — `attachments` and `mentions` are this turn's payload, and
+ *   nothing else changes;
+ * - **per conversation, taking effect this turn** — `model` and
+ *   `reasoningEffort` are *sticky*: they are written to the conversation and
+ *   every later turn keeps them, because the Nomi runtime is built from the
+ *   persisted row. The host refuses them while a turn is running (`conflict`).
+ *
+ * Every field is **additive**: absent means the exact wire shape callers sent
+ * before that field existed, and a plain `send()` never writes the conversation.
+ */
+export interface ConversationSendOptions {
+  /** Absolute paths inside the conversation's workspace (images only). */
+  attachments?: string[];
+  /**
+   * Skills to mount for **this turn** (`kind: "skill"`).
+   *
+   * The ids are `skill/list`'s ids (the skill's own name, not an
+   * `install/status` component id). A turn is the only scope a Skill has here:
+   * the conversation's frozen snapshot is create-time and immutable.
+   */
+  mentions?: MentionRef[];
+  /**
+   * Model to switch the conversation to **from this turn on** (doc `29` §5.1).
+   *
+   * Sticky, not per-turn: the Nomi runtime is built from the persisted row, so
+   * the value is written to the conversation and every later turn keeps it.
+   * Omit it and the conversation's current model stays untouched.
+   */
+  model?: ProviderWithModel;
+  /**
+   * Reasoning level to switch the conversation to **from this turn on**
+   * (doc `29` §5.1). Same sticky scope as `model`.
+   */
+  reasoningEffort?: string;
+}
+export declare class ConversationClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  create(input: ConversationCreateInput): Promise<ConversationView>;
+  update(conversationId: string, input: ConversationUpdateInput): Promise<ConversationView>;
+  modelOptions(): Promise<ConversationModelOptions>;
+  list(limit?: number): Promise<ConversationView[]>;
+  get(conversationId: string): Promise<ConversationView>;
+  messages(query: ConversationMessagesQuery): Promise<ConversationMessagesPage>;
+  /**
+   * R15（W10）：`attachments` 是**会话工作区内的绝对路径**（图片附件）。
+   * doc `27` §4.1：`mentions` 是**本轮挂载的技能**（`kind: "skill"`）——技能的正文与
+   * 不可变快照都随这一轮走；`agent` / `connector` 在 send 上没有载体，服务端会以
+   * `invalid_request` **明确拒绝**（不是静默不挂）。
+   *
+   * 两者缺省都不上 wire，保持老调用方的形状逐字不变；服务端只接受会话工作区内的真实
+   * 文件（越界 / 相对路径 / 不存在一律拒），准入见 `nomifun-app-server` 的
+   * `resolve_conversation_attachments` 与 `send_mention_skills`。
+   *
+   * 第 4 个参数同时接受旧的 `string[]`（附件）与选项对象——再堆一个位置参数会让调用点
+   * 变成一串没有名字的布尔/数组。
+   */
+  send(conversationId: string, content: string, idempotencyKey: string, options?: string[] | ConversationSendOptions): Promise<ConversationSendReceipt>;
+  cancel(conversationId: string): Promise<ConversationView>;
+  delete(conversationId: string): Promise<{
+    conversation_id: string;
+    deleted: boolean;
+  }>;
+  /**
+   * Subscribe to one conversation's realtime stream (doc `16` R1).
+   *
+   * `options.fetchMessages` is what makes auto catch-up possible: a detected
+   * sequence gap or a `conversation/resync-required` triggers one transcript
+   * fetch whose result is handed to `onBackfill`. Conversations have no event
+   * replay API (`05` §「V1 不提供 after_cursor 事件追平」), so the transcript is
+   * the recovery medium — unlike Runs, where `run/events` replays the events
+   * themselves.
+   */
+  follow(conversationId: string, options?: ConversationFollowOptions): Promise<ConversationSubscription>;
+}
+export type ConversationEventListener = (event: ConversationEvent) => void;
+export type ConversationResyncListener = (reason: string) => void;
+export type ConversationErrorListener = (error: unknown) => void;
+/** Transcript snapshot handed back after a detected gap / resync (R1). */
+export interface ConversationBackfill {
+  conversationId: string;
+  /** `gap` or the server's `conversation/resync-required` reason. */
+  reason: string;
+  /** Latest transcript page, newest last (`conversation/messages`). */
+  messages: ConversationMessage[];
+  /** Server-computed: an older page still exists. */
+  hasMore: boolean;
+}
+export type ConversationBackfillListener = (backfill: ConversationBackfill) => void;
+/** Options for `follow()` — mirrors the Run subscription's `FollowOptions`. */
+export interface ConversationFollowOptions {
+  /**
+   * Fetch the transcript automatically after a gap / resync (default `true`).
+   * Needs `fetchMessages`; when absent only `onResync` fires.
+   */
+  autoResync?: boolean;
+  /** Events held before the first `onEvent` listener attaches (default 256). */
+  pendingLimit?: number;
+  /** Transcript fetcher; `follow()` wires the real one. */
+  fetchMessages?: (conversationId: string) => Promise<ConversationMessagesPage>;
+}
+export declare class ConversationSubscription {
+  private readonly transport;
+  readonly conversationId: string;
+  private readonly options;
+  private events;
+  private resyncs;
+  private errors;
+  private backfills;
+  private closed;
+  private lastSeenSequence;
+  private removeListener;
+  /**
+   * `follow()` resolves as soon as the server acknowledged the subscription,
+   * but the caller attaches listeners one tick later. Events landing in that
+   * window used to be dropped silently; they are held here (oldest first) and
+   * flushed to the first `onEvent` listener.
+   */
+  private pending;
+  private pendingDropped;
+  private backfillInFlight;
+  constructor(transport: Transport, conversationId: string, options?: ConversationFollowOptions);
+  get lastSequence(): number;
+  /** Events dropped because nobody was listening and the buffer was full. */
+  get droppedPendingCount(): number;
+  onEvent(listener: ConversationEventListener): () => void;
+  onResync(listener: ConversationResyncListener): () => void;
+  /**
+   * Auto catch-up result (R1). Fires only when `autoResync` is on and the
+   * transcript fetch succeeded; the listener owns replacing the transcript.
+   */
+  onBackfill(listener: ConversationBackfillListener): () => void;
+  /**
+   * Failures that used to be swallowed: the catch-up fetch, and a failed
+   * re-subscribe during `rearm()`. Listener isolation keeps one bad listener
+   * from hiding the error from the others.
+   */
+  onError(listener: ConversationErrorListener): () => void;
+  close(): Promise<void>;
+  /**
+   * Re-arm after a reconnect (docs/agent-store/16 T8): re-register the
+   * notification listener, reset the cursor and re-issue
+   * `conversation/subscribe`. The server restarts a conversation's sequence at
+   * 1 for a fresh subscription, which is exactly why the cursor resets. On a
+   * failed re-subscribe the error reaches `onError` and the caller can still
+   * backfill the outage window via `conversation/messages`.
+   */
+  rearm(): Promise<void>;
+  private dispatch;
+  private buffer;
+  private deliver;
+  private emitResync;
+  private emitError;
+  /**
+   * One in-flight catch-up at a time: a burst of resync signals collapses into
+   * a single transcript fetch (the fetch itself returns the newest page, so the
+   * result supersedes every signal that arrived before it).
+   */
+  private requestBackfill;
+}
+//#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);
+  /** List the Agent Store Connector catalog (public summaries only). */
+  list(): Promise<ConnectorSummary[]>;
+  /** Fetch one Connector detail: namespaced tools + auth state. */
+  get(connectorId: string): Promise<ConnectorDetail>;
+  /** Combined auth × probe status. `connected` only when auth is ready AND the last probe succeeded. */
+  status(connectorId: string): Promise<ConnectorStatusView>;
+  /**
+   * Run a connection probe and report what the connector currently offers —
+   * including each tool's `input_schema`.
+   *
+   * It really connects: a stdio connector gets its child process spawned, an
+   * HTTP/SSE one gets `initialize` + `tools/list`. The result is **persisted**,
+   * so this is also what refreshes the tool list `get()` reads back.
+   *
+   * Named `test` and not `probe` on purpose: this repo's split is `test` for the
+   * action (wire `connector/test`, `test_connection`) and `probe` for its
+   * artifact (`ConnectorProbeResult`, `probe_status`), and every method here is
+   * the last segment of its wire method.
+   */
+  test(connectorId: string): Promise<ConnectorProbeResult>;
+  /**
+   * 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; 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>;
+  /**
+   * Run one tool on a registered connector, through the host's own connection.
+   *
+   * The host holds the transport, its headers and its OAuth token; this sends a
+   * tool name and an argument object and nothing else — you cannot name a URL,
+   * a command or a header. Whether the pair is callable at all is the host's
+   * `[connector_proxy]` policy: once its operator turns the proxy on, the
+   * enabled connectors are callable, and `allow` / `deny` are that operator's
+   * optional narrowing and subtraction. So `policy_denied` means either that
+   * the host never turned the proxy on, or that this pair was narrowed out or
+   * explicitly denied — not that a tool name was misspelled in a list you were
+   * supposed to maintain.
+   *
+   * Arguments are passed through verbatim (there is no client-side schema
+   * check); `get()` / `test()` return each tool's `input_schema` so you can see
+   * what it takes, and a parameter the server rejects comes back as
+   * `is_error: true`, not as a rejected promise.
+   *
+   * Resolves even when the tool itself failed — check `is_error`. It rejects
+   * only when the call never reached the tool: `connector_call_timeout`,
+   * `connector_call_failed`, `response_too_large`, `connector_unavailable`,
+   * `policy_denied`, `not_found`.
+   */
+  call(connectorId: string, tool: string, args?: unknown): Promise<ConnectorCallResult>;
+}
+//#endregion
+//#region src/runs.d.ts
+export declare class RunClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** Start an Agent run and return its asynchronous receipt. */
+  agent(input: AgentRunInput): Promise<RunReceipt>;
+  /**
+   * Start a Team run (`16` §7 决策 3): the server creates the Leader
+   * Conversation, materializes/binds the Team's execution template and returns
+   * the public run id of the execution the Leader started.
+   *
+   * The receipt is `TeamRunReceipt`, not `RunReceipt` — a Team Run has no lead
+   * preset revision/digest to report. Member pool and concurrency limits are not
+   * inputs; sending `planning` is rejected as `invalid_request`.
+   */
+  team(input: TeamRunInput): Promise<TeamRunReceipt>;
+  /** Read the authoritative run state. */
+  get(runId: string): Promise<RunView>;
+  /** Read the terminal result (fails until the run reaches a terminal state). */
+  result(runId: string): Promise<RunResult>;
+  /**
+   * Read the authoritative plan / step snapshot (W4 / W6, resolves D-W6-1):
+   * titles, statuses, retries with their reason, errors and timings — none of
+   * which the append-only event log carries.
+   */
+  plan(runId: string): Promise<RunPlan>;
+  /** Replay persisted events after a cursor. */
+  events(query: RunEventsQuery): Promise<RunEvent[]>;
+  /** Request cancellation; the terminal state is confirmed by events/run/get. */
+  cancel(input: CancelRunInput): Promise<RunView>;
+  /**
+   * Inject steering text into the currently active step of a running Agent
+   * (runtime durable conversation effect; server resolves the opaque step).
+   */
+  steer(input: SteerRunInput): Promise<RunView>;
+  /**
+   * Answer the pending decision of a `waiting_input` attempt.
+   *
+   * The three `expected*Version` tokens are mandatory CAS inputs, normally the
+   * ones projected on the pending `approval.requested` event. The server passes
+   * them straight to the engine's single answer gate, so a stale token is a
+   * `conflict`, never a silent overwrite. There is no `always_allow` here: the
+   * desktop confirmation route's approve-all flag is not part of this protocol.
+   */
+  answerDecision(input: AnswerDecisionInput): Promise<RunView>;
+  /** Subscribe to best-effort realtime events for one run. */
+  follow(runId: string, options?: FollowOptions): Promise<EventSubscription>;
+}
+export interface FollowOptions {
+  /** Silent cursor catch-up after subscribe (default true). */
+  catchUp?: boolean;
+  /** Automatic `run/events`追平 on `run/resync-required` (default true). */
+  autoResync?: boolean;
+}
+export type RunEventListener = (event: RunEvent) => void;
+export type RunResyncListener = (params: {
+  run_ids: string[];
+  reason: string;
+}) => void;
+export type RunErrorListener = (error: unknown) => void;
+export declare class EventSubscription {
+  private readonly transport;
+  readonly runId: string;
+  private readonly fetchAfter?;
+  private eventListeners;
+  private resyncListeners;
+  private errorListeners;
+  private closed;
+  private unsubscribeNotification;
+  private lastSeenSequence;
+  private seenSequences;
+  private resyncInFlight;
+  private readonly autoResync;
+  constructor(transport: Transport, runId: string, fetchAfter?: ((afterSequence: number) => Promise<RunEvent[]>) | undefined, options?: FollowOptions);
+  onEvent(listener: RunEventListener): () => void;
+  onResync(listener: RunResyncListener): () => void;
+  onError(listener: RunErrorListener): () => void;
+  get lastSequence(): number;
+  close(): Promise<void>;
+  private dispatch;
+  /**
+   * Silent cursor baseline: mark already-persisted events seen WITHOUT
+   * dispatching, so the first resync never replays history as "new".
+   * For explicit history use `RunClient.events({ afterSequence: 0 })`.
+   */
+  catchUp(): Promise<void>;
+  /**
+   *追平 missed events via `run/events` after the cursor. Returned (and
+   * dispatched) in sequence order, deduplicated against live delivery.
+   * Concurrent calls share one flight.
+   */
+  resync(): Promise<RunEvent[]>;
+  /**
+   * Re-arm after the connection was re-established (docs/agent-store/16 T8).
+   * A new socket means the server dropped its subscriptions and the transport
+   * dropped its notification listeners, so this:
+   *
+   * 1. re-registers this subscription's notification listener,
+   * 2. resets the cursor to 0 and forgets the dedupe set, then
+   * 3. re-issues `run/subscribe` and replays **all** persisted events.
+   *
+   * The replay is deliberate (the plan's "重连后重置 lastSeenSequence"): a
+   * consumer must dedupe by `sequence`, since events seen before the outage
+   * are delivered again. Call it only once the session handshake has completed
+   * again — the transport's `open` event fires before `initialize`. A no-op
+   * once closed.
+   */
+  rearm(): Promise<RunEvent[]>;
+  private markSeen;
+  private emitEvent;
+  private emitError;
+  /** Forward transport-level errors into subscription error listeners. */
+  deliverError(error: unknown): void;
+}
+//#endregion
+//#region src/skills.d.ts
+export declare class SkillClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List the Agent Store Skill catalog (public summaries only). */
+  list(): Promise<SkillSummary[]>;
+  /** Fetch one Skill detail; instructions are a bounded public summary. */
+  get(skillId: string): Promise<SkillDetail>;
+  /**
+   * Every readable file inside a Skill's directory, with a tree digest.
+   *
+   * This is the only way to learn what a Skill actually ships: `get()` returns
+   * a bounded summary of `SKILL.md` and says nothing about the `references/`,
+   * `scripts/`, `templates/` and `assets/` beside it. Check
+   * `capabilities.skill_files` first — a host may wire the catalog without
+   * this face, in which case it answers `unsupported_operation`.
+   */
+  files(skillId: string): Promise<SkillFileList>;
+  /**
+   * One skill file's bytes, over the WebSocket binding.
+   *
+   * The wire carries base64 because JSON has no byte string, so this decodes
+   * back to `Uint8Array` for you. The HTTP route
+   * (`GET /api/app-server/skills/{id}/files/{path}`) returns the raw body
+   * instead, but that is deliberately not on the typed client's JSON
+   * transport — use this method, or `fetch` the route directly if you are on a
+   * host token.
+   */
+  readFile(skillId: string, path: string): Promise<Uint8Array>;
+  /** Same as {@link readFile}, but also returns the server's content type. */
+  readFileWithType(skillId: string, path: string): Promise<SkillFileContent>;
+}
+/**
+ * Decode base64 to bytes (shared with the snapshot asset face, doc 38).
+ *
+ * `atob` is used when present (browsers, Bun, Node 16+) and a manual decode
+ * otherwise, so the package keeps working on a bare Node without a DOM lib.
+ */
+export declare function decodeBase64(content: string): Uint8Array;
+//#endregion
+//#region src/store.d.ts
+/** Why a `waitForReady` check ended without every component being usable. */
+export type StoreReadyIssue =
+/** The host never reported the component ready inside the timeout. */
+"ready_timeout" |
+/** A connector needs the OAuth browser flow; the caller must drive it. */
+"authorization_required";
+/** Branchable client-side failures. Server-side failures arrive as outcomes. */
+export type StoreErrorCode = "not_installed" | "item_blocked" | "aborted";
+export declare class StoreError extends Error {
+  readonly code: StoreErrorCode;
+  constructor(code: StoreErrorCode, message: string);
+}
+export interface InstallOptions {
+  /**
+   * Wait until every component is actually usable before resolving.
+   *
+   * Defaults to `true` because a resolved `install()` that is not yet usable is
+   * the single most misleading thing this surface could do: a skill is usable
+   * as soon as it is copied, but a connector is not usable until the server has
+   * been switched on and probed.
+   */
+  waitForReady?: boolean;
+  /** Readiness budget. Defaults to `StoreClientOptions.readyTimeoutMs`. */
+  timeoutMs?: number;
+  signal?: AbortSignal;
+}
+export interface UninstallOptions {
+  /** Narrow the release to these component ids (default: every installed one). */
+  componentIds?: string[];
+}
+export interface SetEnabledOptions {
+  /** Narrow the state change to these component ids (default: all installed). */
+  componentIds?: string[];
+}
+export interface StoreClientOptions {
+  /** Default readiness budget in ms. */
+  readyTimeoutMs?: number;
+  /** 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. */
+  snapshotId: string | null;
+  /** The server reported there was nothing to do. */
+  reused: boolean;
+  /**
+   * The host's own count of components it installed, when the verb reports one.
+   *
+   * Absent means "this verb does not say", never "it installed nothing" — the
+   * same rule [`StoreOperationOutcome.warnings`] follows. `install()` /
+   * `update()` pass it through; the uninstall / enable / disable projections
+   * carry no such number.
+   */
+  installedCount?: number;
+  /**
+   * The server's per-component detail, verbatim. Empty on a host that predates
+   * `outcomes` — treat that as "no detail available", never as "nothing ran".
+   */
+  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`).
+   */
+  ready?: boolean;
+  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.
+ *
+ * Declared structurally rather than imported so this module does not depend on
+ * the client that owns it (the client imports this one). It also documents the
+ * exact surface the store layer is allowed to lean on.
+ */
+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>;
+  uninstallInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  readonly skills: {
+    list(): Promise<SkillSummary[]>;
+  };
+  readonly agents: {
+    get(id: string): Promise<AgentDetail>;
+  };
+  readonly teams: {
+    get(id: string): Promise<TeamDetail>;
+  };
+  readonly connectors: {
+    status(id: string): Promise<ConnectorStatusView>;
+    test(id: string): Promise<ConnectorProbeResult>;
+  };
+}
+export declare class StoreClient {
+  private readonly host;
+  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[]>;
+  /** Case-insensitive substring search over the fields a user can see. */
+  search(query: string, filter?: {
+    kind?: StoreItemKind;
+  }): Promise<StoreItem[]>;
+  /** Items currently installed on this host. */
+  installed(): Promise<StoreItem[]>;
+  /**
+   * The installed item that owns a given connector, or `null` when none does.
+   *
+   * A store item carries no field for the connector it installed — its
+   * `entry_name` is the *market's* name (real example: the entry
+   * `fenbi-baokao-decision` installs a server called `fenbi_mcp`), so a caller
+   * holding an id from `connectors.list()` cannot reach the `StoreItem` that
+   * `setEnabled()` / `uninstall()` require. `search()` cannot bridge that
+   * either: it is a substring scan over catalogue text, and the runtime name is
+   * not in it. This is the link, walked through the snapshot each installed item
+   * already points at.
+   *
+   * Both identifiers a caller may hold are accepted: the connector's own `id`
+   * (`connector/get`) and its `name` (`fenbi_mcp` — the MCP row's name and the
+   * tool namespace's middle segment). Matching is exact; call `list()`/`search()`
+   * when the question is "which catalogue entries mention X".
+   */
+  findByConnector(connectorId: string): Promise<StoreItem | null>;
+  /**
+   * Installed items whose marketplace offers a different version.
+   *
+   * Both conditions matter: `update_available` is computed from the imported
+   * snapshot even when nothing is installed, so filtering on it alone would
+   * report an "update" for an entry the user has never installed.
+   */
+  checkUpdates(): Promise<StoreItem[]>;
+  /**
+   * What a caller can offer for an item's pending update.
+   *
+   * `"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.
+   */
+  update(item: StoreItem, options?: InstallOptions): Promise<StoreOperationOutcome>;
+  /**
+   * Import (when needed) and install one store item, then wait until it is
+   * usable.
+   */
+  install(item: StoreItem, options?: InstallOptions): Promise<StoreOperationOutcome>;
+  /**
+   * Release an item's runtime artifacts and clear its install record.
+   *
+   * The server only clears the record for components it actually released, so a
+   * partial failure leaves `ok: false` with the failing component named — and
+   * the item stays installed, which is what makes a retry meaningful.
+   */
+  uninstall(item: StoreItem, options?: UninstallOptions): Promise<StoreOperationOutcome>;
+  /**
+   * Switch an item's components on or off.
+   *
+   * Idempotent: the server sets the state it is asked for instead of toggling.
+   * A skill reports `skill_disable_flag_only` because the skill corpus has no
+   * enable state — that code is passed through, not swallowed, so a caller can
+   * tell "switched off" from "marked in the catalogue".
+   */
+  setEnabled(item: StoreItem, enabled: boolean, options?: SetEnabledOptions): Promise<StoreOperationOutcome>;
+  private assertUsable;
+  private requireSnapshot;
+  private installedComponentIds;
+  private outcomeFromStatus;
+  /**
+   * Poll until every component of the snapshot is usable.
+   *
+   * A timeout does **not** discard the install: the caller gets the successful
+   * install plus `ready: false` and `readyIssue: "ready_timeout"`, so a slow
+   * connector never turns into "the install failed".
+   */
+  private awaitReady;
+  /**
+   * Is this one component usable yet?
+   *
+   * Each kind answers with the narrowest read the protocol already offers. An
+   * unknown kind is reported ready rather than blocking: this layer cannot judge
+   * a component it does not understand, and a false timeout on a future kind
+   * would be worse than passing it through.
+   *
+   * `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;
+}
+//#endregion
+//#region src/teams.d.ts
+export declare class TeamClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** List AgentTeamDefinitions (fixed-member rosters). */
+  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
+export declare class ModelClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  /** Enabled providers' models; `is_default` marks the `agent/run` fallback. */
+  list(): Promise<ModelSummary[]>;
+}
+//#endregion
+//#region src/workspaces.d.ts
+export declare class WorkspaceClient {
+  private readonly transport;
+  constructor(transport: Transport);
+  list(): Promise<WorkspaceView[]>;
+  /**
+   * Validate + register (idempotently per canonical root) an absolute local
+   * directory chosen by the owner. The server canonicalizes the path and
+   * rejects links/reparse points; the returned view only carries the
+   * canonical path back to this same authenticated connection.
+   */
+  create(path: string): Promise<WorkspaceView>;
+  /**
+   * Revoke (soft-delete) an owner's active workspace. Its conversations are
+   * kept and their `workspace_id` reference is preserved, so re-registering
+   * the same path re-activates the same workspace and those conversations
+   * become visible again.
+   */
+  revoke(workspaceId: string): Promise<WorkspaceRevokeResult>;
+}
+//#endregion
+//#region src/client.d.ts
+export interface AppServerClientOptions {
+  /** Ready-made transport (07 §2.3); the host app owns its lifecycle. */
+  transport: Transport;
+  client: ClientInfo;
+  capabilities?: ClientCapabilities;
+  /** Readiness tuning for the `store` sub-client (`store.install`). */
+  store?: StoreClientOptions;
+}
+export declare class AppServerClient {
+  readonly transport: Transport;
+  /** Legacy preset/execution workflow client. */
+  readonly runs: RunClient;
+  /** Persistent presetless Nomi chat client. */
+  readonly conversations: ConversationClient;
+  /** Owner-scoped workspace registry client (user-chosen paths). */
+  readonly workspaces: WorkspaceClient;
+  /** Agent Store Skill catalog client (`skill/list`, `skill/get`). */
+  readonly skills: SkillClient;
+  /** Agent Store Connector catalog/status/probe/OAuth client. */
+  readonly connectors: ConnectorClient;
+  /** Agent Store AgentDefinition catalog client (`agent/list`, `agent/get`). */
+  readonly agents: AgentClient;
+  /** Agent Store Team catalog client (`team/list`, `team/get`). */
+  readonly teams: TeamClient;
+  /** Public model directory (`models/list`, REQ-PAR-05b). */
+  readonly models: ModelClient;
+  /**
+   * Agent Store lifecycle as one state machine: search → install (wait until
+   * usable) → enable/disable → uninstall. Composes the flat methods below; it
+   * adds no wire surface.
+   */
+  readonly store: StoreClient;
+  readonly clientInfo: ClientInfo;
+  readonly capabilities?: ClientCapabilities;
+  private initializeResult;
+  private notificationListeners;
+  /** Transport → client notification bridge; re-armed after a transport close. */
+  private unbridgeNotifications;
+  constructor(options: AppServerClientOptions);
+  /**
+   * Subscribe the client-level fan-out on the transport exactly once.
+   * `transport.close()` drops its listeners, so this is also called on
+   * `connect()`: otherwise a reconnect would leave notifications silent.
+   */
+  private bridgeNotifications;
+  get ready(): boolean;
+  get initializeInfo(): InitializeResult | null;
+  /** Connect and perform the initialize/initialized handshake. */
+  connect(): Promise<InitializeResult>;
+  onNotification(listener: NotificationListener): () => void;
+  /** Close the transport; the server revokes the connection immediately. */
+  close(): void;
+  /** Import a local CodeBuddy/WorkBuddy source directory (roadmap Phase 1). */
+  runImport(input: ImportRequest): Promise<ImportResult>;
+  listImports(): Promise<ImportSummary[]>;
+  /** One immutable snapshot with its standardized components. */
+  getImport(snapshotId: string): Promise<ImportDetail>;
+  /**
+   * The plugin-level asset inventory of one snapshot (`import/assets`, doc 38):
+   * the `avatars/`, `bin/` and `scripts/` files beside the skills, sorted by
+   * path with a sha256 each. This is the same address space `readImportAsset`
+   * accepts and an `ExpertPack.assets` names — one provider, one whitelist.
+   * Check `capabilities.snapshot_assets` first.
+   */
+  listImportAssets(snapshotId: string): Promise<ImportAssetList>;
+  /**
+   * One plugin-level asset's bytes, over the WebSocket binding (`import/asset`,
+   * doc 38). Base64 on the wire, decoded to `Uint8Array` here — the same
+   * envelope `skills.readFile()` decodes. Persona text and skill bodies are
+   * deliberately not reachable through this face.
+   */
+  readImportAsset(snapshotId: string, path: string): Promise<Uint8Array>;
+  /** Install a snapshot into the runtime (roadmap Phase 2). */
+  runInstall(input: InstallRequest): Promise<InstallResult>;
+  /** Per-component installation state of a snapshot. */
+  getInstallStatus(snapshotId: string): Promise<InstallStatus>;
+  /**
+   * Disable installed components.
+   *
+   * The runtime state moves with the flag — a connector's MCP server is switched
+   * off, an expert's Preset is disabled — while the artifacts stay on disk. A
+   * skill is the documented exception: the corpus has no enable state, so it
+   * reports `skill_disable_flag_only` and the flag stays a catalogue marker.
+   */
+  disableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  /** Re-enable previously disabled components. */
+  enableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  /** Uninstall: remove runtime artifacts and clear the state (snapshot kept). */
+  uninstallInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
+  /** Register a marketplace source on the trusted host. */
+  addMarketplace(input: MarketplaceAddRequest): Promise<MarketplaceSummary>;
+  /** All active marketplaces. */
+  listMarketplaces(): Promise<MarketplaceSummary[]>;
+  /** One marketplace with its discovered entries. */
+  getMarketplace(marketplaceId: string): Promise<MarketplaceDetail>;
+  /** Remove a marketplace (`cascade` uninstalls snapshots installed from it). */
+  removeMarketplace(marketplaceId: string, cascade: boolean): Promise<MarketplaceRemoveResult>;
+  /** Toggle auto-update for a marketplace. */
+  setMarketplaceAutoUpdate(marketplaceId: string, enabled: boolean): Promise<MarketplaceSummary>;
+  /** Re-fetch a marketplace source and rebuild entries when the revision changed. */
+  refreshMarketplace(marketplaceId: string): Promise<MarketplaceRefreshResult>;
+  /** Import one discovered marketplace entry (provenance linked). */
+  importMarketplaceEntry(marketplaceId: string, entryName: string): Promise<ImportResult>;
+  /**
+   * The host's market policy: sweep cadence, auto-upgrade kind whitelist and the
+   * last sweep's reading (doc `37` §3.2).
+   *
+   * Host-level rather than per-market: it answers "when does the sweep run and
+   * what may it touch", while {@link setMarketplaceAutoUpdate} answers "which
+   * market participates".
+   */
+  getMarketSettings(): Promise<MarketSettings>;
+  /**
+   * Update the host's market policy. An absent field is left alone; the host
+   * writes the value into its `config.toml` and answers with the file re-read,
+   * so a caller can never see an optimistic echo.
+   */
+  setMarketSettings(patch: MarketSettingsPatch): Promise<MarketSettings>;
+  /** All store items across enabled marketplaces (display + install state). */
+  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
+/** One completed (or in-flight / timed-out) turn in a conversation. */
+export interface ConversationTurn {
+  conversation_id: string;
+  /** The user content that was submitted. */
+  content: string;
+  /** Durable user message id (`ConversationSendReceipt.message_id`). */
+  message_id: string;
+  /** Wire/billing turn id when the server assigned one. */
+  turn_id?: string | null;
+  accepted: boolean;
+  completed: boolean;
+  /** Events observed for this turn (sequence order). */
+  events: ConversationEvent[];
+  /** Terminal assistant text: `receipt.result_text` (authoritative backfill)
+   *  else aggregated from `message.delta` events. */
+  assistant_text: string | null;
+  isError: boolean;
+  result_error?: string | null;
+  result_error_code?: string | null;
+  /** Context occupancy when the runtime reported it during the turn. */
+  usage?: ContextUsage | null;
+}
+export interface ConversationTurnOptions {
+  /** Idempotency key; defaults to `crypto.randomUUID()`. */
+  idempotencyKey?: string;
+  /** Per-turn model override (applied server-side when set). */
+  model?: ConversationCreateInput["model"];
+  reasoningEffort?: string;
+}
+export declare class ConversationHandle {
+  readonly conversationId: string;
+  private readonly conversations;
+  private readonly subscription;
+  private constructor();
+  /** Create a new conversation and subscribe to its live event stream. */
+  static open(conversations: ConversationClient, input?: ConversationCreateInput): Promise<ConversationHandle>;
+  /** Attach to an existing conversation (by id) and subscribe. */
+  static attach(conversations: ConversationClient, conversationId: string): Promise<ConversationHandle>;
+  /** Register a listener for every conversation event (returns an unsubscribe). */
+  onEvent(listener: (event: ConversationEvent) => void): () => void;
+  /**
+   * Send a message (a "turn") and await its terminal state. The event collector
+   * is installed before the send so streaming deltas / usage are captured even
+   * when they arrive before the send acknowledgment is parsed.
+   */
+  send(content: string, options?: ConversationTurnOptions): Promise<ConversationTurn>;
+  /** Cancel the in-flight turn (idempotent; erases the current transcript row). */
+  cancel(): Promise<void>;
+  /** Fetch the transcript (paginated). */
+  messages(query?: Partial<ConversationMessagesQuery>): Promise<ConversationMessagesPage>;
+  /** Unsubscribe and release the handle. */
+  close(): Promise<void>;
+}
+/** Convenience: simple transcript snapshot (all roles, newest last). */
+export declare function conversationMessages(page: ConversationMessagesPage): ConversationMessage[];
+//#endregion
+//#region src/turn-result.d.ts
+/** Token/context usage for the turn (absent until the runtime projects it). */
+export interface TurnUsage {
+  input_tokens?: number;
+  output_tokens?: number;
+  total_tokens?: number;
+}
+/** One event-derived item (plan revision, task, attempt, approval, ...). */
+export interface TurnItem {
+  sequence: number;
+  event_type: string;
+  kind: "plan" | "task" | "attempt" | "status" | "approval" | "other";
+  /** Attempt/step identity when the event payload carries one. */
+  ref_id?: string;
+  status?: string;
+  reason?: string;
+}
+/** Aggregated terminal result returned by `AgentRunHandle.finished`. */
+export interface TurnResult {
+  run_id: string;
+  status: RunStatus;
+  version: number;
+  /** Terminal assistant text (`run/result` summary). */
+  final_response: string | null;
+  output_files: string[];
+  preset_revision?: number | null;
+  content_digest?: string | null;
+  /** Persisted event stream in sequence order (authoritative backfill). */
+  events: RunEvent[];
+  /** Event-derived items in the same order. */
+  items: TurnItem[];
+  usage?: TurnUsage;
+}
+/** Build the terminal turn result from the authoritative view + event stream. */
+export declare function aggregateTurnResult(view: RunView, events: RunEvent[]): TurnResult;
+//#endregion
+//#region src/run-handle.d.ts
+/** Options for `RunClient.launch()` (Codex-parity handle). */
+export interface LaunchHandleOptions {
+  /** Whether to attach a live `EventSubscription` (default true). */
+  follow?: boolean;
+}
+/**
+ * A launched Agent run. Async-iterable over live events; await `.finished`
+ * for the blocking Codex `thread.run()` shape.
+ */
+export declare class AgentRunHandle {
+  readonly runId: string;
+  readonly receipt: RunReceipt;
+  private readonly runClient;
+  private readonly poll;
+  private subscription;
+  private terminalView;
+  private terminalResult;
+  private finishWaiters;
+  private iteratorQueue;
+  private iteratorWaiters;
+  private iteratorClosed;
+  private readonly bufferedEvents;
+  private readonly bufferedSequences;
+  constructor(runClient: RunClient, receipt: RunReceipt, subscription: EventSubscription | null, poll: (runId: string) => Promise<RunView>);
+  /**
+   * Resolves with the aggregated terminal turn result (≈ `thread.run()`):
+   * authoritative status/version plus `final_response`, output files, the
+   * persisted event stream and derived items.
+   */
+  get finished(): Promise<TurnResult>;
+  /** Latest live cursor (proxied from the subscription when attached). */
+  get lastSequence(): number;
+  /** Ask the server to cancel; terminal confirmation still arrives via events/get. */
+  cancel(): Promise<void>;
+  /**
+   * Inject steering text into the currently active step (≈ Codex turn steer).
+   * Throws `conflict` when the run already changed or has no active step —
+   * refresh `receipt`-level state via `runClient.get()` and retry.
+   */
+  steer(text: string): Promise<RunView>;
+  /** Detach the live subscription (events may still be polled via run/events). */
+  close(): Promise<void>;
+  /** Async iterator over live events (≈ `thread.runStreamed()`). */
+  [Symbol.asyncIterator](): AsyncIterator<RunEvent>;
+  private pushEvent;
+  /**
+   * Authoritative backfill for `finished`: `run/result` (terminal summary)
+   * plus the persisted `run/events` stream, falling back to the live buffer
+   * when the query fails.
+   */
+  private aggregate;
+  /** Poll run/get until terminal, then resolve all `finished` waiters once. */
+  private ensureTerminalWatch;
+}
+/** Codex-parity launch: start the run and return a live handle immediately. */
+export declare function launchRun(runClient: RunClient, input: AgentRunInput, options?: LaunchHandleOptions): Promise<AgentRunHandle>;
+//#endregion
+//#region src/retry.d.ts
+/**
+ * Retry helper (REQ-PAR-05e, ≈ Codex `retry_on_overload`): exponential backoff
+ * with jitter, driven by the protocol's stable `retryable` hint.
+ *
+ * Only errors the server/transport marks retryable are retried; protocol
+ * errors that carry `retryable: false` (validation, not_found, ...) surface
+ * immediately. `command_id` / `idempotency_key` callers stay safe because the
+ * App Server deduplicates replayed mutations.
+ */
+export interface RetryInfo {
+  /** 1-based attempt that just failed and triggered the next try. */
+  attempt: number;
+  /** Delay applied before the next attempt. */
+  delayMs: number;
+  error: unknown;
+}
+export interface RetryOptions {
+  /** Total attempts including the first (default 3). */
+  maxAttempts?: number;
+  /** First backoff delay in ms (default 500). */
+  baseDelayMs?: number;
+  /** Upper bound for one delay in ms (default 8000). */
+  maxDelayMs?: number;
+  /** Jitter fraction in [0, 1] (default 0.25 → delay ∈ [0.75×, 1.0×]). */
+  jitter?: number;
+  /** Observer hook for logging/metrics. */
+  onRetry?: (info: RetryInfo) => void;
+  /** Custom predicate; defaults to the protocol `retryable` hint. */
+  shouldRetry?: (error: unknown, attempt: number) => boolean;
+  /** Deterministic delay override (tests). */
+  sleep?: (ms: number) => Promise<void>;
+}
+/** Run `operation`, retrying retryable failures with exponential backoff. */
+export declare function withRetry<T>(operation: () => Promise<T>, options?: RetryOptions): Promise<T>;
+//#endregion