@qontinui/shared-types 0.12.1 → 0.14.0

package/package.json

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

package/src/generated/AgentTextUnit.d.ts

@@ -0,0 +1,152 @@
+/* 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 unit of the agent text corpus: a `(kind, name)` addressed bundle of
+ * text files, owned either by an organization or by the fleet-default layer.
+ *
+ * The content is **untrusted remote content** from the runner's point of
+ * view — it is markdown and shell text rather than compiled code, but it is
+ * instructions to an agent and it becomes files on a fleet device. Consumers
+ * fail soft (a malformed unit falls back to the next rung of the resolution
+ * chain and warns) and never fetch cross-org.
+ *
+ * This mirrors qontinui-web's `AgentTextUnitResponse` field for field, plus
+ * the two forward provenance fields Phase 5 fills in.
+ */
+export interface AgentTextUnit {
+  /**
+   * Canonical digest over the whole [`files`](Self::files) map, from
+   * [`agent_text_unit_files_checksum`]. `None` on a row written before a
+   * checksum was computed.
+   *
+   * This is **not** [`crate::agent_commands::agent_command_checksum`]: that
+   * one digests a single body and is what the legacy `/agent-commands` wire
+   * still carries. The two deliberately disagree even for a one-entry map.
+   */
+  checksum?: string | null;
+  /**
+   * ISO 8601 (RFC 3339) creation timestamp.
+   */
+  created_at: string;
+  /**
+   * User who last authored this unit. **Attribution only** — it does not
+   * scope visibility; [`organization_id`](Self::organization_id) does.
+   */
+  created_by_user_id?: string | null;
+  /**
+   * Head of the version chain — the `version_number` of the
+   * [`AgentTextUnitVersion`] whose content this unit currently serves.
+   * Starts at 1 and only ever increases (a revert bumps it).
+   */
+  current_version: number;
+  /**
+   * The key of [`files`](Self::files) holding this unit's primary text,
+   * derived server-side from `(kind, name)` — see
+   * [`agent_text_unit_entrypoint`]. Read-only: it is recomputed on every
+   * response and ignored on write.
+   */
+  entrypoint: string;
+  /**
+   * The unit's current content: **relative path → text**. A command carries
+   * one entry; a skill carries `SKILL.md` plus siblings.
+   *
+   * Carried inline on the unit, matching the landed
+   * `AgentTextUnitResponse`. Note the cost that buys the convenience: a
+   * whole-corpus list is ~88 units / ~1.8 MB, and the runner fetches it on
+   * the spawn critical path under a 4 s budget, so a caller that only needs
+   * to know whether its cache is current should compare
+   * [`checksum`](Self::checksum) rather than re-reading these bytes.
+   */
+  files: {
+    [k: string]: string;
+  };
+  /**
+   * Unit id (UUID v4 string).
+   */
+  id: string;
+  /**
+   * Whether the harness may offer this unit as an invocable slash command.
+   *
+   * `false` means "carried by the corpus, never invocable": the
+   * underscore-prefixed units (`_gate-registration`, `_loop-control`) are
+   * copy-source specs that other units paste from, and `.claude/commands/`
+   * has no include mechanism, so they must be *present on disk* without
+   * appearing as `/_gate-registration`. Absent means `true`.
+   *
+   * Storage enforces the pairing with a CHECK (`left(name,1) <> '_' OR
+   * is_invocable = false`); [`validate_agent_text_unit_invocability`] is the
+   * same rule at this boundary.
+   * Always written on the wire, matching the landed `AgentTextUnitResponse`
+   * (which emits it unconditionally). `#[serde(default)]` covers reading an
+   * older payload that predates the field; the `#[schemars(default)]` twin
+   * is what puts `true` — rather than `null` — into the generated Python and
+   * TypeScript bindings, so a consumer that sees the field absent defaults
+   * it the same way Rust does.
+   */
+  is_invocable: boolean;
+  /**
+   * Whether this unit is visible to the whole organization rather than only
+   * its author. Absent means `false`.
+   */
+  is_shared: boolean;
+  /**
+   * What sort of unit this is. Open discriminator — see
+   * [`AgentTextUnitKind`].
+   */
+  kind: string;
+  /**
+   * The unit slug, e.g. `vet-plan` or `coord-revive`. It is the filename
+   * stem (single-file kinds) or the directory name (directory kinds) under
+   * `.claude/<subdir>/`, so it is a write-boundary value — validate it with
+   * [`validate_agent_text_unit_name`] before persisting.
+   */
+  name: string;
+  /**
+   * Owning organization (`auth.organizations.id`).
+   *
+   * **`None` is meaningful**: it is the *fleet-default* layer, resolved
+   * after an account override and before the runner's embedded default. It
+   * is also what an organization deletion leaves behind (`ondelete SET
+   * NULL`), which is why storage keys the NULL bucket with its own partial
+   * unique index — see the module docs.
+   */
+  organization_id?: string | null;
+  /**
+   * Which resolution layer this row was served from —
+   * [`AGENT_TEXT_UNIT_SOURCE_USER`] or [`AGENT_TEXT_UNIT_SOURCE_FLEET`].
+   * Server-derived, defaults to `user`.
+   *
+   * ⚠️ **Unrelated to [`source_path`](Self::source_path) /
+   * [`source_commit`](Self::source_commit) despite the shared prefix.** This
+   * field names the *layer the row came from*; those two name the *config
+   * repo the text was imported from*. Adjacent names, different concepts.
+   */
+  source: string;
+  /**
+   * Import provenance: the commit of the source repo (full 40-char SHA).
+   * `None` for a console-authored unit, or for an import from a dirty tree
+   * where no commit honestly describes the bytes.
+   */
+  source_commit?: string | null;
+  /**
+   * Import provenance: the repo-relative path this unit's text came from,
+   * e.g. `.claude/skills/coord-revive/`. `None` for a unit authored directly
+   * in the console.
+   *
+   * Recorded per unit at import so the console can show an operator whether
+   * a unit still matches its source. The path is **repo-relative on
+   * purpose** — an absolute one would pin a build machine's layout into
+   * account data.
+   */
+  source_path?: string | null;
+  /**
+   * ISO 8601 (RFC 3339) last-modification timestamp.
+   */
+  updated_at: string;
+  [k: string]: unknown;
+}

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/AgentTextUnitError.d.ts

@@ -0,0 +1,82 @@
+/* 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`.
+ */
+
+/**
+ * Failure modes for agent text units. Mirrors the tagged-enum shape of
+ * [`crate::apps::AppError`] and [`crate::agent_commands::AgentCommandError`],
+ * so the qontinui-web layer surfaces a rejected unit the same way it surfaces
+ * a rejected app registration.
+ *
+ * One variant per raise site in qontinui-web's `AgentTextUnitValidationError`,
+ * so a Rust caller can render exactly the refusal the store would give.
+ */
+export type AgentTextUnitError =
+  | {
+      name: string;
+      reason: "invalid-name";
+      [k: string]: unknown;
+    }
+  | {
+      name: string;
+      reason: "reserved-name";
+      [k: string]: unknown;
+    }
+  | {
+      kind: string;
+      reason: "invalid-kind";
+      [k: string]: unknown;
+    }
+  | {
+      path: string;
+      reason: "invalid-file-path";
+      [k: string]: unknown;
+    }
+  | {
+      path: string;
+      reason: "reserved-file-path";
+      [k: string]: unknown;
+    }
+  | {
+      reason: "empty-file-set";
+      [k: string]: unknown;
+    }
+  | {
+      count: number;
+      max: number;
+      reason: "too-many-files";
+      [k: string]: unknown;
+    }
+  | {
+      path: string;
+      reason: "blank-file";
+      [k: string]: unknown;
+    }
+  | {
+      bytes: number;
+      max: number;
+      path: string;
+      reason: "file-too-large";
+      [k: string]: unknown;
+    }
+  | {
+      bytes: number;
+      max: number;
+      reason: "unit-too-large";
+      [k: string]: unknown;
+    }
+  | {
+      entrypoint: string;
+      kind: string;
+      name: string;
+      reason: "missing-entrypoint";
+      [k: string]: unknown;
+    }
+  | {
+      name: string;
+      reason: "underscore-not-invocable";
+      [k: string]: unknown;
+    };

package/src/generated/AgentTextUnitFile.d.ts

@@ -0,0 +1,33 @@
+/* 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 `relative path → text` entry of a `files` map, as a standalone record.
+ *
+ * The map is the storage and wire form (it is one JSONB column, and it makes
+ * "no duplicate paths" structural rather than validated). This type is the
+ * **entry** form: what a per-file API operation addresses, what a per-file
+ * validation failure names, and what a provisioner iterates. Convert with
+ * [`from_map`](Self::from_map) / [`into_map`](Self::into_map).
+ */
+export interface AgentTextUnitFile {
+  /**
+   * Path relative to the unit's own directory, `/`-separated, e.g.
+   * `SKILL.md` or `coord-revive.sh`. Validated by
+   * [`validate_agent_text_unit_file_path`].
+   */
+  path: string;
+  /**
+   * The file's full text. Written verbatim (modulo the provisioner's own
+   * line-ending handling); never given an executable bit, because scripts
+   * in this corpus are invoked as `bash <path>` and Windows has no exec bit
+   * anyway. "Account-supplied text written to disk" must not become
+   * "account-supplied program registered with the OS".
+   */
+  text: string;
+  [k: string]: unknown;
+}

package/src/generated/AgentTextUnitVersion.d.ts

@@ -0,0 +1,72 @@
+/* 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 immutable entry in an [`AgentTextUnit`]'s append-only version chain.
+ *
+ * Rows are **only ever inserted**. An edit appends the next `version_number`;
+ * a revert appends a new version whose `files` are copied from an older one
+ * and whose [`restored_from`](Self::restored_from) names that older version.
+ * Nothing in the chain is updated or deleted, so the chain is the complete
+ * edit history and "revert" is itself a recorded edit.
+ */
+export interface AgentTextUnitVersion {
+  /**
+   * The [`AgentTextUnit`] this version belongs to. Deleting the unit
+   * cascades to its versions.
+   */
+  agent_text_unit_id: string;
+  /**
+   * Free-text note describing what changed, supplied by the editor. A
+   * revert writes a generated one (e.g. `"Restored from version 2"`).
+   */
+  change_description?: string | null;
+  /**
+   * Content hash of [`files`](Self::files), from
+   * [`agent_text_unit_files_checksum`]. Equal checksums on two versions mean
+   * the content is identical, which is what makes the Phase 5 re-import
+   * idempotent — it is the field "did the text actually change?" is read
+   * off. `None` on a row written before a checksum was computed.
+   */
+  checksum?: string | null;
+  /**
+   * ISO 8601 (RFC 3339) creation timestamp. Versions are immutable, so
+   * there is deliberately no `updated_at`.
+   */
+  created_at: string;
+  /**
+   * User who authored this version. Attribution only.
+   */
+  created_by_user_id?: string | null;
+  /**
+   * The unit's whole content as of this version: **relative path → text**.
+   *
+   * Every key must satisfy [`validate_agent_text_unit_file_path`]; the map
+   * must be non-empty and must contain the unit's
+   * [`agent_text_unit_entrypoint`].
+   */
+  files: {
+    [k: string]: string;
+  };
+  /**
+   * Version-row id (UUID v4 string).
+   */
+  id: string;
+  /**
+   * Provenance for a revert: the `version_number` this version's content
+   * was copied from. `None` for an ordinary edit.
+   */
+  restored_from?: number | null;
+  /**
+   * Monotonic version number within this unit, starting at 1. Unique per
+   * `(agent_text_unit_id, version_number)`; the DB constraint — not
+   * application code — is what rejects a duplicate under concurrent
+   * appends.
+   */
+  version_number: number;
+  [k: string]: unknown;
+}

package/src/generated/index.ts

@@ -21,6 +21,11 @@ export type { ActiveStatesResult } from './ActiveStatesResult';
 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';
 export type { AgenticPhaseOutput } from './AgenticPhaseOutput';
 export type { AgenticStatus } from './AgenticStatus';
 export type { AiWorkflow } from './AiWorkflow';