@parall/sdk 1.51.0 → 1.52.0

package/src/types.ts

@@ -924,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 {
@@ -3178,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;
@@ -3212,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?:
@@ -3229,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
@@ -3254,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 {
@@ -3267,6 +3291,7 @@ export interface ClaimDispatchResponse {
   reason?: 'held' | 'empty' | '';
   lane?: string;
   lease_until?: string;
+  coverage_mode?: DispatchCoverageMode;
   events?: DispatchEvent[];
 }
 
@@ -3285,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
@@ -3301,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;
 }
 
 /**
@@ -3319,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;
@@ -3346,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;
 }
 
@@ -3386,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;
@@ -3404,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;
@@ -4675,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