wicked-crew-api-types 0.122.0 → 0.127.0

package/README.md

@@ -14,8 +14,8 @@ consumers keep the workspace reference.
 
 ## Rules
 
-- **Wire shapes only.** Engine-internal types (`LaunchRunInput`, `RepoOnboardRef`, runtime
-  constants) stay in the daemon.
+- **Wire shapes only.** Engine-internal types (`LaunchRunInput`) and runtime
+  constants stay in the daemon.
 - **Zero runtime.** This is a `.d.ts`-only package: no JavaScript, nothing to build. Consumers
   declare it as a devDependency (the published `wicked-crew` tarball never depends on it at
   runtime). Import it with `import type` only — the `exports` map offers just a `types`

package/index.d.ts

@@ -10,8 +10,8 @@
  * carry, which could drift from the daemon silently (task #84).
  *
  * Rules of this package:
- * - WIRE SHAPES ONLY. Engine-internal types (`LaunchRunInput`,
- *   `RepoOnboardRef`, runtime constants) stay in `packages/crew/src/core/types.ts`.
+ * - WIRE SHAPES ONLY. Engine-internal types (`LaunchRunInput`) and runtime
+ *   constants stay in `packages/crew/src/core/types.ts`.
  * - ZERO RUNTIME. This is a `.d.ts`-only package with no JavaScript; import it
  *   with `import type` exclusively. The `exports` map deliberately offers only
  *   a `types` condition, so a value import fails loudly at resolution time.
@@ -801,6 +801,20 @@ export interface WorkUnit {
   operator_rulings?: OperatorRuling[];
   /** (crew#894, wicked-core#810) The phase's worker pool (one creator plus monitors). ABSENT = 1. */
   pool?: number;
+  /**
+   * (api-types 0.124.0; crew#1058) Daemon-resolved: the seats a reassign of this unit is REFUSED
+   * for — the authors of the work it checks (engine `authored_by` plus every earlier Build/Recon
+   * agent unit's seat), served on a Review/Test agent unit of a run whose contract enforces a
+   * distinct evaluator. `POST /runs/:id/reassign` answers 409 for such a target BEFORE it approves
+   * the gate, so a skin offers none of them. ABSENT when no seat is refused, and on an older daemon.
+   */
+  reassign_refused?: string[];
+  /**
+   * (api-types 0.124.0) Engine field (`WorkUnit.authored_by`): every seat this unit was ever
+   * dispatched on as its author, current seat aside (reassigned and failed-over creators). ABSENT
+   * when empty, and on an older engine.
+   */
+  authored_by?: string[];
   /** (crew#894) How that pool was seated, once distributed (see {@link UnitPoolSeating}). ABSENT
    *  for a pool of 1 and before distribution. */
   pool_seating?: UnitPoolSeating;
@@ -1155,6 +1169,22 @@ export interface RosterSeat {
    * `GET /roster/record`. ABSENT when there is no active bench.
    */
   recent_bench?: SeatRecentBench;
+  /**
+   * (unreleased, wicked-core#976) The engine's HOST-FLOOR bench reason for this seat: on the interim
+   * host floor (`WICKED_SEAT_FLOOR` other than `container`) the engine refuses governed work on any
+   * seat that keeps no per-call check there (anything but claude and a bounded codex), in every run.
+   * The seat still reviews, triages and votes (those calls are ungoverned), so `council_eligible`
+   * does not read it; `chat_admission` and `work_admission` (`host_floor_bench`) do. ABSENT when the
+   * engine does not bench the seat, or its addon cannot say.
+   */
+  host_floor_bench?: string;
+  /**
+   * (unreleased, wicked-core#976) Present on the host floor when crew could not read the engine's
+   * host-floor bench and holds no earlier reading: the operator's sentence. Admission then fails
+   * closed — `chat_admission` refuses the seat (source `engine`, unless signed out), and
+   * `work_admission` / `qe_reviewer` are ABSENT (not known).
+   */
+  host_floor_unknown?: string;
   /**
    * (api-types 0.115.0, A5) Whether a job of each scope kind would give the seat work, including
    * the engine's launcher benches (core#769's codex worktree bench, via `Core.worktreeBenched`).
@@ -1221,7 +1251,8 @@ export interface SeatRecentBench {
   reason: string;
 }
 
-/** Why a seat would get no work, one code per refusal (api-types 0.115.0). */
+/** Why a seat would get no work, one code per refusal (api-types 0.115.0; `host_floor_bench`
+ *  unreleased, wicked-core#976: the engine refuses the seat's governed work on the host floor). */
 export type SeatWorkReasonCode =
   | 'signed_out'
   | 'not_enabled'
@@ -1229,11 +1260,12 @@ export type SeatWorkReasonCode =
   | 'recent_bench'
   | 'login_pending'
   | 'worktree_bench'
+  | 'host_floor_bench'
   | 'scope_ungoverned';
 
 /** `RosterSeat.work_admission[scope]` (api-types 0.115.0). `source`: `auth` — signed out;
  *  `launcher` — a launch benches it (disabled, reviewer-only, a recent bench, a pending login
- *  check, the engine's worktree bench); `scope` — the scope's governance rule refuses it. */
+ *  check, the engine's worktree bench or host-floor bench); `scope` — the scope's governance rule refuses it. */
 export type SeatWorkAdmission =
   | { ok: true }
   | { ok: false; reason_code: SeatWorkReasonCode; source: 'auth' | 'launcher' | 'scope'; reason: string };
@@ -1250,7 +1282,8 @@ export type SeatQeReviewer =
 
 /**
  * One `RosterSeat.issues` entry (api-types 0.115.0). Today's codes: `signed_out`, `qe_blocked`
- * (problems); `quota`, `usage_limit`, `benched`, `codex_worktree`, `version_unproven`,
+ * (problems); `quota`, `usage_limit`, `benched`, `codex_worktree`, `host_floor` and `host_floor_unknown`
+ * (unreleased, wicked-core#976), `version_unproven`,
  * `unchecked` (`params.why`: `no_governance` | `no_host_boundary`), `fence_scoped`,
  * `live_check_failed` (warnings); `opt_in`, `no_qe`, `unverified` (notes). A client must tolerate
  * an unknown code.
@@ -1490,6 +1523,13 @@ export interface GateInfo {
    * advisory: it never gates a decision, and is omitted entirely on a normal gate.
    */
   refusal?: { matched: boolean; reason: string };
+  /**
+   * (api-types 0.124.0) WHY the run paused — the `awaitingHuman.gateKind` the live frame carried
+   * (`deliver`, `escalation`, `plan_approval`, …), or the durable row's `gate_kind` after a restart.
+   * A refused hand-over parks at an `escalation` whose `ord` is still the deliver unit: read the
+   * kind, never infer it from the unit. ABSENT on an older daemon and when the engine did not say.
+   */
+  gateKind?: string;
   /** (crew ≥ 0.9.0) The gated unit's persisted receipt (`WorkUnit.assurance`) — what assured the
    *  work this gate asks about. `null` when the unit carries none (no gate evaluated it yet, or an
    *  older engine); ABSENT on an older daemon. */
@@ -1612,7 +1652,9 @@ export interface LaunchPlan {
  * Body of `POST /runs/:id/reassign` — the manual operator lever that reassigns a wedged run's
  * cursor unit through the same engine path the stall-watchdog's automatic escalation uses
  * (crew#442). `cli` omitted lets the engine's council re-pick the seat; when present it must be
- * a seat in the run's own pool (`SessionView.clis`) or the route answers 400.
+ * a seat in the run's own pool (`SessionView.clis`) or the route answers 400. On a run parked at a
+ * gate with `cli` named (crew#1058), the unit is re-seated FIRST and the gate approved after: a seat
+ * the engine refuses (see `WorkUnit.reassign_refused`) is a 409 with the gate still open.
  */
 export interface ReassignRequest {
   cli?: string;
@@ -1644,6 +1686,16 @@ export interface CoreEvent {
   message?: string;
   /** `elicitationCreated` (DES-002): the id minted by the actor for this elicitation round. */
   elicitationId?: string;
+  /** `elicitationCreated`: 'ask' for worker questions; chat refusal frames retain their source. */
+  source?: 'ask' | ChatRefusalSource;
+  /** The operator's accepted free-text or single-select answer. */
+  answer?: string;
+  heldMs?: number;
+  /**
+   * ask `elicitationCreated` (wicked-core, additive): the seat key that asked — the asking unit's
+   * roster seat for that `attempt` (e.g. `pi`, `codex#2`). Absent for every other producer.
+   */
+  seat?: string;
   /** `elicitationCreated`: an ordered set of valid responses; `null` / absent = free-text. */
   options?: string[] | null;
   /**
@@ -1698,7 +1750,7 @@ export interface CoreEvent {
   /** `terminalOpened`: the working directory the PTY was opened in. */
   cwd?: string;
   // ── DES-STUDIO-COCKPIT-001 §3 B-events (Phase B insight wires) ──
-  /** `unitDispatched`/`cliUsage`: 0-based dispatch attempt (`>0` = a re-dispatch / rework). */
+  /** `unitDispatched`/`cliUsage`/ask `elicitationCreated`: 0-based dispatch attempt (`>0` = a re-dispatch / rework). */
   attempt?: number;
   /** `cliUsage`: prompt/input tokens for the unit run. */
   inputTokens?: number;
@@ -5160,6 +5212,18 @@ export interface WorkflowDef {
    * attributed QE PASS, or no push) and is never waived by `reducedAssurance`.
    */
   required_instruments?: string[] | null;
+  /**
+   * (api-types 0.123.0; DES-CHAT-FIRST-001 C2, wicked-core-ts after 0.12.1) How the workflow is
+   * described to an operator: a short display name (`"Build a feature"`). Display data only — the
+   * daemon never sends it to the engine (whose def parser is strict). Served on a built-in that is
+   * not a system workflow, copied from its preset ({@link Preset.title}); ABSENT on a system workflow,
+   * a runtime def, and on any daemon or engine older than the field. Absent ⇒ show the `id`.
+   */
+  title?: string;
+  /** (api-types 0.123.0, C2) One line on what the workflow does. Absent as {@link WorkflowDef.title} is. */
+  summary?: string;
+  /** (api-types 0.123.0, C2) 2–4 short phrases saying when to pick it. Absent as {@link WorkflowDef.title} is. */
+  use_when?: string[];
 }
 
 /** A drop-in workflow definition the ENGINE refused, with the engine's own reason (wicked-crew#718). */
@@ -5659,6 +5723,17 @@ export interface ElicitationInfo {
    * focus, DESIGN-interaction rule 6).
    */
   recommended?: number;
+  /**
+   * (ask) Who asked, relayed from the engine's additive `elicitationCreated` fields for a seat's
+   * MCP `ask` question: `source: "ask"`, the asking unit's `ord` and dispatch `attempt`, and the
+   * `seat` key that asked (the roster instance, e.g. `pi`, `codex#2`). ABSENT for every other
+   * producer and on an engine that predates them; a skin then names the seat running the run's
+   * current step.
+   */
+  source?: 'ask';
+  ord?: number;
+  attempt?: number;
+  seat?: string;
   receivedAt: string;
 }
 
@@ -5751,6 +5826,17 @@ export interface Preset {
    * on every preset it serves (api-types 0.48.0); absent from an older daemon.
    */
   system?: boolean;
+  /**
+   * (api-types 0.123.0; DES-CHAT-FIRST-001 C2, wicked-core-ts after 0.12.1) A short display name,
+   * set by the engine on a built-in row (`created_by: "builtin"`). Absent on a saved preset —
+   * including a project row that shadows a built-in's name — and from an older engine: list it by
+   * `name`.
+   */
+  title?: string;
+  /** (api-types 0.123.0, C2) One line on what the preset does. Absent as {@link Preset.title} is. */
+  summary?: string;
+  /** (api-types 0.123.0, C2) 2–4 short phrases saying when to pick it. Absent as {@link Preset.title} is. */
+  use_when?: string[];
   [k: string]: unknown;
 }
 
@@ -6303,6 +6389,9 @@ export interface InteractionRequest {
   /** The already-run unit the gate reviews, when attributable. */
   reviewing_ord: number | null;
   prompt: string;
+  /** (api-types 0.124.0 types the engine field) WHY the run paused — mirrors
+   *  `awaitingHuman.gateKind`. `null`/ABSENT on a row written before the field. */
+  gate_kind?: string | null;
   status: 'open' | 'answered' | 'expired' | 'cancelled';
   /**
    * The decision payload (JSON text, e.g. `{"approve":true,"amend":null}`) once resolved. Its
@@ -7826,18 +7915,35 @@ export interface ListProposalsResponse {
  * landing that could not complete reports `outcome:"failed"` with a loud, operator-readable `error`
  * (recoverable by hand via `POST /governance/rules`) rather than turning the approve into a 500.
  */
+/**
+ * (api-types 0.126.0) What a proposal is ABOUT — the one `reach` word for memories and policies.
+ * `operator`: how the operator works (style, preferences, standing extra steps, standing rules) —
+ * applies in EVERY project (a memory lands at the operator scope every recall includes; a rule lands
+ * with no project). `project`: that project's or repo's code (a rule lands with `targets.project`).
+ * `pattern` (memories only): a general pattern the person lets cross projects.
+ */
+export type PolicyReach = 'project' | 'operator';
+export type MemoryReach = 'project' | 'pattern' | 'operator';
+
 export interface PolicyLandingResult {
-  /** `landed` = the steering rule is in the store; `failed` = the proposal is approved but no rule
-   *  was written — `error` says why. */
+  /** `landed` = the steering rule is in the store and the proposal is approved; `failed` = no rule
+   *  is in force — `error` says why. Since crew 0.13.3 the rule lands BEFORE estate marks the
+   *  proposal approved, so on `failed` from `POST /proposals/:id/approve` the proposal is still
+   *  pending and can be approved again (an older daemon left it approved with no rule). */
   outcome: 'landed' | 'failed';
   /** The upserted rule's id (deterministic `proposal:<proposalId>`, idempotent on replay). Present on `landed`. */
   ruleId?: string;
+  /** (api-types 0.126.0) The reach the rule landed with: `operator` = every project, `project` =
+   *  {@link PolicyLandingResult.project} only. Present on `landed` from crew ≥ 0.13.3. */
+  reach?: PolicyReach;
   /** 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).
+   * facet (else, since crew 0.13.3, the project of the run that filed it), kept as
+   * `targets.project` and confirmed by reading the rule back. Absent on a landing with no project
+   * (the rule applies everywhere). A proposal scoped only to a `repo` that resolves to no project
+   * fails instead of landing everywhere.
    */
   project?: string;
   /** Present iff `outcome:"failed"` — the loud reason the rule did not land. */
@@ -7860,8 +7966,8 @@ export type ApproveProposalResponse =
  * `POST /proposals/:id/approve` body (api-types 0.49.0) — present only for an accept WITH an edit;
  * no body (or `{}`) is the plain approve. estate has no proposal edit, so the daemon submits the
  * edited copy to the same queue (`payload.edited_from = <id>`), approves it, then rejects the
- * original. Memory proposals only (400 otherwise; 404 when `id` is not pending; 409 while another
- * accept of the same `id` is in flight).
+ * original. `content` is for memory proposals only (400 otherwise; 404 when `id` is not pending;
+ * 409 while another accept of the same `id` is in flight); a policy proposal takes `reach` alone.
  */
 export interface ApproveProposalBody {
   /** The edited memory text (replaces `payload.content`). */
@@ -7870,8 +7976,12 @@ export interface ApproveProposalBody {
    *  (the human act that lets a pattern cross projects; refused on anything but a captured memory, `payload.capture: "memory"`).
    *  `"project"`: it stays scoped to its project — gaining the proposing run's project as its
    *  `project` facet when the worker filed none (400 when no project files that run). An accept
-   *  that changes nothing the store keeps approves the original as filed (no copy, no `edited`). */
-  reach?: 'project' | 'pattern';
+   *  that changes nothing the store keeps approves the original as filed (no copy, no `edited`).
+   *  `"operator"` (api-types 0.126.0): the memory is about how the operator works — it lands at the
+   *  operator scope, recalled in every project, with no project/repo facet pinning it to one.
+   *  On a POLICY proposal (`reach` only, no `content`): `"operator"` lands the rule for every
+   *  project, `"project"` for its project (400 when it names none); `"pattern"` is refused. */
+  reach?: MemoryReach;
 }
 
 /**
@@ -7925,7 +8035,8 @@ export interface CaptureImageFile {
  * per-run inbox and launches a repo-less run filed to the project (through `POST /runs`, so its
  * refusals are that route's). The run's output is proposals in the `/proposals` queue — each with
  * `kind_type: "memory"` (or `"policy:<type>"` for a rule), `payload.capture` = `intent` |
- * `decision` | `memory` | `rule`, `provenance.run_id` = the returned `runId`, and `facets.project`
+ * `choice` | `memory` | `rule` (a memory row filed before crew 0.13.3 may say `decision` for a
+ * `choice`; `decision` on a POLICY row means the decision ledger filed it, DES-decision-capture), `provenance.run_id` = the returned `runId`, and `facets.project`
  * unless the team marked a memory `payload.reach: "pattern"` (the user decides on accept).
  */
 export interface CaptureBody {
@@ -8415,6 +8526,28 @@ export interface RetireMemoryResponse {
   erased: number;
 }
 
+/**
+ * `POST /memory/edit` body (api-types 0.125.0; wicked-studio's Memory page): change ONE memory's
+ * words. estate has no in-place update, so crew writes `content` as a new memory with the old one's
+ * tier, scope and facets (`memory.capture`), then erases the old one by id. Erase-by-id is checked
+ * before anything is written. When a later step does not answer as expected, crew re-reads the store:
+ * a replacement that landed is a 200; a new copy beside a surviving old memory is taken back out.
+ * 400: empty or unchanged `content`; 404: no memory has that id; 409: an edit of the same memory is in
+ * flight; 501 `estate_upgrade_required`: the estate cannot erase by id (nothing was written); 502: an
+ * estate step failed, and the error says what the store holds now (nothing changed, or which ids remain).
+ */
+export interface EditMemoryBody {
+  memory_id: string;
+  /** The new words (1–4000 chars, trimmed). */
+  content: string;
+}
+
+/** `POST /memory/edit` → 200: the new memory's id and the id of the one it replaced (now erased). */
+export interface EditMemoryResponse {
+  memory_id: string;
+  retired: string;
+}
+
 // ── Team events on the bus (DES-TEAMING-002 §6, wicked-core T1; api-types 0.41.0) ──────────────
 //
 // The `wicked.team.*` facts wicked-core publishes on the cross-product bus (`domain`
@@ -10992,3 +11125,97 @@ export interface McpInspectLogResponse {
   state: McpInspectState;
   error: string | null;
 }
+
+// ── Global search (`GET /search`; api-types 0.127.0) ─────────────────────────────────────────────
+//
+// One query over every major entity the daemon can read, answered grouped by type, ranked, with a
+// snippet per hit. The daemon keeps an in-memory text index it builds lazily on the first search
+// (off the request path) and keeps current from its own writes and engine frames. A query never
+// holds the event loop: it yields while it scans, stops at a hard time budget (`partial: true`)
+// and stops early when the client disconnects (a superseded query).
+
+/** The searchable entity types, in the order the daemon answers them. */
+export type SearchType = 'run' | 'project' | 'repo' | 'transcript' | 'rule' | 'memory' | 'doc';
+
+/** A half-open `[start, end)` UTF-16 range of matched text inside a hit's `title` or `snippet`. */
+export type SearchSpan = [number, number];
+
+/** Where a hit opens. A skin maps each kind to its own address. */
+export type SearchTarget =
+  | { kind: 'run'; run_id: string; chat_id: string | null }
+  | { kind: 'project'; project_id: string }
+  | { kind: 'repo'; repo_id: string }
+  /** A chat's transcript (a live chat: chat transcripts are kept only while the chat is open). */
+  | { kind: 'chat'; chat_id: string }
+  /** One unit's captured output (its transcript) inside a run. */
+  | { kind: 'unit'; run_id: string; ord: number; chat_id: string | null }
+  | { kind: 'rule'; rule_id: string; steering_type: string | null }
+  | { kind: 'memory'; memory_id: string; scope: string }
+  | { kind: 'doc'; project_id: string; doc: string };
+
+export interface SearchHit {
+  type: SearchType;
+  /** Unique within `type`. */
+  id: string;
+  title: string;
+  /** The matched ranges in `title`. */
+  title_spans: SearchSpan[];
+  /** A short window of the matched body text (whitespace collapsed, `…` where cut); `null` when the hit has no body. */
+  snippet: string | null;
+  snippet_spans: SearchSpan[];
+  /** Higher is better; comparable only within one group. */
+  score: number;
+  /** Unix MILLIS of the entity's last known change, when the daemon knows it. */
+  updated_at: number | null;
+  project_id: string | null;
+  /** The entity's own state word where it has one (a run's status, `retired`, `archived`), else `null`. */
+  status: string | null;
+  target: SearchTarget;
+}
+
+export interface SearchGroup {
+  type: SearchType;
+  /** Every match the query found in this type (a lower bound when `partial`). */
+  total: number;
+  /** This page, best first. */
+  hits: SearchHit[];
+  /** Pass back as `cursor` (with `types=<this type>`) for the next page; `null` on the last page. */
+  next_cursor: string | null;
+}
+
+/**
+ * How much of a type the index holds. `indexing`: the first read of that source is still running
+ * (search again shortly); `unavailable`: the source could not be read (`note` says why), so the
+ * type was not searched.
+ */
+export interface SearchSourceState {
+  type: SearchType;
+  state: 'ready' | 'indexing' | 'unavailable';
+  /** Entities of this type the index holds. */
+  indexed: number;
+  note: string | null;
+}
+
+/**
+ * `GET /search?q=&types=&limit=&cursor=` → 200.
+ *
+ * - `q` (required, 2–256 chars after trimming): words (each must match, case-insensitive, anywhere
+ *   in a title or body) and `"quoted phrases"`. 400 when missing, too short or too long.
+ * - `types`: comma-separated `SearchType`s (default every type). 400 on an unknown type.
+ * - `limit`: hits per group, 1–50 (default 5).
+ * - `cursor`: a group's `next_cursor`; needs exactly one type in `types` (400 otherwise).
+ *
+ * Unit transcripts are indexed from a capped head and tail of each output (the full output stays at
+ * `GET /runs/:id/units/:unit/output`); the oldest transcripts leave the index first when its text
+ * budget is full.
+ */
+export interface SearchResponse {
+  query: string;
+  /** One group per searched type with at least one hit, in `SearchType` order. */
+  groups: SearchGroup[];
+  /** One row per requested type. */
+  sources: SearchSourceState[];
+  /** The time budget ran out before every type was scanned: totals are lower bounds. */
+  partial: boolean;
+  took_ms: number;
+}

package/package.json

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