@toolplex/client 0.1.41 → 0.1.44

package/dist/mcp-server/clientContext.d.ts

@@ -1,5 +1,5 @@
 import { LLMContext } from "../shared/mcpServerTypes.js";
-import { ClientPermissions, ClientFlags } from "./toolplexApi/types.js";
+import { ClientPermissions, ClientFlags, AutomationContext } from "./toolplexApi/types.js";
 /**
  * Maintains client context for the ToolPlex server
  */
@@ -15,14 +15,15 @@ export declare class ClientContext {
     private _isOrgUser;
     private _clientName;
     private _userId;
+    private _automationContext;
     get sessionId(): string;
     set sessionId(id: string);
     get dev(): boolean;
     set dev(isDev: boolean);
     get apiKey(): string;
     set apiKey(key: string);
-    get clientMode(): "standard" | "restricted";
-    set clientMode(mode: "standard" | "restricted");
+    get clientMode(): "standard" | "restricted" | "automation";
+    set clientMode(mode: "standard" | "restricted" | "automation");
     get clientName(): string;
     set clientName(name: string);
     get llmContext(): LLMContext;
@@ -42,5 +43,12 @@ export declare class ClientContext {
      */
     get userId(): string | null;
     set userId(id: string | null);
+    /**
+     * Automation context for HITL (Human-in-the-Loop) support.
+     * Only set when clientMode is 'automation'.
+     * Contains allowed tools, tools requiring approval, and notification config.
+     */
+    get automationContext(): AutomationContext | null;
+    set automationContext(context: AutomationContext | null);
     isInitialized(): boolean;
 }

package/dist/mcp-server/clientContext.js

@@ -14,6 +14,7 @@ export class ClientContext {
         this._isOrgUser = null;
         this._clientName = null;
         this._userId = null; // For system keys to specify user context
+        this._automationContext = null; // For automation mode HITL
     }
     get sessionId() {
         if (!this._sessionId) {
@@ -116,6 +117,17 @@ export class ClientContext {
     set userId(id) {
         this._userId = id;
     }
+    /**
+     * Automation context for HITL (Human-in-the-Loop) support.
+     * Only set when clientMode is 'automation'.
+     * Contains allowed tools, tools requiring approval, and notification config.
+     */
+    get automationContext() {
+        return this._automationContext;
+    }
+    set automationContext(context) {
+        this._automationContext = context;
+    }
     isInitialized() {
         return !!(this._sessionId &&
             this._apiKey &&

package/dist/mcp-server/index.js

@@ -6,7 +6,10 @@ dotenv.config();
 FileLogger.initialize("mcp-server");
 const isDev = process.env.DEV === "true";
 const apiKey = process.env.TOOLPLEX_API_KEY;
-const clientMode = process.env.TOOLPLEX_CLIENT_MODE || "standard";
+// CLIENT_MODE can come from ai-engine (automation mode) or TOOLPLEX_CLIENT_MODE (legacy)
+const clientMode = process.env.CLIENT_MODE ||
+    process.env.TOOLPLEX_CLIENT_MODE ||
+    "standard";
 const clientName = process.env.CLIENT_NAME || "unknown";
 const logLevel = process.env.LOG_LEVEL || "info";
 // Optional user ID for per-user telemetry (system API keys only)
@@ -39,6 +42,20 @@ if (process.env.TOOLPLEX_SESSION_RESUME_HISTORY) {
         FileLogger.warn(`Failed to parse session resume history: ${error}`);
     }
 }
+// Parse automation context for HITL support (only in automation mode)
+let automationContext;
+if (process.env.AUTOMATION_CONTEXT) {
+    try {
+        automationContext = JSON.parse(process.env.AUTOMATION_CONTEXT);
+        FileLogger.info(`Parsed automation context - ` +
+            `automationId: ${automationContext?.automationId}, ` +
+            `runId: ${automationContext?.runId}, ` +
+            `toolsRequiringApproval: ${automationContext?.toolsRequiringApproval?.length || 0}`);
+    }
+    catch (error) {
+        FileLogger.warn(`Failed to parse automation context: ${error}`);
+    }
+}
 if (!apiKey) {
     process.exit(1);
 }
@@ -51,6 +68,7 @@ const config = {
     bundledDependencies,
     sessionResumeHistory,
     userId,
+    automationContext,
 };
 serve(config).catch(() => {
     process.exit(1);

package/dist/mcp-server/toolHandlers/callToolHandler.js

@@ -27,6 +27,32 @@ export async function handleCallTool(params) {
         validateServerIdOrThrow(params.server_id);
         // Enforce call tool policy
         policyEnforcer.enforceCallToolPolicy(params.server_id);
+        // Automation mode: Check if tool requires HITL approval
+        const automationContext = clientContext.automationContext;
+        if (automationContext) {
+            const toolKey = `${params.server_id}.${params.tool_name}`;
+            // Check if tool requires HITL approval
+            if (automationContext.toolsRequiringApproval.includes(toolKey)) {
+                await logger.info(`Tool ${toolKey} requires HITL approval`);
+                // Return HITL signal for cloud-agent to handle
+                return {
+                    content: [
+                        {
+                            type: "text",
+                            text: JSON.stringify({
+                                _hitl_required: true,
+                                _hitl_type: "tool_approval",
+                                tool_key: toolKey,
+                                server_id: params.server_id,
+                                tool_name: params.tool_name,
+                                args: params.arguments,
+                                context: `Requesting approval to run "${params.tool_name}" on "${params.server_id}"`,
+                            }),
+                        },
+                    ],
+                };
+            }
+        }
         const client = await findServerManagerClient(params.server_id, serverManagerClients);
         const response = await client.sendRequest("call_tool", params);
         if ("error" in response) {

package/dist/mcp-server/toolHandlers/notifyHandler.d.ts

@@ -0,0 +1,8 @@
+import { CallToolResult } from "@modelcontextprotocol/sdk/types.js";
+import { NotifyParams } from "../../shared/mcpServerTypes.js";
+/**
+ * Handler for the notify tool.
+ * Only available in automation mode.
+ * Returns an HITL signal for the cloud-agent to process.
+ */
+export declare function handleNotify(params: NotifyParams): Promise<CallToolResult>;

package/dist/mcp-server/toolHandlers/notifyHandler.js

@@ -0,0 +1,86 @@
+import { FileLogger } from "../../shared/fileLogger.js";
+import Registry from "../registry.js";
+const logger = FileLogger;
+/**
+ * Handler for the notify tool.
+ * Only available in automation mode.
+ * Returns an HITL signal for the cloud-agent to process.
+ */
+export async function handleNotify(params) {
+    const startTime = Date.now();
+    await logger.debug(`Handling notify request with params: ${JSON.stringify(params)}`);
+    const telemetryLogger = Registry.getTelemetryLogger();
+    const clientContext = Registry.getClientContext();
+    try {
+        // Verify we're in automation mode
+        if (clientContext.clientMode !== "automation") {
+            throw new Error("The notify tool is only available in automation mode. It allows the agent to send notifications to the automation owner.");
+        }
+        // Verify automation context is set
+        const automationContext = clientContext.automationContext;
+        if (!automationContext) {
+            throw new Error("Automation context not configured. Cannot send notifications without automation configuration.");
+        }
+        // Verify notification email is configured
+        if (!automationContext.notificationEmail) {
+            throw new Error("No notification email configured for this automation. Cannot send notification.");
+        }
+        // Validate multi_choice has options
+        if (params.response_type === "multi_choice") {
+            if (!params.response_options || params.response_options.length === 0) {
+                throw new Error("response_options is required for multi_choice response type");
+            }
+        }
+        await logger.info(`Sending HITL notification: ${params.title} (pause: ${params.pause_until_response})`);
+        await telemetryLogger.log("client_notify", {
+            success: true,
+            log_context: {
+                response_type: params.response_type,
+                pause_until_response: params.pause_until_response,
+                has_context: !!params.context,
+            },
+            latency_ms: Date.now() - startTime,
+        });
+        // Return HITL signal for cloud-agent to handle
+        // The cloud-agent will parse this and create the notification
+        return {
+            content: [
+                {
+                    type: "text",
+                    text: JSON.stringify({
+                        _hitl_required: true,
+                        _hitl_type: "agent_notify",
+                        title: params.title,
+                        content: params.content,
+                        context: params.context,
+                        response_type: params.response_type,
+                        response_options: params.response_options,
+                        pause_until_response: params.pause_until_response,
+                        automation_id: automationContext.automationId,
+                        run_id: automationContext.runId,
+                        notification_email: automationContext.notificationEmail,
+                        expiration_hours: automationContext.expirationHours,
+                    }),
+                },
+            ],
+        };
+    }
+    catch (error) {
+        const errorMessage = error instanceof Error ? error.message : String(error);
+        await logger.error(`Failed to send notification: ${errorMessage}`);
+        await telemetryLogger.log("client_notify", {
+            success: false,
+            pii_sanitized_error_message: errorMessage,
+            latency_ms: Date.now() - startTime,
+        });
+        return {
+            isError: true,
+            content: [
+                {
+                    type: "text",
+                    text: `Failed to send notification: ${errorMessage}`,
+                },
+            ],
+        };
+    }
+}

package/dist/mcp-server/toolplexApi/types.d.ts

@@ -7,6 +7,22 @@ export interface ClientPermissions {
     allowed_mcp_servers?: string[];
     custom_prompt?: string;
 }
+/**
+ * Automation context for HITL (Human-in-the-Loop) support.
+ * Passed when clientMode is 'automation' to enable tool approval and notifications.
+ */
+export interface AutomationContext {
+    automationId: string;
+    runId: string;
+    /** Tools that require user approval before execution (format: "server_id.tool_name") */
+    toolsRequiringApproval: string[];
+    /** Email address for notifications */
+    notificationEmail?: string;
+    /** Hours before HITL decisions expire (default 24) */
+    expirationHours: number;
+    /** Notification instructions from automation config */
+    notifyInstructions?: string;
+}
 export interface ClientFlags {
     desktop_commander_server_id: string;
     blocked_mcp_servers: string[];

package/dist/mcp-server/toolplexServer.js

@@ -20,9 +20,10 @@ import { handleLogPlaybookUsage } from "./toolHandlers/logPlaybookUsageHandler.j
 import { handleLookupEntityTool } from "./toolHandlers/lookupEntityHandler.js";
 import { handleSubmitFeedback } from "./toolHandlers/submitFeedbackHandler.js";
 import { handleGetServerConfig } from "./toolHandlers/getServerConfigHandler.js";
+import { handleNotify } from "./toolHandlers/notifyHandler.js";
 import { StdioServerManagerClient } from "../shared/stdioServerManagerClient.js";
 import { FileLogger } from "../shared/fileLogger.js";
-import { CallToolParamsSchema, InitializeToolplexParamsSchema, InstallParamsSchema, ListToolsParamsSchema, SearchParamsSchema, UninstallParamsSchema, SavePlaybookParamsSchema, LogPlaybookUsageParamsSchema, LookupEntityParamsSchema, SubmitFeedbackParamsSchema, GetServerConfigParamsSchema, } from "../shared/mcpServerTypes.js";
+import { CallToolParamsSchema, InitializeToolplexParamsSchema, InstallParamsSchema, ListToolsParamsSchema, SearchParamsSchema, UninstallParamsSchema, SavePlaybookParamsSchema, LogPlaybookUsageParamsSchema, LookupEntityParamsSchema, SubmitFeedbackParamsSchema, GetServerConfigParamsSchema, NotifyParamsSchema, } from "../shared/mcpServerTypes.js";
 import { version as clientVersion } from "../version.js";
 const __dirname = path.dirname(fileURLToPath(import.meta.url));
 const logger = FileLogger;
@@ -36,6 +37,10 @@ export async function serve(config) {
     if (config.userId) {
         clientContext.userId = config.userId;
     }
+    // Set automation context for HITL support (only in automation mode)
+    if (config.automationContext) {
+        clientContext.automationContext = config.automationContext;
+    }
     await Registry.init(clientContext);
     // Store bundled dependencies in Registry for use throughout the application
     if (config.bundledDependencies) {
@@ -237,6 +242,17 @@ export async function serve(config) {
                     result = await handleGetServerConfig(parsed.data);
                     break;
                 }
+                // Notify tool handler (automation mode only)
+                case "notify": {
+                    await logger.debug("Handling notify request");
+                    const parsed = NotifyParamsSchema.safeParse(params);
+                    if (!parsed.success)
+                        throw new Error(`Invalid notify params: ${parsed.error}`);
+                    if (!clientContext.isInitialized())
+                        throw new Error(`ToolPlex is not initialized`);
+                    result = await handleNotify(parsed.data);
+                    break;
+                }
                 default:
                     await logger.warn(`Unknown tool requested: ${name}`);
                     result = {

package/dist/shared/mcpServerTypes.d.ts

@@ -1,5 +1,6 @@
 import { z } from "zod";
-export type ClientMode = "standard" | "restricted";
+import type { AutomationContext } from "../mcp-server/toolplexApi/types.js";
+export type ClientMode = "standard" | "restricted" | "automation";
 export type LogLevel = "error" | "warn" | "info" | "debug";
 /**
  * Paths to bundled dependencies provided by the host application (e.g., Electron).
@@ -40,6 +41,8 @@ export interface ToolplexServerConfig {
     };
     /** Optional user ID for system API keys to specify user context (per-user telemetry) */
     userId?: string;
+    /** Automation context for HITL support (only set in automation mode) */
+    automationContext?: AutomationContext;
 }
 export declare const TransportTypeSchema: z.ZodEnum<["stdio", "sse"]>;
 export type TransportType = z.infer<typeof TransportTypeSchema>;
@@ -448,3 +451,26 @@ export declare const SubmitFeedbackParamsSchema: z.ZodObject<{
     } | undefined;
 }>;
 export type SubmitFeedbackParams = z.infer<typeof SubmitFeedbackParamsSchema>;
+export declare const NotifyParamsSchema: z.ZodObject<{
+    title: z.ZodString;
+    content: z.ZodString;
+    context: z.ZodOptional<z.ZodString>;
+    response_type: z.ZodEnum<["boolean", "multi_choice", "freeform"]>;
+    response_options: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+    pause_until_response: z.ZodBoolean;
+}, "strip", z.ZodTypeAny, {
+    title: string;
+    content: string;
+    response_type: "boolean" | "multi_choice" | "freeform";
+    pause_until_response: boolean;
+    context?: string | undefined;
+    response_options?: string[] | undefined;
+}, {
+    title: string;
+    content: string;
+    response_type: "boolean" | "multi_choice" | "freeform";
+    pause_until_response: boolean;
+    context?: string | undefined;
+    response_options?: string[] | undefined;
+}>;
+export type NotifyParams = z.infer<typeof NotifyParamsSchema>;

package/dist/shared/mcpServerTypes.js

@@ -161,3 +161,14 @@ export const SubmitFeedbackParamsSchema = z.object({
     })
         .optional(),
 });
+// --------------------
+// NotifyParams (for automation HITL notifications)
+// --------------------
+export const NotifyParamsSchema = z.object({
+    title: z.string().max(100),
+    content: z.string(),
+    context: z.string().optional(),
+    response_type: z.enum(["boolean", "multi_choice", "freeform"]),
+    response_options: z.array(z.string()).optional(),
+    pause_until_response: z.boolean(),
+});

package/dist/src/mcp-server/clientContext.js

@@ -14,6 +14,7 @@ export class ClientContext {
         this._isOrgUser = null;
         this._clientName = null;
         this._userId = null; // For system keys to specify user context
+        this._automationContext = null; // For automation mode HITL
     }
     get sessionId() {
         if (!this._sessionId) {
@@ -116,6 +117,17 @@ export class ClientContext {
     set userId(id) {
         this._userId = id;
     }
+    /**
+     * Automation context for HITL (Human-in-the-Loop) support.
+     * Only set when clientMode is 'automation'.
+     * Contains allowed tools, tools requiring approval, and notification config.
+     */
+    get automationContext() {
+        return this._automationContext;
+    }
+    set automationContext(context) {
+        this._automationContext = context;
+    }
     isInitialized() {
         return !!(this._sessionId &&
             this._apiKey &&

package/dist/src/shared/mcpServerTypes.js

@@ -161,3 +161,14 @@ export const SubmitFeedbackParamsSchema = z.object({
     })
         .optional(),
 });
+// --------------------
+// NotifyParams (for automation HITL notifications)
+// --------------------
+export const NotifyParamsSchema = z.object({
+    title: z.string().max(100),
+    content: z.string(),
+    context: z.string().optional(),
+    response_type: z.enum(["boolean", "multi_choice", "freeform"]),
+    response_options: z.array(z.string()).optional(),
+    pause_until_response: z.boolean(),
+});

package/dist/version.d.ts

@@ -1 +1 @@
-export declare const version = "0.1.41";
+export declare const version = "0.1.44";

package/dist/version.js

@@ -1 +1 @@
-export const version = '0.1.41';
+export const version = '0.1.44';

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@toolplex/client",
-  "version": "0.1.41",
+  "version": "0.1.44",
   "author": "ToolPlex LLC",
   "license": "SEE LICENSE IN LICENSE",
   "description": "The official ToolPlex client for AI agent tool discovery and execution",