wicked-crew-api-types 0.18.0 → 0.20.0

package/index.d.ts

@@ -197,9 +197,14 @@ export interface AgentSession {
    *
    *   - `'delivered'` — a PR was opened for this run (by the deliver phase, or post-hoc via
    *     `POST /runs/:id/deliver`); `deliverUrl` carries the PR URL.
-   *   - `'stranded'`  — a COMPLETED repo-scoped run with no recorded PR whose worktree still
-   *     exists on disk AND carries work: reviewable work nobody lifted. Derived honestly for
-   *     OLD runs too — records written before this field existed strand exactly the same way.
+   *   - `'stranded'`  — reviewable work nobody lifted, reached two ways: a COMPLETED repo-scoped
+   *     run with no recorded PR whose worktree still exists on disk AND carries work (derived
+   *     honestly for OLD runs too — records written before this field existed strand the same
+   *     way); OR (crew#418) a run whose deliver phase hit a LIFT collision — a rebase conflict or
+   *     non-fast-forward push — which the daemon reinterprets from the engine's `failed` to
+   *     `completed`+`stranded`: its work is committed on the `wicked/<id>` branch (the engine
+   *     reaps the now-clean worktree, but never the branch), recoverable via `POST /runs/:id/
+   *     deliver`, which stands a throwaway worktree back up from that branch to lift it.
    *   - `'vacuous'`   — a COMPLETED repo-scoped run whose surviving worktree carries NO
    *     contribution at all (crew#311: nothing uncommitted, no run-branch commit — units all
    *     reached "done" while producing nothing). There is nothing to deliver; the recovery is a
@@ -231,6 +236,25 @@ export interface AgentSession {
    * idempotent against the existing branch) and `'none'` after it is cleaned up.
    */
   deliverUrl?: string;
+  /**
+   * The campaign this AD-HOC run was attached to at launch (`LaunchRunBody.campaignId`;
+   * wicked-studio#27, api-types 0.19.0) — daemon-joined at DTO assembly on `GET /runs` and
+   * `GET /runs/:id` from the launch record (audit trail), so it survives a daemon restart.
+   * ABSENT — never `null` — when the run was not attached (absence is the one spelling).
+   *
+   * NOT set on a campaign's own DAG-node runs: those are correlated through
+   * {@link Campaign.node_run_id} (their run ids are `{campaign}:{node}:a{attempt}`), and a
+   * caller-chosen `sessionId` may legally contain `:`, so id-shape parsing is unsound — read
+   * membership from the campaign, not from this field or the id.
+   */
+  campaign_id?: string;
+  /**
+   * The ad-hoc group label this run was launched under (`LaunchRunBody.groupLabel`;
+   * wicked-studio#27, api-types 0.19.0) — daemon-joined like {@link AgentSession.campaign_id}.
+   * ABSENT when the run is ungrouped. Runs sharing a label form one `RunGroup` on
+   * `GET /campaigns`.
+   */
+  group_label?: string;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -406,6 +430,13 @@ export interface GateInfo {
   prompt: string;
   lifecycle: string;
   receivedAt: string;
+  /**
+   * Refusal-detection warning (issue #419, api-types 0.20.0). Present ONLY when the gate prompt
+   * reads as a pure sandbox/tool refusal — the worker reported it could not act, with no sign of
+   * productive work — so an operator does not approve a refusal as if it were work. Additive and
+   * advisory: it never gates a decision, and is omitted entirely on a normal gate.
+   */
+  refusal?: { matched: boolean; reason: string };
 }
 
 /** Approve / reject payload for the steering gate (`POST /runs/:id/gate`). On a
@@ -512,7 +543,15 @@ export interface CoreEvent {
   updatedDescription?: string;
   // unitOutputCaptured (EVT-013)
   outputBytes?: number;
-  stepStatus?: 'ok' | 'failed' | 'cancelled';
+  /**
+   * How the worker step finished. `'elicitation_failed'` (DES-002) and `'timed_out'` (perf#4 —
+   * the ENGINE's own turn ceiling, `WICKED_UNIT_TIMEOUT_SECS`) widen the original trio.
+   * `'timed_out'` vs `'cancelled'` is THE wire distinction between the platform's deadline and
+   * an operator cancel: automation may key recovery on `'timed_out'`, and must treat
+   * `'cancelled'` as final. Older engines never send the newer values — consumers keying on
+   * them degrade to doing nothing, which is the safe direction.
+   */
+  stepStatus?: 'ok' | 'failed' | 'cancelled' | 'elicitation_failed' | 'timed_out';
   /** `unitOutputDelta` (api-types 0.5.1): one streamed chunk of a worker's live output text. */
   text?: string;
   // unitPlanned enrichment fields — the wire spelling is camelCase (event_to_json);
@@ -630,13 +669,15 @@ export type WorkerStalledFrame = {
 
 /**
  * The stall watchdog's ESCALATION frame (crew#341; api-types 0.18.0). DAEMON-SYNTHETIC, emitted
- * only when escalation is armed (`SystemSettings.workerStallEscalateMinutes` > 0 — OFF by
- * default) and a detected stall stays silent past that threshold. Reports what the watchdog DID
- * and how it ended, one escalation per quiet period:
+ * only when escalation is armed (`SystemSettings.workerStallEscalateMinutes` > 0 — ON by default
+ * as of perf#4, default 30 minutes; an explicit `0` disarms) and a detected stall stays silent
+ * past that threshold. Reports what the watchdog DID and how it ended, one escalation per quiet
+ * period:
  *
- * - `action: 'reassign'` — the wedged cursor unit was recycled in place (engine `reassignUnit`:
- *   the stale turn is superseded, the session closed, the unit re-dispatched; queued operator
- *   injects survive into the fresh turn). `outcome: 'ok' | 'failed' | 'exhausted'`.
+ * - `action: 'reassign'` — the wedged cursor unit was recycled (engine `reassignUnit`: the stale
+ *   turn is superseded, the session closed, the unit re-dispatched; queued operator injects
+ *   survive into the fresh turn), routed to a DIFFERENT seat from the run's pool when one is
+ *   available (perf#4) and in place otherwise. `outcome: 'ok' | 'failed' | 'exhausted'`.
  * - `action: 'notify'` — surface loudly without touching the run (the fail-loud rung).
  *
  * `needsYou: true` marks the frames a human should act on (failed / exhausted / notify).
@@ -656,8 +697,14 @@ export type WorkerStallEscalatedFrame = {
   outcome: 'ok' | 'failed' | 'exhausted';
   /** True when a human should look; false = the platform recovered on its own. */
   needsYou: boolean;
-  /** action `reassign`: the seat the unit was re-dispatched to, when known. */
+  /** action `reassign`: the seat the unit was re-dispatched to, when known. As of perf#4 this
+   *  is the failover TARGET — a different seat from the run's pool when one exists, else the
+   *  stalled seat recycled in place. */
   cli?: string;
+  /** action `reassign` (perf#4, additive): the seat that was stalled and reassigned AWAY from,
+   *  when the watchdog knew it. Equal to `cli` on a single-seat in-place recycle. Absent on
+   *  frames from daemons predating the field. */
+  previousCli?: string;
   /** action `reassign`: automatic reassigns consumed for this run, this one included. */
   escalations?: number;
   /** outcome `failed`: bounded excerpt of what the recovery call threw. */
@@ -920,8 +967,10 @@ export interface UnitReworkAmendedEvent {
 }
 
 /** P2 — a worker's ApplyStepResult arrived and output is ready to be gated. Fires before GateDecided.
- *  `outputBytes` is the byte length of the worker's output; `stepStatus` is "ok"/"failed"/"cancelled";
- *  `governed` reflects whether the runner armed input governance for this unit. */
+ *  `outputBytes` is the byte length of the worker's output; `stepStatus` is "ok" / "failed" /
+ *  "cancelled" / "elicitation_failed" (DES-002) / "timed_out" (perf#4 — the engine's own turn
+ *  ceiling, kept apart from "cancelled" so an operator cancel is never mistaken for a platform
+ *  timeout); `governed` reflects whether the runner armed input governance for this unit. */
 export interface UnitOutputCapturedEvent {
   type: 'unitOutputCaptured';
   session: string;
@@ -929,7 +978,7 @@ export interface UnitOutputCapturedEvent {
   attempt: number;
   /** Byte length of the worker's raw output — distinguishes 0-byte from 8 MB truncated. */
   outputBytes: number;
-  stepStatus: 'ok' | 'failed' | 'cancelled';
+  stepStatus: 'ok' | 'failed' | 'cancelled' | 'elicitation_failed' | 'timed_out';
   governed: boolean;
 }
 
@@ -1518,6 +1567,28 @@ export interface LaunchRunBody {
    * Omit when the launch is not a retry.
    */
   retryOf?: string;
+  /**
+   * Ad-hoc campaign attach (wicked-studio#27; api-types 0.19.0): file this run onto an EXISTING
+   * campaign's surface. Validated at launch, loudly: an unknown campaign id fails the launch
+   * with a 404 naming it (nothing is launched); a deployment whose engine addon lacks the
+   * campaign bindings answers 501 ("upgrade the engine", never "fix your request").
+   *
+   * The attach is daemon-side provenance ONLY (recorded in the `run.launched` audit entry,
+   * restart-durable, echoed as `AgentSession.campaign_id`): the run executes byte-identically
+   * to an unattached launch — it does NOT become a DAG node, is never scheduled, gated, or
+   * cancelled by the campaign, and the campaign's own lifecycle ignores it. It appears on the
+   * campaigns surface as a `Campaign.attached_runs` entry. Mutually exclusive with
+   * `groupLabel` (both ⇒ 400). Omit both for pre-0.19 behavior, byte for byte.
+   */
+  campaignId?: string;
+  /**
+   * Ad-hoc label grouping, created on first use (wicked-studio#27; api-types 0.19.0): runs
+   * launched with the same label form one group — no pre-registration, no scheduler, no DAG,
+   * no shared gates; pure provenance for "these sibling launches are one effort". 1–200
+   * chars. Served as a `RunGroup` row beside the campaigns on `GET /campaigns` and echoed as
+   * `AgentSession.group_label`. Mutually exclusive with `campaignId` (both ⇒ 400).
+   */
+  groupLabel?: string;
 }
 
 /**
@@ -1785,16 +1856,23 @@ export interface SystemSettings {
   /**
    * The stall watchdog's ESCALATION threshold (crew#341; api-types 0.18.0): quiet minutes before
    * the watchdog ACTS on a detected stall (see {@link WorkerStallEscalatedFrame}). Integer
-   * 0..1440; **absent or 0 = escalation OFF — the shipped default** (the issue's design: automatic
-   * recovery on a run that is merely slow would be worse than the wedge). Values below
+   * 0..1440; `0` = escalation OFF. **Absent = the daemon default (30 — armed)**: as of perf#4 the
+   * ladder is ON by default (run 616c8661 burned a full 2h turn ceiling with the watchdog
+   * detection-only; the engine's `reassignUnit` supersedes the wedged turn safely, so acting is
+   * strictly better than watching). 30 leaves ~55% headroom over the slowest legitimate
+   * time-to-first-output observed in the field (~19.4 min) while still recovering ~4x faster
+   * than the 2h ceiling. Opt out with an explicit `0`. Values below
    * `workerStallMinutes` escalate at the detection threshold — the ladder never acts before it
    * has notified.
    */
   workerStallEscalateMinutes?: number;
   /**
    * What an armed escalation DOES (crew#341): `'reassign'` (default) recycles the wedged cursor
-   * unit in place — the engine supersedes the stale turn, closes the worker session, bumps the
-   * attempt, and re-dispatches (queued operator injects survive into the fresh turn);
+   * unit — the engine supersedes the stale turn, closes the worker session, bumps the
+   * attempt, and re-dispatches (queued operator injects survive into the fresh turn). As of
+   * perf#4 the watchdog routes the re-dispatch to a DIFFERENT seat from the run's own pool when
+   * one is available (a seat that just sat silent past the escalation threshold is the last
+   * seat to hand the retry to), falling back to an in-place recycle on a single-seat pool.
    * `'notify'` is the fail-loud rung — a `needsYou` `workerStallEscalated` frame + an audit
    * entry, the run untouched.
    */
@@ -2408,7 +2486,17 @@ export interface Campaign {
   /** The full definition, embedded so a resume needs no second store. */
   def: CampaignDef;
   node_status: Record<string, CampaignNodeStatus>;
-  /** node_id -> live Run id, always `{campaign}:{node}:a{attempt}` (attempt-keyed, idempotent). */
+  /**
+   * node_id -> live Run id, always `{campaign}:{node}:a{attempt}` (attempt-keyed, idempotent).
+   *
+   * These values ARE the engine session ids: a node's run is an ordinary governed run, so it is
+   * served by `GET /runs` / `GET /runs/:id` under exactly this id, and every session-scoped
+   * CoreEvent frame on `/ws` carries it as `session` (the `campaignNodeStarted` /
+   * `campaignNodeAwaitingHuman` frames additionally spell it as `runId`). Live narration for a
+   * campaign card is therefore a pure client-side correlation:
+   * `frame.session === campaign.node_run_id[node]` — no extra wire, no per-node fetch
+   * (wicked-studio#27).
+   */
   node_run_id: Record<string, string>;
   /** node_id -> 0-based attempt counter (a `human_gate_on_failure` Retry bumps it). */
   node_attempt: Record<string, number>;
@@ -2418,6 +2506,72 @@ export interface Campaign {
   pending_failure_gates: string[];
   /** Whether a fail-fast (or Abort) tripped — finalization lands on `failed`. */
   fail_fast_tripped: boolean;
+  /**
+   * Per-node delivery (wicked-studio#27; api-types 0.19.0) — DAEMON-JOINED at DTO assembly on
+   * `GET /campaigns` and `GET /campaigns/:id`, never engine-persisted: the exact same
+   * `delivery`/`deliverUrl` derivation every run already carries on the runs wire
+   * (`AgentSession.delivery`, crew#393/#311), keyed by node_id like {@link Campaign.node_status}.
+   * A node appears here once its current-attempt run (`node_run_id[node]`) exists on the store —
+   * a still-pending node has no entry. With `node_run_id` + `node_status`, this is everything a
+   * "N of M delivered" rollup needs from ONE campaigns fetch — no per-node run fetch, and no
+   * dependence on the runs list's archived-run filtering. ABSENT only from a pre-0.19 daemon.
+   */
+  node_delivery?: Record<string, CampaignNodeDelivery>;
+  /**
+   * Ad-hoc runs attached to this campaign at launch (`LaunchRunBody.campaignId`;
+   * wicked-studio#27, api-types 0.19.0) — DAEMON-JOINED like {@link Campaign.node_delivery},
+   * launch order. These are NOT DAG nodes: the campaign's scheduler and lifecycle ignore them;
+   * each entry is an independent governed run that an operator filed onto this campaign's
+   * surface. Absent from a pre-0.19 daemon; `[]` when none. Narration correlation is the same
+   * as for nodes: each `runId` is the engine session id on `/ws` frames (`frame.session`).
+   */
+  attached_runs?: AttachedRunView[];
+}
+
+/**
+ * One member's delivery snapshot on the campaigns surface (wicked-studio#27; api-types 0.19.0)
+ * — the same tri-state + URL contract as `AgentSession.delivery`/`deliverUrl` (crew#393/#311),
+ * derived by the same code at DTO assembly. `deliverUrl` present exactly when
+ * `delivery === 'delivered'`.
+ */
+export interface CampaignNodeDelivery {
+  delivery: 'delivered' | 'stranded' | 'vacuous' | 'none';
+  deliverUrl?: string;
+}
+
+/**
+ * An ad-hoc run on the campaigns surface (wicked-studio#27; api-types 0.19.0) — a member of
+ * `Campaign.attached_runs` or `RunGroup.runs`. `runId` is the engine session id: the run is
+ * served in full by `GET /runs/:id`, and live `/ws` CoreEvent frames for it carry it as
+ * `session`. `status`/`delivery`/`deliverUrl` are snapshots of the same fields the run wire
+ * serves, so a rollup needs no second fetch.
+ */
+export interface AttachedRunView {
+  runId: string;
+  status: SessionStatus;
+  delivery: 'delivered' | 'stranded' | 'vacuous' | 'none';
+  deliverUrl?: string;
+}
+
+/**
+ * An ad-hoc label group (wicked-studio#27; api-types 0.19.0): the runs launched with the same
+ * `LaunchRunBody.groupLabel`, in launch order. NOT an engine campaign — no DAG, no scheduler,
+ * no status of its own (derive a rollup from the members); it exists the moment the first run
+ * is launched under the label. Served beside the campaigns in `CampaignsListResponse.groups`.
+ */
+export interface RunGroup {
+  label: string;
+  runs: AttachedRunView[];
+}
+
+/**
+ * `GET /campaigns` 200 body (api-types 0.19.0 — `groups` is ADDITIVE: a pre-0.19 daemon sends
+ * only `campaigns`). One fetch answers the whole grouping surface: engine campaigns (each
+ * carrying its own per-node rollup fields) plus the ad-hoc label groups.
+ */
+export interface CampaignsListResponse {
+  campaigns: Campaign[];
+  groups: RunGroup[];
 }
 
 /**

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.18.0",
+  "version": "0.20.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames \u2014 types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",