@illuma-ai/agents 1.4.0-alpha.5 → 1.5.0

package/src/tools/artifacts/schema.ts

@@ -1,99 +0,0 @@
-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

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

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