@illuma-ai/agents 1.4.0-alpha.1 → 1.4.0-alpha.3

package/src/tools/artifacts/tool.ts

@@ -0,0 +1,277 @@
+/**
+ * artifact_tool + content_reader library factories.
+ *
+ * The library owns the LangChain wiring (schema, description, response
+ * shape) and the action dispatch; the runtime supplies a handler bundle
+ * matching the `ArtifactWriteHandlers` / `ContentReadHandlers` interface.
+ *
+ * This keeps 800+ LOC of host-specific handler logic (S3 adapters, file
+ * model CRUD, syntax checkers, line utils) out of the library while
+ * still centralizing the tool surface every runtime shares.
+ */
+
+import { tool, DynamicStructuredTool } from '@langchain/core/tools';
+import {
+  artifactToolSchema,
+  contentReaderSchema,
+  ARTIFACT_TOOL_NAME,
+  CONTENT_READER_NAME,
+} from './schema';
+import type {
+  ArtifactToolConfig,
+  ContentReaderToolConfig,
+  ArtifactToolScope,
+  ArtifactToolResult,
+  WriteArgs,
+  EditArgs,
+  VerifyArgs,
+  DeleteArgs,
+  ReadArgs,
+  SearchArgs,
+  ListArgs,
+  InfoArgs,
+  ContentIdResolver,
+} from './types';
+
+const DEFAULT_ARTIFACT_DESCRIPTION = `Author content artifacts that render live in the host's preview panel — this tool does NOT produce downloadable files (use execute_code for those).
+
+Actions:
+- write: Create a new artifact. Write a COMPLETE file in one call. The \`name\` field MUST include the file extension — it routes the preview (.tsx, .html, .mmd, .svg, .csv, .json, .dot, .md, .drawio).
+- verify: Check an artifact for syntax errors. REQUIRED as the next step after every write/edit on code files — do not render until verify passes.
+- edit: Surgical string replacement — provide old_str (exact match) and new_str. Works on all file types.
+- delete: Remove an artifact and its backing file.
+
+Artifacts are persisted by the host. No manual save needed.`;
+
+const DEFAULT_CONTENT_READER_DESCRIPTION = `Read and navigate stored content — artifacts authored by artifact_tool, large tool results auto-cached by the host, uploaded file attachments, and code blocks.
+
+Read-only surface. Use write/edit tools (artifact_tool, execute_code) to mutate.
+
+Actions:
+- read: Return line ranges from a specific content_id.
+- search: Regex search across a specific content_id with paginated matches.
+- list: Enumerate every content entry currently stored.
+- info: Metadata (size, kind, creation time) for a specific content_id.`;
+
+/**
+ * Optional content_id self-healing — if the runtime supplies a resolver,
+ * we pre-resolve the ID on every action that takes one so nicknames
+ * (e.g., "Dashboard") map to canonical IDs.
+ */
+async function resolveContentIdIfPresent(
+  resolver: ContentIdResolver | undefined,
+  id: string | undefined,
+  scope: ArtifactToolScope,
+  logger?: { debug: (msg: string) => void },
+): Promise<string | undefined> {
+  if (!resolver || !id) return id;
+  const out = await resolver.resolve(id, scope);
+  if (!out) return id;
+  if (out.resolvedId !== id) {
+    logger?.debug(
+      `[artifact] resolved "${id}" → "${out.resolvedId}"${out.resolvedName ? ` ("${out.resolvedName}")` : ''}`,
+    );
+  }
+  return out.resolvedId;
+}
+
+// ─── Writer tool (artifact_tool) ─────────────────────────────────────────
+
+export function createArtifactTool(
+  config: ArtifactToolConfig,
+): DynamicStructuredTool {
+  const { handlers, getScope, resolver, logger, descriptionOverride } = config;
+
+  return tool(
+    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {
+      const scope = getScope(runnableConfig);
+      if (!scope) {
+        logger?.warn('[artifact_tool] no scope resolved from runnableConfig');
+        return ['Error: No conversation context available', {}];
+      }
+
+      const input = rawInput as {
+        action: 'write' | 'edit' | 'verify' | 'delete';
+        content_id?: string;
+        content?: string;
+        name?: string;
+        old_str?: string;
+        new_str?: string;
+        replace_all?: boolean;
+      };
+
+      const resolvedContentId = await resolveContentIdIfPresent(
+        resolver,
+        input.content_id,
+        scope,
+        logger,
+      );
+
+      const started = Date.now();
+      try {
+        switch (input.action) {
+          case 'write': {
+            const args: WriteArgs = {
+              action: 'write',
+              content_id: resolvedContentId,
+              content: input.content ?? '',
+              name: input.name,
+            };
+            if (!args.content) return ['Error: write requires content', {}];
+            return await handlers.write(args, scope);
+          }
+          case 'edit': {
+            if (!resolvedContentId) return ['Error: edit requires content_id', {}];
+            const args: EditArgs = {
+              action: 'edit',
+              content_id: resolvedContentId,
+              old_str: input.old_str ?? '',
+              new_str: input.new_str ?? '',
+              replace_all: input.replace_all,
+            };
+            if (!args.old_str) return ['Error: edit requires old_str', {}];
+            return await handlers.edit(args, scope);
+          }
+          case 'verify': {
+            if (!resolvedContentId) return ['Error: verify requires content_id', {}];
+            const args: VerifyArgs = {
+              action: 'verify',
+              content_id: resolvedContentId,
+            };
+            return await handlers.verify(args, scope);
+          }
+          case 'delete': {
+            if (!resolvedContentId) return ['Error: delete requires content_id', {}];
+            const args: DeleteArgs = {
+              action: 'delete',
+              content_id: resolvedContentId,
+            };
+            return await handlers.delete(args, scope);
+          }
+          default:
+            return [`Unknown action: ${(input as { action: string }).action}`, {}];
+        }
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        logger?.error('[artifact_tool] handler threw', {
+          action: input.action,
+          contentId: resolvedContentId,
+          error: e.message,
+          elapsed: `${Date.now() - started}ms`,
+        });
+        return [`Error: ${e.message}`, {}];
+      }
+    },
+    {
+      name: ARTIFACT_TOOL_NAME,
+      responseFormat: 'content_and_artifact',
+      description: descriptionOverride ?? DEFAULT_ARTIFACT_DESCRIPTION,
+      schema: artifactToolSchema,
+    },
+  );
+}
+
+// ─── Reader tool (content_reader) ────────────────────────────────────────
+
+export function createContentReaderTool(
+  config: ContentReaderToolConfig,
+): DynamicStructuredTool {
+  const { handlers, getScope, resolver, logger, descriptionOverride } = config;
+
+  return tool(
+    async (rawInput, runnableConfig): Promise<ArtifactToolResult> => {
+      const scope = getScope(runnableConfig);
+      if (!scope) {
+        logger?.warn('[content_reader] no scope resolved from runnableConfig');
+        return ['Error: No conversation context available', {}];
+      }
+
+      const input = rawInput as {
+        action: 'read' | 'search' | 'list' | 'info';
+        content_id?: string;
+        start_line?: number;
+        end_line?: number;
+        pattern?: string;
+        flags?: string;
+        context?: number;
+        offset?: number;
+        limit?: number;
+      };
+
+      const resolvedContentId = await resolveContentIdIfPresent(
+        resolver,
+        input.content_id,
+        scope,
+        logger,
+      );
+
+      const started = Date.now();
+      try {
+        switch (input.action) {
+          case 'read': {
+            if (!resolvedContentId) return ['Error: read requires content_id', {}];
+            const args: ReadArgs = {
+              action: 'read',
+              content_id: resolvedContentId,
+              start_line: input.start_line,
+              end_line: input.end_line,
+              offset: input.offset,
+              limit: input.limit,
+            };
+            return await handlers.read(args, scope);
+          }
+          case 'search': {
+            if (!resolvedContentId) return ['Error: search requires content_id', {}];
+            if (!input.pattern) return ['Error: search requires pattern', {}];
+            const args: SearchArgs = {
+              action: 'search',
+              content_id: resolvedContentId,
+              pattern: input.pattern,
+              flags: input.flags,
+              context: input.context,
+              offset: input.offset,
+              limit: input.limit,
+            };
+            return await handlers.search(args, scope);
+          }
+          case 'list': {
+            const args: ListArgs = { action: 'list' };
+            return await handlers.list(args, scope);
+          }
+          case 'info': {
+            if (!resolvedContentId) return ['Error: info requires content_id', {}];
+            const args: InfoArgs = {
+              action: 'info',
+              content_id: resolvedContentId,
+            };
+            return await handlers.info(args, scope);
+          }
+          default:
+            return [`Unknown action: ${(input as { action: string }).action}`, {}];
+        }
+      } catch (err) {
+        const e = err instanceof Error ? err : new Error(String(err));
+        logger?.error('[content_reader] handler threw', {
+          action: input.action,
+          contentId: resolvedContentId,
+          error: e.message,
+          elapsed: `${Date.now() - started}ms`,
+        });
+        return [`Error: ${e.message}`, {}];
+      }
+    },
+    {
+      name: CONTENT_READER_NAME,
+      responseFormat: 'content_and_artifact',
+      description: descriptionOverride ?? DEFAULT_CONTENT_READER_DESCRIPTION,
+      schema: contentReaderSchema,
+    },
+  );
+}
+
+export {
+  ARTIFACT_TOOL_NAME,
+  CONTENT_READER_NAME,
+  ARTIFACT_WRITE_ACTIONS,
+  CONTENT_READ_ACTIONS,
+} from './schema';

package/src/tools/artifacts/types.ts

@@ -0,0 +1,149 @@
+/**
+ * Artifact-tool types. The library owns the LangChain wiring, schema, and
+ * action dispatch. Runtime supplies an `ArtifactHandlers` bundle — one
+ * function per action — so ranger reuses its existing handlers, CLI
+ * supplies disk-backed ones, and A2A server supplies buffer-backed ones.
+ *
+ * Each handler receives:
+ *   - `args`: the parsed input (typed per action)
+ *   - `scope`: runtime-resolved scope identity (conversationId + userId
+ *     for ranger, agent-run-id for CLI, a2a-task-id for A2A)
+ *
+ * Each handler returns a `[llmText, toolArtifact]` tuple matching
+ * LangChain's `content_and_artifact` response format.
+ */
+
+export interface ArtifactToolScope {
+  /**
+   * Primary scope — whatever the runtime uses to silo artifacts per
+   * session/run/conversation. Ranger uses `conversationId`; CLI uses
+   * `agent-run-id` or `agent-id`; A2A uses `a2a-task-id`.
+   */
+  conversationId: string;
+  /** Optional — present when the runtime has an authenticated user. */
+  userId?: string;
+  /** Free-form extension — runtimes can add their own fields. */
+  [key: string]: unknown;
+}
+
+export type ArtifactToolResult = [llmText: string, artifact?: unknown];
+
+// ─── Action arg shapes ────────────────────────────────────────────────────
+
+export interface WriteArgs {
+  action: 'write';
+  content_id?: string;
+  content: string;
+  name?: string;
+}
+
+export interface EditArgs {
+  action: 'edit';
+  content_id: string;
+  old_str: string;
+  new_str: string;
+  replace_all?: boolean;
+}
+
+export interface VerifyArgs {
+  action: 'verify';
+  content_id: string;
+}
+
+export interface DeleteArgs {
+  action: 'delete';
+  content_id: string;
+}
+
+export interface ReadArgs {
+  action: 'read';
+  content_id: string;
+  start_line?: number;
+  end_line?: number;
+  offset?: number;
+  limit?: number;
+}
+
+export interface SearchArgs {
+  action: 'search';
+  content_id: string;
+  pattern: string;
+  flags?: string;
+  context?: number;
+  offset?: number;
+  limit?: number;
+}
+
+export interface ListArgs {
+  action: 'list';
+}
+
+export interface InfoArgs {
+  action: 'info';
+  content_id: string;
+}
+
+export type ArtifactWriteAction = WriteArgs | EditArgs | VerifyArgs | DeleteArgs;
+export type ArtifactReadAction = ReadArgs | SearchArgs | ListArgs | InfoArgs;
+
+// ─── Handler bundles ──────────────────────────────────────────────────────
+
+/** Writer-surface handlers — invoked by `artifact_tool`. */
+export interface ArtifactWriteHandlers {
+  write(args: WriteArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  edit(args: EditArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  verify(args: VerifyArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  delete(args: DeleteArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+}
+
+/** Reader-surface handlers — invoked by `content_reader`. */
+export interface ContentReadHandlers {
+  read(args: ReadArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  search(args: SearchArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  list(args: ListArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+  info(args: InfoArgs, scope: ArtifactToolScope): Promise<ArtifactToolResult>;
+}
+
+/**
+ * Optional content_id self-healing: runtimes that want to let the LLM
+ * pass nicknames (e.g., "Dashboard") instead of canonical IDs implement
+ * this. Library falls through when unset.
+ */
+export interface ContentIdResolver {
+  resolve(
+    id: string,
+    scope: ArtifactToolScope,
+  ): Promise<{ resolvedId: string; resolvedName?: string } | null>;
+}
+
+export interface ArtifactToolLogger {
+  debug: (msg: string, ...args: unknown[]) => void;
+  info: (msg: string, ...args: unknown[]) => void;
+  warn: (msg: string, ...args: unknown[]) => void;
+  error: (msg: string, ...args: unknown[]) => void;
+}
+
+export interface ArtifactToolBaseConfig {
+  /**
+   * Resolves the runtime scope from the LangChain `config` object on each
+   * invocation. Ranger pulls `conversationId` + `userId` from request
+   * metadata; CLI pulls `agent-run-id` from its runner context.
+   */
+  getScope: (config: unknown) => ArtifactToolScope | null;
+  resolver?: ContentIdResolver;
+  logger?: ArtifactToolLogger;
+  /**
+   * Description override. Host can inject brand-specific guidance
+   * (e.g., ranger's HTML branding mandate, TSX style rules). Defaults
+   * to a generic description appropriate for any runtime.
+   */
+  descriptionOverride?: string;
+}
+
+export interface ArtifactToolConfig extends ArtifactToolBaseConfig {
+  handlers: ArtifactWriteHandlers;
+}
+
+export interface ContentReaderToolConfig extends ArtifactToolBaseConfig {
+  handlers: ContentReadHandlers;
+}

package/src/tools/fileSearch/__tests__/tool.test.ts

@@ -0,0 +1,261 @@
+/**
+ * Unit tests for the file_search library tool.
+ *
+ * The real RAG backend is mocked through the `RagClient` interface so
+ * these tests verify the tool's own logic: target_files filtering,
+ * bounded-concurrency querying, per-file error isolation, formatter
+ * handoff, and empty/no-file edge cases.
+ */
+
+import { createFileSearchTool } from '../tool';
+import {
+  plainTextFormatter,
+  createCitationAnchorFormatter,
+} from '../formatter';
+import type {
+  RagClient,
+  RagQueryParams,
+  RagChunk,
+  FileSearchFile,
+} from '../types';
+
+// Build a mock RagClient that records every query it receives and returns
+// a deterministic chunk set per file.
+function makeRagClient(
+  opts: {
+    chunksByFile?: Record<string, RagChunk[]>;
+    failFileIds?: Set<string>;
+    hang?: boolean;
+  } = {}
+) {
+  const calls: RagQueryParams[] = [];
+  const client: RagClient = {
+    async query(params) {
+      calls.push({ ...params });
+      if (opts.hang) {
+        // Never resolves — used to test timeout handling.
+        await new Promise(() => {});
+      }
+      if (opts.failFileIds?.has(params.file_id)) {
+        throw new Error(`simulated failure for ${params.file_id}`);
+      }
+      return opts.chunksByFile?.[params.file_id] ?? [];
+    },
+  };
+  return { client, calls };
+}
+
+const files: FileSearchFile[] = [
+  { file_id: 'f-alpha', filename: 'alpha.pdf', isCurrentMessage: true },
+  { file_id: 'f-beta', filename: 'beta-report.docx' },
+  { file_id: 'f-gamma', filename: 'gamma_notes.txt' },
+];
+
+describe('createFileSearchTool', () => {
+  it('returns a no-files message when factory was seeded with zero files', async () => {
+    const { client } = makeRagClient();
+    const t = createFileSearchTool({ ragClient: client, files: [] });
+    const result = await t.invoke({ query: 'anything' });
+    // Dual-format tools return [string, artifact?]; LangChain surfaces the
+    // string directly in some invocation paths — handle both shapes.
+    const text = Array.isArray(result) ? result[0] : result;
+    expect(String(text)).toMatch(/no files to search/i);
+  });
+
+  it('queries every file when target_files is omitted', async () => {
+    const { client, calls } = makeRagClient({
+      chunksByFile: {
+        'f-alpha': [chunk('f-alpha', 'alpha page 1', 0.1)],
+        'f-beta': [chunk('f-beta', 'beta text', 0.2)],
+        'f-gamma': [chunk('f-gamma', 'gamma note', 0.3)],
+      },
+    });
+    const t = createFileSearchTool({ ragClient: client, files });
+    await t.invoke({ query: 'test' });
+    expect(calls.map((c) => c.file_id).sort()).toEqual([
+      'f-alpha',
+      'f-beta',
+      'f-gamma',
+    ]);
+  });
+
+  it('filters files by target_files substring (case-insensitive)', async () => {
+    const { client, calls } = makeRagClient({
+      chunksByFile: { 'f-beta': [chunk('f-beta', 'beta', 0.2)] },
+    });
+    const t = createFileSearchTool({ ragClient: client, files });
+    await t.invoke({ query: 'q', target_files: ['BETA-REPORT'] });
+    expect(calls.map((c) => c.file_id)).toEqual(['f-beta']);
+  });
+
+  it('falls back to all files when target_files matches nothing', async () => {
+    const { client, calls } = makeRagClient({
+      chunksByFile: {
+        'f-alpha': [chunk('f-alpha', 'a', 0.1)],
+        'f-beta': [chunk('f-beta', 'b', 0.2)],
+        'f-gamma': [chunk('f-gamma', 'c', 0.3)],
+      },
+    });
+    const warn = jest.fn();
+    const t = createFileSearchTool({
+      ragClient: client,
+      files,
+      logger: { debug: jest.fn(), info: jest.fn(), warn, error: jest.fn() },
+    });
+    await t.invoke({ query: 'q', target_files: ['no-such-file'] });
+    expect(calls.length).toBe(3);
+    expect(warn).toHaveBeenCalled();
+  });
+
+  it('isolates per-file failures so one bad file does not fail the call', async () => {
+    const { client, calls } = makeRagClient({
+      chunksByFile: {
+        'f-alpha': [chunk('f-alpha', 'alpha good', 0.1)],
+        'f-gamma': [chunk('f-gamma', 'gamma good', 0.2)],
+      },
+      failFileIds: new Set(['f-beta']),
+    });
+    const onFileError = jest.fn();
+    const t = createFileSearchTool({
+      ragClient: client,
+      files,
+      callbacks: { onFileError },
+      logger: silentLogger(),
+    });
+    const result = await t.invoke({ query: 'q' });
+    const text = Array.isArray(result) ? result[0] : result;
+    expect(String(text)).toMatch(/alpha good/);
+    expect(String(text)).toMatch(/gamma good/);
+    expect(calls.length).toBe(3);
+    expect(onFileError).toHaveBeenCalledWith(
+      expect.objectContaining({ file_id: 'f-beta' }),
+      expect.any(Error)
+    );
+  });
+
+  it('forwards entity_id, scope, and authHeaders on every query', async () => {
+    const { client, calls } = makeRagClient({
+      chunksByFile: { 'f-alpha': [chunk('f-alpha', 'x', 0.1)] },
+    });
+    const t = createFileSearchTool({
+      ragClient: client,
+      files: [files[0]],
+      entity_id: 'tenant-42',
+      scope: 'user:alice',
+      getAuthHeaders: () => ({ Authorization: 'Bearer TOKEN' }),
+    });
+    await t.invoke({ query: 'q' });
+    expect(calls[0]).toEqual(
+      expect.objectContaining({
+        file_id: 'f-alpha',
+        query: 'q',
+        entity_id: 'tenant-42',
+        scope: 'user:alice',
+        authHeaders: { Authorization: 'Bearer TOKEN' },
+      })
+    );
+  });
+
+  it('prioritizes current-turn files even when stale files have closer distances', async () => {
+    const { client } = makeRagClient({
+      chunksByFile: {
+        'f-alpha': [chunk('f-alpha', 'current-turn', 0.5)],
+        'f-beta': [chunk('f-beta', 'older-turn', 0.1)],
+      },
+    });
+    const t = createFileSearchTool({
+      ragClient: client,
+      files: [files[0], files[1]], // alpha=current, beta=not
+    });
+    const result = await t.invoke({ query: 'q' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    const currentIdx = text.indexOf('current-turn');
+    const olderIdx = text.indexOf('older-turn');
+    expect(currentIdx).toBeGreaterThanOrEqual(0);
+    expect(olderIdx).toBeGreaterThan(currentIdx);
+  });
+
+  it('uses plainTextFormatter by default (no citation anchors)', async () => {
+    const { client } = makeRagClient({
+      chunksByFile: { 'f-alpha': [chunk('f-alpha', 'hello', 0.1)] },
+    });
+    const t = createFileSearchTool({
+      ragClient: client,
+      files: [files[0]],
+    });
+    const result = await t.invoke({ query: 'q' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    expect(text).not.toMatch(/\\ue202turn0file/);
+    expect(text).toMatch(/File: alpha\.pdf/);
+  });
+
+  it('uses citation anchors when createCitationAnchorFormatter is supplied', async () => {
+    const { client } = makeRagClient({
+      chunksByFile: { 'f-alpha': [chunk('f-alpha', 'hello', 0.1)] },
+    });
+    let offset = 0;
+    const formatter = createCitationAnchorFormatter({
+      getSourceOffset: () => offset,
+      advanceSourceOffset: (by) => {
+        offset += by;
+      },
+    });
+    const t = createFileSearchTool({
+      ragClient: client,
+      files: [files[0]],
+      formatter,
+    });
+    const first = await t.invoke({ query: 'q' });
+    const text1 = Array.isArray(first) ? String(first[0]) : String(first);
+    expect(text1).toMatch(/Source 0/);
+    expect(text1).toMatch(/\\ue202turn0file0/);
+
+    // Second call in the same turn: offset should have advanced.
+    const second = await t.invoke({ query: 'q2' });
+    const text2 = Array.isArray(second) ? String(second[0]) : String(second);
+    expect(text2).toMatch(/Source 1/);
+    expect(text2).toMatch(/\\ue202turn0file1/);
+  });
+
+  it('extracts 1-indexed page numbers from metadata.page (rag_api 0-indexed)', async () => {
+    const { client } = makeRagClient({
+      chunksByFile: {
+        'f-alpha': [
+          {
+            file_id: 'f-alpha',
+            page_content: 'page two content',
+            distance: 0.1,
+            metadata: { page: 1 }, // rag_api 0-indexed → display = 2
+          },
+        ],
+      },
+    });
+    const t = createFileSearchTool({
+      ragClient: client,
+      files: [files[0]],
+    });
+    const result = await t.invoke({ query: 'q' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    expect(text).toMatch(/Page: 2/);
+  });
+});
+
+// ── helpers ──────────────────────────────────────────────────────────────
+
+function chunk(
+  file_id: string,
+  text: string,
+  distance: number,
+  metadata?: Record<string, unknown>
+): RagChunk {
+  return { file_id, page_content: text, distance, metadata };
+}
+
+function silentLogger() {
+  return {
+    debug: jest.fn(),
+    info: jest.fn(),
+    warn: jest.fn(),
+    error: jest.fn(),
+  };
+}