wicked-crew-api-types 0.38.0 → 0.39.0

package/index.d.ts

@@ -191,6 +191,17 @@ export interface HealthCapabilities {
    * the field — read as `false`: do not send `revisesPr` to such a daemon.
    */
   revisesPr?: boolean;
+  /**
+   * `LaunchRunBody.chatId` is accepted (crew#619; crew ≥ 0.7.39). ABSENT on a daemon before
+   * the field — read as `false`: do not send `chatId` to such a daemon.
+   */
+  chatIdOnLaunch?: boolean;
+  /**
+   * `InteractiveDocCreateRequest.clisJson` (and the same field on demo/video and testing bodies)
+   * is accepted (crew#631; crew ≥ 0.7.40). ABSENT on a daemon before the field — omit `clisJson`
+   * on such a daemon.
+   */
+  seatChipOnCreate?: boolean;
 }
 
 /** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
@@ -399,6 +410,37 @@ export interface AgentSession {
   /** Wave 6 (F-7R2-006): the seats BENCHED for this run — never convened, never a failover or
    *  judge target. Absent (never `[]`) when none / on an older engine. */
   benched_seats?: BenchedSeat[];
+  /** crew#661: the declared skills this run's phases ran WITHOUT (the published skills snapshot did not
+   *  hold them when the launching subsystem armed) — the run proceeded DEGRADED, and says so here.
+   *  ABSENT (never `[]`) when the run launched fully armed, and on a daemon before this field. */
+  skill_gaps?: RunSkillGap[];
+  /**
+   * The surface that triggered this launch (crew#632; crew ≥ 0.7.40): `'studio'` (web UI),
+   * `'cli'` (wicked-crew CLI), or `'api'` (programmatic). ABSENT when the launch did not include
+   * the field (an older daemon or a caller that omitted it).
+   */
+  channel?: 'studio' | 'cli' | 'api';
+  /**
+   * An opaque caller-supplied identifier for the user or system that triggered the launch
+   * (crew#632; crew ≥ 0.7.40). ABSENT when the launch did not name one. Use `AgentSession.actor`
+   * (the authenticated crew actor) for the identity of WHO launched; `launch_actor` is an
+   * ADDITIONAL annotation the caller may attach (e.g. a CI job name or a studio tab id).
+   */
+  launch_actor?: string;
+  /**
+   * The number of warm seats in the chat this run was promoted from (crew#641/#642, item 5).
+   * ABSENT — never `null` — when the run was not promoted from a chat (`chatId` absent at launch)
+   * or on a daemon predating this field. A value of `1` means the intent was authored by a single
+   * model that could not disagree with itself.
+   */
+  chat_seat_count?: number;
+  /**
+   * Whether the chat this run was promoted from was graph-grounded at launch (crew#641/#642,
+   * item 5). `true` = at least one repo graph was bound and held entities; `false` = ungrounded.
+   * ABSENT — never `null` — when the run was not promoted from a chat or on a daemon predating
+   * this field.
+   */
+  chat_grounded?: boolean;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -885,7 +927,7 @@ export interface CoreEvent {
   seatConstraint?: string | null;
   /** `unitDistributed` (wicked-core#461): the evaluator ≠ creator fallback as a field — see
    *  `UnitDistributedEvent.distinctnessFallback`. */
-  distinctnessFallback?: 'creator_seat' | null;
+  distinctnessFallback?: 'creator_seat' | 'same_cli_instance' | null;
   /** `gateEvaluated` (wave 6, F-7R2-005): `true` when NOTHING gated the unit — render as UNGATED. */
   ungated?: boolean;
   /** `gateEvaluated` (wave 6): why, when `ungated`. */
@@ -1995,8 +2037,14 @@ export interface UnitDistributedEvent {
    * never absent — the `seatConstraint` rule) from the wicked-core release carrying #461 on, but an
    * older engine does not send it at all, and this contract must read frames from both. Consumers
    * guard with `== null`, never `=== undefined`.
+   *
+   * `'same_cli_instance'` (wicked-core#591/#595): the unit IS on a seat distinct from every builder
+   * seat, but that seat runs the SAME cli as a builder (`claude#2` grading `claude#1`) — instance
+   * distinctness removes the creator's context, not the model's blind spots, so it is a degraded
+   * gate and disclosed. `'creator_seat'` dominates when both would apply. Consumers must treat an
+   * unrecognised value as a disclosure too, never as "distinct".
    */
-  distinctnessFallback?: 'creator_seat' | null;
+  distinctnessFallback?: 'creator_seat' | 'same_cli_instance' | null;
   /** @deprecated api-types 0.36.0 — the engine emits `routingMethod`; removed in 0.37. */
   routing_method?: 'council' | 'degraded' | 'evaluator_distinct' | 'tool';
   /** @deprecated api-types 0.36.0 — the engine emits `agreementPct`; removed in 0.37. */
@@ -3361,6 +3409,15 @@ export interface LaunchRunBody {
    * launch schema rejects the key with a 400.
    */
   revisesPr?: number;
+  /**
+   * Promote-from-chat linkage (crew#619; api-types 0.39.0, additive): the id of the chat this
+   * run was promoted from. When present, the daemon retains that chat's conversation transcript
+   * on disk for the run's lifetime, so the Continue-in-Build prefill is always reproducible
+   * even if the chat is idle-reclaimed before the run finishes. Optional; omit when the launch
+   * is not promoted from a chat. Check `GET /health.capabilities.chatIdOnLaunch` before sending —
+   * an older daemon's strict launch schema rejects the key with a 400.
+   */
+  chatId?: string;
   /**
    * Retry lineage (DES-UX-001 §8.3, CREW-UX-3; api-types 0.8.0): the id of the run this
    * launch retries. Must name an EXISTING run id — an unknown id fails the launch (400 with
@@ -3392,6 +3449,21 @@ export interface LaunchRunBody {
    * `AgentSession.group_label`. Mutually exclusive with `campaignId` (both ⇒ 400).
    */
   groupLabel?: string;
+  /**
+   * The surface that triggered this launch (crew#632; additive). `'studio'` (web UI), `'cli'`
+   * (wicked-crew CLI), or `'api'` (programmatic caller). Persisted in the `run.launched` audit
+   * entry and echoed as `AgentSession.channel`. Absent ⇒ origin unknown. Check
+   * `GET /health.capabilities.seatChipOnCreate` to confirm the daemon accepts the field before
+   * sending — an older daemon's strict schema rejects unknown keys with a 400.
+   */
+  channel?: 'studio' | 'cli' | 'api';
+  /**
+   * An opaque caller-supplied identifier for the user or system that triggered the launch
+   * (crew#632; additive). Persisted in the `run.launched` audit entry and echoed as
+   * `AgentSession.launch_actor`. Absent ⇒ caller omitted it. Subject to the same daemon-version
+   * guard as `channel` above.
+   */
+  actor?: string;
 }
 
 /**
@@ -4043,6 +4115,18 @@ export interface InteractiveDocCreateRequest {
   repo_ref?: string;
   /** SEVERAL subject repositories (at most 8); the union with `repo_ref`, de-duplicated. */
   repo_refs?: string[];
+  /**
+   * Per-doc council roster override (crew#631; crew ≥ 0.7.40 — check `GET /health` capabilities
+   * `seatChipOnCreate` before sending). JSON-serialised `AgenticCli[]`; defaults to the daemon's
+   * full roster when absent. Seat keys not present in `GET /roster` → 400.
+   */
+  clisJson?: string;
+  /** Launch channel (crew#632). Persisted to the run's `run.launched` audit entry and served on
+   *  run DTOs as `channel`. ABSENT when the caller does not know the channel. */
+  channel?: 'studio' | 'cli' | 'api';
+  /** Launch actor (crew#632). Free-form string (≤ 256 chars) identifying the human or service
+   *  that triggered the launch. ABSENT when unknown. */
+  actor?: string;
 }
 
 /**
@@ -4288,10 +4372,32 @@ export interface ChatOpenBody {
   /** File the chat into a project (`crew.chat` membership, attached on open) — and, when no
    *  `repoRefs` are given, scope it to every registered `crew.repo` member of that project. */
   projectId?: string;
+  /**
+   * The scope the caller NAMES (api-types 0.39.0, studio#323 R4). Omitted ⇒ the legacy inference
+   * above (`repoRefs` ⇒ `repos`, else `projectId` ⇒ `project`, else `none`) — unchanged for older
+   * skins. Named, the daemon resolves exactly that kind or refuses with 400:
+   *   - `system`     — the platform itself (daemon, seats, runs, config): NO repository and no code
+   *                    graph. The seats have no live read of the daemon; what they know of it is what
+   *                    the message carries. Takes no `repoRefs`; `projectId` only files the chat.
+   *   - `everything` — EVERY repository registered with the daemon, across all projects, as read
+   *                    roots — never an enumerated list (no 1–32 cap). No single code graph spans
+   *                    them, so none is bound. Takes no `repoRefs`; `projectId` only files the chat.
+   *   - `project`    — requires `projectId`; takes no `repoRefs` (name `repo` to narrow).
+   *   - `repo`       — requires `repoRefs`; `repos` is the same kind in its legacy spelling.
+   *   - `none`       — the legacy unscoped chat; takes neither `projectId` nor `repoRefs`.
+   */
+  scopeKind?: ChatScopeRequestKind;
 }
 
-/** How a chat's scope was chosen (crew#502). */
-export type ChatScopeKind = 'project' | 'repos' | 'none';
+/** The scope a `POST /chats` caller may name (api-types 0.39.0, studio#323 R4). */
+export type ChatScopeRequestKind = 'system' | 'everything' | 'project' | 'repo' | 'repos' | 'none';
+
+/**
+ * How a chat's scope was chosen (crew#502). `system` and `everything` (api-types 0.39.0,
+ * studio#323 R4) come back only for a request that named them (`ChatOpenBody.scopeKind`); a named
+ * `repo` comes back as `repos`, the kind for an explicit repo list.
+ */
+export type ChatScopeKind = 'system' | 'everything' | 'project' | 'repos' | 'none';
 
 /** One repository a chat's seats may read. */
 export interface ChatScopeRepo {
@@ -4310,7 +4416,7 @@ export interface ChatScope {
   kind: ChatScopeKind;
   /** The project the chat is filed into, when any. */
   projectId?: string;
-  /** The repositories in scope (read-only). Empty for `kind: 'none'`. */
+  /** The repositories in scope (read-only). Empty for `kind: 'none'` and `kind: 'system'`. */
   repos: ChatScopeRepo[];
   /** The seats' working directory: the chat's private scratch root under the OS temp dir. */
   cwd: string;
@@ -4356,6 +4462,47 @@ export interface ChatSeatRefusal {
   source?: ChatRefusalSource;
 }
 
+/**
+ * Single-seat degradation disclosure (crew#641/#650): present on `POST /chats` → 201 and on
+ * `POST /chats/:id/messages` → 202 whenever exactly ONE seat is warm — refusals or not, since a
+ * one-seat chat cannot disagree with itself either way. Named here so callers do not have to reason
+ * about the `refused[]` array. The root cause is tracked as wicked-core#563.
+ */
+export interface ChatSingleSeatDegradation {
+  degraded: true;
+  /** The one warm seat key (e.g. `"claude"`). */
+  warmed: string;
+  /**
+   * The seats currently ON RECORD as refused, with each reason and source — EVIDENCE, not the
+   * trigger. It describes the daemon's RECORD (what the open, or the last `POST /chats/:id/seats`,
+   * observed); `warmed` describes the roster NOW, and the two are different moments.
+   *
+   * `[]` with `refusalsKnown: true` therefore means **no refusal is on record** — NOT "no seat was
+   * ever refused": a seat re-seated through `POST /chats/:id/seats` is removed from the record when
+   * it warms, and a seat RELEASED mid-session (it blew its turn budget) was never refused at all,
+   * yet either can leave a chat with one warm seat and an empty record. `[]` with `refusalsKnown:
+   * false` means the record is GONE — see that field.
+   */
+  refused: ChatSeatRefusal[];
+  /**
+   * Whether `refused` is the record this daemon actually holds (crew#650, review follow-up). `true`
+   * on every 201 (the daemon just opened the chat) and on a 202 for a chat it still holds. `false`
+   * on a 202 for a chat this daemon did not open — the engine keeps a warm session across a restart,
+   * the daemon's in-memory scope index does not — where `refused: []` means THE RECORD IS GONE, not
+   * that nothing was refused, and `message` says so instead of asserting either way. Absent on a
+   * daemon predating this field, where `[]` was ambiguous.
+   */
+  refusalsKnown?: boolean;
+  /**
+   * Human-readable summary naming the degradation, its cause, and wicked-core#563. It states only
+   * what the answering route witnessed: the 201 performed the open, so it may say the chat was
+   * opened with a single seat; a 202 knows the roster NOW and the refusal record and says nothing
+   * about how the chat came to look this way — the one warm seat may be the survivor of a two-seat
+   * chat whose other seat was released.
+   */
+  message: string;
+}
+
 /** `POST /chats` → 201. */
 export interface ChatOpenResponse {
   chatId: string;
@@ -4367,6 +4514,33 @@ export interface ChatOpenResponse {
   /** Every seat that was asked for or defaulted and is NOT in `seats` as warm, with its reason
    *  (api-types 0.35.0). Empty when every seat warmed; absent on a daemon predating the field. */
   refused?: ChatSeatRefusal[];
+  /**
+   * crew#641/#650: present whenever exactly ONE seat is warm — the chat cannot disagree with
+   * itself, which is equally true when nothing was refused (a chat opened with one seat on
+   * purpose). ABSENT only when two or more seats are warm. Absent on a daemon predating this
+   * field; a daemon between #641 and #650 emitted it only when `refused` was non-empty.
+   */
+  singleSeat?: ChatSingleSeatDegradation;
+}
+
+/** `POST /chats/:id/messages` → 202. */
+export interface ChatMessageResponse {
+  /** The seats the engine delivered the message to (warm seat keys). */
+  seats: string[];
+  /** The turn id stamped on every `chatDelta` / `chatReply` frame for this message. Absent on a
+   *  daemon predating the turn index (crew ≥ 0.7.35). */
+  turnId?: string;
+  /**
+   * crew#641/#650: re-stated on every turn when the chat has exactly one WARM seat — decided from
+   * the warm roster, never from the seats this turn reached, and never from whether refusals are
+   * still on record (a restarted daemon has none and the chat is still single-seated). ABSENT when
+   * two or more seats are warm. Absent on a daemon predating this field.
+   *
+   * This is a statement about NOW. It never describes how the chat was opened — the single warm seat
+   * may be the survivor of a multi-seat chat whose other seats were refused, re-seated or released —
+   * and only `POST /chats` → 201, which performed the open, says anything about that moment.
+   */
+  singleSeat?: ChatSingleSeatDegradation;
 }
 
 /**
@@ -5151,7 +5325,9 @@ export interface DiagnosticsSkillsFinding {
    *  the configured BASE skill (`SystemSettings.baseSkillRef`) is not in the current generation —
    *  a `warning` under `baseSkillPolicy: 'warn'` (runs proceed without the discipline directive),
    *  an `error` under `'require'` (the engine refuses every launch at intake); cleared by a publish
-   *  that hands it. Also carried as `DiagnosticsSkills.baseSkill.finding`. */
+   *  that hands it. Also carried as `DiagnosticsSkills.baseSkill.finding`; `skills.phase-skill`
+   *  (`warning`, crew#661) = a subsystem's phases declare a skill the published snapshot did not hold
+   *  when it armed, so they run without it — one per `DiagnosticsSkills.phaseSkillGaps` entry. */
   kind:
     | 'skills.fallback'
     | 'skills.blocked'
@@ -5159,7 +5335,8 @@ export interface DiagnosticsSkillsFinding {
     | 'skills.source'
     | 'skills.manifest'
     | 'skills.stale-rules'
-    | 'skills.base-skill';
+    | 'skills.base-skill'
+    | 'skills.phase-skill';
   severity: 'warning' | 'error';
   message: string;
 }
@@ -5193,8 +5370,40 @@ export interface DiagnosticsSkills {
    *  when the setting is off or the seam is `disabled`. A daemon before this field omits the key
    *  (read it as `null`). */
   baseSkill: BaseSkillPosture | null;
+  /** Subsystems whose phases run WITHOUT a skill their workflow declares (crew#661; additive) — one
+   *  entry per subsystem, judged when that seam ARMED (the decision holds until the daemon restarts).
+   *  Each entry also rides `findings` as a `skills.phase-skill` warning. `[]` when every armed seam
+   *  holds its skill; ABSENT on a daemon before this field (read it as unknown, not as `[]`). */
+  phaseSkillGaps?: DiagnosticsPhaseSkillGap[];
+}
+
+/**
+ * One subsystem whose phases declare a skill the published snapshot did not hold when the subsystem
+ * armed (crew#661) — today the interactive seams' `wicked-garden-draft` quality floor. The phases
+ * run DEGRADED (no `skill_ref`, no quality floor) and every run launched on it says so in
+ * `AgentSession.skill_gaps`; the engine would refuse a `skill_ref` its snapshot lacks, so the seam
+ * cannot simply stamp it.
+ */
+export interface DiagnosticsPhaseSkillGap {
+  /** The subsystem (`interactive-draft` / `interactive-edit` / `interactive-chat`). */
+  subsystem: string;
+  /** The workflow id the subsystem launches. */
+  workflow: string;
+  /** The agent phases that declare the skill and run without it. */
+  phases: string[];
+  /** The declared skill (`wicked-garden-draft`). */
+  skill: string;
+  /** The published skills generation judged at arm time, or `null` when none was published. */
+  gen: number | null;
+  /** Epoch ms of the arm-time judgement. */
+  armedAt: number;
+  /** The fix: republish the skills snapshot from a wicked-garden that carries the skill, then restart. */
+  remedy: string;
 }
 
+/** A skill gap a run LAUNCHED with (`AgentSession.skill_gaps[]`, crew#661) — the arm-time gap without its timestamp. */
+export type RunSkillGap = Omit<DiagnosticsPhaseSkillGap, 'armedAt'>;
+
 /**
  * The BASE skill in force for the next launch (crew#554 — the launcher half of wicked-core#468).
  * The engine leads EVERY agent unit's prompt with one role-keyed directive naming this skill and

package/package.json

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