@dexto/tools-process 1.5.0

package/dist/tool-provider.cjs

@@ -0,0 +1,96 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __export = (target, all) => {
+  for (var name in all)
+    __defProp(target, name, { get: all[name], enumerable: true });
+};
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var tool_provider_exports = {};
+__export(tool_provider_exports, {
+  processToolsProvider: () => processToolsProvider
+});
+module.exports = __toCommonJS(tool_provider_exports);
+var import_zod = require("zod");
+var import_process_service = require("./process-service.js");
+var import_bash_exec_tool = require("./bash-exec-tool.js");
+var import_bash_output_tool = require("./bash-output-tool.js");
+var import_kill_process_tool = require("./kill-process-tool.js");
+const DEFAULT_SECURITY_LEVEL = "moderate";
+const DEFAULT_MAX_TIMEOUT = 6e5;
+const DEFAULT_MAX_CONCURRENT_PROCESSES = 5;
+const DEFAULT_MAX_OUTPUT_BUFFER = 1 * 1024 * 1024;
+const DEFAULT_ALLOWED_COMMANDS = [];
+const DEFAULT_BLOCKED_COMMANDS = [];
+const DEFAULT_ENVIRONMENT = {};
+const ProcessToolsConfigSchema = import_zod.z.object({
+  type: import_zod.z.literal("process-tools"),
+  securityLevel: import_zod.z.enum(["strict", "moderate", "permissive"]).default(DEFAULT_SECURITY_LEVEL).describe("Security level for command execution validation"),
+  maxTimeout: import_zod.z.number().int().positive().max(DEFAULT_MAX_TIMEOUT).default(DEFAULT_MAX_TIMEOUT).describe(
+    `Maximum timeout for commands in milliseconds (max: ${DEFAULT_MAX_TIMEOUT / 1e3 / 60} minutes)`
+  ),
+  maxConcurrentProcesses: import_zod.z.number().int().positive().default(DEFAULT_MAX_CONCURRENT_PROCESSES).describe(
+    `Maximum number of concurrent background processes (default: ${DEFAULT_MAX_CONCURRENT_PROCESSES})`
+  ),
+  maxOutputBuffer: import_zod.z.number().int().positive().default(DEFAULT_MAX_OUTPUT_BUFFER).describe(
+    `Maximum output buffer size in bytes (default: ${DEFAULT_MAX_OUTPUT_BUFFER / 1024 / 1024}MB)`
+  ),
+  workingDirectory: import_zod.z.string().optional().describe("Working directory for process execution (defaults to process.cwd())"),
+  allowedCommands: import_zod.z.array(import_zod.z.string()).default(DEFAULT_ALLOWED_COMMANDS).describe(
+    "Explicitly allowed commands (empty = all allowed with approval, strict mode only)"
+  ),
+  blockedCommands: import_zod.z.array(import_zod.z.string()).default(DEFAULT_BLOCKED_COMMANDS).describe("Blocked command patterns (applies to all security levels)"),
+  environment: import_zod.z.record(import_zod.z.string()).default(DEFAULT_ENVIRONMENT).describe("Custom environment variables to set for command execution"),
+  timeout: import_zod.z.number().int().positive().max(DEFAULT_MAX_TIMEOUT).optional().describe(
+    `Default timeout in milliseconds (max: ${DEFAULT_MAX_TIMEOUT / 1e3 / 60} minutes)`
+  )
+}).strict();
+const processToolsProvider = {
+  type: "process-tools",
+  configSchema: ProcessToolsConfigSchema,
+  create: (config, context) => {
+    const { logger } = context;
+    logger.debug("Creating ProcessService for process tools");
+    const processService = new import_process_service.ProcessService(
+      {
+        securityLevel: config.securityLevel,
+        maxTimeout: config.maxTimeout,
+        maxConcurrentProcesses: config.maxConcurrentProcesses,
+        maxOutputBuffer: config.maxOutputBuffer,
+        workingDirectory: config.workingDirectory || process.cwd(),
+        allowedCommands: config.allowedCommands,
+        blockedCommands: config.blockedCommands,
+        environment: config.environment
+      },
+      logger
+    );
+    processService.initialize().catch((error) => {
+      logger.error(`Failed to initialize ProcessService: ${error.message}`);
+    });
+    logger.debug("ProcessService created - initialization will complete on first tool use");
+    return [
+      (0, import_bash_exec_tool.createBashExecTool)(processService),
+      (0, import_bash_output_tool.createBashOutputTool)(processService),
+      (0, import_kill_process_tool.createKillProcessTool)(processService)
+    ];
+  },
+  metadata: {
+    displayName: "Process Tools",
+    description: "Process execution and management (bash, output, kill)",
+    category: "process"
+  }
+};
+// Annotate the CommonJS export names for ESM import in node:
+0 && (module.exports = {
+  processToolsProvider
+});

package/dist/tool-provider.d.cts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { CustomToolProvider } from '@dexto/core';
+
+/**
+ * Process Tools Provider
+ *
+ * Provides process execution and management tools by wrapping ProcessService.
+ * When registered, the provider initializes ProcessService and creates tools
+ * for command execution and process management.
+ */
+
+/**
+ * Configuration schema for Process tools provider.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all configuration:
+ * - Validation rules
+ * - Default values (using constants above)
+ * - Documentation
+ * - Type definitions
+ *
+ * Services receive fully-validated config from this schema and use it as-is,
+ * with no additional defaults or fallbacks needed.
+ */
+declare const ProcessToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"process-tools">;
+    securityLevel: z.ZodDefault<z.ZodEnum<["strict", "moderate", "permissive"]>>;
+    maxTimeout: z.ZodDefault<z.ZodNumber>;
+    maxConcurrentProcesses: z.ZodDefault<z.ZodNumber>;
+    maxOutputBuffer: z.ZodDefault<z.ZodNumber>;
+    workingDirectory: z.ZodOptional<z.ZodString>;
+    allowedCommands: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockedCommands: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    environment: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "process-tools";
+    securityLevel: "strict" | "moderate" | "permissive";
+    maxTimeout: number;
+    maxConcurrentProcesses: number;
+    maxOutputBuffer: number;
+    allowedCommands: string[];
+    blockedCommands: string[];
+    environment: Record<string, string>;
+    timeout?: number | undefined;
+    workingDirectory?: string | undefined;
+}, {
+    type: "process-tools";
+    timeout?: number | undefined;
+    securityLevel?: "strict" | "moderate" | "permissive" | undefined;
+    maxTimeout?: number | undefined;
+    maxConcurrentProcesses?: number | undefined;
+    maxOutputBuffer?: number | undefined;
+    allowedCommands?: string[] | undefined;
+    blockedCommands?: string[] | undefined;
+    environment?: Record<string, string> | undefined;
+    workingDirectory?: string | undefined;
+}>;
+type ProcessToolsConfig = z.output<typeof ProcessToolsConfigSchema>;
+/**
+ * Process tools provider.
+ *
+ * Wraps ProcessService and provides process operation tools:
+ * - bash_exec: Execute bash commands (foreground or background)
+ * - bash_output: Retrieve output from background processes
+ * - kill_process: Terminate background processes
+ *
+ * When registered via customToolRegistry, ProcessService is automatically
+ * initialized and process operation tools become available to the agent.
+ */
+declare const processToolsProvider: CustomToolProvider<'process-tools', ProcessToolsConfig>;
+
+export { processToolsProvider };

package/dist/tool-provider.d.ts

@@ -0,0 +1,72 @@
+import { z } from 'zod';
+import { CustomToolProvider } from '@dexto/core';
+
+/**
+ * Process Tools Provider
+ *
+ * Provides process execution and management tools by wrapping ProcessService.
+ * When registered, the provider initializes ProcessService and creates tools
+ * for command execution and process management.
+ */
+
+/**
+ * Configuration schema for Process tools provider.
+ *
+ * This is the SINGLE SOURCE OF TRUTH for all configuration:
+ * - Validation rules
+ * - Default values (using constants above)
+ * - Documentation
+ * - Type definitions
+ *
+ * Services receive fully-validated config from this schema and use it as-is,
+ * with no additional defaults or fallbacks needed.
+ */
+declare const ProcessToolsConfigSchema: z.ZodObject<{
+    type: z.ZodLiteral<"process-tools">;
+    securityLevel: z.ZodDefault<z.ZodEnum<["strict", "moderate", "permissive"]>>;
+    maxTimeout: z.ZodDefault<z.ZodNumber>;
+    maxConcurrentProcesses: z.ZodDefault<z.ZodNumber>;
+    maxOutputBuffer: z.ZodDefault<z.ZodNumber>;
+    workingDirectory: z.ZodOptional<z.ZodString>;
+    allowedCommands: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    blockedCommands: z.ZodDefault<z.ZodArray<z.ZodString, "many">>;
+    environment: z.ZodDefault<z.ZodRecord<z.ZodString, z.ZodString>>;
+    timeout: z.ZodOptional<z.ZodNumber>;
+}, "strict", z.ZodTypeAny, {
+    type: "process-tools";
+    securityLevel: "strict" | "moderate" | "permissive";
+    maxTimeout: number;
+    maxConcurrentProcesses: number;
+    maxOutputBuffer: number;
+    allowedCommands: string[];
+    blockedCommands: string[];
+    environment: Record<string, string>;
+    timeout?: number | undefined;
+    workingDirectory?: string | undefined;
+}, {
+    type: "process-tools";
+    timeout?: number | undefined;
+    securityLevel?: "strict" | "moderate" | "permissive" | undefined;
+    maxTimeout?: number | undefined;
+    maxConcurrentProcesses?: number | undefined;
+    maxOutputBuffer?: number | undefined;
+    allowedCommands?: string[] | undefined;
+    blockedCommands?: string[] | undefined;
+    environment?: Record<string, string> | undefined;
+    workingDirectory?: string | undefined;
+}>;
+type ProcessToolsConfig = z.output<typeof ProcessToolsConfigSchema>;
+/**
+ * Process tools provider.
+ *
+ * Wraps ProcessService and provides process operation tools:
+ * - bash_exec: Execute bash commands (foreground or background)
+ * - bash_output: Retrieve output from background processes
+ * - kill_process: Terminate background processes
+ *
+ * When registered via customToolRegistry, ProcessService is automatically
+ * initialized and process operation tools become available to the agent.
+ */
+declare const processToolsProvider: CustomToolProvider<'process-tools', ProcessToolsConfig>;
+
+export { processToolsProvider };

package/dist/tool-provider.js

@@ -0,0 +1,72 @@
+import { z } from "zod";
+import { ProcessService } from "./process-service.js";
+import { createBashExecTool } from "./bash-exec-tool.js";
+import { createBashOutputTool } from "./bash-output-tool.js";
+import { createKillProcessTool } from "./kill-process-tool.js";
+const DEFAULT_SECURITY_LEVEL = "moderate";
+const DEFAULT_MAX_TIMEOUT = 6e5;
+const DEFAULT_MAX_CONCURRENT_PROCESSES = 5;
+const DEFAULT_MAX_OUTPUT_BUFFER = 1 * 1024 * 1024;
+const DEFAULT_ALLOWED_COMMANDS = [];
+const DEFAULT_BLOCKED_COMMANDS = [];
+const DEFAULT_ENVIRONMENT = {};
+const ProcessToolsConfigSchema = z.object({
+  type: z.literal("process-tools"),
+  securityLevel: z.enum(["strict", "moderate", "permissive"]).default(DEFAULT_SECURITY_LEVEL).describe("Security level for command execution validation"),
+  maxTimeout: z.number().int().positive().max(DEFAULT_MAX_TIMEOUT).default(DEFAULT_MAX_TIMEOUT).describe(
+    `Maximum timeout for commands in milliseconds (max: ${DEFAULT_MAX_TIMEOUT / 1e3 / 60} minutes)`
+  ),
+  maxConcurrentProcesses: z.number().int().positive().default(DEFAULT_MAX_CONCURRENT_PROCESSES).describe(
+    `Maximum number of concurrent background processes (default: ${DEFAULT_MAX_CONCURRENT_PROCESSES})`
+  ),
+  maxOutputBuffer: z.number().int().positive().default(DEFAULT_MAX_OUTPUT_BUFFER).describe(
+    `Maximum output buffer size in bytes (default: ${DEFAULT_MAX_OUTPUT_BUFFER / 1024 / 1024}MB)`
+  ),
+  workingDirectory: z.string().optional().describe("Working directory for process execution (defaults to process.cwd())"),
+  allowedCommands: z.array(z.string()).default(DEFAULT_ALLOWED_COMMANDS).describe(
+    "Explicitly allowed commands (empty = all allowed with approval, strict mode only)"
+  ),
+  blockedCommands: z.array(z.string()).default(DEFAULT_BLOCKED_COMMANDS).describe("Blocked command patterns (applies to all security levels)"),
+  environment: z.record(z.string()).default(DEFAULT_ENVIRONMENT).describe("Custom environment variables to set for command execution"),
+  timeout: z.number().int().positive().max(DEFAULT_MAX_TIMEOUT).optional().describe(
+    `Default timeout in milliseconds (max: ${DEFAULT_MAX_TIMEOUT / 1e3 / 60} minutes)`
+  )
+}).strict();
+const processToolsProvider = {
+  type: "process-tools",
+  configSchema: ProcessToolsConfigSchema,
+  create: (config, context) => {
+    const { logger } = context;
+    logger.debug("Creating ProcessService for process tools");
+    const processService = new ProcessService(
+      {
+        securityLevel: config.securityLevel,
+        maxTimeout: config.maxTimeout,
+        maxConcurrentProcesses: config.maxConcurrentProcesses,
+        maxOutputBuffer: config.maxOutputBuffer,
+        workingDirectory: config.workingDirectory || process.cwd(),
+        allowedCommands: config.allowedCommands,
+        blockedCommands: config.blockedCommands,
+        environment: config.environment
+      },
+      logger
+    );
+    processService.initialize().catch((error) => {
+      logger.error(`Failed to initialize ProcessService: ${error.message}`);
+    });
+    logger.debug("ProcessService created - initialization will complete on first tool use");
+    return [
+      createBashExecTool(processService),
+      createBashOutputTool(processService),
+      createKillProcessTool(processService)
+    ];
+  },
+  metadata: {
+    displayName: "Process Tools",
+    description: "Process execution and management (bash, output, kill)",
+    category: "process"
+  }
+};
+export {
+  processToolsProvider
+};

package/dist/types.cjs

@@ -0,0 +1,16 @@
+"use strict";
+var __defProp = Object.defineProperty;
+var __getOwnPropDesc = Object.getOwnPropertyDescriptor;
+var __getOwnPropNames = Object.getOwnPropertyNames;
+var __hasOwnProp = Object.prototype.hasOwnProperty;
+var __copyProps = (to, from, except, desc) => {
+  if (from && typeof from === "object" || typeof from === "function") {
+    for (let key of __getOwnPropNames(from))
+      if (!__hasOwnProp.call(to, key) && key !== except)
+        __defProp(to, key, { get: () => from[key], enumerable: !(desc = __getOwnPropDesc(from, key)) || desc.enumerable });
+  }
+  return to;
+};
+var __toCommonJS = (mod) => __copyProps(__defProp({}, "__esModule", { value: true }), mod);
+var types_exports = {};
+module.exports = __toCommonJS(types_exports);

package/dist/types.d.cts

@@ -0,0 +1,108 @@
+/**
+ * Process Service Types
+ *
+ * Types and interfaces for command execution and process management
+ */
+/**
+ * Process execution options
+ */
+interface ExecuteOptions {
+    /** Working directory */
+    cwd?: string | undefined;
+    /** Timeout in milliseconds (max: 600000) */
+    timeout?: number | undefined;
+    /** Run command in background */
+    runInBackground?: boolean | undefined;
+    /** Environment variables */
+    env?: Record<string, string> | undefined;
+    /** Description of what the command does (5-10 words) */
+    description?: string | undefined;
+    /** Abort signal for cancellation support */
+    abortSignal?: AbortSignal | undefined;
+}
+/**
+ * Process execution result (foreground execution only)
+ * For background execution, see ProcessHandle
+ */
+interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    duration: number;
+}
+/**
+ * Background process handle
+ */
+interface ProcessHandle {
+    processId: string;
+    command: string;
+    pid?: number | undefined;
+    startedAt: Date;
+    description?: string | undefined;
+}
+/**
+ * Process output (for retrieving from background processes)
+ */
+interface ProcessOutput {
+    stdout: string;
+    stderr: string;
+    status: 'running' | 'completed' | 'failed';
+    exitCode?: number | undefined;
+    duration?: number | undefined;
+}
+/**
+ * Process information
+ */
+interface ProcessInfo {
+    processId: string;
+    command: string;
+    pid?: number | undefined;
+    status: 'running' | 'completed' | 'failed';
+    startedAt: Date;
+    completedAt?: Date | undefined;
+    exitCode?: number | undefined;
+    description?: string | undefined;
+}
+/**
+ * Command validation result
+ */
+interface CommandValidation {
+    isValid: boolean;
+    error?: string;
+    normalizedCommand?: string;
+    requiresApproval?: boolean;
+}
+/**
+ * Process service configuration
+ */
+interface ProcessConfig {
+    /** Security level for command execution */
+    securityLevel: 'strict' | 'moderate' | 'permissive';
+    /** Maximum timeout for commands in milliseconds */
+    maxTimeout: number;
+    /** Maximum concurrent background processes */
+    maxConcurrentProcesses: number;
+    /** Maximum output buffer size in bytes */
+    maxOutputBuffer: number;
+    /** Explicitly allowed commands (empty = all allowed with approval) */
+    allowedCommands: string[];
+    /** Blocked command patterns */
+    blockedCommands: string[];
+    /** Custom environment variables */
+    environment: Record<string, string>;
+    /** Working directory (defaults to process.cwd()) */
+    workingDirectory?: string | undefined;
+}
+/**
+ * Output buffer management
+ */
+interface OutputBuffer {
+    stdout: string[];
+    stderr: string[];
+    complete: boolean;
+    lastRead: number;
+    bytesUsed: number;
+    truncated?: boolean;
+}
+
+export type { CommandValidation, ExecuteOptions, OutputBuffer, ProcessConfig, ProcessHandle, ProcessInfo, ProcessOutput, ProcessResult };

package/dist/types.d.ts

@@ -0,0 +1,108 @@
+/**
+ * Process Service Types
+ *
+ * Types and interfaces for command execution and process management
+ */
+/**
+ * Process execution options
+ */
+interface ExecuteOptions {
+    /** Working directory */
+    cwd?: string | undefined;
+    /** Timeout in milliseconds (max: 600000) */
+    timeout?: number | undefined;
+    /** Run command in background */
+    runInBackground?: boolean | undefined;
+    /** Environment variables */
+    env?: Record<string, string> | undefined;
+    /** Description of what the command does (5-10 words) */
+    description?: string | undefined;
+    /** Abort signal for cancellation support */
+    abortSignal?: AbortSignal | undefined;
+}
+/**
+ * Process execution result (foreground execution only)
+ * For background execution, see ProcessHandle
+ */
+interface ProcessResult {
+    stdout: string;
+    stderr: string;
+    exitCode: number;
+    duration: number;
+}
+/**
+ * Background process handle
+ */
+interface ProcessHandle {
+    processId: string;
+    command: string;
+    pid?: number | undefined;
+    startedAt: Date;
+    description?: string | undefined;
+}
+/**
+ * Process output (for retrieving from background processes)
+ */
+interface ProcessOutput {
+    stdout: string;
+    stderr: string;
+    status: 'running' | 'completed' | 'failed';
+    exitCode?: number | undefined;
+    duration?: number | undefined;
+}
+/**
+ * Process information
+ */
+interface ProcessInfo {
+    processId: string;
+    command: string;
+    pid?: number | undefined;
+    status: 'running' | 'completed' | 'failed';
+    startedAt: Date;
+    completedAt?: Date | undefined;
+    exitCode?: number | undefined;
+    description?: string | undefined;
+}
+/**
+ * Command validation result
+ */
+interface CommandValidation {
+    isValid: boolean;
+    error?: string;
+    normalizedCommand?: string;
+    requiresApproval?: boolean;
+}
+/**
+ * Process service configuration
+ */
+interface ProcessConfig {
+    /** Security level for command execution */
+    securityLevel: 'strict' | 'moderate' | 'permissive';
+    /** Maximum timeout for commands in milliseconds */
+    maxTimeout: number;
+    /** Maximum concurrent background processes */
+    maxConcurrentProcesses: number;
+    /** Maximum output buffer size in bytes */
+    maxOutputBuffer: number;
+    /** Explicitly allowed commands (empty = all allowed with approval) */
+    allowedCommands: string[];
+    /** Blocked command patterns */
+    blockedCommands: string[];
+    /** Custom environment variables */
+    environment: Record<string, string>;
+    /** Working directory (defaults to process.cwd()) */
+    workingDirectory?: string | undefined;
+}
+/**
+ * Output buffer management
+ */
+interface OutputBuffer {
+    stdout: string[];
+    stderr: string[];
+    complete: boolean;
+    lastRead: number;
+    bytesUsed: number;
+    truncated?: boolean;
+}
+
+export type { CommandValidation, ExecuteOptions, OutputBuffer, ProcessConfig, ProcessHandle, ProcessInfo, ProcessOutput, ProcessResult };

package/package.json

@@ -0,0 +1,38 @@
+{
+  "name": "@dexto/tools-process",
+  "version": "1.5.0",
+  "description": "Process tools provider for Dexto agents",
+  "type": "module",
+  "main": "./dist/index.js",
+  "types": "./dist/index.d.ts",
+  "exports": {
+    ".": {
+      "types": "./dist/index.d.ts",
+      "import": "./dist/index.js"
+    }
+  },
+  "keywords": [
+    "dexto",
+    "tools",
+    "process",
+    "bash",
+    "shell"
+  ],
+  "dependencies": {
+    "zod": "^3.25.0",
+    "@dexto/core": "1.5.0"
+  },
+  "devDependencies": {
+    "tsup": "^8.0.0",
+    "typescript": "^5.3.3"
+  },
+  "files": [
+    "dist",
+    "README.md"
+  ],
+  "scripts": {
+    "build": "tsup",
+    "typecheck": "tsc --noEmit",
+    "clean": "rm -rf dist"
+  }
+}