@fabricorg/platform-host 0.3.0 → 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;
@@ -63,11 +86,30 @@ interface PlatformHostStore<TDb> {
     updateActionInvocation(id: string, tenantId: string, spaceId: string, patch: Partial<Pick<ActionInvocationRecord, "status" | "result" | "error">>): Promise<void>;
     appendPolicyEvaluation(record: PolicyEvaluationRecord): Promise<void>;
     createAdapterInvocation(record: AdapterInvocationRecord): Promise<void>;
+    getAdapterInvocation(id: string): Promise<AdapterInvocationRecord | undefined>;
     updateAdapterInvocation(id: string, patch: Partial<Pick<AdapterInvocationRecord, "status" | "output" | "error" | "attempt" | "updatedAt">>): Promise<void>;
     appendEvent(event: AssetEventEnvelope): Promise<void>;
     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;
@@ -102,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;
@@ -135,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;
@@ -158,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>;
@@ -165,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 & {
@@ -180,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[];
@@ -196,8 +259,11 @@ 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>;
     updateAdapterInvocation(id: string, patch: Partial<Pick<AdapterInvocationRecord, "status" | "output" | "error" | "attempt" | "updatedAt">>): Promise<void>;
     appendEvent(event: AssetEventEnvelope): Promise<void>;
     nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
@@ -215,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);
@@ -224,8 +290,11 @@ 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>;
     updateAdapterInvocation(id: string, patch: Partial<Pick<AdapterInvocationRecord, "status" | "output" | "error" | "attempt" | "updatedAt">>): Promise<void>;
     appendEvent(event: AssetEventEnvelope): Promise<void>;
     nextEventSequence(tenantId: string, spaceId: string): Promise<number>;
@@ -245,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 };