@pptb/types 1.2.7-beta.4 → 1.2.7-beta.6

package/README.md

@@ -18,6 +18,7 @@ TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI
         - [Connections](#connections)
         - [Utilities](#utilities)
         - [Terminal Operations](#terminal-operations)
+        - [Native Workers](#native-workers)
         - [Events](#events)
         - [Inter-Tool Invocation](#inter-tool-invocation)
             - [Caller: launching another tool with prefill data](#caller-launching-another-tool-with-prefill-data)
@@ -42,6 +43,7 @@ TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI
             - [Connections](#connections-1)
             - [Utils](#utils)
             - [Terminal](#terminal)
+            - [Workers](#workers)
             - [Events](#events-1)
             - [Invocation](#invocation)
         - [Dataverse API (`window.dataverseAPI`)](#dataverse-api-windowdataverseapi)
@@ -256,6 +258,18 @@ The ToolBox API provides organized namespaces for different functionality:
 
 ### Connections
 
+Declare an exact count or range with `features.connections`, for example `3`, `{ "min": 0, "max": 3 }`, or `{ "min": 1, "max": 4 }`. Exact `0` means no connections. Counts are bounded to 0–10; object defaults are min 1 and max equal to the resolved min. Remove the deprecated `multiConnection` and `connectionRequirement` fields when migrating; existing legacy-only tools remain supported.
+
+```typescript
+const slots = await toolboxAPI.connections.getConnections();
+const third = await toolboxAPI.connections.getConnection(2);
+if (third) {
+    const records = await dataverseAPI.queryData("accounts?$select=name&$top=5", 2);
+}
+```
+
+Targets are zero-based; `"primary"` and `"secondary"` alias 0 and 1. Null slots retain their positions, so never filter the array before routing requests. `getSecondaryConnection()` is deprecated but supported; use `getConnection(1)` or `(await getConnections())[1]`. See the [connection-slot author guide](https://github.com/PowerPlatformToolBox/desktop-app/blob/main/docs/N_CONNECTION_TOOL_AUTHOR_GUIDE.md) for migration and lifecycle examples.
+
 ```typescript
 // Get the active Dataverse connection
 const connection = await toolboxAPI.connections.getActiveConnection();
@@ -339,6 +353,42 @@ const terminals = await toolboxAPI.terminal.list();
 await toolboxAPI.terminal.close(terminal.id);
 ```
 
+### Native Workers
+
+If a tool declares a .NET worker in `pptb.config.json`, connect to it through
+`toolboxAPI.workers.connect()`. PPTB owns process startup, consent, JSON-RPC
+framing, readiness, request correlation, cancellation and cleanup. Tool code only
+registers any worker-to-tool callbacks it needs, then calls worker methods by
+name:
+
+```typescript
+const worker = await toolboxAPI.workers.connect("sample", {
+    requests: {
+        "dataverse/fetchXml": async (params, context) => {
+            if (context.isCancellationRequested) throw new Error("Request cancelled");
+            const fetchXml = String(params);
+            const result = await dataverseAPI.fetchXmlQuery(fetchXml);
+            if (context.isCancellationRequested) throw new Error("Request cancelled");
+            return { value: result.value };
+        },
+    },
+    notifications: {
+        progress: (message) => setStatus(String(message)),
+    },
+});
+
+await worker.ready;
+const result = await worker.request("query", fetchXml);
+await worker.stop();
+```
+
+Use `worker.cancel()` to cancel outstanding requests. `worker.stop()` waits for
+PPTB's verified process cleanup; if it rejects, keep the session and let the user
+retry stop rather than claiming the worker was stopped. Workers are trusted
+native code running as the current OS user, not sandboxed. Do not send tokens or
+credential material to them; implement narrowly scoped reverse requests through
+PPTB APIs instead.
+
 ### Events
 
 ```typescript
@@ -690,6 +740,13 @@ Core platform features organized into namespaces:
 
 #### Connections
 
+- **getConnections()**: Promise<Array<Connection | null>>
+    - Returns configured slots, preserving null gaps; not necessarily padded to the declared maximum.
+- **getConnection(target: "primary" | "secondary" | number)**: Promise<Connection | null>
+    - Gets one slot by zero-based index or legacy alias. Unassigned slots return null; negative/fractional targets reject.
+- **getSecondaryConnection()**: Promise<Connection | null>
+    - Deprecated compatibility adapter; prefer `getConnection("secondary")`.
+
 - **getActiveConnection()**: Promise<Connection | null>
     - Returns the currently active connection or null if none is active
     - Includes `enabledForPowerPlatformAPI` so tools can decide whether to use Power Platform API
@@ -750,6 +807,21 @@ Core platform features organized into namespaces:
 - **setVisibility(terminalId: string, visible: boolean)**: Promise<void>
     - Shows or hides the terminal UI for the specified terminal id
 
+#### Workers
+
+- **connect(workerId: string, options?: WorkerSessionOptions)**: Promise<WorkerSession>
+    - Starts the declared worker and returns a JSON-RPC session. `ready` resolves after the protocol initialize handshake.
+    - `options.requests` registers worker-initiated requests handled by the tool; `options.notifications` handles worker notifications; `options.onExit` observes process termination.
+- **WorkerSession.request<Result>(method: string, params?: unknown)**: Promise<Result>
+    - Sends a named request to the worker and resolves with its result.
+- **WorkerSession.notify(method: string, params?: unknown)**: Promise<void>
+    - Sends a notification to the worker.
+- **WorkerSession.cancel()**: void
+    - Requests cancellation of outstanding requests. Worker and callback cancellation is cooperative.
+- **WorkerSession.stop() / dispose()**: Promise<void>
+    - Stops the worker and waits for verified cleanup. A failed stop must remain visible and retryable.
+- **WorkerSessionOptions.requests** handlers receive `(params, context)`, where `context.isCancellationRequested` and `context.onCancellationRequested()` expose cancellation without exposing transport details.
+
 #### Events
 
 - **getHistory(limit?: number)**: Promise<ToolBoxEventPayload[]>
@@ -784,7 +856,7 @@ Core platform features organized into namespaces:
 - **launchTool(targetToolId, prefillData?, options?)**: Promise\<unknown\>
     - Launches the specified tool, optionally with prefill data
     - Returns a Promise that resolves with the data returned by the callee, or `null` if it closes without returning or the user clicks the "Return to Caller" banner
-    - The callee automatically inherits the caller's FXS connection; pass `options.primaryConnectionId` to override
+    - The callee inherits the caller's full positional connection array, bounded by its declared maximum; `options.connectionIds` replaces the array and legacy overrides affect only slots 0/1
     - Only one active callee per caller is allowed; throws `"A callee invocation is already in progress"` if a callee is already open
     - Pass `options.noReturn: true` for one-way "Send To" flows; the banner is suppressed entirely for the callee
 
@@ -835,13 +907,13 @@ Complete HTTP client for interacting with Microsoft Dataverse:
     - Supports both bound and unbound operations
 - **publishCustomizations(tableLogicalName?: string)**: Promise<void>
     - Publishes pending customizations. When `tableLogicalName` is omitted it runs PublishAllXml; otherwise it publishes only the specified table.
-- **deploySolution(base64SolutionContent: string | ArrayBuffer | ArrayBufferView, options?: DeploySolutionOptions, connectionTarget?: "primary" | "secondary")**: Promise<{ImportJobId: string}>
+- **deploySolution(base64SolutionContent: string | ArrayBuffer | ArrayBufferView, options?: DeploySolutionOptions, connectionTarget?: "primary" | "secondary" | number)**: Promise<{ImportJobId: string}>
     - Deploys (imports) a solution to the Dataverse environment
     - Accepts either a base64-encoded solution zip string or raw binary data (Buffer, ArrayBuffer, Uint8Array)
     - Always supplies `PublishWorkflows` and `OverwriteUnmanagedCustomizations` booleans to Dataverse, defaulting to `false` when you omit them
     - Supports optional parameters for customizing the import (publishWorkflows, overwriteUnmanagedCustomizations, skipProductUpdateDependencies, convertToManaged)
     - Returns an ImportJobId for tracking the import progress
-- **getImportJobStatus(importJobId: string, connectionTarget?: "primary" | "secondary")**: Promise<Record<string, unknown>>
+- **getImportJobStatus(importJobId: string, connectionTarget?: "primary" | "secondary" | number)**: Promise<Record<string, unknown>>
     - Gets the status of a solution import job
     - Returns import job details including progress, completion status, and error information
     - Use to track the progress of a solution deployment initiated with deploySolution
@@ -852,6 +924,8 @@ Generic HTTP client for Power Platform Admin APIs covering all categories:
 
 #### Category Methods
 
+`connectionTarget` accepts zero-based numeric slots plus `"primary"` / `"secondary"`. For example, `powerplatformAPI.PowerApps.Get("apps", 2)` routes to slot 3. Calling an API with an unassigned slot returns a missing-connection error.
+
 Each category (Analytics, AppManagement, Authorization, Connectivity, CopilotStudio, Dynamics, EnvironmentManagement, Governance, Licensing, PowerApps, PowerAutomate, PowerPages, ResourceQuery, UserManagement, WorkflowAgents) exposes:
 
 - **Get(path?, connectionTarget?, headers?)**: Promise<PowerPlatformResponse>

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pptb/types",
-  "version": "1.2.7-beta.4",
+  "version": "1.2.7-beta.6",
   "description": "Type definitions for Power Platform ToolBox APIs and validity checks for tool packages",
   "main": "index.d.ts",
   "types": "index.d.ts",

package/pptbConfig.d.ts

@@ -174,15 +174,40 @@ export interface InvocationConfig {
 }
 
 /**
- * The shape of a tool's `pptb.config.json` file.
- *
- * This file lives alongside `package.json` in the tool's package root.
- * All sections are optional; the file itself is optional.  When present it
- * is validated by `pptb-validate` in addition to `package.json`.
+ * Author-facing runtime policy. Latest maps to native LatestMajor in later runtime work.
  */
+export type WorkerRollForward = "Disable" | "Latest" | "Minor" | "Major";
+export type WorkerTargetFramework = "net8.0" | "net9.0" | "net10.0";
+export type WorkerPlatform = "all" | "windows-x64" | "windows-arm64" | "macos-x64" | "macos-arm64" | "linux-x64" | "linux-arm64";
+
+/** Declarative metadata only; no worker execution API is available yet. */
+export interface WorkerDeclaration {
+    kind: "dotnet-tool";
+    packageId: string;
+    /** Exact NuGet version; ranges, floating versions and tags are forbidden. */
+    packageVersion: string;
+    command: string;
+    dotnet: {
+        targetFramework: WorkerTargetFramework;
+        /** Stable major.minor.patch matching the executable target framework. */
+        minimumRuntimeVersion: string;
+        /** Defaults to Major when omitted. Explicit null/empty/unknown values are invalid. */
+        rollForward?: WorkerRollForward;
+    };
+    /** Required unique aliases; all must appear alone and names the versioned officially supported PPTB platform matrix. */
+    platforms: WorkerPlatform[];
+}
+
+export interface NormalizedWorkerDeclaration extends WorkerDeclaration {
+    dotnet: WorkerDeclaration["dotnet"] & { rollForward: WorkerRollForward };
+}
+
+/** Optional package-root config, validated alongside package.json by pptb-validate. */
 export interface PPTBConfig {
     /** Invocation contract – how this tool can be called by other tools. */
     invocation?: InvocationConfig;
     /** Agent contract – how this tool can be called by external automation. */
     agents?: AgentsConfig;
+    /** Native worker declarations keyed by stable ID. Requires package.json features.minAPI. */
+    workers?: Record<string, WorkerDeclaration>;
 }

package/toolboxAPI.d.ts

@@ -169,6 +169,55 @@ declare namespace ToolBoxAPI {
         error?: string;
     }
 
+    const workerHandleBrand: unique symbol;
+    export type WorkerHandle = string & { readonly [workerHandleBrand]: true };
+
+    export type WorkerRpcMessage =
+        | { jsonrpc: "2.0"; method: string; id?: string | number; params?: unknown[] | Record<string, unknown> }
+        | { jsonrpc: "2.0"; id: string | number | null; result: unknown }
+        | { jsonrpc: "2.0"; id: string | number | null; error: { code: number; message: string; data?: unknown } };
+
+    export interface WorkerSnapshot {
+        state: "starting" | "running" | "stopping" | "exited" | "failed";
+        failure?: string;
+        stderr: { bytes: number; truncated: boolean; summary: "Worker stderr redacted" };
+    }
+
+    export interface WorkerStart {
+        handle: WorkerHandle;
+        ready: Promise<void>;
+    }
+
+    export interface WorkerRequestContext {
+        readonly isCancellationRequested: boolean;
+        onCancellationRequested(callback: () => void): { dispose(): void };
+    }
+
+    export interface WorkerSessionOptions {
+        requests?: Record<string, (params: unknown, context: WorkerRequestContext) => unknown | Promise<unknown>>;
+        notifications?: Record<string, (params: unknown) => void>;
+        onExit?: (snapshot: WorkerSnapshot) => void;
+    }
+
+    export interface WorkerSession {
+        readonly ready: Promise<void>;
+        request<Result = unknown>(method: string, params?: unknown): Promise<Result>;
+        notify(method: string, params?: unknown): Promise<void>;
+        cancel(): void;
+        stop(): Promise<void>;
+        dispose(): Promise<void>;
+    }
+
+    export interface WorkersAPI {
+        connect(workerId: string, options?: WorkerSessionOptions): Promise<WorkerSession>;
+        start(workerId: string): Promise<WorkerStart>;
+        send(handle: WorkerHandle, message: WorkerRpcMessage): Promise<void>;
+        onMessage(handle: WorkerHandle, callback: (message: WorkerRpcMessage) => void): () => void;
+        onExit(handle: WorkerHandle, callback: (snapshot: WorkerSnapshot) => void): () => void;
+        stop(handle: WorkerHandle): Promise<void>;
+        dispose(handle: WorkerHandle): Promise<void>;
+    }
+
     /**
      * Connections namespace - restricted access for tools
      */
@@ -179,7 +228,7 @@ declare namespace ToolBoxAPI {
         getActiveConnection: () => Promise<Connection | null>;
 
         /**
-         * @deprecated Use `getConnection("secondary")` or `getConnections()[1]` for slot-aware connection access.
+         * @deprecated Use `getConnection("secondary")` or `(await getConnections())[1]` for slot-aware connection access.
          */
         getSecondaryConnection: () => Promise<Connection | null>;
 
@@ -406,6 +455,9 @@ declare namespace ToolBoxAPI {
      * Main ToolBox API exposed to tools via window.toolboxAPI
      */
     export interface API {
+        /** Start and communicate with a worker declared by this tool's manifest. */
+        workers: WorkersAPI;
+
         /**
          * Connection-related operations (restricted)
          */