@relay-harness/coding-agent 0.0.0-stage → 1.0.3

package/dist/core/mcp-servers.js

@@ -0,0 +1,198 @@
+/**
+ * MCP server configuration and the servers extensions register with `relay.registerMcpServer()`.
+ *
+ * The core only validates and stores registrations. The MCP extension (built in, or another
+ * extension that handles `mcp_servers_change`) connects them next to the servers from `mcp.json`.
+ */
+const MCP_EXPOSURES = ["codemode", "deferred", "direct", "hidden"];
+/** Older exposure names, accepted in configs and replaced by their current name when validated. */
+const MCP_EXPOSURE_ALIASES = { "codemode-deferred": "codemode" };
+const LOOPBACK_HOSTS = ["localhost", "127.0.0.1", "[::1]"];
+/** Whether a redirect URI can be served by relay's loopback callback server. */
+export function isLoopbackRedirectUri(value) {
+    if (!URL.canParse(value))
+        return false;
+    const url = new URL(value);
+    return url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname) && url.search === "" && url.hash === "";
+}
+const SERVER_NAME = /^[A-Za-z0-9_-]+$/;
+/** Namespace of a server's tools: `mcp__<server>` with `-` replaced by `_`, like the tool names. */
+export function mcpNamespace(server) {
+    return `mcp__${server.replace(/-/g, "_")}`;
+}
+function isRecord(value) {
+    return typeof value === "object" && value !== null && !Array.isArray(value);
+}
+function isStringRecord(value) {
+    return isRecord(value) && Object.values(value).every((entry) => typeof entry === "string");
+}
+function validateOAuth(value) {
+    if (value === undefined)
+        return undefined;
+    if (!isRecord(value))
+        return "oauth must be an object";
+    if (value.clientId !== undefined && typeof value.clientId !== "string")
+        return "oauth.clientId must be a string";
+    if (value.clientSecret !== undefined && typeof value.clientSecret !== "string") {
+        return "oauth.clientSecret must be a string";
+    }
+    const port = value.callbackPort;
+    if (port !== undefined && (typeof port !== "number" || !Number.isInteger(port) || port < 1 || port > 65535)) {
+        return "oauth.callbackPort must be a port number";
+    }
+    if (value.callbackUrl !== undefined) {
+        if (typeof value.callbackUrl !== "string" || !isLoopbackRedirectUri(value.callbackUrl)) {
+            return "oauth.callbackUrl must be an http URI on localhost, 127.0.0.1, or [::1] without query or fragment";
+        }
+        const urlPort = new URL(value.callbackUrl).port;
+        if (urlPort && port !== undefined && Number(urlPort) !== port) {
+            return "oauth.callbackUrl and oauth.callbackPort name different ports";
+        }
+    }
+    if (value.scope !== undefined && typeof value.scope !== "string")
+        return "oauth.scope must be a string";
+    if (value.clientName !== undefined && (typeof value.clientName !== "string" || !value.clientName.trim())) {
+        return "oauth.clientName must be a non-empty string";
+    }
+    const metadataUrl = value.authServerMetadataUrl;
+    if (metadataUrl !== undefined) {
+        const url = typeof metadataUrl === "string" && URL.canParse(metadataUrl) ? new URL(metadataUrl) : undefined;
+        if (!url || !(url.protocol === "https:" || (url.protocol === "http:" && LOOPBACK_HOSTS.includes(url.hostname)))) {
+            return "oauth.authServerMetadataUrl must be an https URL, or http on localhost, 127.0.0.1, or [::1]";
+        }
+    }
+    return undefined;
+}
+function isExposure(value) {
+    return typeof value === "string" && MCP_EXPOSURES.includes(value);
+}
+/** The exposure an alias stands for; other values are returned unchanged. */
+function resolveExposureAlias(value) {
+    return typeof value === "string" ? (MCP_EXPOSURE_ALIASES[value] ?? value) : value;
+}
+/** A copy of the server entry with exposure aliases replaced by their current names. */
+function resolveExposureAliases(value) {
+    const { exposure, toolExposure } = value;
+    const resolved = { ...value };
+    if (exposure !== undefined)
+        resolved.exposure = resolveExposureAlias(exposure);
+    if (isRecord(toolExposure)) {
+        resolved.toolExposure = Object.fromEntries(Object.entries(toolExposure).map(([tool, entry]) => [tool, resolveExposureAlias(entry)]));
+    }
+    return resolved;
+}
+function toolPatternRegExp(pattern) {
+    const source = pattern
+        .split("*")
+        .map((part) => part.replace(/[.+?^${}()|[\]\\]/g, "\\$&"))
+        .join(".*");
+    return new RegExp(`^${source}$`);
+}
+/** Exposure of one tool of a server: its `toolExposure` entry, else the server's `exposure`. */
+export function getMcpToolExposure(config, toolName) {
+    const overrides = config.toolExposure ?? {};
+    const exact = overrides[toolName];
+    if (exact !== undefined)
+        return exact;
+    for (const [pattern, exposure] of Object.entries(overrides)) {
+        if (pattern.includes("*") && toolPatternRegExp(pattern).test(toolName))
+            return exposure;
+    }
+    return config.exposure ?? "codemode";
+}
+/**
+ * Validate one server entry of the `mcpServers` shape. Returns a copy of the config with exposure
+ * aliases resolved, or an error message.
+ */
+export function validateMcpServerConfig(name, raw) {
+    if (!SERVER_NAME.test(name))
+        return `invalid server name "${name}" (use letters, digits, "_" and "-")`;
+    if (!isRecord(raw))
+        return `server "${name}" must be an object`;
+    const value = resolveExposureAliases(raw);
+    const { type, exposure, enabled, timeout, toolExposure, description } = value;
+    const exposures = MCP_EXPOSURES.map((value) => `"${value}"`).join(", ");
+    if (exposure !== undefined && !isExposure(exposure)) {
+        return `server "${name}": exposure must be one of ${exposures}`;
+    }
+    if (toolExposure !== undefined) {
+        if (!isRecord(toolExposure))
+            return `server "${name}": toolExposure must map tool names to exposures`;
+        for (const [tool, value] of Object.entries(toolExposure)) {
+            if (!isExposure(value))
+                return `server "${name}": toolExposure "${tool}" must be one of ${exposures}`;
+        }
+    }
+    if (enabled !== undefined && typeof enabled !== "boolean")
+        return `server "${name}": enabled must be a boolean`;
+    if (description !== undefined && typeof description !== "string") {
+        return `server "${name}": description must be a string`;
+    }
+    if (timeout !== undefined && (typeof timeout !== "number" || !(timeout > 0))) {
+        return `server "${name}": timeout must be a positive number of seconds`;
+    }
+    if (type === "sse")
+        return `server "${name}": legacy SSE transport is not supported; use the streamable HTTP URL`;
+    if (typeof value.url === "string" && (type === undefined || type === "http" || type === "streamable-http")) {
+        if (!URL.canParse(value.url) || !/^https?:$/.test(new URL(value.url).protocol)) {
+            return `server "${name}": url must be an http or https URL`;
+        }
+        if (value.headers !== undefined && !isStringRecord(value.headers)) {
+            return `server "${name}": headers must map names to strings`;
+        }
+        const oauthError = validateOAuth(value.oauth);
+        if (oauthError)
+            return `server "${name}": ${oauthError}`;
+        if (value.auth !== undefined) {
+            if (!isRecord(value.auth) || typeof value.auth.provider !== "string" || !value.auth.provider) {
+                return `server "${name}": auth.provider must be a provider name`;
+            }
+            const url = new URL(value.url);
+            if (url.protocol !== "https:" && !LOOPBACK_HOSTS.includes(url.hostname)) {
+                return `server "${name}": auth requires an https URL, or http on localhost, 127.0.0.1, or [::1]`;
+            }
+        }
+        return value;
+    }
+    if (typeof value.command === "string" && (type === undefined || type === "stdio")) {
+        if (value.args !== undefined &&
+            !(Array.isArray(value.args) && value.args.every((arg) => typeof arg === "string"))) {
+            return `server "${name}": args must be an array of strings`;
+        }
+        if (value.env !== undefined && !isStringRecord(value.env))
+            return `server "${name}": env must map names to strings`;
+        if (value.cwd !== undefined && typeof value.cwd !== "string")
+            return `server "${name}": cwd must be a string`;
+        return value;
+    }
+    return `server "${name}" needs either "command" (stdio) or "url" (streamable HTTP)`;
+}
+/** Servers registered by the extensions of one runtime. */
+export class McpServerRegistry {
+    servers = new Map();
+    changeListener;
+    /** Register or replace a server. The caller checks ownership. */
+    register(server) {
+        this.servers.set(server.name, server);
+        this.changeListener?.();
+    }
+    /** Remove a server registered by `extensionPath`. Servers of other extensions are left alone. */
+    unregister(name, extensionPath) {
+        if (this.servers.get(name)?.extensionPath !== extensionPath)
+            return;
+        this.servers.delete(name);
+        this.changeListener?.();
+    }
+    get(name) {
+        return this.servers.get(name);
+    }
+    /** Copies of the registered servers, in registration order. */
+    list() {
+        return [...this.servers.values()].map((server) => ({ ...server, config: structuredClone(server.config) }));
+    }
+    /** Called after every change. The runner sets it when it binds, to emit `mcp_servers_change`. */
+    setChangeListener(listener) {
+        this.changeListener = listener;
+    }
+}
+//# sourceMappingURL=mcp-servers.js.map

package/dist/core/mcp-servers.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"mcp-servers.js","sourceRoot":"","sources":["../../src/core/mcp-servers.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * MCP server configuration and the servers extensions register with `relay.registerMcpServer()`.\n *\n * The core only validates and stores registrations. The MCP extension (built in, or another\n * extension that handles `mcp_servers_change`) connects them next to the servers from `mcp.json`.\n */\n\n/**\n * - `codemode`: tools are callable from codemode scripts but neither declared to the model nor\n *   listed in the codemode description, which lists only the server's namespace. Scripts find them\n *   with `searchTools()`. `codemode-deferred` is accepted as an alias.\n * - `deferred`: not declared to the model until the `tool_search` tool loads them; the model then\n *   calls them directly. Does not need codemode.\n * - `direct`: tools are declared to the model like any other tool (and callable from codemode).\n * - `hidden`: tools are registered but unreachable.\n */\nexport type McpExposure = \"codemode\" | \"deferred\" | \"direct\" | \"hidden\";\n\nconst MCP_EXPOSURES: readonly string[] = [\"codemode\", \"deferred\", \"direct\", \"hidden\"] satisfies McpExposure[];\n\n/** Older exposure names, accepted in configs and replaced by their current name when validated. */\nconst MCP_EXPOSURE_ALIASES: Readonly<Record<string, McpExposure>> = { \"codemode-deferred\": \"codemode\" };\n\ninterface McpServerConfigBase {\n\t/** Default: `codemode`. */\n\texposure?: McpExposure;\n\t/**\n\t * What the server offers, in a sentence. The `mcp_servers` system prompt section lists the server\n\t * with it, tool search ranks the server's tools by it, and codemode's `describeNamespace()` returns it.\n\t */\n\tdescription?: string;\n\t/**\n\t * Exposure of single tools, overriding `exposure`. Keys are tool names as the server offers them,\n\t * or patterns where `*` matches any characters. An exact name wins over patterns; among patterns\n\t * the first match in the object wins. `hidden` removes tools, so `\"exposure\": \"hidden\"` with\n\t * overrides for a few tools exposes only those.\n\t */\n\ttoolExposure?: Record<string, McpExposure>;\n\t/** Set to false to keep the entry without connecting. Default: true. */\n\tenabled?: boolean;\n\t/** Per-request timeout in seconds. Progress notifications from the server reset it. Default: 60. */\n\ttimeout?: number;\n}\n\nexport interface McpStdioServerConfig extends McpServerConfigBase {\n\ttype?: \"stdio\";\n\tcommand: string;\n\targs?: string[];\n\t/** Values may reference environment variables (`${NAME}`) or commands (`!cmd`). */\n\tenv?: Record<string, string>;\n\t/** Relative paths resolve against the session working directory. */\n\tcwd?: string;\n}\n\n/** OAuth client settings for servers that do not support dynamic client registration. */\nexport interface McpOAuthConfig {\n\t/** Pre-registered client id. Without it, relay registers a client with the authorization server. */\n\tclientId?: string;\n\t/** May reference environment variables (`${NAME}`) or commands (`!cmd`). */\n\tclientSecret?: string;\n\t/**\n\t * Port of the loopback callback server, for clients registered with a fixed redirect URI. Without\n\t * `callbackUrl`, the redirect URI is `http://127.0.0.1:<port>/callback`.\n\t */\n\tcallbackPort?: number;\n\t/**\n\t * Redirect URI registered for `clientId`, for example `http://localhost:8080/oauth/callback`. It must\n\t * be an `http` URI on `localhost`, `127.0.0.1`, or `[::1]`. Without a port, the callback server\n\t * listens on `callbackPort` or a free port, which is added to the URI (RFC 8252).\n\t */\n\tcallbackUrl?: string;\n\t/** Scopes to request, separated by spaces. Default: the scopes the server advertises. */\n\tscope?: string;\n\t/**\n\t * `client_name` sent with dynamic client registration, for servers that only accept known clients.\n\t * Default: `relay`.\n\t */\n\tclientName?: string;\n\t/**\n\t * Authorization server metadata document (RFC 8414 or OpenID Connect discovery) to use instead of\n\t * discovery through the server, for servers that advertise a wrong authorization server or none.\n\t * The document is trusted as configured. Must use https, except on loopback hosts.\n\t */\n\tauthServerMetadataUrl?: string;\n}\n\nconst LOOPBACK_HOSTS = [\"localhost\", \"127.0.0.1\", \"[::1]\"];\n\n/** Whether a redirect URI can be served by relay's loopback callback server. */\nexport function isLoopbackRedirectUri(value: string): boolean {\n\tif (!URL.canParse(value)) return false;\n\tconst url = new URL(value);\n\treturn url.protocol === \"http:\" && LOOPBACK_HOSTS.includes(url.hostname) && url.search === \"\" && url.hash === \"\";\n}\n\nexport interface McpHttpServerConfig extends McpServerConfigBase {\n\ttype?: \"http\";\n\turl: string;\n\t/** Values may reference environment variables (`${NAME}`) or commands (`!cmd`). */\n\theaders?: Record<string, string>;\n\toauth?: McpOAuthConfig;\n\t/**\n\t * Send the token of a relay provider (`/login <provider>`) instead of using OAuth. Not allowed in project\n\t * `mcp.json` files, and requires https except on loopback hosts, since it sends the credential to `url`.\n\t */\n\tauth?: { provider: string };\n}\n\nexport type McpServerConfig = McpStdioServerConfig | McpHttpServerConfig;\n\nconst SERVER_NAME = /^[A-Za-z0-9_-]+$/;\n\n/** Namespace of a server's tools: `mcp__<server>` with `-` replaced by `_`, like the tool names. */\nexport function mcpNamespace(server: string): string {\n\treturn `mcp__${server.replace(/-/g, \"_\")}`;\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n\treturn typeof value === \"object\" && value !== null && !Array.isArray(value);\n}\n\nfunction isStringRecord(value: unknown): value is Record<string, string> {\n\treturn isRecord(value) && Object.values(value).every((entry) => typeof entry === \"string\");\n}\n\nfunction validateOAuth(value: unknown): string | undefined {\n\tif (value === undefined) return undefined;\n\tif (!isRecord(value)) return \"oauth must be an object\";\n\tif (value.clientId !== undefined && typeof value.clientId !== \"string\") return \"oauth.clientId must be a string\";\n\tif (value.clientSecret !== undefined && typeof value.clientSecret !== \"string\") {\n\t\treturn \"oauth.clientSecret must be a string\";\n\t}\n\tconst port = value.callbackPort;\n\tif (port !== undefined && (typeof port !== \"number\" || !Number.isInteger(port) || port < 1 || port > 65535)) {\n\t\treturn \"oauth.callbackPort must be a port number\";\n\t}\n\tif (value.callbackUrl !== undefined) {\n\t\tif (typeof value.callbackUrl !== \"string\" || !isLoopbackRedirectUri(value.callbackUrl)) {\n\t\t\treturn \"oauth.callbackUrl must be an http URI on localhost, 127.0.0.1, or [::1] without query or fragment\";\n\t\t}\n\t\tconst urlPort = new URL(value.callbackUrl).port;\n\t\tif (urlPort && port !== undefined && Number(urlPort) !== port) {\n\t\t\treturn \"oauth.callbackUrl and oauth.callbackPort name different ports\";\n\t\t}\n\t}\n\tif (value.scope !== undefined && typeof value.scope !== \"string\") return \"oauth.scope must be a string\";\n\tif (value.clientName !== undefined && (typeof value.clientName !== \"string\" || !value.clientName.trim())) {\n\t\treturn \"oauth.clientName must be a non-empty string\";\n\t}\n\tconst metadataUrl = value.authServerMetadataUrl;\n\tif (metadataUrl !== undefined) {\n\t\tconst url = typeof metadataUrl === \"string\" && URL.canParse(metadataUrl) ? new URL(metadataUrl) : undefined;\n\t\tif (!url || !(url.protocol === \"https:\" || (url.protocol === \"http:\" && LOOPBACK_HOSTS.includes(url.hostname)))) {\n\t\t\treturn \"oauth.authServerMetadataUrl must be an https URL, or http on localhost, 127.0.0.1, or [::1]\";\n\t\t}\n\t}\n\treturn undefined;\n}\n\nfunction isExposure(value: unknown): value is McpExposure {\n\treturn typeof value === \"string\" && MCP_EXPOSURES.includes(value);\n}\n\n/** The exposure an alias stands for; other values are returned unchanged. */\nfunction resolveExposureAlias(value: unknown): unknown {\n\treturn typeof value === \"string\" ? (MCP_EXPOSURE_ALIASES[value] ?? value) : value;\n}\n\n/** A copy of the server entry with exposure aliases replaced by their current names. */\nfunction resolveExposureAliases(value: Record<string, unknown>): Record<string, unknown> {\n\tconst { exposure, toolExposure } = value;\n\tconst resolved: Record<string, unknown> = { ...value };\n\tif (exposure !== undefined) resolved.exposure = resolveExposureAlias(exposure);\n\tif (isRecord(toolExposure)) {\n\t\tresolved.toolExposure = Object.fromEntries(\n\t\t\tObject.entries(toolExposure).map(([tool, entry]) => [tool, resolveExposureAlias(entry)]),\n\t\t);\n\t}\n\treturn resolved;\n}\n\nfunction toolPatternRegExp(pattern: string): RegExp {\n\tconst source = pattern\n\t\t.split(\"*\")\n\t\t.map((part) => part.replace(/[.+?^${}()|[\\]\\\\]/g, \"\\\\$&\"))\n\t\t.join(\".*\");\n\treturn new RegExp(`^${source}$`);\n}\n\n/** Exposure of one tool of a server: its `toolExposure` entry, else the server's `exposure`. */\nexport function getMcpToolExposure(config: McpServerConfig, toolName: string): McpExposure {\n\tconst overrides = config.toolExposure ?? {};\n\tconst exact = overrides[toolName];\n\tif (exact !== undefined) return exact;\n\tfor (const [pattern, exposure] of Object.entries(overrides)) {\n\t\tif (pattern.includes(\"*\") && toolPatternRegExp(pattern).test(toolName)) return exposure;\n\t}\n\treturn config.exposure ?? \"codemode\";\n}\n\n/**\n * Validate one server entry of the `mcpServers` shape. Returns a copy of the config with exposure\n * aliases resolved, or an error message.\n */\nexport function validateMcpServerConfig(name: string, raw: unknown): McpServerConfig | string {\n\tif (!SERVER_NAME.test(name)) return `invalid server name \"${name}\" (use letters, digits, \"_\" and \"-\")`;\n\tif (!isRecord(raw)) return `server \"${name}\" must be an object`;\n\tconst value = resolveExposureAliases(raw);\n\tconst { type, exposure, enabled, timeout, toolExposure, description } = value;\n\tconst exposures = MCP_EXPOSURES.map((value) => `\"${value}\"`).join(\", \");\n\tif (exposure !== undefined && !isExposure(exposure)) {\n\t\treturn `server \"${name}\": exposure must be one of ${exposures}`;\n\t}\n\tif (toolExposure !== undefined) {\n\t\tif (!isRecord(toolExposure)) return `server \"${name}\": toolExposure must map tool names to exposures`;\n\t\tfor (const [tool, value] of Object.entries(toolExposure)) {\n\t\t\tif (!isExposure(value)) return `server \"${name}\": toolExposure \"${tool}\" must be one of ${exposures}`;\n\t\t}\n\t}\n\tif (enabled !== undefined && typeof enabled !== \"boolean\") return `server \"${name}\": enabled must be a boolean`;\n\tif (description !== undefined && typeof description !== \"string\") {\n\t\treturn `server \"${name}\": description must be a string`;\n\t}\n\tif (timeout !== undefined && (typeof timeout !== \"number\" || !(timeout > 0))) {\n\t\treturn `server \"${name}\": timeout must be a positive number of seconds`;\n\t}\n\tif (type === \"sse\") return `server \"${name}\": legacy SSE transport is not supported; use the streamable HTTP URL`;\n\n\tif (typeof value.url === \"string\" && (type === undefined || type === \"http\" || type === \"streamable-http\")) {\n\t\tif (!URL.canParse(value.url) || !/^https?:$/.test(new URL(value.url).protocol)) {\n\t\t\treturn `server \"${name}\": url must be an http or https URL`;\n\t\t}\n\t\tif (value.headers !== undefined && !isStringRecord(value.headers)) {\n\t\t\treturn `server \"${name}\": headers must map names to strings`;\n\t\t}\n\t\tconst oauthError = validateOAuth(value.oauth);\n\t\tif (oauthError) return `server \"${name}\": ${oauthError}`;\n\t\tif (value.auth !== undefined) {\n\t\t\tif (!isRecord(value.auth) || typeof value.auth.provider !== \"string\" || !value.auth.provider) {\n\t\t\t\treturn `server \"${name}\": auth.provider must be a provider name`;\n\t\t\t}\n\t\t\tconst url = new URL(value.url);\n\t\t\tif (url.protocol !== \"https:\" && !LOOPBACK_HOSTS.includes(url.hostname)) {\n\t\t\t\treturn `server \"${name}\": auth requires an https URL, or http on localhost, 127.0.0.1, or [::1]`;\n\t\t\t}\n\t\t}\n\t\treturn value as unknown as McpHttpServerConfig;\n\t}\n\tif (typeof value.command === \"string\" && (type === undefined || type === \"stdio\")) {\n\t\tif (\n\t\t\tvalue.args !== undefined &&\n\t\t\t!(Array.isArray(value.args) && value.args.every((arg) => typeof arg === \"string\"))\n\t\t) {\n\t\t\treturn `server \"${name}\": args must be an array of strings`;\n\t\t}\n\t\tif (value.env !== undefined && !isStringRecord(value.env))\n\t\t\treturn `server \"${name}\": env must map names to strings`;\n\t\tif (value.cwd !== undefined && typeof value.cwd !== \"string\") return `server \"${name}\": cwd must be a string`;\n\t\treturn value as unknown as McpStdioServerConfig;\n\t}\n\treturn `server \"${name}\" needs either \"command\" (stdio) or \"url\" (streamable HTTP)`;\n}\n\n/** A server an extension registered with `relay.registerMcpServer()`. */\nexport interface RegisteredMcpServer {\n\tname: string;\n\tconfig: McpServerConfig;\n\t/** Path of the extension that registered the server. */\n\textensionPath: string;\n}\n\n/** Servers registered by the extensions of one runtime. */\nexport class McpServerRegistry {\n\tprivate readonly servers = new Map<string, RegisteredMcpServer>();\n\tprivate changeListener: (() => void) | undefined;\n\n\t/** Register or replace a server. The caller checks ownership. */\n\tregister(server: RegisteredMcpServer): void {\n\t\tthis.servers.set(server.name, server);\n\t\tthis.changeListener?.();\n\t}\n\n\t/** Remove a server registered by `extensionPath`. Servers of other extensions are left alone. */\n\tunregister(name: string, extensionPath: string): void {\n\t\tif (this.servers.get(name)?.extensionPath !== extensionPath) return;\n\t\tthis.servers.delete(name);\n\t\tthis.changeListener?.();\n\t}\n\n\tget(name: string): RegisteredMcpServer | undefined {\n\t\treturn this.servers.get(name);\n\t}\n\n\t/** Copies of the registered servers, in registration order. */\n\tlist(): RegisteredMcpServer[] {\n\t\treturn [...this.servers.values()].map((server) => ({ ...server, config: structuredClone(server.config) }));\n\t}\n\n\t/** Called after every change. The runner sets it when it binds, to emit `mcp_servers_change`. */\n\tsetChangeListener(listener: (() => void) | undefined): void {\n\t\tthis.changeListener = listener;\n\t}\n}\n"]}

package/dist/core/messages.d.ts

@@ -0,0 +1,77 @@
+/**
+ * Custom message types and transformers for the coding agent.
+ *
+ * Extends the base AgentMessage type with coding-agent specific message types,
+ * and provides a transformer to convert them to LLM-compatible messages.
+ */
+import type { AgentMessage } from "@relay-harness/agent-core";
+import type { ImageContent, Message, TextContent } from "@relay-harness/ai";
+export declare const COMPACTION_SUMMARY_PREFIX = "The conversation history before this point was compacted into the following summary:\n\n<summary>\n";
+export declare const COMPACTION_SUMMARY_SUFFIX = "\n</summary>";
+export declare const BRANCH_SUMMARY_PREFIX = "The following is a summary of a branch that this conversation came back from:\n\n<summary>\n";
+export declare const BRANCH_SUMMARY_SUFFIX = "</summary>";
+/**
+ * Message type for bash executions via the ! command.
+ */
+export interface BashExecutionMessage {
+    role: "bashExecution";
+    command: string;
+    output: string;
+    exitCode: number | undefined;
+    cancelled: boolean;
+    truncated: boolean;
+    fullOutputPath?: string;
+    timestamp: number;
+    /** If true, this message is excluded from LLM context (!! prefix) */
+    excludeFromContext?: boolean;
+}
+/**
+ * Message type for extension-injected messages via sendMessage().
+ * These are custom messages that extensions can inject into the conversation.
+ */
+export interface CustomMessage<T = unknown> {
+    role: "custom";
+    customType: string;
+    content: string | (TextContent | ImageContent)[];
+    display: boolean;
+    details?: T;
+    timestamp: number;
+}
+export interface BranchSummaryMessage {
+    role: "branchSummary";
+    summary: string;
+    fromId: string | null;
+    timestamp: number;
+}
+export interface CompactionSummaryMessage {
+    role: "compactionSummary";
+    summary: string;
+    tokensBefore: number;
+    timestamp: number;
+}
+declare module "@relay-harness/agent-core" {
+    interface CustomAgentMessages {
+        bashExecution: BashExecutionMessage;
+        custom: CustomMessage;
+        branchSummary: BranchSummaryMessage;
+        compactionSummary: CompactionSummaryMessage;
+    }
+}
+/**
+ * Convert a BashExecutionMessage to user message text for LLM context.
+ */
+export declare function bashExecutionToText(msg: BashExecutionMessage): string;
+export declare function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage;
+export declare function createCompactionSummaryMessage(summary: string, tokensBefore: number, timestamp: string): CompactionSummaryMessage;
+/** Convert CustomMessageEntry to AgentMessage format */
+export declare function createCustomMessage(customType: string, content: string | (TextContent | ImageContent)[], display: boolean, details: unknown | undefined, timestamp: string): CustomMessage;
+/**
+ * Transform AgentMessages (including custom types) to LLM-compatible Messages.
+ *
+ * This is used by:
+ * - Agent's transormToLlm option (for prompt calls and queued messages)
+ * - Compaction's generateSummary (for summarization)
+ * - Custom extensions and tools
+ */
+export declare function convertToLlm(messages: AgentMessage[]): Message[];
+//# sourceMappingURL=messages.d.ts.map

package/dist/core/messages.d.ts.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.d.ts","sourceRoot":"","sources":["../../src/core/messages.ts"],"names":[],"mappings":"AAAA;;;;;GAKG;AAEH,OAAO,KAAK,EAAE,YAAY,EAAE,MAAM,2BAA2B,CAAC;AAC9D,OAAO,KAAK,EAAE,YAAY,EAAE,OAAO,EAAE,WAAW,EAAE,MAAM,mBAAmB,CAAC;AAE5E,eAAO,MAAM,yBAAyB,wGAGrC,CAAC;AAEF,eAAO,MAAM,yBAAyB,iBAC3B,CAAC;AAEZ,eAAO,MAAM,qBAAqB,iGAGjC,CAAC;AAEF,eAAO,MAAM,qBAAqB,eAAe,CAAC;AAElD;;GAEG;AACH,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,CAAC;IACf,QAAQ,EAAE,MAAM,GAAG,SAAS,CAAC;IAC7B,SAAS,EAAE,OAAO,CAAC;IACnB,SAAS,EAAE,OAAO,CAAC;IACnB,cAAc,CAAC,EAAE,MAAM,CAAC;IACxB,SAAS,EAAE,MAAM,CAAC;IAClB,qEAAqE;IACrE,kBAAkB,CAAC,EAAE,OAAO,CAAC;CAC7B;AAED;;;GAGG;AACH,MAAM,WAAW,aAAa,CAAC,CAAC,GAAG,OAAO;IACzC,IAAI,EAAE,QAAQ,CAAC;IACf,UAAU,EAAE,MAAM,CAAC;IACnB,OAAO,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,CAAC;IACjD,OAAO,EAAE,OAAO,CAAC;IACjB,OAAO,CAAC,EAAE,CAAC,CAAC;IACZ,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,oBAAoB;IACpC,IAAI,EAAE,eAAe,CAAC;IACtB,OAAO,EAAE,MAAM,CAAC;IAChB,MAAM,EAAE,MAAM,GAAG,IAAI,CAAC;IACtB,SAAS,EAAE,MAAM,CAAC;CAClB;AAED,MAAM,WAAW,wBAAwB;IACxC,IAAI,EAAE,mBAAmB,CAAC;IAC1B,OAAO,EAAE,MAAM,CAAC;IAChB,YAAY,EAAE,MAAM,CAAC;IACrB,SAAS,EAAE,MAAM,CAAC;CAClB;AAGD,OAAO,QAAQ,2BAA2B,CAAC;IAC1C,UAAU,mBAAmB;QAC5B,aAAa,EAAE,oBAAoB,CAAC;QACpC,MAAM,EAAE,aAAa,CAAC;QACtB,aAAa,EAAE,oBAAoB,CAAC;QACpC,iBAAiB,EAAE,wBAAwB,CAAC;KAC5C;CACD;AAED;;GAEG;AACH,wBAAgB,mBAAmB,CAAC,GAAG,EAAE,oBAAoB,GAAG,MAAM,CAgBrE;AAED,wBAAgB,0BAA0B,CAAC,OAAO,EAAE,MAAM,EAAE,MAAM,EAAE,MAAM,EAAE,SAAS,EAAE,MAAM,GAAG,oBAAoB,CAOnH;AAED,wBAAgB,8BAA8B,CAC7C,OAAO,EAAE,MAAM,EACf,YAAY,EAAE,MAAM,EACpB,SAAS,EAAE,MAAM,GACf,wBAAwB,CAO1B;AAED,wDAAwD;AACxD,wBAAgB,mBAAmB,CAClC,UAAU,EAAE,MAAM,EAClB,OAAO,EAAE,MAAM,GAAG,CAAC,WAAW,GAAG,YAAY,CAAC,EAAE,EAChD,OAAO,EAAE,OAAO,EAChB,OAAO,EAAE,OAAO,GAAG,SAAS,EAC5B,SAAS,EAAE,MAAM,GACf,aAAa,CASf;AAED;;;;;;;GAOG;AACH,wBAAgB,YAAY,CAAC,QAAQ,EAAE,YAAY,EAAE,GAAG,OAAO,EAAE,CAgDhE"}

package/dist/core/messages.js

@@ -0,0 +1,124 @@
+/**
+ * Custom message types and transformers for the coding agent.
+ *
+ * Extends the base AgentMessage type with coding-agent specific message types,
+ * and provides a transformer to convert them to LLM-compatible messages.
+ */
+export const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:
+
+<summary>
+`;
+export const COMPACTION_SUMMARY_SUFFIX = `
+</summary>`;
+export const BRANCH_SUMMARY_PREFIX = `The following is a summary of a branch that this conversation came back from:
+
+<summary>
+`;
+export const BRANCH_SUMMARY_SUFFIX = `</summary>`;
+/**
+ * Convert a BashExecutionMessage to user message text for LLM context.
+ */
+export function bashExecutionToText(msg) {
+    let text = `Ran \`${msg.command}\`\n`;
+    if (msg.output) {
+        text += `\`\`\`\n${msg.output}\n\`\`\``;
+    }
+    else {
+        text += "(no output)";
+    }
+    if (msg.cancelled) {
+        text += "\n\n(command cancelled)";
+    }
+    else if (msg.exitCode !== null && msg.exitCode !== undefined && msg.exitCode !== 0) {
+        text += `\n\nCommand exited with code ${msg.exitCode}`;
+    }
+    if (msg.truncated && msg.fullOutputPath) {
+        text += `\n\n[Output truncated. Full output: ${msg.fullOutputPath}]`;
+    }
+    return text;
+}
+export function createBranchSummaryMessage(summary, fromId, timestamp) {
+    return {
+        role: "branchSummary",
+        summary,
+        fromId,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+export function createCompactionSummaryMessage(summary, tokensBefore, timestamp) {
+    return {
+        role: "compactionSummary",
+        summary: summary,
+        tokensBefore,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+/** Convert CustomMessageEntry to AgentMessage format */
+export function createCustomMessage(customType, content, display, details, timestamp) {
+    return {
+        role: "custom",
+        customType,
+        content,
+        display,
+        details,
+        timestamp: new Date(timestamp).getTime(),
+    };
+}
+/**
+ * Transform AgentMessages (including custom types) to LLM-compatible Messages.
+ *
+ * This is used by:
+ * - Agent's transormToLlm option (for prompt calls and queued messages)
+ * - Compaction's generateSummary (for summarization)
+ * - Custom extensions and tools
+ */
+export function convertToLlm(messages) {
+    return messages
+        .map((m) => {
+        switch (m.role) {
+            case "bashExecution":
+                // Skip messages excluded from context (!! prefix)
+                if (m.excludeFromContext) {
+                    return undefined;
+                }
+                return {
+                    role: "user",
+                    content: [{ type: "text", text: bashExecutionToText(m) }],
+                    timestamp: m.timestamp,
+                };
+            case "custom": {
+                const content = typeof m.content === "string" ? [{ type: "text", text: m.content }] : m.content;
+                return {
+                    role: "user",
+                    content,
+                    timestamp: m.timestamp,
+                };
+            }
+            case "branchSummary":
+                return {
+                    role: "user",
+                    content: [{ type: "text", text: BRANCH_SUMMARY_PREFIX + m.summary + BRANCH_SUMMARY_SUFFIX }],
+                    timestamp: m.timestamp,
+                };
+            case "compactionSummary":
+                return {
+                    role: "user",
+                    content: [
+                        { type: "text", text: COMPACTION_SUMMARY_PREFIX + m.summary + COMPACTION_SUMMARY_SUFFIX },
+                    ],
+                    timestamp: m.timestamp,
+                };
+            case "system":
+            case "user":
+            case "assistant":
+            case "toolResult":
+                return m;
+            default:
+                // biome-ignore lint/correctness/noSwitchDeclarations: fine
+                const _exhaustiveCheck = m;
+                return undefined;
+        }
+    })
+        .filter((m) => m !== undefined);
+}
+//# sourceMappingURL=messages.js.map

package/dist/core/messages.js.map

@@ -0,0 +1 @@
+{"version":3,"file":"messages.js","sourceRoot":"","sources":["../../src/core/messages.ts"],"names":[],"mappings":"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","sourcesContent":["/**\n * Custom message types and transformers for the coding agent.\n *\n * Extends the base AgentMessage type with coding-agent specific message types,\n * and provides a transformer to convert them to LLM-compatible messages.\n */\n\nimport type { AgentMessage } from \"@relay-harness/agent-core\";\nimport type { ImageContent, Message, TextContent } from \"@relay-harness/ai\";\n\nexport const COMPACTION_SUMMARY_PREFIX = `The conversation history before this point was compacted into the following summary:\n\n<summary>\n`;\n\nexport const COMPACTION_SUMMARY_SUFFIX = `\n</summary>`;\n\nexport const BRANCH_SUMMARY_PREFIX = `The following is a summary of a branch that this conversation came back from:\n\n<summary>\n`;\n\nexport const BRANCH_SUMMARY_SUFFIX = `</summary>`;\n\n/**\n * Message type for bash executions via the ! command.\n */\nexport interface BashExecutionMessage {\n\trole: \"bashExecution\";\n\tcommand: string;\n\toutput: string;\n\texitCode: number | undefined;\n\tcancelled: boolean;\n\ttruncated: boolean;\n\tfullOutputPath?: string;\n\ttimestamp: number;\n\t/** If true, this message is excluded from LLM context (!! prefix) */\n\texcludeFromContext?: boolean;\n}\n\n/**\n * Message type for extension-injected messages via sendMessage().\n * These are custom messages that extensions can inject into the conversation.\n */\nexport interface CustomMessage<T = unknown> {\n\trole: \"custom\";\n\tcustomType: string;\n\tcontent: string | (TextContent | ImageContent)[];\n\tdisplay: boolean;\n\tdetails?: T;\n\ttimestamp: number;\n}\n\nexport interface BranchSummaryMessage {\n\trole: \"branchSummary\";\n\tsummary: string;\n\tfromId: string | null;\n\ttimestamp: number;\n}\n\nexport interface CompactionSummaryMessage {\n\trole: \"compactionSummary\";\n\tsummary: string;\n\ttokensBefore: number;\n\ttimestamp: number;\n}\n\n// Extend CustomAgentMessages via declaration merging\ndeclare module \"@relay-harness/agent-core\" {\n\tinterface CustomAgentMessages {\n\t\tbashExecution: BashExecutionMessage;\n\t\tcustom: CustomMessage;\n\t\tbranchSummary: BranchSummaryMessage;\n\t\tcompactionSummary: CompactionSummaryMessage;\n\t}\n}\n\n/**\n * Convert a BashExecutionMessage to user message text for LLM context.\n */\nexport function bashExecutionToText(msg: BashExecutionMessage): string {\n\tlet text = `Ran \\`${msg.command}\\`\\n`;\n\tif (msg.output) {\n\t\ttext += `\\`\\`\\`\\n${msg.output}\\n\\`\\`\\``;\n\t} else {\n\t\ttext += \"(no output)\";\n\t}\n\tif (msg.cancelled) {\n\t\ttext += \"\\n\\n(command cancelled)\";\n\t} else if (msg.exitCode !== null && msg.exitCode !== undefined && msg.exitCode !== 0) {\n\t\ttext += `\\n\\nCommand exited with code ${msg.exitCode}`;\n\t}\n\tif (msg.truncated && msg.fullOutputPath) {\n\t\ttext += `\\n\\n[Output truncated. Full output: ${msg.fullOutputPath}]`;\n\t}\n\treturn text;\n}\n\nexport function createBranchSummaryMessage(summary: string, fromId: string, timestamp: string): BranchSummaryMessage {\n\treturn {\n\t\trole: \"branchSummary\",\n\t\tsummary,\n\t\tfromId,\n\t\ttimestamp: new Date(timestamp).getTime(),\n\t};\n}\n\nexport function createCompactionSummaryMessage(\n\tsummary: string,\n\ttokensBefore: number,\n\ttimestamp: string,\n): CompactionSummaryMessage {\n\treturn {\n\t\trole: \"compactionSummary\",\n\t\tsummary: summary,\n\t\ttokensBefore,\n\t\ttimestamp: new Date(timestamp).getTime(),\n\t};\n}\n\n/** Convert CustomMessageEntry to AgentMessage format */\nexport function createCustomMessage(\n\tcustomType: string,\n\tcontent: string | (TextContent | ImageContent)[],\n\tdisplay: boolean,\n\tdetails: unknown | undefined,\n\ttimestamp: string,\n): CustomMessage {\n\treturn {\n\t\trole: \"custom\",\n\t\tcustomType,\n\t\tcontent,\n\t\tdisplay,\n\t\tdetails,\n\t\ttimestamp: new Date(timestamp).getTime(),\n\t};\n}\n\n/**\n * Transform AgentMessages (including custom types) to LLM-compatible Messages.\n *\n * This is used by:\n * - Agent's transormToLlm option (for prompt calls and queued messages)\n * - Compaction's generateSummary (for summarization)\n * - Custom extensions and tools\n */\nexport function convertToLlm(messages: AgentMessage[]): Message[] {\n\treturn messages\n\t\t.map((m): Message | undefined => {\n\t\t\tswitch (m.role) {\n\t\t\t\tcase \"bashExecution\":\n\t\t\t\t\t// Skip messages excluded from context (!! prefix)\n\t\t\t\t\tif (m.excludeFromContext) {\n\t\t\t\t\t\treturn undefined;\n\t\t\t\t\t}\n\t\t\t\t\treturn {\n\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\tcontent: [{ type: \"text\", text: bashExecutionToText(m) }],\n\t\t\t\t\t\ttimestamp: m.timestamp,\n\t\t\t\t\t};\n\t\t\t\tcase \"custom\": {\n\t\t\t\t\tconst content = typeof m.content === \"string\" ? [{ type: \"text\" as const, text: m.content }] : m.content;\n\t\t\t\t\treturn {\n\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\tcontent,\n\t\t\t\t\t\ttimestamp: m.timestamp,\n\t\t\t\t\t};\n\t\t\t\t}\n\t\t\t\tcase \"branchSummary\":\n\t\t\t\t\treturn {\n\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\tcontent: [{ type: \"text\" as const, text: BRANCH_SUMMARY_PREFIX + m.summary + BRANCH_SUMMARY_SUFFIX }],\n\t\t\t\t\t\ttimestamp: m.timestamp,\n\t\t\t\t\t};\n\t\t\t\tcase \"compactionSummary\":\n\t\t\t\t\treturn {\n\t\t\t\t\t\trole: \"user\",\n\t\t\t\t\t\tcontent: [\n\t\t\t\t\t\t\t{ type: \"text\" as const, text: COMPACTION_SUMMARY_PREFIX + m.summary + COMPACTION_SUMMARY_SUFFIX },\n\t\t\t\t\t\t],\n\t\t\t\t\t\ttimestamp: m.timestamp,\n\t\t\t\t\t};\n\t\t\t\tcase \"system\":\n\t\t\t\tcase \"user\":\n\t\t\t\tcase \"assistant\":\n\t\t\t\tcase \"toolResult\":\n\t\t\t\t\treturn m;\n\t\t\t\tdefault:\n\t\t\t\t\t// biome-ignore lint/correctness/noSwitchDeclarations: fine\n\t\t\t\t\tconst _exhaustiveCheck: never = m;\n\t\t\t\t\treturn undefined;\n\t\t\t}\n\t\t})\n\t\t.filter((m) => m !== undefined);\n}\n"]}