@illuma-ai/agents 1.4.0-alpha.2 → 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

@@ -8,16 +8,26 @@
  */
 
 import { createFileSearchTool } from '../tool';
-import { plainTextFormatter, createCitationAnchorFormatter } from '../formatter';
-import type { RagClient, RagQueryParams, RagChunk, FileSearchFile } from '../types';
+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;
-} = {}) {
+function makeRagClient(
+  opts: {
+    chunksByFile?: Record<string, RagChunk[]>;
+    failFileIds?: Set<string>;
+    hang?: boolean;
+  } = {}
+) {
   const calls: RagQueryParams[] = [];
   const client: RagClient = {
     async query(params) {
@@ -119,7 +129,7 @@ describe('createFileSearchTool', () => {
     expect(calls.length).toBe(3);
     expect(onFileError).toHaveBeenCalledWith(
       expect.objectContaining({ file_id: 'f-beta' }),
-      expect.any(Error),
+      expect.any(Error)
     );
   });
 
@@ -142,7 +152,7 @@ describe('createFileSearchTool', () => {
         entity_id: 'tenant-42',
         scope: 'user:alice',
         authHeaders: { Authorization: 'Bearer TOKEN' },
-      }),
+      })
     );
   });
 
@@ -236,7 +246,7 @@ function chunk(
   file_id: string,
   text: string,
   distance: number,
-  metadata?: Record<string, unknown>,
+  metadata?: Record<string, unknown>
 ): RagChunk {
   return { file_id, page_content: text, distance, metadata };
 }

package/src/tools/fileSearch/formatter.ts

@@ -63,14 +63,14 @@ export interface CitationAnchorFormatterOptions {
 }
 
 export function createCitationAnchorFormatter(
-  opts: CitationAnchorFormatterOptions = {},
+  opts: CitationAnchorFormatterOptions = {}
 ): FileSearchResultFormatter {
   const toolName = opts.toolName ?? 'file_search';
-  const getOffset = opts.getSourceOffset ?? (() => 0);
-  const advance = opts.advanceSourceOffset ?? (() => {});
+  const getOffset = opts.getSourceOffset ?? ((): number => 0);
+  const advance = opts.advanceSourceOffset ?? ((_by: number): void => {});
 
   return {
-    format(chunks) {
+    format(chunks): { message: string; artifact?: unknown } {
       if (chunks.length === 0) {
         return {
           message:
@@ -100,9 +100,7 @@ export function createCitationAnchorFormatter(
         relevance: 1 - c.distance,
         pages: getPage(c) != null ? [getPage(c) as number] : [],
         pageRelevance:
-          getPage(c) != null
-            ? { [getPage(c) as number]: 1 - c.distance }
-            : {},
+          getPage(c) != null ? { [getPage(c) as number]: 1 - c.distance } : {},
       }));
 
       advance(chunks.length);

package/src/tools/fileSearch/ragClient.ts

@@ -21,14 +21,11 @@ export const RAG_API_URL_ENV = 'RAG_API_URL';
 
 /** Resolve base URL at call time so env-var changes propagate. */
 export function getRagBaseUrl(override?: string): string {
-  const url =
-    override ??
-    getEnvironmentVariable(RAG_API_URL_ENV) ??
-    '';
+  const url = override ?? getEnvironmentVariable(RAG_API_URL_ENV) ?? '';
   if (!url) {
     throw new Error(
       `file_search: ${RAG_API_URL_ENV} is not configured. ` +
-        `Set the env var or pass baseUrl to HttpRagClient.`,
+        `Set the env var or pass baseUrl to HttpRagClient.`
     );
   }
   return url.replace(/\/$/, '');
@@ -112,7 +109,7 @@ export class HttpRagClient implements RagClient {
       if (!res.ok) {
         const text = await res.text().catch(() => '');
         throw new Error(
-          `RAG query failed: ${res.status} ${res.statusText} — ${text.slice(0, 200)}`,
+          `RAG query failed: ${res.status} ${res.statusText} — ${text.slice(0, 200)}`
         );
       }
       const json = (await res.json()) as RagApiResponse;
@@ -131,11 +128,10 @@ export class HttpRagClient implements RagClient {
     return resp
       .filter((row) => Array.isArray(row) && row.length === 2)
       .map(([doc, distance]) => ({
-        file_id:
-          (doc?.metadata?.file_id as string | undefined) ?? file_id,
-        page_content: doc?.page_content ?? '',
+        file_id: (doc.metadata?.file_id as string | undefined) ?? file_id,
+        page_content: doc.page_content ?? '',
         distance: typeof distance === 'number' ? distance : 1,
-        metadata: doc?.metadata,
+        metadata: doc.metadata,
       }));
   }
 }

package/src/tools/fileSearch/schema.ts

@@ -4,13 +4,13 @@ export const fileSearchInputSchema = z.object({
   query: z
     .string()
     .describe(
-      "A natural language query to search for relevant information in the files. Be SPECIFIC and TARGETED — use keywords for the specific section or topic you need. For comprehensive tasks (summaries, overviews), call this tool multiple times with different targeted queries (e.g., 'introduction', 'methodology', 'results', 'conclusions') rather than one broad query.",
+      "A natural language query to search for relevant information in the files. Be SPECIFIC and TARGETED — use keywords for the specific section or topic you need. For comprehensive tasks (summaries, overviews), call this tool multiple times with different targeted queries (e.g., 'introduction', 'methodology', 'results', 'conclusions') rather than one broad query."
     ),
   target_files: z
     .array(z.string())
     .optional()
     .describe(
-      'Optional list of filenames (or partial names) to limit the search to. When provided, only files whose name contains one of these strings will be searched. Use this to avoid searching irrelevant files. Omit to search all available files.',
+      'Optional list of filenames (or partial names) to limit the search to. When provided, only files whose name contains one of these strings will be searched. Use this to avoid searching irrelevant files. Omit to search all available files.'
     ),
 });
 

package/src/tools/fileSearch/tool.ts

@@ -54,7 +54,7 @@ Cite EVERY statement derived from file content. Place the citation anchor IMMEDI
 }
 
 export function createFileSearchTool(
-  config: FileSearchToolConfig,
+  config: FileSearchToolConfig
 ): DynamicStructuredTool {
   const {
     ragClient,
@@ -97,16 +97,16 @@ export function createFileSearchTool(
       if (target_files && target_files.length > 0) {
         const lowerTargets = target_files.map((t) => t.toLowerCase());
         const matched = files.filter((f) =>
-          lowerTargets.some((t) => f.filename.toLowerCase().includes(t)),
+          lowerTargets.some((t) => f.filename.toLowerCase().includes(t))
         );
         if (matched.length === 0) {
           logger?.warn(
-            `[file_search] No files matched target_files ${target_files.join(', ')}; falling back to all files`,
+            `[file_search] No files matched target_files ${target_files.join(', ')}; falling back to all files`
           );
           filesToQuery = files;
         } else {
           logger?.info(
-            `[file_search] Filtered to ${matched.length}/${files.length} via target_files`,
+            `[file_search] Filtered to ${matched.length}/${files.length} via target_files`
           );
           filesToQuery = matched;
         }
@@ -131,7 +131,7 @@ export function createFileSearchTool(
         } catch (err) {
           const e = err instanceof Error ? err : new Error(String(err));
           logger?.error(
-            `[file_search] Query failed for ${file.filename}: ${e.message}`,
+            `[file_search] Query failed for ${file.filename}: ${e.message}`
           );
           callbacks?.onFileError?.(file, e);
           return [];
@@ -200,7 +200,7 @@ export function createFileSearchTool(
       responseFormat: 'content_and_artifact',
       description: buildDescription({ fileCitations }),
       schema: fileSearchInputSchema,
-    },
+    }
   );
 }
 

package/src/tools/fileSearch/types.ts

@@ -79,7 +79,7 @@ export interface FileSearchResultFormatter {
       callIndex: number;
       /** Same files list the factory was seeded with (for lookups). */
       files: FileSearchFile[];
-    },
+    }
   ): {
     /** Message returned to the LLM (content). */
     message: string;
@@ -122,7 +122,9 @@ export interface FileSearchToolConfig {
    * the host can mint fresh short-lived tokens (ranger's JWT pattern).
    * When omitted, no auth headers are sent.
    */
-  getAuthHeaders?: () => Record<string, string> | Promise<Record<string, string>>;
+  getAuthHeaders?: () =>
+    | Record<string, string>
+    | Promise<Record<string, string>>;
   /**
    * Result formatter. When omitted, the default plain-text formatter is
    * used (suitable for CLI/A2A runtimes that don't need citation anchors).