@parall/sdk 1.50.1 → 1.52.0

package/src/client.ts

@@ -5,6 +5,8 @@ import type {
   ClaimDispatchResponse,
   SteerDispatchRequest,
   SteerDispatchResponse,
+  UpdateDispatchInputStateRequest,
+  UpdateDispatchInputStateResponse,
   CompleteDispatchByIDRequest,
   CompleteDispatchBySourceResult,
   CompleteDispatchLaneRequest,
@@ -240,14 +242,19 @@ import type {
   EdgeProfileProxyStatus,
   SetEdgeProfileProxyRequest,
   ClipConnection,
+  MCPConfigPutRequest,
+  MCPConfigResponse,
   EdgeOnboardingStatus,
   ExecEdgeClipRequest,
   EdgeClipExecResult,
   ReactionSummary,
   ToggleReactionResponse,
+  DependencyCheckResult,
   DeployTemplateRequest,
+  OnboardingProgress,
   Template,
   TemplateDeploymentReport,
+  UpdateOnboardingProgressRequest,
 } from './types.js';
 
 export interface ParallClientOptions {
@@ -707,7 +714,7 @@ export class ParallClient {
     data: Partial<
       Pick<
         Organization,
-        'name' | 'avatar_url' | 'smart_routing_strategy' | 'smart_routing_agent_id'
+        'name' | 'avatar_url' | 'smart_routing_strategy' | 'smart_routing_agent_id' | 'timezone'
       >
     >,
   ): Promise<Organization> {
@@ -816,8 +823,10 @@ export class ParallClient {
     );
   }
 
-  // Pending tasks (todo + in_progress) assigned to a member. Powers both
-  // member profile Activity and the agent startup catch-up flow.
+  // Pending tasks (todo + in_progress) assigned to a member. On-demand listing
+  // (member profile Activity; agents via `parall tasks`) — startup catch-up
+  // runs on dispatch redrive, not this endpoint. Self-assigned tasks appear
+  // here without any dispatch WorkItem (self-assign is deliberately silent).
   async getMemberTasks(
     orgId: string,
     memberId: string,
@@ -1330,7 +1339,7 @@ export class ParallClient {
   async getAgentSessions(
     orgId: string,
     agentId: string,
-    params?: { limit?: number; status?: string; cursor?: string },
+    params?: { limit?: number; status?: string; cursor?: string; sort?: 'finished_at' },
   ): Promise<PaginatedResponse<AgentSessionDB>> {
     return this.request('GET', ENDPOINTS.AGENT_SESSIONS(orgId, agentId), undefined, params);
   }
@@ -1452,7 +1461,12 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.AGENT_RUNTIME_RELEASE(orgId, agentId, tag));
   }
 
-  /** Fetch all pending tasks (todo/in_progress) assigned to an agent. Pages automatically. */
+  /**
+   * Fetch all pending tasks (todo/in_progress) assigned to an agent. Pages
+   * automatically. On-demand listing only — not a dispatch source: startup
+   * catch-up runs on dispatch redrive, and self-assigned tasks listed here
+   * deliberately have no WorkItem behind them.
+   */
   async getAgentTasks(orgId: string, agentId: string): Promise<Task[]> {
     const all: Task[] = [];
     let cursor: string | undefined;
@@ -2067,6 +2081,14 @@ export class ParallClient {
     return this.request('POST', ENDPOINTS.DISPATCH_STEER(orgId), req);
   }
 
+  /** Advance exact runtime-input lifecycle for members of an explicit lane. */
+  async updateDispatchInputState(
+    orgId: string,
+    req: UpdateDispatchInputStateRequest,
+  ): Promise<UpdateDispatchInputStateResponse> {
+    return this.request('POST', ENDPOINTS.DISPATCH_INPUT_STATE(orgId), req);
+  }
+
   /**
    * End a turn. Overloaded on the three mutually exclusive reference forms:
    * lane (no_action sweep + lane release + re-drive), source (the lane-less
@@ -3365,6 +3387,30 @@ export class ParallClient {
     return this.request('GET', ENDPOINTS.TEMPLATE_DEPLOYMENT(orgId, deploymentId));
   }
 
+  /** Pre-deploy dependency connection state (wizard S3). Live answer, no
+   *  cache — poll it the way getTemplateDeployment is polled. */
+  async checkClipDependencies(orgId: string, refs: string[]): Promise<DependencyCheckResult[]> {
+    const response = await this.request<{ results: DependencyCheckResult[] }>(
+      'POST',
+      ENDPOINTS.CLIP_DEPENDENCIES_CHECK(orgId),
+      { refs },
+    );
+    return response.results ?? [];
+  }
+
+  // ---- Onboarding wizard progress (org-scoped, self) ----
+
+  async getOnboardingProgress(orgId: string): Promise<OnboardingProgress> {
+    return this.request('GET', ENDPOINTS.ONBOARDING_PROGRESS(orgId));
+  }
+
+  async updateOnboardingProgress(
+    orgId: string,
+    request: UpdateOnboardingProgressRequest,
+  ): Promise<OnboardingProgress> {
+    return this.request('PATCH', ENDPOINTS.ONBOARDING_PROGRESS(orgId), request);
+  }
+
   // ---- Billing & Credits (org-scoped) ----
 
   async getBilling(orgId: string): Promise<BillingSummary> {
@@ -3802,12 +3848,17 @@ export class ParallClient {
    * command RAN and failed — `error`/`error_code` describe why). Everything
    * else throws a typed {@link ApiError}; match on `err.code`:
    *
-   * Safe to retry (guaranteed nothing was dispatched):
-   * - `EDGE_ACTIVATING` 503 + `Retry-After` — cold cloud profile is starting.
-   *   Bounded backoff, same `correlation_id` across the loop.
-   * - `EDGE_BUSY` 409 — the device is executing another request.
-   * - `EDGE_CONCURRENCY_LIMIT` 429 — org at its concurrent-session limit.
-   * - `EDGE_UNAVAILABLE` 503 — session torn down / replaced mid-dispatch.
+   * Safe to retry (provably not executed). Exactly three carry `Retry-After`
+   * pacing ({@link ApiError.retryAfterSeconds}) — `EDGE_ACTIVATING`,
+   * `EDGE_BUSY`, `EDGE_CONCURRENCY_LIMIT`:
+   * - `EDGE_ACTIVATING` 503 — cold cloud profile is starting. Answered before
+   *   any dispatch. Bounded backoff, same `correlation_id` across the loop.
+   * - `EDGE_BUSY` 409 — the device is executing another request; the pod
+   *   refused this one before starting any script.
+   * - `EDGE_CONCURRENCY_LIMIT` 429 — org at its concurrent-session limit,
+   *   answered before any dispatch.
+   * - `EDGE_UNAVAILABLE` 503 — session torn down / replaced mid-dispatch. No
+   *   `Retry-After` (no slot to wait for — retry re-resolves routing).
    *
    * NOT retryable:
    * - `OUTCOME_UNKNOWN` 504 — dispatched, but no result arrived. The command
@@ -3875,6 +3926,84 @@ export class ParallClient {
   async deleteClipConnection(orgId: string, connId: string): Promise<void> {
     return this.request('DELETE', ENDPOINTS.CLIP_CONNECTION(orgId, connId));
   }
+
+  // ---- MCP clip server config (cap:clip-mcp; publisher-org only) ----
+
+  /**
+   * Read the redacted MCP config. 404 NOT_FOUND when the clip has none yet;
+   * 403 MCP_CROSS_ORG_DISABLED for a cross-org installed clip (the whole
+   * mcp-config family is publisher-org property, reads included). `version`
+   * is the CAS token the mutations echo via If-Match.
+   */
+  async getClipMCPConfig(orgId: string, clipId: string): Promise<MCPConfigResponse> {
+    return this.request('GET', ENDPOINTS.ORG_CLIP_MCP_CONFIG(orgId, clipId));
+  }
+
+  /**
+   * Upsert the MCP config (human org-admin JWT only). Pass `expectedVersion`
+   * from the last GET; omit it ONLY on first create (no config exists yet).
+   * Save probes the remote server first — a probe failure persists nothing and
+   * surfaces as MCP_URL_FORBIDDEN / MCP_AUTH_FAILED / MCP_SERVER_UNREACHABLE /
+   * MCP_PROTOCOL_ERROR. Other typed conflicts: MCP_CONFIG_STALE (reload, then
+   * retry with the current version), MCP_CONFIG_BUSY (another change in
+   * flight — retry), MCP_CONNECTION_CONFLICT (a device-targeted default
+   * connection must be unbound first), SECRETBOX_UNCONFIGURED (503 — the
+   * server cannot store credentials safely).
+   */
+  async putClipMCPConfig(
+    orgId: string,
+    clipId: string,
+    req: MCPConfigPutRequest,
+    expectedVersion?: string,
+  ): Promise<MCPConfigResponse> {
+    return this.request(
+      'PUT',
+      ENDPOINTS.ORG_CLIP_MCP_CONFIG(orgId, clipId),
+      req,
+      undefined,
+      false,
+      {
+        headers: expectedVersion ? { 'If-Match': `"${expectedVersion}"` } : undefined,
+        // The server probes the remote MCP server inside the request on a fixed
+        // 30s budget; give the HTTP layer headroom past it so a slow-but-valid
+        // save isn't chopped locally into a fake transport error.
+        timeoutMs: 40_000,
+      },
+    );
+  }
+
+  /**
+   * Delete the MCP config and every connection routed through it (one
+   * transaction — no orphaned target-less connections). `expectedVersion` is
+   * mandatory: deleting always mutates an existing config.
+   */
+  async deleteClipMCPConfig(orgId: string, clipId: string, expectedVersion: string): Promise<void> {
+    return this.request(
+      'DELETE',
+      ENDPOINTS.ORG_CLIP_MCP_CONFIG(orgId, clipId),
+      undefined,
+      undefined,
+      false,
+      { headers: { 'If-Match': `"${expectedVersion}"` } },
+    );
+  }
+
+  /**
+   * Re-run tools/list and replace the cached snapshot (org-admin only).
+   * Deliberately does NOT advance the CAS version, so an in-flight edit in
+   * another tab stays valid; on probe failure the old snapshot survives.
+   */
+  async refreshClipMCPTools(orgId: string, clipId: string): Promise<MCPConfigResponse> {
+    return this.request(
+      'POST',
+      ENDPOINTS.ORG_CLIP_MCP_TOOLS_REFRESH(orgId, clipId),
+      undefined,
+      undefined,
+      false,
+      // Same fixed 30s server-side probe budget as PUT (see putClipMCPConfig).
+      { timeoutMs: 40_000 },
+    );
+  }
 }
 
 function normalizeWikiChangeset(changeset: WikiChangeset): WikiChangeset {

package/src/constants.ts

@@ -781,6 +781,7 @@ export const ENDPOINTS = {
   DISPATCH_BY_MESSAGES: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/by-messages`,
   DISPATCH_CLAIM: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/claim`,
   DISPATCH_STEER: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/steer`,
+  DISPATCH_INPUT_STATE: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/input-state`,
   DISPATCH_COMPLETE: (orgId: string) => `${API_BASE}/orgs/${orgId}/dispatch/complete`,
   DISPATCH_COMPLETE_SOURCES: (orgId: string) =>
     `${API_BASE}/orgs/${orgId}/dispatch/complete-sources`,
@@ -829,6 +830,10 @@ export const ENDPOINTS = {
   TEMPLATE_DEPLOYMENTS: (orgId: string) => `${API_BASE}/orgs/${orgId}/template-deployments`,
   TEMPLATE_DEPLOYMENT: (orgId: string, deploymentId: string) =>
     `${API_BASE}/orgs/${orgId}/template-deployments/${deploymentId}`,
+  CLIP_DEPENDENCIES_CHECK: (orgId: string) => `${API_BASE}/orgs/${orgId}/clip-dependencies/check`,
+
+  // Onboarding wizard progress (org-scoped, self)
+  ONBOARDING_PROGRESS: (orgId: string) => `${API_BASE}/orgs/${orgId}/onboarding`,
 
   // Billing & Credits (org-scoped)
   BILLING: (orgId: string) => `${API_BASE}/orgs/${orgId}/billing`,
@@ -917,6 +922,12 @@ export const ENDPOINTS = {
   ORG_CLIP_REGISTRY: (orgId: string) => `/api/v1/orgs/${orgId}/clip-registry`,
   ORG_CLIP_INSTALL: (orgId: string) => `/api/v1/orgs/${orgId}/clips/install`,
   ORG_CLIPS_INSTALLED: (orgId: string) => `/api/v1/orgs/${orgId}/clips/installed`,
+  // MCP clip server config (cap:clip-mcp; publisher-org only — cross-org gets
+  // 403 MCP_CROSS_ORG_DISABLED on the whole family, reads included)
+  ORG_CLIP_MCP_CONFIG: (orgId: string, clipId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-config`,
+  ORG_CLIP_MCP_TOOLS_REFRESH: (orgId: string, clipId: string) =>
+    `/api/v1/orgs/${orgId}/clip-registry/${clipId}/mcp-config/tools/refresh`,
 } as const;
 
 /**

package/src/types.ts

@@ -408,6 +408,8 @@ export interface Organization {
   /** Agent ID for strategy='agent'. NULL when strategy is 'llm' or unset. */
   smart_routing_agent_id: string | null;
   onboarding_agent_id: string | null;
+  /** Org-level IANA timezone (e.g. "America/New_York"). Defaults to "UTC". */
+  timezone: string;
   created_at: string;
   /** Per-member flag: true when the user has dismissed the onboarding popup for this org. */
   onboarding_dismissed: boolean;
@@ -746,6 +748,46 @@ export interface DeployTemplateRequest {
   template_id: string;
   template_revision: string;
   parameter_values?: Record<string, TemplateParameterValue>;
+  /** Hire-time per-agent adjustments (onboarding wizard S2). Keys are the
+   *  template's agent keys; omitted agents keep template defaults. */
+  agent_overrides?: Record<string, DeployAgentOverride>;
+}
+
+/** Per-agent hire-time override. Substitutes values within the platform-legal
+ *  surface; never adds capability. Dependencies may only disable (false)
+ *  declared optional deps — required deps and undeclared refs are rejected. */
+export interface DeployAgentOverride {
+  runtime_type?: string;
+  /** Model catalog id. Empty string clears the template's pin (platform default). */
+  model?: string;
+  compute?: { machine_type: 'cloud'; machine_label?: string };
+  dependencies?: Record<string, boolean>;
+}
+
+/** Pre-deploy dependency connection state (wizard S3 poll target). Same
+ *  checker as the deployment report, so the two surfaces cannot disagree. */
+export interface DependencyCheckResult {
+  ref: string;
+  connected: boolean;
+  name?: string;
+}
+
+/** Onboarding wizard progress (self-scoped). A member who never started
+ *  reads step='s1', state={}, version=0 (missing-row semantics). */
+export interface OnboardingProgress {
+  step: string;
+  state: Record<string, unknown>;
+  completed_at?: string;
+  version: number;
+}
+
+export interface UpdateOnboardingProgressRequest {
+  step: string;
+  state: Record<string, unknown>;
+  /** Stamps completed_at server-side (idempotent, never un-completes). */
+  completed?: boolean;
+  /** 0 = first write (no row yet). */
+  expected_version: number;
 }
 
 export type TemplateDeploymentAgentState = 'up' | 'provisioning' | 'error';
@@ -882,6 +924,13 @@ export interface DispatchSourceRef {
  */
 export interface CompleteDispatchSourcesRequest {
   sources: DispatchSourceRef[];
+  /**
+   * Optional session attribution for the swept no_action rows (message ↔
+   * session linking; effect-covered rows inherit their covering reply's
+   * session). Validated against (org, agent); a mismatch drops the
+   * attribution.
+   */
+  session_id?: string;
 }
 
 export interface CompleteDispatchSourcesResult {
@@ -3136,6 +3185,8 @@ export type DispatchEventType =
   | 'channel_message';
 export type DispatchStatus = 'pending' | 'received' | 'acked';
 export type DispatchDeliveryReason = 'mention' | 'watcher' | 'assignee' | 'creator';
+export type DispatchCoverageMode = 'implicit' | 'explicit';
+export type DispatchInputState = 'offered' | 'started' | 'completed' | 'failed';
 
 export interface DispatchEvent {
   id: string;
@@ -3170,6 +3221,7 @@ export interface DispatchEvent {
    */
   dedupe_key?: string | null;
   lease_owner?: string | null;
+  input_state?: DispatchInputState | null;
   target_uri?: string | null;
   thread_root_id?: string | null;
   resolution_kind?:
@@ -3187,6 +3239,14 @@ export interface DispatchEvent {
    * redrive_exhausted. Absent on pre-budget servers.
    */
   redrive_count?: number;
+  /**
+   * Agent session that ultimately handled this WorkItem, stamped at resolve
+   * time where deterministically known (reply commits + broad cover /
+   * by-source contagion; complete endpoints' validated self-report).
+   * NULL = unattributed: live rows, cancelled, legacy acks, typed effects
+   * until their runtimes report it.
+   */
+  session_id?: string | null;
   /**
    * Reply-message provenance ("prll://msg_x") of the resolving Effect.
    * Populated only by GET /dispatch/by-messages (Effect join) on
@@ -3212,6 +3272,12 @@ export interface ClaimDispatchRequest {
   source_type?: string;
   source_id?: string;
   limit?: number;
+  /**
+   * Explicit requires the runtime to report exact per-WorkItem input
+   * lifecycle before reply/no-action coverage. Omit for legacy implicit
+   * fold-means-consumed behavior.
+   */
+  coverage_mode?: DispatchCoverageMode;
 }
 
 export interface ClaimDispatchResponse {
@@ -3225,6 +3291,7 @@ export interface ClaimDispatchResponse {
   reason?: 'held' | 'empty' | '';
   lane?: string;
   lease_until?: string;
+  coverage_mode?: DispatchCoverageMode;
   events?: DispatchEvent[];
 }
 
@@ -3243,6 +3310,22 @@ export interface SteerDispatchResponse {
   dispatch_event_id: string;
 }
 
+/** POST /dispatch/input-state — advance exact explicit-lane input members. */
+export interface UpdateDispatchInputStateRequest {
+  lane: string;
+  target_uri: string;
+  thread_root_id?: string;
+  dispatch_event_ids: string[];
+  state: Exclude<DispatchInputState, 'offered'>;
+}
+
+export interface UpdateDispatchInputStateResponse {
+  /** Exact IDs accepted, including idempotent same-state retries. */
+  recognized: number;
+  released: number;
+  redriven: boolean;
+}
+
 /**
  * POST /dispatch/complete — end a turn. Two mutually exclusive reference
  * forms (dispatch-convergence-design.md §3), each with its own result shape
@@ -3259,13 +3342,31 @@ export interface CompleteDispatchLaneRequest {
   target_uri: string;
   thread_root_id?: string;
   /**
-   * "ok" (default) or "error". An error turn's members are released back to
-   * pending on the redrive budget instead of being no_action-swept, so failed
-   * work is retried rather than silently resolved. Ignored by older servers.
+   * "ok" (default), "error", or "deferred". An error turn's members are
+   * released back to pending on the redrive budget instead of being
+   * no_action-swept, so failed work is retried rather than silently
+   * resolved. A deferred turn (self-healing LLM usage limit,
+   * agent-turn-outcome-design.md §6) releases its members to pending with
+   * next_redrive_at = retry_at WITHOUT burning redrive budget — the renotify
+   * slow loop re-delivers them at reset time. Servers predating "deferred"
+   * answer 400; the bridge falls back to "error".
    */
-  turn_outcome?: 'ok' | 'error';
+  turn_outcome?: 'ok' | 'error' | 'deferred';
+  /** Normalized failure class for the deferred form (observability only). */
+  outcome_class?: 'usage_limit';
+  /**
+   * ISO 8601 re-delivery time for turn_outcome=deferred. The server clamps
+   * it into [now+1min, now+6h] and defaults a missing value to now+30min.
+   */
+  retry_at?: string;
   sources?: never;
   dispatch_event_id?: never;
+  /**
+   * Optional session attribution for the swept no_action rows (message ↔
+   * session linking). Validated against (org, agent); a mismatch drops the
+   * attribution, never the sweep.
+   */
+  session_id?: string;
 }
 
 /**
@@ -3277,6 +3378,12 @@ export interface CompleteDispatchLaneRequest {
 export interface CompleteDispatchSourceFormRequest {
   sources: DispatchSourceRef[];
   turn_outcome?: 'ok' | 'error';
+  /**
+   * Optional session attribution for the turn's no_action rows
+   * (effect-covered rows inherit their covering reply's session instead).
+   * Validated against (org, agent); informational.
+   */
+  session_id?: string;
   lane?: never;
   target_uri?: never;
   thread_root_id?: never;
@@ -3304,6 +3411,8 @@ export interface CompleteDispatchByIDRequest {
 /** Lane-form result. */
 export interface CompleteDispatchResult {
   swept_no_action: number;
+  /** Members not eligible for no-action coverage and released for retry. */
+  released?: number;
   redriven: boolean;
 }
 
@@ -3344,9 +3453,10 @@ export interface DispatchReceivedData {
 /**
  * Terminal counterpart of DispatchReceivedData: published on org:{orgId} when
  * a message WorkItem reaches a terminal resolution, so the message-level
- * Activity indicator flips active→done (or clears, for `cancelled` /
- * `redrive_exhausted`) without inferring completion from agent session state.
- * Message WorkItems only.
+ * Activity indicator flips active→done — or, per indicator v2.1, active→failed
+ * for `redrive_exhausted` (persistent dead-letter row); only `cancelled`
+ * clears the indicator — without inferring completion from agent session
+ * state. Message WorkItems only.
  */
 export interface DispatchResolvedData {
   agent_id: string;
@@ -3362,6 +3472,12 @@ export interface DispatchResolvedData {
    * message. Absent for no_action / legacy_ack.
    */
   result_uri?: string | null;
+  /**
+   * Session attribution mirrored from the resolved rows — lets the
+   * indicator's click-through open the exact session without a refetch.
+   * Absent when the resolution is unattributed.
+   */
+  session_id?: string | null;
 }
 
 export type InboxNewData = InboxItem;
@@ -4158,15 +4274,31 @@ export type BrowserProfileStatus = 'pending' | 'running' | 'stopped' | 'error' |
 /**
  * Routing/identity discriminant: `byoc` runs on a user machine (machine_id
  * required), `hosted` runs on the platform pool (machine_id null).
+ *
+ * NOTE: `hosted` is RETIRED — its compute plane was removed, so creating a profile
+ * with it is rejected (400 `HOSTED_PLACEMENT_RETIRED`) and existing hosted rows are
+ * read-only (readable, proxy-editable, deletable; never startable). The value stays
+ * in the union because those preserved rows still report it. For a platform-run
+ * browser use a v3 Cloud Profile (`POST /orgs/{org}/edge`).
  */
 export type BrowserPlacement = 'byoc' | 'hosted';
 
-/** Deployment-wide hosted browser runtime availability (the controller startup
- *  gate). Drives whether the create UI offers the platform-hosted placement; it
- *  is org-scoped only for auth — the value itself is the same for every org.
- *  Fail-closed: the server reports `available: false` if it cannot verify. */
+/** Platform-hosted browser runtime availability.
+ *
+ *  This now always reports `available: false`: the v2 hosted compute plane is
+ *  retired, so the answer is a constant rather than a probe of a controller that no
+ *  longer exists. Clients that already treat `available: false` as "offer BYOC
+ *  instead" degrade correctly with no change.
+ *
+ *  `code` distinguishes PERMANENT retirement (`HOSTED_PLACEMENT_RETIRED`) from the
+ *  transient outage the old flag could also mean — do not retry on it. It is
+ *  optional so older servers, which sent only `{available, reason}`, still typecheck. */
 export interface BrowserRuntimeStatus {
   available: boolean;
+  /** Present when `available` is false for a structural reason. Currently only
+   *  `HOSTED_PLACEMENT_RETIRED`; typed as string so a new server code is not a
+   *  breaking SDK change. */
+  code?: string;
   reason?: string;
 }
 
@@ -4617,6 +4749,56 @@ export interface ClipConnection {
   updated_at: string;
 }
 
+/** v1 MCP clip auth modes. Server-side OAuth is a designed follow-up. */
+export type MCPAuthType = 'none' | 'bearer' | 'api_key';
+
+/**
+ * One tool from the cached tools/list snapshot. The full remote tool object is
+ * snapshotted verbatim (inputSchema etc. ride along in the index signature).
+ * Name/description are REMOTE-CONTROLLED UNTRUSTED TEXT — render as plain text
+ * only, never as markdown/HTML and never into a privileged prompt.
+ */
+export interface MCPToolInfo {
+  name: string;
+  description?: string;
+  [key: string]: unknown;
+}
+
+/**
+ * Redacted MCP server config of an MCP clip
+ * (`GET /orgs/{orgId}/clip-registry/{clipId}/mcp-config`). The whole
+ * mcp-config family is publisher-org only: cross-org installs get
+ * `403 MCP_CROSS_ORG_DISABLED`, reads included. The stored credential NEVER
+ * appears in any response — `credential_set` is the only credential fact.
+ */
+export interface MCPConfigResponse {
+  server_url: string;
+  auth_type: MCPAuthType;
+  /** Whether a credential is stored (write-only; the value is never returned). */
+  credential_set: boolean;
+  /** Cached tools/list snapshot; untrusted remote metadata (see MCPToolInfo). */
+  tools?: MCPToolInfo[];
+  tools_refreshed_at?: string;
+  /**
+   * Opaque CAS token for If-Match on PUT/DELETE (lost-update protection).
+   * Version mismatch answers `409 MCP_CONFIG_STALE`.
+   */
+  version: string;
+}
+
+/**
+ * PUT body for the MCP config. Credential semantics (server-enforced):
+ * omitted keeps the stored one ONLY while auth_type is unchanged; switching
+ * credentialed types requires a new credential; auth_type "none" clears it.
+ * Saving probes the server (initialize + tools/list) first — a failed probe
+ * persists nothing.
+ */
+export interface MCPConfigPutRequest {
+  server_url: string;
+  auth_type: MCPAuthType;
+  credential?: string;
+}
+
 /**
  * A clip in the api-server org registry (`crg_…`, table `clip_registry`) — the
  * v3 registry that install and clip connections operate on. Distinct from