wicked-crew-api-types 0.126.0 → 0.128.0

package/index.d.ts

@@ -282,6 +282,11 @@ export interface HealthCapabilities {
    * older daemon — read as `'required'`.
    */
   qeAcceptance?: 'required' | 'off';
+  /**
+   * (api-types 0.128.0) `LaunchRunBody.primary` is accepted: a launch may name the seat that leads
+   * the run. ABSENT on an older daemon — do not send the field (its strict schema 400s on it).
+   */
+  launchPrimary?: boolean;
 }
 
 /** One `GET /health.warnings[]` entry (additive; wicked-core#411 / wicked-crew#497). */
@@ -4746,6 +4751,15 @@ export interface LaunchRunBody {
   problem: string;
   sessionId?: string;
   clisJson?: string;
+  /**
+   * (api-types 0.128.0; DES-TEAMING-002 §8.1) The seat that LEADS the run (the primary agent, PA):
+   * a seat key from the launch roster (`clisJson`, else the daemon's default roster). The PA owns
+   * every step not marked `owner: "team"`. Omitted: the engine picks one at random among the
+   * eligible seats; either way the choice is recorded as `wicked.team.path.started.selection`
+   * (`"chosen"` | `"random"`). A key that is not in the roster, or names a signed-out seat, is a 400.
+   * Send only when `GET /health.capabilities.launchPrimary === true`.
+   */
+  primary?: string;
   entityMode?: EntityMode;
   humanConfirm?: string;
   repoRef?: string;
@@ -10081,7 +10095,11 @@ export interface McpSecretResponse {
 /** `POST /mcp/call`: what the garden shim sends. `token` is the worker's `WICKED_MCP_TOKEN`. */
 export interface McpCallBody {
   token: string;
-  /** `mcp:<server>/<tool>`. */
+  /**
+   * `mcp:<server>/<tool>`. The server name `estate` is reserved (wicked-core#1018): `mcp:estate/<tool>`
+   * is the estate relay, a container seat's way to its run's estate (the read-only graph, memory,
+   * knowledge and rules lookups, and `proposal.submit`), scoped by the daemon to the token's run.
+   */
   subject: string;
   /** The tool's arguments (a JSON object); absent = `{}`. */
   args?: Record<string, unknown>;
@@ -10118,7 +10136,11 @@ export interface McpCallResponse {
   subject: string;
   /** The call record's span id (`GET /mcp/usage` and the run's Governance panel resolve it). */
   callId: string | null;
-  /** The scrubbed `tools/call` result — only when `outcome` is `ok`. */
+  /**
+   * The scrubbed `tools/call` result — only when `outcome` is `ok`. For `mcp:estate/<tool>`, a
+   * JSON-RPC error estate answered (e.g. `-32602`, fix the arguments) is a tool error that keeps
+   * its code: `{ content, isError: true, rpcError: { code, message } }`.
+   */
   result?: Record<string, unknown>;
   /** The rules or gates that decided (deny, ask, withheld). */
   ruleIds: string[];
@@ -11125,3 +11147,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.126.0",
+  "version": "0.128.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",