@illuma-ai/agents 1.4.0-alpha.6 → 1.5.1

package/src/tools/CodeExecutor.ts

@@ -15,10 +15,41 @@ export const getCodeBaseURL = (): string =>
 
 const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
+const inheritedFileMessage =
+  'Available as an input — already known to the user';
 const accessMessage =
   'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
   "stdout: Empty. Ensure you're writing output explicitly.\n";
+const inheritedFilesHeader =
+  'Available files (inputs, not generated by this execution):';
+const generatedFilesHeader = 'Generated files:';
+const inheritedNote =
+  'Note: Files in "Available files" are inputs the user (or a skill) already provided to the sandbox. They were not produced by this execution and you should not present them as new outputs in your response.';
+
+/**
+ * Renders one section of the post-execution file listing. Used by the
+ * code/bash tool formatters to keep generated outputs and inherited
+ * inputs visually separated. See BashExecutor for full docs.
+ */
+export function renderFileSection(
+  header: string,
+  files: t.FileRefs,
+  defaultMessage: string
+): string {
+  if (files.length === 0) return '';
+  let out = `${header}\n`;
+  for (let i = 0; i < files.length; i++) {
+    const file = files[i];
+    const isImage = imageExtRegex.test(file.name);
+    out += `- /mnt/data/${file.name} | ${isImage ? imageMessage : defaultMessage}`;
+    if (i < files.length - 1) {
+      out += files.length <= 3 ? ', ' : ',\n';
+    }
+  }
+  out += '\n';
+  return out;
+}
 
 const SUPPORTED_LANGUAGES = [
   'py',
@@ -36,6 +67,12 @@ const SUPPORTED_LANGUAGES = [
   'bash',
 ] as const;
 
+// Minimal schema for raw code execution. Only what the /exec endpoint needs.
+// Higher-level workflows (versioning, edit, store, replay) are consumer
+// concerns — downstream consumers may layer their own write/edit/execute
+// schemas on top via wrapper utilities and content-store backed Zod
+// schemas. Keeping this tool narrow means every consumer gets a clean,
+// schema-stable primitive.
 export const CodeExecutionToolSchema = {
   type: 'object',
   properties: {
@@ -66,23 +103,8 @@ export const CodeExecutionToolSchema = {
       description:
         'Additional arguments to execute the code with. This should only be used if the input code requires additional arguments to run.',
     },
-    code_id: {
-      type: 'string',
-      description:
-        'ID of previously stored code (returned by a prior execute_code call). Use with old_str/new_str to edit stored code instead of rewriting it.',
-    },
-    old_str: {
-      type: 'string',
-      description:
-        'Exact string to find in stored code (requires code_id). Copy verbatim from the code you wrote.',
-    },
-    new_str: {
-      type: 'string',
-      description:
-        'Replacement string (requires code_id and old_str). The matched old_str will be replaced with this value.',
-    },
   },
-  required: ['lang'],
+  required: [],
 } as const;
 
 // NOTE: Resolved at call time inside the tool function, not at module load time.
@@ -97,7 +119,6 @@ Usage:
 - No network access available. Do NOT use pip install, npm install, or any package manager.
 - Generated files are automatically delivered; **DO NOT** provide download links.
 - NEVER use this tool to execute malicious code.
-- When a code_id is returned in output, you can edit that code using code_id + old_str + new_str instead of rewriting the entire code block.
 
 Pre-installed Python packages (use directly, no installation needed):
 - Data Science: numpy, pandas
@@ -137,29 +158,7 @@ function createCodeExecutionTool(
     throw new Error('No API key provided for code execution tool.');
   }
 
-  const description = `
-⛔ STOP! Before using this tool, ask: "Does user need a DOWNLOADABLE FILE?"
-- If NO (dashboard, chart, visualization, UI) → DO NOT USE THIS TOOL. Use content_tool write instead.
-- If YES (.pptx, .docx, .pdf, .xlsx) → Use this tool.
-
-Runs code in a stateless execution environment. Each execution is isolated.
-
-🚫 NEVER USE FOR:
-- Dashboards, charts, visualizations → Use content_tool write with React/Chart.js
-- "Mock data" or "sample data" for display → Hardcode data in content_tool write
-- UI components, HTML pages, React apps → Use content_tool write
-
-✅ ONLY USE FOR:
-- File generation: PowerPoint (.pptx), Word (.docx), PDF (.pdf), Excel (.xlsx)
-- Processing uploaded files (CSV, Excel analysis)
-- Heavy computation requiring Python (numpy, pandas for data analytics)
-
-Rules:
-- No network access — do NOT use pip install, npm install, or any package manager
-- All packages are pre-installed: numpy, pandas, matplotlib, seaborn, plotly, python-docx, python-pptx, reportlab, openpyxl, xlsxwriter, pillow, faker, orjson, lxml, beautifulsoup4
-- Generated files auto-delivered (no download links needed)
-- **Error recovery**: When execution fails, use \`code_id\` + \`old_str\` + \`new_str\` to fix only the broken part — do NOT rewrite the entire code block. This is faster and saves tokens.
-`.trim();
+  const description = CodeExecutionToolDescription;
 
   return tool(
     async (rawInput, config) => {
@@ -170,9 +169,6 @@ Rules:
       const { lang, code, ...rest } = rawInput as {
         lang: SupportedLanguage;
         code: string;
-        code_id?: string;
-        old_str?: string;
-        new_str?: string;
         args?: string[];
       };
       /**
@@ -338,20 +334,33 @@ Rules:
         }
 
         if (result.files && result.files.length > 0) {
-          formattedOutput += 'Generated files:\n';
+          /* Split inherited (read-only passthrough) inputs from real
+           * generated outputs so the LLM doesn't conflate skill files
+           * with newly-produced artifacts. */
+          const inheritedFiles = result.files.filter(
+            (f) => f.inherited === true
+          );
+          const generatedFiles = result.files.filter(
+            (f) => f.inherited !== true
+          );
 
-          const fileCount = result.files.length;
-          for (let i = 0; i < fileCount; i++) {
-            const file = result.files[i];
-            const isImage = imageExtRegex.test(file.name);
-            formattedOutput += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+          formattedOutput += renderFileSection(
+            generatedFilesHeader,
+            generatedFiles,
+            otherMessage
+          );
+          formattedOutput += renderFileSection(
+            inheritedFilesHeader,
+            inheritedFiles,
+            inheritedFileMessage
+          );
 
-            if (i < fileCount - 1) {
-              formattedOutput += fileCount <= 3 ? ', ' : ',\n';
-            }
+          if (generatedFiles.length > 0) {
+            formattedOutput += `\n\n${accessMessage}`;
+          }
+          if (inheritedFiles.length > 0) {
+            formattedOutput += `\n\n${inheritedNote}`;
           }
-
-          formattedOutput += `\n\n${accessMessage}`;
           return [
             formattedOutput.trim(),
             {

package/src/tools/ProgrammaticToolCalling.ts

@@ -6,7 +6,7 @@ import { getEnvironmentVariable } from '@langchain/core/utils/env';
 import { tool, DynamicStructuredTool } from '@langchain/core/tools';
 import type { ToolCall } from '@langchain/core/messages/tool';
 import type * as t from '@/types';
-import { imageExtRegex, getCodeBaseURL } from './CodeExecutor';
+import { getCodeBaseURL, renderFileSection } from './CodeExecutor';
 import { EnvVar, Constants } from '@/common';
 
 config();
@@ -15,8 +15,14 @@ config();
 // Constants
 // ============================================================================
 
-const imageMessage = 'Image is already displayed to the user';
 const otherMessage = 'File is already downloaded by the user';
+const inheritedFileMessage =
+  'Available as an input — already known to the user';
+const inheritedFilesHeader =
+  'Available files (inputs, not generated by this execution):';
+const generatedFilesHeader = 'Generated files:';
+const inheritedNote =
+  'Note: Files in "Available files" are inputs the user (or a skill) already provided to the sandbox. They were not produced by this execution and you should not present them as new outputs in your response.';
 const accessMessage =
   'Note: Files from previous executions are automatically available and can be modified.';
 const emptyOutputMessage =
@@ -563,20 +569,29 @@ export function formatCompletedResponse(
   }
 
   if (response.files && response.files.length > 0) {
-    formatted += 'Generated files:\n';
-
-    const fileCount = response.files.length;
-    for (let i = 0; i < fileCount; i++) {
-      const file = response.files[i];
-      const isImage = imageExtRegex.test(file.name);
-      formatted += `- /mnt/data/${file.name} | ${isImage ? imageMessage : otherMessage}`;
+    /* See BashExecutor for the rationale: split inherited (read-only
+     * passthrough) inputs from real generated outputs so the LLM doesn't
+     * conflate skill files with newly-produced artifacts. */
+    const inheritedFiles = response.files.filter((f) => f.inherited === true);
+    const generatedFiles = response.files.filter((f) => f.inherited !== true);
+
+    formatted += renderFileSection(
+      generatedFilesHeader,
+      generatedFiles,
+      otherMessage
+    );
+    formatted += renderFileSection(
+      inheritedFilesHeader,
+      inheritedFiles,
+      inheritedFileMessage
+    );
 
-      if (i < fileCount - 1) {
-        formatted += fileCount <= 3 ? ', ' : ',\n';
-      }
+    if (generatedFiles.length > 0) {
+      formatted += `\n\n${accessMessage}`;
+    }
+    if (inheritedFiles.length > 0) {
+      formatted += `\n\n${inheritedNote}`;
     }
-
-    formatted += `\n\n${accessMessage}`;
   }
 
   return [

package/src/tools/ReadFile.ts

@@ -0,0 +1,39 @@
+// src/tools/ReadFile.ts
+import { Constants } from '@/common';
+
+export const ReadFileToolName = Constants.READ_FILE;
+
+export const ReadFileToolDescription = `Read the contents of a file. Returns text content with line numbers for easy reference.
+
+For skill files, use the path format: {skillName}/{filePath} (e.g. "pdf-analyzer/src/utils.py", "code-review/SKILL.md").
+
+BEHAVIOR:
+- Text files: returned with numbered lines.
+- Images (png, jpeg, gif, webp): returned as visual content the model can see.
+- PDFs: returned as document content.
+- Other binary files: metadata returned with a note to use bash for processing.
+- Large files (>256KB text, >10MB binary): metadata only.
+- SKILL.md: returns the skill's instructions directly.
+
+CONSTRAINTS:
+- Only files from invoked skills or code execution output are accessible.
+- Do not guess file paths. Use paths from the skill documentation or tool output.`;
+
+export const ReadFileToolSchema = {
+  type: 'object',
+  properties: {
+    file_path: {
+      type: 'string',
+      description:
+        'Path to the file. For skill files: "{skillName}/{path}" (e.g. "pdf-analyzer/src/utils.py"). For code execution output: the path as returned by the execution tool.',
+    },
+  },
+  required: ['file_path'],
+} as const;
+
+export const ReadFileToolDefinition = {
+  name: ReadFileToolName,
+  description: ReadFileToolDescription,
+  parameters: ReadFileToolSchema,
+  responseFormat: 'content_and_artifact' as const,
+} as const;

package/src/tools/SkillTool.ts

@@ -0,0 +1,46 @@
+// src/tools/SkillTool.ts
+import { Constants } from '@/common';
+
+export const SkillToolName = Constants.SKILL_TOOL;
+
+export const SkillToolDescription = `Invoke a skill from the user's library. Skills provide domain-specific instructions loaded into the conversation context, and may also provide files accessible via available tools depending on the runtime environment.
+
+WHEN TO USE:
+- The user's request matches a skill listed in the "Available Skills" section of the system prompt.
+- You MUST invoke the matching skill BEFORE attempting the task yourself.
+
+WHAT HAPPENS:
+- The skill's full instructions are loaded into the conversation as context.
+- Files bundled with the skill may become accessible via available tools.
+- Follow the skill's instructions to complete the task.
+
+CONSTRAINTS:
+- Do not invoke a skill that is already active in this conversation.
+- Skill names come from the catalog only. Do not guess names.`;
+
+/**
+ * JSON Schema for the SkillTool parameters.
+ * Single source of truth used by both SkillToolDefinition (LCTool registry)
+ * and createSkillTool() (DynamicStructuredTool instance).
+ */
+export const SkillToolSchema = {
+  type: 'object',
+  properties: {
+    skillName: {
+      type: 'string',
+      description:
+        'The kebab-case identifier of the skill to invoke (e.g. "financial-analyzer", "meeting-notes"). Must match a name from the "Available Skills" section.',
+    },
+    args: {
+      type: 'string',
+      description: 'Optional freeform arguments string passed to the skill.',
+    },
+  },
+  required: ['skillName'],
+} as const;
+
+export const SkillToolDefinition = {
+  name: SkillToolName,
+  description: SkillToolDescription,
+  parameters: SkillToolSchema,
+} as const;

package/src/tools/SubagentTool.ts

@@ -0,0 +1,100 @@
+import { Constants } from '@/common';
+import type { SubagentConfig } from '@/types';
+import type { JsonSchemaType, LCTool } from '@/types/tools';
+
+export const SubagentToolName = Constants.SUBAGENT;
+
+export const SubagentToolDescription = `Delegate a task to a specialized subagent that runs in an isolated context window. The subagent executes independently and returns only its final text result — all intermediate tool calls, reasoning, and context stay isolated.
+
+WHEN TO USE:
+- The task is self-contained and can be described in a single prompt.
+- You want to offload verbose or exploratory work without bloating your own context.
+- A specialized subagent is available for the task domain.
+
+WHAT HAPPENS:
+- A fresh agent is created with the task description as its only input.
+- The subagent runs to completion using its own tools and context.
+- Only the final text response is returned to you.
+
+CONSTRAINTS:
+- subagent_type must match one of the available types listed below.
+- The subagent cannot see your conversation history.`;
+
+const DESCRIPTION_PROP_DESCRIPTION =
+  'Complete task description for the subagent. This is the ONLY information it receives — include all necessary context, requirements, and constraints.';
+
+const SUBAGENT_TYPE_PROP_DESCRIPTION =
+  'Which subagent type to delegate to. Must be one of the available types.';
+
+export const SubagentToolSchema = {
+  type: 'object',
+  properties: {
+    description: {
+      type: 'string',
+      description: DESCRIPTION_PROP_DESCRIPTION,
+    },
+    subagent_type: {
+      type: 'string',
+      description: SUBAGENT_TYPE_PROP_DESCRIPTION,
+    },
+  },
+  required: ['description', 'subagent_type'] as string[],
+} as const;
+
+export const SubagentToolDefinition: LCTool = {
+  name: SubagentToolName,
+  description: SubagentToolDescription,
+  parameters: SubagentToolSchema,
+};
+
+/**
+ * Build the name, schema, and description params for `tool()` from available configs.
+ * Used by `Graph.createAgentNode()` when constructing the runtime tool instance.
+ * Extends `SubagentToolSchema` by populating `subagent_type.enum` dynamically.
+ */
+export function buildSubagentToolParams(configs: SubagentConfig[]): {
+  name: string;
+  schema: JsonSchemaType;
+  description: string;
+} {
+  const types = configs.map((c) => c.type);
+  const typeDescriptions = configs
+    .map((c) => `- "${c.type}" (${c.name}): ${c.description}`)
+    .join('\n');
+
+  return {
+    name: SubagentToolName,
+    schema: {
+      type: 'object',
+      properties: {
+        description: {
+          type: 'string',
+          description: DESCRIPTION_PROP_DESCRIPTION,
+        },
+        subagent_type: {
+          type: 'string',
+          enum: types,
+          description: `${SUBAGENT_TYPE_PROP_DESCRIPTION} Available: ${types.join(', ')}.`,
+        },
+      },
+      required: ['description', 'subagent_type'],
+    },
+    description: `${SubagentToolDescription}\n\nAvailable types:\n${typeDescriptions}`,
+  };
+}
+
+/**
+ * Create a SubagentTool LCTool definition with dynamic enum and description
+ * populated from the available subagent configs.
+ * Used for the tool registry in event-driven mode.
+ */
+export function createSubagentToolDefinition(
+  configs: SubagentConfig[]
+): LCTool {
+  const params = buildSubagentToolParams(configs);
+  return {
+    name: params.name,
+    description: params.description,
+    parameters: params.schema,
+  };
+}