@modelprofile.com/mcp-crossharness 5.0.0

package/readme.md

@@ -0,0 +1,204 @@
+# @modelprofile.com/mcp-crossharness
+
+Connection-first MCP server for interacting with AI coding harness sessions through their explicit web-server APIs.
+
+## Issue Reporting and Security
+
+For reporting bugs, issues, or security vulnerabilities, please visit [community.foss.global/](https://community.foss.global/). This is the central community hub for all issue reporting. Developers who sign and comply with our contribution agreement and go through identification can also get a [code.foss.global/](https://code.foss.global/) account to submit Pull Requests directly.
+
+## Transport Contract
+
+Crossharness only talks to explicitly connected harness web servers:
+
+| Harness | Server transport | Support |
+| --- | --- | --- |
+| OpenCode | `http://` or `https://` | list, read, send, health |
+| Codex | `ws://` or `wss://` app-server | list, read, send, health |
+| Claude Code | none | rejected at connection time |
+
+There is no local session-store access, CLI invocation, process spawn, server discovery, auto-start, restart, or fallback. If a connection or request fails, the operation fails.
+
+Claude Code 2.1.219 does not expose a URL-addressable session server. Its CLI and Agent SDK are local process/library interfaces, so it cannot participate in this server-only contract yet.
+
+## Connection Flow
+
+Harness operations start with `connect_harness`:
+
+```text
+connect_harness {
+  harness: "opencode",
+  serverUrl: "http://127.0.0.1:4096",
+  directory: "/absolute/path/on/server"
+}
+```
+
+The result contains an opaque `connectionId`. Connection-scoped calls must reference it:
+
+```text
+list_connections     {}
+list_chats          { connectionId: "c-...", limit: 10 }
+read_chat           { connectionId: "c-...", chatId: "ses_..." }
+send_message        { connectionId: "c-...", chatId: "ses_...", message: "..." }
+send_message_async  { connectionId: "c-...", chatId: "ses_...", message: "..." }
+check_reply         { connectionId: "c-...", dispatchId: "d-..." }
+connection_status   { connectionId: "c-..." }
+disconnect_harness  { connectionId: "c-..." }
+```
+
+Connections and asynchronous dispatches live in the MCP process and do not survive a restart.
+
+If `disconnect_harness` cannot close the connection, it returns an error and retains that
+connection ID for a retry. Calling `disconnect_harness` again with the same ID retries cleanup.
+
+`send_message` defaults to a 300-second timeout and `send_message_async` to 900 seconds; both accept 1-3,600 seconds. `check_reply.waitSeconds` accepts 0-60 seconds. The send timeout covers connection-scoped validation, queueing, and the harness request. Codex timeout recovery can then take up to 3 seconds for interrupt acknowledgment and 3 seconds for terminal completion.
+
+Canceling a foreground `send_message` aborts its OpenCode request or safely interrupts its correlated Codex turn. Canceling `check_reply` stops only that wait. A `send_message_async` dispatch remains independent after its `dispatchId` is returned.
+
+The in-memory dispatch registry retains at most 100 records. Settled records expire after two hours and may be evicted earlier to admit new work; if all 100 records are active, a new asynchronous send is rejected before delivery starts.
+
+## Trusted Origins
+
+Agents must not be allowed to send harness credentials to arbitrary URLs. Configure exact approved origins before starting Crossharness:
+
+```bash
+export CROSSHARNESS_ALLOWED_SERVER_URLS="http://127.0.0.1:4096/,ws://127.0.0.1:4500/"
+```
+
+`connect_harness` rejects origins not in this comma-separated allowlist. URLs containing user info, query parameters, fragments, or non-root paths are also rejected. HTTP redirects are never followed. At most one connection may bind a given harness, origin, and directory in one MCP process; the registry accepts up to 32 connections.
+
+The standalone MCP server reads credentials from the harnesses' fixed environment variables. They are never accepted as tool arguments or printed:
+
+- OpenCode: required `OPENCODE_SERVER_PASSWORD` and optional `OPENCODE_SERVER_USERNAME`
+- Codex: `CODEX_REMOTE_TOKEN`
+
+For remote servers, use TLS: `https://` for OpenCode and `wss://` for Codex.
+
+## OpenCode
+
+Start an OpenCode server on a fixed URL:
+
+```bash
+OPENCODE_SERVER_PASSWORD="..." opencode serve --hostname 127.0.0.1 --port 4096
+```
+
+Crossharness uses only the official HTTP API:
+
+- `GET /global/health`
+- `GET /session`
+- `GET /session/:id`
+- `GET /session/:id/message`
+- `POST /session/:id/message`
+
+The connection directory is sent as a server-side query filter and verified against every selected session. Concurrent sends are passed directly to OpenCode; OpenCode owns session queuing. Crossharness does not intercept permissions and does not issue session-wide aborts. If a local HTTP wait times out, the server may still have queued or started the turn; Crossharness reports that uncertainty and never retries.
+
+## Codex
+
+Start a Codex app-server on an explicit WebSocket URL:
+
+```bash
+codex app-server --listen ws://127.0.0.1:4500
+```
+
+For remote listeners, configure Codex WebSocket authentication and use `wss://`. Crossharness sends `CODEX_REMOTE_TOKEN` as a bearer token.
+
+Each connection owns one initialized WebSocket and uses the official app-server JSON-RPC protocol:
+
+- `initialize` followed by `initialized`
+- `thread/list` with the connection directory as `cwd`
+- `thread/read` with `includeTurns`
+- `thread/resume`
+- `turn/start` and correlated turn/item notifications
+- `turn/interrupt` for a timed-out correlated turn
+
+Turns on different threads may run concurrently. Sends to the same thread are sequenced so notification identity remains unambiguous. Each connection permits at most 100 queued or active sends, with at most 10 for one thread; a queued send can time out before delivery. Approval and elicitation requests are conservatively declined; unsupported server requests receive a JSON-RPC method-not-supported error instead of hanging.
+
+If a Codex turn times out, Crossharness keeps the same-thread queue locked until `turn/interrupt` is acknowledged and `turn/completed` confirms terminal state. If the turn cannot be correlated, interruption is not acknowledged, or terminal state is not reported, the WebSocket connection is closed rather than risk overlapping turns or retrying an uncertain send.
+
+## Package Migration
+
+The package and executable were renamed for consistent `mcp-*` naming:
+
+| Previous | Replacement |
+| --- | --- |
+| `@modelprofile.com/crossharness-mcp` | `@modelprofile.com/mcp-crossharness` |
+| `crossharness-mcp` | `mcp-crossharness` |
+
+The previous package remains installable after deprecation, and existing lockfiles continue to resolve it. Update package references and MCP client commands explicitly; npm deprecation does not redirect imports or executables.
+
+## Install
+
+```bash
+pnpm add -g @modelprofile.com/mcp-crossharness
+
+# library use
+pnpm add @modelprofile.com/mcp-crossharness
+```
+
+Requires Node.js 24 or newer.
+
+Register the `mcp-crossharness` binary as a stdio MCP server in your client.
+
+## Library API
+
+```typescript
+import {
+  ConnectionRegistry,
+  DispatchRegistry,
+  CrossHarnessMcpServer,
+} from '@modelprofile.com/mcp-crossharness';
+
+const connections = new ConnectionRegistry({
+  allowedServerUrls: ['http://127.0.0.1:4096/'],
+  openCodeCredentials: {
+    serverUrl: 'http://127.0.0.1:4096/',
+    username: 'opencode',
+    password: controllerOwnedPassword,
+  },
+});
+
+const connection = await connections.connect(
+  'opencode',
+  'http://127.0.0.1:4096/',
+  '/absolute/path/on/server',
+);
+
+const chats = await connections.get(connection.connectionId).listChats(10);
+await connections.disconnect(connection.connectionId);
+```
+
+Connection closure is fail-closed and retryable. `disconnect()` retains ownership when a close
+fails, and another call with the same connection ID retries it. Overlapping close requests share
+the active close attempt. `closeAll()` permanently closes the registry to new connections, waits
+for every current close attempt, and retains failed connections for a later `closeAll()` retry. A
+single failure is rethrown directly; multiple failures are reported as an `AggregateError`.
+
+`openCodeCredentials` is intended for an embedding application that owns the
+OpenCode server credential. The registry validates and copies it during
+construction. An injected password bypasses the environment credentials; an
+omitted username uses the protocol default `opencode`. Injected credentials are
+bound to their exact `serverUrl`, never included in connection metadata, and
+redacted from OpenCode HTTP response errors. Plain HTTP injection is accepted
+only for loopback hosts; use HTTPS for remote OpenCode servers. The standalone
+MCP server continues to read its credentials from fixed environment variables;
+credentials are never accepted as tool arguments.
+
+## License and Legal Information
+
+This repository contains open-source code licensed under the MIT License. A copy of the license can be found in the repository license file.
+
+**Please note:** The MIT License does not grant permission to use the trade names, trademarks, service marks, or product names of the project, except as required for reasonable and customary use in describing the origin of the work and reproducing the content of the NOTICE file.
+
+### Trademarks
+
+This project is owned and maintained by Task Venture Capital GmbH. The names and logos associated with Task Venture Capital GmbH and any related products or services are trademarks of Task Venture Capital GmbH or third parties, and are not included within the scope of the MIT license granted herein.
+
+Use of these trademarks must comply with Task Venture Capital GmbH's Trademark Guidelines or the guidelines of the respective third-party owners, and any usage must be approved in writing. Third-party trademarks used herein are the property of their respective owners and used only in a descriptive manner, e.g. for an implementation of an API or similar.
+
+### Company Information
+
+Task Venture Capital GmbH<br>
+Registered at District Court Bremen HRB 35230 HB, Germany
+
+For any legal inquiries or further information, please contact us via email at hello@task.vc.
+
+By using this repository, you acknowledge that you have read this section, agree to comply with its terms, and understand that the licensing of the code does not imply endorsement by Task Venture Capital GmbH of any derivative works.

package/ts/00_commitinfo_data.ts

@@ -0,0 +1,8 @@
+/**
+ * autocreated commitinfo by @push.rocks/commitinfo
+ */
+export const commitinfo = {
+  name: '@modelprofile.com/mcp-crossharness',
+  version: '5.0.0',
+  description: 'Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers'
+}