@flowdular/sdk 0.2.4 → 0.3.0

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

@@ -1,5 +1,6 @@
 import { createHash, randomUUID } from 'node:crypto';
 import {
+	integer,
 	runDatabaseMigrations,
 	type DatabaseHandle,
 	type DatabaseTransaction,
@@ -14,10 +15,13 @@ import type {
 	JsonValue,
 } from '@flowdular/sdk/harness';
 import { usageCostMicros } from '@flowdular/sdk/harness/catalog';
+import { keysetWhere } from '@flowdular/sdk/server';
 import type {
 	AgentAuditEvent,
-	AgentAuditPage,
+	AgentAuditListQuery,
 	AgentDefinition,
+	AgentListPage,
+	AgentListQuery,
 	AgentDefinitionRevision,
 	AgentActionInvocation,
 	AgentRevisionProcedure,
@@ -28,6 +32,7 @@ import type {
 	AgentRun,
 	AgentRunDetail,
 	AgentRunExecution,
+	AgentRunListQuery,
 	AgentUsageAgent,
 	AgentUsageBucket,
 	AgentUsageDay,
@@ -41,7 +46,10 @@ import {
 	DuplicateActionIdempotencyKeyError,
 	DuplicateRunIdempotencyKeyError,
 	ModuleAgentBindingConflictError,
+	type AgentReadOptions,
 	type AgentRepository,
+	type AgentRunExportCursor,
+	type ExportedAgentRun,
 	type PendingAgentAuditEvent,
 	type RecoverableRun,
 } from './repository.ts';
@@ -192,6 +200,11 @@ interface RunEventRow {
 	occurred_at: number | string;
 }
 
+/** The run id a page of events carries, so one query can serve many runs. */
+interface RunEventPageRow extends RunEventRow {
+	run_id: string;
+}
+
 interface AuditRow {
 	id: string;
 	tenant_id: string;
@@ -243,7 +256,7 @@ interface UsageRow {
 	input_tokens: number | string;
 	output_tokens: number | string;
 	cost_micro_usd: number | string | null;
-	unpriced_runs: number | string;
+	unpriced_runs: number | string | null;
 }
 
 function stringArray(value: string): readonly string[] {
@@ -296,15 +309,15 @@ function fromAgentRow(row: AgentRow): AgentDefinition {
 		allowedTools: stringArray(row.allowed_tools_json),
 		procedureIds: [],
 		maxSteps: row.max_steps,
-		timeoutMs: integer(row.timeout_ms),
+		timeoutMs: integer(row.timeout_ms, 'timeout_ms'),
 		temperature: row.temperature_milli / 1_000,
-		maxOutputTokens: integer(row.max_output_tokens),
+		maxOutputTokens: integer(row.max_output_tokens, 'max_output_tokens'),
 		status: row.status,
 		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'),
 	};
 }
 
@@ -343,10 +356,10 @@ function fromRunRow(row: RunRow): AgentRun {
 		failureCode: row.failure_code,
 		failureMessage: row.failure_message,
 		attempt: row.attempt,
-		queuedAt: integer(row.queued_at),
-		startedAt: integerOrNull(row.started_at),
-		completedAt: integerOrNull(row.completed_at),
-		leaseExpiresAt: integerOrNull(row.lease_expires_at),
+		queuedAt: integer(row.queued_at, 'queued_at'),
+		startedAt: integerOrNull(row.started_at, 'started_at'),
+		completedAt: integerOrNull(row.completed_at, 'completed_at'),
+		leaseExpiresAt: integerOrNull(row.lease_expires_at, 'lease_expires_at'),
 	};
 }
 
@@ -364,9 +377,9 @@ function fromRevisionRow(row: AgentRevisionRow): AgentDefinitionRevision {
 		allowedTools: stringArray(row.allowed_tools_json),
 		procedures: JSON.parse(row.skills_json) as AgentRevisionProcedure[],
 		maxSteps: row.max_steps,
-		timeoutMs: integer(row.timeout_ms),
+		timeoutMs: integer(row.timeout_ms, 'timeout_ms'),
 		temperature: row.temperature_milli / 1_000,
-		maxOutputTokens: integer(row.max_output_tokens),
+		maxOutputTokens: integer(row.max_output_tokens, 'max_output_tokens'),
 		status: row.status,
 		ownership:
 			row.module_id === null
@@ -378,7 +391,7 @@ function fromRevisionRow(row: AgentRevisionRow): AgentDefinitionRevision {
 					},
 		moduleDefinitionRevision: row.module_definition_revision,
 		retainedBy: row.retained_by,
-		retainedAt: integer(row.retained_at),
+		retainedAt: integer(row.retained_at, 'retained_at'),
 	};
 }
 
@@ -394,7 +407,7 @@ function fromModuleBindingRow(row: ModuleAgentBindingRow): ModuleAgentBinding {
 		executableRevision: row.executable_revision,
 		revision: row.revision,
 		updatedBy: row.updated_by,
-		updatedAt: integer(row.updated_at),
+		updatedAt: integer(row.updated_at, 'updated_at'),
 	};
 }
 
@@ -421,10 +434,10 @@ function fromActionRow(row: ActionRow): AgentActionInvocation {
 		output: jsonValue(row.output_json),
 		code: row.failure_code,
 		attempt: row.attempt,
-		queuedAt: integer(row.queued_at),
-		startedAt: integerOrNull(row.started_at),
-		completedAt: integerOrNull(row.completed_at),
-		leaseExpiresAt: integerOrNull(row.lease_expires_at),
+		queuedAt: integer(row.queued_at, 'queued_at'),
+		startedAt: integerOrNull(row.started_at, 'started_at'),
+		completedAt: integerOrNull(row.completed_at, 'completed_at'),
+		leaseExpiresAt: integerOrNull(row.lease_expires_at, 'lease_expires_at'),
 	};
 }
 
@@ -440,9 +453,9 @@ function fromSkillRow(row: SkillRow): AgentProcedure {
 		status: row.status,
 		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'),
 	};
 }
 
@@ -456,32 +469,29 @@ function executionFromRow(row: RunRow): AgentRunExecution {
 		model: row.model,
 		allowedTools: stringArray(row.allowed_tools_json),
 		maxSteps: row.max_steps,
-		timeoutMs: integer(row.timeout_ms),
+		timeoutMs: integer(row.timeout_ms, 'timeout_ms'),
 		temperature: row.temperature_milli / 1_000,
-		maxOutputTokens: integer(row.max_output_tokens),
+		maxOutputTokens: integer(row.max_output_tokens, 'max_output_tokens'),
 	};
 	return { run: fromRunRow(row), definition };
 }
 
-/* SUM() over BIGINT is NUMERIC in PostgreSQL, and the driver hands NUMERIC
-   back as a string. Aggregates leave this repository as numbers. */
-function integer(value: number | string | null): number {
-	return typeof value === 'number' ? value : Number(value ?? 0);
-}
-
 /* A nullable BIGINT must stay null: coercing it to 0 would turn "never started"
    into "started at the epoch". */
-function integerOrNull(value: number | string | null): number | null {
-	return value === null ? null : integer(value);
+function integerOrNull(
+	value: number | string | null,
+	field: string,
+): number | null {
+	return value === null ? null : integer(value, field);
 }
 
 function fromUsageRow(row: UsageRow): AgentUsageBucket {
 	return {
-		runs: integer(row.runs),
-		inputTokens: integer(row.input_tokens),
-		outputTokens: integer(row.output_tokens),
-		costMicroUsd: integer(row.cost_micro_usd),
-		unpricedRuns: integer(row.unpriced_runs),
+		runs: integer(row.runs, 'runs'),
+		inputTokens: integer(row.input_tokens, 'input_tokens'),
+		outputTokens: integer(row.output_tokens, 'output_tokens'),
+		costMicroUsd: integer(row.cost_micro_usd ?? 0, 'cost_micro_usd'),
+		unpricedRuns: integer(row.unpriced_runs ?? 0, 'unpriced_runs'),
 	};
 }
 
@@ -491,17 +501,27 @@ const USAGE_COLUMNS = `COUNT(*) AS runs,
  COALESCE(SUM(cost_micro_usd), 0) AS cost_micro_usd,
  SUM(CASE WHEN cost_micro_usd IS NULL THEN 1 ELSE 0 END) AS unpriced_runs`;
 
+function fromRunEventRow(row: RunEventRow): AgentExecutionEvent {
+	return {
+		sequence: integer(row.sequence, 'sequence'),
+		type: row.event_type,
+		timestamp: integer(row.occurred_at, 'occurred_at'),
+		message: row.message,
+		metadata: metadata(row.metadata_json),
+	};
+}
+
 function fromAuditRow(row: AuditRow): AgentAuditEvent {
 	return {
 		id: row.id,
 		tenantId: row.tenant_id,
-		sequence: integer(row.sequence),
+		sequence: integer(row.sequence, 'sequence'),
 		actorId: row.actor_id,
 		action: row.action,
 		subjectType: row.subject_type,
 		subjectId: row.subject_id,
 		metadata: metadata(row.metadata_json),
-		occurredAt: integer(row.occurred_at),
+		occurredAt: integer(row.occurred_at, 'occurred_at'),
 		previousHash: row.previous_hash,
 		eventHash: row.event_hash,
 	};
@@ -558,15 +578,75 @@ const RUN_FROM = `agent_runs LEFT JOIN agent_run_execution_limits
 	LEFT JOIN agent_run_contracts ON agent_run_contracts.run_id = agent_runs.id
 	JOIN agent_run_actors ON agent_run_actors.run_id = agent_runs.id
 	 AND agent_run_actors.tenant_id = agent_runs.tenant_id`;
-const AGENT_SELECT = `SELECT agent_definitions.*,
+const AGENT_COLUMNS = `agent_definitions.*,
  COALESCE(agent_definition_execution_limits.timeout_ms,
  agent_definitions.timeout_ms) AS timeout_ms,
  COALESCE(agent_definition_output_limits.max_output_tokens,
- ${DEFAULT_MAX_OUTPUT_TOKENS}) AS max_output_tokens
- FROM agent_definitions LEFT JOIN agent_definition_execution_limits
+ ${DEFAULT_MAX_OUTPUT_TOKENS}) AS max_output_tokens`;
+const AGENT_FROM = `agent_definitions LEFT JOIN agent_definition_execution_limits
  ON agent_definition_execution_limits.agent_id = agent_definitions.id
  LEFT JOIN agent_definition_output_limits
  ON agent_definition_output_limits.agent_id = agent_definitions.id`;
+const AGENT_SELECT = `SELECT ${AGENT_COLUMNS} FROM ${AGENT_FROM}`;
+
+/* The term is matched as a substring, so the three characters LIKE reads as
+   syntax are escaped with PostgreSQL's default backslash. */
+function likePattern(term: string): string {
+	return '%' + term.replace(/[\\%_]/g, (character) => '\\' + character) + '%';
+}
+
+/* The page order and the keyset predicate are one decision, so the planner
+   walks agent_definitions_tenant_name_key_idx or _tenant_updated_idx from the
+   cursor; tests/list-plan.test.ts reads the plan. A subquery names the collation key, since a keyset column must be a
+   plain identifier; PostgreSQL pulls it up and reads the expression index. */
+const AGENT_PAGE_FROM = `(SELECT ${AGENT_COLUMNS},
+ lower(agent_definitions.name) AS name_key
+ FROM ${AGENT_FROM}
+ WHERE agent_definitions.tenant_id = $1
+   AND ($2::text IS NULL OR agent_definitions.name ILIKE $2
+        OR agent_definitions.agent_key ILIKE $2
+        OR agent_definitions.description ILIKE $2)) AS agents`;
+
+export function agentPageStatement(query: AgentListQuery): string {
+	const column = query.sort === 'name' ? 'name_key' : 'updated_at';
+	const order = query.direction === 'asc' ? 'ASC' : 'DESC';
+	const keyset =
+		query.after === null
+			? ''
+			: ' WHERE ' +
+				keysetWhere([column, 'id'], ['', ''], {
+					direction: query.direction,
+					parameterOffset: 2,
+				}).text;
+	return `SELECT * FROM ${AGENT_PAGE_FROM}${keyset}
+ ORDER BY ${column} ${order}, id ${order} LIMIT $${query.after === null ? 3 : 5}`;
+}
+
+const RUN_LIST_FILTERS = `agent_runs.tenant_id = $1
+ AND ($2::text IS NULL OR status = $2)
+ AND ($3::text IS NULL OR agent_id = $3)
+ AND ($4::text IS NULL OR trigger = $4)
+ AND ($5::text IS NULL OR agent_name ILIKE $5 OR agent_runs.id = $6)`;
+
+export function runPageStatement(query: AgentRunListQuery): string {
+	const order = query.direction === 'asc' ? 'ASC' : 'DESC';
+	const keyset =
+		query.after === null
+			? ''
+			: ' AND ' +
+				keysetWhere(['queued_at', 'id'], ['', ''], {
+					direction: query.direction,
+					parameterOffset: 6,
+				}).text;
+	return `SELECT ${RUN_COLUMNS} FROM ${RUN_FROM} WHERE ${RUN_LIST_FILTERS}${keyset}
+ ORDER BY queued_at ${order}, agent_runs.id ${order} LIMIT $${query.after === null ? 7 : 9}`;
+}
+
+/* Newest first over the order agent_audit_v4_tenant_time_idx carries. */
+const AUDIT_PAGE_KEYSET = keysetWhere(['occurred_at', 'sequence'], ['', ''], {
+	direction: 'desc',
+	parameterOffset: 1,
+}).text;
 const AGENT_REVISION_SELECT = `SELECT agent_definition_revisions.*,
  agent_revision_ownership.module_id,
  agent_revision_ownership.module_definition_revision
@@ -618,7 +698,6 @@ export interface AgentsPersistenceStatements {
 	readonly updateProcedure: string;
 	readonly procedureUsage: string;
 	readonly deleteProcedure: string;
-	readonly listRuns: string;
 	readonly getRun: string;
 	readonly listRunEvents: string;
 	readonly findRunByIdempotencyKey: string;
@@ -648,12 +727,21 @@ export interface AgentsPersistenceStatements {
 	readonly listRecoverableActions: string;
 	readonly claimAction: string;
 	readonly renewActionLease: string;
+	readonly releaseAction: string;
 	readonly completeAction: string;
 	readonly failAction: string;
 	readonly cancelAction: string;
+	readonly exportRunsPage1: string;
+	readonly exportRunsPage2: string;
+	readonly exportRunEvents: string;
+	readonly deleteSettledRunsBefore: string;
+	readonly deleteRunsRequestedBy: string;
 	readonly appendAuditEvent1: string;
 	readonly appendAuditEvent2: string;
+	readonly pruneMeterRefusals: string;
+	readonly claimMeterRefusal: string;
 	readonly listAuditEvents: string;
+	readonly exportAuditEventsPage: string;
 	readonly pageAuditEvents1: string;
 	readonly pageAuditEvents2: string;
 	readonly verifyAuditChainDetailed: string;
@@ -822,8 +910,6 @@ export const AGENTS_SQL: AgentsPersistenceStatements = Object.freeze({
 				 WHERE agent_skill_assignments.tenant_id = $1
 				   AND agent_skill_assignments.skill_id = $2`,
 	deleteProcedure: `DELETE FROM agent_skills WHERE tenant_id = $1 AND id = $2`,
-	listRuns: `SELECT ${RUN_COLUMNS} FROM ${RUN_FROM} WHERE agent_runs.tenant_id = $1
-					 ORDER BY queued_at DESC, agent_runs.id DESC LIMIT $2`,
 	getRun: `SELECT ${RUN_COLUMNS} FROM ${RUN_FROM} WHERE agent_runs.tenant_id = $1 AND agent_runs.id = $2`,
 	listRunEvents: `SELECT sequence, event_type, message, metadata_json, occurred_at
 					 FROM agent_run_events WHERE tenant_id = $1 AND run_id = $2
@@ -930,6 +1016,13 @@ export const AGENTS_SQL: AgentsPersistenceStatements = Object.freeze({
 	renewActionLease: `UPDATE agent_action_invocations SET lease_expires_at = $1
 					 WHERE tenant_id = $2 AND id = $3 AND status = 'running'
 					 AND lease_owner = $4`,
+	/* The claim handed back by the worker that took it, so the queue offers the
+	   invocation again at once instead of waiting out a lease nothing renews.
+	   `started_at` keeps the first claim instant, as a reclaim does. */
+	releaseAction: `UPDATE agent_action_invocations SET status = 'queued',
+					 lease_owner = NULL, lease_expires_at = NULL
+					 WHERE tenant_id = $1 AND id = $2 AND status = 'running'
+					 AND lease_owner = $3`,
 	completeAction: `UPDATE agent_action_invocations SET status = 'succeeded',
 					 output_json = $1, completed_at = $2, lease_owner = NULL,
 					 lease_expires_at = NULL WHERE tenant_id = $3 AND id = $4
@@ -948,11 +1041,46 @@ export const AGENTS_SQL: AgentsPersistenceStatements = Object.freeze({
 					 (id, tenant_id, sequence, actor_id, action, subject_type,
 					  subject_id, metadata_json, occurred_at, previous_hash, event_hash)
 					 VALUES ($1, $2, $3, $4, $5, $6, $7, $8, $9, $10, $11)`,
+	/* The order agent_runs_tenant_queued_idx already carries, so the walk is an
+	   index range scan and a run queued during it lands ahead of the cursor
+	   rather than being visited twice. */
+	exportRunsPage1: `SELECT ${RUN_COLUMNS} FROM ${RUN_FROM}
+					 WHERE agent_runs.tenant_id = $1
+					 ORDER BY queued_at DESC, agent_runs.id LIMIT $2`,
+	exportRunsPage2: `SELECT ${RUN_COLUMNS} FROM ${RUN_FROM}
+					 WHERE agent_runs.tenant_id = $1
+					 AND (queued_at < $2 OR (queued_at = $3 AND agent_runs.id > $4))
+					 ORDER BY queued_at DESC, agent_runs.id LIMIT $5`,
+	exportRunEvents: `SELECT run_id, sequence, event_type, message, metadata_json,
+					 occurred_at FROM agent_run_events
+					 WHERE tenant_id = $1 AND run_id = ANY($2::text[])
+					 ORDER BY run_id, sequence`,
+	/* The inner select applies the batch limit; the child tables of a run go
+	   with it through their own cascade. */
+	deleteSettledRunsBefore: `DELETE FROM agent_runs WHERE id IN (
+					 SELECT id FROM agent_runs
+					 WHERE tenant_id = $1 AND completed_at < $2
+					  AND status IN ('succeeded', 'failed', 'cancelled')
+					 ORDER BY completed_at LIMIT $3)`,
+	deleteRunsRequestedBy: `DELETE FROM agent_runs WHERE id IN (
+					 SELECT id FROM agent_runs
+					 WHERE tenant_id = $1 AND requested_by = $2
+					 ORDER BY id LIMIT $3)`,
+	pruneMeterRefusals: `DELETE FROM agent_meter_refusals
+					 WHERE tenant_id = $1 AND meter = $2 AND period <> $3`,
+	claimMeterRefusal: `INSERT INTO agent_meter_refusals
+					 (tenant_id, meter, period, first_refused_at)
+					 VALUES ($1, $2, $3, $4)
+					 ON CONFLICT (tenant_id, meter, period) DO NOTHING
+					 RETURNING tenant_id`,
 	listAuditEvents: `SELECT * FROM agent_audit_events_v4 WHERE tenant_id = $1
 					 ORDER BY sequence DESC LIMIT $2`,
+	exportAuditEventsPage: `SELECT * FROM agent_audit_events_v4
+					 WHERE tenant_id = $1 AND sequence > $2
+					 ORDER BY sequence LIMIT $3`,
 	pageAuditEvents1: `SELECT * FROM agent_audit_events_v4 WHERE tenant_id = $1
-							 AND (occurred_at < $2 OR (occurred_at = $3 AND sequence < $4))
-							 ORDER BY occurred_at DESC, sequence DESC LIMIT $5`,
+							 AND ${AUDIT_PAGE_KEYSET}
+							 ORDER BY occurred_at DESC, sequence DESC LIMIT $4`,
 	pageAuditEvents2: `SELECT * FROM agent_audit_events_v4 WHERE tenant_id = $1
 							 ORDER BY occurred_at DESC, sequence DESC LIMIT $2`,
 	verifyAuditChainDetailed: `SELECT * FROM agent_audit_events_v4 WHERE tenant_id = $1
@@ -999,9 +1127,16 @@ export class DatabaseAgentRepository implements AgentRepository {
 		tenantId: string,
 		access: 'read' | 'write',
 		body: (transaction: DatabaseTransaction) => Promise<T>,
+		options?: AgentReadOptions,
 	): Promise<T> {
 		await this.readyPromise;
-		return this.handles.runtime.transaction(body, { access, tenantId });
+		return this.handles.runtime.transaction(body, {
+			access,
+			tenantId,
+			/* The caller's budget reaches the statement, so a read nobody waits
+			   for stops holding a connection open. */
+			...(options?.signal === undefined ? {} : { signal: options.signal }),
+		});
 	}
 
 	/* The recovery polls have to find work before they know whose it is. They
@@ -1533,22 +1668,57 @@ export class DatabaseAgentRepository implements AgentRepository {
 			const rows = (await this.#query(transaction, AGENTS_SQL.listAgents, [
 				tenantId,
 			])) as unknown as AgentRow[];
-			const agents: AgentDefinition[] = [];
-			for (const row of rows) {
-				const agent = fromAgentRow(row);
-				agents.push({
-					...agent,
-					procedureIds: await this.#procedureIds(
-						transaction,
-						agent.tenantId,
-						agent.id,
-					),
-				});
-			}
-			return agents;
+			return await this.#withProcedureIds(transaction, rows);
 		});
 	}
 
+	async listAgentsPage(
+		tenantId: string,
+		query: AgentListQuery,
+	): Promise<AgentListPage> {
+		return this.#tx(tenantId, 'read', async (transaction) => {
+			const rows = (await this.#query(transaction, agentPageStatement(query), [
+				tenantId,
+				query.search === null ? null : likePattern(query.search),
+				...(query.after === null
+					? []
+					: [query.after.sortValue, query.after.id]),
+				query.limit,
+			])) as unknown as (AgentRow & { name_key: string })[];
+			const agents = await this.#withProcedureIds(transaction, rows);
+			const last = agents.at(-1);
+			return {
+				agents,
+				last: last
+					? {
+							nameKey: rows[rows.length - 1]!.name_key,
+							updatedAt: last.updatedAt,
+							id: last.id,
+						}
+					: null,
+			};
+		});
+	}
+
+	async #withProcedureIds(
+		transaction: DatabaseTransaction,
+		rows: readonly AgentRow[],
+	): Promise<readonly AgentDefinition[]> {
+		const agents: AgentDefinition[] = [];
+		for (const row of rows) {
+			const agent = fromAgentRow(row);
+			agents.push({
+				...agent,
+				procedureIds: await this.#procedureIds(
+					transaction,
+					agent.tenantId,
+					agent.id,
+				),
+			});
+		}
+		return agents;
+	}
+
 	providerUsage(
 		tenantId: string,
 		providerId: string,
@@ -1569,8 +1739,8 @@ export class DatabaseAgentRepository implements AgentRepository {
 				])
 			)[0] as unknown as { count: number | string };
 			return {
-				definitions: integer(definitions.count),
-				pendingRuns: integer(pendingRuns.count),
+				definitions: integer(definitions.count, 'count'),
+				pendingRuns: integer(pendingRuns.count, 'count'),
 			};
 		});
 	}
@@ -1881,12 +2051,18 @@ export class DatabaseAgentRepository implements AgentRepository {
 
 	async listRuns(
 		tenantId: string,
-		limit: number,
+		query: AgentRunListQuery,
 	): Promise<readonly AgentRun[]> {
 		return this.#tx(tenantId, 'read', async (transaction) => {
-			const rows = (await this.#query(transaction, AGENTS_SQL.listRuns, [
+			const rows = (await this.#query(transaction, runPageStatement(query), [
 				tenantId,
-				limit,
+				query.status,
+				query.agentId,
+				query.trigger,
+				query.search === null ? null : likePattern(query.search),
+				query.search,
+				...(query.after === null ? [] : [query.after.queuedAt, query.after.id]),
+				query.limit,
 			])) as unknown as RunRow[];
 			const runs: AgentRun[] = [];
 			for (const row of rows) {
@@ -1939,15 +2115,7 @@ export class DatabaseAgentRepository implements AgentRepository {
 					runId,
 					afterSequence,
 				])) as unknown as RunEventRow[]
-			).map(
-				(event): AgentExecutionEvent => ({
-					sequence: integer(event.sequence),
-					type: event.event_type,
-					timestamp: integer(event.occurred_at),
-					message: event.message,
-					metadata: metadata(event.metadata_json),
-				}),
-			);
+			).map(fromRunEventRow);
 		}
 	}
 
@@ -2482,6 +2650,22 @@ export class DatabaseAgentRepository implements AgentRepository {
 		});
 	}
 
+	async releaseAction(
+		tenantId: string,
+		invocationId: string,
+		workerId: string,
+	): Promise<boolean> {
+		return this.#tx(tenantId, 'write', async (transaction) => {
+			return (
+				(await this.#exec(transaction, AGENTS_SQL.releaseAction, [
+					tenantId,
+					invocationId,
+					workerId,
+				])) === 1
+			);
+		});
+	}
+
 	async completeAction(
 		tenantId: string,
 		invocationId: string,
@@ -2587,7 +2771,7 @@ export class DatabaseAgentRepository implements AgentRepository {
 		/* count and every BIGINT arrive as a string from the server driver, so the
 		   next sequence must be added as a number. Without this the chain reads
 		   1, then "11", then "111". */
-		const sequence = integer(previous?.sequence ?? 0) + 1;
+		const sequence = integer(previous?.sequence ?? 0, 'sequence') + 1;
 		const previousHash = previous?.event_hash ?? null;
 		const metadataJson = stableMetadata(event.metadata);
 		const eventHash = auditHash({
@@ -2632,6 +2816,29 @@ export class DatabaseAgentRepository implements AgentRepository {
 		);
 	}
 
+	async claimMeterRefusal(
+		tenantId: string,
+		meter: string,
+		period: string,
+		at: number,
+	): Promise<boolean> {
+		return this.#tx(tenantId, 'write', async (transaction) => {
+			/* The earlier month goes in the same transaction as the claim, so the
+			   workspace holds one row per meter however long it keeps refusing. */
+			await this.#exec(transaction, AGENTS_SQL.pruneMeterRefusals, [
+				tenantId,
+				meter,
+				period,
+			]);
+			const claimed = await this.#query<{ tenant_id: string }>(
+				transaction,
+				AGENTS_SQL.claimMeterRefusal,
+				[tenantId, meter, period, at],
+			);
+			return claimed.length > 0;
+		});
+	}
+
 	async listAuditEvents(
 		tenantId: string,
 		limit: number,
@@ -2648,31 +2855,21 @@ export class DatabaseAgentRepository implements AgentRepository {
 
 	async pageAuditEvents(
 		tenantId: string,
-		cursor: { readonly occurredAt: number; readonly sequence: number } | null,
-		limit: number,
-	): Promise<AgentAuditPage> {
+		query: AgentAuditListQuery,
+	): Promise<readonly AgentAuditEvent[]> {
 		return this.#tx(tenantId, 'read', async (transaction) => {
-			const rows = (cursor
+			const rows = (query.after
 				? await this.#query(transaction, AGENTS_SQL.pageAuditEvents1, [
 						tenantId,
-						cursor.occurredAt,
-						cursor.occurredAt,
-						cursor.sequence,
-						limit + 1,
+						query.after.occurredAt,
+						query.after.sequence,
+						query.limit,
 					])
 				: await this.#query(transaction, AGENTS_SQL.pageAuditEvents2, [
 						tenantId,
-						limit + 1,
+						query.limit,
 					])) as unknown as AuditRow[];
-			const page = rows.slice(0, limit).map(fromAuditRow);
-			const last = page[page.length - 1];
-			return {
-				events: page,
-				nextCursor:
-					rows.length > limit && last
-						? `${last.occurredAt}:${last.sequence}`
-						: null,
-			};
+			return rows.map(fromAuditRow);
 		});
 	}
 
@@ -2718,16 +2915,22 @@ export class DatabaseAgentRepository implements AgentRepository {
 		tenantId: string,
 		fromDay: string,
 		toDay: string,
+		options?: AgentReadOptions,
 	): Promise<readonly AgentUsageDay[]> {
-		return this.#tx(tenantId, 'read', async (transaction) => {
-			return (
-				(await this.#query(transaction, AGENTS_SQL.usageByDay, [
-					tenantId,
-					fromDay,
-					toDay,
-				])) as unknown as UsageRow[]
-			).map((row) => ({ day: row.day, ...fromUsageRow(row) }));
-		});
+		return this.#tx(
+			tenantId,
+			'read',
+			async (transaction) => {
+				return (
+					(await this.#query(transaction, AGENTS_SQL.usageByDay, [
+						tenantId,
+						fromDay,
+						toDay,
+					])) as unknown as UsageRow[]
+				).map((row) => ({ day: row.day, ...fromUsageRow(row) }));
+			},
+			options,
+		);
 	}
 
 	async usageByAgent(
@@ -2782,5 +2985,94 @@ export class DatabaseAgentRepository implements AgentRepository {
 		});
 	}
 
+	/* The operations behind the declared data classes. Each runs on this
+	   module's own lease, inside its own tenant-scoped transaction. */
+
+	async exportRunsPage(
+		tenantId: string,
+		after: AgentRunExportCursor | null,
+		limit: number,
+	): Promise<readonly ExportedAgentRun[]> {
+		return this.#tx(tenantId, 'read', async (transaction) => {
+			const runs = (after === null
+				? await this.#query(transaction, AGENTS_SQL.exportRunsPage1, [
+						tenantId,
+						limit,
+					])
+				: await this.#query(transaction, AGENTS_SQL.exportRunsPage2, [
+						tenantId,
+						after.queuedAt,
+						after.queuedAt,
+						after.id,
+						limit,
+					])) as unknown as RunRow[];
+			if (runs.length === 0) return [];
+			/* One query for the steps of the whole page: a run is a row, not a
+			   round trip. */
+			const events = (await this.#query(
+				transaction,
+				AGENTS_SQL.exportRunEvents,
+				[tenantId, runs.map((run) => run.id)],
+			)) as unknown as RunEventPageRow[];
+			const steps = new Map<string, AgentExecutionEvent[]>();
+			for (const event of events) {
+				const existing = steps.get(event.run_id);
+				if (existing) existing.push(fromRunEventRow(event));
+				else steps.set(event.run_id, [fromRunEventRow(event)]);
+			}
+			return runs.map((run) => ({
+				run: fromRunRow(run),
+				events: steps.get(run.id) ?? [],
+			}));
+		});
+	}
+
+	async deleteSettledRunsBefore(
+		tenantId: string,
+		before: number,
+		limit: number,
+	): Promise<number> {
+		return this.#tx(tenantId, 'write', (transaction) =>
+			this.#exec(transaction, AGENTS_SQL.deleteSettledRunsBefore, [
+				tenantId,
+				before,
+				limit,
+			]),
+		);
+	}
+
+	/* A run this removes while a worker holds it takes its lease with it: the
+	   next renewal finds no row, the worker stops the execution as it does for
+	   any lost lease, and its settle write reaches nothing. */
+	async deleteRunsRequestedBy(
+		tenantId: string,
+		accountId: string,
+		limit: number,
+	): Promise<number> {
+		return this.#tx(tenantId, 'write', (transaction) =>
+			this.#exec(transaction, AGENTS_SQL.deleteRunsRequestedBy, [
+				tenantId,
+				accountId,
+				limit,
+			]),
+		);
+	}
+
+	async exportAuditEventsPage(
+		tenantId: string,
+		afterSequence: number,
+		limit: number,
+	): Promise<readonly AgentAuditEvent[]> {
+		return this.#tx(tenantId, 'read', async (transaction) =>
+			(
+				(await this.#query(transaction, AGENTS_SQL.exportAuditEventsPage, [
+					tenantId,
+					afterSequence,
+					limit,
+				])) as unknown as AuditRow[]
+			).map(fromAuditRow),
+		);
+	}
+
 	async close(): Promise<void> {}
 }