@fabricorg/platform-host 0.3.1 → 0.4.0

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionId, ActorType, ActionStatus, PolicyOutcome, AssetEventEnvelope, AdapterImplementation, FabricRuntimeServices, RuntimePolicyDefinition } from '@fabricorg/platform';
+import { ActorType, ActionId, ActionStatus, AgentActionRoute, AgentActionRiskTier, PolicyOutcome, AssetEventEnvelope, AdapterImplementation, FabricRuntimeServices, AgentActionPolicyEvaluator, RuntimePolicyDefinition } from '@fabricorg/platform';
 
 interface PendingAssetEvent {
     eventType: string;
@@ -24,10 +24,33 @@ interface ActionInvocationRecord {
     attemptCount: number;
     leaseOwner?: string;
     leaseExpiresAt?: Date;
+    hitlRoute?: AgentActionRoute;
+    hitlRiskTier?: AgentActionRiskTier;
+    hitlReason?: string;
+    hitlPolicyVersion?: string;
+    approvalDecision?: PersistedActionApprovalDecision;
     error?: string;
     createdAt: Date;
     updatedAt: Date;
 }
+interface HitlDecisionEvidence {
+    route: AgentActionRoute;
+    riskTier: AgentActionRiskTier;
+    reason: string;
+    policyVersion?: string;
+    evaluatedAt: Date;
+}
+interface ActionApprovalDecision {
+    approved: boolean;
+    approverId: string;
+    approverType: ActorType;
+    reason?: string;
+    editsReference?: string;
+    decidedAt?: Date;
+}
+interface PersistedActionApprovalDecision extends Omit<ActionApprovalDecision, "decidedAt"> {
+    decidedAt: Date;
+}
 interface PolicyEvaluationRecord {
     id: string;
     actionInvocationId: string;
@@ -69,6 +92,24 @@ interface PlatformHostStore<TDb> {
     nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
     getEntityState(tenantId: string, spaceId: string, entityType: string, entityId: string): Promise<string | undefined>;
 }
+interface BeginApprovalDecisionInput {
+    actionInvocationId: string;
+    tenantId: string;
+    spaceId: string;
+    decision: PersistedActionApprovalDecision;
+    leaseOwner: string;
+    leaseDurationMs: number;
+    now: Date;
+}
+interface ApprovalDecisionTransitionResult {
+    applied: boolean;
+    invocation?: ActionInvocationRecord;
+}
+/** Optional store capability required only when agent HITL or approval resume is used. */
+interface ApprovalPlatformHostStore<TDb> extends PlatformHostStore<TDb> {
+    recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
+    beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
+}
 interface ListActionInvocationsInput {
     tenantId?: string;
     spaceId?: string;
@@ -103,6 +144,10 @@ interface ActionAuthorizationInput {
 interface PlatformHostAuthorization {
     checkEntitlement(input: ActionAuthorizationInput): Promise<boolean>;
     authorize(input: ActionAuthorizationInput): Promise<boolean>;
+    /** Optional distinct authorization boundary for human/system approval decisions. */
+    authorizeApproval?(input: ActionAuthorizationInput & {
+        decision: ActionApprovalDecision;
+    }): Promise<boolean>;
 }
 interface DispatchActionInput {
     actionInvocationId: string;
@@ -136,12 +181,20 @@ interface SubmitActionResult {
     runId?: string;
     result?: Record<string, unknown>;
     error?: string;
+    hitlRoute?: AgentActionRoute;
+    hitlRiskTier?: AgentActionRiskTier;
 }
 interface ExecuteActionResult {
     actionInvocationId: string;
     status: ActionStatus;
     result?: Record<string, unknown>;
     error?: string;
+    hitlRoute?: AgentActionRoute;
+    hitlRiskTier?: AgentActionRiskTier;
+}
+interface ExecuteInvocationOptions {
+    /** Required when executing a row already protected by a worker or approval-resume lease. */
+    leaseOwner?: string;
 }
 interface PlatformActionWorkerOptions<TDb> {
     host: GovernedActionHost;
@@ -159,6 +212,8 @@ interface PlatformActionWorkerCycleResult {
     claimed: number;
     completed: number;
     failed: number;
+    /** Present when claimed agent work was durably parked instead of failing. */
+    waitingForApproval?: number;
 }
 interface PlatformHostOptions<TDb> {
     store: PlatformHostStore<TDb>;
@@ -166,6 +221,12 @@ interface PlatformHostOptions<TDb> {
     adapters?: readonly AdapterImplementation[];
     dispatcher?: PlatformActionDispatcher;
     services?: FabricRuntimeServices;
+    /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
+    hitlEvaluator?: AgentActionPolicyEvaluator;
+    /** Durable evaluator/ruleset version recorded with every HITL decision. */
+    hitlPolicyVersion?: string;
+    /** Lease held while an approved invocation resumes; defaults to five minutes. */
+    approvalResumeLeaseDurationMs?: number;
     /** Remove forbidden/sensitive fields before durable invocation persistence. */
     redactActionParameters?: (actionId: ActionId, parameters: Record<string, unknown>) => Record<string, unknown>;
     resolvePolicies?: (input: ActionAuthorizationInput & {
@@ -181,12 +242,13 @@ interface PlatformHostOptions<TDb> {
 }
 interface GovernedActionHost {
     submitAction(input: SubmitActionInput): Promise<SubmitActionResult>;
-    executeInvocation(actionInvocationId: string, tenantId: string, spaceId: string): Promise<ExecuteActionResult>;
+    executeInvocation(actionInvocationId: string, tenantId: string, spaceId: string, options?: ExecuteInvocationOptions): Promise<ExecuteActionResult>;
+    resumeApprovedInvocation(actionInvocationId: string, tenantId: string, spaceId: string, decision: ActionApprovalDecision): Promise<ExecuteActionResult>;
 }
 
 declare function createGovernedActionHost<TDb>(options: PlatformHostOptions<TDb>): GovernedActionHost;
 
-declare class MemoryPlatformHostStore<TDb> implements PlatformHostStore<TDb> {
+declare class MemoryPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb> {
     readonly db: TDb;
     readonly invocations: ActionInvocationRecord[];
     readonly policyEvaluations: PolicyEvaluationRecord[];
@@ -197,6 +259,8 @@ declare class MemoryPlatformHostStore<TDb> implements PlatformHostStore<TDb> {
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
     updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
+    recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
+    beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
     createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
     getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
@@ -217,7 +281,7 @@ interface PlatformHostSqlClient {
     query<Row = Record<string, unknown>>(sql: string, values?: unknown[]): Promise<PlatformHostSqlResult<Row>>;
 }
 /** Durable mutation-pipeline ledger for Databricks Lakebase or standard Postgres. */
-declare class PostgresPlatformHostStore<TDb> implements PlatformHostStore<TDb> {
+declare class PostgresPlatformHostStore<TDb> implements RecoverablePlatformHostStore<TDb>, ApprovalPlatformHostStore<TDb> {
     readonly db: TDb;
     private readonly sql;
     constructor(db: TDb, sql: PlatformHostSqlClient);
@@ -226,6 +290,8 @@ declare class PostgresPlatformHostStore<TDb> implements PlatformHostStore<TDb> {
     createActionInvocation(input: CreateActionInvocationInput): Promise<ActionInvocationRecord>;
     getActionInvocation(id: string, tenantId: string, spaceId: string): Promise<ActionInvocationRecord | undefined>;
     updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
+    recordHitlDecision(actionInvocationId: string, tenantId: string, spaceId: string, decision: HitlDecisionEvidence): Promise<ActionInvocationRecord>;
+    beginApprovalDecision(input: BeginApprovalDecisionInput): Promise<ApprovalDecisionTransitionResult>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
     createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
     getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
@@ -248,4 +314,4 @@ declare function runPlatformActionWorkerCycle<TDb>(options: PlatformActionWorker
 /** Poll until aborted. Each iteration is bounded and waits without busy-spinning. */
 declare function runPlatformActionWorker<TDb>(options: PlatformActionWorkerOptions<TDb>): Promise<void>;
 
-export { type ActionAuthorizationInput, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ClaimActionInvocationsInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type ExecuteActionResult, type GovernedActionHost, type ListActionInvocationsInput, MemoryPlatformHostStore, type PendingAssetEvent, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, PostgresPlatformHostStore, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, createGovernedActionHost, createStoreBackedActionDispatcher, runPlatformActionWorker, runPlatformActionWorkerCycle };
+export { type ActionApprovalDecision, type ActionAuthorizationInput, type ActionInvocationRecord, type AdapterInvocationRecord, type AdapterInvocationStatus, type ApprovalDecisionTransitionResult, type ApprovalPlatformHostStore, type BeginApprovalDecisionInput, type ClaimActionInvocationsInput, type CreateActionInvocationInput, type DispatchActionInput, type DispatchActionResult, type ExecuteActionResult, type ExecuteInvocationOptions, type GovernedActionHost, type HitlDecisionEvidence, type ListActionInvocationsInput, MemoryPlatformHostStore, type PendingAssetEvent, type PersistedActionApprovalDecision, type PlatformActionDispatcher, type PlatformActionWorkerCycleResult, type PlatformActionWorkerOptions, type PlatformHostAuthorization, type PlatformHostOptions, type PlatformHostSqlClient, type PlatformHostSqlResult, type PlatformHostStore, type PolicyEvaluationRecord, PostgresPlatformHostStore, type RecoverablePlatformHostStore, type SubmitActionInput, type SubmitActionResult, createGovernedActionHost, createStoreBackedActionDispatcher, runPlatformActionWorker, runPlatformActionWorkerCycle };

package/dist/index.js

@@ -45,7 +45,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 +62,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,19 +84,23 @@ 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);
@@ -106,15 +114,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,
@@ -327,11 +388,80 @@ function createGovernedActionHost(options) {
         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 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 = resolveAction(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) {
     const timestamp = now();
     const envelope = {
@@ -364,9 +494,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 {
@@ -444,6 +603,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 +719,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 +816,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 +833,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 +1088,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 +1149,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) {