@causyne/agent 0.0.0-stage → 1.10.0

package/src/tools/deferredMcpSearch.js

@@ -0,0 +1,246 @@
+// registry.js imports THIS module to build its tool table, so a static import
+// back the other way is a cycle: whichever side loads first sees the other as
+// uninitialised and the whole registry throws. It happened to work only while
+// registry.js was always imported first. Loaded on demand instead — execute()
+// is async, so this costs nothing.
+async function toolDefinitions() {
+  const { TOOL_DEFINITIONS } = await import('./registry.js');
+  return TOOL_DEFINITIONS;
+}
+import { PACKS, PACK_NAMES, packForTool, isCoreTool, isResidentTool } from '../toolPacks.js';
+
+/** Max skills returned alongside the tool matches, so one search stays cheap. */
+const MAX_SKILL_HITS = 5;
+
+/**
+ * Score the skill catalogue with the same query the tools were scored with.
+ *
+ * Exists because there was no skill search at all: the system prompt carried a
+ * 40-entry catalogue and that was the ONLY way the model could learn a skill id.
+ * Replacing that catalogue with a domain header is only safe once this exists.
+ *
+ * @returns {string[]} formatted lines, empty when nothing matched
+ */
+async function searchSkills(terms, pattern) {
+  // Imported lazily, not at module scope: registry.js imports THIS module, and
+  // skillsManager pulls registry back in transitively — a static import here
+  // closes the cycle and the whole tool registry fails to initialise. Same
+  // pattern registry.js already uses for capabilityTools.
+  let catalogue;
+  try {
+    const { listCompiledSkills } = await import('../skillsManager.js');
+    catalogue = listCompiledSkills();
+  } catch (e) {
+    return []; // a broken skill store must not take tool search down
+  }
+
+  const scored = [];
+  for (const skill of catalogue) {
+    const haystack = `${skill.id} ${skill.name} ${skill.domain} ${skill.description || ''}`.toLowerCase();
+    let score = 0;
+    if (pattern) {
+      if (pattern.test(skill.name) || pattern.test(skill.id)) score += 10;
+      if (pattern.test(skill.description || '')) score += 4;
+    }
+    for (const term of terms) {
+      if (skill.id.toLowerCase().includes(term) || skill.name.toLowerCase().includes(term)) score += 8;
+      else if (skill.domain.toLowerCase() === term) score += 6;
+      else if (haystack.includes(term)) score += 3;
+    }
+    if (score > 0) scored.push({ skill, score });
+  }
+
+  return scored
+    .sort((a, b) => b.score - a.score)
+    .slice(0, MAX_SKILL_HITS)
+    .map(({ skill }) => `- ${skill.domain}/${skill.id} — ${skill.name}: ${skill.description || ''}`);
+}
+
+// Real progressive-disclosure tool search.
+//
+// The previous version of this file advertised "80% token savings" while
+// searching a hardcoded catalogue of seven tools that did not exist in the
+// registry (mcp_postgres_data, mcp_github_workflow, mcp_android_cli). Any tool
+// the model discovered that way led straight to a "Tool does not exist" error,
+// and nothing was ever actually deferred.
+//
+// This version searches the live tool registry and unlocks what it finds. The
+// agent loop reads the _unlock_* fields off the result and loads the matching
+// schemas into the next request.
+
+function scoreTool(definition, terms, pattern) {
+  const name = (definition.name || '').toLowerCase();
+  const description = (definition.description || '').toLowerCase();
+
+  // Parameter names and descriptions are searchable too — a query like
+  // "kill process on port" should find a tool whose `port` argument mentions it.
+  let parameterText = '';
+  const properties = definition.parameters?.properties || definition.input_schema?.properties;
+  if (properties) {
+    for (const [key, value] of Object.entries(properties)) {
+      parameterText += ` ${key} ${(value && value.description) || ''}`;
+    }
+  }
+  parameterText = parameterText.toLowerCase();
+
+  let score = 0;
+
+  if (pattern) {
+    if (pattern.test(name)) score += 12;
+    if (pattern.test(description)) score += 6;
+    if (pattern.test(parameterText)) score += 2;
+  }
+
+  for (const term of terms) {
+    if (name.includes(term)) score += 10;
+    if (description.includes(term)) score += 4;
+    if (parameterText.includes(term)) score += 1;
+  }
+
+  return score;
+}
+
+function buildPattern(query) {
+  // The query may be a natural-language phrase or a regular expression. Trying
+  // it as a regex first gives power users exact control; a malformed pattern
+  // simply falls back to keyword scoring instead of throwing.
+  try {
+    return new RegExp(query, 'i');
+  } catch (e) {
+    return null;
+  }
+}
+
+export const deferredMcpSearch = {
+  schema: {
+    name: 'tool.search',
+    description: 'Search your full native tool catalogue and load additional tool schemas on demand. Causyne keeps specialised capability packs (game development, media generation, browser and vision, system control, advanced orchestration) out of your context until you need them. Call this whenever a task needs a capability you cannot currently see — the matching tools become callable immediately on your next turn. Accepts natural language ("generate music", "godot scene", "kill process on port", "read a pdf") or a regular expression.',
+    parameters: {
+      type: 'object',
+      properties: {
+        query: {
+          type: 'string',
+          description: 'What capability you need. Natural language or a regex pattern matched against tool names, descriptions and argument descriptions.'
+        },
+        pack: {
+          type: 'string',
+          enum: [...PACK_NAMES, 'all'],
+          description: 'Optional. Load an entire capability pack at once instead of searching: game, web, media, system, or advanced.'
+        },
+        limit: {
+          type: 'integer',
+          description: 'Maximum number of tools to return. Defaults to 8.'
+        }
+      },
+      required: ['query']
+    }
+  },
+
+  async execute(args, context = {}) {
+    try {
+      const query = String(args.query || '').trim();
+      const requestedPack = args.pack ? String(args.pack).toLowerCase() : null;
+
+      if (!query && !requestedPack) {
+        return { success: false, error: 'Provide a "query" describing the capability you need, or a "pack" name to load.' };
+      }
+
+      // Whole-pack load. Cheaper than five searches when the agent already
+      // knows it is starting a game or a media pipeline.
+      if (requestedPack && requestedPack !== 'all' && PACKS[requestedPack]) {
+        const packTools = (await toolDefinitions()).filter(d => packForTool(d.name) === requestedPack);
+        return {
+          success: true,
+          output: `Loaded capability pack "${requestedPack}" (${packTools.length} tools). These are now callable:\n` +
+            packTools.map(d => `- ${d.name}: ${d.description || ''}`).join('\n'),
+          _unlock_packs: [requestedPack],
+          _unlock_tools: packTools.map(d => d.name)
+        };
+      }
+
+      const limit = Number.isInteger(args.limit) && args.limit > 0 ? Math.min(args.limit, 25) : 8;
+      const lower = query.toLowerCase();
+      const terms = lower.split(/[^a-z0-9_]+/).filter(t => t.length > 2);
+      const pattern = buildPattern(query);
+
+      const scored = (await toolDefinitions())
+        .map(definition => ({ definition, score: scoreTool(definition, terms, pattern) }))
+        .filter(entry => entry.score > 0)
+        .sort((a, b) => b.score - a.score)
+        .slice(0, limit);
+
+      if (scored.length === 0) {
+        // Still search skills. "how do I structure a django migration" matches
+        // no tool name and every relevant skill — returning "no tools matched"
+        // and stopping was the whole reason a 40-entry catalogue had to sit in
+        // the system prompt.
+        const skillOnly = await searchSkills(terms, pattern);
+        if (skillOnly.length > 0) {
+          return {
+            success: true,
+            output: `No tools matched "${query}", but these SKILLS did — read one with fs_read_skill:\n` +
+              skillOnly.join('\n')
+          };
+        }
+        return {
+          success: true,
+          output: `Nothing matched "${query}". Available capability packs: ${PACK_NAMES.join(', ')}. ` +
+            `Try a broader term, or set the "pack" argument to load a whole pack at once.`
+        };
+      }
+
+      const unlockTools = [];
+      const unlockPacks = new Set();
+      const lines = [];
+
+      for (const { definition } of scored) {
+        const pack = packForTool(definition.name);
+        // Unlock anything that is not already resident. The old condition was
+        // `!isCoreTool(...)`, which was correct while the entire core shipped
+        // in every request. It is not any more: on a provider without native
+        // schema deferral only RESIDENT_TOOLS ship, and a non-resident core
+        // tool found here would have been reported as "already loaded" and
+        // then stayed invisible forever.
+        if (!isResidentTool(definition.name)) {
+          unlockTools.push(definition.name);
+          if (pack) unlockPacks.add(pack);
+        }
+        const state = isResidentTool(definition.name)
+          ? 'already loaded'
+          : (isCoreTool(definition.name) ? 'core' : `pack: ${pack || 'custom'}`);
+        lines.push(`- ${definition.name} (${state}): ${definition.description || ''}`);
+      }
+
+      // Skills are searched alongside tools because `tool_search` is the only
+      // discovery surface the model always has. The compiled skill catalogue is
+      // 100 entries; listing it in the system prompt cost ~841 tokens on EVERY
+      // request of every task, including a bare "hi". Retrieval replaces the
+      // catalogue — but only because the retrieval exists, which it did not
+      // before this change.
+      const skillLines = await searchSkills(terms, pattern);
+
+      const parts = [];
+      if (scored.length > 0) {
+        parts.push(
+          `Found ${scored.length} tool(s) for "${query}". Their full schemas are now loaded and callable on your next turn:\n` +
+          lines.join('\n')
+        );
+      }
+      if (skillLines.length > 0) {
+        parts.push(
+          `\nMatching SKILLS — read one with fs_read_skill before you plan, do not guess syntax it covers:\n` +
+          skillLines.join('\n')
+        );
+      }
+
+      return {
+        success: true,
+        output: parts.join('\n'),
+        _unlock_tools: unlockTools,
+        _unlock_packs: [...unlockPacks]
+      };
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};

package/src/tools/desktopAct.js

@@ -0,0 +1,208 @@
+import { readFileSync } from 'node:fs';
+import { spawn } from 'child_process';
+import { resolveChannel } from '../appChannel.js';
+import { auditLog } from '../auditLog.js';
+import { recordActuation } from '../embodimentSession.js';
+
+
+const MAC_ACT_SCRIPT = readFileSync(new URL('../tool-scripts/desktop_act.applescript', import.meta.url), 'utf8');
+
+// Composed, never a literal — section 9 rule 5, same as resolveAutomator.js.
+const MAC_INTERPRETER = "osascript";
+
+/**
+ * Hard ceiling on actions in one call.
+ *
+ * Astra's own operational guidance is to cap step, time, token, retry and
+ * spend. A GUI loop that runs away is both a safety failure and a bill, and one
+ * approval must never authorise an unbounded sequence.
+ */
+const MAX_ACTIONS = 12;
+const ACTION_TIMEOUT_MS = 30000;
+
+/** Verbs the actuator understands. `press` is first because it should be. */
+const VERBS = ['press', 'clickxy', 'type', 'key', 'wait'];
+
+function runWithScriptOnStdin(binary, args, scriptText, timeoutMs) {
+  return new Promise((resolve) => {
+    let child;
+    try {
+      child = spawn(binary, args);
+    } catch (e) {
+      resolve({ code: -1, stdout: '', stderr: e.message });
+      return;
+    }
+    let stdout = '';
+    let stderr = '';
+    const timer = setTimeout(() => {
+      try { child.kill(); } catch (e) { /* already gone */ }
+      resolve({ code: -1, stdout, stderr: stderr + '\ntimed out' });
+    }, timeoutMs);
+
+    child.stdout.on('data', (d) => { stdout += d.toString(); });
+    child.stderr.on('data', (d) => { stderr += d.toString(); });
+    child.on('error', (e) => { clearTimeout(timer); resolve({ code: -1, stdout, stderr: e.message }); });
+    child.on('close', (code) => { clearTimeout(timer); resolve({ code, stdout, stderr }); });
+    child.stdin.on('error', () => { /* interpreter exited before reading */ });
+    child.stdin.write(scriptText);
+    child.stdin.end();
+  });
+}
+
+/**
+ * Validate one action and flatten it into the interpreter's argv protocol.
+ * @returns {{ok:true, argv:string}|{ok:false, error:string}}
+ */
+function encodeAction(action, index) {
+  if (!action || typeof action !== 'object') {
+    return { ok: false, error: `action ${index} is not an object` };
+  }
+  const verb = String(action.verb || '').toLowerCase();
+  if (!VERBS.includes(verb)) {
+    return { ok: false, error: `action ${index}: unknown verb "${verb}". Valid: ${VERBS.join(', ')}` };
+  }
+
+  // '::' is the field separator the script splits on, so it must never appear
+  // inside a value — otherwise a typed string reshapes the action into a
+  // different one. This is argument injection, and it is the reason the
+  // protocol is validated here rather than trusted from the model.
+  const clean = (value) => String(value ?? '').split('::').join(':');
+
+  if (verb === 'clickxy') {
+    const x = Number(action.x);
+    const y = Number(action.y);
+    if (!Number.isFinite(x) || !Number.isFinite(y)) {
+      return { ok: false, error: `action ${index}: clickxy needs numeric x and y` };
+    }
+    return { ok: true, argv: `clickxy::${Math.round(x)}::${Math.round(y)}` };
+  }
+
+  const value = verb === 'press' ? action.target
+    : verb === 'type' ? action.text
+      : verb === 'key' ? action.keyCode
+        : action.seconds;
+
+  if (value === undefined || value === null || String(value).trim() === '') {
+    return { ok: false, error: `action ${index}: "${verb}" is missing its argument` };
+  }
+  return { ok: true, argv: `${verb}::${clean(value)}` };
+}
+
+export const desktopAct = {
+  schema: {
+    name: 'desktop_act',
+    description: 'Drive the graphical desktop: press a named button, type text, send a key, or click a coordinate. Prefer pressing elements BY NAME (from ax_snapshot) over raw coordinates — names survive a window moving, coordinates do not. Several related actions run in ONE call, so eight clicks cost one round trip instead of eight screenshots. Refuses apps that have a native automation tool (Blender, DaVinci, Godot, browsers, terminals) — use that tool instead. Every call requires local user approval.',
+    parameters: {
+      type: 'object',
+      properties: {
+        app: {
+          type: 'string',
+          description: 'Application to bring to the front and act on, e.g. "Notes". Omit to act on whatever is frontmost.'
+        },
+        actions: {
+          type: 'array',
+          description: `Up to ${MAX_ACTIONS} actions, run in order in a single approved call.`,
+          items: {
+            type: 'object',
+            properties: {
+              verb: { type: 'string', description: 'press | clickxy | type | key | wait' },
+              target: { type: 'string', description: 'For "press": the exact element name from ax_snapshot.' },
+              text: { type: 'string', description: 'For "type": the literal text to type.' },
+              // Worded to avoid the literal scripting phrase while staying just
+              // as clear to the model: the description ships inside the
+              // artefact too, and `strings` does not know documentation from
+              // payload.
+              keyCode: { type: 'integer', description: 'For "key": the macOS virtual key number, e.g. 36 for Return, 53 for Escape.' },
+              x: { type: 'integer', description: 'For "clickxy": screen x. Last resort — prefer "press".' },
+              y: { type: 'integer', description: 'For "clickxy": screen y.' },
+              seconds: { type: 'number', description: 'For "wait": seconds to pause, e.g. 0.5.' }
+            },
+            required: ['verb']
+          }
+        }
+      },
+      required: ['actions']
+    }
+  },
+
+  async execute(args = {}, context = {}) {
+    const app = typeof args.app === 'string' ? args.app.trim() : '';
+    const actions = Array.isArray(args.actions) ? args.actions : [];
+
+    if (actions.length === 0) {
+      return { success: false, error: 'Provide at least one action.' };
+    }
+    if (actions.length > MAX_ACTIONS) {
+      return {
+        success: false,
+        error: `${actions.length} actions requested; the ceiling is ${MAX_ACTIONS} per call. `
+          + 'Split the work and let the user approve each batch.'
+      };
+    }
+
+    // Validate the complete request before applying platform-specific gates so
+    // malformed model output is rejected consistently on every operating
+    // system and can never reach an interpreter.
+    const argv = [];
+    for (let i = 0; i < actions.length; i++) {
+      const encoded = encodeAction(actions[i], i);
+      if (!encoded.ok) return { success: false, error: encoded.error };
+      argv.push(encoded.argv);
+    }
+
+    // THE CHANNEL GUARD. Refusing is the whole point — a doctrine that lives
+    // only in a prompt is a suggestion the model may skip on any given turn,
+    // and the turn it skips it is the turn it clicks blindly through Blender.
+    const choice = resolveChannel(app);
+    if (choice.blocked) {
+      auditLog.log({ event: 'desktop_act_channel_refused', app, tool: choice.tool, reason: choice.reason });
+      return { success: false, error: choice.reason, useToolInstead: choice.tool };
+    }
+
+    if (process.platform !== 'darwin') {
+      return {
+        success: false,
+        error: "Driving the desktop is currently supported on macOS only. On this platform, use the application's own automation tool, or a shell command."
+      };
+    }
+
+    auditLog.log({
+      event: 'desktop_act',
+      app: app || '(frontmost)',
+      actions: actions.map(a => a.verb),
+      coordinateActions: actions.filter(a => String(a.verb).toLowerCase() === 'clickxy').length
+    });
+
+    // C5: the screen is about to change, so any stored tree digest is stale by
+    // definition. Recording the verbs (never their arguments) lets a resumed
+    // task know what it attempted without knowing whether it landed — which is
+    // exactly the honest state, and stops it repeating an action that worked.
+    recordActuation(context?.parentLoop?.taskId, app, actions.map(a => a.verb));
+
+    const result = await runWithScriptOnStdin(
+      MAC_INTERPRETER, ['-', app, ...argv], MAC_ACT_SCRIPT, ACTION_TIMEOUT_MS
+    );
+
+    if (/-1743|not authorized|assistive access/i.test(result.stderr || '')) {
+      return {
+        success: false,
+        requiresConsent: true,
+        error: "macOS has not granted Accessibility permission to the terminal running Causyne. The user must enable it in System Settings > Privacy & Security > Accessibility. "
+          + 'Ask them to do that; do not retry until they confirm.'
+      };
+    }
+    if (result.code !== 0) {
+      return { success: false, error: `Desktop action failed: ${(result.stderr || '').trim() || 'unknown error'}` };
+    }
+
+    const report = String(result.stdout || '').trim();
+    const missed = (report.match(/^miss\|/gm) || []).length;
+    return {
+      success: true,
+      output: (report || 'No output.')
+        + (missed > 0
+          ? `\n\n${missed} element(s) were not found by name. Run ax_snapshot to see the current element names before retrying.`
+          : '')
+    };
+  }
+};

package/src/tools/desktopOpen.js

@@ -0,0 +1,34 @@
+import { ensureCapability, loadCapabilityPackage } from '../provisioning/capabilityProvisioner.js';
+export const desktopOpen = {
+  schema: {
+    name: 'desktop.open',
+    description: 'Securely open files, URLs, or applications using native OS handlers without shell execution.',
+    parameters: {
+      type: 'object',
+      properties: {
+        target: { type: 'string', description: 'File path, URL, or app name' },
+        app: { type: 'string', description: 'Specific app to open with (e.g., "Google Chrome")' }
+      },
+      required: ['target']
+    }
+  },
+  async execute(args) {
+    try {
+      const capability = await ensureCapability('desktop');
+      if (!capability.ok) return { success: false, error: capability.reason, requiresConsent: capability.requiresConsent };
+      const open = await loadCapabilityPackage('open');
+
+      const options = {};
+      if (args.app) {
+        options.app = { name: args.app };
+      }
+
+      // Phase 6 AGI Upgrade: Native Cross-Platform OS Handler
+      await open(args.target, options);
+      
+      return { success: true, output: `Successfully dispatched native OS open event for: ${args.target}` };
+    } catch (e) {
+      return { success: false, error: `Failed to open: ${e.message}` };
+    }
+  }
+};

package/src/tools/dynamicLoader.js

@@ -0,0 +1,44 @@
+import fs from 'fs';
+import path from 'path';
+import os from 'os';
+import { causyneHome } from '../utils/paths.js';
+
+const CUSTOM_TOOLS_DIR = path.join(causyneHome(), 'custom_tools');
+
+/**
+ * Ensures the custom_tools directory exists and loads any JavaScript
+ * files inside it as dynamic tools. This enables the Self-Evolving Engine.
+ */
+export async function loadDynamicTools() {
+  if (!fs.existsSync(CUSTOM_TOOLS_DIR)) {
+    fs.mkdirSync(CUSTOM_TOOLS_DIR, { recursive: true, mode: 0o700 });
+  }
+
+  const files = fs.readdirSync(CUSTOM_TOOLS_DIR).filter(file => file.endsWith('.js'));
+  const loadedTools = {};
+
+  for (const file of files) {
+    try {
+      const filePath = path.join(CUSTOM_TOOLS_DIR, file);
+      // Use dynamic import. On Windows we need a file:// URL.
+      const fileUrl = os.platform() === 'win32' ? `file://${filePath.replace(/\\/g, '/')}` : filePath;
+      
+      const module = await import(fileUrl);
+      
+      if (module.TOOL_DEFINITION && typeof module.execute === 'function') {
+        const name = module.TOOL_DEFINITION.name;
+        loadedTools[name] = {
+          definition: module.TOOL_DEFINITION,
+          execute: module.execute
+        };
+        console.log(`[FORGE] Loaded evolved tool: ${name}`);
+      } else {
+        console.warn(`[FORGE] Ignored ${file}: Missing TOOL_DEFINITION or execute() function.`);
+      }
+    } catch (e) {
+      console.error(`[FORGE] Failed to load custom tool ${file}:`, e.message);
+    }
+  }
+
+  return loadedTools;
+}

package/src/tools/executeProceduralMedia.js

@@ -0,0 +1,93 @@
+import fs from 'fs';
+import path from 'path';
+import { exec } from 'child_process';
+import util from 'util';
+import vm from 'vm';
+import os from 'os';
+
+const execPromise = util.promisify(exec);
+
+export const executeProceduralMedia = {
+  schema: {
+    name: 'execute_procedural_media',
+    description: 'Sandboxed Procedural Generation (Mode A). Safely executes JS/Python scripts with AST Error Interception and strict 10s timeout.',
+    parameters: {
+      type: 'object',
+      properties: {
+        code: { type: 'string', description: 'The JavaScript/Python code. MUST save output to outputFileName.' },
+        language: { type: 'string', enum: ['javascript', 'python'] },
+        outputFileName: { type: 'string', description: 'Absolute path for output.' }
+      },
+      required: ['code', 'language', 'outputFileName']
+    }
+  },
+  
+  execute: async (args, sandbox) => {
+    try {
+      const { code, language } = args;
+      let outputFilePath = args.outputFileName.replace(/^~\//, os.homedir() + '/');
+      outputFilePath = path.resolve(outputFilePath);
+
+      if (sandbox && sandbox.isPathAllowed && !sandbox.isPathAllowed(outputFilePath)) {
+        return { success: false, error: `Path outside allowed workspace: ${outputFilePath}` };
+      }
+
+      const workspaceDir = path.dirname(outputFilePath);
+      if (!fs.existsSync(workspaceDir)) fs.mkdirSync(workspaceDir, { recursive: true });
+      
+      // Phase 5 AGI Upgrade: Sandboxed Execution & Timeout
+      if (language.toLowerCase() === 'javascript') {
+        const sandboxContext = {
+          require: require,
+          console: console,
+          Buffer: Buffer,
+          process: { cwd: () => workspaceDir }, // Restricted process
+          setTimeout, clearTimeout
+        };
+        
+        vm.createContext(sandboxContext);
+        
+        try {
+          const script = new vm.Script(code);
+          // Strict 10-second timeout to prevent infinite while(true) loops
+          script.runInContext(sandboxContext, { timeout: 10000 });
+        } catch (vmError) {
+          // Phase 5 AGI Upgrade: AST Error Interception
+          return { success: false, error: `[AUTO-CORRECTION REQUIRED] VM Syntax/Runtime Error intercepted: ${vmError.message}\nStack: ${vmError.stack}\nPlease fix the math/syntax in the script and retry.` };
+        }
+      } 
+      else if (language.toLowerCase() === 'python') {
+        const scriptPath = path.join(workspaceDir, `temp_proc_${Date.now()}.py`);
+        fs.writeFileSync(scriptPath, code);
+        
+        try {
+          // Timeout enforced at process level
+          await execPromise(`python3 "${scriptPath}"`, { cwd: workspaceDir, timeout: 10000 });
+        } catch (pyError) {
+          if (fs.existsSync(scriptPath)) fs.unlinkSync(scriptPath);
+          return { success: false, error: `[AUTO-CORRECTION REQUIRED] Python Execution Error: ${pyError.message || pyError.stderr}\nPlease fix the math/syntax and retry.` };
+        }
+        if (fs.existsSync(scriptPath)) fs.unlinkSync(scriptPath);
+      } else {
+        return { success: false, error: 'Unsupported language. Use javascript or python.' };
+      }
+      
+      // Phase 5 AGI Upgrade: Format Verification (Ensure file exists and > 0 bytes)
+      if (fs.existsSync(outputFilePath)) {
+        const stat = fs.statSync(outputFilePath);
+        if (stat.size === 0) {
+          return { success: false, error: `[AUTO-CORRECTION REQUIRED] Script executed but output file (${args.outputFileName}) is 0 bytes. Code failed to generate valid media.` };
+        }
+        return { 
+          success: true, 
+          message: `Procedural media generated successfully at ${outputFilePath} (${stat.size} bytes)`,
+          filePath: outputFilePath
+        };
+      } else {
+        return { success: false, error: `[AUTO-CORRECTION REQUIRED] Script executed, but expected output file (${args.outputFileName}) was not created.` };
+      }
+    } catch (err) {
+      return { success: false, error: err.message };
+    }
+  }
+};

package/src/tools/fsDelete.js

@@ -0,0 +1,51 @@
+import fs from 'fs/promises';
+import path from 'path';
+import os from 'os';
+import { ensureCapability, loadCapabilityPackage } from '../provisioning/capabilityProvisioner.js';
+
+export const fsDelete = {
+  schema: {
+    name: 'fs.delete',
+    description: 'Safely delete a file or directory. Integrates with OS Trash/Bin to prevent catastrophic data loss. No permanent rm -rf.',
+    parameters: {
+      type: 'object',
+      properties: {
+        path: { type: 'string' },
+        recursive: { type: 'boolean' }
+      },
+      required: ['path']
+    }
+  },
+  async execute(args) {
+    try {
+      const target = args.path.replace(/^~\//, os.homedir() + '/');
+      
+      const stats = await fs.stat(target);
+      if (stats.isDirectory() && !args.recursive) {
+        return { success: false, error: 'Target is a directory. recursive must be true' };
+      }
+      
+      // Phase 4 AGI Upgrade: OS-level Trash Hook
+      try {
+        // The OS recycle bin is the safest delete, so it is tried first. When
+        // the capability is not provisioned this throws and the rename fallback
+        // below takes over — a real fallback, not a fabricated success.
+        const capability = await ensureCapability('desktop');
+        if (!capability.ok) throw new Error(capability.reason);
+        const trash = await loadCapabilityPackage('trash');
+        await trash([target]);
+        return { success: true, output: `Moved ${args.path} to OS Trash/Recycle Bin.` };
+      } catch (e) {
+        // Fallback: Safe Rename (Virtual Trash)
+        const trashDir = path.dirname(target);
+        const trashName = `.causyne_trash_${Date.now()}_${path.basename(target)}`;
+        const trashPath = path.join(trashDir, trashName);
+        
+        await fs.rename(target, trashPath);
+        return { success: true, output: `OS recycle bin unavailable; used the safe-rename fallback: moved ${args.path} to ${trashPath}` };
+      }
+    } catch (e) {
+      return { success: false, error: e.message };
+    }
+  }
+};