@illuma-ai/agents 1.4.0-alpha.2 → 1.4.0-alpha.4

package/src/tools/artifacts/types.ts

@@ -0,0 +1,162 @@
+/**
+ * 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).