reference ~9 min
PipeContextProtocol Package API

- [Overview](#overview)

PipeContextProtocol Package API

Table of Contents

Overview

The PipeContextProtocol (PCP) package provides a comprehensive tool execution system that allows LLMs to interact with external systems through multiple transport mechanisms including stdio, HTTP, Python, and native TPipe functions.

Core Classes

PcpContext

Main configuration container for PCP tool availability and security settings.

@Serializable
data class PcpContext(@Transient val cinit: Boolean = false)

Public Properties

Transport Configuration:

  • transport: Transport: Default transport mechanism (Auto, Stdio, TPipe, Http, Python, Kotlin, JavaScript)

Tool Options:

  • stdioOptions: MutableList<StdioContextOptions>: Available stdio commands
  • tpipeOptions: MutableList<TPipeContextOptions>: Available TPipe functions
  • httpOptions: MutableList<HttpContextOptions>: Available HTTP endpoints
  • pythonOptions: PythonContext: Python execution environment
  • kotlinOptions: KotlinContext: Kotlin scripting configuration
  • javascriptOptions: JavaScriptContext: JavaScript/Node.js configuration

Security Settings:

  • allowedDirectoryPaths: MutableList<String>: Permitted directory access
  • forbiddenDirectoryPaths: MutableList<String>: Restricted directories
  • allowedFiles: MutableList<String>: Permitted file access
  • forbiddenFiles: MutableList<String>: Restricted files
  • enableSessionAccessControl: Boolean: Session-based access control
  • enableBufferAccessControl: Boolean: Buffer access validation
  • currentUserId: String: Current user for access control

Public Functions

addStdioOption(option: StdioContextOptions) Adds stdio command option to available tools.

addTPipeOption(option: TPipeContextOptions) Adds TPipe function option to available tools.

Behavior: Only adds options with non-blank function names to prevent invalid tool registration.

PcPRequest

Request object generated by LLMs for tool execution.

@Serializable
data class PcPRequest(
    val stdioContextOptions: StdioContextOptions = StdioContextOptions(),
    val tPipeContextOptions: TPipeContextOptions = TPipeContextOptions(),
    val httpContextOptions: HttpContextOptions = HttpContextOptions(),
    val pythonContextOptions: PythonContext = PythonContext(),
    val argumentsOrFunctionParams: List<String> = mutableListOf()
)

Public Properties

Context Options: Each transport type has its own context options populated by the LLM based on the desired tool execution.

Parameters: argumentsOrFunctionParams contains the actual arguments or script content for execution.

PcpExecutionDispatcher

Central dispatcher that routes PCP requests to appropriate executors.

class PcpExecutionDispatcher

Public Functions

executeRequest(request: PcPRequest, context: PcpContext): PcpRequestResult Executes a single PCP request with context validation.

Behavior:

  • Determines transport type from request content
  • Validates transport against context restrictions
  • Routes to appropriate executor (stdio, HTTP, Python, TPipe)
  • Returns structured result with success status and output
  • Handles execution errors gracefully

executeRequests(requests: List<PcPRequest>, context: PcpContext): PcpExecutionResult Executes multiple PCP requests concurrently.

Behavior:

  • Processes requests in parallel using coroutines
  • Aggregates results and execution times
  • Collects all errors for comprehensive reporting
  • Returns overall success status based on individual results

PcpResponseParser

Parses LLM responses to extract and validate PCP requests.

class PcpResponseParser

Public Functions

extractPcpRequests(llmResponse: String): PcpParseResult Extracts PCP requests from LLM response text.

Behavior:

  • Uses TPipe’s extractJson utility for robust JSON parsing
  • Handles malformed JSON with automatic repair
  • Supports both single requests and request arrays
  • Validates each extracted request
  • Returns comprehensive parse results with errors

validatePcpRequest(request: PcPRequest): PcpValidationResult Validates PCP request for completeness and correctness.

Behavior:

  • Checks transport-specific required fields
  • Validates function names, commands, URLs, scripts
  • Ensures at least one transport context is populated
  • Returns detailed validation errors for debugging

determineTransport(request: PcPRequest): Transport Determines transport type based on populated context options.

Behavior:

  • Analyzes which context options contain data
  • Returns appropriate transport type
  • Handles ambiguous cases with priority ordering

Context Options

ContextOptionParameter

Data class defining a parameter for a context option.

data class ContextOptionParameter(
    val type: ParamType,
    val description: String,
    val enumValues: List<String> = emptyList(),
    val isRequired: Boolean = false
)

Properties:

  • type: ParamType: The data type of the parameter (e.g., String, Int, List).
  • description: String: Optional explanation of the parameter for the LLM.
  • enumValues: List<String>: List of allowed values if the parameter acts as an enum.
  • isRequired: Boolean: Boolean indicating whether the LLM is required to provide this parameter.

StdioContextOptions

Configuration for stdio command execution.

@Serializable
data class StdioContextOptions(@Transient val cinit: Boolean = false)

Key Properties

Command Configuration:

  • command: String: Command/program to execute
  • args: MutableList<String>: Allowed arguments
  • description: String: LLM-facing command description

Execution Control:

  • executionMode: StdioExecutionMode: ONE_SHOT, INTERACTIVE, CONNECT, BUFFER_REPLAY
  • sessionId: String?: Session identifier for persistent connections
  • bufferId: String?: Buffer identifier for replay operations
  • timeoutMs: Long: Execution timeout (default: 30000ms)

Environment:

  • workingDirectory: String?: Command working directory
  • environmentVariables: MutableMap<String, String>: Environment variables
  • keepSessionAlive: Boolean: Maintain session after execution
  • bufferPersistence: Boolean: Enable buffer persistence
  • maxBufferSize: Int: Maximum buffer size (default: 1MB)

Security:

  • permissions: MutableList<Permissions>: Allowed operations (Read, Write, Delete, Execute)

TPipeContextOptions

Configuration for native TPipe function calls.

@Serializable
data class TPipeContextOptions(@Transient val cinit: Boolean = false)

Key Properties

Function Definition:

  • functionName: String: Function name for LLM calls
  • description: String: Function purpose and usage
  • params: MutableMap<String, Triple<ParamType, String, List<String>>>: Parameter definitions

Parameter Structure: Each parameter maps to Triple containing:

  • ParamType: Type information (String, Int, Bool, Float, Enum, List, Map, Object, Any)
  • String: Parameter description
  • List<String>: Enum values (if applicable)

HttpContextOptions

Configuration for HTTP endpoint access.

@Serializable
data class HttpContextOptions(@Transient val cinit: Boolean = false)

Key Properties

Endpoint Configuration:

  • baseUrl: String: Base URL for requests
  • endpoint: String: Endpoint path
  • method: String: HTTP method (default: GET)
  • allowedMethods: MutableList<String>: Permitted HTTP methods

Request Configuration:

  • requestBody: String: Request body content
  • headers: MutableMap<String, String>: Request headers
  • followRedirects: Boolean: Follow HTTP redirects (default: true)
  • timeoutMs: Int: Request timeout (default: 30000ms)

Authentication:

  • authType: String: Authentication type (NONE, BASIC, BEARER, API_KEY)
  • authCredentials: MutableMap<String, String>: Authentication credentials

Security:

  • allowedHosts: MutableList<String>: Permitted hosts (empty = any host)
  • permissions: MutableList<Permissions>: Allowed operations
  • description: String: Endpoint description for LLM

PythonContext

Configuration for Python script execution.

@Serializable
data class PythonContext(@Transient val cinit: Boolean = false)

Key Properties

Python Environment:

  • availablePackages: MutableList<String>: Installed packages
  • pythonVersion: String: Python version (e.g., “3.11.5”)
  • pythonPath: String: Python executable path
  • workingDirectory: String: Execution directory
  • environmentVariables: MutableMap<String, String>: Environment variables

Execution Control:

  • timeoutMs: Int: Execution timeout (default: 30000ms)
  • captureOutput: Boolean: Capture stdout/stderr (default: true)
  • permissions: MutableList<Permissions>: Allowed operations

KotlinContext

Configuration for Kotlin script execution within the JVM.

@Serializable
data class KotlinContext(@Transient val cinit: Boolean = false)

Key Properties

Import Control:

  • allowedImports: MutableList<String>: Whitelist of allowed imports
  • blockedImports: MutableList<String>: Blacklist of forbidden imports
  • allowedPackages: MutableList<String>: Allowed package prefixes
  • blockedPackages: MutableList<String>: Forbidden package prefixes

Security Flags:

  • allowTpipeIntrospection: Boolean: Expose PcpRegistry and PcpContext (default: false)
  • allowHostApplicationAccess: Boolean: Expose custom bindings (default: false)
  • allowReflection: Boolean: Allow reflection API (default: false)
  • allowClassLoaderAccess: Boolean: Allow ClassLoader access (default: false)
  • allowSystemAccess: Boolean: Allow System class access (default: false)

Bindings:

  • exposedBindings: MutableMap<String, String>: Custom object bindings (name -> description)

Execution Control:

  • timeoutMs: Int: Execution timeout (default: 30000ms)

See Also: PCP Kotlin and JavaScript Support

JavaScriptContext

Configuration for JavaScript execution via Node.js.

@Serializable
data class JavaScriptContext(@Transient val cinit: Boolean = false)

Key Properties

Node.js Environment:

  • nodePath: String: Path to Node.js executable (default: “node”)
  • allowedModules: MutableList<String>: Whitelist of npm modules
  • workingDirectory: String: Execution directory
  • environmentVariables: MutableMap<String, String>: Environment variables

Execution Control:

  • timeoutMs: Int: Execution timeout (default: 30000ms)
  • permissions: MutableList<Permissions>: Allowed operations

See Also: PCP Kotlin and JavaScript Support

Executors

KotlinExecutor

Executes Kotlin scripts within the JVM using the Kotlin scripting engine.

class KotlinExecutor : PcpExecutor

Methods

execute(request: PcPRequest, context: PcpContext): PcpRequestResult

  • Validates script against KotlinSecurityManager
  • Executes script using JSR-223 Kotlin script engine
  • Returns execution result with output and timing

registerBinding(name: String, obj: Any, description: String = "")

  • Registers custom objects for script access
  • Objects become available when allowHostApplicationAccess = true

JavaScriptExecutor

Executes JavaScript via external Node.js process.

class JavaScriptExecutor : PcpExecutor

Methods

execute(request: PcPRequest, context: PcpContext): PcpRequestResult

  • Validates script against JavaScriptSecurityManager
  • Creates temporary script file
  • Spawns Node.js process with configured environment
  • Captures stdout/stderr
  • Returns execution result with output and timing

Security Managers

KotlinSecurityManager

Validates Kotlin scripts before execution.

class KotlinSecurityManager

Methods

validateKotlinRequest(script: String, options: KotlinContext, context: PcpContext): ValidationResult

Checks:

  • Import statements against allowlists/blocklists
  • Package usage restrictions
  • Reflection usage (if disabled)
  • ClassLoader access (if disabled)
  • System class access (if disabled)

JavaScriptSecurityManager

Validates JavaScript scripts before execution.

class JavaScriptSecurityManager

Methods

validateJavaScriptRequest(script: String, options: JavaScriptContext): ValidationResult

Checks:

  • require() statements against allowed modules
  • Dangerous patterns (eval, Function constructor)
  • File system access patterns
  • Network access patterns

Result Classes

PcpRequestResult

Result of executing a single PCP request.

@Serializable
data class PcpRequestResult(
    val success: Boolean,
    val output: String,
    val executionTimeMs: Long,
    val transport: Transport,
    val error: String? = null
)

PcpExecutionResult

Result of executing multiple PCP requests.

@Serializable
data class PcpExecutionResult(
    val success: Boolean,
    val results: List<PcpRequestResult>,
    val executionTimeMs: Long,
    val errors: List<String>
)

PcpParseResult

Result of parsing LLM response for PCP requests.

@Serializable
data class PcpParseResult(
    val success: Boolean,
    val requests: List<PcPRequest>,
    val errors: List<String>,
    val originalResponse: String
)

PcpValidationResult

Result of validating a single PCP request.

@Serializable
data class PcpValidationResult(
    val isValid: Boolean,
    val errors: List<String>
)

Enums

Transport

enum class Transport { Auto, Stdio, Tpipe, Http, Python, Unknown }

Permissions

enum class Permissions { Read, Write, Delete, Execute }

ParamType

enum class ParamType { String, Int, Bool, Float, Enum, List, Map, Object, Any }

StdioExecutionMode

enum class StdioExecutionMode { ONE_SHOT, INTERACTIVE, CONNECT, BUFFER_REPLAY }

Key Behaviors

Multi-Transport Support

PCP supports multiple execution environments with unified configuration and security models. Each transport type has specialized context options and validation rules.

Security Framework

Comprehensive security controls including directory/file access restrictions, permission-based operations, and session/buffer access control for multi-user environments.

Robust Parsing

Uses TPipe’s extractJson utility for resilient JSON parsing with automatic repair capabilities, handling malformed LLM responses gracefully.

Concurrent Execution

Multiple PCP requests can be executed concurrently with proper error aggregation and performance tracking.

Flexible Configuration

Context options support both simple and advanced use cases, from basic command execution to complex HTTP API interactions and Python script execution.

Validation Pipeline

Multi-layer validation ensures requests are complete, transport-appropriate, and security-compliant before execution.

Next Steps