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

package/src/tools/__tests__/BashExecutor.test.ts

@@ -0,0 +1,49 @@
+import { describe, it, expect } from '@jest/globals';
+import {
+  BashExecutionToolDescription,
+  BashToolOutputReferencesGuide,
+  buildBashExecutionToolDescription,
+} from '../BashExecutor';
+
+describe('buildBashExecutionToolDescription', () => {
+  it('returns the base description by default', () => {
+    expect(buildBashExecutionToolDescription()).toBe(
+      BashExecutionToolDescription
+    );
+    expect(buildBashExecutionToolDescription({})).toBe(
+      BashExecutionToolDescription
+    );
+    expect(
+      buildBashExecutionToolDescription({ enableToolOutputReferences: false })
+    ).toBe(BashExecutionToolDescription);
+  });
+
+  it('appends the tool-output references guide when enabled', () => {
+    const composed = buildBashExecutionToolDescription({
+      enableToolOutputReferences: true,
+    });
+    expect(composed.startsWith(BashExecutionToolDescription)).toBe(true);
+    expect(composed).toContain(BashToolOutputReferencesGuide);
+    expect(composed).toContain('{{tool<idx>turn<turn>}}');
+  });
+
+  it('nudges the model toward heredoc when payloads may contain shell metacharacters', () => {
+    /**
+     * Real-world failure observed against ClickHouse + bash piping:
+     * the model emitted `echo '{{ref}}' | wc -c` and the substituted
+     * binary payload contained literal single quotes, breaking the
+     * shell. The model self-corrected to a heredoc on retry. Surface
+     * the heredoc pattern upfront so the round-trip isn't burned to
+     * rediscover it.
+     */
+    expect(BashToolOutputReferencesGuide).toContain('heredoc');
+    expect(BashToolOutputReferencesGuide).toContain("<< 'EOF'");
+  });
+
+  it('separates base and guide with a blank line', () => {
+    const composed = buildBashExecutionToolDescription({
+      enableToolOutputReferences: true,
+    });
+    expect(composed.includes(`${BashExecutionToolDescription}\n\n`)).toBe(true);
+  });
+});

package/src/tools/__tests__/CodeExecutor.test.ts

@@ -1,9 +1,10 @@
 /**
  * Unit tests for CodeExecutor schema and tool definition.
  *
- * Validates the execute_code tool schema accepts the new optional
- * code_id/old_str/new_str fields for code editing, and that
- * 'code' is no longer required (only 'lang' is).
+ * Validates the execute_code tool exposes a minimal raw-execution schema —
+ * `{ lang, code, args }`. Higher-level workflows (versioning, code_id,
+ * old_str/new_str edits) are consumer concerns (e.g. consumer-side
+ * wrapper utilities) and must NOT appear in this schema.
  */
 import {
   CodeExecutionToolSchema,
@@ -13,64 +14,64 @@ import {
 } from '../CodeExecutor';
 
 describe('CodeExecutionToolSchema', () => {
-  it('should require only "lang" in required array', () => {
-    expect(CodeExecutionToolSchema.required).toEqual(['lang']);
+  it('exposes a minimal raw-execution surface (lang, code, args) — no required fields', () => {
+    expect(CodeExecutionToolSchema.required).toEqual([]);
   });
 
-  it('should have "code" as an optional property', () => {
+  it('has "code" as an optional string property', () => {
     expect(CodeExecutionToolSchema.properties.code).toBeDefined();
     expect(CodeExecutionToolSchema.properties.code.type).toBe('string');
-    // code is not in required
     expect(CodeExecutionToolSchema.required).not.toContain('code');
   });
 
-  it('should have optional code_id property', () => {
-    expect(CodeExecutionToolSchema.properties.code_id).toBeDefined();
-    expect(CodeExecutionToolSchema.properties.code_id.type).toBe('string');
-    expect(CodeExecutionToolSchema.required).not.toContain('code_id');
-  });
-
-  it('should have optional old_str property', () => {
-    expect(CodeExecutionToolSchema.properties.old_str).toBeDefined();
-    expect(CodeExecutionToolSchema.properties.old_str.type).toBe('string');
-    expect(CodeExecutionToolSchema.required).not.toContain('old_str');
-  });
-
-  it('should have optional new_str property', () => {
-    expect(CodeExecutionToolSchema.properties.new_str).toBeDefined();
-    expect(CodeExecutionToolSchema.properties.new_str.type).toBe('string');
-    expect(CodeExecutionToolSchema.required).not.toContain('new_str');
-  });
-
-  it('should still have lang with enum of supported languages', () => {
+  it('has "lang" with enum of supported languages', () => {
     expect(CodeExecutionToolSchema.properties.lang.type).toBe('string');
     expect(CodeExecutionToolSchema.properties.lang.enum).toContain('py');
     expect(CodeExecutionToolSchema.properties.lang.enum).toContain('js');
     expect(CodeExecutionToolSchema.properties.lang.enum).toContain('ts');
   });
 
-  it('should still have args as optional array', () => {
+  it('has "args" as optional array', () => {
     expect(CodeExecutionToolSchema.properties.args).toBeDefined();
     expect(CodeExecutionToolSchema.properties.args.type).toBe('array');
   });
+
+  it('does NOT expose consumer-workflow fields (code_id, old_str, new_str, replace_all)', () => {
+    // These live in consumer-side wrapper schemas, not here.
+    const props = CodeExecutionToolSchema.properties as Record<string, unknown>;
+    expect(props.code_id).toBeUndefined();
+    expect(props.old_str).toBeUndefined();
+    expect(props.new_str).toBeUndefined();
+    expect(props.replace_all).toBeUndefined();
+  });
 });
 
 describe('CodeExecutionToolDescription', () => {
-  it('should mention code_id editing capability', () => {
-    expect(CodeExecutionToolDescription).toContain('code_id');
-    expect(CodeExecutionToolDescription).toContain('old_str');
-    expect(CodeExecutionToolDescription).toContain('new_str');
+  it('does NOT teach code_id / old_str / new_str workflows (consumer concerns)', () => {
+    expect(CodeExecutionToolDescription).not.toMatch(/code_id/);
+    expect(CodeExecutionToolDescription).not.toMatch(/old_str/);
+    expect(CodeExecutionToolDescription).not.toMatch(/new_str/);
+  });
+
+  it('describes the raw execution environment', () => {
+    expect(CodeExecutionToolDescription).toMatch(/stateless/);
+    expect(CodeExecutionToolDescription).toMatch(/No network access/);
   });
 });
 
 describe('CodeExecutionToolDefinition', () => {
-  it('should export correct name', () => {
+  it('exports the canonical tool name', () => {
     expect(CodeExecutionToolName).toBe('execute_code');
   });
 
-  it('should have schema with new fields', () => {
-    expect(CodeExecutionToolDefinition.schema.properties.code_id).toBeDefined();
-    expect(CodeExecutionToolDefinition.schema.properties.old_str).toBeDefined();
-    expect(CodeExecutionToolDefinition.schema.properties.new_str).toBeDefined();
+  it('schema is the minimal raw-execution surface', () => {
+    const props = CodeExecutionToolDefinition.schema.properties as Record<
+      string,
+      unknown
+    >;
+    expect(props.lang).toBeDefined();
+    expect(props.code).toBeDefined();
+    expect(props.args).toBeDefined();
+    expect(props.code_id).toBeUndefined();
   });
 });

package/src/tools/__tests__/ProgrammaticToolCalling.test.ts

@@ -664,6 +664,66 @@ for member in team:
       expect(output).toContain('chart.png');
       expect(output).toContain('Image is already displayed to the user');
     });
+
+    it('splits inherited inputs from generated outputs into distinct sections', () => {
+      const response: t.ProgrammaticExecutionResponse = {
+        status: 'completed',
+        stdout: 'analysis done\n',
+        stderr: '',
+        files: [
+          { id: 'g1', name: 'report.pdf' },
+          { id: 'i1', name: 'pptx/SKILL.md', inherited: true },
+          { id: 'i2', name: 'pptx/scripts/clean.py', inherited: true },
+          { id: 'g2', name: 'chart.png' },
+        ],
+        session_id: 'sess_abc123',
+      };
+
+      const [output, artifact] = formatCompletedResponse(response);
+
+      /* Generated section lists only outputs the run produced. */
+      const generatedIdx = output.indexOf('Generated files:');
+      const inheritedIdx = output.indexOf('Available files (inputs');
+      expect(generatedIdx).toBeGreaterThan(-1);
+      expect(inheritedIdx).toBeGreaterThan(generatedIdx);
+
+      /* Slice each section so we can assert membership without
+       * cross-talk between the two listings. */
+      const generatedSection = output.slice(generatedIdx, inheritedIdx);
+      const inheritedSection = output.slice(inheritedIdx);
+
+      expect(generatedSection).toContain('report.pdf');
+      expect(generatedSection).toContain('chart.png');
+      expect(generatedSection).not.toContain('SKILL.md');
+
+      expect(inheritedSection).toContain('pptx/SKILL.md');
+      expect(inheritedSection).toContain('pptx/scripts/clean.py');
+      expect(inheritedSection).toContain('Available as an input');
+
+      /* The artifact still carries every file so the host can still
+       * thread per-file ids through to subsequent calls. */
+      expect(artifact.files).toHaveLength(4);
+    });
+
+    it('omits the Generated files header when every entry is inherited', () => {
+      const response: t.ProgrammaticExecutionResponse = {
+        status: 'completed',
+        stdout: 'cat: ok\n',
+        stderr: '',
+        files: [
+          { id: 'i1', name: 'pptx/SKILL.md', inherited: true },
+          { id: 'i2', name: 'pptx/editing.md', inherited: true },
+        ],
+        session_id: 'sess_abc123',
+      };
+
+      const [output] = formatCompletedResponse(response);
+
+      expect(output).not.toContain('Generated files:');
+      expect(output).toContain('Available files (inputs');
+      expect(output).toContain('pptx/SKILL.md');
+      expect(output).toContain('pptx/editing.md');
+    });
   });
 
   describe('createProgrammaticToolCallingTool - Manual Invocation', () => {

package/src/tools/__tests__/ReadFile.test.ts

@@ -0,0 +1,44 @@
+import { describe, it, expect } from '@jest/globals';
+import { Constants } from '@/common';
+import {
+  ReadFileToolName,
+  ReadFileToolSchema,
+  ReadFileToolDescription,
+  ReadFileToolDefinition,
+} from '../ReadFile';
+
+describe('ReadFile', () => {
+  describe('schema structure', () => {
+    it('has file_path as required string property', () => {
+      expect(ReadFileToolSchema.properties.file_path.type).toBe('string');
+      expect(ReadFileToolSchema.required).toContain('file_path');
+    });
+
+    it('is an object type schema', () => {
+      expect(ReadFileToolSchema.type).toBe('object');
+    });
+  });
+
+  describe('ReadFileToolDefinition', () => {
+    it('has correct name', () => {
+      expect(ReadFileToolDefinition.name).toBe(Constants.READ_FILE);
+      expect(ReadFileToolDefinition.name).toBe('read_file');
+    });
+
+    it('references the same ReadFileToolSchema object', () => {
+      expect(ReadFileToolDefinition.parameters).toBe(ReadFileToolSchema);
+    });
+
+    it('has a non-empty description', () => {
+      expect(ReadFileToolDefinition.description).toBe(ReadFileToolDescription);
+      expect(ReadFileToolDefinition.description.length).toBeGreaterThan(0);
+    });
+  });
+
+  describe('ReadFileToolName', () => {
+    it('equals Constants.READ_FILE', () => {
+      expect(ReadFileToolName).toBe('read_file');
+      expect(ReadFileToolName).toBe(Constants.READ_FILE);
+    });
+  });
+});