wicked-crew-api-types 0.88.0 → 0.92.0

package/index.d.ts

@@ -215,6 +215,15 @@ export interface HealthResponse {
 export interface HealthCapabilities {
   /** See {@link HealthResponse} — the engine's deliver gate exists (wicked-core-ts ≥ 0.7.24). */
   deliverGate: boolean;
+  /**
+   * (DES-ASK-TEAM-CHAT-001 §5.1; api-types 0.92.0) An ask starts a PATH: `POST /chats` resolves
+   * eligibility and warms nothing, the first `POST /chats/:id/messages` launches one team run
+   * (one PA, picked at random among the eligible seats unless `primary` names one; a reviewer
+   * member), later messages continue it, and the reply is the PA's `step.completed` output. The
+   * whole behaviour contract — launch, continue, output review — needs wicked-core-ts ≥ 0.7.38;
+   * ABSENT or `false` means this daemon still fans a send out to every warm seat.
+   */
+  askPath?: boolean;
   /**
    * `LaunchRunBody.revisesPr` is accepted (crew#550; crew ≥ 0.7.36). ABSENT on a daemon before
    * the field — read as `false`: do not send `revisesPr` to such a daemon.
@@ -1010,7 +1019,7 @@ export interface RunFileContent {
 export interface RunDiff {
   /** Unified diff text (`git diff --no-color --no-ext-diff HEAD`), cut at 1 MB when `truncated`. */
   diff: string;
-  /** The diff exceeded the 1 MB output cap and was cut. */
+  /** The diff exceeded the 1 MB output cap and was cut (or, crew#790, ran out of its time budget). */
   truncated: boolean;
   /**
    * Where the diff was read from (wave 6, F-7R2-013; api-types 0.36.0): `worktree` — the live run
@@ -1025,7 +1034,12 @@ export interface RunDiff {
   branch?: string;
   /** `source: 'branch'` — the base commit the branch was diffed against: the engine's recorded
    *  `AgentSession.base_commit` when it has one, else the branch's merge-base with the default
-   *  branch; `?base=<ref>` overrides it with a plain in-repo ref. */
+   *  branch; `?base=<ref>` overrides it with a plain in-repo ref. `source: 'worktree'` (crew#790)
+   *  — present when no `?base=` was sent and the worktree was diffed against the recorded
+   *  `base_commit` (committed AND uncommitted run work); absent when the baseline was HEAD (no
+   *  recorded base, or it does not resolve in the worktree). `truncated` is also `true` when the
+   *  untracked-file pass stopped at its time budget on a busy host; a git stopped before it
+   *  answered is 503 `{ code: "diff_busy" }` with `Retry-After`. */
   base?: string;
 }
 
@@ -1135,6 +1149,11 @@ export interface LaunchPlan {
   steps: Array<{ catalog: string; id?: string | undefined; [k: string]: unknown }>;
   touch?: string[];
   override?: TeamPlanOverride;
+  /**
+   * (DES-TEAMING-002 §6.1 `plan.proposed.monitors`; core ASK-K1b) How many members the plan asks
+   * for; the supervisor seats `min(max(band monitors, asked), 3)`. An ask asks for one reviewer.
+   */
+  monitors?: { asked: number };
 }
 
 /**
@@ -4542,6 +4561,17 @@ export interface BlastRadius {
    * hot symbol. When non-zero, an empty `dependents` still never means "safe".
    */
   unresolved: number;
+  /**
+   * Completeness causes from estate (wicked-estate#222, estate >= 0.18.0; api-types 0.91.0, crew#751),
+   * ABSENT on an older estate. `depth_horizon_reached`: the depth horizon stopped the walk with
+   * dependents beyond it; `node_cap_reached`: the node budget dropped reachable nodes;
+   * `searched_depth`: the horizon that applied (re-ask with a larger one); `truncated_dependents`:
+   * rows estate had but cut to fit its output budget. Any of them set ⇒ `dependents` is partial.
+   */
+  depth_horizon_reached?: boolean;
+  node_cap_reached?: boolean;
+  searched_depth?: number;
+  truncated_dependents?: number;
 }
 
 /** An open elicitation as `GET /runs/:id/elicitation` returns it (DES-002). */
@@ -5004,8 +5034,10 @@ export interface InteractiveDocsListing {
   unreachable: InteractiveDocsUnreachable[];
 }
 
-/** The seams that can answer a document (the handoff ledgers). */
-export type InteractiveSeamKind = 'draft' | 'edit' | 'chat' | 'demo' | (string & {});
+/** The seams that can answer a document (the handoff ledgers). `theme` (EP-C4 theme learning) and
+ *  `review` (EP-C2 reviews) keep their rows in the edit seam's ledger and are told apart by the row
+ *  key (api-types 0.90.0, crew#785): a document only reviewed reads `review`, never `edit`. */
+export type InteractiveSeamKind = 'draft' | 'edit' | 'chat' | 'demo' | 'theme' | 'review' | (string & {});
 
 /** One document on the daemon-wide listing (api-types 0.36.0). */
 export interface InteractiveDocIndexRow {
@@ -5140,6 +5172,12 @@ export interface ChatOpenBody {
    *   - `none`       — the legacy unscoped chat; takes neither `projectId` nor `repoRefs`.
    */
   scopeKind?: ChatScopeRequestKind;
+  /**
+   * (DES-ASK-TEAM-CHAT-001 §4.1; api-types 0.92.0) The seat the operator CHOSE as the primary
+   * agent — one of the eligible seats, else 400. Omitted: the engine picks one at random
+   * (`path.started.selection: "random"`).
+   */
+  primary?: string;
 }
 
 /** The scope a `POST /chats` caller may name (api-types 0.39.0, studio#323 R4). */
@@ -5294,6 +5332,9 @@ export interface ChatMessageResponse {
    * and only `POST /chats` → 201, which performed the open, says anything about that moment.
    */
   singleSeat?: ChatSingleSeatDegradation;
+  /** (api-types 0.92.0) The ask path this message launched or continued, and its answer step. */
+  runId?: string;
+  stepId?: string;
 }
 
 /**
@@ -5462,6 +5503,25 @@ export interface ChatDetailResponse {
    * "session continues" without history). Unbounded — a reply may be up to the engine's cap.
    */
   messages?: ChatTranscriptRecord[];
+  /**
+   * (DES-ASK-TEAM-CHAT-001 §5.1; api-types 0.92.0) The chat's path once its first message
+   * launched it: the run, the PA and how it was picked, the reviewer member (null until one
+   * attached) and the helpers that answered. Absent before the first message and on a daemon
+   * without `capabilities.askPath`.
+   */
+  path?: ChatPathView;
+}
+
+/** (api-types 0.92.0) A chat's ask path — see {@link ChatDetailResponse.path}. */
+export interface ChatPathView {
+  runId: string;
+  /** The primary agent's seat key, `null` until `path.started` has been seen. */
+  pa: string | null;
+  selection: 'chosen' | 'random';
+  reviewer: string | null;
+  helpers: string[];
+  /** The answer step the last message added (`answer-N`). */
+  stepId: string;
 }
 
 // ── Project code graph (DES-PROJECT-001; the co-located multi-repo graph) ──────
@@ -5656,6 +5716,17 @@ export interface ProjectBlastRadius {
   missingRepos: string[];
   linkage: ProjectGraphLinkage;
   note: string;
+  /**
+   * Completeness causes from estate (wicked-estate#222, estate >= 0.18.0; api-types 0.91.0, crew#751),
+   * ABSENT on an older estate. `depth_horizon_reached`: the depth horizon stopped the walk with
+   * dependents beyond it; `node_cap_reached`: the node budget dropped reachable nodes;
+   * `searched_depth`: the horizon that applied (re-ask with a larger one); `truncated_dependents`:
+   * rows estate had but cut to fit its output budget. Any of them set ⇒ `dependents` is partial.
+   */
+  depth_horizon_reached?: boolean;
+  node_cap_reached?: boolean;
+  searched_depth?: number;
+  truncated_dependents?: number;
 }
 
 /** `GET /projects/:id/graph/search?name=` — exact-name symbol resolution across member repos. */
@@ -6839,7 +6910,8 @@ export interface WalkthroughView {
   /** Proof-root-relative paths of the stitched take; `null` until there is one. */
   video: { mp4: string | null; poster: string | null; markers: DemoMarker[] };
   chapters: WalkthroughChapter[];
-  /** Per creator step, the check state from THIS pair's take — computed at every read from its re-verified seal (WT-W2). */
+  /** Per creator step, the check state from THIS pair's take — computed at every read from its re-verified seal (WT-W2).
+   *  With no pair because the accepted plan's override removed it, every finished creator step `owned_by_you` (0.88.1). */
   steps: WalkthroughStepState[];
 }
 
@@ -6850,7 +6922,9 @@ export interface WalkthroughView {
  * engine-captured output), `bundle_sha` recomputed from the proof root, and the proof root's stamped
  * ledger verdicts against the sealed chapter verdicts. The gate is deny-dominates across the repo
  * ledger and every row: a missing, mismatched ("changed after it was sealed") or non-PASS seal
- * denies. ABSENT when the requirement names no walkthrough step.
+ * denies. ABSENT when the requirement names no walkthrough step — except when the accepted plan's floor
+ * override removed the walkthrough pair (§4.9; api-types 0.88.1): then it is present with `roots: []`,
+ * `sealed: true` (nothing to seal) and every finished creator step `owned_by_you`.
  */
 export interface RunAcceptanceWalkthrough {
   roots: Array<{ stepId: string; sealed: boolean; satisfied: boolean; reason: string }>;
@@ -6871,7 +6945,8 @@ export interface RunAcceptanceSummary {
   /** Deny-dominates across the repo ledger and every walkthrough (`gate.satisfied`). */
   satisfied: boolean;
   line: string;
-  /** From the newest walkthrough; `null` when the requirement names none. */
+  /** From the newest walkthrough; `null` when the requirement names none — unless the accepted plan's
+   *  override removed the pair (then `tree` is `null` and `ownedByYou` counts the operator's steps). */
   walkthrough: {
     checked: number;
     failed: number;
@@ -6904,6 +6979,24 @@ export interface PutStorylineResponse {
   at: string;
 }
 
+/**
+ * `GET /runs/:id/walkthrough/storyline?step=` → 200 (#782; api-types 0.89.0): the author's storyline
+ * — `author/<planStepId>/storyline.mjs` — so "Edit the check" can prefill the box and send the edit
+ * back through `PUT` ({@link PutStorylineBody}). Readable at any run status. `step` names the author or
+ * its recorder (default: the newest pair). 404 `no_storyline` before the author wrote one; 409
+ * `no_author` / `no_evidence_root` / `read_refused` (a link or a non-file, never followed); 413 over
+ * 256 KB. `edited_by` / `at` come from crew's edit marker only when its `sha256` names THIS text.
+ */
+export interface WalkthroughStorylineView {
+  runId: string;
+  planStepId: string;
+  storyline: string;
+  sha256: string;
+  edited_by: 'human' | null;
+  /** ISO-8601 of the operator's edit; `null` when the text is the author's. */
+  at: string | null;
+}
+
 /** `POST /proposals/:id/reject` → 200. */
 export interface RejectProposalResponse {
   ok: true;
@@ -7065,7 +7158,9 @@ export type TeamEventType =
   | 'wicked.team.ledger.folded'
   | 'wicked.team.gate.opened'
   | 'wicked.team.gate.decided'
-  | 'wicked.team.path.ended';
+  | 'wicked.team.path.ended'
+  /** (DES-ASK-TEAM-CHAT-001 §4.1; core ASK-K1a) The PA changed mid-path. */
+  | 'wicked.team.path.repicked';
 
 /** The fields every team payload carries. */
 export interface TeamEnvelope {
@@ -7165,6 +7260,15 @@ export type TeamPlanAcceptedPayload = TeamEnvelope & {
   steps: TeamPlanStep[];
   override: TeamPlanOverride | null;
   proposal_id: string | null;
+  /**
+   * (core TR-W1a) This rev's declared touch unioned with every earlier accepted rev's, first-seen
+   * order, capped; absent on rows written before the field existed. `touch_source` names where
+   * THIS rev's declared touch came from: `user` (the launch), `pa_scope` (the PA's SCOPE answer,
+   * or — DES-TEAMING-002 rev 15 — the touch a first-creator PA `PLAN+` declared), `none`.
+   */
+  touch?: string[];
+  touch_truncated?: boolean;
+  touch_source?: 'user' | 'pa_scope' | 'none' | (string & {});
 };
 
 export type TeamPlanRefusedPayload = TeamEnvelope & {
@@ -7176,7 +7280,12 @@ export type TeamPlanRefusedPayload = TeamEnvelope & {
 export type TeamMemberJoinedPayload = TeamEnvelope & {
   member_id: string;
   open_seq: number;
-  seat: string;
+  /**
+   * (DES-ASK-TEAM-CHAT-001 §4.6; core ASK-K3a) `null` on a `status: 'failed'` row published when
+   * no distinct seat exists to seat the member on (one signed-in seat); `member_id`/`open_seq`
+   * are still minted, so the row keeps its key.
+   */
+  seat: string | null;
   role: 'monitor' | (string & {});
   status: 'attached' | 'failed' | (string & {});
   reason: string;
@@ -7220,6 +7329,12 @@ export type TeamFindingRaisedPayload = TeamEnvelope & {
   anchor: string | null;
   anchor_source: 'graph' | 'hunk' | 'none' | (string & {}) | null;
   severity: 'high' | 'medium' | (string & {});
+  /**
+   * (DES-ASK-TEAM-CHAT-001 §4.6; core ASK-K3a) What the finding cites: a line of the settled tree
+   * (`tree`, absent on old rows) or a line of the step's output (`output`: `path` is the step id,
+   * `line` a line of the output; the bar is `medium`).
+   */
+  target?: 'tree' | 'output' | (string & {});
   path: string;
   line: number;
   evidence: string;
@@ -7228,6 +7343,8 @@ export type TeamFindingRaisedPayload = TeamEnvelope & {
   tree: string;
   in_diff: boolean;
   corroborated_by: string[];
+  /** (core T6) The attempt that first raised it, when a redriven attempt carried it; else null. */
+  carried_from_attempt?: number | null;
 };
 
 export type TeamAdviceDeliveredPayload = TeamEnvelope & {
@@ -7260,8 +7377,16 @@ export type TeamHelpRequestedPayload = TeamEnvelope & {
 export type TeamHelpAnsweredPayload = TeamEnvelope & {
   help_id: string;
   answer_id: string;
-  answer: string;
+  /** `null` when `outcome` is not `answered` (core ASK-K3a). */
+  answer: string | null;
   evidence: string[];
+  /**
+   * (DES-ASK-TEAM-CHAT-001 §4.5; core ASK-K3a) The help turn's terminal outcome, a fact on the row
+   * S owns — never inferred from a missing row. Absent on old rows (= `answered`).
+   */
+  outcome?: 'answered' | 'timed_out' | 'failed' | 'no_member' | (string & {});
+  /** Why, for a non-`answered` outcome. */
+  error?: string | null;
 };
 
 export type TeamChangeRequestedPayload = TeamEnvelope & {
@@ -7277,6 +7402,11 @@ export type TeamStepCompletedPayload = TeamEnvelope & {
   tree: string | null;
   output_bytes: number;
   output_ref: string;
+  /**
+   * (core ASK-K3c) The attempt's `[team advice]` boundary block reached a seat turn. Omitted
+   * when false (old rows read false).
+   */
+  answers_presented?: boolean;
 };
 
 export type TeamStepReviewedPayload = TeamEnvelope & {
@@ -7284,6 +7414,8 @@ export type TeamStepReviewedPayload = TeamEnvelope & {
   verdict: 'accepted' | 'rejected' | (string & {});
   to: 'member' | 'pa' | (string & {}) | null;
   reason: string;
+  /** (core T6) The attempt of `step_id` the verdict is about; null on rows written before it existed. */
+  reviewed_attempt?: number | null;
 };
 
 export type TeamFindingSettledPayload = TeamEnvelope & {
@@ -7439,6 +7571,21 @@ export type TeamPathEndedPayload = TeamEnvelope & {
   status: 'completed' | 'failed' | 'cancelled' | (string & {});
 };
 
+/**
+ * (DES-ASK-TEAM-CHAT-001 §4.1; core ASK-K1a) `wicked.team.path.repicked` (E): a PA step's attempt
+ * ended for a seat cause (`timed_out`, `failed`, a seat refusal's class) and another eligible seat
+ * took over as the PA. The envelope's `ord`/`attempt` name the step; it is redispatched as
+ * attempt+1 on `to`. Keyed by `pick_seq`, the engine's per-run re-pick counter (from 1).
+ */
+export type TeamPathRepickedPayload = TeamEnvelope & {
+  from: string;
+  to: string;
+  reason: string;
+  /** Always `'random'`: a re-pick is never the operator's choice. */
+  selection: 'random' | (string & {});
+  pick_seq: number;
+};
+
 /** Each team event type's payload. */
 export interface TeamEventPayloads {
   'wicked.team.path.started': TeamPathStartedPayload;
@@ -7466,6 +7613,7 @@ export interface TeamEventPayloads {
   'wicked.team.gate.opened': TeamGateOpenedPayload;
   'wicked.team.gate.decided': TeamGateDecidedPayload;
   'wicked.team.path.ended': TeamPathEndedPayload;
+  'wicked.team.path.repicked': TeamPathRepickedPayload;
 }
 
 /** One team bus row, discriminated on `event_type`. */

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.88.0",
+  "version": "0.92.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",