@ai-matrx/agents 0.59.176 → 0.59.177

package/dist/versions/react/index.d.cts

@@ -0,0 +1,137 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import * as _ai_matrx_diff_react from '@ai-matrx/diff/react';
+import { EnrichmentContext } from '@ai-matrx/diff/react';
+import { DiffTemporalMetadata, ViewMode, DiffResult } from '@ai-matrx/diff/structural';
+import { VersionTimelineEntry, MatrxTableIconAction } from '@ai-matrx/design-system/data-table';
+
+/**
+ * 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 AgentModelRefProps {
+    modelId: string;
+    /** The name the diff's enrichment resolved, when it did. */
+    name?: string | null | undefined;
+    /** Show the raw id under the name (the diff's label column does). */
+    showId?: boolean | undefined;
+    className?: string | undefined;
+}
+interface AgentToolRefProps {
+    toolId: string;
+    name?: string | null | undefined;
+    showId?: boolean | undefined;
+    className?: string | undefined;
+}
+interface AgentDiffRefPorts {
+    ModelRef?: ComponentType<AgentModelRefProps> | undefined;
+    ToolRef?: ComponentType<AgentToolRefProps> | undefined;
+}
+interface ResolvedRefs {
+    ModelRef: ComponentType<AgentModelRefProps>;
+    ToolRef: ComponentType<AgentToolRefProps>;
+}
+declare function AgentDiffRefsProvider({ refs, children }: {
+    refs?: AgentDiffRefPorts | undefined;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useAgentDiffRefs(): ResolvedRefs;
+
+interface AgentDiffViewerProps {
+    oldAgent: ComparableAgent;
+    newAgent: ComparableAgent;
+    oldLabel: string;
+    newLabel: string;
+    temporalMetadata?: DiffTemporalMetadata;
+    defaultMode?: ViewMode;
+    className?: string;
+    /** Names for model/tool/MCP ids. Absent: ids show as they are. */
+    enrichment?: EnrichmentContext | undefined;
+    /** How a model or tool id is drawn. Absent: its resolved name and the id, as text. */
+    refs?: AgentDiffRefPorts | undefined;
+}
+/**
+ * The canonical agent field-adapter registry. Exported so a diff PAGE can name and describe changed
+ * fields exactly as this viewer renders them (Copy-for-AI) — one registry, never a parallel label table.
+ */
+declare function buildAgentAdapterRegistry(): _ai_matrx_diff_react.AdapterRegistry;
+declare function AgentDiffViewer({ oldAgent, newAgent, oldLabel, newLabel, temporalMetadata, defaultMode, className, enrichment, refs, }: AgentDiffViewerProps): react.JSX.Element;
+
+/** 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 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>;
+}
+
+/** Where the timeline says a result: the host's toasts (sonner on the web). */
+interface VersionTimelineNotify {
+    success: (message: string) => void;
+    error: (message: string) => void;
+}
+interface VersionHistoryTimelineProps {
+    agentId: string;
+    versions: readonly AgentVersionHistoryEntry[];
+    currentVersion: number | null;
+    onCompare: (version: number, compareToVersion: number | "current") => void;
+    /** The snapshot-load state: the host keeps snapshots (Redux on the web) and enriches with `enrichVersions`. */
+    history: VersionHistoryLoad;
+    /** Records a declared contract break (`declareContractBreak`); a rejection rolls the badge back. Absent: no declare menu. */
+    onDeclareContractBreak?: ((versionNumber: number, kind: ContractBreakKind | null) => Promise<void>) | undefined;
+    notify?: VersionTimelineNotify | undefined;
+    /** The host's own row actions (duplicate as a new agent, …) after the timeline's. */
+    rowActions?: ((entry: VersionTimelineEntry) => readonly MatrxTableIconAction[]) | undefined;
+    /** Rendered once below the timeline (the host's dialogs). */
+    footer?: ReactNode;
+    /** The host's "explain this error" slot beside a failed read. */
+    ErrorMenu?: ComponentType<{
+        error?: string;
+    }> | undefined;
+}
+/**
+ * The agent's versions on THE shared version timeline (`MatrxVersionTimeline`): compare with the
+ * previous / current version, duplicate any version as a new agent, Load for snapshots not read
+ * yet, and — per version — the contract-break badge, the declare-a-break menu and the changed
+ * fields as chips.
+ */
+declare function VersionHistoryTimeline({ agentId, versions, currentVersion, onCompare, history, onDeclareContractBreak, notify, rowActions, footer, ErrorMenu, }: VersionHistoryTimelineProps): react.JSX.Element;
+
+interface ModelTierIdentity {
+    key: string;
+    role: string;
+    modelId: string;
+}
+/** The named model identities inside an agent's nested `modelTiers` object (default first). */
+declare function readModelTierIdentities(value: unknown): ModelTierIdentity[];
+
+export { type AgentDiffRefPorts, AgentDiffRefsProvider, AgentDiffViewer, type AgentDiffViewerProps, type AgentModelRefProps, type AgentToolRefProps, VersionHistoryTimeline, type VersionHistoryTimelineProps, type VersionTimelineNotify, buildAgentAdapterRegistry, readModelTierIdentities, useAgentDiffRefs };

package/dist/versions/react/index.d.ts

@@ -0,0 +1,137 @@
+import * as react from 'react';
+import { ComponentType, ReactNode } from 'react';
+import * as _ai_matrx_diff_react from '@ai-matrx/diff/react';
+import { EnrichmentContext } from '@ai-matrx/diff/react';
+import { DiffTemporalMetadata, ViewMode, DiffResult } from '@ai-matrx/diff/structural';
+import { VersionTimelineEntry, MatrxTableIconAction } from '@ai-matrx/design-system/data-table';
+
+/**
+ * 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 AgentModelRefProps {
+    modelId: string;
+    /** The name the diff's enrichment resolved, when it did. */
+    name?: string | null | undefined;
+    /** Show the raw id under the name (the diff's label column does). */
+    showId?: boolean | undefined;
+    className?: string | undefined;
+}
+interface AgentToolRefProps {
+    toolId: string;
+    name?: string | null | undefined;
+    showId?: boolean | undefined;
+    className?: string | undefined;
+}
+interface AgentDiffRefPorts {
+    ModelRef?: ComponentType<AgentModelRefProps> | undefined;
+    ToolRef?: ComponentType<AgentToolRefProps> | undefined;
+}
+interface ResolvedRefs {
+    ModelRef: ComponentType<AgentModelRefProps>;
+    ToolRef: ComponentType<AgentToolRefProps>;
+}
+declare function AgentDiffRefsProvider({ refs, children }: {
+    refs?: AgentDiffRefPorts | undefined;
+    children: ReactNode;
+}): react.JSX.Element;
+declare function useAgentDiffRefs(): ResolvedRefs;
+
+interface AgentDiffViewerProps {
+    oldAgent: ComparableAgent;
+    newAgent: ComparableAgent;
+    oldLabel: string;
+    newLabel: string;
+    temporalMetadata?: DiffTemporalMetadata;
+    defaultMode?: ViewMode;
+    className?: string;
+    /** Names for model/tool/MCP ids. Absent: ids show as they are. */
+    enrichment?: EnrichmentContext | undefined;
+    /** How a model or tool id is drawn. Absent: its resolved name and the id, as text. */
+    refs?: AgentDiffRefPorts | undefined;
+}
+/**
+ * The canonical agent field-adapter registry. Exported so a diff PAGE can name and describe changed
+ * fields exactly as this viewer renders them (Copy-for-AI) — one registry, never a parallel label table.
+ */
+declare function buildAgentAdapterRegistry(): _ai_matrx_diff_react.AdapterRegistry;
+declare function AgentDiffViewer({ oldAgent, newAgent, oldLabel, newLabel, temporalMetadata, defaultMode, className, enrichment, refs, }: AgentDiffViewerProps): react.JSX.Element;
+
+/** 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 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>;
+}
+
+/** Where the timeline says a result: the host's toasts (sonner on the web). */
+interface VersionTimelineNotify {
+    success: (message: string) => void;
+    error: (message: string) => void;
+}
+interface VersionHistoryTimelineProps {
+    agentId: string;
+    versions: readonly AgentVersionHistoryEntry[];
+    currentVersion: number | null;
+    onCompare: (version: number, compareToVersion: number | "current") => void;
+    /** The snapshot-load state: the host keeps snapshots (Redux on the web) and enriches with `enrichVersions`. */
+    history: VersionHistoryLoad;
+    /** Records a declared contract break (`declareContractBreak`); a rejection rolls the badge back. Absent: no declare menu. */
+    onDeclareContractBreak?: ((versionNumber: number, kind: ContractBreakKind | null) => Promise<void>) | undefined;
+    notify?: VersionTimelineNotify | undefined;
+    /** The host's own row actions (duplicate as a new agent, …) after the timeline's. */
+    rowActions?: ((entry: VersionTimelineEntry) => readonly MatrxTableIconAction[]) | undefined;
+    /** Rendered once below the timeline (the host's dialogs). */
+    footer?: ReactNode;
+    /** The host's "explain this error" slot beside a failed read. */
+    ErrorMenu?: ComponentType<{
+        error?: string;
+    }> | undefined;
+}
+/**
+ * The agent's versions on THE shared version timeline (`MatrxVersionTimeline`): compare with the
+ * previous / current version, duplicate any version as a new agent, Load for snapshots not read
+ * yet, and — per version — the contract-break badge, the declare-a-break menu and the changed
+ * fields as chips.
+ */
+declare function VersionHistoryTimeline({ agentId, versions, currentVersion, onCompare, history, onDeclareContractBreak, notify, rowActions, footer, ErrorMenu, }: VersionHistoryTimelineProps): react.JSX.Element;
+
+interface ModelTierIdentity {
+    key: string;
+    role: string;
+    modelId: string;
+}
+/** The named model identities inside an agent's nested `modelTiers` object (default first). */
+declare function readModelTierIdentities(value: unknown): ModelTierIdentity[];
+
+export { type AgentDiffRefPorts, AgentDiffRefsProvider, AgentDiffViewer, type AgentDiffViewerProps, type AgentModelRefProps, type AgentToolRefProps, VersionHistoryTimeline, type VersionHistoryTimelineProps, type VersionTimelineNotify, buildAgentAdapterRegistry, readModelTierIdentities, useAgentDiffRefs };