@flowdular/sdk 0.1.0

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

@@ -0,0 +1,127 @@
+import { t } from '@flowdular/sdk/client';
+import { SearchField, TableCard, Tag, type TableColumn } from '@flowdular/sdk/ui';
+import type {
+	AgentDefinition,
+	AgentProviderConnection,
+} from '../domain/types.ts';
+import { stateTone } from './presentation.ts';
+
+export interface AgentDefinitionListProps {
+	readonly agents: readonly AgentDefinition[];
+	readonly status: 'idle' | 'loading';
+	readonly providers: readonly AgentProviderConnection[];
+	readonly filtered: boolean;
+	readonly canManage: boolean;
+	readonly query: string;
+	readonly activeCount: number;
+	readonly onQuery: (value: string) => void;
+	readonly onSelect: (agentId: string) => void;
+	readonly onArchive: (agentId: string) => void;
+	readonly onDelete: (agentId: string) => void;
+}
+
+function columns(
+	providers: readonly AgentProviderConnection[],
+): readonly TableColumn<AgentDefinition>[] {
+	const providerName = (id: string) =>
+		providers.find((provider) => provider.id === id)?.name ??
+			t('agents.definitions.unknownProvider');
+	return [
+		{
+			key: 'agent',
+			header: t('agents.definitions.column.agent'),
+			width: '23%',
+			cell: (agent) => <span class="ui-cell">
+				<b>{agent.name}</b>
+				<small class="ui-mono">{agent.key + ' · r' + agent.revision}</small>
+			</span>,
+		},
+		{
+			key: 'purpose',
+			header: t('agents.definitions.column.purpose'),
+			width: '30%',
+			cell: (agent) => <span class="ui-cell__muted">{agent.description}</span>,
+		},
+		{
+			key: 'model',
+			header: t('agents.definitions.column.model'),
+			width: '21%',
+			cell: (agent) => <span class="ui-cell">
+				<b class="ui-mono">{agent.model}</b>
+				<small>{providerName(agent.provider)}</small>
+			</span>,
+		},
+		{
+			key: 'status',
+			header: t('agents.definitions.column.status'),
+			width: '16%',
+			cell: (agent) =>
+				<Tag tone={stateTone(agent.status)} dot>{t(
+					'agents.status.' + agent.status,
+				)}</Tag>,
+		},
+	];
+}
+
+export function AgentDefinitionList(props: AgentDefinitionListProps) @{
+	<TableCard
+		title={t('agents.definitions.table.title')}
+		count={t('agents.definitions.table.count', {
+			active: props.activeCount,
+			total: props.agents.length,
+		})}
+		search={<SearchField
+			value={props.query}
+			placeholder={t('agents.definitions.search.placeholder')}
+			label={t('agents.definitions.search.label')}
+			onInput={props.onQuery}
+		/>}
+		columns={columns(props.providers)}
+		rows={props.agents}
+		status={props.status}
+		loadingLabel={t('agents.definitions.loading')}
+		rowKey={(agent) => agent.id}
+		filtered={props.filtered}
+		empty={{
+			icon: 'bot',
+			title: t('agents.definitions.empty.title'),
+			hint: t('agents.definitions.empty.hint'),
+		}}
+		emptyFiltered={{
+			icon: 'search',
+			title: t('agents.definitions.empty.filteredTitle'),
+			hint: t('agents.definitions.empty.filteredHint'),
+		}}
+		actionsLabel={t('agents.common.actions')}
+		actionsWidth="280px"
+		actions={props.canManage
+			? (agent) => [
+					{
+						id: 'open',
+						label: t('agents.common.edit'),
+						onSelect: () => props.onSelect(agent.id),
+					},
+					...(agent.status === 'archived'
+						? [
+								{
+									id: 'delete',
+									label: t('agents.common.delete'),
+									tone: 'danger' as const,
+									onSelect: () => props.onDelete(agent.id),
+								},
+							]
+						: [
+								{
+									id: 'archive',
+									label: t('agents.common.archive'),
+									onSelect: () => props.onArchive(agent.id),
+								},
+							]),
+				]
+			: undefined}
+		onSelect={props.canManage ? (agent) => props.onSelect(agent.id) : undefined}
+		caption={t('agents.definitions.table.caption')}
+		note={t('agents.definitions.note')}
+		noteIcon="shield"
+	/>
+}

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

@@ -0,0 +1,246 @@
+import { useEffect, useMemo } from 'octane';
+import { t } from '@flowdular/sdk/client';
+import {
+	Alert,
+	Button,
+	EmptyState,
+	FormField,
+	PageHeader,
+} from '@flowdular/sdk/ui';
+import { useValue } from 'segment-state';
+import type { AgentRunDetail } from '../domain/types.ts';
+import {
+	cancelAgentRun,
+	enqueueAgentRun,
+	loadAgents,
+	loadAgentWorker,
+	observeAgentRun,
+} from './api.ts';
+import { RunTimeline } from './RunTimeline.tsrx';
+import { createAgentClientState } from './state.ts';
+
+export interface AgentPlaygroundViewProps {
+	readonly csrfToken: string;
+}
+
+function terminal(status: AgentRunDetail['status']): boolean {
+	return ['succeeded', 'failed', 'cancelled'].includes(status);
+}
+
+export function AgentPlaygroundView(props: AgentPlaygroundViewProps) @{
+	const client = useMemo(() => createAgentClientState(), []);
+	const [agents] = useValue(client.state.agents);
+	const [selectedAgentId, setSelectedAgentId] = useValue(
+		client.state.selectedAgentId,
+	);
+	const [selectedRun, setSelectedRun] = useValue(client.state.selectedRun);
+	const [input, setInput] = useValue(client.state.playgroundInput);
+	const [submissionKey, setSubmissionKey] = useValue(
+		client.state.playgroundKey,
+	);
+	const [worker, setWorker] = useValue(client.state.worker);
+	const [status, setStatus] = useValue(client.state.status);
+	const [error, setError] = useValue(client.state.error);
+	const activeAgents = agents.filter((agent) => agent.status === 'active');
+
+	const refreshWorker = () => loadAgentWorker().then(setWorker).catch(
+		() => setWorker(null),
+	);
+
+	useEffect(() => {
+		setStatus('loading');
+		void loadAgents().then((result) => {
+			client.store.act((transaction) => {
+				transaction.set(client.state.agents, result.agents);
+				if (!selectedAgentId) {
+					transaction.set(
+						client.state.selectedAgentId,
+						result.agents.find((agent) => agent.status === 'active')?.id ?? '',
+					);
+				}
+			}, 'agents/playground-loaded');
+		}).catch(
+			(loadError) => setError(
+				loadError instanceof Error
+					? loadError.message
+					: t('agents.definitions.error.load'),
+			),
+		).finally(() => setStatus('idle'));
+		void refreshWorker();
+		const timer = setInterval(() => void refreshWorker(), 15_000);
+		return () => clearInterval(timer);
+	}, []);
+
+	useEffect(() => {
+		if (!selectedRun || terminal(selectedRun.status)) return;
+		return observeAgentRun(
+			selectedRun.id,
+			setSelectedRun,
+			selectedRun.timeline,
+		);
+	}, [selectedRun?.id, selectedRun?.status]);
+
+	const submit = async (event: SubmitEvent) => {
+		event.preventDefault();
+		setStatus('submitting');
+		setError('');
+		/* One key per submission. A failed request keeps it so the retry maps
+   to the same run; editing the input starts a new submission. */
+		const key = submissionKey || crypto.randomUUID();
+		setSubmissionKey(key);
+		try {
+			const queued = await enqueueAgentRun(
+				{
+					agentId: selectedAgentId,
+					input,
+					toolGrants: agents.find(
+						(agent) => agent.id === selectedAgentId,
+					)?.allowedTools ??
+						[],
+				},
+				props.csrfToken,
+				key,
+			);
+			setSubmissionKey('');
+			setSelectedRun({ ...queued, timeline: [] });
+			void refreshWorker();
+		} catch (runError) {
+			setError(
+				runError instanceof Error
+					? runError.message
+					: t('agents.playground.error.queue'),
+			);
+		} finally {
+			setStatus('idle');
+		}
+	};
+
+	const cancel = async () => {
+		if (!selectedRun) return;
+		setStatus('submitting');
+		setError('');
+		try {
+			setSelectedRun(await cancelAgentRun(selectedRun.id, props.csrfToken));
+		} catch (cancelError) {
+			setError(
+				cancelError instanceof Error
+					? cancelError.message
+					: t('agents.runs.error.cancel'),
+			);
+		} finally {
+			setStatus('idle');
+		}
+	};
+
+	<div class="ui-view">
+		<PageHeader
+			eyebrow={t('agents.playground.eyebrow')}
+			title={t('agents.playground.title')}
+			description={t('agents.playground.description')}
+		/>
+		<div class="ui-two-col ui-two-col--wide-aside">
+			<section class="ui-card">
+				<div class="ui-card__head">
+					<span class="ui-card__title">
+						{t('agents.playground.form.title')}
+						<small>{t('agents.playground.form.subtitle')}</small>
+					</span>
+					<span
+						class={[
+							'playground-live',
+							worker?.online !== true && 'playground-live--offline',
+						]}
+						title={worker
+							? t('agents.playground.worker.slots', {
+									inFlight: worker.inFlight,
+									concurrency: worker.concurrency,
+								})
+							: t('agents.playground.worker.unavailable')}
+					>
+						<i
+							class={['ui-dot', worker?.online !== true && 'ui-dot--muted']}
+							aria-hidden="true"
+						></i>
+						{worker === null
+							? t('agents.playground.worker.unknown')
+							: worker.online
+								? t('agents.playground.worker.online', {
+										inFlight: worker.inFlight,
+									})
+								: t('agents.playground.worker.offline')}
+					</span>
+				</div>
+				<form class="ui-form" onSubmit={submit}>
+					<FormField label={t('agents.playground.form.agent')}>
+						<select
+							class="ui-select"
+							value={selectedAgentId}
+							onInput={(event) => {
+								setSelectedAgentId(event.currentTarget.value);
+								setSubmissionKey('');
+							}}
+							disabled={activeAgents.length === 0}
+						>
+							@if (activeAgents.length === 0) {
+								<option value="">{t(
+									'agents.playground.form.activateFirst',
+								)}</option>
+							}
+							@for (const agent of activeAgents; key agent.id) {
+								<option value={agent.id}>
+									{agent.name + ' · r' + agent.revision}
+								</option>
+							}
+						</select>
+					</FormField>
+					<FormField label={t('agents.playground.form.input')} required>
+						<textarea
+							class="ui-textarea"
+							rows={10}
+							value={input}
+							onInput={(event) => {
+								setInput(event.currentTarget.value);
+								setSubmissionKey('');
+							}}
+							placeholder={t('agents.playground.form.inputPlaceholder')}
+							maxlength={100_000}
+							required
+						></textarea>
+					</FormField>
+					@if (error) {
+						<Alert>{error}</Alert>
+					}
+					<div class="ui-form__foot">
+						<small>{t('agents.playground.form.note')}</small>
+						<div class="ui-form__actions">
+							<Button
+								variant="primary"
+								type="submit"
+								disabled={status === 'submitting' || !selectedAgentId ||
+									!input.trim()}
+							>
+								{status === 'submitting'
+									? t('agents.playground.form.queuing')
+									: t('agents.playground.form.queue')}
+							</Button>
+						</div>
+					</div>
+				</form>
+			</section>
+			@if (selectedRun) {
+				<RunTimeline
+					run={selectedRun}
+					onCancel={() => void cancel()}
+					cancelling={status === 'submitting'}
+				/>
+			} @else {
+				<aside class="ui-card">
+					<EmptyState
+						icon="flask"
+						title={t('agents.playground.empty.title')}
+					>{t('agents.playground.empty.hint')}</EmptyState>
+				</aside>
+			}
+		</div>
+	</div>
+}

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

@@ -0,0 +1,182 @@
+import { useMemo } from 'octane';
+import { t } from '@flowdular/sdk/client';
+import { Button, CheckGrid, FormField } from '@flowdular/sdk/ui';
+import type { CheckGroup, CheckOption } from '@flowdular/sdk/ui';
+import { cell, createStore, useValue } from 'segment-state';
+import type {
+	AgentProcedure,
+	CreateAgentProcedureInput,
+	UpdateAgentProcedureInput,
+} from '../domain/types.ts';
+
+export interface AgentProcedureFormProps {
+	readonly procedure: AgentProcedure | null;
+	readonly tools: readonly string[];
+	readonly busy: boolean;
+	readonly onCancel: () => void;
+	readonly onSubmit: (input: | CreateAgentProcedureInput
+	| UpdateAgentProcedureInput) => Promise<void>;
+}
+
+function toolGroups(tools: readonly string[]): readonly CheckGroup[] {
+	const groups = new Map<string, CheckOption[]>();
+	for (const tool of tools) {
+		const namespace = tool.split('.')[0] ?? tool;
+		const options = groups.get(namespace) ?? [];
+		options.push({
+			value: tool,
+			label: tool.slice(namespace.length + 1) || tool,
+		});
+		groups.set(namespace, options);
+	}
+	return [...groups].map(([label, options]) => ({ label, options }));
+}
+
+function stringValue(form: FormData, key: string): string {
+	const value = form.get(key);
+	return typeof value === 'string' ? value : '';
+}
+
+export function AgentProcedureForm(props: AgentProcedureFormProps) @{
+	const formState = useMemo(
+		() => createStore({
+			requiredTools: cell<readonly string[]>(
+				props.procedure?.requiredTools ?? [],
+			),
+		}),
+		[],
+	);
+	const [requiredTools, setRequiredTools] = useValue(
+		formState.state.requiredTools,
+	);
+
+	const submit = async (event: SubmitEvent) => {
+		event.preventDefault();
+		const form = new FormData(event.currentTarget as HTMLFormElement);
+		const base: CreateAgentProcedureInput = {
+			key: stringValue(form, 'key'),
+			name: stringValue(form, 'name'),
+			description: stringValue(form, 'description'),
+			instructions: stringValue(form, 'instructions'),
+			requiredTools,
+			status: stringValue(
+				form,
+				'status',
+			) as CreateAgentProcedureInput['status'],
+		};
+		await props.onSubmit(
+			props.procedure
+				? { ...base, expectedRevision: props.procedure.revision }
+				: base,
+		);
+	};
+
+	<form class="ui-drawer__form" onSubmit={submit}>
+		<div class="ui-drawer__body">
+			<div class="ui-form">
+				<div class="ui-form__row">
+					<FormField label={t('agents.procedures.form.name')} required>
+						<input
+							class="ui-input"
+							name="name"
+							defaultValue={props.procedure?.name ?? ''}
+							minlength={2}
+							maxlength={120}
+							autoFocus
+							required
+						/>
+					</FormField>
+					<FormField
+						label={t('agents.procedures.form.key')}
+						help={props.procedure
+							? t('agents.procedures.form.keyFixed')
+							: undefined}
+						required
+					>
+						<input
+							class="ui-input ui-mono"
+							name="key"
+							defaultValue={props.procedure?.key ?? ''}
+							readonly={Boolean(props.procedure)}
+							placeholder="invoice-triage"
+							minlength={3}
+							maxlength={64}
+							required
+						/>
+					</FormField>
+				</div>
+				<FormField label={t('agents.procedures.form.description')} required>
+					<input
+						class="ui-input"
+						name="description"
+						defaultValue={props.procedure?.description ?? ''}
+						placeholder={t('agents.procedures.form.descriptionPlaceholder')}
+						maxlength={500}
+						required
+					/>
+				</FormField>
+				<FormField
+					label={t('agents.procedures.form.instructions')}
+					help={t('agents.procedures.form.instructionsHelp')}
+					required
+				>
+					<textarea
+						class="ui-textarea"
+						name="instructions"
+						defaultValue={props.procedure?.instructions ?? ''}
+						placeholder={t('agents.procedures.form.instructionsPlaceholder')}
+						minlength={8}
+						maxlength={8_000}
+						required
+					></textarea>
+				</FormField>
+				<FormField label={t('agents.procedures.form.status')}>
+					<select
+						class="ui-select"
+						name="status"
+						defaultValue={props.procedure?.status ?? 'draft'}
+					>
+						<option value="draft">{t('agents.status.draft')}</option>
+						<option value="active">{t('agents.status.active')}</option>
+						<option value="archived">{t('agents.status.archived')}</option>
+					</select>
+				</FormField>
+				<div class="ui-field">
+					<span class="ui-label">{t('agents.procedures.form.tools')}</span>
+					@if (props.tools.length === 0) {
+						<p class="agent-empty-note">{t(
+							'agents.procedures.form.toolsEmpty',
+						)}</p>
+					} @else {
+						<CheckGrid
+							groups={toolGroups(props.tools)}
+							value={requiredTools}
+							mono
+							onChange={setRequiredTools}
+						/>
+					}
+					<span class="ui-help">{t('agents.procedures.form.toolsHelp')}</span>
+				</div>
+			</div>
+		</div>
+		<div class="ui-drawer__foot">
+			<small>
+				{props.procedure
+					? t('agents.procedures.form.revisionNote', {
+							revision: props.procedure.revision + 1,
+						})
+					: t('agents.procedures.form.createNote')}
+			</small>
+			<div class="ui-form__actions">
+				<Button onClick={props.onCancel}>{t('agents.common.cancel')}</Button>
+				<Button variant="primary" type="submit" disabled={props.busy}>
+					{props.busy
+						? t('agents.common.saving')
+						: props.procedure
+							? t('agents.procedures.form.save')
+							: t('agents.procedures.form.create')}
+				</Button>
+			</div>
+		</div>
+	</form>
+}

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

@@ -0,0 +1,118 @@
+import { t } from '@flowdular/sdk/client';
+import { SearchField, TableCard, Tag, type TableColumn } from '@flowdular/sdk/ui';
+import type { AgentProcedure } from '../domain/types.ts';
+import { countLabel, stateTone } from './presentation.ts';
+
+export interface AgentProcedureListProps {
+	readonly procedures: readonly AgentProcedure[];
+	readonly filtered: boolean;
+	readonly canManage: boolean;
+	readonly query: string;
+	readonly activeCount: number;
+	readonly onQuery: (value: string) => void;
+	readonly onSelect: (procedureId: string) => void;
+	readonly onArchive: (procedureId: string) => void;
+	readonly onDelete: (procedureId: string) => void;
+}
+
+function columns(): readonly TableColumn<AgentProcedure>[] {
+	return [
+		{
+			key: 'procedure',
+			header: t('agents.procedures.column.procedure'),
+			width: '26%',
+			cell: (procedure) => <span class="ui-cell">
+				<b>{procedure.name}</b>
+				<small class="ui-mono">
+					{procedure.key + ' · r' + procedure.revision}
+				</small>
+			</span>,
+		},
+		{
+			key: 'purpose',
+			header: t('agents.procedures.column.purpose'),
+			width: '35%',
+			cell: (procedure) =>
+				<span class="ui-cell__muted">{procedure.description}</span>,
+		},
+		{
+			key: 'tools',
+			header: t('agents.procedures.column.tools'),
+			width: '12%',
+			numeric: true,
+			cell: (procedure) => countLabel(procedure.requiredTools.length),
+		},
+		{
+			key: 'status',
+			header: t('agents.procedures.column.status'),
+			width: '17%',
+			cell: (procedure) =>
+				<Tag tone={stateTone(procedure.status)} dot>{t(
+					'agents.status.' + procedure.status,
+				)}</Tag>,
+		},
+	];
+}
+
+export function AgentProcedureList(props: AgentProcedureListProps) @{
+	<TableCard
+		title={t('agents.procedures.table.title')}
+		count={t('agents.procedures.table.count', {
+			active: props.activeCount,
+			total: props.procedures.length,
+		})}
+		search={<SearchField
+			value={props.query}
+			placeholder={t('agents.procedures.search.placeholder')}
+			label={t('agents.procedures.search.label')}
+			onInput={props.onQuery}
+		/>}
+		columns={columns()}
+		rows={props.procedures}
+		rowKey={(procedure) => procedure.id}
+		filtered={props.filtered}
+		empty={{
+			icon: 'file-text',
+			title: t('agents.procedures.empty.title'),
+			hint: t('agents.procedures.empty.hint'),
+		}}
+		emptyFiltered={{
+			icon: 'search',
+			title: t('agents.procedures.empty.filteredTitle'),
+			hint: t('agents.procedures.empty.filteredHint'),
+		}}
+		actionsLabel={t('agents.common.actions')}
+		actionsWidth="280px"
+		actions={props.canManage
+			? (procedure) => [
+					{
+						id: 'open',
+						label: t('agents.common.edit'),
+						onSelect: () => props.onSelect(procedure.id),
+					},
+					...(procedure.status === 'archived'
+						? [
+								{
+									id: 'delete',
+									label: t('agents.common.delete'),
+									tone: 'danger' as const,
+									onSelect: () => props.onDelete(procedure.id),
+								},
+							]
+						: [
+								{
+									id: 'archive',
+									label: t('agents.common.archive'),
+									onSelect: () => props.onArchive(procedure.id),
+								},
+							]),
+				]
+			: undefined}
+		onSelect={props.canManage
+			? (procedure) => props.onSelect(procedure.id)
+			: undefined}
+		caption={t('agents.procedures.table.caption')}
+		note={t('agents.procedures.note')}
+		noteIcon="shield"
+	/>
+}