wicked-crew-api-types 0.20.0 → 0.25.0

package/index.d.ts

@@ -255,6 +255,33 @@ export interface AgentSession {
    * `GET /campaigns`.
    */
   group_label?: string;
+  /**
+   * When this run was LAUNCHED — unix SECONDS (home command-center run metrics; api-types 0.24.0).
+   * Daemon-derived at DTO assembly on BOTH `GET /runs` and `GET /runs/:id` from the `run.launched`
+   * audit entry's timestamp (the daemon's durable system-of-record for run provenance — task #88),
+   * joined exactly like {@link retry_of} / {@link guidance} and hydrated from the SAME trail scan
+   * at boot, so it survives a daemon restart.
+   *
+   * This is the ONE launch instant the daemon records: "created" and "started" are the SAME event
+   * here — the engine's `AgentSession` (wicked-core `domain.rs`) carries no launch time, so there
+   * is no separate queued-vs-started split to expose. Unlocks time-bucketed KPI deltas and a real
+   * 7/30/90-day range on the home dashboard.
+   *
+   * ABSENT — never `null`, never fabricated — when the daemon has no `run.launched` entry for the
+   * run: a run launched OFF the `POST /runs` path (a repo's onboarding run, a campaign's own
+   * DAG-node runs), a run predating this field, or a `--db`-isolated daemon reading a trail that
+   * never saw the launch. Read with `typeof === 'number'`; a bucketed KPI or a 7/30/90-day range
+   * must EXCLUDE an undated run, never date it with a fabricated now.
+   *
+   * COST (deferred, not faked): a per-run cost/spend figure is deliberately NOT joined onto this
+   * DTO. Cost exists only on the per-unit {@link CliUsageEvent} (`costUsd`), streamed over `/ws`
+   * and never accumulated per run daemon-side — a reliable per-run total would require replaying
+   * the durable event log per run on this hot path (the unbounded cost the GET /runs delivery-cache
+   * architecture forbids) or a new live cliUsage accumulator plus a durable per-run store. A burn
+   * chart should sum `cliUsage.costUsd` from the live `/ws` stream (or `GET /runs/:id/events`) for
+   * now; a joined `AgentSession.cost` is a follow-up once that store exists.
+   */
+  created_at?: number;
 }
 
 /** An ordered unit of work within a run (`WorkUnit`). */
@@ -448,6 +475,16 @@ export interface GateDecision {
   amend?: string;
 }
 
+/**
+ * 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.
+ */
+export interface ReassignRequest {
+  cli?: string;
+}
+
 /**
  * A CoreEvent frame as delivered verbatim over `/ws` — a tagged-JSON object
  * discriminated on `type` (wicked-core-ts `event_to_json`). The named optional
@@ -1125,6 +1162,21 @@ export interface ConformanceRule {
   obligations?: string[];
   /** The frozen acceptance-criteria text (becomes a claim's `criteria` when the rule decides a gate). */
   criteria?: string;
+  /**
+   * Unix-SECONDS timestamp of when this rule FIRST entered the store — the "added" time the Steering
+   * surface sorts + date-filters on (NOT the latest-edit time), stamped once by the engine on first
+   * create and preserved across updates (api-types 0.23.0).
+   *
+   * WIRED-BUT-PENDING A CORE-TS BUMP: the field exists on the engine's `ConformanceRule`
+   * (wicked-core `conformance.rs`, serialized with `skip_serializing_if = Option::is_none`), but it
+   * landed AFTER the published `core-ts-v0.7.16` this daemon builds against — so a rule served by
+   * the current binding carries NO `created_at`. The daemon passes the field through verbatim
+   * (`listConformanceRules` returns the parsed rows unchanged), so it begins flowing the moment
+   * crew re-pins to a core-ts that includes it — no daemon change needed. ABSENT — never
+   * fabricated — on any rule the engine did not stamp (pre-field rows, and every row from a
+   * pre-bump binding), so a `since`/`until` filter cannot assert an undated rule in range.
+   */
+  created_at?: number;
 }
 
 /** Facet query for `GET /governance/rules/preview`. All fields are optional. */
@@ -1160,6 +1212,21 @@ export interface RuleBrowseQuery {
    * contradict, and picking a winner silently would answer a question the caller didn't ask).
    */
   include_retired?: 'true' | 'false';
+  /**
+   * Inclusive LOWER date bound (api-types 0.23.0): keep only rules with `created_at >= since`.
+   * Unix SECONDS, a non-negative integer (a present-but-non-integer value is a 400). Applied
+   * server-side over the listed rows, alongside the facet filters. A rule with NO `created_at`
+   * is EXCLUDED whenever `since` (or `until`) is set — see {@link ConformanceRule.created_at}: on
+   * a pre-bump core-ts binding NO rule carries the field, so this filter narrows to empty until the
+   * engine surfaces it. Omitted ⇒ no lower bound.
+   */
+  since?: string;
+  /**
+   * Inclusive UPPER date bound (api-types 0.23.0): keep only rules with `created_at <= until`.
+   * Same units/validation/undated-exclusion as {@link RuleBrowseQuery.since}. Omitted ⇒ no upper
+   * bound.
+   */
+  until?: string;
 }
 
 // ── Steering management (STEERING program) ──────────────────────────────────────
@@ -1442,6 +1509,66 @@ export interface ImportEvalCorpusResponse {
   embedded: boolean;
 }
 
+// ── Eval run history (crew-side EvalRunStore) — the Evals section's real list ───
+
+/**
+ * One steering type's slice of an eval run's rollup — the same four counts as
+ * {@link GovernanceEvalSummary}, derived from the run's results grouped by `sample.steering_type`.
+ * This is what makes "which steering type carries the gaps" a stored field, not a per-request
+ * recompute over the full results.
+ */
+export interface EvalRunPerTypeCount {
+  total: number;
+  caught: number;
+  gaps: number;
+  false_positives: number;
+}
+
+/**
+ * One PERSISTED eval run — the listable rollup row (`GET /testing/evals`). A run is one
+ * `POST /testing/evals/run` and its report, stamped with WHO ran it, WHAT it ran against, and
+ * WHEN, so the Evals section is a real history instead of a single session-local report that a
+ * reload loses. The per-sample `results` are NOT here — they live on {@link EvalRunDetail} (the
+ * drilldown), so listing the history stays cheap no matter how large a custom corpus is.
+ *
+ * Evals take no repo/project (they judge a STORE, not a workspace), so this is a single GLOBAL
+ * feed per daemon — unlike recon campaign runs, which file into projects.
+ */
+export interface EvalRunSummary {
+  /** Server-minted run id. */
+  id: string;
+  /** Unix SECONDS the run was recorded (the crew `created_at` convention — see AgentSession). */
+  created_at: number;
+  /** The authenticated actor who ran it. */
+  actor: string;
+  /** The corpus scope (`evals:<name>`), or null for the engine's built-in dev-behaviors corpus. */
+  corpus: string | null;
+  /** The single steering type the run was narrowed to, or null when it ran all seven. */
+  type_filter: SteeringType | null;
+  /** The steering rule store the run was judged against (the daemon's `--db` steering store). */
+  rule_store: string;
+  /** The report's rollup, verbatim ({@link GovernanceEvalSummary}). */
+  summary: GovernanceEvalSummary;
+  /** Per-steering-type rollup, derived from the results — present only for the types the run covered. */
+  per_type: Partial<Record<SteeringType, EvalRunPerTypeCount>>;
+  /** `'facet-only'` when the run degraded to facet matching; null when it ran full-fidelity. */
+  degraded: 'facet-only' | null;
+}
+
+/**
+ * One eval run WITH its full per-sample results (`GET /testing/evals/:id`) — the drilldown behind a
+ * history row. `results` is the same verbatim {@link GovernanceEvalResult} array the run's original
+ * `POST /testing/evals/run` returned, so the existing report view renders it unchanged.
+ */
+export interface EvalRunDetail extends EvalRunSummary {
+  results: GovernanceEvalResult[];
+}
+
+/** The `GET /testing/evals` 200 body — the eval run history, newest first. */
+export interface ListEvalRunsResponse {
+  runs: EvalRunSummary[];
+}
+
 /**
  * The `POST /testing/recon` request body (api-types 0.15.0) — the Testing page's campaign-recon
  * trigger. `problem` is the recon brief, passed to every launched run VERBATIM (the client owns
@@ -2755,3 +2882,191 @@ export interface DiagnosticsResponse {
   recentErrors: DiagnosticsRecentError[];
   acp: AcpDiagnostics;
 }
+
+// ── Memory proposal queue (DES-MEM-FACETED-001 §5.0, api-types 0.21.0) ─────────
+
+/**
+ * A proposal's lifecycle state. A proposal is INERT while `pending` (never recalled/applied);
+ * `approve` promotes its payload to the active store and marks it `approved`, `reject` marks it
+ * `rejected`.
+ */
+export type ProposalState = 'pending' | 'approved' | 'rejected';
+
+/**
+ * One entry in the estate proposal queue — a type-generic, inert write agents submit and operators
+ * decide (estate #162). The shape is the estate MCP `proposal.list` wire form verbatim.
+ */
+export interface Proposal {
+  /** Stable proposal-node id. */
+  id: string;
+  /** `"memory"` | `"policy:<steering_type>"` | future — the router key `approve` promotes by. */
+  kind_type: string;
+  /** The proposed content (a memory body, a policy rule, …). Opaque here; narrowed by `kind_type`. */
+  payload: unknown;
+  /** Agent-declared orthogonal facets (axis → value). */
+  facets: Record<string, string>;
+  /** Run/unit/agent attribution — AUTHORITY-STAMPED by the estate MCP from its launch env, never
+   *  taken from the submitter. Empty when the server had no `WICKED_RUN_*` env. */
+  provenance: Record<string, string>;
+  state: ProposalState;
+  /** Unix seconds. */
+  created_at: number;
+}
+
+/** `GET /proposals` query filters — both optional; omitting a filter lists across that dimension. */
+export interface ListProposalsQuery {
+  kind_type?: string;
+  state?: ProposalState;
+}
+
+/** `GET /proposals` → 200. */
+export interface ListProposalsResponse {
+  proposals: Proposal[];
+}
+
+/**
+ * The result of landing an approved POLICY proposal as a steering rule (DES-MEM-FACETED-001 §5.2).
+ * estate performs no rules-write for a policy proposal (the AW-11 invariant) — it hands the payload
+ * to crew, the one governed rules-write path, which shapes a `ConformanceRule` and upserts it. Like
+ * the steering-author landing (crew#388) the estate decision (approve) stands regardless, so a
+ * 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.
+ */
+export interface PolicyLandingResult {
+  /** `landed` = the steering rule is in the store; `failed` = the proposal is approved but no rule
+   *  was written — `error` says why. */
+  outcome: 'landed' | 'failed';
+  /** The upserted rule's id (deterministic `proposal:<proposalId>`, idempotent on replay). Present on `landed`. */
+  ruleId?: string;
+  /** The steering type derived from the proposal's `kind_type` (`policy:<type>`). Present on `landed`. */
+  steering_type?: SteeringType;
+  /** Present iff `outcome:"failed"` — the loud reason the rule did not land. */
+  error?: string;
+}
+
+/**
+ * `POST /proposals/:id/approve` → 200. A MEMORY proposal is `promoted` (its payload is now an
+ * active memory, `active_id`) and is complete. A POLICY proposal is `handed_off` — its `payload`
+ * (`{ rule, severity }`) is still returned verbatim, and `landing` now reports the steering rule
+ * crew created from it (`landing.outcome:"landed"` with the `ruleId`), or the loud reason it could
+ * not (`landing.outcome:"failed"`). `landing` is absent only from responses served by a daemon
+ * predating the policy→steering landing (forward-additive, DES-MEM-FACETED-001 §5.2).
+ */
+export type ApproveProposalResponse =
+  | { outcome: 'promoted'; active_id: string }
+  | { outcome: 'handed_off'; payload: unknown; landing?: PolicyLandingResult };
+
+/** `POST /proposals/:id/reject` → 200. */
+export interface RejectProposalResponse {
+  ok: true;
+}
+
+// ── Memory management (governed-knowledge surface, DES-MEM-FACETED-001, api-types 0.22.0) ──────
+//
+// The studio's surface for managing the memories that ALREADY exist in the operator store — the
+// counterpart to the proposal queue (which decides learnings not yet stored). Backed by the estate
+// MCP memory tools (memory.recall / memory.coverage / memory.erase) exposed over crew's /api/v1.
+// The granularity is estate's, surfaced honestly: browse is query-based (no "list all"), and
+// retire is SUBTREE-scoped (no per-id delete).
+
+/**
+ * One memory as browsed from the store (`GET /memory`, from estate `memory.recall`).
+ *
+ * estate `memory.recall` is query-based and token-budgeted — there is NO "list all" — and returns
+ * `{ memory_id, scope, content, tier, score }` per item. It does NOT surface per-item `facets`, so
+ * `facets` is presently always `{}` (kept in the shape for forward-compatibility and to mirror
+ * `Proposal.facets`); `score` is the recall relevance score, absent when estate omits it.
+ */
+export interface MemoryItem {
+  /** Stable memory-node id (estate `memory_id`). */
+  id: string;
+  /** The memory body. */
+  content: string;
+  /** Tier: `working` | `episodic` | `semantic` | `procedural` | `archival`. */
+  tier: string;
+  /** The memory's own hierarchical scope path (slash-separated `kind:id` segments; `""` = root). */
+  scope: string;
+  /** Orthogonal facets (axis → value) the memory is tagged with. Populated by estate `memory.list`
+   *  (the management browse) — this is what powers the surface's facet filter. `{}` for an
+   *  unfaceted memory (and for a `memory.recall`-sourced item, which carries no facets). */
+  facets: Record<string, string>;
+  /** Relevance score — only present on a `memory.recall` item; `memory.list` (the browse) is not
+   *  relevance-ranked, so it is absent there. */
+  score?: number;
+  /**
+   * Unix-SECONDS timestamp of when this memory FIRST entered the store — the "added" time the
+   * governance surface sorts + date-filters on (api-types 0.23.0). Populated from estate
+   * `memory.list`, which returns `created_at` per item; ABSENT — never fabricated — on a memory
+   * whose creation time the store did not report (and on a `memory.recall`-sourced item, which
+   * carries none). Additive: absence is the one spelling of "unknown", so a `since`/`until` filter
+   * cannot assert an undated memory in range.
+   */
+  created_at?: number;
+}
+
+/**
+ * `GET /memory` query filters. All optional. The browse itself lists the COMPLETE in-scope set via
+ * estate `memory.list`; `query`, `facets`, and `limit` are applied server-side as post-filters over
+ * that set (they are NOT a relevance query). `scope_prefix` is the only estate-side argument — a
+ * subtree filter where `""`/omitted matches EVERY memory (the same predicate as retire). `query` is
+ * a case-insensitive CONTENT substring match. `facets` is a JSON-encoded object of axis→value
+ * strings; an item is kept only if it carries every pair. `limit` caps the returned ROW count.
+ */
+export interface ListMemoriesQuery {
+  /** Case-insensitive content substring filter over the complete set. */
+  query?: string;
+  scope_prefix?: string;
+  /** JSON-encoded `Record<string, string>` (axis→value); a malformed value is a 400. */
+  facets?: string;
+  /** Positive integer; caps the returned row count. */
+  limit?: string;
+  /**
+   * Inclusive LOWER date bound (api-types 0.23.0): keep only memories with `created_at >= since`.
+   * Unix SECONDS, a non-negative integer (a present-but-non-integer value is a 400). Applied
+   * server-side over the loaded set, alongside `query`/`facets`. A memory with NO `created_at`
+   * is EXCLUDED whenever `since` (or `until`) is set — an unknown creation time is not asserted
+   * in range. Omitted ⇒ no lower bound.
+   */
+  since?: string;
+  /**
+   * Inclusive UPPER date bound (api-types 0.23.0): keep only memories with `created_at <= until`.
+   * Same units/validation/undated-exclusion as {@link ListMemoriesQuery.since}. Omitted ⇒ no
+   * upper bound.
+   */
+  until?: string;
+}
+
+/** `GET /memory` → 200. */
+export interface ListMemoriesResponse {
+  memories: MemoryItem[];
+}
+
+/** `GET /memory/coverage` query — an optional subtree filter (`""`/omitted = global totals). */
+export interface MemoryCoverageQuery {
+  scope_prefix?: string;
+}
+
+/**
+ * `GET /memory/coverage` → 200 (estate `memory.coverage`). Memory-node counts, optionally scoped to
+ * a subtree: `total`, plus per-tier and per-kind breakdowns.
+ */
+export interface MemoryCoverageResponse {
+  total: number;
+  by_tier: Record<string, number>;
+  by_kind: Record<string, number>;
+}
+
+/**
+ * `POST /memory/retire` body. Retire is SUBTREE-scoped, never per-id: estate `memory.erase`
+ * hard-deletes EVERY memory whose scope equals or descends from `scope_prefix`. `scope_prefix` is
+ * required and must be non-empty (estate refuses a total wipe) — the surface must show the operator
+ * the whole subtree it will remove, not a single row.
+ */
+export interface RetireMemoryBody {
+  scope_prefix: string;
+}
+
+/** `POST /memory/retire` → 200. The number of memories the subtree wipe deleted. */
+export interface RetireMemoryResponse {
+  erased: number;
+}

package/package.json

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