wicked-crew-api-types 0.109.0 → 0.114.0

package/index.d.ts

@@ -288,6 +288,18 @@ export interface AgentSession {
   id: string;
   workflow_id: string;
   problem: string;
+  /**
+   * (api-types 0.113.0; operator ruling 2026-10-12) The run's SHORT JOB TITLE, derived by the daemon
+   * at DTO assembly on `GET /runs` and `GET /runs/:id` from {@link problem} — deterministic, at most
+   * 60 characters (an ellipsis included), so every skin shows the same headline: the operator's words
+   * without an attached studio context pack or step scaffold, cut at the first clause and then at an
+   * aside ("— …", ", meaning …", " when …"), which reads as a clause end; only a cut at a word boundary
+   * (no aside left) ends in "…". Onboarding runs read
+   * "Set up <repo>"; a chat's ask run reads "A conversation about <repos>". The full text stays in
+   * `problem` (show it on hover). ABSENT on a daemon before this field: a skin then falls back to its
+   * own first-clause cut of `problem`, never an invented title.
+   */
+  title?: string;
   entity_mode: EntityMode;
   collection_scope: string | null;
   clis: string[];
@@ -502,10 +514,13 @@ export interface AgentSession {
    * {@link created_at} ("started" ≡ "created" — the ONE launch instant) it gives a run its own clock;
    * a skin prefers these over the moment it happened to attach.
    *
-   * ABSENT — never `null`, never fabricated — when the daemon has no `run.ended` entry: a run
-   * still live, a run that terminalled before this field existed or before THIS daemon booted
-   * (no re-emission at boot), a lost trail, or the one crash window between the engine's status
-   * write and the daemon's synchronous audit record. Read with `typeof === 'number'`; a duration
+   * A terminal run with no `run.ended` entry (it ended before this field existed, or while no
+   * daemon was watching) is dated from the FIRST terminal frame in the engine's event log
+   * (`GET /runs/:id/events`), derived at read time and never written back (crew#985).
+   *
+   * ABSENT — never `null`, never fabricated — when neither source has it: a run still live, or a
+   * terminal run with no `run.ended` entry whose event log holds no terminal frame (it predates
+   * the log). Read with `typeof === 'number'`; a duration
    * or a "finished N minutes ago" MUST be omitted for an undated run, never derived from now.
    * Distinct from {@link finished_at} (engine-side unix MILLIS, retention bookkeeping).
    */
@@ -978,6 +993,11 @@ export interface SeatHealth {
  * the seat intact so it round-trips verbatim into `clisJson` on launch.
  */
 export interface RosterSeat {
+  /** (api-types 0.110.0, operator ruling 2026-10-11) An OPT-IN seat (opencode): never in a default
+   *  launch roster — a launch surface shows it unticked with `optInNote` ("opt-in: known to stall")
+   *  and includes it only when the operator ticks it. ABSENT for every other seat. */
+  optIn?: true;
+  optInNote?: string;
   key: string;
   display_name: string;
   binary: string;
@@ -1165,14 +1185,21 @@ export interface RosterSeatCouncilBench {
 }
 
 /**
- * `GET /roster/record?days=N` (api-types 0.52.0): each seat's record over the last N days (default 7,
- * max 30), folded from the runs' durable event logs (studio's weekly 1:1 per agent). Nothing new is
+ * `GET /roster/record?days=N[&project=<id>]` (api-types 0.52.0): each seat's record over the last N days
+ * (default 7, max 90 from api-types 0.113.0; was 30), folded from the runs' durable event logs (studio's
+ * weekly 1:1 per agent; the dashboards sum `costUsd` across seats for a window's spend). Nothing new is
  * stored; the window is by event time. A unit's seat is `unitDistributed.cli` (moved by
  * `unitReassigned.newCli`), else the unit row's `assigned_cli`. 503 when the engine has no event-log
  * read binding (a missing binding is not an empty week).
  */
 export interface SeatRecordResponse {
   days: number;
+  /**
+   * (api-types 0.113.0) The project the read was scoped to (`?project=<id>`: only that project's runs
+   * were folded). ABSENT on an unscoped read AND on a daemon before the parameter, which ignores it and
+   * answers for every run: trust a project-scoped spend only when this echoes the id you asked for.
+   */
+  project?: string;
   /** Window start, unix MILLIS. */
   since: number;
   /** Window end (the read time), unix MILLIS. */
@@ -1958,8 +1985,24 @@ export type AssuranceInstrument =
   | 'judge'
   | 'evaluator_pass'
   | 'distinct_evaluator'
+  /** (api-types 0.110.0) The operator judged a gate whose judge could not rule. */
+  | 'operator_judge'
   | (string & {});
 
+/**
+ * (api-types 0.110.0, operator ruling 2026-10-11) "Judged by operator": the operator's explicit
+ * approve at a `judge_unavailable` gate (no eligible judge, or a judge that gave no verdict). `by` is
+ * the actor the gate API recorded (the operator, or the agent acting for them); never automatic.
+ */
+export interface OperatorJudgment {
+  by: string;
+  /** Unix millis. */
+  at: number;
+  note: string | null;
+  /** Why the judge could not rule (the gate's denial reason). */
+  reason: string | null;
+}
+
 /** Why an instrument is absent from a receipt. */
 export type AssuranceSkipReason =
   | 'reduced_assurance'
@@ -2042,6 +2085,9 @@ export interface AssuranceReceipt {
    *  decided (`seats`) and the draw's `seed`. ABSENT when none was convened (the routine case) or on
    *  an older engine. A delivery receipt lists every council of the run. */
   councils?: TeamDispute[];
+  /** (api-types 0.110.0) Every gate the operator judged ("judged by operator"); ABSENT when none or on
+   *  an older engine. A unit receipt carries its own; a delivery receipt lists the run's. */
+  operatorJudges?: OperatorJudgment[];
 }
 
 /**
@@ -9466,8 +9512,22 @@ export interface McpPreviewTool {
   description: string | null;
   annotations: McpToolAnnotations | null;
   inputSchema: Record<string, unknown> | null;
+  /** The class the tool will have once saved: `classOverride ?? ` the class its annotations imply. */
   class: McpToolClass;
+  /**
+   * (api-types 0.111.0) The operator's class override this save keeps: the registered tool's, while
+   * its schema is unchanged; `null` for a new or changed tool, or one with no override.
+   */
+  classOverride: McpToolClass | null;
   schemaHash: string;
+  /**
+   * (api-types 0.111.0, G1) The switch `POST /mcp/servers` gives this tool when `enabledWrites`
+   * does not name it. A `write` or `destructive` tool that is new, or whose schema changed since
+   * the last save, is `false`: registered DISABLED until the operator grants it. A tool whose saved
+   * schema is unchanged keeps its switch; a new `read` tool is `true`. Enabling a tool is not
+   * approving it: `MCP-FIRST-USE` still asks on its first call.
+   */
+  enabledOnSave: boolean;
 }
 
 /**
@@ -9493,6 +9553,12 @@ export interface McpPreviewResponse {
   diff: McpToolDiff | null;
   /** `rest` only (api-types 0.64.0): operations that could not be wrapped, each with why. */
   skipped?: string[];
+  /**
+   * `rest` only (api-types 0.112.0, G2): where the tools' calls would go, checked against the
+   * document's `servers`. When `confirmRequired`, `POST /mcp/servers` needs `allowOrigin` set to
+   * exactly `egress.origin`.
+   */
+  egress?: McpRestEgress;
   /**
    * Each tool's decision per phase role × seat × mode under the current policies and approvals,
    * judged as if this preview were saved now (api-types 0.63.0); see `withdrawOnSave`. `null` when
@@ -9504,6 +9570,57 @@ export interface McpPreviewResponse {
 /** `POST /mcp/servers`. No `previewHash`, or one that is unknown or expired, is a 409. */
 export interface SaveMcpServerBody {
   previewHash?: string;
+  /**
+   * (api-types 0.111.0, G1) The operator's write grant: names of this preview's `write` or
+   * `destructive` tools to register ENABLED. Every other write tool that is new or changed is
+   * registered disabled (`McpPreviewTool.enabledOnSave`). A name the preview does not list is a 400
+   * `unknown_tool`; a tool that would not be a write once saved (its annotations, or a class override
+   * that survives an unchanged schema) a 400 `not_a_write_tool`. Both are refused before any approval
+   * is withdrawn and leave the preview usable. A grant from anyone but a human
+   * operator a 403 `write_grant_human_only`. Each grant is audited `mcp.tool.write_granted`.
+   */
+  enabledWrites?: string[];
+  /**
+   * (api-types 0.112.0, G2) The operator naming the exact origin a `rest` server's calls go to
+   * (`McpPreviewResponse.egress.origin`). Required when the preview's `egress.confirmRequired`
+   * (the base URL matches none of the document's `servers`, or its host is a loopback or private
+   * address, or did not resolve); without it, or with any other value, the save is a 409 `egress_unconfirmed`. It is
+   * remembered with the server, so re-saving over the same origin does not ask again. Human
+   * operator only (403 `egress_confirm_human_only`); audited `mcp.server.egress_confirmed`. A 400
+   * `egress_not_rest` for a server that is not `rest`.
+   */
+  allowOrigin?: string;
+}
+
+/**
+ * (api-types 0.112.0, G2, DES-data-connectors §3) A `rest` server's egress as its preview found it.
+ * A REST tool's schema hash also covers `{origin, basePath, auth header}`, so a changed target
+ * re-registers its tools and withdraws their approvals.
+ */
+export interface McpRestEgress {
+  /** The base URL's origin (`https://api.example.com`): the exact string `allowOrigin` names. */
+  origin: string;
+  /** The base URL's path, no trailing slash (`""` at the root). */
+  basePath: string;
+  /**
+   * The document's `servers` crew could resolve, as absolute URLs (`{variable}` = its default; a
+   * relative URL resolves against `openapiUrl`). No `servers` means `/`, per OpenAPI 3.
+   */
+  servers: string[];
+  /** The origin is one server's and the base path is that server's path or under it. */
+  matches: boolean;
+  /** The host is `localhost`, or is or resolves to a loopback/private/link-local/unique-local address. */
+  privateAddress: boolean;
+  /**
+   * `false` = the host is a name that did not resolve at preview, so crew could not check that it
+   * is not private. An IP literal is always `true`.
+   */
+  resolved: boolean;
+  /**
+   * `!matches || privateAddress || !resolved`, unless this origin was already confirmed for this
+   * server by an earlier save: the save needs `allowOrigin`.
+   */
+  confirmRequired: boolean;
 }
 
 /** `PATCH /mcp/servers/:name`. */
@@ -9511,7 +9628,13 @@ export interface PatchMcpServerBody {
   enabled: boolean;
 }
 
-/** `PATCH /mcp/tools/:subject` (subject URL-encoded). At least one field. */
+/**
+ * `PATCH /mcp/tools/:subject` (subject URL-encoded). At least one field. (G1) A patch that leaves
+ * the tool enabled AND a write (by its annotations, or its class after the patch) when it was not
+ * both before is a write grant: turning a write on, or re-classing an enabled read as a write. A
+ * grant is a human operator's only (else 403 `write_grant_human_only`) and is audited
+ * `mcp.tool.write_granted`. Turning a tool off, and enabling a read, need no grant.
+ */
 export interface PatchMcpToolBody {
   enabled?: boolean;
   classOverride?: McpToolClass | null;
@@ -10114,7 +10237,10 @@ export type EditorPermission =
   | 'media.read'
   | 'artifact.export'
   | 'ui.fullscreen'
-  | 'network.media';
+  | 'network.media'
+  /** Talk, through studio's host, to an MCP server the operator connected (DES-MCP-INSPECTOR-001).
+   *  No posture rule allows it: the editor's install consent writes its per-build grant. */
+  | 'mcp.session';
 
 /**
  * One registered editor, as Settings → Editors renders it. No path is on the wire: the bundle is
@@ -10169,6 +10295,14 @@ export interface InstallEditorResponse {
   editors: EditorView[];
   check: PackCheckResult;
   conformance: EditorConformanceSummary;
+  /**
+   * The `mcp.session` grant tokens this install consent wrote into `EDITOR-GRANTS` (one per installed
+   * editor that declares it). Absent when no installed editor declares it. `grantError` = the editor is
+   * installed but the ledger could not be edited: a declaring build's `mcp.session` still asks, or (for
+   * a build that no longer declares it) an earlier build's grant was not withdrawn.
+   */
+  granted?: string[];
+  grantError?: string;
 }
 
 /** What the install-time conformance run found (garden `scripts/editor/conformance.py`). */
@@ -10434,3 +10568,96 @@ export interface LearnTopicsResponse {
   repoRef: string;
   topics: LearnTopic[];
 }
+
+// ── MCP inspector bridge (DES-MCP-INSPECTOR-001 §3) ───────────────────────────────────────────
+// `/api/v1/mcp-inspect/sessions`: one live connection to an MCP server per session, driven by
+// studio's host for an `mcp-server` editor. Start, send and delete are human-only; the log is
+// operator-only. No session id, command, URL, env or header value is ever given to the plugin.
+
+/** What to connect to: a server in crew's MCP registry, a stdio command, or an HTTP endpoint. */
+export type McpInspectTarget =
+  | { server: string }
+  | { command: string; args?: string[]; env?: Record<string, string>; cwd?: string }
+  | { url: string; transport?: 'streamable-http' | 'sse'; headers?: Record<string, string> };
+
+/** `POST /mcp-inspect/sessions` */
+export interface McpInspectStartBody {
+  target: McpInspectTarget;
+}
+
+export type McpInspectState = 'connecting' | 'ready' | 'closed' | 'failed';
+
+/** The server's `initialize` result, secrets scrubbed. */
+export interface McpInspectInitialize {
+  protocolVersion: string | null;
+  serverInfo: { name: string; version: string; [k: string]: unknown } | null;
+  capabilities: Record<string, unknown>;
+  instructions: string | null;
+}
+
+export interface McpInspectSessionView {
+  id: string;
+  target: {
+    kind: 'server' | 'stdio' | 'streamable-http' | 'sse';
+    /** A short name: the registry name, the command's basename, or the URL's host. */
+    name: string;
+    /** The full command line or URL, for the HOST's header only. */
+    label: string;
+    /** Names only, never values. */
+    envNames: string[];
+    headerNames: string[];
+  };
+  state: McpInspectState;
+  initialize: McpInspectInitialize | null;
+  error: string | null;
+  startedAt: string;
+  /** The last log sequence number written. */
+  lastSeq: number;
+}
+
+/** `201` of `POST /mcp-inspect/sessions` */
+export interface McpInspectStartResponse {
+  session: McpInspectSessionView;
+}
+
+/** `POST /mcp-inspect/sessions/:id/rpc` */
+export interface McpInspectRpcBody {
+  method: string;
+  params?: Record<string, unknown>;
+}
+
+export interface McpInspectRpcResponse {
+  /** The server's JSON-RPC answer (`{ result }` or `{ error: { code, message, data? } }`), secrets scrubbed. */
+  response: { result?: unknown; error?: { code: number; message: string; data?: unknown } };
+  ms: number;
+  /** The answer was over the cap and is cut (the log entry carries the cut text). */
+  truncated: boolean;
+}
+
+export interface McpInspectLogEntry {
+  seq: number;
+  /** ISO time. */
+  at: string;
+  /** `out` = to the server, `in` = from it, `host` = the bridge's own line (state, exit). */
+  dir: 'out' | 'in' | 'host';
+  kind: 'request' | 'response' | 'notification' | 'stderr' | 'state';
+  method?: string;
+  rpcId?: string | number;
+  /** Round trip, on a response. */
+  ms?: number;
+  error?: boolean;
+  /** The message as JSON (or the stderr text), secrets scrubbed, at most 64 KB. */
+  text: string;
+  truncated?: boolean;
+}
+
+/** `GET /mcp-inspect/sessions/:id/log?after=&wait=` (a long poll) */
+export interface McpInspectLogResponse {
+  entries: McpInspectLogEntry[];
+  /** Pass as `after` next time. */
+  next: number;
+  /** The oldest sequence still held; entries before it were evicted (a gap). */
+  first: number;
+  state: McpInspectState;
+  error: string | null;
+}

package/package.json

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