wicked-crew-api-types 0.1.0 → 0.4.0

package/index.d.ts

@@ -26,6 +26,69 @@
  * the daemon's produced types stop satisfying this contract.
  */
 
+// ── Identity / actor contract (task #88, locked decision #6) ───────────────────
+
+/** What kind of principal an actor is: a person (OAuth/OIDC or local operator), a workload, or an internal process. */
+export type ActorKind = 'human' | 'agent' | 'system';
+
+/**
+ * The minimal trust ladder: `admin` > `operator` > `observer`.
+ *
+ * - `observer` — read-only: every GET, and the `/ws` event stream.
+ * - `operator` — does the work: launch/steer/cancel runs, answer gates and
+ *   elicitations, open chats and terminals, register repos and workflows.
+ * - `admin` — governs the system: governance writes (policies/rules),
+ *   settings writes, and project archive/restore.
+ *
+ * Deliberately minimal and enumerated here rather than per-route: unknown
+ * mutating routes default to `operator`, reads to `observer` (docs/auth.md).
+ */
+export type TrustLevel = 'observer' | 'operator' | 'admin';
+
+/**
+ * The ONE actor shape every authenticated (or implicitly local) request carries
+ * — replacing free-text actor strings, which any caller could spoof. In local
+ * no-auth mode every request acts as `{id:"local", kind:"human", trust:"admin"}`
+ * (full trust), so downstream consumers never branch on "was there auth".
+ */
+export interface Actor {
+  /** Stable principal id (token-file `actor.id`, or an OIDC subject once that seam lands). */
+  id: string;
+  kind: ActorKind;
+  trust: TrustLevel;
+}
+
+/** `GET /whoami` — the actor this request authenticated as, and the daemon's auth mode. */
+export interface WhoAmI {
+  actor: Actor;
+  /** `required` (team/hosted: bearer token mandatory) | `off` (local loopback default). */
+  authMode: 'required' | 'off';
+}
+
+/**
+ * One line of the daemon's append-only audit trail (`GET /audit`): who did what,
+ * to which run, when. Written crew-side because the engine's `LaunchOptions`
+ * carries no actor field — this is the system of record for "who approved that
+ * gate" / "who launched that run".
+ */
+export interface AuditEntry {
+  /** Unix millis. */
+  ts: number;
+  /** Dotted verb, e.g. `run.launched`, `gate.decided`, `governance.policy.upserted`. */
+  action: string;
+  actor: Actor;
+  /** The run the action addressed, when it addressed one. */
+  runId?: string;
+  /** Action-specific fields (`approve`, `amend`, ids, …). */
+  detail?: Record<string, unknown>;
+  [k: string]: unknown;
+}
+
+/** `GET /audit` — newest first, filterable by `?runId=` / `?action=` / `?limit=`. */
+export interface AuditPage {
+  entries: AuditEntry[];
+}
+
 /** Run-level lifecycle status (`SessionStatus`, snake_case serde token). */
 export type SessionStatus =
   | 'planning'
@@ -88,6 +151,16 @@ export interface AgentSession {
   attempt: number;
   workdir: string | null;
   repo_ref: string | null;
+  /** Launcher-declared extra write roots for the run's deliverables (wicked-core#259). */
+  extra_write_roots: string[];
+  /**
+   * When the operator ARCHIVED this run (crew#265) — a write-off, not a delete: the run stays
+   * fully readable but default run listings exclude it. Unix millis; `null` = live. Guard with
+   * `== null` (the live API sends `null`, never omits the key).
+   */
+  archived_at: number | null;
+  /** Optional operator note recorded at archival. */
+  archive_note: string | null;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -148,6 +221,26 @@ export interface OnboardRef {
   runId: string | null;
 }
 
+/**
+ * Runtime health of one council seat (crew#274).
+ *
+ * Derived by the daemon from the live CoreEvent stream — NEVER from config. The roster is
+ * declarative: every configured CLI stays listed and enabled in `clis.toml`; quota/auth/runtime
+ * errors are runtime state the platform detects and displays as `inactive` + the error excerpt.
+ * Recovery is automatic: a captured-ok unit output for the seat, or an exit-0 `version_probe`
+ * from the daemon's low-frequency recovery probe, flips the seat back to `active` and clears
+ * the message — no operator hand-edit involved.
+ */
+export interface SeatHealth {
+  status: 'active' | 'inactive';
+  /** Bounded excerpt of the last seat-level error; present while `inactive`. */
+  message?: string;
+  /** When the seat entered its current status (ISO-8601). */
+  since: string;
+  /** When the last seat-level error was observed (ISO-8601), if any was. */
+  lastErrorAt?: string;
+}
+
 /**
  * A council seat (`AgenticCli`) as returned by `GET /roster`. Only the fields
  * the launch form uses are named; the index signature keeps the (large) rest of
@@ -159,9 +252,26 @@ export interface RosterSeat {
   binary: string;
   enabled_for_council: boolean;
   category?: string;
+  /**
+   * Runtime health (crew#274). Additive: absent on a daemon predating the field, and safe to
+   * round-trip into `clisJson` (the engine's `AgenticCli` deserializer ignores unknown fields).
+   * Absent-or-default reads as `active` with no message.
+   */
+  health?: SeatHealth;
   [k: string]: unknown;
 }
 
+/** Body for `POST /open` — open a file/folder with the OS default application (crew#273). */
+export interface OpenPathBody {
+  /**
+   * ABSOLUTE path to open. Validated daemon-side: it must resolve inside the run's workdir /
+   * extra write roots (when `runId` is given) or a registered repo root — never an arbitrary path.
+   */
+  path: string;
+  /** Widen validation to this run's workdir + extra write roots. Unknown id ⇒ 404. */
+  runId?: string;
+}
+
 /** The daemon's cached open-gate record (`GET /runs/:id/gate`, DES-STUDIO-001 §3.3). */
 export interface GateInfo {
   runId: string;

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "wicked-crew-api-types",
-  "version": "0.1.0",
+  "version": "0.4.0",
   "description": "The wire contract of the wicked-crew daemon's /api/v1 REST surface and /ws CoreEvent frames — types only, zero runtime",
   "type": "module",
   "types": "./index.d.ts",