@causyne/agent 0.0.0-stage → 1.10.0

package/src/designPalettes.js

@@ -0,0 +1,99 @@
+// Curated design data — the alternative to slop, not just the ban on it.
+//
+// The anti-slop directive in toolPacks.js has always told the model what NOT to
+// do. Telling a model "no purple-to-blue gradients" without handing it something
+// concrete is how you get the second-most-common gradient instead. This module
+// is the positive half: real palettes and font pairings anchored to actual
+// design movements, so "pick a movement and commit" has something to commit to.
+//
+// Plain data. No shell, no dependency, no eval.
+
+/**
+ * Palettes are stored as HSL triples because the playbook asks for HSL, and
+ * because hue distance is what the detector reasons about.
+ */
+export const DESIGN_MOVEMENTS = [
+  {
+    id: 'swiss',
+    name: 'Swiss / International Style',
+    principles: 'Grid discipline, generous whitespace, flush-left ragged-right type, one accent only.',
+    palette: { background: '#FFFFFF', surface: '#F2F2F2', ink: '#111111', accent: '#D40000', muted: '#767676' },
+    fonts: { display: 'Helvetica Now, Inter, sans-serif', body: 'Inter, Helvetica, sans-serif' }
+  },
+  {
+    id: 'brutalist',
+    name: 'Brutalism',
+    principles: 'Raw structure, visible borders, system type, high contrast, no rounded corners, no shadows.',
+    palette: { background: '#E8E8E3', surface: '#FFFFFF', ink: '#000000', accent: '#0000EE', muted: '#5A5A55' },
+    fonts: { display: 'Archivo Black, Impact, sans-serif', body: 'Courier New, monospace' }
+  },
+  {
+    id: 'editorial',
+    name: 'Editorial / Magazine',
+    principles: 'Serif display at large sizes, multi-column rhythm, pull quotes, asymmetric layout.',
+    palette: { background: '#FBF9F4', surface: '#FFFFFF', ink: '#1A1614', accent: '#8C2F1E', muted: '#6B625B' },
+    fonts: { display: 'Playfair Display, Georgia, serif', body: 'Source Serif Pro, Georgia, serif' }
+  },
+  {
+    id: 'japanese-minimal',
+    name: 'Japanese Minimalism',
+    principles: 'Ma (negative space) as the subject, muted naturals, hairline rules, restrained scale.',
+    palette: { background: '#F7F5F0', surface: '#FFFFFF', ink: '#2B2B2B', accent: '#7B6C54', muted: '#9A9287' },
+    fonts: { display: 'Noto Serif JP, Georgia, serif', body: 'Noto Sans JP, Inter, sans-serif' }
+  },
+  {
+    id: 'bauhaus',
+    name: 'Bauhaus',
+    principles: 'Primary triad, geometric primitives, diagonal energy, function-first composition.',
+    palette: { background: '#F4F1EA', surface: '#FFFFFF', ink: '#1C1C1C', accent: '#D62828', muted: '#003049' },
+    fonts: { display: 'Futura, Poppins, sans-serif', body: 'Poppins, Inter, sans-serif' }
+  },
+  {
+    id: 'terminal',
+    name: 'Terminal / Retro-Computing',
+    principles: 'Monospace throughout, phosphor accent on near-black, scanline restraint, ASCII rules.',
+    palette: { background: '#0C0F0A', surface: '#131A11', ink: '#D6E5C8', accent: '#7FFF3F', muted: '#5C6B52' },
+    fonts: { display: 'JetBrains Mono, monospace', body: 'IBM Plex Mono, monospace' }
+  },
+  {
+    id: 'art-deco',
+    name: 'Art Deco',
+    principles: 'Symmetry, metallic accent on deep ground, stepped geometry, high-contrast display type.',
+    palette: { background: '#10161F', surface: '#18202C', ink: '#EDE3D0', accent: '#C9A227', muted: '#6E7885' },
+    fonts: { display: 'Poiret One, Didot, serif', body: 'Jost, Inter, sans-serif' }
+  },
+  {
+    id: 'scandinavian',
+    name: 'Scandinavian Minimal',
+    principles: 'Warm off-white ground, pale wood neutrals, single desaturated accent, soft rounded geometry.',
+    palette: { background: '#FAF8F5', surface: '#FFFFFF', ink: '#2E2A26', accent: '#6A8CAF', muted: '#A39C93' },
+    fonts: { display: 'Outfit, Inter, sans-serif', body: 'Inter, system-ui, sans-serif' }
+  }
+];
+
+/** A movement by id, or null. */
+export function getMovement(id) {
+  return DESIGN_MOVEMENTS.find(movement => movement.id === id) || null;
+}
+
+/**
+ * Suggest movements the agent has NOT recently used.
+ *
+ * The creativePattern memory records what the last projects looked like; the
+ * whole point of recording it is to deliberately diverge next time rather than
+ * drifting back into one house style.
+ */
+export function suggestMovements(recentlyUsedIds = [], count = 3) {
+  const used = new Set(recentlyUsedIds);
+  const unused = DESIGN_MOVEMENTS.filter(movement => !used.has(movement.id));
+  const pool = unused.length >= count ? unused : DESIGN_MOVEMENTS;
+  return pool.slice(0, count);
+}
+
+/** A compact briefing the agent can be handed when its output scores as slop. */
+export function formatMovementBrief(movements) {
+  return movements.map(movement => {
+    const palette = Object.entries(movement.palette).map(([role, hex]) => `${role} ${hex}`).join(', ');
+    return `- ${movement.name}: ${movement.principles}\n  palette: ${palette}\n  type: ${movement.fonts.display} / ${movement.fonts.body}`;
+  }).join('\n');
+}

package/src/devMode.js

@@ -0,0 +1,6 @@
+// The former Android entitlement emulator is retired. Keep this internal
+// predicate while callers migrate to explicit local runtime budgets. Neither
+// environment variables nor a hidden developer secret can bypass approvals.
+export function isDevEmulator() {
+  return false;
+}

package/src/embodimentSession.js

@@ -0,0 +1,180 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { causyneHome } from './utils/paths.js';
+
+// C5 — the resumable embodiment session.
+//
+// Astra's other headline, next to computer use, is STAYING ON THE JOB. Causyne
+// already persists more session state than most agents ship (checkpoints.js,
+// the V5 Cortex, the spill store). What none of them carried is the one thing a
+// GUI task cannot rebuild from the transcript: WHICH APPLICATION THE AGENT WAS
+// DRIVING AND WHAT IT LAST SAW ON SCREEN.
+//
+// Why that specifically. A file edit is recoverable from disk — the file is
+
+// something into "Notes" only if it re-reads the screen, and re-reading costs a
+// full Channel B pass on a window that may since have moved, closed, or been
+// replaced. Worse, without the state it does not know whether its last action
+// LANDED. Repeating an action that already succeeded is how a GUI agent sends
+// the same message twice.
+//
+// FAIL-OPEN BY CONTRACT. Every function here swallows its own errors and
+// returns a safe default. Losing session state must degrade the agent to
+// "re-read the screen", never break the task — the same contract outputStore.js
+// holds, and for the same reason.
+//
+// WHAT IS DELIBERATELY NOT STORED: no screenshots, no typed text, no element
+// values. A record of what a user's screen said, sitting in a file, is a
+// surveillance artefact. Only the app name, the action verbs, and a HASH of the
+// last tree are kept — enough to answer "is the screen still as I left it?"
+// without keeping the screen.
+
+const SESSION_DIR = path.join(causyneHome(), 'embodiment');
+
+/** Sessions older than this are pruned. A GUI session has no value stale. */
+const RETENTION_MS = 24 * 60 * 60 * 1000;
+
+/** Kill switch, matching CAUSYNE_OUTPUT_SPILL's shape. */
+export function isSessionTrackingEnabled() {
+  return process.env.CAUSYNE_EMBODIMENT_SESSION !== '0';
+}
+
+function ensureSessionDir() {
+  if (!fs.existsSync(SESSION_DIR)) {
+    fs.mkdirSync(SESSION_DIR, { recursive: true, mode: 0o700 });
+  }
+}
+
+
+function safeTaskId(taskId) {
+  const cleaned = String(taskId || 'default').replace(/[^a-zA-Z0-9_-]/g, '');
+  return cleaned === '' ? 'default' : cleaned.slice(0, 64);
+}
+
+function sessionFile(taskId) {
+  return path.join(SESSION_DIR, `${safeTaskId(taskId)}.json`);
+}
+
+/**
+ * Cheap, dependency-free digest of a screen reading.
+ *
+ * Not cryptographic and does not need to be — it answers one question, "is this
+ * the same screen I saw before?", where a collision costs one redundant re-read.
+ */
+function digestOf(text) {
+  let hash = 5381;
+  const source = String(text || '');
+  for (let i = 0; i < source.length; i++) {
+    hash = ((hash * 33) ^ source.charCodeAt(i)) >>> 0;
+  }
+  return `${hash.toString(16)}:${source.length}`;
+}
+
+/**
+ * Record that the agent observed a screen.
+ *
+ * @param {string} taskId
+ * @param {string} app       Application observed, '' for frontmost.
+ * @param {string} treeText  The ax_snapshot output. Hashed, never stored.
+ */
+export function recordObservation(taskId, app, treeText) {
+  if (!isSessionTrackingEnabled()) return;
+  try {
+    ensureSessionDir();
+    const previous = readSession(taskId) || {};
+    const state = {
+      ...previous,
+      app: app || previous.app || '',
+      lastTreeDigest: digestOf(treeText),
+      lastTreeNodeCount: String(treeText || '').split('\n').filter(Boolean).length,
+      observedAt: new Date().toISOString()
+    };
+    fs.writeFileSync(sessionFile(taskId), JSON.stringify(state, null, 2), { mode: 0o600 });
+  } catch (e) {
+    // Fail open: a lost session record must never fail the task.
+  }
+}
+
+/**
+ * Record that the agent acted on a screen.
+ *
+ * Stores the VERBS only, never their arguments. "typed 14 characters into
+ * Notes" is enough to resume; the 14 characters are the user's business.
+ */
+export function recordActuation(taskId, app, verbs) {
+  if (!isSessionTrackingEnabled()) return;
+  try {
+    ensureSessionDir();
+    const previous = readSession(taskId) || {};
+    const state = {
+      ...previous,
+      app: app || previous.app || '',
+      lastActions: Array.isArray(verbs) ? verbs.map(v => String(v)).slice(0, 12) : [],
+      // The screen has almost certainly changed, so the stored digest is stale
+      // by definition. Marking it beats silently trusting it.
+      lastTreeDigest: null,
+      actedAt: new Date().toISOString()
+    };
+    fs.writeFileSync(sessionFile(taskId), JSON.stringify(state, null, 2), { mode: 0o600 });
+  } catch (e) {
+    // Fail open.
+  }
+}
+
+/** @returns {object|null} the stored session, or null when there is none. */
+export function readSession(taskId) {
+  try {
+    const file = sessionFile(taskId);
+    if (!fs.existsSync(file)) return null;
+    return JSON.parse(fs.readFileSync(file, 'utf8'));
+  } catch (e) {
+    return null;
+  }
+}
+
+
+export function describeSession(taskId) {
+  const state = readSession(taskId);
+  if (!state || (!state.app && !state.lastActions)) return '';
+
+  const parts = [];
+  parts.push(`You were driving ${state.app ? `"${state.app}"` : 'the frontmost application'} before this session resumed.`);
+  if (Array.isArray(state.lastActions) && state.lastActions.length > 0) {
+    parts.push(`Your last actions were: ${state.lastActions.join(', ')}.`);
+    parts.push('You do NOT know whether they landed — the screen may have changed while you were gone.');
+  }
+  parts.push('Call ax_snapshot before acting again, and compare what you see to what you expected.');
+  return `\n\n🖥️ EMBODIMENT SESSION\n${parts.join(' ')}`;
+}
+
+/** Drop a task's session, e.g. when the task completes. */
+export function clearSession(taskId) {
+  try {
+    const file = sessionFile(taskId);
+    if (fs.existsSync(file)) fs.unlinkSync(file);
+  } catch (e) {
+    // Fail open.
+  }
+}
+
+/** Retire sessions past the retention window. Fire-and-forget, never throws. */
+export function pruneSessions() {
+  try {
+    if (!fs.existsSync(SESSION_DIR)) return;
+    const cutoff = Date.now() - RETENTION_MS;
+    for (const name of fs.readdirSync(SESSION_DIR)) {
+      const file = path.join(SESSION_DIR, name);
+      try {
+        if (fs.statSync(file).mtimeMs < cutoff) fs.unlinkSync(file);
+      } catch (e) { /* skip this one */ }
+    }
+  } catch (e) {
+    // Fail open.
+  }
+}
+
+/** Where sessions live. For diagnostics and tests. */
+export function getSessionDir() {
+  return SESSION_DIR;
+}

package/src/entrypoint.js

@@ -0,0 +1,194 @@
+import { program } from 'commander';
+
+import { runTask, chatMode, execCommand, interactiveConfig } from './cliMode.js';
+import { runSelfUpdate } from './autoUpdate.js';
+import { printContextReport, printUsageReport, printCheckpoints, printUndo, buildStatusText, printReport } from './reporting.js';
+import { runCommand } from './commands.js';
+import { resolveInvocation } from './tui/invocation.js';
+
+// The old flag remains parseable only to explain its retirement.
+function announceDevEmulator(requested) {
+  if (requested) console.log('Developer emulator mode is retired. Configure local budgets explicitly.');
+}
+/**
+ * Ask before something irreversible, without dragging in a prompt framework.
+ *
+ * These commands run outside the chat surface, so ChatPrompt's ConfirmLayer is
+ * not available — it needs the live region to draw into. A bare readline
+ * question is the honest primitive here. A non-TTY answers NO: an unattended
+ * `causyne undo` in a script must not silently rewrite the working tree, and
+ * `--yes` is the way a script says it meant it.
+ */
+async function confirmDestructive(question) {
+  if (!process.stdin.isTTY || !process.stdout.isTTY) return false;
+  const readline = (await import('readline')).default;
+  const rl = readline.createInterface({ input: process.stdin, output: process.stdout });
+  try {
+    const answer = await new Promise((resolve) => rl.question(`${question} [y/N] `, resolve));
+    return /^y(es)?$/i.test(String(answer).trim());
+  } finally {
+    rl.close();
+  }
+}
+
+import { getPackageVersion } from './version.js';
+const pkgVersion = getPackageVersion();
+
+
+program
+  // The advertised name. `causyne-agent` still resolves to the same launcher via
+  // the second entry in package.json "bin", but the help text has to teach ONE
+  // name or it teaches neither — a user who typed `causyne` and is answered
+  // "Usage: causyne-agent" reasonably concludes they ran the wrong thing.
+  .name('causyne')
+  .description('Causyne — Local desktop AI harness (alias: causyne-agent)')
+  .version(pkgVersion);
+
+program
+  .command('update')
+  .description('Show source update guidance (no automatic installation)')
+  .action(async () => {
+    await runSelfUpdate(true);
+  });
+
+program
+  .command('status')
+  .description('Show local provider, workspace and runtime status')
+  .action(() => printReport(buildStatusText(), { title: 'Status' }));
+
+program
+  .command('config')
+  .description('Configure Direct API Provider (Interactive)')
+  .option('-p, --provider <name>', 'Set LLM provider (openai, anthropic, gemini, muse, ollama, dashscope, deepseek)')
+  .option('-k, --apikey <key>', 'Set API key')
+  .option('-m, --model <name>', 'Set model name')
+  .action(async (options) => {
+    await interactiveConfig(options);
+  });
+
+program
+  .command('run <task>')
+  .description('Run a single task directly from the CLI')
+  .option('--dev-emulator', 'Retired compatibility flag; grants no additional permissions')
+  .action(async (task, options) => {
+    announceDevEmulator(options.devEmulator);
+    await runTask(task);
+  });
+
+program
+  .command('chat')
+  .description('Start interactive chat mode with the agent')
+  .option('--dev-emulator', 'Retired compatibility flag; grants no additional permissions')
+  .action(async (options) => {
+    announceDevEmulator(options.devEmulator);
+    await chatMode();
+  });
+
+program
+  .command('context')
+  .description('Show what fills the context window (tool schemas, window pool, spilled output)')
+  .action(async () => {
+    printContextReport();
+  });
+
+program
+  .command('usage')
+  .description('Show BYOK token usage and estimated cost (today and lifetime)')
+  .action(async () => {
+    await printUsageReport();
+  });
+
+program
+  .command('checkpoints')
+  .description('List recent undo checkpoints (files + conversation snapshots)')
+  .option('-n, --limit <count>', 'How many task groups to show', '15')
+  .action(async (options) => {
+    printCheckpoints(parseInt(options.limit, 10) || 15);
+  });
+
+program
+  .command('undo [taskId]')
+  .description("Roll back the last task's file changes and rewind the conversation")
+  .option('--step', 'Undo only the single most recent file change')
+  .option('--full', 'Also roll back files changed by terminal commands (reverts your own manual edits too)')
+  .option('--dry-run', 'Show what would change without writing anything')
+  .option('-y, --yes', 'Do not ask for confirmation')
+  .action(async (taskId, options) => {
+    const opts = { step: options.step, dryRun: options.dryRun, full: options.full };
+
+    // A rollback writes to the user's files, and this command had no gate at
+    // all: `causyne undo` restored immediately. The preview is the same code
+    // path with dryRun forced, so what is shown is exactly what will happen —
+    // not a description of it.
+    if (!options.dryRun && !options.yes) {
+      const { buildUndoText } = await import('./reporting.js');
+      const preview = buildUndoText(taskId, { ...opts, dryRun: true });
+      printReport(preview.text, { title: 'Undo preview' });
+      if (!(await confirmDestructive('Apply this rollback?'))) {
+        console.log('Cancelled. Nothing was written.');
+        process.exit(0);
+      }
+    }
+
+    // Explicit now that the default is a preview: reaching here means either
+    // --dry-run was asked for, or the user confirmed the preview above.
+    const ok = printUndo(taskId, { ...opts, dryRun: options.dryRun === true ? true : false });
+    process.exit(ok ? 0 : 1);
+  });
+
+program
+  .command('mcp [action] [args...]')
+  .description('Manage MCP servers: list (default), add, remove, grant, revoke')
+  // An MCP invocation is somebody else's command line — `npx -y @scope/server`
+  // is normal. Without this, commander claims `-y` as its own unknown option and
+  // the add fails before it reaches us. (passThroughOptions() would be the
+  // stricter tool but requires enablePositionalOptions() on the root command,
+  // which would change parsing for every other subcommand.)
+  .allowUnknownOption()
+  .action(async (action, args) => {
+    // Same registry the chat surfaces use, so `causyne-agent mcp` and `/mcp`
+    // can never disagree about what a server is or what enabling one means.
+    const argv = action ? [action, ...(args || [])] : [];
+    const result = await runCommand('mcp', argv, { surface: 'terminal' });
+    console.log('\n' + result.output + '\n');
+    process.exit(result.ok ? 0 : 1);
+  });
+
+program
+  .command('exec <command>')
+  .description('Quick execute a command using the agent terminal')
+  .action(async (command) => {
+    await execCommand(command);
+  });
+
+// Setup fallback for missing commands
+program.on('command:*', function () {
+  console.error('Invalid command: %s\nSee --help for a list of available commands.', program.args.join(' '));
+  process.exit(1);
+});
+
+// Bare `causyne` opens the application; anything else is a subcommand.
+//
+// This was `process.argv.length <= 2`, which is true only for the exact string
+// `causyne`. resolveInvocation() consumes declared root options first, so
+// `causyne --dev-emulator` is still bare, while an unknown option or any bare
+// word still goes to Commander to be dispatched or rejected. See
+// src/tui/invocation.js for why each rule is conservative in that direction.
+const invocation = resolveInvocation(process.argv);
+
+if (invocation.isBareRoot) {
+  if (!process.stdout.isTTY) {
+    // Nothing can be interactive here, and printing a wordmark into a pipe is
+    // noise. `causyne | cat` behaves like every other CLI: it says what it does.
+    program.outputHelp();
+    process.exit(0);
+  }
+  announceDevEmulator(invocation.rootOptions.includes('--dev-emulator'));
+  // A missing key is a hint on the home screen, not a gate in front of it.
+  chatMode({ home: true }).catch((e) => {
+    console.error(e && e.stack ? e.stack : e);
+    process.exit(1);
+  });
+} else {
+  program.parse(process.argv);
+}

package/src/execSafe.js

@@ -0,0 +1,21 @@
+import { exec, execSync as nodeExecSync } from 'node:child_process';
+
+// Compatibility wrapper, NOT a security boundary. These APIs invoke a shell.
+// Callers must enforce approval and validate input; prefer execFile with argv.
+export function execSync(command, options) {
+  return nodeExecSync(command, options);
+}
+
+export function execAsync(command, options = {}) {
+  return new Promise((resolve, reject) => {
+    exec(command, options, (error, stdout, stderr) => {
+      if (error) {
+        error.stdout = stdout;
+        error.stderr = stderr;
+        reject(error);
+        return;
+      }
+      resolve(typeof stdout === 'string' ? stdout : String(stdout ?? ''));
+    });
+  });
+}