@medeo-plugin/sdk 0.0.0-stage → 0.8.0

package/dist/index.d.ts

@@ -0,0 +1,891 @@
+import type { JsonValue } from './generated.ts';
+import type { MethodName } from './registry.ts';
+export { METHODS, LIMITS, type MethodName } from './registry.ts';
+/** One SDK for both runtimes: a sandboxed worker/window, and a `runtime: "node"`
+ * plugin, whose bootstrap installs the same `medeoPlugin` surface. The SDK itself
+ * imports nothing from Node and asserts no identity of its own. */
+export type { Manifest, PluginCommand, Permission, CapabilityDescriptor } from './generated.ts';
+/** The `api_version` this SDK targets; `spec/api-v1.json` carries the same number. */
+export declare const API_VERSION = 1;
+export interface PluginAPI {
+    onLocaleChanged(callback: (state: PluginLocaleState) => void): () => void;
+    onEvent(callback: (event: PlatformEvent) => void): () => void;
+    post(message: unknown): Promise<void>;
+    onMessage(callback: (message: unknown) => void): () => void;
+    invoke(method: MethodName, args?: Record<string, unknown>): Promise<unknown>;
+    run(command: string, args?: JsonValue): Promise<unknown>;
+}
+declare global {
+    var medeoPlugin: PluginAPI;
+    interface Window {
+        medeoPlugin: PluginAPI;
+    }
+}
+/** Pushed by the Host: an operation changed status (or streamed progress), or a
+ * plugin-owned queue has entries to pull. Events carry no payload data. */
+export type PlatformEvent = {
+    type: 'operation';
+    id: string;
+    method: string;
+    status: string;
+    revision?: number;
+} | {
+    type: 'signal';
+    channel: 'files.watch' | 'server' | 'input_method' | 'background' | 'permissions' | 'config' | 'shortcuts' | 'tray';
+};
+/** Messages between this plugin's background worker and its own windows
+ * (64 KiB each, JSON). A worker message reaches every open window; a window
+ * message reaches the worker. Nothing is persisted or sent elsewhere. */
+export declare const channel: {
+    post: (message: unknown) => Promise<void>;
+    onMessage: <T = unknown>(callback: (message: T) => void) => () => void;
+};
+export declare const events: {
+    on: (callback: (event: PlatformEvent) => void) => () => void;
+    /** Call `pull` now and again whenever the channel signals new entries. A
+     * failed pull (e.g. a permission withdrawn meanwhile) waits for the next signal. */
+    onSignal(channel: Extract<PlatformEvent, {
+        type: "signal";
+    }>["channel"], pull: () => unknown): () => void;
+};
+export declare const storage: {
+    get: <T = unknown>(key: string) => Promise<T | null>;
+    remove: (key: string) => Promise<unknown>;
+    set: (key: string, value: unknown) => Promise<unknown>;
+};
+export declare const creation: {
+    open: () => Promise<unknown>;
+};
+export declare const commands: {
+    run: <T = unknown>(command: string, args?: JsonValue) => Promise<T>;
+};
+export interface Disposable {
+    dispose(): unknown;
+}
+/** Passed to `activate` (VS Code style), in both runtimes. */
+export interface PluginContext {
+    /** Disposed, in reverse order, when the plugin stops. */
+    subscriptions: Disposable[];
+    /** Register a handler for each command the manifest declares; all must be registered when `activate` returns. */
+    commands: {
+        register(id: string, handler: (args?: JsonValue) => unknown | Promise<unknown>): Disposable;
+    };
+    /** `runtime: "node"` only: the installed, verified package directory (read-only). */
+    extensionPath?: string;
+    /** `runtime: "node"` only: a private writable directory that survives updates. */
+    storagePath?: string;
+}
+/** A plugin's background entry: export the result, e.g.
+ * `export const { activate, deactivate } = definePlugin({ activate(context) { … } })`. */
+export interface PluginDefinition {
+    activate(context: PluginContext): unknown | Promise<unknown>;
+    deactivate?(): unknown | Promise<unknown>;
+}
+export declare function definePlugin(definition: PluginDefinition): Required<PluginDefinition>;
+/** Settings declared under `contributes.configuration`; the user edits them in the plugin center. */
+export declare const config: {
+    get: <T = unknown>(key: string) => Promise<T>;
+    all: () => Promise<Record<string, unknown>>;
+    set: (key: string, value: unknown) => Promise<unknown>;
+    /** Calls `listener` with all values after each change, from the user or the plugin. */
+    onDidChange(listener: (values: Record<string, unknown>) => void): () => void;
+};
+/** Native providers return quickly; subscribe to progress instead of holding a command open. */
+export interface Provider {
+    id: string;
+    version: number;
+    available: boolean;
+    capabilities: string[];
+}
+/** `full`: the user approved full access (view and direct Trash) for this directory. */
+export interface Resource {
+    id: string;
+    name: string;
+    available: boolean;
+    full?: boolean;
+}
+/** Ask for full access (requires the `file_full_access` permission). */
+export interface DirectoryAccess {
+    full?: boolean;
+}
+export declare const providers: {
+    list: () => Promise<Provider[]>;
+    require: (id: string, version?: number) => Promise<Provider>;
+};
+export declare const resources: {
+    chooseDirectories: (access?: DirectoryAccess) => Promise<Resource[]>;
+    list: () => Promise<Resource[]>;
+    revoke: (id: string) => Promise<Resource[]>;
+    requestDirectory: (path: string, reason: string, access?: DirectoryAccess) => Promise<Resource[]>;
+};
+/** Generic registered-provider entry point; the Host remains the authority. */
+export declare const capabilities: {
+    list: () => Promise<import("./generated").CapabilityDescriptor[]>;
+    labels: () => Promise<Record<string, string>>;
+    invoke: <T = unknown>(method: string, args?: Record<string, unknown>) => Promise<T>;
+};
+export declare const clipboard: {
+    read: () => Promise<{
+        text: string;
+    }>;
+    write: (text: string) => Promise<unknown>;
+};
+/** `running` reports, per rule, whether a matching process exists; it never
+ * returns the process list. Rules match an exact executable name or a path fragment. */
+export interface ProcessRule {
+    name?: string;
+    path_contains?: string;
+}
+export interface SystemInfo {
+    platform: string;
+    architecture: string;
+    release: string;
+    locale: string; /** The Medeo running the plugin (0.1.23+; absent on older Medeo). */
+    medeo?: {
+        version: string;
+        channel: 'stg' | 'prd';
+    };
+    displays: {
+        id: string;
+        bounds: {
+            x: number;
+            y: number;
+            width: number;
+            height: number;
+        };
+        scale: number;
+    }[];
+}
+export declare const system: {
+    info: () => Promise<SystemInfo>;
+    running: (rules: ProcessRule[]) => Promise<NativeOperation<boolean[]>>;
+};
+/** One outcome per path of `trash`, in the order given. */
+export interface TrashResult {
+    path: string;
+    trashed: boolean;
+    error?: string;
+}
+/** `runtime: "node"` plugins only (the `node` permission): moves up to 256 absolute
+ * paths to the OS Trash, the one thing Node cannot do itself. A failure does not stop the rest. */
+export declare const trash: (paths: string[]) => Promise<TrashResult[]>;
+export declare const notifications: {
+    show: (id: string, title: string, body: string) => Promise<unknown>;
+    close: (id: string) => Promise<unknown>;
+};
+export declare const power: {
+    start: (type: "prevent-app-suspension" | "prevent-display-sleep") => Promise<{
+        id: string;
+    }>;
+    stop: (id: string) => Promise<unknown>;
+    state: () => Promise<unknown>;
+};
+export declare const shortcuts: {
+    list: () => Promise<{
+        id: string;
+        accelerator: string;
+        open_ui: boolean;
+    }[]>;
+    register: (id: string, accelerator: string, openUI?: boolean) => Promise<unknown>;
+    unregister: (id: string) => Promise<unknown>;
+    events: () => Promise<unknown>;
+};
+/** `panel: true` (macOS): a frameless window floating over every app and Space that does not
+ * activate Medeo — the app the user was in keeps focus — opened at the pointer and hidden (not
+ * closed) when it loses focus; opening it again moves it to the pointer. `hide` keeps a window
+ * and its page alive for the next `open`/`focus`. */
+export declare const appWindows: {
+    open: (options: {
+        id: string;
+        entry: string;
+        title: string;
+        width: number;
+        height: number;
+        panel?: boolean;
+    }) => Promise<unknown>;
+    close: (id: string) => Promise<unknown>;
+    focus: (id: string) => Promise<unknown>;
+    hide: (id: string) => Promise<unknown>;
+    list: () => Promise<{
+        id: string;
+        title: string;
+        visible: boolean;
+    }[]>;
+};
+/** A menu entry, a checkmarked toggle, or a divider. */
+export type TrayItem = {
+    id: string;
+    title: string;
+    checked?: boolean;
+} | {
+    separator: true;
+};
+/** `icon`: a PNG in the package drawn as a menu-bar template (black + alpha, about 36 px tall);
+ *  `click`: an id reported on a left click, which then leaves the menu to a right click. */
+export interface TrayOptions {
+    icon?: string;
+    click?: string;
+}
+export declare const tray: {
+    set: (title: string, items: TrayItem[], options?: TrayOptions) => Promise<unknown>;
+    remove: () => Promise<unknown>;
+    events: () => Promise<unknown>;
+};
+export declare const external: {
+    open: (url: string) => Promise<unknown>;
+};
+/** `scope` says how long an approval lasts: `always` (stored), `run` (until the plugin stops),
+ * `never` (refused with "don't ask again"). `remembered`: refused earlier, no dialog was shown. */
+export interface PermissionAnswer {
+    granted: boolean;
+    scope?: 'always' | 'run' | 'never' | 'none';
+    remembered?: boolean;
+}
+export declare const permissions: {
+    request: (permission: string, reason: string) => Promise<PermissionAnswer>;
+};
+/** One of the plugin's own actions for the user to approve (`approvals` permission; `action` must be declared).
+ * `rule_key` identifies it (`bash:git status`); `rule_pattern` (a prefix of it ending in `*`) is what
+ * "always" remembers instead. Medeo draws the dialog and keeps the rules. In a Node plugin nothing
+ * forces you to ask: it is up to the plugin to call this before acting. */
+export interface ApprovalRequest {
+    action: string;
+    title: string;
+    detail?: string;
+    preview?: {
+        kind: 'text' | 'command' | 'diff';
+        text: string;
+    };
+    rule_key: string;
+    rule_pattern?: string;
+}
+/** `scope`: `once`, `run`, `always`, or `rule` when a remembered answer decided without a dialog. */
+export interface ApprovalAnswer {
+    decision: 'allow' | 'deny';
+    scope: 'once' | 'run' | 'always' | 'rule';
+    rule?: string;
+}
+export interface ApprovalRule {
+    action: string;
+    pattern: string;
+    allow: boolean;
+    scope: 'run' | 'always';
+}
+export declare const approvals: {
+    request: (request: ApprovalRequest) => Promise<ApprovalAnswer>;
+    rules: () => Promise<ApprovalRule[]>;
+    forget: (action: string, pattern: string) => Promise<ApprovalRule[]>;
+};
+export interface AgentJob {
+    id: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    text?: string;
+    models?: string[];
+    error?: string | null;
+}
+export declare const agent: {
+    models: () => Promise<AgentJob>;
+    start: (messages: {
+        role: "system" | "user" | "assistant";
+        content: string;
+    }[], model?: string) => Promise<AgentJob>;
+    state: (id: string) => Promise<AgentJob>;
+    cancel: (id: string) => Promise<AgentJob>;
+    release: (id: string) => Promise<unknown>;
+    /** Calls `onText` as the reply streams in; resolves with the final job. */
+    follow(id: string, onText: (job: AgentJob) => void): Promise<AgentJob>;
+};
+export interface ApplicationEntry {
+    id: string;
+    title: string;
+    path: string;
+    bundle_id: string;
+}
+export interface ApplicationList {
+    status: string;
+    error: string | null;
+    incomplete: boolean;
+    total: number;
+    entries: ApplicationEntry[];
+}
+export interface ApplicationState {
+    status: string;
+    error: string | null;
+    launch: {
+        id: string;
+        status: string;
+        error: string | null;
+        pid?: number;
+    } | null;
+}
+export declare const applications: {
+    /** The whole inventory; plugins rank and filter it themselves. */
+    list: (refresh?: boolean) => Promise<ApplicationList>;
+    launch: (id: string) => Promise<{
+        id: string;
+        status: string;
+    }>;
+    state: () => Promise<ApplicationState>;
+};
+export interface CaptureSource {
+    id: string;
+    title: string;
+    width: number;
+    height: number;
+}
+export interface CaptureRecord {
+    id: string;
+    source_title: string;
+    status: string;
+    active: boolean;
+    can_stop: boolean;
+    can_recover: boolean;
+    error?: string | null;
+    playable: boolean;
+    duration_ms: number;
+    bytes: number;
+    microphone: boolean;
+    system_audio: boolean;
+    audio_tracks?: number;
+}
+export declare const capture: {
+    status: (refresh?: boolean) => Promise<{
+        status: string;
+        os: Record<string, string>;
+    }>;
+    sources: (refresh?: boolean, requestPermission?: boolean) => Promise<{
+        status: string;
+        error?: string;
+        os: Record<string, string>;
+        sources: CaptureSource[];
+    }>;
+    start: (source: string, options?: {
+        microphone?: boolean;
+        systemAudio?: boolean;
+    }) => Promise<{
+        id?: string;
+        cancelled?: boolean;
+    }>;
+    state: () => Promise<{
+        records: CaptureRecord[];
+        os: Record<string, string>;
+    }>;
+    stop: (id: string) => Promise<unknown>;
+    cancel: (id: string) => Promise<unknown>;
+    recover: (id: string) => Promise<unknown>;
+    open: (id: string, mode?: "play" | "reveal") => Promise<unknown>;
+    previewURL: (id: string) => string;
+};
+export interface InputMethodState {
+    enabled: boolean;
+    provider_ready: boolean;
+    configured_name: string;
+    occupied: boolean;
+    system_source: string;
+}
+export interface InputSourceState {
+    status: string;
+    state_key: string;
+    can_setup: boolean;
+    can_remove: boolean;
+    installed?: boolean;
+    registered?: boolean;
+    enabled?: boolean;
+    selected?: boolean;
+    update_available?: boolean;
+    error?: string;
+    last_operation?: {
+        id: string;
+        status: string;
+        error?: string;
+    };
+    task?: string;
+}
+export declare const inputMethod: {
+    system: (refresh?: boolean) => Promise<InputSourceState>;
+    setup: () => Promise<{
+        task?: string;
+        cancelled?: boolean;
+    }>;
+    remove: () => Promise<{
+        task?: string;
+        cancelled?: boolean;
+    }>;
+    settings: () => Promise<{
+        task: string;
+    }>;
+    status: () => Promise<InputMethodState>;
+    configure: (name: string) => Promise<unknown>;
+    enable: () => Promise<InputMethodState>;
+    disable: () => Promise<unknown>;
+    events: () => Promise<{
+        id: string;
+        text: string;
+    }[]>;
+    respond: (id: string, candidates: string[]) => Promise<unknown>;
+};
+/** HTTP uses only approved origins; no redirects, browser cookies, or Medeo credentials.
+ * Closing UI preserves jobs; disable/revoke cancels. Mutations are never replayed.
+ * Release completed results to return the per-instance memory quota.
+ */
+export interface NetworkRequest {
+    url: string;
+    method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE' | 'OPTIONS';
+    headers?: Record<string, string>;
+    body?: string;
+    body_base64?: string;
+    timeout_ms?: number;
+    stream?: boolean;
+}
+export interface NetworkJob {
+    id: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    received?: number;
+    http_status?: number | null;
+    headers?: [string, string][];
+    error?: string | null;
+    stream?: boolean;
+}
+export interface NetworkChunk {
+    data_base64: string;
+    next_offset: number;
+    eof: boolean;
+}
+export interface NetworkOrigin {
+    origin: string;
+    declared: boolean;
+    allowed: boolean;
+}
+export interface NetworkServerEvent {
+    data: string;
+    event: string;
+    id: string;
+    retry?: number;
+}
+export declare const network: {
+    origins: () => Promise<NetworkOrigin[]>;
+    requestOrigin: (origin: string, reason: string) => Promise<{
+        origin: string;
+        granted: boolean;
+    }>;
+    revokeOrigin: (origin: string) => Promise<NetworkOrigin[]>;
+    request: (request: NetworkRequest) => Promise<NetworkJob>;
+    state: (id: string) => Promise<NetworkJob>;
+    read: (id: string, offset?: number, length?: number) => Promise<NetworkChunk>;
+    cancel: (id: string) => Promise<NetworkJob>;
+    release: (id: string) => Promise<{
+        released: boolean;
+    }>;
+    /** Resolves once the response has fully arrived; the job stays readable until released. */
+    settled(id: string): Promise<NetworkJob>;
+    /** Single consumer for a stream:true job. Break/throw/abort cancels and releases it. */
+    bytes(id: string, signal?: AbortSignal): AsyncGenerator<Uint8Array>;
+    /** Incremental UTF-8 decoder, including code points split across HTTP chunks. */
+    textStream(id: string, signal?: AbortSignal): AsyncGenerator<string>;
+    /** SSE framing only: no automatic reconnect/retry or Last-Event-ID requests. */
+    sse(id: string, signal?: AbortSignal): AsyncGenerator<NetworkServerEvent>;
+    /** Explicitly dispose a stream that was never iterated (or has another owner). */
+    dispose(id: string): Promise<void>;
+    text(id: string): Promise<string>;
+};
+/** Workspace operations use current directory references and asynchronous jobs. */
+export interface FileRoot {
+    id: string | null;
+    name: string;
+    available: boolean;
+    error?: string;
+}
+export interface FileEntry {
+    path: string;
+    name: string;
+    kind: 'file' | 'directory' | 'blocked';
+    size: number;
+    revision: string;
+    accessible: boolean;
+}
+export interface FileRecord {
+    id: string;
+    operation: string;
+    source: string;
+    destination: string;
+    status: string;
+    has_original: boolean;
+    in_trash?: boolean | null;
+    created_ms: number | null;
+    retention: "workspace" | "trash" | "none" | "unknown";
+}
+export interface FileJob<T = unknown> {
+    id: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled';
+    result: T | null;
+    error: string | null;
+    method?: string;
+}
+export interface FileWatch {
+    id: string;
+    status: 'starting' | 'watching' | 'stopped' | 'failed';
+    cursor?: number;
+    error?: string | null;
+}
+export interface FileWatchEvents extends FileWatch {
+    cursor: number;
+    rescan_required: boolean;
+    events: {
+        cursor: number;
+        kind: 'ready' | 'created' | 'changed' | 'removed' | 'rescan_required';
+        path: string | null;
+    }[];
+}
+export interface FilePreview {
+    id: string;
+    path: string;
+    bytes: number;
+    count: number;
+    revision: string | null;
+    purpose: string;
+    record: string | null;
+}
+export interface FileHistoryPage {
+    items: FileRecord[];
+    next_cursor: string | null;
+    total: number;
+}
+export declare const files: {
+    backupPreview: (root: string, record: string) => Promise<FileJob<FilePreview>>;
+    archiveBackup: (preview: string) => Promise<FileJob<FileRecord>>;
+    forgetPreview: (root: string, record: string) => Promise<FileJob<FilePreview>>;
+    forgetRecord: (preview: string) => Promise<FileJob<{
+        forgotten: string;
+    }>>;
+    historyPage: (root: string, cursor?: string, limit?: number) => Promise<FileJob<FileHistoryPage>>;
+    trashPreview: (root: string, path: string) => Promise<FileJob<FilePreview>>;
+    discardPreview: (preview: string) => Promise<{
+        discarded: boolean;
+    }>;
+    trash: (preview: string) => Promise<FileJob<FileRecord>>;
+    /** Breadth-first listings of a whole tree in one call. Hidden and `skip`
+     * directories are listed by their parent but not entered. */
+    listTree: (root: string, path?: string, options?: {
+        depth?: number;
+        skip?: string[];
+        hidden?: boolean;
+        limit?: number;
+    }) => Promise<FileJob<{
+        directories: {
+            path: string;
+            entries?: FileEntry[];
+            error?: string;
+        }[];
+        truncated: boolean;
+    }>>;
+    /** Full-access roots only: move entries to the Trash without a Host confirmation.
+     * `stamp` is what `files.measure` returned; a changed entry is refused, not moved. */
+    trashDirect: (items: {
+        root: string;
+        path: string;
+        stamp: {
+            revision: string;
+            digest: string;
+            bytes: number;
+            count: number;
+        };
+    }[]) => Promise<FileJob<{
+        path: string;
+        record?: FileRecord;
+        error?: string;
+    }[]>>;
+    watch: (root: string, path?: string, recursive?: boolean) => Promise<FileWatch>;
+    watches: () => Promise<FileWatch[]>;
+    events: (id: string, after?: number) => Promise<FileWatchEvents>;
+    unwatch: (id: string) => Promise<{
+        stopped: boolean;
+    }>;
+    roots: () => Promise<FileJob<FileRoot[]>>;
+    list: (root: string, path?: string) => Promise<FileJob<FileEntry[]>>;
+    stat: (root: string, path?: string) => Promise<FileJob<FileEntry>>;
+    readText: (root: string, path: string, revision?: string) => Promise<FileJob<{
+        text: string;
+        entry: FileEntry;
+    }>>;
+    writeText: (root: string, path: string, text: string, revision: string) => Promise<FileJob<{
+        record: FileRecord;
+        entry: FileEntry | null;
+    }>>;
+    mkdir: (root: string, path: string) => Promise<FileJob<FileEntry>>;
+    move: (root: string, path: string, destination: string, revision: string) => Promise<FileJob<FileRecord>>;
+    history: (root: string) => Promise<FileJob<FileRecord[]>>;
+    restore: (root: string, record: string) => Promise<FileJob<FileRecord>>;
+    state: <T = unknown>(id: string) => Promise<FileJob<T>>;
+    cancel: (id: string) => Promise<unknown>;
+    release: (id: string) => Promise<unknown>;
+    result: <T>(job: FileJob<T>) => Promise<T>;
+};
+/** Plugin-owned credentials. Values are returned only to this granted plugin;
+ * Agent/Medeo credentials are never part of this vault. No automatic retry. */
+export interface SecretOperation {
+    id: string;
+    status: 'running' | 'completed' | 'failed';
+    value?: string | null;
+    error?: string;
+}
+export declare const secrets: {
+    get: (key: string) => Promise<string | null>;
+    set: (key: string, value: string) => Promise<void>;
+    remove: (key: string) => Promise<void>;
+};
+export interface LocalServerOptions {
+    port?: number;
+    routes: {
+        method: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+        path: string;
+    }[];
+    origins?: string[];
+    timeout_ms?: number;
+}
+export interface LocalServerState {
+    id: string;
+    status: 'starting' | 'running' | 'stopping' | 'stopped' | 'failed';
+    origin: string | null;
+    error: string | null;
+    pending: number;
+    accepted: number;
+}
+export interface LocalRequest {
+    id: string;
+    method: string;
+    path: string;
+    query: string;
+    headers: Record<string, string>;
+    body_base64: string;
+}
+/** A loopback server is instance-owned and never survives Host restart. Keep the
+ * start token in private memory and serve requests in a worker for background use. */
+export declare const server: {
+    start: (options: LocalServerOptions) => Promise<{
+        id: string;
+        status: "starting";
+        access_token: string;
+    }>;
+    state: (id: string) => Promise<LocalServerState>;
+    list: () => Promise<LocalServerState[]>;
+    events: (id: string, limit?: number) => Promise<{
+        requests: LocalRequest[];
+    }>;
+    respond: (id: string, request: string, response: {
+        status?: number;
+        body_base64?: string;
+        content_type?: string;
+    }) => Promise<{
+        responded: boolean;
+    }>;
+    stop: (id: string) => Promise<LocalServerState>;
+};
+export interface PluginLocaleState {
+    preference: string;
+    locale: string;
+    system_locale: string;
+    direction: 'ltr';
+    supported_locales: string[];
+    catalog_locales: string[];
+    catalog_locale: string | null;
+    fallback_locale: string | null;
+    name: string;
+    commands: Record<string, string>;
+}
+/** Text is formatted in Rust from the signed package. Render with textContent,
+ * never innerHTML. Register listeners before initial state fetch to avoid races. */
+export declare const i18n: {
+    state: () => Promise<PluginLocaleState>;
+    setLocale: (preference: string) => Promise<PluginLocaleState>;
+    t: (key: string, params?: Record<string, string | number>) => Promise<string>;
+    /** Every message of the effective locale (default-locale fallback merged in). */
+    catalog: () => Promise<Record<string, string>>;
+    onDidChangeLocale: (callback: (state: PluginLocaleState) => void) => () => void;
+};
+/** Every asynchronous call returns an owned operation handle. Status changes
+ * are pushed; `wait` resolves on them and releases the result. */
+export interface NativeOperation<T = unknown> {
+    id: string;
+    status: 'running' | 'completed' | 'failed' | 'cancelled' | 'interrupted';
+    result: T | null;
+    error: string | null;
+}
+export declare const operations: {
+    state: <T = unknown>(id: string) => Promise<NativeOperation<T>>;
+    list: () => Promise<{
+        id: string;
+        method: string;
+        status: string;
+    }[]>;
+    cancel: (id: string) => Promise<unknown>;
+    release: (id: string) => Promise<unknown>;
+    wait<T>(operation: {
+        id: string;
+        status: string;
+    }, signal?: AbortSignal): Promise<T>;
+};
+/** A camera / microphone / system audio recording. `waveform` (240 peaks, 0…1) is in `state(id)` once
+ * completed; listings carry a 40-point `waveform_preview` instead. Live fields exist only while recording:
+ * `levels` holds the latest input levels (0…1, about 20 a second) and `levels_seq` counts every level so far;
+ * `frame` is the camera's latest preview as base64 JPEG. "completed" means `previewURL` can play it. */
+export interface MediaRecord {
+    id: string;
+    kind: 'camera' | 'microphone' | 'system_audio';
+    status: 'starting' | 'recording' | 'stopping' | 'completed' | 'failed' | 'interrupted';
+    error?: string | null;
+    created_ms: number;
+    extension: string;
+    duration_ms?: number;
+    bytes?: number;
+    waveform?: number[];
+    waveform_preview?: number[];
+    elapsed_ms?: number;
+    level?: number;
+    peak?: number;
+    levels?: number[];
+    levels_seq?: number;
+    frame?: string;
+}
+export declare const camera: {
+    status: () => Promise<NativeOperation<{
+        authorization: string;
+    }>>;
+    start: (maxSeconds?: number) => Promise<NativeOperation<{
+        id: string;
+        status: string;
+    }>>;
+    stop: (id: string) => Promise<NativeOperation<unknown>>;
+    state: (id?: string) => Promise<NativeOperation<unknown>>;
+    read: (id: string, offset?: number, length?: number) => Promise<NativeOperation<NetworkChunk>>;
+    /** Same-origin URL for an `<audio>` / `<video>` element; plays once the record is "completed". */
+    previewURL: (record: Pick<MediaRecord, "id" | "extension">) => string;
+}, microphone: {
+    status: () => Promise<NativeOperation<{
+        authorization: string;
+    }>>;
+    start: (maxSeconds?: number) => Promise<NativeOperation<{
+        id: string;
+        status: string;
+    }>>;
+    stop: (id: string) => Promise<NativeOperation<unknown>>;
+    state: (id?: string) => Promise<NativeOperation<unknown>>;
+    read: (id: string, offset?: number, length?: number) => Promise<NativeOperation<NetworkChunk>>;
+    /** Same-origin URL for an `<audio>` / `<video>` element; plays once the record is "completed". */
+    previewURL: (record: Pick<MediaRecord, "id" | "extension">) => string;
+}, systemAudio: {
+    status: () => Promise<NativeOperation<{
+        authorization: string;
+    }>>;
+    start: (maxSeconds?: number) => Promise<NativeOperation<{
+        id: string;
+        status: string;
+    }>>;
+    stop: (id: string) => Promise<NativeOperation<unknown>>;
+    state: (id?: string) => Promise<NativeOperation<unknown>>;
+    read: (id: string, offset?: number, length?: number) => Promise<NativeOperation<NetworkChunk>>;
+    /** Same-origin URL for an `<audio>` / `<video>` element; plays once the record is "completed". */
+    previewURL: (record: Pick<MediaRecord, "id" | "extension">) => string;
+};
+export declare const accessibility: {
+    status: () => Promise<NativeOperation<unknown>>;
+    request: () => Promise<NativeOperation<unknown>>;
+    windows: () => Promise<NativeOperation<{
+        id: string;
+        title: string;
+        application: string;
+    }[]>>;
+    focus: (id: string) => Promise<NativeOperation<unknown>>;
+    selectedText: (id: string) => Promise<NativeOperation<{
+        id: string;
+        text: string;
+    }>>;
+    insertText: (focus: string, text: string) => Promise<NativeOperation<unknown>>;
+};
+export declare const browserView: {
+    open: (id: string, url: string, width?: number, height?: number) => Promise<unknown>;
+    state: (id: string) => Promise<unknown>;
+    close: (id: string) => Promise<unknown>;
+};
+export declare const printing: {
+    print: (text: string) => Promise<unknown>;
+};
+export declare const processes: {
+    start: (executable: string, args?: string[], timeoutMs?: number) => Promise<NativeOperation<{
+        id: string;
+        status: string;
+    }>>;
+    state: (id: string) => Promise<NativeOperation<{
+        status: string;
+        exit_code: number | null;
+        stdout: string;
+        stderr: string;
+        truncated: boolean;
+    }>>;
+    write: (id: string, text: string) => Promise<NativeOperation<{
+        written: number;
+    }>>;
+    stop: (id: string) => Promise<NativeOperation<unknown>>;
+};
+export interface BackgroundEvent {
+    id: string;
+    schedule: string;
+    due_ms: number;
+    payload: JsonValue;
+}
+export declare const background: {
+    schedule: (id: string, delayMs: number, payload?: JsonValue, intervalMs?: number) => Promise<unknown>;
+    list: () => Promise<unknown>;
+    cancel: (id: string) => Promise<unknown>;
+    events: () => Promise<BackgroundEvent[]>;
+};
+export declare const contacts: {
+    status: () => Promise<NativeOperation<unknown>>;
+    request: () => Promise<NativeOperation<unknown>>;
+    list: (query?: string, limit?: number) => Promise<NativeOperation<unknown>>;
+    save: (contact: {
+        given_name: string;
+        family_name: string;
+        email: string;
+        phone: string;
+    }) => Promise<NativeOperation<{
+        id: string;
+        created: boolean;
+    }>>;
+};
+export declare const calendar: {
+    status: () => Promise<NativeOperation<unknown>>;
+    request: () => Promise<NativeOperation<unknown>>;
+    list: (startMs: number, endMs: number, limit?: number) => Promise<NativeOperation<unknown>>;
+    save: (event: {
+        title: string;
+        notes: string;
+        start_ms: number;
+        end_ms: number;
+    }) => Promise<NativeOperation<{
+        id: string;
+        created: boolean;
+    }>>;
+};
+export declare const deviceLocation: {
+    status: () => Promise<NativeOperation<unknown>>;
+    request: () => Promise<NativeOperation<unknown>>;
+    current: () => Promise<NativeOperation<{
+        latitude: number;
+        longitude: number;
+        accuracy_m: number;
+        timestamp_ms: number;
+    }>>;
+};
+export declare const devices: {
+    choose: (transport: "serial" | "hid" | "ble") => Promise<NativeOperation<unknown>>;
+    open: (id: string, baudRate?: number) => Promise<NativeOperation<unknown>>;
+    list: () => Promise<NativeOperation<unknown>>;
+    read: (id: string, length?: number) => Promise<NativeOperation<{
+        data_base64: string;
+        bytes: number;
+    }>>;
+    write: (id: string, dataBase64: string) => Promise<NativeOperation<{
+        written: number;
+    }>>;
+    close: (id: string) => Promise<NativeOperation<unknown>>;
+};