@causyne/agent 1.10.21 → 1.11.0

package/src/perception.ts

@@ -0,0 +1,387 @@
+import fs from 'node:fs/promises';
+import path from 'node:path';
+import os from 'node:os';
+
+const SKIP_DIRECTORIES = new Set([
+  'node_modules', '.git', 'dist', 'build', 'out', 'target',
+  '.next', '.nuxt', '.venv', 'venv', '__pycache__', '.gradle',
+  '.idea', '.cache', 'coverage', 'vendor', 'Pods', '.causyne'
+]);
+
+export interface FrameworkInfo {
+  type: string;
+  language: string;
+  toString(): string;
+}
+
+export interface OsInfo {
+  platform: string;
+  arch: string;
+  toString(): string;
+}
+
+export interface PackageJsonContext {
+  name?: string | undefined;
+  dependencies?: Record<string, string> | undefined;
+  devDependencies?: Record<string, string> | undefined;
+  scripts?: Record<string, string> | undefined;
+}
+
+export type DirectoryTree = {
+  [name: string]: DirectoryTree | string;
+};
+
+export interface GitInfo {
+  branch: string | null;
+  gitDir: string | null;
+  status?: string;
+}
+
+export interface WorkspaceContextData {
+  cwd: string;
+  projectName: string;
+  structure: DirectoryTree | string;
+  framework: FrameworkInfo | null;
+  designSystem: string[] | null;
+  subprojects: string[];
+  keyFiles: string[];
+  packageManager: string | null;
+  gitBranch?: string;
+  gitStatus?: string;
+  packageJson?: PackageJsonContext;
+  projectType: string;
+  readme?: string;
+  os: OsInfo;
+}
+
+export class WorkspacePerception {
+  async buildContext(workspacePath: string): Promise<WorkspaceContextData> {
+    const resolvedPath = workspacePath.replace(/^~\//, os.homedir() + '/');
+
+    const context: Partial<WorkspaceContextData> = {
+      cwd: resolvedPath,
+      projectName: path.basename(resolvedPath)
+    };
+
+    // 1. Directory structure (tree, max depth 2 to keep context size manageable)
+    context.structure = await this.getDirectoryTree(resolvedPath, 2);
+
+    // 2. Framework detection
+    const fw = await this.detectFramework(resolvedPath);
+    if (fw && fw.type !== 'unknown') {
+      const fwStr = `${fw.type} (${fw.language})`;
+      context.framework = Object.assign(new String(fwStr) as unknown as FrameworkInfo, {
+        type: fw.type,
+        language: fw.language,
+        toString: () => fwStr
+      });
+    } else {
+      context.framework = null;
+    }
+
+    // 2b. Design system detection (Anti-Slop: tells the brain what's already installed)
+    context.designSystem = await this.detectDesignContext(resolvedPath);
+
+    // 2c. Subprojects detection (find subfolders like 'pixel2d games', 'causyne-agent', etc.)
+    context.subprojects = await this.detectSubprojects(resolvedPath);
+
+    // 2d. Key files discovery
+    context.keyFiles = await this.detectKeyFiles(resolvedPath);
+
+    // 2e. Package manager detection
+    context.packageManager = await this.detectPackageManager(resolvedPath);
+
+    // 2f. Git branch and status
+    const gitInfo = await this.detectGitInfo(resolvedPath);
+    if (gitInfo.branch) context.gitBranch = gitInfo.branch;
+    if (gitInfo.status) context.gitStatus = gitInfo.status;
+
+    // 3. Package/dependency context
+    try {
+      const pkgPath = path.join(resolvedPath, 'package.json');
+      const pkgStats = await fs.stat(pkgPath);
+      if (pkgStats.isFile()) {
+        const raw = await fs.readFile(pkgPath, 'utf8');
+        const pkgData = JSON.parse(raw) as {
+          name?: string;
+          dependencies?: Record<string, string>;
+          devDependencies?: Record<string, string>;
+          scripts?: Record<string, string>;
+        };
+        context.packageJson = {
+          name: pkgData.name,
+          dependencies: pkgData.dependencies || {},
+          devDependencies: pkgData.devDependencies || {},
+          scripts: pkgData.scripts || {}
+        };
+      }
+    } catch {
+      // ignore missing or invalid package.json
+    }
+
+    // 3b. Project type classification
+    context.projectType = await this.detectProjectType(resolvedPath, context);
+
+    // 4. README (first 1000 chars)
+    try {
+      const readmePath = path.join(resolvedPath, 'README.md');
+      const readmeContent = await fs.readFile(readmePath, 'utf8');
+      context.readme = readmeContent.slice(0, 1000) + (readmeContent.length > 1000 ? '...' : '');
+    } catch {
+      // ignore
+    }
+
+    // 5. OS & environment
+    const osStr = `${os.platform()} (${os.arch()})`;
+    context.os = Object.assign(new String(osStr) as unknown as OsInfo, {
+      platform: os.platform(),
+      arch: os.arch(),
+      toString: () => osStr
+    });
+
+    return context as WorkspaceContextData;
+  }
+
+  async getDirectoryTree(dir: string, maxDepth: number, currentDepth = 0): Promise<DirectoryTree | string> {
+    if (currentDepth > maxDepth) return '... (max depth reached)';
+
+    try {
+      const items = await fs.readdir(dir, { withFileTypes: true });
+      const tree: DirectoryTree = {};
+
+      let count = 0;
+      for (const item of items) {
+        if (item.name.startsWith('.') || item.name === 'node_modules') continue;
+
+        if (count >= 30) {
+          tree['...'] = `(${items.length - count} more items hidden)`;
+          break;
+        }
+
+        count++;
+        if (item.isDirectory()) {
+          tree[item.name] = await this.getDirectoryTree(path.join(dir, item.name), maxDepth, currentDepth + 1);
+        } else {
+          tree[item.name] = 'file';
+        }
+      }
+      return tree;
+    } catch (e: unknown) {
+      const msg = e instanceof Error ? e.message : String(e);
+      return `Error: ${msg}`;
+    }
+  }
+
+  async detectFramework(dir: string): Promise<{ type: string; language: string }> {
+    const detectors = [
+      { file: 'next.config.js', type: 'nextjs', lang: 'javascript' },
+      { file: 'next.config.ts', type: 'nextjs', lang: 'typescript' },
+      { file: 'next.config.mjs', type: 'nextjs', lang: 'javascript' },
+      { file: 'vite.config.ts', type: 'vite', lang: 'typescript' },
+      { file: 'vite.config.js', type: 'vite', lang: 'javascript' },
+      { file: 'nuxt.config.ts', type: 'nuxt', lang: 'typescript' },
+      { file: 'astro.config.mjs', type: 'astro', lang: 'javascript' },
+      { file: 'svelte.config.js', type: 'svelte', lang: 'javascript' },
+      { file: 'tsconfig.json', type: 'node', lang: 'typescript' },
+      { file: 'package.json', type: 'node', lang: 'javascript' },
+      { file: 'manage.py', type: 'django', lang: 'python' },
+      { file: 'pyproject.toml', type: 'python', lang: 'python' },
+      { file: 'requirements.txt', type: 'python', lang: 'python' },
+      { file: 'Cargo.toml', type: 'rust', lang: 'rust' },
+      { file: 'go.mod', type: 'go', lang: 'go' },
+      { file: 'project.godot', type: 'godot', lang: 'gdscript' },
+      { file: 'build.gradle.kts', type: 'android', lang: 'kotlin' },
+      { file: 'docker-compose.yml', type: 'docker', lang: 'various' },
+    ];
+
+    for (const d of detectors) {
+      try {
+        await fs.access(path.join(dir, d.file));
+        return { type: d.type, language: d.lang };
+      } catch {
+        // ignore
+      }
+    }
+
+    return { type: 'unknown', language: 'unknown' };
+  }
+
+  async detectDesignContext(dir: string): Promise<string[] | null> {
+    const designDetectors = [
+      { dep: 'tailwindcss', system: 'Tailwind CSS' },
+      { dep: '@astryxdesign/core', system: 'Astryx Design System' },
+      { dep: '@mui/material', system: 'Material-UI (MUI)' },
+      { dep: '@chakra-ui/react', system: 'Chakra UI' },
+      { dep: 'bootstrap', system: 'Bootstrap' },
+      { dep: 'styled-components', system: 'Styled Components' },
+      { dep: '@emotion/react', system: 'Emotion CSS-in-JS' },
+    ];
+
+    try {
+      const pkgPath = path.join(dir, 'package.json');
+      const raw = await fs.readFile(pkgPath, 'utf8');
+      const pkgData = JSON.parse(raw) as {
+        dependencies?: Record<string, string>;
+        devDependencies?: Record<string, string>;
+      };
+      const allDeps: Record<string, string> = { ...pkgData.dependencies, ...pkgData.devDependencies };
+
+      const detected = designDetectors
+        .filter(d => Boolean(allDeps[d.dep]))
+        .map(d => d.system);
+
+      return detected.length > 0 ? detected : null;
+    } catch {
+      return null;
+    }
+  }
+
+  async detectSubprojects(dir: string): Promise<string[]> {
+    const subprojects: string[] = [];
+    try {
+      const entries = await fs.readdir(dir, { withFileTypes: true });
+      for (const entry of entries) {
+        if (!entry.isDirectory()) continue;
+        if (entry.name.startsWith('.') || SKIP_DIRECTORIES.has(entry.name)) continue;
+
+        const subDir = path.join(dir, entry.name);
+        const markers = [
+          'package.json', 'index.html', 'project.godot', 'main.py',
+          'Cargo.toml', 'requirements.txt', 'go.mod', 'Makefile', 'CMakeLists.txt'
+        ];
+
+        for (const marker of markers) {
+          try {
+            await fs.access(path.join(subDir, marker));
+            subprojects.push(entry.name);
+            break;
+          } catch {
+            // ignore
+          }
+        }
+      }
+    } catch {
+      // ignore
+    }
+    return subprojects;
+  }
+
+  async detectKeyFiles(dir: string): Promise<string[]> {
+    const candidateFiles = [
+      'package.json', 'tsconfig.json', 'index.html', 'main.js',
+      'src/index.js', 'src/index.ts', 'src/main.js', 'src/main.ts',
+      'src/App.tsx', 'src/App.jsx', 'README.md', 'project.godot',
+      'Makefile', 'docker-compose.yml', 'Dockerfile'
+    ];
+    const found: string[] = [];
+    for (const rel of candidateFiles) {
+      try {
+        await fs.access(path.join(dir, rel));
+        found.push(rel);
+      } catch {
+        // ignore
+      }
+    }
+    return found;
+  }
+
+  async detectPackageManager(dir: string): Promise<string | null> {
+    const managers = [
+      { file: 'pnpm-lock.yaml', name: 'pnpm' },
+      { file: 'bun.lockb', name: 'bun' },
+      { file: 'bun.lock', name: 'bun' },
+      { file: 'yarn.lock', name: 'yarn' },
+      { file: 'package-lock.json', name: 'npm' },
+      { file: 'Cargo.lock', name: 'cargo' },
+      { file: 'Pipfile.lock', name: 'pipenv' },
+      { file: 'poetry.lock', name: 'poetry' }
+    ];
+
+    for (const m of managers) {
+      try {
+        await fs.access(path.join(dir, m.file));
+        return m.name;
+      } catch {
+        // ignore
+      }
+    }
+
+    try {
+      await fs.access(path.join(dir, 'package.json'));
+      return 'npm';
+    } catch {
+      // ignore
+    }
+
+    return null;
+  }
+
+  async detectGitInfo(dir: string): Promise<GitInfo> {
+    let current = dir;
+    for (let depth = 0; depth < 5; depth++) {
+      const gitDir = path.join(current, '.git');
+      try {
+        const stat = await fs.stat(gitDir);
+        if (stat.isDirectory()) {
+          const headFile = path.join(gitDir, 'HEAD');
+          const headContent = await fs.readFile(headFile, 'utf8');
+          const match = headContent.trim().match(/^ref:\s+refs\/heads\/(.+)$/);
+          const branch = match ? (match[1] ?? null) : headContent.trim().slice(0, 8);
+          return { branch, gitDir };
+        }
+      } catch {
+        // ignore
+      }
+      const parent = path.dirname(current);
+      if (parent === current) break;
+      current = parent;
+    }
+    return { branch: null, gitDir: null };
+  }
+
+  async detectProjectType(dir: string, context: Partial<WorkspaceContextData>): Promise<string> {
+    const deps: Record<string, string> = context.packageJson ? {
+      ...context.packageJson.dependencies,
+      ...context.packageJson.devDependencies
+    } : {};
+
+    // 1. Game Development (2D Canvas, WebGL, Pixi, Phaser, Godot, Kaplay)
+    const gameLibs = ['phaser', 'pixi.js', 'kaboom', 'kaplay', 'three', 'howler', 'matter-js', 'planck'];
+    if (gameLibs.some(lib => Boolean(deps[lib]))) {
+      return '2D / Canvas Game Project';
+    }
+
+    try {
+      await fs.access(path.join(dir, 'project.godot'));
+      return 'Godot Game Project';
+    } catch {
+      // ignore
+    }
+
+    // Check directory name or key files for game patterns
+    const baseName = path.basename(dir).toLowerCase();
+    if (baseName.includes('game') || baseName.includes('pixel') || baseName.includes('arcade')) {
+      return '2D Game Project';
+    }
+
+    // 2. Web Application
+    if (deps['next'] || deps['react'] || deps['vue'] || deps['svelte'] || deps['vite']) {
+      return 'Frontend Web Application';
+    }
+
+    // 3. Backend / Server / Service
+    if (deps['express'] || deps['fastify'] || deps['koa'] || deps['@nestjs/core']) {
+      return 'Backend Web Service';
+    }
+
+    if (context.framework && context.framework.type === 'android') {
+      return 'Android Application';
+    }
+
+    if (context.framework && context.framework.type === 'rust') {
+      return 'Rust Application / Library';
+    }
+
+    return 'Software Application';
+  }
+}

package/src/procSignal.js

@@ -1,16 +1,13 @@
-
-const SIGNAL_DISPATCH = "kill";
-
+const SIGNAL_DISPATCH = 'kill';
 /**
  * Deliver a signal to a process id. Throws on failure, exactly like the
  * platform call it wraps, so callers can distinguish ESRCH from EPERM.
- * @param {number} pid
- * @param {string|number} signal - e.g. 'SIGTERM', or 0 for an existence probe.
+ * @param pid
+ * @param signal - e.g. 'SIGTERM', or 0 for an existence probe.
  */
 export function sendSignal(pid, signal) {
-  return process[SIGNAL_DISPATCH](pid, signal);
+    return process[SIGNAL_DISPATCH](pid, signal);
 }
-
 /**
  * Existence probe for a process id.
  *
@@ -18,15 +15,17 @@ export function sendSignal(pid, signal) {
  * EPERM means the process exists but belongs to another user — still alive, so
  * it must count as running. Every other error (ESRCH, invalid pid) means gone.
  *
- * @param {number} pid
- * @returns {boolean}
+ * @param pid
+ * @returns boolean indicating if the process is alive.
  */
 export function isProcessAlive(pid) {
-  if (!Number.isInteger(pid) || pid <= 0) return false;
-  try {
-    sendSignal(pid, 0);
-    return true;
-  } catch (e) {
-    return e.code === 'EPERM';
-  }
+    if (!Number.isInteger(pid) || pid <= 0)
+        return false;
+    try {
+        sendSignal(pid, 0);
+        return true;
+    }
+    catch (e) {
+        return e?.code === 'EPERM';
+    }
 }

package/src/procSignal.ts

@@ -0,0 +1,31 @@
+const SIGNAL_DISPATCH = 'kill' as const;
+
+/**
+ * Deliver a signal to a process id. Throws on failure, exactly like the
+ * platform call it wraps, so callers can distinguish ESRCH from EPERM.
+ * @param pid
+ * @param signal - e.g. 'SIGTERM', or 0 for an existence probe.
+ */
+export function sendSignal(pid: number, signal: string | number): true {
+  return process[SIGNAL_DISPATCH](pid, signal as NodeJS.Signals | number);
+}
+
+/**
+ * Existence probe for a process id.
+ *
+ * A signal-0 delivery succeeds when the process exists and we may signal it.
+ * EPERM means the process exists but belongs to another user — still alive, so
+ * it must count as running. Every other error (ESRCH, invalid pid) means gone.
+ *
+ * @param pid
+ * @returns boolean indicating if the process is alive.
+ */
+export function isProcessAlive(pid: number): boolean {
+  if (!Number.isInteger(pid) || pid <= 0) return false;
+  try {
+    sendSignal(pid, 0);
+    return true;
+  } catch (e: unknown) {
+    return (e as { code?: string })?.code === 'EPERM';
+  }
+}

package/src/promptMentions.js

@@ -0,0 +1,170 @@
+// Resolution of `@` mentions for files and directories in user prompts.
+//
+// Pure Node.js. Zero dependencies. No external shell commands.
+//
+// Extracts both quoted (`@"path with spaces/file.js"`, `@'path'`) and
+// unquoted (`@path/to/file.js`) mentions, resolves them against the active
+// working directory and known subprojects, and formats bounded context
+// representations so the agent immediately possesses referenced files and
+// folder trees without needing exploratory tool calls.
+import fs from 'node:fs';
+import path from 'node:path';
+const MAX_MENTION_FILE_LINES = 500;
+const MAX_MENTION_DIR_ITEMS = 40;
+/**
+ * Extract all @ mentions from prompt text.
+ *
+ * @param text - User prompt text.
+ * @returns Array of parsed mentions.
+ */
+export function extractMentions(text) {
+    if (!text || typeof text !== 'string')
+        return [];
+    const mentions = [];
+    const seen = new Set();
+    // 1. Quoted mentions: @"..." or @'...'
+    // This allows spaces, e.g. @"pixel2d games/main.js" or @'assets/sprite sheet.png'
+    const quotedRegex = /(?:^|\s)@(["'])([^"'\n\r]+)\1/g;
+    let match;
+    while ((match = quotedRegex.exec(text)) !== null) {
+        const raw = match[0].trim();
+        const cleanPath = (match[2] ?? '').trim();
+        if (cleanPath && !seen.has(cleanPath)) {
+            seen.add(cleanPath);
+            mentions.push({ raw, path: cleanPath, isQuoted: true });
+        }
+    }
+    // 2. Unquoted mentions: @path/to/file or @dir/
+    // Matches @ preceded by start-of-line or whitespace, not part of an email address
+    const unquotedRegex = /(?:^|\s)@([a-zA-Z0-9_.\-/\\]+)(?=$|\s|[.,;:?!)\]}])/g;
+    while ((match = unquotedRegex.exec(text)) !== null) {
+        const raw = match[0].trim();
+        const cleanPath = (match[1] ?? '').trim();
+        // Skip if already captured via quotes or if empty
+        if (!cleanPath || seen.has(cleanPath))
+            continue;
+        // Do not capture npm scope prefixes on their own or common non-file @ words
+        if (cleanPath === 'here' || cleanPath === 'all' || cleanPath === 'workspace') {
+            seen.add(cleanPath);
+            mentions.push({ raw, path: cleanPath, isQuoted: false, isMeta: true });
+            continue;
+        }
+        seen.add(cleanPath);
+        mentions.push({ raw, path: cleanPath, isQuoted: false });
+    }
+    return mentions;
+}
+/**
+ * Resolve mentioned files and folders against the active working directory
+ * and detected subprojects. Returns bounded context blocks for model ingestion.
+ *
+ * @param prompt - Raw prompt string.
+ * @param options - Resolution options.
+ * @returns Bounded context and list of mentions.
+ */
+export async function resolveMentionedContext(prompt, options = {}) {
+    const mentions = extractMentions(prompt);
+    if (mentions.length === 0) {
+        return { mentions: [], referencedContext: '', detectedSubproject: null };
+    }
+    const cwd = options.cwd || process.cwd();
+    const subprojects = Array.isArray(options.subprojects) ? options.subprojects : [];
+    const sections = [];
+    let detectedSubproject = null;
+    for (const m of mentions) {
+        if (m.isMeta) {
+            if (m.path === 'workspace' || m.path === 'here') {
+                sections.push(`📁 REFERENCED SCOPE: Whole workspace (${cwd})`);
+            }
+            continue;
+        }
+        let targetPath = path.resolve(cwd, m.path);
+        let found = false;
+        try {
+            if (fs.existsSync(targetPath)) {
+                found = true;
+            }
+        }
+        catch {
+            // ignore
+        }
+        // Check if path refers to a file/folder inside any detected subproject
+        if (!found && subprojects.length > 0) {
+            for (const sp of subprojects) {
+                const candidate = path.resolve(cwd, sp, m.path);
+                try {
+                    if (fs.existsSync(candidate)) {
+                        targetPath = candidate;
+                        found = true;
+                        detectedSubproject = sp;
+                        break;
+                    }
+                }
+                catch {
+                    // ignore
+                }
+            }
+        }
+        // Check if the mention path explicitly names a subproject (e.g. @"pixel2d games/...")
+        if (subprojects.length > 0) {
+            for (const sp of subprojects) {
+                if (m.path === sp || m.path.startsWith(sp + '/') || m.path.startsWith(sp + '\\')) {
+                    detectedSubproject = sp;
+                    break;
+                }
+            }
+        }
+        const relPath = path.relative(cwd, targetPath);
+        if (!found) {
+            sections.push(`📂 REFERENCED PATH: ${m.path} (Note: path was not found on disk at ${relPath})`);
+            continue;
+        }
+        try {
+            const stats = fs.statSync(targetPath);
+            if (stats.isDirectory()) {
+                const entries = fs.readdirSync(targetPath, { withFileTypes: true });
+                const summary = entries
+                    .filter(e => !e.name.startsWith('.') && e.name !== 'node_modules')
+                    .slice(0, MAX_MENTION_DIR_ITEMS)
+                    .map(e => e.isDirectory() ? `${e.name}/` : e.name);
+                const more = entries.length > MAX_MENTION_DIR_ITEMS
+                    ? `\n  ... (${entries.length - MAX_MENTION_DIR_ITEMS} more items)`
+                    : '';
+                sections.push(`📁 REFERENCED DIRECTORY: ${relPath}/\n` +
+                    `Directory listing (${summary.length} items):\n` +
+                    summary.map(s => `  - ${s}`).join('\n') +
+                    more);
+            }
+            else if (stats.isFile()) {
+                const content = fs.readFileSync(targetPath, 'utf8');
+                const lines = content.split('\n');
+                let body;
+                if (lines.length > MAX_MENTION_FILE_LINES) {
+                    body = lines.slice(0, MAX_MENTION_FILE_LINES).join('\n') +
+                        `\n\n... [Truncated: showing first ${MAX_MENTION_FILE_LINES} of ${lines.length} lines. Use fs.read for remaining lines.]`;
+                }
+                else {
+                    body = content;
+                }
+                sections.push(`📄 REFERENCED FILE: ${relPath} (${lines.length} lines):\n` +
+                    '```\n' +
+                    body + '\n' +
+                    '```');
+            }
+        }
+        catch (err) {
+            const msg = err instanceof Error ? err.message : String(err);
+            sections.push(`📂 REFERENCED PATH: ${relPath} (Error reading: ${msg})`);
+        }
+    }
+    const referencedContext = sections.length > 0
+        ? `\n\n=== REFERENCED WORKSPACE CONTEXT (@ mentions) ===\n` +
+            sections.join('\n\n') +
+            `\n=== END REFERENCED WORKSPACE CONTEXT ===\n`
+        : '';
+    return {
+        mentions,
+        referencedContext,
+        detectedSubproject
+    };
+}