wicked-crew-api-types 0.7.0 → 0.10.0

package/index.d.ts

@@ -161,6 +161,35 @@ export interface AgentSession {
   archived_at: number | null;
   /** Optional operator note recorded at archival. */
   archive_note: string | null;
+  /**
+   * The project this run is filed into (DES-UX-001 §8.2, CREW-UX-2; api-types 0.8.0) —
+   * populated by the crew server from the membership record at DTO assembly on BOTH
+   * `GET /runs` and `GET /runs/:id`, so clients no longer re-derive the run→project join.
+   *
+   * `null` = genuinely unfiled (the synthesized `default` project); ABSENT = a pre-0.8.0
+   * server that never joins. Read with `== null` only if "unfiled" and "old server" may
+   * collapse for your surface; a project chip should render only on `typeof === 'string'`.
+   */
+  project_id?: string | null;
+  /**
+   * Retry lineage (DES-UX-001 §8.3, CREW-UX-3; api-types 0.8.0): the id of the run this run
+   * was launched as a retry of (`LaunchRunBody.retryOf`, validated at launch to name an
+   * existing run). ABSENT — never `null` — when the run is not a retry: absence is the one
+   * spelling of "no lineage", so `'retry_of' in session` and `!== undefined` agree.
+   */
+  retry_of?: string;
+  /**
+   * Durable operator guidance (DES-UX-002 §7.2 — spec'd there as CREW-UX-4, shipped as
+   * CREW-UX-7; api-types 0.9.0): the ONE pre-gate note upserted via `PUT /runs/:id/guidance`,
+   * populated at DTO assembly on both `GET /runs` and `GET /runs/:id`. ABSENT — never `null`
+   * or `''` — when no note is set (never set, cleared, or a pre-0.9.0 server), so old clients
+   * are unaffected and `'guidance' in session` and `!== undefined` agree.
+   *
+   * Operator-visible context ONLY: the governance gate never reads this field; the amend text
+   * at gate decision (`GateDecision.amend`) remains the one injection point. Skins use it to
+   * pre-populate the steer textarea when a gate arrives.
+   */
+  guidance?: string;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -931,6 +960,32 @@ export interface LaunchRunBody {
    * field is forward-additive on the wire (DES-STUDIO-001 §5.1).
    */
   deliver?: 'pr';
+  /**
+   * 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
+   * a named error), never a silently unrecorded lineage. The daemon persists it, echoes it
+   * as `AgentSession.retry_of`, and carries it in the `run.launched` audit entry's detail,
+   * so provenance renders "retry of {id}" from the system of record, not prompt equality.
+   * Omit when the launch is not a retry.
+   */
+  retryOf?: string;
+}
+
+/**
+ * Body for `PUT /runs/:id/guidance` (DES-UX-002 §7.2, CREW-UX-7; api-types 0.9.0) — upsert the
+ * run's ONE durable operator guidance note. `text: ''` CLEARS the note (the DTO field returns
+ * to absent). Capped at 8192 UTF-8 bytes — beyond it the daemon answers 400 with a named
+ * error. An unknown run is a 404. The write is audit-trailed (`action: 'guidance.set'` with
+ * the authenticated actor) and survives daemon restart.
+ */
+export interface SetGuidanceBody {
+  text: string;
+}
+
+/** Response of `PUT /runs/:id/guidance` — echoes what was stored (`''` after a clear). */
+export interface SetGuidanceResult {
+  runId: string;
+  guidance: string;
 }
 
 // ── Governance types (crew#40/41) ──────────────────────────────────────────────
@@ -1122,6 +1177,18 @@ export interface SystemSettings {
    * the engine default `~/.wicked-worker`.
    */
   worker_config_root?: string;
+  /**
+   * SKIN-OWNED preference blobs (crew#323). The settings store is shared: alongside the
+   * engine's keys it carries the studio's own state — `studio.appearance` (accent/logo/theme),
+   * `studio.notifications` (desktop-notification opt-in) — which the daemon persists and
+   * returns VERBATIM without ever interpreting them.
+   *
+   * `PUT /settings` accepts a key matching `^studio\.[a-z][a-z0-9-]*$` whose value is
+   * JSON-serializable and at most 512KB of JSON; it answers 400 naming the key otherwise.
+   * Any other unrecognized key is still dropped from the patch (request bodies are
+   * forward-additive, §5.1), so a skin's own state MUST ride this namespace to persist.
+   */
+  [key: `studio.${string}`]: unknown;
 }
 
 // ── Requirements management (server-side search + overrides; crew api/requirements.ts) ──

package/package.json

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