@flowdular/sdk 0.1.0

package/packages/harness/src/task-packet.ts

@@ -0,0 +1,86 @@
+export interface TaskPacket {
+	readonly schemaVersion: 1;
+	readonly taskId: string;
+	readonly capability: string;
+	readonly blueprint: string;
+	readonly spec: string;
+	readonly specStatus: 'approved';
+	readonly allowedPaths: readonly string[];
+	readonly steps: readonly string[];
+	readonly gates: readonly string[];
+}
+
+export interface TaskPacketIssue {
+	readonly code: string;
+	readonly message: string;
+}
+
+const broadPaths = new Set([
+	'*',
+	'**',
+	'./**',
+	'platform/**',
+	'modules/**',
+	'packages/**',
+	'infra/**',
+	'docs/**',
+	'specs/**',
+	'.ai/**',
+	'.github/**',
+	'.',
+]);
+
+export function validateTaskPacket(
+	packet: TaskPacket,
+): readonly TaskPacketIssue[] {
+	const issues: TaskPacketIssue[] = [];
+	if (packet.schemaVersion !== 1) {
+		issues.push({
+			code: 'TASK_SCHEMA_VERSION',
+			message: 'Only task packet schemaVersion 1 is supported.',
+		});
+	}
+	if (packet.specStatus !== 'approved') {
+		issues.push({
+			code: 'SPEC_NOT_APPROVED',
+			message: 'Implementation requires an approved spec.',
+		});
+	}
+	if (!/^[a-z][a-z0-9-]+@[0-9]+\.[0-9]+\.[0-9]+$/.test(packet.blueprint)) {
+		issues.push({
+			code: 'BLUEPRINT_NOT_PINNED',
+			message: 'Blueprint id must include an exact semantic version.',
+		});
+	}
+	if (
+		packet.allowedPaths.length === 0 ||
+		packet.allowedPaths.some((path) => broadPaths.has(path))
+	) {
+		issues.push({
+			code: 'PATH_SCOPE_TOO_BROAD',
+			message: 'Task paths must be non-empty and module-bounded.',
+		});
+	}
+	if (packet.steps.length === 0) {
+		issues.push({
+			code: 'STEPS_MISSING',
+			message: 'A low-cost executor needs explicit ordered steps.',
+		});
+	}
+	if (packet.gates.length === 0) {
+		issues.push({
+			code: 'GATES_MISSING',
+			message: 'A task packet must declare verification gates.',
+		});
+	}
+	return issues;
+}
+
+export function assertTaskPacket(packet: TaskPacket): void {
+	const issues = validateTaskPacket(packet);
+	if (issues.length > 0) {
+		throw new Error(
+			issues.map((issue) => `${issue.code}: ${issue.message}`).join('\n'),
+		);
+	}
+}

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

@@ -0,0 +1,106 @@
+import type { CapabilityRisk } from '@flowdular/sdk/contracts';
+import type { AgentTool, AgentToolContext } from './runtime.ts';
+
+interface AgentToolBase {
+	readonly id: string;
+	readonly description: string;
+	readonly requiredPermissions: readonly string[];
+	readonly inputSchema?: Readonly<Record<string, unknown>>;
+	readonly contractVersion?: number;
+	readonly outputSchema?: Readonly<Record<string, unknown>>;
+	readonly risk?: 'read' | 'workspace-write' | 'external' | 'destructive';
+	readonly idempotency?: 'required';
+	readonly idempotencyProtection?: 'target-ledger';
+	readonly cancellation?: 'cooperative' | 'not-supported';
+	execute(input: unknown, context: AgentToolContext): Promise<unknown>;
+}
+
+export interface ApiAgentToolDefinition extends AgentToolBase {
+	readonly endpointId: string;
+}
+
+export interface CliAgentToolDefinition extends AgentToolBase {
+	readonly capability: {
+		readonly id: string;
+		readonly risk: CapabilityRisk;
+	};
+}
+
+function dottedIdentifier(value: string, field: string): string {
+	if (!/^[a-z][a-z0-9-]*(\.[a-z][a-z0-9-]*)+$/.test(value)) {
+		throw new Error(`${field} must be a lowercase dot-separated identifier.`);
+	}
+	return value;
+}
+
+export function defineApiAgentTool(
+	definition: ApiAgentToolDefinition,
+): AgentTool {
+	return Object.freeze({
+		id: dottedIdentifier(definition.id, 'Tool id'),
+		transport: 'api' as const,
+		target: dottedIdentifier(definition.endpointId, 'Endpoint id'),
+		description: definition.description,
+		requiredPermissions: [...definition.requiredPermissions],
+		...(definition.contractVersion === undefined
+			? {}
+			: { contractVersion: definition.contractVersion }),
+		...(definition.outputSchema === undefined
+			? {}
+			: { outputSchema: definition.outputSchema }),
+		...(definition.risk === undefined ? {} : { risk: definition.risk }),
+		...(definition.idempotency === undefined
+			? {}
+			: { idempotency: definition.idempotency }),
+		...(definition.idempotencyProtection === undefined
+			? {}
+			: { idempotencyProtection: definition.idempotencyProtection }),
+		...(definition.cancellation === undefined
+			? {}
+			: { cancellation: definition.cancellation }),
+		...(definition.inputSchema === undefined
+			? {}
+			: { inputSchema: definition.inputSchema }),
+		execute: definition.execute,
+	});
+}
+
+export function defineCliAgentTool(
+	definition: CliAgentToolDefinition,
+): AgentTool {
+	if (
+		definition.capability.risk === 'external' ||
+		definition.capability.risk === 'destructive'
+	) {
+		throw new Error(
+			`CLI capability ${definition.capability.id} requires an approval receipt and cannot be registered as an unattended agent tool.`,
+		);
+	}
+	return Object.freeze({
+		id: dottedIdentifier(definition.id, 'Tool id'),
+		transport: 'cli' as const,
+		target: dottedIdentifier(definition.capability.id, 'Capability id'),
+		description: definition.description,
+		requiredPermissions: [...definition.requiredPermissions],
+		...(definition.contractVersion === undefined
+			? {}
+			: { contractVersion: definition.contractVersion }),
+		...(definition.outputSchema === undefined
+			? {}
+			: { outputSchema: definition.outputSchema }),
+		...(definition.risk === undefined ? {} : { risk: definition.risk }),
+		...(definition.idempotency === undefined
+			? {}
+			: { idempotency: definition.idempotency }),
+		...(definition.idempotencyProtection === undefined
+			? {}
+			: { idempotencyProtection: definition.idempotencyProtection }),
+		...(definition.cancellation === undefined
+			? {}
+			: { cancellation: definition.cancellation }),
+		...(definition.inputSchema === undefined
+			? {}
+			: { inputSchema: definition.inputSchema }),
+		execute: definition.execute,
+	});
+}

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

@@ -0,0 +1,242 @@
+import { AgentHarnessError } from './errors.ts';
+
+export const DEFAULT_TOOL_TIMEOUT_MS = 30_000;
+export const MIN_TOOL_TIMEOUT_MS = 250;
+export const MAX_TOOL_TIMEOUT_MS = 600_000;
+/* Tool output is re-fed to the model as context. 32 KB keeps one result from
+   consuming the whole window or the run's token budget. */
+export const MAX_TOOL_OUTPUT_CHARACTERS = 32 * 1_024;
+
+export type JsonSchema = Readonly<Record<string, unknown>>;
+
+function typeOf(value: unknown): string {
+	if (value === null) return 'null';
+	if (Array.isArray(value)) return 'array';
+	return typeof value;
+}
+
+function matchesType(value: unknown, expected: string): boolean {
+	const actual = typeOf(value);
+	if (expected === 'integer') {
+		return actual === 'number' && Number.isInteger(value);
+	}
+	if (expected === 'number') return actual === 'number';
+	return actual === expected;
+}
+
+function fail(
+	path: string,
+	reason: string,
+	code: string,
+	label: string,
+): never {
+	throw new AgentHarnessError(code, `${label} ${path || 'value'} ${reason}.`);
+}
+
+/* A deliberately small JSON Schema subset: type, enum, required, properties,
+   additionalProperties: false, items. Tools that need more validate inside
+   execute; this check exists so a model cannot hand a tool an unexpected
+   shape without the run recording why it was refused. */
+export function validateToolInput(
+	schema: JsonSchema | undefined,
+	value: unknown,
+	path = '',
+): void {
+	validateJsonValue(value, 'TOOL_INPUT_INVALID', 'Tool input');
+	validateJsonSchemaValue(schema, value, {
+		path,
+		code: 'TOOL_INPUT_INVALID',
+		label: 'Tool input',
+	});
+}
+
+export function validateToolOutput(
+	schema: JsonSchema | undefined,
+	value: unknown,
+): void {
+	validateJsonValue(value, 'TOOL_OUTPUT_INVALID', 'Tool output');
+	validateJsonSchemaValue(schema, value, {
+		code: 'TOOL_OUTPUT_INVALID',
+		label: 'Tool output',
+	});
+}
+
+export function validateStructuredOutput(
+	schema: JsonSchema,
+	value: unknown,
+): void {
+	validateJsonValue(value, 'STRUCTURED_OUTPUT_INVALID', 'Structured output');
+	validateJsonSchemaValue(schema, value, {
+		code: 'STRUCTURED_OUTPUT_INVALID',
+		label: 'Structured output',
+	});
+}
+
+/* JSON schemas cannot make undefined, non-finite numbers, class instances, or
+   cycles serializable. Durable outputs need that stronger wire guarantee. */
+export function validateJsonValue(
+	value: unknown,
+	code = 'JSON_VALUE_INVALID',
+	label = 'Value',
+): void {
+	const seen = new WeakSet<object>();
+	const visit = (item: unknown, path: string): void => {
+		if (
+			item === null ||
+			typeof item === 'string' ||
+			typeof item === 'boolean'
+		) {
+			return;
+		}
+		if (typeof item === 'number') {
+			if (Number.isFinite(item)) return;
+			fail(path, 'must be a finite number', code, label);
+		}
+		if (typeof item !== 'object') {
+			fail(path, 'must be JSON serializable', code, label);
+		}
+		if (seen.has(item)) fail(path, 'must not contain cycles', code, label);
+		seen.add(item);
+		if (Array.isArray(item)) {
+			item.forEach((child, index) => visit(child, `${path}[${index}]`));
+		} else {
+			const prototype = Object.getPrototypeOf(item);
+			if (prototype !== Object.prototype && prototype !== null) {
+				fail(path, 'must contain only plain objects', code, label);
+			}
+			for (const [key, child] of Object.entries(item)) {
+				visit(child, `${path}${path ? '.' : ''}${key}`);
+			}
+		}
+		seen.delete(item);
+	};
+	visit(value, '');
+}
+
+function validateJsonSchemaValue(
+	schema: JsonSchema | undefined,
+	value: unknown,
+	options: {
+		readonly path?: string;
+		readonly code: string;
+		readonly label: string;
+	},
+): void {
+	if (!schema) return;
+	const path = options.path ?? '';
+	const expected = schema.type;
+	if (typeof expected === 'string' && !matchesType(value, expected)) {
+		fail(path, `must be of type ${expected}`, options.code, options.label);
+	}
+	if (
+		Array.isArray(expected) &&
+		!expected.some(
+			(candidate) =>
+				typeof candidate === 'string' && matchesType(value, candidate),
+		)
+	) {
+		fail(
+			path,
+			`must be one of ${expected.join(', ')}`,
+			options.code,
+			options.label,
+		);
+	}
+	if (
+		Array.isArray(schema.enum) &&
+		!schema.enum.some((candidate) => candidate === value)
+	) {
+		fail(path, 'is not an allowed value', options.code, options.label);
+	}
+	if (typeOf(value) === 'object') {
+		const record = value as Record<string, unknown>;
+		const properties =
+			schema.properties && typeof schema.properties === 'object'
+				? (schema.properties as Record<string, JsonSchema>)
+				: {};
+		for (const key of Array.isArray(schema.required) ? schema.required : []) {
+			if (typeof key === 'string' && !(key in record)) {
+				fail(
+					`${path}${path ? '.' : ''}${key}`,
+					'is required',
+					options.code,
+					options.label,
+				);
+			}
+		}
+		for (const [key, item] of Object.entries(record)) {
+			const child = `${path}${path ? '.' : ''}${key}`;
+			const property = properties[key];
+			if (property) {
+				validateJsonSchemaValue(property, item, {
+					...options,
+					path: child,
+				});
+			} else if (schema.additionalProperties === false) {
+				fail(child, 'is not an accepted property', options.code, options.label);
+			}
+		}
+	}
+	if (
+		Array.isArray(value) &&
+		schema.items &&
+		typeof schema.items === 'object' &&
+		!Array.isArray(schema.items)
+	) {
+		value.forEach((item, index) =>
+			validateJsonSchemaValue(schema.items as JsonSchema, item, {
+				...options,
+				path: `${path}[${index}]`,
+			}),
+		);
+	}
+}
+
+export interface BoundedToolOutput {
+	readonly value: unknown;
+	readonly characters: number;
+	readonly truncated: boolean;
+}
+
+function serialize(value: unknown): string {
+	if (typeof value === 'string') return value;
+	if (value === undefined) return 'null';
+	try {
+		return JSON.stringify(value) ?? 'null';
+	} catch {
+		return String(value);
+	}
+}
+
+/* Within the cap the output passes through unchanged so structured results
+   stay structured. Over it the model receives a marked prefix instead. */
+export function boundToolOutput(
+	value: unknown,
+	maximum = MAX_TOOL_OUTPUT_CHARACTERS,
+): BoundedToolOutput {
+	const serialized = serialize(value);
+	if (serialized.length <= maximum) {
+		return { value, characters: serialized.length, truncated: false };
+	}
+	const omitted = serialized.length - maximum;
+	return {
+		value: `${serialized.slice(0, maximum)}\n[tool output truncated: ${omitted} characters omitted]`,
+		characters: serialized.length,
+		truncated: true,
+	};
+}
+
+export function toolTimeoutMs(value: number | undefined): number {
+	if (value === undefined) return DEFAULT_TOOL_TIMEOUT_MS;
+	if (
+		!Number.isSafeInteger(value) ||
+		value < MIN_TOOL_TIMEOUT_MS ||
+		value > MAX_TOOL_TIMEOUT_MS
+	) {
+		throw new AgentHarnessError(
+			'INVALID_TOOL_TIMEOUT',
+			`tool.timeoutMs must be between ${MIN_TOOL_TIMEOUT_MS} and ${MAX_TOOL_TIMEOUT_MS}.`,
+		);
+	}
+	return value;
+}

package/packages/harness/src/vercel-ai-provider.ts

@@ -0,0 +1,198 @@
+import {
+	AiProviderError,
+	classifyProviderFailure,
+	normalizeUsage,
+	probeLanguageModel,
+	resolveLanguageModel,
+	temperatureSetting,
+	type AiProviderConfiguration,
+	type AiProviderKind,
+	type ProviderReadinessResult,
+} from '@flowdular/sdk/ai-provider';
+import {
+	jsonSchema,
+	Output,
+	stepCountIs,
+	streamText,
+	tool,
+	type ToolSet,
+} from 'ai';
+import { AgentHarnessError } from './errors.ts';
+import { withSystemPreamble } from './preamble.ts';
+import {
+	DEFAULT_MAX_OUTPUT_TOKENS,
+	type AgentProvider,
+	type AgentProviderContext,
+	type AgentProviderResult,
+	type AgentUsage,
+} from './runtime.ts';
+
+/* Provider kinds, model resolution, and failure classification are owned by
+   @flowdular/sdk/ai-provider so the platform runtime and the sandbox coding agent
+   share one definition. This module keeps the agent-runtime contract. */
+export type VercelAiProviderKind = AiProviderKind;
+export type { ProviderReadinessResult };
+export { AiProviderError as VercelAiProviderError };
+
+export interface VercelAiProviderConfiguration extends AiProviderConfiguration {
+	readonly id: string;
+}
+
+function providerId(value: string): string {
+	const normalized = value.trim();
+	if (!normalized || normalized.length > 128) {
+		throw new AiProviderError(
+			'INVALID_PROVIDER_CONFIGURATION',
+			'provider id is invalid.',
+		);
+	}
+	return normalized;
+}
+
+function finishReason(value: string): AgentProviderResult['finishReason'] {
+	if (value === 'length') return 'length';
+	if (value === 'tool-calls') return 'tool-limit';
+	return 'stop';
+}
+
+function toolsFor(context: AgentProviderContext): {
+	readonly tools: ToolSet;
+	readonly ids: ReadonlyMap<string, string>;
+} {
+	const tools: ToolSet = {};
+	const ids = new Map<string, string>();
+	for (const available of context.availableTools) {
+		const name = available.id.replace(/[^a-zA-Z0-9_]/g, '_');
+		if (ids.has(name)) {
+			throw new AiProviderError(
+				'TOOL_NAME_COLLISION',
+				'Two granted tools resolve to the same provider-safe name.',
+			);
+		}
+		ids.set(name, available.id);
+		tools[name] = tool({
+			description: available.description,
+			inputSchema: jsonSchema(available.inputSchema),
+			execute: (input, options) =>
+				context.invokeTool(available.id, input, {
+					providerCallId: options.toolCallId,
+				}),
+		});
+	}
+	return { tools, ids };
+}
+
+export function createVercelAiSdkProvider(
+	configuration: VercelAiProviderConfiguration,
+): AgentProvider {
+	const id = providerId(configuration.id);
+	return {
+		id,
+		capabilities: { structuredOutput: true },
+		async execute(context): Promise<AgentProviderResult> {
+			try {
+				const { tools, ids } = toolsFor(context);
+				const outputContract = context.request.outputContract ?? {
+					kind: 'text' as const,
+				};
+				const outputSpec =
+					outputContract.kind === 'json-schema'
+						? Output.object({
+								schema: jsonSchema(outputContract.schema),
+								name: outputContract.name,
+							})
+						: Output.text();
+				const result = streamText({
+					model: resolveLanguageModel(configuration),
+					instructions: withSystemPreamble(
+						context.request,
+						context.availableTools.map((available) => available.id),
+					),
+					prompt: context.request.input,
+					...temperatureSetting(
+						configuration,
+						context.request.definition.temperature,
+					),
+					maxOutputTokens:
+						context.request.definition.maxOutputTokens ??
+						DEFAULT_MAX_OUTPUT_TOKENS,
+					maxRetries: 1,
+					abortSignal: context.signal,
+					stopWhen: stepCountIs(context.request.definition.maxSteps),
+					tools,
+					output: outputSpec,
+				});
+				let output = '';
+				let totalUsage: AgentUsage = {
+					inputTokens: 0,
+					outputTokens: 0,
+					totalTokens: 0,
+				};
+				let completedReason: AgentProviderResult['finishReason'] = 'stop';
+				for await (const part of result.fullStream) {
+					if (part.type === 'text-delta') {
+						output += part.text;
+						/* The text block id travels with every delta so a reader can fold
+						   one block into one answer and never merge two of them. */
+						for (const chunk of part.text.match(/.{1,450}/gs) ?? []) {
+							context.emit('provider.output.delta', chunk, {
+								stream: part.id,
+							});
+						}
+					}
+					/* The harness already recorded failures raised by its own tools.
+					   What remains here is the SDK refusing a call before execution,
+					   such as unparseable arguments from the model. */
+					if (
+						part.type === 'tool-error' &&
+						!(part.error instanceof AgentHarnessError)
+					) {
+						context.emit(
+							'tool.failed',
+							`Tool ${ids.get(part.toolName) ?? part.toolName} failed.`,
+							{
+								tool: ids.get(part.toolName) ?? part.toolName,
+								reason: 'PROVIDER_TOOL_ERROR',
+							},
+						);
+					}
+					if (part.type === 'finish') {
+						totalUsage = normalizeUsage(part.totalUsage);
+						completedReason = finishReason(part.finishReason);
+					}
+					if (part.type === 'error') throw part.error;
+				}
+				const structuredOutput =
+					outputContract.kind === 'json-schema'
+						? ((await result.output) as AgentProviderResult['structuredOutput'])
+						: undefined;
+				return {
+					output:
+						outputContract.kind === 'json-schema'
+							? JSON.stringify(structuredOutput)
+							: output.trim() || 'The provider completed without text output.',
+					...(structuredOutput === undefined ? {} : { structuredOutput }),
+					usage: totalUsage,
+					finishReason: completedReason,
+				};
+			} catch (error) {
+				const failure = classifyProviderFailure(error);
+				/* The run keeps the stable code. The provider's own reason is
+				   redacted of credentials and stays in the server log, which is the
+				   only place a failed run can be diagnosed. */
+				console.error(
+					`[harness] provider ${id} failed on ${configuration.model}: ${failure.code}`,
+					failure.detail ?? '',
+				);
+				throw failure;
+			}
+		},
+	};
+}
+
+export function probeVercelAiSdkProvider(
+	configuration: VercelAiProviderConfiguration,
+	timeoutMs = 10_000,
+): Promise<ProviderReadinessResult> {
+	return probeLanguageModel(configuration, timeoutMs);
+}

package/packages/kernel/package.json

@@ -0,0 +1,44 @@
+{
+	"name": "@flowdular/kernel",
+	"version": "0.1.0",
+	"type": "module",
+	"exports": {
+		".": "./src/index.ts",
+		"./legacy-local-state": "./src/legacy-local-state.ts",
+		"./runtime-config": "./src/runtime-config.ts"
+	},
+	"scripts": {
+		"typecheck": "tsc --noEmit -p tsconfig.json",
+		"test": "vitest run"
+	},
+	"dependencies": {
+		"@flowdular/contracts": "workspace:*",
+		"semver": "7.7.4",
+		"@types/semver": "7.7.1"
+	},
+	"devDependencies": {
+		"@types/node": "24.13.3",
+		"typescript": "5.9.3",
+		"vitest": "4.1.10"
+	},
+	"license": "MIT",
+	"repository": {
+		"type": "git",
+		"url": "git+https://github.com/Flowdular/flowdular.git",
+		"directory": "packages/kernel"
+	},
+	"files": [
+		"src",
+		"schemas",
+		"dist",
+		"bin",
+		"public",
+		"module.json",
+		"migrations",
+		"translations",
+		"spec",
+		"README.md",
+		"LICENSE"
+	],
+	"private": true
+}

package/packages/kernel/src/acl.ts

@@ -0,0 +1,20 @@
+export interface Principal {
+	readonly id: string;
+	readonly permissions: ReadonlySet<string>;
+}
+
+export interface AccessDecision {
+	readonly allowed: boolean;
+	readonly reason: 'granted' | 'anonymous' | 'missing-permission';
+}
+
+export function authorize(
+	principal: Principal | null,
+	permission: string,
+): AccessDecision {
+	if (!principal) return { allowed: false, reason: 'anonymous' };
+	if (!principal.permissions.has(permission)) {
+		return { allowed: false, reason: 'missing-permission' };
+	}
+	return { allowed: true, reason: 'granted' };
+}