@causyne/agent 1.10.13 → 1.10.17

package/src/plugins/pluginManager.js

@@ -4,6 +4,7 @@ import crypto from 'node:crypto';
 import { spawn } from 'node:child_process';
 import { fileURLToPath } from 'node:url';
 import { causyneHome } from '../utils/paths.js';
+import { parsePluginSkills } from './pluginSkills.js';
 
 const PLUGIN_ROOT = path.join(causyneHome(), 'plugins');
 const STATE_FILE = path.join(PLUGIN_ROOT, 'state.json');
@@ -131,14 +132,15 @@ function readPlugin(directory) {
   if (typeof manifest.description !== 'string' || !manifest.description.trim()) {
     throw new Error('Plugin description is required');
   }
-  if (!Array.isArray(manifest.tools)) throw new Error('Plugin tools must be an array');
-  if (manifest.tools.length > MAX_TOOLS_PER_PLUGIN) {
+  const manifestTools = manifest.tools ?? [];
+  if (!Array.isArray(manifestTools)) throw new Error('Plugin tools must be an array');
+  if (manifestTools.length > MAX_TOOLS_PER_PLUGIN) {
     throw new Error(`Plugin exceeds ${MAX_TOOLS_PER_PLUGIN} tools`);
   }
 
   const pluginCapabilities = validateCapabilities(manifest.capabilities, manifest.name);
   const names = new Set();
-  const tools = manifest.tools.map((tool) => {
+  const tools = manifestTools.map((tool) => {
     if (!TOOL_NAME.test(tool?.name || '')) throw new Error(`Invalid tool name ${JSON.stringify(tool?.name)}`);
     if (names.has(tool.name)) throw new Error(`Duplicate tool name ${tool.name}`);
     names.add(tool.name);
@@ -164,6 +166,10 @@ function readPlugin(directory) {
         : DEFAULT_TIMEOUT_MS
     };
   });
+  const skills = parsePluginSkills(directory, manifest.name, manifest.skills);
+  if (tools.length === 0 && skills.length === 0) {
+    throw new Error('Plugin must contribute at least one tool or skill');
+  }
 
   return {
     directory,
@@ -173,7 +179,8 @@ function readPlugin(directory) {
     // changing plugin.json and would inherit stale trust.
     digest: digestPluginDirectory(directory),
     manifest: { ...manifest, capabilities: pluginCapabilities },
-    tools
+    tools,
+    skills
   };
 }
 
@@ -202,6 +209,7 @@ export function listPlugins() {
         digest: plugin.digest,
         capabilities: plugin.manifest.capabilities,
         tools: plugin.tools.map((tool) => tool.name),
+        skills: plugin.skills.map((skill) => `${skill.domain}/${skill.id}`),
         path: plugin.directory
       });
     } catch (error) {
@@ -218,7 +226,14 @@ export function enablePlugin(name) {
     const state = readState();
     state.plugins[name] = { enabled: true, digest: plugin.digest, enabledAt: Date.now() };
     writeState(state);
-    return { ok: true, name, digest: plugin.digest, capabilities: plugin.manifest.capabilities, tools: plugin.tools.map((tool) => tool.name) };
+    return {
+      ok: true,
+      name,
+      digest: plugin.digest,
+      capabilities: plugin.manifest.capabilities,
+      tools: plugin.tools.map((tool) => tool.name),
+      skills: plugin.skills.map((skill) => `${skill.domain}/${skill.id}`)
+    };
   } catch (error) {
     return { ok: false, error: error.message };
   }
@@ -314,6 +329,26 @@ export function getPluginToolDefinitions() {
   }));
 }
 
+/**
+ * Reviewed, enabled plugins may contribute prompt-only skills. Discovery has
+ * already parsed these as inert UTF-8 data; no plugin module is imported.
+ */
+export function getPluginSkills() {
+  const state = readState();
+  const skills = [];
+  for (const directory of pluginDirectories()) {
+    try {
+      const plugin = readPlugin(directory);
+      const trust = safeObject(state.plugins[plugin.manifest.name]);
+      if (!trust.enabled || trust.digest !== plugin.digest) continue;
+      skills.push(...plugin.skills);
+    } catch (error) {
+      // Invalid or modified plugins contribute nothing to the prompt.
+    }
+  }
+  return skills;
+}
+
 function permissionArgs(tool, workspaceRoot) {
   // Node resolves `.js` module type by walking to package.json. Grant that one
   // metadata file explicitly; granting the repository root would let an

package/src/plugins/pluginSkills.js

@@ -0,0 +1,84 @@
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_SKILLS_PER_PLUGIN = 32;
+const MAX_SKILL_BYTES = 32 * 1024;
+const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+function resolveInside(root, relativePath) {
+    const resolvedRoot = path.resolve(root);
+    const resolved = path.resolve(root, relativePath);
+    if (resolved === resolvedRoot || !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+        throw new Error(`Skill path escapes plugin root: ${relativePath}`);
+    }
+    return resolved;
+}
+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 readSkillFile(file) {
+    const stat = fs.lstatSync(file);
+    if (!stat.isFile() || stat.isSymbolicLink())
+        throw new Error(`${file} must be a regular file`);
+    if (stat.size > MAX_SKILL_BYTES)
+        throw new Error(`${file} exceeds ${MAX_SKILL_BYTES / 1024} KB`);
+    return fs.readFileSync(file, 'utf8')
+        // Keep newlines and tabs, but remove control bytes that can corrupt a prompt.
+        // eslint-disable-next-line no-control-regex
+        .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+/**
+ * Validate plugin-contributed skills without importing or evaluating plugin
+ * code. A skill becomes visible only after the caller verifies the plugin's
+ * whole-directory digest against the explicit enablement record.
+ */
+export function parsePluginSkills(directory, pluginName, value) {
+    if (value === undefined)
+        return [];
+    if (!Array.isArray(value))
+        throw new Error('Plugin skills must be an array');
+    if (value.length > MAX_SKILLS_PER_PLUGIN) {
+        throw new Error(`Plugin exceeds ${MAX_SKILLS_PER_PLUGIN} skills`);
+    }
+    const domain = `plugin-${pluginName}`;
+    const ids = new Set();
+    return value.map((raw, index) => {
+        if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+            throw new Error(`Skill ${index + 1} must be an object`);
+        }
+        const input = raw;
+        const id = String(input.id ?? '');
+        if (!SKILL_ID.test(id))
+            throw new Error(`Invalid plugin skill id ${JSON.stringify(id)}`);
+        if (ids.has(id))
+            throw new Error(`Duplicate plugin skill id ${id}`);
+        ids.add(id);
+        const name = cleanLine(input.name ?? id, 120);
+        const description = cleanLine(input.description, 400);
+        if (!name)
+            throw new Error(`Plugin skill ${id} needs a name`);
+        if (!description)
+            throw new Error(`Plugin skill ${id} needs a description`);
+        if (typeof input.file !== 'string' || !input.file) {
+            throw new Error(`Plugin skill ${id} needs a file`);
+        }
+        const file = resolveInside(directory, input.file);
+        const content = readSkillFile(file);
+        if (!content.trim())
+            throw new Error(`Plugin skill ${id} is empty`);
+        return {
+            domain,
+            id,
+            name,
+            description,
+            content,
+            source: 'plugin',
+            plugin: pluginName,
+            path: file
+        };
+    });
+}
+export { MAX_SKILLS_PER_PLUGIN, MAX_SKILL_BYTES };

package/src/plugins/pluginSkills.ts

@@ -0,0 +1,106 @@
+import fs from 'node:fs';
+import path from 'node:path';
+
+const MAX_SKILLS_PER_PLUGIN = 32;
+const MAX_SKILL_BYTES = 32 * 1024;
+const SKILL_ID = /^[a-z0-9][a-z0-9-]{0,63}$/;
+
+export interface PluginSkillManifestInput {
+  id?: unknown;
+  name?: unknown;
+  description?: unknown;
+  file?: unknown;
+}
+
+export interface PluginSkill {
+  domain: string;
+  id: string;
+  name: string;
+  description: string;
+  content: string;
+  source: 'plugin';
+  plugin: string;
+  path: string;
+}
+
+function resolveInside(root: string, relativePath: string): string {
+  const resolvedRoot = path.resolve(root);
+  const resolved = path.resolve(root, relativePath);
+  if (resolved === resolvedRoot || !resolved.startsWith(`${resolvedRoot}${path.sep}`)) {
+    throw new Error(`Skill path escapes plugin root: ${relativePath}`);
+  }
+  return resolved;
+}
+
+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 readSkillFile(file: string): string {
+  const stat = fs.lstatSync(file);
+  if (!stat.isFile() || stat.isSymbolicLink()) throw new Error(`${file} must be a regular file`);
+  if (stat.size > MAX_SKILL_BYTES) throw new Error(`${file} exceeds ${MAX_SKILL_BYTES / 1024} KB`);
+  return fs.readFileSync(file, 'utf8')
+    // Keep newlines and tabs, but remove control bytes that can corrupt a prompt.
+    // eslint-disable-next-line no-control-regex
+    .replace(/[\x00-\x08\x0b\x0c\x0e-\x1f\x7f]/g, '');
+}
+
+/**
+ * Validate plugin-contributed skills without importing or evaluating plugin
+ * code. A skill becomes visible only after the caller verifies the plugin's
+ * whole-directory digest against the explicit enablement record.
+ */
+export function parsePluginSkills(
+  directory: string,
+  pluginName: string,
+  value: unknown
+): PluginSkill[] {
+  if (value === undefined) return [];
+  if (!Array.isArray(value)) throw new Error('Plugin skills must be an array');
+  if (value.length > MAX_SKILLS_PER_PLUGIN) {
+    throw new Error(`Plugin exceeds ${MAX_SKILLS_PER_PLUGIN} skills`);
+  }
+
+  const domain = `plugin-${pluginName}`;
+  const ids = new Set<string>();
+  return value.map((raw, index) => {
+    if (raw === null || typeof raw !== 'object' || Array.isArray(raw)) {
+      throw new Error(`Skill ${index + 1} must be an object`);
+    }
+    const input = raw as PluginSkillManifestInput;
+    const id = String(input.id ?? '');
+    if (!SKILL_ID.test(id)) throw new Error(`Invalid plugin skill id ${JSON.stringify(id)}`);
+    if (ids.has(id)) throw new Error(`Duplicate plugin skill id ${id}`);
+    ids.add(id);
+
+    const name = cleanLine(input.name ?? id, 120);
+    const description = cleanLine(input.description, 400);
+    if (!name) throw new Error(`Plugin skill ${id} needs a name`);
+    if (!description) throw new Error(`Plugin skill ${id} needs a description`);
+    if (typeof input.file !== 'string' || !input.file) {
+      throw new Error(`Plugin skill ${id} needs a file`);
+    }
+    const file = resolveInside(directory, input.file);
+    const content = readSkillFile(file);
+    if (!content.trim()) throw new Error(`Plugin skill ${id} is empty`);
+
+    return {
+      domain,
+      id,
+      name,
+      description,
+      content,
+      source: 'plugin' as const,
+      plugin: pluginName,
+      path: file
+    };
+  });
+}
+
+export { MAX_SKILLS_PER_PLUGIN, MAX_SKILL_BYTES };

package/src/provisioning/capabilityProvisioner.d.ts

@@ -0,0 +1,10 @@
+export interface CapabilityVerdict {
+  ok: boolean;
+  group: string;
+  reason?: string;
+  requiresConsent?: boolean;
+}
+
+export function ensureCapability(group: string): Promise<CapabilityVerdict>;
+export function loadCapabilityPackage(packageName: string): Promise<unknown>;
+export function capabilityDirectory(): string;

package/src/provisioning/capabilityProvisioner.js

@@ -15,6 +15,10 @@ const CAPABILITY_DIR = path.join(causyneHome(), 'capabilities');
 // ("let it see the screen"), not once per npm package. Names stay in value
 // position — see the D-5 note above.
 const GROUP_PACKAGES = {
+  browser: [
+    ['camoufox-js', '0.11.5'],
+    ['playwright-core', '1.58.0']
+  ],
   vision: [
     ['puppeteer-core', '25.8.0'],
     ['screenshot-desktop', '1.15.6']
@@ -40,6 +44,7 @@ const GROUP_PACKAGES = {
 
 // than listing package names.
 export const GROUP_DESCRIPTIONS = {
+  browser: 'use an existing Camoufox installation for rendered navigation, extraction, and workspace-scoped downloads; Causyne never downloads the browser binary automatically',
   vision: 'drive a browser and capture the screen, so the agent can look at what it built',
   ocr: 'read text out of images and screenshots',
   system: 'list running processes and read system load',

package/src/provisioning/capabilityTools.js

@@ -11,7 +11,8 @@
 import { isGroupDeclined } from './capabilityConsent.js';
 
 export const TOOLS_BY_GROUP = {
-  vision: ['browser_act', 'screenshot', 'vision_inspect_ui', 'game_canvas_audit', 'game_web_runtime_inspector'],
+  browser: ['browser_act'],
+  vision: ['screenshot', 'vision_inspect_ui', 'game_canvas_audit', 'game_web_runtime_inspector'],
   ocr: [],
   system: ['process_list'],
   desktop: ['clipboard', 'desktop_open'],

package/src/sandbox.js

@@ -1,5 +1,6 @@
 import path from 'path';
 import os from 'os';
+import { isIP } from 'node:net';
 import { loadConfig } from './config.js';
 import { isDevEmulator } from './devMode.js';
 
@@ -276,6 +277,27 @@ export class Sandbox {
       }
     }
 
+    if (toolName === 'browser_act') {
+      const actions = Array.isArray(args.actions) ? args.actions : [];
+      let hasDownload = false;
+      for (const action of actions) {
+        if (action && action.url && this.isInternalUrl(action.url)) {
+          return { allowed: false, reason: 'Cannot navigate the agent browser to an internal or invalid URL', risk: 'forbidden' };
+        }
+        if (action && ['download', 'screenshot'].includes(action.type)) {
+          if (!action.outputFile || !this.isPathAllowed(path.resolve(this.workspacePaths[0], action.outputFile))) {
+            return { allowed: false, reason: 'Browser downloads must stay inside the selected workspace', risk: 'forbidden' };
+          }
+          hasDownload = true;
+        }
+      }
+      if (hasDownload) return { allowed: true, risk: 'extreme', reason: 'Writes browser content to the selected workspace' };
+      if (actions.some(action => ['click', 'clickIndex', 'type', 'typeIndex', 'selectOption', 'keyPress'].includes(action?.type))) {
+        return { allowed: true, risk: 'dangerous', reason: 'Interacts with a website through the dedicated agent browser' };
+      }
+      return { allowed: true, risk: 'safe' };
+    }
+
     if (toolName === 'game_asset_fetch' && args.action === 'download_asset') {
       if (!args.url || this.isInternalUrl(args.url)) {
         return { allowed: false, reason: 'Cannot download from an internal or invalid URL', risk: 'forbidden' };
@@ -390,11 +412,19 @@ export class Sandbox {
   isInternalUrl(urlString) {
     try {
       const url = new URL(urlString);
-      const host = url.hostname;
+      if (!['http:', 'https:'].includes(url.protocol) || url.username || url.password) return true;
+      const host = url.hostname.toLowerCase().replace(/^\[|\]$/g, '').replace(/\.$/, '');
+      if (host === 'localhost' || host.endsWith('.localhost') || host.endsWith('.local') || host.endsWith('.internal')) return true;
       
       // Block localhost, private IPs, cloud metadata
-      const blockedRegex = /^(localhost|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|192\.168\.\d+\.\d+|169\.254\.\d+\.\d+|0\.0\.0\.0)$/;
+      const blockedRegex = /^(localhost|0\.\d+\.\d+\.\d+|127\.\d+\.\d+\.\d+|10\.\d+\.\d+\.\d+|100\.(6[4-9]|[7-9]\d|1[01]\d|12[0-7])\.\d+\.\d+|172\.(1[6-9]|2\d|3[01])\.\d+\.\d+|169\.254\.\d+\.\d+|192\.168\.\d+\.\d+|192\.0\.(0|2)\.\d+|192\.88\.99\.\d+|198\.(18|19)\.\d+\.\d+|198\.51\.100\.\d+|203\.0\.113\.\d+|(22[4-9]|23\d|24\d|25[0-5])\.\d+\.\d+\.\d+)$/;
       if (blockedRegex.test(host)) return true;
+      if (host === 'metadata.google.internal') return true;
+      if (isIP(host) === 6) {
+        const normalized = host.split('%')[0];
+        if (normalized === '::' || normalized === '::1' || /^(fc|fd|fe8|fe9|fea|feb|fec|fed|fee|fef|ff|2001:db8:|64:ff9b:)/.test(normalized)) return true;
+        if (normalized.startsWith('::ffff:')) return true;
+      }
       
       return false;
     } catch(e) {