@flowdular/sdk 0.2.3 → 0.3.0

package/packages/database/src/decoders.ts

@@ -0,0 +1,25 @@
+/**
+ * Reads an integer column as the adapters hand it back: the embedded build
+ * returns a number, the server driver returns int8 as text and a driver
+ * configured for it returns a bigint. A fraction, an unsafe integer or a value
+ * below `min` is a defect in the read, so it throws naming the field.
+ */
+export function integer(
+	value: unknown,
+	field: string,
+	options?: { readonly min?: number },
+): number {
+	const normalized =
+		typeof value === 'number' ||
+		typeof value === 'bigint' ||
+		typeof value === 'string'
+			? Number(value)
+			: Number.NaN;
+	if (
+		!Number.isSafeInteger(normalized) ||
+		(options?.min !== undefined && normalized < options.min)
+	) {
+		throw new Error(`The database returned an invalid ${field}.`);
+	}
+	return normalized;
+}

package/packages/database/src/index.ts

@@ -67,7 +67,24 @@ export type {
 	DatabaseProviderFactories,
 	DatabaseReadiness,
 } from './provider.ts';
+export {
+	backupKeyFingerprint,
+	backupKeyFingerprints,
+	compareBackupKeys,
+	createBackupManifest,
+	parseBackupManifest,
+	BACKUP_KEY_VARIABLES,
+	BACKUP_MANIFEST_FILE,
+	BACKUP_MANIFEST_VERSION,
+} from './backup.ts';
+export type {
+	BackupKeyComparison,
+	BackupKeyFingerprint,
+	BackupKeyStatus,
+	BackupManifest,
+} from './backup.ts';
 export { appendRecordHistory, queryRecordHistory } from './record-history.ts';
+export { integer } from './decoders.ts';
 export { databaseResetPlan, resetDatabase } from './reset.ts';
 export type {
 	DatabaseResetAuthorization,

package/packages/database/src/record-history.ts

@@ -14,6 +14,7 @@ import {
 	type DatabaseParameter,
 	type DatabaseSession,
 } from './contracts.ts';
+import { integer } from './decoders.ts';
 
 interface HistoryRow {
 	readonly id: string;
@@ -29,17 +30,6 @@ interface HistoryRow {
 	readonly occurred_at: number | bigint | string;
 }
 
-/* The server driver returns BIGINT as a string while the embedded build returns
-   a number, so every integer read crosses the same normalizer instead of
-   trusting whichever one a deployment happens to open. */
-function integer(value: number | bigint | string, field: string): number {
-	const normalized = Number(value);
-	if (!Number.isSafeInteger(normalized) || normalized < 0) {
-		throw new Error(`The history table returned an invalid ${field}.`);
-	}
-	return normalized;
-}
-
 function actorFromRow(row: HistoryRow): Actor {
 	if (row.actor_kind === 'user') {
 		return { kind: 'user', id: row.actor_id, label: row.actor_label };
@@ -115,7 +105,8 @@ export async function appendRecordHistory(
 		parameters: [write.tenantId, write.recordId],
 	});
 	const current = previous.rows[0]?.version ?? null;
-	const version = (current === null ? 0 : integer(current, 'version')) + 1;
+	const version =
+		(current === null ? 0 : integer(current, 'version', { min: 0 })) + 1;
 	const values: DatabaseParameter[] = [
 		randomUUID(),
 		write.tenantId,
@@ -185,11 +176,11 @@ export async function queryRecordHistory(
 		(row): HistoryEntry => ({
 			id: row.id,
 			recordId: row.record_id,
-			version: integer(row.version, 'version'),
+			version: integer(row.version, 'version', { min: 0 }),
 			action: row.action,
 			actor: actorFromRow(row),
 			changes: JSON.parse(row.changes_json) as RecordChanges,
-			occurredAt: integer(row.occurred_at, 'timestamp'),
+			occurredAt: integer(row.occurred_at, 'timestamp', { min: 0 }),
 		}),
 	);
 	const last = page[page.length - 1];

package/packages/dev-console/package.json

@@ -3,7 +3,8 @@
 	"version": "0.1.0",
 	"type": "module",
 	"exports": {
-		".": "./src/index.mjs"
+		".": "./src/index.mjs",
+		"./brand": "./src/brand.mjs"
 	},
 	"scripts": {
 		"test": "vitest run --passWithNoTests"

package/packages/dev-console/src/brand.d.mts

@@ -0,0 +1,8 @@
+export interface BrandHeaderOptions {
+	readonly title?: string;
+	readonly subtitle?: string;
+	readonly color?: boolean;
+	readonly columns?: number;
+	readonly terminal?: boolean;
+}
+export function renderBrandHeader(options?: BrandHeaderOptions): string;

package/packages/dev-console/src/brand.mjs

@@ -0,0 +1,33 @@
+// ASCII rendering of Flowdular's existing crossed-thread mark.
+const MARK = [
+	'    XXX     XXX',
+	'    XXX     XXX',
+	' XXXXXXXXXXXXXXXXX',
+	'XXXXXXXXXXXXXXXXXXX',
+	'    XXX     XXX',
+	'XXXXXXXXXXXXXXXXXXX',
+	' XXXXXXXXXXXXXXXXX',
+	'    XXX     XXX',
+	'    XXX     XXX',
+];
+
+/** Shared terminal branding without loading Vite or browser UI dependencies. */
+export function renderBrandHeader({
+	title = 'FLOWDULAR',
+	subtitle = '',
+	color = false,
+	columns = process.stdout.columns ?? 80,
+	terminal = Boolean(process.stdout.isTTY),
+} = {}) {
+	const brand = (text) => (color ? `\u001b[1;38;5;42m${text}\u001b[0m` : text);
+	const muted = (text) => (color ? `\u001b[90m${text}\u001b[0m` : text);
+	if (!terminal) {
+		return `  ${brand(title)}${subtitle ? `  ${muted(subtitle)}` : ''}`;
+	}
+	const heading = [
+		`  ${brand(title)}`,
+		...(subtitle ? [`  ${muted(subtitle)}`] : []),
+	];
+	if (columns < 21) return heading.join('\n');
+	return [...MARK.map((row) => `  ${brand(row)}`), '', ...heading].join('\n');
+}

package/packages/dev-console/src/index.mjs

@@ -1,4 +1,5 @@
 import { createLogger } from 'vite';
+import { renderBrandHeader } from './brand.mjs';
 
 /* Developer-facing startup output, shared by every Flowdular launcher. One
    presentation for the platform and the sandbox: the same brand block, the same
@@ -80,7 +81,7 @@ export function statusLine(theme, label, value, tone = 'text') {
    `[label, value, tone]` triples, so each application names its own facts. */
 export function printReady({ title, subtitle, lines, theme }) {
 	console.log('');
-	console.log(`  ${theme.brand(title)}  ${theme.muted(subtitle)}`);
+	console.log(renderBrandHeader({ title, subtitle, color: theme.enabled }));
 	for (const [label, value, tone = 'text'] of lines) {
 		if (value === null || value === undefined) continue;
 		console.log(statusLine(theme, label, value, tone));

package/packages/harness/src/index.ts

@@ -32,6 +32,8 @@ export type {
 	AgentTool,
 	AgentToolAccessAuthorizer,
 	AgentToolAuthorizationRequest,
+	AgentToolConsent,
+	AgentToolConsentDecision,
 	AgentToolContext,
 	AgentUsage,
 	JsonValue,

package/packages/harness/src/runtime.ts

@@ -106,6 +106,12 @@ export interface AgentToolContext {
 	   refuse when the trusted identity is absent. */
 	readonly agentId?: string;
 	readonly agentName?: string;
+	/* How the tool was reached: a model turn inside an agent run, or a workflow
+	   node running it as a published action. A tool whose admission differs per
+	   caller kind reads this instead of assuming one. Optional keeps v1 callers
+	   and direct module tests source-compatible; absent means an agent run,
+	   because the workflow action runtime always states it. */
+	readonly invocation?: 'agent-run' | 'workflow-action';
 	readonly idempotencyKey?: string;
 	/* Trusted provenance for record history. Optional preserves v1 direct tool
 	   callers; harness and workflow executions always provide it. */
@@ -115,6 +121,28 @@ export interface AgentToolContext {
 	readonly signal: AbortSignal;
 }
 
+export interface AgentToolConsentDecision {
+	readonly granted: boolean;
+	/** Stable code recorded on the denial event when the gate refuses. */
+	readonly reason?: string;
+}
+
+/**
+ * A module-owned gate asked before every call of a tool that declares one, so
+ * a workspace can admit a tool per record (a connector instance an owner
+ * consented to) without the tool declaring a risk the harness refuses outright.
+ * The answer is computed per call from the already validated input and is never
+ * cached; a gate that throws denies.
+ */
+export interface AgentToolConsent {
+	/** Stable id of the gate, recorded on the denial event. */
+	readonly id: string;
+	check(
+		input: unknown,
+		context: AgentToolContext,
+	): Promise<AgentToolConsentDecision> | AgentToolConsentDecision;
+}
+
 export interface AgentTool {
 	readonly id: string;
 	readonly transport: 'api' | 'cli';
@@ -125,6 +153,9 @@ export interface AgentTool {
 	readonly contractVersion?: number;
 	readonly outputSchema?: Readonly<Record<string, unknown>>;
 	readonly risk?: 'read' | 'workspace-write' | 'external' | 'destructive';
+	/* Run-time admission on top of the permission snapshot. A tool declaring one
+	   is offered to the model as usual and refused per call when the gate says so. */
+	readonly consent?: AgentToolConsent;
 	readonly idempotency?: 'required';
 	/* A mutating tool is executable only when its target persists the key and
 	   returns the first result on retry. Declaring `required` alone is not that
@@ -355,15 +386,92 @@ function toolFailure(error: unknown): { code: string; message: string } {
 	return { code: 'TOOL_EXECUTION_FAILED', message };
 }
 
+/**
+ * `external` is the ceiling no unattended caller crosses: the CLI runner
+ * refuses it, `defineCliAgentTool` and `defineApiAgentTool` refuse to build it,
+ * and a hand-built tool object is refused here as well, before the model is
+ * ever told the tool exists.
+ */
+function admissibleRisk(tool: AgentTool): boolean {
+	return tool.risk !== 'external';
+}
+
+/* A refusal code comes from module code, so it is bounded to the shape an
+   event metadata field may carry before it is recorded. */
+function consentReason(reason: string | undefined): string {
+	return reason !== undefined && /^[A-Z][A-Z0-9_]{2,63}$/.test(reason)
+		? reason
+		: 'TOOL_CONSENT_REFUSED';
+}
+
+/**
+ * The narrow tracing port the harness needs, declared here rather than
+ * imported: `@flowdular/sdk/server` is a sibling package, not a dependency of the
+ * harness, and its tracer satisfies this shape structurally. The composer that
+ * owns both hands one in; without it the harness records nothing and pays one
+ * optional call per provider and per tool.
+ */
+export interface AgentTraceContext {
+	readonly traceId: string;
+	readonly spanId: string;
+	readonly sampled: boolean;
+}
+
+export interface AgentTraceSpan {
+	readonly context: AgentTraceContext;
+	setAttribute(key: string, value: string | number | boolean): void;
+	end(status?: 'unset' | 'ok' | 'error', message?: string): void;
+}
+
+export interface AgentSpanOptions {
+	readonly parent?: AgentTraceContext | null;
+	readonly kind?: 'internal' | 'client';
+	readonly attributes?: Readonly<Record<string, string | number | boolean>>;
+}
+
+export interface AgentTracer {
+	startSpan(name: string, options?: AgentSpanOptions): AgentTraceSpan;
+}
+
+/* Foreign code on the run path: a tracer that throws must cost the run
+   nothing, so both ends answer with an absent span instead of raising. */
+function startSpan(
+	tracer: AgentTracer | undefined,
+	name: string,
+	options: AgentSpanOptions,
+): AgentTraceSpan | undefined {
+	if (!tracer) return undefined;
+	try {
+		return tracer.startSpan(name, options);
+	} catch {
+		return undefined;
+	}
+}
+
+function endSpan(
+	span: AgentTraceSpan | undefined,
+	status: 'ok' | 'error',
+	message?: string,
+): void {
+	if (!span) return;
+	try {
+		span.end(status, message);
+	} catch {
+		/* An observer that throws is the observer's defect, not the run's. */
+	}
+}
+
 export class AgentHarness {
 	readonly #providers: ReadonlyMap<string, AgentProvider>;
 	readonly #tools: ReadonlyMap<string, AgentTool>;
 	readonly #authorizeToolAccess: AgentToolAccessAuthorizer;
+	readonly #tracer: AgentTracer | undefined;
 
 	constructor(options: {
 		readonly providers: readonly AgentProvider[];
 		readonly tools?: readonly AgentTool[];
 		readonly authorizeToolAccess?: AgentToolAccessAuthorizer;
+		readonly tracer?: AgentTracer;
 	}) {
 		const providers = new Map<string, AgentProvider>();
 		for (const provider of options.providers) {
@@ -385,6 +493,9 @@ export class AgentHarness {
 					`Tool ${id} is already registered.`,
 				);
 			}
+			/* The gate id reaches the denial event, so it is held to the same
+			   shape as the tool id rather than checked only where it is emitted. */
+			if (tool.consent) identifier(tool.consent.id, 'tool.consent.id');
 			toolTimeoutMs(tool.timeoutMs);
 			tools.set(id, tool);
 		}
@@ -394,6 +505,7 @@ export class AgentHarness {
 		   service actors fail-closed instead of treating a stored snapshot as a
 		   permanent credential. */
 		this.#authorizeToolAccess = options.authorizeToolAccess ?? (() => []);
+		this.#tracer = options.tracer;
 	}
 
 	providers(): readonly string[] {
@@ -514,6 +626,7 @@ export class AgentHarness {
 		const initialPermissions = await livePermissions();
 		const availableTools = [...this.#tools.values()]
 			.filter((tool) => snapshotGrants.has(tool.id))
+			.filter(admissibleRisk)
 			.filter((tool) =>
 				tool.requiredPermissions.every((permission) =>
 					initialPermissions.has(permission),
@@ -547,6 +660,8 @@ export class AgentHarness {
 			model: request.definition.model,
 		});
 		const grantedIds = new Set(availableTools.map((tool) => tool.id));
+		const tracer = this.#tracer;
+		let providerSpan: AgentTraceSpan | undefined;
 		let toolCallOrdinal = 0;
 		const invokeTool = async (
 			id: string,
@@ -555,6 +670,16 @@ export class AgentHarness {
 		): Promise<unknown> => {
 			const ordinal = ++toolCallOrdinal;
 			const tool = this.#tools.get(id);
+			if (tool && !admissibleRisk(tool)) {
+				emit('tool.denied', `Tool ${id} was denied.`, {
+					tool: id,
+					reason: 'TOOL_RISK_REFUSED',
+				});
+				throw new AgentHarnessError(
+					'TOOL_RISK_REFUSED',
+					`Tool ${id} declares external risk and cannot run unattended.`,
+				);
+			}
 			if (!tool || !grantedIds.has(id)) {
 				emit('tool.denied', `Tool ${id} was denied.`, {
 					tool: id,
@@ -623,6 +748,47 @@ export class AgentHarness {
 				});
 				throw error;
 			}
+			if (tool.consent) {
+				/* Foreign code: a throw is a refusal, never a crash. The run deadline
+				   already bounds it, because the provider call this runs inside races
+				   the execution timeout. */
+				let decision: AgentToolConsentDecision;
+				try {
+					decision = await tool.consent.check(input, {
+						runId: request.runId,
+						tenantId: request.tenantId,
+						requestedBy: request.requestedBy,
+						agentId: request.definition.id,
+						agentName: request.definition.name,
+						invocation: 'agent-run',
+						actor: {
+							kind: 'agent',
+							id: request.definition.id,
+							label: request.definition.name,
+							runId: request.runId,
+						},
+						...(authorizationSubject?.kind === 'user'
+							? { authorizationSubject }
+							: {}),
+						permissions,
+						signal: controller.signal,
+					});
+				} catch {
+					decision = { granted: false, reason: 'TOOL_CONSENT_UNAVAILABLE' };
+				}
+				if (!decision.granted) {
+					const reason = consentReason(decision.reason);
+					emit('tool.denied', `Tool ${id} was denied.`, {
+						tool: id,
+						consent: tool.consent.id,
+						reason,
+					});
+					throw new AgentHarnessError(
+						reason,
+						`Tool ${id} was not consented for this workspace.`,
+					);
+				}
+			}
 			emit('tool.started', `Tool ${id} started.`, {
 				tool: id,
 				ordinal,
@@ -658,6 +824,7 @@ export class AgentHarness {
 						requestedBy: request.requestedBy,
 						agentId: request.definition.id,
 						agentName: request.definition.name,
+						invocation: 'agent-run',
 						actor: {
 							kind: 'agent',
 							id: request.definition.id,
@@ -710,6 +877,38 @@ export class AgentHarness {
 				controller.signal.removeEventListener('abort', abortTool);
 			}
 		};
+		/* Wrapped rather than instrumented inside: the wrapper sees exactly what
+		   the provider sees, so a denial before the tool ever runs is a span too.
+		   Without a tracer the provider is handed the original function. */
+		const tracedInvokeTool: typeof invokeTool = !tracer
+			? invokeTool
+			: async (id, input, invocation = {}) => {
+					const span = startSpan(tracer, `tool ${id}`, {
+						...(providerSpan ? { parent: providerSpan.context } : {}),
+						kind: 'internal',
+						attributes: {
+							'flowdular.tool': id,
+							...(invocation.providerCallId
+								? {
+										'flowdular.tool.provider_call_id':
+											invocation.providerCallId.slice(0, 128),
+									}
+								: {}),
+						},
+					});
+					try {
+						const output = await invokeTool(id, input, invocation);
+						endSpan(span, 'ok');
+						return output;
+					} catch (error) {
+						endSpan(
+							span,
+							'error',
+							error instanceof AgentHarnessError ? error.code : 'TOOL_FAILED',
+						);
+						throw error;
+					}
+				};
 		let timer: ReturnType<typeof setTimeout> | undefined;
 		let rejectProviderAbort: (() => void) | undefined;
 		try {
@@ -738,6 +937,16 @@ export class AgentHarness {
 					controller.abort('timeout');
 				}, request.definition.timeoutMs);
 			});
+			providerSpan = startSpan(tracer, `provider ${provider.id}`, {
+				kind: 'client',
+				attributes: {
+					'flowdular.agent.run_id': request.runId,
+					'flowdular.agent.id': request.definition.id,
+					'flowdular.agent.provider': provider.id,
+					'flowdular.agent.model': request.definition.model,
+					'flowdular.agent.trigger': request.trigger,
+				},
+			});
 			const providerResult = await Promise.race([
 				provider.execute({
 					request,
@@ -752,7 +961,7 @@ export class AgentHarness {
 							additionalProperties: false,
 						},
 					})),
-					invokeTool,
+					invokeTool: tracedInvokeTool,
 					emit,
 				}),
 				timeout,
@@ -779,6 +988,7 @@ export class AgentHarness {
 			emit('provider.completed', `Provider ${provider.id} completed.`, {
 				finishReason: providerResult.finishReason,
 			});
+			endSpan(providerSpan, 'ok', providerResult.finishReason);
 			const completedAt = Date.now();
 			emit('run.completed', 'Harness completed the run.');
 			return {
@@ -788,6 +998,13 @@ export class AgentHarness {
 				startedAt,
 				completedAt,
 			};
+		} catch (error) {
+			endSpan(
+				providerSpan,
+				'error',
+				error instanceof AgentHarnessError ? error.code : 'PROVIDER_FAILED',
+			);
+			throw error;
 		} finally {
 			acceptingEvents = false;
 			if (timer !== undefined) clearTimeout(timer);

package/packages/harness/src/tool-adapters.ts

@@ -1,5 +1,9 @@
 import type { CapabilityRisk } from '@flowdular/sdk/contracts';
-import type { AgentTool, AgentToolContext } from './runtime.ts';
+import type {
+	AgentTool,
+	AgentToolConsent,
+	AgentToolContext,
+} from './runtime.ts';
 
 interface AgentToolBase {
 	readonly id: string;
@@ -9,6 +13,9 @@ interface AgentToolBase {
 	readonly contractVersion?: number;
 	readonly outputSchema?: Readonly<Record<string, unknown>>;
 	readonly risk?: 'read' | 'workspace-write' | 'external' | 'destructive';
+	/* Asked per call, after input validation, by every caller that runs the
+	   tool: the harness and the workflow action runtime. */
+	readonly consent?: AgentToolConsent;
 	readonly idempotency?: 'required';
 	readonly idempotencyProtection?: 'target-ledger';
 	readonly cancellation?: 'cooperative' | 'not-supported';
@@ -36,6 +43,11 @@ function dottedIdentifier(value: string, field: string): string {
 export function defineApiAgentTool(
 	definition: ApiAgentToolDefinition,
 ): AgentTool {
+	if (definition.risk === 'external') {
+		throw new Error(
+			`Tool ${definition.id} declares external risk and cannot be registered as an unattended agent tool.`,
+		);
+	}
 	return Object.freeze({
 		id: dottedIdentifier(definition.id, 'Tool id'),
 		transport: 'api' as const,
@@ -49,6 +61,9 @@ export function defineApiAgentTool(
 			? {}
 			: { outputSchema: definition.outputSchema }),
 		...(definition.risk === undefined ? {} : { risk: definition.risk }),
+		...(definition.consent === undefined
+			? {}
+			: { consent: definition.consent }),
 		...(definition.idempotency === undefined
 			? {}
 			: { idempotency: definition.idempotency }),
@@ -89,6 +104,9 @@ export function defineCliAgentTool(
 			? {}
 			: { outputSchema: definition.outputSchema }),
 		...(definition.risk === undefined ? {} : { risk: definition.risk }),
+		...(definition.consent === undefined
+			? {}
+			: { consent: definition.consent }),
 		...(definition.idempotency === undefined
 			? {}
 			: { idempotency: definition.idempotency }),