wicked-crew-api-types 0.73.0 → 0.83.0

package/index.d.ts

@@ -237,6 +237,13 @@ export interface HealthCapabilities {
    * as `false`: group such a daemon's runs one session per run.
    */
   runChatId?: boolean;
+  /**
+   * Repo-bound runs get an EVIDENCE ROOT for walkthroughs (WT-W1, api-types 0.74.0): the engine
+   * addon takes `LaunchOptions.evidenceRoot` (wicked-core-ts ≥ 0.7.35), so a walkthrough step on a
+   * run launched now can record and pass. `GET /runs/:id/walkthrough` answers on every daemon that
+   * has the field. ABSENT or `false` — a walkthrough step on this daemon's runs fails closed.
+   */
+  walkthroughRoots?: boolean;
 }
 
 /** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
@@ -350,6 +357,24 @@ export interface AgentSession {
    * plus `denial_reason` (crew#318's message), both already on the list wire.
    */
   delivery?: 'delivered' | 'pushed' | 'stranded' | 'vacuous' | 'none';
+  /**
+   * (crew#755; api-types 0.76.0) `'text_only'` on a COMPLETED free-text run (launched with neither a
+   * workflow nor a plan) that had no repo and no write root of its own: whatever it did, it did in
+   * text — nothing was changed, checked or delivered. Show it as such, never as plain completed
+   * work. ABSENT on every other run (and on a daemon before the field).
+   */
+  outcome?: 'text_only';
+  /**
+   * (crew#762; api-types 0.79.0) Was delivery ASKED FOR on this run? A durable fact, so a skin can
+   * tell a run kept locally as asked from one whose delivery was attempted and did not land, also
+   * after a reload or a daemon restart. `stranded` with no deliver unit covers both.
+   *   - `true`: the launch resolved `deliver: 'pr'`, OR a post-hoc `POST /runs/:id/deliver` was
+   *     attempted (recorded before the script runs, whatever came of it), OR a delivery is on record.
+   *   - `false`: the launch resolved `deliver: 'none'` and nothing was attempted since.
+   *   - ABSENT: this daemon holds no launch record for the run and no attempt (a pre-field run, or a
+   *     daemon before the field). Never fabricated.
+   */
+  deliver_requested?: boolean;
   /**
    * The delivered PR's URL (crew#393; api-types 0.18.0) — present exactly when
    * `delivery === 'delivered'`; absent otherwise (absence is the one spelling, never `null`).
@@ -521,6 +546,14 @@ export interface AgentSession {
    * workflow ids.
    */
   run_identity?: RunIdentity;
+  /**
+   * The run's EVIDENCE ROOT (WT-W1, DES-walkthrough-proof §4.2; api-types 0.74.0), minted by the
+   * daemon for every repo-bound run on an engine that takes it: `<root>/author/<plan step>/` is
+   * the walkthrough author's write dir, `<root>/<review step>/` the proof root only the jailed
+   * `walkthrough_review` Tool writes. Read the walkthrough through `GET /runs/:id/walkthrough`, not
+   * from this path. ABSENT on a repo-less run, on an engine before the field, and on older runs.
+   */
+  evidence_root?: string;
 }
 
 /**
@@ -1142,6 +1175,12 @@ export interface CoreEvent {
   elicitationId?: string;
   /** `elicitationCreated`: an ordered set of valid responses; `null` / absent = free-text. */
   options?: string[] | null;
+  /**
+   * `elicitationCreated` (C3; wicked-core-ts >= 0.7.35, api-types 0.83.0): the index into `options`
+   * of the option the PRODUCER of the options recommends (the field's JSON Schema `default`).
+   * ABSENT ⇒ nothing is preselected.
+   */
+  recommended?: number;
   /** PTY terminal frames (`terminalOpened`/`terminalOutput`/`terminalExited`): the terminal id. */
   id?: string;
   /**
@@ -2557,7 +2596,13 @@ export interface ConformanceRule {
   statement: string;
   severity: 'info' | 'warn' | 'error' | 'critical';
   confidence: number;
-  targets: { language?: string; layer?: string; framework?: string };
+  /**
+   * Facets. `language` / `layer` / `framework` are wildcards (absent = every value). `project`
+   * (api-types 0.77.0, DC-S3; engine >= wicked-core-ts 0.7.35) is ASYMMETRIC: a rule with no project
+   * applies everywhere; a rule with one is recalled only for that project. A landed policy proposal
+   * keeps its `project` facet here.
+   */
+  targets: { language?: string; layer?: string; framework?: string; project?: string };
   symbol_ref?: string;
   compliance?: { framework: string; control_id: string };
   /** Where the rule came from. Doc-ingested rules keep `path@sha#id` in `ref`; UI/chat-authored
@@ -2601,6 +2646,8 @@ export interface ConformanceRule {
    * pre-bump binding), so a `since`/`until` filter cannot assert an undated rule in range.
    */
   created_at?: number;
+  /** (api-types 0.77.0, DC-S1/DC-S3) The rule ids this rule replaces. Absent when it replaces none. */
+  supersedes?: string[];
 }
 
 /** Facet query for `GET /governance/rules/preview`. All fields are optional. */
@@ -3946,6 +3993,12 @@ export interface LinkedIssue {
 export interface LaunchRunResponse {
   runId: string;
   linkedIssues?: LinkedIssue[];
+  /**
+   * (crew#755; api-types 0.76.0) PRESENT when the launch named neither a `workflow` nor a `plan`:
+   * the run uses the engine's free-text planner (one step, the brief verbatim; no phases, checks or
+   * delivery), and `notice` says so in words a composer can show. ABSENT on every other launch.
+   */
+  freeText?: { notice: string };
 }
 
 /**
@@ -4465,6 +4518,13 @@ export interface ElicitationInfo {
   message: string;
   /** Ordered set of valid responses; `null` means free-text. */
   options: string[] | null;
+  /**
+   * (C3, api-types 0.83.0) The index into `options` the producer of the options recommends —
+   * relayed from the engine's `elicitationCreated.recommended`, kept only when it names one of
+   * `options`. ABSENT ⇒ nothing is preselected (and a skin's Enter stays inert until a choice has
+   * focus, DESIGN-interaction rule 6).
+   */
+  recommended?: number;
   receivedAt: string;
 }
 
@@ -6043,7 +6103,12 @@ export interface DiagnosticsSkillsFinding {
    *  an `error` under `'require'` (the engine refuses every launch at intake); cleared by a publish
    *  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. */
+   *  when it armed, so they run without it — one per `DiagnosticsSkills.phaseSkillGaps` entry;
+   *  `skills.garden` (`error`, api-types 0.78.0, crew#753) = the installed wicked-garden is older
+   *  than the daemon requires (`GardenRequiredBody.required`), so it is not used: found at seed,
+   *  the runtime is `config-error` and the engine is handed a refusal path. Rides
+   *  `/health.warnings` too; launches and onboarding answer 422
+   *  `garden_required` until a newer garden is installed and published. */
   kind:
     | 'skills.fallback'
     | 'skills.blocked'
@@ -6052,11 +6117,25 @@ export interface DiagnosticsSkillsFinding {
     | 'skills.manifest'
     | 'skills.stale-rules'
     | 'skills.base-skill'
-    | 'skills.phase-skill';
+    | 'skills.phase-skill'
+    | 'skills.garden';
   severity: 'warning' | 'error';
   message: string;
 }
 
+/**
+ * The 422 `POST /runs`, `POST /repos` and `POST /repos/:id/onboard` answer while the installed
+ * wicked-garden is older than the daemon requires (api-types 0.78.0, crew#753). `error` names the
+ * version found, where, the version required and the install command. Nothing was launched or
+ * registered. A daemon with NO garden answers the base skill's 422 `base_skill_refused` instead.
+ */
+export interface GardenRequiredBody {
+  code: 'garden_required';
+  error: string;
+  /** The minimum wicked-garden version, e.g. `"12.40.0"`. */
+  required: string;
+}
+
 /**
  * `GET /diagnostics` → `skills`: whether the engine is being handed a verified snapshot, and if not,
  * why — the one read-only answer to "why do launches refuse the skills snapshot". `disabled` is a
@@ -6307,6 +6386,12 @@ export interface PolicyLandingResult {
   ruleId?: string;
   /** The steering type derived from the proposal's `kind_type` (`policy:<type>`). Present on `landed`. */
   steering_type?: SteeringType;
+  /**
+   * (api-types 0.77.0, DC-S3) The project the landed rule is scoped to — the proposal's `project`
+   * facet, kept as `targets.project` and confirmed by reading the rule back. Absent on a landing
+   * with no project (the rule applies everywhere).
+   */
+  project?: string;
   /** Present iff `outcome:"failed"` — the loud reason the rule did not land. */
   error?: string;
 }
@@ -6533,6 +6618,185 @@ export interface DemoExportResponse {
   bytes: number;
 }
 
+// ── Walkthroughs: the recording view (WT-W1, DES-walkthrough-proof §4.10; api-types 0.74.0) ──────
+
+/**
+ * Where a walkthrough stands (`WalkthroughView.state`), read from the run's walkthrough pair — the
+ * `walkthrough_plan` unit (the author, an evaluator) and the `walkthrough_review` unit (the jailed
+ * engine-run recorder) — and the recorder's files in the proof root.
+ *
+ *   - `authoring`     the author has not finished the storyline (also: the run has no walkthrough
+ *                     step yet — `stepId` is then `null` and `cause` says so);
+ *   - `linting`       the author's storyline was refused by its pinned lint (the unit was denied;
+ *                     its escalation gate is open, `cause` is the lint's reason);
+ *   - `starting_app`, `recording`, `judging`
+ *                     the recorder is queued or running: its `progress.json` names the phase;
+ *   - `passed`, `failed`, `inconclusive`
+ *                     the recorder finished: `result.json`'s `overall` (PASS / FAIL / INCONCLUSIVE).
+ *                     A finished recorder with no readable `result.json` reads `inconclusive` with
+ *                     `cause: 'no_result'`.
+ */
+export type WalkthroughState =
+  | 'authoring'
+  | 'linting'
+  | 'starting_app'
+  | 'recording'
+  | 'judging'
+  | 'passed'
+  | 'failed'
+  | 'inconclusive';
+
+/** One chapter's verdict, as the recorder's judge wrote it (§4.5). */
+export type WalkthroughVerdict = 'PASS' | 'FAIL' | 'INCONCLUSIVE';
+
+/** One check of a chapter: what was captured on screen or underneath, and whether its verifier passed. */
+export interface WalkthroughCheck {
+  id: string;
+  /** `on_screen`, `saved_state`, `events`, `side_effects`, `output`, `must_not_happen`, `cross_check`. */
+  kind: string;
+  /** The plain sentence the check proves. */
+  sentence: string;
+  /** `null` when the check never ran (its `ctx.check` was not reached, or the take was refused). */
+  passed: boolean | null;
+  /** Seconds into the chapter when the check was captured; `null` when it never ran. */
+  atSec: number | null;
+  /** Proof-root-relative paths (for `GET /runs/:id/walkthrough/file`). */
+  evidence: string[];
+  vaultEntry: string | null;
+  detail: string | null;
+}
+
+/** A capped leg of a chapter (§4.5 "the honest cap"): e.g. the provider leg ran against a sink. */
+export interface WalkthroughLeg {
+  leg: string;
+  claim_level: string;
+  reason: string;
+}
+
+/** One chapter of a walkthrough: the demo chapter plus its verdict and checks. */
+export interface WalkthroughChapter extends DemoChapter {
+  /** 1-based position and the chapter count, for "chapter 2 of 5". */
+  index: number;
+  total: number;
+  /** `null` until the judge has written it. */
+  verdict: WalkthroughVerdict | null;
+  /** How many takes the recorder made of this chapter (failed takes are kept, never stitched). */
+  takes: number;
+  /** Seconds into the chapter of the first failing check; `null` unless it failed. */
+  failedAtSec: number | null;
+  /** The failing frame (proof-root-relative), when the recorder kept one. */
+  failedFrame: string | null;
+  /** The plan step ids this chapter proves. */
+  proves: string[];
+  legs: WalkthroughLeg[];
+  checks: WalkthroughCheck[];
+}
+
+/**
+ * Per plan step, whether a sealed walkthrough proves it (§4.9). Computed at every read, never stored.
+ * `checked`: every proving chapter of the newest sealed walkthrough passed; `failed`: one failed;
+ * `claimed`: the step passed its own gate and no sealed chapter proves it; `owned_by_you`: the
+ * accepted plan's override removed the walkthrough pair.
+ */
+export type WalkthroughCheckState = 'checked' | 'failed' | 'claimed' | 'owned_by_you';
+
+export interface WalkthroughStepState {
+  stepId: string;
+  checkState: WalkthroughCheckState;
+  provedBy: Array<{ chapter: string; atSec: number | null }>;
+}
+
+/**
+ * `GET /runs/:id/walkthrough?step=` → 200 for every known run (404 for an unknown run, or a `step`
+ * that names no walkthrough step of it). `step` is the `walkthrough_review` step id (or its author's
+ * `walkthrough_plan` step id); omitted, the NEWEST pair. Studio polls it, as Demo mode polls `DemoView`.
+ */
+export interface WalkthroughView {
+  runId: string;
+  /** The `walkthrough_review` step id; `null` when the run has no walkthrough step. */
+  stepId: string | null;
+  /** The `walkthrough_plan` step that authored it; `null` when there is none. */
+  planStepId: string | null;
+  state: WalkthroughState;
+  /** Why the state is what it is, when there is something to say (`no_walkthrough`, `no_evidence_root`,
+   *  the recorder's own causes such as `unjailed_host`, `fixture_unavailable`, `storyline_refused`). */
+  cause: string | null;
+  /** Evaluator ≠ creator: the seat that wrote the checks, and the seats that built what they check. */
+  seat: { evaluator: string | null; builders: string[] };
+  /** The tree id the recorder recorded (`git archive` of it is what ran). */
+  tree: string | null;
+  /** Always `false`: a later creator step re-inserts the pair after it (§4.8). Kept so an old plan shape reads honestly. */
+  stale: false;
+  /** The take's seal was found in the engine store and every re-check against the files on disk held (WT-W2). */
+  sealed: boolean;
+  /** 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). */
+  steps: WalkthroughStepState[];
+}
+
+/**
+ * `GET /runs/:id/acceptance` → `walkthrough` (WT-W2, DES-walkthrough-proof §4.9; api-types 0.75.0):
+ * the walkthrough half of the gate. One row per `walkthrough_review` step the run's requirement names,
+ * each re-verified at this read — the seal (the last `WALKTHROUGH-SEAL` line of the recorder's
+ * 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.
+ */
+export interface RunAcceptanceWalkthrough {
+  roots: Array<{ stepId: string; sealed: boolean; satisfied: boolean; reason: string }>;
+  /** Every row's seal held. */
+  sealed: boolean;
+  /** Per creator step, from the NEWEST walkthrough of the run. */
+  steps: WalkthroughStepState[];
+}
+
+/**
+ * `GET /runs/:id/acceptance` → `summary` (WT-W3, DES-walkthrough-proof §4.8/§7; api-types 0.82.0): the
+ * deliver card's ONE acceptance line, computed at the same read as the gate. `line` is plain words
+ * ("Checked by a walkthrough: 3 of 3 steps at a1b2c3d."); it cites counts and the tree, never a path.
+ */
+export interface RunAcceptanceSummary {
+  /** The run had something to prove (`gate.required`). */
+  required: boolean;
+  /** 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. */
+  walkthrough: {
+    checked: number;
+    failed: number;
+    ownedByYou: number;
+    /** Creator steps with a check state. */
+    steps: number;
+    /** Every walkthrough seal held. */
+    sealed: boolean;
+    /** The tree the newest seal binds; `null` with no seal. */
+    tree: string | null;
+  } | null;
+}
+
+/**
+ * `PUT /runs/:id/walkthrough/storyline?step=` body (WT-W3, §4.8 "Edit the check"): the whole storyline
+ * module text. Accepted only while that walkthrough's escalation gate is open (409
+ * `no_open_escalation` otherwise), only from a human actor (403), at most 256 KB (413).
+ */
+export interface PutStorylineBody {
+  storyline: string;
+}
+
+/** `PUT /runs/:id/walkthrough/storyline` → 200: crew wrote `author/<planStepId>/storyline.mjs`, marked `edited_by: human`. */
+export interface PutStorylineResponse {
+  runId: string;
+  planStepId: string;
+  sha256: string;
+  edited_by: 'human';
+  /** ISO-8601. */
+  at: string;
+}
+
 /** `POST /proposals/:id/reject` → 200. */
 export interface RejectProposalResponse {
   ok: true;
@@ -7310,6 +7574,12 @@ export interface WatchEntry {
   version: number;
   /** See {@link WatchEntrySource}. A `bus` type is a 4-segment `wicked.<domain>.<noun>.<verb>` type. */
   on: { source: WatchEntrySource; type: string };
+  /**
+   * (api-types 0.81.0, TR-W5b) The key points the check JOINS to its trigger — "the same unit's
+   * `repoChecksEvaluated`", "the cursor unit's latest `unitOutputCaptured`". They reach the check
+   * unfiltered so it can fold them; only `on` (with `filter`) triggers a row. Absent = none.
+   */
+  join?: Array<{ source: Exclude<WatchEntrySource, 'internal'>; type: string }>;
   /** JSON-path equality, AND of keys; an array means "any of". */
   filter: Record<string, unknown>;
   check: string;
@@ -8334,3 +8604,132 @@ export interface McpUsageResponse {
   /** Lines of `calls.ndjson` that did not parse as a call record. */
   skipped: number;
 }
+
+// ── Decision capture (DES-decision-capture §4.2.1 / §4.6; DC-S4a, api-types 0.80.0) ──────────────
+
+/** The laya codebook's decision types. `none` is crew's label for "no decision". */
+export type DecisionType = 'rule' | 'correction' | 'scope' | 'exception' | 'choice' | 'confirmation' | 'none';
+
+/** Where the operator's words entered crew. S4a records the three structured hosts. */
+export type DecisionHost = 'studio-chat' | 'gate' | 'elicitation' | 'inject' | 'capture' | 'claude-code';
+
+/** The deterministic templates (`derive.ts`). Only `T1-always` and `T2-never` can auto-remember. */
+export type DecisionTemplateId =
+  | 'T1-always'
+  | 'T2-never'
+  | 'T3-before'
+  | 'T4-prefer'
+  | 'T5-must'
+  | 'T6-only'
+  | 'in-your-words';
+
+/** How the derivation routed a decision (§4.4): the first that applies wins. */
+export type DecisionRoute = 'ledger' | 'offer' | 'auto' | 'restated' | 'maybe-restated' | 'conflict';
+
+/** The latest outcome of a decision. `recorded` = no outcome yet (ledger-only, or still landing). */
+export type DecisionState =
+  | 'recorded'
+  | 'offered'
+  | 'remembered'
+  | 'undone'
+  | 'dismissed'
+  | 'restated'
+  | 'widened'
+  | 'landing_failed';
+
+/** Why an offered decision was dismissed (a label for the laya v3 flywheel). */
+export type DecisionDismissReason = 'not-a-rule' | 'one-off' | 'wrong-type' | 'wrong-scope' | 'not-the-same' | 'undone';
+
+/**
+ * One decision as studio renders it (`GET /decisions`, operator+). ORIGIN (`origin.words`) comes
+ * ONLY from crew's ledger: a proposal payload carries just the decision id, so a forged payload
+ * has no ORIGIN. Words are never on the bus.
+ */
+export interface DecisionView {
+  id: string;
+  /** Epoch ms the words were recorded. */
+  at: number;
+  project_id: string | null;
+  host: DecisionHost;
+  origin: {
+    actor: { id: string; kind: 'human'; trust: TrustLevel };
+    auth_mode: 'off' | 'required';
+    run_id?: string;
+    ord?: number;
+    gate_id?: string;
+    elicitation_id?: string;
+    chat_id?: string;
+    turn_id?: string;
+    /** The verbatim words (masked where a secret was found; then `redacted: true`). */
+    words: string;
+    /** A bare gate approve/reject or a picked elicitation option, when there were no words. */
+    choice?: string;
+    words_source: 'typed' | 'operator-files' | 'cli-transcript';
+    redacted: boolean;
+  };
+  /** The derived rule: the statement crew would remember, never the model's paraphrase. */
+  derived: {
+    statement: string | null;
+    polarity: 'do' | 'dont' | null;
+    key: string | null;
+    scope: 'project' | 'everywhere';
+    steering_type: SteeringType;
+    template: DecisionTemplateId | null;
+    exclusions: string[];
+  };
+  route: DecisionRoute;
+  state: DecisionState;
+  /** How it was remembered (present once `remembered`). */
+  how?: 'auto' | 'chip' | 'needs-you';
+  proposal_id?: string;
+  rule_id?: string;
+  /** The in-force rule this restates (`restated`) or contradicts (`conflict`). */
+  restates_rule_id?: string;
+  conflicts_rule_id?: string;
+  /** Edits the operator made at Remember; ORIGIN keeps the original words. */
+  edits?: { statement?: string; scope?: 'project' | 'everywhere'; steering_type?: SteeringType };
+  /** The loud reason a landing failed (`landing_failed`). */
+  error?: string;
+  /** B8: the same rule decided in ≥ 2 projects — "Make it apply everywhere". */
+  widen?: { projects: string[] };
+}
+
+/** `GET /decisions?project=&chat=&run=&state=&since=` (operator+). Newest first. */
+export interface ListDecisionsResponse {
+  decisions: DecisionView[];
+  /** `off` | `ledger` | `on` — the `WICKED_DECISIONS` switch this daemon runs under. */
+  mode: 'off' | 'ledger' | 'on';
+}
+
+/** `POST /decisions/:id/remember` body. An edited `statement` is recorded in `edits`. */
+export interface RememberDecisionBody {
+  scope?: 'project' | 'everywhere';
+  steering_type?: SteeringType;
+  statement?: string;
+}
+
+/** `POST /decisions/:id/remember` → the landed rule. */
+export interface RememberDecisionResponse {
+  rule_id: string;
+  proposal_id: string;
+  project?: string;
+}
+
+/** `POST /decisions/:id/dismiss` body. */
+export interface DismissDecisionBody {
+  reason: DecisionDismissReason;
+}
+
+/** `POST /decisions/:id/same` body — resolves a `maybe-restated` decision. */
+export interface SameDecisionBody {
+  same: boolean;
+}
+
+/** `/ws` frame: a decision's state changed (no words). */
+export interface DecisionChangedFrame {
+  type: 'decisionChanged';
+  id: string;
+  state: DecisionState;
+  rule_id?: string;
+  project_id: string | null;
+}

package/package.json

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