@cadraos/sdk 0.3.12 → 0.3.14-p102.1

package/dist/index.d.cts

@@ -1472,8 +1472,61 @@ interface StreamingConfig {
     reconnectMaxDelayMs: number;
     /** Activity timeout - no events for this long triggers reconnect (ms) */
     activityTimeoutMs: number;
-    /** Polling interval for fallback mode (ms) */
+    /**
+     * Base polling interval for fallback mode (ms).
+     *
+     * This is a FLOOR, not a fixed period: the fallback loop starts here and
+     * backs off from it when polls fail or stop learning anything new
+     * (see {@link pollingMaxIntervalMs}).
+     */
     pollingIntervalMs: number;
+    /**
+     * Ceiling the fallback poll delay backs off to (ms). Default 30000.
+     * Bounds the request rate of a fallback loop that is failing or idle.
+     */
+    pollingMaxIntervalMs?: number;
+    /**
+     * Consecutive poll failures (non-429) before the loop gives up and surfaces
+     * an error instead of retrying forever. Default 10.
+     */
+    pollingMaxConsecutiveFailures?: number;
+    /**
+     * Consecutive 429 responses before the loop gives up. Default 3.
+     * A 429 is not transient noise — it means the quota window is spent, and
+     * continuing to probe it starves every other feature on the same key.
+     */
+    pollingMaxConsecutiveRateLimits?: number;
+    /**
+     * Consecutive 4xx responses (excluding 429 and 408) from the status endpoint
+     * before the loop gives up. Default 3. A 4xx will not fix itself by asking
+     * again — a wrong path, a dead run id or rejected auth all land here — but a
+     * poll issued immediately after dispatch can legitimately 404 once, hence a
+     * small tolerance rather than the SSE side's instant termination.
+     */
+    pollingMaxConsecutiveClientErrors?: number;
+    /**
+     * How long the fallback loop may go without learning anything before it gives
+     * up (ms). Default 1800000 (30 min). Measured from the last poll that
+     * observed a new log or a status change — NOT from when the loop started, so
+     * a fallback that is still delivering output is never cut off.
+     */
+    pollingMaxDurationMs?: number;
+    /**
+     * Longest server-named `Retry-After` the loop will sit out (ms). Default
+     * 300000 (5 min). Beyond this the loop gives up rather than silently
+     * holding a session open for a reset that far away.
+     */
+    pollingMaxRetryAfterMs?: number;
+    /**
+     * Positive-only jitter applied to fallback poll delays, as a ratio of the
+     * delay. Default 0.1. Set to 0 for deterministic timing.
+     */
+    pollingJitterRatio?: number;
+    /**
+     * How often to re-attempt SSE while in fallback polling (ms). Default 60000.
+     * A transient outage must not cost the session its stream for good.
+     */
+    sseRetryIntervalMs?: number;
 }
 
 /**
@@ -2742,7 +2795,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *
@@ -2834,6 +2897,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -2896,6 +2964,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Input for transitioning a card to another lane.

package/dist/index.d.ts

@@ -1472,8 +1472,61 @@ interface StreamingConfig {
     reconnectMaxDelayMs: number;
     /** Activity timeout - no events for this long triggers reconnect (ms) */
     activityTimeoutMs: number;
-    /** Polling interval for fallback mode (ms) */
+    /**
+     * Base polling interval for fallback mode (ms).
+     *
+     * This is a FLOOR, not a fixed period: the fallback loop starts here and
+     * backs off from it when polls fail or stop learning anything new
+     * (see {@link pollingMaxIntervalMs}).
+     */
     pollingIntervalMs: number;
+    /**
+     * Ceiling the fallback poll delay backs off to (ms). Default 30000.
+     * Bounds the request rate of a fallback loop that is failing or idle.
+     */
+    pollingMaxIntervalMs?: number;
+    /**
+     * Consecutive poll failures (non-429) before the loop gives up and surfaces
+     * an error instead of retrying forever. Default 10.
+     */
+    pollingMaxConsecutiveFailures?: number;
+    /**
+     * Consecutive 429 responses before the loop gives up. Default 3.
+     * A 429 is not transient noise — it means the quota window is spent, and
+     * continuing to probe it starves every other feature on the same key.
+     */
+    pollingMaxConsecutiveRateLimits?: number;
+    /**
+     * Consecutive 4xx responses (excluding 429 and 408) from the status endpoint
+     * before the loop gives up. Default 3. A 4xx will not fix itself by asking
+     * again — a wrong path, a dead run id or rejected auth all land here — but a
+     * poll issued immediately after dispatch can legitimately 404 once, hence a
+     * small tolerance rather than the SSE side's instant termination.
+     */
+    pollingMaxConsecutiveClientErrors?: number;
+    /**
+     * How long the fallback loop may go without learning anything before it gives
+     * up (ms). Default 1800000 (30 min). Measured from the last poll that
+     * observed a new log or a status change — NOT from when the loop started, so
+     * a fallback that is still delivering output is never cut off.
+     */
+    pollingMaxDurationMs?: number;
+    /**
+     * Longest server-named `Retry-After` the loop will sit out (ms). Default
+     * 300000 (5 min). Beyond this the loop gives up rather than silently
+     * holding a session open for a reset that far away.
+     */
+    pollingMaxRetryAfterMs?: number;
+    /**
+     * Positive-only jitter applied to fallback poll delays, as a ratio of the
+     * delay. Default 0.1. Set to 0 for deterministic timing.
+     */
+    pollingJitterRatio?: number;
+    /**
+     * How often to re-attempt SSE while in fallback polling (ms). Default 60000.
+     * A transient outage must not cost the session its stream for good.
+     */
+    sseRetryIntervalMs?: number;
 }
 
 /**
@@ -2742,7 +2795,17 @@ interface KanbanLane {
      * a tick fans out ⌈cap / chunkSize⌉ runs. Ignored for `per-card`/`event` lanes.
      */
     chunkSize?: number;
+    /**
+     * p46 Handoff contract, OPT-IN per lane (D1). Absent ⇒ `off` (existing boards
+     * are byte-identical). `verdict` ⇒ the engine sends
+     * `HANDOFF_VERDICT_JSON_SCHEMA` as the run's `context.outputSchema` and a
+     * completion MUST carry a valid verdict (else the run fails with a FAILED
+     * handoff). Active only on hosts whose adapter implements the ledger group.
+     */
+    handoff?: KanbanLaneHandoffMode;
 }
+/** Per-lane Handoff mode (p46 D1). */
+type KanbanLaneHandoffMode = "off" | "verdict";
 /**
  * A declared edge between two lanes in the lifecycle.
  *
@@ -2834,6 +2897,11 @@ interface KanbanCard {
     configVersion?: number;
     /** Arbitrary shared context carried across transitions. */
     sharedContext?: Record<string, unknown>;
+    /**
+     * p46 (P46-002): the card's id in an external host (a Jira issue key).
+     * Absent on native / crm / yobo cards.
+     */
+    externalRef?: string;
     /**
      * Execution UUID of the card's current/last run, if any.
      *
@@ -2896,6 +2964,18 @@ interface CreateCardInput {
      * in the lifecycle's initial lane.
      */
     lane?: string;
+    /**
+     * p46 (P46-002): the card's id in an EXTERNAL host (a Jira issue key, e.g.
+     * `CAD-231`). Optional. When set, a card is created at most ONCE per
+     * `(boardConfigUuid, externalRef)`: a repeat create returns the existing card
+     * and dispatches nothing. Hosts that don't store it simply ignore it.
+     */
+    externalRef?: string;
+    /**
+     * p46 (P46-002): opaque host facts stored with the card (Jira `statusId`,
+     * `mover`, `detached`, …). Passed through to `adapter.createCard` untouched.
+     */
+    externalMeta?: Record<string, unknown>;
 }
 /**
  * Input for transitioning a card to another lane.