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

package/dist/types/tools/fileSearch/formatter.d.ts

@@ -0,0 +1,25 @@
+/**
+ * Default result formatters.
+ *
+ * - `plainTextFormatter`: CLI / A2A / generic output. No citation anchors.
+ * - `citationAnchorFormatter`: ranger-style `\ue202turn0fileN` anchors with
+ *   a monotonic `sourceOffset` so multi-call turns stay globally unique.
+ *
+ * Runtimes can supply their own `FileSearchResultFormatter` to override.
+ */
+import type { FileSearchResultFormatter, FileSearchFile, RagChunk } from './types';
+export declare const plainTextFormatter: FileSearchResultFormatter;
+export interface CitationAnchorFormatterOptions {
+    /** Tool name used in the `file_search` artifact wrapper. Defaults to `'file_search'`. */
+    toolName?: string;
+    /**
+     * Monotonic counter for source indices within a turn. Pass the SAME
+     * function to the formatter across multiple calls in the same turn so
+     * anchors stay globally unique.
+     */
+    getSourceOffset?: () => number;
+    /** Called after formatting to advance the offset. */
+    advanceSourceOffset?: (by: number) => void;
+}
+export declare function createCitationAnchorFormatter(opts?: CitationAnchorFormatterOptions): FileSearchResultFormatter;
+export type { FileSearchResultFormatter, FileSearchFile, RagChunk };

package/dist/types/tools/fileSearch/index.d.ts

@@ -0,0 +1,5 @@
+export { createFileSearchTool, FileSearchToolName } from './tool';
+export { HttpRagClient, getRagBaseUrl, RAG_API_URL_ENV, type HttpRagClientOptions, } from './ragClient';
+export { plainTextFormatter, createCitationAnchorFormatter, type CitationAnchorFormatterOptions, } from './formatter';
+export { fileSearchInputSchema, type FileSearchInput } from './schema';
+export type { FileSearchFile, RagChunk, RagClient, RagQueryParams, FileSearchResultFormatter, FileSearchToolCallbacks, FileSearchToolConfig, FileSearchToolLogger, } from './types';

package/dist/types/tools/fileSearch/ragClient.d.ts

@@ -0,0 +1,32 @@
+/**
+ * Default HTTP RAG client. Posts to `${baseUrl}/query` with the shape
+ * rag_api expects (`{ file_id, query, k, entity_id? }`). Runtimes that
+ * use a different vector backend implement their own `RagClient`.
+ *
+ * Auth is runtime-provided per call (via `authHeaders` on the params) so
+ * short-lived tokens can be minted per request without the client
+ * caching stale credentials.
+ */
+import type { RagClient, RagQueryParams, RagChunk, FileSearchToolLogger } from './types';
+export declare const RAG_API_URL_ENV = "RAG_API_URL";
+/** Resolve base URL at call time so env-var changes propagate. */
+export declare function getRagBaseUrl(override?: string): string;
+export interface HttpRagClientOptions {
+    /** Base URL of the RAG service (no trailing slash). Falls back to env. */
+    baseUrl?: string;
+    /** Default headers sent on every request (e.g., a static API key). */
+    defaultHeaders?: Record<string, string>;
+    /** Default timeout if params don't override. Default 15_000. */
+    defaultTimeoutMs?: number;
+    logger?: FileSearchToolLogger;
+}
+export declare class HttpRagClient implements RagClient {
+    private readonly baseUrlOverride?;
+    private readonly defaultHeaders;
+    private readonly defaultTimeoutMs;
+    private readonly logger?;
+    constructor(opts?: HttpRagClientOptions);
+    query(params: RagQueryParams): Promise<RagChunk[]>;
+    /** Convert rag_api's tuple format into the library's normalized shape. */
+    private normalize;
+}

package/dist/types/tools/fileSearch/schema.d.ts

@@ -0,0 +1,13 @@
+import { z } from 'zod';
+export declare const fileSearchInputSchema: z.ZodObject<{
+    query: z.ZodString;
+    target_files: z.ZodOptional<z.ZodArray<z.ZodString, "many">>;
+}, "strip", z.ZodTypeAny, {
+    query: string;
+    target_files?: string[] | undefined;
+}, {
+    query: string;
+    target_files?: string[] | undefined;
+}>;
+export type FileSearchInput = z.infer<typeof fileSearchInputSchema>;
+export declare const FileSearchToolName = "file_search";

package/dist/types/tools/fileSearch/tool.d.ts

@@ -0,0 +1,18 @@
+/**
+ * file_search tool factory — library-native equivalent of the CodeExecutor
+ * pattern. Runtimes supply a `RagClient`, the file list for this turn, and
+ * an optional formatter (ranger uses citation anchors; CLI/A2A use plain
+ * text).
+ *
+ * The tool itself:
+ *   1. Accepts `{ query, target_files? }` from the LLM.
+ *   2. Filters files by `target_files` substring match when provided.
+ *   3. Queries each file in bounded concurrent batches.
+ *   4. Enforces per-file timeouts (failures isolated per file).
+ *   5. Flattens chunks, deprioritizes stale-turn files, caps results.
+ *   6. Hands formatted output to the runtime's formatter for final shape.
+ */
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import type { FileSearchToolConfig } from './types';
+export declare function createFileSearchTool(config: FileSearchToolConfig): DynamicStructuredTool;
+export { FileSearchToolName } from './schema';

package/dist/types/tools/fileSearch/types.d.ts

@@ -0,0 +1,139 @@
+/**
+ * File-search tool types. Mirrors the web_search / code_executor split —
+ * the library owns tool logic; the host supplies a `RagClient` + config
+ * shaped to its own deployment (auth strategy, scope identity, file set).
+ */
+export interface FileSearchFile {
+    /** Stable identifier within the RAG backend. */
+    file_id: string;
+    /** Human-readable name surfaced in tool results and prompts. */
+    filename: string;
+    /**
+     * Hint that this file arrived on the *current* conversation turn (as
+     * opposed to an earlier turn). Hosts that don't distinguish leave this
+     * undefined; the formatter deprioritizes older files when set.
+     */
+    isCurrentMessage?: boolean;
+}
+/**
+ * A single chunk returned by the RAG backend for a query.
+ * Shape is normalized here so the library stays independent of any
+ * specific RAG service's response format — the `RagClient` is responsible
+ * for translating the backend response into this shape.
+ */
+export interface RagChunk {
+    file_id: string;
+    page_content: string;
+    distance: number;
+    metadata?: Record<string, unknown>;
+}
+export interface RagQueryParams {
+    file_id: string;
+    query: string;
+    /** Top-K chunks to return per file. Default 10. */
+    k?: number;
+    /** Optional tenant/entity ID — forwarded to the backend verbatim. */
+    entity_id?: string;
+    /**
+     * Scope identifier. Hosts use this for per-tenant isolation in the RAG
+     * backend (ranger → userId, cli → agentId, a2a → task-id).
+     */
+    scope?: string;
+    /**
+     * Per-request auth headers — the host builds these (e.g., ranger sends
+     * `Authorization: Bearer <short-lived-JWT-for-userId>`). Allows
+     * different runtimes to use different auth strategies without the
+     * library knowing.
+     */
+    authHeaders?: Record<string, string>;
+    /** Optional per-call timeout override. */
+    timeoutMs?: number;
+}
+/**
+ * Pluggable RAG backend. Runtimes provide an implementation that speaks
+ * to whatever vector DB / search service they've deployed (rag_api is the
+ * default; azure search, pinecone, etc. are valid alternates).
+ */
+export interface RagClient {
+    query(params: RagQueryParams): Promise<RagChunk[]>;
+}
+/**
+ * Formatter callback that shapes raw chunks into the runtime's preferred
+ * presentation. Ranger uses citation anchors (`\ue202turn0fileN`), CLI
+ * uses plain text, A2A server can return structured parts.
+ */
+export interface FileSearchResultFormatter {
+    format(chunks: Array<RagChunk & {
+        filename: string;
+        isCurrentMessage: boolean;
+    }>, context: {
+        /**
+         * Monotonic call index within a single turn. Ranger uses this to
+         * keep citation source indices globally unique across multiple
+         * file_search invocations.
+         */
+        callIndex: number;
+        /** Same files list the factory was seeded with (for lookups). */
+        files: FileSearchFile[];
+    }): {
+        /** Message returned to the LLM (content). */
+        message: string;
+        /** Optional artifact payload (sources, metadata) returned alongside. */
+        artifact?: unknown;
+    };
+}
+export interface FileSearchToolCallbacks {
+    /**
+     * Fires when a RAG query completes successfully for one file. Hosts can
+     * use this for telemetry, streaming UI updates, etc.
+     */
+    onFileQueried?: (file: FileSearchFile, chunkCount: number) => void;
+    /** Fires when a RAG query fails. Hosts can log or surface via UI. */
+    onFileError?: (file: FileSearchFile, error: Error) => void;
+}
+export interface FileSearchToolLogger {
+    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 FileSearchToolConfig {
+    /** The RAG backend client. Required. */
+    ragClient: RagClient;
+    /** Files the agent has access to this turn. Empty = tool self-reports so. */
+    files: FileSearchFile[];
+    /** Tenant/entity ID forwarded to the backend per-query. */
+    entity_id?: string;
+    /**
+     * Per-turn scope identity. Most runtimes pin this once (userId/agentId);
+     * if omitted, no scope is sent to the backend.
+     */
+    scope?: string;
+    /**
+     * Per-call auth header builder. Called on every tool invocation so
+     * 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>>;
+    /**
+     * Result formatter. When omitted, the default plain-text formatter is
+     * used (suitable for CLI/A2A runtimes that don't need citation anchors).
+     */
+    formatter?: FileSearchResultFormatter;
+    /** Per-file query timeout in ms. Default 15_000. */
+    queryTimeoutMs?: number;
+    /**
+     * Max concurrent in-flight RAG queries. Protects HTTP connection pools
+     * under heavy file counts. Default 10.
+     */
+    concurrencyLimit?: number;
+    /** Top-K chunks per file. Default 10. */
+    topK?: number;
+    /**
+     * Cap on total chunks returned to the LLM after sorting. Default is
+     * `max(10, filesCount * 3)`.
+     */
+    resultCap?: number;
+    callbacks?: FileSearchToolCallbacks;
+    logger?: FileSearchToolLogger;
+}

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.4.0-alpha.1",
+  "version": "1.4.0-alpha.3",
   "main": "./dist/cjs/main.cjs",
   "module": "./dist/esm/main.mjs",
   "types": "./dist/types/index.d.ts",

package/src/index.ts

@@ -26,6 +26,8 @@ export * from './tools/schema';
 export * from './tools/handlers';
 export * from './tools/search';
 export * from './tools/memory';
+export * from './tools/fileSearch';
+export * from './tools/artifacts';
 export * from './tools/proxyTool';
 
 /* Capability Providers */

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

@@ -0,0 +1,243 @@
+/**
+ * Unit tests for the artifact_tool + content_reader library factories.
+ *
+ * The factories are thin dispatchers — their job is:
+ *   1. Resolve scope from runnableConfig (error if missing)
+ *   2. Optionally self-heal content_id via the resolver
+ *   3. Validate per-action required args
+ *   4. Route to the runtime's handler, propagate errors
+ *
+ * We verify each of those paths here with mock handlers.
+ */
+
+import {
+  createArtifactTool,
+  createContentReaderTool,
+} from '../tool';
+import type {
+  ArtifactWriteHandlers,
+  ContentReadHandlers,
+  ArtifactToolScope,
+  ArtifactToolResult,
+  ContentIdResolver,
+} from '../types';
+
+function makeScope(): ArtifactToolScope {
+  return { conversationId: 'conv-1', userId: 'user-1' };
+}
+
+function makeWriteHandlers(): ArtifactWriteHandlers & {
+  _calls: Array<{ action: string; args: unknown; scope: ArtifactToolScope }>;
+} {
+  const calls: Array<{
+    action: string;
+    args: unknown;
+    scope: ArtifactToolScope;
+  }> = [];
+  return {
+    _calls: calls,
+    write: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'write', args, scope });
+      return ['wrote it', { id: 'new-id' }];
+    }),
+    edit: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'edit', args, scope });
+      return ['edited', {}];
+    }),
+    verify: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'verify', args, scope });
+      return ['verified', {}];
+    }),
+    delete: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'delete', args, scope });
+      return ['deleted', {}];
+    }),
+  };
+}
+
+function makeReadHandlers(): ContentReadHandlers & {
+  _calls: Array<{ action: string; args: unknown; scope: ArtifactToolScope }>;
+} {
+  const calls: Array<{
+    action: string;
+    args: unknown;
+    scope: ArtifactToolScope;
+  }> = [];
+  return {
+    _calls: calls,
+    read: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'read', args, scope });
+      return ['read-output', {}];
+    }),
+    search: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'search', args, scope });
+      return ['search-output', {}];
+    }),
+    list: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'list', args, scope });
+      return ['list-output', {}];
+    }),
+    info: jest.fn(async (args, scope): Promise<ArtifactToolResult> => {
+      calls.push({ action: 'info', args, scope });
+      return ['info-output', {}];
+    }),
+  };
+}
+
+describe('createArtifactTool', () => {
+  it('returns a scope error when getScope returns null', async () => {
+    const handlers = makeWriteHandlers();
+    const t = createArtifactTool({
+      handlers,
+      getScope: () => null,
+    });
+    const result = await t.invoke({ action: 'write', content: 'x' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    expect(text).toMatch(/no conversation context/i);
+  });
+
+  it('dispatches write to handlers.write with resolved args + scope', async () => {
+    const handlers = makeWriteHandlers();
+    const t = createArtifactTool({
+      handlers,
+      getScope: makeScope,
+    });
+    await t.invoke({ action: 'write', content: 'hello', name: 'doc.md' });
+    expect(handlers.write).toHaveBeenCalledTimes(1);
+    expect(handlers._calls[0].args).toEqual(
+      expect.objectContaining({ action: 'write', content: 'hello', name: 'doc.md' }),
+    );
+    expect(handlers._calls[0].scope).toEqual(
+      expect.objectContaining({ conversationId: 'conv-1' }),
+    );
+  });
+
+  it('rejects write without content', async () => {
+    const handlers = makeWriteHandlers();
+    const t = createArtifactTool({
+      handlers,
+      getScope: makeScope,
+    });
+    const result = await t.invoke({ action: 'write' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    expect(text).toMatch(/write requires content/i);
+    expect(handlers.write).not.toHaveBeenCalled();
+  });
+
+  it('rejects edit/verify/delete without content_id', async () => {
+    const handlers = makeWriteHandlers();
+    const t = createArtifactTool({
+      handlers,
+      getScope: makeScope,
+    });
+    const e = await t.invoke({ action: 'edit', old_str: 'a', new_str: 'b' });
+    expect(String(Array.isArray(e) ? e[0] : e)).toMatch(/edit requires content_id/i);
+    const v = await t.invoke({ action: 'verify' });
+    expect(String(Array.isArray(v) ? v[0] : v)).toMatch(/verify requires content_id/i);
+    const d = await t.invoke({ action: 'delete' });
+    expect(String(Array.isArray(d) ? d[0] : d)).toMatch(/delete requires content_id/i);
+  });
+
+  it('applies the resolver before dispatching to handler', async () => {
+    const handlers = makeWriteHandlers();
+    const resolver: ContentIdResolver = {
+      resolve: jest.fn(async (id) => ({ resolvedId: `canonical:${id}`, resolvedName: 'X' })),
+    };
+    const t = createArtifactTool({
+      handlers,
+      getScope: makeScope,
+      resolver,
+    });
+    await t.invoke({
+      action: 'edit',
+      content_id: 'nickname',
+      old_str: 'a',
+      new_str: 'b',
+    });
+    expect(handlers._calls[0].args).toEqual(
+      expect.objectContaining({ content_id: 'canonical:nickname' }),
+    );
+  });
+
+  it('catches handler exceptions and returns them as tool errors', async () => {
+    const handlers = makeWriteHandlers();
+    handlers.write = jest.fn(async () => {
+      throw new Error('s3 unavailable');
+    });
+    const t = createArtifactTool({
+      handlers,
+      getScope: makeScope,
+    });
+    const result = await t.invoke({ action: 'write', content: 'x' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    expect(text).toMatch(/s3 unavailable/);
+  });
+
+  it('honors descriptionOverride for host-specific guidance', async () => {
+    const handlers = makeWriteHandlers();
+    const t = createArtifactTool({
+      handlers,
+      getScope: makeScope,
+      descriptionOverride: 'HOST-BRAND-GUIDE',
+    });
+    expect(t.description).toBe('HOST-BRAND-GUIDE');
+  });
+});
+
+describe('createContentReaderTool', () => {
+  it('dispatches list with no content_id required', async () => {
+    const handlers = makeReadHandlers();
+    const t = createContentReaderTool({
+      handlers,
+      getScope: makeScope,
+    });
+    await t.invoke({ action: 'list' });
+    expect(handlers.list).toHaveBeenCalledTimes(1);
+  });
+
+  it('rejects read/info/search without content_id', async () => {
+    const handlers = makeReadHandlers();
+    const t = createContentReaderTool({
+      handlers,
+      getScope: makeScope,
+    });
+    const r = await t.invoke({ action: 'read' });
+    expect(String(Array.isArray(r) ? r[0] : r)).toMatch(/read requires content_id/i);
+    const i = await t.invoke({ action: 'info' });
+    expect(String(Array.isArray(i) ? i[0] : i)).toMatch(/info requires content_id/i);
+    const s = await t.invoke({ action: 'search', pattern: 'p' });
+    expect(String(Array.isArray(s) ? s[0] : s)).toMatch(/search requires content_id/i);
+  });
+
+  it('rejects search without pattern even when content_id is given', async () => {
+    const handlers = makeReadHandlers();
+    const t = createContentReaderTool({
+      handlers,
+      getScope: makeScope,
+    });
+    const result = await t.invoke({ action: 'search', content_id: 'x' });
+    const text = Array.isArray(result) ? String(result[0]) : String(result);
+    expect(text).toMatch(/search requires pattern/i);
+  });
+
+  it('passes read pagination args through to the handler', async () => {
+    const handlers = makeReadHandlers();
+    const t = createContentReaderTool({
+      handlers,
+      getScope: makeScope,
+    });
+    await t.invoke({
+      action: 'read',
+      content_id: 'c-1',
+      start_line: 10,
+      end_line: 50,
+    });
+    expect(handlers._calls[0].args).toEqual(
+      expect.objectContaining({
+        content_id: 'c-1',
+        start_line: 10,
+        end_line: 50,
+      }),
+    );
+  });
+});

package/src/tools/artifacts/index.ts

@@ -0,0 +1,33 @@
+export {
+  createArtifactTool,
+  createContentReaderTool,
+  ARTIFACT_TOOL_NAME,
+  CONTENT_READER_NAME,
+  ARTIFACT_WRITE_ACTIONS,
+  CONTENT_READ_ACTIONS,
+} from './tool';
+export {
+  artifactToolSchema,
+  contentReaderSchema,
+  type ArtifactToolInput,
+  type ContentReaderInput,
+} from './schema';
+export type {
+  ArtifactToolScope,
+  ArtifactToolResult,
+  ArtifactToolLogger,
+  ArtifactToolBaseConfig,
+  ArtifactToolConfig,
+  ContentReaderToolConfig,
+  ArtifactWriteHandlers,
+  ContentReadHandlers,
+  ContentIdResolver,
+  WriteArgs,
+  EditArgs,
+  VerifyArgs,
+  DeleteArgs,
+  ReadArgs,
+  SearchArgs,
+  ListArgs,
+  InfoArgs,
+} from './types';

package/src/tools/artifacts/schema.ts

@@ -0,0 +1,76 @@
+import { z } from 'zod';
+
+export const ARTIFACT_WRITE_ACTIONS = ['write', 'edit', 'verify', 'delete'] as const;
+export const CONTENT_READ_ACTIONS = ['read', 'search', 'list', 'info'] as const;
+
+export const artifactToolSchema = z.object({
+  action: z
+    .enum(ARTIFACT_WRITE_ACTIONS)
+    .describe(
+      'Authoring action: write (create/overwrite), edit (str_replace), verify (syntax check), delete (remove).',
+    ),
+  content_id: z
+    .string()
+    .optional()
+    .describe(
+      'ID of the artifact entry. Required for edit/verify/delete; optional for write (supply to overwrite an existing entry).',
+    ),
+
+  // write
+  content: z
+    .string()
+    .optional()
+    .describe('Full file content (required for write action).'),
+  name: z
+    .string()
+    .optional()
+    .describe(
+      'Filename for the new entry (required when creating). MUST include the correct file extension — the extension drives the preview template.',
+    ),
+
+  // edit (str_replace)
+  old_str: z
+    .string()
+    .optional()
+    .describe('Exact string to find and replace (required for edit).'),
+  new_str: z.string().optional().describe('Replacement string (required for edit).'),
+  replace_all: z
+    .boolean()
+    .optional()
+    .describe(
+      'edit: when true, replaces every occurrence of old_str. When false (default) and old_str matches more than one location, the edit is refused.',
+    ),
+});
+
+export const contentReaderSchema = z.object({
+  action: z
+    .enum(CONTENT_READ_ACTIONS)
+    .describe(
+      'Read-only action: read (lines), search (regex), list (all entries), info (metadata).',
+    ),
+  content_id: z
+    .string()
+    .optional()
+    .describe(
+      'ID of the content entry. Required for read/search/info. Omit for list.',
+    ),
+
+  // read pagination
+  start_line: z.number().optional().describe('1-based start line for reading.'),
+  end_line: z.number().optional().describe('1-based end line (inclusive).'),
+
+  // search
+  pattern: z.string().optional().describe('Regex pattern (required for search).'),
+  flags: z.string().optional().describe('Regex flags (e.g., "i" for case-insensitive).'),
+  context: z.number().optional().describe('Lines of context around each match.'),
+
+  // shared pagination
+  offset: z.number().optional().describe('Offset for read or search pagination.'),
+  limit: z.number().optional().describe('Max lines (read) or matches (search).'),
+});
+
+export const ARTIFACT_TOOL_NAME = 'artifact_tool';
+export const CONTENT_READER_NAME = 'content_reader';
+
+export type ArtifactToolInput = z.infer<typeof artifactToolSchema>;
+export type ContentReaderInput = z.infer<typeof contentReaderSchema>;