@ai-matrx/agents 0.59.176 → 0.59.177

package/CHANGELOG.md

@@ -2,17 +2,24 @@
 
 ### Unreleased
 
+- **New `./versions` and `./versions/react` entries: an agent's saved versions — list, compare, restore — moved from the web app (2026-10-21).** `./versions` (pure): `listAgentVersions`, `readAgentVersionSnapshot`, `resolveAgentVersionId`, `promoteAgentVersion` (restore, `agx_promote_version`), `declareContractBreak` over the host's supabase client (`VersionsClient`); `compareAgentDefinitions`, `AGENT_DIFF_OPTIONS`, `promoteFailureMessage`, `computeVersionFetchTargets`, `enrichVersions`, `snapshotToComparable`. `./versions/react`: `AgentDiffViewer` (ports: `enrichment`, `refs` for model/tool identity refs), `buildAgentAdapterRegistry`, `VersionHistoryTimeline` (presentational: the host passes load state, the contract-break write, row actions). New dependency `@ai-matrx/diff`. Consumer action: the web imports these instead of its own copies; Matrx 2 shows them.
+
 - **`ContextRulesChip` closes its compact popover on the first Escape even when a focused control has an open tooltip.** The tooltip dismissal layer previously took that key and left the popover visible. Consumer action: none.
 
 - **`useAgentSummary` looks an agent up by server search once per id per catalog (2026-10-19, Board remount law).** An agent tile that woke or remounted searched (`agx_search`) three times each time when the search found nothing; a found, missing or in-flight id is now asked once per tab, and a lookup that failed is forgotten so the next mount asks again. Consumer action: none.
 
 - **`toolPriceText` returns null for a zero-cost tool instead of "Free" (2026-10-18, law 14: no "Free").** Positive hints still read "N pts". Consumer action: none (callers already handle null).
 
-## 0.59.176
+## 0.59.177
 
 UNVERIFIED: this release has no Unreleased entry and the source comparison could not be made (the caller supplied no source comparison). Whether source changed is unknown; consumer action is unknown.
 Check the package's gitHead on npm against this version's gitHead: `git diff <previous gitHead> <this gitHead> -- apps/shared/matrx-agents/src`.
 
+## 0.59.176
+
+Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff fd6c15b440 ca1c252bee -- apps/shared/matrx-agents/src`
+has no shipped-source changes outside tests, fixtures and docs). No consumer action required.
+
 ## 0.59.175
 
 Automatic changed-only republish (docs/metadata drift since the last published version; verified: `git diff a1c540b807 fd6c15b440 -- apps/shared/matrx-agents/src`

package/dist/content-transfer/index.cjs

@@ -703,7 +703,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.176 — no longer declared in
+   * @deprecated retiring since 0.59.177 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/index.js

@@ -680,7 +680,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.176 — no longer declared in
+   * @deprecated retiring since 0.59.177 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/react/index.cjs

@@ -656,7 +656,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.176 — no longer declared in
+   * @deprecated retiring since 0.59.177 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/content-transfer/react/index.js

@@ -628,7 +628,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.176 — no longer declared in
+   * @deprecated retiring since 0.59.177 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */

package/dist/mandates/index.cjs

@@ -47,9 +47,9 @@ module.exports = __toCommonJS(mandates_exports);
 
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "ca1c252beec48565c47288b33e1adbdffbd816a3",
+  aidreamRevision: "3265c56d02c86272ed921537d89ca14880b3ded3",
   generatorVersion: "1.0.0",
-  packageVersion: "0.59.176",
+  packageVersion: "0.59.177",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -666,7 +666,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.176 — no longer declared in
+   * @deprecated retiring since 0.59.177 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */
@@ -693,7 +693,7 @@ var MANDATE_KEYS = {
 var ALL_MANDATE_KEYS = Object.values(MANDATE_KEYS);
 var RETIRING_MANDATE_KEYS = {
   "brand_discovery.offering_roles": "0.59.0",
-  "coding_session.managed_translation_reference": "0.59.176",
+  "coding_session.managed_translation_reference": "0.59.177",
   "pdf.content_cleaner": "0.59.0",
   "sms.owner_beta": "0.59.0",
   "voice.owner_beta": "0.59.0"

package/dist/mandates/index.d.cts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   ca1c252beec48565c47288b33e1adbdffbd816a3
+ * aidream revision:   3265c56d02c86272ed921537d89ca14880b3ded3
  * generator version:  1.0.0
- * package version:    0.59.176
+ * package version:    0.59.177
  * active keys:        606
  * retiring keys:      5
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "ca1c252beec48565c47288b33e1adbdffbd816a3";
+    readonly aidreamRevision: "3265c56d02c86272ed921537d89ca14880b3ded3";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.59.176";
+    readonly packageVersion: "0.59.177";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -639,7 +639,7 @@ declare const MANDATE_KEYS: {
      */
     readonly brand_discovery__offering_roles: "brand_discovery.offering_roles";
     /**
-     * @deprecated retiring since 0.59.176 — no longer declared in
+     * @deprecated retiring since 0.59.177 — no longer declared in
      * aidream. It leaves this union once no snapshot within the last
      * 3 published versions still carries it as active.
      */
@@ -670,7 +670,7 @@ declare const ALL_MANDATE_KEYS: readonly MandateKey[];
 /** Keys still in the union but no longer declared (two-phase retire, phase 1). */
 declare const RETIRING_MANDATE_KEYS: {
     readonly "brand_discovery.offering_roles": "0.59.0";
-    readonly "coding_session.managed_translation_reference": "0.59.176";
+    readonly "coding_session.managed_translation_reference": "0.59.177";
     readonly "pdf.content_cleaner": "0.59.0";
     readonly "sms.owner_beta": "0.59.0";
     readonly "voice.owner_beta": "0.59.0";

package/dist/mandates/index.d.ts

@@ -6,9 +6,9 @@
  * from the IN-PROCESS mandate declarations — the same `declared_mandates()` the
  * boot sync writes to the database from. There is no hand list anywhere.
  *
- * aidream revision:   ca1c252beec48565c47288b33e1adbdffbd816a3
+ * aidream revision:   3265c56d02c86272ed921537d89ca14880b3ded3
  * generator version:  1.0.0
- * package version:    0.59.176
+ * package version:    0.59.177
  * active keys:        606
  * retiring keys:      5
  *
@@ -19,9 +19,9 @@
  */
 /** Where this module came from — surfaced so a report can name the exact build. */
 declare const MANDATE_KEYS_META: {
-    readonly aidreamRevision: "ca1c252beec48565c47288b33e1adbdffbd816a3";
+    readonly aidreamRevision: "3265c56d02c86272ed921537d89ca14880b3ded3";
     readonly generatorVersion: "1.0.0";
-    readonly packageVersion: "0.59.176";
+    readonly packageVersion: "0.59.177";
     readonly retireWindow: 3;
 };
 /** Every declared mandate key, by THE IDENTIFIER RULE. */
@@ -639,7 +639,7 @@ declare const MANDATE_KEYS: {
      */
     readonly brand_discovery__offering_roles: "brand_discovery.offering_roles";
     /**
-     * @deprecated retiring since 0.59.176 — no longer declared in
+     * @deprecated retiring since 0.59.177 — no longer declared in
      * aidream. It leaves this union once no snapshot within the last
      * 3 published versions still carries it as active.
      */
@@ -670,7 +670,7 @@ declare const ALL_MANDATE_KEYS: readonly MandateKey[];
 /** Keys still in the union but no longer declared (two-phase retire, phase 1). */
 declare const RETIRING_MANDATE_KEYS: {
     readonly "brand_discovery.offering_roles": "0.59.0";
-    readonly "coding_session.managed_translation_reference": "0.59.176";
+    readonly "coding_session.managed_translation_reference": "0.59.177";
     readonly "pdf.content_cleaner": "0.59.0";
     readonly "sms.owner_beta": "0.59.0";
     readonly "voice.owner_beta": "0.59.0";

package/dist/mandates/index.js

@@ -1,8 +1,8 @@
 // mandates/keys.generated.ts
 var MANDATE_KEYS_META = {
-  aidreamRevision: "ca1c252beec48565c47288b33e1adbdffbd816a3",
+  aidreamRevision: "3265c56d02c86272ed921537d89ca14880b3ded3",
   generatorVersion: "1.0.0",
-  packageVersion: "0.59.176",
+  packageVersion: "0.59.177",
   retireWindow: 3
 };
 var MANDATE_KEYS = {
@@ -619,7 +619,7 @@ var MANDATE_KEYS = {
    */
   brand_discovery__offering_roles: "brand_discovery.offering_roles",
   /**
-   * @deprecated retiring since 0.59.176 — no longer declared in
+   * @deprecated retiring since 0.59.177 — no longer declared in
    * aidream. It leaves this union once no snapshot within the last
    * 3 published versions still carries it as active.
    */
@@ -646,7 +646,7 @@ var MANDATE_KEYS = {
 var ALL_MANDATE_KEYS = Object.values(MANDATE_KEYS);
 var RETIRING_MANDATE_KEYS = {
   "brand_discovery.offering_roles": "0.59.0",
-  "coding_session.managed_translation_reference": "0.59.176",
+  "coding_session.managed_translation_reference": "0.59.177",
   "pdf.content_cleaner": "0.59.0",
   "sms.owner_beta": "0.59.0",
   "voice.owner_beta": "0.59.0"

package/dist/versions/index.cjs

@@ -0,0 +1,231 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+
+// versions/index.ts
+var versions_exports = {};
+__export(versions_exports, {
+  AGENT_DIFF_OPTIONS: () => AGENT_DIFF_OPTIONS,
+  AGENT_EXCLUDE_PATHS: () => AGENT_EXCLUDE_PATHS,
+  AGENT_IDENTITY_KEYS: () => AGENT_IDENTITY_KEYS,
+  AgentVersionsError: () => AgentVersionsError,
+  compareAgentDefinitions: () => compareAgentDefinitions,
+  computeVersionFetchTargets: () => computeVersionFetchTargets,
+  declareContractBreak: () => declareContractBreak,
+  enrichVersions: () => enrichVersions,
+  listAgentVersions: () => listAgentVersions,
+  promoteAgentVersion: () => promoteAgentVersion,
+  promoteFailureMessage: () => promoteFailureMessage,
+  readAgentVersionSnapshot: () => readAgentVersionSnapshot,
+  resolveAgentVersionId: () => resolveAgentVersionId,
+  snapshotToComparable: () => snapshotToComparable
+});
+module.exports = __toCommonJS(versions_exports);
+
+// versions/constants.ts
+var AGENT_EXCLUDE_PATHS = /* @__PURE__ */ new Set([
+  "id",
+  "userId",
+  "organizationId",
+  "taskId",
+  "createdAt",
+  "updatedAt",
+  "isVersion",
+  "parentAgentId",
+  "sourceAgentId",
+  "sourceSnapshotAt",
+  // Lineage and record bookkeeping: who made the row and which version it was
+  // copied from never change what the agent does, so a copy never "differs" here.
+  "sourceVersion",
+  "followsSource",
+  "createdBy",
+  "runCounts",
+  "isOwner",
+  "accessLevel",
+  "sharedByEmail",
+  "agentType",
+  "version",
+  "changeNote",
+  "changedAt"
+]);
+var AGENT_IDENTITY_KEYS = {
+  variableDefinitions: "name",
+  contextPolicies: "key",
+  customTools: "name"
+};
+var AGENT_DIFF_OPTIONS = {
+  excludePaths: AGENT_EXCLUDE_PATHS,
+  identityKeys: AGENT_IDENTITY_KEYS,
+  // Output-schema property order is authored behavior: model providers often
+  // emit fields in schema order, so a reorder must be visible in version diffs.
+  orderSensitiveObjectPaths: /* @__PURE__ */ new Set(["outputSchema"]),
+  // Agent configuration is executable data. `_`/`__` keys (especially
+  // output-schema `__kind`) are contract fields, never hidden metadata.
+  skipUnderscorePrefix: false
+};
+
+// versions/compare.ts
+var import_structural = require("@ai-matrx/diff/structural");
+var AGENT_PROFILE_FIELDS = /* @__PURE__ */ new Set(["name", "description", "category", "tags"]);
+var AGENT_LOCAL_STATE_FIELDS = /* @__PURE__ */ new Set([
+  "isActive",
+  "isArchived",
+  "isFavorite"
+]);
+function toComparableAgentRecord(agent) {
+  return Object.fromEntries(
+    Object.entries(agent).filter(([key]) => !key.startsWith("_"))
+  );
+}
+function compareAgentDefinitions(systemAgent, personalAgent) {
+  const systemRecord = toComparableAgentRecord(systemAgent);
+  const personalRecord = toComparableAgentRecord(personalAgent);
+  const diffResult = (0, import_structural.computeDiff)(
+    systemRecord,
+    personalRecord,
+    AGENT_DIFF_OPTIONS
+  );
+  const changedFields = diffResult.root.filter(
+    (node) => node.changeType !== "unchanged"
+  );
+  const profileFields = changedFields.filter(
+    (node) => AGENT_PROFILE_FIELDS.has(node.key)
+  );
+  const localStateFields = changedFields.filter(
+    (node) => AGENT_LOCAL_STATE_FIELDS.has(node.key)
+  );
+  const behaviorFields = changedFields.filter(
+    (node) => !AGENT_PROFILE_FIELDS.has(node.key) && !AGENT_LOCAL_STATE_FIELDS.has(node.key)
+  );
+  return {
+    diffResult,
+    changedFields,
+    behaviorFields,
+    profileFields,
+    localStateFields,
+    behaviorMatches: behaviorFields.length === 0,
+    comparedConfigurationMatches: !diffResult.hasChanges
+  };
+}
+
+// versions/promote-failure-message.ts
+var GENERIC = "Failed to promote version";
+function promoteFailureMessage(err) {
+  const raw = err instanceof Error ? err.message : err && typeof err === "object" && "message" in err ? String(err.message ?? "") : typeof err === "string" ? err : "";
+  const reason = raw.trim();
+  return reason ? `${GENERIC}: ${reason}` : GENERIC;
+}
+
+// versions/enrich.ts
+var import_structural2 = require("@ai-matrx/diff/structural");
+function computeVersionFetchTargets(versions) {
+  if (versions.length === 0) return [];
+  const sorted = [...versions].sort((a, b) => b.version_number - a.version_number);
+  const targets = /* @__PURE__ */ new Set();
+  for (const v of sorted.slice(0, 10)) targets.add(v.version_number);
+  if (sorted.length <= 10) return [...targets];
+  targets.add(sorted[sorted.length - 1].version_number);
+  const remaining = sorted.slice(10, -1);
+  if (remaining.length > 0) {
+    const step = Math.max(1, Math.floor(remaining.length / Math.ceil(remaining.length / 10)));
+    for (let i = 0; i < remaining.length; i += step) targets.add(remaining[i].version_number);
+  }
+  return [...targets];
+}
+function enrichVersions(versions, snapshotOf) {
+  const sorted = [...versions].sort((a, b) => b.version_number - a.version_number);
+  return sorted.map((v, i) => {
+    const snapshot = snapshotOf(v.version_number);
+    const prev = sorted[i + 1];
+    const prevSnapshot = prev ? snapshotOf(prev.version_number) : void 0;
+    let diffSummary;
+    if (snapshot && prevSnapshot) {
+      diffSummary = (0, import_structural2.computeDiff)(
+        prevSnapshot,
+        snapshot,
+        AGENT_DIFF_OPTIONS
+      );
+    }
+    return { ...v, snapshotLoaded: !!snapshot, ...diffSummary ? { diffSummary } : {} };
+  });
+}
+var camel = (key) => key.replace(/_([a-z0-9])/g, (_, c) => c.toUpperCase());
+function snapshotToComparable(row) {
+  const out = {};
+  for (const [key, value] of Object.entries(row)) {
+    const name = key === "version_number" ? "version" : camel(key);
+    out[name] = value;
+  }
+  return out;
+}
+
+// versions/data.ts
+var AgentVersionsError = class extends Error {
+  code;
+  detail;
+  hint;
+  constructor(error) {
+    super(error.message || "The agent's versions could not be read and the database gave no reason.");
+    this.name = "AgentVersionsError";
+    this.code = error.code ?? null;
+    this.detail = error.details ?? null;
+    this.hint = error.hint ?? null;
+  }
+};
+async function listAgentVersions(client, query) {
+  const { data, error } = await client.rpc("agx_get_version_history", {
+    p_agent_id: query.agentId,
+    p_limit: query.limit ?? 50,
+    p_offset: query.offset ?? 0
+  });
+  if (error) throw new AgentVersionsError(error);
+  return Array.isArray(data) ? data : [];
+}
+async function readAgentVersionSnapshot(client, query) {
+  const { data, error } = await client.rpc("agx_get_version_snapshot", {
+    p_agent_id: query.agentId,
+    p_version_number: query.version
+  });
+  if (error) throw new AgentVersionsError(error);
+  const raw = Array.isArray(data) ? data[0] : data;
+  return raw && typeof raw === "object" ? raw : null;
+}
+async function resolveAgentVersionId(client, versionId) {
+  const { data, error } = await client.schema("agent").from("definition_version").select("id, agent_id, version_number, name").eq("id", versionId).maybeSingle();
+  if (error) throw new AgentVersionsError(error);
+  if (!data) return null;
+  const row = data;
+  return { versionId: row.id, agentId: row.agent_id, versionNumber: row.version_number, agentName: row.name };
+}
+async function promoteAgentVersion(client, query) {
+  const { data, error } = await client.rpc("agx_promote_version", {
+    p_agent_id: query.agentId,
+    p_version_number: query.version
+  });
+  if (error) throw new AgentVersionsError(error);
+  const result = data ?? {};
+  return { ...result, success: result.success === true };
+}
+async function declareContractBreak(client, query) {
+  const { error } = await client.rpc("agx_declare_contract_break", {
+    p_agent_id: query.agentId,
+    p_version_number: query.version,
+    p_kind: query.kind ?? void 0
+  });
+  if (error) throw new AgentVersionsError(error);
+}

package/dist/versions/index.d.cts

@@ -0,0 +1,158 @@
+import { DiffOptions, DiffResult, DiffNode } from '@ai-matrx/diff/structural';
+
+/** Internal/runtime fields that should never appear in diffs */
+declare const AGENT_EXCLUDE_PATHS: Set<string>;
+/** Identity keys for array matching — prevents false diffs when items shift position */
+declare const AGENT_IDENTITY_KEYS: Record<string, string>;
+declare const AGENT_DIFF_OPTIONS: DiffOptions;
+
+/**
+ * Any agent record the diff can compare: the web's Redux `AgentDefinition`, a version snapshot
+ * mapped by `snapshotToComparable`, or a fixture. Only top-level keys matter to the comparison.
+ */
+type ComparableAgent = object;
+interface AgentDefinitionComparison {
+    diffResult: DiffResult;
+    changedFields: DiffNode[];
+    behaviorFields: DiffNode[];
+    profileFields: DiffNode[];
+    localStateFields: DiffNode[];
+    behaviorMatches: boolean;
+    comparedConfigurationMatches: boolean;
+}
+/**
+ * Compare two live agents through the same exclusions and identity rules as
+ * the canonical AgentDiffViewer, while separating behavior from expected
+ * personal-copy profile differences.
+ */
+declare function compareAgentDefinitions(systemAgent: ComparableAgent, personalAgent: ComparableAgent): AgentDefinitionComparison;
+
+declare function promoteFailureMessage(err: unknown): string;
+
+/** One row of `agx_get_version_history`: a saved version of an agent (newest first). */
+interface AgentVersionHistoryEntry {
+    version_id: string;
+    version_number: number;
+    name: string;
+    changed_at: string;
+    change_note: string | null;
+    contract_change: string | null;
+    contract_break_declared: string | null;
+    input_contract_hash: string | null;
+    output_contract_hash: string | null;
+}
+/** A version id resolved to its agent and number (`agent.definition_version`). */
+interface AgentVersionLookup {
+    versionId: string;
+    agentId: string;
+    versionNumber: number;
+    agentName: string | null;
+}
+/** What `agx_promote_version` answers. */
+interface PromoteVersionResult {
+    success: boolean;
+    error?: string;
+    promoted_version?: number;
+    agent_id?: string;
+}
+/** A contract break a person declares on a version (null clears the declaration). */
+type ContractBreakKind = "input" | "output" | "both";
+/** A history entry with what changed since the version before it, once both snapshots were read. */
+interface EnrichedVersion extends AgentVersionHistoryEntry {
+    diffSummary?: DiffResult;
+    snapshotLoaded: boolean;
+}
+/** The load state the version timeline renders (the host owns where snapshots are kept). */
+interface VersionHistoryLoad {
+    enrichedVersions: EnrichedVersion[];
+    loading: boolean;
+    progress: {
+        fetched: number;
+        total: number;
+    };
+    /** Versions whose snapshot read failed — never invisible. */
+    failedVersions: number[];
+    failureReason: string | null;
+    fetchEnrichedHistory: () => void | Promise<void>;
+    /** Read the named versions' snapshots (the timeline's Load on a gap). */
+    fetchGap: (versionNumbers: number[]) => void | Promise<void>;
+}
+
+/**
+ * The versions a "Load Full History" reads: the 10 newest, the oldest, and about every 10th in
+ * between — enough to say what changed across a long history without reading every snapshot.
+ */
+declare function computeVersionFetchTargets(versions: readonly Pick<AgentVersionHistoryEntry, "version_number">[]): number[];
+/**
+ * Each version (newest first) with `snapshotLoaded` and, when it and the version before it were
+ * both read, the diff between them. `snapshotOf` answers the host's stored snapshot or undefined.
+ */
+declare function enrichVersions<V extends AgentVersionHistoryEntry>(versions: readonly V[], snapshotOf: (versionNumber: number) => ComparableAgent | undefined): (V & EnrichedVersion)[];
+/**
+ * A raw `agx_get_version_snapshot` row in the agent-definition key names the diff adapters read
+ * (`model_id` → `modelId`, `variable_definitions` → `variableDefinitions`, …). Top-level keys only;
+ * values pass through untouched, so both sides of a comparison made this way read alike. A host
+ * with its own parsed agent records (the web's Redux store) compares those instead.
+ */
+declare function snapshotToComparable(row: Record<string, unknown>): Record<string, unknown>;
+
+/** The database's refusal, as supabase-js reports it. */
+interface VersionsDbError {
+    message: string;
+    code?: string | null;
+    details?: string | null;
+    hint?: string | null;
+}
+type Answer = PromiseLike<{
+    data: unknown;
+    error: VersionsDbError | null;
+}>;
+/** The calls these reads make: a supabase-js client fits it as is. */
+interface VersionsClient {
+    rpc(fn: string, args: Record<string, unknown>): Answer;
+    schema(name: "agent"): {
+        from(table: "definition_version"): {
+            select(columns: string): {
+                eq(column: string, value: string): {
+                    maybeSingle(): Answer;
+                };
+            };
+        };
+    };
+}
+/** A refused or failed read, carrying the database's own sentence. */
+declare class AgentVersionsError extends Error {
+    readonly code: string | null;
+    readonly detail: string | null;
+    readonly hint: string | null;
+    constructor(error: VersionsDbError);
+}
+/** One page of an agent's saved versions, newest first. */
+declare function listAgentVersions(client: VersionsClient, query: {
+    agentId: string;
+    limit?: number;
+    offset?: number;
+}): Promise<AgentVersionHistoryEntry[]>;
+/** The raw snapshot row of one version (null: the database has no such version for this agent). */
+declare function readAgentVersionSnapshot(client: VersionsClient, query: {
+    agentId: string;
+    version: number;
+}): Promise<Record<string, unknown> | null>;
+/** An immutable version id → its agent and number. RLS on agent.definition_version is the boundary. */
+declare function resolveAgentVersionId(client: VersionsClient, versionId: string): Promise<AgentVersionLookup | null>;
+/**
+ * Restore: make a past version the agent's current definition (`agx_promote_version`). A refusal
+ * throws with the database's sentence — show it with `promoteFailureMessage`.
+ */
+declare function promoteAgentVersion(client: VersionsClient, query: {
+    agentId: string;
+    version: number;
+}): Promise<PromoteVersionResult>;
+/** Declare (or clear, with null) a contract break the hashes cannot see. */
+declare function declareContractBreak(client: VersionsClient, query: {
+    agentId: string;
+    version: number;
+    kind: ContractBreakKind | null;
+}): Promise<void>;
+
+export { AGENT_DIFF_OPTIONS, AGENT_EXCLUDE_PATHS, AGENT_IDENTITY_KEYS, type AgentDefinitionComparison, type AgentVersionHistoryEntry, type AgentVersionLookup, AgentVersionsError, type ComparableAgent, type ContractBreakKind, type EnrichedVersion, type PromoteVersionResult, type VersionHistoryLoad, type VersionsClient, type VersionsDbError, compareAgentDefinitions, computeVersionFetchTargets, declareContractBreak, enrichVersions, listAgentVersions, promoteAgentVersion, promoteFailureMessage, readAgentVersionSnapshot, resolveAgentVersionId, snapshotToComparable };