@neurosquad/card-sdk 1.0.0

package/dist/types/contract/api.d.ts

@@ -0,0 +1,812 @@
+import type { CardJsonSchema, JsonValue } from './jsonSchema.js';
+import type { CardLanguage, LocalizedText } from './localized.js';
+import type { CardSize, SettingField, SettingValue } from './manifest.js';
+import type { NormalizedPermission, PermissionId } from './permissions.js';
+import type { PortInfo, PortTypeId } from './ports.js';
+import { type CardTone, type HostIconName, type ThemeSnapshot } from './theme.js';
+import { LIMITS } from './version.js';
+/** Where the card is, as far as the user can see it. */
+export type CardVisibility = 
+/** On screen, body shown. */
+'visible'
+/** Its workspace is shown but the card is outside the viewport. */
+ | 'offscreen'
+/** Zoomed out past the overview threshold: the host shows the overview tile, the frame is hidden. */
+ | 'overview'
+/** Its workspace is not the one shown, or the window is hidden. Suspended after LIMITS.hiddenSuspendMs unless `background`. */
+ | 'hidden';
+export declare const CARD_VISIBILITIES: readonly CardVisibility[];
+export type AgentStatus = 'working' | 'needs-input' | 'finished' | 'idle' | 'exited';
+export interface CardInstanceInfo {
+    /** The card's id on the canvas (the Agent record id). */
+    instanceId: string;
+    packageId: string;
+    /** Manifest `name`. */
+    name: string;
+    /** Manifest `displayName`, resolved to the app language. */
+    displayName: string;
+    version: string;
+    /** Installed commit; null for a dev-linked folder. */
+    commit: string | null;
+    /** The user's name for this card, else the card's own title, else null. */
+    title: string | null;
+    size: CardSize;
+    dev: boolean;
+}
+export interface WorkspaceInfo {
+    id: string;
+    name: string;
+    /** Absolute folder path — only with `fs.read`. */
+    path?: string;
+}
+export interface AgentInfo {
+    id: string;
+    name: string;
+    /** Harness id (`claude-code`, `codex-cli`, `shell-bash`…). */
+    harness: string;
+    kind: 'ai' | 'shell';
+    status: AgentStatus;
+    /** An arrow connects it with this card (either direction). */
+    connected: boolean;
+    sessionTitle?: string;
+    /** Epoch ms the current turn started (status 'working'). */
+    turnStartedAt?: number;
+    /**
+     * The last finished turn since the app started, so a card whose frame was
+     * not mounted when it ended (zoomed out, hidden) can catch up. Absent on
+     * older hosts and before the first turn ends.
+     */
+    lastTurn?: {
+        startedAt: number | null;
+        endedAt: number;
+        endedAs: 'finished' | 'needs-input';
+    };
+    model?: string;
+}
+export type PeerKind = 'custom' | 'note' | 'todo' | 'kanban' | 'sticky' | 'agent' | 'terminal' | 'other';
+export interface PeerInfo {
+    cardId: string;
+    kind: PeerKind;
+    /** Card name as the user sees it. */
+    name: string;
+    /** Harness id for agents/terminals; manifest name for custom cards. */
+    type?: string;
+    /** `downstream`: this card → peer (our outputs reach its inputs). `upstream`: peer → this card. */
+    direction: 'downstream' | 'upstream' | 'both';
+    inputs: PortInfo[];
+    outputs: PortInfo[];
+}
+export interface PermissionState {
+    id: PermissionId;
+    hosts?: string[];
+    optional: boolean;
+    granted: boolean;
+    reason?: string;
+}
+export interface SettingsSnapshot {
+    values: Record<string, SettingValue>;
+    /** Secret setting key → whether the user has set one. The value never reaches the card. */
+    secrets: Record<string, boolean>;
+}
+export interface MenuItem {
+    id: string;
+    label: string;
+    icon?: HostIconName;
+    tone?: 'default' | 'danger';
+    disabled?: boolean;
+}
+export interface OverviewContent {
+    /** Big line under the name (e.g. "3 / 11", "Build passing"). */
+    primary?: string | null;
+    secondary?: string | null;
+    /** 0..1 progress ring/bar. */
+    progress?: number | null;
+    tone?: CardTone;
+    icon?: HostIconName | null;
+}
+export interface HostContext {
+    protocol: number;
+    /** The app's version. */
+    appVersion: string;
+    instance: CardInstanceInfo;
+    workspace: WorkspaceInfo;
+    visibility: CardVisibility;
+    expanded: boolean;
+    theme: ThemeSnapshot;
+    i18n: I18nSnapshot;
+    settings: SettingsSnapshot;
+    permissions: PermissionState[];
+    ports: {
+        inputs: PortInfo[];
+        outputs: PortInfo[];
+    };
+    peers: PeerInfo[];
+    /** `init` passed by the card that spawned this one (card.spawn kind 'self'), once. */
+    spawnInit?: JsonValue;
+    /** Why the frame (re)started. */
+    launch: 'created' | 'opened' | 'resumed' | 'reloaded' | 'updated';
+    limits: typeof LIMITS;
+    /**
+     * The card's chrome as main holds it right now. It outlives frame reloads
+     * (dev reload, update, resume), so a card that raised `attention` before a
+     * reload can see the pulse is still on and clear it. Absent on hosts older
+     * than this field: treat it as unknown.
+     */
+    chrome?: CardChromeState;
+}
+/** What main currently shows for this card (`HostContext.chrome`). */
+export interface CardChromeState {
+    title: string | null;
+    status: {
+        text: string;
+        tone: CardTone;
+        busy: boolean;
+    } | null;
+    badge: {
+        count: number | null;
+        text: string | null;
+        tone: CardTone;
+    } | null;
+    overview: OverviewContent | null;
+    attention: {
+        level: 'info' | 'needs-input';
+        message: string | null;
+    } | null;
+}
+export interface I18nSnapshot {
+    language: CardLanguage;
+    /** BCP 47 for Intl (`en-US`, `ru-RU`, `zh-CN`). */
+    locale: string;
+}
+export interface ToolResultPayload {
+    content: ({
+        type: 'text';
+        text: string;
+    } | {
+        type: 'image';
+        data: string;
+        mimeType: 'image/png' | 'image/jpeg' | 'image/webp' | 'image/gif';
+    })[];
+    isError?: boolean;
+}
+export interface NetResponse {
+    requestId: string;
+    status: number;
+    statusText: string;
+    /** Lowercased names; set-cookie removed. */
+    headers: Record<string, string>;
+    /** Final URL after redirects. */
+    url: string;
+    /** For responseType text/base64. */
+    body?: string;
+    /** For responseType json. */
+    json?: JsonValue;
+    /** Body was longer than the limit and was cut (text/base64 only; json fails with TOO_LARGE). */
+    truncated?: boolean;
+}
+export interface FsStat {
+    path: string;
+    type: 'file' | 'directory';
+    size: number;
+    mtimeMs: number;
+}
+export interface FsEntry {
+    path: string;
+    type: 'file' | 'directory';
+    size?: number;
+}
+export interface UsageRow {
+    agentId: string;
+    name: string;
+    harness: string;
+    inputTokens: number;
+    outputTokens: number;
+    cacheReadTokens: number;
+    cacheWriteTokens: number;
+    /** Micro-dollars; null when the model has no known price. */
+    costMicroUsd: number | null;
+}
+export interface UsageSummary {
+    period: 'today' | '7d' | '30d';
+    /** ISO timestamps, local days, end exclusive. */
+    from: string;
+    to: string;
+    rows: UsageRow[];
+    totalCostMicroUsd: number;
+    /** Some rows had no price and are not in the total. */
+    partial: boolean;
+}
+export type EventTopic = 'agents.status' | 'agents.turn' | 'agents.changed' | 'agents.output' | 'storage.changed';
+export declare const EVENT_TOPICS: readonly EventTopic[];
+/** Permission each subscribable topic needs. */
+export declare const TOPIC_PERMISSION: Record<EventTopic, PermissionId | null>;
+type StorageScope = 'instance' | 'package';
+export interface CardMethods {
+    'host.ready': {
+        params: {
+            sdkVersion: string;
+            protocol: number;
+        };
+        result: HostContext;
+    };
+    'host.capabilities': {
+        params: void;
+        result: {
+            protocol: number;
+            methods: string[];
+            events: string[];
+        };
+    };
+    'host.log': {
+        params: {
+            level: 'debug' | 'info' | 'warn' | 'error';
+            message: string;
+        };
+        result: void;
+    };
+    'host.pong': {
+        params: {
+            seq: number;
+        };
+        result: void;
+    };
+    'events.subscribe': {
+        params: {
+            topics: EventTopic[];
+            agentIds?: string[];
+        };
+        result: {
+            topics: EventTopic[];
+        };
+    };
+    'events.unsubscribe': {
+        params: {
+            topics: EventTopic[];
+        };
+        result: void;
+    };
+    'card.getInfo': {
+        params: void;
+        result: CardInstanceInfo;
+    };
+    'card.setTitle': {
+        params: {
+            title: string | null;
+        };
+        result: void;
+    };
+    'card.setStatus': {
+        params: {
+            text?: string | null;
+            tone?: CardTone;
+            busy?: boolean;
+        };
+        result: void;
+    };
+    'card.setBadge': {
+        params: {
+            count?: number | null;
+            text?: string | null;
+            tone?: CardTone;
+        };
+        result: void;
+    };
+    'card.setOverview': {
+        params: OverviewContent;
+        result: void;
+    };
+    'card.attention': {
+        params: {
+            level: 'none' | 'info' | 'needs-input';
+            message?: string;
+        };
+        result: void;
+    };
+    'card.requestResize': {
+        params: CardSize;
+        result: CardSize;
+    };
+    'card.openLink': {
+        params: {
+            url: string;
+        };
+        result: {
+            opened: boolean;
+        };
+    };
+    'card.focus': {
+        params: {
+            cardId: string;
+        };
+        result: void;
+    };
+    'card.spawn': {
+        params: {
+            kind: 'self' | 'note' | 'todo' | 'kanban' | 'sticky';
+            title?: string;
+            connect?: boolean;
+            init?: JsonValue;
+        };
+        result: {
+            cardId: string;
+        };
+    };
+    'ui.toast': {
+        params: {
+            message: string;
+            tone?: CardTone;
+            durationMs?: number;
+        };
+        result: void;
+    };
+    'ui.confirm': {
+        params: {
+            title: string;
+            message: string;
+            confirmLabel?: string;
+            cancelLabel?: string;
+            tone?: 'default' | 'danger';
+        };
+        result: {
+            confirmed: boolean;
+        };
+    };
+    'ui.setMenu': {
+        params: {
+            items: MenuItem[];
+        };
+        result: void;
+    };
+    'settings.get': {
+        params: void;
+        result: SettingsSnapshot;
+    };
+    'settings.set': {
+        params: {
+            values: Record<string, SettingValue>;
+        };
+        result: SettingsSnapshot;
+    };
+    'settings.open': {
+        params: void;
+        result: void;
+    };
+    'storage.get': {
+        params: {
+            scope: StorageScope;
+            key: string;
+        };
+        result: {
+            exists: boolean;
+            value: JsonValue | null;
+        };
+    };
+    'storage.set': {
+        params: {
+            scope: StorageScope;
+            key: string;
+            value: JsonValue;
+        };
+        result: void;
+    };
+    'storage.delete': {
+        params: {
+            scope: StorageScope;
+            key: string;
+        };
+        result: void;
+    };
+    'storage.keys': {
+        params: {
+            scope: StorageScope;
+            prefix?: string;
+        };
+        result: {
+            keys: string[];
+        };
+    };
+    'storage.clear': {
+        params: {
+            scope: StorageScope;
+        };
+        result: void;
+    };
+    'storage.usage': {
+        params: {
+            scope: StorageScope;
+        };
+        result: {
+            bytes: number;
+            quota: number;
+            keys: number;
+        };
+    };
+    'theme.get': {
+        params: void;
+        result: ThemeSnapshot;
+    };
+    'i18n.get': {
+        params: void;
+        result: I18nSnapshot;
+    };
+    'workspace.get': {
+        params: void;
+        result: WorkspaceInfo;
+    };
+    'permissions.list': {
+        params: void;
+        result: PermissionState[];
+    };
+    'permissions.request': {
+        params: {
+            ids: PermissionId[];
+        };
+        result: {
+            granted: PermissionId[];
+        };
+    };
+    'agents.list': {
+        params: void;
+        result: AgentInfo[];
+    };
+    'agents.get': {
+        params: {
+            agentId: string;
+        };
+        result: AgentInfo;
+    };
+    'agents.readScreen': {
+        params: {
+            agentId: string;
+            lines?: number;
+        };
+        result: {
+            text: string;
+        };
+    };
+    'agents.lastReply': {
+        params: {
+            agentId: string;
+        };
+        result: {
+            text: string | null;
+            at: number | null;
+        };
+    };
+    'agents.prompt': {
+        params: {
+            agentId: string;
+            text: string;
+            submit?: boolean;
+            whenBusy?: 'queue' | 'send' | 'fail';
+        };
+        result: {
+            delivered: 'sent' | 'queued' | 'inserted';
+        };
+    };
+    'terminals.run': {
+        params: {
+            agentId: string;
+            command: string;
+            timeoutMs?: number;
+        };
+        result: {
+            exitCode: number | null;
+            output: string;
+            truncated: boolean;
+            timedOut: boolean;
+        };
+    };
+    'terminals.write': {
+        params: {
+            agentId: string;
+            text: string;
+            submit?: boolean;
+        };
+        result: void;
+    };
+    'ports.describe': {
+        params: void;
+        result: {
+            inputs: PortInfo[];
+            outputs: PortInfo[];
+        };
+    };
+    'ports.peers': {
+        params: void;
+        result: PeerInfo[];
+    };
+    'ports.emit': {
+        params: {
+            port: string;
+            data: JsonValue;
+        };
+        result: {
+            delivered: number;
+        };
+    };
+    'ports.send': {
+        params: {
+            to: string;
+            port: string;
+            input?: string;
+            data: JsonValue;
+        };
+        result: {
+            delivered: number;
+        };
+    };
+    'ports.request': {
+        params: {
+            to: string;
+            input: string;
+            data: JsonValue;
+            timeoutMs?: number;
+        };
+        result: {
+            data: JsonValue;
+        };
+    };
+    'ports.respond': {
+        params: {
+            requestId: string;
+            data?: JsonValue;
+            error?: string;
+        };
+        result: void;
+    };
+    'ports.read': {
+        params: {
+            from: string;
+            port: string;
+        };
+        result: {
+            data: JsonValue;
+            at: number;
+        } | null;
+    };
+    'tools.respond': {
+        params: {
+            callId: string;
+            result?: ToolResultPayload;
+            error?: string;
+        };
+        result: void;
+    };
+    'tools.progress': {
+        params: {
+            callId: string;
+            message: string;
+        };
+        result: void;
+    };
+    'tools.setEnabled': {
+        params: {
+            tool: string;
+            enabled: boolean;
+        };
+        result: void;
+    };
+    'net.fetch': {
+        params: {
+            url: string;
+            method?: 'GET' | 'HEAD' | 'POST' | 'PUT' | 'PATCH' | 'DELETE';
+            headers?: Record<string, string>;
+            body?: string;
+            bodyEncoding?: 'text' | 'base64';
+            responseType?: 'text' | 'json' | 'base64' | 'stream';
+            timeoutMs?: number;
+            /** Caller-chosen id for net.abort and stream chunks; generated when absent. */
+            requestId?: string;
+        };
+        result: NetResponse;
+    };
+    'net.abort': {
+        params: {
+            requestId: string;
+        };
+        result: void;
+    };
+    'fs.stat': {
+        params: {
+            path: string;
+        };
+        result: FsStat;
+    };
+    'fs.list': {
+        params: {
+            path: string;
+            recursive?: boolean;
+            maxEntries?: number;
+        };
+        result: {
+            entries: FsEntry[];
+            truncated: boolean;
+        };
+    };
+    'fs.read': {
+        params: {
+            path: string;
+            encoding?: 'utf8' | 'base64';
+            maxBytes?: number;
+        };
+        result: {
+            data: string;
+            encoding: 'utf8' | 'base64';
+            size: number;
+            truncated: boolean;
+        };
+    };
+    'fs.write': {
+        params: {
+            path: string;
+            data: string;
+            encoding?: 'utf8' | 'base64';
+            createDirs?: boolean;
+            ifMtimeMs?: number;
+        };
+        result: FsStat;
+    };
+    'fs.mkdir': {
+        params: {
+            path: string;
+        };
+        result: FsStat;
+    };
+    'fs.trash': {
+        params: {
+            path: string;
+        };
+        result: void;
+    };
+    'fs.watch': {
+        params: {
+            path: string;
+            recursive?: boolean;
+        };
+        result: {
+            watchId: string;
+        };
+    };
+    'fs.unwatch': {
+        params: {
+            watchId: string;
+        };
+        result: void;
+    };
+    'clipboard.writeText': {
+        params: {
+            text: string;
+        };
+        result: void;
+    };
+    'usage.summary': {
+        params: {
+            period: 'today' | '7d' | '30d';
+        };
+        result: UsageSummary;
+    };
+}
+export type CardMethodName = keyof CardMethods;
+export type MethodParams<M extends CardMethodName> = CardMethods[M]['params'];
+export type MethodResult<M extends CardMethodName> = CardMethods[M]['result'];
+export interface CardEvents {
+    'host.ping': {
+        seq: number;
+    };
+    'lifecycle.visibility': {
+        state: CardVisibility;
+    };
+    /** Save what you need; the frame is unloaded after `graceMs`. It comes back with launch 'resumed'. */
+    'lifecycle.suspend': {
+        graceMs: number;
+    };
+    'lifecycle.expanded': {
+        expanded: boolean;
+    };
+    'lifecycle.resized': CardSize;
+    'settings.changed': SettingsSnapshot;
+    'theme.changed': ThemeSnapshot;
+    'i18n.changed': I18nSnapshot;
+    'permissions.changed': PermissionState[];
+    'ui.menu': {
+        id: string;
+    };
+    'ports.message': {
+        from: string;
+        fromKind: PeerKind;
+        /** The sender's output port id. */
+        output: string;
+        /** Our input port id it was delivered to. */
+        input: string;
+        /** The type after coercion (= our input's type). */
+        type: PortTypeId;
+        /** The sender's declared output type, before coercion (absent on older hosts). */
+        sourceType?: PortTypeId;
+        data: JsonValue;
+        at: number;
+    };
+    'ports.request': {
+        requestId: string;
+        from: string;
+        input: string;
+        data: JsonValue;
+        deadline: number;
+    };
+    'ports.peersChanged': PeerInfo[];
+    'tools.call': {
+        callId: string;
+        tool: string;
+        args: JsonValue;
+        agent: {
+            id: string;
+            name: string;
+        };
+        deadline: number;
+    };
+    'tools.cancel': {
+        callId: string;
+    };
+    'net.chunk': {
+        requestId: string;
+        chunk: string;
+        encoding: 'text' | 'base64';
+        done: boolean;
+        error?: string;
+    };
+    'fs.changed': {
+        watchId: string;
+        path: string;
+        type: 'change' | 'rename';
+    };
+    'storage.changed': {
+        scope: 'package';
+        key: string;
+        byInstance: string;
+    };
+    'agents.status': {
+        agentId: string;
+        status: AgentStatus;
+        at: number;
+    };
+    'agents.turn': {
+        agentId: string;
+        phase: 'start' | 'end';
+        at: number;
+    };
+    'agents.changed': {
+        agents: AgentInfo[];
+    };
+    'agents.output': {
+        agentId: string;
+        text: string;
+        at: number;
+    };
+}
+export type CardEventName = keyof CardEvents;
+export declare const CARD_EVENT_NAMES: CardEventName[];
+export interface MethodSpec {
+    /**
+     * Required grant. An array means *any one of* (net.fetch: main then picks the
+     * precise one from the URL). Absent = always allowed.
+     */
+    permission?: PermissionId | readonly PermissionId[];
+    params: CardJsonSchema;
+    /** Refused with NOT_VISIBLE unless the card is 'visible' (and its window focused, for dialogs). */
+    visible?: boolean;
+    /** Extra per-method throttle on top of the global bucket. */
+    minIntervalMs?: number;
+    perMinute?: number;
+    /** Response may use LIMITS.largeMessageBytes. */
+    largeResponse?: boolean;
+    /** Allowed before host.ready (only host.ready itself). */
+    beforeReady?: boolean;
+}
+export declare const METHOD_SPECS: Record<CardMethodName, MethodSpec>;
+export declare const CARD_METHOD_NAMES: CardMethodName[];
+/** Is a method allowed by these (expanded) grants? */
+export declare function methodAllowed(method: CardMethodName, granted: ReadonlySet<PermissionId>): boolean;
+/** PermissionState list for a manifest's permissions and the current grants. */
+export declare function permissionStates(declared: readonly NormalizedPermission[], granted: ReadonlySet<PermissionId>, resolveReason: (text: LocalizedText) => string): PermissionState[];
+/** Settings fields as the SDK exposes them (for cards that render their own settings UI). */
+export type { SettingField };