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

package/dist/index.d.mts

@@ -1,4 +1,4 @@
-import { AgentDetail, AgentRunInput, AgentSummary, CancelRunInput, ClientCapabilities, ClientInfo, ConnectorDetail, ConnectorProbeResult, ConnectorStatusView, ConnectorSummary, ContextUsage, ConversationCreateInput, ConversationEvent, ConversationMessage, ConversationMessagesPage, ConversationMessagesQuery, ConversationModelOptions, ConversationSendReceipt, ConversationUpdateInput, ConversationView, ImportDetail, ImportRequest, ImportResult, ImportSummary, InitializeResult, InstallRequest, InstallResult, InstallStatus, MarketplaceAddRequest, MarketplaceDetail, MarketplaceRefreshResult, MarketplaceRemoveResult, MarketplaceSummary, ModelSummary, OAuthStartResult, OAuthStatusView, RunEvent, RunEventsQuery, RunReceipt, RunResult, RunStatus, RunView, ServerNotification, SkillDetail, SkillSummary, SteerRunInput, StoreInstallResult, StoreList, TeamDetail, TeamSummary, WorkspaceRevokeResult, WorkspaceView } from "@flowy-agent-store/protocol";
+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, ModelSummary, OAuthStartResult, OAuthStatusView, 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;
 /**
@@ -82,6 +82,109 @@ export declare class WebSocketTransport implements Transport {
   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;
@@ -102,39 +205,115 @@ export declare class ConversationClient {
   list(limit?: number): Promise<ConversationView[]>;
   get(conversationId: string): Promise<ConversationView>;
   messages(query: ConversationMessagesQuery): Promise<ConversationMessagesPage>;
-  send(conversationId: string, content: string, idempotencyKey: string): Promise<ConversationSendReceipt>;
+  /**
+   * R15（W10）：`attachments` 是**会话工作区内的绝对路径**（图片附件）。
+   *
+   * 缺省不传，保持老调用方的 wire 形状逐字不变；服务端只接受会话工作区内的真实
+   * 文件（越界 / 相对路径 / 不存在一律拒），具体准入见
+   * `nomifun-app-server` 的 `resolve_conversation_attachments`。
+   */
+  send(conversationId: string, content: string, idempotencyKey: string, attachments?: string[]): Promise<ConversationSendReceipt>;
   cancel(conversationId: string): Promise<ConversationView>;
   delete(conversationId: string): Promise<{
     conversation_id: string;
     deleted: boolean;
   }>;
-  follow(conversationId: string): Promise<ConversationSubscription>;
+  /**
+   * 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;
-  constructor(transport: Transport, conversationId: string);
+  /**
+   * `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`. This subscription has no event-replay API, so the
-   * caller must still backfill the transcript for the outage window
-   * (`conversation/messages`). Call it once the handshake completed; a no-op
-   * once closed.
+   * `conversation/subscribe`. The server restarts a conversation's sequence at
+   * 1 for a fresh subscription, which is exactly why the cursor resets. On a
+   * failed re-subscribe the error reaches `onError` and the caller can still
+   * backfill the outage window via `conversation/messages`.
    */
   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
@@ -158,6 +337,22 @@ export declare class ConnectorClient {
   authStart(connectorId: string): Promise<OAuthStartResult>;
   /** 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]` allowlist, so expect `policy_denied` on a host whose
+   * operator has not listed this tool (that is the default, not a
+   * misconfiguration).
+   *
+   * Resolves even when the tool itself failed — check `is_error`. It rejects
+   * only when the call never reached the tool: `connector_call_timeout`,
+   * `connector_call_failed`, `response_too_large`, `connector_unavailable`,
+   * `policy_denied`, `not_found`.
+   */
+  call(connectorId: string, tool: string, args?: unknown): Promise<ConnectorCallResult>;
 }
 //#endregion
 //#region src/runs.d.ts
@@ -166,10 +361,26 @@ export declare class RunClient {
   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. */
@@ -179,6 +390,16 @@ export declare class RunClient {
    * (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>;
 }
@@ -257,6 +478,197 @@ export declare class SkillClient {
   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>;
+}
+//#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;
+}
+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 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;
+  /**
+   * `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;
+}
+/**
+ * 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>;
+  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;
+  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[]>;
+  /**
+   * 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; `"uninstall_reinstall"` means the
+   * entry is installed at a different version and the only path the wire offers
+   * is to release it and install again (the version-aware re-import then picks
+   * up the current version). `"unknown"` is returned rather than guessing when
+   * the item carries no snapshot to release.
+   */
+  updateHint(item: StoreItem): "none" | "uninstall_reinstall" | "unknown";
+  /**
+   * 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.
+   */
+  private readiness;
 }
 //#endregion
 //#region src/teams.d.ts
@@ -304,6 +716,8 @@ export interface AppServerClientOptions {
   transport: Transport;
   client: ClientInfo;
   capabilities?: ClientCapabilities;
+  /** Readiness tuning for the `store` sub-client (`store.install`). */
+  store?: StoreClientOptions;
 }
 export declare class AppServerClient {
   readonly transport: Transport;
@@ -323,6 +737,12 @@ export declare class AppServerClient {
   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;
@@ -352,7 +772,14 @@ export declare class AppServerClient {
   runInstall(input: InstallRequest): Promise<InstallResult>;
   /** Per-component installation state of a snapshot. */
   getInstallStatus(snapshotId: string): Promise<InstallStatus>;
-  /** Disable installed components (runtime artifacts stay). */
+  /**
+   * Disable installed components.
+   *
+   * The runtime state moves with the flag — a connector's MCP server is switched
+   * off, an expert's Preset is disabled — while the artifacts stay on disk. A
+   * skill is the documented exception: the corpus has no enable state, so it
+   * reports `skill_disable_flag_only` and the flag stays a catalogue marker.
+   */
   disableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;
   /** Re-enable previously disabled components. */
   enableInstall(snapshotId: string, componentIds: string[]): Promise<InstallStatus>;