@causyne/agent 1.10.12 → 1.10.17

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/benchmarks/planCache.js

@@ -0,0 +1,159 @@
+#!/usr/bin/env node
+
+import fs from 'node:fs';
+import os from 'node:os';
+import path from 'node:path';
+import { performance } from 'node:perf_hooks';
+
+// Never inspect or mutate a user's real plan cache. utils/paths.js resolves the
+// state root at module initialization, so set it before importing planCache.js.
+const benchmarkHome = fs.mkdtempSync(path.join(os.tmpdir(), 'causyne-plan-cache-bench-'));
+process.env.CAUSYNE_HOME = benchmarkHome;
+
+const {
+  forgetPlans,
+  lookupPlan,
+  planStats,
+  prewarmPlans
+} = await import('../planCache.js');
+
+const sizes = [1, 10, 20, 50, 100, 200];
+const hitIterations = 500;
+// Production deliberately cools down after a sustained low hit rate. Staying
+// below that threshold measures a real miss scan instead of the cheap bypass.
+const missIterations = 16;
+
+function sample(index) {
+  const key = `taskkey${String(index).padStart(3, '0')}`;
+  return {
+    prompt: `benchmark workflow ${key} inspect validate artifact`,
+    archetype: 'benchmark',
+    steps: [
+      { tool: 'fs_search', action: 'inspect', ok: true },
+      { tool: 'sys_run', action: 'validate', ok: true }
+    ]
+  };
+}
+
+function percentile(values, fraction) {
+  const sorted = [...values].sort((left, right) => left - right);
+  if (sorted.length === 0) return 0;
+  return sorted[Math.min(sorted.length - 1, Math.floor((sorted.length - 1) * fraction))];
+}
+
+function measure(iterations, operation) {
+  const values = [];
+  for (let index = 0; index < iterations; index++) {
+    const startedAt = performance.now();
+    operation(index);
+    values.push(performance.now() - startedAt);
+  }
+  const total = values.reduce((sum, value) => sum + value, 0);
+  return {
+    iterations,
+    averageMs: total / values.length,
+    medianMs: percentile(values, 0.5),
+    p95Ms: percentile(values, 0.95),
+    maxMs: Math.max(...values)
+  };
+}
+
+function fixed(value) {
+  return Number(value.toFixed(4));
+}
+
+function compactMeasurement(measurement) {
+  return {
+    iterations: measurement.iterations,
+    averageMs: fixed(measurement.averageMs),
+    medianMs: fixed(measurement.medianMs),
+    p95Ms: fixed(measurement.p95Ms),
+    maxMs: fixed(measurement.maxMs)
+  };
+}
+
+function prewarmInBatches(seeds) {
+  const combined = { accepted: 0, rejected: 0, errors: [] };
+  for (let offset = 0; offset < seeds.length; offset += 100) {
+    const batch = prewarmPlans(seeds.slice(offset, offset + 100));
+    combined.accepted += batch.accepted;
+    combined.rejected += batch.rejected;
+    combined.errors.push(...batch.errors);
+  }
+  return combined;
+}
+
+const results = [];
+
+try {
+  for (const size of sizes) {
+    forgetPlans();
+    const seeds = Array.from({ length: size }, (_, index) => sample(index));
+    const prewarmStartedAt = performance.now();
+    const prewarm = prewarmInBatches(seeds);
+    const prewarmMs = performance.now() - prewarmStartedAt;
+    const target = sample(Math.floor(size / 2));
+
+    // Warm filesystem and in-memory index before measuring lookup paths.
+    lookupPlan({ prompt: target.prompt, archetype: target.archetype, allowFuzzy: true });
+
+    const exact = measure(hitIterations, () => {
+      const match = lookupPlan({
+        prompt: target.prompt,
+        archetype: target.archetype,
+        allowFuzzy: true
+      });
+      if (!match || match.matchType !== 'exact') {
+        throw new Error(`Exact lookup failed at cache size ${size}`);
+      }
+    });
+
+    const fuzzyPrompt = target.prompt.replace('validate artifact', 'validate repaired artifact');
+    const fuzzy = measure(hitIterations, () => {
+      const match = lookupPlan({
+        prompt: fuzzyPrompt,
+        archetype: target.archetype,
+        allowFuzzy: true
+      });
+      if (!match || match.matchType !== 'fuzzy') {
+        throw new Error(`Fuzzy lookup failed at cache size ${size}`);
+      }
+    });
+
+    const miss = measure(missIterations, (index) => {
+      const match = lookupPlan({
+        prompt: `unrelated cold miss ${size} ${index} quantum orchard telescope`,
+        archetype: 'different-archetype',
+        allowFuzzy: true
+      });
+      if (match) throw new Error(`Unexpected cache hit at cache size ${size}`);
+    });
+
+    results.push({
+      cacheSize: size,
+      acceptedSeeds: prewarm.accepted,
+      prewarmMs: fixed(prewarmMs),
+      exact: compactMeasurement(exact),
+      fuzzy: compactMeasurement(fuzzy),
+      miss: compactMeasurement(miss),
+      telemetry: planStats()
+    });
+  }
+
+  const report = {
+    benchmark: 'Causyne Agent plan cache lookup',
+    generatedAt: new Date().toISOString(),
+    runtime: { node: process.version, platform: process.platform, arch: process.arch },
+    method: {
+      cacheSizes: sizes,
+      hitIterations,
+      missIterations,
+      note: 'Synthetic microbenchmark. It measures Causyne cache operations only; it does not reproduce paper task accuracy, model cost, or end-to-end agent latency.'
+    },
+    results
+  };
+
+  process.stdout.write(`${JSON.stringify(report, null, 2)}\n`);
+} finally {
+  fs.rmSync(benchmarkHome, { recursive: true, force: true });
+}

package/src/browser/camofoxRuntime.js

@@ -0,0 +1,93 @@
+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(`Camoufox 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 resolveCamoufoxRuntime() {
+    const configured = process.env.CAUSYNE_CAMOFOX_EXECUTABLE?.trim();
+    const configuredHome = process.env.CAMOUFOX_INSTALL_DIR?.trim();
+    const candidates = configured
+        ? [path.resolve(configured)]
+        : configuredHome
+            ? [expectedExecutable(path.resolve(configuredHome))]
+            : candidateExecutables();
+    const executablePath = candidates.find(existsSync);
+    if (!executablePath) {
+        throw new Error('Camoufox is not installed. Causyne does not download browser binaries automatically. ' +
+            'Install a trusted Camoufox build separately, then set CAUSYNE_CAMOFOX_EXECUTABLE to its executable path.');
+    }
+    assertExecutable(executablePath);
+    const resolvedExecutable = realpathSync(executablePath);
+    const installDirectory = findInstallDirectory(resolvedExecutable);
+    if (!installDirectory) {
+        throw new Error(`Camoufox at ${resolvedExecutable} is not inside a complete distribution. ` +
+            'Keep the distribution version.json beside its platform bundle and point CAUSYNE_CAMOFOX_EXECUTABLE at that bundle.');
+    }
+    const resourceDirectory = resourceDirectoryFor(resolvedExecutable);
+    if (!existsSync(path.join(resourceDirectory, 'properties.json'))) {
+        throw new Error(`Camoufox properties.json was not found in ${resourceDirectory}.`);
+    }
+    return {
+        installDirectory,
+        resourceDirectory,
+        source: configured || configuredHome ? 'environment' : 'system'
+    };
+}

package/src/browser/camofoxRuntime.ts

@@ -0,0 +1,112 @@
+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 PreparedCamoufoxRuntime {
+  installDirectory: string;
+  resourceDirectory: string;
+  source: 'environment' | 'system';
+}
+
+function assertExecutable(candidate: string): void {
+  const stat = statSync(candidate);
+  if (!stat.isFile() && !stat.isSymbolicLink()) {
+    throw new Error(`Camoufox 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 resolveCamoufoxRuntime(): PreparedCamoufoxRuntime {
+  const configured = process.env.CAUSYNE_CAMOFOX_EXECUTABLE?.trim();
+  const configuredHome = process.env.CAMOUFOX_INSTALL_DIR?.trim();
+  const candidates = configured
+    ? [path.resolve(configured)]
+    : configuredHome
+      ? [expectedExecutable(path.resolve(configuredHome))]
+      : candidateExecutables();
+  const executablePath = candidates.find(existsSync);
+  if (!executablePath) {
+    throw new Error(
+      'Camoufox is not installed. Causyne does not download browser binaries automatically. ' +
+      'Install a trusted Camoufox build separately, then set CAUSYNE_CAMOFOX_EXECUTABLE to its executable path.'
+    );
+  }
+
+  assertExecutable(executablePath);
+  const resolvedExecutable = realpathSync(executablePath);
+  const installDirectory = findInstallDirectory(resolvedExecutable);
+  if (!installDirectory) {
+    throw new Error(
+      `Camoufox at ${resolvedExecutable} is not inside a complete distribution. ` +
+      'Keep the distribution version.json beside its platform bundle and point CAUSYNE_CAMOFOX_EXECUTABLE at that bundle.'
+    );
+  }
+  const resourceDirectory = resourceDirectoryFor(resolvedExecutable);
+  if (!existsSync(path.join(resourceDirectory, 'properties.json'))) {
+    throw new Error(`Camoufox properties.json was not found in ${resourceDirectory}.`);
+  }
+
+  return {
+    installDirectory,
+    resourceDirectory,
+    source: configured || configuredHome ? 'environment' : 'system'
+  };
+}