wicked-crew-api-types 0.91.0 → 0.94.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.
@@ -1140,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 };
 }
 
 /**
@@ -1399,6 +1413,30 @@ export interface CoreEvent {
  * named live, and a bundle assembled after a run cannot describe it in different
  * words than the operator watched it happen in. (FINDING-014)
  */
+/**
+ * The engine's ORPHAN frame (wicked-core `RunOrphaned`, core#124; named here additively for
+ * crew#830). Written to a run's durable event log at actor bootstrap for every session the store
+ * still calls `executing` that the new process restored no worker for — the daemon died mid-run.
+ * It is a REPORT, not a terminal: the run stays `executing` and resumable (`qe/acceptance.ts` keeps
+ * it out of the terminal set on purpose). A trail that ENDS on this frame is a run nobody is
+ * running; a live run's trail continues past it.
+ *
+ * The daemon acts on it at boot: every `executing` run whose trail ends on `runOrphaned` is resumed
+ * once through the engine's `resumeRun` (the same path as `POST /runs/:id/resume`) and the resume is
+ * recorded in the audit trail as `run.resumed` by the `daemon` actor with
+ * `detail: { via: 'boot', status, ord? }` — `via: 'boot'` is what tells it apart from an operator's
+ * manual resume (`detail: { status }`, actor = the caller).
+ */
+export type RunOrphanedFrame = {
+  type: 'runOrphaned';
+  /** The orphaned run's id. */
+  session: string;
+  /** The cursor unit's 1-based ord (the cursor position when the units could not be read). */
+  ord: number;
+  /** The remedy, spelled out: `POST /api/v1/runs/<id>/resume`. */
+  detail: string;
+};
+
 /**
  * The stall watchdog's DETECTION frame (crew#287; api-types 0.18.0 — previously daemon-local).
  * DAEMON-SYNTHETIC: broadcast straight to `/ws` when a run in `executing` has been silent on the
@@ -1468,9 +1506,12 @@ export type WorkerStallEscalatedFrame = {
    * `evaluating` — the worker returned and its gate evaluation is in flight, a reassign would start
    * a second creator; `evaluator_distinct` — every other seat is one evaluator ≠ creator forbids
    * (see `avoided`), so the unit was left for a human; `no_output` (outcome `exhausted`) — the
-   * reassigned seat produced nothing past a startup banner.
+   * reassigned seat produced nothing past a startup banner; `no_eligible_seat` (crew#833; additive)
+   * — every other seat is one this run BENCHED (see `benched`: quota exhausted, signed out — a seat
+   * the engine already failed over away from) or one evaluator ≠ creator forbids (see `avoided`),
+   * so the unit was left for a human rather than dispatched to a seat known to fail.
    */
-  reason?: 'tool_unit' | 'evaluating' | 'evaluator_distinct' | 'no_output';
+  reason?: 'tool_unit' | 'evaluating' | 'evaluator_distinct' | 'no_output' | 'no_eligible_seat';
   /**
    * The seats the failover pick excluded under evaluator ≠ creator (crew#638; additive): a
    * creator cursor avoids the run's evaluator seats, an evaluator cursor the seats that built its
@@ -1478,6 +1519,13 @@ export type WorkerStallEscalatedFrame = {
    * reassign that skipped one and on a `reason: 'evaluator_distinct'` notify; absent otherwise.
    */
   avoided?: string[];
+  /**
+   * The pool seats the failover pick excluded because THIS RUN benched them (crew#833; additive):
+   * `AgentSession.benched_seats` keys — a seat the engine failed over away from (quota exhausted,
+   * signed out, dead) is never a failover target in the same run. Present on an `ok` reassign that
+   * skipped one and on a `reason: 'no_eligible_seat'` notify; absent otherwise.
+   */
+  benched?: string[];
 };
 
 export interface RecordedEvent extends CoreEvent {
@@ -3057,6 +3105,14 @@ export interface SkillsManifestResponse {
    * `manifest.baseline`: different = Refresh baseline, then Publish.
    */
   installed?: InstalledPlugin | null;
+  /**
+   * Whether a `POST /skills/publish` is running on the daemon right now (crew#852; api-types
+   * 0.94.0) — its validate / hash / stage / lock run paced on the event loop, so this read answers
+   * while it runs, and `current` names the PREVIOUS generation until the publish commits and flips
+   * it (a reader sees the old generation or the new one, never half). A second publish in that
+   * window is the 2xx `publish-in-flight` envelope. Absent on a daemon older than 0.8.4.
+   */
+  publishing?: boolean;
 }
 
 /** `SkillsManifestResponse.installed` — the live plugin's identity (wicked-studio#388). */
@@ -4916,6 +4972,43 @@ export interface InteractiveStatusPosted {
   /** Wave 6: the unit (ord) the line narrates — the latest unit-scoped engine frame's `ord`, so a
    *  skin renders one council at a time. Absent before the first unit-scoped frame. */
   unit_ord?: number;
+  /**
+   * crew#512 (api-types 0.93.0): the document's repository grounding as data — present on exactly
+   * ONE frame per draft launch, the same `working` frame whose `message` is the "Grounded on …" /
+   * "Requested repository … skipped." narration (the text stays, for a skin that renders the
+   * transcript only). A skin keys a persistent header chip off this and never parses the sentence.
+   * Absent on every other frame, on a pre-0.93 daemon, and when the project has no repositories.
+   */
+  grounding?: InteractiveDocGrounding;
+}
+
+/**
+ * Where a document is grounded and why (crew#512; api-types 0.93.0) — the structured twin of the
+ * draft seam's "Grounded on …" narration (`groundingNarration`, doc-grounding.ts). Rides the one
+ * `InteractiveStatusPosted` frame that carries the narration and, once recorded, the document's
+ * `InteractiveDocSummary` row — the same object in both places, from the `crew-grounding.json`
+ * sidecar beside the document.
+ */
+export interface InteractiveDocGrounding {
+  /** Registry ids of the repositories the launch grounded on — the worker reads an offline snapshot
+   *  of each. `[]` = not repository-grounded (brief + code graph only). Names resolve through `GET /repos`. */
+  repo_refs: string[];
+  /** Why those: `named` — `repo_ref(s)` on the create request; `brief` — the brief names member repos;
+   *  `sole-member` — the project's only repository; `none` — nothing named, nothing inferred. */
+  source: 'named' | 'brief' | 'sole-member' | 'none';
+  /** Requested repositories that grounded nothing, with why (the narration's "skipped" clauses). */
+  skipped: InteractiveDocGroundingSkip[];
+  /** How many repositories the project has — the "1 of N" in a chip; `0` for a repo-less project. */
+  member_count: number;
+}
+
+/** One repository a launch did not ground on, as spelled on the request (or its registry id). */
+export interface InteractiveDocGroundingSkip {
+  ref: string;
+  /** `not-a-member` — not (or no longer) a project member; `ambiguous` — several members share that
+   *  name, the registry id disambiguates; `unsnapshotable` — a member whose offline snapshot failed
+   *  (too large, unreadable, …), so the task names it but the worker has no copy. */
+  reason: 'not-a-member' | 'ambiguous' | 'unsnapshotable';
 }
 
 // ── EP-C2: a document's checks — the four reviewers (api-types 0.88.0) ─────────────────────────
@@ -4999,6 +5092,14 @@ export interface InteractiveDocSummary {
   retired_at?: string;
   /** The crew project this row was listed under — the mount's `:projectId`. */
   projectId: string;
+  /**
+   * crew#512 (api-types 0.93.0): the repository grounding the draft seam resolved for this document,
+   * read from the `crew-grounding.json` sidecar beside it — the same object the launch's status
+   * frame carried, so a reopened document shows its chip without replaying the thread. Absent
+   * until a draft launch resolved it (a document still generating, one created before this release, an
+   * unfiled document) and on a pre-0.93 daemon.
+   */
+  grounding?: InteractiveDocGrounding;
 }
 
 /**
@@ -5158,6 +5259,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). */
@@ -5312,6 +5419,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;
 }
 
 /**
@@ -5480,6 +5590,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) ──────
@@ -6203,7 +6332,10 @@ export interface GovernanceReplayOutcome {
   alreadyPresent: number | null;
   failed: number;
   dryRun: boolean;
-  /** The same-event conflation caveat the CLI prints, or `null`. */
+  /** The caveat the CLI prints, or `null`: on a dry run, that the outbox's untimestamped (pre-stamp) entries
+   *  cannot be ordered by a replay — they land in file order, and byte-identical unstamped lines share one
+   *  replay id (crew#829; `null` when every entry is stamped); on a real replay, the same-event conflation
+   *  caveat when entries were `alreadyPresent` and the outbox held unstamped lines. */
   note: string | null;
   /** Dry run only: the outbox fold (the `/diagnostics` dead-letter block minus the legacy pointer). */
   fold?: Omit<DiagnosticsGovernanceDeadletters, 'legacyOutbox'>;
@@ -7116,7 +7248,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 {
@@ -7216,6 +7350,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 & {
@@ -7227,7 +7370,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;
@@ -7271,6 +7419,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;
@@ -7279,6 +7433,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 & {
@@ -7311,8 +7467,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 & {
@@ -7328,6 +7492,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 & {
@@ -7335,6 +7504,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 & {
@@ -7490,6 +7661,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;
@@ -7517,6 +7703,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.91.0",
+  "version": "0.94.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",