/**
 * Orchestrator Adapter SDK -- public interface surface
 *
 * Defines the abstract interface that every orchestrator adapter must
 * implement, the canonical audit-event taxonomy, the reviewer-tier model,
 * the error hierarchy, and the supporting context/decision types.
 *
 * The governance runtime dispatches plan approval, task governance,
 * delegation routing, reviewer-queue insertion, and audit-chain emission
 * through this interface. No orchestrator-specific branching is permitted
 * in the runtime layer -- all orchestrator logic lives in the adapters.
 *
 * Spec: P3-ORCH-01, AC 1-3, AC 20, Section 3.1-3.4
 * Depends on: P3-SUB-01 (LlmProviderError hierarchy)
 *
 * @connexum/ai-governance
 */
export { LlmProviderError } from '../llm-adapters/index';
import { LlmProviderError } from '../llm-adapters/index';
export type { TaskContext, TaskDecision, PlanContext, PlanStep, PlanDecision, DelegationContext, DelegationDecision, } from './orchestrator-adapter';
export { ActionDecisionType } from '../adapters/index';
/**
 * Fixed reviewer tiers. Custom tiers require a semver major bump.
 * See Section 3.4 for routing semantics.
 */
export type ReviewerTier = 'agent-supervisor' | 'human-reviewer' | 'legal-reviewer' | 'security-reviewer';
/**
 * The 18 canonical orchestrator audit event names.
 * Every adapter emits events from this fixed vocabulary.
 * Adapter-internal event names are retained for debugging but must be
 * accompanied by a canonical event.
 */
export type CanonicalAuditEventName = 'orchestrator:workflow-start' | 'orchestrator:workflow-complete' | 'orchestrator:plan-proposed' | 'orchestrator:plan-approved' | 'orchestrator:plan-denied' | 'orchestrator:plan-step-begin' | 'orchestrator:plan-step-end' | 'orchestrator:task-approved' | 'orchestrator:task-denied' | 'orchestrator:delegation-approved' | 'orchestrator:delegation-denied' | 'orchestrator:role-edge-invoked' | 'orchestrator:reviewer-routed' | 'orchestrator:reviewer-timeout' | 'orchestrator:unregistered-role' | 'orchestrator:termination-by-exhaustion' | 'orchestrator:framework-dispatch' | 'orchestrator:circuit-breaker-tripped' | 'orchestrator:tool-output-classified';
import type { AgentIdentity } from '../adapters/index';
export interface WorkflowContext {
    /** Unique identifier for this workflow run */
    workflowId: string;
    /** Human-readable name or description */
    name: string;
    /** The agent or system initiating the workflow */
    initiator: AgentIdentity;
    /** ISO-8601 timestamp */
    timestamp: string;
    /** Organization/tenant ID for multi-tenant environments */
    orgId?: string;
    /** Arbitrary structured metadata */
    metadata?: Record<string, unknown>;
}
export interface WorkflowResult {
    success: boolean;
    /** Brief summary (no secrets) */
    summary: string;
    /** Duration in milliseconds */
    durationMs?: number;
    /** Error message if success is false */
    error?: string;
}
export type WorkflowDecisionType = 'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL';
export interface WorkflowDecision {
    type: WorkflowDecisionType;
    reason: string;
    auditId: string;
    metadata?: Record<string, unknown>;
}
export interface WorkflowStepContext extends WorkflowContext {
    /** Current step index (0-based) */
    stepIndex: number;
    /** Identifier of the step in the plan */
    stepId: string;
}
export interface WorkflowStepDecision {
    type: WorkflowDecisionType;
    reason: string;
    auditId: string;
    metadata?: Record<string, unknown>;
}
export interface RoleEdgeContext {
    /** Unique identifier for this edge invocation */
    edgeId: string;
    /** Source role label */
    fromRole: string;
    /** Destination role label */
    toRole: string;
    /** The agent at the source */
    fromAgent: AgentIdentity;
    /** The agent at the destination */
    toAgent: AgentIdentity;
    /** ISO-8601 timestamp */
    timestamp: string;
    /** Arbitrary payload being sent across the edge */
    payload?: Record<string, unknown>;
    orgId?: string;
}
export interface RoleEdgeDecision {
    type: WorkflowDecisionType;
    reason: string;
    auditId: string;
    metadata?: Record<string, unknown>;
}
import type { PlanContext, PlanStep } from './orchestrator-adapter';
export interface PlanNodeVisitor {
    /** Called when the DFS enters a plan step */
    visitStep(step: PlanStep, depth: number): Promise<void>;
}
export interface RolePolicyContext {
    /** Role being dispatched */
    role: string;
    /** Arbitrary context for the policy evaluation */
    policyInput: Record<string, unknown>;
    orgId?: string;
}
export type RolePolicyDecisionType = 'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL';
export interface RolePolicyDecision {
    type: RolePolicyDecisionType;
    reason: string;
    auditId: string;
    metadata?: Record<string, unknown>;
}
export interface ReviewerContext {
    /** The tier this decision is being routed to */
    requestedTier: ReviewerTier;
    /** Description of the item requiring review */
    subject: string;
    /** ISO-8601 timestamp */
    timestamp: string;
    /** Originating agent */
    requestingAgent: AgentIdentity;
    /** Arbitrary additional context */
    context?: Record<string, unknown>;
    orgId?: string;
}
export interface ReviewerRoutingResult {
    /** Queue entry ID */
    queueEntryId: string;
    /** The tier the entry was routed to */
    resolvedTier: ReviewerTier;
    /** Estimated review deadline (ISO-8601) */
    reviewDeadline?: string;
}
/** Per-role policy and reviewer tier mapping, registered at initialize() */
export interface RoleRegistration {
    role: string;
    policyPack: string;
    reviewerTier: ReviewerTier;
}
/** Queue binding: tier -> queue identifier */
export type ReviewerQueueBindings = Partial<Record<ReviewerTier, string>>;
export interface OrchestratorAdapterConfig {
    /** Unique name for this adapter instance */
    adapterName: string;
    /** Human-readable orchestrator name */
    orchestratorName?: string;
    /** Reviewer-queue bindings -- required (fail closed if absent) */
    reviewerQueues: ReviewerQueueBindings;
    /** Registered roles with their policy packs and reviewer tiers */
    roles?: RoleRegistration[];
    /** Circuit-breaker: number of consecutive failures before tripping */
    circuitBreakerThreshold?: number;
    /**
     * C1 fix: active compliance pack binding for this adapter instance.
     * Used by postActionClassify() to scope G-series classification events.
     * An empty array means no pack context is forwarded to the classifier.
     */
    packBinding?: string[];
    /**
     * H9c: JWT-derived organization ID for this adapter instance.
     * Sourced from the server-validated entitlement token at initialization time.
     * All canonical audit events emitted by this adapter carry this orgId.
     * NEVER derived from caller-supplied agentId strings -- those may be attacker-
     * controlled and must have any embedded org field stripped before use.
     */
    jwtOrgId?: string;
    /** Arbitrary additional options */
    options?: Record<string, unknown>;
}
export interface OrchestratorCapabilities {
    /** Supports workflow-level governance (startWorkflow / completeWorkflow) */
    workflowGovernance: boolean;
    /** Supports task-level governance (preTask / postTask) */
    taskGovernance: boolean;
    /** Supports plan-level governance (prePlan / postPlan) */
    planGovernance: boolean;
    /** Supports delegation governance (preDelegation / postDelegation) */
    delegationGovernance: boolean;
    /** Supports role-edge invocation governance */
    roleEdgeGovernance: boolean;
    /** Supports parallel task execution governance */
    parallelExecution: boolean;
    /** Supports nested / hierarchical plan governance */
    nestedPlans: boolean;
    /** Whether the circuit breaker is enabled */
    circuitBreaker: boolean;
}
/**
 * Every orchestrator adapter must implement this interface.
 *
 * No method is optional. Adapters that do not support a surface (e.g. an
 * orchestrator with no delegation concept) must throw
 * OrchestratorUnsupportedError with an explicit reason -- not return null,
 * undefined, or a silent ALLOW.
 *
 * Spec: P3-ORCH-01 Section 3.1
 */
export interface OrchestratorAdapter {
    readonly adapterId: string;
    readonly orchestratorId: string;
    /**
     * Initialize the adapter with config.
     * Throws ReviewerRoutingError if reviewerQueues is empty or unresolvable.
     * (AC 28: fail-closed on missing reviewer-queue binding)
     */
    initialize(config: OrchestratorAdapterConfig): void;
    /** Called when a workflow begins. Fail closed: deny unknown workflows. */
    startWorkflow(ctx: WorkflowContext): Promise<WorkflowDecision>;
    /** Called at each step boundary in a workflow. */
    stepWorkflow(ctx: WorkflowStepContext): Promise<WorkflowStepDecision>;
    /** Called when a workflow completes (success or failure). Audit only. */
    completeWorkflow(ctx: WorkflowContext, result: WorkflowResult): Promise<void>;
    /** Pre-task governance check. */
    preTask(task: import('./orchestrator-adapter').TaskContext): Promise<import('./orchestrator-adapter').TaskDecision>;
    /** Post-task audit hook. */
    postTask(task: import('./orchestrator-adapter').TaskContext, result: Record<string, unknown>): Promise<void>;
    /** Pre-plan governance check. Validates plan structure synchronously. */
    prePlan(plan: PlanContext): Promise<import('./orchestrator-adapter').PlanDecision>;
    /** Post-plan audit hook. */
    postPlan(plan: PlanContext, result: Record<string, unknown>): Promise<void>;
    /** Pre-delegation governance check. */
    preDelegation(d: import('./orchestrator-adapter').DelegationContext): Promise<import('./orchestrator-adapter').DelegationDecision>;
    /** Post-delegation audit hook. */
    postDelegation(d: import('./orchestrator-adapter').DelegationContext, result: Record<string, unknown>): Promise<void>;
    /** Governance check for a role-to-role edge crossing. */
    invokeRoleEdge(edge: RoleEdgeContext): Promise<RoleEdgeDecision>;
    /** Depth-first traversal with cycle detection. */
    traversePlanTree(root: PlanContext, visitor: PlanNodeVisitor): Promise<void>;
    /** Dispatch policy for a registered role. Throws RoleNotRegisteredError if missing. */
    dispatchRolePolicy(role: string, ctx: RolePolicyContext): Promise<RolePolicyDecision>;
    /** Route a REQUIRE_APPROVAL decision to the correct reviewer tier. */
    routeToReviewer(tier: ReviewerTier, ctx: ReviewerContext): Promise<ReviewerRoutingResult>;
    /** Translate a raw framework-native exception to a typed OrchestratorError. */
    translateError(raw: unknown): OrchestratorError;
    /** Report orchestrator-specific capabilities. */
    getOrchestratorCapabilities(): OrchestratorCapabilities;
}
/**
 * Base orchestrator error. Extends LlmProviderError so orchestrator errors
 * are a subtype of the P3-SUB-01 hierarchy and can be handled uniformly.
 */
export declare class OrchestratorError extends LlmProviderError {
    constructor(opts: {
        message: string;
        code: string;
        orchestratorId?: string;
        adapterId?: string;
        raw?: unknown;
    });
}
/**
 * The adapter does not support the requested surface.
 * Thrown instead of returning null, undefined, or a silent ALLOW.
 */
export declare class OrchestratorUnsupportedError extends OrchestratorError {
    /** The surface that is not supported (e.g. 'delegation', 'parallelExecution') */
    readonly surface: string;
    constructor(opts: {
        message: string;
        surface: string;
        orchestratorId?: string;
        adapterId?: string;
    });
}
/**
 * A submitted plan is structurally invalid (empty steps, cycle, undefined deps).
 * Thrown synchronously at prePlan() time; partial-execution fallback is prohibited.
 */
export declare class PlanValidationError extends OrchestratorError {
    readonly planId: string;
    readonly failedStepIds: string[];
    constructor(opts: {
        message: string;
        planId: string;
        failedStepIds: string[];
        orchestratorId?: string;
        adapterId?: string;
    });
}
/**
 * Delegation was denied by policy.
 */
export declare class DelegationDeniedError extends OrchestratorError {
    readonly fromAgent: string;
    readonly toAgent: string;
    readonly deniedPermissions: string[];
    constructor(opts: {
        message: string;
        fromAgent: string;
        toAgent: string;
        deniedPermissions: string[];
        orchestratorId?: string;
        adapterId?: string;
    });
}
/**
 * A role was referenced that is not registered with the adapter.
 * Thrown at the point of first task dispatch into that role.
 */
export declare class RoleNotRegisteredError extends OrchestratorError {
    readonly role: string;
    constructor(opts: {
        message: string;
        role: string;
        orchestratorId?: string;
        adapterId?: string;
    });
}
/**
 * Reviewer routing failed: the requested tier has no queue binding,
 * or the adapter was initialized without any reviewer-queue binding.
 */
export declare class ReviewerRoutingError extends OrchestratorError {
    readonly requestedTier: string;
    constructor(opts: {
        message: string;
        requestedTier: string;
        orchestratorId?: string;
        adapterId?: string;
    });
}
//# sourceMappingURL=index.d.ts.map