wicked-crew-api-types 0.77.0 → 0.86.0

package/index.d.ts

@@ -364,6 +364,17 @@ export interface AgentSession {
    * 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`).
@@ -1164,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;
   /**
@@ -4501,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;
 }
 
@@ -5209,7 +5233,8 @@ export type ChatSeatRefusedFrame = {
 // verdicts; the seat's TEXT is never edited — a skin MARKS it from these items.
 
 /** What class of thing a citation is. */
-export type ChatCitationKind = 'path' | 'line' | 'symbol' | 'sha';
+/** `rule` (api-types 0.85.0, DC-S7): a `[rule:<id>]` the reply wrote — "cited by the step — unchecked", never a followed count. */
+export type ChatCitationKind = 'path' | 'line' | 'symbol' | 'sha' | 'rule';
 
 /**
  * The verdict on one citation.
@@ -5315,7 +5340,21 @@ export type ChatTranscriptRecord =
       corrected: number;
       unchecked: number;
       items: ChatCitationItem[];
-    };
+    }
+  /**
+   * The decisions recorded from the operator's message of `turnId` (api-types 0.84.0, DC-S4b) — a
+   * SEPARATE record, like `citations`, because derivation runs after the seats' replies are stored. A
+   * reader folds it onto the turn's `user` record; a skin that does not know this kind ignores it.
+   * The live frame is {@link ChatDecisionsFrame}. The seats' `wicked-decisions` blocks themselves
+   * never reach the transcript (they are cut from the reply before it is persisted or broadcast).
+   */
+  | { at: number; turnId: string; kind: 'decisions'; items: DecisionView[] }
+  /**
+   * A crew-authored preface the seats received with the operator's message of `turnId` (api-types
+   * 0.85.0, DC-S7): the rules remembered since they last heard from crew. Disclosed here so the
+   * operator sees exactly what crew added; the `user` record keeps the operator's own words.
+   */
+  | { at: number; turnId: string; kind: 'system'; text: string };
 
 /** `GET /chats/:id` → 200. */
 export interface ChatDetailResponse {
@@ -5935,6 +5974,8 @@ export interface DiagnosticsResponse {
    *  `DiagnosticsStateHome`. `null` on a daemon booted without the watch (some tests); ABSENT on a
    *  daemon before this field. */
   stateHome?: DiagnosticsStateHome | null;
+  /** The studio chat recorder's per-CLI format compliance (api-types 0.84.0, DC-S4b); `null` without the chat host. */
+  decisions?: DiagnosticsDecisions | null;
 }
 
 // ── Diagnostics — governance store + dead letters (api-types 0.31.0, crew#495 / F-022) ─────────
@@ -6079,7 +6120,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'
@@ -6088,11 +6134,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
@@ -6710,6 +6770,50 @@ export interface RunAcceptanceWalkthrough {
   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;
@@ -7487,6 +7591,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;
@@ -8511,3 +8621,328 @@ 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;
+}
+
+/**
+ * `/ws` frame (api-types 0.84.0, DC-S4b): the decisions recorded from ONE chat turn's operator
+ * message, once every seat of the turn has answered (or the turn went stale). Mirrors
+ * {@link ChatCitationsFrame}; the same items land in the transcript as a `decisions` record.
+ */
+export interface ChatDecisionsFrame {
+  type: 'chatDecisions';
+  chat: string;
+  turn_id: string;
+  items: DecisionView[];
+  project_id?: string;
+}
+
+/**
+ * `GET /diagnostics.decisions` (api-types 0.84.0, DC-S4b): the studio chat recorder's format
+ * compliance per seat CLI — how often a seat ended its reply with a well-formed `wicked-decisions`
+ * block (§4.3.3 measures the rate per CLI). `null` on a daemon without the chat host.
+ */
+export interface DiagnosticsDecisions {
+  /** The `WICKED_DECISIONS` switch this daemon runs under. */
+  mode: 'off' | 'ledger' | 'on';
+  /** Per `cliKey`: replies seen, well-formed blocks, malformed blocks. */
+  recorder: Record<string, { replies: number; blocks: number; malformed: number }>;
+  /** Turns whose recorder seat posted no usable block. The words were still recorded, unlabelled. */
+  unclassified_turns: number;
+  /** Turns that produced at least one decision record. */
+  recorded_turns: number;
+}
+
+// ── Considered · set aside · cited (unchecked) (DES-decision-capture §4.7; DC-S7, api-types 0.85.0) ──
+
+export interface ConsiderationRule {
+  id: string;
+  statement: string;
+  severity: 'info' | 'warn' | 'error' | 'critical';
+  steering_type?: SteeringType;
+  /** Present on a project-scoped rule. */
+  project?: string;
+}
+
+export interface ConsiderationSetAside {
+  id: string;
+  statement: string;
+  /** The engine's reasons, plus crew's `not_confirmed`: a decision offered for this project, not yet remembered. */
+  reason: 'out_of_scope' | 'replaced' | 'retired' | 'not_confirmed';
+}
+
+/**
+ * A `[rule:<id>]` the reply or step wrote. `unchecked` = the id is in force and the step cited it —
+ * whether it FOLLOWED it is not checked (DES-rule-check will say); `unverified` = not an in-force
+ * rule here (invented, or another project's). Never summed into a "followed" count.
+ */
+export interface ConsiderationCitation {
+  id: string;
+  /** The seat (`cliKey`) or the unit id that wrote it. */
+  by: string;
+  status: 'unchecked' | 'unverified';
+  label: string;
+}
+
+/**
+ * `GET /chats/:id/turns/:turnId/considered` and `GET /runs/:id/units/:unitKey/considered?attempt=`
+ * (operator+): what the seats were given to consider, what was set aside, and what they cited.
+ */
+export interface Consideration {
+  subject: { kind: 'chat'; chat_id: string; turn_id: string } | { kind: 'unit'; run_id: string; ord: number; attempt: number };
+  /** `considered:<chat>:<turn>` or `considered:<run>:<ord>:<attempt>` — the bus fact's idempotency key. */
+  key: string;
+  project_id: string | null;
+  /** Severity-ordered (critical → info). */
+  considered: ConsiderationRule[];
+  set_aside: ConsiderationSetAside[];
+  cited: ConsiderationCitation[];
+  /** `considerRules` (the engine's project-aware read), `global-only` (an engine without it), or `unavailable`. */
+  source: 'considerRules' | 'global-only' | 'unavailable';
+}
+
+// ── Artifact editors (DES-artifact-editor-plugins §5.2, §6, §8.2; EP-C1, api-types 0.86.0) ───────
+
+/** What a plugin can ask for (§6.1). There is no permission for network calls, agents or gates. */
+export type EditorPermission =
+  | 'artifact.read'
+  | 'artifact.write'
+  | 'selection.chip'
+  | 'composer.draft'
+  | 'checks.read'
+  | 'checks.contribute'
+  | 'sources.read'
+  | 'media.read'
+  | 'artifact.export'
+  | 'ui.fullscreen'
+  | 'network.media';
+
+/**
+ * One registered editor, as Settings → Editors renders it. No path is on the wire: the bundle is
+ * fetched at `entry_url` (`GET /editors/:id/:version/entry`, the §8.2 headers, re-hashed per serve).
+ * First-party editors ship inside studio's bundle (`<studio dist>/editors/<id>/editor.json` +
+ * `index.html`, ids `wicked-*`) and are discovered at boot; third-party editors arrive as garden
+ * packs and cannot be installed before the install-time conformance run (EP-C8).
+ */
+export interface EditorView {
+  id: string;
+  title: string;
+  version: string;
+  /** wicked.editor protocol versions it speaks. */
+  protocol: number[];
+  /** Artifact kinds it can open. */
+  kinds: string[];
+  sizes: Array<'inline' | 'pane' | 'full'>;
+  panels?: Array<'checks'>;
+  /** Each with the reason shown at install. The GRANTED set is `GET /editors/:id/grants`. */
+  permissions: Array<{ id: EditorPermission; why: string }>;
+  /** The full sha256 of the entry file, pinned when the registry read it. */
+  sha256: string;
+  bytes: number;
+  first_party: boolean;
+  enabled: boolean;
+  source: 'studio-bundle';
+  entry_url: string;
+}
+
+/** `GET /editors` (operator+). */
+export interface ListEditorsResponse {
+  editors: EditorView[];
+  /** Why `POST /editors` answers 501 today: third-party installs wait on EP-C8. */
+  installs: 'refused_until_conformance';
+}
+
+/** `POST /editors` body (human-only): a pack directory holding `wicked-pack.json`. */
+export interface InstallEditorBody {
+  packRoot: string;
+}
+
+/** One finding of garden's `pack check --json`. */
+export interface PackCheckFinding {
+  level: 'error' | 'warn';
+  code: string;
+  message: string;
+  path?: string;
+}
+
+/** The verdict of garden's `pack check --json` (the fail-closed gate every install runs first). */
+export interface PackCheckResult {
+  ok: boolean;
+  errors: PackCheckFinding[];
+  warnings: PackCheckFinding[];
+}
+
+/**
+ * `POST /editors` → 501: the pack passed garden's gate, and this is what the install WOULD ask the
+ * operator to approve (§3.2 "Add these") once third-party installs open (EP-C8). Nothing was written.
+ */
+export interface InstallEditorRefusal {
+  code: 'third_party_editors_not_available';
+  error: string;
+  check: PackCheckResult;
+  pack: {
+    name: string;
+    vendor: string;
+    version: string;
+    editors: Array<{ id: string; title: string; version: string; kinds: string[]; permissions: Array<{ id: string; why: string }> }>;
+    blocks: Array<{ id: string; label: string; produces_kind: string; skills: string[] }>;
+    /** The pack's skill directories, approved together with its editors and blocks. */
+    skills: string[];
+  };
+}
+
+/** `POST /editors/:id/enabled` body (human-only). */
+export interface SetEditorEnabledBody {
+  enabled: boolean;
+}
+
+/** One decided permission (the engine's `evaluate_editor_grants`, EP-K1). */
+export interface EditorGrant {
+  permission: EditorPermission | string;
+  decision: 'allow' | 'ask' | 'deny';
+  /** The steering rules that decided it. */
+  ruleIds: string[];
+  /** The ledger entry an operator's "allow" adds to `EDITOR-GRANTS.excludes` (`editor:<id>@<version>#<sha256>/<permission>`). */
+  token: string;
+}
+
+/**
+ * `GET /editors/:id/grants?project=` (operator+): the engine's decided set for this editor's version
+ * and hash (a changed hash is a new token and asks again), deny dominating. The host fetches it
+ * before `host.hello` and on every settings/rule change, and enforces it on every request.
+ */
+export interface EditorGrantsResponse {
+  editorId: string;
+  version: string;
+  sha256: string;
+  project: string | null;
+  firstParty: boolean;
+  grants: EditorGrant[];
+}

package/package.json

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