@pptb/types 1.2.1 → 1.2.2-beta.1

package/README.md

@@ -8,6 +8,7 @@ TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI
         - [Quick start](#quick-start)
         - [CLI options](#cli-options)
         - [What is validated](#what-is-validated)
+        - [pptb.config.json (optional)](#pptbconfigjson-optional)
     - [Overview](#overview)
     - [Usage](#usage)
         - [Include all type definitions](#include-all-type-definitions)
@@ -17,6 +18,7 @@ TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI
         - [Utilities](#utilities)
         - [Terminal Operations](#terminal-operations)
         - [Events](#events)
+        - [Inter-Tool Invocation](#inter-tool-invocation)
     - [Dataverse API Examples](#dataverse-api-examples)
         - [CRUD Operations](#crud-operations)
         - [FetchXML Queries](#fetchxml-queries)
@@ -29,6 +31,7 @@ TypeScript type definitions for Power Platform ToolBox APIs, plus a built-in CLI
             - [Utils](#utils)
             - [Terminal](#terminal)
             - [Events](#events-1)
+            - [Invocation](#invocation)
         - [Dataverse API (`window.dataverseAPI`)](#dataverse-api-windowdataverseapi)
             - [CRUD Operations](#crud-operations-1)
             - [Query Operations](#query-operations)
@@ -109,6 +112,43 @@ The validator checks every field that the official review pipeline inspects:
 
 > \* Required only when the `features` object is present.
 
+#### pptb.config.json (optional)
+
+In addition to `package.json`, the validator automatically checks a `pptb.config.json` file if one is present in the same directory. This file declares tool-to-tool communication contracts and other PPTB-specific metadata.
+
+| Field                                   | Required | Rules                                                                                                                     |
+| --------------------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------- |
+| `invocation.version`                    | ✅\*\*   | Must be a valid **semantic version** string (e.g. `"1.0.0"`). Tool developers own this version and bump it when the invocation contract changes. |
+| `invocation.prefill`                    | ❌       | JSON-schema-style object describing data callers can pre-populate                                                         |
+| `invocation.prefill.properties`         | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                           |
+| `invocation.returnTopic`                | ❌       | JSON-schema-style object describing the data this tool returns to its caller                                              |
+| `invocation.returnTopic.properties`     | ❌       | Map of property names to `{ type?, enum?, items? }` descriptors                                                           |
+
+> \*\* Required only when the `invocation` object is present.
+
+**Example `pptb.config.json`:**
+
+```json
+{
+    "invocation": {
+        "version": "1.0.0",
+        "prefill": {
+            "properties": {
+                "entityName": { "type": "string" },
+                "attributes": { "type": "array", "items": { "type": "string" } }
+            }
+        },
+        "returnTopic": {
+            "properties": {
+                "result": { "type": "object" },
+                "status": { "type": "string", "enum": ["success", "cancelled", "error"] },
+                "error": { "type": "string" }
+            }
+        }
+    }
+}
+```
+
 ## Overview
 
 The `@pptb/types` package provides TypeScript definitions for two main APIs:
@@ -248,6 +288,67 @@ toolboxAPI.events.on((event, payload) => {
 const history = await toolboxAPI.events.getHistory(10); // Last 10 events
 ```
 
+### Inter-Tool Invocation
+
+Tools can launch one another and pass data between them using the `invocation` namespace.
+
+#### Caller: launching another tool with prefill data
+
+```typescript
+// Tool A – launches the entity-picker tool and waits for a selection
+const result = await toolboxAPI.invocation.launchTool(
+    "@my-org/entity-picker",
+    { entityName: "account", allowMultiSelect: false },
+);
+
+if (result) {
+    console.log("Selected record id:", (result as { selectedId: string }).selectedId);
+}
+```
+
+#### Callee: reading prefill data and returning a result
+
+```typescript
+// Tool B (@my-org/entity-picker) – reads the context provided by Tool A
+const ctx = await toolboxAPI.invocation.getLaunchContext();
+if (ctx) {
+    const entityName = ctx.entityName as string; // "account"
+    // … show records from entityName …
+
+    // When the user makes their selection:
+    await toolboxAPI.invocation.returnData({ selectedId: "a1b2c3...", selectedName: "Contoso" });
+}
+```
+
+> **Tip:** A tool that was *not* launched by another tool receives `null` from `getLaunchContext()`.  
+> Use this to show a standalone UI or redirect accordingly.
+
+#### Declaring your invocation contract
+
+Add a `pptb.config.json` alongside your `package.json` to tell callers what data you expect and return:
+
+```json
+{
+    "invocation": {
+        "version": "1.0.0",
+        "prefill": {
+            "properties": {
+                "entityName": { "type": "string" },
+                "allowMultiSelect": { "type": "boolean" }
+            }
+        },
+        "returnTopic": {
+            "properties": {
+                "selectedId": { "type": "string" },
+                "selectedName": { "type": "string" }
+            }
+        }
+    }
+}
+```
+
+Run `pptb-validate` to validate both `package.json` and `pptb.config.json` at once.
+
 ## Dataverse API Examples
 
 The Dataverse API provides direct access to Microsoft Dataverse operations:
@@ -495,6 +596,19 @@ Core platform features organized into namespaces:
 - **off(callback: (event: any, payload: ToolBoxEventPayload) => void)**: void
     - Removes a previously registered event listener
 
+#### Invocation
+
+- **getLaunchContext()**: Promise\<Record\<string, unknown\> | null\>
+    - Returns the prefill data passed by the tool that launched this tool, or `null` when not launched via inter-tool invocation
+
+- **returnData(returnData: Record\<string, unknown\>)**: Promise\<void\>
+    - Sends data back to the caller tool and signals completion; no-op if not launched by another tool
+
+- **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)
+    - `options.primaryConnectionId` / `options.secondaryConnectionId` – override connection for the callee
+
 ### Dataverse API (`window.dataverseAPI`)
 
 Complete HTTP client for interacting with Microsoft Dataverse:

package/bin/pptb-validate.js

@@ -16,7 +16,7 @@
 
 const fs = require("fs");
 const path = require("path");
-const { validatePackageJson } = require("../lib/validate");
+const { validatePackageJson, validatePPTBConfig } = require("../lib/validate");
 
 // ANSI colour helpers – gracefully degrade when colours are unsupported
 const NO_COLOR = !process.stdout.isTTY || process.env.NO_COLOR;
@@ -37,7 +37,8 @@ ${c.bold("USAGE")}
   pptb-validate [options] [path/to/package.json]
 
   When no path is given the tool looks for ${c.cyan("package.json")} in the current
-  working directory.
+  working directory. If a ${c.cyan("pptb.config.json")} file exists in the same directory
+  it is automatically validated as well.
 
 ${c.bold("OPTIONS")}
   ${c.cyan("--skip-url-checks")}   Skip URL reachability checks (faster, works offline)
@@ -79,6 +80,10 @@ async function main() {
         packageJsonPath = path.resolve(process.cwd(), packageJsonPath);
     }
 
+    // Derive pptb.config.json path from the same directory as package.json
+    const toolDir = path.dirname(packageJsonPath);
+    const pptbConfigPath = path.join(toolDir, "pptb.config.json");
+
     // --- Load package.json ---
     if (!fs.existsSync(packageJsonPath)) {
         if (jsonOutput) {
@@ -102,21 +107,35 @@ async function main() {
         process.exit(1);
     }
 
+    // --- Load pptb.config.json (optional) ---
+    let pptbConfig = null;
+    let pptbConfigParseError = null;
+    if (fs.existsSync(pptbConfigPath)) {
+        try {
+            pptbConfig = JSON.parse(fs.readFileSync(pptbConfigPath, "utf8"));
+        } catch (err) {
+            pptbConfigParseError = err instanceof Error ? err.message : String(err);
+        }
+    }
+
     // --- Run validation ---
     if (!jsonOutput) {
         console.log();
         console.log(c.bold("Power Platform ToolBox – Tool Validator"));
         console.log(c.dim("─".repeat(45)));
         console.log(c.dim(`File: ${packageJsonPath}`));
+        if (pptbConfig !== null) {
+            console.log(c.dim(`Config: ${pptbConfigPath}`));
+        }
         if (skipUrlChecks) {
             console.log(c.yellow("⚠  URL reachability checks are skipped"));
         }
         console.log();
     }
 
-    let result;
+    let packageResult;
     try {
-        result = await validatePackageJson(packageJson, { skipUrlChecks });
+        packageResult = await validatePackageJson(packageJson, { skipUrlChecks });
     } catch (err) {
         const message = err instanceof Error ? err.message : String(err);
         if (jsonOutput) {
@@ -127,27 +146,62 @@ async function main() {
         process.exit(1);
     }
 
+    // --- Validate pptb.config.json if present ---
+    let configResult = null;
+    if (pptbConfigParseError !== null) {
+        configResult = { valid: false, errors: [`Failed to parse pptb.config.json: ${pptbConfigParseError}`], warnings: [] };
+    } else if (pptbConfig !== null) {
+        configResult = validatePPTBConfig(pptbConfig);
+    }
+
+    // Merge results for overall pass/fail
+    const allErrors = [...packageResult.errors, ...(configResult ? configResult.errors : [])];
+    const allWarnings = [...packageResult.warnings, ...(configResult ? configResult.warnings : [])];
+    const overallValid = packageResult.valid && (configResult === null || configResult.valid);
+
     // --- Output results ---
     if (jsonOutput) {
-        console.log(JSON.stringify(result, null, 2));
-        process.exit(result.valid ? 0 : 1);
+        const output = {
+            valid: overallValid,
+            errors: allErrors,
+            warnings: allWarnings,
+            packageInfo: packageResult.packageInfo,
+            configInfo: configResult ? configResult.packageInfo : undefined,
+        };
+        console.log(JSON.stringify(output, null, 2));
+        process.exit(overallValid ? 0 : 1);
     }
 
-    // Human-readable output
-    if (result.errors.length > 0) {
-        console.log(c.bold(c.red(`Errors (${result.errors.length})`)));
-        result.errors.forEach((e) => console.log(`  ${c.red("✖")} ${e}`));
+    // Human-readable output – package.json section
+    if (packageResult.errors.length > 0) {
+        console.log(c.bold(c.red(`package.json Errors (${packageResult.errors.length})`)));
+        packageResult.errors.forEach((e) => console.log(`  ${c.red("✖")} ${e}`));
         console.log();
     }
 
-    if (result.warnings.length > 0) {
-        console.log(c.bold(c.yellow(`Warnings (${result.warnings.length})`)));
-        result.warnings.forEach((w) => console.log(`  ${c.yellow("⚠")} ${w}`));
+    if (packageResult.warnings.length > 0) {
+        console.log(c.bold(c.yellow(`package.json Warnings (${packageResult.warnings.length})`)));
+        packageResult.warnings.forEach((w) => console.log(`  ${c.yellow("⚠")} ${w}`));
         console.log();
     }
 
-    if (result.valid) {
-        const info = result.packageInfo;
+    // Human-readable output – pptb.config.json section
+    if (configResult !== null) {
+        if (configResult.errors.length > 0) {
+            console.log(c.bold(c.red(`pptb.config.json Errors (${configResult.errors.length})`)));
+            configResult.errors.forEach((e) => console.log(`  ${c.red("✖")} ${e}`));
+            console.log();
+        }
+
+        if (configResult.warnings.length > 0) {
+            console.log(c.bold(c.yellow(`pptb.config.json Warnings (${configResult.warnings.length})`)));
+            configResult.warnings.forEach((w) => console.log(`  ${c.yellow("⚠")} ${w}`));
+            console.log();
+        }
+    }
+
+    if (overallValid) {
+        const info = packageResult.packageInfo;
         console.log(c.green(c.bold("✔ Validation passed")));
         console.log();
         console.log(c.bold("Package summary"));
@@ -157,13 +211,16 @@ async function main() {
         console.log(`  Display name: ${info.displayName}`);
         console.log(`  Description : ${info.description}`);
         console.log(`  License     : ${info.license}`);
-        console.log(`  Contributors: ${info.contributors.map((c) => c.name).join(", ")}`);
+        console.log(`  Contributors: ${info.contributors.map((contributor) => contributor.name).join(", ")}`);
         if (info.icon) {
             console.log(`  Icon        : ${info.icon}`);
         }
         if (info.features) {
             console.log(`  Features    : multiConnection=${info.features.multiConnection}${info.features.minAPI ? `, minAPI=${info.features.minAPI}` : ""}`);
         }
+        if (configResult !== null && configResult.packageInfo && configResult.packageInfo.invocation) {
+            console.log(`  Invocation  : version=${configResult.packageInfo.invocation.version}`);
+        }
         console.log();
     } else {
         console.log(c.red(c.bold("✖ Validation failed")));
@@ -172,7 +229,7 @@ async function main() {
         console.log();
     }
 
-    process.exit(result.valid ? 0 : 1);
+    process.exit(overallValid ? 0 : 1);
 }
 
 main().catch((err) => {

package/index.d.ts

@@ -16,7 +16,9 @@
 
 /// <reference path="./toolboxAPI.d.ts" />
 /// <reference path="./dataverseAPI.d.ts" />
+/// <reference path="./pptbConfig.d.ts" />
 
 // Re-export all namespaces for convenience
 export * from "./dataverseAPI";
 export * from "./toolboxAPI";
+export * from "./pptbConfig";

package/lib/validate.js

@@ -33,6 +33,19 @@
  * }} ValidationResult
  */
 
+/**
+ * @typedef {{ type?: string; enum?: string[]; items?: object }} JsonSchemaProperty
+ * @typedef {{ properties?: Record<string, JsonSchemaProperty> }} JsonSchemaObject
+ * @typedef {{
+ *   version: string;
+ *   prefill?: JsonSchemaObject;
+ *   returnTopic?: JsonSchemaObject;
+ * }} InvocationConfig
+ * @typedef {{
+ *   invocation?: InvocationConfig;
+ * }} PPTBConfig
+ */
+
 // List of approved open source licenses
 const APPROVED_LICENSES = ["MIT", "Apache-2.0", "BSD-2-Clause", "BSD-3-Clause", "GPL-2.0", "GPL-3.0", "LGPL-3.0", "ISC", "AGPL-3.0-only"];
 
@@ -321,4 +334,110 @@ async function validatePackageJson(packageJson, options = {}) {
     };
 }
 
-module.exports = { validatePackageJson, isValidUrl, APPROVED_LICENSES };
+module.exports = { validatePackageJson, validatePPTBConfig, isValidUrl, APPROVED_LICENSES };
+
+/**
+ * Validates a tool's pptb.config.json against the official review criteria.
+ *
+ * @param {PPTBConfig} config - The parsed pptb.config.json object.
+ * @returns {ValidationResult}
+ */
+function validatePPTBConfig(config) {
+    const errors = /** @type {string[]} */ ([]);
+    const warnings = /** @type {string[]} */ ([]);
+
+    if (config === null || typeof config !== "object" || Array.isArray(config)) {
+        errors.push("pptb.config.json must be a JSON object");
+        return { valid: false, errors, warnings };
+    }
+
+    const VALID_ROOT_KEYS = ["invocation"];
+    const unknownRootKeys = Object.keys(config).filter((k) => !VALID_ROOT_KEYS.includes(k));
+    if (unknownRootKeys.length > 0) {
+        warnings.push(`pptb.config.json contains unrecognised root keys: ${unknownRootKeys.join(", ")}`);
+    }
+
+    // Invocation section
+    if (config.invocation !== undefined) {
+        const inv = config.invocation;
+
+        if (inv === null || typeof inv !== "object" || Array.isArray(inv)) {
+            errors.push("invocation must be a non-array object");
+        } else {
+            // invocation.version – required, must be a valid semver string
+            if (inv.version === undefined || inv.version === null) {
+                errors.push("invocation.version is required");
+            } else if (typeof inv.version !== "string") {
+                errors.push("invocation.version must be a string");
+            } else if (!SEMVER_REGEX.test(inv.version)) {
+                errors.push(`invocation.version "${inv.version}" is not a valid semantic version string (e.g. "1.0.0")`);
+            }
+
+            // invocation.prefill – optional JSON-schema-like object
+            if (inv.prefill !== undefined) {
+                if (inv.prefill === null || typeof inv.prefill !== "object" || Array.isArray(inv.prefill)) {
+                    errors.push("invocation.prefill must be a non-array object");
+                } else if (inv.prefill.properties !== undefined) {
+                    validateJsonSchemaProperties("invocation.prefill", inv.prefill.properties, errors);
+                }
+            }
+
+            // invocation.returnTopic – optional JSON-schema-like object
+            if (inv.returnTopic !== undefined) {
+                if (inv.returnTopic === null || typeof inv.returnTopic !== "object" || Array.isArray(inv.returnTopic)) {
+                    errors.push("invocation.returnTopic must be a non-array object");
+                } else if (inv.returnTopic.properties !== undefined) {
+                    validateJsonSchemaProperties("invocation.returnTopic", inv.returnTopic.properties, errors);
+                }
+            }
+        }
+    }
+
+    const valid = errors.length === 0;
+
+    return {
+        valid,
+        errors,
+        warnings,
+        packageInfo: valid
+            ? {
+                  invocation: config.invocation,
+              }
+            : undefined,
+    };
+}
+
+/**
+ * Validates a JSON-schema-style `properties` map used inside invocation sections.
+ * Only performs basic structural validation; full JSON Schema validation is not required.
+ *
+ * @param {string} fieldName
+ * @param {unknown} properties
+ * @param {string[]} errors
+ */
+function validateJsonSchemaProperties(fieldName, properties, errors) {
+    if (properties === null || typeof properties !== "object" || Array.isArray(properties)) {
+        errors.push(`${fieldName}.properties must be a non-array object`);
+        return;
+    }
+
+    const propsRecord = /** @type {Record<string, unknown>} */ (properties);
+
+    for (const [key, value] of Object.entries(propsRecord)) {
+        if (value === null || typeof value !== "object" || Array.isArray(value)) {
+            errors.push(`${fieldName}.properties.${key} must be an object`);
+            continue;
+        }
+        const prop = /** @type {Record<string, unknown>} */ (value);
+        if (prop.type !== undefined && typeof prop.type !== "string") {
+            errors.push(`${fieldName}.properties.${key}.type must be a string`);
+        }
+        if (prop.enum !== undefined) {
+            if (!Array.isArray(prop.enum)) {
+                errors.push(`${fieldName}.properties.${key}.enum must be an array`);
+            } else if (prop.enum.length === 0) {
+                errors.push(`${fieldName}.properties.${key}.enum must not be empty`);
+            }
+        }
+    }
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@pptb/types",
-  "version": "1.2.1",
+  "version": "1.2.2-beta.1",
   "description": "Type definitions for Power Platform ToolBox APIs and validity checks for tool packages",
   "main": "index.d.ts",
   "types": "index.d.ts",
@@ -26,6 +26,7 @@
     "index.d.ts",
     "toolboxAPI.d.ts",
     "dataverseAPI.d.ts",
+    "pptbConfig.d.ts",
     "bin/",
     "lib/",
     "README.md"

package/pptbConfig.d.ts

@@ -0,0 +1,82 @@
+/**
+ * Type definitions for pptb.config.json – the optional configuration file that
+ * tools can place alongside their package.json to declare invocation contracts
+ * and other Power Platform ToolBox-specific metadata.
+ *
+ * Tool developers should place this file in the root of their tool package so
+ * that `pptb-validate` can automatically discover and validate it.
+ *
+ * Example pptb.config.json:
+ * ```json
+ * {
+ *   "invocation": {
+ *     "version": "1.0.0",
+ *     "prefill": {
+ *       "properties": {
+ *         "entityName": { "type": "string" },
+ *         "attributes": { "type": "array", "items": { "type": "string" } }
+ *       }
+ *     },
+ *     "returnTopic": {
+ *       "properties": {
+ *         "result": { "type": "object" },
+ *         "status": { "type": "string", "enum": ["success", "cancelled", "error"] },
+ *         "error": { "type": "string" }
+ *       }
+ *     }
+ *   }
+ * }
+ * ```
+ */
+
+/** A JSON-schema-style property descriptor used inside invocation definitions. */
+export interface JsonSchemaProperty {
+    /** The JSON type of the value (e.g. "string", "number", "boolean", "object", "array"). */
+    type?: string;
+    /** Restricts the value to one of the listed literals. */
+    enum?: string[];
+    /** Describes the items of an array property. */
+    items?: JsonSchemaProperty;
+}
+
+/** A JSON-schema-style object definition: a map of named property descriptors. */
+export interface JsonSchemaObject {
+    properties?: Record<string, JsonSchemaProperty>;
+}
+
+/**
+ * The invocation contract for a tool.
+ *
+ * - `version` controls which revision of this contract is in effect.  It must
+ *   follow **semantic versioning** (`MAJOR.MINOR.PATCH[-prerelease][+build]`).
+ *   Tool developers own this version and should bump it whenever the shape of
+ *   `prefill` or `returnTopic` changes in a meaningful way.
+ * - `prefill` describes the data that callers can pre-populate when opening
+ *   this tool programmatically.
+ * - `returnTopic` describes the data this tool will resolve back to its caller
+ *   when it finishes.
+ */
+export interface InvocationConfig {
+    /**
+     * Semantic version of this invocation contract (e.g. "1.0.0").
+     * Tool developers control this version so they can evolve the prefill or
+     * return shape independently of the tool's npm package version.
+     */
+    version: string;
+    /** Schema of the data the caller can pass in when invoking this tool. */
+    prefill?: JsonSchemaObject;
+    /** Schema of the data this tool returns to its caller on completion. */
+    returnTopic?: JsonSchemaObject;
+}
+
+/**
+ * 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`.
+ */
+export interface PPTBConfig {
+    /** Invocation contract – how this tool can be called by other tools. */
+    invocation?: InvocationConfig;
+}

package/toolboxAPI.d.ts

@@ -397,6 +397,14 @@ declare namespace ToolBoxAPI {
          */
         events: EventsAPI;
 
+        /**
+         * Inter-tool launch context API.
+         *
+         * Allows one tool to launch another, pass prefill data to it, and receive
+         * a return value when the callee finishes.
+         */
+        invocation: InvocationAPI;
+
         /**
          * Get the current tool context
          * @internal Used internally by the framework
@@ -404,6 +412,76 @@ declare namespace ToolBoxAPI {
         getToolContext: () => Promise<ToolContext>;
     }
 
+    /**
+     * Inter-tool launch context API.
+     *
+     * Tools use this namespace to:
+     * 1. **Launch another tool** with prefill data (`invocation.launchTool`).
+     * 2. **Read their own launch context** when they were launched by another tool (`invocation.getLaunchContext`).
+     * 3. **Return data** back to the tool that launched them (`invocation.returnData`).
+     *
+     * @example Caller (Tool A)
+     * ```ts
+     * const result = await toolboxAPI.invocation.launchTool(
+     *   "@my-org/entity-picker",
+     *   { entityName: "account" },
+     * );
+     * console.log(result); // { selectedId: "...", selectedName: "..." }
+     * ```
+     *
+     * @example Callee (Tool B)
+     * ```ts
+     * const ctx = await toolboxAPI.invocation.getLaunchContext();
+     * if (ctx) {
+     *   console.log(ctx.entityName); // "account"
+     * }
+     *
+     * // After user picks something...
+     * await toolboxAPI.invocation.returnData({ selectedId, selectedName });
+     * ```
+     */
+    export interface InvocationAPI {
+        /**
+         * Returns the prefill data that was passed by the caller tool when it launched
+         * this tool, or `null` if this tool was not launched via an inter-tool invocation.
+         */
+        getLaunchContext: () => Promise<Record<string, unknown> | null>;
+
+        /**
+         * Returns data back to the caller tool that launched this tool.
+         *
+         * The value resolves the `Promise` returned by the caller's
+         * `invocation.launchTool()` call.  After calling `returnData`, the PPTB host
+         * will notify the caller; it is the callee's responsibility to close itself (or
+         * update its UI) after the return.
+         *
+         * If this tool was not launched by another tool, the call is a no-op.
+         *
+         * @param returnData The data to pass back to the caller
+         */
+        returnData: (returnData: Record<string, unknown>) => Promise<void>;
+
+        /**
+         * Launch another tool from within this tool and (optionally) pass prefill data.
+         *
+         * Returns a Promise that resolves with the data the target tool sends via
+         * `invocation.returnData()`, or `null` if the target tool closes without
+         * returning any data.
+         *
+         * The target tool must be installed and its `pptb.config.json` must declare an
+         * `invocation.prefill` schema that matches the shape of `prefillData`.
+         *
+         * @param targetToolId The npm package name (toolId) of the tool to launch
+         * @param prefillData  Data to pre-populate the target tool's state
+         * @param options      Optional connection overrides for the target tool
+         */
+        launchTool: (
+            targetToolId: string,
+            prefillData?: Record<string, unknown>,
+            options?: { primaryConnectionId?: string | null; secondaryConnectionId?: string | null },
+        ) => Promise<unknown>;
+    }
+
     /**
      * Auto-update event handlers
      */