@promptbook/cli 0.113.0-9 → 0.114.0-1

package/apps/agents-server/src/utils/vpsTask/runWithVpsServerSetupTask.ts

@@ -0,0 +1,192 @@
+import { buildVpsServerSetupAdminChatTaskId, VPS_SERVER_SETUP_ADMIN_CHAT_TASK_ID_PREFIX } from '../adminChatTaskLinks';
+import type { AdminChatTaskRecord } from '../chatTasksAdmin';
+import { appendVpsServerSetupTask, finishVpsServerSetupTask } from './vpsTaskHistory';
+import type { VpsServerSetupTaskOptions, VpsServerSetupTaskResult } from './vpsTaskTypes';
+
+/**
+ * Queue name shown for VPS server setup and certificate-maintenance tasks.
+ *
+ * @private constant of `runWithVpsServerSetupTask`
+ */
+export const VPS_SERVER_SETUP_TASK_QUEUE_NAME = 'vps-server-setup';
+
+/**
+ * Runs one VPS operation while recording its common task-manager lifecycle fields.
+ *
+ * The task is persisted before the operation starts and is completed in both the normal and
+ * exceptional paths. Persistence failures are deliberately observational: task logging must
+ * never prevent server setup or certificate maintenance from running.
+ *
+ * @param options - Task display and target metadata.
+ * @param operation - VPS operation to execute.
+ * @param resolveResult - Optional result-status resolver for APIs that return failures instead of throwing.
+ * @returns The operation result.
+ *
+ * @private internal utility of Agents Server
+ */
+export async function runWithVpsServerSetupTask<Result>(
+    options: VpsServerSetupTaskOptions,
+    operation: () => Promise<Result>,
+    resolveResult: (result: Result) => boolean | VpsServerSetupTaskResult = () => true,
+): Promise<Result> {
+    const task = createVpsServerSetupTaskRecord(options);
+    let isTaskPersisted = false;
+
+    try {
+        await appendVpsServerSetupTask(task);
+        isTaskPersisted = true;
+    } catch (error) {
+        console.error('[admin-chat-task] failed to persist VPS server setup task start', error);
+    }
+
+    try {
+        const result = await operation();
+        const taskResult = normalizeVpsServerSetupTaskResult(resolveResult(result));
+        if (isTaskPersisted) {
+            await finishVpsServerSetupTaskSafely(task.id, taskResult);
+        }
+        return result;
+    } catch (error) {
+        if (isTaskPersisted) {
+            await finishVpsServerSetupTaskSafely(task.id, {
+                isSuccessful: false,
+                errorSummary: resolveVpsTaskErrorSummary(error),
+                errorDetails: resolveVpsTaskErrorDetails(error),
+            });
+        }
+        throw error;
+    }
+}
+
+/**
+ * Creates the complete task-manager row written at operation start.
+ *
+ * @param options - Task display and target metadata.
+ * @returns Running task row.
+ *
+ * @private function of `runWithVpsServerSetupTask`
+ */
+function createVpsServerSetupTaskRecord(options: VpsServerSetupTaskOptions): AdminChatTaskRecord {
+    const timestamp = new Date().toISOString();
+    const taskId = buildVpsServerSetupAdminChatTaskId(createVpsServerSetupTaskIdentity(timestamp));
+
+    return {
+        id: taskId,
+        kind: 'VPS_SERVER_SETUP',
+        status: 'RUNNING',
+        createdAt: timestamp,
+        queuedAt: timestamp,
+        startedAt: timestamp,
+        updatedAt: timestamp,
+        finishedAt: null,
+        cancelRequestedAt: null,
+        pausedAt: null,
+        lastHeartbeatAt: timestamp,
+        leaseExpiresAt: null,
+        recurrenceIntervalMs: null,
+        priority: null,
+        attemptCount: 1,
+        retryCount: 0,
+        lastErrorSummary: null,
+        lastErrorDetails: null,
+        userId: 0,
+        username: null,
+        agentPermanentId: taskId,
+        agentName: options.taskName,
+        chatId: options.chatId,
+        workerId: String(process.pid),
+        queueName: VPS_SERVER_SETUP_TASK_QUEUE_NAME,
+        serverName: options.serverName ?? null,
+        serverDomain: options.serverDomain ?? null,
+    };
+}
+
+/**
+ * Creates a unique identity for one task-history row.
+ *
+ * @param startedAt - Task start timestamp used by the fallback identity.
+ * @returns Task identity.
+ *
+ * @private function of `createVpsServerSetupTaskRecord`
+ */
+function createVpsServerSetupTaskIdentity(startedAt: string): string {
+    if (typeof globalThis.crypto?.randomUUID === 'function') {
+        return globalThis.crypto.randomUUID();
+    }
+
+    return `${startedAt.replace(/[^0-9]/gu, '')}-${process.pid}-${Math.floor(
+        Math.random() * Number.MAX_SAFE_INTEGER,
+    ).toString(36)}`;
+}
+
+/**
+ * Normalizes the supported task-result resolver return forms.
+ *
+ * @param result - Boolean or detailed task result.
+ * @returns Detailed task result.
+ *
+ * @private function of `runWithVpsServerSetupTask`
+ */
+function normalizeVpsServerSetupTaskResult(result: boolean | VpsServerSetupTaskResult): VpsServerSetupTaskResult {
+    return typeof result === 'boolean' ? { isSuccessful: result } : result;
+}
+
+/**
+ * Persists one terminal task state without changing the wrapped operation result.
+ *
+ * @param taskId - Task identifier.
+ * @param taskResult - Terminal task fields.
+ * @returns Promise that resolves after persistence or logging.
+ *
+ * @private function of `runWithVpsServerSetupTask`
+ */
+async function finishVpsServerSetupTaskSafely(taskId: string, taskResult: VpsServerSetupTaskResult): Promise<void> {
+    const finishedAt = new Date().toISOString();
+    try {
+        await finishVpsServerSetupTask(taskId, {
+            status: taskResult.isSuccessful ? 'COMPLETED' : 'FAILED',
+            finishedAt,
+            updatedAt: finishedAt,
+            lastErrorSummary: taskResult.isSuccessful ? null : taskResult.errorSummary || 'VPS operation failed.',
+            lastErrorDetails: taskResult.isSuccessful ? null : taskResult.errorDetails || null,
+        });
+    } catch (error) {
+        console.error('[admin-chat-task] failed to persist VPS server setup task completion', error);
+    }
+}
+
+/**
+ * Extracts a compact error summary for a failed VPS task.
+ *
+ * @param error - Unknown operation error.
+ * @returns Error summary.
+ *
+ * @private function of `runWithVpsServerSetupTask`
+ */
+function resolveVpsTaskErrorSummary(error: unknown): string {
+    return error instanceof Error ? error.message : String(error);
+}
+
+/**
+ * Extracts detailed error text for a failed VPS task.
+ *
+ * @param error - Unknown operation error.
+ * @returns Error details.
+ *
+ * @private function of `runWithVpsServerSetupTask`
+ */
+function resolveVpsTaskErrorDetails(error: unknown): string {
+    return error instanceof Error ? error.stack || error.message : String(error);
+}
+
+/**
+ * Returns whether a task id belongs to a VPS server setup task.
+ *
+ * @param taskId - Candidate task identifier.
+ * @returns `true` when the identifier uses the VPS setup prefix.
+ *
+ * @private internal utility of Agents Server
+ */
+export function isVpsServerSetupTaskId(taskId: string): boolean {
+    return taskId.startsWith(`${VPS_SERVER_SETUP_ADMIN_CHAT_TASK_ID_PREFIX}:`);
+}

package/apps/agents-server/src/utils/vpsTask/vpsTaskHistory.ts

@@ -0,0 +1,189 @@
+import { mkdir, readFile, writeFile } from 'fs/promises';
+import { dirname, resolve } from 'path';
+import { resolveVpsEnvironmentFilePath } from '../vpsConfiguration';
+import type { AdminChatTaskRecord } from '../chatTasksAdmin';
+import type { VpsServerSetupTaskHistoryFile } from './vpsTaskTypes';
+
+/**
+ * Version of the persisted VPS server setup task-history file.
+ *
+ * @private constant of `vpsTaskHistory`
+ */
+const VPS_SERVER_SETUP_TASK_HISTORY_VERSION = 1 as const;
+
+/**
+ * In-process write queue preventing overlapping setup-task history updates from dropping rows.
+ *
+ * @private variable of `vpsTaskHistory`
+ */
+let vpsServerSetupTaskHistoryWriteQueue: Promise<void> = Promise.resolve();
+
+/**
+ * Reads all persisted VPS server setup and certificate-maintenance tasks.
+ *
+ * @returns Valid task rows, newest first.
+ *
+ * @private internal utility of Agents Server
+ */
+export async function readVpsServerSetupTaskHistory(): Promise<Array<AdminChatTaskRecord>> {
+    try {
+        const rawHistory = await readFile(resolveVpsServerSetupTaskHistoryFilePath(), 'utf-8');
+        const parsedHistory = JSON.parse(rawHistory) as unknown;
+        if (!isVpsServerSetupTaskHistoryFile(parsedHistory)) {
+            return [];
+        }
+
+        return parsedHistory.tasks.filter(isVpsServerSetupTaskRecord).map((task) => ({ ...task }));
+    } catch (error) {
+        if ((error as NodeJS.ErrnoException).code === 'ENOENT' || error instanceof SyntaxError) {
+            return [];
+        }
+
+        throw error;
+    }
+}
+
+/**
+ * Adds one newly started VPS server setup task to the persisted history.
+ *
+ * @param task - Task row to persist.
+ * @returns Promise that resolves after the row is written.
+ *
+ * @private internal utility of Agents Server
+ */
+export async function appendVpsServerSetupTask(task: AdminChatTaskRecord): Promise<void> {
+    await enqueueVpsServerSetupTaskHistoryWrite(async () => {
+        const existingTasks = await readVpsServerSetupTaskHistory();
+        await writeVpsServerSetupTaskHistory([task, ...existingTasks]);
+    });
+}
+
+/**
+ * Updates the terminal state of one persisted VPS server setup task.
+ *
+ * @param taskId - Task identifier to update.
+ * @param taskUpdate - Terminal fields to apply.
+ * @returns Promise that resolves after the row is written.
+ *
+ * @private internal utility of Agents Server
+ */
+export async function finishVpsServerSetupTask(
+    taskId: string,
+    taskUpdate: Pick<
+        AdminChatTaskRecord,
+        'status' | 'finishedAt' | 'updatedAt' | 'lastErrorSummary' | 'lastErrorDetails'
+    >,
+): Promise<void> {
+    await enqueueVpsServerSetupTaskHistoryWrite(async () => {
+        const existingTasks = await readVpsServerSetupTaskHistory();
+        const updatedTasks = existingTasks.map((task) => (task.id === taskId ? { ...task, ...taskUpdate } : task));
+        await writeVpsServerSetupTaskHistory(updatedTasks);
+    });
+}
+
+/**
+ * Resolves the persisted task-history file used by VPS setup operations.
+ *
+ * @returns Absolute task-history file path.
+ *
+ * @private internal utility of Agents Server
+ */
+export function resolveVpsServerSetupTaskHistoryFilePath(): string {
+    return resolve(dirname(resolveVpsEnvironmentFilePath()), '.promptbook', 'vps-server-setup-task-history.json');
+}
+
+/**
+ * Serializes the VPS server setup task history.
+ *
+ * @param tasks - Task rows to write.
+ * @returns File payload.
+ *
+ * @private function of `writeVpsServerSetupTaskHistory`
+ */
+function createVpsServerSetupTaskHistoryFile(tasks: ReadonlyArray<AdminChatTaskRecord>): VpsServerSetupTaskHistoryFile {
+    return {
+        version: VPS_SERVER_SETUP_TASK_HISTORY_VERSION,
+        tasks,
+    };
+}
+
+/**
+ * Writes the complete VPS server setup task history.
+ *
+ * @param tasks - Task rows to write.
+ * @returns Promise that resolves after the file is written.
+ *
+ * @private function of `appendVpsServerSetupTask`
+ */
+async function writeVpsServerSetupTaskHistory(tasks: ReadonlyArray<AdminChatTaskRecord>): Promise<void> {
+    const historyFilePath = resolveVpsServerSetupTaskHistoryFilePath();
+    await mkdir(dirname(historyFilePath), { recursive: true });
+    await writeFile(
+        historyFilePath,
+        `${JSON.stringify(createVpsServerSetupTaskHistoryFile(tasks), null, 2)}\n`,
+        'utf-8',
+    );
+}
+
+/**
+ * Serializes file updates so concurrent setup operations preserve every task row.
+ *
+ * @param operation - One history read-modify-write operation.
+ * @returns Promise returned by the queued operation.
+ *
+ * @private function of `appendVpsServerSetupTask`
+ */
+function enqueueVpsServerSetupTaskHistoryWrite(operation: () => Promise<void>): Promise<void> {
+    const queuedOperation = vpsServerSetupTaskHistoryWriteQueue.then(operation, operation);
+    vpsServerSetupTaskHistoryWriteQueue = queuedOperation.catch(() => undefined);
+    return queuedOperation;
+}
+
+/**
+ * Checks whether parsed JSON has the expected task-history envelope.
+ *
+ * @param value - Parsed JSON value.
+ * @returns `true` when the value has the expected version and task array.
+ *
+ * @private function of `readVpsServerSetupTaskHistory`
+ */
+function isVpsServerSetupTaskHistoryFile(value: unknown): value is VpsServerSetupTaskHistoryFile {
+    return (
+        typeof value === 'object' &&
+        value !== null &&
+        'version' in value &&
+        value.version === VPS_SERVER_SETUP_TASK_HISTORY_VERSION &&
+        'tasks' in value &&
+        Array.isArray(value.tasks)
+    );
+}
+
+/**
+ * Checks whether one parsed value is a safe VPS setup task row.
+ *
+ * @param value - Parsed JSON value.
+ * @returns `true` when the value contains the fields needed by the task manager.
+ *
+ * @private function of `readVpsServerSetupTaskHistory`
+ */
+function isVpsServerSetupTaskRecord(value: unknown): value is AdminChatTaskRecord {
+    if (typeof value !== 'object' || value === null) {
+        return false;
+    }
+
+    const task = value as Partial<AdminChatTaskRecord>;
+    return (
+        typeof task.id === 'string' &&
+        task.kind === 'VPS_SERVER_SETUP' &&
+        typeof task.status === 'string' &&
+        typeof task.createdAt === 'string' &&
+        typeof task.queuedAt === 'string' &&
+        typeof task.updatedAt === 'string' &&
+        typeof task.attemptCount === 'number' &&
+        typeof task.retryCount === 'number' &&
+        typeof task.userId === 'number' &&
+        typeof task.agentPermanentId === 'string' &&
+        typeof task.agentName === 'string' &&
+        typeof task.chatId === 'string'
+    );
+}

package/apps/agents-server/src/utils/vpsTask/vpsTaskTypes.ts

@@ -0,0 +1,67 @@
+import type { AdminChatTaskRecord } from '../chatTasksAdmin';
+
+/**
+ * Options used when recording one VPS-wide setup task.
+ *
+ * @private internal utility of Agents Server
+ */
+export type VpsServerSetupTaskOptions = {
+    /**
+     * Human-readable operation shown in the task manager.
+     */
+    readonly taskName: string;
+
+    /**
+     * Searchable object identifier, usually the affected domain or domain list.
+     */
+    readonly chatId: string;
+
+    /**
+     * Registered server name when the operation belongs to one server.
+     */
+    readonly serverName?: string | null;
+
+    /**
+     * Registered server domain when the operation belongs to one server.
+     */
+    readonly serverDomain?: string | null;
+};
+
+/**
+ * Result of resolving whether a wrapped VPS operation completed successfully.
+ *
+ * @private internal utility of Agents Server
+ */
+export type VpsServerSetupTaskResult = {
+    /**
+     * Whether the operation should be shown as completed.
+     */
+    readonly isSuccessful: boolean;
+
+    /**
+     * Optional failure summary for the task row.
+     */
+    readonly errorSummary?: string | null;
+
+    /**
+     * Optional failure details for the task row.
+     */
+    readonly errorDetails?: string | null;
+};
+
+/**
+ * Persisted VPS server setup task-history file.
+ *
+ * @private internal utility of Agents Server
+ */
+export type VpsServerSetupTaskHistoryFile = {
+    /**
+     * File-format version.
+     */
+    readonly version: 1;
+
+    /**
+     * Server setup and certificate-maintenance task rows.
+     */
+    readonly tasks: ReadonlyArray<AdminChatTaskRecord>;
+};

package/esm/apps/agents-server/src/constants/serverLimits.d.ts

@@ -27,7 +27,7 @@ export declare const DEFAULT_SPAWN_AGENT_RATE_LIMIT_WINDOW_MS: number;
  *
  * @private shared Agents Server constant
  */
-export declare const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 3;
+export declare const DEFAULT_LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS = 1;
 /**
  * Default maximum number of local runner harness instances allowed to answer queued messages at once.
  *

package/esm/apps/agents-server/src/database/sqlite/$provideAgentsServerSqliteDatabase.d.ts

@@ -0,0 +1,69 @@
+/**
+ * Shape of the `better-sqlite3` module constructor loaded at runtime.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export type BetterSqliteConstructor = new (path: string) => AgentsServerSqliteDatabase;
+/**
+ * Minimal `better-sqlite3` database surface shared by Agents Server SQLite utilities.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export type AgentsServerSqliteDatabase = {
+    readonly pragma: (source: string) => unknown;
+    readonly exec: (source: string) => void;
+    readonly prepare: (source: string) => AgentsServerSqliteStatement;
+    readonly transaction: <TArguments extends ReadonlyArray<unknown>, TResult>(fn: (...args: TArguments) => TResult) => (...args: TArguments) => TResult;
+    readonly close?: () => void;
+};
+/**
+ * Minimal `better-sqlite3` prepared statement surface shared by Agents Server SQLite utilities.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export type AgentsServerSqliteStatement = {
+    readonly reader?: boolean;
+    readonly all: (...values: ReadonlyArray<unknown>) => Array<Record<string, unknown>>;
+    readonly get: (...values: ReadonlyArray<unknown>) => Record<string, unknown> | undefined;
+    readonly run: (...values: ReadonlyArray<unknown>) => {
+        readonly changes: number;
+        readonly lastInsertRowid: number | bigint;
+    };
+};
+/**
+ * Opens and initializes one SQLite database file, caching the connection per path.
+ *
+ * @param databasePath - Absolute path of the SQLite database file.
+ * @returns Cached SQLite database connection.
+ *
+ * @private exported from Agents Server SQLite utilities
+ */
+export declare function $provideSqliteDatabaseAtPath(databasePath: string): AgentsServerSqliteDatabase;
+/**
+ * Opens the VPS-wide SQLite registry database.
+ *
+ * This database is owned by the super-admin and holds only VPS-level data,
+ * most importantly the `_Server` table listing all servers running on this VPS.
+ * Server-scoped data (agents, projects, metadata, users, ...) lives in isolated
+ * per-server databases provided by `$provideServerSqliteDatabase`.
+ *
+ * @returns Shared VPS registry SQLite database connection.
+ *
+ * @private exported from Agents Server SQLite utilities
+ */
+export declare function $provideVpsRegistrySqliteDatabase(): AgentsServerSqliteDatabase;
+/**
+ * Opens the isolated SQLite database of one server namespace.
+ *
+ * @param tablePrefix - Stable server namespace key, or an empty string for the default server.
+ * @returns Per-server SQLite database connection.
+ *
+ * @private exported from Agents Server SQLite utilities
+ */
+export declare function $provideServerSqliteDatabase(tablePrefix: string): AgentsServerSqliteDatabase;
+/**
+ * Closes all cached SQLite connections and resets adapter state for isolated tests.
+ *
+ * @private exported from Agents Server SQLite utilities
+ */
+export declare function $resetAgentsServerSqliteDatabaseForTests(): void;

package/esm/apps/agents-server/src/database/sqlite/localSqliteSupabase/ensureTable.d.ts

@@ -0,0 +1,7 @@
+import type { AgentsServerSqliteDatabase } from '../$provideAgentsServerSqliteDatabase';
+/**
+ * Ensures a table and all required columns exist.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function ensureTable(database: AgentsServerSqliteDatabase, tableName: string, requiredColumns: ReadonlyArray<string>): void;

package/esm/apps/agents-server/src/database/sqlite/localSqliteSupabase/localSqliteSql.d.ts

@@ -0,0 +1,30 @@
+/**
+ * Quotes one SQLite identifier.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function quoteIdentifier(identifier: string): string;
+/**
+ * Creates a safe identifier suffix for generated index names.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function sanitizeSqlIdentifier(identifier: string): string;
+/**
+ * Creates a select expression from parsed columns.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function createSelectExpression(columns: ReadonlyArray<string>): string;
+/**
+ * Parses a simple Supabase select column list.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function parseSelectedColumns(columns: string): Array<string>;
+/**
+ * Deduplicates strings while preserving order.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function uniqueStrings(values: ReadonlyArray<string>): Array<string>;

package/esm/apps/agents-server/src/database/sqlite/localSqliteSupabase/localSqliteTableSchema.d.ts

@@ -0,0 +1,76 @@
+import type { LocalSqliteUpsertOptions } from './localSqliteTypes';
+/**
+ * Read index definition for hot SQLite queries.
+ *
+ * @private type of `$provideLocalSqliteSupabase`
+ */
+export type LocalSqliteReadIndex = {
+    readonly name: string;
+    readonly columns: ReadonlyArray<string>;
+};
+/**
+ * Resolves a table base name from the actual prefixed table name.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveTableBaseName(tableName: string): string;
+/**
+ * Resolves columns participating in known unique indexes.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveUniqueIndexColumns(tableBaseName: string): Array<string>;
+/**
+ * Resolves columns participating in known read indexes.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveReadIndexColumns(tableBaseName: string): Array<string>;
+/**
+ * Resolves upsert conflict columns.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveUpsertConflictColumns(tableBaseName: string, options: LocalSqliteUpsertOptions): ReadonlyArray<string>;
+/**
+ * Resolves the unique index definitions declared for a table base name.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveUniqueIndexes(tableBaseName: string): ReadonlyArray<ReadonlyArray<string>>;
+/**
+ * Resolves the read index definitions declared for a table base name.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveReadIndexes(tableBaseName: string): ReadonlyArray<LocalSqliteReadIndex>;
+/**
+ * Resolves whether a column is JSON for a specific table.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function isJsonColumn(tableName: string, column: string): boolean;
+/**
+ * Resolves whether a column should be forced to a string for a specific table.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function isTextColumn(tableName: string, column: string): boolean;
+/**
+ * Resolves whether a column is a boolean stored as an integer.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function isBooleanColumn(column: string): boolean;
+/**
+ * Resolves whether a table base name uses a text primary key.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function isTextPrimaryKeyTable(tableBaseName: string): boolean;
+/**
+ * Resolves SQLite column affinity for dynamically added columns.
+ *
+ * @private function of `$provideLocalSqliteSupabase`
+ */
+export declare function resolveSqliteColumnType(tableBaseName: string, column: string): string;

package/esm/apps/agents-server/src/database/sqlite/resolveAgentsServerSqliteDatabasePath.d.ts

@@ -0,0 +1,4 @@
+/**
+ * Resolves the SQLite database path used by the standalone backend.
+ */
+export declare function resolveAgentsServerSqliteDatabasePath(): string;

package/esm/apps/agents-server/src/database/sqlite/resolveServerSqliteDatabasePath.d.ts

@@ -0,0 +1,28 @@
+/**
+ * Database key used for requests that do not belong to any registered server,
+ * for example localhost development traffic before any server is registered.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export declare const DEFAULT_SERVER_SQLITE_DATABASE_KEY = "default";
+/**
+ * Resolves the isolated SQLite database file path for one server namespace.
+ *
+ * Each registered server has its own SQLite database file so servers on one VPS
+ * cannot leak agents, projects, metadata or any other data into each other.
+ *
+ * @param tablePrefix - Stable server namespace key such as `server_ClientA_`, or an empty string for the default server.
+ * @returns Absolute path of the per-server SQLite database file.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export declare function resolveServerSqliteDatabasePath(tablePrefix: string): string;
+/**
+ * Converts one server table prefix into a safe database file key.
+ *
+ * @param tablePrefix - Stable server namespace key, or an empty string for the default server.
+ * @returns Validated file-name-safe database key.
+ *
+ * @private internal SQLite utility of Agents Server
+ */
+export declare function resolveServerSqliteDatabaseKey(tablePrefix: string): string;