/**
 * IDE Adapter SDK -- public interface surface.
 *
 * Defines the abstract TypeScript interfaces and error hierarchy for
 * IDE-layer governance adapters. Every IDE adapter (Claude Code, Cursor,
 * GitHub Copilot Workspace, Continue.dev) implements `IdeAdapter`.
 *
 * The governance runtime dispatches tool-invocation interception, policy
 * evaluation, reviewer routing, audit-chain emission, and session lifecycle
 * through this interface. No IDE-specific branching is permitted in the
 * runtime layer -- all IDE logic lives in the concrete adapter.
 *
 * Spec: P3-IDE-01 (IDE Adapter SDK)
 * AC:   1-3, 17, 22-24 (interfaces, base, error hierarchy, identity types)
 *
 * @connexum/ai-governance
 */
import { LlmProviderError } from '../llm-adapters/index';
export { LlmProviderError };
export type IdeAuditEventType = 'ide:session-open' | 'ide:session-close' | 'ide:tool-invocation-approved' | 'ide:tool-invocation-denied' | 'ide:tool-invocation-require-approval' | 'ide:user-identity-resolved' | 'ide:user-identity-unresolved' | 'ide:attribution-ambiguous' | 'ide:pr-check-created' | 'ide:pr-check-passed' | 'ide:pr-check-failed' | 'ide:pr-check-neutral' | 'ide:api-version-mismatch' | 'ide:circuit-breaker-tripped';
/**
 * Represents the human user on whose behalf an AI IDE session is acting.
 *
 * Both `agent` identity (the AI session ID) and `initiatingUser` are
 * captured; neither is inferred from the other. Every governance audit event
 * emits both.
 *
 * Anonymous sessions require `allowAnonymousIdeSessions: true` in
 * `IdeAdapterConfig`. Default is false (fail-closed per AC 22).
 */
export interface UserIdentity {
    userId: string;
    githubLogin?: string;
    email?: string;
    orgId?: string;
    /**
     * How the identity was resolved. Determines trust level and audit detail.
     * 'session-env'      -- CLAUDE_SESSION_USER env var (Claude Code)
     * 'session-file'     -- .claude/session.json file (Claude Code fallback)
     * 'github-webhook'   -- GitHub event payload (Copilot Workspace)
     * 'continue-config'  -- Continue.dev config userId (Continue.dev)
     * 'cursor-composer'  -- Cursor composer session attribution (Cursor)
     */
    attributionMethod: 'session-env' | 'session-file' | 'github-webhook' | 'continue-config' | 'cursor-composer';
}
export interface IdeSessionHandle {
    /** Opaque session identifier, unique per adapter instance */
    sessionId: string;
    /** ISO-8601 timestamp when the session was opened */
    openedAt: string;
    /** Additional session-scoped metadata for this adapter */
    metadata?: Record<string, unknown>;
}
export interface IdeSessionContext {
    /** Client-supplied session identifier (Cursor composerSessionId, etc.) */
    clientSessionId?: string;
    /** Working directory path for the IDE session */
    workspacePath?: string;
    /** User-supplied or pre-resolved identity (adapter may override) */
    identity?: Partial<UserIdentity>;
    /** Pass-through metadata */
    metadata?: Record<string, unknown>;
}
export interface ToolInvocationContext {
    /** Tool name (e.g. 'Edit', 'Bash', 'Read') */
    tool: string;
    /** Tool input parameters */
    input: Record<string, unknown>;
    /** Session handle this invocation belongs to */
    sessionHandle: IdeSessionHandle;
    /** Resolved user identity for audit attribution */
    initiatingUser: UserIdentity;
    /** ISO-8601 timestamp */
    timestamp: string;
    /** IDE-specific metadata (hook type, PID, etc.) */
    ideMetadata?: Record<string, unknown>;
}
export interface ToolResult {
    success: boolean;
    /** Brief summary of the output (never raw secrets) */
    outputSummary: string;
    durationMs?: number;
    error?: string;
}
export type ToolDecisionType = 'ALLOW' | 'DENY' | 'REQUIRE_APPROVAL';
export interface ToolInvocationDecision {
    decision: ToolDecisionType;
    reason: string;
    /** Approval ticket ID when decision is REQUIRE_APPROVAL */
    approvalTicketId?: string;
    metadata?: Record<string, unknown>;
}
export interface ReviewerRoutingResult {
    routed: boolean;
    reviewerId?: string;
    tier?: string;
    ticketId?: string;
    reason: string;
}
export interface IdeAdapterCapabilities {
    /** Supports per-tool runtime interception (PreToolUse / PostToolUse hooks) */
    runtimeHooks: boolean;
    /** Supports PR-boundary enforcement (GitHub App diff evaluation) */
    prBoundary: boolean;
    /** Supports user-identity attribution */
    userIdentity: boolean;
    /** Supports reviewer routing for REQUIRE_APPROVAL decisions */
    reviewerRouting: boolean;
    /** Adapter integration mode (IDE-specific) */
    integrationMode?: string;
}
export interface IdeAdapterConfig {
    /** Compliance pack binding (required -- fail closed without this) */
    packId: string;
    /**
     * Allow sessions with no resolvable user identity.
     * Default: false (fail-closed per AC 22 and Thomas philosophy).
     * Must be explicitly true to permit anonymous sessions.
     */
    allowAnonymousIdeSessions?: boolean;
    /** Path to .claude/session.json (Claude Code only; default: '.claude/session.json') */
    sessionFilePath?: string;
    /** Integration mode for adapters with multiple modes (Cursor) */
    integrationMode?: string;
    /** IDE-specific options */
    options?: Record<string, unknown>;
}
export interface PrDiffContext {
    prUrl: string;
    prNumber: number;
    repositoryFullName: string;
    /** Human on whose behalf Copilot Workspace (or similar) acted */
    initiatingUser?: UserIdentity;
    /** Unified diff string */
    diff: string;
    /** PR commit SHA */
    headSha: string;
    metadata?: Record<string, unknown>;
}
export type PrCheckStatus = 'passed' | 'failed' | 'neutral';
export interface PrCheckDecision {
    status: PrCheckStatus;
    reason: string;
    /** Check-run ID returned by GitHub API */
    checkRunId?: string;
    violations?: Array<{
        rule: string;
        detail: string;
    }>;
}
export interface IdeAdapter {
    /** Unique adapter identifier (e.g. 'claude-code', 'cursor') */
    readonly adapterId: string;
    /** Canonical IDE identifier (e.g. 'claude-code', 'cursor', 'copilot-workspace') */
    readonly ideId: string;
    /**
     * Initialize the adapter with config and bind a policy pack.
     * Throws `IdeSessionError` if called without a packId in config.
     * No default pack is loaded. No neutral-pass. (AC 28)
     */
    initialize(config: IdeAdapterConfig): void;
    /**
     * Intercept a tool invocation before it executes.
     * Returns ALLOW, DENY, or REQUIRE_APPROVAL.
     * Adapters that do not support runtime hooks throw IdeUnsupportedError.
     */
    interceptToolInvocation(ctx: ToolInvocationContext): Promise<ToolInvocationDecision>;
    /**
     * Record the result of an executed tool invocation (PostToolUse equivalent).
     * Used for audit-chain completion and post-hoc policy evaluation.
     */
    recordToolResult(ctx: ToolInvocationContext, result: ToolResult): Promise<void>;
    openSession(ctx: IdeSessionContext): Promise<IdeSessionHandle>;
    closeSession(handle: IdeSessionHandle): Promise<void>;
    /**
     * Resolve the human user identity for this session.
     * Throws `IdeAttributionError` on failure unless allowAnonymousIdeSessions
     * is true in config.
     */
    resolveUserIdentity(session: IdeSessionContext): Promise<UserIdentity>;
    /**
     * Route a REQUIRE_APPROVAL tool decision to the appropriate reviewer tier.
     */
    routeToolToReviewer(tool: string, ctx: ToolInvocationContext, tier: ReviewerTier): Promise<ReviewerRoutingResult>;
    /**
     * Translate a raw IDE-native exception into a typed IdeAdapterError subclass.
     * No raw Error escapes the adapter.
     */
    translateError(raw: unknown): IdeAdapterError;
    getIdeCapabilities(): IdeAdapterCapabilities;
}
export interface PrBoundaryEnforcer {
    evaluatePrDiff(ctx: PrDiffContext): Promise<PrCheckDecision>;
    postCheckRun(ctx: PrDiffContext, decision: PrCheckDecision): Promise<void>;
}
import type { ReviewerTier } from './reviewer-tier';
export type { ReviewerTier } from './reviewer-tier';
/**
 * Base error for all IDE adapter errors.
 * Extends LlmProviderError so the error hierarchy is unified:
 *   LlmProviderError -> IdeAdapterError -> (subclasses)
 *
 * No raw Error escapes any adapter. Every catch block calls translateError().
 */
export declare class IdeAdapterError extends LlmProviderError {
    readonly ideId: string;
    constructor(opts: {
        message: string;
        code: string;
        ideId: string;
        adapterId: string;
        raw?: unknown;
    });
}
/**
 * The IDE does not support the requested operation or integration surface.
 * Adapters throw this instead of returning null/undefined for unsupported methods.
 *
 * `.surface` describes which method or IDE surface is unsupported.
 */
export declare class IdeUnsupportedError extends IdeAdapterError {
    readonly surface: string;
    constructor(opts: {
        message: string;
        ideId: string;
        adapterId: string;
        surface: string;
        raw?: unknown;
    });
}
/**
 * User identity could not be resolved and anonymous sessions are not permitted.
 * Thrown at initialize time (fail-closed) when identity resolution fails.
 */
export declare class IdeAttributionError extends IdeAdapterError {
    constructor(opts: {
        message: string;
        ideId: string;
        adapterId: string;
        raw?: unknown;
    });
}
/**
 * PR-boundary enforcement failure (Copilot Workspace adapter).
 * `.prUrl` and `.checkRunId` are optional because the error may fire before
 * a check-run is created.
 */
export declare class PrBoundaryEnforcementError extends IdeAdapterError {
    readonly prUrl?: string;
    readonly checkRunId?: string;
    constructor(opts: {
        message: string;
        ideId: string;
        adapterId: string;
        prUrl?: string;
        checkRunId?: string;
        raw?: unknown;
    });
}
/**
 * Session lifecycle error (initialize without policy pack, session not found, etc.)
 */
export declare class IdeSessionError extends IdeAdapterError {
    constructor(opts: {
        message: string;
        ideId: string;
        adapterId: string;
        raw?: unknown;
    });
}
//# sourceMappingURL=index.d.ts.map