@modelprofile.com/mcp-crossharness 5.0.0 → 5.2.0

package/ts/classes.mcptoolregistrar.ts

@@ -0,0 +1,345 @@
+import * as plugins from './plugins.js';
+import type * as interfaces from './interfaces.js';
+import { ConnectionRegistry } from './classes.connectionregistry.js';
+import { DispatchRegistry } from './classes.dispatchregistry.js';
+
+const harnessNameSchema = plugins.z.enum(['claudecode', 'opencode', 'codex']);
+
+/**
+ * Registers the Crossharness tool surface on an externally owned MCP server and
+ * owns only the resources used by those tools.
+ */
+export class CrossHarnessMcpToolRegistrar {
+  public readonly connections: ConnectionRegistry;
+  public readonly dispatches: DispatchRegistry;
+  private registeredTools: plugins.RegisteredTool[] = [];
+  private registeredServer: InstanceType<typeof plugins.McpServer> | undefined;
+  private registered = false;
+  private closeStarted = false;
+  private closePromise: Promise<void> | undefined;
+  private resourceShutdownPromise: Promise<void> | undefined;
+
+  constructor(connectionsArg = new ConnectionRegistry(), dispatchesArg = new DispatchRegistry()) {
+    this.connections = connectionsArg;
+    this.dispatches = dispatchesArg;
+  }
+
+  /** Register the tool surface before the externally owned MCP server connects. */
+  public register(serverArg: InstanceType<typeof plugins.McpServer>): void {
+    if (this.closeStarted) {
+      throw new Error('Crossharness MCP tool registrar is closed');
+    }
+    if (this.registered) {
+      throw new Error('Crossharness MCP tools are already registered');
+    }
+    if (serverArg.isConnected()) {
+      throw new Error('Crossharness MCP tools must be registered before the MCP server connects');
+    }
+
+    const registeredTools: plugins.RegisteredTool[] = [];
+    try {
+      registeredTools.push(serverArg.registerTool(
+        'connect_harness',
+        {
+          title: 'Connect to harness server',
+          description:
+            'Establish an explicit connection to an allowlisted harness web server. The exact origin must be listed in CROSSHARNESS_ALLOWED_SERVER_URLS. OpenCode uses http(s), Codex uses ws(s), and Claude Code is rejected because it exposes no URL-addressable session server. Returns a connectionId required by every connection-scoped operation; list_connections remains global.',
+          inputSchema: {
+            harness: harnessNameSchema,
+            serverUrl: plugins.z.string().max(2048).url().describe('Allowlisted harness server origin'),
+            directory: plugins.z
+              .string()
+              .max(4096)
+              .startsWith('/')
+              .describe('Absolute project directory on the harness server'),
+          },
+        },
+        async (args, extra) =>
+          this.wrapToolCall(async () => {
+            const info = await this.connections.connect(
+              args.harness as interfaces.THarnessName,
+              args.serverUrl,
+              args.directory,
+              extra.signal,
+            );
+            return this.describeConnection(info);
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'disconnect_harness',
+        {
+          title: 'Disconnect harness server',
+          description:
+            'Close and remove an established harness connection. In-flight requests fail; async dispatch records remain inspectable with check_reply.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+          },
+        },
+        async (args) =>
+          this.wrapToolCall(async () =>
+            this.describeConnection(await this.connections.disconnect(args.connectionId)),
+          ),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'list_connections',
+        {
+          title: 'List harness connections',
+          description: 'List explicit harness web-server connections established in this MCP process.',
+          inputSchema: {},
+        },
+        async () =>
+          this.wrapToolCall(async () => {
+            const connections = this.connections.list();
+            return connections.length > 0
+              ? connections.map((connection) => this.describeConnection(connection)).join('\n\n')
+              : 'No harness server connections established.';
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'connection_status',
+        {
+          title: 'Check harness connection',
+          description: 'Run the protocol health check for one explicit harness server connection.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+          },
+        },
+        async (args) =>
+          this.wrapToolCall(async () => {
+            const status = await this.connections.get(args.connectionId).getStatus();
+            return `${this.describeConnection(status)}\nhealthy: ${status.healthy ? 'yes' : 'no'}\ndetail: ${status.detail}`;
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'list_chats',
+        {
+          title: 'List harness chats',
+          description:
+            'List chats from the server and directory bound to an explicit connection. No local session stores are read.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+            limit: plugins.z.number().int().min(1).max(100).optional(),
+          },
+        },
+        async (args) =>
+          this.wrapToolCall(async () => {
+            const chats = await this.connections.get(args.connectionId).listChats(args.limit ?? 10);
+            if (chats.length === 0) return 'No chats found for this connection.';
+            return [
+              'harness\tchatId\tupdatedAt\tactivity\ttitle',
+              ...chats.map(
+                (chat) =>
+                  `${chat.harness}\t${chat.chatId}\t${chat.updatedAt}\t${chat.isActive ? 'active' : 'idle'}\t${chat.title.replace(/\s+/g, ' ').slice(0, 120)}`,
+              ),
+            ].join('\n');
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'read_chat',
+        {
+          title: 'Read harness chat',
+          description:
+            'Read a chat through the harness web server bound to an explicit connection.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+            chatId: plugins.z.string().min(1).max(1024),
+            limit: plugins.z.number().int().min(1).max(500).optional(),
+            maxChars: plugins.z.number().int().min(200).max(50000).optional(),
+          },
+        },
+        async (args) =>
+          this.wrapToolCall(async () => {
+            const transcript = await this.connections
+              .get(args.connectionId)
+              .readChat(args.chatId, args.limit ?? 20, args.maxChars ?? 2000);
+            const header = [
+              `harness: ${transcript.harness}`,
+              `chatId: ${transcript.chatId}`,
+              `title: ${transcript.title}`,
+              `directory: ${transcript.directory}`,
+              transcript.totalMessages === undefined
+                ? `messages: showing ${transcript.messages.length}; server total unavailable`
+                : `messages: showing ${transcript.messages.length} of ${transcript.totalMessages}`,
+            ].join('\n');
+            const body = transcript.messages
+              .map(
+                (message) =>
+                  `-- [${message.role}]${message.timestamp ? ` ${message.timestamp}` : ''}\n${message.text}`,
+              )
+              .join('\n');
+            return `${header}\n\n${body}`;
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'send_message',
+        {
+          title: 'Send message through harness server',
+          description:
+            'Send a message only through the harness web server bound to an explicit connection and wait for the reply. There is no CLI, process, local-store, discovery, or retry fallback.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+            chatId: plugins.z.string().min(1).max(1024),
+            message: plugins.z.string().min(1).max(1024 * 1024),
+            timeoutSeconds: plugins.z.number().int().min(1).max(3600).optional(),
+          },
+        },
+        async (args, extra) =>
+          this.wrapToolCall(async () => {
+            const result = await this.connections
+              .get(args.connectionId)
+              .sendMessage(args.chatId, args.message, args.timeoutSeconds ?? 300, extra.signal);
+            return `${result.reply}\n\n[crossharness transport: ${result.via}]`;
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'send_message_async',
+        {
+          title: 'Send message through harness server asynchronously',
+          description:
+            'Start a server-only send and return a dispatchId immediately. Both this connectionId and the dispatchId are required by check_reply.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id returned by connect_harness'),
+            chatId: plugins.z.string().min(1).max(1024),
+            message: plugins.z.string().min(1).max(1024 * 1024),
+            timeoutSeconds: plugins.z.number().int().min(1).max(3600).optional(),
+          },
+        },
+        async (args) =>
+          this.wrapToolCall(async () => {
+            const connection = this.connections.get(args.connectionId);
+            const record = this.dispatches.track(
+              args.connectionId,
+              connection.harness,
+              args.chatId,
+              () => connection.sendMessage(args.chatId, args.message, args.timeoutSeconds ?? 900),
+            );
+            return [
+              `connectionId: ${record.connectionId}`,
+              `dispatchId: ${record.dispatchId}`,
+              `harness: ${record.harness}`,
+              `chatId: ${record.chatId}`,
+              `startedAt: ${record.startedAt}`,
+            ].join('\n');
+          }),
+      ));
+
+      registeredTools.push(serverArg.registerTool(
+        'check_reply',
+        {
+          title: 'Check async server send',
+          description:
+            'Check an asynchronous send. The connectionId must own the dispatch. Records remain inspectable after disconnect.',
+          inputSchema: {
+            connectionId: plugins.z.string().max(128).describe('Connection id used for send_message_async'),
+            dispatchId: plugins.z.string().max(128).describe('Dispatch id returned by send_message_async'),
+            waitSeconds: plugins.z.number().int().min(0).max(60).optional(),
+          },
+        },
+        async (args, extra) =>
+          this.wrapToolCall(async () => {
+            const record = await this.dispatches.waitFor(
+              args.connectionId,
+              args.dispatchId,
+              (args.waitSeconds ?? 0) * 1000,
+              extra.signal,
+            );
+            if (!record) throw new Error('unknown dispatchId for this connectionId');
+            const header = [
+              `connectionId: ${record.connectionId}`,
+              `dispatchId: ${record.dispatchId}`,
+              `status: ${record.status}`,
+              `harness: ${record.harness}`,
+              `chatId: ${record.chatId}`,
+              `startedAt: ${record.startedAt}`,
+              ...(record.completedAt ? [`completedAt: ${record.completedAt}`] : []),
+            ].join('\n');
+            if (record.status === 'working') return `${header}\n\nStill working.`;
+            if (record.status === 'failed') return `${header}\n\nError: ${record.error}`;
+            return `${header}\n\n${record.reply}\n\n[crossharness transport: ${record.via}]`;
+          }),
+      ));
+    } catch (errorArg) {
+      for (const registeredTool of registeredTools.reverse()) registeredTool.remove();
+      throw errorArg;
+    }
+
+    this.registeredTools = registeredTools;
+    this.registeredServer = serverArg;
+    this.registered = true;
+  }
+
+  /** Close the externally owned MCP server before closing this registrar. */
+  public async close(): Promise<void> {
+    if (this.closePromise) return this.closePromise;
+    if (this.registeredServer?.isConnected()) {
+      throw new Error(
+        'Crossharness MCP tool registrar cannot close while its MCP server is connected; close the shared MCP server first',
+      );
+    }
+    this.closeStarted = true;
+    this.removeRegisteredTools();
+    this.registeredServer = undefined;
+    this.closePromise = this.ensureResourceShutdown().finally(() => {
+      this.closePromise = undefined;
+    });
+    return this.closePromise;
+  }
+
+  private removeRegisteredTools(): void {
+    for (const registeredTool of this.registeredTools.reverse()) registeredTool.remove();
+    this.registeredTools = [];
+  }
+
+  private ensureResourceShutdown(): Promise<void> {
+    if (this.resourceShutdownPromise) return this.resourceShutdownPromise;
+    let shutdownPromise!: Promise<void>;
+    shutdownPromise = this.connections.closeAll().finally(() => {
+      this.dispatches.dispose();
+    }).catch((errorArg) => {
+      if (this.resourceShutdownPromise === shutdownPromise) {
+        this.resourceShutdownPromise = undefined;
+      }
+      throw errorArg;
+    });
+    this.resourceShutdownPromise = shutdownPromise;
+    return shutdownPromise;
+  }
+
+  private describeConnection(infoArg: interfaces.IConnectionInfo): string {
+    return [
+      `connectionId: ${infoArg.connectionId}`,
+      `harness: ${infoArg.harness}`,
+      `serverUrl: ${infoArg.serverUrl}`,
+      `directory: ${infoArg.directory}`,
+      `state: ${infoArg.state}`,
+      `connectedAt: ${infoArg.connectedAt}`,
+      ...(infoArg.serverVersion ? [`serverVersion: ${infoArg.serverVersion}`] : []),
+    ].join('\n');
+  }
+
+  private async wrapToolCall(
+    handlerArg: () => Promise<string>,
+  ): Promise<{ content: Array<{ type: 'text'; text: string }>; isError?: boolean }> {
+    try {
+      const text = await handlerArg();
+      return { content: [{ type: 'text', text: text.slice(0, 100000) }] };
+    } catch (error) {
+      return {
+        content: [
+          {
+            type: 'text',
+            text: `Error: ${error instanceof Error ? error.message : String(error)}`.slice(0, 100000),
+          },
+        ],
+        isError: true,
+      };
+    }
+  }
+}

package/ts/index.ts

@@ -1,6 +1,8 @@
 export * from './interfaces.js';
+export * from './classes.codexappserverclient.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
+export * from './classes.mcptoolregistrar.js';
 export * from './classes.mcpserver.js';
 
 import { CrossHarnessMcpServer } from './classes.mcpserver.js';

package/ts/plugins.ts

@@ -9,6 +9,7 @@ export type { AddressInfo };
 
 // Third-party modules
 import { McpServer } from '@modelcontextprotocol/sdk/server/mcp.js';
+import type { RegisteredTool } from '@modelcontextprotocol/sdk/server/mcp.js';
 import { StdioServerTransport } from '@modelcontextprotocol/sdk/server/stdio.js';
 import { Client as McpClient } from '@modelcontextprotocol/sdk/client/index.js';
 import { InMemoryTransport } from '@modelcontextprotocol/sdk/inMemory.js';
@@ -27,4 +28,5 @@ export {
   z,
 };
 export type { RawData };
+export type { RegisteredTool };
 export type { Transport };