@qontinui/shared-types 0.13.0 → 1.0.0

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@qontinui/shared-types",
-  "version": "0.13.0",
+  "version": "1.0.0",
   "description": "Shared TypeScript types for the Qontinui ecosystem",
   "type": "module",
   "main": "./dist/index.js",

package/src/generated/AgentTextUnitDefault.d.ts

@@ -0,0 +1,110 @@
+/* eslint-disable */
+/**
+ * This file was automatically generated.
+ * DO NOT MODIFY IT BY HAND. Regenerate with `just generate-types` or
+ * `qontinui-runner/src-tauri/scripts/generate_types.sh`.
+ */
+
+/**
+ * One embedded default as the **runner binary** ships it, on its way to the
+ * account so there is a baseline to diff an override against.
+ *
+ * ## Why this exists as a third layer
+ *
+ * [`AgentTextUnit`]'s resolution chain is
+ * `account override → fleet default → embedded default (runner binary)`, and
+ * the store holds rows for the first two only — the binary's copy has never
+ * had a row anywhere. That is the gap this type closes. A user who overrode
+ * `/implement-plan` can diff their versions against each other but not
+ * against what actually ships, and `ResetToDefaultDialog` cannot preview the
+ * text it is about to restore, because there is no baseline to put on the
+ * left-hand side.
+ *
+ * Plan `2026-08-31-runner-publishes-embedded-command-defaults`; the deferral
+ * it discharges is recorded in the code at qontinui-web's
+ * `settings/agent-commands/_components/VersionDiff.tsx`.
+ *
+ * ## What it is NOT
+ *
+ * * **Not an [`AgentTextUnit`].** There is no `id`, no version chain, and no
+ *   `is_shared` — a published default is content plus provenance, not a
+ *   corpus row with an edit history. It is the *input* to a row.
+ * * **Not fleet-scoped.** `organization_id` is deliberately absent from the
+ *   wire: the runner publishes with the operator's own user bearer, so the
+ *   server assigns the org from that credential. A client-supplied org — or
+ *   the fleet layer's `organization_id IS NULL` — would let any signed-in
+ *   user rewrite another tenant's baseline, or silently clobber an
+ *   operator's deliberate fleet default.
+ * * **Not authoritative for provisioning.** The runner keeps resolving
+ *   `fresh fetch → disk cache → embedded default`; this is a *display*
+ *   baseline. Publishing it must never put the network on the
+ *   out-of-the-box path.
+ *
+ * ## The checksum is the files-map digest, not the single-body one
+ *
+ * [`checksum`](Self::checksum) is [`agent_text_unit_files_checksum`] — the
+ * same digest [`AgentTextUnit::checksum`] and [`AgentTextUnitVersion`] carry,
+ * so a published default and the override it is diffed against are
+ * comparable. It is **not**
+ * [`crate::agent_commands::agent_command_checksum`], which digests a single
+ * body and is what the legacy `/agent-commands` wire still carries. Those two
+ * deliberately disagree even for a one-entry map, so a default digested with
+ * the wrong one would never compare equal to its override — an always-drifted
+ * baseline, which is strictly worse than the honest "baseline unavailable"
+ * state it would replace.
+ */
+export interface AgentTextUnitDefault {
+  /**
+   * Canonical digest over [`files`](Self::files), from
+   * [`agent_text_unit_files_checksum`].
+   *
+   * Required, unlike [`AgentTextUnit::checksum`] — that one is optional only
+   * to describe rows written before a checksum was computed, whereas a
+   * publish is always freshly computed. The receiving store **recomputes it
+   * and rejects a mismatch**: a client-asserted digest is not evidence.
+   * [`checksum_matches`](Self::checksum_matches) is that check.
+   */
+  checksum: string;
+  /**
+   * The embedded content: **relative path → text**. A command carries one
+   * entry; a skill carries `SKILL.md` plus siblings. Same arity-agnostic
+   * shape as [`AgentTextUnit::files`].
+   */
+  files: {
+    [k: string]: string;
+  };
+  /**
+   * What sort of unit this default is. The corpus is `kind`-discriminated,
+   * so the default layer must be too — otherwise a command and a skill of
+   * the same name collapse into one baseline.
+   */
+  kind: string;
+  /**
+   * The unit slug, e.g. `vet-plan`. Must satisfy the same
+   * [`validate_agent_text_unit_name`] rules as an override: a default that
+   * could not be named as an override could never be paired with one for a
+   * diff, which is the only thing it is for.
+   */
+  name: string;
+  /**
+   * ISO 8601 (RFC 3339) publish timestamp, matching this module's wire
+   * convention for [`AgentTextUnit::updated_at`] and
+   * [`AgentTextUnitVersion::created_at`].
+   */
+  published_at: string;
+  /**
+   * The runner version that published this body, e.g. `"0.4.12"`.
+   *
+   * Carried so the UI can label the baseline **"published by runner
+   * vX.Y.Z"** rather than "the default" — an org whose devices run
+   * different builds has no single default, and the label must not claim
+   * otherwise. It is also the monotonic guard's input: the store rejects a
+   * publish older than the version it already holds.
+   *
+   * That guard is a **mitigation, not a fix** — a genuine downgrade still
+   * wins and equal versions tie-break last-writer — so neither this field
+   * nor the UI built on it may describe the baseline as authoritative.
+   */
+  published_by_version: string;
+  [k: string]: unknown;
+}

package/src/generated/UIBridgeElement.d.ts

@@ -41,8 +41,55 @@ export interface UIBridgeElement {
   bbox?: ElementBbox | null;
   /**
    * Custom (application-defined) actions.
-   */
-  customActions?: string[] | null;
+   *
+   * **Objects, not names.** These used to be a bare `Vec<String>` of action
+   * names, which left an element-level custom action with nowhere to carry a
+   * safety class — so the walker had no way to tell a `refresh` from a
+   * `sendKeys` that writes raw bytes into a live agent PTY. Widening this to
+   * [`ElementActionInfo`] is what makes `effect` REACHABLE from an element;
+   * see that type's docs.
+   *
+   * Absent (`None`) means the element declares none. That is deliberately
+   * distinct from an empty list, which would mean "declared, and empty".
+   * ---
+   *
+   * **TRANSITIONAL: this field also accepts the legacy bare-NAME form on the
+   * way in.** `["sendKeys"]` deserializes as
+   * `[ElementActionInfo { id: "sendKeys", .. }]`, with every other field —
+   * `effect` included — left `None`, i.e. UNCLASSIFIED. See
+   * [`deserialize_custom_actions`].
+   *
+   * **Why a shim exists at all**, when this workspace's rule is
+   * delete-over-deprecate. The shape change spans three repos that cannot
+   * land atomically — this crate owns the type, `ui-bridge` emits, and
+   * `qontinui-runner` parses live SDK snapshots strictly
+   * (`spec-check/src/fetch.rs`, `spec_api/spec_check.rs`) while pinning a
+   * PUBLISHED SDK. Both two-party orderings leave a window in which the
+   * fleet is broken: land this crate first and the runner rejects the names
+   * the published SDK still emits; land the SDK first and it emits objects
+   * at a runner whose type is still `Vec<String>`. Only a tolerant READER
+   * removes the window, and there is one reader against nine emitters.
+   *
+   * This is NOT here to spare a caller a breaking change — that is never a
+   * reason in this workspace.
+   *
+   * **DELETE ME, and the trigger is observable rather than intentional:**
+   * once no emitter produces names — `ui-bridge`'s eight element
+   * projections plus `qontinui-runner`'s
+   * `src/services/background-observer-service.ts` — and the runner's SDK pin
+   * has moved past that release, remove [`deserialize_custom_actions`] and
+   * this attribute, and flip
+   * `ui_bridge_element_tolerates_legacy_name_custom_actions` into a test
+   * that asserts a bare string is REJECTED. Plan
+   * `2026-09-04-effect-calculus-joins-the-component-action-registry`,
+   * Design decision 4, step 5.
+   *
+   * The published SCHEMA is deliberately not widened to advertise the name
+   * form: the schema states the target contract, while the reader is
+   * transitionally lenient. A producer validating against the schema is
+   * correctly told that names are not the shape to emit.
+   */
+  customActions?: ElementActionInfo[] | null;
   /**
    * Unique element ID within the registry.
    */
@@ -94,3 +141,72 @@ export interface UIBridgeElement {
    */
   visible?: boolean | null;
 }
+/**
+ * Information about a single custom (application-defined) action exposed by a
+ * UI Bridge **element**.
+ *
+ * The element-level twin of [`ComponentActionInfo`], and deliberately the same
+ * field vocabulary so a consumer that walks both action planes reads one shape,
+ * not two. One field is NOT carried over: `path`. A component action has a
+ * resolved per-action invocation path because the SDK annotates one
+ * (`/control/component/<componentId>/action/<actionId>`); an element action has
+ * no analogue — every element action is invoked through the single
+ * `/control/element/<elementId>/action` route with the action name in the body.
+ * A field nothing would ever populate is dead schema surface, so it is absent
+ * rather than perpetually `null`.
+ *
+ * ## Why this is an object rather than a name
+ *
+ * It exists so `effect` has somewhere to live. A bare list of action NAMES is
+ * unannotatable: there is no slot on a name for a safety class, so an
+ * element-level custom action could not declare itself `destructive` however
+ * much its author wanted to. That is not hypothetical — the runner exposes
+ * element custom actions that write raw bytes into a live agent PTY, and some
+ * of them act on a pane with no visible view.
+ *
+ * The wire projection is widened FIRST and the annotation lands on top of it.
+ * The reverse order ships an UNREACHABLE annotation, which is worse than an
+ * absent one: the author believes the delete button is marked, and the walker
+ * walks it anyway.
+ */
+export interface ElementActionInfo {
+  /**
+   * Longer description of what the action does.
+   */
+  description?: string | null;
+  /**
+   * Safety class of this action: `read`, `write` or `destructive`.
+   *
+   * **A safety annotation, not a hint.** An autonomous walk MUST NOT fire an
+   * action annotated `destructive`; that is the same exclusion the IR already
+   * applies to `destructive` transitions when generating auto-regressions.
+   * Author-declared, because only the app author knows that a particular
+   * custom action sends the keystrokes that end a session.
+   *
+   * Absent means **unclassified, not safe** — an action nobody has judged
+   * must be treated as unknown rather than as `read`. `skip_serializing_if`
+   * keeps an un-annotated action ABSENT on the wire rather than defaulting to
+   * a class nobody chose.
+   */
+  effect?: ("read" | "write" | "destructive") | null;
+  /**
+   * Unique action identifier within the element — the key the action is
+   * registered under, and the name `/control/element/<id>/action` is called
+   * with.
+   */
+  id: string;
+  /**
+   * Human-readable label.
+   */
+  label?: string | null;
+  /**
+   * Free-form declaration of the action's parameters, author-supplied on the
+   * SDK side and surfaced verbatim. Conventionally a small JSON Schema
+   * subset, but the SDK does not constrain the shape, so it is carried
+   * through untyped — the same treatment `ElementActionRequest::params` and
+   * `ComponentActionInfo::param_schema` get.
+   */
+  paramSchema?: {
+    [k: string]: unknown;
+  };
+}

package/src/generated/index.ts

@@ -22,6 +22,7 @@ export type { AgentCommand } from './AgentCommand';
 export type { AgentCommandError } from './AgentCommandError';
 export type { AgentCommandVersion } from './AgentCommandVersion';
 export type { AgentTextUnit } from './AgentTextUnit';
+export type { AgentTextUnitDefault } from './AgentTextUnitDefault';
 export type { AgentTextUnitError } from './AgentTextUnitError';
 export type { AgentTextUnitFile } from './AgentTextUnitFile';
 export type { AgentTextUnitVersion } from './AgentTextUnitVersion';