@mxf-dev/core 1.0.1 → 2.0.0

package/src/prompts/MxfAgentSystemPrompt.ts

@@ -35,7 +35,6 @@ import { Logger } from '../utils/Logger.js';
 import { createStrictValidator } from '../utils/validation.js';
 import {
     COMMUNICATION_TOOLS,
-    CONTROL_LOOP_TOOLS,
     CONTEXT_MEMORY_TOOLS,
     META_TOOLS
 } from '../constants/ToolNames.js';
@@ -145,7 +144,7 @@ Execute immediately when you have sufficient information. Take decisive action b
     private static buildMxfIdentity(agentConfig: AgentConfig, availableTools?: string[]): string {
         // Determine available capabilities based on tools
         const toolSet = availableTools || [];
-        const hasControlLoop = toolSet.some(tool => tool.startsWith('controlLoop_'));
+        const hasOrpar = toolSet.some(tool => tool.startsWith('orpar_'));
         const hasCommunication = toolSet.some(tool => tool.startsWith('messaging_') || tool.startsWith('agent_'));
         const hasMemoryContext = toolSet.some(tool => tool.includes('context_') || tool.includes('memory_'));
         
@@ -165,7 +164,7 @@ Execute immediately when you have sufficient information. Take decisive action b
 MXF enables you to collaborate with other AI agents`;
         
         // Only mention ORPAR if control loop tools are available
-        if (hasControlLoop) {
+        if (hasOrpar) {
             content += `, execute complex workflows through ORPAR cognitive cycles,`;
         }
         
@@ -261,15 +260,18 @@ Use tools to take actions - the system will automatically execute your tool requ
         }
         
         // Control Loop - only if control loop tools are available
-        const hasControlLoop = toolSet.some(tool => tool.startsWith('controlLoop_'));
-        if (hasControlLoop) {
-            const controlCapabilities: string[] = [];
-            if (toolSet.includes('controlLoop_start')) controlCapabilities.push(`- **${CONTROL_LOOP_TOOLS.START}**: Start new ORPAR cognitive cycles`);
-            if (toolSet.includes('controlLoop_observe')) controlCapabilities.push(`- **${CONTROL_LOOP_TOOLS.OBSERVE}**: Submit observations to active control loops`);
-            if (toolSet.includes('controlLoop_execute')) controlCapabilities.push(`- **${CONTROL_LOOP_TOOLS.EXECUTE}**: Execute planned actions within control loops`);
-            
-            if (controlCapabilities.length > 0) {
-                sections.push(`**Control Loop (ORPAR Integration):**\n${controlCapabilities.join('\n')}`);
+        const hasOrpar = toolSet.some(tool => tool.startsWith('orpar_'));
+        if (hasOrpar) {
+            const orparCapabilities: string[] = [];
+            if (toolSet.includes('orpar_observe')) orparCapabilities.push('- **orpar_observe**: Record what you observed, starting a cognitive cycle');
+            if (toolSet.includes('orpar_reason')) orparCapabilities.push('- **orpar_reason**: Record your reasoning about the observation');
+            if (toolSet.includes('orpar_plan')) orparCapabilities.push('- **orpar_plan**: Record the plan you intend to carry out');
+            if (toolSet.includes('orpar_act')) orparCapabilities.push('- **orpar_act**: Record the action you took');
+            if (toolSet.includes('orpar_reflect')) orparCapabilities.push('- **orpar_reflect**: Record what you learned, completing the cycle');
+            if (toolSet.includes('orpar_status')) orparCapabilities.push('- **orpar_status**: Check which phase of the cycle you are in');
+
+            if (orparCapabilities.length > 0) {
+                sections.push(`**ORPAR cognitive cycle:**\n${orparCapabilities.join('\n')}`);
             }
         }
         
@@ -304,43 +306,26 @@ Use tools to take actions - the system will automatically execute your tool requ
 
     /**
      * Detailed Tool Schemas with JSON Examples
-     * Now respects allowedTools to only show documentation for tools the agent can actually use
+     * Only documents tools the registry actually provided and the agent is allowed to use.
      */
     private static async buildToolSchemas(config: MxfSystemPromptConfig, availableTools?: any[], toolNames?: string[], agentConfig?: AgentConfig): Promise<string> {
         if (!config.includeToolSchemas) return '';
 
-        // Use provided tools from the actual tool registry
-        let tools: any[] = availableTools || [];
+        // Tools come from the registry. Nothing else is a valid source.
+        //
+        // An earlier version, when handed no tools, invented them: it took the
+        // list of tool NAMES and built "mock tool objects" with made-up
+        // descriptions and guessed input schemas, then presented them to the
+        // agent as documentation. The agent then called those tools with the
+        // guessed arguments, producing malformed calls. If the registry has no
+        // tools, the honest output is no tool-schema section at all.
+        const tools: any[] = availableTools || [];
         if (tools.length === 0) {
-            // Core tools fallback - create mock tool objects for allowed tools (or all core tools if no allowedTools)
-            const toolsToMock = (toolNames && toolNames.length > 0) ? toolNames : CORE_MXF_TOOLS;
-            tools = toolsToMock.map(toolName => ({
-                name: toolName,
-                description: `${toolName} - Core MXF ${toolName.includes('memory') ? 'Memory Management' : toolName.includes('messaging') ? 'Communication' : toolName.includes('controlLoop') ? 'ORPAR Control Loop' : toolName.includes('task') ? 'Task Management' : 'Meta'} tool`,
-                inputSchema: {
-                    type: 'object',
-                    properties: {
-                        ...(toolName.includes('messaging') && {
-                            targetAgentId: { type: 'string' },
-                            message: { type: 'string' }
-                        }),
-                        ...(toolName.includes('memory') && {
-                            key: { type: 'string' },
-                            value: { type: 'string' }
-                        }),
-                        ...(toolName.includes('controlLoop') && {
-                            observation: { type: 'string' },
-                            confidence: { type: 'number' }
-                        }),
-                        ...(toolName === 'task_complete' && {
-                            summary: { type: 'string', required: true },
-                            success: { type: 'boolean', default: true },
-                            details: { type: 'object', optional: true },
-                            nextSteps: { type: 'string', optional: true }
-                        })
-                    }
-                }
-            }));
+            logger.error(
+                'SYSTEM PROMPT: the tool registry returned no tools, so no tool schemas can be documented. ' +
+                'Check that the agent has tools registered and that allowedTools is not empty.'
+            );
+            return '';
         }
 
         // Deduplicate tools by name (keep first occurrence)
@@ -370,8 +355,13 @@ Use tools to take actions - the system will automatically execute your tool requ
         const finalToolsForDocumentation = mxfCoreTools;
         
         if (finalToolsForDocumentation.length === 0) {
-            logger.error('❌ SYSTEM PROMPT: No allowed tools found for this agent - this indicates a configuration issue');
-            return '## Tool Usage Reference\n\n❌ **ERROR: No allowed tools found**\n\nThis agent has no tools configured in its allowedTools list.';
+            // Emit no section rather than writing an error notice into the
+            // agent's system prompt, which the model would read as instructions.
+            logger.error(
+                'SYSTEM PROMPT: none of the registry tools match this agent\'s allowedTools, ' +
+                'so no tool schemas can be documented. This is a configuration issue.'
+            );
+            return '';
         }
 
         // Apply deferred tool schema disclosure if enabled — tier-2 tools get
@@ -400,7 +390,7 @@ Use tools to take actions - the system will automatically execute your tool requ
 
         // Group allowed tools by category (only show documentation for tools this agent can actually use)
         const communicationTools = toolsForFullDocs.filter(t => t.name.startsWith('messaging_'));
-        const controlLoopTools = toolsForFullDocs.filter(t => t.name.startsWith('controlLoop_'));
+        const orparTools = toolsForFullDocs.filter(t => t.name.startsWith('orpar_'));
         const infrastructureTools = toolsForFullDocs.filter(t =>
             t.name === 'filesystem_read' || t.name === 'filesystem_write' ||
             t.name === 'filesystem_list' || t.name === 'shell_execute' ||
@@ -424,9 +414,9 @@ Use tools to take actions - the system will automatically execute your tool requ
         }
 
         // Control Loop Tools Section
-        if (controlLoopTools.length > 0) {
+        if (orparTools.length > 0) {
             toolSections.push('### Control Loop Tools\n');
-            for (const tool of controlLoopTools) {
+            for (const tool of orparTools) {
                 toolSections.push(this.buildToolExample(tool, agentConfig?.mxpEnabled, compactionConfig.toolBehavioralGuidanceEnabled));
             }
         }
@@ -534,12 +524,12 @@ ${toolSections.join('\n')}${deferredSummary}`;
         }
         
         // Pattern 2: ORPAR Integration - only if control loop tools are available
-        const hasControlLoop = toolSet.some(tool => tool.startsWith('controlLoop_'));
-        if (hasControlLoop) {
-            const observeTool = toolSet.find(tool => tool === 'controlLoop_observe');
+        const hasOrpar = toolSet.some(tool => tool.startsWith('orpar_'));
+        if (hasOrpar) {
+            const observeTool = toolSet.find(tool => tool === 'orpar_observe');
             if (observeTool) {
                 sections.push(`**Pattern 2: ORPAR Integration**
-- Submit observations using 'controlLoop_observe'
+- Submit observations using 'orpar_observe'
 - Include confidence scores and data sources
 - Provide rich metadata for better reasoning`);
             }
@@ -638,9 +628,9 @@ When you need capabilities beyond your core tools:
         
         // Only include ORPAR if control loop tools are available
         const toolSet = availableTools || [];
-        const hasControlLoop = toolSet.some(tool => tool.startsWith('controlLoop_'));
+        const hasOrpar = toolSet.some(tool => tool.startsWith('orpar_'));
         
-        if (!hasControlLoop) return '';
+        if (!hasOrpar) return '';
 
         return `## MXF Operational Guidelines
 

package/src/protocols/mcp/ToolError.ts

@@ -0,0 +1,201 @@
+/**
+ * Copyright 2024 Brad Anderson
+ *
+ * Licensed under the Apache License, Version 2.0 (the "License");
+ * you may not use this file except in compliance with the License.
+ * You may obtain a copy of the License at
+ *
+ *     http://www.apache.org/licenses/LICENSE-2.0
+ *
+ * Unless required by applicable law or agreed to in writing, software
+ * distributed under the License is distributed on an "AS IS" BASIS,
+ * WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
+ * See the License for the specific language governing permissions and
+ * limitations under the License.
+ *
+ * @author Brad Anderson <BradA1878@pm.me>
+ * @repository https://github.com/BradA1878/model-exchange-framework
+ * @documentation https://mxf-dev.github.io/mxf/
+ */
+
+/**
+ * ToolError.ts
+ *
+ * The single error type for MCP tool handlers.
+ *
+ * Before this existed, tool failures were encoded three different ways — a thrown
+ * Error, a `{ success: false }` object, or a result whose `data` happened to hold
+ * an `error` string — so callers could not tell a failure from a result. Handlers
+ * written with `defineTool` throw a ToolError; the factory turns it into one
+ * result envelope with `isError: true`.
+ *
+ * `code` is a stable, machine-readable classification. `message` is written for
+ * the model that will read it: say what failed and what to do next.
+ */
+
+/**
+ * Machine-readable failure classifications.
+ *
+ * These map to how a caller should react, not to where the failure happened:
+ * - INVALID_INPUT: arguments did not satisfy the tool's schema or its own checks.
+ *   The model should fix the arguments and retry.
+ * - NOT_FOUND: a referenced entity (task, plan, file, server) does not exist.
+ * - PERMISSION_DENIED: the operation was blocked by a security policy.
+ * - PRECONDITION_FAILED: the system is not in a state where this can run
+ *   (for example a required service is not initialized).
+ * - EXECUTION_FAILED: the tool ran but the underlying operation failed.
+ * - UPSTREAM_ERROR: a dependency the tool calls out to failed (external MCP
+ *   server, HTTP API, database).
+ * - NOT_IMPLEMENTED: the requested mode or option is not supported.
+ */
+export type ToolErrorCode =
+    | 'INVALID_INPUT'
+    | 'NOT_FOUND'
+    | 'PERMISSION_DENIED'
+    | 'PRECONDITION_FAILED'
+    | 'EXECUTION_FAILED'
+    | 'UPSTREAM_ERROR'
+    | 'NOT_IMPLEMENTED';
+
+/**
+ * Serialized form of a ToolError, carried as the `data` of an error envelope.
+ */
+export interface ToolErrorData {
+    /** Always true — lets a reader detect an error payload without shape sniffing */
+    error: true;
+    /** Stable classification */
+    code: ToolErrorCode;
+    /** Human/model-readable description of what failed */
+    message: string;
+    /** Name of the tool that failed */
+    tool?: string;
+    /** Structured, tool-specific context (never secrets) */
+    details?: Record<string, unknown>;
+}
+
+/**
+ * The error type thrown by tool handlers.
+ *
+ * Use the static constructors rather than `new ToolError(...)` where one fits —
+ * they keep codes consistent across the ~184 tools.
+ */
+export class ToolError extends Error {
+    /** Stable, machine-readable classification */
+    public readonly code: ToolErrorCode;
+    /** Structured context for the caller. Must not contain secrets. */
+    public readonly details?: Record<string, unknown>;
+    /**
+     * The original error, when this ToolError wraps one.
+     *
+     * Set as a plain property rather than through the ES2022 `Error(msg, { cause })`
+     * option, because the test tsconfig compiles against an older lib where that
+     * constructor overload does not exist.
+     */
+    public readonly cause?: unknown;
+    /** Tool name, set by defineTool when the error passes through the factory */
+    public toolName?: string;
+
+    constructor(
+        code: ToolErrorCode,
+        message: string,
+        options?: { details?: Record<string, unknown>; cause?: unknown }
+    ) {
+        super(message);
+        this.name = 'ToolError';
+        this.code = code;
+        this.details = options?.details;
+        this.cause = options?.cause;
+
+        // Restore the prototype chain — required for `instanceof` to work when
+        // the compile target is ES5/ES2015 and Error is subclassed.
+        Object.setPrototypeOf(this, ToolError.prototype);
+    }
+
+    /** Arguments did not satisfy the schema or the handler's own checks. */
+    public static invalidInput(
+        message: string,
+        details?: Record<string, unknown>
+    ): ToolError {
+        return new ToolError('INVALID_INPUT', message, { details });
+    }
+
+    /** A referenced entity does not exist. */
+    public static notFound(
+        message: string,
+        details?: Record<string, unknown>
+    ): ToolError {
+        return new ToolError('NOT_FOUND', message, { details });
+    }
+
+    /** Blocked by a security policy. */
+    public static permissionDenied(
+        message: string,
+        details?: Record<string, unknown>
+    ): ToolError {
+        return new ToolError('PERMISSION_DENIED', message, { details });
+    }
+
+    /** The system is not in a state where this operation can run. */
+    public static preconditionFailed(
+        message: string,
+        details?: Record<string, unknown>
+    ): ToolError {
+        return new ToolError('PRECONDITION_FAILED', message, { details });
+    }
+
+    /** The tool ran but the underlying operation failed. */
+    public static executionFailed(
+        message: string,
+        options?: { details?: Record<string, unknown>; cause?: unknown }
+    ): ToolError {
+        return new ToolError('EXECUTION_FAILED', message, options);
+    }
+
+    /** A dependency the tool calls out to failed. */
+    public static upstream(
+        message: string,
+        options?: { details?: Record<string, unknown>; cause?: unknown }
+    ): ToolError {
+        return new ToolError('UPSTREAM_ERROR', message, options);
+    }
+
+    /** The requested mode or option is not supported. */
+    public static notImplemented(
+        message: string,
+        details?: Record<string, unknown>
+    ): ToolError {
+        return new ToolError('NOT_IMPLEMENTED', message, { details });
+    }
+
+    /**
+     * Serialize to the payload carried in an error result envelope.
+     */
+    public toData(): ToolErrorData {
+        return {
+            error: true,
+            code: this.code,
+            message: this.message,
+            ...(this.toolName ? { tool: this.toolName } : {}),
+            ...(this.details ? { details: this.details } : {})
+        };
+    }
+}
+
+/**
+ * Coerce any thrown value into a ToolError.
+ *
+ * A plain `throw new Error(...)` from a handler (or from a library it calls)
+ * becomes an EXECUTION_FAILED ToolError with the original attached as `cause`,
+ * so every failure leaves the factory in the same shape.
+ */
+export function toToolError(thrown: unknown): ToolError {
+    if (thrown instanceof ToolError) {
+        return thrown;
+    }
+
+    if (thrown instanceof Error) {
+        return new ToolError('EXECUTION_FAILED', thrown.message, { cause: thrown });
+    }
+
+    return new ToolError('EXECUTION_FAILED', String(thrown), { cause: thrown });
+}