@flowdular/sdk 0.1.0

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

@@ -0,0 +1,294 @@
+import type {
+	AgentExecutionEvent,
+	AgentExecutionResult,
+} from '@flowdular/sdk/harness';
+import type {
+	AgentAuditEvent,
+	AgentAuditPage,
+	AgentDefinition,
+	AgentDefinitionRevision,
+	ModuleAgentBinding,
+	ModuleAgentDefinition,
+	AgentActionInvocation,
+	AgentRun,
+	AgentRunDetail,
+	AgentRunExecution,
+	AgentProcedure,
+	AgentUsageAgent,
+	AgentUsageBucket,
+	AgentUsageDay,
+	AuditChainVerification,
+} from '../domain/types.ts';
+
+export class DuplicateAgentKeyError extends Error {
+	constructor() {
+		super('An agent with this key already exists in the active tenant.');
+		this.name = 'DuplicateAgentKeyError';
+	}
+}
+
+export class DuplicateAgentProcedureKeyError extends Error {
+	constructor() {
+		super(
+			'An agent procedure with this key already exists in the active tenant.',
+		);
+		this.name = 'DuplicateAgentProcedureKeyError';
+	}
+}
+
+export class DuplicateRunIdempotencyKeyError extends Error {
+	constructor() {
+		super(
+			'A run with this idempotency key already exists in the active tenant.',
+		);
+		this.name = 'DuplicateRunIdempotencyKeyError';
+	}
+}
+
+export class DuplicateActionIdempotencyKeyError extends Error {
+	constructor() {
+		super('An action invocation with this idempotency key already exists.');
+		this.name = 'DuplicateActionIdempotencyKeyError';
+	}
+}
+
+export class ModuleAgentBindingConflictError extends Error {
+	constructor() {
+		super('The module agent binding was changed by another request.');
+		this.name = 'ModuleAgentBindingConflictError';
+	}
+}
+
+export interface RecoverableRun {
+	readonly tenantId: string;
+	readonly runId: string;
+}
+
+export interface CompletedRunCost {
+	readonly day: string;
+	readonly costMicroUsd: number | null;
+}
+
+export type PendingAgentAuditEvent = Omit<
+	AgentAuditEvent,
+	'id' | 'sequence' | 'previousHash' | 'eventHash'
+>;
+
+export interface AgentRepository {
+	close(): Promise<void>;
+	reconcileModuleAgents(
+		definitions: readonly ModuleAgentDefinition[],
+		reconciledAt: number,
+	): Promise<void>;
+	listModuleAgentBindings(
+		tenantId: string,
+	): Promise<readonly ModuleAgentBinding[]>;
+	getModuleAgentBinding(
+		tenantId: string,
+		agentId: string,
+	): Promise<ModuleAgentBinding | null>;
+	saveModuleAgentBinding(
+		binding: ModuleAgentBinding,
+		definition: ModuleAgentDefinition,
+		expectedRevision: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<ModuleAgentBinding>;
+	listAgents(tenantId: string): Promise<readonly AgentDefinition[]>;
+	getAgent(tenantId: string, agentId: string): Promise<AgentDefinition | null>;
+	getAgentRevision(
+		tenantId: string,
+		agentId: string,
+		revision: number,
+	): Promise<AgentDefinitionRevision | null>;
+	listAgentRevisions(
+		tenantId: string,
+	): Promise<readonly AgentDefinitionRevision[]>;
+	createAgent(agent: AgentDefinition): Promise<AgentDefinition>;
+	updateAgent(agent: AgentDefinition): Promise<AgentDefinition>;
+	deleteAgent(tenantId: string, agentId: string): Promise<boolean>;
+	agentUsage(
+		tenantId: string,
+		agentId: string,
+	): Promise<{
+		readonly runs: number;
+		readonly pendingRuns: number;
+		readonly assignments: number;
+	}>;
+	providerUsage(
+		tenantId: string,
+		providerId: string,
+	): Promise<{ readonly definitions: number; readonly pendingRuns: number }>;
+	listProcedures(tenantId: string): Promise<readonly AgentProcedure[]>;
+	getProcedure(
+		tenantId: string,
+		procedureId: string,
+	): Promise<AgentProcedure | null>;
+	createProcedure(skill: AgentProcedure): Promise<AgentProcedure>;
+	updateProcedure(skill: AgentProcedure): Promise<AgentProcedure>;
+	deleteProcedure(tenantId: string, procedureId: string): Promise<boolean>;
+	procedureUsage(
+		tenantId: string,
+		procedureId: string,
+	): Promise<{
+		readonly assignments: number;
+		readonly activeDefinitions: number;
+	}>;
+	listRuns(tenantId: string, limit: number): Promise<readonly AgentRun[]>;
+	getRun(tenantId: string, runId: string): Promise<AgentRunDetail | null>;
+	listRunEvents(
+		tenantId: string,
+		runId: string,
+		afterSequence: number,
+	): Promise<readonly AgentExecutionEvent[]>;
+	findRunByIdempotencyKey(
+		tenantId: string,
+		idempotencyKey: string,
+	): Promise<AgentRun | null>;
+	enqueueRun(
+		run: AgentRunExecution,
+		idempotencyKey: string | null,
+		audit: PendingAgentAuditEvent,
+	): Promise<AgentRun>;
+	listRecoverableRuns(
+		now: number,
+		limit: number,
+	): Promise<readonly RecoverableRun[]>;
+	claimRun(
+		tenantId: string,
+		runId: string,
+		workerId: string,
+		now: number,
+		leaseExpiresAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<AgentRunExecution | null>;
+	renewLease(
+		tenantId: string,
+		runId: string,
+		workerId: string,
+		leaseExpiresAt: number,
+	): Promise<boolean>;
+	consumeRunGrant(input: {
+		readonly grantId: string;
+		readonly tokenHash: string;
+		readonly tenantId: string;
+		readonly runId: string;
+		readonly workerId: string;
+		readonly providerId: string;
+		readonly modelId: string;
+		readonly issuedAt: number;
+		readonly expiresAt: number;
+		readonly consumedAt: number;
+	}): Promise<boolean>;
+	appendRunEvent(
+		tenantId: string,
+		runId: string,
+		event: AgentExecutionEvent,
+	): Promise<void>;
+	completeRun(
+		tenantId: string,
+		runId: string,
+		workerId: string,
+		result: AgentExecutionResult,
+		audit: PendingAgentAuditEvent,
+	): Promise<void>;
+	failRun(
+		tenantId: string,
+		runId: string,
+		workerId: string,
+		code: string,
+		message: string,
+		completedAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<void>;
+	/* Returns the status the run had, or null when it was already terminal. */
+	cancelRun(
+		tenantId: string,
+		runId: string,
+		message: string,
+		completedAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<AgentRun['status'] | null>;
+	enqueueAction(
+		invocation: AgentActionInvocation,
+		audit: PendingAgentAuditEvent,
+	): Promise<AgentActionInvocation>;
+	getAction(
+		tenantId: string,
+		invocationId: string,
+	): Promise<AgentActionInvocation | null>;
+	findActionByIdempotencyKey(
+		tenantId: string,
+		idempotencyKey: string,
+	): Promise<AgentActionInvocation | null>;
+	listRecoverableActions(
+		now: number,
+		limit: number,
+	): Promise<
+		readonly { readonly tenantId: string; readonly invocationId: string }[]
+	>;
+	claimAction(
+		tenantId: string,
+		invocationId: string,
+		workerId: string,
+		now: number,
+		leaseExpiresAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<AgentActionInvocation | null>;
+	renewActionLease(
+		tenantId: string,
+		invocationId: string,
+		workerId: string,
+		leaseExpiresAt: number,
+	): Promise<boolean>;
+	completeAction(
+		tenantId: string,
+		invocationId: string,
+		workerId: string,
+		output: import('@flowdular/sdk/harness').JsonValue,
+		completedAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<boolean>;
+	failAction(
+		tenantId: string,
+		invocationId: string,
+		workerId: string,
+		code: string,
+		completedAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<boolean>;
+	cancelAction(
+		tenantId: string,
+		invocationId: string,
+		completedAt: number,
+		audit: PendingAgentAuditEvent,
+	): Promise<AgentActionInvocation['status'] | null>;
+	appendAuditEvent(event: PendingAgentAuditEvent): Promise<AgentAuditEvent>;
+	listAuditEvents(
+		tenantId: string,
+		limit: number,
+	): Promise<readonly AgentAuditEvent[]>;
+	/* Keyset page over the tenant trail, newest first, cursor `occurredAt:sequence`. */
+	pageAuditEvents(
+		tenantId: string,
+		cursor: { readonly occurredAt: number; readonly sequence: number } | null,
+		limit: number,
+	): Promise<AgentAuditPage>;
+	verifyAuditChain(tenantId: string): Promise<boolean>;
+	verifyAuditChainDetailed(tenantId: string): Promise<AuditChainVerification>;
+	usageByDay(
+		tenantId: string,
+		fromDay: string,
+		toDay: string,
+	): Promise<readonly AgentUsageDay[]>;
+	usageByAgent(
+		tenantId: string,
+		fromDay: string,
+		toDay: string,
+	): Promise<readonly AgentUsageAgent[]>;
+	/* One indexed aggregate; `agentId` narrows it to a single agent's spend. */
+	usageTotal(
+		tenantId: string,
+		fromDay: string,
+		agentId: string | null,
+	): Promise<AgentUsageBucket>;
+}

package/modules/agents/src/services/run-grant.ts

@@ -0,0 +1,305 @@
+import {
+	createHash,
+	createHmac,
+	randomBytes,
+	randomUUID,
+	timingSafeEqual,
+} from 'node:crypto';
+import {
+	closeSync,
+	mkdirSync,
+	openSync,
+	readFileSync,
+	writeFileSync,
+} from 'node:fs';
+import { dirname } from 'node:path';
+import { flowdularLocalDataPath } from '@flowdular/sdk/kernel/legacy-local-state';
+
+const GRANT_ISSUER = 'flowdular-control-plane';
+const GRANT_AUDIENCE = 'agent-provider-broker';
+
+export interface AgentRunGrantClaims {
+	readonly version: 1;
+	readonly issuer: typeof GRANT_ISSUER;
+	readonly audience: typeof GRANT_AUDIENCE;
+	readonly grantId: string;
+	readonly tenantId: string;
+	readonly runId: string;
+	readonly providerId: string;
+	readonly modelId: string;
+	readonly workerId: string;
+	readonly attempt: number;
+	readonly permissionDigest: string;
+	readonly toolGrantDigest: string;
+	readonly issuedAt: number;
+	readonly expiresAt: number;
+}
+
+export interface IssuedAgentRunGrant {
+	readonly token: string;
+	readonly claims: AgentRunGrantClaims;
+}
+
+export interface IssueAgentRunGrantInput {
+	readonly tenantId: string;
+	readonly runId: string;
+	readonly providerId: string;
+	readonly modelId: string;
+	readonly workerId: string;
+	readonly attempt: number;
+	readonly permissions: readonly string[];
+	readonly toolGrants: readonly string[];
+	readonly leaseExpiresAt: number;
+}
+
+export class AgentRunGrantError extends Error {
+	constructor(
+		readonly code: string,
+		message: string,
+	) {
+		super(message);
+		this.name = 'AgentRunGrantError';
+	}
+}
+
+function digest(values: readonly string[]): string {
+	return createHash('sha256')
+		.update(JSON.stringify([...new Set(values)].sort()), 'utf8')
+		.digest('base64url');
+}
+
+function grantKey(value: string): Buffer {
+	const key = Buffer.from(value.trim(), 'base64');
+	if (key.byteLength !== 32) {
+		key.fill(0);
+		throw new Error(
+			'FD_AGENT_RUN_GRANT_KEY must be a base64-encoded 32-byte key.',
+		);
+	}
+	return key;
+}
+
+function readOrCreateDevelopmentKey(path: string): Buffer {
+	try {
+		return grantKey(readFileSync(path, 'utf8'));
+	} catch (error) {
+		if ((error as NodeJS.ErrnoException).code !== 'ENOENT') throw error;
+	}
+	mkdirSync(dirname(path), { recursive: true, mode: 0o700 });
+	const descriptor = openSync(path, 'wx', 0o600);
+	try {
+		const encoded = randomBytes(32).toString('base64');
+		writeFileSync(descriptor, encoded, { encoding: 'utf8' });
+		return grantKey(encoded);
+	} finally {
+		closeSync(descriptor);
+	}
+}
+
+function stringClaim(value: unknown, field: string, maximum = 256): string {
+	if (
+		typeof value !== 'string' ||
+		value.length < 1 ||
+		value.length > maximum ||
+		value.includes('\u0000')
+	) {
+		throw new AgentRunGrantError(
+			'RUN_GRANT_INVALID',
+			`Run grant ${field} is invalid.`,
+		);
+	}
+	return value;
+}
+
+function numberClaim(value: unknown, field: string): number {
+	if (!Number.isSafeInteger(value) || (value as number) < 0) {
+		throw new AgentRunGrantError(
+			'RUN_GRANT_INVALID',
+			`Run grant ${field} is invalid.`,
+		);
+	}
+	return value as number;
+}
+
+export class AgentRunGrantAuthority {
+	readonly #key: Buffer;
+	readonly #now: () => number;
+
+	constructor(
+		key: Buffer,
+		private readonly ttlMs = 30_000,
+		now: () => number = Date.now,
+	) {
+		if (key.byteLength !== 32) {
+			throw new Error('Run grant signing requires a 32-byte key.');
+		}
+		if (!Number.isSafeInteger(ttlMs) || ttlMs < 1_000 || ttlMs > 300_000) {
+			throw new Error('Run grant TTL must be between 1000 and 300000 ms.');
+		}
+		this.#key = Buffer.from(key);
+		this.#now = now;
+	}
+
+	issue(input: IssueAgentRunGrantInput): IssuedAgentRunGrant {
+		const issuedAt = this.#now();
+		const expiresAt = Math.min(issuedAt + this.ttlMs, input.leaseExpiresAt);
+		if (expiresAt - issuedAt < 500) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_LEASE_TOO_SHORT',
+				'The worker lease is too short to issue a run grant.',
+			);
+		}
+		const claims: AgentRunGrantClaims = {
+			version: 1,
+			issuer: GRANT_ISSUER,
+			audience: GRANT_AUDIENCE,
+			grantId: randomUUID(),
+			tenantId: stringClaim(input.tenantId, 'tenantId'),
+			runId: stringClaim(input.runId, 'runId'),
+			providerId: stringClaim(input.providerId, 'providerId'),
+			modelId: stringClaim(input.modelId, 'modelId'),
+			workerId: stringClaim(input.workerId, 'workerId'),
+			attempt: numberClaim(input.attempt, 'attempt'),
+			permissionDigest: digest(input.permissions),
+			toolGrantDigest: digest(input.toolGrants),
+			issuedAt,
+			expiresAt,
+		};
+		const payload = Buffer.from(JSON.stringify(claims), 'utf8').toString(
+			'base64url',
+		);
+		const signed = `v1.${payload}`;
+		const signature = createHmac('sha256', this.#key)
+			.update(signed, 'utf8')
+			.digest('base64url');
+		return { token: `${signed}.${signature}`, claims };
+	}
+
+	verify(token: string): AgentRunGrantClaims {
+		if (token.length < 64 || token.length > 8_192) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_INVALID',
+				'Run grant is invalid.',
+			);
+		}
+		const [version, payload, signature, extra] = token.split('.');
+		if (version !== 'v1' || !payload || !signature || extra !== undefined) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_INVALID',
+				'Run grant is invalid.',
+			);
+		}
+		const expected = createHmac('sha256', this.#key)
+			.update(`${version}.${payload}`, 'utf8')
+			.digest();
+		let supplied: Buffer;
+		try {
+			supplied = Buffer.from(signature, 'base64url');
+		} catch {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_INVALID',
+				'Run grant is invalid.',
+			);
+		}
+		if (
+			supplied.byteLength !== expected.byteLength ||
+			!timingSafeEqual(supplied, expected)
+		) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_SIGNATURE_INVALID',
+				'Run grant signature is invalid.',
+			);
+		}
+		let raw: unknown;
+		try {
+			raw = JSON.parse(Buffer.from(payload, 'base64url').toString('utf8'));
+		} catch {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_INVALID',
+				'Run grant payload is invalid.',
+			);
+		}
+		if (!raw || typeof raw !== 'object' || Array.isArray(raw)) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_INVALID',
+				'Run grant payload is invalid.',
+			);
+		}
+		const value = raw as Record<string, unknown>;
+		if (
+			value.version !== 1 ||
+			(value.issuer !== GRANT_ISSUER &&
+				value.issuer !== 'coreloom-control-plane') ||
+			value.audience !== GRANT_AUDIENCE
+		) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_BOUNDARY_INVALID',
+				'Run grant issuer or audience is invalid.',
+			);
+		}
+		const claims: AgentRunGrantClaims = {
+			version: 1,
+			issuer: GRANT_ISSUER,
+			audience: GRANT_AUDIENCE,
+			grantId: stringClaim(value.grantId, 'grantId'),
+			tenantId: stringClaim(value.tenantId, 'tenantId'),
+			runId: stringClaim(value.runId, 'runId'),
+			providerId: stringClaim(value.providerId, 'providerId'),
+			modelId: stringClaim(value.modelId, 'modelId'),
+			workerId: stringClaim(value.workerId, 'workerId'),
+			attempt: numberClaim(value.attempt, 'attempt'),
+			permissionDigest: stringClaim(
+				value.permissionDigest,
+				'permissionDigest',
+				64,
+			),
+			toolGrantDigest: stringClaim(
+				value.toolGrantDigest,
+				'toolGrantDigest',
+				64,
+			),
+			issuedAt: numberClaim(value.issuedAt, 'issuedAt'),
+			expiresAt: numberClaim(value.expiresAt, 'expiresAt'),
+		};
+		const now = this.#now();
+		if (
+			claims.issuedAt > now + 5_000 ||
+			claims.expiresAt <= now ||
+			claims.expiresAt - claims.issuedAt > this.ttlMs
+		) {
+			throw new AgentRunGrantError(
+				'RUN_GRANT_EXPIRED',
+				'Run grant is expired or outside its allowed lifetime.',
+			);
+		}
+		return claims;
+	}
+
+	tokenHash(token: string): string {
+		return createHash('sha256').update(token, 'utf8').digest('base64url');
+	}
+}
+
+export function runGrantAuthorityFromEnvironment(
+	environment: NodeJS.ProcessEnv = process.env,
+	workspaceRoot = process.cwd(),
+	ttlMs = 30_000,
+): AgentRunGrantAuthority {
+	const configured = environment.FD_AGENT_RUN_GRANT_KEY;
+	if (configured)
+		return new AgentRunGrantAuthority(grantKey(configured), ttlMs);
+	if (environment.NODE_ENV === 'production') {
+		throw new Error(
+			'FD_AGENT_RUN_GRANT_KEY is required in production before agent runs can execute.',
+		);
+	}
+	if (environment.NODE_ENV === 'test') {
+		return new AgentRunGrantAuthority(Buffer.alloc(32, 0x47), ttlMs);
+	}
+	return new AgentRunGrantAuthority(
+		readOrCreateDevelopmentKey(
+			flowdularLocalDataPath(workspaceRoot, 'agent-run-grant.key'),
+		),
+		ttlMs,
+	);
+}

package/modules/agents/src/services/usage-service.ts

@@ -0,0 +1,119 @@
+import type { AgentUsageSummary } from '../domain/types.ts';
+import type { AgentSettingsReader } from '../settings.ts';
+import type { AgentRepository } from './repository.ts';
+
+/* The bucket a run is counted in. UTC so a tenant rollup does not move when a
+   reader's clock does, and precomputed at write time so the aggregate stays an
+   index scan instead of a per-row date conversion. */
+export function usageDay(timestamp: number): string {
+	return new Date(timestamp).toISOString().slice(0, 10);
+}
+
+const DAY_MS = 86_400_000;
+const MAX_WINDOW_DAYS = 180;
+const DEFAULT_WINDOW_DAYS = 30;
+
+export interface BudgetRefusal {
+	readonly code: string;
+	readonly message: string;
+}
+
+function firstDayOfMonth(now: number): string {
+	return `${usageDay(now).slice(0, 7)}-01`;
+}
+
+function usd(micros: number): string {
+	return `$${(micros / 1_000_000).toFixed(2)}`;
+}
+
+/* Caps are entered in whole dollars and compared in micro-USD, the same unit
+   every stored cost uses, so the comparison never crosses a float boundary. */
+function capMicros(value: number): number {
+	return Number.isFinite(value) && value > 0
+		? Math.round(value * 1_000_000)
+		: 0;
+}
+
+/* Reads the rollup the runs already wrote. It never prices a run itself: the
+   price is applied once, when the run completes. */
+export class AgentUsageService {
+	constructor(
+		private readonly repository: AgentRepository,
+		private readonly settings?: AgentSettingsReader,
+		private readonly now: () => number = Date.now,
+	) {}
+
+	async summary(
+		tenantId: string,
+		days = DEFAULT_WINDOW_DAYS,
+	): Promise<AgentUsageSummary> {
+		const window = Number.isSafeInteger(days)
+			? Math.min(Math.max(1, days), MAX_WINDOW_DAYS)
+			: DEFAULT_WINDOW_DAYS;
+		const now = this.now();
+		const to = usageDay(now);
+		const from = usageDay(now - (window - 1) * DAY_MS);
+		const monthFrom = firstDayOfMonth(now);
+		return {
+			from,
+			to,
+			days: await this.repository.usageByDay(tenantId, from, to),
+			agents: await this.repository.usageByAgent(tenantId, from, to),
+			month: {
+				from: monthFrom,
+				...(await this.repository.usageTotal(tenantId, monthFrom, null)),
+			},
+			caps: this.caps(tenantId),
+		};
+	}
+
+	caps(tenantId: string): AgentUsageSummary['caps'] {
+		return {
+			monthlyCostMicroUsd: capMicros(
+				this.settings?.monthlyCostCapUsd(tenantId) ?? 0,
+			),
+			agentMonthlyCostMicroUsd: capMicros(
+				this.settings?.agentMonthlyCostCapUsd(tenantId) ?? 0,
+			),
+		};
+	}
+
+	/* Checked at enqueue against spend already settled. A run that is in flight
+	   has not reported usage yet, so concurrent enqueues can overshoot a cap by
+	   the cost of the runs still executing; a run over the cap is never killed
+	   mid-way, only the next enqueue is refused. */
+	async check(
+		tenantId: string,
+		agentId: string,
+		now = this.now(),
+	): Promise<BudgetRefusal | null> {
+		const caps = this.caps(tenantId);
+		if (caps.monthlyCostMicroUsd === 0 && caps.agentMonthlyCostMicroUsd === 0) {
+			return null;
+		}
+		const monthFrom = firstDayOfMonth(now);
+		if (caps.monthlyCostMicroUsd > 0) {
+			const spent = (
+				await this.repository.usageTotal(tenantId, monthFrom, null)
+			).costMicroUsd;
+			if (spent >= caps.monthlyCostMicroUsd) {
+				return {
+					code: 'BUDGET_EXCEEDED',
+					message: `The workspace has used ${usd(spent)} of its ${usd(caps.monthlyCostMicroUsd)} monthly agent budget.`,
+				};
+			}
+		}
+		if (caps.agentMonthlyCostMicroUsd > 0) {
+			const spent = (
+				await this.repository.usageTotal(tenantId, monthFrom, agentId)
+			).costMicroUsd;
+			if (spent >= caps.agentMonthlyCostMicroUsd) {
+				return {
+					code: 'BUDGET_EXCEEDED',
+					message: `This agent has used ${usd(spent)} of its ${usd(caps.agentMonthlyCostMicroUsd)} monthly budget.`,
+				};
+			}
+		}
+		return null;
+	}
+}