@fabricorg/platform-host 8.5.0 → 8.6.0

package/CHANGELOG.md

@@ -1,5 +1,15 @@
 # @fabricorg/platform-host
 
+## 8.6.0
+
+### Minor Changes
+
+- 019ba30: Add the agent proposal submission envelope and Host HITL evaluator context with durable invocation identity. Snapshot proposals before awaiting authorization; validate strict approval evidence and support `redactAgentProposal` beside parameter redaction, after admission where declared. Persist and evaluate the redacted envelope, including on recovery and approval resume.
+
+  Idempotency compares redacted proposals and adds the `agent_proposal` conflict reason, including presence changes and legacy records. Consumers with exhaustive conflict-reason switches must handle the new value.
+
+  Run `ensureSchema()` to apply PostgreSQL migration 13 (`agent_proposal`) before submitting the first proposal. Inserts without proposals omit the new column. Staged and saga children do not inherit their parent's envelope.
+
 ## 8.5.0
 
 ### Minor Changes

package/README.md

@@ -1712,3 +1712,40 @@ This capability lives on `OutboxRequeuePlatformHostStore`, which extends `Outbox
 `MemoryPlatformHostStore` and `PostgresPlatformHostStore` implement it, and a custom outbox store
 without it makes the operation throw. PostgreSQL adds migration 5, the
 `fabric_platform.event_outbox_requeues` table, which `ensureSchema()` creates.
+
+### Agent proposals and Host evaluator context
+
+Agent callers can submit `SubmitActionInput.agentProposal` separately from action parameters:
+`{ confidence, riskTier, agentSessionId, agentRunId, reason, evidence }`. Confidence must be
+finite; risk tier is `low`, `medium`, or `high`. Session/run IDs must contain non-whitespace
+text and fit within 256 UTF-16 code units; reason may be empty and is limited to 4096 code
+units. Evidence uses the approval-decision strict JSON object validation and
+`MAX_APPROVAL_EVIDENCE_BYTES` (16 KiB). Invalid proposals and proposals from other actor
+types reject submission before invocation creation through the existing Error rejection path.
+
+For the submission snapshot, Host reads `agentProposal` once and deeply copies it before
+its first await, including for actions without `admitSubmission`. The sibling
+`redactAgentProposal(actionId, proposal)` hook runs beside `redactActionParameters`: after
+admission for actions declaring `admitSubmission`, otherwise before composition resolution.
+Its result is validated and copied again. A thrown hook or invalid output rejects submission
+without creating an invocation, like a thrown parameter-redaction hook. Applications should
+remove secrets and unnecessary sensitive evidence through this hook before durable storage.
+
+The redacted proposal is stored on `ActionInvocationRecord` and compared canonically on
+idempotent re-submission. Differences, including absence versus presence, add the
+`agent_proposal` conflict reason under the configured `enforce` or `audit-only` mode,
+including legacy records without parameter digests. Exhaustive conflict-reason switches
+must handle this new value.
+
+`hitlEvaluator` receives `HostHitlEvaluatorContext`, extending the portable context with
+`actionInvocationId` and the durable `invocation` read before evaluation. Proposal fields
+supply confidence, risk tier, session ID, and run ID individually, falling back to parameters
+for absent fields. Reason and evidence are available through `invocation.agentProposal`.
+Approval authorization and resumed execution authorization receive that durable proposal too.
+Staged and saga children do not inherit a parent's proposal. Approval lifecycle event payloads
+and Host telemetry do not include the envelope.
+
+Apply PostgreSQL migration 13 (`agent_proposal`) with `ensureSchema()` before the first
+proposal submission. Inserts without proposals omit the new column, following the
+`admitted_at` rollout pattern. Existing migration SQL is unchanged; readers accept legacy
+rows without a proposal. See `src/postgres-store.ts` (`ensureSchema`, `toActionRecord`).

package/dist/index.cjs

@@ -297,6 +297,52 @@ async function appendLifecycleEvent(transaction, factory, invocation, kind) {
 	}, metadata);
 }
 //#endregion
+//#region src/agent-proposal.ts
+/** Validate without invoking getters or retaining caller-owned evidence. */
+function snapshotAgentProposal(value) {
+	const invalid = () => {
+		throw new Error("Invalid agent proposal.");
+	};
+	if (!value || typeof value !== "object" || Array.isArray(value) || util.types.isProxy(value)) return invalid();
+	if (Object.getPrototypeOf(value) !== Object.prototype && Object.getPrototypeOf(value) !== null) return invalid();
+	const allowed = [
+		"confidence",
+		"riskTier",
+		"agentSessionId",
+		"agentRunId",
+		"reason",
+		"evidence"
+	];
+	for (const key of Reflect.ownKeys(value)) {
+		const descriptor = Object.getOwnPropertyDescriptor(value, key);
+		if (typeof key !== "string" || !allowed.includes(key) || !descriptor.enumerable || !Object.hasOwn(descriptor, "value")) return invalid();
+	}
+	if (value.confidence !== void 0 && (typeof value.confidence !== "number" || !Number.isFinite(value.confidence))) return invalid();
+	if (value.riskTier !== void 0 && ![
+		"low",
+		"medium",
+		"high"
+	].includes(value.riskTier)) return invalid();
+	for (const key of [
+		"agentSessionId",
+		"agentRunId",
+		"reason"
+	]) {
+		const field = value[key];
+		if (field !== void 0 && (typeof field !== "string" || field.length > (key === "reason" ? 4096 : 256) || key !== "reason" && field.trim().length === 0)) return invalid();
+	}
+	const evidence = snapshotApprovalDecision({
+		approved: true,
+		approverId: "proposal",
+		approverType: "agent",
+		...value.evidence !== void 0 ? { evidence: value.evidence } : {}
+	}).evidence;
+	return {
+		...value,
+		...evidence !== void 0 ? { evidence } : {}
+	};
+}
+//#endregion
 //#region src/command-identity.ts
 const PARAMETER_DIGEST_ALGORITHM = "fabric-canonical-json-sha256-v1";
 function digestParameters(parameters) {
@@ -1002,7 +1048,11 @@ function snapshotSubmission(input) {
 	const executionReason = scalar("executionReason");
 	const idempotencyKey = scalar("idempotencyKey");
 	const authorizationBindingId = scalar("authorizationBindingId");
+	const proposal = input.agentProposal;
+	if (proposal !== void 0 && actorType !== "agent") throw new Error("Agent proposal requires an agent actor.");
+	const agentProposal = proposal === void 0 ? void 0 : snapshotAgentProposal(proposal);
 	const live = {
+		...agentProposal !== void 0 ? { agentProposal } : {},
 		actionId,
 		tenantId,
 		spaceId,
@@ -1071,6 +1121,7 @@ function privateSubmission(snapshot) {
 	const provenance = provenanceRead ? copyProvenance(provenanceRead) : void 0;
 	const authorizationBinding = bindingRead ? copyBinding(bindingRead) : void 0;
 	return Object.freeze({
+		...snapshot.agentProposal !== void 0 ? { agentProposal: snapshot.agentProposal } : {},
 		actionId: snapshot.actionId,
 		tenantId: snapshot.tenantId,
 		spaceId: snapshot.spaceId,
@@ -1167,6 +1218,7 @@ function parametersCopy(snapshot) {
 */
 function liveSubmissionView(snapshot, input) {
 	const view = {
+		...snapshot.agentProposal !== void 0 ? { agentProposal: snapshotAgentProposal(snapshot.agentProposal) } : {},
 		actionId: snapshot.actionId,
 		tenantId: snapshot.tenantId,
 		spaceId: snapshot.spaceId,
@@ -1208,6 +1260,7 @@ function submissionView(snapshot) {
 	const provenance = fresh(snapshot.provenance);
 	const authorizationBinding = fresh(snapshot.authorizationBinding);
 	return {
+		...snapshot.agentProposal !== void 0 ? { agentProposal: snapshotAgentProposal(snapshot.agentProposal) } : {},
 		actionId: snapshot.actionId,
 		parameters: parametersCopy(snapshot),
 		tenantId: snapshot.tenantId,
@@ -1544,7 +1597,8 @@ function createGovernedActionHost(options) {
 			if (submission.authorizationBinding) validateAuthorizationBinding(submission, parameterDigest, action.execution?.authorityMoment, now());
 			return {
 				durableParameters,
-				parameterDigest
+				parameterDigest,
+				agentProposal: submission.agentProposal === void 0 ? void 0 : snapshotAgentProposal(options.redactAgentProposal ? options.redactAgentProposal(submission.actionId, submission.agentProposal) : submission.agentProposal)
 			};
 		};
 		const early = declaresAdmission ? void 0 : prepare();
@@ -1559,9 +1613,10 @@ function createGovernedActionHost(options) {
 		};
 		(0, _fabricorg_platform.assertGovernanceRuntimeEvidence)(runtimeEvidence);
 		const admission = declaresAdmission ? await admitSubmission(action, submission) : void 0;
-		const { durableParameters, parameterDigest } = early ?? prepare();
+		const { durableParameters, parameterDigest, agentProposal } = early ?? prepare();
 		const invocationInput = {
 			id: actionInvocationId,
+			...agentProposal !== void 0 ? { agentProposal } : {},
 			tenantId: submission.tenantId,
 			spaceId: submission.spaceId,
 			actionId: submission.actionId,
@@ -1615,6 +1670,7 @@ function createGovernedActionHost(options) {
 		});
 		if (durableInvocation.id !== actionInvocationId && submission.idempotencyKey) {
 			const conflict = idempotencyConflict(durableInvocation, {
+				agentProposal,
 				actorId: submission.actorId,
 				authorizationBindingId: submission.authorizationBindingId,
 				actionVersion: action.version,
@@ -2336,21 +2392,24 @@ function createGovernedActionHost(options) {
 			}
 			if (invocation.actorType === "agent" && options.hitlEvaluator) {
 				const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
+				const proposal = invocation.agentProposal;
 				const approvalStore = asApprovalStore(options.store);
 				if (!approvalStore) return hostOperation(() => failExecution(invocation, "failed", "The configured HITL evaluator requires a store with approval persistence support."));
 				let evaluatedApprovalExpiresAt;
 				if (!invocation.hitlRoute) {
 					const decision = await options.hitlEvaluator({
+						actionInvocationId: invocation.id,
+						invocation,
 						actionId: action.actionId,
 						actorId: invocation.actorId,
 						actorType: invocation.actorType,
 						tenantId,
 						spaceId,
 						parameters: hitlParameters,
-						...numberValue(hitlParameters.confidence) !== void 0 ? { confidence: numberValue(hitlParameters.confidence) } : {},
-						...isRiskTier(hitlParameters.riskTier) ? { riskTier: hitlParameters.riskTier } : {},
-						...stringValue(hitlParameters.agentSessionId) ? { agentSessionId: stringValue(hitlParameters.agentSessionId) } : {},
-						...stringValue(hitlParameters.agentRunId) ? { agentRunId: stringValue(hitlParameters.agentRunId) } : {}
+						...(proposal?.confidence ?? numberValue(hitlParameters.confidence)) !== void 0 ? { confidence: proposal?.confidence ?? numberValue(hitlParameters.confidence) } : {},
+						...isRiskTier(proposal?.riskTier ?? hitlParameters.riskTier) ? { riskTier: proposal?.riskTier ?? hitlParameters.riskTier } : {},
+						...proposal?.agentSessionId ?? stringValue(hitlParameters.agentSessionId) ? { agentSessionId: proposal?.agentSessionId ?? stringValue(hitlParameters.agentSessionId) } : {},
+						...proposal?.agentRunId ?? stringValue(hitlParameters.agentRunId) ? { agentRunId: proposal?.agentRunId ?? stringValue(hitlParameters.agentRunId) } : {}
 					});
 					if (decision.approvalExpiresAt !== void 0 && !validApprovalDate(decision.approvalExpiresAt)) return hostOperation(() => failExecution(invocation, "failed", "approvalExpiresAt must be a valid Date."));
 					evaluatedApprovalExpiresAt = decision.approvalExpiresAt === void 0 ? void 0 : new Date(decision.approvalExpiresAt);
@@ -4314,6 +4373,7 @@ function validateAuthorizationBinding(input, parameterDigest, authorityMoment, c
 }
 function idempotencyConflict(existing, incoming) {
 	const reasons = [];
+	if ((0, _fabricorg_platform.canonicalJson)(existing.agentProposal ?? null) !== (0, _fabricorg_platform.canonicalJson)(incoming.agentProposal ?? null)) reasons.push("agent_proposal");
 	if ((existing.idempotencyActorId ?? existing.actorId) !== incoming.actorId) reasons.push("actor");
 	if ((existing.idempotencyAuthorizationBindingId ?? existing.authorizationBindingId) !== incoming.authorizationBindingId) reasons.push("authority_binding");
 	if (existing.actionVersion !== incoming.actionVersion) reasons.push("action_version");
@@ -5619,6 +5679,11 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 					ON fabric_platform.action_invocations (approval_expires_at, id)
 					WHERE status='waiting_for_approval' AND approval_expires_at IS NOT NULL;
 			`
+			},
+			{
+				version: 13,
+				name: "agent_proposal",
+				sql: `ALTER TABLE fabric_platform.action_invocations ADD COLUMN IF NOT EXISTS agent_proposal jsonb;`
 			}
 		]);
 	}
@@ -5630,6 +5695,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 		const admitted = input.admittedAt !== void 0;
 		const admittedColumn = admitted ? "admitted_at," : "";
 		const admittedValue = admitted ? "$25," : "";
+		const proposalColumn = input.agentProposal !== void 0 ? "agent_proposal," : "";
+		const proposalValue = input.agentProposal !== void 0 ? `$${admitted ? 26 : 25}::jsonb,` : "";
 		let result;
 		try {
 			result = await this.sql.query(`INSERT INTO fabric_platform.action_invocations
@@ -5637,8 +5704,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				  parameters,result,correlation_id,causation_id,idempotency_key,
 				  parameter_digest,parameter_digest_algorithm,idempotency_actor_id,
 				  idempotency_authorization_binding_id,invocation_provenance,authorization_binding,execution_reason,
-				  authorization_binding_id,error,runtime_evidence,${admittedColumn}created_at,updated_at)
-				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15,$16,$17,$18::jsonb,$19::jsonb,$20,$21,$22,$23::jsonb,${admittedValue}$24,$24)
+				  authorization_binding_id,error,runtime_evidence,${admittedColumn}${proposalColumn}created_at,updated_at)
+				 VALUES ($1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15,$16,$17,$18::jsonb,$19::jsonb,$20,$21,$22,$23::jsonb,${admittedValue}${proposalValue}$24,$24)
 				 ON CONFLICT (tenant_id,space_id,action_id,idempotency_key)
 				 WHERE idempotency_key IS NOT NULL DO UPDATE SET id=fabric_platform.action_invocations.id
 				 RETURNING *`, [
@@ -5666,9 +5733,11 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				input.error ?? null,
 				input.runtimeEvidence ? JSON.stringify(input.runtimeEvidence) : null,
 				now,
-				...admitted ? [input.admittedAt] : []
+				...admitted ? [input.admittedAt] : [],
+				...input.agentProposal !== void 0 ? [JSON.stringify(input.agentProposal)] : []
 			]);
 		} catch (error) {
+			if (input.agentProposal !== void 0 && error?.code === "42703") throw new Error("Agent proposals require PostgreSQL migration 13 (agent_proposal); run ensureSchema().", { cause: error });
 			if (admitted && error?.code === "42703") throw new Error("An admitted invocation needs the action_invocations.admitted_at column; run ensureSchema() to apply PostgreSQL migration 6 (invocation_admission) before submitting actions that declare admitSubmission.", { cause: error });
 			throw error;
 		}
@@ -5680,6 +5749,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 		const admitted = invocation.admittedAt !== void 0;
 		const admittedColumn = admitted ? ",admitted_at" : "";
 		const admittedValue = admitted ? ",$30" : "";
+		const proposalColumn = invocation.agentProposal !== void 0 ? ",agent_proposal" : "";
+		const proposalValue = invocation.agentProposal !== void 0 ? `,$${admitted ? 31 : 30}::jsonb` : "";
 		const values = [
 			invocation.id,
 			invocation.tenantId,
@@ -5710,7 +5781,8 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 			input.workerId,
 			input.leaseToken,
 			current,
-			...admitted ? [invocation.admittedAt] : []
+			...admitted ? [invocation.admittedAt] : [],
+			...invocation.agentProposal !== void 0 ? [JSON.stringify(invocation.agentProposal)] : []
 		];
 		let result;
 		try {
@@ -5728,15 +5800,16 @@ var PostgresPlatformHostStore = class PostgresPlatformHostStore {
 				  parameters,result,correlation_id,causation_id,idempotency_key,parameter_digest,
 				  parameter_digest_algorithm,idempotency_actor_id,idempotency_authorization_binding_id,
 				  invocation_provenance,authorization_binding,execution_reason,authorization_binding_id,error,
-				  runtime_evidence,staged_parent_invocation_id,staged_stage_key${admittedColumn},created_at,updated_at)
+				  runtime_evidence,staged_parent_invocation_id,staged_stage_key${admittedColumn}${proposalColumn},created_at,updated_at)
 				 SELECT $1,$2,$3,$4,$5,$6,$7,$8,$9::jsonb,$10::jsonb,$11,$12,$13,$14,$15,$16,$17,
-				        $18::jsonb,$19::jsonb,$20,$21,$22,$23::jsonb,$24,$25${admittedValue},$29,$29
+				        $18::jsonb,$19::jsonb,$20,$21,$22,$23::jsonb,$24,$25${admittedValue}${proposalValue},$29,$29
 				 FROM fence
 				 ON CONFLICT (tenant_id,space_id,staged_parent_invocation_id,staged_stage_key)
 				 WHERE staged_parent_invocation_id IS NOT NULL AND staged_stage_key IS NOT NULL
 				 DO UPDATE SET id=fabric_platform.action_invocations.id
 				 RETURNING *`, values);
 		} catch (error) {
+			if (invocation.agentProposal !== void 0 && error?.code === "42703") throw new Error("Agent proposals require PostgreSQL migration 13 (agent_proposal); run ensureSchema().", { cause: error });
 			if (error?.code === "42703" || error?.code === "42P01") throw new Error("A staged child needs PostgreSQL migration 11 (staged_descendant_invocations); run ensureSchema() before dispatching staged invocations.", { cause: error });
 			throw error;
 		}
@@ -6856,6 +6929,7 @@ function toActionRecord(row) {
 		...row.mutation_footprint ? { mutationFootprint: row.mutation_footprint } : {},
 		...row.execution_principal ? { executionPrincipal: row.execution_principal } : {},
 		...row.runtime_evidence ? { runtimeEvidence: row.runtime_evidence } : {},
+		...row.agent_proposal != null ? { agentProposal: row.agent_proposal } : {},
 		...row.admitted_at ? { admittedAt: new Date(row.admitted_at) } : {},
 		...row.error ? { error: String(row.error) } : {},
 		createdAt: new Date(row.created_at),