@flowdular/sdk 0.2.3 → 0.3.0

package/modules/agents/src/services/metering.ts

@@ -0,0 +1,111 @@
+/* The metering.core meter contract, declared here rather than imported.
+   agents.core depends on metering.core and requires metering.meters.v1, so the
+   module registry composes metering.core first and refuses a deployment
+   without it. The mirror is what keeps the dependency a capability rather than
+   a package import: this module reads the registry through the platform and
+   never reaches metering.core's own code or tables. It is the contract
+   metering.core owns (modules/metering/src/domain/meters.ts) and must not
+   drift from it. */
+export const METERING_METERS_CAPABILITY = 'metering.meters.v1';
+
+/** The stable code this module records when `check` refuses a run. */
+export const METER_LIMIT_EXCEEDED = 'METER_LIMIT_EXCEEDED';
+
+export type MeterKind = 'cumulative' | 'gauge';
+
+export interface MeterDeclaration {
+	readonly key: string;
+	readonly label: string;
+	readonly unit: string;
+	readonly kind: MeterKind;
+}
+
+export interface MeterRecordInput {
+	readonly tenantId: string;
+	/** The full key, `<moduleId>.<key>`, as `declare` composed it. */
+	readonly meter: string;
+	readonly amount: number;
+	readonly at?: number;
+	/** Makes the fact idempotent. Without it every call counts again. */
+	readonly sourceRef?: string;
+}
+
+export interface MeterRecordResult {
+	readonly recorded: boolean;
+	readonly day: string;
+}
+
+export interface MeterCheckInput {
+	readonly tenantId: string;
+	readonly meter: string;
+	readonly amount: number;
+}
+
+export type MeterVerdict = 'allowed' | 'warning' | 'refused';
+
+export interface MeterCheckResult {
+	readonly verdict: MeterVerdict;
+	readonly used: number;
+	readonly limit: number | null;
+}
+
+export interface MeterRegistry {
+	declare(moduleId: string, meters: readonly MeterDeclaration[]): void;
+	record(input: MeterRecordInput): Promise<MeterRecordResult>;
+	check(input: MeterCheckInput): Promise<MeterCheckResult>;
+}
+
+/* Read at the point of use, never captured at composition time, so a run reads
+   the registry the platform holds now rather than one this module closed over
+   while it composed. Null is a process that built this module outside the
+   module registry, such as a test that constructs a worker of its own; a
+   composed deployment always has the provider. */
+export type MeterRegistryResolver = () => MeterRegistry | null;
+
+/**
+ * The month a refusal belongs to, as `YYYY-MM` in UTC. A limit is monthly, so
+ * a standing refusal is keyed by the month it was recorded in and answers again
+ * as soon as the month turns.
+ */
+export function meterPeriod(at: number): string {
+	return new Date(at).toISOString().slice(0, 7);
+}
+
+/** The meter keys as metering.core composes them, for `record` and `check`. */
+export const AGENT_METERS = {
+	runTokens: 'agents.core.run-tokens',
+	runs: 'agents.core.runs',
+} as const;
+
+/**
+ * What agents.core counts. Declared at composition, once, so the workspace
+ * sees both meters whether or not a run has happened yet.
+ */
+export const AGENT_METER_DECLARATIONS: readonly MeterDeclaration[] = [
+	{
+		key: 'run-tokens',
+		label: 'Agent run tokens',
+		unit: 'tokens',
+		kind: 'cumulative',
+	},
+	{ key: 'runs', label: 'Agent runs', unit: 'runs', kind: 'cumulative' },
+];
+
+/**
+ * What one run may cost before it starts. The prompt and the resolved
+ * instructions are the tokens the provider is certain to read, at the four
+ * characters per token the bundled catalogue prices with, and the output limit
+ * is the most it may write back. It is an estimate, so a run may still settle
+ * above or below it; the limit it is checked against is a monthly ceiling, not
+ * a per-run budget, and the settled fact replaces this guess.
+ */
+export function estimateRunTokens(input: {
+	readonly instructions: string;
+	readonly input: string;
+	readonly maxOutputTokens: number;
+}): number {
+	return (
+		Math.ceil((input.instructions.length + input.input.length) / 4) +
+		Math.max(0, Math.trunc(input.maxOutputTokens))
+	);
+}

package/modules/agents/src/services/migration.ts

@@ -763,6 +763,66 @@ CREATE POLICY module_agent_bindings_reconciliation_policy ON module_agent_bindin
 GRANT SELECT (tenant_id, agent_id) ON module_agent_bindings TO coreloom_background;
 `;
 
+export const AGENTS_MIGRATION_0022 = `-- The rotation command has to find the connections still sealed with a retired
+-- key before it knows whose they are. It is granted the routing columns and the
+-- key id alone: the nonce, the tag and the ciphertext stay unreadable on this
+-- connection, and every row it re-seals is read again under the tenant that row
+-- named.
+GRANT SELECT (tenant_id, credential_key_id)
+  ON agent_provider_connections TO coreloom_background;
+`;
+
+/* Mirrors migrations/0023_agents_retention_indexes.up.sql byte for byte. */
+export const AGENTS_MIGRATION_0023 = `-- The retention sweep of agents.core.runs asks one workspace for its oldest
+-- settled runs, and a subject erasure asks it for the runs one account
+-- requested. Both are bounded batches, so both need a range scan rather than a
+-- pass over the workspace's runs; the export walks the order
+-- agent_runs_tenant_queued_idx already carries and needs no index of its own.
+CREATE INDEX IF NOT EXISTS agent_runs_tenant_settled_idx
+  ON agent_runs (tenant_id, completed_at);
+CREATE INDEX IF NOT EXISTS agent_runs_tenant_requested_idx
+  ON agent_runs (tenant_id, requested_by, id);
+`;
+
+/* Mirrors migrations/0024_agent_meter_refusals.up.sql byte for byte. */
+export const AGENTS_MIGRATION_0024 = `-- A meter refusal stands until the workspace's month turns or its limit is
+-- raised, so recording it on every refused enqueue wrote the same fact to the
+-- hash-chained trail as fast as a caller could retry. This row is the claim
+-- that the refusal has already been recorded: the first refusal of a workspace,
+-- a meter and a month takes it and writes the audit event, and every refusal
+-- behind it is answered without touching the trail.
+--
+-- One row per workspace and meter at a time. The claim removes the rows of
+-- earlier months for that workspace and meter in the same transaction, so the
+-- table is bounded by the meters agents.core declares rather than by time.
+CREATE TABLE IF NOT EXISTS agent_meter_refusals (
+  tenant_id TEXT NOT NULL,
+  meter TEXT NOT NULL,
+  period TEXT NOT NULL,
+  first_refused_at BIGINT NOT NULL,
+  PRIMARY KEY (tenant_id, meter, period)
+);
+ALTER TABLE agent_meter_refusals ENABLE ROW LEVEL SECURITY;
+ALTER TABLE agent_meter_refusals FORCE ROW LEVEL SECURITY;
+CREATE POLICY agent_meter_refusals_tenant_policy ON agent_meter_refusals
+  USING (tenant_id = current_setting('coreloom.tenant_id', true))
+  WITH CHECK (tenant_id = current_setting('coreloom.tenant_id', true));
+`;
+
+/* Mirrors migrations/0025_agent_list_indexes.up.sql byte for byte. */
+export const AGENTS_MIGRATION_0025 = `-- agents.definitions.list pages by lower(name) or updated_at, each followed by
+-- id, and agent_definitions_tenant_name_idx orders by the raw name, so neither
+-- paged read had an index carrying its order. agents.runs.list orders queued_at
+-- and id in one direction, while agent_runs_tenant_queued_idx carries queued_at
+-- descending beside an ascending id, so the planner sorted every page.
+CREATE INDEX IF NOT EXISTS agent_definitions_tenant_name_key_idx
+  ON agent_definitions (tenant_id, lower(name), id);
+CREATE INDEX IF NOT EXISTS agent_definitions_tenant_updated_idx
+  ON agent_definitions (tenant_id, updated_at, id);
+CREATE INDEX IF NOT EXISTS agent_runs_tenant_queue_order_idx
+  ON agent_runs (tenant_id, queued_at, id);
+`;
+
 export const databaseMigrations: readonly DatabaseMigration[] = [
 	{
 		id: '0001_agents_core',
@@ -1149,4 +1209,53 @@ export const databaseMigrations: readonly DatabaseMigration[] = [
 				},
 			]),
 	},
+	{
+		id: '0022_credential_rotation_inventory',
+		sql: { postgresql: AGENTS_MIGRATION_0022 },
+		/* A grant leaves no object behind, so the column privilege itself is what
+		   proves this migration ran. */
+		inspectExisting: (database) =>
+			migrationObjectState([
+				async () => {
+					const result = await database.query<{ granted: boolean }>({
+						text: `SELECT CASE WHEN to_regclass('agent_provider_connections') IS NOT NULL THEN
+						  has_column_privilege('coreloom_background', 'agent_provider_connections', 'tenant_id', 'SELECT')
+						  AND has_column_privilege('coreloom_background', 'agent_provider_connections', 'credential_key_id', 'SELECT')
+						ELSE false END AS granted`,
+					});
+					return result.rows[0]?.granted === true;
+				},
+			]),
+	},
+	{
+		id: '0023_agents_retention_indexes',
+		sql: { postgresql: AGENTS_MIGRATION_0023 },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasIndex('agent_runs_tenant_settled_idx'),
+				() => database.schema.hasIndex('agent_runs_tenant_requested_idx'),
+			]),
+	},
+
+	{
+		id: '0024_agent_meter_refusals',
+		sql: { postgresql: AGENTS_MIGRATION_0024 },
+		inspectExisting: (database) =>
+			postgresTenantTableState(
+				database,
+				'agent_meter_refusals',
+				'agent_meter_refusals_tenant_policy',
+				[],
+			),
+	},
+	{
+		id: '0025_agent_list_indexes',
+		sql: { postgresql: AGENTS_MIGRATION_0025 },
+		inspectExisting: (database) =>
+			migrationObjectState([
+				() => database.schema.hasIndex('agent_definitions_tenant_name_key_idx'),
+				() => database.schema.hasIndex('agent_definitions_tenant_updated_idx'),
+				() => database.schema.hasIndex('agent_runs_tenant_queue_order_idx'),
+			]),
+	},
 ];

package/modules/agents/src/services/module-agent-preflight.ts

@@ -14,6 +14,10 @@ interface StoredModuleAgentDefinition {
 	readonly content_hash: string;
 }
 
+/* The catalogue has no tenant column; the repository reconciles it under this
+   sentinel tenant on the runtime handle, so the boot read uses the same one. */
+const MODULE_AGENT_CATALOG_TENANT = '__flowdular_module_agents__';
+
 /* Validate persisted revision high-water marks before HMR retires the healthy
    generation. This read is deliberately the only database work the new
    generation does up front: migrations, reconciliation, vault access, workers
@@ -28,7 +32,7 @@ export async function preflightModuleAgentDefinitions(
 
 	const lease = await databases.acquire({
 		namespace: 'agents.core',
-		purpose: 'migration',
+		purpose: 'runtime',
 		requirements: {
 			dialectIds: [DATABASE_DIALECT_IDS.postgresql],
 			capabilities: [
@@ -38,18 +42,22 @@ export async function preflightModuleAgentDefinitions(
 		},
 	});
 	try {
-		/* A first run has no catalog table yet, and that is not a downgrade. */
-		if (!(await lease.database.schema.hasTable('module_agent_definitions'))) {
-			return normalized;
-		}
 		const stored = await lease.database.transaction(
-			(transaction) =>
-				transaction.query<StoredModuleAgentDefinition & { agent_id: string }>({
+			async (transaction) => {
+				/* A first run has no catalog table yet, and that is not a downgrade. */
+				if (!(await transaction.schema.hasTable('module_agent_definitions'))) {
+					return undefined;
+				}
+				return transaction.query<
+					StoredModuleAgentDefinition & { agent_id: string }
+				>({
 					text: `SELECT agent_id, definition_revision, content_hash
 					       FROM module_agent_definitions`,
-				}),
-			{ access: 'read' },
+				});
+			},
+			{ access: 'read', tenantId: MODULE_AGENT_CATALOG_TENANT },
 		);
+		if (!stored) return normalized;
 		const byAgent = new Map(stored.rows.map((row) => [row.agent_id, row]));
 		for (const definition of normalized) {
 			const previous = byAgent.get(definition.id);

package/modules/agents/src/services/notifications.ts

@@ -0,0 +1,98 @@
+import type { UserActor } from '@flowdular/sdk/kernel';
+
+/* The notifications.core publish contract, declared here rather than imported.
+   notifications.core is optional: agents.core composes, runs and settles runs
+   with that module absent, so it may not be a package dependency. This mirror
+   is the contract notifications.core owns and must not drift from it.
+   modules/workflows/src/services/notifications.ts holds the same mirror and
+   stays identical to this file apart from the module id; change both. */
+export const NOTIFICATIONS_PUBLISH_CAPABILITY = 'notifications.publish.v1';
+
+export type NotificationKind =
+	| 'agent-run-completed'
+	| 'agent-run-failed'
+	| 'workflow-run-completed'
+	| 'workflow-run-failed'
+	| 'webhook-dead-letter'
+	| 'approval-requested'
+	| 'approval-decided'
+	| 'meter-threshold';
+
+export interface NotificationPublishInput {
+	readonly tenantId: string;
+	readonly kind: NotificationKind;
+	readonly sourceModule: string;
+	readonly sourceRef: string;
+	readonly title: string;
+	readonly body?: string;
+	readonly recipients: readonly string[];
+}
+
+export interface NotificationPublishResult {
+	readonly inboxItemIds: readonly string[];
+	readonly deliveryIds: readonly string[];
+}
+
+export interface NotificationPublisher {
+	publish(input: NotificationPublishInput): Promise<NotificationPublishResult>;
+}
+
+/* Read at the point of use, never at composition time: the platform may
+   register notifications.core after agents.core, or never. */
+export type NotificationPublisherResolver = () => NotificationPublisher | null;
+
+const LIMITS = {
+	sourceModule: 64,
+	sourceRef: 200,
+	title: 200,
+	body: 4_000,
+	recipients: 64,
+	recipientId: 128,
+} as const;
+
+function clamp(value: string, limit: number): string {
+	return value.length > limit ? value.slice(0, limit) : value;
+}
+
+/* The person accountable for the run. The service that enqueued it already
+   derived and validated one: the member who started the run, or the member who
+   configured the service identity that did. A run with no person behind it,
+   such as one an agent started for itself, has nobody to notify. */
+export function runNotificationRecipients(
+	authorizationSubject: UserActor | null,
+): readonly string[] {
+	return authorizationSubject ? [authorizationSubject.id] : [];
+}
+
+/* Advisory and post-commit. An absent notifications module, nobody to notify,
+   or a publisher that throws never changes a settled run, so this never
+   rejects. The caller passes the run id as sourceRef, which makes a retried
+   terminal step publish the same notification instead of a second one. */
+export async function publishRunOutcome(
+	resolve: NotificationPublisherResolver | undefined,
+	input: NotificationPublishInput,
+): Promise<void> {
+	if (input.recipients.length === 0) return;
+	try {
+		const publisher = resolve?.();
+		if (!publisher) return;
+		await publisher.publish({
+			tenantId: input.tenantId,
+			kind: input.kind,
+			sourceModule: clamp(input.sourceModule, LIMITS.sourceModule),
+			sourceRef: clamp(input.sourceRef, LIMITS.sourceRef),
+			title: clamp(input.title, LIMITS.title),
+			...(input.body === undefined
+				? {}
+				: { body: clamp(input.body, LIMITS.body) }),
+			recipients: input.recipients
+				.slice(0, LIMITS.recipients)
+				.map((recipient) => clamp(recipient, LIMITS.recipientId)),
+		});
+	} catch (error) {
+		console.warn(
+			`[agents] notification publish for run ${input.sourceRef} failed:`,
+			error instanceof Error ? error.message : error,
+		);
+	}
+}

package/modules/agents/src/services/provider-repository.ts

@@ -1,4 +1,5 @@
 import type { DatabaseHandle, DatabaseTransaction } from '@flowdular/sdk/database';
+import { integer } from '@flowdular/sdk/database';
 import { modelSupportsTemperature } from '@flowdular/sdk/harness/catalog';
 import type {
 	AgentModelReadiness,
@@ -106,9 +107,9 @@ function readinessMap(
 			result.get(row.provider_id) ?? new Map<string, AgentModelReadiness>();
 		models.set(row.model_id, {
 			status: row.status,
-			latencyMs: integerOrNull(row.latency_ms),
+			latencyMs: integerOrNull(row.latency_ms, 'latency_ms'),
 			errorCode: row.error_code,
-			checkedAt: integer(row.checked_at),
+			checkedAt: integer(row.checked_at, 'checked_at'),
 		});
 		result.set(row.provider_id, models);
 	}
@@ -134,9 +135,9 @@ function fromRow(
 			credentialRevision: row.credential_revision,
 			revision: row.revision,
 			createdBy: row.created_by,
-			createdAt: integer(row.created_at),
+			createdAt: integer(row.created_at, 'created_at'),
 			updatedBy: row.updated_by,
-			updatedAt: integer(row.updated_at),
+			updatedAt: integer(row.updated_at, 'updated_at'),
 		},
 		credential: {
 			keyId: row.credential_key_id,
@@ -180,20 +181,10 @@ export interface ProviderRepository {
 
 type Int = number | bigint | string;
 
-/* PostgreSQL returns BIGINT and NUMERIC aggregates as strings, so a count read
-   raw compares against text where it should compare against a number. */
-function integer(value: Int): number {
-	const normalized = Number(value);
-	if (!Number.isSafeInteger(normalized)) {
-		throw new Error('The agents database returned an invalid integer.');
-	}
-	return normalized;
-}
-
 /* A nullable BIGINT must stay null: coercing it to 0 would turn "never checked"
    into "checked at the epoch". */
-function integerOrNull(value: Int | null): number | null {
-	return value === null ? null : integer(value);
+function integerOrNull(value: Int | null, field: string): number | null {
+	return value === null ? null : integer(value, field);
 }
 
 export interface ProvidersPersistenceStatements {
@@ -326,8 +317,8 @@ export class DatabaseProviderRepository implements ProviderRepository {
 		);
 		const row = result.rows[0]!;
 		return {
-			connections: integer(row.connections),
-			enabled: integer(row.enabled),
+			connections: integer(row.connections, 'connections'),
+			enabled: integer(row.enabled, 'enabled'),
 		};
 	}
 

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

@@ -15,7 +15,7 @@ import type {
 	CreateAgentProviderInput,
 	UpdateAgentProviderInput,
 } from '../domain/types.ts';
-import type { CredentialVault } from './credential-vault.ts';
+import { credentialContext, type CredentialVault } from './credential-vault.ts';
 import {
 	assertPublicHost,
 	createProviderFetch,
@@ -198,14 +198,6 @@ function resourceName(
 	return value;
 }
 
-function credentialContext(connection: {
-	readonly tenantId: string;
-	readonly id: string;
-	readonly kind: AgentProviderKind;
-}): string {
-	return `${connection.tenantId}:${connection.id}:${connection.kind}`;
-}
-
 function localConnection(tenantId: string): AgentProviderConnection {
 	return {
 		id: LOCAL_PROVIDER_ID,

package/modules/agents/src/services/reports.ts

@@ -0,0 +1,107 @@
+import type {
+	ReportProvider,
+	ReportProviderAnswer,
+} from '@flowdular/sdk/modules/reports';
+import { AGENT_PERMISSIONS } from '../acl/permissions.ts';
+import type { AgentUsageDay } from '../domain/types.ts';
+import type { AgentRepository } from './repository.ts';
+
+export const AGENT_RUNS_REPORT_PROVIDER_KEY = 'agents.runs';
+
+export const AGENT_RUNS_REPORT_PROVIDER_LABEL = 'Agent runs';
+
+/**
+ * This module's own bundle names the provider, its tiles and its lines; the
+ * English literals beside each key are what a deployment without the bundle,
+ * or a locale that lacks the key, still shows.
+ */
+export const AGENT_RUNS_REPORT_LABEL_KEYS = {
+	provider: 'agents.report.runs.label',
+	runs: 'agents.report.runs.tile.runs',
+	tokens: 'agents.report.runs.tile.tokens',
+	runsPerDay: 'agents.report.runs.series.runsPerDay',
+	tokensPerDay: 'agents.report.runs.series.tokensPerDay',
+} as const;
+
+/**
+ * Runs and tokens as the run cost rollup already holds them: totals as tiles,
+ * one point per day as series. The rollup groups by day inside the range, and
+ * reports.core bounds a range to the same number of days a series may carry,
+ * so the point count can never pass the contract's bound.
+ */
+export function runsAnswer(
+	days: readonly AgentUsageDay[],
+): ReportProviderAnswer {
+	let runs = 0;
+	let tokens = 0;
+	const runPoints: { at: string; value: number }[] = [];
+	const tokenPoints: { at: string; value: number }[] = [];
+	for (const day of days) {
+		const dayTokens = day.inputTokens + day.outputTokens;
+		runs += day.runs;
+		tokens += dayTokens;
+		runPoints.push({ at: day.day, value: day.runs });
+		tokenPoints.push({ at: day.day, value: dayTokens });
+	}
+	return {
+		tiles: [
+			{
+				key: 'runs',
+				label: 'Runs',
+				tileLabelKey: AGENT_RUNS_REPORT_LABEL_KEYS.runs,
+				value: runs,
+				unit: 'runs',
+			},
+			{
+				key: 'tokens',
+				label: 'Tokens',
+				tileLabelKey: AGENT_RUNS_REPORT_LABEL_KEYS.tokens,
+				value: tokens,
+				unit: 'tokens',
+			},
+		],
+		series: [
+			{
+				key: 'runs',
+				label: 'Runs per day',
+				seriesLabelKey: AGENT_RUNS_REPORT_LABEL_KEYS.runsPerDay,
+				points: runPoints,
+			},
+			{
+				key: 'tokens',
+				label: 'Tokens per day',
+				seriesLabelKey: AGENT_RUNS_REPORT_LABEL_KEYS.tokensPerDay,
+				points: tokenPoints,
+			},
+		],
+	};
+}
+
+function aborted(signal: AbortSignal | undefined): boolean {
+	return signal?.aborted === true;
+}
+
+/**
+ * This workspace's agent runs as a report provider. The read is the existing
+ * rollup under this module's own tenant transaction, with the tenant
+ * reports.core resolved from the principal; it prices nothing and writes
+ * nothing.
+ */
+export function createAgentRunsReportProvider(
+	repository: () => Promise<AgentRepository>,
+): ReportProvider {
+	return {
+		key: AGENT_RUNS_REPORT_PROVIDER_KEY,
+		label: AGENT_RUNS_REPORT_PROVIDER_LABEL,
+		labelKey: AGENT_RUNS_REPORT_LABEL_KEYS.provider,
+		permission: AGENT_PERMISSIONS.runsRead,
+		async read({ tenantId, range, signal }): Promise<ReportProviderAnswer> {
+			if (aborted(signal)) return { tiles: [] };
+			const days = await (
+				await repository()
+			).usageByDay(tenantId, range.from, range.to, { signal });
+			if (aborted(signal)) return { tiles: [] };
+			return runsAnswer(days);
+		},
+	};
+}