@parall/sdk 1.51.0 → 1.52.0

package/dist/types.d.ts

@@ -754,6 +754,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 {
     resolved_effect: number;
@@ -2588,6 +2595,8 @@ export interface SlackStatusInput {
 export type DispatchEventType = 'message' | 'task_assign' | 'task_update' | 'task_comment' | 'wiki_comment' | 'schedule.fire' | 'external_trigger' | 'approval_decided' | '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;
     org_id: string;
@@ -2621,6 +2630,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?: 'effect' | 'no_action' | 'cancelled' | 'legacy_ack' | 'redrive_exhausted' | null;
@@ -2632,6 +2642,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
@@ -2656,6 +2674,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 {
     claimed: boolean;
@@ -2668,6 +2692,7 @@ export interface ClaimDispatchResponse {
     reason?: 'held' | 'empty' | '';
     lane?: string;
     lease_until?: string;
+    coverage_mode?: DispatchCoverageMode;
     events?: DispatchEvent[];
 }
 /** POST /dispatch/steer — fold a pending same-target WorkItem into a live lane. */
@@ -2683,6 +2708,20 @@ export interface SteerDispatchRequest {
 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
@@ -2695,13 +2734,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;
 }
 /**
  * Source form: the lane-less close for runtimes without a resident process —
@@ -2712,6 +2769,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;
@@ -2737,6 +2800,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;
 }
 /** Source-form result (mirrors CompleteDispatchSourcesResult). */
@@ -2771,9 +2836,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;
@@ -2789,6 +2855,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;
 export interface InboxUpdateData {
@@ -3882,6 +3954,52 @@ export interface ClipConnection {
     created_at: string;
     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