@theaiplatform/miniapp-sdk 0.2.2 → 0.3.0

package/README.md

@@ -40,17 +40,42 @@ requests through host consent instead of browser `fetch`, and
 secrets remain in the host vault and are injected only by the native request
 authority.
 
-`sdk.printing` is an optional desktop-only receipt printer API. It accepts only
-bounded semantic version-1 receipt rows with printable ASCII text and a stable job key; the host chooses
-the machine-local printer/profile and owns wrapping, feed, cut, and OS spooler
-submission. Packages must declare the exact descriptor effect
+`sdk.printing` is an optional desktop-only receipt printer API. It discovers
+bounded machine-local printer metadata and host-supported 58 mm and 80 mm paper
+profiles, then accepts only bounded semantic version-1 receipt rows with
+printable ASCII text and a stable job key. The miniapp passes its exact
+printer/profile selection to status and submission; the host revalidates that
+destination and owns wrapping, feed, cut, and OS spooler submission. Packages
+must declare the exact descriptor effect
 `{ "kind": "physical-output", "resources": ["receipt-printer"] }` and a
 persisted `printing.receipt` action with reusable consent, `do` autonomy, and
-consequential risk. Printer identity, raw ESC/POS, direct USB/network access,
-and `window.print()` are not SDK capabilities. Job-key journaling suppresses
+consequential risk. Raw ESC/POS, direct USB/network access, and `window.print()`
+are not SDK capabilities. Job-key journaling suppresses
 routine reconnect duplicates, but physical exactly-once printing is impossible;
 every result therefore carries `physicalExactlyOnce: false`.
 
+## Terminal sessions in 0.3.0
+
+`sdk.terminal?.v1` is an optional desktop-only terminal session API introduced
+in SDK 0.3.0. It exposes
+only the fixed `workspace-shell` and `neovim` profiles; package code cannot
+choose an executable, environment, native terminal ID, working directory, or
+filesystem path. `open()` returns a host-owned session with ordered binary
+events, acknowledged binary writes, resize, and idempotent close. A dedicated
+per-session channel applies byte credit and bounded buffering, so terminal
+output never uses the ordinary miniapp host-action bridge as a data plane.
+Packages opening a session declare the selected `terminal` profile and the
+`filesystem-mount` resource `conversation-vfs:read-write`, plus the persisted
+`terminal.session.open`, `filesystem.read`, and `filesystem.write` actions.
+Capability discovery is authoritative: the initial host reports both profiles
+unavailable. `workspace-shell` waits for positive conversation-scoped read
+isolation, and `neovim` additionally waits for an integrity-locked runtime.
+
+See the
+[terminal API reference](https://docs.theaiplatform.app/miniapps/reference/sdk#terminal-sessions)
+for capability detection, the required descriptor authorization, session
+events, limits, and cleanup.
+
 ## Discovery metadata
 
 Descriptor-backed packages may assign up to three unique

package/THIRD_PARTY_NOTICES.md

@@ -9,30 +9,30 @@ distributed as source. Optional peer dependencies are not distributed with
 this package and remain subject to their own licenses.
 
 The inventory below records the direct and transitive runtime dependency
-versions resolved by the release workspace lockfile on July 18, 2026. A
+versions resolved by the release workspace lockfile on July 22, 2026. A
 downstream application may resolve a different compatible transitive version
 and is responsible for reviewing the notices required by its own lockfile and
 distribution artifact.
 
 | Relationship     | Package                        | Version | License      |
 | ---------------- | ------------------------------ | ------: | ------------ |
-| Direct UI        | `@radix-ui/react-alert-dialog` |  1.1.15 | MIT          |
-| Direct UI        | `@radix-ui/react-avatar`       |  1.1.11 | MIT          |
-| Direct UI        | `@radix-ui/react-checkbox`     |   1.3.3 | MIT          |
-| Direct UI        | `@radix-ui/react-compose-refs` |   1.1.2 | MIT          |
-| Direct UI        | `@radix-ui/react-dialog`       |  1.1.15 | MIT          |
-| Direct UI        | `@radix-ui/react-label`        |   2.1.8 | MIT          |
-| Direct UI        | `@radix-ui/react-progress`     |   1.1.8 | MIT          |
-| Direct UI        | `@radix-ui/react-radio-group`  |   1.3.8 | MIT          |
-| Direct UI        | `@radix-ui/react-scroll-area`  |  1.2.10 | MIT          |
-| Direct UI        | `@radix-ui/react-select`       |   2.2.6 | MIT          |
-| Direct UI        | `@radix-ui/react-separator`    |   1.1.8 | MIT          |
-| Direct UI        | `@radix-ui/react-slider`       |   1.3.6 | MIT          |
-| Direct UI        | `@radix-ui/react-slot`         |   1.2.4 | MIT          |
-| Direct UI        | `@radix-ui/react-tabs`         |  1.1.13 | MIT          |
-| Direct UI        | `@radix-ui/react-toggle`       |  1.1.10 | MIT          |
-| Direct UI        | `@radix-ui/react-toggle-group` |  1.1.11 | MIT          |
-| Direct UI        | `@radix-ui/react-tooltip`      |   1.2.8 | MIT          |
+| Direct UI        | `@radix-ui/react-alert-dialog` |  1.1.20 | MIT          |
+| Direct UI        | `@radix-ui/react-avatar`       |   1.2.3 | MIT          |
+| Direct UI        | `@radix-ui/react-checkbox`     |   1.3.8 | MIT          |
+| Direct UI        | `@radix-ui/react-compose-refs` |   1.1.3 | MIT          |
+| Direct UI        | `@radix-ui/react-dialog`       |  1.1.20 | MIT          |
+| Direct UI        | `@radix-ui/react-label`        |  2.1.12 | MIT          |
+| Direct UI        | `@radix-ui/react-progress`     |  1.1.13 | MIT          |
+| Direct UI        | `@radix-ui/react-radio-group`  |   1.4.4 | MIT          |
+| Direct UI        | `@radix-ui/react-scroll-area`  |  1.2.15 | MIT          |
+| Direct UI        | `@radix-ui/react-select`       |   2.3.4 | MIT          |
+| Direct UI        | `@radix-ui/react-separator`    |  1.1.12 | MIT          |
+| Direct UI        | `@radix-ui/react-slider`       |   1.4.4 | MIT          |
+| Direct UI        | `@radix-ui/react-slot`         |   1.3.0 | MIT          |
+| Direct UI        | `@radix-ui/react-tabs`         |  1.1.18 | MIT          |
+| Direct UI        | `@radix-ui/react-toggle`       |  1.1.15 | MIT          |
+| Direct UI        | `@radix-ui/react-toggle-group` |  1.1.16 | MIT          |
+| Direct UI        | `@radix-ui/react-tooltip`      |  1.2.13 | MIT          |
 | Direct UI        | `class-variance-authority`     |   0.7.1 | Apache-2.0   |
 | Direct UI        | `clsx`                         |   2.1.1 | MIT          |
 | Direct UI        | `lucide-react`                 |  1.20.0 | ISC          |

package/config-schema.json

@@ -600,27 +600,6 @@
       ],
       "type": "string"
     },
-    "MiniAppReferencesManifest": {
-      "additionalProperties": false,
-      "description": "Manifest that references built TAP miniapp manifests.",
-      "properties": {
-        "$schema": {
-          "description": "Optional JSON Schema reference for editor support.",
-          "type": ["string", "null"]
-        },
-        "references": {
-          "description": "References to built TAP miniapp manifests.\n\nString shorthand remains available for local and mutable development sources. An\nimmutable remote collection uses the object form (`{ \"url\": ..., \"hash\": ... }`) so\nevery child manifest carries its own SHA-256 integrity boundary.",
-          "items": {
-            "$ref": "#/$defs/MiniAppSource"
-          },
-          "minItems": 1,
-          "type": "array"
-        }
-      },
-      "required": ["references"],
-      "title": "Tap Miniapp References Manifest",
-      "type": "object"
-    },
     "MiniAppSource": {
       "description": "Absolute URL or local path. Bundle entry paths are resolved relative to the manifest that declares them.",
       "oneOf": [
@@ -3694,12 +3673,8 @@
     {
       "$ref": "#/$defs/MiniAppBundleManifest",
       "description": "A single miniapp bundle with its runtime entrypoint."
-    },
-    {
-      "$ref": "#/$defs/MiniAppReferencesManifest",
-      "description": "A collection manifest that points at built miniapp manifests."
     }
   ],
-  "description": "Manifest for a Tap miniapp bundle or a collection of built miniapps.",
+  "description": "Manifest for one Tap package or legacy miniapp bundle.",
   "title": "Tap Miniapp Manifest"
 }

package/dist/index.d.ts

@@ -230,10 +230,17 @@ export declare type MiniAppHttpRequestInput = {
 
 export declare type MiniAppHttpRequestOptions = {
     /**
-     * Opaque host-managed credential reference. Secret material never enters
-     * miniapp JavaScript.
+     * Opaque host-managed credential reference, or the reserved
+     * `platform-session` reference for the active TAP account. Secret material
+     * never enters miniapp JavaScript.
      */
     credentialRef?: string;
+    /**
+     * Requests one host-managed integration credential. The host attaches it
+     * only after the package declares and receives the corresponding credential
+     * permission; secret material never enters miniapp JavaScript.
+     */
+    auth?: 'github';
 };
 
 export declare type MiniAppHttpResponse = {
@@ -323,8 +330,6 @@ export declare type MiniAppPlatformApi = {
         create(options: CreateChannelOptions): CreateChannelResult | Promise<CreateChannelResult>;
         list(options?: ListChannelsOptions): ListChannelsResult | Promise<ListChannelsResult>;
         sendMessage(options: SendChannelMessageOptions): SendChannelMessageResult | Promise<SendChannelMessageResult>;
-        /** Persist one deterministic completed row under a joined specialist. */
-        sendSpecialistMessage(options: SendChannelSpecialistMessageOptions): SendChannelSpecialistMessageResult | Promise<SendChannelSpecialistMessageResult>;
         getAccess(options: GetChannelAccessOptions): GetChannelAccessResult | Promise<GetChannelAccessResult>;
         getTimeline(options: GetChannelTimelineOptions): GetChannelTimelineResult | Promise<GetChannelTimelineResult>;
     };
@@ -350,6 +355,8 @@ export declare type MiniAppPlatformApi = {
     credentials?: MiniAppCredentialsApi;
     /** Desktop host capability; feature-detect before use on portable targets. */
     printing?: MiniAppReceiptPrintingApi;
+    /** Desktop host capability; feature-detect before opening a terminal. */
+    terminal?: MiniAppTerminalApi;
     /** Browser capabilities appear only when the selected target supports them. */
     auth?: MiniAppAuthApi;
     vfs?: MiniAppVfsApi;
@@ -405,7 +412,8 @@ export declare type MiniAppProject = {
 export declare type MiniAppProvisionProjectChatOptions = {
     conversationId: string;
     projectId: string;
-    referenceBranch?: string | null;
+    baseBranch?: string | null;
+    workingBranch?: string | null;
 };
 
 export declare type MiniAppProvisionProjectChatResult = {
@@ -441,24 +449,51 @@ export declare type MiniAppReceiptLine = {
     kind: 'blank';
 };
 
-/** Abstract machine-local printer readiness; destination identity stays host-only. */
+/** Host rendering capabilities for one supported receipt paper width. */
+export declare type MiniAppReceiptPaperProfile = {
+    id: MiniAppReceiptPrinterProfile;
+    widthMm: 58 | 80;
+    columns: 32 | 48;
+};
+
+/** Bounded metadata for one machine-local printer visible to an authorized miniapp. */
+export declare type MiniAppReceiptPrinter = {
+    name: string;
+    isDefault: boolean;
+};
+
+export declare type MiniAppReceiptPrinterDiscovery = {
+    printers: MiniAppReceiptPrinter[];
+    paperProfiles: MiniAppReceiptPaperProfile[];
+};
+
+export declare type MiniAppReceiptPrinterProfile = 'receipt-58mm' | 'receipt-80mm';
+
+/** Miniapp-owned selection passed explicitly to status and submission calls. */
+export declare type MiniAppReceiptPrinterSelection = {
+    printerName: string;
+    profile: MiniAppReceiptPrinterProfile;
+};
+
+/** Readiness for an exact machine-local printer selection. */
 export declare type MiniAppReceiptPrinterStatus = {
-    availability: 'unconfigured' | 'ready' | 'unavailable';
-    profile: 'receipt-58mm' | 'receipt-80mm' | null;
+    availability: 'ready' | 'unavailable';
 };
 
-/** Desktop-only silent receipt output through the host-configured OS spooler. */
+/** Desktop-only silent receipt output through a discovered OS spooler. */
 export declare type MiniAppReceiptPrintingApi = {
-    getStatus(): MiniAppMaybePromise<MiniAppReceiptPrinterStatus>;
+    listPrinters(): MiniAppMaybePromise<MiniAppReceiptPrinterDiscovery>;
+    getStatus(selection: MiniAppReceiptPrinterSelection): MiniAppMaybePromise<MiniAppReceiptPrinterStatus>;
     submit(options: MiniAppReceiptPrintOptions): MiniAppMaybePromise<MiniAppReceiptPrintResult>;
 };
 
 export declare type MiniAppReceiptPrintOptions = {
     /**
      * Stable caller key, capped at 128 characters. The host journals it within
-     * installation, workspace, and configured-destination scope.
+     * installation, workspace, and selected-destination scope.
      */
     jobKey: string;
+    selection: MiniAppReceiptPrinterSelection;
     document: MiniAppReceiptDocument;
 };
 
@@ -587,6 +622,76 @@ export declare type MiniAppStorageSetOptions = MiniAppStorageAddress & {
     expectedRevision: number | null;
 };
 
+export declare type MiniAppTerminalApi = {
+    readonly v1: MiniAppTerminalV1Api;
+};
+
+/** Versioned, desktop-only host terminal capability. */
+export declare type MiniAppTerminalV1Api = {
+    getCapabilities(): Promise<MiniAppTerminalV1Capabilities>;
+    open(options: MiniAppTerminalV1OpenOptions): Promise<MiniAppTerminalV1Session>;
+};
+
+export declare type MiniAppTerminalV1Capabilities = {
+    profiles: MiniAppTerminalV1Profile[];
+    limits: MiniAppTerminalV1Limits;
+};
+
+export declare type MiniAppTerminalV1DataEvent = {
+    type: 'data';
+    sequence: number;
+    data: Uint8Array;
+};
+
+export declare type MiniAppTerminalV1Event = MiniAppTerminalV1DataEvent | MiniAppTerminalV1ExitEvent;
+
+export declare type MiniAppTerminalV1ExitEvent = {
+    type: 'exit';
+    sequence: number;
+    code: number | null;
+    signal: string | null;
+    reason: 'exited' | 'closed' | 'revoked' | 'error';
+};
+
+export declare type MiniAppTerminalV1Limits = {
+    maxSessionsPerDocument: number;
+    maxWriteBytes: number;
+    maxOutputBytesInFlight: number;
+    maxCols: number;
+    maxRows: number;
+};
+
+export declare type MiniAppTerminalV1OpenOptions = {
+    profile: MiniAppTerminalV1ProfileId;
+    cols: number;
+    rows: number;
+};
+
+export declare type MiniAppTerminalV1Profile = {
+    id: MiniAppTerminalV1ProfileId;
+    available: boolean;
+    unavailableReason: string | null;
+};
+
+/** Host-owned terminal runtime profiles exposed by `sdk.terminal.v1`. */
+export declare type MiniAppTerminalV1ProfileId = 'workspace-shell' | 'neovim';
+
+export declare type MiniAppTerminalV1ResizeOptions = {
+    cols: number;
+    rows: number;
+};
+
+export declare type MiniAppTerminalV1Session = {
+    /** Opaque host-minted session identity; it carries no ambient authority. */
+    readonly id: string;
+    readonly profile: MiniAppTerminalV1ProfileId;
+    /** Ordered output with byte-sized backpressure owned by the host session. */
+    readonly events: ReadableStream<MiniAppTerminalV1Event>;
+    write(data: Uint8Array): Promise<void>;
+    resize(options: MiniAppTerminalV1ResizeOptions): Promise<void>;
+    close(): Promise<void>;
+};
+
 export declare type MiniAppUserProfile = {
     sub: string;
     name?: string | null;
@@ -656,21 +761,6 @@ export declare type SendChannelMessageResult = {
     clientMessageId: string;
 };
 
-export declare type SendChannelSpecialistMessageOptions = {
-    workspaceId?: string;
-    channelId: string;
-    projectId: string;
-    specialistId: string;
-    clientMessageId: string;
-    body: string;
-    messageContent?: Record<string, MiniAppJsonValue>;
-};
-
-export declare type SendChannelSpecialistMessageResult = {
-    messageId: string;
-    clientMessageId: string;
-};
-
 export declare type ToolDefinition<TArguments = unknown, TResult = unknown> = {
     displayName?: string;
     description: string;