import { z } from 'zod';
import type { ActorRef, CapabilityDescriptor, CapabilitySurface, GatewayScope } from '@xopcai/gateway-contract';
export { CapabilityError } from './errors.js';
/** Constructed by a trusted entry point, never parsed from tool or HTTP input. */
export interface CapabilityContext {
    principalId: string;
    surface: CapabilitySurface;
    scopes: readonly GatewayScope[];
    allowedCapabilities?: readonly string[];
    authorize: (id: string, input: unknown) => boolean | Promise<boolean>;
    signal?: AbortSignal;
    /** Synchronous lease/grant guard immediately before domain execution or receipt replay. */
    assertCurrent?: () => void;
    actor?: ActorRef;
    /** Active conversation supplied by the trusted Agent runtime. */
    conversationId?: string;
}
export interface ReadCapability<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> {
    id: string;
    majorVersion: number;
    description: string;
    effect: 'read';
    surfaces: readonly CapabilitySurface[];
    scopes: readonly GatewayScope[];
    input: I;
    output: O;
    execute: (input: z.output<I>, context: CapabilityContext) => z.input<O> | Promise<z.input<O>>;
}
export declare function defineReadCapability<I extends z.ZodType, O extends z.ZodType>(definition: ReadCapability<I, O>): ReadCapability<I, O>;
export interface AtomicCapability<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> extends Omit<ReadCapability<I, O>, 'effect' | 'execute'> {
    effect: 'local-write';
    /** Bind receipts to trusted domain ownership that is not supplied in the public input. */
    requestScope?: (context: CapabilityContext) => string;
    /** Read-only asynchronous validation, skipped for committed receipt replay. Never perform effects here. */
    prepare?: (input: z.output<I>, context: CapabilityContext) => void | Promise<void>;
    execute: (input: z.output<I>, context: CapabilityContext & {
        operationId: string;
        idempotencyKey: string;
    }) => z.input<O>;
    afterCommit?: (result: z.output<O>, input: z.output<I>) => void | Promise<void>;
}
export declare function defineAtomicCapability<I extends z.ZodType, O extends z.ZodType>(definition: AtomicCapability<I, O>): AtomicCapability<I, O>;
export interface ExternalCapability<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> extends Omit<ReadCapability<I, O>, 'effect' | 'execute'> {
    effect: 'external-write';
    recovery: 'manual' | 'provider-idempotent';
    requestScope?: (context: CapabilityContext) => string;
    /** Provider-idempotent implementations must send operationId as the provider key. */
    execute: (input: z.output<I>, context: CapabilityContext & {
        operationId: string;
        idempotencyKey: string;
    }) => Promise<z.input<O>>;
}
export declare function defineExternalCapability<I extends z.ZodType, O extends z.ZodType>(definition: ExternalCapability<I, O>): ExternalCapability<I, O>;
type CapabilityDefinition<I extends z.ZodType = z.ZodType, O extends z.ZodType = z.ZodType> = ReadCapability<I, O> | AtomicCapability<I, O> | ExternalCapability<I, O>;
/** Stable JSON encoding for contract digests; rejects non-JSON values. */
export declare function canonicalCapabilityJson(value: unknown): string;
export declare class CapabilityDispatcher {
    private readonly entries;
    register<I extends z.ZodType, O extends z.ZodType>(definition: CapabilityDefinition<I, O>): void;
    private visible;
    list(context: CapabilityContext): CapabilityDescriptor[];
    describe(id: string, context: CapabilityContext): CapabilityDescriptor;
    validateInput(id: string, input: unknown, context: CapabilityContext): Promise<unknown>;
    call(id: string, input: unknown, context: CapabilityContext, expected?: {
        majorVersion: number;
        descriptorDigest: string;
        idempotencyKey?: string;
    }): Promise<unknown>;
    private validateResult;
}