CompanionRpc

CompanionRpc exposes a system-restricted RPC surface for paired companion apps. It provides a manifest of locally available tools, RPC methods, and workflows, and it can execute approved tools and workflows on behalf of those companion integrations.

Endpoints

POST /api/rpc (Method: CompanionRpc.getToolManifest)

This method returns a manifest describing tools exposed by the application for companion-app consumption. It can include AI tools, RPC methods, and workflows depending on the supplied flags.

• Description: Returns RPC and workflow tools exposed by this app for paired companion apps.

• Request Body:

  {
    "method": "CompanionRpc.getToolManifest",
    "params": {
      "includeAiTools": true,
      "includeRpc": true,
      "includeWorkflows": true
    }
  }

• Parameters:

  Name	Type	Required	Description
  includeAiTools	Boolean	No	When true, includes locally exposed AI tools in the manifest. Defaults to true when omitted.
  includeRpc	Boolean	No	When true, includes RPC methods in the manifest. Defaults to true when omitted.
  includeWorkflows	Boolean	No	When true, includes workflows in the manifest. Defaults to true when omitted.

• Response:

  {
    "success": true,
    "data": {
      "appName": "string",
      "namespace": "string",
      "aiTools": [
        {
          "appName": "string",
          "toolName": "string",
          "description": "string",
          "parameters": {
            "type": "object",
            "properties": {}
          },
          "source": "string"
        }
      ],
      "rpcTools": [
        {
          "appName": "string",
          "methodName": "string",
          "toolName": "string",
          "description": "string",
          "parameters": {
            "type": "object",
            "properties": {}
          }
        }
      ],
      "workflowTools": [
        {
          "appName": "string",
          "workflowName": "string",
          "toolName": "string",
          "description": "string",
          "parameters": {
            "type": "object",
            "properties": {}
          }
        }
      ]
    }
  }

  The aiTools, rpcTools, and workflowTools arrays are populated only when the corresponding include flags are enabled and the relevant manager is available. For RPC methods and workflows, parameter descriptions are derived from the registered Zod schemas when present; otherwise, an empty object schema is returned.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "CompanionRpc.getToolManifest",
      "params": {
        "includeAiTools": true,
        "includeRpc": true,
        "includeWorkflows": true
      }
    }'

POST /api/rpc (Method: CompanionRpc.executeTool)

This method executes a locally defined AI tool by name and forwards the provided parameters to the tool manager.

• Description: Executes a locally-defined AI tool on this app for a paired companion app.

• Request Body:

  {
    "method": "CompanionRpc.executeTool",
    "params": {
      "toolName": "string",
      "parameters": {}
    }
  }

• Parameters:

  Name	Type	Required	Description
  toolName	String	Yes	The name of the tool to execute.
  parameters	Object	No	Arbitrary tool arguments to pass to the tool executor. Defaults to an empty object when omitted.

• Response:

  {
    "success": true,
    "data": "tool-specific return value"
  }

  The return value is whatever the underlying tool executor returns. This endpoint throws an error if the tool manager is disabled, the named tool does not exist, or the tool is not exposed to companion apps.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "CompanionRpc.executeTool",
      "params": {
        "toolName": "example-tool",
        "parameters": {}
      }
    }'

POST /api/rpc (Method: CompanionRpc.executeWorkflow)

This method runs a workflow by name and passes the supplied parameters to the workflow executor.

• Description: Executes a workflow on this app for a paired companion app.

• Request Body:

  {
    "method": "CompanionRpc.executeWorkflow",
    "params": {
      "workflowName": "string",
      "parameters": {}
    }
  }

• Parameters:

  Name	Type	Required	Description
  workflowName	String	Yes	The workflow to execute.
  parameters	Object	No	Arbitrary workflow parameters to pass to the workflow executor. Defaults to an empty object when omitted.

• Response:

  {
    "success": true,
    "data": "workflow-specific return value"
  }

  The return value is whatever the underlying workflow executor returns. This endpoint throws an error if the workflow manager is disabled.

• Example (cURL):

  curl -X POST "${APP_BASE_URL}/api/rpc" \
    -H "Content-Type: application/json" \
    -d '{
      "method": "CompanionRpc.executeWorkflow",
      "params": {
        "workflowName": "example-workflow",
        "parameters": {}
      }
    }'

Access Control

All methods in CompanionRpc are marked systemOnly: true and also enforce an explicit runtime check that requires context.isSystem to be truthy. If that condition is not met, the RPC throws Access Denied: Companion RPC is restricted to system calls.

Execution Flow