@brutalsystems/muster 0.6.0 → 0.7.1

package/dist/opencode-http.js

@@ -0,0 +1,241 @@
+import net from "node:net";
+import { z } from "zod";
+const REQUEST_TIMEOUT_MS = 2_000;
+const healthSchema = z.object({
+    healthy: z.boolean(),
+    version: z.string().min(1),
+});
+const sessionSchema = z.object({
+    id: z.string().min(1),
+    title: z.string(),
+    directory: z.string().min(1),
+    time: z.object({
+        created: z.number(),
+        updated: z.number(),
+    }),
+});
+const statusSchema = z.discriminatedUnion("type", [
+    z.object({ type: z.literal("idle") }),
+    z.object({ type: z.literal("busy") }),
+    z.object({
+        type: z.literal("retry"),
+        attempt: z.number(),
+        message: z.string(),
+        next: z.number(),
+        action: z
+            .object({
+            reason: z.string(),
+            provider: z.string(),
+            title: z.string(),
+            message: z.string(),
+            label: z.string(),
+            link: z.string().optional(),
+        })
+            .optional(),
+    }),
+]);
+const eventSchema = z
+    .object({
+    id: z.string().optional(),
+    type: z.string().min(1),
+    properties: z.unknown(),
+})
+    .passthrough();
+export class OpenCodeProtocolError extends Error {
+    code;
+    method;
+    path;
+    status;
+    name = "OpenCodeProtocolError";
+    constructor(message, code, method, path, status) {
+        super(`OpenCode protocol error: ${message}`);
+        this.code = code;
+        this.method = method;
+        this.path = path;
+        this.status = status;
+    }
+}
+function protocolError(message, code = "request", method, path, status) {
+    return new OpenCodeProtocolError(message, code, method, path, status);
+}
+function requestTimeout(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw protocolError("request timed out", "timeout");
+    return Math.min(remaining, REQUEST_TIMEOUT_MS);
+}
+function isJsonContentType(value) {
+    const mediaType = value?.split(";", 1)[0]?.trim().toLowerCase();
+    return mediaType === "application/json" || mediaType?.endsWith("+json");
+}
+function isLoopbackHostname(hostname) {
+    return hostname === "127.0.0.1" || hostname === "[::1]";
+}
+/**
+ * Reserves an ephemeral loopback port only long enough to learn its number.
+ * The caller must still prove endpoint ownership during readiness because
+ * another process can claim the port after this function closes its listener.
+ */
+export function allocateLoopbackPort() {
+    return new Promise((resolve, reject) => {
+        const server = net.createServer();
+        server.unref();
+        server.once("error", reject);
+        server.listen(0, "127.0.0.1", () => {
+            const address = server.address();
+            if (!address || typeof address === "string") {
+                server.close();
+                reject(protocolError("could not allocate a loopback port"));
+                return;
+            }
+            const port = address.port;
+            server.close((error) => {
+                if (error)
+                    reject(protocolError("could not release allocated port"));
+                else
+                    resolve(port);
+            });
+        });
+    });
+}
+export class OpenCodeHttp {
+    baseUrl;
+    constructor(baseUrl) {
+        let parsed;
+        try {
+            parsed = new URL(baseUrl);
+        }
+        catch {
+            throw protocolError("endpoint must be a loopback HTTP URL using a literal loopback IP", "endpoint");
+        }
+        if (parsed.protocol !== "http:" ||
+            !isLoopbackHostname(parsed.hostname) ||
+            parsed.username !== "" ||
+            parsed.password !== "") {
+            throw protocolError("endpoint must be a loopback HTTP URL using a literal loopback IP", "endpoint");
+        }
+        this.baseUrl = new URL(parsed.origin);
+    }
+    health(deadline) {
+        return this.requestJson("GET", "/global/health", deadline, healthSchema);
+    }
+    sessions(deadline) {
+        return this.requestJson("GET", "/session", deadline, z.array(sessionSchema));
+    }
+    session(id, deadline) {
+        return this.requestJson("GET", `/session/${encodeURIComponent(id)}`, deadline, sessionSchema);
+    }
+    statuses(deadline) {
+        return this.requestJson("GET", "/session/status", deadline, z.record(statusSchema));
+    }
+    abort(id, deadline) {
+        return this.requestJson("POST", `/session/${encodeURIComponent(id)}/abort`, deadline, z.boolean());
+    }
+    async *events(deadline) {
+        const method = "GET";
+        const path = "/event";
+        const controller = new AbortController();
+        let timer = setTimeout(() => controller.abort(), requestTimeout(deadline));
+        try {
+            const response = await fetch(new URL(path, this.baseUrl), {
+                method,
+                headers: { accept: "text/event-stream" },
+                signal: controller.signal,
+            });
+            clearTimeout(timer);
+            const streamTimeout = deadline - Date.now();
+            if (streamTimeout <= 0)
+                throw protocolError(`${method} ${path} timed out`, "timeout", method, path);
+            timer = setTimeout(() => controller.abort(), streamTimeout);
+            if (!response.ok)
+                throw protocolError(`${method} ${path} returned HTTP ${response.status}`, "http", method, path, response.status);
+            const mediaType = response.headers
+                .get("content-type")
+                ?.split(";", 1)[0]
+                ?.trim()
+                .toLowerCase();
+            if (mediaType !== "text/event-stream")
+                throw protocolError(`${method} ${path} returned the wrong content type`, "content_type", method, path);
+            if (!response.body)
+                throw protocolError(`${method} ${path} returned no event stream`, "invalid_payload", method, path);
+            const decoder = new TextDecoder();
+            let buffer = "";
+            for await (const chunk of response.body) {
+                buffer += decoder.decode(chunk, { stream: true });
+                let boundary;
+                while ((boundary = buffer.match(/\r?\n\r?\n/))) {
+                    const block = buffer.slice(0, boundary.index);
+                    buffer = buffer.slice(boundary.index + boundary[0].length);
+                    const data = block
+                        .split(/\r?\n/)
+                        .filter((line) => line === "data" || line.startsWith("data:"))
+                        .map((line) => line.slice(5).replace(/^ /, ""))
+                        .join("\n");
+                    if (data === "")
+                        continue;
+                    yield this.parseEvent(data);
+                }
+            }
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw protocolError(`${method} ${path} timed out`, "timeout", method, path);
+            if (error instanceof OpenCodeProtocolError)
+                throw error;
+            throw protocolError(`${method} ${path} request failed`, "request", method, path);
+        }
+        finally {
+            clearTimeout(timer);
+            controller.abort();
+        }
+    }
+    parseEvent(data) {
+        let value;
+        try {
+            value = JSON.parse(data);
+        }
+        catch {
+            throw protocolError("GET /event returned invalid JSON", "invalid_json", "GET", "/event");
+        }
+        const parsed = eventSchema.safeParse(value);
+        if (!parsed.success)
+            throw protocolError("GET /event returned an invalid event payload", "invalid_payload", "GET", "/event");
+        return parsed.data;
+    }
+    async requestJson(method, path, deadline, schema) {
+        const controller = new AbortController();
+        const timer = setTimeout(() => controller.abort(), requestTimeout(deadline));
+        try {
+            const response = await fetch(new URL(path, this.baseUrl), {
+                method,
+                headers: { accept: "application/json" },
+                signal: controller.signal,
+            });
+            if (!response.ok)
+                throw protocolError(`${method} ${path} returned HTTP ${response.status}`, "http", method, path, response.status);
+            if (!isJsonContentType(response.headers.get("content-type")))
+                throw protocolError(`${method} ${path} returned the wrong content type`, "content_type", method, path);
+            let value;
+            try {
+                value = await response.json();
+            }
+            catch {
+                throw protocolError(`${method} ${path} returned invalid JSON`, "invalid_json", method, path);
+            }
+            const parsed = schema.safeParse(value);
+            if (!parsed.success)
+                throw protocolError(`${method} ${path} returned an invalid payload`, "invalid_payload", method, path);
+            return parsed.data;
+        }
+        catch (error) {
+            if (controller.signal.aborted)
+                throw protocolError(`${method} ${path} timed out`, "timeout", method, path);
+            if (error instanceof OpenCodeProtocolError)
+                throw error;
+            throw protocolError(`${method} ${path} request failed`, "request", method, path);
+        }
+        finally {
+            clearTimeout(timer);
+        }
+    }
+}

package/dist/opencode-policy.js

@@ -0,0 +1,382 @@
+import { execFile } from "node:child_process";
+import { promisify } from "node:util";
+import { resolvePermissions, runtimeArgs } from "./guard.js";
+const exec = promisify(execFile);
+const DEBUG_CONFIG_ERROR = "Cannot verify effective OpenCode MCP configuration";
+const ISOLATION_ERROR = "OpenCode MCP isolation could not be verified; refusing launch";
+const INLINE_CONFIG_ERROR = "Cannot safely compose the existing inline OpenCode config";
+function isRecord(value) {
+    return !!value && typeof value === "object" && !Array.isArray(value);
+}
+function commandTimeout(deadline) {
+    const remaining = deadline - Date.now();
+    if (remaining <= 0)
+        throw new Error(DEBUG_CONFIG_ERROR);
+    return Math.min(4000, remaining);
+}
+async function resolvedConfig(env, cwd, deadline, errorMessage = DEBUG_CONFIG_ERROR) {
+    try {
+        const { stdout } = await exec("opencode", ["--pure", "debug", "config"], {
+            env,
+            cwd,
+            timeout: commandTimeout(deadline),
+            maxBuffer: 1024 * 1024,
+            encoding: "utf8",
+        });
+        const value = JSON.parse(stdout);
+        if (!isRecord(value))
+            throw new Error("invalid config");
+        return value;
+    }
+    catch {
+        // OpenCode diagnostics and resolved config may contain credentials. Never
+        // include child output, inline config, or the underlying error here.
+        throw new Error(errorMessage);
+    }
+}
+function fixedEnvironmentName(server, key) {
+    const encode = (value) => Buffer.from(value, "utf8").toString("hex").toUpperCase();
+    return `MUSTER_OPENCODE_MCP_${encode(server)}_${encode(key)}`;
+}
+function environmentReference(name) {
+    return `{env:${name}}`;
+}
+export function openCodeMcpConfig(server) {
+    const config = server.config;
+    if (config.command) {
+        const environment = Object.fromEntries([
+            ...Object.keys(config.env).map((key) => [
+                key,
+                environmentReference(fixedEnvironmentName(server.name, key)),
+            ]),
+            ...config.env_vars.map((key) => [key, environmentReference(key)]),
+        ]);
+        return {
+            type: "local",
+            command: [config.command, ...config.args],
+            ...(Object.keys(environment).length ? { environment } : {}),
+            timeout: config.startup_timeout_sec * 1000,
+            enabled: true,
+        };
+    }
+    return {
+        type: "remote",
+        url: config.url,
+        ...(config.bearer_token_env_var
+            ? {
+                headers: {
+                    Authorization: `Bearer ${environmentReference(config.bearer_token_env_var)}`,
+                },
+            }
+            : {}),
+        timeout: config.startup_timeout_sec * 1000,
+        enabled: true,
+    };
+}
+function effectiveMcp(selected, inheritedMcpNames) {
+    const used = new Set(inheritedMcpNames);
+    return selected.map((server) => {
+        let name = server.name;
+        let suffix = 0;
+        while (used.has(name))
+            name = `muster_${server.name}_${++suffix}`;
+        used.add(name);
+        return { server, name };
+    });
+}
+function mcpPolicy(selected, inheritedMcpNames) {
+    const effective = effectiveMcp(selected, inheritedMcpNames);
+    const mcp = Object.fromEntries(inheritedMcpNames.map((name) => [name, { enabled: false }]));
+    const tools = Object.fromEntries(inheritedMcpNames.map((name) => [`${name}_*`, false]));
+    for (const { server, name } of effective) {
+        mcp[name] = openCodeMcpConfig(server);
+        tools[`${name}_*`] = true;
+        for (const tool of server.excludedTools)
+            tools[`${name}_${tool}`] = false;
+    }
+    return { effective, mcp, tools };
+}
+function permissions(req, config, tools) {
+    const policy = resolvePermissions(req, config);
+    const permission = {
+        "*": policy.permissions === "bypass"
+            ? "allow"
+            : policy.permissions === "auto"
+                ? "ask"
+                : "deny",
+    };
+    if (policy.permissions !== "bypass") {
+        for (const name of [
+            "read",
+            "glob",
+            "grep",
+            "list",
+            "lsp",
+            "todoread",
+            "question",
+        ])
+            permission[name] = "allow";
+    }
+    if (policy.permissions === "deny" || policy.sandbox === "read-only") {
+        for (const name of [
+            "edit",
+            "bash",
+            "task",
+            "external_directory",
+            "webfetch",
+            "websearch",
+        ])
+            permission[name] = "deny";
+    }
+    else if (policy.permissions === "auto") {
+        for (const name of ["external_directory", "webfetch", "websearch"])
+            permission[name] = "deny";
+        permission.question = "allow";
+    }
+    for (const [pattern, enabled] of Object.entries(tools))
+        permission[pattern] = enabled ? "allow" : "deny";
+    return permission;
+}
+export function openCodeConfig(req, config, selected, inheritedMcpNames) {
+    const { mcp, tools } = mcpPolicy(selected, inheritedMcpNames);
+    return {
+        share: "disabled",
+        server: { hostname: "127.0.0.1" },
+        permission: permissions(req, config, tools),
+        tools,
+        mcp,
+    };
+}
+function mergeRecords(base, override) {
+    return Object.fromEntries([...new Set([...Object.keys(base), ...Object.keys(override)])].map((key) => {
+        const original = base[key];
+        const replacement = override[key];
+        return [
+            key,
+            isRecord(original) && isRecord(replacement)
+                ? mergeRecords(original, replacement)
+                : replacement === undefined
+                    ? original
+                    : replacement,
+        ];
+    }));
+}
+function composeInlineConfig(env, overlay) {
+    let inherited = {};
+    const source = env.OPENCODE_CONFIG_CONTENT;
+    if (source !== undefined) {
+        try {
+            const value = JSON.parse(source);
+            if (!isRecord(value))
+                throw new Error("invalid inline config");
+            inherited = value;
+        }
+        catch {
+            throw new Error(INLINE_CONFIG_ERROR);
+        }
+    }
+    const inheritedMcp = inherited.mcp;
+    const overlayMcp = overlay.mcp;
+    if ((inheritedMcp !== undefined && !isRecord(inheritedMcp)) ||
+        !isRecord(overlayMcp))
+        throw new Error(INLINE_CONFIG_ERROR);
+    return {
+        ...inherited,
+        ...overlay,
+        // Preserve inherited inline definitions so provider/model configuration
+        // remains intact, but apply Muster's enabled state and selected definitions.
+        mcp: mergeRecords(inheritedMcp ?? {}, overlayMcp),
+    };
+}
+function envPatch(selected, overlay, env) {
+    const config = composeInlineConfig(env, overlay);
+    const patch = {
+        OPENCODE_CONFIG_CONTENT: JSON.stringify(config),
+    };
+    for (const server of selected)
+        for (const [key, value] of Object.entries(server.config.env))
+            patch[fixedEnvironmentName(server.name, key)] = value;
+    return patch;
+}
+function sameKeys(actual, expected) {
+    return (JSON.stringify(Object.keys(actual).sort()) ===
+        JSON.stringify(Object.keys(expected).sort()));
+}
+function resolveExpectedEnvironment(value, env) {
+    if (typeof value === "string")
+        return value.replace(/\{env:([A-Za-z_][A-Za-z0-9_]*)\}/g, (_, name) => env[name] === undefined ? "" : env[name]);
+    if (Array.isArray(value))
+        return value.map((item) => resolveExpectedEnvironment(item, env));
+    if (isRecord(value))
+        return Object.fromEntries(Object.entries(value).map(([key, item]) => [
+            key,
+            resolveExpectedEnvironment(item, env),
+        ]));
+    return value;
+}
+function equivalentMcpDefinition(actual, expected, env) {
+    const resolved = resolveExpectedEnvironment(expected, env);
+    return (isRecord(resolved) &&
+        sameKeys(actual, resolved) &&
+        JSON.stringify(actual) === JSON.stringify(resolved));
+}
+function denyOnly(value) {
+    if (value === "deny")
+        return true;
+    return (isRecord(value) &&
+        Object.values(value).length > 0 &&
+        Object.values(value).every(denyOnly));
+}
+async function verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline) {
+    const patch = envPatch(selected, overlay, env);
+    const effectiveConfig = await resolvedConfig({ ...env, ...patch }, cwd, deadline, ISOLATION_ERROR);
+    const actualMcp = isRecord(effectiveConfig.mcp) ? effectiveConfig.mcp : {};
+    const actualTools = isRecord(effectiveConfig.tools)
+        ? effectiveConfig.tools
+        : {};
+    const actualPermission = isRecord(effectiveConfig.permission)
+        ? effectiveConfig.permission
+        : {};
+    const expectedPermission = isRecord(overlay.permission)
+        ? overlay.permission
+        : {};
+    const expected = mcpPolicy(selected, inheritedMcpNames);
+    const selectedNames = new Set(expected.effective.map(({ name }) => name));
+    for (const name of inheritedMcpNames) {
+        const value = actualMcp[name];
+        if (!isRecord(value) || value.enabled !== false)
+            throw new Error(ISOLATION_ERROR);
+    }
+    for (const { server, name } of expected.effective) {
+        const value = actualMcp[name];
+        if (!isRecord(value) ||
+            !equivalentMcpDefinition(value, openCodeMcpConfig(server), {
+                ...env,
+                ...patch,
+            }))
+            throw new Error(ISOLATION_ERROR);
+    }
+    for (const [name, value] of Object.entries(actualMcp))
+        if (!selectedNames.has(name) &&
+            !inheritedMcpNames.includes(name) &&
+            (!isRecord(value) || value.enabled !== false))
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, enabled] of Object.entries(expected.tools))
+        if (actualTools[pattern] !== enabled)
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, enabled] of Object.entries(actualTools))
+        if (enabled === true && expected.tools[pattern] !== true)
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, action] of Object.entries(expectedPermission))
+        if (actualPermission[pattern] !== action)
+            throw new Error(ISOLATION_ERROR);
+    for (const [pattern, action] of Object.entries(actualPermission))
+        if (!(pattern in expectedPermission) && !denyOnly(action))
+            throw new Error(ISOLATION_ERROR);
+    if (effectiveConfig.share !== "disabled")
+        throw new Error(ISOLATION_ERROR);
+    const expectedServer = overlay.server;
+    if (!isRecord(expectedServer) ||
+        !isRecord(effectiveConfig.server) ||
+        JSON.stringify(effectiveConfig.server) !== JSON.stringify(expectedServer))
+        throw new Error(ISOLATION_ERROR);
+    return patch;
+}
+export async function openCodeMcpNames(env, cwd, deadline) {
+    const config = await resolvedConfig(env, cwd, deadline);
+    if (config.mcp === undefined)
+        return [];
+    if (!isRecord(config.mcp))
+        throw new Error(DEBUG_CONFIG_ERROR);
+    return Object.keys(config.mcp);
+}
+export async function openCodeSessionLaunch(req, config, selected, inheritedMcpNames, port, env, cwd, deadline) {
+    const extra = runtimeArgs(req);
+    const policy = resolvePermissions(req, config);
+    const overlay = {
+        ...openCodeConfig(req, config, selected, inheritedMcpNames),
+        server: { hostname: "127.0.0.1", port },
+    };
+    const patch = await verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline);
+    return {
+        argv: [
+            "opencode",
+            "--pure",
+            "--hostname",
+            "127.0.0.1",
+            "--port",
+            String(port),
+            ...(policy.permissions === "auto" ? ["--auto"] : []),
+            ...extra,
+            "--prompt",
+            req.prompt,
+        ],
+        envPatch: patch,
+        port,
+        serverUrl: `http://127.0.0.1:${port}`,
+    };
+}
+export async function openCodeTaskLaunch(req, config, selected, inheritedMcpNames, env, cwd, deadline) {
+    const extra = runtimeArgs(req);
+    const policy = resolvePermissions(req, config);
+    const overlay = openCodeConfig(req, config, selected, inheritedMcpNames);
+    const patch = await verifyOverlay(overlay, selected, inheritedMcpNames, env, cwd, deadline);
+    return {
+        argv: [
+            "opencode",
+            "run",
+            "--format",
+            "json",
+            "--pure",
+            ...(policy.permissions === "auto" ? ["--auto"] : []),
+            ...extra,
+            "--",
+            req.prompt,
+        ],
+        envPatch: patch,
+    };
+}
+function parseVersion(value) {
+    const match = /^v?(\d+)\.(\d+)\.(\d+)(?:-([0-9A-Za-z.-]+))?(?:\+[0-9A-Za-z.-]+)?$/.exec(value.trim());
+    if (!match)
+        return undefined;
+    return {
+        major: Number(match[1]),
+        minor: Number(match[2]),
+        patch: Number(match[3]),
+        prerelease: match[4] !== undefined,
+    };
+}
+function atLeast(actual, minimum) {
+    for (const key of ["major", "minor", "patch"]) {
+        if (actual[key] !== minimum[key])
+            return actual[key] > minimum[key];
+    }
+    return !actual.prerelease || minimum.prerelease;
+}
+export async function assertOpenCodeVersion(env, minimum, deadline) {
+    const required = parseVersion(minimum);
+    if (!required)
+        throw new Error(`Invalid required OpenCode version: ${minimum}`);
+    let detected;
+    try {
+        const remaining = deadline - Date.now();
+        if (remaining <= 0)
+            throw new Error("deadline");
+        const { stdout } = await exec("opencode", ["--version"], {
+            env,
+            timeout: Math.min(4000, remaining),
+            maxBuffer: 64 * 1024,
+            encoding: "utf8",
+        });
+        detected = stdout.trim();
+    }
+    catch {
+        throw new Error(`OpenCode executable not found or version could not be determined; requires ${minimum}+`);
+    }
+    const actual = parseVersion(detected);
+    if (!actual)
+        throw new Error(`Unrecognized OpenCode version; requires compatible version ${minimum}+`);
+    if (!atLeast(actual, required))
+        throw new Error(`OpenCode ${detected} is unsupported; requires OpenCode ${minimum} or newer`);
+}

package/dist/reach/opencode.js

@@ -0,0 +1,17 @@
+export async function openCodeReachable(client, identity, deadline) {
+    const session = await client.session(identity.id, deadline);
+    if (session.id !== identity.id)
+        throw new Error("OpenCode session detail returned no matching session");
+    const statuses = await client.statuses(deadline);
+    const status = statuses[identity.id];
+    const rawName = session.title.trim() === "" ? null : session.title;
+    if (!status || status.type === "idle")
+        return { rawName, state: "idle" };
+    if (status.type === "retry")
+        return {
+            rawName,
+            state: "busy",
+            diagnostic: `OpenCode retry attempt ${status.attempt}: ${status.message}`,
+        };
+    return { rawName, state: "busy" };
+}