@flowdular/sdk 0.2.3 → 0.3.0

package/modules/agents/src/client/AgentsView.tsrx

@@ -7,6 +7,7 @@ import {
 	Drawer,
 	Icon,
 	PageHeader,
+	type TableSort,
 } from '@flowdular/sdk/ui';
 import { useValue } from 'segment-state';
 import type {
@@ -18,7 +19,8 @@ import {
 	archiveAgent,
 	createAgent,
 	deleteAgent,
-	loadAgents,
+	loadAgentContext,
+	loadAgentsPage,
 	updateAgent,
 	updateModuleAgentBinding,
 } from './api.ts';
@@ -26,13 +28,25 @@ import { AgentDefinitionForm } from './AgentDefinitionForm.tsrx';
 import { AgentDefinitionList } from './AgentDefinitionList.tsrx';
 import { ModuleAgentBindingForm } from './ModuleAgentBindingForm.tsrx';
 import { ModuleAgentList } from './ModuleAgentList.tsrx';
-import { createAgentClientState } from './state.ts';
+import {
+	agentSorting,
+	createAgentClientState,
+	FIRST_PAGE,
+	moveToPage,
+	PAGE_SIZE,
+	pageCursor,
+	pageLoaded,
+} from './state.ts';
 
 export interface AgentsViewProps {
 	readonly csrfToken: string;
 	readonly canManage: boolean;
 }
 
+/* A search term waits for the reader to stop typing before it becomes a
+   request; a sort or page change is one deliberate action and goes at once. */
+const SEARCH_DEBOUNCE_MS = 250;
+
 export function AgentsView(props: AgentsViewProps) @{
 	const client = useMemo(() => createAgentClientState(), []);
 	const [agents] = useValue(client.state.agents);
@@ -48,7 +62,9 @@ export function AgentsView(props: AgentsViewProps) @{
 	);
 	const [status, setStatus] = useValue(client.state.status);
 	const [error, setError] = useValue(client.state.error);
-	const [query, setQuery] = useValue(client.state.query);
+	const [query] = useValue(client.state.query);
+	const [sorting] = useValue(client.state.sorting);
+	const [page] = useValue(client.state.page);
 	const [moduleQuery, setModuleQuery] = useValue(client.state.moduleQuery);
 	const [editorOpen, setEditorOpen] = useValue(client.state.editorOpen);
 	const [moduleEditorOpen, setModuleEditorOpen] = useValue(
@@ -60,22 +76,11 @@ export function AgentsView(props: AgentsViewProps) @{
 	const selected = agents.find((agent) => agent.id === selectedAgentId) ?? null;
 	const selectedModuleAgent =
 		moduleAgents.find((agent) => agent.id === selectedModuleAgentId) ?? null;
-	const active = agents.filter((agent) => agent.status === 'active');
 	const activeModuleAgents = moduleAgents.filter(
 		(agent) => agent.status === 'active',
 	);
-	const term = query.trim().toLocaleLowerCase(activeLocale());
-	const visible =
-		term === ''
-			? agents
-			: agents.filter(
-					(agent) =>
-						agent.name.toLocaleLowerCase(activeLocale()).includes(term) ||
-							agent.key.includes(term) ||
-							agent.description.toLocaleLowerCase(activeLocale()).includes(
-								term,
-							),
-				);
+	const term = query.trim();
+	const sort = sorting[0] ?? { key: 'name', desc: false };
 	const moduleTerm = moduleQuery.trim().toLocaleLowerCase(activeLocale());
 	const visibleModuleAgents =
 		moduleTerm === ''
@@ -90,29 +95,92 @@ export function AgentsView(props: AgentsViewProps) @{
 							),
 				);
 
+	const loadPage = async (isCurrent: () => boolean = () => true) => {
+		setStatus('loading');
+		setError('');
+		try {
+			const result = await loadAgentsPage({
+				limit: PAGE_SIZE,
+				cursor: pageCursor(page),
+				sort: sort.key === 'updatedAt' ? 'updatedAt' : 'name',
+				direction: sort.desc ? 'desc' : 'asc',
+				q: term,
+			});
+			if (!isCurrent()) return;
+			client.store.act((transaction) => {
+				transaction.set(client.state.agents, result.items);
+				transaction.set(
+					client.state.page,
+					pageLoaded(page, result.page.nextCursor),
+				);
+			}, 'agents/page-loaded');
+		} catch (loadError) {
+			if (!isCurrent()) return;
+			setError(
+				loadError instanceof Error
+					? loadError.message
+					: t('agents.definitions.error.load'),
+			);
+		} finally {
+			if (isCurrent()) setStatus('idle');
+		}
+	};
+
 	const refresh = async () => {
 		setStatus('loading');
 		setError('');
 		try {
-			const result = await loadAgents();
+			const result = await loadAgentContext();
 			client.store.act((transaction) => {
-				transaction.set(client.state.agents, result.agents);
 				transaction.set(client.state.moduleAgents, result.moduleAgents);
 				transaction.set(client.state.providers, result.providers);
 				transaction.set(client.state.tools, result.tools);
 				transaction.set(client.state.procedures, result.procedures);
-			}, 'agents/loaded');
+			}, 'agents/context-loaded');
 		} catch (loadError) {
 			setError(
 				loadError instanceof Error
 					? loadError.message
 					: t('agents.definitions.error.load'),
 			);
-		} finally {
 			setStatus('idle');
+			return;
 		}
+		await loadPage();
 	};
 
+	/* Every change of the search, the sort or the page is one request for the
+   page it names; the reset to page zero happens where the change is made. */
+	const setQuery = (value: string) => client.store.act((transaction) => {
+		transaction.set(client.state.query, value);
+		transaction.set(client.state.page, FIRST_PAGE);
+	}, 'agents/search');
+	const setSorting = (sorts: readonly TableSort[]) => client.store.act((
+		transaction,
+	) => {
+		transaction.set(client.state.sorting, agentSorting(sorts));
+		transaction.set(client.state.page, FIRST_PAGE);
+	}, 'agents/sort');
+	const setPage = (pageIndex: number) => client.store.act(
+		(transaction) => transaction.set(
+			client.state.page,
+			moveToPage(page, pageIndex),
+		),
+		'agents/page',
+	);
+
+	useEffect(() => {
+		let current = true;
+		const timer = setTimeout(
+			() => void loadPage(() => current),
+			term === '' ? 0 : SEARCH_DEBOUNCE_MS,
+		);
+		return () => {
+			current = false;
+			clearTimeout(timer);
+		};
+	}, [term, sort.key, sort.desc, page.pageIndex]);
+
 	const openModuleAgent = (agentId: string) => {
 		setSelectedModuleAgentId(agentId);
 		if (props.canManage) setModuleEditorOpen(true);
@@ -142,7 +210,20 @@ export function AgentsView(props: AgentsViewProps) @{
 	};
 
 	useEffect(() => {
-		void refresh();
+		void loadAgentContext().then(
+			(result) => client.store.act((transaction) => {
+				transaction.set(client.state.moduleAgents, result.moduleAgents);
+				transaction.set(client.state.providers, result.providers);
+				transaction.set(client.state.tools, result.tools);
+				transaction.set(client.state.procedures, result.procedures);
+			}, 'agents/context-loaded'),
+		).catch(
+			(loadError: unknown) => setError(
+				loadError instanceof Error
+					? loadError.message
+					: t('agents.definitions.error.load'),
+			),
+		);
 	}, []);
 
 	const open = (agentId: string) => {
@@ -159,15 +240,10 @@ export function AgentsView(props: AgentsViewProps) @{
 					? await updateAgent(selected.id, input, props.csrfToken)
 					: await createAgent(input, props.csrfToken);
 			client.store.act((transaction) => {
-				transaction.set(
-					client.state.agents,
-					[...agents.filter((agent) => agent.id !== saved.id), saved].sort(
-						(left, right) => left.name.localeCompare(right.name),
-					),
-				);
 				transaction.set(client.state.selectedAgentId, saved.id);
 				transaction.set(client.state.editorOpen, false);
 			}, 'agents/saved');
+			await loadPage();
 		} catch (saveError) {
 			setError(
 				saveError instanceof Error
@@ -205,12 +281,9 @@ export function AgentsView(props: AgentsViewProps) @{
 					props.csrfToken,
 				);
 				client.store.act((transaction) => {
-					transaction.set(
-						client.state.agents,
-						agents.filter((agent) => agent.id !== lifecycleTarget.id),
-					);
 					transaction.set(client.state.selectedAgentId, '');
 				}, 'agents/deleted');
+				await loadPage();
 			}
 			setLifecycleAction('');
 		} catch (lifecycleError) {
@@ -262,14 +335,17 @@ export function AgentsView(props: AgentsViewProps) @{
 			onConfigure={openModuleAgent}
 		/>
 		<AgentDefinitionList
-			agents={visible}
+			agents={agents}
 			status={status === 'loading' ? 'loading' : 'idle'}
 			providers={providers}
 			filtered={term !== ''}
 			canManage={props.canManage}
 			query={query}
-			activeCount={active.length}
+			sorting={sorting}
+			page={page}
 			onQuery={setQuery}
+			onSortingChange={setSorting}
+			onPageChange={setPage}
 			onSelect={open}
 			onArchive={(id) => beginLifecycle(id, 'archive')}
 			onDelete={(id) => beginLifecycle(id, 'delete')}

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

@@ -7,6 +7,7 @@ import {
 } from '../domain/run-timeline.ts';
 import type {
 	AgentDefinition,
+	AgentListSort,
 	AgentProviderConnection,
 	AgentRun,
 	AgentRunTimeline,
@@ -17,6 +18,7 @@ import type {
 	CreateAgentInput,
 	CreateAgentProcedureInput,
 	EnqueueAgentRunInput,
+	ListDirection,
 	ModuleAgentView,
 	TenantAgentView,
 	UpdateAgentProviderInput,
@@ -44,18 +46,81 @@ function mutationHeaders(csrfToken: string): HeadersInit {
 	};
 }
 
-export async function loadAgents(): Promise<{
-	readonly agents: readonly TenantAgentView[];
+export interface PageResult<Item> {
+	readonly items: readonly Item[];
+	readonly page: { readonly nextCursor: string | null; readonly limit: number };
+}
+
+function query(params: object): string {
+	const search = new URLSearchParams();
+	for (const [key, value] of Object.entries(params) as [string, unknown][]) {
+		if (value === undefined || value === null || value === '') continue;
+		search.set(key, String(value));
+	}
+	const text = search.toString();
+	return text === '' ? '' : '?' + text;
+}
+
+async function getJson<T>(path: string): Promise<T> {
+	const response = await fetch(path, {
+		headers: { accept: 'application/json' },
+		credentials: 'same-origin',
+	});
+	return payload(response);
+}
+
+/* A reader that needs a whole set (a select box, a count) walks the cursors
+   to the end. The walk stops at this many rows and reports the set as
+   incomplete, so a workspace of unusual size costs a bounded number of pages. */
+export const WHOLE_LIST_CAP = 1_000;
+const WHOLE_LIST_PAGE = 200;
+
+export interface WholeList<Item> {
+	readonly items: readonly Item[];
+	/** False when the walk hit WHOLE_LIST_CAP before the list ended. */
+	readonly complete: boolean;
+}
+
+async function collectPages<Item>(
+	load: (cursor: string | null) => Promise<PageResult<Item>>,
+): Promise<WholeList<Item>> {
+	const items: Item[] = [];
+	let cursor: string | null = null;
+	do {
+		const result: PageResult<Item> = await load(cursor);
+		items.push(...result.items);
+		cursor = result.page.nextCursor;
+	} while (cursor !== null && items.length < WHOLE_LIST_CAP);
+	return { items, complete: cursor === null };
+}
+
+export interface AgentListRequest {
+	readonly limit?: number;
+	readonly cursor?: string | null;
+	readonly sort?: AgentListSort;
+	readonly direction?: ListDirection;
+	readonly q?: string;
+}
+
+export function loadAgentsPage(
+	request: AgentListRequest = {},
+): Promise<PageResult<TenantAgentView>> {
+	return getJson('/api/agents' + query(request));
+}
+
+export function loadAllAgents(): Promise<WholeList<TenantAgentView>> {
+	return collectPages((cursor) =>
+		loadAgentsPage({ limit: WHOLE_LIST_PAGE, sort: 'name', cursor }),
+	);
+}
+
+export function loadAgentContext(): Promise<{
 	readonly moduleAgents: readonly ModuleAgentView[];
 	readonly providers: readonly AgentProviderConnection[];
 	readonly tools: readonly string[];
 	readonly procedures: readonly AgentProcedure[];
 }> {
-	const response = await fetch('/api/agents', {
-		headers: { accept: 'application/json' },
-		credentials: 'same-origin',
-	});
-	return payload(response);
+	return getJson('/api/agents/context');
 }
 
 export async function updateModuleAgentBinding(
@@ -258,23 +323,36 @@ export async function deleteAgentProcedure(
 	await payload<{ readonly deleted: true }>(response);
 }
 
-export async function loadAgentRuns(): Promise<readonly AgentRun[]> {
-	const response = await fetch('/api/agent-runs', {
-		headers: { accept: 'application/json' },
-		credentials: 'same-origin',
-	});
-	return (await payload<{ readonly runs: readonly AgentRun[] }>(response)).runs;
+export interface RunListRequest {
+	readonly limit?: number;
+	readonly cursor?: string | null;
+	readonly direction?: ListDirection;
+	readonly status?: string;
+	readonly agentId?: string;
+	readonly trigger?: string;
+	readonly q?: string;
 }
 
-export async function loadAgentRun(runId: string): Promise<AgentRunTimeline> {
-	const response = await fetch(
-		`/api/agent-runs?id=${encodeURIComponent(runId)}`,
-		{
-			headers: { accept: 'application/json' },
-			credentials: 'same-origin',
-		},
+export function loadAgentRuns(
+	request: RunListRequest = {},
+): Promise<PageResult<AgentRun>> {
+	return getJson('/api/agent-runs' + query(request));
+}
+
+export function loadAllAgentRuns(
+	filters: Pick<RunListRequest, 'status' | 'agentId' | 'trigger'>,
+): Promise<WholeList<AgentRun>> {
+	return collectPages((cursor) =>
+		loadAgentRuns({ ...filters, limit: WHOLE_LIST_PAGE, cursor }),
 	);
-	return (await payload<{ readonly run: AgentRunTimeline }>(response)).run;
+}
+
+export async function loadAgentRun(runId: string): Promise<AgentRunTimeline> {
+	return (
+		await getJson<{ readonly run: AgentRunTimeline }>(
+			'/api/agent-runs/get' + query({ id: runId }),
+		)
+	).run;
 }
 
 export async function loadAgentWorker(): Promise<AgentWorkerStatus> {

package/modules/agents/src/client/state.ts

@@ -1,4 +1,5 @@
 import { cell, createStore } from 'segment-state';
+import type { TableSort } from '@flowdular/sdk/ui';
 import type {
 	AgentProviderConnection,
 	AgentDefinition,
@@ -7,9 +8,100 @@ import type {
 	AgentProcedure,
 	AgentUsageSummary,
 	AgentWorkerStatus,
+	ListDirection,
 	ModuleAgentView,
 } from '../domain/types.ts';
 
+export const PAGE_SIZE = 25;
+
+/**
+ * The cursor that opened each page the reader has seen. `cursors[0]` is null
+ * for the first page and `cursors[i]` is the cursor the server returned with
+ * page `i - 1`, so going back reuses a stored cursor and a page past the last
+ * known one cannot be opened. A filter or sort change throws the stack away.
+ */
+export interface CursorStack {
+	readonly pageIndex: number;
+	readonly cursors: readonly (string | null)[];
+}
+
+export const FIRST_PAGE: CursorStack = { pageIndex: 0, cursors: [null] };
+
+export function pageCursor(stack: CursorStack): string | null {
+	return stack.cursors[stack.pageIndex] ?? null;
+}
+
+export function hasMorePages(stack: CursorStack): boolean {
+	return typeof stack.cursors[stack.pageIndex + 1] === 'string';
+}
+
+/* Records what follows the page on screen and forgets the pages behind it: a
+   set that changed under the reader hands out fresh cursors from here on. */
+export function pageLoaded(
+	stack: CursorStack,
+	nextCursor: string | null,
+): CursorStack {
+	return {
+		pageIndex: stack.pageIndex,
+		cursors: [
+			...stack.cursors.slice(0, stack.pageIndex + 1),
+			...(nextCursor === null ? [] : [nextCursor]),
+		],
+	};
+}
+
+export function moveToPage(stack: CursorStack, pageIndex: number): CursorStack {
+	const index = Math.min(
+		Math.max(0, Math.trunc(pageIndex)),
+		stack.cursors.length - 1,
+	);
+	return index === stack.pageIndex ? stack : { ...stack, pageIndex: index };
+}
+
+export const DEFAULT_AGENT_SORT: readonly TableSort[] = [
+	{ key: 'name', desc: false },
+];
+
+/* The table reports an empty state when a header toggles past descending; the
+   list then falls back to its default order rather than an unsorted page. */
+export function agentSorting(
+	sorts: readonly TableSort[],
+): readonly TableSort[] {
+	const sort = sorts.find(
+		(candidate) => candidate.key === 'name' || candidate.key === 'updatedAt',
+	);
+	return sort ? [sort] : DEFAULT_AGENT_SORT;
+}
+
+export function runDirection(sorts: readonly TableSort[]): ListDirection {
+	const sort = sorts.find((candidate) => candidate.key === 'queuedAt');
+	return sort && !sort.desc ? 'asc' : 'desc';
+}
+
+export interface AgentOption {
+	readonly id: string;
+	readonly name: string;
+}
+
+/* The agent filter offers every agent seen in a loaded page, so an option
+   never disappears when the reader pages away from the runs that named it. */
+export function mergeAgentOptions(
+	options: readonly AgentOption[],
+	runs: readonly AgentRun[],
+): readonly AgentOption[] {
+	const known = new Map(options.map((option) => [option.id, option]));
+	let changed = false;
+	for (const run of runs) {
+		if (known.has(run.agentId)) continue;
+		known.set(run.agentId, { id: run.agentId, name: run.agentName });
+		changed = true;
+	}
+	if (!changed) return options;
+	return [...known.values()].sort((left, right) =>
+		left.name.localeCompare(right.name),
+	);
+}
+
 export function createAgentClientState() {
 	const store = createStore({
 		agents: cell<readonly AgentDefinition[]>([]),
@@ -18,6 +110,8 @@ export function createAgentClientState() {
 		providers: cell<readonly AgentProviderConnection[]>([]),
 		tools: cell<readonly string[]>([]),
 		procedures: cell<readonly AgentProcedure[]>([]),
+		page: cell<CursorStack>(FIRST_PAGE),
+		sorting: cell<readonly TableSort[]>(DEFAULT_AGENT_SORT),
 		selectedAgentId: '',
 		selectedModuleAgentId: '',
 		selectedRun: cell<AgentRunTimeline | null>(null),
@@ -39,6 +133,9 @@ export function createAgentClientState() {
 export function createAgentRunClientState() {
 	const store = createStore({
 		runs: cell<readonly AgentRun[]>([]),
+		page: cell<CursorStack>(FIRST_PAGE),
+		direction: cell<ListDirection>('desc'),
+		agentOptions: cell<readonly AgentOption[]>([]),
 		selectedRun: cell<AgentRunTimeline | null>(null),
 		status: cell<'idle' | 'loading' | 'submitting'>('idle'),
 		error: '',

package/modules/agents/src/domain/types.ts

@@ -466,10 +466,50 @@ export interface AgentAuditEvent {
 	readonly eventHash: string;
 }
 
-export interface AgentAuditPage {
-	readonly events: readonly AgentAuditEvent[];
-	/** `${occurredAt}:${sequence}` of the last event, or null when exhausted. */
-	readonly nextCursor: string | null;
+export type ListDirection = 'asc' | 'desc';
+
+export type AgentListSort = 'name' | 'updatedAt';
+
+/* One page of tenant definitions. `after` is the keyset of the last row of the
+   previous page: the collation key SQL computed for a name sort, so a cursor
+   never carries a JavaScript lowercase that PostgreSQL would order elsewhere. */
+export interface AgentListQuery {
+	readonly sort: AgentListSort;
+	readonly direction: ListDirection;
+	readonly search: string | null;
+	readonly limit: number;
+	readonly after: {
+		readonly sortValue: string | number;
+		readonly id: string;
+	} | null;
+}
+
+export interface AgentListPage {
+	readonly agents: readonly AgentDefinition[];
+	/** The keyset of the last row, from which the caller signs the next cursor. */
+	readonly last: {
+		readonly nameKey: string;
+		readonly updatedAt: number;
+		readonly id: string;
+	} | null;
+}
+
+export interface AgentRunListQuery {
+	readonly direction: ListDirection;
+	readonly status: AgentRunStatus | null;
+	readonly agentId: string | null;
+	readonly trigger: AgentRunTrigger | null;
+	readonly search: string | null;
+	readonly limit: number;
+	readonly after: { readonly queuedAt: number; readonly id: string } | null;
+}
+
+export interface AgentAuditListQuery {
+	readonly limit: number;
+	readonly after: {
+		readonly occurredAt: number;
+		readonly sequence: number;
+	} | null;
 }
 
 /* Reports whether the tenant hash chain reproduces, and the id of the first

package/modules/agents/src/platform.ts

@@ -4,6 +4,10 @@ import type {
 } from '@flowdular/sdk/modules/auth/server';
 import type { ModuleSettingsDeclaration } from '@flowdular/sdk/kernel';
 import type { AgentTool } from '@flowdular/sdk/harness';
+import {
+	REPORTS_PROVIDERS_CAPABILITY,
+	type ReportProviderRegistry,
+} from '@flowdular/sdk/modules/reports';
 import type { ModuleAgentDefinition } from './domain/types.ts';
 import {
 	AGENT_ACTION_EXECUTION_CAPABILITY,
@@ -14,6 +18,17 @@ import {
 	createAgentRoutes,
 	createAgentRuntime,
 } from './server/index.ts';
+import { agentsDataClasses } from './services/data-classes.ts';
+import { createAgentRunsReportProvider } from './services/reports.ts';
+import {
+	AGENT_METER_DECLARATIONS,
+	METERING_METERS_CAPABILITY,
+	type MeterRegistry,
+} from './services/metering.ts';
+import {
+	NOTIFICATIONS_PUBLISH_CAPABILITY,
+	type NotificationPublisher,
+} from './services/notifications.ts';
 import {
 	agentSettings,
 	agentsModuleSettingsFromEnvironment,
@@ -46,6 +61,13 @@ export type AgentServerComposition = PlatformServerComposition & {
 export function createServerComposition(
 	context: PlatformServerContext,
 ): AgentServerComposition {
+	/* agents.core requires metering.meters.v1, so the module registry composes
+	   metering.core first and the registry is here to declare into. Declaring
+	   happens once, while this module composes; every later use resolves the
+	   registry again through the capability rather than holding this one. */
+	const meters = () =>
+		context.capabilities.get<MeterRegistry>(METERING_METERS_CAPABILITY);
+	meters()?.declare('agents.core', AGENT_METER_DECLARATIONS);
 	const runtime = createAgentRuntime({
 		...agentRuntimeOptionsFromEnvironment(
 			context.environment,
@@ -58,7 +80,27 @@ export function createServerComposition(
 		authorizeToolAccess: ({ tenantId, actor }) =>
 			context.auth.authorizeAgentToolAccess(tenantId, actor),
 		settings: agentSettings(context),
+		/* notifications.core is optional and is not declared as a dependency.
+		   The lookup happens when a run settles, so a module composed after
+		   this one is found and an absent one is a no-op. */
+		notifications: () =>
+			context.capabilities.get<NotificationPublisher>(
+				NOTIFICATIONS_PUBLISH_CAPABILITY,
+			),
+		meters,
 	});
+	/* The sweep, the export and the erasure run here, on this module's own
+	   leases and under its own tenant transaction; the platform only holds the
+	   declaration. */
+	context.dataClasses.declare(agentsDataClasses(() => runtime.repository()));
+	/* reports.core is a declared dependency, so it has composed and its registry
+	   is still open. The capability stays optional all the same: a deployment
+	   that leaves reports out still composes this module. */
+	context.capabilities
+		.get<ReportProviderRegistry>(REPORTS_PROVIDERS_CAPABILITY)
+		?.register('agents.core', [
+			createAgentRunsReportProvider(() => runtime.repository()),
+		]);
 	context.capabilities.register(
 		AGENT_RUN_QUEUE_CAPABILITY,
 		createAgentRunQueue(() => runtime.service()),