commandmate 0.49.3 → 0.50.0

package/dist/server/src/lib/agent-roles/composition.js

@@ -0,0 +1,222 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleCompositionError = void 0;
+exports.fixedEnvReader = fixedEnvReader;
+exports.readCodexDeveloperInstructions = readCodexDeveloperInstructions;
+exports.parseUserOpencodeContent = parseUserOpencodeContent;
+exports.resolveOpencodeV2EffectiveAgent = resolveOpencodeV2EffectiveAgent;
+exports.loadRoleComposition = loadRoleComposition;
+/**
+ * Reading what a role has to be composed with: the user's env value, Codex's
+ * `config.toml`, OpenCode V2's effective agent (§6.2, §7.1). Reads only; the D4
+ * rule is that an existing file of the user's is never written.
+ *
+ * A failure refuses the launch ({@link RoleCompositionError}) rather than falling
+ * through: V2 silently ignores a broken env, and overriding an agent's own `system`
+ * silently removes the user's text from the request (§7.1).
+ *
+ * ## Which environment
+ *
+ * A pane inherits the tmux server's environment, not this process's, so an
+ * interactive launch asks tmux (`./pane-env`), and with no server running the one
+ * it starts is this process's. A Schedule reads what its child gets
+ * (`sanitizeEnvForChildProcess`). What a login shell's rc adds cannot be known here.
+ *
+ * Errors name a file or a variable, never a value: these can hold API keys.
+ *
+ * @module lib/agent-roles/composition
+ */
+const fs_1 = require("fs");
+const os_1 = require("os");
+const path_1 = require("path");
+const smol_toml_1 = require("smol-toml");
+const hooks_config_1 = require("../../lib/hooks/sources/codex/hooks-config");
+const adapters_1 = require("./adapters");
+const jsonc_1 = require("./jsonc");
+class RoleCompositionError extends Error {
+    constructor(message) {
+        super(message);
+        this.name = 'RoleCompositionError';
+    }
+}
+exports.RoleCompositionError = RoleCompositionError;
+/** An agent name goes into a config key, so nothing unusual gets through unnoticed. */
+const AGENT_NAME = /^[A-Za-z0-9_.-]+$/;
+/** An env reader for a child process given exactly this environment. */
+function fixedEnvReader(env) {
+    return async (name) => env[name];
+}
+function readOptional(path) {
+    try {
+        return (0, fs_1.readFileSync)(path, 'utf8');
+    }
+    catch (error) {
+        if (error.code === 'ENOENT')
+            return null;
+        throw new RoleCompositionError(`Could not read ${path}`);
+    }
+}
+/**
+ * What a profile would otherwise replace (§6.2). Never written.
+ *
+ * @throws {RoleCompositionError} `config.toml` cannot be read, is not TOML, or holds another type there
+ */
+function readCodexDeveloperInstructions(codexHome = (0, hooks_config_1.getCodexHome)()) {
+    const path = (0, path_1.join)(codexHome, 'config.toml');
+    const text = readOptional(path);
+    if (text === null)
+        return null;
+    let parsed;
+    try {
+        parsed = (0, smol_toml_1.parse)(text);
+    }
+    catch {
+        throw new RoleCompositionError(`${path} is not valid TOML`);
+    }
+    const value = parsed.developer_instructions;
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string')
+        throw new RoleCompositionError(`developer_instructions in ${path} is not a string`);
+    return value;
+}
+/**
+ * The user's `OPENCODE_CONFIG_CONTENT`, parsed, or null when unset.
+ *
+ * @throws {RoleCompositionError} It is not a JSONC object
+ */
+function parseUserOpencodeContent(raw) {
+    if (raw === undefined || raw.trim() === '')
+        return null;
+    try {
+        return (0, jsonc_1.parseJsoncObject)(raw);
+    }
+    catch (error) {
+        throw new RoleCompositionError(`${adapters_1.OPENCODE_CONFIG_CONTENT_ENV_VAR} is ${error instanceof Error ? error.message : 'invalid'}; ` +
+            'OpenCode V2 would silently ignore it and start with no role');
+    }
+}
+/** The files read at one level of §7.1's order. */
+function readConfigLevel(paths) {
+    const files = [];
+    for (const path of paths) {
+        const text = readOptional(path);
+        if (text === null)
+            continue;
+        try {
+            files.push({ path, data: (0, jsonc_1.parseJsoncObject)(text) });
+        }
+        catch {
+            throw new RoleCompositionError(`${path} is not valid JSONC, so the effective agent cannot be worked out`);
+        }
+    }
+    return files;
+}
+function defaultAgentOf(data, where) {
+    const value = data.default_agent;
+    if (value === undefined)
+        return null;
+    if (typeof value !== 'string' || !AGENT_NAME.test(value)) {
+        throw new RoleCompositionError(`default_agent in ${where} is not a usable agent name`);
+    }
+    return value;
+}
+/**
+ * The strongest level's answer. Two files at one level saying different things have
+ * no measured order (§7.1), so that is refused rather than guessed.
+ */
+function levelDefaultAgent(files) {
+    const answers = files
+        .map((file) => ({ path: file.path, agent: defaultAgentOf(file.data, file.path) }))
+        .filter((answer) => answer.agent !== null);
+    if (new Set(answers.map((answer) => answer.agent)).size > 1) {
+        throw new RoleCompositionError(`${answers.map((answer) => answer.path).join(' and ')} name different default agents`);
+    }
+    return answers[0]?.agent ?? null;
+}
+function agentHasOwnSystem(data, agent) {
+    for (const key of ['agents', 'agent']) {
+        const agents = data[key];
+        if (typeof agents !== 'object' || agents === null)
+            continue;
+        const entry = agents[agent];
+        if (typeof entry === 'object' && entry !== null && entry.system !== undefined)
+            return true;
+    }
+    return false;
+}
+/**
+ * §7.1's order: explicit, env, project, global, `build`. Refuses an agent whose
+ * `system` the user wrote, wherever they wrote it: overriding it would drop their text.
+ *
+ * @throws {RoleCompositionError}
+ */
+function resolveOpencodeV2EffectiveAgent(input) {
+    const { explicitAgent, userContent, projectConfigs, globalConfigs } = input;
+    if (explicitAgent != null && !AGENT_NAME.test(explicitAgent)) {
+        throw new RoleCompositionError('The explicit agent is not a usable agent name');
+    }
+    const agent = explicitAgent ??
+        (userContent ? defaultAgentOf(userContent, adapters_1.OPENCODE_CONFIG_CONTENT_ENV_VAR) : null) ??
+        levelDefaultAgent(projectConfigs) ??
+        levelDefaultAgent(globalConfigs) ??
+        'build';
+    const holders = [
+        ...(userContent && agentHasOwnSystem(userContent, agent) ? [adapters_1.OPENCODE_CONFIG_CONTENT_ENV_VAR] : []),
+        ...[...projectConfigs, ...globalConfigs].filter((file) => agentHasOwnSystem(file.data, agent)).map((file) => file.path),
+    ];
+    const markdown = input.markdownDefinition(agent);
+    if (markdown)
+        holders.push(markdown);
+    if (holders.length > 0) {
+        throw new RoleCompositionError(`The agent "${agent}" has its own system text (${holders.join(', ')}); a role would remove it from the request`);
+    }
+    return agent;
+}
+const JSON_NAMES = ['opencode.json', 'opencode.jsonc'];
+async function loadOpencodeV2Agent(context, userContent) {
+    const home = (await context.readEnv('HOME')) || (0, os_1.homedir)();
+    const configHome = (await context.readEnv('XDG_CONFIG_HOME')) || (0, path_1.join)(home, '.config');
+    const globalDir = (0, path_1.join)(configHome, 'opencode');
+    const projectDirs = [context.worktreePath, (0, path_1.join)(context.worktreePath, '.opencode')];
+    return resolveOpencodeV2EffectiveAgent({
+        explicitAgent: context.explicitAgent,
+        userContent,
+        projectConfigs: readConfigLevel(projectDirs.flatMap((dir) => JSON_NAMES.map((name) => (0, path_1.join)(dir, name)))),
+        globalConfigs: readConfigLevel(JSON_NAMES.map((name) => (0, path_1.join)(globalDir, name))),
+        markdownDefinition: (agent) => {
+            const candidates = [(0, path_1.join)(context.worktreePath, '.opencode'), globalDir].flatMap((dir) => ['agents', 'agent'].map((sub) => (0, path_1.join)(dir, sub, `${agent}.md`)));
+            return candidates.find((path) => (0, fs_1.existsSync)(path)) ?? null;
+        },
+    });
+}
+/**
+ * Everything the adapter needs from the user's settings.
+ *
+ * @throws {RoleCompositionError} Anything unreadable or contradictory
+ */
+async function loadRoleComposition(adapter, context) {
+    const explicitAgent = context.explicitAgent ?? null;
+    switch (adapter) {
+        case 'codex':
+            return { explicitAgent, codexDeveloperInstructions: readCodexDeveloperInstructions(context.codexHome) };
+        case 'opencode': {
+            const opencodeUserContent = parseUserOpencodeContent(await context.readEnv(adapters_1.OPENCODE_CONFIG_CONTENT_ENV_VAR));
+            const existing = opencodeUserContent?.instructions;
+            if (existing !== undefined && !Array.isArray(existing)) {
+                throw new RoleCompositionError(`instructions in ${adapters_1.OPENCODE_CONFIG_CONTENT_ENV_VAR} is not an array`);
+            }
+            return { explicitAgent, opencodeUserContent };
+        }
+        case 'opencode-v2': {
+            const opencodeUserContent = parseUserOpencodeContent(await context.readEnv(adapters_1.OPENCODE_CONFIG_CONTENT_ENV_VAR));
+            return {
+                explicitAgent,
+                opencodeUserContent,
+                opencodeV2EffectiveAgent: await loadOpencodeV2Agent(context, opencodeUserContent),
+            };
+        }
+        default:
+            return { explicitAgent };
+    }
+}

package/dist/server/src/lib/agent-roles/fingerprint.js

@@ -0,0 +1,21 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.computeFingerprint = computeFingerprint;
+exports.computeBodyFingerprint = computeBodyFingerprint;
+/**
+ * The fingerprints of `docs/design/agent-roles-adapters.md` §5. All SHA-256, and
+ * three different things: the body fingerprint hashes the body's bytes, the
+ * artifact fingerprint hashes every byte of a generated file, and the injection
+ * fingerprint belongs to #4115's transform. They are never compared to each other.
+ *
+ * @module lib/agent-roles/fingerprint
+ */
+const crypto_1 = require("crypto");
+/** Lower-case hex SHA-256 of exactly these bytes. */
+function computeFingerprint(bytes) {
+    return (0, crypto_1.createHash)('sha256').update(bytes).digest('hex');
+}
+/** The body fingerprint: the UTF-8 bytes of the body and nothing else. */
+function computeBodyFingerprint(body) {
+    return computeFingerprint(Buffer.from(body, 'utf8'));
+}

package/dist/server/src/lib/agent-roles/jsonc.js

@@ -0,0 +1,85 @@
+"use strict";
+/**
+ * Reading the JSONC an OpenCode config is written in (§7.1): JSON with comments and
+ * trailing commas. For reading only. A failure says where, never what: the text can
+ * hold an API key.
+ *
+ * @module lib/agent-roles/jsonc
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.parseJsoncObject = parseJsoncObject;
+/** Remove comments and trailing commas, leaving strings as they are. */
+function stripJsonc(text) {
+    let out = '';
+    let index = 0;
+    while (index < text.length) {
+        const char = text[index];
+        if (char === '"') {
+            const start = index;
+            index += 1;
+            while (index < text.length && text[index] !== '"') {
+                index += text[index] === '\\' ? 2 : 1;
+            }
+            index += 1;
+            out += text.slice(start, index);
+            continue;
+        }
+        if (char === '/' && text[index + 1] === '/') {
+            while (index < text.length && text[index] !== '\n')
+                index += 1;
+            continue;
+        }
+        if (char === '/' && text[index + 1] === '*') {
+            const close = text.indexOf('*/', index + 2);
+            if (close === -1)
+                throw new Error('Unterminated comment');
+            index = close + 2;
+            continue;
+        }
+        if (char === ',') {
+            let next = index + 1;
+            for (;;) {
+                while (next < text.length && /\s/.test(text[next]))
+                    next += 1;
+                if (text[next] === '/' && text[next + 1] === '/') {
+                    while (next < text.length && text[next] !== '\n')
+                        next += 1;
+                    continue;
+                }
+                if (text[next] === '/' && text[next + 1] === '*') {
+                    const close = text.indexOf('*/', next + 2);
+                    if (close === -1)
+                        throw new Error('Unterminated comment');
+                    next = close + 2;
+                    continue;
+                }
+                break;
+            }
+            if (text[next] === '}' || text[next] === ']') {
+                index += 1;
+                continue;
+            }
+        }
+        out += char;
+        index += 1;
+    }
+    return out;
+}
+/**
+ * Parse a JSONC document that must be an object.
+ *
+ * @throws Error when it is not, with a message that quotes nothing from the text
+ */
+function parseJsoncObject(text) {
+    let parsed;
+    try {
+        parsed = JSON.parse(stripJsonc(text));
+    }
+    catch {
+        throw new Error('not valid JSONC');
+    }
+    if (typeof parsed !== 'object' || parsed === null || Array.isArray(parsed)) {
+        throw new Error('not a JSON object');
+    }
+    return parsed;
+}

package/dist/server/src/lib/agent-roles/launch-errors.js

@@ -0,0 +1,58 @@
+"use strict";
+/**
+ * Why a launch or a send was refused because of its role (Issue #4115). No imports
+ * beyond types, so the send service, the routes and the drivers can all read it.
+ *
+ * A tool driver wraps what its launch threw in `new Error('Failed to start …: msg')`,
+ * which keeps the message and drops the class. So the message carries the reason in
+ * a fixed form and {@link readRoleLaunchRefusal} reads either, as the session-start
+ * errors do. The message never holds a role's body, only names and paths.
+ *
+ * @module lib/agent-roles/launch-errors
+ */
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.RoleConditionUnmetError = exports.RoleLaunchRefusedError = exports.SESSION_LAUNCH_ROLE_MISMATCH_CODE = exports.ROLE_CONDITION_UNMET_CODE = exports.ROLE_LAUNCH_REFUSED_CODE = void 0;
+exports.readRoleLaunchRefusal = readRoleLaunchRefusal;
+exports.isRoleConditionUnmet = isRoleConditionUnmet;
+/** The stable code of a launch refused because of its role. Nothing was typed. */
+exports.ROLE_LAUNCH_REFUSED_CODE = 'ROLE_LAUNCH_REFUSED';
+/** The stable code of a send whose role condition does not hold. Nothing was typed. */
+exports.ROLE_CONDITION_UNMET_CODE = 'ROLE_CONDITION_UNMET';
+/** The stable code of a start refused because another start is running with another role. */
+exports.SESSION_LAUNCH_ROLE_MISMATCH_CODE = 'SESSION_LAUNCH_ROLE_MISMATCH';
+const MARK = /\(role launch refused: ([a-z-]+)\)/;
+/** A launch that did not happen because of its role. Nothing was typed. */
+class RoleLaunchRefusedError extends Error {
+    reason;
+    code = exports.ROLE_LAUNCH_REFUSED_CODE;
+    constructor(reason, message) {
+        super(`${message} (role launch refused: ${reason})`);
+        this.reason = reason;
+        this.name = 'RoleLaunchRefusedError';
+    }
+}
+exports.RoleLaunchRefusedError = RoleLaunchRefusedError;
+/** The reason when `error` is, or wraps the message of, a {@link RoleLaunchRefusedError}. */
+function readRoleLaunchRefusal(error) {
+    if (error instanceof RoleLaunchRefusedError)
+        return error.reason;
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
+    const match = MARK.exec(message);
+    return match ? match[1] : null;
+}
+/** A condition on a send's role did not hold right before the body. Nothing was typed. */
+class RoleConditionUnmetError extends Error {
+    code = exports.ROLE_CONDITION_UNMET_CODE;
+    constructor(message) {
+        super(`${message} (${exports.ROLE_CONDITION_UNMET_CODE})`);
+        this.name = 'RoleConditionUnmetError';
+    }
+}
+exports.RoleConditionUnmetError = RoleConditionUnmetError;
+/** Whether `error` is, or wraps the message of, a {@link RoleConditionUnmetError}. */
+function isRoleConditionUnmet(error) {
+    if (error instanceof RoleConditionUnmetError)
+        return true;
+    const message = error instanceof Error ? error.message : typeof error === 'string' ? error : '';
+    return message.includes(`(${exports.ROLE_CONDITION_UNMET_CODE})`);
+}

package/dist/server/src/lib/agent-roles/pane-env.js

@@ -0,0 +1,63 @@
+"use strict";
+Object.defineProperty(exports, "__esModule", { value: true });
+exports.tmuxPaneEnvReader = tmuxPaneEnvReader;
+exports.roleEnvReaderForPane = roleEnvReaderForPane;
+exports.loadPaneComposition = loadPaneComposition;
+/**
+ * Reading the environment a pane will have (§7.1). Apart from `./composition`
+ * because this is the one part of composing a role that runs tmux: a Schedule and
+ * the contract check never need it, and importing it would give every route they
+ * are reached from a path to tmux.
+ *
+ * Read-only. It names a session only to read one variable of its environment.
+ *
+ * @module lib/agent-roles/pane-env
+ */
+const child_process_1 = require("child_process");
+const session_name_1 = require("../../lib/cli-tools/session-name");
+const test_run_detection_1 = require("../../lib/test-run-detection");
+const composition_1 = require("./composition");
+/**
+ * An env reader for a pane: the session's own value, then the tmux server's, and
+ * with no server the environment the server about to start would be given.
+ */
+function tmuxPaneEnvReader(sessionName, fallback = process.env) {
+    const show = (args) => new Promise((resolve) => {
+        (0, child_process_1.execFile)('tmux', ['show-environment', ...args], { timeout: 5000 }, (error, stdout, stderr) => {
+            if (!error) {
+                // `-NAME` says it was removed from the environment.
+                const line = stdout.replace(/\n$/, '');
+                const equals = line.indexOf('=');
+                resolve(line.startsWith('-') || equals === -1 ? { kind: 'absent' } : { kind: 'set', value: line.slice(equals + 1) });
+                return;
+            }
+            const text = String(stderr);
+            resolve(/no server running|error connecting/i.test(text) ? { kind: 'no-server' } : { kind: 'absent' });
+        });
+    });
+    return async (name) => {
+        const own = await show(['-t', `=${sessionName}`, name]);
+        if (own.kind === 'set')
+            return own.value;
+        const global = await show(['-g', name]);
+        if (global.kind === 'set')
+            return global.value;
+        return global.kind === 'no-server' ? fallback[name] : undefined;
+    };
+}
+/**
+ * The reader for one instance's pane. In a test run, this process's environment: no
+ * test reaches a real tmux server from here.
+ */
+function roleEnvReaderForPane(target) {
+    if ((0, test_run_detection_1.isUnderTest)())
+        return (0, composition_1.fixedEnvReader)(process.env);
+    return tmuxPaneEnvReader((0, session_name_1.resolveSessionName)(target.cliToolId, target.worktreeId, target.instanceId));
+}
+/** The user's settings, as this instance's pane sees them: its session can have its own env. */
+function loadPaneComposition(worktreeId, cliToolId, instanceId, worktreePath) {
+    return (0, composition_1.loadRoleComposition)(cliToolId, {
+        worktreePath,
+        readEnv: roleEnvReaderForPane({ worktreeId, cliToolId, instanceId }),
+    });
+}