@dfsramos/foreman 0.0.0-stage → 0.3.0

package/dist/agent/adapters/claude.js

@@ -0,0 +1,152 @@
+import { listSetting, textSetting, truncate, } from '../types.js';
+function toolResultText(content) {
+    if (typeof content === 'string')
+        return content;
+    if (Array.isArray(content)) {
+        return content
+            .map((part) => (typeof part?.text === 'string' ? part.text : ''))
+            .filter(Boolean)
+            .join('\n');
+    }
+    return content === undefined ? '' : JSON.stringify(content);
+}
+/**
+ * Reads a `rate_limit_event`. This event is not documented; its shape was taken from the output of
+ * CLI 2.1.291, so anything unexpected is ignored rather than trusted.
+ */
+function parseUsage(info) {
+    const windows = {};
+    for (const [name, window] of Object.entries(info?.unifiedWindows ?? {})) {
+        if (typeof window?.utilization !== 'number' || !Number.isFinite(window.utilization))
+            continue;
+        windows[name] = {
+            utilization: window.utilization,
+            resetsAt: typeof window.resetsAt === 'number' ? new Date(window.resetsAt * 1000).toISOString() : null,
+        };
+    }
+    if (Object.keys(windows).length === 0)
+        return null;
+    return { windows, usingOverage: info?.isUsingOverage === true, at: new Date().toISOString() };
+}
+const PERMISSION_MODES = ['acceptEdits', 'bypassPermissions', 'default'];
+/** Claude Code: `claude -p` with stream-json output and an allow-list of tools. */
+export const claudeAdapter = {
+    id: 'claude',
+    name: 'Claude Code',
+    defaultBin: 'claude',
+    versionArgs: ['--version'],
+    // `claude auth status` prints JSON with `loggedIn` and exits 1 when signed out (CLI 2.1.307).
+    signIn: {
+        args: ['auth', 'status'],
+        parse(stdout) {
+            try {
+                const status = JSON.parse(stdout);
+                return typeof status.loggedIn === 'boolean' ? status.loggedIn : null;
+            }
+            catch {
+                return null;
+            }
+        },
+    },
+    verified: true,
+    reportsUsage: true,
+    fields: [
+        {
+            key: 'permissionMode',
+            label: 'Permission mode',
+            type: 'select',
+            options: PERMISSION_MODES,
+            help: 'acceptEdits allows file edits; anything else needs a rule below. bypassPermissions allows everything.',
+        },
+        {
+            key: 'allowedTools',
+            label: 'Allowed tools',
+            type: 'list',
+            help: 'Passed as --allowedTools, e.g. Bash(git:*)',
+        },
+    ],
+    defaultSettings: {
+        permissionMode: 'acceptEdits',
+        allowedTools: [
+            'Read',
+            'Glob',
+            'Grep',
+            'Edit',
+            'Write',
+            'Skill',
+            'Task',
+            'TodoWrite',
+            'Bash(git:*)',
+            'Bash(gh pr:*)',
+            'Bash(npm:*)',
+            'Bash(npx:*)',
+            'Bash(node:*)',
+        ],
+    },
+    requiresResult: true,
+    buildCommand({ prompt, settings }) {
+        const mode = textSetting(settings, 'permissionMode', 'acceptEdits');
+        const tools = listSetting(settings, 'allowedTools');
+        const args = ['-p', '--output-format', 'stream-json', '--verbose', '--permission-mode', mode];
+        if (tools.length > 0)
+            args.push('--allowedTools', ...tools);
+        return { args, stdin: prompt };
+    },
+    createParser() {
+        let parsed = null;
+        let lastAssistantText = null;
+        let usage = null;
+        return {
+            push(line) {
+                const events = [];
+                let message;
+                try {
+                    message = JSON.parse(line);
+                }
+                catch {
+                    return [{ kind: 'foreman', text: `unparsed output: ${truncate(line)}` }];
+                }
+                const content = Array.isArray(message.message?.content) ? message.message.content : [];
+                if (message.type === 'assistant') {
+                    for (const block of content) {
+                        if (block.type === 'text' && typeof block.text === 'string') {
+                            lastAssistantText = block.text;
+                            events.push({ kind: 'assistant', text: block.text });
+                        }
+                        else if (block.type === 'tool_use') {
+                            events.push({ kind: 'tool_use', text: `${block.name ?? 'tool'} ${truncate(JSON.stringify(block.input ?? {}))}` });
+                        }
+                    }
+                }
+                else if (message.type === 'user') {
+                    for (const block of content) {
+                        if (block.type === 'tool_result') {
+                            events.push({ kind: 'tool_result', text: truncate(toolResultText(block.content)) });
+                        }
+                    }
+                }
+                else if (message.type === 'rate_limit_event') {
+                    usage = parseUsage(message.rate_limit_info) ?? usage;
+                }
+                else if (message.type === 'result') {
+                    parsed = {
+                        isError: message.is_error === true,
+                        resultText: typeof message.result === 'string' ? message.result : null,
+                        costUsd: typeof message.total_cost_usd === 'number' ? message.total_cost_usd : null,
+                        numTurns: typeof message.num_turns === 'number' ? message.num_turns : null,
+                    };
+                    // The result normally repeats the agent's last message; logging it twice is noise.
+                    if (parsed.resultText !== lastAssistantText || parsed.isError) {
+                        events.push({
+                            kind: 'result',
+                            text: parsed.resultText ?? `Agent finished (${String(message.subtype ?? 'no result text')})`,
+                        });
+                    }
+                }
+                return events;
+            },
+            result: () => parsed,
+            usage: () => usage,
+        };
+    },
+};

package/dist/agent/adapters/codex.js

@@ -0,0 +1,107 @@
+import { listSetting, textSetting, truncate } from '../types.js';
+const SANDBOX_MODES = ['danger-full-access', 'workspace-write', 'read-only'];
+/**
+ * OpenAI Codex CLI: `codex exec --json`, prompt on stdin.
+ *
+ * Written from the documentation and the event definitions in the CLI's source
+ * (codex-rs/exec/src/exec_events.rs); not yet run against the real CLI. The exact nesting of
+ * items inside events was not confirmed, so the parser accepts an item either under `item` or
+ * at the top level.
+ */
+export const codexAdapter = {
+    id: 'codex',
+    name: 'Codex CLI',
+    defaultBin: 'codex',
+    versionArgs: ['--version'],
+    verified: false,
+    notes: [
+        'The workspace-write sandbox keeps .git read-only and blocks the network, so commit, push and gh fail under it. danger-full-access removes the sandbox entirely.',
+        'Reports token usage but not cost or turn count.',
+    ],
+    fields: [
+        {
+            key: 'sandbox',
+            label: 'Sandbox',
+            type: 'select',
+            options: SANDBOX_MODES,
+            help: 'Passed as --sandbox. Only danger-full-access can commit and push from a worktree.',
+        },
+        {
+            key: 'networkAccess',
+            label: 'Network in workspace-write',
+            type: 'select',
+            options: ['off', 'on'],
+            help: 'Sets sandbox_workspace_write.network_access; ignored in the other modes.',
+        },
+        { key: 'extraArgs', label: 'Extra arguments', type: 'list', help: 'Appended to codex exec, one argument per row.' },
+    ],
+    defaultSettings: { sandbox: 'danger-full-access', networkAccess: 'off', extraArgs: [] },
+    requiresResult: false,
+    buildCommand({ prompt, settings }) {
+        const sandbox = textSetting(settings, 'sandbox', 'danger-full-access');
+        const args = ['exec', '--json', '--sandbox', sandbox];
+        if (sandbox === 'workspace-write' && textSetting(settings, 'networkAccess', 'off') === 'on') {
+            args.push('-c', 'sandbox_workspace_write.network_access=true');
+        }
+        args.push(...listSetting(settings, 'extraArgs'));
+        // "-" makes codex read the whole prompt from stdin.
+        args.push('-');
+        return { args, stdin: prompt };
+    },
+    createParser() {
+        let parsed = null;
+        let lastMessage = null;
+        const fail = (message) => {
+            parsed = { isError: true, resultText: message, costUsd: null, numTurns: null };
+        };
+        return {
+            push(line) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    return [{ kind: 'foreman', text: `unparsed output: ${truncate(line)}` }];
+                }
+                const events = [];
+                const type = event.type ?? '';
+                if (type.startsWith('item.')) {
+                    const item = event.item ?? event;
+                    if (item.type === 'agent_message' && type === 'item.completed' && typeof item.text === 'string') {
+                        lastMessage = item.text;
+                        events.push({ kind: 'assistant', text: item.text });
+                    }
+                    else if (item.type === 'command_execution') {
+                        if (type === 'item.started') {
+                            events.push({ kind: 'tool_use', text: `shell ${truncate(String(item.command ?? ''))}` });
+                        }
+                        else if (type === 'item.completed') {
+                            const exit = item.exit_code === null || item.exit_code === undefined ? '' : `exit ${item.exit_code}\n`;
+                            events.push({ kind: 'tool_result', text: truncate(`${exit}${item.aggregated_output ?? ''}`.trim() || (item.status ?? 'done')) });
+                        }
+                    }
+                    else if (type === 'item.completed' && (item.type === 'file_change' || item.type === 'mcp_tool_call' || item.type === 'web_search')) {
+                        const { type: itemType, ...rest } = item;
+                        events.push({ kind: 'tool_use', text: `${itemType} ${truncate(JSON.stringify(rest))}` });
+                    }
+                    else if (type === 'item.completed' && item.type === 'error') {
+                        events.push({ kind: 'foreman', text: `codex: ${truncate(String(item.message ?? 'error'))}` });
+                    }
+                }
+                else if (type === 'turn.completed') {
+                    parsed = { isError: false, resultText: lastMessage, costUsd: null, numTurns: null };
+                }
+                else if (type === 'turn.failed') {
+                    fail(event.error?.message ?? 'Turn failed');
+                    events.push({ kind: 'result', text: parsed.resultText ?? 'Turn failed' });
+                }
+                else if (type === 'error') {
+                    fail(event.message ?? event.error?.message ?? 'Codex reported an error');
+                    events.push({ kind: 'result', text: parsed.resultText ?? 'error' });
+                }
+                return events;
+            },
+            result: () => parsed,
+        };
+    },
+};

package/dist/agent/adapters/opencode.js

@@ -0,0 +1,91 @@
+import { listSetting, textSetting, truncate } from '../types.js';
+/**
+ * opencode: `opencode run --format json`, prompt on stdin.
+ *
+ * Written from the documentation and the `run` command's source; not yet run against the real
+ * CLI. The event envelope (`type`, `timestamp`, `sessionID`) is confirmed from source, but where
+ * each event keeps its payload is not, so the parser looks under `part` and at the top level.
+ * There is no final result event: success is the exit code and the absence of an `error` event.
+ */
+export const opencodeAdapter = {
+    id: 'opencode',
+    name: 'opencode',
+    defaultBin: 'opencode',
+    versionArgs: ['--version'],
+    verified: false,
+    notes: [
+        'Has no sandbox. Its permission config decides what runs without asking; anything set to "ask" is rejected in a headless run unless auto-approve is on.',
+        'Starts a local server for the duration of each run.',
+    ],
+    fields: [
+        {
+            key: 'autoApprove',
+            label: 'Auto-approve',
+            type: 'select',
+            options: ['off', 'on'],
+            help: 'Passes --auto, approving every permission that is not explicitly denied.',
+        },
+        {
+            key: 'permission',
+            label: 'Permission config (JSON)',
+            type: 'text',
+            help: 'Passed in OPENCODE_PERMISSION, e.g. {"bash":{"*":"deny","git *":"allow","gh pr *":"allow"}}. Empty uses your opencode config.',
+        },
+        { key: 'extraArgs', label: 'Extra arguments', type: 'list', help: 'Appended to opencode run, one argument per row.' },
+    ],
+    defaultSettings: { autoApprove: 'on', permission: '', extraArgs: [] },
+    requiresResult: false,
+    buildCommand({ prompt, settings }) {
+        const args = ['run', '--format', 'json'];
+        if (textSetting(settings, 'autoApprove', 'on') === 'on')
+            args.push('--auto');
+        args.push(...listSetting(settings, 'extraArgs'));
+        const permission = textSetting(settings, 'permission');
+        // opencode reads the message from stdin when it is not a terminal.
+        return { args, stdin: prompt, ...(permission ? { env: { OPENCODE_PERMISSION: permission } } : {}) };
+    },
+    createParser() {
+        let error = null;
+        let lastText = null;
+        let finished = false;
+        return {
+            push(line) {
+                let event;
+                try {
+                    event = JSON.parse(line);
+                }
+                catch {
+                    return [{ kind: 'foreman', text: `unparsed output: ${truncate(line)}` }];
+                }
+                const part = event.part ?? event;
+                const events = [];
+                if (event.type === 'text' && typeof part.text === 'string') {
+                    lastText = part.text;
+                    events.push({ kind: 'assistant', text: part.text });
+                }
+                else if (event.type === 'tool_use') {
+                    // The call and its result arrive together, once the tool has finished.
+                    events.push({ kind: 'tool_use', text: `${part.tool ?? 'tool'} ${truncate(JSON.stringify(part.state?.input ?? {}))}` });
+                    const output = part.state?.error ?? part.state?.output;
+                    if (output !== undefined) {
+                        events.push({ kind: 'tool_result', text: truncate(typeof output === 'string' ? output : JSON.stringify(output)) });
+                    }
+                }
+                else if (event.type === 'step_finish') {
+                    finished = true;
+                }
+                else if (event.type === 'error') {
+                    const detail = event.error ?? event.message ?? 'opencode reported an error';
+                    error = typeof detail === 'string' ? detail : JSON.stringify(detail);
+                    events.push({ kind: 'result', text: truncate(error) });
+                }
+                return events;
+            },
+            result() {
+                if (error !== null)
+                    return { isError: true, resultText: error, costUsd: null, numTurns: null };
+                return finished ? { isError: false, resultText: lastText, costUsd: null, numTurns: null } : null;
+            },
+        };
+    },
+};

package/dist/agent/config.js

@@ -0,0 +1,169 @@
+import path from 'node:path';
+import { ADAPTERS, probeAgent } from './registry.js';
+export const MAX_CONCURRENT_LIMIT = 16;
+const SETTINGS_KEY = 'agents';
+/** Where the claude allow-list lived before agents had their own settings. */
+const LEGACY_ALLOWED_TOOLS_KEY = 'agentAllowedTools';
+export const DEFAULT_MAX_USAGE_PERCENT = 90;
+const USAGE_DEFAULTS = { maxUsagePercent: DEFAULT_MAX_USAGE_PERCENT, allowOverage: false };
+function defaultEntry(adapter, env, legacyTools) {
+    if (adapter.id !== 'claude') {
+        // Other CLIs are opt-in: they run with write and network access under adapters that may be unverified.
+        return { enabled: false, maxConcurrent: 1, ...USAGE_DEFAULTS, settings: structuredClone(adapter.defaultSettings) };
+    }
+    const tools = Array.isArray(legacyTools) && legacyTools.every((tool) => typeof tool === 'string') ? legacyTools : env.agentAllowedTools;
+    return {
+        enabled: true,
+        maxConcurrent: 1,
+        ...USAGE_DEFAULTS,
+        ...(env.claudeBin !== adapter.defaultBin ? { bin: env.claudeBin } : {}),
+        settings: { ...structuredClone(adapter.defaultSettings), allowedTools: [...tools] },
+    };
+}
+/** The stored agents configuration, completed with defaults for adapters it does not mention yet. */
+export function loadAgentsConfig(db, env, adapters = ADAPTERS) {
+    const stored = db.getSetting(SETTINGS_KEY);
+    const legacyTools = stored ? undefined : db.getSetting(LEGACY_ALLOWED_TOOLS_KEY);
+    const known = new Set(adapters.map((adapter) => adapter.id));
+    const agents = {};
+    for (const adapter of adapters) {
+        const entry = stored?.agents?.[adapter.id];
+        const fallback = defaultEntry(adapter, env, legacyTools);
+        agents[adapter.id] = entry ? { ...fallback, ...entry, settings: { ...fallback.settings, ...entry.settings } } : fallback;
+    }
+    const order = [...new Set([...(stored?.order ?? []).filter((id) => known.has(id)), ...adapters.map((adapter) => adapter.id)])];
+    const config = { order, agents };
+    if (!stored && legacyTools !== undefined) {
+        // One-time migration of an allow-list saved through the old Config tab.
+        db.setSetting(SETTINGS_KEY, config);
+        db.deleteSetting(LEGACY_ALLOWED_TOOLS_KEY);
+    }
+    return config;
+}
+function validateSettings(adapter, value, errors) {
+    const settings = {};
+    if (typeof value !== 'object' || value === null || Array.isArray(value)) {
+        errors[`${adapter.id}.settings`] = 'must be an object';
+        return settings;
+    }
+    const fields = new Map(adapter.fields.map((field) => [field.key, field]));
+    for (const [key, raw] of Object.entries(value)) {
+        const field = fields.get(key);
+        const where = `${adapter.id}.settings.${key}`;
+        if (!field) {
+            errors[where] = 'is not a setting of this agent';
+        }
+        else if (field.type === 'list') {
+            if (!Array.isArray(raw) || raw.some((item) => typeof item !== 'string')) {
+                errors[where] = 'must be a list of strings';
+            }
+            else {
+                const items = raw.map((item) => item.trim()).filter((item) => item.length > 0);
+                if (new Set(items).size !== items.length)
+                    errors[where] = 'must not contain duplicates';
+                settings[key] = items;
+            }
+        }
+        else if (typeof raw !== 'string') {
+            errors[where] = 'must be text';
+        }
+        else if (field.type === 'select' && !field.options?.includes(raw)) {
+            errors[where] = `must be one of: ${field.options?.join(', ')}`;
+        }
+        else {
+            settings[key] = raw.trim();
+        }
+    }
+    return settings;
+}
+/** Validates and stores an agents configuration. Returns the stored value, or what is wrong with the input. */
+export function saveAgentsConfig(db, input, adapters = ADAPTERS) {
+    const errors = {};
+    const body = input;
+    if (typeof body !== 'object' || body === null || typeof body.agents !== 'object' || body.agents === null || !Array.isArray(body.order)) {
+        return { errors: { _: 'Request body must be { order: [...], agents: {...} }' } };
+    }
+    const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
+    for (const id of Object.keys(body.agents)) {
+        if (!byId.has(id))
+            errors[id] = 'is not a known agent';
+    }
+    const order = body.order.filter((id) => typeof id === 'string');
+    if (order.length !== adapters.length || new Set(order).size !== order.length || order.some((id) => !byId.has(id))) {
+        errors.order = 'must list every known agent exactly once';
+    }
+    const agents = {};
+    for (const adapter of adapters) {
+        const raw = body.agents[adapter.id];
+        if (typeof raw !== 'object' || raw === null) {
+            errors[adapter.id] = 'is missing';
+            continue;
+        }
+        if (typeof raw.enabled !== 'boolean')
+            errors[`${adapter.id}.enabled`] = 'must be true or false';
+        const max = raw.maxConcurrent;
+        if (typeof max !== 'number' || !Number.isInteger(max) || max < 0 || max > MAX_CONCURRENT_LIMIT) {
+            errors[`${adapter.id}.maxConcurrent`] = `must be a whole number between 0 and ${MAX_CONCURRENT_LIMIT}`;
+        }
+        const maxUsage = raw.maxUsagePercent ?? null;
+        if (maxUsage !== null && (typeof maxUsage !== 'number' || !Number.isInteger(maxUsage) || maxUsage < 1 || maxUsage > 100)) {
+            errors[`${adapter.id}.maxUsagePercent`] = 'must be a whole number between 1 and 100, or empty';
+        }
+        if (raw.allowOverage !== undefined && typeof raw.allowOverage !== 'boolean') {
+            errors[`${adapter.id}.allowOverage`] = 'must be true or false';
+        }
+        if (raw.bin !== undefined && typeof raw.bin !== 'string')
+            errors[`${adapter.id}.bin`] = 'must be text';
+        const bin = typeof raw.bin === 'string' ? raw.bin.trim() : '';
+        if (bin.includes(path.sep) && !path.isAbsolute(bin))
+            errors[`${adapter.id}.bin`] = 'must be a command name or an absolute path';
+        agents[adapter.id] = {
+            enabled: raw.enabled === true,
+            maxConcurrent: typeof max === 'number' ? max : 0,
+            maxUsagePercent: typeof maxUsage === 'number' ? maxUsage : null,
+            allowOverage: raw.allowOverage === true,
+            ...(bin ? { bin } : {}),
+            settings: validateSettings(adapter, raw.settings ?? {}, errors),
+        };
+    }
+    if (Object.keys(errors).length > 0)
+        return { errors };
+    const config = { order, agents };
+    db.setSetting(SETTINGS_KEY, config);
+    return { config };
+}
+export function createAvailability(adapters = ADAPTERS, probe = probeAgent) {
+    const results = new Map();
+    return {
+        async refresh(config) {
+            const probed = await Promise.all(adapters.map(async (adapter) => [adapter.id, await probe(adapter, config.agents[adapter.id]?.bin)]));
+            for (const [id, result] of probed)
+                results.set(id, result);
+        },
+        get: (id) => results.get(id),
+    };
+}
+/** Agents in preference order, combining configuration with what was found installed. */
+export function resolveAgents(config, availability, adapters = ADAPTERS) {
+    const byId = new Map(adapters.map((adapter) => [adapter.id, adapter]));
+    return config.order.flatMap((id) => {
+        const adapter = byId.get(id);
+        const entry = config.agents[id];
+        if (!adapter || !entry)
+            return [];
+        const probe = availability.get(id);
+        return [
+            {
+                id,
+                adapter,
+                bin: probe?.available ? probe.bin : (entry.bin ?? adapter.defaultBin),
+                enabled: entry.enabled,
+                available: probe?.available ?? false,
+                maxConcurrent: entry.maxConcurrent,
+                maxUsagePercent: entry.maxUsagePercent ?? null,
+                allowOverage: entry.allowOverage ?? false,
+                settings: entry.settings,
+            },
+        ];
+    });
+}