A desktop coding agent with free access to frontier models.
TypeScript
/**
* Pre-flight compatibility check for user-owned OpenCode config files, for
* the bundled 1.x engine (or OMNIRUSH_OPENCODE_BIN).
*
* A 1.x engine (OpenCode V1) lowers V2-style
* config on load (packages/opencode/src/config/v2-compat.ts). Most V2 keys
* degrade to a "configuration compatibility diagnostic" warning, but a
* `permissions` key — top-level, or under `agent`/`agents`/`mode.<name>` — is
* fatal since 1.18.32: the engine throws ConfigInvalidError. In the global
* config that aborts `opencode serve` at boot (exit 1); in a workspace config
* every instance-scoped route for that directory answers 400 ConfigInvalidError.
*
* This module mirrors that one fatal rule so the server can name the file and
* the offending keys before the engine is spawned, and translates the engine's
* ConfigInvalidError response body into an actionable API error instead of a
* generic opencode_request_failed.
*/
import { join } from "node:path";
import { globalOpencodeConfigDir, workspaceOpencodeConfigCandidates } from "@omnirush/paths";
import { readJsoncFile } from "./jsonc.js";
export const OPENCODE_V2_PERMISSIONS_MESSAGE =
'V2 permissions are not supported by OmniRush V1. Use V1 "permission" rules or run opencode2.';
export const OPENCODE_CONFIG_COMPAT_HINT =
'Rename "permissions" to "permission" (OmniRush V1 rules) or remove it, then restart OmniRush.ai.';
export type OpencodeConfigCompatScope = "global" | "workspace";
export type OpencodeConfigCompatIssue = { path: string[]; message: string };
export type OpencodeConfigCompatFinding = {
/** "global" files abort the engine at boot; "workspace" files break that directory's instance. */
scope: OpencodeConfigCompatScope;
file: string;
issues: OpencodeConfigCompatIssue[];
};
export type OpencodeConfigErrorBody = {
name: string;
file: string | null;
message: string;
issues: OpencodeConfigCompatIssue[];
};
type CompatLogger = {
log: (level: "warn" | "error", message: string, attributes?: Record<string, unknown>) => void;
};
/** Engine error names the HTTP error middleware answers with status 400 and `{ name, data }`. */
const OPENCODE_CONFIG_ERROR_NAMES = new Set([
"ConfigInvalidError",
"ConfigJsonError",
"ConfigFrontmatterError",
"ConfigDirectoryTypoError",
]);
function isRecord(value: unknown): value is Record<string, unknown> {
return typeof value === "object" && value !== null && !Array.isArray(value);
}
/**
* Mirror of the engine's fatal rule in ConfigV2Compat.lower: a `permissions`
* key at the top level or directly under any `agents`/`agent`/`mode` entry.
* Key presence is what the engine checks, so the value is irrelevant.
*/
export function findUnsupportedV2PermissionPaths(config: unknown): string[][] {
if (!isRecord(config)) return [];
const paths: string[][] = [];
if (Object.hasOwn(config, "permissions")) paths.push(["permissions"]);
for (const key of ["agents", "agent", "mode"]) {
const agents = config[key];
if (!isRecord(agents)) continue;
for (const [name, agent] of Object.entries(agents)) {
if (isRecord(agent) && Object.hasOwn(agent, "permissions")) paths.push([key, name, "permissions"]);
}
}
return paths;
}
/** Files the engine merges into its global config at boot, in load order. */
export function globalOpencodeConfigFiles(env: NodeJS.ProcessEnv = process.env): string[] {
const dir = globalOpencodeConfigDir({ env });
return ["config.json", "opencode.json", "opencode.jsonc"].map((name) => join(dir, name));
}
/** Files the engine merges into a workspace instance's config. */
export function workspaceOpencodeConfigFiles(workspaceRoot: string): string[] {
return workspaceOpencodeConfigCandidates(workspaceRoot);
}
export async function inspectOpencodeConfigFile(
scope: OpencodeConfigCompatScope,
file: string,
): Promise<OpencodeConfigCompatFinding | null> {
let data: unknown;
try {
// Unreadable or malformed files are the engine's own (pre-existing)
// ConfigJsonError; this check only covers the rule introduced by 1.18.32.
const result = await readJsoncFile<unknown>(file, null, { allowInvalid: true });
if (result.missing || result.invalid) return null;
data = result.data;
} catch {
return null;
}
const paths = findUnsupportedV2PermissionPaths(data);
if (paths.length === 0) return null;
return {
scope,
file,
issues: paths.map((path) => ({ path, message: OPENCODE_V2_PERMISSIONS_MESSAGE })),
};
}
export async function diagnoseOpencodeConfigCompat(input: {
workspaceRoots?: string[];
env?: NodeJS.ProcessEnv;
}): Promise<OpencodeConfigCompatFinding[]> {
const env = input.env ?? process.env;
const targets: Array<{ scope: OpencodeConfigCompatScope; file: string }> = [
...globalOpencodeConfigFiles(env).map((file) => ({ scope: "global" as const, file })),
];
const seenRoots = new Set<string>();
for (const root of input.workspaceRoots ?? []) {
const trimmed = root.trim();
if (!trimmed || seenRoots.has(trimmed)) continue;
seenRoots.add(trimmed);
for (const file of workspaceOpencodeConfigFiles(trimmed)) targets.push({ scope: "workspace", file });
}
const findings = await Promise.all(targets.map(({ scope, file }) => inspectOpencodeConfigFile(scope, file)));
return findings.filter((finding): finding is OpencodeConfigCompatFinding => finding !== null);
}
function formatIssues(issues: OpencodeConfigCompatIssue[]): string {
return issues.map((issue) => `${issue.message} (${issue.path.join(".")})`).join("; ");
}
/** Same wording the engine prints when it refuses the file, plus the OmniRush.ai fix. */
export function formatOpencodeConfigCompatFinding(finding: OpencodeConfigCompatFinding): string {
return `Configuration is invalid at ${finding.file}: ${formatIssues(finding.issues)}`;
}
export function opencodeConfigCompatLogAttributes(finding: OpencodeConfigCompatFinding): Record<string, unknown> {
return {
"opencode.config.scope": finding.scope,
"opencode.config.file": finding.file,
"opencode.config.issues": finding.issues.map((issue) => issue.path.join(".")).join(","),
"opencode.config.message": OPENCODE_V2_PERMISSIONS_MESSAGE,
};
}
export class OpencodeConfigCompatError extends Error {
readonly code = "opencode_config_invalid";
readonly findings: OpencodeConfigCompatFinding[];
constructor(findings: OpencodeConfigCompatFinding[]) {
super([
"OmniRush cannot start with the current global configuration.",
...findings.map(formatOpencodeConfigCompatFinding),
OPENCODE_CONFIG_COMPAT_HINT,
].join("\n"));
this.name = "OpencodeConfigCompatError";
this.findings = findings;
}
}
/**
* Run before spawning the managed engine. Global findings throw (the engine
* would exit at boot anyway, with the same message buried in its stderr);
* workspace findings only log, because the engine boots and other workspaces
* keep working — that workspace's routes surface opencode_config_invalid.
*/
export async function assertOpencodeConfigCompat(input: {
workspaceRoots?: string[];
env?: NodeJS.ProcessEnv;
logger?: CompatLogger;
}): Promise<OpencodeConfigCompatFinding[]> {
const findings = await diagnoseOpencodeConfigCompat(input);
const fatal = findings.filter((finding) => finding.scope === "global");
for (const finding of findings) {
input.logger?.log(
finding.scope === "global" ? "error" : "warn",
finding.scope === "global"
? "OmniRush global configuration uses V2 permissions; the bundled engine refuses to start."
: "OmniRush workspace configuration uses V2 permissions; the engine will reject that workspace.",
opencodeConfigCompatLogAttributes(finding),
);
}
if (fatal.length > 0) throw new OpencodeConfigCompatError(fatal);
return findings;
}
/**
* Parse the body of an engine config error (`{ name: "ConfigInvalidError",
* data: { path, issues?, message? } }`, HTTP 400) into an actionable message.
* Returns null for anything else so callers keep their generic mapping.
*/
export function parseOpencodeConfigErrorBody(body: unknown): OpencodeConfigErrorBody | null {
if (!isRecord(body) || typeof body.name !== "string" || !OPENCODE_CONFIG_ERROR_NAMES.has(body.name)) return null;
const data = isRecord(body.data) ? body.data : {};
const file = typeof data.path === "string" && data.path && data.path !== "config" ? data.path : null;
const detail = typeof data.message === "string" ? data.message.trim() : "";
const issues: OpencodeConfigCompatIssue[] = Array.isArray(data.issues)
? data.issues.flatMap((issue) => {
if (!isRecord(issue) || typeof issue.message !== "string") return [];
const path = Array.isArray(issue.path) ? issue.path.filter((segment): segment is string => typeof segment === "string") : [];
return [{ path, message: issue.message }];
})
: [];
const parts = [detail, formatIssues(issues)].filter(Boolean);
const message = `OmniRush configuration is invalid${file ? ` at ${file}` : ""}${parts.length ? `: ${parts.join("; ")}` : ""}`;
return { name: body.name, file, message, issues };
}