@flowdular/sdk 0.2.3 → 0.3.0

package/modules/agents/spec/module.yaml

@@ -1,6 +1,6 @@
 schemaVersion: 1
 id: agents.core
-specVersion: 0.9.1
+specVersion: 0.12.9
 status: approved
 name: Agentic Core
 description: Provides tenant-created and module-owned business agent definitions, tenant-scoped provider connections, reusable procedures, durable streamed execution, run history, and the public run queue used by optional automation modules.
@@ -14,15 +14,26 @@ capabilities:
   - cli
 dependencies:
   - id: system.core
-    range: 0.5.0
+    range: ^0.7.0
   - id: auth.core
-    range: 0.10.0
+    range: ^0.13.0
+  - id: metering.core
+    range: ^0.1.0
+  - id: reports.core
+    range: ^0.1.0
+requires:
+  - id: notifications.publish.v1
+    optional: true
+  - id: metering.meters.v1
+  - id: reports.v1
+    optional: true
 tenancy: required
 locales:
   - en
   - pl
 invariants:
   - Every agent managed by agents.core is a business agent with explicit ownership. A tenant-created definition is owned by one tenant; a module-owned definition is owned by one enabled module and receives a separate tenant-scoped execution binding. Sandbox coding specialists are outside agents.core. Every binding, run, and repository query receives the trusted tenant identifier.
+  - agents.core registers the report provider agents.runs through the public capability reports.v1 at composition when reports.core is present, and continues without it when it is not. The provider answers the runs and token totals of the requested range as tiles and runs and tokens per day as series, read from the existing agent run cost rollup inside this module's own tenant transaction; it prices nothing, writes nothing and opens no other module's tables. It names itself, each tile and each line with a key of this module's own translation bundle beside the English literal, and hands the reader's time budget to that transaction so the statement is cancelled when the budget expires.
   - An enabled module may register immutable business agent behavior during platform composition with defineAgent. Its stable identity is derived from module id and agent key, its positive definition revision is supplied by the module, and malformed or duplicate identities fail platform boot before workers start.
   - Module-owned instructions, names, maximum tool allowlists, and execution limits are read-only module source. A tenant administrator may bind an available provider and model, pause the binding, and reduce its enabled tool set, but cannot broaden the module allowlist or edit the module behavior in the Agents UI.
   - An unconfigured module-owned agent is visible as unconfigured but cannot be activated, published in a workflow, or executed until its tenant binding names a usable provider and model.
@@ -67,7 +78,12 @@ invariants:
   - Business actions exposed to workflows are explicit versioned contracts. Only read and workspace-write risks are eligible, input and output are schema checked, and every invocation is persisted before execution.
   - Workflow action invocations receive a trusted actor, permission snapshot, idempotency key, and AbortSignal. Secrets, raw input, and raw output never enter audit metadata.
   - Every request-time read and write runs on a tenant-scoped database handle. The worker recovery polls are the only cross-tenant reads, they run on a separate read-only role, and the module agent catalog is reconciled at boot on the schema-owner lease that runs migrations.
+  - Run outcome notifications are an optional integration. When a durable run reaches a terminal state the worker resolves notifications.publish.v1 from the platform capability registry at that moment, never at composition time, and publishes the outcome keyed by the run id. notifications.core is never a declared dependency. An absent capability, a run with no person behind it, and a run a workflow owns publish nothing. A publisher failure is logged once at warning level and never changes the settled run, and a repeated terminal step reports the same outcome instead of a second notification.
   - Every table that carries tenant data enables and forces row-level security with a policy bound to the transaction-local tenant, including the child tables that hang off a run, a definition or a provider connection. A read by a caller-supplied parent id therefore cannot cross a workspace even when application code forgets the predicate.
+  - agents.core declares three data classes to the platform registry while it composes, and performs their operations itself on its own leases under its own tenant transaction. agents.core.runs holds the run record, its steps and the child rows that hang off it, keeps them 90 days by default, sweeps only settled runs in bounded batches so a queued or running run is never taken from its worker, exports one workspace by keyset in bounded pages, and erases the runs one account requested in bounded batches, reporting a full batch as truncated. agents.core.audit-events is exportable and is kept until a person deletes it, because the trail is hash chained and removing its oldest links by age would make the next verification report a break it cannot tell from tampering. agents.core.provider-credentials is workspace configuration, is never swept, and is excluded from the export with a stated reason because the row exists to hold a sealed provider secret. No export carries a credential or a sealed payload.
+  - agents.core depends on metering.core and requires the public metering.meters.v1 capability, so the module registry composes metering.core first and refuses a composition that leaves it out or that provides no meter registry. The meters agents.core.run-tokens and agents.core.runs are declared once while agents.core composes; every later use resolves the registry through the capability at the point of use rather than holding the one composition found. A settled run is counted once, keyed by the run id, so a repeated terminal step reports the same fact instead of a second one, and a run that reported no tokens counts the run alone. Counting is advisory and runs after the terminal row commits, so a metering failure never changes a settled run.
+  - Before a run is created the module asks metering.meters.v1 about both meters a run costs, on every enqueue path. agents.core.runs is asked for one run first and agents.core.run-tokens for the tokens the run may read and write, so a workspace that has spent either allowance is refused. A refused verdict fails the run start with METER_LIMIT_EXCEEDED naming that meter and creates no run. An allowed or warning verdict starts the run unchanged, and the settled fact replaces the estimate.
+  - A refused meter is recorded in this module's own hash-chained trail once per workspace, meter and calendar month, with the meter, the estimate, the month's usage and the limit. The claim that a refusal was already recorded is a row of agents.core's own tenant table, and taking it removes the rows of earlier months, so the workspace holds one row per meter however long it keeps being refused. Every attempt still asks metering.core, so a workspace is refused on what its month holds now and never on a remembered verdict, and the first refusal after the month turns is recorded again.
 permissions:
   - id: agents.definitions.read
     description: Read agent definitions in the active tenant.
@@ -96,11 +112,13 @@ dataOwnership:
   - agents.core owns the per-run cost projection, its per-day and per-agent rollups, and the budget caps declared as module settings.
   - agents.core owns immutable agent revision snapshots, workflow-bound run output contracts, and durable versioned action invocation state.
   - Business modules own their records and expose narrowly scoped tools to the harness; agents.core never bypasses their services or ACL rules.
+  - metering.core owns meter declarations as recorded, day buckets and limits. agents.core owns the meters it declares, the standing refusal rows that keep one refused meter out of its trail per workspace and month, and the decision about what a refusal means for a run; it never reads or writes metering storage.
+  - notifications.core owns inbox items, deliveries, and read state. agents.core owns the run it reports and hands over only the run id, the outcome kind, a bounded English title and outcome summary, and the accountable member; it never writes or reads notification records and never receives them back.
 acceptanceScenarios:
   - id: AGENTS-LIST
     given: Tenant-created business agents and enabled modules with module-owned business agents exist.
     when: An authorized principal lists agents.
-    then: The active tenant receives a deterministic catalog with an explicit tenant or module ownership discriminator and no definition from another tenant or disabled module.
+    then: The active tenant receives a deterministic catalog with an explicit tenant or module ownership discriminator and no definition from another tenant or disabled module. Tenant definitions arrive as pages of at most 200 rows, 50 by default, sorted by name or updatedAt in either direction with an optional search term, and each page ends in an opaque cursor bound to the tenant, the sort and the filters that a request with a different tenant, sort or filter cannot reuse; the module catalog, providers, tools and procedures are read separately.
   - id: AGENTS-MODULE-REGISTER
     given: An enabled module registers a valid defineAgent definition during composition.
     when: The platform finishes composing modules before starting workers.
@@ -133,6 +151,10 @@ acceptanceScenarios:
     given: An active agent and a principal with execution permission.
     when: A playground or platform run is requested.
     then: A queued run is durably persisted and a 202 response is returned before provider execution completes.
+  - id: AGENTS-RUNS-LIST
+    given: A tenant holds more runs than one page carries.
+    when: A principal with agents.runs.read lists runs.
+    then: Runs arrive newest first or oldest first by queuedAt in pages of at most 200 rows, 50 by default, narrowed by status, agent, trigger or a search term on the server, and each page ends in an opaque cursor bound to the tenant, the sort and the filters that another tenant, sort or filter cannot reuse; one run with its timeline is read by its id through a separate endpoint.
   - id: AGENTS-EXECUTE
     given: A queued run with valid server-side grants and bounded execution settings.
     when: The harness worker claims the run.
@@ -224,7 +246,7 @@ acceptanceScenarios:
   - id: AGENTS-AUDIT-READ
     given: A principal reads the agent audit trail over HTTP.
     when: The principal lacks agents.runs.read, or holds it and pages with a cursor.
-    then: The request is denied before any row is read without the scope, and with it only the active tenant's events are returned newest first with a stable occurred-at and sequence cursor and the chain fields.
+    then: The request is denied before any row is read without the scope, and with it only the active tenant's events are returned newest first with a stable occurred-at and sequence cursor and the chain fields. A page carries at most 100 events, 50 by default, and the cursor is opaque and bound to the tenant, so a cursor issued to another tenant or edited by a client is refused.
   - id: AGENTS-AUDIT-VERIFY
     given: A stored agent audit row is altered after it was written.
     when: A principal with agents.runs.read verifies the chain over HTTP, reusing the same walk as the audit-verify CLI.
@@ -265,7 +287,43 @@ acceptanceScenarios:
     given: A schedule, webhook, or other service identity was configured by an authenticated user.
     when: It initiates workflow agent work or a versioned action.
     then: Durable state records the service actor and its configuring user so history never presents background work as an anonymous system mutation.
+  - id: AGENTS-NOTIFY-RUN
+    given: A durable agent run started by a member reaches a terminal state, and the optional notifications module may or may not be composed.
+    when: The worker commits the terminal status.
+    then: With notifications.core composed, exactly one agent-run-completed or agent-run-failed notification is published after that commit, keyed by the run id, addressed to the member accountable for the run, and carrying no credentials, prompt, or transcript; without it, for a run a workflow owns, or when the publisher fails, the run settles unchanged and nothing is published.
   - id: AGENT-CHILD-ISOLATION
     given: Two workspaces each own an agent run with procedure snapshots and a provider connection with model readiness.
     when: A caller supplies the other workspace's run id or provider id directly.
     then: The read returns nothing, because those child tables carry their own workspace and force row-level security rather than relying on their parent.
+  - id: AGENTS-DATA-CLASSES
+    given: Two workspaces hold agent runs of several ages with their steps, one run still queued, a provider connection with a sealed credential, and the platform has sealed the data class registry.
+    when: The platform sweeps, exports and erases the declared classes for one of them.
+    then: The sweep removes only that workspace's settled runs strictly older than the cutoff and at most the batch it was given, taking their steps with them while the queued run stays; the export streams that workspace's runs and its audit trail through the sink in keyset pages with the oldest and newest record time, answers no rows and no range for a workspace that holds none, and carries no provider credential; the audit class declares no sweep; and erasing a subject removes the runs that account requested in that workspace alone, reporting a full batch as truncated.
+  - id: AGENTS-METER-COUNT
+    given: A workspace runs an agent and metering.core is composed, as every deployment of agents.core must compose it.
+    when: The platform composes and the run settles.
+    then: agents.core.run-tokens and agents.core.runs are declared at composition, the settled run counts one run and its reported tokens against the run id, and a run that reported none counts the run alone.
+  - id: AGENTS-METER-REFUSED
+    given: A workspace has used its monthly token allowance for agents.core.run-tokens.
+    when: A further run is requested through any enqueue path.
+    then: The request is refused with METER_LIMIT_EXCEEDED before a run row exists, the refusal is recorded in the agents audit trail with the meter, the estimate, the usage and the limit, the chain still verifies, and nothing is counted for the refused request.
+  - id: AGENTS-METERING-REQUIRED
+    given: A composition of agents.core with the platform modules it depends on.
+    when: The module registry composes it without metering.core, and again with a metering.core that provides no meter registry.
+    then: The first is refused with MODULE_DEPENDENCY_MISSING and the second with MODULE_CAPABILITY_MISSING; a complete composition orders metering.core before agents.core.
+  - id: AGENTS-METER-RUNS-LIMIT
+    given: A workspace that has used its monthly allowance of agents.core.runs while its token allowance is untouched.
+    when: A run is requested.
+    then: The request is refused with METER_LIMIT_EXCEEDED before a run row exists, the refusal names the runs meter and the amount of one run, and the token allowance is never asked.
+  - id: AGENTS-METER-REFUSAL-ONCE
+    given: A workspace refused on one meter that retries the request several times inside one month.
+    when: Every attempt is made.
+    then: Each is refused and asks metering.core again, the trail carries exactly one refusal for that workspace, meter and month, the chain still verifies, and the first attempt in the next month is recorded once more.
+  - id: AGENTS-ERASE-RUNNING-RUN
+    given: A run a worker of this process is executing, requested by the account an erasure names.
+    when: The agents.core.runs erase operation removes it mid-flight.
+    then: The worker's lease renewal cannot prove ownership, the execution is aborted as a lost lease, no terminal status and no terminal audit event are written for the run that is gone, and the worker returns to idle.
+  - id: AGENTS-REPORT-RUNS
+    given: A workspace with runs settled on several days inside the requested range and runs settled outside it.
+    when: The reports.core provider agents.runs is read.
+    then: It answers the runs and token totals of the range as tiles and runs and tokens per day as two series read from the existing rollup, counting only the days inside the range and writing nothing. It names itself, its tiles and its lines with keys of this module's bundle, and it passes the reader's time budget into its own tenant transaction so an expired budget cancels the statement instead of leaving it running.

package/modules/agents/src/api/endpoints.ts

@@ -1,9 +1,14 @@
+import { randomBytes } from 'node:crypto';
 import {
+	decodeCursor,
 	defineEndpoint,
+	encodeCursor,
 	HttpProblem,
 	jsonResponse,
+	pageResponse,
 	problemResponse,
 	readJsonObject,
+	readPageQuery,
 	requiredInteger,
 	requiredString,
 } from '@flowdular/sdk/server';
@@ -14,18 +19,20 @@ import {
 	principalFromContext,
 	sessionMutationDenial,
 } from '@flowdular/sdk/modules/auth/server';
-import type { AgentExecutionEvent } from '@flowdular/sdk/harness';
+import type { AgentExecutionEvent, AgentRunTrigger } from '@flowdular/sdk/harness';
 import { userActor } from '@flowdular/sdk/kernel';
 import { AGENT_PERMISSIONS } from '../acl/permissions.ts';
 import type {
-	AgentDefinition,
+	AgentListSort,
 	AgentProcedure,
 	AgentProcedureSnapshot,
 	AgentProviderKind,
 	AgentProviderModelConfiguration,
 	AgentRunDetail,
+	AgentRunStatus,
 	AgentProcedureStatus,
 	AgentStatus,
+	ListDirection,
 	CreateAgentInput,
 	CreateAgentProviderInput,
 	CreateAgentProcedureInput,
@@ -39,6 +46,30 @@ import { AgentServiceError } from '../services/agent-service.ts';
 import { AgentProviderServiceError } from '../services/provider-service.ts';
 import type { AgentRuntime } from '../server/runtime.ts';
 
+/** The default page of every list here, and the ceiling of the audit trail. */
+const LIST_PAGE_LIMIT = 50;
+const AUDIT_PAGE_LIMIT = 100;
+const SEARCH_LIMIT = 200;
+const AGENT_SORTS: readonly AgentListSort[] = ['name', 'updatedAt'];
+const AGENT_SORT_DIRECTIONS: Readonly<Record<AgentListSort, ListDirection>> = {
+	name: 'asc',
+	updatedAt: 'desc',
+};
+const RUN_SORTS = ['queuedAt'] as const;
+const RUN_STATUSES: readonly AgentRunStatus[] = [
+	'queued',
+	'running',
+	'succeeded',
+	'failed',
+	'cancelled',
+];
+const RUN_TRIGGERS: readonly AgentRunTrigger[] = [
+	'playground',
+	'workflow',
+	'service',
+	'schedule',
+];
+
 function failure(error: unknown): Response {
 	if (
 		error instanceof AgentServiceError ||
@@ -196,6 +227,77 @@ function agentInput(value: Record<string, unknown>): CreateAgentInput {
 	};
 }
 
+function invalid(message: string): HttpProblem {
+	return new HttpProblem('INVALID_INPUT', message, 400);
+}
+
+function queryValue(url: URL, key: string, maximum: number): string | null {
+	const raw = url.searchParams.get(key);
+	if (raw === null) return null;
+	const value = raw.trim();
+	if (value === '') return null;
+	if (value.length > maximum) throw invalid(`${key} is too long.`);
+	return value;
+}
+
+function queryChoice<Choice extends string>(
+	url: URL,
+	key: string,
+	choices: readonly Choice[],
+): Choice | null {
+	const value = queryValue(url, key, 32);
+	if (value === null) return null;
+	const chosen = choices.find((choice) => choice === value);
+	if (chosen === undefined) {
+		throw invalid(`${key} must be one of ${choices.join(', ')}.`);
+	}
+	return chosen;
+}
+
+interface ListOrder<Sort extends string> {
+	readonly sort: Sort;
+	readonly direction: ListDirection;
+}
+
+function listOrder<Sort extends string>(
+	url: URL,
+	sorts: readonly Sort[],
+	defaults: Readonly<Record<Sort, ListDirection>>,
+): ListOrder<Sort> {
+	const sort = queryChoice(url, 'sort', sorts) ?? sorts[0]!;
+	const direction = queryChoice(url, 'direction', ['asc', 'desc'] as const);
+	return { sort, direction: direction ?? defaults[sort] };
+}
+
+type CursorScope = Readonly<Record<string, string | number>> & {
+	readonly list: 'definitions' | 'runs' | 'audit';
+};
+
+/* A cursor answers one request: the list, tenant, order and filters it was
+   signed with are compared to the request's, and its keyset fields must carry
+   the type the statement binds, so a cursor of another list of the same
+   workspace is refused rather than moved onto a result set it never described. */
+function boundCursor(
+	raw: string | null,
+	secret: Uint8Array,
+	scope: CursorScope,
+	keys: Readonly<Record<string, 'string' | 'number'>>,
+): Record<string, string | number> | null {
+	if (raw === null) return null;
+	const cursor = decodeCursor(raw, secret);
+	const refused = () =>
+		new HttpProblem('CURSOR_INVALID', 'The page cursor is not valid.', 400);
+	for (const [key, value] of Object.entries(scope)) {
+		if (cursor[key] !== value) throw refused();
+	}
+	for (const [key, type] of Object.entries(keys)) {
+		const value = cursor[key];
+		if (typeof value !== type) throw refused();
+		if (type === 'number' && !Number.isSafeInteger(value)) throw refused();
+	}
+	return cursor;
+}
+
 /* A tenant agent and a run carry the deprecated projection beside the canonical
    field, so a client on either contract reads the same configuration and the
    same retained evidence. */
@@ -332,6 +434,10 @@ async function runEventStream(
 }
 
 export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
+	/* Module-owned and never stored: a cursor names a position in one
+	   workspace's own list, so a restart invalidating one costs a client the
+	   first page. */
+	const cursorSecret = randomBytes(32);
 	const listAgents = defineEndpoint({
 		id: 'agents.definitions.list',
 		path: '/api/agents',
@@ -341,17 +447,84 @@ export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
 			permission: AGENT_PERMISSIONS.definitionsRead,
 		},
 		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const url = new URL(octane.request.url);
+				const page = readPageQuery(url, { defaultLimit: LIST_PAGE_LIMIT });
+				const order = listOrder(url, AGENT_SORTS, AGENT_SORT_DIRECTIONS);
+				const search = queryValue(url, 'q', SEARCH_LIMIT);
+				const scope = {
+					list: 'definitions' as const,
+					tenant: principal.tenantId,
+					sort: order.sort,
+					direction: order.direction,
+					q: search ?? '',
+				};
+				const cursor = boundCursor(page.cursor, cursorSecret, scope, {
+					key: order.sort === 'name' ? 'string' : 'number',
+					id: 'string',
+				});
+				const result = await (
+					await runtime.service()
+				).listAgentsPage(principal.tenantId, {
+					sort: order.sort,
+					direction: order.direction,
+					search,
+					limit: page.limit,
+					after:
+						cursor === null
+							? null
+							: {
+									sortValue:
+										order.sort === 'name'
+											? String(cursor.key)
+											: Number(cursor.key),
+									id: String(cursor.id),
+								},
+				});
+				return pageResponse({
+					items: result.agents.map((agent) =>
+						withDeprecatedProcedureFields<TenantAgentView>({
+							...agent,
+							ownership: { kind: 'tenant' },
+						}),
+					),
+					limit: page.limit,
+					nextCursor:
+						result.last && result.agents.length === page.limit
+							? encodeCursor(
+									{
+										...scope,
+										key:
+											order.sort === 'name'
+												? result.last.nameKey
+												: result.last.updatedAt,
+										id: result.last.id,
+									},
+									cursorSecret,
+								)
+							: null,
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	/* What the definitions screen needs beside its page: the module catalog,
+	   the providers, the registered tools and the procedures. */
+	const agentContext = defineEndpoint({
+		id: 'agents.definitions.context',
+		path: '/api/agents/context',
+		methods: ['GET'],
+		access: {
+			kind: 'permission',
+			permission: AGENT_PERMISSIONS.definitionsRead,
+		},
+		resolveIdentity: endpointIdentityFromContext,
 		handler: async ({ octane }) => {
 			const principal = principalFromContext(octane)!;
 			return jsonResponse({
-				agents: (
-					await (await runtime.service()).listAgents(principal.tenantId)
-				).map((agent: AgentDefinition) =>
-					withDeprecatedProcedureFields<TenantAgentView>({
-						...agent,
-						ownership: { kind: 'tenant' },
-					}),
-				),
 				moduleAgents: await (
 					await runtime.service()
 				).listModuleAgents(principal.tenantId),
@@ -711,18 +884,72 @@ export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
 			try {
 				const principal = principalFromContext(octane)!;
 				const url = new URL(octane.request.url);
-				const runId = url.searchParams.get('id');
-				return runId
-					? jsonResponse({
-							run: await (
-								await runtime.service()
-							).getRunTimeline(principal.tenantId, runId),
-						})
-					: jsonResponse({
-							runs: (
-								await (await runtime.service()).listRuns(principal.tenantId)
-							).map(withDeprecatedRunFields),
-						});
+				const page = readPageQuery(url, { defaultLimit: LIST_PAGE_LIMIT });
+				const order = listOrder(url, RUN_SORTS, { queuedAt: 'desc' });
+				const filters = {
+					status: queryChoice(url, 'status', RUN_STATUSES),
+					agentId: queryValue(url, 'agentId', 128),
+					trigger: queryChoice(url, 'trigger', RUN_TRIGGERS),
+					search: queryValue(url, 'q', SEARCH_LIMIT),
+				};
+				const scope = {
+					list: 'runs' as const,
+					tenant: principal.tenantId,
+					sort: order.sort,
+					direction: order.direction,
+					status: filters.status ?? '',
+					agentId: filters.agentId ?? '',
+					trigger: filters.trigger ?? '',
+					q: filters.search ?? '',
+				};
+				const cursor = boundCursor(page.cursor, cursorSecret, scope, {
+					queuedAt: 'number',
+					id: 'string',
+				});
+				const runs = await (
+					await runtime.service()
+				).listRuns(principal.tenantId, {
+					...filters,
+					direction: order.direction,
+					limit: page.limit,
+					after:
+						cursor === null
+							? null
+							: { queuedAt: Number(cursor.queuedAt), id: String(cursor.id) },
+				});
+				const last = runs.at(-1);
+				return pageResponse({
+					items: runs.map(withDeprecatedRunFields),
+					limit: page.limit,
+					nextCursor:
+						last && runs.length === page.limit
+							? encodeCursor(
+									{ ...scope, queuedAt: last.queuedAt, id: last.id },
+									cursorSecret,
+								)
+							: null,
+				});
+			} catch (error) {
+				return failure(error);
+			}
+		},
+	});
+	const getRun = defineEndpoint({
+		id: 'agents.runs.get',
+		path: '/api/agent-runs/get',
+		methods: ['GET'],
+		access: { kind: 'permission', permission: AGENT_PERMISSIONS.runsRead },
+		resolveIdentity: endpointIdentityFromContext,
+		handler: async ({ octane }) => {
+			try {
+				const principal = principalFromContext(octane)!;
+				const runId = queryValue(new URL(octane.request.url), 'id', 128);
+				if (runId === null) throw invalid('id is required.');
+				return jsonResponse({
+					run: await (
+						await runtime.service()
+					).getRunTimeline(principal.tenantId, runId),
+				});
 			} catch (error) {
 				return failure(error);
 			}
@@ -857,17 +1084,44 @@ export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
 		handler: async ({ octane }) => {
 			try {
 				const principal = principalFromContext(octane)!;
-				const url = new URL(octane.request.url);
-				const limit = Number(url.searchParams.get('limit') ?? '50');
-				return jsonResponse(
-					await (
-						await runtime.service()
-					).pageAuditEvents(
-						principal.tenantId,
-						url.searchParams.get('cursor'),
-						limit,
-					),
-				);
+				const page = readPageQuery(new URL(octane.request.url), {
+					maxLimit: AUDIT_PAGE_LIMIT,
+					defaultLimit: LIST_PAGE_LIMIT,
+				});
+				const scope = { list: 'audit' as const, tenant: principal.tenantId };
+				const cursor = boundCursor(page.cursor, cursorSecret, scope, {
+					occurredAt: 'number',
+					sequence: 'number',
+				});
+				const events = await (
+					await runtime.service()
+				).pageAuditEvents(principal.tenantId, {
+					limit: page.limit,
+					after:
+						cursor === null
+							? null
+							: {
+									occurredAt: Number(cursor.occurredAt),
+									sequence: Number(cursor.sequence),
+								},
+				});
+				const last = events.at(-1);
+				/* The body keeps `events` and `nextCursor`: auth.core's audit screen
+				   reads this trail beside the platform one through that shape. */
+				return jsonResponse({
+					events,
+					nextCursor:
+						last && events.length === page.limit
+							? encodeCursor(
+									{
+										...scope,
+										occurredAt: last.occurredAt,
+										sequence: last.sequence,
+									},
+									cursorSecret,
+								)
+							: null,
+				});
 			} catch (error) {
 				return failure(error);
 			}
@@ -1062,6 +1316,7 @@ export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
 	});
 	return [
 		listAgents.serverRoute,
+		agentContext.serverRoute,
 		updateModuleAgentBinding.serverRoute,
 		createAgent.serverRoute,
 		updateAgent.serverRoute,
@@ -1076,6 +1331,7 @@ export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
 		archiveSkill.serverRoute,
 		deleteSkill.serverRoute,
 		listRuns.serverRoute,
+		getRun.serverRoute,
 		enqueueRun.serverRoute,
 		cancelRun.serverRoute,
 		workerStatus.serverRoute,
@@ -1093,6 +1349,7 @@ export function createAgentRoutes(auth: AuthRuntime, runtime: AgentRuntime) {
 
 export const endpoints = [
 	'agents.definitions.list',
+	'agents.definitions.context',
 	'agents.module-bindings.update',
 	'agents.definitions.create',
 	'agents.definitions.update',
@@ -1107,6 +1364,7 @@ export const endpoints = [
 	'agents.skills.archive',
 	'agents.skills.delete',
 	'agents.runs.list',
+	'agents.runs.get',
 	'agents.runs.enqueue',
 	'agents.runs.cancel',
 	'agents.runs.worker',

package/modules/agents/src/cli/commands.json

@@ -13,6 +13,17 @@
 				"supportsDryRun": false
 			}
 		},
+		{
+			"path": ["agents", "secrets-rotate"],
+			"capability": {
+				"id": "agents.secrets.rotate",
+				"version": 1,
+				"summary": "Re-seal stored provider credentials with the current encryption key.",
+				"risk": "process",
+				"requiresApprovedSpec": false,
+				"supportsDryRun": true
+			}
+		},
 		{
 			"path": ["agents", "audit-verify"],
 			"capability": {

package/modules/agents/src/cli/index.ts

@@ -9,6 +9,8 @@ import {
 } from '@flowdular/sdk/database';
 import { AI_PROVIDER_KINDS } from '@flowdular/sdk/harness/catalog';
 import { agentRuntimeOptionsFromEnvironment } from '../server/runtime.ts';
+import { rotateProviderCredentials } from '../services/credential-rotation.ts';
+import { credentialVaultFromEnvironment } from '../services/credential-vault.ts';
 import { DatabaseProviderRepository } from '../services/provider-repository.ts';
 import {
 	DatabaseAgentRepository,
@@ -24,6 +26,16 @@ const statusCapability = {
 	supportsDryRun: false,
 };
 
+const rotateCapability = {
+	id: 'agents.secrets.rotate',
+	version: 1,
+	summary:
+		'Re-seal stored provider credentials with the current encryption key.',
+	risk: 'process' as const,
+	requiresApprovedSpec: false,
+	supportsDryRun: true,
+};
+
 const auditCapability = {
 	id: 'agents.audit.verify',
 	version: 1,
@@ -127,6 +139,39 @@ export const cliExtension = defineCliExtension({
 				}
 			},
 		},
+		{
+			path: ['agents', 'secrets-rotate'],
+			capability: rotateCapability,
+			execute: async (context) => {
+				/* The report names key ids and row counts only; a credential never
+				   reaches the command output. */
+				const vault = credentialVaultFromEnvironment(
+					process.env,
+					context.workspaceRoot,
+				);
+				const opened = await open(context);
+				try {
+					const report = await rotateProviderCredentials({
+						runtime: opened.runtime.database,
+						background: opened.background.database,
+						vault,
+						apply: context.apply,
+					});
+					return {
+						data: { moduleId: 'agents.core', ...report },
+						evidence: ['modules/agents/spec/module.yaml', 'docs/operations.md'],
+						warnings:
+							report.skipped > 0
+								? [
+										`${report.skipped} rows were rewritten by the application while this ran and keep their own envelope. Run the command again.`,
+									]
+								: [],
+					};
+				} finally {
+					await close(opened);
+				}
+			},
+		},
 		{
 			path: ['agents', 'audit-verify'],
 			capability: auditCapability,