@neurosquad/card-sdk 1.0.0

package/dist/types/client/base64.d.ts

@@ -0,0 +1,7 @@
+/** Encodes bytes as standard base64. */
+export declare function bytesToBase64(bytes: Uint8Array): string;
+/** Decodes standard base64 into bytes. */
+export declare function base64ToBytes(base64: string): Uint8Array;
+/** Bytes from any binary body the SDK accepts. */
+export declare function toBytes(data: ArrayBuffer | ArrayBufferView): Uint8Array;
+export declare function isBinary(value: unknown): value is ArrayBuffer | ArrayBufferView;

package/dist/types/client/card.d.ts

@@ -0,0 +1,653 @@
+import { type AgentInfo, type CardEventName, type CardEvents, type CardInstanceInfo, type CardMethodName, type CardSize, type CardTone, type CardVisibility, type EventTopic, type FsEntry, type FsStat, type HostContext, type HostIconName, type I18nSnapshot, type JsonValue, type MenuItem, type MethodParams, type MethodResult, type OverviewContent, type PeerInfo, type PermissionId, type PermissionState, type PortInfo, type SettingsSnapshot, type SettingValue, type ThemeSnapshot, type ToolResultPayload, type UsageSummary, type WorkspaceInfo } from '../contract/index.js';
+import type { CallOptions, Channel } from './channel.js';
+import { CardResponse, ChunkQueue, type CardFetchInit } from './net.js';
+import { type ThemeTarget } from './theme.js';
+/** Arguments of `card.call(method, …)`: params are optional for parameterless methods. */
+export type CallArgs<M extends CardMethodName> = [MethodParams<M>] extends [void] ? [params?: Record<string, never> | null, options?: CallOptions] : [params: MethodParams<M>, options?: CallOptions];
+/** Handler of a host event. */
+export type EventHandler<E extends CardEventName> = (data: CardEvents[E]) => void;
+/** Removes a listener / handler / watcher. Calling it twice is harmless. */
+export type Unsubscribe = () => void;
+/** Widens literal types (`''` → `string`, `0` → `number`) so `get('k', '')` is a `string`. */
+export type Widen<T> = T extends string ? string : T extends number ? number : T extends boolean ? boolean : T;
+/** Scope of a storage call: this card on the canvas, or every card of the package. */
+export type StorageScope = 'instance' | 'package';
+/** What a tool handler may return; see {@link CardTools.handle}. */
+export type ToolReturn = string | ToolResultPayload | JsonValue | undefined | void;
+/** Context passed to a tool handler. */
+export interface ToolCall {
+    callId: string;
+    /** The tool's name as declared in the manifest. */
+    tool: string;
+    /** The agent calling it. */
+    agent: {
+        id: string;
+        name: string;
+    };
+    /** Epoch ms after which the host has given up. */
+    deadline: number;
+    /** Aborted when the host cancels the call (`tools.cancel`) or the deadline passes. */
+    signal: AbortSignal;
+    /** Shows a short progress line on the arrow (throttled by the host to 4/s). */
+    progress(message: string): void;
+}
+/** Handler registered with {@link CardTools.handle}. */
+export type ToolHandler<A = JsonValue> = (args: A, call: ToolCall) => ToolReturn | Promise<ToolReturn>;
+/** Context passed to a port request handler. */
+export interface PortRequest {
+    requestId: string;
+    /** Card id of the asker. */
+    from: string;
+    /** Our input port the request came in on. */
+    input: string;
+    deadline: number;
+    /** Aborted when the deadline passes. */
+    signal: AbortSignal;
+}
+/** Handler registered with {@link CardPorts.onRequest}. Return the reply, or throw to refuse. */
+export type PortRequestHandler<T = JsonValue> = (data: T, request: PortRequest) => JsonValue | Promise<JsonValue>;
+/** A menu item for {@link CardUi.setMenu}; `onSelect` stays in the card, it is not sent to the host. */
+export interface CardMenuItem extends MenuItem {
+    onSelect?: () => void;
+}
+/** Options of {@link Card}. Set through `connect()`. */
+export interface CardOptions {
+    /** Apply the app theme as `--ns-*` variables (and follow changes). `false` to skip; an element to target it. Default: `<html>`. */
+    theme?: boolean | ThemeTarget;
+    /** Keep `<html lang>` equal to the app language. Default true. */
+    syncLang?: boolean;
+    /** Forward uncaught errors and unhandled rejections to the host log. Default true. */
+    forwardErrors?: boolean;
+}
+/** Per-card key/value storage (JSON values, persisted by the host; see spec §8.4). */
+export interface ScopedStorage {
+    /** The stored value, or `fallback` (default `undefined`) when the key does not exist. */
+    get<T extends JsonValue = JsonValue>(key: string): Promise<T | undefined>;
+    get<T extends JsonValue = JsonValue>(key: string, fallback: T): Promise<Widen<T>>;
+    /** Stores a JSON value (≤ 1 MB). Writes are atomic in the host. */
+    set(key: string, value: JsonValue): Promise<void>;
+    delete(key: string): Promise<void>;
+    /** Keys, optionally only those starting with `prefix`. */
+    keys(prefix?: string): Promise<string[]>;
+    clear(): Promise<void>;
+    /** Bytes used, the quota and the key count. */
+    usage(): Promise<{
+        bytes: number;
+        quota: number;
+        keys: number;
+    }>;
+}
+/** `card.storage`: instance-scope storage, with `card.storage.package` for data every card of the package shares. */
+export interface CardStorage extends ScopedStorage {
+    /** Storage shared by every card of this package (20 MB). */
+    readonly package: ScopedStorage;
+    /** Another instance of this package wrote a package-scope key. */
+    onChange(handler: (change: CardEvents['storage.changed']) => void): Unsubscribe;
+}
+/**
+ * A connected card. Get one with `await connect()`.
+ *
+ * Everything the host offers is here, typed from the contract:
+ * `card.call(method, params)` for any method, `card.on(event, handler)` for
+ * any event, and namespaced helpers (`card.storage`, `card.agents`,
+ * `card.ports`, `card.tools`, `card.net`, `card.fs`, `card.ui`, …) that
+ * read nicer and add conveniences (auto-subscription, streaming,
+ * base64, tool/request dispatch).
+ *
+ * @example
+ * import { connect } from '@neurosquad/card-sdk'
+ *
+ * const card = await connect()
+ * card.setStatus('Ready', { tone: 'success' })
+ * const agents = await card.agents.list()
+ * card.tools.handle('count_agents', () => `${agents.length} agents`)
+ */
+export declare class Card {
+    private readonly channel;
+    private readonly options;
+    private ctx;
+    private readonly listeners;
+    private readonly buffered;
+    private readonly contextListeners;
+    private readonly topicCounts;
+    private readonly outputAgents;
+    private outputSync;
+    private readonly toolHandlers;
+    private readonly waitingToolCalls;
+    private readonly activeToolCalls;
+    private readonly requestHandlers;
+    private readonly waitingRequests;
+    private readonly streams;
+    private readonly watchers;
+    private readonly suspendHandlers;
+    private menuHandlers;
+    private logWindow;
+    private readonly disposers;
+    private readonly lanes;
+    /** Instance-scope storage; `card.storage.package` is shared by every card of the package. */
+    readonly storage: CardStorage;
+    /** The card's settings form (rendered by the host from the manifest's `settings`). */
+    readonly settings: CardSettings;
+    /** Host dialogs, toasts and the card's kebab menu. */
+    readonly ui: CardUi;
+    /** Agents and terminals on the canvas (`agents.read`, `agents.output`, `agents.prompt`). */
+    readonly agents: CardAgents;
+    /** Shell cards connected by an arrow (`terminals.write`). */
+    readonly terminals: CardTerminals;
+    /** Typed ports between cards connected by arrows. */
+    readonly ports: CardPorts;
+    /** Tools this card offers to connected agents over MCP. */
+    readonly tools: CardTools;
+    /** Network through the host's proxy (`network`, `network.local`). */
+    readonly net: CardNet;
+    /** Files in the workspace folder (`fs.read`, `fs.write`). */
+    readonly fs: CardFs;
+    /** Declared permissions and their grant state; ask for optional ones. */
+    readonly permissions: CardPermissions;
+    /** Visibility, suspension, expansion and size. */
+    readonly lifecycle: CardLifecycle;
+    /** Messages for the package log (and the `neurosquad-card dev` console). */
+    readonly log: CardLog;
+    /** @internal Use `connect()`. */
+    constructor(channel: Channel, context: HostContext, options?: CardOptions);
+    /**
+     * Calls any host method, fully typed from the contract.
+     *
+     * @example
+     * const { keys } = await card.call('storage.keys', { scope: 'instance', prefix: 'draft:' })
+     * const info = await card.call('card.getInfo')
+     */
+    call<M extends CardMethodName>(method: M, ...args: CallArgs<M>): Promise<MethodResult<M>>;
+    /**
+     * Calls a method by name without compile-time types — for methods a newer
+     * host added within the same protocol (check `card.host.capabilities()` first).
+     */
+    callUnchecked(method: string, params?: JsonValue, options?: CallOptions): Promise<unknown>;
+    /**
+     * Listens to a host event. Subscribable topics (`agents.status`,
+     * `agents.turn`, `agents.changed`, `storage.changed`) are subscribed with
+     * the host automatically while at least one listener exists.
+     * `agents.output` needs agent ids: use `card.agents.onOutput()`.
+     *
+     * @returns A function that removes the listener.
+     */
+    on<E extends CardEventName>(event: E, handler: EventHandler<E>): Unsubscribe;
+    /** Like {@link on}, but only for the next occurrence. */
+    once<E extends CardEventName>(event: E, handler: EventHandler<E>): Unsubscribe;
+    /** Resolves with the next occurrence of an event (optionally the first one matching `filter`). */
+    waitFor<E extends CardEventName>(event: E, filter?: (data: CardEvents[E]) => boolean, options?: {
+        timeoutMs?: number;
+        signal?: AbortSignal;
+    }): Promise<CardEvents[E]>;
+    /** Subscribes to topics directly (normally `on()` does it for you). Resolves with the granted subset. */
+    subscribe(topics: EventTopic[], agentIds?: string[]): Promise<EventTopic[]>;
+    /** Unsubscribes topics directly. */
+    unsubscribe(topics: EventTopic[]): Promise<void>;
+    /**
+     * Everything the host told the card at start, kept current: visibility,
+     * expanded, size, theme, language, settings, permissions and peers are
+     * updated from their events. The object is replaced (never mutated) on
+     * every change — safe for React's `useSyncExternalStore`.
+     */
+    get context(): HostContext;
+    /** Called with the new context after any change to it. */
+    onContextChange(listener: (context: HostContext) => void): Unsubscribe;
+    /** This card's id on the canvas. */
+    get instanceId(): string;
+    /** Package, version, title and size. */
+    get instance(): CardInstanceInfo;
+    get workspace(): WorkspaceInfo;
+    /** `visible`, `offscreen`, `overview` or `hidden`. Pause work when not `visible`. */
+    get visibility(): CardVisibility;
+    /** The card is expanded to fill the canvas. */
+    get expanded(): boolean;
+    get size(): CardSize;
+    get theme(): ThemeSnapshot;
+    /** `en`, `ru` or `zh`, plus a BCP 47 locale for `Intl`. */
+    get i18n(): I18nSnapshot;
+    get language(): I18nSnapshot['language'];
+    /** Why the frame (re)started: created, opened, resumed, reloaded or updated. */
+    get launch(): HostContext['launch'];
+    /** `init` from the card that spawned this one with `card.spawn('self', { init })`, on its first start. */
+    get spawnInit(): JsonValue | undefined;
+    /** The host's limits (sizes, rates). */
+    get limits(): HostContext['limits'];
+    /** The app's version. */
+    get appVersion(): string;
+    /** Fresh instance info from the host. */
+    getInfo(): Promise<CardInstanceInfo>;
+    /** The card's own title (the user's name for the card still wins). `null` clears it. */
+    setTitle(title: string | null): Promise<void>;
+    /**
+     * The status chip in the card header. `null` clears it.
+     *
+     * @example
+     * card.setStatus('Running tests…', { busy: true })
+     * card.setStatus('3 failed', { tone: 'danger' })
+     */
+    setStatus(text: string | null, options?: {
+        tone?: CardTone;
+        busy?: boolean;
+    }): Promise<void>;
+    /** The header badge: a count (`3`), a short text (`'NEW'`, ≤ 12 chars), or `null` to clear. */
+    setBadge(value: number | string | null, options?: {
+        tone?: CardTone;
+    }): Promise<void>;
+    /**
+     * What the overview tile shows when the canvas is zoomed out (and while the
+     * card is suspended, and on the phone). Persisted by the host.
+     */
+    setOverview(overview: OverviewContent): Promise<void>;
+    /**
+     * Asks for the user's attention: `needs-input` pulses the card like a
+     * waiting agent and lists it in the Inbox; `info` is softer; `none` clears.
+     * The host allows one change per 10 s; when it refuses, the SDK retries
+     * with the latest level as soon as it is allowed (a burst folds into one).
+     * `card.context.chrome?.attention` says what the host shows right now
+     * (it survives frame reloads — clear it if it is stale).
+     */
+    attention(level: 'none' | 'info' | 'needs-input', message?: string): Promise<void>;
+    /** Keeps `context.chrome` in step with what the host now shows (hosts that send it). */
+    private noteChrome;
+    /**
+     * Sends a chrome update through its latest-wins lane (MC-8: the host
+     * throttles these; the lane spaces them so the host never refuses one).
+     */
+    private coalesced;
+    /** Asks to be resized; clamped to the manifest's min/max. Resolves with the size applied. */
+    requestResize(size: CardSize): Promise<CardSize>;
+    /** Opens an https link after the user confirms it on the card. Resolves `true` if it was opened. */
+    openLink(url: string): Promise<boolean>;
+    /** Flies the camera to another card of the same workspace (card must be visible; every 5 s at most). */
+    focusCard(cardId: string): Promise<void>;
+    /**
+     * Adds a card next to this one (`canvas.spawn`, ≤ 4 per card) and connects
+     * it with an arrow unless `connect: false`. `self` = another card of this
+     * package; it receives `init` as `card.spawnInit`.
+     */
+    spawn(kind: 'self' | 'note' | 'todo' | 'kanban' | 'sticky', options?: {
+        title?: string;
+        connect?: boolean;
+        init?: JsonValue;
+    }): Promise<string>;
+    /** Host info and feature detection. */
+    readonly host: {
+        /** Methods and events this app supports (for features added within a protocol version). */
+        capabilities: () => Promise<{
+            protocol: number;
+            methods: string[];
+            events: string[];
+        }>;
+        /** True when the app supports a method (asks the host once and caches). */
+        supports: (method: string) => Promise<boolean>;
+    };
+    private capabilityCache;
+    /** The workspace; `path` only with `fs.read`. */
+    getWorkspace(): Promise<WorkspaceInfo>;
+    /** Fresh theme snapshot (the context copy is already kept current). */
+    getTheme(): Promise<ThemeSnapshot>;
+    /** Fresh language snapshot. */
+    getI18n(): Promise<I18nSnapshot>;
+    /** Token usage and cost of this workspace (`usage.read`). Money is in micro-dollars. */
+    usage(period?: 'today' | '7d' | '30d'): Promise<UsageSummary>;
+    /** Copies text to the user's clipboard (`clipboard.write`, once per second). */
+    copyText(text: string): Promise<void>;
+    /** Closes the connection. The card stops receiving events; calls fail with UNAVAILABLE. */
+    close(): void;
+    /** True after {@link close} or when the host closed the port. */
+    get closed(): boolean;
+    /** @internal */
+    emitLocal(event: string, data: unknown): void;
+    /** @internal */
+    setContext(patch: Partial<HostContext>): void;
+    /** @internal */
+    notify<M extends CardMethodName>(method: M, params: MethodParams<M>): void;
+    /** @internal */
+    registerToolHandler(name: string, handler: ToolHandler<never>): Unsubscribe;
+    /** @internal */
+    registerRequestHandler(input: string, handler: PortRequestHandler<never>): Unsubscribe;
+    /** @internal */
+    openStream(requestId: string): ChunkQueue;
+    /** @internal */
+    closeStream(requestId: string): void;
+    /** @internal */
+    addWatcher(watchId: string, handler: (event: CardEvents['fs.changed']) => void): void;
+    /** @internal */
+    removeWatcher(watchId: string): void;
+    /** @internal */
+    addSuspendHandler(handler: (graceMs: number) => void | Promise<void>): Unsubscribe;
+    /** @internal */
+    setMenuHandlers(handlers: Map<string, () => void>): void;
+    /** @internal Reference-counted `agents.output` subscription for these agents. */
+    watchOutput(agentIds: string[], delta: 1 | -1): void;
+    private scheduleOutputSync;
+    private retainTopic;
+    private releaseTopic;
+    private dispatch;
+    private onToolCall;
+    private runTool;
+    private onPortRequest;
+    private runRequest;
+    private runSuspend;
+    private applyEnvironment;
+    private installErrorForwarding;
+    private writeLog;
+    private safely;
+    private reportHandlerError;
+    private makeStorage;
+}
+/** `card.log`: lines for the package log (visible in `neurosquad-card dev`). Throttled to 50 lines/s. */
+export interface CardLog {
+    debug(...args: unknown[]): void;
+    info(...args: unknown[]): void;
+    warn(...args: unknown[]): void;
+    error(...args: unknown[]): void;
+}
+/** `card.settings` */
+export declare class CardSettings {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /** Current values (defaults filled in; secrets are never included). */
+    get values(): Record<string, SettingValue>;
+    /** Which secret settings the user has filled in (the values never reach the card). */
+    get secrets(): Record<string, boolean>;
+    /** One value, typed by you. */
+    value<T extends SettingValue = SettingValue>(key: string): T | undefined;
+    /** True when the user has set the secret setting `key`. Use it in `net.fetch` headers as `{{secret:key}}`. */
+    hasSecret(key: string): boolean;
+    /** Fresh snapshot from the host. */
+    get(): Promise<SettingsSnapshot>;
+    /** Changes non-secret settings (validated against the manifest). Every instance gets `settings.changed`. */
+    set(values: Record<string, SettingValue>): Promise<SettingsSnapshot>;
+    /** Opens the host's settings form on the card (card must be visible). */
+    open(): Promise<void>;
+    /** Settings changed (by the user in the form, or by `set`). */
+    onChange(handler: (settings: SettingsSnapshot) => void): Unsubscribe;
+}
+/** `card.ui` */
+export declare class CardUi {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /** A small toast inside the card box (once per 2 s). */
+    toast(message: string, options?: {
+        tone?: CardTone;
+        durationMs?: number;
+    }): Promise<void>;
+    /**
+     * A host confirmation dialog inside the card box. Resolves `true` when the
+     * user confirms. Card must be visible.
+     */
+    confirm(options: {
+        title: string;
+        message: string;
+        confirmLabel?: string;
+        cancelLabel?: string;
+        tone?: 'default' | 'danger';
+    }): Promise<boolean>;
+    /**
+     * Items appended to the card's kebab menu (≤ 12). Give each an `onSelect`,
+     * or listen with {@link onMenu}. Replaces the previous items.
+     *
+     * @example
+     * card.ui.setMenu([
+     *   { id: 'refresh', label: 'Refresh', icon: 'arrow-path', onSelect: refresh },
+     *   { id: 'reset', label: 'Reset', tone: 'danger', onSelect: reset }
+     * ])
+     */
+    setMenu(items: CardMenuItem[]): Promise<void>;
+    /** A menu item was chosen. */
+    onMenu(handler: (id: string) => void): Unsubscribe;
+}
+/** `card.agents` */
+export declare class CardAgents {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /** AI agents and shells in this workspace (`agents.read`). */
+    list(): Promise<AgentInfo[]>;
+    get(agentId: string): Promise<AgentInfo>;
+    /** The visible screen of a connected agent or terminal (`agents.output`), up to 500 lines. */
+    readScreen(agentId: string, lines?: number): Promise<string>;
+    /** Claude Code's last reply (connected, `agents.output`); `text: null` for other harnesses. */
+    lastReply(agentId: string): Promise<{
+        text: string | null;
+        at: number | null;
+    }>;
+    /**
+     * Sends a prompt to a connected AI agent (`agents.prompt`, 6 per minute).
+     * While the agent works it is queued (`whenBusy: 'queue'`, default),
+     * sent anyway (`'send'`), or refused with BUSY (`'fail'`).
+     * `submit: false` only types it in; the user presses Enter.
+     *
+     * @returns How it was delivered: `sent`, `queued` or `inserted`.
+     */
+    prompt(agentId: string, text: string, options?: {
+        submit?: boolean;
+        whenBusy?: 'queue' | 'send' | 'fail';
+    }): Promise<'sent' | 'queued' | 'inserted'>;
+    /** An agent's status changed (optionally only for one agent). */
+    onStatus(handler: (event: CardEvents['agents.status']) => void, agentId?: string): Unsubscribe;
+    /** A turn started or ended (optionally only for one agent). */
+    onTurn(handler: (event: CardEvents['agents.turn']) => void, agentId?: string): Unsubscribe;
+    /** Agents were added, removed or renamed; receives the full new list. */
+    onChanged(handler: (agents: AgentInfo[]) => void): Unsubscribe;
+    /**
+     * Live output (ANSI stripped, coalesced) of connected agents/terminals
+     * (`agents.output`). Subscribes for these ids while the handler is attached.
+     */
+    onOutput(agentIds: string[], handler: (event: CardEvents['agents.output']) => void): Unsubscribe;
+}
+/** `card.terminals` */
+export declare class CardTerminals {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /**
+     * Runs a command in a connected shell card and waits for it
+     * (`terminals.write`). `exitCode` is null for cmd.exe.
+     */
+    run(agentId: string, command: string, options?: {
+        timeoutMs?: number;
+    }): Promise<{
+        exitCode: number | null;
+        output: string;
+        truncated: boolean;
+        timedOut: boolean;
+    }>;
+    /** Types text into a connected shell; `submit: true` presses Enter after it. */
+    write(agentId: string, text: string, options?: {
+        submit?: boolean;
+    }): Promise<void>;
+}
+/** `card.ports` */
+export declare class CardPorts {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /** This card's inputs, as declared in the manifest (labels resolved). */
+    get inputs(): PortInfo[];
+    /** This card's outputs. */
+    get outputs(): PortInfo[];
+    /** Cards connected by arrows, with their direction and ports (kept current in `card.context.peers`). */
+    get peers(): PeerInfo[];
+    /** Fresh peer list from the host. */
+    refreshPeers(): Promise<PeerInfo[]>;
+    /** Own ports, fresh from the host. */
+    describe(): Promise<{
+        inputs: PortInfo[];
+        outputs: PortInfo[];
+    }>;
+    /**
+     * Sends a value out of an output port to every downstream peer whose input
+     * accepts it (converted when the types differ). Resolves with how many
+     * peers got it. Retained outputs also remember the value.
+     */
+    emit(port: string, data: JsonValue): Promise<number>;
+    /** Sends to one peer; `input` picks its input explicitly. */
+    send(to: string, port: string, data: JsonValue, options?: {
+        input?: string;
+    }): Promise<number>;
+    /** Asks a peer's `mode: "request"` input and waits for the reply. */
+    request<T = JsonValue>(to: string, input: string, data: JsonValue, options?: {
+        timeoutMs?: number;
+    }): Promise<T>;
+    /** A connected peer's retained output value, or null. */
+    read<T = JsonValue>(from: string, port: string): Promise<{
+        data: T;
+        at: number;
+    } | null>;
+    /**
+     * Values arriving on inputs (optionally one input). Messages that arrive
+     * before the first listener are kept (up to 100) and delivered to it.
+     */
+    onMessage<T = JsonValue>(handler: (data: T, message: CardEvents['ports.message']) => void, options?: {
+        input?: string;
+    }): Unsubscribe;
+    /**
+     * Answers requests to one of our `mode: "request"` inputs. Return the reply
+     * (checked against the input's `response` type by the host), or throw to
+     * send an error. Requests that arrive before you register wait until
+     * their deadline.
+     */
+    onRequest<T = JsonValue>(input: string, handler: PortRequestHandler<T>): Unsubscribe;
+    /** Arrows or peers changed. */
+    onPeersChanged(handler: (peers: PeerInfo[]) => void): Unsubscribe;
+}
+/** `card.tools` */
+export declare class CardTools {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /**
+     * Implements a tool declared in the manifest's `tools`. Connected agents
+     * call it over MCP; the handler's return value is the result:
+     * a string (text), a `ToolResultPayload` (`{ content: [...] }`, images too),
+     * or any JSON value (sent as pretty JSON). Throwing sends an error result.
+     * Calls that arrive before registration wait for it until their deadline.
+     *
+     * @example
+     * card.tools.handle<{ filter?: string }>('run_tests', async ({ filter }, call) => {
+     *   call.progress('running…')
+     *   const result = await runTests(filter, call.signal)
+     *   return result.failures.length ? result.failures.join('\n') : 'All tests passed'
+     * })
+     */
+    handle<A = JsonValue>(name: string, handler: ToolHandler<A>): Unsubscribe;
+    /** Hides or shows a declared tool from agents (e.g. until the user signs in). */
+    setEnabled(tool: string, enabled: boolean): Promise<void>;
+}
+/** `card.net` */
+export declare class CardNet {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /**
+     * `fetch` through the host's proxy. Only https hosts granted by the
+     * `network` permission (or localhost with `network.local`); cookies are
+     * never kept. See {@link CardFetchInit} and {@link CardResponse}.
+     *
+     * @example
+     * const res = await card.net.fetch('https://api.example.com/items', {
+     *   method: 'POST',
+     *   headers: { authorization: 'Bearer {{secret:apiKey}}' },
+     *   body: { name: 'x' },
+     *   responseType: 'json'
+     * })
+     */
+    fetch(url: string | URL, init?: CardFetchInit): Promise<CardResponse>;
+}
+/** `card.fs` — paths are relative to the workspace folder. */
+export declare class CardFs {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    stat(path: string): Promise<FsStat>;
+    /** Lists a folder (`recursive` skips .git and node_modules). */
+    list(path?: string, options?: {
+        recursive?: boolean;
+        maxEntries?: number;
+    }): Promise<{
+        entries: FsEntry[];
+        truncated: boolean;
+    }>;
+    /** Reads a file as UTF-8 text. */
+    readText(path: string, options?: {
+        maxBytes?: number;
+    }): Promise<string>;
+    /** Reads a file as bytes. */
+    readBytes(path: string, options?: {
+        maxBytes?: number;
+    }): Promise<Uint8Array>;
+    /** The raw read result (with `size` and `truncated`). */
+    read(path: string, options?: {
+        encoding?: 'utf8' | 'base64';
+        maxBytes?: number;
+    }): Promise<{
+        data: string;
+        encoding: 'utf8' | 'base64';
+        size: number;
+        truncated: boolean;
+    }>;
+    /**
+     * Writes a text file atomically (`fs.write`; never under .git/).
+     * `ifMtimeMs` fails with FS_ERROR (`data.conflict`) if the file changed since you read it.
+     */
+    writeText(path: string, text: string, options?: {
+        createDirs?: boolean;
+        ifMtimeMs?: number;
+    }): Promise<FsStat>;
+    /** Writes bytes atomically. */
+    writeBytes(path: string, data: ArrayBuffer | ArrayBufferView, options?: {
+        createDirs?: boolean;
+        ifMtimeMs?: number;
+    }): Promise<FsStat>;
+    mkdir(path: string): Promise<FsStat>;
+    /** Moves to the OS trash (there is no hard delete). */
+    trash(path: string): Promise<void>;
+    /**
+     * Watches a file or folder (debounced 100 ms; ≤ 20 watchers per card).
+     * Resolves with a function that stops watching.
+     */
+    watch(path: string, handler: (change: CardEvents['fs.changed']) => void, options?: {
+        recursive?: boolean;
+    }): Promise<() => Promise<void>>;
+}
+/** `card.permissions` */
+export declare class CardPermissions {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /** Declared permissions and whether each is granted (kept current). */
+    get all(): PermissionState[];
+    /** True when the permission is granted (directly or implied, e.g. `fs.write` implies `fs.read`). */
+    has(id: PermissionId): boolean;
+    /** Fresh list from the host. */
+    list(): Promise<PermissionState[]>;
+    /**
+     * Asks the user for optional permissions declared in the manifest (a host
+     * popover on the card; the card must be visible). Resolves with the ids
+     * granted now.
+     */
+    request(...ids: PermissionId[]): Promise<PermissionId[]>;
+    onChange(handler: (permissions: PermissionState[]) => void): Unsubscribe;
+}
+/** `card.lifecycle` */
+export declare class CardLifecycle {
+    private readonly card;
+    /** @internal */
+    constructor(card: Card);
+    /** Visibility changed: `visible`, `offscreen`, `overview` (zoomed out, frame hidden) or `hidden`. */
+    onVisibility(handler: (state: CardVisibility) => void): Unsubscribe;
+    /**
+     * The frame is about to be unloaded (hidden too long, or the live-frame cap).
+     * Save state now; the SDK waits for your promise up to `graceMs`.
+     * The card comes back later with `card.launch === 'resumed'`.
+     */
+    onSuspend(handler: (graceMs: number) => void | Promise<void>): Unsubscribe;
+    onExpanded(handler: (expanded: boolean) => void): Unsubscribe;
+    onResized(handler: (size: CardSize) => void): Unsubscribe;
+}
+/** Icons the host can draw for a card (overview tile, menu items). */
+export type { HostIconName };