@mxf-dev/core 2.0.5 → 3.0.0

package/src/protocols/mcp/tools/shell/ShellExecuteHandler.ts

@@ -26,7 +26,7 @@
  * event emission. Replaces the inline handler in InfrastructureTools.ts.
  *
  * Key improvements over the original inline handler:
- * - Uses spawn() instead of exec() — streams output, no maxBuffer limit
+ * - Runs arbitrary commands only inside the Docker shell sandbox
  * - Interprets exit codes semantically (e.g., grep returning 1 = no matches, not error)
  * - Classifies commands (read-only, silent, category) for downstream decision-making
  * - Emits lifecycle events (started, completed, failed, destructive warning)
@@ -34,7 +34,6 @@
  * - Surfaces destructive command warnings as informational events
  */
 
-import { spawn } from 'child_process';
 import crypto from 'crypto';
 
 import { Events } from '../../../../events/EventNames.js';
@@ -48,10 +47,11 @@ import {
 import { getSecurityGuard, SecurityContext } from '../../security/McpSecurityGuard.js';
 import { getConfirmationManager } from '../../security/McpConfirmationManager.js';
 import {
+    assertCommandAllowlisted,
     buildShellChildEnv,
-    getShellAllowedCommands,
-    hasShellAllowlist,
-    isShellSandboxEnabled
+    isShellSandboxEnabled,
+    requireWorkspaceRoot,
+    resolveWorkspacePath
 } from '../../security/McpToolPolicy.js';
 import { Logger } from '../../../../utils/Logger.js';
 import { createStrictValidator } from '../../../../utils/validation.js';
@@ -61,7 +61,6 @@ import { classifyCommand } from './CommandClassification.js';
 import { getDestructiveWarnings } from './DestructiveCommandWarnings.js';
 import { interpretExitCode } from './CommandSemantics.js';
 import { processOutput } from './LargeOutputHandler.js';
-import { extractEffectiveCommands } from './ShellCommandParser.js';
 import { executeInSandbox } from './ShellSandbox.js';
 
 const logger = new Logger('info', 'ShellExecuteHandler', 'server');
@@ -184,50 +183,6 @@ function buildFullCommand(command: string, args?: string[]): string {
     return `${command} ${escapedArgs}`;
 }
 
-/**
- * Execute a command using spawn() wrapped in a Promise.
- * Returns stdout, stderr, and exit code once the process closes.
- */
-function spawnCommand(
-    fullCommand: string,
-    cwd: string,
-    env: NodeJS.ProcessEnv,
-    timeout: number
-): Promise<{ stdout: string; stderr: string; exitCode: number }> {
-    return new Promise((resolve, reject) => {
-        const child = spawn(fullCommand, [], {
-            shell: true,
-            cwd,
-            env,
-            timeout
-        });
-
-        const stdoutChunks: Buffer[] = [];
-        const stderrChunks: Buffer[] = [];
-
-        child.stdout.on('data', (chunk: Buffer) => {
-            stdoutChunks.push(chunk);
-        });
-
-        child.stderr.on('data', (chunk: Buffer) => {
-            stderrChunks.push(chunk);
-        });
-
-        child.on('error', (err: Error) => {
-            // Spawn-level error (e.g., command not found, ENOENT)
-            reject(err);
-        });
-
-        child.on('close', (exitCode: number | null) => {
-            resolve({
-                stdout: Buffer.concat(stdoutChunks).toString('utf-8'),
-                stderr: Buffer.concat(stderrChunks).toString('utf-8'),
-                exitCode: exitCode ?? 1
-            });
-        });
-    });
-}
-
 // ---------------------------------------------------------------------------
 // Main execute function
 // ---------------------------------------------------------------------------
@@ -252,6 +207,16 @@ export async function execute(
     try {
         // ── 1. Validate input ──────────────────────────────────────────────
         validator.assertIsString(input.command, 'command');
+        if (!isShellSandboxEnabled()) {
+            throw new Error(
+                'shell_execute requires MXF_SHELL_SANDBOX_ENABLED=true; ' +
+                'host shell execution is not workspace-contained'
+            );
+        }
+        const workingDirectory = resolveWorkspacePath(
+            input.workingDirectory,
+            'shell_execute workingDirectory'
+        );
 
         // ── 2. Classify the command ────────────────────────────────────────
         const classification = classifyCommand(input.command);
@@ -261,7 +226,7 @@ export async function execute(
         const warningMessages = destructiveWarnings.map(w => w.warning);
 
         // ── 4. Security validation ─────────────────────────────────────────
-        const securityGuard = getSecurityGuard();
+        const securityGuard = getSecurityGuard(requireWorkspaceRoot('shell_execute'));
         const confirmationManager = getConfirmationManager();
 
         const securityContext: SecurityContext = {
@@ -320,23 +285,7 @@ export async function execute(
         // The allowlist comes from MXF_SHELL_ALLOWED_COMMANDS, not from the tool
         // input. An allowlist passed as an argument is chosen by the model it is
         // meant to restrict, which makes it decorative.
-        if (hasShellAllowlist()) {
-            const allowedCommands = getShellAllowedCommands();
-            // Use the parser to extract the effective command, handling env
-            // prefixes (FOO=bar cmd) and wrappers (sudo cmd, timeout 5 cmd)
-            const effectiveCommands = extractEffectiveCommands(input.command);
-            for (const effectiveCmd of effectiveCommands) {
-                // extractEffectiveCommands yields the full command line; compare
-                // on the base binary so `git status` matches an allowlisted `git`.
-                const baseCommand = effectiveCmd.trim().split(/\s+/)[0];
-                if (!allowedCommands.includes(baseCommand)) {
-                    throw new Error(
-                        `Command '${baseCommand}' is not in the configured allowlist ` +
-                        `(MXF_SHELL_ALLOWED_COMMANDS). Allowed: ${allowedCommands.join(', ')}`
-                    );
-                }
-            }
-        }
+        assertCommandAllowlisted(input.command);
 
         // ── 7. Build command string and compute hash ───────────────────────
         const fullCommand = buildFullCommand(input.command, input.args);
@@ -382,22 +331,15 @@ export async function execute(
             // container with no network, a read-only root, dropped capabilities
             // and resource limits. If Docker is unavailable, executeInSandbox
             // throws — it never falls back to running on the host.
-            const result = isShellSandboxEnabled()
-                ? await executeInSandbox(
-                    fullCommand,
-                    { enabled: true },
-                    {
-                        timeout,
-                        workingDirectory: input.workingDirectory,
-                        environment: childEnv as Record<string, string>
-                    }
-                )
-                : await spawnCommand(
-                    fullCommand,
-                    input.workingDirectory || process.cwd(),
-                    childEnv,
-                    timeout
-                );
+            const result = await executeInSandbox(
+                fullCommand,
+                { enabled: true },
+                {
+                    timeout,
+                    workingDirectory,
+                    environment: childEnv as Record<string, string>
+                }
+            );
             stdout = result.stdout;
             stderr = result.stderr;
             exitCode = result.exitCode;

package/src/protocols/mcp/tools/shell/ShellSandbox.ts

@@ -38,11 +38,11 @@
  * silent fallback to host execution.
  */
 
-import * as path from 'path';
 import crypto from 'crypto';
 import Docker from 'dockerode';
 import { Logger } from '../../../../utils/Logger.js';
 import { ContainerExecutionManager } from '../../../../services/ContainerExecutionManager.js';
+import { resolveWorkspacePath } from '../../security/McpToolPolicy.js';
 
 const logger = new Logger('info', 'ShellSandbox', 'server');
 
@@ -155,6 +155,10 @@ export async function executeInSandbox(
         ...DEFAULT_SHELL_SANDBOX_CONFIG,
         ...config
     };
+    const workspaceDirectory = resolveWorkspacePath(
+        options.workingDirectory,
+        'ShellSandbox workingDirectory'
+    );
 
     // Verify Docker is available — fail fast, never fall back to host execution
     const available = await isSandboxAvailable();
@@ -176,7 +180,7 @@ export async function executeInSandbox(
     }
 
     // Build Docker volume mounts
-    const binds = buildBindMounts(mergedConfig, options.workingDirectory);
+    const binds = buildBindMounts(mergedConfig, workspaceDirectory);
 
     // Build environment variables for the container
     const envVars = options.environment
@@ -184,9 +188,7 @@ export async function executeInSandbox(
         : [];
 
     // Determine the working directory inside the container
-    const containerWorkDir = options.workingDirectory
-        ? mapHostPathToContainer(options.workingDirectory)
-        : '/workspace';
+    const containerWorkDir = '/workspace';
 
     const containerId = `mxf-shell-${Date.now()}-${crypto.randomUUID().slice(0, 8)}`;
     const timeout = options.timeout || 30000;
@@ -346,50 +348,30 @@ async function checkShellExecutorImageExists(): Promise<boolean> {
  */
 function buildBindMounts(
     config: ShellSandboxConfig,
-    workingDirectory?: string
+    workingDirectory: string
 ): string[] {
     const binds: string[] = [];
 
     // Mount the project directory (or working directory) as read-only at /workspace
-    const projectDir = workingDirectory || process.cwd();
+    const projectDir = resolveWorkspacePath(workingDirectory, 'ShellSandbox project mount');
     binds.push(`${projectDir}:/workspace:ro`);
 
     // Mount writable paths — each gets mounted at the same path inside the container
     for (const writablePath of config.writablePaths) {
-        binds.push(`${writablePath}:${writablePath}:rw`);
+        const hostPath = resolveWorkspacePath(writablePath, 'ShellSandbox writable mount');
+        binds.push(`${hostPath}:${hostPath}:rw`);
     }
 
     // Mount custom mount configurations
     for (const mount of config.mountPaths) {
         const mode = mount.readOnly ? 'ro' : 'rw';
-        binds.push(`${mount.host}:${mount.container}:${mode}`);
+        const hostPath = resolveWorkspacePath(mount.host, 'ShellSandbox custom mount');
+        binds.push(`${hostPath}:${mount.container}:${mode}`);
     }
 
     return binds;
 }
 
-/**
- * Map a host filesystem path to its corresponding container path.
- * The project root (process.cwd()) is mounted at /workspace, so subdirectories
- * are resolved as relative paths under /workspace.
- *
- * @param hostPath - The host filesystem path
- * @returns The corresponding path inside the container
- */
-function mapHostPathToContainer(hostPath: string): string {
-    const projectRoot = process.cwd();
-    const resolved = path.resolve(hostPath);
-
-    // If the host path is within the project root, compute relative path
-    if (resolved.startsWith(projectRoot)) {
-        const relative = resolved.substring(projectRoot.length);
-        return `/workspace${relative}`;
-    }
-
-    // Path is outside the project root — default to /workspace
-    return '/workspace';
-}
-
 /**
  * Collect stdout and stderr from a Docker container after it finishes.
  * Waits for the container to exit, then reads logs.

package/src/repositories/interfaces/IKnowledgeGraphRepository.ts

@@ -65,24 +65,26 @@ export interface IKnowledgeGraphRepository {
      * @param entityId - The entity ID
      * @returns The entity or null if not found
      */
-    getEntity(entityId: string): Promise<Entity | null>;
+    getEntity(entityId: string, channelId?: ChannelId): Promise<Entity | null>;
 
     /**
-     * Update an entity
+     * Update an entity inside its channel
      *
      * @param entityId - The entity ID
+     * @param channelId - Channel the entity must belong to
      * @param updates - Partial entity updates
-     * @returns The updated entity or null if not found
+     * @returns The updated entity, or null if no such entity exists in the channel
      */
-    updateEntity(entityId: string, updates: Partial<Entity>): Promise<Entity | null>;
+    updateEntity(entityId: string, channelId: ChannelId, updates: Partial<Entity>): Promise<Entity | null>;
 
     /**
-     * Delete an entity
+     * Delete an entity and its relationships inside its channel
      *
      * @param entityId - The entity ID
+     * @param channelId - Channel the entity must belong to
      * @returns true if deleted
      */
-    deleteEntity(entityId: string): Promise<boolean>;
+    deleteEntity(entityId: string, channelId: ChannelId): Promise<boolean>;
 
     /**
      * Find entities matching filters
@@ -138,7 +140,8 @@ export interface IKnowledgeGraphRepository {
      */
     mergeEntities(
         targetEntityId: string,
-        sourceEntityIds: string[]
+        sourceEntityIds: string[],
+        channelId?: ChannelId
     ): Promise<EntityMergeResult>;
 
     /**
@@ -174,24 +177,27 @@ export interface IKnowledgeGraphRepository {
     getRelationship(relationshipId: string): Promise<Relationship | null>;
 
     /**
-     * Update a relationship
+     * Update a relationship inside its channel
      *
      * @param relationshipId - The relationship ID
+     * @param channelId - Channel the relationship must belong to
      * @param updates - Partial relationship updates
-     * @returns The updated relationship or null if not found
+     * @returns The updated relationship, or null if no such relationship exists in the channel
      */
     updateRelationship(
         relationshipId: string,
+        channelId: ChannelId,
         updates: Partial<Relationship>
     ): Promise<Relationship | null>;
 
     /**
-     * Delete a relationship
+     * Delete a relationship inside its channel
      *
      * @param relationshipId - The relationship ID
+     * @param channelId - Channel the relationship must belong to
      * @returns true if deleted
      */
-    deleteRelationship(relationshipId: string): Promise<boolean>;
+    deleteRelationship(relationshipId: string, channelId: ChannelId): Promise<boolean>;
 
     /**
      * Get relationships between two entities
@@ -238,7 +244,8 @@ export interface IKnowledgeGraphRepository {
             entityType?: EntityType | EntityType[];
             maxDepth?: number;
             limit?: number;
-        }
+        },
+        channelId?: ChannelId
     ): Promise<{
         entities: Entity[];
         relationships: Relationship[];
@@ -255,7 +262,8 @@ export interface IKnowledgeGraphRepository {
     findPath(
         fromEntityId: string,
         toEntityId: string,
-        maxHops?: number
+        maxHops?: number,
+        channelId?: ChannelId
     ): Promise<GraphPath | null>;
 
     /**
@@ -271,7 +279,8 @@ export interface IKnowledgeGraphRepository {
         fromEntityId: string,
         toEntityId: string,
         maxHops?: number,
-        limit?: number
+        limit?: number,
+        channelId?: ChannelId
     ): Promise<GraphPath[]>;
 
     /**
@@ -294,7 +303,8 @@ export interface IKnowledgeGraphRepository {
     getSubgraph(
         entityId: string,
         depth?: number,
-        limit?: number
+        limit?: number,
+        channelId?: ChannelId
     ): Promise<{
         entities: Entity[];
         relationships: Relationship[];
@@ -333,25 +343,29 @@ export interface IKnowledgeGraphRepository {
     // ========================================================================
 
     /**
-     * Update entity Q-value
+     * Update entity Q-value inside its channel
      *
      * @param entityId - The entity ID
+     * @param channelId - Channel the entity must belong to
      * @param newQValue - The new Q-value
      * @param reason - Reason for update
-     * @returns Updated entity
+     * @returns Updated entity, or null if no such entity exists in the channel
      */
     updateEntityQValue(
         entityId: string,
+        channelId: ChannelId,
         newQValue: number,
         reason: string
     ): Promise<Entity | null>;
 
     /**
-     * Batch update Q-values
+     * Batch update Q-values for entities of one channel
      *
+     * @param channelId - Channel every entity must belong to
      * @param updates - Array of updates
      */
     batchUpdateQValues(
+        channelId: ChannelId,
         updates: Array<{
             entityId: string;
             qValue: number;
@@ -376,39 +390,43 @@ export interface IKnowledgeGraphRepository {
     ): Promise<Entity[]>;
 
     /**
-     * Increment retrieval count for entities
+     * Increment retrieval count for entities of one channel
      *
+     * @param channelId - Channel every entity must belong to
      * @param entityIds - Entity IDs to update
      */
-    incrementRetrievalCount(entityIds: string[]): Promise<void>;
+    incrementRetrievalCount(channelId: ChannelId, entityIds: string[]): Promise<void>;
 
     /**
-     * Record success/failure for entities (for Q-value learning)
+     * Record success/failure for entities of one channel (for Q-value learning)
      *
+     * @param channelId - Channel every entity must belong to
      * @param entityIds - Entity IDs
      * @param success - Whether outcome was successful
      */
-    recordOutcome(entityIds: string[], success: boolean): Promise<void>;
+    recordOutcome(channelId: ChannelId, entityIds: string[], success: boolean): Promise<void>;
 
     // ========================================================================
     // Batch Operations
     // ========================================================================
 
     /**
-     * Get multiple entities by their IDs in a single query
+     * Get multiple entities of one channel by their IDs in a single query
      *
+     * @param channelId - Channel every entity must belong to
      * @param entityIds - Array of entity IDs to fetch
-     * @returns Array of found entities (excludes missing IDs)
+     * @returns Array of found entities (excludes missing and foreign IDs)
      */
-    getEntitiesByIds(entityIds: string[]): Promise<Entity[]>;
+    getEntitiesByIds(channelId: ChannelId, entityIds: string[]): Promise<Entity[]>;
 
     /**
-     * Get all relationships where either endpoint is in the given entity IDs
+     * Get all relationships of one channel where either endpoint is in the given entity IDs
      *
+     * @param channelId - Channel every relationship must belong to
      * @param entityIds - Array of entity IDs to find relationships for
      * @returns Array of relationships involving the given entities
      */
-    getRelationshipsByEntityIds(entityIds: string[]): Promise<Relationship[]>;
+    getRelationshipsByEntityIds(channelId: ChannelId, entityIds: string[]): Promise<Relationship[]>;
 
     // ========================================================================
     // Context Operations

package/src/schemas/EventPayloadSchema.ts

@@ -84,6 +84,8 @@ import {
     PostCompactionRestoredPayload,
     CompactionSummaryGeneratedPayload,
 } from '../events/event-definitions/CompactionEvents.js';
+import { TaskEvents } from '../events/event-definitions/TaskEvents.js';
+import type { SdkReconnectedEventData } from '../events/event-definitions/SdkEvents.js';
 
 // Create logger instance for event payload schema
 const logger = new Logger('warn', 'EventPayloadSchema', 'server');
@@ -327,8 +329,12 @@ export type SubscriptionEventPayload = BaseEventPayload<SubscriptionEventData>;
  */
 export interface TaskEventData {
     taskId: string;
+    /** Correlates an asynchronous request with its authoritative server result. */
+    requestId?: string;
     fromAgentId?: AgentId; // Agent initiating the task (could be different from BaseEventPayload.agentId if event is relayed)
     toAgentId?: AgentId;   // Agent designated to perform the task
+    targetAgentId?: AgentId;
+    targetChannelId?: ChannelId;
     task: any;            // The task content/details — typing this union is the head of the SDK-API typing pass (15 sender contract drifts to reconcile)
 }
 export type TaskEventPayload = BaseEventPayload<TaskEventData>;
@@ -722,6 +728,39 @@ export function createAgentEventPayload(
     return createBaseEventPayload<AgentEventData>(eventType, agentId, channelId, agentData, options);
 }
 
+/**
+ * Channel id carried by SDK connection events. The SDK's user connection is
+ * not bound to a channel; payload validation still requires a non-empty id.
+ */
+export const SDK_CONNECTION_CHANNEL_ID: ChannelId = 'system';
+
+/**
+ * Creates the payload for SdkEvents.RECONNECTED.
+ *
+ * The SDK's user connection has no agent; the authenticated user id stands in
+ * the agentId slot, as the SDK's other user-level payloads do.
+ *
+ * @param eventType - SdkEvents.RECONNECTED.
+ * @param userId - Server-confirmed user id of the re-authenticated connection.
+ * @param data - Reconnect details.
+ * @param options - Optional base event payload options.
+ */
+export function createSdkReconnectedEventPayload(
+    eventType: EventName | string,
+    userId: string,
+    data: SdkReconnectedEventData,
+    options: { source?: string; eventId?: string; timestamp?: number; } = {}
+): BaseEventPayload<SdkReconnectedEventData> {
+    const validator = createStrictValidator('createSdkReconnectedEventPayload');
+    validator.assertIsNonEmptyString(data.userId, 'data.userId');
+    if (data.attempt !== null && (!Number.isInteger(data.attempt) || data.attempt < 0)) {
+        throw new Error('data.attempt must be a non-negative integer or null');
+    }
+    return createBaseEventPayload<SdkReconnectedEventData>(
+        eventType, userId, SDK_CONNECTION_CHANNEL_ID, data, options
+    );
+}
+
 /**
  * Creates an AllowedToolsUpdateEventPayload.
  * Used when dynamically changing an agent's allowed tools during runtime.
@@ -938,7 +977,10 @@ export function createTaskEventPayload<TData extends TaskEventData>(
     // Task content is either a plain instruction string (simple request flow)
     // or a creation-fields object — validate per shape.
     const task = taskData.task;
-    if (typeof task === 'string') {
+    if (eventType === TaskEvents.UPDATE_REQUEST) {
+        validator.assertIsObject(task, 'Task update content must be an object');
+        validator.assertIsNonEmptyString(task.taskId, 'Task update taskId is required');
+    } else if (typeof task === 'string') {
         validator.assertIsNonEmptyString(task, 'Task instruction must be a non-empty string');
     } else {
     validator.assertIsObject(task, 'Task content must be an object');
@@ -3105,6 +3147,7 @@ export interface MeilisearchIndexEventData {
     success: boolean;             // Whether indexing succeeded
     duration?: number;            // Time taken to index in milliseconds
     error?: string;               // Error message if indexing failed
+    retryAfterMs?: number;        // Set when the server throttled the request: retry after this delay
     metadata?: {                  // Additional context
         messageCount?: number;    // For batch operations
         agentId?: string;
@@ -3148,6 +3191,7 @@ export interface MeilisearchBackfillEventData {
     success: boolean;             // Whether backfill completed successfully
     source: 'mongodb' | 'memory' | 'other'; // Source of backfilled data
     error?: string;               // Error message if backfill failed
+    retryAfterMs?: number;        // Set when the server throttled the request: retry after this delay
     metadata?: {                  // Additional context
         agentId?: string;
         channelId?: string;