@promptbook/cli 0.112.0-99 → 0.112.0

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

@@ -0,0 +1,241 @@
+import { createHash } from 'crypto';
+import { NextRequest, NextResponse } from 'next/server';
+import { spaceTrim } from 'spacetrim';
+import { getRequestIp } from '../middleware/createMiddlewareRequestContext/getRequestIp';
+import { getSession } from './session';
+import { validateApiKey } from './validateApiKey';
+
+/**
+ * Categorizes the kind of paid third-party AI call a route performs.
+ *
+ * Each tier maps to its own per-identity sliding-window budget because the
+ * marginal cost (and therefore acceptable rate) differs significantly between
+ * speech-to-text, text-to-speech, and image generation.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestTier = 'AUDIO_TRANSCRIPTION' | 'TEXT_TO_SPEECH' | 'IMAGE_GENERATION';
+
+/**
+ * Per-tier rate limit definition.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+type PaidApiRateLimitDefinition = {
+    /**
+     * Maximum number of paid calls permitted per identity in a single window.
+     */
+    readonly maxRequestsPerWindow: number;
+    /**
+     * Length of the sliding window in milliseconds.
+     */
+    readonly windowMs: number;
+};
+
+/**
+ * Per-identity, per-tier sliding-window budgets for paid third-party calls.
+ *
+ * Numbers are intentionally generous for normal interactive UI use while still
+ * blocking sustained abuse — e.g. an attacker who has obtained a valid API key
+ * or signed-in account cannot loop millions of image generations.
+ *
+ * @private internal constant of paid AI proxy routes
+ */
+const PAID_API_RATE_LIMITS: Readonly<Record<PaidApiRequestTier, PaidApiRateLimitDefinition>> = {
+    AUDIO_TRANSCRIPTION: { maxRequestsPerWindow: 60, windowMs: 60_000 },
+    TEXT_TO_SPEECH: { maxRequestsPerWindow: 60, windowMs: 60_000 },
+    IMAGE_GENERATION: { maxRequestsPerWindow: 20, windowMs: 60_000 },
+};
+
+/**
+ * In-memory map of request timestamps keyed by `tier|identity`.
+ *
+ * In-memory state is intentional: the sliding window is a defense in depth on
+ * top of authentication, and we do not want to add a Redis dependency just for
+ * this guard. Operators who run multiple replicas should still configure a
+ * front-door rate limiter; this layer prevents single-process abuse.
+ *
+ * @private internal constant of paid AI proxy routes
+ */
+const PAID_API_REQUEST_TIMESTAMPS: Map<string, Array<number>> = new Map();
+
+/**
+ * Successful guard outcome describing the authenticated identity.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardSuccess = {
+    readonly ok: true;
+    /**
+     * Stable identity key used for rate limiting and audit logs.
+     *
+     * Derived from (in order): the signed session username, the bearer API key
+     * hash, and finally the request IP for anonymous fallbacks (which should
+     * not happen because `authenticatedOnly` rejects them).
+     */
+    readonly identityKey: string;
+};
+
+/**
+ * Failure outcome containing the response that should be returned verbatim.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardFailure = {
+    readonly ok: false;
+    readonly response: NextResponse;
+};
+
+/**
+ * Guard outcome returned by `guardPaidApiRequest`.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export type PaidApiRequestGuardResult = PaidApiRequestGuardSuccess | PaidApiRequestGuardFailure;
+
+/**
+ * Combined authentication and per-identity rate-limit check for routes that
+ * proxy directly to paid third-party AI providers (OpenAI, ElevenLabs, ...).
+ *
+ * The guard enforces two invariants in a single place so that every paid
+ * endpoint stays consistent (DRY) and no new endpoint accidentally forgets
+ * authentication or rate limiting:
+ *
+ * 1. The caller must be authenticated via a signed session cookie or a valid
+ *    `Authorization: Bearer ptbk_...` API key.
+ * 2. The caller must stay within the per-tier sliding-window budget defined
+ *    in `PAID_API_RATE_LIMITS`.
+ *
+ * @param request - Incoming HTTP request.
+ * @param tier - Paid call category determining the applicable budget.
+ * @returns Either `{ ok: true, identityKey }` or `{ ok: false, response }`.
+ *
+ * @private internal helper of paid AI proxy routes
+ */
+export async function guardPaidApiRequest(
+    request: NextRequest,
+    tier: PaidApiRequestTier,
+): Promise<PaidApiRequestGuardResult> {
+    const apiKeyValidation = await validateApiKey(request);
+    if (!apiKeyValidation.isValid) {
+        return {
+            ok: false,
+            response: NextResponse.json(
+                {
+                    error: {
+                        message: apiKeyValidation.error || 'Authentication required',
+                        type: 'authentication_error',
+                    },
+                },
+                { status: 401 },
+            ),
+        };
+    }
+
+    const identityKey = await resolvePaidApiIdentityKey(request, apiKeyValidation.token);
+
+    const rateLimitCheck = checkPaidApiRateLimit(tier, identityKey);
+    if (!rateLimitCheck.isAllowed) {
+        return {
+            ok: false,
+            response: NextResponse.json(
+                {
+                    error: {
+                        message: spaceTrim(`
+                            Rate limit exceeded for paid AI proxy.
+
+                            **Tier:** \`${tier}\`
+                            **Limit:** ${rateLimitCheck.maxRequestsPerWindow} requests per ${Math.round(
+                            rateLimitCheck.windowMs / 1000,
+                        )} seconds.
+
+                            Try again in **${rateLimitCheck.retryAfterSeconds}** seconds.
+                        `),
+                        type: 'rate_limit_exceeded',
+                    },
+                },
+                {
+                    status: 429,
+                    headers: {
+                        'Retry-After': String(rateLimitCheck.retryAfterSeconds),
+                    },
+                },
+            ),
+        };
+    }
+
+    return { ok: true, identityKey };
+}
+
+/**
+ * Resolves a stable per-identity key used to bucket rate-limit counts.
+ *
+ * @param request - Incoming HTTP request.
+ * @param apiKeyToken - Optional bearer token recovered by `validateApiKey`.
+ * @returns Identity key prefixed with the source kind (`user:`, `apikey:`, or `ip:`).
+ *
+ * @private internal helper of `guardPaidApiRequest`
+ */
+async function resolvePaidApiIdentityKey(request: NextRequest, apiKeyToken: string | undefined): Promise<string> {
+    const session = await getSession();
+    if (session?.username) {
+        return `user:${session.username}`;
+    }
+
+    if (apiKeyToken) {
+        return `apikey:${createHash('sha256').update(apiKeyToken).digest('hex')}`;
+    }
+
+    return `ip:${getRequestIp(request)}`;
+}
+
+/**
+ * Sliding-window rate-limit check shared by all paid AI proxy tiers.
+ *
+ * @param tier - Paid call category determining the applicable budget.
+ * @param identityKey - Stable per-identity key from `resolvePaidApiIdentityKey`.
+ * @returns Decision describing whether the request is allowed and, if not, how long to wait.
+ *
+ * @private internal helper of `guardPaidApiRequest`
+ */
+function checkPaidApiRateLimit(
+    tier: PaidApiRequestTier,
+    identityKey: string,
+): {
+    readonly isAllowed: boolean;
+    readonly maxRequestsPerWindow: number;
+    readonly windowMs: number;
+    readonly retryAfterSeconds: number;
+} {
+    const { maxRequestsPerWindow, windowMs } = PAID_API_RATE_LIMITS[tier];
+    const bucketKey = `${tier}|${identityKey}`;
+    const now = Date.now();
+    const windowStart = now - windowMs;
+
+    const existingTimestamps = PAID_API_REQUEST_TIMESTAMPS.get(bucketKey) || [];
+    const recentTimestamps = existingTimestamps.filter((timestamp) => timestamp > windowStart);
+
+    if (recentTimestamps.length >= maxRequestsPerWindow) {
+        const oldestRelevantTimestamp = recentTimestamps[0]!;
+        const retryAfterMs = Math.max(1_000, oldestRelevantTimestamp + windowMs - now);
+        PAID_API_REQUEST_TIMESTAMPS.set(bucketKey, recentTimestamps);
+        return {
+            isAllowed: false,
+            maxRequestsPerWindow,
+            windowMs,
+            retryAfterSeconds: Math.ceil(retryAfterMs / 1_000),
+        };
+    }
+
+    recentTimestamps.push(now);
+    PAID_API_REQUEST_TIMESTAMPS.set(bucketKey, recentTimestamps);
+
+    return {
+        isAllowed: true,
+        maxRequestsPerWindow,
+        windowMs,
+        retryAfterSeconds: 0,
+    };
+}
+
+// Note: [🟢] Code for the Agents Server paid AI request guard should never be published into packages that could be imported into browser environment

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

@@ -0,0 +1,59 @@
+import type { AgentsServerDatabase } from '../database/schema';
+
+/**
+ * Database row shape for the `User` table.
+ */
+type UserRow = AgentsServerDatabase['public']['Tables']['User']['Row'];
+
+/**
+ * Public user shape safe to send to browser UI.
+ *
+ * @private internal Agents Server API shape
+ */
+export type PublicUser = Pick<
+    UserRow,
+    'id' | 'username' | 'isAdmin' | 'createdAt' | 'updatedAt' | 'profileImageUrl'
+> & {
+    /**
+     * Email address from external authentication providers.
+     */
+    readonly email?: string | null;
+    /**
+     * Human-readable display name from external authentication providers.
+     */
+    readonly displayName?: string | null;
+    /**
+     * Authentication provider marker such as `LOCAL` or `SHIBBOLETH`.
+     */
+    readonly authenticationProvider?: string | null;
+};
+
+/**
+ * Supabase projection for user fields safe to return from UI-facing endpoints.
+ *
+ * @private internal Agents Server API projection
+ */
+export const PUBLIC_USER_SELECT_COLUMNS: string =
+    'id, username, isAdmin, createdAt, updatedAt, profileImageUrl, email, displayName, authenticationProvider';
+
+/**
+ * Maps a database user projection into the public user response shape.
+ *
+ * @param row - User projection loaded from the database.
+ * @returns User data safe to serialize to the browser.
+ *
+ * @private internal Agents Server API mapper
+ */
+export function toPublicUser(row: PublicUser): PublicUser {
+    return {
+        id: row.id,
+        username: row.username,
+        isAdmin: row.isAdmin,
+        createdAt: row.createdAt,
+        updatedAt: row.updatedAt,
+        profileImageUrl: row.profileImageUrl ?? null,
+        email: row.email ?? null,
+        displayName: row.displayName ?? null,
+        authenticationProvider: row.authenticationProvider ?? null,
+    };
+}

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

@@ -39,6 +39,15 @@ export type SpawnAgentLimits = {
     readonly rateLimitWindowMs: number;
 };
 
+/**
+ * Dedicated subset consumed by the local coding-agent runner.
+ *
+ * @private internal Agents Server type
+ */
+export type LocalAgentRunnerLimits = {
+    readonly maxFailedAttempts: number;
+};
+
 /**
  * Row shape loaded from the dedicated `ServerLimit` table.
  *
@@ -250,6 +259,20 @@ export async function getSpawnAgentLimits(): Promise<SpawnAgentLimits> {
     };
 }
 
+/**
+ * Loads the local coding-agent runner retry limits.
+ *
+ * @returns Dedicated local agent runner limits.
+ *
+ * @private internal Agents Server helper
+ */
+export async function getLocalAgentRunnerLimits(): Promise<LocalAgentRunnerLimits> {
+    const limits = await getServerLimits();
+    return {
+        maxFailedAttempts: limits[SERVER_LIMIT_KEYS.LOCAL_AGENT_RUNNER_MAX_FAILED_ATTEMPTS],
+    };
+}
+
 /**
  * Normalizes one arbitrary key/value object into the supported dedicated server-limit payload.
  *
@@ -277,7 +300,9 @@ export function normalizeServerLimitValues(rawValue: Record<string, unknown>): S
  */
 async function loadLegacyServerLimits(): Promise<Partial<Record<ServerLimitKey, unknown>>> {
     const metadata = await getMetadataMap(DEPRECATED_LIMIT_METADATA_KEYS);
-    const normalizedToolUsageLimits = normalizeToolUsageLimits(parseJsonValue(metadata[TOOL_USAGE_LIMITS_METADATA_KEY]));
+    const normalizedToolUsageLimits = normalizeToolUsageLimits(
+        parseJsonValue(metadata[TOOL_USAGE_LIMITS_METADATA_KEY]),
+    );
 
     return {
         [SERVER_LIMIT_KEYS.TIMEOUT_MAX_ACTIVE_PER_CHAT]: normalizedToolUsageLimits.timeout.maxActivePerChat,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/bootstrapManagedServer.ts

@@ -5,7 +5,6 @@ import {
     acquireMigrationExecutionLock,
     releaseMigrationExecutionLock,
 } from '../../../database/acquireMigrationExecutionLock';
-import { scheduleDefaultFederatedAgentsSync } from '../../defaultFederatedAgents/scheduleDefaultFederatedAgentsSync';
 import { createServerPublicUrl, invalidateRegisteredServersCache } from '../../serverRegistry';
 import type { CreateServerResult } from '../createManagedServer';
 import { resolveManagedServerConnectionString } from '../resolveManagedServerConnectionString';
@@ -14,6 +13,7 @@ import { createFailedServerResult } from './createFailedServerResult';
 import { createSqlRecorder } from './createSqlRecorder';
 import { insertManagedServerRegistryRow } from './insertManagedServerRegistryRow';
 import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
+import { seedServerCoreAgents } from './seedServerCoreAgents';
 import { seedServerDefaultAgents } from './seedServerDefaultAgents';
 import { seedServerMetadata } from './seedServerMetadata';
 import { seedServerUsers } from './seedServerUsers';
@@ -47,16 +47,15 @@ export async function bootstrapManagedServer(input: NormalizedCreateServerInput)
         await applyManagedServerMigrations(client, input, sqlRecorder, migrationLogger);
         await seedServerUsers(client, input, sqlRecorder);
         await seedServerMetadata(client, input, sqlRecorder);
-        await seedServerDefaultAgents(client, input, sqlRecorder);
+        if (input.isDefaultAgentsInstalled) {
+            await seedServerDefaultAgents(client, input, sqlRecorder);
+        }
+        await seedServerCoreAgents(client, input, sqlRecorder);
 
         await client.query('COMMIT');
         sqlRecorder.addStatement('COMMIT');
 
         invalidateRegisteredServersCache();
-        scheduleDefaultFederatedAgentsSync({
-            tablePrefix: server.tablePrefix,
-            localServerUrl: createServerPublicUrl(server.domain).href,
-        });
 
         return {
             ok: true,

package/apps/agents-server/src/utils/serverManagement/createManagedServer/normalizeCreateServerInput.ts

@@ -51,6 +51,11 @@ export type NormalizedCreateServerInput = {
      * Initial metadata rows inserted during bootstrap.
      */
     readonly metadataEntries: ReadonlyArray<ServerMetadataSeedEntry>;
+
+    /**
+     * Whether bundled default agents from `agents/default` should be created during bootstrap.
+     */
+    readonly isDefaultAgentsInstalled: boolean;
 };
 
 /**
@@ -103,5 +108,6 @@ export function normalizeCreateServerInput(input: CreateServerInput): Normalized
             iconUrl,
             initialSettings: input.initialSettings,
         }),
+        isDefaultAgentsInstalled: input.isDefaultAgentsInstalled !== false,
     };
 }

package/apps/agents-server/src/utils/serverManagement/createManagedServer/seedServerCoreAgents.ts

@@ -0,0 +1,162 @@
+import type { Client } from 'pg';
+import { createAgentPersistenceRecords } from '../../../../../../src/collection/agent-collection/constructors/agent-collection-in-supabase/createAgentPersistenceRecords';
+import { DEFAULT_AGENT_VISIBILITY } from '../../agentVisibility';
+import { CORE_AGENT_DIRECTORY_NAME, loadCoreAgentBooks } from '../../defaultAgents/loadDefaultAgentBooks';
+import { createInsertStatement, quoteIdentifier, type SqlRecorder } from './createSqlRecorder';
+import type { NormalizedCreateServerInput } from './normalizeCreateServerInput';
+
+/**
+ * Loads bundled `.core` agent books from the repository and persists them into the newly created server.
+ *
+ * Each `*.book` file in `agents/default/.core` becomes one persisted agent in the `.core` folder with its initial
+ * history snapshot.
+ *
+ * @param client - Connected PostgreSQL client inside the bootstrap transaction.
+ * @param input - Normalized create-server payload.
+ * @param sqlRecorder - Mutable SQL dump recorder.
+ *
+ * @private function of createManagedServer
+ */
+export async function seedServerCoreAgents(
+    client: Client,
+    input: NormalizedCreateServerInput,
+    sqlRecorder: SqlRecorder,
+): Promise<void> {
+    const coreAgentBooks = await loadCoreAgentBooks();
+    if (coreAgentBooks.length === 0) {
+        return;
+    }
+
+    const coreFolderId = await insertCoreFolder(client, input, sqlRecorder);
+    const agentTableIdentifier = quoteIdentifier(`${input.tablePrefix}Agent`);
+    const agentHistoryTableIdentifier = quoteIdentifier(`${input.tablePrefix}AgentHistory`);
+
+    for (const [index, coreAgentBook] of coreAgentBooks.entries()) {
+        const createdAt = new Date().toISOString();
+        const { agentInsertRecord, agentHistoryInsertRecord } = createAgentPersistenceRecords(
+            coreAgentBook,
+            { folderId: coreFolderId, sortOrder: index, visibility: DEFAULT_AGENT_VISIBILITY },
+            createdAt,
+        );
+
+        await client.query(
+            `
+                INSERT INTO ${agentTableIdentifier} (
+                    "agentName",
+                    "createdAt",
+                    "updatedAt",
+                    "permanentId",
+                    "agentHash",
+                    "agentSource",
+                    "agentProfile",
+                    "promptbookEngineVersion",
+                    "usage",
+                    "folderId",
+                    "sortOrder",
+                    "visibility"
+                )
+                VALUES ($1, $2, $3, $4, $5, $6, $7::jsonb, $8, $9::jsonb, $10, $11, $12)
+            `,
+            [
+                agentInsertRecord.agentName,
+                agentInsertRecord.createdAt,
+                agentInsertRecord.updatedAt,
+                agentInsertRecord.permanentId,
+                agentInsertRecord.agentHash,
+                agentInsertRecord.agentSource,
+                JSON.stringify(agentInsertRecord.agentProfile),
+                agentInsertRecord.promptbookEngineVersion,
+                JSON.stringify(agentInsertRecord.usage),
+                coreFolderId,
+                agentInsertRecord.sortOrder ?? index,
+                agentInsertRecord.visibility ?? DEFAULT_AGENT_VISIBILITY,
+            ],
+        );
+        sqlRecorder.addStatement(
+            createInsertStatement(`${input.tablePrefix}Agent`, {
+                ...agentInsertRecord,
+                agentProfile: JSON.stringify(agentInsertRecord.agentProfile),
+                usage: JSON.stringify(agentInsertRecord.usage),
+                folderId: coreFolderId,
+                sortOrder: agentInsertRecord.sortOrder ?? index,
+                visibility: agentInsertRecord.visibility ?? DEFAULT_AGENT_VISIBILITY,
+            }),
+        );
+
+        await client.query(
+            `
+                INSERT INTO ${agentHistoryTableIdentifier} (
+                    "createdAt",
+                    "agentName",
+                    "permanentId",
+                    "agentHash",
+                    "previousAgentHash",
+                    "agentSource",
+                    "promptbookEngineVersion",
+                    "versionName"
+                )
+                VALUES ($1, $2, $3, $4, $5, $6, $7, $8)
+            `,
+            [
+                agentHistoryInsertRecord.createdAt,
+                agentHistoryInsertRecord.agentName,
+                agentHistoryInsertRecord.permanentId,
+                agentHistoryInsertRecord.agentHash,
+                agentHistoryInsertRecord.previousAgentHash,
+                agentHistoryInsertRecord.agentSource,
+                agentHistoryInsertRecord.promptbookEngineVersion,
+                agentHistoryInsertRecord.versionName,
+            ],
+        );
+        sqlRecorder.addStatement(createInsertStatement(`${input.tablePrefix}AgentHistory`, agentHistoryInsertRecord));
+    }
+}
+
+/**
+ * Inserts the `.core` folder row for the newly bootstrapped server.
+ *
+ * @param client - Connected PostgreSQL client inside the bootstrap transaction.
+ * @param input - Normalized create-server payload.
+ * @param sqlRecorder - Mutable SQL dump recorder.
+ * @returns Identifier of the inserted `.core` folder.
+ *
+ * @private function of createManagedServer
+ */
+async function insertCoreFolder(
+    client: Client,
+    input: NormalizedCreateServerInput,
+    sqlRecorder: SqlRecorder,
+): Promise<number> {
+    const agentFolderTableIdentifier = quoteIdentifier(`${input.tablePrefix}AgentFolder`);
+    const createdAt = new Date().toISOString();
+    const insertResult = await client.query<{ id: number }>(
+        `
+            INSERT INTO ${agentFolderTableIdentifier} (
+                "name",
+                "parentId",
+                "sortOrder",
+                "icon",
+                "color",
+                "createdAt",
+                "updatedAt"
+            )
+            VALUES ($1, NULL, $2, NULL, NULL, $3, NULL)
+            RETURNING "id"
+        `,
+        [CORE_AGENT_DIRECTORY_NAME, 0, createdAt],
+    );
+
+    sqlRecorder.addStatement(
+        createInsertStatement(`${input.tablePrefix}AgentFolder`, {
+            name: CORE_AGENT_DIRECTORY_NAME,
+            parentId: null,
+            sortOrder: 0,
+            icon: null,
+            color: null,
+            createdAt,
+            updatedAt: null,
+        }),
+    );
+
+    return insertResult.rows[0].id;
+}