@promptbook/cli 0.113.0-4 → 0.113.0-8

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupPreviews.ts

@@ -0,0 +1,97 @@
+import type { AgentRow, BackupAgentPreview, BackupUserPreview, UserRow } from './serverBackupTypes';
+
+/**
+ * Builds the user preview map reused across metadata sidecars.
+ *
+ * @param users - Full user rows.
+ * @returns User preview map keyed by numeric id.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createUserPreviewById(users: ReadonlyArray<UserRow>): Map<number, BackupUserPreview> {
+    return new Map(
+        users.map((user) => [
+            user.id,
+            {
+                id: user.id,
+                username: user.username,
+                isAdmin: user.isAdmin,
+                profileImageUrl: user.profileImageUrl,
+            } satisfies BackupUserPreview,
+        ] as const),
+    );
+}
+
+/**
+ * Builds the agent preview map keyed by numeric id.
+ *
+ * @param agents - Full agent rows.
+ * @returns Agent preview map keyed by numeric id.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAgentPreviewById(agents: ReadonlyArray<AgentRow>): Map<number, BackupAgentPreview> {
+    return new Map(
+        agents.map((agent) => [
+            agent.id,
+            {
+                id: agent.id,
+                agentName: agent.agentName,
+                permanentId: agent.permanentId,
+            } satisfies BackupAgentPreview,
+        ] as const),
+    );
+}
+
+/**
+ * Builds the agent preview map keyed by permanent id.
+ *
+ * @param agents - Full agent rows.
+ * @returns Agent preview map keyed by permanent id.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAgentPreviewByPermanentId(agents: ReadonlyArray<AgentRow>): Map<string, BackupAgentPreview> {
+    return new Map(
+        agents.flatMap((agent) =>
+            agent.permanentId
+                ? [
+                      [
+                          agent.permanentId,
+                          {
+                              id: agent.id,
+                              agentName: agent.agentName,
+                              permanentId: agent.permanentId,
+                          } satisfies BackupAgentPreview,
+                      ] as const,
+                  ]
+                : [],
+        ),
+    );
+}
+
+/**
+ * Builds the first-agent-by-name preview map used by feedback sidecars.
+ *
+ * @param agents - Full agent rows.
+ * @returns Agent preview map keyed by agent name.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function createAgentPreviewByName(agents: ReadonlyArray<AgentRow>): Map<string, BackupAgentPreview> {
+    const agentPreviewByName = new Map<string, BackupAgentPreview>();
+
+    for (const agent of agents) {
+        if (agentPreviewByName.has(agent.agentName)) {
+            continue;
+        }
+
+        agentPreviewByName.set(agent.agentName, {
+            id: agent.id,
+            agentName: agent.agentName,
+            permanentId: agent.permanentId,
+        });
+    }
+
+    return agentPreviewByName;
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupRowUtilities.ts

@@ -0,0 +1,158 @@
+/**
+ * Groups rows by a computed key.
+ *
+ * @param rows - Rows to group.
+ * @param getKey - Key selector.
+ * @returns Grouped rows keyed by the computed value.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function groupRowsBy<Row, Key extends string | number>(
+    rows: ReadonlyArray<Row>,
+    getKey: (row: Row) => Key,
+): Map<Key, Array<Row>> {
+    const rowsByKey = new Map<Key, Array<Row>>();
+
+    for (const row of rows) {
+        const key = getKey(row);
+        const groupedRows = rowsByKey.get(key) || [];
+        groupedRows.push(row);
+        rowsByKey.set(key, groupedRows);
+    }
+
+    return rowsByKey;
+}
+
+/**
+ * Converts one unknown persisted message array into serializable objects.
+ *
+ * @param value - Raw message array candidate.
+ * @returns Serializable message array.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function resolveSerializableArray(value: unknown): Array<Record<string, unknown>> {
+    if (!Array.isArray(value)) {
+        return [];
+    }
+
+    return value.filter(isRecord);
+}
+
+/**
+ * Type guard for plain objects used throughout the backup builders.
+ *
+ * @param value - Unknown value.
+ * @returns `true` when the value is a non-array object.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function isRecord(value: unknown): value is Record<string, unknown> {
+    return Boolean(value) && typeof value === 'object' && !Array.isArray(value);
+}
+
+/**
+ * Deduplicates JSON-serializable objects using their serialized representation.
+ *
+ * @param values - Serializable objects.
+ * @returns Deduplicated object list in first-seen order.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function deduplicateSerializableObjects<Value extends object>(values: ReadonlyArray<Value>): Array<Value> {
+    const seenSerializedValues = new Set<string>();
+    const deduplicatedValues: Array<Value> = [];
+
+    for (const value of values) {
+        const serializedValue = JSON.stringify(value);
+        if (seenSerializedValues.has(serializedValue)) {
+            continue;
+        }
+
+        seenSerializedValues.add(serializedValue);
+        deduplicatedValues.push(value);
+    }
+
+    return deduplicatedValues;
+}
+
+/**
+ * Normalizes one optional text field to a trimmed string or `null`.
+ *
+ * @param value - Raw value.
+ * @returns Trimmed text or `null`.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function normalizeOptionalText(value: unknown): string | null {
+    if (typeof value !== 'string') {
+        return null;
+    }
+
+    const normalizedValue = value.trim();
+    return normalizedValue.length > 0 ? normalizedValue : null;
+}
+
+/**
+ * Sorts exported rows so JSON files remain stable and easier to diff.
+ *
+ * @param rows - Raw table rows fetched from Supabase.
+ * @returns Sorted shallow-cloned row list.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+export function sortBackupRows(rows: ReadonlyArray<Record<string, unknown>>): Array<Record<string, unknown>> {
+    return [...rows].sort(compareBackupRows);
+}
+
+/**
+ * Compares two generic backup rows using the most common stable identifier fields.
+ *
+ * @param left - First row.
+ * @param right - Second row.
+ * @returns Stable ordering for backup JSON output.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+function compareBackupRows(left: Record<string, unknown>, right: Record<string, unknown>): number {
+    const comparableKeys = ['sortOrder', 'id', 'key', 'username', 'agentName', 'permanentId', 'messageHash', 'createdAt'];
+
+    for (const comparableKey of comparableKeys) {
+        const comparison = compareComparableValues(left[comparableKey], right[comparableKey]);
+
+        if (comparison !== 0) {
+            return comparison;
+        }
+    }
+
+    return JSON.stringify(left).localeCompare(JSON.stringify(right));
+}
+
+/**
+ * Compares one optional pair of identifier values.
+ *
+ * @param left - First value.
+ * @param right - Second value.
+ * @returns Comparison result compatible with `Array.sort`.
+ *
+ * @private function of `createServerBackupZipStream`
+ */
+function compareComparableValues(left: unknown, right: unknown): number {
+    if (left === right) {
+        return 0;
+    }
+
+    if (typeof left === 'number' && typeof right === 'number') {
+        return left - right;
+    }
+
+    if (left === undefined || left === null) {
+        return 1;
+    }
+
+    if (right === undefined || right === null) {
+        return -1;
+    }
+
+    return String(left).localeCompare(String(right));
+}

package/apps/agents-server/src/utils/backup/serverBackup/serverBackupTypes.ts

@@ -0,0 +1,59 @@
+import type { AgentsServerDatabase } from '../../../database/schema';
+
+/**
+ * Typed row alias for `Agent`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type AgentRow = AgentsServerDatabase['public']['Tables']['Agent']['Row'];
+
+/**
+ * Typed row alias for `User`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+
+/**
+ * Typed row alias for `UserChat`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type UserChatRow = AgentsServerDatabase['public']['Tables']['UserChat']['Row'];
+
+/**
+ * Typed row alias for `ChatFeedback`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type ChatFeedbackRow = AgentsServerDatabase['public']['Tables']['ChatFeedback']['Row'];
+
+/**
+ * Typed row alias for `Wallet`.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type WalletRow = AgentsServerDatabase['public']['Tables']['Wallet']['Row'];
+
+/**
+ * Shared preview persisted for referenced users inside backup metadata files.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type BackupUserPreview = {
+    readonly id: number;
+    readonly username: string;
+    readonly isAdmin: boolean;
+    readonly profileImageUrl: string | null;
+};
+
+/**
+ * Shared preview persisted for referenced agents inside backup metadata files.
+ *
+ * @private type of `createServerBackupZipStream`
+ */
+export type BackupAgentPreview = {
+    readonly id: number;
+    readonly agentName: string;
+    readonly permanentId: string | null;
+};

package/apps/agents-server/src/utils/createLocalAgentSourceImporter.ts

@@ -0,0 +1,159 @@
+import type { AgentReferenceResolver } from '../../../../src/book-2.0/agent-source/AgentReferenceResolver';
+import type { AgentCollection } from '../../../../src/collection/agent-collection/AgentCollection';
+import { DEFAULT_MAX_RECURSION } from '../../../../src/config';
+import { NotFoundError } from '../../../../src/errors/NotFoundError';
+import { ParseError } from '../../../../src/errors/ParseError';
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
+import type { FederatedAgentImportConfiguration } from '../constants/federatedAgentImport';
+import {
+    resolveBookScopedAgentContext,
+    type ResolvedBookScopedAgentContext,
+} from './agentReferenceResolver/bookScopedAgentReferences';
+import {
+    createLocalAgentUrl,
+    normalizeLocalAgentUrlReferences,
+    normalizeLocalServerUrls,
+    resolveLocalAgentRouteReference,
+} from './localAgentRouteReferences';
+import { createMissingImportedAgentFallback } from './createMissingImportedAgentFallback';
+import {
+    resolveInheritedAgentSource,
+    type AgentSourceImporter,
+} from './resolveInheritedAgentSource';
+
+/**
+ * Dependencies needed for importing same-instance agent sources without HTTP.
+ */
+export type CreateLocalAgentSourceImporterOptions = {
+    /**
+     * Collection used to load local regular and book-scoped agent sources.
+     */
+    readonly collection: Pick<AgentCollection, 'getAgentPermanentId' | 'getAgentSource'>;
+
+    /**
+     * Server origins that should be treated as this Agents Server instance.
+     */
+    readonly localServerUrls: ReadonlyArray<string>;
+
+    /**
+     * Exact agent URLs that should be treated as local even when their origin is not in `localServerUrls`.
+     */
+    readonly localAgentUrls?: ReadonlyArray<string_agent_url>;
+
+    /**
+     * Adam agent URL used for implicit default inheritance.
+     */
+    readonly adamAgentUrl: string_agent_url;
+
+    /**
+     * Resolver used for compact references that are not book-scoped.
+     */
+    readonly fallbackResolver?: AgentReferenceResolver;
+
+    /**
+     * Retry configuration used when nested imports leave the local server.
+     */
+    readonly federatedAgentImportConfiguration?: FederatedAgentImportConfiguration;
+};
+
+/**
+ * Creates an importer that loads same-instance agent URLs directly from the collection.
+ *
+ * @param options - Same-instance import dependencies.
+ * @returns Importer suitable for `resolveInheritedAgentSource`.
+ */
+export function createLocalAgentSourceImporter(options: CreateLocalAgentSourceImporterOptions): AgentSourceImporter {
+    const localServerUrls = normalizeLocalServerUrls(options.localServerUrls);
+    const localAgentUrlReferences = normalizeLocalAgentUrlReferences(options.localAgentUrls || []);
+    const localAgentSourceImporter: AgentSourceImporter = async (agentUrl, context) => {
+        const localRouteReference = resolveLocalAgentRouteReference(agentUrl, localServerUrls, localAgentUrlReferences);
+
+        if (!localRouteReference) {
+            return null;
+        }
+
+        const nextRecursionLevel = (context.importAgentOptions.recursionLevel || 0) + 1;
+        assertRecursionLevel(nextRecursionLevel, agentUrl);
+
+        let resolvedAgentContext: ResolvedBookScopedAgentContext;
+
+        try {
+            resolvedAgentContext = await resolveBookScopedAgentContext({
+                collection: options.collection,
+                agentIdentifier: localRouteReference.agentIdentifier,
+                localServerUrl: localRouteReference.localServerUrl,
+                fallbackResolver: options.fallbackResolver,
+            });
+        } catch (error) {
+            if (error instanceof NotFoundError) {
+                return createMissingImportedAgentFallback(agentUrl, 1, error);
+            }
+
+            throw error;
+        }
+
+        return resolveInheritedAgentSource(resolvedAgentContext.unresolvedAgentSource, {
+            adamAgentUrl: options.adamAgentUrl,
+            recursionLevel: nextRecursionLevel,
+            inheritancePath: context.importAgentOptions.inheritancePath,
+            currentAgentUrl: resolvedAgentContext.canonicalAgentUrl,
+            currentAgentAliases: createCurrentAgentAliases(resolvedAgentContext, localServerUrls),
+            agentReferenceResolver: resolvedAgentContext.scopedAgentReferenceResolver,
+            federatedAgentImportConfiguration:
+                options.federatedAgentImportConfiguration || context.federatedAgentImportConfiguration,
+            agentSourceImporter: localAgentSourceImporter,
+        });
+    };
+
+    return localAgentSourceImporter;
+}
+
+/**
+ * Throws when direct local importing would exceed the configured recursion limit.
+ *
+ * @param recursionLevel - Next recursion level.
+ * @param agentUrl - Local agent URL being imported.
+ */
+function assertRecursionLevel(recursionLevel: number, agentUrl: string_agent_url): void {
+    if (recursionLevel <= DEFAULT_MAX_RECURSION) {
+        return;
+    }
+
+    throw new ParseError(
+        spaceTrim(
+            (block) => `
+                Recursion depth ${recursionLevel} exceeds maximum allowed ${DEFAULT_MAX_RECURSION} while importing local agent:
+
+                ${block(agentUrl)}
+            `,
+        ),
+    );
+}
+
+/**
+ * Builds cycle-detection aliases for every same-instance origin.
+ *
+ * @param resolvedAgentContext - Resolved local/book-scoped agent context.
+ * @param localServerUrls - Same-instance server origins.
+ * @returns Unique local URL aliases for the imported agent.
+ */
+function createCurrentAgentAliases(
+    resolvedAgentContext: ResolvedBookScopedAgentContext,
+    localServerUrls: ReadonlyArray<string>,
+): Array<string_agent_url> {
+    const agentIdentifiers = [
+        resolvedAgentContext.canonicalAgentIdentifier,
+        resolvedAgentContext.requestedAgentIdentifier,
+        resolvedAgentContext.resolvedAgentName,
+    ].filter((agentIdentifier, index, agentIdentifierList) => agentIdentifierList.indexOf(agentIdentifier) === index);
+    const agentAliases = new Set<string>(resolvedAgentContext.currentAgentAliases);
+
+    for (const localServerUrl of localServerUrls) {
+        for (const agentIdentifier of agentIdentifiers) {
+            agentAliases.add(createLocalAgentUrl(localServerUrl, agentIdentifier));
+        }
+    }
+
+    return [...agentAliases] as Array<string_agent_url>;
+}

package/apps/agents-server/src/utils/createMissingImportedAgentFallback.ts

@@ -0,0 +1,60 @@
+import { padBook } from '../../../../src/book-2.0/agent-source/padBook';
+import { validateBook } from '../../../../src/book-2.0/agent-source/string_book';
+import type { string_agent_url } from '../../../../src/types/typeAliases';
+import type { string_book } from '../../../../src/book-2.0/agent-source/string_book';
+import { spaceTrim } from '../../../../src/utils/organization/spaceTrim';
+
+/**
+ * Collapses one thrown error into a single-line message suitable for `NOTE` commitments.
+ *
+ * @param agentUrl - Canonical imported agent URL.
+ * @param error - Unknown error raised while loading the imported agent.
+ * @returns Human-readable single-line failure reason.
+ *
+ * @private internal helper for imported-agent fallback books
+ */
+function normalizeImportFailureMessage(agentUrl: string_agent_url, error: unknown): string {
+    const rawMessage = error instanceof Error ? error.message : String(error);
+    const normalizedMessage = rawMessage.replace(/\s+/g, ' ').trim();
+    const prefix = `Failed to import agent from "${agentUrl}"`;
+
+    if (normalizedMessage.startsWith(prefix)) {
+        const suffix = normalizedMessage.slice(prefix.length).trim();
+        if (suffix.length > 0) {
+            return suffix.replace(/^[-:,\s]+/, '').trim() || 'unknown error';
+        }
+    }
+
+    return normalizedMessage || 'unknown error';
+}
+
+/**
+ * Creates the ad-hoc fallback source returned when a referenced agent stays unavailable.
+ *
+ * @param agentUrl - Canonical imported agent URL.
+ * @param attempts - Total number of attempts that were used.
+ * @param error - Final error raised by the failed import attempts.
+ * @returns Valid fallback book source.
+ *
+ * @private internal helper for imported-agent fallback books
+ */
+export function createMissingImportedAgentFallback(
+    agentUrl: string_agent_url,
+    attempts: number,
+    error: unknown,
+): string_book {
+    const failureMessage = normalizeImportFailureMessage(agentUrl, error);
+
+    return padBook(
+        validateBook(
+            spaceTrim(
+                `
+                    Not found agent
+
+                    NOTE This agent was supposed to be imported from ${agentUrl}, but it can not be loaded after ${attempts} attempts because of ${failureMessage}
+                    CLOSED
+                `,
+            ),
+        ),
+    );
+}