wicked-crew-api-types 0.173.0 → 0.178.0

package/index.d.ts

@@ -12311,9 +12311,12 @@ export interface PutDeliveryFreezeBody {
 
 /**
  * How crew reaches an upstream: an MCP server over stdio or streamable HTTP, or a plain REST API
- * wrapped as tools from its OpenAPI document (`rest`, api-types 0.64.0).
+ * wrapped as tools from its OpenAPI document (`rest`, api-types 0.64.0). (api-types 0.175.0,
+ * DES-APPS-001 §5.1) `sql` (drivers `postgres`, `mysql`, `sqlite`) and `graphql` are Apps data
+ * sources: registered through the same preview/save, but with NO tools — nothing of theirs is ever
+ * offered to a governed run. Their preview answers {@link McpPreviewResponse.source} (the catalog).
  */
-export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest';
+export type McpUpstreamKind = 'mcp-stdio' | 'mcp-http' | 'rest' | 'sql' | 'graphql';
 /**
  * A tool's class, from its own `tools/list` annotations (never from a carrier): `read` when
  * `readOnlyHint` is true; else `destructive` unless `destructiveHint` is false; else `write`. A tool
@@ -12354,6 +12357,29 @@ export interface McpAuthConfig {
   prefix?: string;
 }
 
+/**
+ * (api-types 0.174.0, DES-APPS-001 §5.2) The ranges the person confirmed for one server's (or
+ * source's) connections. Every connection crew makes to it goes through ONE dialer that resolves
+ * the host once, checks EVERY address, connects to the checked address (keeping the name for TLS)
+ * and refuses redirects. With nothing confirmed, only global unicast addresses are reached, over
+ * TLS. A loopback or private address is reached only when a range here covers it. `0.0.0.0/8`,
+ * link-local (`169.254.0.0/16`, which holds `169.254.169.254`), CGNAT (`100.64.0.0/10`),
+ * `fd00:ec2::254`, multicast, documentation and reserved ranges are always refused and cannot be
+ * confirmed. An IPv4-mapped IPv6 address is judged as its IPv4 address.
+ */
+export interface McpAddressPolicy {
+  /**
+   * CIDR ranges wholly inside loopback (`127.0.0.0/8`, `::1/128`) or a private range
+   * (`10.0.0.0/8`, `172.16.0.0/12`, `192.168.0.0/16`, `fc00::/7`); at most 16. Anything else is a 400.
+   */
+  allow: string[];
+  /**
+   * Plaintext (`http:`) is accepted on a confirmed PRIVATE range. Loopback never needs it; a global
+   * address never gets it. `false`/absent = TLS only.
+   */
+  plaintext?: boolean;
+}
+
 /**
  * `POST /mcp/servers/preview`. `mcp-stdio` takes `command` (+ `args`); `mcp-http` takes `url`.
  * `rest` takes `url`, the base URL every call of the API is pinned to (its scheme, host and port,
@@ -12375,6 +12401,28 @@ export interface McpServerConfigBody {
   openapi?: Record<string, unknown>;
   /** `rest` only: the operations to wrap, by `operationId` or tool name; absent = all. */
   operations?: string[];
+  /**
+   * (api-types 0.174.0, DES-APPS-001 §5.2) `mcp-http` and `rest` only (a 400 on `mcp-stdio`, a
+   * local program outside the dialer): the loopback/private ranges this server's connections may
+   * reach. The preview already dials under it, so a preview of a server whose host is loopback or
+   * private without a range covering it is a 409 `address_unconfirmed` naming the range to confirm
+   * (`address_refused` for an always-refused address, `plaintext_refused` for http where TLS is
+   * required). A non-empty `allow`, or
+   * `plaintext: true`, is a human operator's only, at the preview and at the save (else 403
+   * `address_confirm_human_only`), and the save audits it `mcp.server.address_confirmed`.
+   */
+  address?: McpAddressPolicy;
+  /**
+   * (api-types 0.175.0, DES-APPS-001 §5.1) `sql` only: the driver and its connection settings. The
+   * password is the secret behind `auth.ref` (`auth` takes only `ref` for `sql`). `sqlite` sources come
+   * from `POST /apps/uploads` (a snapshot digest), not from a preview.
+   */
+  sql?: SqlSourceConfigBody;
+  /**
+   * (api-types 0.175.0) `sql` only: the views (and materialized views) a read may name, as
+   * `schema.view` (MySQL `database.view`). A view not listed is refused by the read policy.
+   */
+  viewsAllowed?: string[];
   /**
    * The secret VALUE this server's keychain entry will hold (wicked-crew#719). The preview is
    * probed with it and it is held with the preview; `POST /mcp/servers` writes it to the OS store
@@ -12453,6 +12501,30 @@ export interface McpServer {
   openapiUrl?: string | null;
   /** `rest` only: the operations that were picked; `null` = all. */
   operations?: string[] | null;
+  /** (api-types 0.175.0) `sql` only: driver and connection settings (`ca` shown as whether one is set). */
+  sql?: SqlSourceView;
+  /** (api-types 0.175.0) `sql` only: views a read may name. */
+  viewsAllowed?: string[];
+  /**
+   * (api-types 0.175.0, DES-APPS-001 §7.4) Postgres `sql` only: the per-source **Allow writes**
+   * switch, `false` on every new source. Only a human operator turns it on or off
+   * (`PUT /sources/:name/allow-writes`); turning it off withdraws every row-write grant on the
+   * source. It is not part of the connection descriptor: reads are unaffected.
+   */
+  allowWrites?: boolean;
+  /**
+   * (api-types 0.175.0) `sql`/`graphql`: the sha256 of the source's connection descriptor (driver,
+   * host, port, database, login, TLS mode, url, auth header, snapshot, confirmed ranges; never
+   * `allowWrites`). Queries, actions and grants bind to it.
+   */
+  descriptorHash?: string;
+  /**
+   * (api-types 0.174.0) `mcp-http` and `rest` only: the ranges confirmed for this server's
+   * connections. A server saved before 0.174.0 shows what crew re-derived for it: the IP literal or
+   * `localhost` it was registered at; a private host NAME is not re-derived, and its calls are
+   * refused until it is saved again with a range.
+   */
+  address?: McpAddressPolicy;
   authState: McpAuthState;
   enabled: boolean;
   health: McpHealth;
@@ -12534,7 +12606,17 @@ export interface McpPreviewResponse {
     auth: McpAuthConfig | null;
     openapiUrl?: string | null;
     operations?: string[] | null;
+    /** (api-types 0.174.0) `mcp-http` and `rest` only: the ranges this preview dialled under. */
+    address?: McpAddressPolicy;
+    /** (api-types 0.175.0) `sql` only. */
+    sql?: SqlSourceView;
+    viewsAllowed?: string[];
   };
+  /**
+   * (api-types 0.175.0, DES-APPS-001 §5.1) `sql`/`graphql` only: what the describe found —
+   * structure, never a value from a row — and, for Postgres, the login's privilege report.
+   */
+  source?: { catalog: SourceCatalog; privileges?: SourcePrivilegeReport };
   serverInfo: { name: string; version: string } | null;
   tools: McpPreviewTool[];
   diff: McpToolDiff | null;
@@ -12570,8 +12652,8 @@ export interface SaveMcpServerBody {
   /**
    * (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
+   * (the base URL matches none of the document's `servers`; since 0.174.0 a loopback or private
+   * host is confirmed as a range in the config's `address` instead); 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`.
@@ -12596,16 +12678,21 @@ export interface McpRestEgress {
   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. */
+  /**
+   * The host is a loopback or private address (since api-types 0.174.0 always one the preview's
+   * `address` confirmed: an unconfirmed one fails the preview, and an always-refused one, like
+   * link-local or CGNAT, can never be confirmed).
+   */
   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`.
+   * Since api-types 0.174.0 always `true`: a host that does not resolve fails the preview, because
+   * the dialer cannot check where it goes.
    */
   resolved: boolean;
   /**
-   * `!matches || privateAddress || !resolved`, unless this origin was already confirmed for this
-   * server by an earlier save: the save needs `allowOrigin`.
+   * `!matches`, unless this origin was already confirmed for this server by an earlier save: the
+   * save needs `allowOrigin`. (Before api-types 0.174.0 a private or unresolved host needed it too;
+   * addresses are now confirmed as ranges, in the config's `address`.)
    */
   confirmRequired: boolean;
 }
@@ -13012,6 +13099,248 @@ export interface McpUsageResponse {
   skipped: number;
 }
 
+// ── Apps data sources (DES-APPS-001 §5, §7.4, §7.5; api-types 0.175.0) ───────────────────────────
+
+/** `McpServerConfigBody.sql`: a network SQL source's settings. Secrets go in `auth.ref` only. */
+export interface SqlSourceConfigBody {
+  driver: 'postgres' | 'mysql';
+  host: string;
+  /** Default 5432 (Postgres), 3306 (MySQL). */
+  port?: number;
+  database: string;
+  /** The login. A read-only login is recommended; the privilege report says when it is not one. */
+  user: string;
+  /**
+   * `verify-full` (default; Postgres verify-full, MySQL VERIFY_IDENTITY: the certificate and the
+   * host name are verified). `disable` only to loopback, or a private range confirmed as plaintext
+   * in `address` (else the preview is a 409 `plaintext_refused`).
+   */
+  tls?: 'verify-full' | 'disable';
+  /** A CA certificate (PEM) when the server's is not signed by a public root. */
+  ca?: string;
+}
+
+/** A `sql` source's settings as answered (the CA as whether one is set). */
+export interface SqlSourceView {
+  driver: 'postgres' | 'mysql' | 'sqlite';
+  host: string | null;
+  port: number | null;
+  database: string | null;
+  user: string | null;
+  tls: 'verify-full' | 'disable';
+  ca: boolean;
+  /** `sqlite`: the snapshot's sha256. */
+  snapshot: string | null;
+}
+
+/** How a relation may be read: base tables; views only by name (`viewsAllowed`); foreign tables never. */
+export type SourceRelationKind = 'table' | 'partitioned' | 'view' | 'matview' | 'foreign';
+
+export interface SourceCatalogColumn {
+  name: string;
+  /** The source's own type text (`integer`, `character varying(80)`, `support.priority`). */
+  type: string;
+  nullable: boolean;
+  /** Enum literals the schema declares (Postgres enum, MySQL ENUM). Never a value read from a row. */
+  enumValues?: string[];
+}
+
+export interface SourceCatalogRelation {
+  /** Postgres schema, MySQL database; `null` for SQLite. */
+  schema: string | null;
+  name: string;
+  kind: SourceRelationKind;
+  /** The planner's estimate (SQLite: the snapshot's exact count); `null` = unknown. */
+  rowEstimate: number | null;
+  columns: SourceCatalogColumn[];
+  primaryKey: string[];
+  foreignKeys: Array<{ name: string; columns: string[]; references: { schema: string | null; table: string; columns: string[] } }>;
+  /** Postgres: row security enabled or forced. */
+  rowSecurity?: boolean;
+  /** (api-types 0.176.0) Postgres: row security FORCED (it applies to the table's owner too). */
+  rowSecurityForced?: boolean;
+}
+
+/** A `sql` source's catalog: structure only. */
+export interface SqlSourceCatalog {
+  dialect: 'postgres' | 'mysql' | 'sqlite';
+  database: string | null;
+  relations: SourceCatalogRelation[];
+  describedAt: string;
+}
+
+/** A `graphql` source's catalog: root fields and declared enums (from introspection). */
+export interface GraphqlSourceCatalog {
+  queries: Array<{ name: string; type: string; args: Array<{ name: string; type: string }> }>;
+  mutations: Array<{ name: string; type: string; args: Array<{ name: string; type: string }> }>;
+  enums: Array<{ name: string; values: string[] }>;
+  describedAt: string;
+}
+
+export type SourceCatalog = SqlSourceCatalog | GraphqlSourceCatalog;
+
+/** One declared Postgres row write, as the privilege report and the safety check take it (DES §7.4). */
+export interface SourceRowWrite {
+  schema: string;
+  table: string;
+  op: 'insert' | 'update' | 'delete';
+  /** The columns the write sets (an insert: every column of the table). */
+  set: string[];
+  /** Every primary-key column. */
+  key: string[];
+}
+
+/**
+ * The Postgres privilege report (DES §5.1 "Test", §7.4 "the writer login"): what the login can read
+ * and change, whether it is read-only, and per declared row write the EXACT `GRANT` statements still
+ * missing: `USAGE` on the schema, table-level `SELECT` (the returned row type reads the whole row;
+ * it covers the key and written columns), table-level `UPDATE` for every row write (the lock needs
+ * it), and `INSERT` or `DELETE` for those operations.
+ */
+export interface SourcePrivilegeReport {
+  login: string;
+  superuser: boolean;
+  /**
+   * Not a superuser, and no INSERT/UPDATE/DELETE/TRUNCATE (table or column level) on any visible
+   * table, view (an updatable view writes its table) or foreign table, nor UPDATE or USAGE
+   * (`nextval`) on a sequence.
+   */
+  readOnly: boolean;
+  tables: Array<{ schema: string; table: string; select: boolean; selectSomeColumns: boolean; insert: boolean; update: boolean; delete: boolean }>;
+  writes: Array<{ write: SourceRowWrite; missing: string[] }>;
+}
+
+/** `GET /sources/:name/catalog`, `POST /sources/:name/describe` (re-describe now). */
+export interface SourceCatalogResponse {
+  name: string;
+  kind: 'sql' | 'graphql' | 'crew';
+  catalog: SourceCatalog | CrewSourceCatalog;
+  privileges?: SourcePrivilegeReport;
+  descriptorHash: string | null;
+}
+
+/** `POST /sources/:name/privileges`. */
+export interface SourcePrivilegesBody {
+  writes?: SourceRowWrite[];
+}
+
+/** `POST /sources/:name/check` — the per-kind source check: policy, then prepare/describe, never execute. */
+export interface SourceCheckBody {
+  /** SQL text (Postgres `$1…`, MySQL and SQLite `?`), or a GraphQL document. */
+  text: string;
+}
+
+export type SourceCheckResponse =
+  | { ok: true; columns: Array<{ name: string; type: string }>; params: string[]; relations: string[] }
+  | {
+      ok: false;
+      /**
+       * Why the query was refused. Two kinds of class:
+       *
+       * - The read policy, before anything reaches the source: `not_select`, `function`, `cast`,
+       *   `operator`, `relation`, `view`, `unqualified`, `qualified_name`, `column`, `recursive`,
+       *   `locking`, `into`, `statements`, `lexical`, `syntax` (NATURAL JOIN among them), `parse`,
+       *   `params`, `too_long`; GraphQL `operations`, `not_query`, `invalid`, `schema` (the described
+       *   schema does not validate: describe the source again).
+       * - The source, after crew connected and asked it to prepare the text (never to execute it):
+       *   `prepare` (the source refused to prepare it; its own words reach a human only, an agent gets
+       *   the SQLSTATE), `authorizer` (SQLite's authorizer denied it), `refused` (a relation changed at
+       *   the source since the describe: describe it again), or a dialer refusal code.
+       */
+      code: string;
+      detail: string;
+    };
+
+/** `POST /sources/:name/safety` — the Postgres table safety check (DES §7.4 rev 11). */
+export interface SourceSafetyBody {
+  schema: string;
+  table: string;
+  /** A declared row write to check as well (key = the whole primary key; FK enforcement refused). */
+  write?: { op: 'insert' | 'update' | 'delete'; set: string[]; key: string[] };
+}
+
+export interface SourceSafetyResponse {
+  table: { schema: string; name: string };
+  safe: boolean;
+  /**
+   * Each reason a v1 row write may not touch the table, in words naming the object (`code`:
+   * `not_a_table`, `partitioned`, `partition`, `access_method`, `inheritance_parent`,
+   * `inheritance_child`, `row_security`, `rule`, `user_trigger`, `internal_trigger_disabled`,
+   * `cascading_key`, `fk_operator`, `column_type`, `user_cast`, `generated_column`,
+   * `exclusion_constraint`, `check_expression`, `check_dependency`, `index_expression`,
+   * `index_partial`, `index_access_method`, `index_opclass`, `statistics_expression`, `depend_net`,
+   * `no_primary_key`, `table_not_found`; for a declared write also `key_mismatch`, `key_write`,
+   * `unknown_column`, `nothing_set`, `fk_enforcement`, `insert_columns`, `written_type`).
+   */
+  reasons: Array<{ code: string; detail: string }>;
+  /** sha256 over the full definitions read; a grant binds to it (K2b). */
+  fingerprint: string;
+}
+
+/** `PUT /sources/:name/allow-writes` — human operator only (403 `writes_switch_human_only`). */
+export interface SourceAllowWritesBody {
+  allowed: boolean;
+}
+
+export interface SourceAllowWritesResponse {
+  name: string;
+  allowWrites: boolean;
+  /** Row-write grants withdrawn by turning the switch off (0 when turning it on). */
+  withdrawnGrants: number;
+}
+
+/**
+ * `POST /sources/:name/test-call` (G6) — human operator only. Without `confirm` it sends NOTHING and
+ * answers the exact request it would send and its `requestHash`; with `confirm` equal to that hash it
+ * sends exactly that one request. Reads only: a REST GET/HEAD operation, a GraphQL `query`, an MCP
+ * tool whose class is `read`. Audited `apps.source.test_call`.
+ */
+export interface SourceTestCallBody {
+  /** REST: the tool (operation) name; MCP: the tool name; GraphQL: the query document. */
+  target: string;
+  args?: Record<string, unknown>;
+  confirm?: string;
+}
+
+export interface SourceTestCallRequest {
+  kind: 'rest' | 'graphql' | 'mcp';
+  /** REST/GraphQL: `GET https://api…/v1/tickets?page=1`; MCP: the tool name. */
+  summary: string;
+  method?: string;
+  url?: string;
+  /** Header NAMES only; the auth header's value is never shown. */
+  headers?: string[];
+  body?: unknown;
+  tool?: string;
+  args?: Record<string, unknown>;
+}
+
+export type SourceTestCallResponse =
+  | { sent: false; request: SourceTestCallRequest; requestHash: string }
+  | { sent: true; request: SourceTestCallRequest; ok: boolean; status: number | null; result: unknown; truncated: boolean };
+
+/** `POST /apps/uploads?name=<source>&filename=<file>` (body: the file's bytes) — a file becomes a `sql`/`sqlite` source. */
+export interface SourceUploadResponse {
+  source: McpServer;
+  snapshot: { digest: string; bytes: number; kind: 'csv' | 'xlsx' | 'sqlite' };
+  /** The table a CSV/XLSX became; `null` for a `.sqlite` file. */
+  table: string | null;
+  /**
+   * CSV/XLSX: whether the first row was taken as the header, and the column names. Only a HUMAN's
+   * upload takes one (detected, or `header=yes`); a first row that looks like data, or holds values
+   * such as an email, becomes `col_1…`, and an agent's upload always gets `col_1…` names.
+   */
+  header: { detected: boolean; columns: string[] } | null;
+  /** The first 20 rows, answered to a HUMAN actor only (an agent gets `[]`). */
+  sample: string[][];
+  catalog: SqlSourceCatalog;
+}
+
+/** The built-in `crew` source (DES §5.1): allowlisted GET routes, read in-process as the viewing actor. */
+export interface CrewSourceCatalog {
+  routes: Array<{ path: string; responseType: string; params: string[] }>;
+}
+
 // ── Decision capture (DES-decision-capture §4.2.1 / §4.6; DC-S4a, api-types 0.80.0) ──────────────
 
 /** The laya codebook's decision types. `none` is crew's label for "no decision". */
@@ -13834,7 +14163,18 @@ export interface DismissRecommendationResponse {
 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> };
+  | {
+      url: string;
+      transport?: 'streamable-http' | 'sse';
+      headers?: Record<string, string>;
+      /**
+       * (api-types 0.174.0, DES-APPS-001 §5.2) Every request goes through crew's one dialer. A typed
+       * loopback IP literal or `localhost` is reachable as typed (http allowed); a typed private IP
+       * literal is reachable over https, and over http only with `plaintext: true` here; a private
+       * host NAME needs a range here (a 400 for a range outside loopback/private).
+       */
+      address?: McpAddressPolicy;
+    };
 
 /** `POST /mcp-inspect/sessions` */
 export interface McpInspectStartBody {
@@ -14738,6 +15078,38 @@ export interface AppLockAction {
   contractHash: string;
 }
 
+/**
+ * (api-types 0.176.0, DES-APPS-001 K2b) One argument of a `.json` query text: a declared parameter of the
+ * query, or a literal fixed by the app (a string of at most 1,000 characters). Viewer values are declared on
+ * the query's parameters (`from`), never here.
+ */
+export type AppQueryArg = { kind: 'param'; name: string } | { kind: 'literal'; value: string | number | boolean | null };
+
+/**
+ * (api-types 0.176.0) `queries/<id>.json` of a `rest` or `mcp` query: one registry tool the person accepted
+ * as a read on the source sheet, and its arguments (at most 50, each one of the tool's input properties).
+ */
+export interface AppToolQueryText {
+  tool: string;
+  args: Record<string, AppQueryArg>;
+}
+
+/**
+ * (api-types 0.176.0) `queries/<id>.json` of a `crew` query: one route the built-in crew source reads
+ * (`SourceCatalogResponse` of `crew` lists them, e.g. `/runs/:id`), every `:param` of it in `params`, and
+ * query-string values in `query`.
+ */
+export interface AppCrewQueryText {
+  route: string;
+  params: Record<string, AppQueryArg>;
+  query: Record<string, AppQueryArg>;
+}
+
+// How a query's text binds its parameters (api-types 0.176.0): SQL `$n` (Postgres) and the n-th `?` (MySQL,
+// SQLite) bind the n-th parameter in the order `params.properties` declares them, and every declared
+// parameter is used; GraphQL variables are the parameters by name; `.json` texts name them in `AppQueryArg`s.
+// The order is part of the query's contract, so reordering the parameters is checked again.
+
 // ── Apps: the store and its routes (DES §6.4, §7.6, §9.1) ────────────────────────────────────────
 
 /**
@@ -14945,7 +15317,13 @@ export interface AppQueryBody {
 /** One cell: values are rendered as text by the runtime. */
 export type AppCell = string | number | boolean | null;
 
-/** `POST /apps/:app/query` 200 (DES §7.2). `rows` are aligned with `columns`. */
+/**
+ * `POST /apps/:app/query` 200 (DES §7.2). `rows` are aligned with `columns`, which are exactly the query's
+ * declared output (api-types 0.177.0: values coerced to their declared types; `integer` and `number` cells
+ * are JS numbers within ±2^53; `date` is `YYYY-MM-DD`, `datetime` ISO 8601). `truncated`: a cap cut the
+ * answer (5,000 rows, 10 MB, a cell past 64 KB cut). `hasMore`: the more path says another page exists.
+ * `ms`: this request's time. Identical reads within the query's cache life share one answer.
+ */
 export interface AppQueryResponse {
   columns: AppOutputColumn[];
   rows: AppCell[][];
@@ -14956,6 +15334,151 @@ export interface AppQueryResponse {
   cachedAt: number | null;
 }
 
+// ── Apps: the write path (api-types 0.178.0, DES-APPS-001 §7.3, §7.4, §9.4, slice K2b) ─────────────────
+
+/** Where a value on an action card comes from (DES §7.3: "your sign-in", "fixed by the app", "filled by studio: now"). */
+export type AppActionValueSource = 'param' | 'app' | 'viewer' | 'crew';
+
+/** One value on a card: the column or argument, the value as it will be sent, and where it comes from. */
+export interface AppActionCardValue {
+  name: string;
+  /** A list argument shows its items (an array parameter, the viewer's groups). */
+  value: string | number | boolean | null | Array<string | number | boolean>;
+  from: AppActionValueSource;
+  /** The words for `from`: "you entered it", "fixed by the app", "your sign-in", "filled by studio: now". */
+  label: string;
+}
+
+/**
+ * The card crew generates from the RESOLVED operation (DES §7.3) and the host draws outside the app's
+ * frame: the only per-run consent. Every value is on it, literals included.
+ */
+export type AppActionCard =
+  | {
+      kind: 'api';
+      app: string;
+      action: string;
+      source: string;
+      /** The source's kind: `rest`, `mcp-http`, `mcp-stdio` or `graphql`. */
+      sourceKind: string;
+      /** `POST /v1/tickets/4821/assign`, `mutation assign`, or `tool assign_ticket`. */
+      operation: string;
+      args: AppActionCardValue[];
+      /** The request as it will be sent (method and URL and body, the GraphQL document and variables, or the tool call). */
+      request: string;
+      /** The action's description, labelled "The app says" by the host. */
+      appSays?: string;
+    }
+  | {
+      kind: 'row-write';
+      app: string;
+      action: string;
+      source: string;
+      /** The login the write runs as. */
+      login: string;
+      verb: 'INSERT' | 'UPDATE' | 'DELETE';
+      /** Schema-qualified: `support.tickets`. */
+      table: string;
+      /** Every column it sets (an insert: every column of the table), with its value. */
+      columns: AppActionCardValue[];
+      /** The key (`id = 4821`). */
+      key: AppActionCardValue[];
+      /** "exactly 1 row, verified". */
+      rows: string;
+      /** "plain table: no triggers, rules, inheritance or row security; checked just now". */
+      checks: string;
+      /** The statement as it will run (values are its `$n` parameters, listed above). */
+      statement: string;
+      appSays?: string;
+    };
+
+/** `POST /apps/:app/actions/:id/prepare` (HUMAN operator). `params` are the action's declared, non-viewer parameters. */
+export interface AppActionPrepareBody {
+  version: number | string;
+  params?: Record<string, unknown>;
+}
+
+/** `POST /apps/:app/actions/:id/prepare` 200: the record to run within 2 minutes, and its card. */
+export interface AppActionPrepareResponse {
+  record: string;
+  card: AppActionCard;
+  /** Unix millis. */
+  expiresAt: number;
+}
+
+/** `POST /apps/:app/actions/:id/run` (HUMAN operator, the person who prepared it). */
+export interface AppActionRunBody {
+  record: string;
+}
+
+/**
+ * An action record's states (DES §7.3): `prepared → running → succeeded | failed | unknown`. `running` is the
+ * linearization point (persisted before the upstream call); `unknown` = the outcome could not be known (the
+ * daemon restarted during the call, or the call was sent and no answer came). Nothing is ever re-run.
+ */
+export type AppActionState = 'prepared' | 'running' | 'succeeded' | 'failed' | 'unknown';
+
+/** `POST /apps/:app/actions/:id/run` 200: how it ended. */
+export interface AppActionRunResponse {
+  record: string;
+  state: 'succeeded' | 'failed' | 'unknown';
+  /** Why it failed or is unknown, in crew's words. */
+  reason?: string;
+  /** A row write: `{ table, op, key }`; an API action: the answer, scrubbed and cut at 64 KB. */
+  result?: unknown;
+}
+
+/** `GET /apps/:app/actions/records/:id` 200 (the person who prepared it): answers a lost response. */
+export interface AppActionRecordView {
+  id: string;
+  app: string;
+  action: string;
+  version: number | null;
+  tree: string;
+  state: AppActionState;
+  reason?: string;
+  result?: unknown;
+  card: AppActionCard;
+  createdAt: number;
+  expiresAt: number;
+  endedAt?: number;
+}
+
+/** `POST /apps/:app/actions/:id/grant` (HUMAN operator): grant the action as it is in this version. */
+export interface AppActionGrantBody {
+  version: number | string;
+}
+
+/**
+ * A grant (DES §9.4): keyed by app and action, bound to the action hash, the contract hash (a row write's
+ * holds the table's safety fingerprint) and the source descriptor; any change withdraws it. Turning a
+ * source's Allow writes off withdraws its row-write grants.
+ */
+export interface AppActionGrant {
+  app: string;
+  action: string;
+  kind: 'api' | 'row-write';
+  source: string;
+  actionHash: string;
+  contractHash: string;
+  descriptorHash: string;
+  /** A row write: the table safety check's fingerprint at grant. */
+  fingerprint?: string;
+  grantedBy: Actor;
+  /** Unix millis. */
+  grantedAt: number;
+}
+
+/** `POST …/grant` 200 and `GET …/grant` 200 (observer). */
+export interface AppActionGrantResponse {
+  grant: AppActionGrant;
+}
+
+/** `DELETE …/grant` 200: whether a grant was there. */
+export interface AppActionRevokeResponse {
+  revoked: boolean;
+}
+
 /** One reason a check refused a tree. `path` is a JSON path into `apps.json`, or a repo path. */
 export interface AppCheckFinding {
   stage: 'spec' | 'files' | 'policy' | 'source';
@@ -14979,6 +15502,26 @@ export interface AppCheckFinding {
  *  - 429 `rate_limited` (with `retryAfterMs`: a query queue or a per-viewer rate is full, DES §7.5);
  *  - 501 `not_implemented` (a route a later slice serves; nothing happened);
  *  - 503 `apps_unavailable`.
+ *
+ * (api-types 0.178.0, K2b) The action routes also answer: 409 `read_only` (`APPS_READ_ONLY` is set: no
+ * write at all), `not_granted` (no grant for the action as it is now; a stale grant is withdrawn and says
+ * so), `writes_off` (the source's Allow writes switch is off), `table_changed` (the row write's table no
+ * longer passes the safety check, or its fingerprint differs from the grant's: the grant is withdrawn),
+ * `value_does_not_fit` (a value its column would change, P28), `record_used` (the record already ran or is
+ * running: nothing is re-run), `record_expired`, `missing_grants` (granting a row write whose login lacks a
+ * privilege the write needs: the message lists the exact `GRANT` statements); 404 `unknown_action`,
+ * `unknown_record`.
+ *
+ * (api-types 0.177.0, K2b) `POST /apps/:app/query` also answers: 400 `bad_params` (a parameter that is not
+ * declared, does not satisfy its schema, is required and missing, or is viewer-bound and was sent); 403
+ * `human_only` for an agent or plugin actor (an app's rows reach a person, never a model); 409
+ * `viewer_unavailable` (a viewer-bound value crew does not know, e.g. no git `user.email` locally, or groups
+ * in local preview), `contract_changed` (the source's connection, or what the query reads there, changed
+ * since this version was checked: check it again), `query_refused` (the read policy or the source's live
+ * relation checks refuse it now); 422 `result_invalid` (a value does not fit its declared column: the
+ * message names the column and row, never the value); 502 `source_failed` / `source_unavailable` (the
+ * source answered an error or could not be reached: a class and a SQLSTATE, never the source's words); 504
+ * `source_timeout` (stopped at the 10 s deadline, at the source).
  */
 export interface AppErrorBody {
   code:
@@ -15004,7 +15547,25 @@ export interface AppErrorBody {
     | 'not_this_turn'
     | 'not_checked'
     | 'reviewer_not_distinct'
-    | 'apps_unavailable';
+    | 'apps_unavailable'
+    | 'bad_params'
+    | 'viewer_unavailable'
+    | 'contract_changed'
+    | 'query_refused'
+    | 'result_invalid'
+    | 'source_failed'
+    | 'source_unavailable'
+    | 'source_timeout'
+    | 'read_only'
+    | 'not_granted'
+    | 'writes_off'
+    | 'table_changed'
+    | 'value_does_not_fit'
+    | 'record_used'
+    | 'record_expired'
+    | 'unknown_action'
+    | 'unknown_record'
+    | 'missing_grants';
   error: string;
   /** `rate_limited`: when to try again (also sent as `Retry-After`). */
   retryAfterMs?: number;
@@ -15042,9 +15603,15 @@ export type AppsCheckResponse =
  * serves that route for real rather than answering `501`.
  */
 export interface AppsCapabilities {
-  /** `POST /apps/:app/query` runs queries (until then it checks the receipt, then answers `501`). */
+  /**
+   * `POST /apps/:app/query` runs queries (until then it checks the receipt, then answers `501`). True since
+   * api-types 0.177.0 (K2b, the executor).
+   */
   query: boolean;
-  /** `POST /apps/:app/actions/:id/prepare|run|grant`, `GET …/actions/records/:id`. */
+  /**
+   * `POST /apps/:app/actions/:id/prepare|run|grant`, `GET|DELETE …/grant`, `GET …/actions/records/:id`. True
+   * since api-types 0.178.0 (K2b, the write path: API actions and Postgres row writes).
+   */
   actions: boolean;
   /** `POST /apps/:app/turns` launches `apps-turn` runs. */
   turns: boolean;
@@ -15052,7 +15619,10 @@ export interface AppsCapabilities {
   publish: boolean;
   /** `POST /apps/uploads`. */
   uploads: boolean;
-  /** The read policy and the per-kind source check run, so a change to queries or actions can land. */
+  /**
+   * The read policy and the per-kind source check run, so a change to queries or actions can land (true since
+   * api-types 0.176.0 on a daemon with a connector registry: crew's source stage, DES §9.2 step 3).
+   */
   sourceCheck: boolean;
 }
 

package/package.json

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