@ai-matrx/agents 0.59.176 → 0.59.177

package/dist/versions/index.d.ts

@@ -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 };

package/dist/versions/index.js

@@ -0,0 +1,208 @@
+// 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
+import { computeDiff } from "@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 = 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
+import { computeDiff as computeDiff2 } from "@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 = computeDiff2(
+        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);
+}
+export {
+  AGENT_DIFF_OPTIONS,
+  AGENT_EXCLUDE_PATHS,
+  AGENT_IDENTITY_KEYS,
+  AgentVersionsError,
+  compareAgentDefinitions,
+  computeVersionFetchTargets,
+  declareContractBreak,
+  enrichVersions,
+  listAgentVersions,
+  promoteAgentVersion,
+  promoteFailureMessage,
+  readAgentVersionSnapshot,
+  resolveAgentVersionId,
+  snapshotToComparable
+};