@modelprofile.com/mcp-crossharness 5.5.0 → 5.6.0

package/dist_ts/00_commitinfo_data.js

@@ -3,7 +3,7 @@
  */
 export const commitinfo = {
     name: '@modelprofile.com/mcp-crossharness',
-    version: '5.5.0',
+    version: '5.6.0',
     description: 'Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers'
 };
 //# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiMDBfY29tbWl0aW5mb19kYXRhLmpzIiwic291cmNlUm9vdCI6IiIsInNvdXJjZXMiOlsiLi4vdHMvMDBfY29tbWl0aW5mb19kYXRhLnRzIl0sIm5hbWVzIjpbXSwibWFwcGluZ3MiOiJBQUFBOztHQUVHO0FBQ0gsTUFBTSxDQUFDLE1BQU0sVUFBVSxHQUFHO0lBQ3hCLElBQUksRUFBRSxvQ0FBb0M7SUFDMUMsT0FBTyxFQUFFLE9BQU87SUFDaEIsV0FBVyxFQUFFLDRGQUE0RjtDQUMxRyxDQUFBIn0=

package/dist_ts/functions.codexversion.d.ts

@@ -0,0 +1,39 @@
+/**
+ * The first Codex release whose `app-server --listen unix://PATH` publishes the alias
+ * `codexUnixSocketTarget` and `observeCodexUnixSocket` verify. Earlier releases bind PATH
+ * directly, which this package refuses, so a consumer that relies on that contract refuses
+ * them up front, by version.
+ */
+export declare const CODEX_UNIX_SOCKET_MINIMUM_VERSION = "0.156.0";
+/** A Codex release number as Codex prints it: `MAJOR.MINOR.PATCH` with an optional prerelease. */
+export interface ICodexVersion {
+    major: number;
+    minor: number;
+    patch: number;
+    /** The prerelease after `-`, such as `alpha.2`, or null for a release. */
+    prerelease: string | null;
+    /** The exact text that was parsed. */
+    text: string;
+}
+/** `unreadable`: not a Codex release number. `below_minimum`: older than the required release. */
+export type TCodexVersionUnsupportedReason = 'unreadable' | 'below_minimum';
+/** A Codex whose version cannot be read, or is older than the release a consumer requires. */
+export declare class CodexVersionUnsupportedError extends Error {
+    readonly reason: TCodexVersionUnsupportedReason;
+    /** The version text that was checked; null when none was reported. */
+    readonly version: string | null;
+    readonly minimum: string;
+    constructor(reasonArg: TCodexVersionUnsupportedReason, versionArg: string | null, minimumArg: string);
+}
+/**
+ * Parses exactly one Codex release number, such as `0.157.1` or `0.158.0-alpha.2`. Anything else
+ * returns null: a prefix such as `codex-cli `, surrounding whitespace, build metadata, leading
+ * zeros or components beyond the safe integer range.
+ */
+export declare const parseCodexVersion: (textArg: string) => ICodexVersion | null;
+/**
+ * Returns the parsed version when it is `minimumArg` or newer, and throws
+ * `CodexVersionUnsupportedError` otherwise. A prerelease of a newer release is accepted; a
+ * prerelease of the minimum itself is older than the minimum. The minimum must be a release.
+ */
+export declare const requireCodexVersion: (versionArg: string | null | undefined, minimumArg?: string) => ICodexVersion;

package/dist_ts/functions.codexversion.js

@@ -0,0 +1,70 @@
+/**
+ * The first Codex release whose `app-server --listen unix://PATH` publishes the alias
+ * `codexUnixSocketTarget` and `observeCodexUnixSocket` verify. Earlier releases bind PATH
+ * directly, which this package refuses, so a consumer that relies on that contract refuses
+ * them up front, by version.
+ */
+export const CODEX_UNIX_SOCKET_MINIMUM_VERSION = '0.156.0';
+/** A Codex whose version cannot be read, or is older than the release a consumer requires. */
+export class CodexVersionUnsupportedError extends Error {
+    reason;
+    /** The version text that was checked; null when none was reported. */
+    version;
+    minimum;
+    constructor(reasonArg, versionArg, minimumArg) {
+        super(reasonArg === 'unreadable'
+            ? `Codex did not report a readable version; Codex ${minimumArg} or newer is required`
+            : `Codex ${versionArg} is older than the required Codex ${minimumArg}`);
+        this.name = 'CodexVersionUnsupportedError';
+        this.reason = reasonArg;
+        this.version = versionArg;
+        this.minimum = minimumArg;
+    }
+}
+const maximumVersionLength = 64;
+const numericPart = '(0|[1-9]\\d*)';
+const prereleasePart = '(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)';
+const versionPattern = new RegExp(`^${numericPart}\\.${numericPart}\\.${numericPart}(?:-(${prereleasePart}(?:\\.${prereleasePart})*))?$`);
+/**
+ * Parses exactly one Codex release number, such as `0.157.1` or `0.158.0-alpha.2`. Anything else
+ * returns null: a prefix such as `codex-cli `, surrounding whitespace, build metadata, leading
+ * zeros or components beyond the safe integer range.
+ */
+export const parseCodexVersion = (textArg) => {
+    if (typeof textArg !== 'string' || textArg.length > maximumVersionLength)
+        return null;
+    const match = versionPattern.exec(textArg);
+    if (!match)
+        return null;
+    const [major, minor, patch] = [match[1], match[2], match[3]].map(Number);
+    if (![major, minor, patch].every(Number.isSafeInteger))
+        return null;
+    return { major, minor, patch, prerelease: match[4] ?? null, text: textArg };
+};
+/** Orders by release number; a prerelease precedes the release of the same number. */
+const isBelow = (versionArg, minimumArg) => {
+    for (const key of ['major', 'minor', 'patch']) {
+        if (versionArg[key] !== minimumArg[key])
+            return versionArg[key] < minimumArg[key];
+    }
+    return versionArg.prerelease !== null;
+};
+/**
+ * Returns the parsed version when it is `minimumArg` or newer, and throws
+ * `CodexVersionUnsupportedError` otherwise. A prerelease of a newer release is accepted; a
+ * prerelease of the minimum itself is older than the minimum. The minimum must be a release.
+ */
+export const requireCodexVersion = (versionArg, minimumArg = CODEX_UNIX_SOCKET_MINIMUM_VERSION) => {
+    const minimum = parseCodexVersion(minimumArg);
+    if (!minimum || minimum.prerelease !== null) {
+        throw new Error('Codex minimum version must be a release number such as 0.156.0');
+    }
+    const reported = typeof versionArg === 'string' ? versionArg : null;
+    const version = reported === null ? null : parseCodexVersion(reported);
+    if (!version)
+        throw new CodexVersionUnsupportedError('unreadable', reported, minimumArg);
+    if (isBelow(version, minimum))
+        throw new CodexVersionUnsupportedError('below_minimum', reported, minimumArg);
+    return version;
+};
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiZnVuY3Rpb25zLmNvZGV4dmVyc2lvbi5qcyIsInNvdXJjZVJvb3QiOiIiLCJzb3VyY2VzIjpbIi4uL3RzL2Z1bmN0aW9ucy5jb2RleHZlcnNpb24udHMiXSwibmFtZXMiOltdLCJtYXBwaW5ncyI6IkFBQUE7Ozs7O0dBS0c7QUFDSCxNQUFNLENBQUMsTUFBTSxpQ0FBaUMsR0FBRyxTQUFTLENBQUM7QUFnQjNELDhGQUE4RjtBQUM5RixNQUFNLE9BQU8sNEJBQTZCLFNBQVEsS0FBSztJQUNyQyxNQUFNLENBQWlDO0lBQ3ZELHNFQUFzRTtJQUN0RCxPQUFPLENBQWdCO0lBQ3ZCLE9BQU8sQ0FBUztJQUVoQyxZQUFZLFNBQXlDLEVBQUUsVUFBeUIsRUFBRSxVQUFrQjtRQUNsRyxLQUFLLENBQUMsU0FBUyxLQUFLLFlBQVk7WUFDOUIsQ0FBQyxDQUFDLGtEQUFrRCxVQUFVLHVCQUF1QjtZQUNyRixDQUFDLENBQUMsU0FBUyxVQUFVLHFDQUFxQyxVQUFVLEVBQUUsQ0FBQyxDQUFDO1FBQzFFLElBQUksQ0FBQyxJQUFJLEdBQUcsOEJBQThCLENBQUM7UUFDM0MsSUFBSSxDQUFDLE1BQU0sR0FBRyxTQUFTLENBQUM7UUFDeEIsSUFBSSxDQUFDLE9BQU8sR0FBRyxVQUFVLENBQUM7UUFDMUIsSUFBSSxDQUFDLE9BQU8sR0FBRyxVQUFVLENBQUM7SUFDNUIsQ0FBQztDQUNGO0FBRUQsTUFBTSxvQkFBb0IsR0FBRyxFQUFFLENBQUM7QUFDaEMsTUFBTSxXQUFXLEdBQUcsZUFBZSxDQUFDO0FBQ3BDLE1BQU0sY0FBYyxHQUFHLDRDQUE0QyxDQUFDO0FBQ3BFLE1BQU0sY0FBYyxHQUFHLElBQUksTUFBTSxDQUMvQixJQUFJLFdBQVcsTUFBTSxXQUFXLE1BQU0sV0FBVyxRQUFRLGNBQWMsU0FBUyxjQUFjLFFBQVEsQ0FDdkcsQ0FBQztBQUVGOzs7O0dBSUc7QUFDSCxNQUFNLENBQUMsTUFBTSxpQkFBaUIsR0FBRyxDQUFDLE9BQWUsRUFBd0IsRUFBRTtJQUN6RSxJQUFJLE9BQU8s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

package/dist_ts/index.d.ts

@@ -1,6 +1,7 @@
 export * from './interfaces.js';
 export * from './classes.codexappserverclient.js';
 export * from './functions.codexunixsocket.js';
+export * from './functions.codexversion.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
 export * from './classes.mcptoolregistrar.js';

package/dist_ts/index.js

@@ -1,6 +1,7 @@
 export * from './interfaces.js';
 export * from './classes.codexappserverclient.js';
 export * from './functions.codexunixsocket.js';
+export * from './functions.codexversion.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
 export * from './classes.mcptoolregistrar.js';
@@ -9,4 +10,4 @@ import { CrossHarnessMcpServer } from './classes.mcpserver.js';
 export const runCli = async () => {
     await new CrossHarnessMcpServer().start();
 };
-//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsbUNBQW1DLENBQUM7QUFDbEQsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLGlDQUFpQyxDQUFDO0FBQ2hELGNBQWMsK0JBQStCLENBQUM7QUFDOUMsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLHdCQUF3QixDQUFDO0FBRXZDLE9BQU8sRUFBRSxxQkFBcUIsRUFBRSxNQUFNLHdCQUF3QixDQUFDO0FBRS9ELE1BQU0sQ0FBQyxNQUFNLE1BQU0sR0FBRyxLQUFLLElBQW1CLEVBQUU7SUFDOUMsTUFBTSxJQUFJLHFCQUFxQixFQUFFLENBQUMsS0FBSyxFQUFFLENBQUM7QUFDNUMsQ0FBQyxDQUFDIn0=
+//# sourceMappingURL=data:application/json;base64,eyJ2ZXJzaW9uIjozLCJmaWxlIjoiaW5kZXguanMiLCJzb3VyY2VSb290IjoiIiwic291cmNlcyI6WyIuLi90cy9pbmRleC50cyJdLCJuYW1lcyI6W10sIm1hcHBpbmdzIjoiQUFBQSxjQUFjLGlCQUFpQixDQUFDO0FBQ2hDLGNBQWMsbUNBQW1DLENBQUM7QUFDbEQsY0FBYyxnQ0FBZ0MsQ0FBQztBQUMvQyxjQUFjLDZCQUE2QixDQUFDO0FBQzVDLGNBQWMsaUNBQWlDLENBQUM7QUFDaEQsY0FBYywrQkFBK0IsQ0FBQztBQUM5QyxjQUFjLCtCQUErQixDQUFDO0FBQzlDLGNBQWMsd0JBQXdCLENBQUM7QUFFdkMsT0FBTyxFQUFFLHFCQUFxQixFQUFFLE1BQU0sd0JBQXdCLENBQUM7QUFFL0QsTUFBTSxDQUFDLE1BQU0sTUFBTSxHQUFHLEtBQUssSUFBbUIsRUFBRTtJQUM5QyxNQUFNLElBQUkscUJBQXFCLEVBQUUsQ0FBQyxLQUFLLEVBQUUsQ0FBQztBQUM1QyxDQUFDLENBQUMifQ==

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@modelprofile.com/mcp-crossharness",
-  "version": "5.5.0",
+  "version": "5.6.0",
   "private": false,
   "description": "Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers",
   "main": "dist_ts/index.js",
@@ -25,8 +25,8 @@
   "devDependencies": {
     "@git.zone/tsbuild": "^5.0.0",
     "@git.zone/tsrun": "^3.0.0",
-    "@git.zone/tstest": "^6.2.1",
-    "@types/node": "^26.6.1",
+    "@git.zone/tstest": "^6.3.0",
+    "@types/node": "^26.6.2",
     "@types/ws": "^8.18.1"
   },
   "dependencies": {

package/readme.md

@@ -247,6 +247,38 @@ plain `Error`s with these exact messages:
 
 Filesystem errors other than a missing path propagate unchanged.
 
+### Codex version floor
+
+A consumer that relies on the alias contract refuses an older Codex by version before it
+starts one. `CODEX_UNIX_SOCKET_MINIMUM_VERSION` is `'0.156.0'`, the first release that
+publishes the alias, and `requireCodexVersion` checks a version against it:
+
+```typescript
+import { CodexVersionUnsupportedError, requireCodexVersion } from '@modelprofile.com/mcp-crossharness';
+
+await client.connect();
+requireCodexVersion(client.serverVersion); // throws CodexVersionUnsupportedError below 0.156.0
+```
+
+`parseCodexVersion(text)` reads exactly one release number, `MAJOR.MINOR.PATCH` with an
+optional prerelease such as `0.158.0-alpha.2`, and returns `{ major, minor, patch, prerelease, text }`,
+or `null` for anything else: a prefix such as `codex-cli `, surrounding whitespace, build
+metadata, leading zeros or a component beyond the safe integer range. Strip Codex's own
+prefix before parsing.
+
+`requireCodexVersion(version, minimum?)` returns the parsed version when it is the minimum or
+newer. The minimum defaults to `CODEX_UNIX_SOCKET_MINIMUM_VERSION`; a consumer that needs a
+later release for its own reasons passes that release, which must be a release number and not
+a prerelease. A prerelease of a newer release is accepted; a prerelease of the minimum itself
+is older than the minimum. Otherwise it throws `CodexVersionUnsupportedError`, whose `reason`
+is `'unreadable'` (no version, or not a release number) or `'below_minimum'`, with the checked
+`version` (null when none was reported) and the `minimum`:
+
+| Message | Reason |
+| --- | --- |
+| `Codex did not report a readable version; Codex <minimum> or newer is required` | `unreadable` |
+| `Codex <version> is older than the required Codex <minimum>` | `below_minimum` |
+
 ### Composable tool registration
 
 `CrossHarnessMcpToolRegistrar` registers the same nine Crossharness tools used by the standalone

package/ts/00_commitinfo_data.ts

@@ -3,6 +3,6 @@
  */
 export const commitinfo = {
   name: '@modelprofile.com/mcp-crossharness',
-  version: '5.5.0',
+  version: '5.6.0',
   description: 'Connection-first MCP server for explicit OpenCode HTTP and Codex WebSocket session servers'
 }

package/ts/functions.codexversion.ts

@@ -0,0 +1,88 @@
+/**
+ * The first Codex release whose `app-server --listen unix://PATH` publishes the alias
+ * `codexUnixSocketTarget` and `observeCodexUnixSocket` verify. Earlier releases bind PATH
+ * directly, which this package refuses, so a consumer that relies on that contract refuses
+ * them up front, by version.
+ */
+export const CODEX_UNIX_SOCKET_MINIMUM_VERSION = '0.156.0';
+
+/** A Codex release number as Codex prints it: `MAJOR.MINOR.PATCH` with an optional prerelease. */
+export interface ICodexVersion {
+  major: number;
+  minor: number;
+  patch: number;
+  /** The prerelease after `-`, such as `alpha.2`, or null for a release. */
+  prerelease: string | null;
+  /** The exact text that was parsed. */
+  text: string;
+}
+
+/** `unreadable`: not a Codex release number. `below_minimum`: older than the required release. */
+export type TCodexVersionUnsupportedReason = 'unreadable' | 'below_minimum';
+
+/** A Codex whose version cannot be read, or is older than the release a consumer requires. */
+export class CodexVersionUnsupportedError extends Error {
+  public readonly reason: TCodexVersionUnsupportedReason;
+  /** The version text that was checked; null when none was reported. */
+  public readonly version: string | null;
+  public readonly minimum: string;
+
+  constructor(reasonArg: TCodexVersionUnsupportedReason, versionArg: string | null, minimumArg: string) {
+    super(reasonArg === 'unreadable'
+      ? `Codex did not report a readable version; Codex ${minimumArg} or newer is required`
+      : `Codex ${versionArg} is older than the required Codex ${minimumArg}`);
+    this.name = 'CodexVersionUnsupportedError';
+    this.reason = reasonArg;
+    this.version = versionArg;
+    this.minimum = minimumArg;
+  }
+}
+
+const maximumVersionLength = 64;
+const numericPart = '(0|[1-9]\\d*)';
+const prereleasePart = '(?:0|[1-9]\\d*|\\d*[A-Za-z-][0-9A-Za-z-]*)';
+const versionPattern = new RegExp(
+  `^${numericPart}\\.${numericPart}\\.${numericPart}(?:-(${prereleasePart}(?:\\.${prereleasePart})*))?$`,
+);
+
+/**
+ * Parses exactly one Codex release number, such as `0.157.1` or `0.158.0-alpha.2`. Anything else
+ * returns null: a prefix such as `codex-cli `, surrounding whitespace, build metadata, leading
+ * zeros or components beyond the safe integer range.
+ */
+export const parseCodexVersion = (textArg: string): ICodexVersion | null => {
+  if (typeof textArg !== 'string' || textArg.length > maximumVersionLength) return null;
+  const match = versionPattern.exec(textArg);
+  if (!match) return null;
+  const [major, minor, patch] = [match[1], match[2], match[3]].map(Number);
+  if (![major, minor, patch].every(Number.isSafeInteger)) return null;
+  return { major, minor, patch, prerelease: match[4] ?? null, text: textArg };
+};
+
+/** Orders by release number; a prerelease precedes the release of the same number. */
+const isBelow = (versionArg: ICodexVersion, minimumArg: ICodexVersion): boolean => {
+  for (const key of ['major', 'minor', 'patch'] as const) {
+    if (versionArg[key] !== minimumArg[key]) return versionArg[key] < minimumArg[key];
+  }
+  return versionArg.prerelease !== null;
+};
+
+/**
+ * Returns the parsed version when it is `minimumArg` or newer, and throws
+ * `CodexVersionUnsupportedError` otherwise. A prerelease of a newer release is accepted; a
+ * prerelease of the minimum itself is older than the minimum. The minimum must be a release.
+ */
+export const requireCodexVersion = (
+  versionArg: string | null | undefined,
+  minimumArg: string = CODEX_UNIX_SOCKET_MINIMUM_VERSION,
+): ICodexVersion => {
+  const minimum = parseCodexVersion(minimumArg);
+  if (!minimum || minimum.prerelease !== null) {
+    throw new Error('Codex minimum version must be a release number such as 0.156.0');
+  }
+  const reported = typeof versionArg === 'string' ? versionArg : null;
+  const version = reported === null ? null : parseCodexVersion(reported);
+  if (!version) throw new CodexVersionUnsupportedError('unreadable', reported, minimumArg);
+  if (isBelow(version, minimum)) throw new CodexVersionUnsupportedError('below_minimum', reported, minimumArg);
+  return version;
+};

package/ts/index.ts

@@ -1,6 +1,7 @@
 export * from './interfaces.js';
 export * from './classes.codexappserverclient.js';
 export * from './functions.codexunixsocket.js';
+export * from './functions.codexversion.js';
 export * from './classes.connectionregistry.js';
 export * from './classes.dispatchregistry.js';
 export * from './classes.mcptoolregistrar.js';