@fabricorg/platform-host 8.5.0 → 8.7.0

package/dist/index.d.cts

@@ -1,4 +1,4 @@
-import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyDecision, AgentActionPolicyEvaluator, AgentActionRiskTier, AgentActionRoute, AssetEventEnvelope, EvidencePacketReference, ExecutionAttestation, ExecutionPrincipal, ExternalReconciliation, FabricRuntimeServices, GovernanceRuntimeEvidence, ModuleRegistry, MutationFootprint, MutationGovernanceResolver, PolicyObligation, PolicyObligationStatus, PolicyOutcome, RuntimePolicyDefinition, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
+import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyContext, AgentActionPolicyDecision, AgentActionRiskTier, AgentActionRoute, AssetEventEnvelope, EvidencePacketReference, ExecutionAttestation, ExecutionPrincipal, ExternalReconciliation, FabricRuntimeServices, GovernanceRuntimeEvidence, ModuleRegistry, MutationFootprint, MutationGovernanceResolver, PolicyObligation, PolicyObligationStatus, PolicyOutcome, RuntimePolicyDefinition, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
 import { AssemblyLockfile } from "@fabricorg/assembly";
 //#region src/observability.d.ts
 /** Version of the vendor-neutral health/readiness contract. */
@@ -183,7 +183,7 @@ export interface IdempotencyConflict {
   code: "IDEMPOTENCY_CONFLICT";
   idempotencyKey: string;
   existingInvocationId: string;
-  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters">;
+  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters" | "agent_proposal">;
 }
 export declare class IdempotencyConflictError extends Error {
   readonly conflict: IdempotencyConflict;
@@ -275,8 +275,24 @@ export interface FinalizationCheckpoint {
 export interface StagedInvocationOrigin {
   parentInvocationId: string;
   stageKey: string;
+  /** Host-registered principal name captured in the durable staged intent. */
+  principal?: string;
+}
+export interface AgentProposal {
+  confidence?: number;
+  riskTier?: AgentActionRiskTier;
+  agentSessionId?: string;
+  agentRunId?: string;
+  reason?: string;
+  evidence?: ApprovalEvidence;
+}
+export interface HostHitlEvaluatorContext extends AgentActionPolicyContext {
+  actionInvocationId: string;
+  /** The durable (post-redaction) invocation record as read before evaluation. */
+  invocation: Readonly<ActionInvocationRecord>;
 }
 export interface ActionInvocationRecord {
+  readonly agentProposal?: AgentProposal;
   id: string;
   tenantId: string;
   spaceId: string;
@@ -743,6 +759,8 @@ export interface StagedInvocationRecord {
   parentActionId: ActionId;
   key: string;
   actionId: ActionId;
+  /** Host-registered principal name selected by the parent action declaration. */
+  principal?: string;
   expectedActionVersion: number;
   parameters: Record<string, unknown>;
   parameterDigest: string;
@@ -1335,9 +1353,12 @@ export interface PlatformActionDispatcher {
  * `provenance` and `authorizationBinding` are also read once there and
  * replaced by Host's own copies. For any other action Host uses those three
  * as the caller's objects, read where and as often as before (README,
- * "Submission snapshot").
+ * "Submission snapshot"). `agentProposal` is read once and deeply copied before
+ * the first await for all actions, independently of `admitSubmission`.
  */
 export interface SubmitActionInput {
+  /** Read once and deeply copied before the first await, regardless of admission. */
+  agentProposal?: AgentProposal;
   actionId: ActionId;
   parameters: Record<string, unknown>;
   tenantId: string;
@@ -1481,6 +1502,11 @@ export interface PlatformHostOptions<TDb> {
   registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine"> & Partial<Pick<ModuleRegistry<TDb>, "orderedModules">>;
   /** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
   resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
+  /** Host-owned identities available to parent action declarations for staged dispatch. */
+  stagedInvocationPrincipals?: Readonly<Record<string, {
+    actorId: string;
+    actorType: ActorType;
+  }>>;
   adapters?: readonly AdapterImplementation[];
   /**
    * Supplies the circuit breaker for each adapter call. Defaults to a new
@@ -1550,7 +1576,7 @@ export interface PlatformHostOptions<TDb> {
     shouldPublish?(event: AssetEventEnvelope): boolean;
   };
   /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
-  hitlEvaluator?: (context: Parameters<AgentActionPolicyEvaluator>[0]) => HostHitlDecision | Promise<HostHitlDecision>;
+  hitlEvaluator?: (context: HostHitlEvaluatorContext) => HostHitlDecision | Promise<HostHitlDecision>;
   /** Positive integer milliseconds, used when the evaluator supplies no absolute deadline. */
   approvalDefaultTtlMs?: number;
   /** Atomic approval lifecycle events and outbox writes; defaults to false. */
@@ -1607,6 +1633,8 @@ export interface PlatformHostOptions<TDb> {
    * copy, after the check admitted the submission.
    */
   redactActionParameters?: (actionId: ActionId, parameters: Record<string, unknown>) => Record<string, unknown>;
+  /** Runs beside parameter redaction; output is validated and copied before persistence. */
+  redactAgentProposal?: (actionId: ActionId, proposal: AgentProposal) => AgentProposal;
   /**
    * The bound on an action's `admitSubmission` check. An answer that
    * settles this many milliseconds or more after the check was called,
@@ -2214,11 +2242,13 @@ export declare const MAX_STAGED_INVOCATION_KEY_LENGTH = 128;
 export declare const MAX_STAGED_INVOCATION_BYTES: number;
 export declare const MAX_STAGED_INVOCATION_BATCH_BYTES: number;
 export declare const STAGED_INVOCATION_KEY_PATTERN: RegExp;
+export declare const STAGED_INVOCATION_PRINCIPAL_PATTERN: RegExp;
 interface PrepareStagedInvocationBatchInput<TDb> {
   parent: Pick<ActionInvocationRecord, "id" | "tenantId" | "spaceId" | "actionId">;
   parentAction: ActionDefinition<TDb>;
   requests: readonly StagedInvocationRequest[];
   resolveAction(actionId: ActionId): ActionDefinition<TDb> | undefined;
+  stagedInvocationPrincipals?: Readonly<Record<string, unknown>>;
   redactParameters?(actionId: ActionId, parameters: Record<string, unknown>): Record<string, unknown>;
   /** Keys whose parameters already passed the redactor into a durable checkpoint. */
   redactedKeys?: readonly string[];

package/dist/index.d.ts

@@ -1,4 +1,4 @@
-import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyDecision, AgentActionPolicyEvaluator, AgentActionRiskTier, AgentActionRoute, AssetEventEnvelope, EvidencePacketReference, ExecutionAttestation, ExecutionPrincipal, ExternalReconciliation, FabricRuntimeServices, GovernanceRuntimeEvidence, ModuleRegistry, MutationFootprint, MutationGovernanceResolver, PolicyObligation, PolicyObligationStatus, PolicyOutcome, RuntimePolicyDefinition, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
+import { ActionDefinition, ActionId, ActionStatus, ActorType, AdapterCircuitBreakerProvider, AdapterImplementation, AgentActionPolicyContext, AgentActionPolicyDecision, AgentActionRiskTier, AgentActionRoute, AssetEventEnvelope, EvidencePacketReference, ExecutionAttestation, ExecutionPrincipal, ExternalReconciliation, FabricRuntimeServices, GovernanceRuntimeEvidence, ModuleRegistry, MutationFootprint, MutationGovernanceResolver, PolicyObligation, PolicyObligationStatus, PolicyOutcome, RuntimePolicyDefinition, StagedInvocationRequest, canonicalJson } from "@fabricorg/platform";
 import { AssemblyLockfile } from "@fabricorg/assembly";
 //#region src/observability.d.ts
 /** Version of the vendor-neutral health/readiness contract. */
@@ -183,7 +183,7 @@ export interface IdempotencyConflict {
   code: "IDEMPOTENCY_CONFLICT";
   idempotencyKey: string;
   existingInvocationId: string;
-  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters">;
+  reasons: Array<"actor" | "authority_binding" | "action_version" | "parameters" | "agent_proposal">;
 }
 export declare class IdempotencyConflictError extends Error {
   readonly conflict: IdempotencyConflict;
@@ -275,8 +275,24 @@ export interface FinalizationCheckpoint {
 export interface StagedInvocationOrigin {
   parentInvocationId: string;
   stageKey: string;
+  /** Host-registered principal name captured in the durable staged intent. */
+  principal?: string;
+}
+export interface AgentProposal {
+  confidence?: number;
+  riskTier?: AgentActionRiskTier;
+  agentSessionId?: string;
+  agentRunId?: string;
+  reason?: string;
+  evidence?: ApprovalEvidence;
+}
+export interface HostHitlEvaluatorContext extends AgentActionPolicyContext {
+  actionInvocationId: string;
+  /** The durable (post-redaction) invocation record as read before evaluation. */
+  invocation: Readonly<ActionInvocationRecord>;
 }
 export interface ActionInvocationRecord {
+  readonly agentProposal?: AgentProposal;
   id: string;
   tenantId: string;
   spaceId: string;
@@ -743,6 +759,8 @@ export interface StagedInvocationRecord {
   parentActionId: ActionId;
   key: string;
   actionId: ActionId;
+  /** Host-registered principal name selected by the parent action declaration. */
+  principal?: string;
   expectedActionVersion: number;
   parameters: Record<string, unknown>;
   parameterDigest: string;
@@ -1335,9 +1353,12 @@ export interface PlatformActionDispatcher {
  * `provenance` and `authorizationBinding` are also read once there and
  * replaced by Host's own copies. For any other action Host uses those three
  * as the caller's objects, read where and as often as before (README,
- * "Submission snapshot").
+ * "Submission snapshot"). `agentProposal` is read once and deeply copied before
+ * the first await for all actions, independently of `admitSubmission`.
  */
 export interface SubmitActionInput {
+  /** Read once and deeply copied before the first await, regardless of admission. */
+  agentProposal?: AgentProposal;
   actionId: ActionId;
   parameters: Record<string, unknown>;
   tenantId: string;
@@ -1481,6 +1502,11 @@ export interface PlatformHostOptions<TDb> {
   registry?: Pick<ModuleRegistry<TDb>, "resolveAction" | "resolvePolicy" | "resolveStateMachine"> & Partial<Pick<ModuleRegistry<TDb>, "orderedModules">>;
   /** Resolve vertical- or runtime-local actions without mutating the process-wide registry. */
   resolveAction?: (actionId: ActionId) => ActionDefinition<TDb> | undefined;
+  /** Host-owned identities available to parent action declarations for staged dispatch. */
+  stagedInvocationPrincipals?: Readonly<Record<string, {
+    actorId: string;
+    actorType: ActorType;
+  }>>;
   adapters?: readonly AdapterImplementation[];
   /**
    * Supplies the circuit breaker for each adapter call. Defaults to a new
@@ -1550,7 +1576,7 @@ export interface PlatformHostOptions<TDb> {
     shouldPublish?(event: AssetEventEnvelope): boolean;
   };
   /** Optional vertical-owned evaluator. When absent, agent behavior is unchanged. */
-  hitlEvaluator?: (context: Parameters<AgentActionPolicyEvaluator>[0]) => HostHitlDecision | Promise<HostHitlDecision>;
+  hitlEvaluator?: (context: HostHitlEvaluatorContext) => HostHitlDecision | Promise<HostHitlDecision>;
   /** Positive integer milliseconds, used when the evaluator supplies no absolute deadline. */
   approvalDefaultTtlMs?: number;
   /** Atomic approval lifecycle events and outbox writes; defaults to false. */
@@ -1607,6 +1633,8 @@ export interface PlatformHostOptions<TDb> {
    * copy, after the check admitted the submission.
    */
   redactActionParameters?: (actionId: ActionId, parameters: Record<string, unknown>) => Record<string, unknown>;
+  /** Runs beside parameter redaction; output is validated and copied before persistence. */
+  redactAgentProposal?: (actionId: ActionId, proposal: AgentProposal) => AgentProposal;
   /**
    * The bound on an action's `admitSubmission` check. An answer that
    * settles this many milliseconds or more after the check was called,
@@ -2214,11 +2242,13 @@ export declare const MAX_STAGED_INVOCATION_KEY_LENGTH = 128;
 export declare const MAX_STAGED_INVOCATION_BYTES: number;
 export declare const MAX_STAGED_INVOCATION_BATCH_BYTES: number;
 export declare const STAGED_INVOCATION_KEY_PATTERN: RegExp;
+export declare const STAGED_INVOCATION_PRINCIPAL_PATTERN: RegExp;
 interface PrepareStagedInvocationBatchInput<TDb> {
   parent: Pick<ActionInvocationRecord, "id" | "tenantId" | "spaceId" | "actionId">;
   parentAction: ActionDefinition<TDb>;
   requests: readonly StagedInvocationRequest[];
   resolveAction(actionId: ActionId): ActionDefinition<TDb> | undefined;
+  stagedInvocationPrincipals?: Readonly<Record<string, unknown>>;
   redactParameters?(actionId: ActionId, parameters: Record<string, unknown>): Record<string, unknown>;
   /** Keys whose parameters already passed the redactor into a durable checkpoint. */
   redactedKeys?: readonly string[];