@flowdular/sdk 0.2.3 → 0.3.0

package/modules/agents/src/services/agent-service.ts

@@ -19,8 +19,11 @@ import {
 } from '../domain/context-variables.ts';
 import { groupRunTimeline } from '../domain/run-timeline.ts';
 import type {
-	AgentAuditPage,
+	AgentAuditEvent,
+	AgentAuditListQuery,
 	AgentDefinition,
+	AgentListPage,
+	AgentListQuery,
 	AgentDefinitionRevision,
 	ModuleAgentBinding,
 	ModuleAgentDefinition,
@@ -28,6 +31,7 @@ import type {
 	AgentProviderConnection,
 	AgentRun,
 	AgentRunDetail,
+	AgentRunListQuery,
 	AgentRunTimeline,
 	AgentProcedure,
 	AgentProcedureSnapshot,
@@ -41,6 +45,14 @@ import type {
 	UpdateModuleAgentBindingInput,
 } from '../domain/types.ts';
 import type { AgentSettingsReader } from '../settings.ts';
+import {
+	AGENT_METERS,
+	estimateRunTokens,
+	meterPeriod,
+	METER_LIMIT_EXCEEDED,
+	type MeterRegistry,
+	type MeterRegistryResolver,
+} from './metering.ts';
 import {
 	DuplicateAgentKeyError,
 	DuplicateAgentProcedureKeyError,
@@ -53,8 +65,9 @@ import type { AgentWorker } from './worker.ts';
 import { normalizeModuleAgentDefinitions } from '../server/define-agent.ts';
 
 const DEFAULT_MAX_OUTPUT_TOKENS = 4_096;
-const DEFAULT_AUDIT_PAGE = 50;
-const MAX_AUDIT_PAGE = 100;
+/* One page of any list this service serves; an endpoint may bound lower. */
+const MAX_LIST_PAGE = 200;
+const DEFAULT_LIST_PAGE = 50;
 const TERMINAL_STATUSES: readonly AgentRun['status'][] = [
 	'succeeded',
 	'failed',
@@ -97,22 +110,6 @@ function outputContract(value: AgentOutputContract): AgentOutputContract {
 	return { kind: 'json-schema', name, schema: value.schema };
 }
 
-/* `occurredAt:sequence` of the last row of the previous page. Both halves are
-   non-negative integers; anything else is a client error, never a silent
-   first-page fallback. */
-function auditCursor(
-	raw: string | null,
-): { readonly occurredAt: number; readonly sequence: number } | null {
-	if (raw === null || raw === '') return null;
-	const match = /^(\d+):(\d+)$/.exec(raw);
-	const occurredAt = match ? Number(match[1]) : NaN;
-	const sequence = match ? Number(match[2]) : NaN;
-	if (!Number.isSafeInteger(occurredAt) || !Number.isSafeInteger(sequence)) {
-		throw new AgentServiceError('INVALID_CURSOR', 'cursor is malformed.', 400);
-	}
-	return { occurredAt, sequence };
-}
-
 export class AgentServiceError extends Error {
 	constructor(
 		readonly code: string,
@@ -124,6 +121,12 @@ export class AgentServiceError extends Error {
 	}
 }
 
+function pageLimit(limit: number): number {
+	return Number.isSafeInteger(limit)
+		? Math.min(Math.max(1, limit), MAX_LIST_PAGE)
+		: DEFAULT_LIST_PAGE;
+}
+
 function bounded(
 	value: string,
 	field: string,
@@ -311,8 +314,97 @@ export class AgentService {
 		private readonly now: () => number = Date.now,
 		private readonly settings?: AgentSettingsReader,
 		private readonly budget?: AgentBudgetGuard,
+		private readonly meters?: MeterRegistryResolver,
 	) {}
 
+	/**
+	 * The workspace's monthly allowance, checked before a run exists. A run
+	 * costs it one run and the tokens the run may read and write, and
+	 * metering.core answers each meter's own month, so both are asked: checking
+	 * the tokens alone let a workspace whose run allowance was spent keep
+	 * starting runs. What to do about a refusal is this module's decision, so it
+	 * is recorded in this module's own trail under the stable metering code and
+	 * the run is never created. An estimate may be wrong in either direction;
+	 * the settled run replaces it with what it actually used.
+	 */
+	async #assertMeterCapacity(
+		tenantId: string,
+		actorId: string,
+		agentId: string,
+		estimatedTokens: number,
+	): Promise<void> {
+		const meters = this.meters?.();
+		if (!meters) return;
+		/* The run first: a workspace out of runs is refused before it is also
+		   measured against the token allowance. */
+		await this.#assertMeter(meters, tenantId, actorId, agentId, {
+			meter: AGENT_METERS.runs,
+			amount: 1,
+			allowance: 'agent runs',
+		});
+		await this.#assertMeter(meters, tenantId, actorId, agentId, {
+			meter: AGENT_METERS.runTokens,
+			amount: estimatedTokens,
+			allowance: 'agent tokens',
+		});
+	}
+
+	/**
+	 * One meter. A refused verdict stands until the month turns or the limit is
+	 * raised, so the trail records it once per workspace, meter and month: a
+	 * caller retrying a refused enqueue would otherwise write the same fact to
+	 * the chain as fast as it could ask.
+	 */
+	async #assertMeter(
+		meters: MeterRegistry,
+		tenantId: string,
+		actorId: string,
+		agentId: string,
+		request: {
+			readonly meter: string;
+			readonly amount: number;
+			readonly allowance: string;
+		},
+	): Promise<void> {
+		const verdict = await meters.check({
+			tenantId,
+			meter: request.meter,
+			amount: request.amount,
+		});
+		if (verdict.verdict !== 'refused') return;
+		const limit = verdict.limit ?? 0;
+		const at = this.now();
+		if (
+			await this.repository.claimMeterRefusal(
+				tenantId,
+				request.meter,
+				meterPeriod(at),
+				at,
+			)
+		) {
+			await this.repository.appendAuditEvent({
+				tenantId,
+				actorId,
+				action: 'agent-run.meter-refused',
+				subjectType: 'agent',
+				subjectId: agentId,
+				metadata: {
+					code: METER_LIMIT_EXCEEDED,
+					meter: request.meter,
+					amount: request.amount,
+					used: verdict.used,
+					limit,
+				},
+				occurredAt: at,
+			});
+		}
+		throw new AgentServiceError(
+			METER_LIMIT_EXCEEDED,
+			`This workspace has used ${verdict.used} of its ${limit} ${request.allowance} for the month.`,
+			409,
+		);
+	}
+
 	workerStatus(): AgentWorkerStatus {
 		return this.worker.status();
 	}
@@ -520,18 +612,23 @@ export class AgentService {
 		);
 	}
 
+	async listAgentsPage(
+		tenantId: string,
+		query: AgentListQuery,
+	): Promise<AgentListPage> {
+		return await this.repository.listAgentsPage(
+			bounded(tenantId, 'tenantId', 1, 128),
+			{ ...query, limit: pageLimit(query.limit) },
+		);
+	}
+
 	async pageAuditEvents(
 		tenantId: string,
-		cursor: string | null,
-		limit: number,
-	): Promise<AgentAuditPage> {
-		const size = Number.isSafeInteger(limit)
-			? Math.min(Math.max(1, Math.trunc(limit)), MAX_AUDIT_PAGE)
-			: DEFAULT_AUDIT_PAGE;
+		query: AgentAuditListQuery,
+	): Promise<readonly AgentAuditEvent[]> {
 		return await this.repository.pageAuditEvents(
 			bounded(tenantId, 'tenantId', 1, 128),
-			auditCursor(cursor),
-			size,
+			{ ...query, limit: pageLimit(query.limit) },
 		);
 	}
 
@@ -732,6 +829,7 @@ export class AgentService {
 		input: CreateAgentInput,
 	): Promise<AgentDefinition> {
 		const trustedTenantId = bounded(tenantId, 'tenantId', 1, 128);
+		await this.settings?.prime(trustedTenantId);
 		// Provider references are stored connection IDs, not tool identifiers.
 		const provider = bounded(
 			input.provider || (this.settings?.defaultProvider(trustedTenantId) ?? ''),
@@ -959,11 +1057,21 @@ export class AgentService {
 		});
 	}
 
-	async listRuns(tenantId: string, limit = 100): Promise<readonly AgentRun[]> {
-		const boundedLimit = Math.max(1, Math.min(250, Math.trunc(limit)));
+	async listRuns(
+		tenantId: string,
+		query: Partial<AgentRunListQuery> = {},
+	): Promise<readonly AgentRun[]> {
 		return await this.repository.listRuns(
 			bounded(tenantId, 'tenantId', 1, 128),
-			boundedLimit,
+			{
+				direction: query.direction ?? 'desc',
+				status: query.status ?? null,
+				agentId: query.agentId ?? null,
+				trigger: query.trigger ?? null,
+				search: query.search ?? null,
+				after: query.after ?? null,
+				limit: pageLimit(query.limit ?? 50),
+			},
 		);
 	}
 
@@ -1380,6 +1488,16 @@ export class AgentService {
 				409,
 			);
 		}
+		await this.#assertMeterCapacity(
+			trustedTenantId,
+			actor.id,
+			retained.agentId,
+			estimateRunTokens({
+				instructions,
+				input: prompt,
+				maxOutputTokens: retained.maxOutputTokens,
+			}),
+		);
 		const queuedAt = this.now();
 		const run: AgentRun = {
 			id: randomUUID(),
@@ -1700,6 +1818,16 @@ export class AgentService {
 				409,
 			);
 		}
+		await this.#assertMeterCapacity(
+			trustedTenantId,
+			identity,
+			agent.id,
+			estimateRunTokens({
+				instructions,
+				input: prompt,
+				maxOutputTokens: agent.maxOutputTokens,
+			}),
+		);
 		const queuedAt = this.now();
 		const run: AgentRun = {
 			id: randomUUID(),

package/modules/agents/src/services/credential-rotation.ts

@@ -0,0 +1,185 @@
+import type { DatabaseHandle } from '@flowdular/sdk/database';
+import type { AgentProviderKind } from '../domain/types.ts';
+import { credentialContext, type CredentialVault } from './credential-vault.ts';
+
+/** Rows re-sealed inside one tenant-scoped transaction. */
+export const CREDENTIAL_ROTATION_BATCH = 200;
+
+export const CREDENTIAL_ROTATION_TABLE = 'agent_provider_connections';
+
+export interface CredentialKeyCount {
+	readonly keyId: string;
+	readonly rows: number;
+}
+
+export interface CredentialRotationReport {
+	readonly table: string;
+	/** Key id every row should end on: the current key of the vault. */
+	readonly currentKeyId: string;
+	readonly counts: readonly CredentialKeyCount[];
+	/** Rows on a retired key when the run started. */
+	readonly stale: number;
+	readonly tenants: number;
+	readonly rotated: number;
+	/** Rows a concurrent write changed between the read and the update. */
+	readonly skipped: number;
+}
+
+export interface CredentialRotationOptions {
+	/** Tenant-scoped handle. Every read and write of a row runs on it. */
+	readonly runtime: DatabaseHandle;
+	/** Cross-tenant handle. It is granted the key ids and nothing else. */
+	readonly background: DatabaseHandle;
+	readonly vault: CredentialVault;
+	readonly apply?: boolean;
+	readonly batchSize?: number;
+}
+
+interface StaleRow {
+	id: string;
+	kind: AgentProviderKind;
+	credential_key_id: string;
+	credential_iv: string;
+	credential_tag: string;
+	credential_ciphertext: string;
+}
+
+const SQL = {
+	counts: `SELECT credential_key_id AS key_id, count(*) AS row_count
+	         FROM agent_provider_connections
+	         GROUP BY credential_key_id
+	         ORDER BY credential_key_id`,
+	staleTenants: `SELECT tenant_id, count(*) AS row_count
+	               FROM agent_provider_connections
+	               WHERE credential_key_id <> $1
+	               GROUP BY tenant_id
+	               ORDER BY tenant_id`,
+	/* Paged by primary key: a row the optimistic update skipped stays stale, so
+	   a query that only asked for stale rows would return it forever. */
+	staleBatch: `SELECT id, kind, credential_key_id, credential_iv,
+	                    credential_tag, credential_ciphertext
+	             FROM agent_provider_connections
+	             WHERE tenant_id = $1 AND credential_key_id <> $2 AND id > $3
+	             ORDER BY id
+	             LIMIT $4`,
+	/* The envelope the row still holds is the optimistic check: a credential
+	   rewritten by the application in between keeps its own value. Nothing
+	   outside the envelope columns changes, so a re-seal is not an edit. */
+	reseal: `UPDATE agent_provider_connections
+	         SET credential_key_id = $1, credential_iv = $2,
+	             credential_tag = $3, credential_ciphertext = $4
+	         WHERE tenant_id = $5 AND id = $6 AND credential_ciphertext = $7`,
+};
+
+function count(value: number | bigint | string): number {
+	const normalized = Number(value);
+	if (!Number.isSafeInteger(normalized)) {
+		throw new Error('The agents database returned an invalid count.');
+	}
+	return normalized;
+}
+
+/**
+ * Re-seals every stored provider credential that is not on the current key.
+ * The inventory is read once across tenants, and each batch of rows is read,
+ * decrypted, re-sealed and written inside one transaction scoped to the tenant
+ * that owns them. It is idempotent: a second run finds nothing to do.
+ */
+export async function rotateProviderCredentials(
+	options: CredentialRotationOptions,
+): Promise<CredentialRotationReport> {
+	const currentKeyId = options.vault.keyId;
+	const batchSize = options.batchSize ?? CREDENTIAL_ROTATION_BATCH;
+	const inventory = await options.background.transaction(
+		async (transaction) => ({
+			counts: (
+				await transaction.query<{
+					key_id: string;
+					row_count: number | bigint | string;
+				}>({ text: SQL.counts })
+			).rows,
+			stale: (
+				await transaction.query<{
+					tenant_id: string;
+					row_count: number | bigint | string;
+				}>({ text: SQL.staleTenants, parameters: [currentKeyId] })
+			).rows,
+		}),
+		{ access: 'read' },
+	);
+	const counts = inventory.counts.map((row) => ({
+		keyId: row.key_id,
+		rows: count(row.row_count),
+	}));
+	const stale = inventory.stale.reduce(
+		(total, row) => total + count(row.row_count),
+		0,
+	);
+	const report = {
+		table: CREDENTIAL_ROTATION_TABLE,
+		currentKeyId,
+		counts,
+		stale,
+		tenants: inventory.stale.length,
+	};
+	if (options.apply !== true) {
+		return { ...report, rotated: 0, skipped: 0 };
+	}
+	let rotated = 0;
+	let skipped = 0;
+	for (const { tenant_id: tenantId } of inventory.stale) {
+		let cursor = '';
+		for (;;) {
+			const batch = await options.runtime.transaction(
+				async (transaction) => {
+					const rows = (
+						await transaction.query<StaleRow>({
+							text: SQL.staleBatch,
+							parameters: [tenantId, currentKeyId, cursor, batchSize],
+						})
+					).rows;
+					let written = 0;
+					for (const row of rows) {
+						const context = credentialContext({
+							tenantId,
+							id: row.id,
+							kind: row.kind,
+						});
+						const sealed = options.vault.encrypt(
+							options.vault.decrypt(
+								{
+									keyId: row.credential_key_id,
+									iv: row.credential_iv,
+									tag: row.credential_tag,
+									ciphertext: row.credential_ciphertext,
+								},
+								context,
+							),
+							context,
+						);
+						const result = await transaction.execute({
+							text: SQL.reseal,
+							parameters: [
+								sealed.keyId,
+								sealed.iv,
+								sealed.tag,
+								sealed.ciphertext,
+								tenantId,
+								row.id,
+								row.credential_ciphertext,
+							],
+						});
+						written += result.affectedRows;
+					}
+					return { read: rows.length, written, last: rows.at(-1)?.id };
+				},
+				{ access: 'write', tenantId },
+			);
+			rotated += batch.written;
+			skipped += batch.read - batch.written;
+			if (batch.read < batchSize || batch.last === undefined) break;
+			cursor = batch.last;
+		}
+	}
+	return { ...report, rotated, skipped };
+}

package/modules/agents/src/services/credential-vault.ts

@@ -1,9 +1,4 @@
-import {
-	createCipheriv,
-	createDecipheriv,
-	createHash,
-	randomBytes,
-} from 'node:crypto';
+import { randomBytes } from 'node:crypto';
 import {
 	closeSync,
 	mkdirSync,
@@ -12,7 +7,14 @@ import {
 	writeFileSync,
 } from 'node:fs';
 import { dirname } from 'node:path';
+import {
+	createKeyring,
+	KeyringError,
+	parsePreviousKeys,
+	type Keyring,
+} from '@flowdular/sdk/kernel';
 import { flowdularLocalDataPath } from '@flowdular/sdk/kernel/legacy-local-state';
+import type { AgentProviderKind } from '../domain/types.ts';
 
 export interface EncryptedCredential {
 	readonly keyId: string;
@@ -21,36 +23,53 @@ export interface EncryptedCredential {
 	readonly ciphertext: string;
 }
 
+/**
+ * The additional data every provider credential envelope is bound to. It is
+ * part of the stored envelope: re-sealing a row under a new key must rebuild
+ * exactly this string, so it lives with the envelope format and not with a
+ * service.
+ */
+export function credentialContext(connection: {
+	readonly tenantId: string;
+	readonly id: string;
+	readonly kind: AgentProviderKind;
+}): string {
+	return `${connection.tenantId}:${connection.id}:${connection.kind}`;
+}
+
 export interface CredentialVault {
+	/** Key id every new envelope is written with; stored rows may carry older ones. */
+	readonly keyId: string;
 	encrypt(credential: string, context: string): EncryptedCredential;
 	decrypt(envelope: EncryptedCredential, context: string): string;
 }
 
-function encryptionKey(value: string): Buffer {
+function encryptionKey(
+	value: string,
+	variable = 'FD_AGENT_CREDENTIAL_KEY',
+): Buffer {
 	const key = Buffer.from(value.trim(), 'base64');
 	if (key.byteLength !== 32) {
 		key.fill(0);
-		throw new Error(
-			'FD_AGENT_CREDENTIAL_KEY must be a base64-encoded 32-byte key.',
-		);
+		throw new Error(`${variable} must be a base64-encoded 32-byte key.`);
 	}
 	return key;
 }
 
-function keyId(key: Buffer): string {
-	return createHash('sha256').update(key).digest('hex').slice(0, 16);
-}
-
 export class AesGcmCredentialVault implements CredentialVault {
-	readonly #key: Buffer;
-	readonly #keyId: string;
+	readonly #keyring: Keyring;
 
-	constructor(key: Buffer) {
+	/* `previous` holds the keys a rotation has not finished retiring: they open
+	   stored rows, and nothing is ever written with them. */
+	constructor(key: Buffer, previous: readonly Buffer[] = []) {
 		if (key.byteLength !== 32) {
 			throw new Error('Credential encryption requires a 32-byte key.');
 		}
-		this.#key = Buffer.from(key);
-		this.#keyId = keyId(key);
+		this.#keyring = createKeyring({ current: key, previous });
+	}
+
+	get keyId(): string {
+		return this.#keyring.keyId;
 	}
 
 	encrypt(credential: string, context: string): EncryptedCredential {
@@ -60,37 +79,36 @@ export class AesGcmCredentialVault implements CredentialVault {
 				'Provider credential must contain 8 to 16384 characters.',
 			);
 		}
-		const iv = randomBytes(12);
-		const cipher = createCipheriv('aes-256-gcm', this.#key, iv);
-		cipher.setAAD(Buffer.from(context, 'utf8'));
-		const ciphertext = Buffer.concat([
-			cipher.update(normalized, 'utf8'),
-			cipher.final(),
-		]);
-		const tag = cipher.getAuthTag();
+		const sealed = this.#keyring.seal(normalized, context);
 		return {
-			keyId: this.#keyId,
-			iv: iv.toString('base64'),
-			tag: tag.toString('base64'),
-			ciphertext: ciphertext.toString('base64'),
+			keyId: sealed.keyId,
+			iv: sealed.iv.toString('base64'),
+			tag: sealed.tag.toString('base64'),
+			ciphertext: sealed.ciphertext.toString('base64'),
 		};
 	}
 
 	decrypt(envelope: EncryptedCredential, context: string): string {
-		if (envelope.keyId !== this.#keyId) {
-			throw new Error('The credential encryption key is unavailable.');
+		try {
+			return this.#keyring
+				.open(
+					{
+						keyId: envelope.keyId,
+						iv: Buffer.from(envelope.iv, 'base64'),
+						tag: Buffer.from(envelope.tag, 'base64'),
+						ciphertext: Buffer.from(envelope.ciphertext, 'base64'),
+					},
+					context,
+				)
+				.toString('utf8');
+		} catch (error) {
+			if (error instanceof KeyringError && error.code === 'KEY_UNKNOWN') {
+				throw new Error('The credential encryption key is unavailable.', {
+					cause: error,
+				});
+			}
+			throw error;
 		}
-		const decipher = createDecipheriv(
-			'aes-256-gcm',
-			this.#key,
-			Buffer.from(envelope.iv, 'base64'),
-		);
-		decipher.setAAD(Buffer.from(context, 'utf8'));
-		decipher.setAuthTag(Buffer.from(envelope.tag, 'base64'));
-		return Buffer.concat([
-			decipher.update(Buffer.from(envelope.ciphertext, 'base64')),
-			decipher.final(),
-		]).toString('utf8');
 	}
 }
 
@@ -115,19 +133,26 @@ export function credentialVaultFromEnvironment(
 	environment: NodeJS.ProcessEnv = process.env,
 	workspaceRoot = process.cwd(),
 ): CredentialVault {
+	const previous = parsePreviousKeys(
+		environment.FD_AGENT_CREDENTIAL_KEY_PREVIOUS,
+		(entry) => encryptionKey(entry, 'FD_AGENT_CREDENTIAL_KEY_PREVIOUS'),
+	);
 	const configured = environment.FD_AGENT_CREDENTIAL_KEY;
-	if (configured) return new AesGcmCredentialVault(encryptionKey(configured));
+	if (configured) {
+		return new AesGcmCredentialVault(encryptionKey(configured), previous);
+	}
 	if (environment.NODE_ENV === 'production') {
 		throw new Error(
 			'FD_AGENT_CREDENTIAL_KEY is required in production before provider credentials can be used.',
 		);
 	}
 	if (environment.NODE_ENV === 'test') {
-		return new AesGcmCredentialVault(Buffer.alloc(32, 0x43));
+		return new AesGcmCredentialVault(Buffer.alloc(32, 0x43), previous);
 	}
 	return new AesGcmCredentialVault(
 		readOrCreateDevelopmentKey(
 			flowdularLocalDataPath(workspaceRoot, 'agent-credential.key'),
 		),
+		previous,
 	);
 }