@flowdular/sdk 0.2.4 → 0.3.1

package/packages/harness/src/runtime.ts

@@ -1,6 +1,16 @@
 import { createHash } from 'node:crypto';
 import { AgentHarnessError } from './errors.ts';
-import { normalizeActor, type Actor, type UserActor } from '@flowdular/sdk/kernel';
+import {
+	APPROVAL_GRANT_MAX_TOKEN_LENGTH,
+	approvalGrantKeyringFromEnvironment,
+	approvalInputDigest,
+	normalizeActor,
+	verifyApprovalGrant,
+	type Actor,
+	type ApprovalGrantKeyring,
+	type ApprovalGrantReason,
+	type UserActor,
+} from '@flowdular/sdk/kernel';
 import {
 	boundToolOutput,
 	toolTimeoutMs,
@@ -49,10 +59,16 @@ export interface AgentExecutionRequest {
 	readonly definition: AgentExecutionDefinition;
 	readonly permissionSnapshot: readonly string[];
 	readonly toolGrants: readonly string[];
+	/* Signed approval grants (`issueApprovalGrant`) for the external or
+	   destructive tools this run may call, each bound to one tool id and one
+	   input digest. Absent means no such tool is offered. */
+	readonly grants?: readonly string[];
 	/* Absent keeps the v1 text behavior. */
 	readonly outputContract?: AgentOutputContract;
 }
 
+export const MAX_APPROVAL_GRANTS = 16;
+
 export type JsonPrimitive = string | number | boolean | null;
 export type JsonValue =
 	| JsonPrimitive
@@ -106,6 +122,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 +137,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 +169,13 @@ export interface AgentTool {
 	readonly contractVersion?: number;
 	readonly outputSchema?: Readonly<Record<string, unknown>>;
 	readonly risk?: 'read' | 'workspace-write' | 'external' | 'destructive';
+	/* A CLI capability the runner admits in development and test only. The
+	   harness reads FD_ENV or NODE_ENV the way the runner does and refuses it
+	   elsewhere, grant or not. */
+	readonly localOnly?: boolean;
+	/* 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
@@ -254,6 +305,23 @@ function assertExecutionRequest(request: AgentExecutionRequest): void {
 		);
 	}
 	boundedText(request.input, 'input', 1, 100_000);
+	if (request.grants !== undefined) {
+		if (
+			!Array.isArray(request.grants) ||
+			request.grants.length > MAX_APPROVAL_GRANTS ||
+			request.grants.some(
+				(grant) =>
+					typeof grant !== 'string' ||
+					grant.length < 1 ||
+					grant.length > APPROVAL_GRANT_MAX_TOKEN_LENGTH,
+			)
+		) {
+			throw new AgentHarnessError(
+				'INVALID_INPUT',
+				`grants must be at most ${MAX_APPROVAL_GRANTS} tokens of at most ${APPROVAL_GRANT_MAX_TOKEN_LENGTH} characters.`,
+			);
+		}
+	}
 	boundedText(request.definition.name, 'definition.name', 2, 120);
 	boundedText(request.definition.instructions, 'instructions', 8, 40_000);
 	providerReference(request.definition.provider);
@@ -355,15 +423,158 @@ function toolFailure(error: unknown): { code: string; message: string } {
 	return { code: 'TOOL_EXECUTION_FAILED', message };
 }
 
+/**
+ * `external` is the ceiling no unattended caller crosses on its own: the CLI
+ * runner, `defineCliAgentTool` for a destructive capability, and a hand-built
+ * tool object here all run only under a signed approval grant naming the tool
+ * and the input, before the model is ever told the tool exists.
+ */
+function requiresApprovalGrant(tool: AgentTool): boolean {
+	return (
+		tool.risk === 'external' ||
+		(tool.risk === 'destructive' && tool.transport === 'cli')
+	);
+}
+
+type GrantRefusal = ApprovalGrantReason | 'APPROVAL_GRANT_CONSUMED';
+
+interface RunApprovalGrants {
+	/** Tokens that verify for this tenant, by the tool id they name. */
+	readonly byTool: ReadonlyMap<string, readonly string[]>;
+	/** Why the first refused token was refused, per tool, for the denial event. */
+	readonly refusals: ReadonlyMap<string, GrantRefusal>;
+}
+
+/* The same reading the CLI runner applies to a localOnly capability. */
+function localOnlyRefused(tool: AgentTool): boolean {
+	const environment =
+		process.env.FD_ENV ?? process.env.NODE_ENV ?? 'development';
+	return (
+		tool.localOnly === true &&
+		environment !== 'development' &&
+		environment !== 'test'
+	);
+}
+
+/* Signature, key and tenant are settled once per run; the input digest is
+   settled per call, because the model chooses the input. A token that is
+   invalid or expired is so for every tool, and is recorded against each. */
+function runApprovalGrants(
+	keyring: ApprovalGrantKeyring | undefined,
+	request: AgentExecutionRequest,
+	tools: ReadonlyMap<string, AgentTool>,
+): RunApprovalGrants {
+	const byTool = new Map<string, string[]>();
+	const refusals = new Map<string, GrantRefusal>();
+	if (!keyring) return { byTool, refusals };
+	const gated = [...tools.values()].filter(requiresApprovalGrant);
+	for (const token of request.grants ?? []) {
+		let reason: ApprovalGrantReason = 'APPROVAL_GRANT_MISMATCH';
+		let matched = false;
+		for (const tool of gated) {
+			const verified = verifyApprovalGrant(keyring, token, {
+				tenantId: request.tenantId,
+				capabilityId: tool.id,
+			});
+			if (verified.ok) {
+				byTool.set(tool.id, [...(byTool.get(tool.id) ?? []), token]);
+				matched = true;
+				break;
+			}
+			reason = verified.reason;
+			if (reason !== 'APPROVAL_GRANT_MISMATCH') break;
+		}
+		/* A token that verifies for no tool is refused for every gated tool: it
+		   was signed for another tenant or capability, or not by this platform. */
+		if (!matched) {
+			for (const other of gated) {
+				if (!refusals.has(other.id)) refusals.set(other.id, reason);
+			}
+		}
+	}
+	return { byTool, refusals };
+}
+
+/* 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;
+	readonly #approvalGrants: ApprovalGrantKeyring | undefined;
 
 	constructor(options: {
 		readonly providers: readonly AgentProvider[];
 		readonly tools?: readonly AgentTool[];
 		readonly authorizeToolAccess?: AgentToolAccessAuthorizer;
+		readonly tracer?: AgentTracer;
+		/* Verifies the approval grants a run carries. Absent reads
+		   FD_APPROVAL_GRANT_KEY; without either, no external tool ever runs. */
+		readonly approvalGrants?: ApprovalGrantKeyring;
 	}) {
 		const providers = new Map<string, AgentProvider>();
 		for (const provider of options.providers) {
@@ -385,6 +596,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 +608,9 @@ 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;
+		this.#approvalGrants =
+			options.approvalGrants ?? approvalGrantKeyringFromEnvironment();
 	}
 
 	providers(): readonly string[] {
@@ -512,8 +729,17 @@ export class AgentHarness {
 			);
 		};
 		const initialPermissions = await livePermissions();
+		const grantKeyring = this.#approvalGrants;
+		const approvals = runApprovalGrants(grantKeyring, request, this.#tools);
+		const admissible = (tool: AgentTool): boolean =>
+			!localOnlyRefused(tool) &&
+			(!requiresApprovalGrant(tool) || approvals.byTool.has(tool.id));
+		/* One call per grant: a request approved once admits one invocation of
+		   the tool it names, however many times the model asks. */
+		const consumedGrants = new Set<string>();
 		const availableTools = [...this.#tools.values()]
 			.filter((tool) => snapshotGrants.has(tool.id))
+			.filter(admissible)
 			.filter((tool) =>
 				tool.requiredPermissions.every((permission) =>
 					initialPermissions.has(permission),
@@ -547,6 +773,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 +783,28 @@ export class AgentHarness {
 		): Promise<unknown> => {
 			const ordinal = ++toolCallOrdinal;
 			const tool = this.#tools.get(id);
+			if (tool && localOnlyRefused(tool)) {
+				emit('tool.denied', `Tool ${id} was denied.`, {
+					tool: id,
+					reason: 'TOOL_LOCAL_ONLY',
+				});
+				throw new AgentHarnessError(
+					'TOOL_LOCAL_ONLY',
+					`Tool ${id} is a local-only capability and cannot run in this environment.`,
+				);
+			}
+			if (tool && !admissible(tool)) {
+				const refusal = approvals.refusals.get(id);
+				emit('tool.denied', `Tool ${id} was denied.`, {
+					tool: id,
+					reason: 'TOOL_RISK_REFUSED',
+					...(refusal ? { grant: refusal } : {}),
+				});
+				throw new AgentHarnessError(
+					'TOOL_RISK_REFUSED',
+					`Tool ${id} declares ${tool.risk} risk and runs only under an approval grant.`,
+				);
+			}
 			if (!tool || !grantedIds.has(id)) {
 				emit('tool.denied', `Tool ${id} was denied.`, {
 					tool: id,
@@ -623,6 +873,81 @@ export class AgentHarness {
 				});
 				throw error;
 			}
+			if (requiresApprovalGrant(tool)) {
+				const expected = {
+					tenantId: request.tenantId,
+					capabilityId: id,
+					inputDigest: approvalInputDigest(input),
+				};
+				let refusal: GrantRefusal = 'APPROVAL_GRANT_MISMATCH';
+				const admitted =
+					grantKeyring !== undefined &&
+					(approvals.byTool.get(id) ?? []).some((token) => {
+						const verified = verifyApprovalGrant(grantKeyring, token, expected);
+						if (!verified.ok) {
+							refusal = verified.reason;
+							return false;
+						}
+						if (consumedGrants.has(verified.claims.requestId)) {
+							refusal = 'APPROVAL_GRANT_CONSUMED';
+							return false;
+						}
+						consumedGrants.add(verified.claims.requestId);
+						return true;
+					});
+				if (!admitted) {
+					emit('tool.denied', `Tool ${id} was denied.`, {
+						tool: id,
+						reason: 'TOOL_RISK_REFUSED',
+						grant: refusal,
+					});
+					throw new AgentHarnessError(
+						'TOOL_RISK_REFUSED',
+						`Tool ${id} has no approval grant for this input.`,
+					);
+				}
+			}
+			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 +983,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 +1036,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 +1096,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 +1120,7 @@ export class AgentHarness {
 							additionalProperties: false,
 						},
 					})),
-					invokeTool,
+					invokeTool: tracedInvokeTool,
 					emit,
 				}),
 				timeout,
@@ -779,6 +1147,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 +1157,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';
@@ -23,6 +30,7 @@ export interface CliAgentToolDefinition extends AgentToolBase {
 	readonly capability: {
 		readonly id: string;
 		readonly risk: CapabilityRisk;
+		readonly localOnly?: boolean;
 	};
 }
 
@@ -33,6 +41,8 @@ function dottedIdentifier(value: string, field: string): string {
 	return value;
 }
 
+/* An external tool builds as any other; the harness offers and runs it only
+   under an approval grant naming the tool and the input. */
 export function defineApiAgentTool(
 	definition: ApiAgentToolDefinition,
 ): AgentTool {
@@ -49,6 +59,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 }),
@@ -65,17 +78,11 @@ export function defineApiAgentTool(
 	});
 }
 
+/* An external or destructive capability builds as any other; the harness runs
+   the tool only under an approval grant naming the tool and the input. */
 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,
@@ -89,6 +96,10 @@ export function defineCliAgentTool(
 			? {}
 			: { outputSchema: definition.outputSchema }),
 		...(definition.risk === undefined ? {} : { risk: definition.risk }),
+		...(definition.capability.localOnly === true ? { localOnly: true } : {}),
+		...(definition.consent === undefined
+			? {}
+			: { consent: definition.consent }),
 		...(definition.idempotency === undefined
 			? {}
 			: { idempotency: definition.idempotency }),