@ai.ntellect/core 1.0.0 → 1.1.0

package/agent/prompt-builder.ts

@@ -0,0 +1,78 @@
+import { AgentContext, PromptSection } from "../types/agent";
+
+/**
+ * Builder class for creating structured prompts with multiple sections
+ * @class PromptBuilder
+ */
+export class PromptBuilder {
+  private sections: PromptSection[] = [];
+  private formatFn?: (
+    sections: PromptSection[],
+    context: AgentContext
+  ) => string | Promise<string>;
+
+  /**
+   * Adds a new section to the prompt
+   * @param {string} title - The title of the section
+   * @param {string | ((context: AgentContext) => string | Promise<string>)} content - The content or a function to generate content
+   * @returns {this} The builder instance for method chaining
+   */
+  addSection(
+    title: string,
+    content: string | ((context: AgentContext) => string | Promise<string>)
+  ): this {
+    this.sections.push({ title, content });
+    return this;
+  }
+
+  /**
+   * Sets a custom formatter function for the final prompt
+   * @param {(sections: PromptSection[], context: AgentContext) => string | Promise<string>} formatter - The formatter function
+   * @returns {this} The builder instance for method chaining
+   */
+  setFormatter(
+    formatter: (
+      sections: PromptSection[],
+      context: AgentContext
+    ) => string | Promise<string>
+  ): this {
+    this.formatFn = formatter;
+    return this;
+  }
+
+  /**
+   * Builds the final prompt by resolving all sections and applying formatting
+   * @param {AgentContext} context - The context to use when resolving dynamic content
+   * @returns {Promise<string>} The formatted prompt string
+   */
+  async build(context: AgentContext): Promise<string> {
+    const resolvedSections = await Promise.all(
+      this.sections.map(async (section) => ({
+        title: section.title,
+        content:
+          typeof section.content === "function"
+            ? await section.content(context)
+            : section.content,
+      }))
+    );
+
+    if (this.formatFn) {
+      return this.formatFn(resolvedSections, context);
+    }
+
+    return resolvedSections
+      .map((section) => `## ${section.title}\n${section.content}`)
+      .join("\n\n");
+  }
+}
+
+/**
+ * Default formatter function that formats sections with markdown-style headers
+ * @param {PromptSection[]} sections - The sections to format
+ * @returns {string} The formatted prompt string
+ */
+export const defaultFormatter = (sections: PromptSection[]): string => {
+  return sections
+    .map((section) => `## ${section.title}\n${section.content}`)
+    .join("\n\n");
+};

package/agent/registry.ts

@@ -0,0 +1,64 @@
+import { Agent } from "./agent";
+
+export type AgentRegistration = {
+  agent: Agent;
+  role: string;
+  description: string;
+  capabilities?: string[];
+};
+
+export class AgentRegistry {
+  private agents: Map<string, AgentRegistration> = new Map();
+
+  register(
+    name: string,
+    agent: Agent,
+    role: string,
+    description: string,
+    capabilities?: string[]
+  ): void {
+    if (this.agents.has(name)) {
+      throw new Error(`Agent "${name}" is already registered`);
+    }
+    this.agents.set(name, { agent, role, description, capabilities });
+  }
+
+  get(name: string): AgentRegistration | undefined {
+    return this.agents.get(name);
+  }
+
+  getAgent(name: string): Agent | undefined {
+    return this.agents.get(name)?.agent;
+  }
+
+  find(query: string): AgentRegistration[] {
+    const q = query.toLowerCase();
+    const results: AgentRegistration[] = [];
+    for (const [, reg] of this.agents) {
+      if (
+        reg.role.toLowerCase().includes(q) ||
+        reg.description.toLowerCase().includes(q) ||
+        reg.capabilities?.some((c) => c.toLowerCase().includes(q))
+      ) {
+        results.push(reg);
+      }
+    }
+    return results;
+  }
+
+  list(): AgentRegistration[] {
+    return Array.from(this.agents.values());
+  }
+
+  remove(name: string): boolean {
+    return this.agents.delete(name);
+  }
+
+  has(name: string): boolean {
+    return this.agents.has(name);
+  }
+
+  get size(): number {
+    return this.agents.size;
+  }
+}

package/agent/tools/file-system.ts

@@ -0,0 +1,471 @@
+import { GraphFlow } from "../../execution/index";
+import { z } from "zod";
+import { spawn, exec } from "child_process";
+import { promisify } from "util";
+import { resolvePath } from "./tool-resolver";
+
+const execAsync = promisify(exec);
+
+export function createFileReaderTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "file_reader",
+    schema: z.object({
+      entityId: z.string().describe("Entity handle from AVAILABLE ENTITY HANDLES list (e.g. 'ent_0'). Use ONLY this for target resolution."),
+      path: z.string().optional(),
+      content: z.any().optional().describe("File content (populated by tool)"),
+      encoding: z.enum(["utf-8", "base64"]).optional().default("utf-8").catch("utf-8").describe("File encoding (use utf-8, NOT utf8)"),
+    }),
+    context: { path: "", encoding: "utf-8", entityId: "" },
+    nodes: [{
+      name: "read",
+      execute: async (ctx: any) => {
+        const fs = await import("fs/promises");
+        const cwd = process.cwd();
+        let targetPath = ctx.path;
+        try {
+          await fs.access(targetPath);
+        } catch {
+          const resolved = resolvePath(targetPath, cwd);
+          const file = resolved.find(e => e.type === "file");
+          if (file) {
+            console.log(`  [TOOL:file_reader] Resolved "${targetPath}" → "${file.path}"`);
+            targetPath = file.path;
+          }
+        }
+        try {
+          ctx.content = await fs.readFile(targetPath, ctx.encoding as BufferEncoding);
+          console.log(`  [TOOL:file_reader] Read ${targetPath}`);
+        } catch (e: any) {
+          console.log(`  [TOOL:file_reader] Error: ${e.message}`);
+          ctx.content = `Error: ${e.message}`;
+        }
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createFileWriterTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "file_writer",
+    schema: z.object({
+      entityId: z.string().describe("Entity handle from AVAILABLE ENTITY HANDLES list. Use ONLY this for target resolution."),
+      path: z.string().optional(),
+      content: z.string().describe("Content to write"),
+      append: z.boolean().optional().default(false).describe("Append instead of overwrite"),
+      success: z.any().optional().describe("Write result (populated by tool)"),
+    }),
+    context: { path: "", content: "", append: false, entityId: "" },
+    nodes: [{
+      name: "write",
+      execute: async (ctx: any) => {
+        const fs = await import("fs/promises");
+        const cwd = process.cwd();
+        let targetPath = ctx.path;
+        try {
+          await fs.access(targetPath);
+        } catch {
+          const resolved = resolvePath(targetPath, cwd);
+          const file = resolved.find(e => e.type === "file");
+          if (file) {
+            console.log(`  [TOOL:file_writer] Resolved "${targetPath}" → "${file.path}"`);
+            targetPath = file.path;
+          }
+        }
+        try {
+          const flag = ctx.append ? "a" : "w";
+          await fs.writeFile(targetPath, ctx.content, { flag });
+          ctx.success = true;
+          console.log(`  [TOOL:file_writer] ${ctx.append ? "Appended to" : "Wrote"} ${targetPath}`);
+        } catch (e: any) {
+          console.log(`  [TOOL:file_writer] Error: ${e.message}`);
+          ctx.success = false;
+        }
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createFileDeleterTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "file_deleter",
+    schema: z.object({
+      entityId: z.string().describe("Entity handle from AVAILABLE ENTITY HANDLES list. Use ONLY this for target resolution."),
+      path: z.string().optional(),
+      recursive: z.boolean().optional().default(false).describe("Delete directories recursively"),
+      success: z.any().optional().describe("Delete result (populated by tool)"),
+    }),
+    context: { path: "", recursive: false, entityId: "" },
+    nodes: [{
+      name: "delete",
+      execute: async (ctx: any) => {
+        const fs = await import("fs/promises");
+        const cwd = process.cwd();
+        let targetPath = ctx.path;
+        try {
+          await fs.access(targetPath);
+        } catch {
+          const resolved = resolvePath(targetPath, cwd);
+          const entry = resolved.find(e => e.type === "file" || e.type === "dir");
+          if (entry) {
+            console.log(`  [TOOL:file_deleter] Resolved "${targetPath}" → "${entry.path}"`);
+            targetPath = entry.path;
+          }
+        }
+        try {
+          const stat = await fs.stat(targetPath);
+          if (stat.isDirectory()) {
+            await fs.rm(targetPath, { recursive: ctx.recursive });
+          } else {
+            await fs.unlink(targetPath);
+          }
+          ctx.success = true;
+          console.log(`  [TOOL:file_deleter] Deleted ${targetPath}`);
+        } catch (e: any) {
+          console.log(`  [TOOL:file_deleter] Error: ${e.message}`);
+          ctx.success = false;
+        }
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createDirectoryCreatorTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "directory_creator",
+    schema: z.object({
+      entityId: z.string().describe("Entity handle from AVAILABLE ENTITY HANDLES list. Use ONLY this for target resolution."),
+      path: z.string().optional(),
+      recursive: z.boolean().optional().default(true).describe("Create parent directories"),
+      success: z.any().optional().describe("Create result (populated by tool)"),
+    }),
+    context: { path: "", recursive: true, entityId: "" },
+    nodes: [{
+      name: "mkdir",
+      execute: async (ctx: any) => {
+        const fs = await import("fs/promises");
+        const cwd = process.cwd();
+        let targetPath = ctx.path;
+        try {
+          await fs.access(targetPath);
+        } catch {
+          const resolved = resolvePath(targetPath, cwd);
+          const dir = resolved.find(e => e.type === "dir");
+          if (dir) {
+            console.log(`  [TOOL:directory_creator] Resolved "${targetPath}" → "${dir.path}"`);
+            targetPath = dir.path;
+          }
+        }
+        try {
+          await fs.mkdir(targetPath, { recursive: ctx.recursive });
+          ctx.success = true;
+          console.log(`  [TOOL:directory_creator] Created ${targetPath}`);
+        } catch (e: any) {
+          console.log(`  [TOOL:directory_creator] Error: ${e.message}`);
+          ctx.success = false;
+        }
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createDirectoryListerTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "directory_lister",
+    schema: z.object({
+      entityId: z.string().describe("Entity handle from AVAILABLE ENTITY HANDLES list. Use ONLY this for target resolution."),
+      path: z.string().optional(),
+      entries: z.any().optional().describe("Directory entries (populated by tool)"),
+    }),
+    context: { path: "", entityId: "" },
+    nodes: [{
+      name: "list",
+      execute: async (ctx: any) => {
+        const fs = await import("fs/promises");
+        const cwd = process.cwd();
+        let targetPath = ctx.path;
+        try {
+          await fs.access(targetPath);
+        } catch {
+          const resolved = resolvePath(targetPath, cwd);
+          const dir = resolved.find(e => e.type === "dir");
+          if (dir) {
+            console.log(`  [TOOL:directory_lister] Resolved "${targetPath}" → "${dir.path}"`);
+            targetPath = dir.path;
+          }
+        }
+        try {
+          const entries = await fs.readdir(targetPath, { withFileTypes: true });
+          ctx.entries = entries.map((e: any) => ({
+            name: e.name,
+            type: e.isDirectory() ? "directory" : "file",
+          }));
+          console.log(`  [TOOL:directory_lister] Listed ${targetPath}: ${ctx.entries.length} entries`);
+        } catch (e: any) {
+          console.log(`  [TOOL:directory_lister] Error: ${e.message}`);
+          ctx.entries = [];
+        }
+      },
+      next: [],
+    }],
+  });
+}
+
+const BLOCKED_COMMANDS = [
+  "rm -rf /", "mkfs", "dd if=", "chmod -R 777 /",
+  ":(){ :|:& };:", "kill -9 -1", "shutdown", "reboot", "init ",
+];
+
+function isCommandBlocked(command: string): boolean {
+  const normalized = command.toLowerCase().trim();
+  return BLOCKED_COMMANDS.some(b => normalized.includes(b));
+}
+
+async function isDockerAvailable(): Promise<boolean> {
+  try {
+    await execAsync("docker info", { timeout: 3000 });
+    return true;
+  } catch {
+    return false;
+  }
+}
+
+async function executeInDocker(command: string, cwd: string, timeout: number): Promise<{
+  stdout: string; stderr: string; exitCode: number; method: string
+}> {
+  const safeCwd = cwd.replace(/[^a-zA-Z0-9/_.\-]/g, "");
+  const dockerCmd = `docker run --rm --network none --memory=256m --cpus=0.5 --security-opt no-new-privileges --timeout ${timeout / 1000}s -v ${safeCwd}:/workspace:ro -w /workspace alpine:3.19 sh -c ${JSON.stringify(command)}`;
+  try {
+    const { stdout, stderr } = await execAsync(dockerCmd, { timeout, maxBuffer: 1024 * 1024 });
+    return { stdout: stdout.toString(), stderr: stderr.toString(), exitCode: 0, method: "docker" };
+  } catch (e: any) {
+    return {
+      stdout: e.stdout || "",
+      stderr: e.stderr || e.message || "Docker execution failed",
+      exitCode: typeof e.code === 'number' ? e.code : 1,
+      method: "docker"
+    };
+  }
+}
+
+async function executeInProcess(command: string, cwd: string, timeout: number): Promise<{
+  stdout: string; stderr: string; exitCode: number; method: string
+}> {
+  const isWindows = process.platform === "win32";
+  const shell = isWindows ? "cmd.exe" : "/bin/sh";
+  const args = isWindows ? ["/c", command] : ["-c", command];
+  const safeEnv = { PATH: process.env.PATH || "", HOME: process.env.HOME || "", LANG: "en_US.UTF-8" };
+
+  return new Promise((resolve) => {
+    const child = spawn(shell, args, { cwd, env: safeEnv });
+    let stdout = "";
+    let stderr = "";
+    let done = false;
+    let timer: ReturnType<typeof setTimeout> | null = null;
+
+    const finish = (code: number) => {
+      if (done) return;
+      done = true;
+      if (timer) clearTimeout(timer);
+      resolve({ stdout, stderr, exitCode: code, method: "process" });
+    };
+
+    timer = setTimeout(() => {
+      if (!done) {
+        child.kill("SIGKILL");
+        finish(124);
+      }
+    }, timeout);
+
+    child.stdout?.on("data", (d: Buffer) => { stdout += d.toString(); });
+    child.stderr?.on("data", (d: Buffer) => { stderr += d.toString(); });
+    child.on("close", (code: number | null) => finish(code ?? 1));
+    child.on("error", () => finish(1));
+    child.on("exit", (code: number | null, sig: NodeJS.Signals | null) => {
+      if (code !== null) finish(code);
+    });
+  });
+}
+
+export function createShellTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "shell",
+    schema: z.object({
+      command: z.string().describe("Shell command to execute"),
+      cwd: z.string().optional().describe("Working directory (host path, only used as context)"),
+      timeout: z.number().optional().describe("Timeout in ms (max 60000)"),
+      stdout: z.string().optional().describe("Command output"),
+      stderr: z.string().optional().describe("Error output"),
+      exitCode: z.number().optional().describe("Exit code"),
+      isolationMethod: z.string().optional().describe("Isolation method used: docker or process"),
+    }),
+    context: { command: "", cwd: process.cwd(), timeout: 30000 },
+    nodes: [{
+      name: "execute",
+      execute: async (ctx: any) => {
+        if (!ctx.command) { ctx.exitCode = 1; ctx.stderr = "No command provided"; return; }
+        if (isCommandBlocked(ctx.command)) {
+          ctx.exitCode = 1; ctx.stderr = "Command blocked for security"; ctx.isolationMethod = "blocked";
+          console.log(`  [TOOL:shell] Blocked: ${ctx.command}`);
+          return;
+        }
+        const timeout = Math.min(ctx.timeout || 30000, 60000);
+        const cwd = ctx.cwd || process.cwd();
+        const dockerAvailable = await isDockerAvailable();
+        console.log(`  [TOOL:shell] Running: ${ctx.command} (${dockerAvailable ? "docker" : "process"} isolation)`);
+        const result = dockerAvailable
+          ? await executeInDocker(ctx.command, cwd, timeout)
+          : await executeInProcess(ctx.command, cwd, timeout);
+        ctx.stdout = result.stdout;
+        ctx.stderr = result.stderr;
+        ctx.exitCode = result.exitCode;
+        ctx.isolationMethod = result.method;
+        console.log(`  [TOOL:shell] Exit code: ${ctx.exitCode} [${result.method}]`);
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createNodeCodeTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "node_code",
+    schema: z.object({
+      code: z.string().describe("JavaScript/TypeScript code to execute"),
+      result: z.string().optional().describe("Execution result"),
+      error: z.string().optional().describe("Error message"),
+      exitCode: z.number().optional().describe("Exit code"),
+      isolationMethod: z.string().optional().describe("Isolation method: docker or vm"),
+    }),
+    context: { code: "", result: "", error: "", exitCode: 0 },
+    nodes: [{
+      name: "run",
+      execute: async (ctx: any) => {
+        if (!ctx.code) { ctx.exitCode = 1; ctx.error = "No code provided"; return; }
+        const codePreview = ctx.code.length > 80 ? ctx.code.slice(0, 80) + "..." : ctx.code;
+        console.log(`  [TOOL:node_code] Running: ${codePreview}`);
+        const dockerAvailable = await isDockerAvailable();
+
+        if (dockerAvailable) {
+          const result = await executeInDocker(
+            `node -e ${JSON.stringify(ctx.code)}`,
+            process.cwd(),
+            30000
+          );
+          ctx.result = result.stdout;
+          ctx.error = result.stderr;
+          ctx.exitCode = result.exitCode;
+          ctx.isolationMethod = "docker";
+          if (!ctx.result && !ctx.error) ctx.result = "Code executed (no output)";
+        } else {
+          console.log(`  [TOOL:node_code] Docker not available, using vm.Script (limited sandbox)`);
+          try {
+            const vm = await import("vm");
+            const sandbox = { 
+              ctx, 
+              result: undefined, 
+              error: undefined,
+              console: {
+                log: (...args: any[]) => { 
+                  sandbox._log = (sandbox._log || []).concat(
+                    args.map(a => typeof a === 'object' ? JSON.stringify(a, null, 2) : String(a))
+                  ); 
+                }
+              },
+              _log: [] as string[]
+            };
+            const script = new vm.Script(`
+              (async () => { 
+                ${ctx.code}
+              })()
+            `);
+            await script.runInNewContext(sandbox);
+            const logOutput = sandbox._log?.join('\n') || '';
+            const codeResult = sandbox.ctx?.result !== undefined ? String(sandbox.ctx.result) : '';
+            ctx.result = logOutput || codeResult;
+            ctx.exitCode = 0;
+            ctx.isolationMethod = "vm";
+            if (!ctx.result) ctx.result = "Code executed (no output)";
+          } catch (e: any) {
+            ctx.error = e.message;
+            ctx.exitCode = 1;
+            ctx.isolationMethod = "vm";
+          }
+        }
+        console.log(`  [TOOL:node_code] Exit code: ${ctx.exitCode} [${ctx.isolationMethod}]`);
+        if (ctx.result) console.log(`  [TOOL:node_code] Result: ${ctx.result.slice(0, 200)}`);
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createPythonCodeTool(): GraphFlow<any> {
+  return new GraphFlow({
+    name: "python_code",
+    schema: z.object({
+      code: z.string().describe("Python code to execute"),
+      result: z.string().optional().describe("Execution result (stdout)"),
+      error: z.string().optional().describe("Error message (stderr)"),
+      exitCode: z.number().optional().describe("Exit code"),
+      isolationMethod: z.string().optional().describe("Isolation method: docker or process"),
+    }),
+    context: { code: "", result: "", error: "", exitCode: 0 },
+    nodes: [{
+      name: "run",
+      execute: async (ctx: any) => {
+        if (!ctx.code) { 
+          ctx.exitCode = 1; 
+          ctx.error = "No code provided"; 
+          return; 
+        }
+        const codePreview = ctx.code.length > 80 ? ctx.code.slice(0, 80) + "..." : ctx.code;
+        console.log(`  [TOOL:python_code] Running: ${codePreview}`);
+        const timeout = 30000;
+        const dockerAvailable = await isDockerAvailable();
+
+        if (dockerAvailable) {
+          const result = await executeInDocker(
+            `python3 -c ${JSON.stringify(ctx.code)}`,
+            process.cwd(),
+            timeout
+          );
+          ctx.result = result.stdout;
+          ctx.error = result.stderr;
+          ctx.exitCode = result.exitCode;
+          ctx.isolationMethod = "docker";
+        } else {
+          const result = await executeInProcess(
+            `python3 -c ${JSON.stringify(ctx.code)}`,
+            process.cwd(),
+            timeout
+          );
+          ctx.result = result.stdout;
+          ctx.error = result.stderr;
+          ctx.exitCode = result.exitCode;
+          ctx.isolationMethod = "process";
+        }
+        console.log(`  [TOOL:python_code] Exit code: ${ctx.exitCode} [${ctx.isolationMethod}]`);
+        if (ctx.result) console.log(`  [TOOL:python_code] Output: ${ctx.result.slice(0, 300)}`);
+        if (ctx.error) console.log(`  [TOOL:python_code] Stderr: ${ctx.error.slice(0, 200)}`);
+      },
+      next: [],
+    }],
+  });
+}
+
+export function createAllAgentTools(): GraphFlow<any>[] {
+  return [
+    createFileReaderTool(),
+    createFileWriterTool(),
+    createFileDeleterTool(),
+    createDirectoryCreatorTool(),
+    createDirectoryListerTool(),
+    createShellTool(),
+    createNodeCodeTool(),
+    createPythonCodeTool(),
+  ];
+}

package/agent/tools/index.ts

@@ -0,0 +1,23 @@
+export {
+  createFileReaderTool,
+  createFileWriterTool,
+  createFileDeleterTool,
+  createDirectoryCreatorTool,
+  createDirectoryListerTool,
+  createShellTool,
+  createNodeCodeTool,
+  createPythonCodeTool,
+  createAllAgentTools,
+} from "./file-system";
+
+export {
+  AgentLogger,
+  logger,
+  type LogLevel,
+  type LogEntry,
+} from "./logger";
+
+export {
+  resolvePath,
+  findInCwd,
+} from "./tool-resolver";