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

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

@@ -0,0 +1,259 @@
+/**
+ * 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,99 @@
+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>;

package/src/tools/artifacts/tool.ts

@@ -0,0 +1,289 @@
+/**
+ * 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';