@causyne/agent 0.0.0-stage → 1.10.1

package/src/appChannel.js

@@ -0,0 +1,109 @@
+// The Three-Channel Doctrine, made executable.
+//
+//   Channel A — the app's own API / plugin / CLI     ~50-200 tok   exact
+//   Channel B — the accessibility tree                ~200-800 tok  structured
+//   Channel C — pixels: screenshot + OCR + click     ~1,500-2,500  universal, brittle
+//
+// Channel C costs 10-50x Channel A per observation. An agent that reaches for
+// pixels first is not more capable — it is more expensive AND less reliable.
+//
+// THIS MODULE IS A GUARD, NOT ADVICE. A doctrine that lives only in a system
+// prompt is a suggestion the model may ignore on any given turn, and the turn
+// it ignores it is the turn it clicks blindly through Blender instead of
+// calling `blender_act`. So the router is consulted by `desktop_act` BEFORE any
+// actuation, and it refuses the pixel path for an app that has a native one.
+//
+// It is deliberately NOT a tool the model calls. Another tool schema is another
+// ~200 tokens on every request to describe a decision the runtime can make on
+// its own, and a decision the model is allowed to skip is not a guard.
+//
+// EXTENDING IT: a Higgsfield-style plugin (Photoshop UXP, a Blender add-on) is
+// one more CHANNEL_A row, not a parallel architecture. That is the whole point
+// of the table — the lesson from Higgsfield is "a native app API beats pixels",
+// not "build our own Higgsfield".
+
+/**
+ * Apps that already have a Channel A tool, keyed by matcher.
+ *
+ * `match` is tested against a lowercased app name, so "Blender", "blender" and
+ * "Blender 4.2" all resolve. Order matters only for readability; the first hit
+ * wins.
+ */
+const CHANNEL_A = [
+  { match: /\bblender\b/, tool: 'blender_act', app: 'Blender' },
+  { match: /\b(davinci|resolve)\b/, tool: 'resolve_act', app: 'DaVinci Resolve' },
+  { match: /\bgodot\b/, tool: 'godot_act', app: 'Godot' },
+  { match: /\bpalmier\b/, tool: 'palmier_act', app: 'Palmier Pro' },
+  {
+    match: /\b(chrome|chromium|safari|firefox|edge|brave|arc)\b/,
+    tool: 'browser_act',
+    app: 'a web browser'
+  }
+];
+
+/**
+ * Apps a GUI actuator must never drive, because a text interface already
+ * exists and driving it by pixels is strictly worse in every dimension —
+ * slower, costlier, and unable to read its own output reliably.
+ */
+const NEVER_BY_PIXEL = [
+  { match: /\b(terminal|iterm|iterm2|konsole|gnome-terminal|powershell|cmd|wezterm|alacritty|kitty)\b/,
+    tool: 'sysRun',
+    reason: 'a shell is a text interface; clicking one is slower and cannot read its output reliably' }
+];
+
+/** @typedef {{channel:'A'|'B'|'C', tool:string|null, reason:string, blocked:boolean}} ChannelChoice */
+
+/**
+ * Decide the cheapest channel that can drive `appName`.
+ *
+ * Pure and total — an empty or unknown app name resolves to Channel C, which
+ * is correct: "I do not recognise this app" is exactly when the universal
+ * fallback is the right answer.
+ *
+ * @param   {string} appName  Application name, as the user or the OS reports it.
+ * @returns {ChannelChoice}
+ */
+export function resolveChannel(appName) {
+  const name = String(appName || '').toLowerCase().trim();
+
+  if (name !== '') {
+    for (const entry of NEVER_BY_PIXEL) {
+      if (entry.match.test(name)) {
+        return {
+          channel: 'A',
+          tool: entry.tool,
+          reason: `${appName} must not be driven by pixels — ${entry.reason}. Use ${entry.tool}.`,
+          blocked: true
+        };
+      }
+    }
+
+    for (const entry of CHANNEL_A) {
+      if (entry.match.test(name)) {
+        return {
+          channel: 'A',
+          tool: entry.tool,
+          reason: `${entry.app} has a native automation API. ${entry.tool} is exact, roughly 10x cheaper `
+            + `per observation, and does not break when the window moves. Use it instead of clicking.`,
+          blocked: true
+        };
+      }
+    }
+  }
+
+  return {
+    channel: 'C',
+    tool: null,
+    reason: name === ''
+      ? 'No application named, so no native channel can be selected; the pixel path applies.'
+      : `No native automation channel is registered for "${appName}". Read it with ax_snapshot first `
+        + `(Channel B, structured and ~5x cheaper than a screenshot), and act by element name where possible.`,
+    blocked: false
+  };
+}
+
+/** Every app name pattern with a Channel A tool. For tests and diagnostics. */
+export function channelATools() {
+  return [...CHANNEL_A.map(e => e.tool), ...NEVER_BY_PIXEL.map(e => e.tool)];
+}

package/src/approvalGrants.js

@@ -0,0 +1,66 @@
+// "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
+
+// 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();
+
+/**
+ * Record a standing approval for one tool.
+ *
+ * @param {string} toolName  Canonical tool name, e.g. 'sysRun'.
+ */
+export function grantAlways(toolName) {
+  const name = String(toolName || '').trim();
+  if (name) standingApprovals.add(name);
+}
+
+/**
+ * True when this tool may run without asking again.
+ *
+ * @param {string} toolName
+ * @returns {boolean}
+ */
+export function isAlwaysAllowed(toolName) {
+  return standingApprovals.has(String(toolName || '').trim());
+}
+
+/** Every standing approval, for `/approvals` and for the audit trail. */
+export function listAlwaysAllowed() {
+  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
+ */
+export function revokeAllAlways() {
+  const count = standingApprovals.size;
+  standingApprovals.clear();
+  return count;
+}
+
+/** Revoke one. @returns {boolean} true when there was something to revoke. */
+export function revokeAlways(toolName) {
+  return standingApprovals.delete(String(toolName || '').trim());
+}

package/src/auditLog.js

@@ -0,0 +1,52 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { causyneHome } from './utils/paths.js';
+
+const LOG_DIR = path.join(causyneHome(), 'logs');
+
+export class AuditLog {
+  constructor() {
+    this.ensureLogDir();
+    const date = new Date().toISOString().split('T')[0];
+    this.logFile = path.join(LOG_DIR, `audit-${date}.jsonl`);
+  }
+
+  ensureLogDir() {
+    if (!fs.existsSync(LOG_DIR)) {
+      fs.mkdirSync(LOG_DIR, { recursive: true });
+    }
+  }
+
+  log(eventData) {
+    const entry = {
+      ts: new Date().toISOString(),
+      ...eventData
+    };
+    
+    // Append to file synchronously to ensure it writes before any potential crash
+    try {
+      fs.appendFileSync(this.logFile, JSON.stringify(entry) + '\n');
+    } catch (e) {
+      console.error('Failed to write audit log:', e);
+    }
+  }
+
+  getRecentLogs(limit = 100) {
+    if (!fs.existsSync(this.logFile)) return [];
+    
+    try {
+      const content = fs.readFileSync(this.logFile, 'utf8');
+      const lines = content.split('\n').filter(l => l.trim().length > 0);
+      
+      return lines.slice(-limit).map(l => {
+        try { return JSON.parse(l); } catch(e) { return null; }
+      }).filter(Boolean);
+    } catch (e) {
+      console.error('Failed to read audit log:', e);
+      return [];
+    }
+  }
+}
+
+export const auditLog = new AuditLog();

package/src/autoUpdate.js

@@ -0,0 +1,12 @@
+import { UI } from './utils/cli_ui.js';
+
+// No registry polling or self-modifying installation. A release channel has
+// not been selected or published for the independent Causyne project yet.
+export async function runSelfUpdate(verbose = false) {
+  if (verbose) UI.printInfo('Automatic updates are disabled. Review and update your Causyne source checkout explicitly. No public package is configured yet.');
+  return false;
+}
+
+export function startUpdateChecker() {
+  // Compatibility with the local CLI caller; deliberately no timer or I/O.
+}

package/src/capabilities.js

@@ -0,0 +1,36 @@
+// Capability gating (monetization Move 1) — DORMANT scaffolding.
+//
+// The agent is BYOK, so inference costs the owner nothing; the value a
+// subscription buys is a *better body*, not more tokens. This module maps local
+// capabilities to the minimum tier that unlocks them.
+//
+// It is deliberately INERT until launch: while CAPABILITY_GATING_ENABLED is
+// false, isCapabilityAllowed() returns true for everyone, so pre-release
+// development behaves exactly as before. At launch, flip the flag and call
+// isCapabilityAllowed(tier, cap) at each local feature entry point.
+
+export const CAPABILITY_GATING_ENABLED = false;
+
+// Tiers rank so a higher plan is a superset of a lower one.
+export const TIER_RANK = {
+  starter: 0, free: 0, fast: 1,
+  premium: 2, premium_annual: 2,
+  max: 3, super_max: 4,
+};
+
+// Minimum tier rank required for each gated capability.
+export const CAPABILITY_MIN_RANK = {
+  cortex_memory:     TIER_RANK.premium, // V5 persistent memory across sessions
+  tool_forge:        TIER_RANK.max,     // self-evolving runtime tool creation
+};
+
+/**
+ * Whether `tier` unlocks `capability`. Returns true for everything while the
+ * gate is dormant, and for any capability not present in the matrix.
+ */
+export function isCapabilityAllowed(tier, capability) {
+  if (!CAPABILITY_GATING_ENABLED) return true;
+  const need = CAPABILITY_MIN_RANK[capability];
+  if (need == null) return true;
+  return (TIER_RANK[tier] ?? 0) >= need;
+}