@composio/experimental 0.1.0

package/README.md

@@ -0,0 +1,190 @@
+# `@composio/experimental`
+
+Experimental Composio integrations and helpers.
+
+This package currently includes a Pi provider for [`@earendil-works/pi-coding-agent`](https://www.npmjs.com/package/@earendil-works/pi-coding-agent). It lets Composio tools be passed to Pi SDK sessions as `customTools` and includes a dynamic Tool Router session toolset modeled after the Slack bot integration in `~/composio/slack-bot`.
+
+## Install
+
+```bash
+pnpm add @composio/core @composio/experimental @earendil-works/pi-coding-agent
+```
+
+## Static tool wrapping
+
+Use this when you already know the exact Composio tools to expose to Pi.
+
+```ts
+import { Composio } from '@composio/core';
+import { PiProvider } from '@composio/experimental';
+import { createAgentSession, SessionManager } from '@earendil-works/pi-coding-agent';
+
+const provider = new PiProvider();
+const composio = new Composio({
+  apiKey: process.env.COMPOSIO_API_KEY,
+  provider,
+});
+
+const tools = await composio.tools.get('default', {
+  tools: ['GITHUB_CREATE_ISSUE'],
+});
+
+const { session } = await createAgentSession({
+  cwd: process.cwd(),
+  sessionManager: SessionManager.inMemory(process.cwd()),
+  customTools: tools,
+  tools: ['read', 'bash', ...tools.map(tool => tool.name)],
+});
+
+await session.prompt('Create a GitHub issue for the failing test.');
+```
+
+## Dynamic session helpers
+
+Use this when Pi should search and execute tools dynamically inside one Tool Router session. Prefer the capability form so your app owns connection management and uses one Pi-style `hooks` object for interception/result transforms.
+
+```ts
+import { Composio } from '@composio/core';
+import { PiProvider, createPiComposioSystemPrompt } from '@composio/experimental';
+import {
+  createAgentSession,
+  DefaultResourceLoader,
+  getAgentDir,
+  SessionManager,
+} from '@earendil-works/pi-coding-agent';
+
+const provider = new PiProvider();
+const composio = new Composio({ apiKey: process.env.COMPOSIO_API_KEY });
+
+const composioSession = await composio.sessions.create('slack:T123:U456', {
+  toolkits: ['github', 'gmail'],
+  manageConnections: true,
+  workbench: { enable: true },
+});
+
+const composioTools = provider.createSessionTools({
+  sessionId: composioSession.sessionId,
+  search: composioSession.search.bind(composioSession),
+  execute: composioSession.execute.bind(composioSession),
+  callbackUrl: 'https://your-app.example.com/auth/callback',
+  includeWorkbenchTools: true,
+  connections: {
+    getToolkitStates: toolkits => composioSession.toolkits({ toolkits }),
+    authorizeToolkit: (toolkit, options) => composioSession.authorize(toolkit, options),
+    isConnected: state => state.connection?.isActive === true,
+  },
+  hooks: {
+    search: (ctx, next) => {
+      ctx.request.toolkits = ctx.request.toolkits?.map(toolkit =>
+        toolkit === 'slack' ? 'slackbot' : toolkit
+      );
+      return next();
+    },
+    execute: (ctx, next) => {
+      if (ctx.request.toolSlug === 'COMPOSIO_MANAGE_CONNECTIONS') {
+        return ctx.deny('Meta tools are blocked.');
+      }
+      return next();
+    },
+    remoteWorkbench: async (ctx, next) => {
+      const result = await next();
+      await auditWorkbenchRun({ code: ctx.request.code_to_execute, result });
+      return result;
+    },
+    remoteBash: async (ctx, next) => {
+      if (ctx.request.command.includes('rm -rf')) {
+        return ctx.deny('Destructive bash commands are blocked.');
+      }
+      return next();
+    },
+    onAuthLink: async (ctx, next) => {
+      // DM the user, store the continuation, or redact public output.
+      await sendConnectionLinkToUser({ url: ctx.url, toolkit: ctx.toolkit });
+      return { message: 'Connection link sent out-of-band.' };
+      // To also send the original result/link to the model, use: return next();
+    },
+  },
+  transformResult: async ({ value }) => value,
+});
+
+const loader = new DefaultResourceLoader({
+  cwd: process.cwd(),
+  agentDir: getAgentDir(),
+  systemPromptOverride: () =>
+    createPiComposioSystemPrompt(composioSession.sessionId, { includeWorkbenchTools: true }),
+});
+await loader.reload();
+
+const { session } = await createAgentSession({
+  cwd: process.cwd(),
+  resourceLoader: loader,
+  sessionManager: SessionManager.inMemory(process.cwd()),
+  customTools: composioTools,
+  tools: [
+    'read',
+    'bash',
+    'composio_search_tools',
+    'composio_manage_connections',
+    'composio_execute_tool',
+    'composio_remote_workbench',
+    'composio_remote_bash',
+  ],
+});
+
+await session.prompt('Find my recent GitHub issues and summarize the blockers.');
+```
+
+`composio_manage_connections` uses your `connections.getToolkitStates()` and `connections.authorizeToolkit()` handlers. It does **not** call `session.execute('COMPOSIO_MANAGE_CONNECTIONS', ...)` internally.
+
+The dynamic helpers are:
+
+- `composio_search_tools` — search Tool Router for exact tool slugs and schemas.
+- `composio_manage_connections` — check/initiate user app connections.
+- `composio_execute_tool` — execute exact Composio tool slugs in the session.
+- `composio_remote_workbench` — execute Python in the Composio remote workbench for large outputs, remote files, and session-authenticated scripting.
+- `composio_remote_bash` — run short bash commands in the Composio remote workbench filesystem.
+
+Workbench helpers are opt-in because the Tool Router session must be created with workbench enabled.
+
+## Hooks
+
+`hooks` follows Pi's extension-event style with middleware semantics. Each hook receives a mutable `ctx.request`, `ctx.deny('reason')`, and a typed `next()` function. Calling `await next()` runs the default Composio behavior and returns the result before anything is sent back to the model. Return that result to pass it through, return a replacement value to control what the model sees, or skip `next()` entirely to divert/deny the operation.
+
+Available hooks:
+
+- `search(ctx, next)` — rewrite query/toolkit filters, log search results, or return custom search output.
+- `manageConnections(ctx, next)` — rewrite requested toolkits, force reauth, log connection state, or return custom connection output.
+- `execute(ctx, next)` — block/rewrite tools, route to another session/execute handler, call `ctx.manageConnections(...)`, log outputs, or return a file/workbench reference instead of inline data.
+- `remoteWorkbench(ctx, next)` — rewrite Python code/session metadata, audit workbench runs, or replace large outputs with file/workbench references. Calls through the generic `execute` hook when `next()` is used.
+- `remoteBash(ctx, next)` — rewrite/block shell commands, enforce safety policy, audit filesystem access, or replace output. Calls through the generic `execute` hook when `next()` is used.
+- `onAuthLink(ctx, next)` — send/redact/resume auth links out-of-band. `return next()` keeps the original model-visible result; returning another value replaces it.
+
+## Auth link handling
+
+Embedded agents often need to keep Composio connection URLs out of the public transcript. Use `hooks.onAuthLink()` to choose whether the model sees the original result or a redacted replacement:
+
+```ts
+const tools = provider.createSessionTools({
+  search: composioSession.search.bind(composioSession),
+  execute: composioSession.execute.bind(composioSession),
+  connections: {
+    getToolkitStates: toolkits => composioSession.toolkits({ toolkits }),
+    authorizeToolkit: (toolkit, options) => composioSession.authorize(toolkit, options),
+  },
+  hooks: {
+    onAuthLink: async (ctx, next) => {
+      await sendConnectionLinkToUser({ url: ctx.url, toolkit: ctx.toolkit });
+
+      if (shouldAlsoShowLinkToModel(ctx)) {
+        return next();
+      }
+
+      return { message: 'Connection link sent out-of-band.' };
+    },
+  },
+});
+```
+
+## Status
+
+Experimental. The dynamic helper names and session helper API may change.

package/dist/index.d.mts

@@ -0,0 +1,266 @@
+import { BaseAgenticProvider, ExecuteToolFn, McpServerGetResponse, McpUrlResponse, Tool } from "@composio/core";
+import { ToolDefinition } from "@earendil-works/pi-coding-agent";
+
+//#region src/pi/types.d.ts
+type PiToolDetails = {
+  slug?: string;
+  result?: unknown;
+  error?: string | null;
+  authLinks?: string[];
+  denied?: boolean;
+};
+type PiTool = ToolDefinition;
+type PiToolCollection = PiTool[];
+type PiToolResultFormatter = (result: unknown) => string;
+type PiDeniedResult = {
+  successful: false;
+  error: string;
+  data: null;
+  denied: true;
+};
+interface PiHookControls {
+  /** Return from a hook to explicitly deny/divert the operation with a model-visible error. */
+  deny(error: string): PiDeniedResult;
+}
+type MaybePromise<T> = T | Promise<T>;
+type PiHookNext<TResult> = () => Promise<TResult>;
+interface PiProviderOptions {
+  /** Prefix shown in Pi's TUI labels. Defaults to `Composio`. */
+  labelPrefix?: string;
+  /** Per-tool execution mode. Defaults to Pi's runtime default. */
+  executionMode?: PiTool['executionMode'];
+  /** Convert Composio results to the text sent back to the model. */
+  formatResult?: PiToolResultFormatter;
+  /** Return thrown errors as structured JSON instead of rethrowing to Pi. Defaults to true. */
+  catchErrors?: boolean;
+}
+declare const DEFAULT_SESSION_TOOL_NAMES: {
+  readonly search: "composio_search_tools";
+  readonly manageConnections: "composio_manage_connections";
+  readonly execute: "composio_execute_tool";
+  readonly remoteWorkbench: "composio_remote_workbench";
+  readonly remoteBash: "composio_remote_bash";
+};
+type PiSessionToolName = keyof typeof DEFAULT_SESSION_TOOL_NAMES;
+interface PiBaseToolContext {
+  /** Tool call id passed by Pi. */
+  toolCallId: string;
+  /** The Pi helper tool that is currently running. */
+  sourceTool: string;
+  /** Optional Composio Tool Router session id for prompts/logging/default workbench session ids. */
+  sessionId?: string;
+  /** Original helper request sent by the model. */
+  originalRequest: unknown;
+}
+interface PiSearchContext extends PiBaseToolContext {
+  query: string;
+  requestedToolkits?: string[];
+}
+interface PiConnectionManagementContext extends PiBaseToolContext {
+  requestedToolkits: string[];
+  callbackUrl?: string;
+  reinitiateAll: boolean;
+}
+interface PiExecuteContext extends PiBaseToolContext {
+  toolSlug: string;
+  toolkit?: string;
+  args: Record<string, unknown>;
+  account?: string;
+}
+interface PiAuthLinkContext<TResult = unknown> extends PiHookControls {
+  url: string;
+  toolkit?: string;
+  sourceTool: string;
+  originalRequest: unknown;
+  result: TResult;
+  sessionId?: string;
+}
+interface PiSessionToolOptions extends PiProviderOptions {
+  /** Callback URL passed to `authorizeToolkit()` when connection management initiates auth. */
+  callbackUrl?: string;
+  /** Include first-class wrappers for COMPOSIO_REMOTE_WORKBENCH and COMPOSIO_REMOTE_BASH_TOOL. Defaults to false. */
+  includeWorkbenchTools?: boolean;
+  /** Override the default helper tool names. */
+  names?: Partial<typeof DEFAULT_SESSION_TOOL_NAMES>;
+  /** Called before a result is returned to Pi; useful for redacting or routing auth links. */
+  transformResult?: (params: {
+    tool: PiSessionToolName;
+    requestedToolkits?: string[];
+    value: unknown;
+    context?: PiBaseToolContext;
+  }) => unknown | Promise<unknown>;
+}
+interface PiComposioSessionLike<TSearchResult = unknown, TExecuteResult = unknown, TToolkitStates = unknown, TAuthorizeResult = unknown> {
+  sessionId?: string;
+  search(params: {
+    query: string;
+    toolkits?: string[];
+  }): Promise<TSearchResult>;
+  execute(toolSlug: string, args?: Record<string, unknown>, options?: {
+    account?: string;
+  }): Promise<TExecuteResult>;
+  /** Native Tool Router connection-state API. Preferred over executing a meta tool. */
+  toolkits?(options?: {
+    toolkits?: string[];
+    isConnected?: boolean;
+    limit?: number;
+    cursor?: string;
+  }): Promise<TToolkitStates>;
+  authorize?(toolkit: string, options?: {
+    callbackUrl?: string;
+    alias?: string;
+    experimental?: unknown;
+  }): Promise<TAuthorizeResult>;
+}
+interface PiExecutableSessionLike<TExecuteResult = unknown> {
+  sessionId?: string;
+  execute(toolSlug: string, args?: Record<string, unknown>, options?: {
+    account?: string;
+  }): Promise<TExecuteResult>;
+}
+type PiSearchHandler<TSearchResult = unknown> = (params: {
+  query: string;
+  toolkits?: string[];
+}, context: PiSearchContext) => MaybePromise<TSearchResult>;
+type PiExecuteHandler<TExecuteResult = unknown> = (toolSlug: string, args: Record<string, unknown>, options: {
+  account?: string;
+} | undefined, context: PiExecuteContext) => MaybePromise<TExecuteResult>;
+interface PiAuthorizeToolkitOptions {
+  callbackUrl?: string;
+  alias?: string;
+  experimental?: unknown;
+  reinitiate?: boolean;
+}
+interface PiConnectionHandlers<TState = unknown, TAuthorizeResult = unknown, TToolkitStates = unknown> {
+  /** Return connection states for the requested toolkits, e.g. from `session.toolkits({ toolkits })`. */
+  getToolkitStates?: (toolkits: string[], context: PiConnectionManagementContext) => MaybePromise<TToolkitStates>;
+  /** Start auth for one toolkit, e.g. via `session.authorize(toolkit, { callbackUrl })`. */
+  authorizeToolkit?: (toolkit: string, options: PiAuthorizeToolkitOptions, context: PiConnectionManagementContext) => Promise<TAuthorizeResult> | TAuthorizeResult;
+  /** Interpret one state returned by `getToolkitStates()`. Defaults handle common Tool Router shapes. */
+  isConnected?: (state: TState, context: {
+    toolkit: string;
+    request: PiConnectionManagementContext;
+  }) => boolean;
+}
+interface PiSearchHookContext extends PiHookControls {
+  request: {
+    query: string;
+    toolkits?: string[];
+  };
+  context: PiSearchContext;
+}
+interface PiManageConnectionsHookContext extends PiHookControls {
+  request: {
+    toolkits: string[];
+    reinitiateAll: boolean;
+  };
+  context: PiConnectionManagementContext;
+}
+interface PiExecuteHookContext<TExecuteResult = unknown> extends PiHookControls {
+  request: {
+    toolSlug: string;
+    args: Record<string, unknown>;
+    account?: string;
+    session?: PiExecutableSessionLike<TExecuteResult>;
+    execute?: PiExecuteHandler<TExecuteResult>;
+  };
+  context: PiExecuteContext;
+  manageConnections: (toolkits: string[], options?: {
+    reinitiateAll?: boolean;
+  }) => Promise<unknown>;
+}
+interface PiRemoteWorkbenchRequest extends Record<string, unknown> {
+  code_to_execute: string;
+  timeout?: number;
+  thought?: string;
+  file_path?: string;
+  disabled_tools?: string[];
+  session_id?: string;
+}
+interface PiRemoteBashRequest extends Record<string, unknown> {
+  command: string;
+  session_id?: string;
+}
+interface PiRemoteWorkbenchHookContext extends PiHookControls {
+  request: PiRemoteWorkbenchRequest;
+  context: PiExecuteContext;
+}
+interface PiRemoteBashHookContext extends PiHookControls {
+  request: PiRemoteBashRequest;
+  context: PiExecuteContext;
+}
+interface PiSessionHooks<TSearchResult = unknown, TExecuteResult = unknown, TState = unknown, TAuthorizeResult = unknown> {
+  /** Middleware around search. Mutate `ctx.request`, call `next()` to run search, or return a replacement result. */
+  search?: (ctx: PiSearchHookContext, next: PiHookNext<TSearchResult>) => MaybePromise<unknown>;
+  /** Middleware around connection management. Mutate `ctx.request`, call `next()` to check/connect, or return a replacement result. */
+  manageConnections?: (ctx: PiManageConnectionsHookContext, next: PiHookNext<PiConnectionManagementResult<TState, TAuthorizeResult>>) => MaybePromise<unknown>;
+  /** Middleware around tool execution. Mutate `ctx.request`, call `next()` to execute, or return a replacement result. */
+  execute?: (ctx: PiExecuteHookContext<TExecuteResult>, next: PiHookNext<TExecuteResult>) => MaybePromise<unknown>;
+  /** Middleware around the remote Python workbench helper. Runs outside, then through, the generic `execute` hook when `next()` is called. */
+  remoteWorkbench?: (ctx: PiRemoteWorkbenchHookContext, next: PiHookNext<TExecuteResult>) => MaybePromise<unknown>;
+  /** Middleware around the remote bash helper. Runs outside, then through, the generic `execute` hook when `next()` is called. */
+  remoteBash?: (ctx: PiRemoteBashHookContext, next: PiHookNext<TExecuteResult>) => MaybePromise<unknown>;
+  /** Middleware for auth links found in any result. Call `next()` to keep the current model-visible result, or return a replacement. */
+  onAuthLink?: (ctx: PiAuthLinkContext<TSearchResult | TExecuteResult | TAuthorizeResult>, next: PiHookNext<TSearchResult | TExecuteResult | TAuthorizeResult>) => MaybePromise<unknown>;
+}
+interface PiSessionToolCapabilities<TSearchResult = unknown, TExecuteResult = unknown, TState = unknown, TAuthorizeResult = unknown, TToolkitStates = unknown> extends PiSessionToolOptions {
+  /** Optional session id for prompt context and default workbench session ids. */
+  sessionId?: string;
+  search: PiSearchHandler<TSearchResult>;
+  execute: PiExecuteHandler<TExecuteResult>;
+  connections?: PiConnectionHandlers<TState, TAuthorizeResult, TToolkitStates>;
+  hooks?: PiSessionHooks<TSearchResult, TExecuteResult, TState, TAuthorizeResult>;
+}
+type PiConnectionToolkitResult<TState = unknown, TAuthorizeResult = unknown> = {
+  toolkit: string;
+  connected: boolean;
+  status: 'connected' | 'auth_initiated' | 'missing_authorize_handler';
+  state?: TState;
+  authorization?: TAuthorizeResult;
+  authLinks?: string[];
+};
+type PiConnectionManagementResult<TState = unknown, TAuthorizeResult = unknown> = {
+  successful: true;
+  data: {
+    message: string;
+    results: Record<string, PiConnectionToolkitResult<TState, TAuthorizeResult>>;
+  };
+  error: null;
+};
+//#endregion
+//#region src/pi/auth-links.d.ts
+declare const extractComposioConnectLinks: (value: unknown) => string[];
+//#endregion
+//#region src/pi/provider.d.ts
+/**
+ * Provider for integrating Composio tools with Pi SDK custom tools.
+ */
+declare class PiProvider extends BaseAgenticProvider<PiToolCollection, PiTool, McpServerGetResponse> {
+  private readonly options;
+  readonly name = "pi";
+  constructor(options?: PiProviderOptions);
+  /**
+   * Wrap a concrete Composio tool as a Pi custom tool definition.
+   */
+  wrapTool(composioTool: Tool, executeTool: ExecuteToolFn): PiTool;
+  /**
+   * Wrap multiple concrete Composio tools as Pi custom tools.
+   */
+  wrapTools(tools: Tool[], executeTool: ExecuteToolFn): PiToolCollection;
+  createSessionTools<TSearchResult = unknown, TExecuteResult = unknown, TState = unknown, TAuthorizeResult = unknown, TToolkitStates = unknown>(capabilities: PiSessionToolCapabilities<TSearchResult, TExecuteResult, TState, TAuthorizeResult, TToolkitStates>): PiToolCollection;
+  createSessionTools<TSearchResult = unknown, TExecuteResult = unknown, TToolkitStates = unknown, TAuthorizeResult = unknown>(session: PiComposioSessionLike<TSearchResult, TExecuteResult, TToolkitStates, TAuthorizeResult>, options?: PiSessionToolOptions): PiToolCollection;
+  /**
+   * Transform MCP URL responses into Pi-compatible standard URL entries.
+   */
+  wrapMcpServerResponse(data: McpUrlResponse): McpServerGetResponse;
+}
+//#endregion
+//#region src/pi/prompt.d.ts
+declare const createPiComposioSystemPrompt: (sessionId?: string, options?: {
+  includeWorkbenchTools?: boolean;
+}) => string;
+//#endregion
+//#region src/pi/results.d.ts
+declare const denyPiToolCall: (error: string) => PiDeniedResult;
+//#endregion
+export { type MaybePromise, DEFAULT_SESSION_TOOL_NAMES as PI_COMPOSIO_SESSION_TOOL_NAMES, type PiAuthLinkContext, type PiAuthorizeToolkitOptions, type PiBaseToolContext, type PiComposioSessionLike, type PiConnectionHandlers, type PiConnectionManagementContext, type PiConnectionManagementResult, type PiConnectionToolkitResult, type PiDeniedResult, type PiExecutableSessionLike, type PiExecuteContext, type PiExecuteHandler, type PiExecuteHookContext, type PiHookControls, type PiHookNext, type PiManageConnectionsHookContext, PiProvider, type PiProviderOptions, type PiRemoteBashHookContext, type PiRemoteBashRequest, type PiRemoteWorkbenchHookContext, type PiRemoteWorkbenchRequest, type PiSearchContext, type PiSearchHandler, type PiSearchHookContext, type PiSessionHooks, type PiSessionToolCapabilities, type PiSessionToolName, type PiSessionToolOptions, type PiTool, type PiToolCollection, type PiToolDetails, type PiToolResultFormatter, createPiComposioSystemPrompt, denyPiToolCall, extractComposioConnectLinks };

package/dist/index.mjs

@@ -0,0 +1,694 @@
+import { BaseAgenticProvider, normalizeToolArguments } from "@composio/core";
+import { defineTool } from "@earendil-works/pi-coding-agent";
+import { Type } from "typebox";
+
+//#region src/pi/hooks.ts
+const runHook = async (hook, context, getDefaultResult) => {
+	if (!hook) return getDefaultResult();
+	const state = {};
+	const next = async () => {
+		state.nextResult ??= Promise.resolve(getDefaultResult());
+		return state.nextResult;
+	};
+	const hookValue = await hook(context, next);
+	if (hookValue !== void 0) return hookValue;
+	return state.nextResult ?? next();
+};
+
+//#endregion
+//#region src/pi/results.ts
+const denyPiToolCall = (error) => ({
+	successful: false,
+	error,
+	data: null,
+	denied: true
+});
+const hookControls = { deny: denyPiToolCall };
+const defaultFormatResult = (result) => JSON.stringify(result, null, 2);
+const stringifyError = (error) => error instanceof Error ? error.message : String(error);
+const isPiDeniedResult = (value) => !!value && typeof value === "object" && value.denied === true && value.successful === false;
+const toPiResult = (value, formatter, details = {}) => ({
+	content: [{
+		type: "text",
+		text: formatter(value)
+	}],
+	details: {
+		...details,
+		denied: details.denied ?? (isPiDeniedResult(value) ? true : void 0),
+		result: value
+	}
+});
+const toPiErrorResult = (error, formatter, details = {}) => {
+	const message = stringifyError(error);
+	const value = {
+		successful: false,
+		error: message,
+		data: null
+	};
+	return {
+		content: [{
+			type: "text",
+			text: formatter(value)
+		}],
+		details: {
+			...details,
+			error: message,
+			result: value
+		}
+	};
+};
+
+//#endregion
+//#region src/pi/auth-links.ts
+const extractComposioConnectLinks = (value) => {
+	const text = stringifyUnknown(value);
+	const connectLinks = text.match(/https:\/\/connect\.composio\.dev\/[^\s<>)"']+/gi) ?? [];
+	const genericLinks = text.match(/https:\/\/[^\s<>)"']*composio[^\s<>)"']*\/link\/[^\s<>)"']+/gi) ?? [];
+	return [...new Set([...connectLinks, ...genericLinks].map((url) => url.replace(/[.,;:!?]+$/g, "")))];
+};
+const stringifyUnknown = (value) => {
+	if (typeof value === "string") return value;
+	try {
+		return JSON.stringify(value);
+	} catch {
+		return String(value);
+	}
+};
+const applyAuthLinkHandlers = async (capabilities, value, context) => {
+	const links = extractComposioConnectLinks(value);
+	const run = async (index, currentValue) => {
+		const url = links[index];
+		if (!url) return currentValue;
+		return run(index + 1, await runHook(capabilities.hooks?.onAuthLink, {
+			...context,
+			...hookControls,
+			url,
+			result: currentValue
+		}, async () => currentValue));
+	};
+	return {
+		value: await run(0, value),
+		authLinks: links
+	};
+};
+
+//#endregion
+//#region src/pi/schemas.ts
+const EmptyObjectSchema = Type.Object({});
+const ToolkitsSchema = Type.Optional(Type.Array(Type.String({ description: "Optional toolkit slug filter, e.g. github, gmail." })));
+const objectInputSchema = (schema) => {
+	const candidate = schema && typeof schema === "object" ? { ...schema } : { ...EmptyObjectSchema };
+	if (!candidate.type) candidate.type = "object";
+	if (!candidate.properties) candidate.properties = {};
+	if (candidate.additionalProperties === void 0) candidate.additionalProperties = true;
+	return Type.Unsafe(candidate);
+};
+const optionalRecordSchema = (description) => Type.Optional(Type.Record(Type.String(), Type.Any(), { description }));
+
+//#endregion
+//#region src/pi/utils.ts
+const normalizeToolkits = (value) => {
+	const toolkits = Array.isArray(value) ? value.filter((item) => typeof item === "string" && item.trim().length > 0) : typeof value === "string" && value.trim().length > 0 ? [value] : [];
+	const unique = [...new Set(toolkits.map((toolkit) => toolkit.trim()))];
+	return unique.length > 0 ? unique : void 0;
+};
+const maybeTransform = async (options, params) => options.transformResult ? options.transformResult(params) : params.value;
+const stringValue = (value) => typeof value === "string" && value.trim().length > 0 ? value.trim() : void 0;
+const toolkitFromToolSlug = (toolSlug) => {
+	const normalized = toolSlug.trim().toLowerCase();
+	if (!normalized || normalized.startsWith("composio_")) return void 0;
+	for (const [prefix, toolkit] of [
+		["google_calendar_", "googlecalendar"],
+		["google_drive_", "googledrive"],
+		["microsoft_teams_", "microsoftteams"]
+	]) if (normalized.startsWith(prefix)) return toolkit;
+	const [prefix] = normalized.split("_");
+	return prefix || void 0;
+};
+
+//#endregion
+//#region src/pi/connections.ts
+const defaultIsToolkitConnected = (state) => {
+	if (!state || typeof state !== "object") return false;
+	const record = state;
+	if (record.isNoAuth === true || record.is_no_auth === true) return true;
+	if (typeof record.isConnected === "boolean") return record.isConnected;
+	if (typeof record.is_connected === "boolean") return record.is_connected;
+	const connection = record.connection;
+	if (connection) {
+		if (connection.isActive === true || connection.is_active === true) return true;
+		if (connection.status === "ACTIVE") return true;
+		if (connection.connectedAccount?.status === "ACTIVE") return true;
+		if (connection.connected_account?.status === "ACTIVE") return true;
+	}
+	if (record.connectedAccount?.status === "ACTIVE") return true;
+	if (record.connected_account?.status === "ACTIVE") return true;
+	return false;
+};
+const toolkitKeyFromState = (state) => {
+	if (!state || typeof state !== "object") return void 0;
+	const record = state;
+	const toolkit = record.toolkit;
+	return stringValue(record.slug) ?? stringValue(record.toolkitSlug) ?? stringValue(record.toolkit_slug) ?? stringValue(record.name) ?? stringValue(toolkit?.slug);
+};
+const normalizeToolkitStateMap = (raw, requestedToolkits) => {
+	const byToolkit = /* @__PURE__ */ new Map();
+	const addState = (toolkit, state) => {
+		if (toolkit) byToolkit.set(toolkit.toLowerCase(), state);
+	};
+	if (!raw) return byToolkit;
+	if (Array.isArray(raw)) {
+		raw.forEach((state, index) => addState(toolkitKeyFromState(state) ?? requestedToolkits[index], state));
+		return byToolkit;
+	}
+	if (typeof raw === "object") {
+		const record = raw;
+		if (Array.isArray(record.items)) {
+			record.items.forEach((state, index) => addState(toolkitKeyFromState(state) ?? requestedToolkits[index], state));
+			return byToolkit;
+		}
+		for (const toolkit of requestedToolkits) if (record[toolkit] !== void 0) addState(toolkit, record[toolkit]);
+		if (byToolkit.size === 0 && requestedToolkits.length === 1) addState(toolkitKeyFromState(raw) ?? requestedToolkits[0], raw);
+	}
+	return byToolkit;
+};
+const formatDefaultConnectionResult = (results) => {
+	return {
+		successful: true,
+		data: {
+			message: Object.values(results).filter((result) => !result.connected).length === 0 ? "All requested toolkits are connected." : "Connection flow initiated for missing toolkits.",
+			results
+		},
+		error: null
+	};
+};
+const inferSessionConnections = (session, options) => {
+	if (!session.toolkits && !session.authorize) return void 0;
+	return {
+		getToolkitStates: session.toolkits ? (toolkits) => session.toolkits?.({
+			toolkits,
+			limit: Math.max(toolkits.length, 1)
+		}) : void 0,
+		authorizeToolkit: session.authorize ? (toolkit, authorizeOptions) => session.authorize?.(toolkit, {
+			callbackUrl: authorizeOptions.callbackUrl ?? options.callbackUrl,
+			alias: authorizeOptions.alias,
+			experimental: authorizeOptions.experimental
+		}) : void 0
+	};
+};
+const isCapabilityInput = (value) => "connections" in value || "hooks" in value || "includeWorkbenchTools" in value || "names" in value;
+const toCapabilities = (input, providerOptions, options = {}) => {
+	if (isCapabilityInput(input)) return {
+		...providerOptions,
+		...input,
+		names: {
+			...providerOptions.names,
+			...input.names ?? {}
+		}
+	};
+	const mergedOptions = {
+		...providerOptions,
+		...options
+	};
+	return {
+		...mergedOptions,
+		sessionId: input.sessionId,
+		search: (params) => input.search(params),
+		execute: (toolSlug, args, executeOptions) => executeOptions ? input.execute(toolSlug, args, executeOptions) : input.execute(toolSlug, args),
+		connections: inferSessionConnections(input, mergedOptions)
+	};
+};
+
+//#endregion
+//#region src/pi/types.ts
+const DEFAULT_SESSION_TOOL_NAMES = {
+	search: "composio_search_tools",
+	manageConnections: "composio_manage_connections",
+	execute: "composio_execute_tool",
+	remoteWorkbench: "composio_remote_workbench",
+	remoteBash: "composio_remote_bash"
+};
+
+//#endregion
+//#region src/pi/session-tools.ts
+const createPiSessionTools = (input, providerOptions, options = {}) => {
+	const capabilities = toCapabilities(input, providerOptions, options);
+	const formatter = capabilities.formatResult ?? defaultFormatResult;
+	const catchErrors = capabilities.catchErrors ?? true;
+	const names = {
+		...DEFAULT_SESSION_TOOL_NAMES,
+		...capabilities.names ?? {}
+	};
+	const executionMode = capabilities.executionMode;
+	const buildBaseContext = (toolCallId, sourceTool, originalRequest) => ({
+		toolCallId,
+		sourceTool,
+		sessionId: capabilities.sessionId,
+		originalRequest
+	});
+	const manageConnectionsForToolkits = async (toolCallId, originalRequest, toolkits, reinitiateAll = false) => {
+		const connectionContext = {
+			...buildBaseContext(toolCallId, names.manageConnections, originalRequest),
+			requestedToolkits: toolkits,
+			callbackUrl: capabilities.callbackUrl,
+			reinitiateAll
+		};
+		const hookContext = {
+			...hookControls,
+			request: {
+				toolkits,
+				reinitiateAll
+			},
+			context: connectionContext
+		};
+		const authLinks = [];
+		return {
+			value: await runHook(capabilities.hooks?.manageConnections, hookContext, async () => {
+				const requestedToolkits = normalizeToolkits(hookContext.request.toolkits) ?? [];
+				const shouldReinitiateAll = hookContext.request.reinitiateAll;
+				connectionContext.requestedToolkits = requestedToolkits;
+				connectionContext.reinitiateAll = shouldReinitiateAll;
+				const states = normalizeToolkitStateMap(await capabilities.connections?.getToolkitStates?.(requestedToolkits, connectionContext), requestedToolkits);
+				const results = {};
+				for (const toolkit of requestedToolkits) {
+					const state = states.get(toolkit.toLowerCase());
+					if ((state ? capabilities.connections?.isConnected?.(state, {
+						toolkit,
+						request: connectionContext
+					}) ?? defaultIsToolkitConnected(state) : false) && !shouldReinitiateAll) {
+						results[toolkit] = {
+							toolkit,
+							connected: true,
+							status: "connected",
+							state
+						};
+						continue;
+					}
+					if (!capabilities.connections?.authorizeToolkit) {
+						results[toolkit] = {
+							toolkit,
+							connected: false,
+							status: "missing_authorize_handler",
+							state
+						};
+						continue;
+					}
+					const authorization = await capabilities.connections.authorizeToolkit(toolkit, {
+						callbackUrl: capabilities.callbackUrl,
+						reinitiate: shouldReinitiateAll
+					}, connectionContext);
+					const handledAuthorization = await applyAuthLinkHandlers(capabilities, authorization, {
+						...connectionContext,
+						toolkit,
+						result: authorization
+					});
+					authLinks.push(...handledAuthorization.authLinks);
+					results[toolkit] = {
+						toolkit,
+						connected: false,
+						status: "auth_initiated",
+						state,
+						authorization: handledAuthorization.value
+					};
+				}
+				return formatDefaultConnectionResult(results);
+			}),
+			authLinks,
+			context: connectionContext
+		};
+	};
+	const executeWithPolicy = async (toolCallId, sourceTool, originalRequest, toolSlug, args, account) => {
+		const executeContext = {
+			...buildBaseContext(toolCallId, sourceTool, originalRequest),
+			toolSlug,
+			toolkit: toolkitFromToolSlug(toolSlug),
+			args,
+			account
+		};
+		const authLinks = [];
+		const hookContext = {
+			...hookControls,
+			request: {
+				toolSlug,
+				args,
+				account
+			},
+			context: executeContext,
+			manageConnections: async (managedToolkits, manageOptions) => {
+				const managed = await manageConnectionsForToolkits(toolCallId, originalRequest, managedToolkits, manageOptions?.reinitiateAll);
+				authLinks.push(...managed.authLinks);
+				return managed.value;
+			}
+		};
+		return {
+			value: await runHook(capabilities.hooks?.execute, hookContext, async () => {
+				const finalToolSlug = hookContext.request.toolSlug;
+				const finalArgs = hookContext.request.args;
+				const finalAccount = hookContext.request.account;
+				const finalContext = {
+					...executeContext,
+					toolSlug: finalToolSlug,
+					toolkit: toolkitFromToolSlug(finalToolSlug),
+					args: finalArgs,
+					account: finalAccount
+				};
+				hookContext.context = finalContext;
+				const execute = hookContext.request.execute ?? capabilities.execute;
+				const session = hookContext.request.session;
+				const result = session ? await session.execute(finalToolSlug, finalArgs, finalAccount ? { account: finalAccount } : void 0) : await execute(finalToolSlug, finalArgs, finalAccount ? { account: finalAccount } : void 0, finalContext);
+				const handledResult = await applyAuthLinkHandlers(capabilities, result, {
+					...finalContext,
+					result
+				});
+				authLinks.push(...handledResult.authLinks);
+				return handledResult.value;
+			}),
+			authLinks,
+			context: hookContext.context
+		};
+	};
+	const searchTools = defineTool({
+		name: names.search,
+		label: "Composio Search Tools",
+		description: "Search Composio for tools that can perform a requested action. Search globally by default; pass toolkits only when intentionally narrowing the search.",
+		promptSnippet: "Use composio_search_tools to discover exact Composio tool slugs and schemas before executing app actions.",
+		promptGuidelines: ["Search Composio before inventing tool slugs or arguments.", "Only pass a toolkit filter when you intentionally want to narrow search results."],
+		parameters: Type.Object({
+			query: Type.String({ description: "Natural language description of the action to perform." }),
+			toolkits: ToolkitsSchema
+		}),
+		...executionMode ? { executionMode } : {},
+		execute: async (toolCallId, params) => {
+			try {
+				const requestedToolkits = normalizeToolkits(params.toolkits);
+				const searchContext = {
+					...buildBaseContext(toolCallId, names.search, params),
+					query: params.query,
+					requestedToolkits
+				};
+				const hookContext = {
+					...hookControls,
+					request: {
+						query: params.query,
+						...requestedToolkits ? { toolkits: requestedToolkits } : {}
+					},
+					context: searchContext
+				};
+				const authLinks = [];
+				const value = await runHook(capabilities.hooks?.search, hookContext, async () => {
+					const toolkits = normalizeToolkits(hookContext.request.toolkits);
+					hookContext.context.query = hookContext.request.query;
+					hookContext.context.requestedToolkits = toolkits;
+					const result = await capabilities.search({
+						query: hookContext.request.query,
+						...toolkits ? { toolkits } : {}
+					}, hookContext.context);
+					const handledResult = await applyAuthLinkHandlers(capabilities, result, {
+						...hookContext.context,
+						result
+					});
+					authLinks.push(...handledResult.authLinks);
+					return handledResult.value;
+				});
+				return toPiResult(await maybeTransform(capabilities, {
+					tool: "search",
+					requestedToolkits: hookContext.context.requestedToolkits,
+					value,
+					context: hookContext.context
+				}), formatter, {
+					slug: names.search,
+					authLinks
+				});
+			} catch (error) {
+				if (!catchErrors) throw error;
+				return toPiErrorResult(error, formatter, { slug: names.search });
+			}
+		}
+	});
+	const manageConnections = defineTool({
+		name: names.manageConnections,
+		label: "Composio Manage Connections",
+		description: "Check whether the user has active connections for requested toolkits and initiate Composio auth when needed.",
+		promptSnippet: "Use composio_manage_connections when a searched tool requires a missing app connection.",
+		promptGuidelines: ["When an app connection is missing, call composio_manage_connections with the toolkit slug.", "Never ask the user for OAuth secrets or API keys directly."],
+		parameters: Type.Object({
+			toolkits: Type.Array(Type.String({ description: "Toolkit slugs to check/connect, e.g. github, gmail." })),
+			reinitiate_all: Type.Optional(Type.Boolean({ description: "Force reconnection even if active connections exist." }))
+		}),
+		...executionMode ? { executionMode } : {},
+		execute: async (toolCallId, params) => {
+			const toolkits = normalizeToolkits(params.toolkits) ?? [];
+			try {
+				const managed = await manageConnectionsForToolkits(toolCallId, params, toolkits, params.reinitiate_all ?? false);
+				return toPiResult(await maybeTransform(capabilities, {
+					tool: "manageConnections",
+					requestedToolkits: toolkits,
+					value: managed.value,
+					context: managed.context
+				}), formatter, {
+					slug: names.manageConnections,
+					authLinks: managed.authLinks,
+					denied: managed.denied
+				});
+			} catch (error) {
+				if (!catchErrors) throw error;
+				return toPiErrorResult(error, formatter, { slug: names.manageConnections });
+			}
+		}
+	});
+	const executeTool = defineTool({
+		name: names.execute,
+		label: "Composio Execute Tool",
+		description: "Execute an exact Composio tool slug using the configured Composio execution capability. Use search first so the slug and arguments match the schema.",
+		promptSnippet: "Use composio_execute_tool to execute an exact Composio tool slug returned by composio_search_tools.",
+		promptGuidelines: ["Always use exact tool slugs and schema-compliant arguments.", "For missing connections, use composio_manage_connections instead of asking for credentials."],
+		parameters: Type.Object({
+			toolSlug: Type.String({ description: "Exact Composio tool slug, e.g. GITHUB_CREATE_ISSUE." }),
+			arguments: optionalRecordSchema("Tool arguments matching the searched schema."),
+			account: Type.Optional(Type.String({ description: "Optional account selector for multi-account sessions. Use connected account id or alias when required." }))
+		}),
+		...executionMode ? { executionMode } : {},
+		prepareArguments: (args) => normalizeToolArguments(args, names.execute),
+		execute: async (toolCallId, params) => {
+			const toolSlug = params.toolSlug.trim();
+			const args = params.arguments ?? {};
+			try {
+				const executed = await executeWithPolicy(toolCallId, names.execute, params, toolSlug, args, params.account);
+				return toPiResult(await maybeTransform(capabilities, {
+					tool: "execute",
+					requestedToolkits: toolkitFromToolSlug(executed.context.toolSlug) ? [toolkitFromToolSlug(executed.context.toolSlug)] : void 0,
+					value: executed.value,
+					context: executed.context
+				}), formatter, {
+					slug: executed.context.toolSlug || names.execute,
+					authLinks: executed.authLinks,
+					denied: executed.denied
+				});
+			} catch (error) {
+				if (!catchErrors) throw error;
+				return toPiErrorResult(error, formatter, { slug: toolSlug || names.execute });
+			}
+		}
+	});
+	if (!capabilities.includeWorkbenchTools) return [
+		searchTools,
+		manageConnections,
+		executeTool
+	];
+	return [
+		searchTools,
+		manageConnections,
+		executeTool,
+		defineTool({
+			name: names.remoteWorkbench,
+			label: "Composio Remote Workbench",
+			description: "Execute Python code inside the Composio remote workbench for this Tool Router session. Use it for remote files, bulk processing, large tool outputs, and Composio-authenticated scripting.",
+			promptSnippet: "Use composio_remote_workbench for Python scripting in the Composio remote sandbox when data is large, stored in remote files, or needs session-authenticated tool/proxy helpers.",
+			promptGuidelines: ["Use composio_remote_workbench for large data processing or remote workbench files; do not use it for tiny inline transformations.", "Split long-running work into small cells and save checkpoints in the workbench filesystem."],
+			parameters: Type.Object({
+				code_to_execute: Type.String({ description: "Python code to run in the persistent Composio remote workbench. Keep cells focused and avoid long-running jobs." }),
+				timeout: Type.Optional(Type.Number({
+					minimum: 1,
+					maximum: 780,
+					description: "Maximum seconds to allow execution. Defaults to the session/backend workbench timeout."
+				})),
+				thought: Type.Optional(Type.String({ description: "Concise objective for why this workbench cell is needed." })),
+				file_path: Type.Optional(Type.String({ description: "Remote workbench path/glob to analyze when processing a file." })),
+				disabled_tools: Type.Optional(Type.Array(Type.String({ description: "Tool slugs to disable for this workbench call." }))),
+				session_id: Type.Optional(Type.String({ description: "Workbench workflow session id. Defaults to the Composio Tool Router session id." }))
+			}),
+			...executionMode ? { executionMode } : {},
+			execute: async (toolCallId, params) => {
+				try {
+					const request = {
+						...params,
+						...params.session_id || capabilities.sessionId ? { session_id: params.session_id ?? capabilities.sessionId } : {}
+					};
+					const hookContext = {
+						...hookControls,
+						request,
+						context: {
+							...buildBaseContext(toolCallId, names.remoteWorkbench, params),
+							toolSlug: "COMPOSIO_REMOTE_WORKBENCH",
+							args: request
+						}
+					};
+					const authLinks = [];
+					const details = {};
+					return toPiResult(await maybeTransform(capabilities, {
+						tool: "remoteWorkbench",
+						value: await runHook(capabilities.hooks?.remoteWorkbench, hookContext, async () => {
+							const executed = await executeWithPolicy(toolCallId, names.remoteWorkbench, params, "COMPOSIO_REMOTE_WORKBENCH", hookContext.request);
+							authLinks.push(...executed.authLinks);
+							details.denied = executed.denied;
+							hookContext.context = executed.context;
+							return executed.value;
+						}),
+						context: hookContext.context
+					}), formatter, {
+						slug: hookContext.context.toolSlug,
+						authLinks,
+						denied: details.denied
+					});
+				} catch (error) {
+					if (!catchErrors) throw error;
+					return toPiErrorResult(error, formatter, { slug: "COMPOSIO_REMOTE_WORKBENCH" });
+				}
+			}
+		}),
+		defineTool({
+			name: names.remoteBash,
+			label: "Composio Remote Bash",
+			description: "Execute a bash command inside the Composio remote workbench for this Tool Router session.",
+			promptSnippet: "Use composio_remote_bash to inspect or manipulate files in the Composio remote workbench filesystem.",
+			promptGuidelines: ["Use composio_remote_bash for filesystem inspection in the remote workbench, especially for truncated output files.", "Keep commands short and non-interactive."],
+			parameters: Type.Object({
+				command: Type.String({ description: "Bash command to execute in the Composio remote workbench." }),
+				session_id: Type.Optional(Type.String({ description: "Workbench workflow session id. Defaults to the Composio Tool Router session id." }))
+			}),
+			...executionMode ? { executionMode } : {},
+			execute: async (toolCallId, params) => {
+				try {
+					const request = {
+						...params,
+						...params.session_id || capabilities.sessionId ? { session_id: params.session_id ?? capabilities.sessionId } : {}
+					};
+					const hookContext = {
+						...hookControls,
+						request,
+						context: {
+							...buildBaseContext(toolCallId, names.remoteBash, params),
+							toolSlug: "COMPOSIO_REMOTE_BASH_TOOL",
+							args: request
+						}
+					};
+					const authLinks = [];
+					const details = {};
+					return toPiResult(await maybeTransform(capabilities, {
+						tool: "remoteBash",
+						value: await runHook(capabilities.hooks?.remoteBash, hookContext, async () => {
+							const executed = await executeWithPolicy(toolCallId, names.remoteBash, params, "COMPOSIO_REMOTE_BASH_TOOL", hookContext.request);
+							authLinks.push(...executed.authLinks);
+							details.denied = executed.denied;
+							hookContext.context = executed.context;
+							return executed.value;
+						}),
+						context: hookContext.context
+					}), formatter, {
+						slug: hookContext.context.toolSlug,
+						authLinks,
+						denied: details.denied
+					});
+				} catch (error) {
+					if (!catchErrors) throw error;
+					return toPiErrorResult(error, formatter, { slug: "COMPOSIO_REMOTE_BASH_TOOL" });
+				}
+			}
+		})
+	];
+};
+
+//#endregion
+//#region src/pi/provider.ts
+/**
+* Provider for integrating Composio tools with Pi SDK custom tools.
+*/
+var PiProvider = class extends BaseAgenticProvider {
+	options;
+	name = "pi";
+	constructor(options = {}) {
+		super();
+		this.options = options;
+	}
+	/**
+	* Wrap a concrete Composio tool as a Pi custom tool definition.
+	*/
+	wrapTool(composioTool, executeTool) {
+		const formatter = this.options.formatResult ?? defaultFormatResult;
+		const catchErrors = this.options.catchErrors ?? true;
+		const schema = objectInputSchema(composioTool.inputParameters);
+		return defineTool({
+			name: composioTool.slug,
+			label: `${this.options.labelPrefix ?? "Composio"}: ${composioTool.name ?? composioTool.slug}`,
+			description: composioTool.description ?? `Execute ${composioTool.slug} with Composio.`,
+			promptSnippet: `Use ${composioTool.slug} for ${composioTool.description ?? composioTool.name ?? "this Composio action"}.`,
+			parameters: schema,
+			...this.options.executionMode ? { executionMode: this.options.executionMode } : {},
+			prepareArguments: (args) => normalizeToolArguments(args, composioTool.slug),
+			execute: async (_toolCallId, params) => {
+				try {
+					const args = normalizeToolArguments(params, composioTool.slug);
+					const result = await executeTool(composioTool.slug, args);
+					return toPiResult(result, formatter, {
+						slug: composioTool.slug,
+						error: result?.error
+					});
+				} catch (error) {
+					if (!catchErrors) throw error;
+					return toPiErrorResult(error, formatter, { slug: composioTool.slug });
+				}
+			}
+		});
+	}
+	/**
+	* Wrap multiple concrete Composio tools as Pi custom tools.
+	*/
+	wrapTools(tools, executeTool) {
+		return tools.map((tool) => this.wrapTool(tool, executeTool));
+	}
+	/**
+	* Create Slack-bot-style dynamic Composio helpers.
+	*
+	* Prefer passing capabilities (`search`, `execute`, `connections`, `hooks`)
+	* so app code owns auth, interception, and shared/service-session routing.
+	* Passing a native Tool Router session is also supported; connection
+	* management uses `session.toolkits()` + `session.authorize()` when present
+	* and never executes `COMPOSIO_MANAGE_CONNECTIONS` internally.
+	*/
+	createSessionTools(input, options = {}) {
+		return createPiSessionTools(input, this.options, options);
+	}
+	/**
+	* Transform MCP URL responses into Pi-compatible standard URL entries.
+	*/
+	wrapMcpServerResponse(data) {
+		return data.map((item) => ({
+			url: new URL(item.url),
+			name: item.name
+		}));
+	}
+};
+
+//#endregion
+//#region src/pi/prompt.ts
+const createPiComposioSystemPrompt = (sessionId, options = {}) => [
+	"You have Composio tools for working across the user's connected apps.",
+	"Use composio_search_tools to find the right tool before executing app actions.",
+	"Use composio_manage_connections when an app is not connected; never ask for OAuth secrets or API keys.",
+	"Use composio_execute_tool with exact tool slugs and schema-compliant arguments from search results.",
+	options.includeWorkbenchTools ? "Use composio_remote_workbench or composio_remote_bash for large outputs, remote files, or Composio-authenticated scripting in the remote workbench." : void 0,
+	sessionId ? `Composio session id: ${sessionId}` : void 0
+].filter(Boolean).join("\n");
+
+//#endregion
+export { DEFAULT_SESSION_TOOL_NAMES as PI_COMPOSIO_SESSION_TOOL_NAMES, PiProvider, createPiComposioSystemPrompt, denyPiToolCall, extractComposioConnectLinks };

package/dist/workbench/index.d.mts

@@ -0,0 +1,24 @@
+import { Composio, Session } from "@composio/core";
+
+//#region src/workbench/types.d.ts
+interface LocalWorkbenchSession {
+  helperSource: string;
+  env: Record<string, string>;
+}
+//#endregion
+//#region src/workbench/local-workbench.d.ts
+declare function experimental_createLocalWorkbenchSession(composio: Composio, session: Session<unknown, unknown, never>): Promise<LocalWorkbenchSession>;
+//#endregion
+//#region src/workbench/shim.d.ts
+interface WorkbenchEnvOptions {
+  sessionId: string;
+  backendUrl: string;
+  apiKey: string;
+}
+interface PythonWorkbenchHelperSourceOptions {
+  invokeLlmModel?: string;
+}
+declare function experimental_createWorkbenchEnv(env: WorkbenchEnvOptions): Record<string, string>;
+declare function experimental_createPythonWorkbenchHelperSource(opts?: PythonWorkbenchHelperSourceOptions): string;
+//#endregion
+export { type LocalWorkbenchSession, type PythonWorkbenchHelperSourceOptions, type WorkbenchEnvOptions, experimental_createLocalWorkbenchSession, experimental_createPythonWorkbenchHelperSource, experimental_createWorkbenchEnv };

package/dist/workbench/index.mjs

@@ -0,0 +1,40 @@
+//#region src/workbench/python-helpers.generated.ts
+const PYTHON_WORKBENCH_HELPER_SOURCE = "import json\nimport os\nimport random\nimport time\nimport urllib.error\nimport urllib.parse\nimport urllib.request\nimport uuid\nfrom typing import Any, Dict, Literal, Optional\n\n\n# Config is injected by the SDK via an `_INTERNAL` dict in a prologue prepended\n# at runtime. When running this file directly (e.g. pytest), default to empty.\ntry:\n    _INTERNAL\nexcept NameError:\n    _INTERNAL = {}\n\n\nDEFAULT_INVOKE_LLM_MODEL = _INTERNAL.get(\"invoke_llm_model\", \"openai/gpt-oss-120b\")\nRATE_LIMIT_PATTERNS = (\n    \"rate limit\",\n    \"ratelimit\",\n    \"too many requests\",\n    \"quota exceeded\",\n    \"resource exhausted\",\n)\n\n\ndef _read_env(name, default=None):\n    value = os.environ.get(name)\n    return default if value is None or value == \"\" else value\n\n\ndef _require_value(value, label):\n    if value is None or value == \"\":\n        raise RuntimeError(\"%s is required\" % label)\n    return value\n\n\ndef _request_id():\n    return str(uuid.uuid4())\n\n\ndef _session_execute_url():\n    backend_url = _read_env(\"BACKEND_URL\", \"https://backend.composio.dev\").rstrip(\"/\")\n    session_id = _require_value(\n        _read_env(\"COMPOSIO_TOOLROUTER_SESSION_ID\"),\n        \"COMPOSIO_TOOLROUTER_SESSION_ID\",\n    )\n    encoded_session_id = urllib.parse.quote(session_id, safe=\"\")\n    return \"%s/api/v3/tool_router/session/%s/execute\" % (backend_url, encoded_session_id)\n\n\ndef _session_proxy_execute_url():\n    backend_url = _read_env(\"BACKEND_URL\", \"https://backend.composio.dev\").rstrip(\"/\")\n    session_id = _require_value(\n        _read_env(\"COMPOSIO_TOOLROUTER_SESSION_ID\"),\n        \"COMPOSIO_TOOLROUTER_SESSION_ID\",\n    )\n    encoded_session_id = urllib.parse.quote(session_id, safe=\"\")\n    return \"%s/api/v3/tool_router/session/%s/proxy_execute\" % (\n        backend_url,\n        encoded_session_id,\n    )\n\n\ndef _post_json(url, headers, payload, timeout=120):\n    body = json.dumps(payload).encode(\"utf-8\")\n    request = urllib.request.Request(url, data=body, headers=headers, method=\"POST\")\n    try:\n        with urllib.request.urlopen(request, timeout=timeout) as response:\n            return response.status, dict(response.headers), response.read().decode(\"utf-8\")\n    except urllib.error.HTTPError as error:\n        return error.code, dict(error.headers), error.read().decode(\"utf-8\")\n\n\ndef _parse_json(text):\n    if not text:\n        return {}\n    return json.loads(text)\n\n\ndef _safe_json(text):\n    try:\n        return _parse_json(text)\n    except json.JSONDecodeError:\n        return {\"raw\": text}\n\n\ndef _contains_rate_limit_error(payload):\n    # Only inspect the API \"error\" field, not the whole body — otherwise benign\n    # tool output mentioning \"rate limit\"/\"quota\" triggers spurious retries.\n    if not isinstance(payload, dict):\n        return False\n    error = payload.get(\"error\")\n    if not error:\n        return False\n    text = json.dumps(error, default=str).lower()\n    return any(pattern in text for pattern in RATE_LIMIT_PATTERNS)\n\n\ndef _retry_delay(attempt, delay_ms):\n    base_delay = max(delay_ms, 0) / 1000.0\n    if base_delay == 0:\n        return\n    # Exponential backoff: double the delay each attempt (parity with Apollo).\n    backoff = base_delay * (2 ** attempt)\n    jitter = random.uniform(0, min(backoff * 0.2, 0.5))\n    time.sleep(backoff + jitter)\n\n\ndef _json_shape(value):\n    if isinstance(value, dict):\n        return {key: _json_shape(item) for key, item in value.items()}\n    if isinstance(value, list):\n        return [_json_shape(value[0])] if value else []\n    if value is None:\n        return \"null\"\n    return type(value).__name__\n\n\ndef print_json_structure(value):\n    print(json.dumps(_json_shape(value), indent=2, sort_keys=True))\n\n\ndef _track_helper_event(*_args, **_kwargs):\n    return None\n\n\ndef run_composio_tool(\n    tool_slug,\n    arguments=None,\n    retry_params=None,\n    print_schema_for_tool=True,\n    *,\n    account=None,\n):\n    if not tool_slug:\n        return {}, \"tool_slug is required\"\n\n    api_key = _require_value(_read_env(\"COMPOSIO_API_KEY\"), \"COMPOSIO_API_KEY\")\n    retry_config = {\"max_retries\": 3, \"delay_ms\": 2000}\n    if retry_params:\n        retry_config.update(retry_params)\n\n    payload = {\n        \"tool_slug\": str(tool_slug).strip().upper(),\n        \"arguments\": arguments or {},\n    }\n    if account is not None:\n        payload[\"account\"] = account\n\n    headers = {\n        \"Content-Type\": \"application/json\",\n        \"x-api-key\": api_key,\n        \"x-request-id\": _request_id(),\n    }\n    max_retries = int(retry_config.get(\"max_retries\", 3))\n    delay_ms = int(retry_config.get(\"delay_ms\", 2000))\n\n    for attempt in range(max_retries + 1):\n        try:\n            status, _headers, text = _post_json(_session_execute_url(), headers, payload)\n        except (urllib.error.URLError, TimeoutError) as error:\n            # Network failure (timeout, connection/DNS error). Retry transient\n            # failures, then surface as the error tuple instead of throwing.\n            if attempt < max_retries:\n                _retry_delay(attempt, delay_ms)\n                continue\n            return {}, \"Composio tool request failed: %s\" % error\n\n        if status == 429 and attempt < max_retries:\n            _retry_delay(attempt, delay_ms)\n            continue\n\n        if status >= 400:\n            response_data = _safe_json(text)\n            return response_data, \"Composio tool execution failed with HTTP %s\" % status\n\n        try:\n            response_data = _parse_json(text)\n        except json.JSONDecodeError as error:\n            return {\"raw\": text}, \"Failed to parse Composio tool response as JSON: %s\" % error\n\n        if _contains_rate_limit_error(response_data) and attempt < max_retries:\n            _retry_delay(attempt, delay_ms)\n            continue\n\n        # A failed tool call returns HTTP 200 with a top-level \"error\" field;\n        # surface it as the error tuple element so callers don't read it as success.\n        if isinstance(response_data, dict) and response_data.get(\"error\"):\n            return response_data, str(response_data[\"error\"])\n\n        if print_schema_for_tool:\n            print_json_structure(response_data)\n        return response_data, \"\"\n\n    return {}, \"Composio tool execution failed after retries\"\n\n\ndef _strip_code_fence(content):\n    stripped = content.strip()\n    code_fence = chr(96) * 3\n    if stripped.startswith(code_fence):\n        stripped = stripped[3:].strip()\n        if stripped.lower().startswith(\"json\"):\n            stripped = stripped[4:].strip()\n        if stripped.endswith(code_fence):\n            stripped = stripped[:-3].strip()\n    elif stripped.lower().startswith(\"json\\n\"):\n        stripped = stripped[5:].strip()\n    return stripped.strip()\n\n\ndef invoke_llm(query, reasoning_effort=None):\n    if not query:\n        return \"\", \"query is required\"\n\n    system_prompt = (\n        \"You are a generic, smart large language model. \"\n        \"When asked to output a JSON, respond only with valid JSON - \"\n        \"no other text / code fences / quotes around the JSON.\"\n    )\n    response, error = run_composio_tool(\n        \"COMPOSIO_SEARCH_GROQ_CHAT\",\n        {\n            \"model\": DEFAULT_INVOKE_LLM_MODEL,\n            \"messages\": [\n                {\"role\": \"system\", \"content\": system_prompt},\n                {\"role\": \"user\", \"content\": query},\n            ],\n            \"temperature\": 0.5,\n        },\n        None,\n        False,\n    )\n    _track_helper_event(\"invoke_llm\", {\"reasoning_effort\": reasoning_effort})\n\n    if error:\n        return \"\", error\n\n    choices = (response.get(\"data\") or {}).get(\"choices\", \"\")\n    if not choices:\n        return \"\", \"No choices returned from invoke_llm\"\n\n    first_choice = choices[0] if isinstance(choices, list) else choices\n    content = (first_choice.get(\"message\") or {}).get(\"content\", \"\")\n    if not content:\n        return \"\", \"No content returned from invoke_llm\"\n    return _strip_code_fence(content), \"\"\n\n\ndef web_search(query):\n    if not query:\n        return \"\", \"query is required\"\n\n    response, error = run_composio_tool(\n        \"COMPOSIO_SEARCH_EXA_ANSWER\",\n        {\"content\": query},\n        None,\n        False,\n    )\n    _track_helper_event(\"web_search\", {})\n\n    if error:\n        return \"\", error\n    return (response.get(\"data\") or {}).get(\"answer\", \"\"), \"\"\n\n\ndef proxy_execute(\n    method: Literal[\"GET\", \"POST\", \"PUT\", \"DELETE\", \"PATCH\"],\n    endpoint: str,\n    toolkit: str,\n    query_params: Optional[Dict[str, str]] = None,\n    body: Optional[object] = None,\n    headers: Optional[Dict[str, str]] = None,\n) -> tuple[Any, str]:\n    \"\"\"Call a toolkit's API directly when no Composio tool exists.\n\n    The session resolves the connected account and injects auth server-side, so\n    your code never handles raw credentials.\n\n    Args:\n        method: HTTP method to use for the request. Example: \"GET\"\n        endpoint: API endpoint to call. Example: \"/repos/owner/repo\"\n        toolkit: Name of the toolkit. Example: \"GITHUB\"\n        query_params: Query parameters as key-value pairs. Example: {\"q\": \"is:unread\"}\n        body: The request body (required for POST, PUT, and PATCH requests)\n        headers: HTTP headers as key-value pairs. Example: {\"Accept\": \"application/json\"}\n\n    Returns:\n        tuple[Any, str]:\n            - data: Response data from the API (None if error)\n            - error: Error message (\"\" if no error)\n    \"\"\"\n    # Wrapped end-to-end so the helper always returns a (data, error) tuple\n    # rather than raising.\n    try:\n        valid_methods = [\"GET\", \"POST\", \"PUT\", \"DELETE\", \"PATCH\"]\n        if method.upper() not in valid_methods:\n            return None, \"Invalid HTTP method: \" + method\n\n        if not endpoint.strip():\n            return None, \"Endpoint cannot be empty\"\n\n        if not toolkit.strip():\n            return None, \"Toolkit cannot be empty\"\n\n        if query_params is not None and not isinstance(query_params, dict):\n            return None, (\n                \"Invalid query_params type: expected dict or None, got \"\n                + type(query_params).__name__\n            )\n\n        if headers is not None and not isinstance(headers, dict):\n            return None, (\n                \"Invalid headers type: expected dict or None, got \"\n                + type(headers).__name__\n            )\n\n        if method.upper() in [\"POST\", \"PUT\", \"PATCH\"] and body is None:\n            return None, \"Body is required for \" + method.upper() + \" requests\"\n\n        if method.upper() in [\"GET\", \"DELETE\"] and body is not None:\n            return None, \"Body should not be provided for \" + method.upper() + \" requests\"\n\n        api_key = _read_env(\"COMPOSIO_API_KEY\")\n        if not api_key:\n            return None, \"Missing environment variable COMPOSIO_API_KEY\"\n        if not _read_env(\"COMPOSIO_TOOLROUTER_SESSION_ID\"):\n            return None, \"Missing environment variable COMPOSIO_TOOLROUTER_SESSION_ID\"\n\n        # Convert query_params and headers dicts to the flat parameters array.\n        parameters = []\n        if query_params:\n            for key, value in query_params.items():\n                parameters.append({\"name\": key, \"value\": str(value), \"type\": \"query\"})\n        if headers:\n            for key, value in headers.items():\n                parameters.append({\"name\": key, \"value\": str(value), \"type\": \"header\"})\n\n        payload = {\n            \"toolkit_slug\": toolkit.lower(),\n            \"endpoint\": endpoint,\n            \"method\": method.upper(),\n        }\n        if parameters:\n            payload[\"parameters\"] = parameters\n        if body is not None:\n            payload[\"body\"] = body\n\n        request_headers = {\n            \"Content-Type\": \"application/json\",\n            \"x-api-key\": api_key,\n            \"x-request-id\": _request_id(),\n        }\n\n        status, _response_headers, text = _post_json(\n            _session_proxy_execute_url(), request_headers, payload\n        )\n\n        # Handle HTTP errors explicitly. Always surface a non-empty message so a\n        # >=400 response never looks like success (an empty error/message field\n        # must not win over the default).\n        if status >= 400:\n            error_msg = \"HTTP \" + str(status) + \" Error\"\n            try:\n                error_data = json.loads(text)\n                if isinstance(error_data, dict):\n                    error_msg = (\n                        error_data.get(\"error\") or error_data.get(\"message\") or error_msg\n                    )\n            except (ValueError, TypeError):\n                if text:\n                    sanitized = text[:200].replace(\"\\n\", \" \").strip()\n                    error_msg = \"HTTP \" + str(status) + \": \" + sanitized\n            return None, str(error_msg)\n\n        response_data = json.loads(text)\n\n        # The session wraps the proxied response as {data, status, headers}; the\n        # toolkit's own API may still report a >=400 status inside that envelope.\n        # `status` can arrive as a string or null, so coerce it before comparing\n        # — a bare `>= 400` against a non-int would raise and mask a valid result.\n        if isinstance(response_data, dict):\n            try:\n                api_status = int(response_data.get(\"status\", 200))\n            except (TypeError, ValueError):\n                api_status = 200\n            if api_status >= 400:\n                error_msg = \"API request failed\"\n                if isinstance(response_data.get(\"data\"), dict):\n                    error_msg = response_data[\"data\"].get(\n                        \"message\", response_data[\"data\"].get(\"error\", error_msg)\n                    )\n                return response_data, \"API returned status \" + str(api_status) + \": \" + str(error_msg)\n            return response_data.get(\"data\"), \"\"\n\n        return response_data, \"\"\n    except Exception as error:\n        return None, \"Failed to execute proxy request: \" + str(error)\n";
+
+//#endregion
+//#region src/workbench/shim.ts
+function trimTrailingSlashes(value) {
+	let end = value.length;
+	while (end > 0 && value.charCodeAt(end - 1) === 47) end -= 1;
+	return value.slice(0, end);
+}
+function experimental_createWorkbenchEnv(env) {
+	return {
+		BACKEND_URL: trimTrailingSlashes(env.backendUrl),
+		COMPOSIO_TOOLROUTER_SESSION_ID: env.sessionId,
+		COMPOSIO_API_KEY: env.apiKey
+	};
+}
+function experimental_createPythonWorkbenchHelperSource(opts = {}) {
+	const config = { invoke_llm_model: opts.invokeLlmModel ?? "openai/gpt-oss-120b" };
+	return `import json as _composio_internal_json\n_INTERNAL = _composio_internal_json.loads(${JSON.stringify(JSON.stringify(config))})\n` + PYTHON_WORKBENCH_HELPER_SOURCE;
+}
+
+//#endregion
+//#region src/workbench/local-workbench.ts
+async function experimental_createLocalWorkbenchSession(composio, session) {
+	if (session.workbench?.enable !== false) throw new Error("experimental_createLocalWorkbenchSession requires a session created with workbench.enable: false. The remote workbench and a local sandbox cannot both run for one session.");
+	const { apiKey, baseURL } = composio.getConfig();
+	if (!apiKey) throw new Error("A Composio project API key is required to create a local workbench session");
+	return {
+		env: experimental_createWorkbenchEnv({
+			sessionId: session.sessionId,
+			backendUrl: baseURL ?? "https://backend.composio.dev",
+			apiKey
+		}),
+		helperSource: experimental_createPythonWorkbenchHelperSource()
+	};
+}
+
+//#endregion
+export { experimental_createLocalWorkbenchSession, experimental_createPythonWorkbenchHelperSource, experimental_createWorkbenchEnv };

package/package.json

@@ -0,0 +1,72 @@
+{
+  "name": "@composio/experimental",
+  "version": "0.1.0",
+  "description": "Experimental Composio integrations and helpers",
+  "main": "src/index.ts",
+  "type": "module",
+  "repository": {
+    "type": "git",
+    "url": "https://github.com/ComposioHQ/composio.git",
+    "directory": "ts/packages/experimental"
+  },
+  "bugs": {
+    "url": "https://github.com/ComposioHQ/composio/issues"
+  },
+  "homepage": "https://github.com/ComposioHQ/composio/tree/main/ts/packages/experimental#readme",
+  "publishConfig": {
+    "access": "public",
+    "main": "dist/index.mjs",
+    "types": "dist/index.d.mts"
+  },
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./pi": {
+      "types": "./dist/index.d.mts",
+      "default": "./dist/index.mjs"
+    },
+    "./workbench": {
+      "types": "./dist/workbench/index.d.mts",
+      "default": "./dist/workbench/index.mjs"
+    }
+  },
+  "files": [
+    "README.md",
+    "dist"
+  ],
+  "scripts": {
+    "clean": "git clean -xdf node_modules",
+    "build:python-helpers": "tsx scripts/build-python-helpers.ts",
+    "check:python-helpers": "tsx scripts/build-python-helpers.ts && git diff --exit-code -- src/workbench/python-helpers.generated.ts",
+    "build": "pnpm run build:python-helpers && pnpm exec tsdown",
+    "test": "vitest run",
+    "typecheck": "tsc --noEmit -p tsconfig.json"
+  },
+  "keywords": [
+    "composio",
+    "experimental",
+    "pi",
+    "coding-agent",
+    "tools",
+    "agent"
+  ],
+  "author": "",
+  "license": "ISC",
+  "dependencies": {
+    "typebox": "1.1.38"
+  },
+  "peerDependencies": {
+    "@composio/core": ">=0.10.0 <1.0.0",
+    "@earendil-works/pi-coding-agent": ">=0.79.0 <1.0.0"
+  },
+  "devDependencies": {
+    "@composio/core": "workspace:*",
+    "@earendil-works/pi-coding-agent": "0.79.8",
+    "tsdown": "catalog:",
+    "tsx": "catalog:",
+    "typescript": "catalog:",
+    "vitest": "catalog:"
+  }
+}

package/src/index.ts

@@ -0,0 +1,10 @@
+/**
+ * Experimental Composio integrations and helpers.
+ *
+ * Currently includes the experimental Pi provider for
+ * @earendil-works/pi-coding-agent.
+ *
+ * @packageDocumentation
+ * @module experimental
+ */
+export * from './pi/index';