@causyne/agent 1.10.13 → 1.10.18

package/src/agentProfiles.js

@@ -0,0 +1,135 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { causyneHome } from './utils/paths.js';
+const PROFILE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TOOL_NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+const MAX_PROFILES = 64;
+const MAX_PROFILE_BYTES = 24 * 1024;
+const MAX_INSTRUCTIONS = 16 * 1024;
+const MAX_TOOLS = 64;
+export function agentProfilesRoot() {
+    return path.join(causyneHome(), 'agents');
+}
+function cleanLine(value, maximum) {
+    return String(value ?? '')
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x1f\x7f]/g, ' ')
+        .replace(/\s+/g, ' ')
+        .trim()
+        .slice(0, maximum);
+}
+function cleanInstructions(value) {
+    return String(value ?? '')
+        // Preserve newlines and tabs while excluding prompt-control bytes.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+        .trim();
+}
+function boundedInteger(value, fallback, minimum, maximum) {
+    if (value === undefined)
+        return fallback;
+    if (!Number.isInteger(value))
+        return null;
+    return Math.max(minimum, Math.min(Number(value), maximum));
+}
+function parseProfile(file, expectedName) {
+    try {
+        const stat = fs.lstatSync(file);
+        if (!stat.isFile() || stat.isSymbolicLink())
+            return { ok: false, error: 'profile must be a regular file' };
+        if (stat.size > MAX_PROFILE_BYTES)
+            return { ok: false, error: `profile exceeds ${MAX_PROFILE_BYTES / 1024} KB` };
+        const raw = JSON.parse(fs.readFileSync(file, 'utf8'));
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            return { ok: false, error: 'profile must be a JSON object' };
+        }
+        const value = raw;
+        if (value.schemaVersion !== 1)
+            return { ok: false, error: 'schemaVersion must be 1' };
+        if (value.name !== expectedName || !PROFILE_ID.test(expectedName)) {
+            return { ok: false, error: 'profile name must match its lowercase file name' };
+        }
+        const description = cleanLine(value.description, 400);
+        if (!description)
+            return { ok: false, error: 'description is required' };
+        const instructions = cleanInstructions(value.instructions);
+        if (!instructions)
+            return { ok: false, error: 'instructions are required' };
+        if (Buffer.byteLength(instructions, 'utf8') > MAX_INSTRUCTIONS) {
+            return { ok: false, error: `instructions exceed ${MAX_INSTRUCTIONS / 1024} KB` };
+        }
+        if (!Array.isArray(value.toolScope) || value.toolScope.length === 0 || value.toolScope.length > MAX_TOOLS) {
+            return { ok: false, error: `toolScope must contain 1-${MAX_TOOLS} tool names` };
+        }
+        const toolScope = [];
+        for (const rawTool of value.toolScope) {
+            if (typeof rawTool !== 'string' || !TOOL_NAME.test(rawTool)) {
+                return { ok: false, error: `invalid tool name ${JSON.stringify(rawTool)}` };
+            }
+            const normalized = rawTool.replace(/\./g, '_');
+            if (!toolScope.includes(normalized))
+                toolScope.push(normalized);
+        }
+        const maxSteps = boundedInteger(value.maxSteps, 25, 1, 100);
+        if (maxSteps === null)
+            return { ok: false, error: 'maxSteps must be an integer' };
+        const maxTokens = boundedInteger(value.maxTokens, 50_000, 1_000, 200_000);
+        if (maxTokens === null)
+            return { ok: false, error: 'maxTokens must be an integer' };
+        return {
+            ok: true,
+            profile: {
+                schemaVersion: 1,
+                name: expectedName,
+                description,
+                instructions,
+                toolScope,
+                maxSteps,
+                maxTokens,
+                path: file
+            }
+        };
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        return { ok: false, error: message };
+    }
+}
+export function loadAgentProfile(name) {
+    const id = String(name ?? '');
+    if (!PROFILE_ID.test(id))
+        return { ok: false, error: 'invalid profile name' };
+    return parseProfile(path.join(agentProfilesRoot(), `${id}.json`), id);
+}
+export function listAgentProfiles() {
+    const profiles = [];
+    const problems = [];
+    const root = agentProfilesRoot();
+    try {
+        if (!fs.existsSync(root))
+            return { profiles, problems };
+        const entries = fs.readdirSync(root, { withFileTypes: true })
+            .filter((entry) => entry.name.endsWith('.json') && !entry.name.startsWith('.'))
+            .slice(0, MAX_PROFILES + 1);
+        if (entries.length > MAX_PROFILES)
+            problems.push(`only the first ${MAX_PROFILES} profiles were inspected`);
+        for (const entry of entries.slice(0, MAX_PROFILES)) {
+            const name = entry.name.slice(0, -5);
+            if (!entry.isFile() || !PROFILE_ID.test(name)) {
+                problems.push(`${entry.name}: invalid profile file`);
+                continue;
+            }
+            const loaded = parseProfile(path.join(root, entry.name), name);
+            if (loaded.ok)
+                profiles.push(loaded.profile);
+            else
+                problems.push(`${entry.name}: ${loaded.error}`);
+        }
+    }
+    catch (error) {
+        const message = error instanceof Error ? error.message : String(error);
+        problems.push(`could not read profiles: ${message}`);
+    }
+    return { profiles, problems };
+}
+export { MAX_PROFILES, MAX_PROFILE_BYTES, MAX_INSTRUCTIONS, MAX_TOOLS };

package/src/agentProfiles.ts

@@ -0,0 +1,143 @@
+import fs from 'node:fs';
+import path from 'node:path';
+import { causyneHome } from './utils/paths.js';
+
+const PROFILE_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+const TOOL_NAME = /^[a-zA-Z][a-zA-Z0-9_.-]{0,127}$/;
+const MAX_PROFILES = 64;
+const MAX_PROFILE_BYTES = 24 * 1024;
+const MAX_INSTRUCTIONS = 16 * 1024;
+const MAX_TOOLS = 64;
+
+export interface AgentProfile {
+  schemaVersion: 1;
+  name: string;
+  description: string;
+  instructions: string;
+  toolScope: string[];
+  maxSteps: number;
+  maxTokens: number;
+  path: string;
+}
+
+export type AgentProfileResult =
+  | { ok: true; profile: AgentProfile }
+  | { ok: false; error: string };
+
+export function agentProfilesRoot(): string {
+  return path.join(causyneHome(), 'agents');
+}
+
+function cleanLine(value: unknown, maximum: number): string {
+  return String(value ?? '')
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x1f\x7f]/g, ' ')
+    .replace(/\s+/g, ' ')
+    .trim()
+    .slice(0, maximum);
+}
+
+function cleanInstructions(value: unknown): string {
+  return String(value ?? '')
+    // Preserve newlines and tabs while excluding prompt-control bytes.
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '')
+    .trim();
+}
+
+function boundedInteger(value: unknown, fallback: number, minimum: number, maximum: number): number | null {
+  if (value === undefined) return fallback;
+  if (!Number.isInteger(value)) return null;
+  return Math.max(minimum, Math.min(Number(value), maximum));
+}
+
+function parseProfile(file: string, expectedName: string): AgentProfileResult {
+  try {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink()) return { ok: false, error: 'profile must be a regular file' };
+    if (stat.size > MAX_PROFILE_BYTES) return { ok: false, error: `profile exceeds ${MAX_PROFILE_BYTES / 1024} KB` };
+    const raw: unknown = JSON.parse(fs.readFileSync(file, 'utf8'));
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      return { ok: false, error: 'profile must be a JSON object' };
+    }
+    const value = raw as Record<string, unknown>;
+    if (value.schemaVersion !== 1) return { ok: false, error: 'schemaVersion must be 1' };
+    if (value.name !== expectedName || !PROFILE_ID.test(expectedName)) {
+      return { ok: false, error: 'profile name must match its lowercase file name' };
+    }
+    const description = cleanLine(value.description, 400);
+    if (!description) return { ok: false, error: 'description is required' };
+    const instructions = cleanInstructions(value.instructions);
+    if (!instructions) return { ok: false, error: 'instructions are required' };
+    if (Buffer.byteLength(instructions, 'utf8') > MAX_INSTRUCTIONS) {
+      return { ok: false, error: `instructions exceed ${MAX_INSTRUCTIONS / 1024} KB` };
+    }
+    if (!Array.isArray(value.toolScope) || value.toolScope.length === 0 || value.toolScope.length > MAX_TOOLS) {
+      return { ok: false, error: `toolScope must contain 1-${MAX_TOOLS} tool names` };
+    }
+    const toolScope: string[] = [];
+    for (const rawTool of value.toolScope) {
+      if (typeof rawTool !== 'string' || !TOOL_NAME.test(rawTool)) {
+        return { ok: false, error: `invalid tool name ${JSON.stringify(rawTool)}` };
+      }
+      const normalized = rawTool.replace(/\./g, '_');
+      if (!toolScope.includes(normalized)) toolScope.push(normalized);
+    }
+    const maxSteps = boundedInteger(value.maxSteps, 25, 1, 100);
+    if (maxSteps === null) return { ok: false, error: 'maxSteps must be an integer' };
+    const maxTokens = boundedInteger(value.maxTokens, 50_000, 1_000, 200_000);
+    if (maxTokens === null) return { ok: false, error: 'maxTokens must be an integer' };
+
+    return {
+      ok: true,
+      profile: {
+        schemaVersion: 1,
+        name: expectedName,
+        description,
+        instructions,
+        toolScope,
+        maxSteps,
+        maxTokens,
+        path: file
+      }
+    };
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    return { ok: false, error: message };
+  }
+}
+
+export function loadAgentProfile(name: unknown): AgentProfileResult {
+  const id = String(name ?? '');
+  if (!PROFILE_ID.test(id)) return { ok: false, error: 'invalid profile name' };
+  return parseProfile(path.join(agentProfilesRoot(), `${id}.json`), id);
+}
+
+export function listAgentProfiles(): { profiles: AgentProfile[]; problems: string[] } {
+  const profiles: AgentProfile[] = [];
+  const problems: string[] = [];
+  const root = agentProfilesRoot();
+  try {
+    if (!fs.existsSync(root)) return { profiles, problems };
+    const entries = fs.readdirSync(root, { withFileTypes: true })
+      .filter((entry) => entry.name.endsWith('.json') && !entry.name.startsWith('.'))
+      .slice(0, MAX_PROFILES + 1);
+    if (entries.length > MAX_PROFILES) problems.push(`only the first ${MAX_PROFILES} profiles were inspected`);
+    for (const entry of entries.slice(0, MAX_PROFILES)) {
+      const name = entry.name.slice(0, -5);
+      if (!entry.isFile() || !PROFILE_ID.test(name)) {
+        problems.push(`${entry.name}: invalid profile file`);
+        continue;
+      }
+      const loaded = parseProfile(path.join(root, entry.name), name);
+      if (loaded.ok) profiles.push(loaded.profile);
+      else problems.push(`${entry.name}: ${loaded.error}`);
+    }
+  } catch (error) {
+    const message = error instanceof Error ? error.message : String(error);
+    problems.push(`could not read profiles: ${message}`);
+  }
+  return { profiles, problems };
+}
+
+export { MAX_PROFILES, MAX_PROFILE_BYTES, MAX_INSTRUCTIONS, MAX_TOOLS };

package/src/approvalGrants.js

@@ -8,7 +8,7 @@
 //
 // THE SCOPE IS THE PROCESS, AND THAT IS THE WHOLE SAFETY MODEL.
 // This is a module-level Set. It is never written to config.json, never
-
+// serialized, and never restored. When the process ends, every standing
 // approval is gone — the same contract opencode states to the user in its own
 // words: "This will allow … until OpenCode is restarted."
 //
@@ -17,50 +17,32 @@
 // a session the user has forgotten they configured. If that is ever wanted it
 // should be an explicit, listed, revocable config entry — not a quiet
 // side-effect of a keypress in a modal.
-
 /** Tool names approved for the rest of this process. Deliberately in memory. */
 const standingApprovals = new Set();
-
-/**
- * Record a standing approval for one tool.
- *
- * @param {string} toolName  Canonical tool name, e.g. 'sysRun'.
- */
+function normalizeToolName(toolName) {
+    return String(toolName || '').trim();
+}
+/** Record a standing approval for one canonical tool name. */
 export function grantAlways(toolName) {
-  const name = String(toolName || '').trim();
-  if (name) standingApprovals.add(name);
+    const name = normalizeToolName(toolName);
+    if (name)
+        standingApprovals.add(name);
 }
-
-/**
- * True when this tool may run without asking again.
- *
- * @param {string} toolName
- * @returns {boolean}
- */
+/** True when this tool may run without asking again. */
 export function isAlwaysAllowed(toolName) {
-  return standingApprovals.has(String(toolName || '').trim());
+    return standingApprovals.has(normalizeToolName(toolName));
 }
-
 /** Every standing approval, for `/approvals` and for the audit trail. */
 export function listAlwaysAllowed() {
-  return [...standingApprovals].sort();
+    return [...standingApprovals].sort();
 }
-
-/**
- * Take them all back.
- *
- * A grant with no way out is a trap, so this is reachable from `/approvals
- * clear` as well as from a restart.
- *
- * @returns {number} how many were revoked
- */
+/** Take every standing approval back and return how many were revoked. */
 export function revokeAllAlways() {
-  const count = standingApprovals.size;
-  standingApprovals.clear();
-  return count;
+    const count = standingApprovals.size;
+    standingApprovals.clear();
+    return count;
 }
-
-/** Revoke one. @returns {boolean} true when there was something to revoke. */
+/** Revoke one standing approval. */
 export function revokeAlways(toolName) {
-  return standingApprovals.delete(String(toolName || '').trim());
+    return standingApprovals.delete(normalizeToolName(toolName));
 }

package/src/approvalGrants.ts

@@ -0,0 +1,54 @@
+// "Allow always" — standing approvals, for the length of this process only.
+//
+// WHY THIS EXISTS. Being asked to approve the same tool for the twentieth time
+// in one task does not make anyone safer; it makes them stop reading and start
+// hammering the approve key, which is the exact failure the gate exists to
+// prevent. A gate people are numb to is not a gate. So the honest answer is to
+// let someone who has decided a tool is fine say so once, deliberately.
+//
+// THE SCOPE IS THE PROCESS, AND THAT IS THE WHOLE SAFETY MODEL.
+// This is a module-level Set. It is never written to config.json, never
+// serialized, and never restored. When the process ends, every standing
+// approval is gone — the same contract opencode states to the user in its own
+// words: "This will allow … until OpenCode is restarted."
+//
+// Persisting these to disk would be a different feature with a different risk
+// profile: a permission granted in a hurry six weeks ago, silently applying to
+// a session the user has forgotten they configured. If that is ever wanted it
+// should be an explicit, listed, revocable config entry — not a quiet
+// side-effect of a keypress in a modal.
+
+/** Tool names approved for the rest of this process. Deliberately in memory. */
+const standingApprovals = new Set<string>();
+
+function normalizeToolName(toolName: unknown): string {
+  return String(toolName || '').trim();
+}
+
+/** Record a standing approval for one canonical tool name. */
+export function grantAlways(toolName: unknown): void {
+  const name = normalizeToolName(toolName);
+  if (name) standingApprovals.add(name);
+}
+
+/** True when this tool may run without asking again. */
+export function isAlwaysAllowed(toolName: unknown): boolean {
+  return standingApprovals.has(normalizeToolName(toolName));
+}
+
+/** Every standing approval, for `/approvals` and for the audit trail. */
+export function listAlwaysAllowed(): string[] {
+  return [...standingApprovals].sort();
+}
+
+/** Take every standing approval back and return how many were revoked. */
+export function revokeAllAlways(): number {
+  const count = standingApprovals.size;
+  standingApprovals.clear();
+  return count;
+}
+
+/** Revoke one standing approval. */
+export function revokeAlways(toolName: unknown): boolean {
+  return standingApprovals.delete(normalizeToolName(toolName));
+}

package/src/auditLog.d.ts

@@ -0,0 +1,3 @@
+export const auditLog: {
+  log(event: Record<string, unknown>): void;
+};

package/src/browser/browserRuntime.js

@@ -0,0 +1,88 @@
+import { accessSync, constants, existsSync, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+function assertExecutable(candidate) {
+    const stat = statSync(candidate);
+    if (!stat.isFile() && !stat.isSymbolicLink()) {
+        throw new Error(`Causyne Browser executable is not a file: ${candidate}`);
+    }
+    if (process.platform !== 'win32')
+        accessSync(candidate, constants.X_OK);
+}
+function candidateExecutables() {
+    const home = os.homedir();
+    if (process.platform === 'darwin') {
+        return [
+            path.join(home, 'Library', 'Caches', 'camoufox', 'Camoufox.app', 'Contents', 'MacOS', 'camoufox'),
+            '/Applications/Camoufox.app/Contents/MacOS/camoufox',
+            path.join(home, 'Applications', 'Camoufox.app', 'Contents', 'MacOS', 'camoufox')
+        ];
+    }
+    if (process.platform === 'win32') {
+        const localAppData = process.env.LOCALAPPDATA;
+        const programFiles = process.env.ProgramFiles;
+        return [
+            ...(localAppData ? [path.join(localAppData, 'camoufox', 'camoufox.exe')] : []),
+            ...(localAppData ? [path.join(localAppData, 'Camoufox', 'camoufox.exe')] : []),
+            ...(programFiles ? [path.join(programFiles, 'Camoufox', 'camoufox.exe')] : [])
+        ];
+    }
+    return [
+        path.join(home, '.cache', 'camoufox', 'camoufox-bin'),
+        '/opt/camoufox/camoufox-bin',
+        path.join(home, '.local', 'share', 'camoufox', 'camoufox-bin'),
+        '/usr/local/lib/camoufox/camoufox-bin'
+    ];
+}
+function expectedExecutable(installDirectory) {
+    if (process.platform === 'darwin') {
+        return path.join(installDirectory, 'Camoufox.app', 'Contents', 'MacOS', 'camoufox');
+    }
+    if (process.platform === 'win32')
+        return path.join(installDirectory, 'camoufox.exe');
+    return path.join(installDirectory, 'camoufox-bin');
+}
+function findInstallDirectory(executablePath) {
+    let current = path.dirname(executablePath);
+    for (let depth = 0; depth < 7; depth += 1) {
+        if (existsSync(path.join(current, 'version.json')) && existsSync(expectedExecutable(current))) {
+            return current;
+        }
+        const parent = path.dirname(current);
+        if (parent === current)
+            break;
+        current = parent;
+    }
+    return null;
+}
+function resourceDirectoryFor(executablePath) {
+    if (process.platform === 'darwin') {
+        return path.resolve(path.dirname(executablePath), '..', 'Resources');
+    }
+    return path.dirname(executablePath);
+}
+export function resolveBrowserRuntime() {
+    const configured = process.env.CAUSYNE_BROWSER_EXECUTABLE?.trim();
+    const candidates = configured ? [path.resolve(configured)] : candidateExecutables();
+    const executablePath = candidates.find(existsSync);
+    if (!executablePath) {
+        throw new Error('Causyne Browser runtime is not installed. Causyne does not download browser binaries automatically. ' +
+            'Install a supported browser runtime separately, then set CAUSYNE_BROWSER_EXECUTABLE to its executable path.');
+    }
+    assertExecutable(executablePath);
+    const resolvedExecutable = realpathSync(executablePath);
+    const installDirectory = findInstallDirectory(resolvedExecutable);
+    if (!installDirectory) {
+        throw new Error(`Causyne Browser runtime at ${resolvedExecutable} is not a complete distribution. ` +
+            'Keep version.json beside its platform bundle and point CAUSYNE_BROWSER_EXECUTABLE at that bundle.');
+    }
+    const resourceDirectory = resourceDirectoryFor(resolvedExecutable);
+    if (!existsSync(path.join(resourceDirectory, 'properties.json'))) {
+        throw new Error(`Causyne Browser runtime metadata was not found in ${resourceDirectory}.`);
+    }
+    return {
+        installDirectory,
+        resourceDirectory,
+        source: configured ? 'environment' : 'system'
+    };
+}

package/src/browser/browserRuntime.ts

@@ -0,0 +1,107 @@
+import { accessSync, constants, existsSync, realpathSync, statSync } from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+
+// Adapted from Jo Inc's MIT-licensed Camofox Browser external executable
+// discovery at commit 2c0036a8b18bf9cd983376751ff4d52dfd9add0f. Causyne
+// keeps this integration layer in TypeScript and never downloads a browser.
+
+export interface PreparedBrowserRuntime {
+  installDirectory: string;
+  resourceDirectory: string;
+  source: 'environment' | 'system';
+}
+
+function assertExecutable(candidate: string): void {
+  const stat = statSync(candidate);
+  if (!stat.isFile() && !stat.isSymbolicLink()) {
+    throw new Error(`Causyne Browser executable is not a file: ${candidate}`);
+  }
+  if (process.platform !== 'win32') accessSync(candidate, constants.X_OK);
+}
+
+function candidateExecutables(): string[] {
+  const home = os.homedir();
+  if (process.platform === 'darwin') {
+    return [
+      path.join(home, 'Library', 'Caches', 'camoufox', 'Camoufox.app', 'Contents', 'MacOS', 'camoufox'),
+      '/Applications/Camoufox.app/Contents/MacOS/camoufox',
+      path.join(home, 'Applications', 'Camoufox.app', 'Contents', 'MacOS', 'camoufox')
+    ];
+  }
+  if (process.platform === 'win32') {
+    const localAppData = process.env.LOCALAPPDATA;
+    const programFiles = process.env.ProgramFiles;
+    return [
+      ...(localAppData ? [path.join(localAppData, 'camoufox', 'camoufox.exe')] : []),
+      ...(localAppData ? [path.join(localAppData, 'Camoufox', 'camoufox.exe')] : []),
+      ...(programFiles ? [path.join(programFiles, 'Camoufox', 'camoufox.exe')] : [])
+    ];
+  }
+  return [
+    path.join(home, '.cache', 'camoufox', 'camoufox-bin'),
+    '/opt/camoufox/camoufox-bin',
+    path.join(home, '.local', 'share', 'camoufox', 'camoufox-bin'),
+    '/usr/local/lib/camoufox/camoufox-bin'
+  ];
+}
+
+function expectedExecutable(installDirectory: string): string {
+  if (process.platform === 'darwin') {
+    return path.join(installDirectory, 'Camoufox.app', 'Contents', 'MacOS', 'camoufox');
+  }
+  if (process.platform === 'win32') return path.join(installDirectory, 'camoufox.exe');
+  return path.join(installDirectory, 'camoufox-bin');
+}
+
+function findInstallDirectory(executablePath: string): string | null {
+  let current = path.dirname(executablePath);
+  for (let depth = 0; depth < 7; depth += 1) {
+    if (existsSync(path.join(current, 'version.json')) && existsSync(expectedExecutable(current))) {
+      return current;
+    }
+    const parent = path.dirname(current);
+    if (parent === current) break;
+    current = parent;
+  }
+  return null;
+}
+
+function resourceDirectoryFor(executablePath: string): string {
+  if (process.platform === 'darwin') {
+    return path.resolve(path.dirname(executablePath), '..', 'Resources');
+  }
+  return path.dirname(executablePath);
+}
+
+export function resolveBrowserRuntime(): PreparedBrowserRuntime {
+  const configured = process.env.CAUSYNE_BROWSER_EXECUTABLE?.trim();
+  const candidates = configured ? [path.resolve(configured)] : candidateExecutables();
+  const executablePath = candidates.find(existsSync);
+  if (!executablePath) {
+    throw new Error(
+      'Causyne Browser runtime is not installed. Causyne does not download browser binaries automatically. ' +
+      'Install a supported browser runtime separately, then set CAUSYNE_BROWSER_EXECUTABLE to its executable path.'
+    );
+  }
+
+  assertExecutable(executablePath);
+  const resolvedExecutable = realpathSync(executablePath);
+  const installDirectory = findInstallDirectory(resolvedExecutable);
+  if (!installDirectory) {
+    throw new Error(
+      `Causyne Browser runtime at ${resolvedExecutable} is not a complete distribution. ` +
+      'Keep version.json beside its platform bundle and point CAUSYNE_BROWSER_EXECUTABLE at that bundle.'
+    );
+  }
+  const resourceDirectory = resourceDirectoryFor(resolvedExecutable);
+  if (!existsSync(path.join(resourceDirectory, 'properties.json'))) {
+    throw new Error(`Causyne Browser runtime metadata was not found in ${resourceDirectory}.`);
+  }
+
+  return {
+    installDirectory,
+    resourceDirectory,
+    source: configured ? 'environment' : 'system'
+  };
+}