import { XPHandle, XPFsApi, XPWindowsApi } from '../components/XPBridge';
import { XPSnapshot } from '../snapshot';
import { ScopedHandleConfig } from './types';
/** The subset of XPHandle exposed through the scoped facade. */
export interface ScopedXPHandle {
    fs: Pick<XPFsApi, 'readFile' | 'getNode' | 'exists' | 'writeFile' | 'createFile' | 'deleteFile' | 'unlockNode'>;
    windows: Pick<XPWindowsApi, 'list' | 'focus' | 'minimize' | 'maximize' | 'restore'>;
    openApp: (appId: string, props?: Record<string, unknown>) => string | null;
    openFile: (path: string[]) => string | null;
    notify: (options: Parameters<XPHandle['notify']>[0]) => string;
    sound: {
        play: (name: string) => void;
    };
    getSnapshot: () => XPSnapshot | undefined;
    describe: () => ScopedDescription;
    /** The concrete set of capabilities this handle was granted. */
    capabilities: ReadonlySet<string>;
}
/** Compact, model-friendly world summary. */
export interface ScopedDescription {
    focusedWindow: string | null;
    windows: ScopedWindowInfo[];
    desktop: ScopedDesktopItem[];
    recentEvents?: unknown[];
    flags?: Record<string, unknown>;
}
export interface ScopedWindowInfo {
    id: string;
    appId: string;
    title: string;
    isMinimized: boolean;
    isMaximized: boolean;
}
export interface ScopedDesktopItem {
    name: string;
    type: string;
    icon?: string;
}
/**
 * Create a capability-scoped facade over an {@link XPHandle}.
 *
 * Every method is always present on the returned handle. Calling an
 * ungranted method emits `agent:denied` and returns a safe default (or
 * throws if `onDenied: 'throw'`). Calling a granted method emits
 * `agent:call` with timing.
 */
export declare function createScopedHandle(handle: XPHandle, config: ScopedHandleConfig): ScopedXPHandle;
/** Thrown when a scoped call is denied and `onDenied` is `'throw'`. */
export declare class AgentDeniedError extends Error {
    readonly cap: string;
    readonly method: string;
    constructor(cap: string, method: string);
}
/** Thrown when a scoped call exceeds the rate limit and `onDenied` is `'throw'`. */
export declare class AgentRateLimitError extends Error {
    constructor();
}