@fabricorg/platform-host 0.3.1 → 0.4.1

package/dist/index.js

@@ -10,8 +10,10 @@ function createGovernedActionHost(options) {
   for (const adapter of options.adapters ?? []) adapters.register(adapter);
   const now = options.now ?? (() => /* @__PURE__ */ new Date());
   const extractEvents = options.extractEvents ?? DEFAULT_EXTRACT_EVENTS;
+  const actionResolver = options.resolveAction ?? resolveAction;
+  const eventResultFields = options.eventResultFields ?? ["_events"];
   async function submitAction(input) {
-    const action = resolveAction(input.actionId);
+    const action = actionResolver(input.actionId);
     if (!action) throw new Error(`Unknown action: ${input.actionId}`);
     const authorizationInput = toAuthorizationInput(action, input);
     if (!await options.authorization.checkEntitlement(authorizationInput)) {
@@ -45,7 +47,9 @@ function createGovernedActionHost(options) {
         status: durableInvocation.status,
         workflowId: durableWorkflowId,
         result: durableInvocation.result,
-        ...durableInvocation.error ? { error: durableInvocation.error } : {}
+        ...durableInvocation.error ? { error: durableInvocation.error } : {},
+        ...durableInvocation.hitlRoute ? { hitlRoute: durableInvocation.hitlRoute } : {},
+        ...durableInvocation.hitlRiskTier ? { hitlRiskTier: durableInvocation.hitlRiskTier } : {}
       };
     }
     if (options.dispatcher) {
@@ -60,7 +64,9 @@ function createGovernedActionHost(options) {
           actionInvocationId: durableInvocation.id,
           status: durableInvocation.status,
           workflowId: dispatched.workflowId,
-          ...dispatched.runId ? { runId: dispatched.runId } : {}
+          ...dispatched.runId ? { runId: dispatched.runId } : {},
+          ...durableInvocation.hitlRoute ? { hitlRoute: durableInvocation.hitlRoute } : {},
+          ...durableInvocation.hitlRiskTier ? { hitlRiskTier: durableInvocation.hitlRiskTier } : {}
         };
       } catch (error) {
         const message = errorMessage(error);
@@ -80,22 +86,26 @@ function createGovernedActionHost(options) {
     );
     return { ...executed, workflowId: durableWorkflowId };
   }
-  async function executeInvocation(actionInvocationId, tenantId, spaceId) {
-    const invocation = await options.store.getActionInvocation(
+  async function executeInvocation(actionInvocationId, tenantId, spaceId, executionOptions = {}) {
+    const loadedInvocation = await options.store.getActionInvocation(
       actionInvocationId,
       tenantId,
       spaceId
     );
-    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
-    if (isTerminal(invocation.status)) {
+    if (!loadedInvocation) {
+      throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    }
+    let invocation = loadedInvocation;
+    if (isTerminal(invocation.status) || invocation.status === "waiting_for_approval") {
+      return actionResult(invocation);
+    }
+    if (invocation.status === "running" && invocation.leaseOwner && executionOptions.leaseOwner !== invocation.leaseOwner) {
       return {
-        actionInvocationId,
-        status: invocation.status,
-        result: invocation.result,
-        ...invocation.error ? { error: invocation.error } : {}
+        ...actionResult(invocation),
+        error: `Invocation is leased by ${invocation.leaseOwner}`
       };
     }
-    const action = resolveAction(invocation.actionId);
+    const action = actionResolver(invocation.actionId);
     if (!action) {
       return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
     }
@@ -106,15 +116,68 @@ function createGovernedActionHost(options) {
         `Interrupted action ${invocation.actionId} is not declared idempotent; manual reconciliation is required.`
       );
     }
-    await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
-      status: "running"
-    });
+    if (invocation.status !== "running") {
+      await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
+        status: "running"
+      });
+    }
     try {
       const parsed = action.schema.safeParse(invocation.parameters);
       if (!parsed.success) {
         const message = parsed.error.issues.map((issue) => `${issue.path.join(".") || "(root)"}: ${issue.message}`).join("; ");
         return fail(invocation, "validation_failed", message);
       }
+      if (invocation.actorType === "agent" && options.hitlEvaluator) {
+        const hitlParameters = isRecord(parsed.data) ? parsed.data : invocation.parameters;
+        const approvalStore = asApprovalStore(options.store);
+        if (!approvalStore) {
+          return fail(
+            invocation,
+            "failed",
+            "The configured HITL evaluator requires a store with approval persistence support."
+          );
+        }
+        if (!invocation.hitlRoute) {
+          const decision = await options.hitlEvaluator({
+            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) } : {}
+          });
+          invocation = await approvalStore.recordHitlDecision(
+            actionInvocationId,
+            tenantId,
+            spaceId,
+            {
+              ...decision,
+              ...options.hitlPolicyVersion ? { policyVersion: options.hitlPolicyVersion } : {},
+              evaluatedAt: now()
+            }
+          );
+        }
+        if (invocation.hitlRoute === "rejected") {
+          return fail(
+            invocation,
+            "failed",
+            `HITL rejected: ${invocation.hitlReason ?? "no reason provided"}`
+          );
+        }
+        if ((invocation.hitlRoute === "needs-approval" || invocation.hitlRoute === "escalate") && !invocation.approvalDecision?.approved) {
+          await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
+            status: "waiting_for_approval"
+          });
+          return {
+            ...actionResult(invocation),
+            status: "waiting_for_approval"
+          };
+        }
+      }
       const authorizationInput = toAuthorizationInput(action, invocation);
       const definitions = options.resolvePolicies ? await options.resolvePolicies({
         ...authorizationInput,
@@ -130,7 +193,8 @@ function createGovernedActionHost(options) {
         parameters: parsed.data,
         db: options.store.db,
         services: options.services,
-        mode: "execute"
+        mode: "execute",
+        now: now()
       });
       for (const outcome of outcomes) {
         await options.store.appendPolicyEvaluation({
@@ -163,15 +227,17 @@ function createGovernedActionHost(options) {
           entityId
         ) ?? initialState(binding.entityType) : initialState(binding.entityType);
         const targetState = typeof binding.targetState === "function" ? binding.targetState(parsed.data) : binding.targetState;
-        const transition = validateTransition(
-          binding.entityType,
-          currentState,
-          targetState,
-          action.actionId
-        );
-        const replayingAppliedTransition = action.idempotent && currentState === targetState;
-        if (!transition.valid && !replayingAppliedTransition) {
-          return fail(invocation, "failed", transition.error ?? "Invalid state transition");
+        if (targetState !== "") {
+          const transition = validateTransition(
+            binding.entityType,
+            currentState,
+            targetState,
+            action.actionId
+          );
+          const replayingAppliedTransition = action.idempotent && currentState === targetState;
+          if (!transition.valid && !replayingAppliedTransition) {
+            return fail(invocation, "failed", transition.error ?? "Invalid state transition");
+          }
         }
       }
       let data;
@@ -200,7 +266,7 @@ function createGovernedActionHost(options) {
         domainEvents = extractEvents(data);
         if (action.eventPhase !== "after_adapters") {
           for (const [index, event] of domainEvents.entries()) {
-            await appendEvent(invocation, event, `domain:${index}`);
+            await appendEvent(invocation, event, `domain:${index}`, action.version);
           }
         }
       } catch (error) {
@@ -319,27 +385,96 @@ function createGovernedActionHost(options) {
       }
       if (action.eventPhase === "after_adapters") {
         for (const [index, event] of domainEvents.entries()) {
-          await appendEvent(invocation, event, `domain:${index}`);
+          await appendEvent(invocation, event, `domain:${index}`, action.version);
         }
       }
-      const result = withoutPrivateHostFields(data);
+      const result = withoutPrivateHostFields(data, eventResultFields);
       await options.store.updateActionInvocation(actionInvocationId, tenantId, spaceId, {
         status: "completed",
         result
       });
-      return { actionInvocationId, status: "completed", result };
+      return {
+        actionInvocationId,
+        status: "completed",
+        result,
+        ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+        ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+      };
     } catch (error) {
       return fail(invocation, "failed", errorMessage(error));
     }
   }
-  async function appendEvent(invocation, event, deduplicationKey) {
+  async function resumeApprovedInvocation(actionInvocationId, tenantId, spaceId, decision) {
+    if (!decision.approverId.trim()) throw new Error("approverId is required");
+    const invocation = await options.store.getActionInvocation(
+      actionInvocationId,
+      tenantId,
+      spaceId
+    );
+    if (!invocation) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    if (isTerminal(invocation.status)) return actionResult(invocation);
+    if (invocation.status !== "waiting_for_approval") {
+      return {
+        ...actionResult(invocation),
+        error: `Invocation is not waiting for approval (status: ${invocation.status})`
+      };
+    }
+    const action = actionResolver(invocation.actionId);
+    if (!action) return fail(invocation, "failed", `Unknown action: ${invocation.actionId}`);
+    const approvalAuthorizationInput = toAuthorizationInput(action, {
+      tenantId,
+      spaceId,
+      actorId: decision.approverId,
+      actorType: decision.approverType
+    });
+    const entitled = await options.authorization.checkEntitlement(
+      approvalAuthorizationInput
+    );
+    const authorized = options.authorization.authorizeApproval ? await options.authorization.authorizeApproval({
+      ...approvalAuthorizationInput,
+      decision
+    }) : await options.authorization.authorize(approvalAuthorizationInput);
+    if (!entitled || !authorized) {
+      return {
+        ...actionResult(invocation),
+        error: `Actor ${decision.approverId} is not authorized to decide this approval`
+      };
+    }
+    const approvalStore = asApprovalStore(options.store);
+    if (!approvalStore) {
+      return {
+        ...actionResult(invocation),
+        error: "Approval resume requires a store with approval persistence support."
+      };
+    }
+    const transitionStartedAt = now();
+    const decidedAt = decision.decidedAt ?? transitionStartedAt;
+    const leaseOwner = `approval-resume-${createFabricId("lease")}`;
+    const transition = await approvalStore.beginApprovalDecision({
+      actionInvocationId,
+      tenantId,
+      spaceId,
+      decision: { ...decision, decidedAt },
+      leaseOwner,
+      leaseDurationMs: options.approvalResumeLeaseDurationMs ?? 5 * 6e4,
+      now: transitionStartedAt
+    });
+    const transitioned = transition.invocation ?? await options.store.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!transition.applied || !transitioned) {
+      if (!transitioned) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+      return actionResult(transitioned);
+    }
+    if (!decision.approved) return actionResult(transitioned);
+    return executeInvocation(actionInvocationId, tenantId, spaceId, { leaseOwner });
+  }
+  async function appendEvent(invocation, event, deduplicationKey, defaultEventSchemaVersion = 1) {
     const timestamp = now();
     const envelope = {
       id: lifecycleId("evt", invocation.id, deduplicationKey),
       tenantId: invocation.tenantId,
       spaceId: invocation.spaceId,
       eventType: event.eventType,
-      eventSchemaVersion: event.eventSchemaVersion ?? 1,
+      eventSchemaVersion: event.eventSchemaVersion ?? defaultEventSchemaVersion,
       subjectType: event.subjectType,
       subjectId: event.subjectId,
       actorId: invocation.actorId,
@@ -364,9 +499,38 @@ function createGovernedActionHost(options) {
       invocation.spaceId,
       { status, error }
     );
-    return { actionInvocationId: invocation.id, status, error };
+    return {
+      actionInvocationId: invocation.id,
+      status,
+      error,
+      ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+      ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+    };
   }
-  return { submitAction, executeInvocation };
+  return { submitAction, executeInvocation, resumeApprovedInvocation };
+}
+function actionResult(invocation) {
+  return {
+    actionInvocationId: invocation.id,
+    status: invocation.status,
+    result: invocation.result,
+    ...invocation.error ? { error: invocation.error } : {},
+    ...invocation.hitlRoute ? { hitlRoute: invocation.hitlRoute } : {},
+    ...invocation.hitlRiskTier ? { hitlRiskTier: invocation.hitlRiskTier } : {}
+  };
+}
+function asApprovalStore(store) {
+  const candidate = store;
+  return typeof candidate.recordHitlDecision === "function" && typeof candidate.beginApprovalDecision === "function" ? store : void 0;
+}
+function numberValue(value) {
+  return typeof value === "number" && Number.isFinite(value) ? value : void 0;
+}
+function stringValue(value) {
+  return typeof value === "string" && value.length > 0 ? value : void 0;
+}
+function isRiskTier(value) {
+  return value === "low" || value === "medium" || value === "high";
 }
 function toAuthorizationInput(action, input) {
   return {
@@ -395,9 +559,10 @@ function initialState(entityType) {
 function isTerminal(status) {
   return ["completed", "failed", "blocked_by_policy", "validation_failed"].includes(status);
 }
-function withoutPrivateHostFields(data) {
-  const { _events: _ignored, ...result } = data;
-  return result;
+function withoutPrivateHostFields(data, eventResultFields) {
+  return Object.fromEntries(
+    Object.entries(data).filter(([key]) => !eventResultFields.includes(key))
+  );
 }
 function errorMessage(error) {
   return error instanceof Error ? error.message : String(error);
@@ -444,6 +609,45 @@ var MemoryPlatformHostStore = class {
     const record = await this.getActionInvocation(id, tenantId, spaceId);
     if (!record) throw new Error(`ActionInvocation not found: ${id}`);
     Object.assign(record, patch, { updatedAt: /* @__PURE__ */ new Date() });
+    if (patch.status === "waiting_for_approval" || patch.status === "completed" || patch.status === "failed" || patch.status === "blocked_by_policy" || patch.status === "validation_failed") {
+      delete record.leaseOwner;
+      delete record.leaseExpiresAt;
+    }
+  }
+  async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
+    const record = await this.getActionInvocation(actionInvocationId, tenantId, spaceId);
+    if (!record) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    record.hitlRoute = decision.route;
+    record.hitlRiskTier = decision.riskTier;
+    record.hitlReason = decision.reason;
+    if (decision.policyVersion) record.hitlPolicyVersion = decision.policyVersion;
+    record.updatedAt = decision.evaluatedAt;
+    return record;
+  }
+  async beginApprovalDecision(input) {
+    const record = await this.getActionInvocation(
+      input.actionInvocationId,
+      input.tenantId,
+      input.spaceId
+    );
+    if (!record || record.status !== "waiting_for_approval") {
+      return { applied: false, ...record ? { invocation: record } : {} };
+    }
+    record.approvalDecision = input.decision;
+    record.updatedAt = input.now;
+    if (!input.decision.approved) {
+      record.status = "failed";
+      record.error = `Approval rejected: ${input.decision.reason ?? "no reason provided"}`;
+      delete record.leaseOwner;
+      delete record.leaseExpiresAt;
+      return { applied: true, invocation: record };
+    }
+    record.status = "running";
+    record.error = void 0;
+    record.leaseOwner = input.leaseOwner;
+    record.leaseExpiresAt = new Date(input.now.getTime() + input.leaseDurationMs);
+    record.attemptCount = Math.max(record.attemptCount, 1);
+    return { applied: true, invocation: record };
   }
   async appendPolicyEvaluation(record) {
     if (this.policyEvaluations.some((candidate) => candidate.id === record.id)) return;
@@ -521,14 +725,20 @@ var PostgresPlatformHostStore = class {
 				parameters jsonb NOT NULL, result jsonb NOT NULL DEFAULT '{}'::jsonb,
 				correlation_id text NOT NULL, causation_id text, idempotency_key text, error text,
 				attempt_count integer NOT NULL DEFAULT 0, lease_owner text,
-				lease_expires_at timestamptz,
+				lease_expires_at timestamptz, hitl_route text, hitl_risk_tier text,
+				hitl_reason text, hitl_policy_version text, approval_decision jsonb,
 				created_at timestamptz NOT NULL, updated_at timestamptz NOT NULL
 			);
 			ALTER TABLE fabric_platform.action_invocations
 				ADD COLUMN IF NOT EXISTS idempotency_key text,
 				ADD COLUMN IF NOT EXISTS attempt_count integer NOT NULL DEFAULT 0,
 				ADD COLUMN IF NOT EXISTS lease_owner text,
-				ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz;
+				ADD COLUMN IF NOT EXISTS lease_expires_at timestamptz,
+				ADD COLUMN IF NOT EXISTS hitl_route text,
+				ADD COLUMN IF NOT EXISTS hitl_risk_tier text,
+				ADD COLUMN IF NOT EXISTS hitl_reason text,
+				ADD COLUMN IF NOT EXISTS hitl_policy_version text,
+				ADD COLUMN IF NOT EXISTS approval_decision jsonb;
 			CREATE UNIQUE INDEX IF NOT EXISTS action_invocations_idempotency_idx
 				ON fabric_platform.action_invocations
 				(tenant_id, space_id, action_id, idempotency_key)
@@ -612,9 +822,9 @@ var PostgresPlatformHostStore = class {
       `UPDATE fabric_platform.action_invocations SET
 			 status=COALESCE($4,status), result=COALESCE($5::jsonb,result),
 			 error=CASE WHEN $6::boolean THEN $7 ELSE error END,
-			 lease_owner=CASE WHEN $4 IN ('completed','failed','blocked_by_policy','validation_failed')
+			 lease_owner=CASE WHEN $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','validation_failed')
 			                  THEN NULL ELSE lease_owner END,
-			 lease_expires_at=CASE WHEN $4 IN ('completed','failed','blocked_by_policy','validation_failed')
+			 lease_expires_at=CASE WHEN $4 IN ('waiting_for_approval','completed','failed','blocked_by_policy','validation_failed')
 			                       THEN NULL ELSE lease_expires_at END,
 			 updated_at=now()
 			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3`,
@@ -629,6 +839,54 @@ var PostgresPlatformHostStore = class {
       ]
     );
   }
+  async recordHitlDecision(actionInvocationId, tenantId, spaceId, decision) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.action_invocations SET
+			 hitl_route=$4, hitl_risk_tier=$5, hitl_reason=$6,
+			 hitl_policy_version=$7, updated_at=$8
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3
+			 RETURNING *`,
+      [
+        actionInvocationId,
+        tenantId,
+        spaceId,
+        decision.route,
+        decision.riskTier,
+        decision.reason,
+        decision.policyVersion ?? null,
+        decision.evaluatedAt
+      ]
+    );
+    const row = result.rows[0];
+    if (!row) throw new Error(`ActionInvocation not found: ${actionInvocationId}`);
+    return toActionRecord(row);
+  }
+  async beginApprovalDecision(input) {
+    const result = await this.sql.query(
+      `UPDATE fabric_platform.action_invocations SET
+			 approval_decision=$4::jsonb,
+			 status=CASE WHEN $5::boolean THEN 'running' ELSE 'failed' END,
+			 error=CASE WHEN $5::boolean THEN NULL ELSE $6 END,
+			 lease_owner=CASE WHEN $5::boolean THEN $7 ELSE NULL END,
+			 lease_expires_at=CASE WHEN $5::boolean THEN $8 ELSE NULL END,
+			 attempt_count=CASE WHEN $5::boolean THEN GREATEST(attempt_count,1) ELSE attempt_count END,
+			 updated_at=$9
+			 WHERE id=$1 AND tenant_id=$2 AND space_id=$3 AND status='waiting_for_approval'
+			 RETURNING *`,
+      [
+        input.actionInvocationId,
+        input.tenantId,
+        input.spaceId,
+        JSON.stringify({ ...input.decision, decidedAt: input.decision.decidedAt.toISOString() }),
+        input.decision.approved,
+        `Approval rejected: ${input.decision.reason ?? "no reason provided"}`,
+        input.leaseOwner,
+        new Date(input.now.getTime() + input.leaseDurationMs),
+        input.now
+      ]
+    );
+    return result.rows[0] ? { applied: true, invocation: toActionRecord(result.rows[0]) } : { applied: false };
+  }
   async appendPolicyEvaluation(record) {
     await this.sql.query(
       `INSERT INTO fabric_platform.policy_evaluations
@@ -836,11 +1094,27 @@ function toActionRecord(row) {
     attemptCount: Number(row.attempt_count ?? 0),
     ...row.lease_owner ? { leaseOwner: String(row.lease_owner) } : {},
     ...row.lease_expires_at ? { leaseExpiresAt: new Date(row.lease_expires_at) } : {},
+    ...row.hitl_route ? { hitlRoute: String(row.hitl_route) } : {},
+    ...row.hitl_risk_tier ? { hitlRiskTier: String(row.hitl_risk_tier) } : {},
+    ...row.hitl_reason ? { hitlReason: String(row.hitl_reason) } : {},
+    ...row.hitl_policy_version ? { hitlPolicyVersion: String(row.hitl_policy_version) } : {},
+    ...row.approval_decision ? { approvalDecision: toApprovalDecision(row.approval_decision) } : {},
     ...row.error ? { error: String(row.error) } : {},
     createdAt: new Date(row.created_at),
     updatedAt: new Date(row.updated_at)
   };
 }
+function toApprovalDecision(value) {
+  const decision = value;
+  return {
+    approved: Boolean(decision.approved),
+    approverId: String(decision.approverId),
+    approverType: String(decision.approverType),
+    ...decision.reason ? { reason: String(decision.reason) } : {},
+    ...decision.editsReference ? { editsReference: String(decision.editsReference) } : {},
+    decidedAt: new Date(decision.decidedAt)
+  };
+}
 function toEventRecord(row) {
   return {
     id: String(row.id),
@@ -881,21 +1155,29 @@ async function runPlatformActionWorkerCycle(options) {
   });
   let completed = 0;
   let failed = 0;
+  let waitingForApproval = 0;
   for (const invocation of claimed) {
     try {
       const result = await options.host.executeInvocation(
         invocation.id,
         invocation.tenantId,
-        invocation.spaceId
+        invocation.spaceId,
+        { leaseOwner: options.workerId }
       );
       if (result.status === "completed") completed += 1;
+      else if (result.status === "waiting_for_approval") waitingForApproval += 1;
       else failed += 1;
     } catch (error) {
       failed += 1;
       options.onError?.(error, invocation);
     }
   }
-  return { claimed: claimed.length, completed, failed };
+  return {
+    claimed: claimed.length,
+    completed,
+    failed,
+    ...waitingForApproval > 0 ? { waitingForApproval } : {}
+  };
 }
 async function runPlatformActionWorker(options) {
   while (!options.signal?.aborted) {