@ai-matrx/agents 0.59.179 → 0.59.181

package/dist/models/index.d.ts

@@ -897,6 +897,30 @@ declare function isSupersedable(node: SuccessionNode): boolean;
 declare function resolveSuccessor(modelId: string, index: SuccessionIndex): string;
 /** Test seam: forget which broken chains were already logged. */
 declare function resetSuccessionLogForTests(): void;
+/** The read `resolveLiveModelId` makes: a supabase-js client fits it as is. */
+interface SuccessionClient {
+    schema(name: "ai"): {
+        from(table: "model_public"): {
+            select(columns: string): {
+                in(column: string, values: readonly string[]): PromiseLike<{
+                    data: unknown;
+                    error: {
+                        message: string;
+                    } | null;
+                }>;
+            };
+        };
+    };
+}
+/**
+ * The model a NEW record should be written with: `modelId` followed along its successor chain, read
+ * hop by hop from `ai.model_public`. A creation default pinned in code (a blank agent's model)
+ * outlives the model it names; writing it as is made every new agent start on a superseded model
+ * that the picker then healed on first view, so a brand-new agent showed an unsaved model change
+ * nobody made (Lane D walk, 2026-10-21). A read failure keeps `modelId` and logs: creation never
+ * fails over a name.
+ */
+declare function resolveLiveModelId(client: SuccessionClient, modelId: string): Promise<string>;
 
 /**
  * `@ai-matrx/agents/models` — downloadable (local) models: the catalog shape every client reads, the
@@ -1516,4 +1540,4 @@ declare function curatedList<T extends CuratedModel>(models: readonly T[], { off
     offeredOnly: boolean;
 }): T[];
 
-export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogModel, type CatalogTier, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type RankedVariant, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type Want, acceptsTextInstructions, buildModelClassIndex, buildSuccessionIndex, catalogForApp, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readGgufHeader, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolvePreferredModelChoice, resolveSuccessor, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, toAuditRecord, validateModelSet, withModelClass };
+export { type AdminOffering, type AdminPricingBand, type ArtifactUse, type AuditCapabilitiesRecord, CHAT_DEFAULT_MODEL_KNOB, CONTENT_TYPES, type CapabilitiesParseContext, type CatalogModel, type CatalogTier, type CompatStatus, type ContentType, type CuratedCatalogClient, type CuratedModel, type CuratedPresentation, type CuratedVariant, DEFAULT_CAPABILITIES, type DecidedBy, type DeviceGraphics, type DeviceHardware, type DiscoveryAmbiguity, type DiscoveryArtifact, type DiscoveryMedia, type DiscoveryResult, type DiscoveryRuntime, type DiscoverySource, type DiscoveryVariant, EMPTY_MODEL_RECORDS, FEATURE_BUCKETS, FEATURE_BUCKET_ORDER, FEATURE_KEYS, FILE_TYPE_QUANT, type FeatureBucket, type FeatureBucketMeta, type FeatureKey, GgufError, type GgufHeader, type GgufRead, type GgufTensor, type GroupedFeatures, type HardwareClass, type HardwareClasses, type HeaderFlag, type HeaderJudgement, type HeaderRefusal, INPUT_MODALITIES, INTERACTION_MODES, type Interaction, type InteractionMode, type LocalArtifact, type LocalCompatRow, type LocalModel, type LocalModelCatalog, type LocalPresentation, type LocalRuntime, type LocalRuntimeBuild, type LocalVariant, MAX_SUCCESSION_HOPS, MODEL_FAVORITE_ENTITY_TYPE, type Modality, type ModelCapabilities, type ModelCatalog, type ModelCatalogClient, type ModelCatalogConfig, type ModelCatalogErrorSink, type ModelCatalogPgError, type ModelCatalogPgResult, type ModelCatalogQuery, type ModelCatalogState, type ModelCatalogVariant, type ModelCatalogVariantState, type ModelClassConfig, type ModelClassEntry, type ModelClassIndex, type ModelDiagnosticEntry, type ModelDiagnosticsSink, type ModelFavorites, type ModelFavoritesCache, type ModelFavoritesClient, type ModelFavoritesConfig, type ModelFavoritesErrorSink, type ModelFavoritesState, type ModelFetchScope, type ModelFileHandle, type ModelFit, type ModelIdentityRow, type ModelJson, type ModelOfferingRow, type ModelOption, type ModelOptionWithLifecycle, type ModelRecord, type ModelRecordFetchType, type ModelRecords, type ModelRecordsClient, type ModelRecordsConfig, type ModelRecordsState, type ModelSelectionPurpose, type ModelSetEnv, type ModelSetFacts, type ModelSetValidation, type NoSelection, OUTPUT_MODALITIES, type OrderedLike, type PreferredModelChoice, type PreferredModelChoicePorts, type PriceTier, type RankedVariant, SERVICE_LABEL, SERVICE_LABEL_PLURAL, type SelectDevice, type Selection, type ShardName, type SuccessionClient, type SuccessionIndex, type SuccessionNode, TOP_TIER_COST_RATING, TOP_TIER_LOCKED_TITLE, type VariantDiscovery, type Want, acceptsTextInstructions, buildModelClassIndex, buildSuccessionIndex, catalogForApp, classConfigKey, collapseTiersByClass, costRatingTier, costRatingWord, createModelCatalog, createModelFavorites, createModelRecords, curatedList, displayOrderOf, favoriteIdsEqual, fetchCuratedModels, findNonCanonicalCapabilityValues, fitsMemory, fitsThisComputer, formatMemoryBytes, fromDiscovery, ggufEngine, ggufFacts, groupFeatures, hardwareClassesOf, hasCompatibleDecisionInteraction, isContentType, isConversationalModelCapability, isDecisionModelCapability, isFeatureKey, isHelperGguf, isInteractionMode, isLocalModelCatalog, isManagedAgentModelCapability, isProjectorName, isSupersedable, isTopTierRating, judgeHeaderFacts, mergeAuditRecordIntoCapabilities, missingShards, modelClassKnobFor, modelClassName, modelClassPinOf, modelsForSelectionPurpose, normalizeArch, normalizeModel, normalizeModels, normalizeOs, normalizePromptSettings, orderCatalogGroups, orderCatalogModels, outputFormatControlKey, parseCapabilities, pickProjector, priceTierRating, quantFromName, rankVariants, readGgufHeader, reconcileModelFavoriteIds, reportModelDiagnostic, requireCanonicalCapabilities, requiredArtifacts, resetSuccessionLogForTests, resolveLiveModelId, resolvePreferredModelChoice, resolveSuccessor, selectActiveModels, selectActiveModelsReady, selectAllModelOptions, selectAllModels, selectAllModelsReady, selectDeprecatedModels, selectDeprecatedModelsReady, selectModelById, selectModelClassConfig, selectModelClassName, selectModelControls, selectModelDetailError, selectModelFetchType, selectModelFullyLoaded, selectModelIdentityById, selectModelIdentityLookupStatus, selectModelLabelById, selectModelLabelWithClass, selectModelNameById, selectModelOptions, selectVariant, serviceCountLabel, setModelDiagnosticsSink, shapeCuratedModels, shardFileName, shardName, speedRatingLabel, speedRatingWord, splitSetProblems, toAuditRecord, validateModelSet, withModelClass };

package/dist/models/index.js

@@ -1550,6 +1550,28 @@ function resolveSuccessor(modelId, index) {
 function resetSuccessionLogForTests() {
   loggedBroken.clear();
 }
+async function resolveLiveModelId(client, modelId) {
+  const index = /* @__PURE__ */ new Map();
+  let want = modelId;
+  for (let hop = 0; want && hop <= MAX_SUCCESSION_HOPS && !index.has(want); hop += 1) {
+    const { data, error } = await client.schema("ai").from("model_public").select("id, is_deprecated, retired_at, successor_id").in("id", [want]);
+    if (error) {
+      console.warn(`[models/succession] ${modelId}: the catalog could not be read (${error.message}); keeping the model as given.`);
+      return modelId;
+    }
+    const row = Array.isArray(data) ? data[0] : null;
+    if (!row || typeof row.id !== "string") break;
+    const node = {
+      id: row.id,
+      isDeprecated: row.is_deprecated === true,
+      retiredAt: typeof row.retired_at === "string" ? row.retired_at : null,
+      successorId: typeof row.successor_id === "string" ? row.successor_id : null
+    };
+    index.set(node.id, node);
+    want = isSupersedable(node) ? node.successorId : null;
+  }
+  return resolveSuccessor(modelId, index);
+}
 
 // models/local.ts
 import { compareVersions } from "@ai-matrx/kit/versions";
@@ -2368,6 +2390,7 @@ export {
   requireCanonicalCapabilities,
   requiredArtifacts,
   resetSuccessionLogForTests,
+  resolveLiveModelId,
   resolvePreferredModelChoice,
   resolveSuccessor,
   selectActiveModels,

package/dist/versions/index.cjs

@@ -31,6 +31,8 @@ __export(versions_exports, {
   listAgentVersions: () => listAgentVersions,
   promoteAgentVersion: () => promoteAgentVersion,
   promoteFailureMessage: () => promoteFailureMessage,
+  promoteSuccessMessage: () => promoteSuccessMessage,
+  readAgentCurrentVersion: () => readAgentCurrentVersion,
   readAgentVersionSnapshot: () => readAgentVersionSnapshot,
   resolveAgentVersionId: () => resolveAgentVersionId,
   snapshotToComparable: () => snapshotToComparable
@@ -130,6 +132,9 @@ function promoteFailureMessage(err) {
   const reason = raw.trim();
   return reason ? `${GENERIC}: ${reason}` : GENERIC;
 }
+function promoteSuccessMessage(version) {
+  return `v${version}'s settings are now current; no new version was saved`;
+}
 
 // versions/enrich.ts
 var import_structural2 = require("@ai-matrx/diff/structural");
@@ -221,6 +226,12 @@ async function promoteAgentVersion(client, query) {
   const result = data ?? {};
   return { ...result, success: result.success === true };
 }
+async function readAgentCurrentVersion(client, agentId) {
+  const { data, error } = await client.schema("agent").from("definition").select("version").eq("id", agentId).maybeSingle();
+  if (error) throw new AgentVersionsError(error);
+  const v = data?.version;
+  return typeof v === "number" && Number.isInteger(v) ? v : null;
+}
 async function declareContractBreak(client, query) {
   const { error } = await client.rpc("agx_declare_contract_break", {
     p_agent_id: query.agentId,

package/dist/versions/index.d.cts

@@ -28,6 +28,13 @@ interface AgentDefinitionComparison {
 declare function compareAgentDefinitions(systemAgent: ComparableAgent, personalAgent: ComparableAgent): AgentDefinitionComparison;
 
 declare function promoteFailureMessage(err: unknown): string;
+/**
+ * The sentence a successful restore shows. `agx_promote_version` copies the version's settings onto
+ * the agent and SAVES NO NEW VERSION (it sets `app.skip_version_snapshot`; read 2026-10-21), so the
+ * history gains no row: the restored version becomes the current one. Saying so keeps a person from
+ * looking for a new row that will never come.
+ */
+declare function promoteSuccessMessage(version: number): string;
 
 /** One row of `agx_get_version_history`: a saved version of an agent (newest first). */
 interface AgentVersionHistoryEntry {
@@ -111,7 +118,7 @@ type Answer = PromiseLike<{
 interface VersionsClient {
     rpc(fn: string, args: Record<string, unknown>): Answer;
     schema(name: "agent"): {
-        from(table: "definition_version"): {
+        from(table: "definition_version" | "definition"): {
             select(columns: string): {
                 eq(column: string, value: string): {
                     maybeSingle(): Answer;
@@ -148,6 +155,12 @@ declare function promoteAgentVersion(client: VersionsClient, query: {
     agentId: string;
     version: number;
 }): Promise<PromoteVersionResult>;
+/**
+ * The version the agent is at NOW (`agent.definition.version`). A restore sets it to the restored
+ * number without adding a history row, so the newest history row is not the current version after
+ * one: read this instead. Null when the person cannot read the agent.
+ */
+declare function readAgentCurrentVersion(client: VersionsClient, agentId: string): Promise<number | null>;
 /** Declare (or clear, with null) a contract break the hashes cannot see. */
 declare function declareContractBreak(client: VersionsClient, query: {
     agentId: string;
@@ -155,4 +168,4 @@ declare function declareContractBreak(client: VersionsClient, query: {
     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 };
+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, promoteSuccessMessage, readAgentCurrentVersion, readAgentVersionSnapshot, resolveAgentVersionId, snapshotToComparable };

package/dist/versions/index.d.ts

@@ -28,6 +28,13 @@ interface AgentDefinitionComparison {
 declare function compareAgentDefinitions(systemAgent: ComparableAgent, personalAgent: ComparableAgent): AgentDefinitionComparison;
 
 declare function promoteFailureMessage(err: unknown): string;
+/**
+ * The sentence a successful restore shows. `agx_promote_version` copies the version's settings onto
+ * the agent and SAVES NO NEW VERSION (it sets `app.skip_version_snapshot`; read 2026-10-21), so the
+ * history gains no row: the restored version becomes the current one. Saying so keeps a person from
+ * looking for a new row that will never come.
+ */
+declare function promoteSuccessMessage(version: number): string;
 
 /** One row of `agx_get_version_history`: a saved version of an agent (newest first). */
 interface AgentVersionHistoryEntry {
@@ -111,7 +118,7 @@ type Answer = PromiseLike<{
 interface VersionsClient {
     rpc(fn: string, args: Record<string, unknown>): Answer;
     schema(name: "agent"): {
-        from(table: "definition_version"): {
+        from(table: "definition_version" | "definition"): {
             select(columns: string): {
                 eq(column: string, value: string): {
                     maybeSingle(): Answer;
@@ -148,6 +155,12 @@ declare function promoteAgentVersion(client: VersionsClient, query: {
     agentId: string;
     version: number;
 }): Promise<PromoteVersionResult>;
+/**
+ * The version the agent is at NOW (`agent.definition.version`). A restore sets it to the restored
+ * number without adding a history row, so the newest history row is not the current version after
+ * one: read this instead. Null when the person cannot read the agent.
+ */
+declare function readAgentCurrentVersion(client: VersionsClient, agentId: string): Promise<number | null>;
 /** Declare (or clear, with null) a contract break the hashes cannot see. */
 declare function declareContractBreak(client: VersionsClient, query: {
     agentId: string;
@@ -155,4 +168,4 @@ declare function declareContractBreak(client: VersionsClient, query: {
     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 };
+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, promoteSuccessMessage, readAgentCurrentVersion, readAgentVersionSnapshot, resolveAgentVersionId, snapshotToComparable };

package/dist/versions/index.js

@@ -91,6 +91,9 @@ function promoteFailureMessage(err) {
   const reason = raw.trim();
   return reason ? `${GENERIC}: ${reason}` : GENERIC;
 }
+function promoteSuccessMessage(version) {
+  return `v${version}'s settings are now current; no new version was saved`;
+}
 
 // versions/enrich.ts
 import { computeDiff as computeDiff2 } from "@ai-matrx/diff/structural";
@@ -182,6 +185,12 @@ async function promoteAgentVersion(client, query) {
   const result = data ?? {};
   return { ...result, success: result.success === true };
 }
+async function readAgentCurrentVersion(client, agentId) {
+  const { data, error } = await client.schema("agent").from("definition").select("version").eq("id", agentId).maybeSingle();
+  if (error) throw new AgentVersionsError(error);
+  const v = data?.version;
+  return typeof v === "number" && Number.isInteger(v) ? v : null;
+}
 async function declareContractBreak(client, query) {
   const { error } = await client.rpc("agx_declare_contract_break", {
     p_agent_id: query.agentId,
@@ -202,6 +211,8 @@ export {
   listAgentVersions,
   promoteAgentVersion,
   promoteFailureMessage,
+  promoteSuccessMessage,
+  readAgentCurrentVersion,
   readAgentVersionSnapshot,
   resolveAgentVersionId,
   snapshotToComparable