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

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

@@ -0,0 +1,63 @@
+import { z } from 'zod';
+export declare const ARTIFACT_WRITE_ACTIONS: readonly ["write", "edit", "verify", "delete"];
+export declare const CONTENT_READ_ACTIONS: readonly ["read", "search", "list", "info"];
+export declare const artifactToolSchema: z.ZodObject<{
+    action: z.ZodEnum<["write", "edit", "verify", "delete"]>;
+    content_id: z.ZodOptional<z.ZodString>;
+    content: z.ZodOptional<z.ZodString>;
+    name: z.ZodOptional<z.ZodString>;
+    old_str: z.ZodOptional<z.ZodString>;
+    new_str: z.ZodOptional<z.ZodString>;
+    replace_all: z.ZodOptional<z.ZodBoolean>;
+}, "strip", z.ZodTypeAny, {
+    action: "write" | "delete" | "edit" | "verify";
+    content?: string | undefined;
+    name?: string | undefined;
+    old_str?: string | undefined;
+    new_str?: string | undefined;
+    content_id?: string | undefined;
+    replace_all?: boolean | undefined;
+}, {
+    action: "write" | "delete" | "edit" | "verify";
+    content?: string | undefined;
+    name?: string | undefined;
+    old_str?: string | undefined;
+    new_str?: string | undefined;
+    content_id?: string | undefined;
+    replace_all?: boolean | undefined;
+}>;
+export declare const contentReaderSchema: z.ZodObject<{
+    action: z.ZodEnum<["read", "search", "list", "info"]>;
+    content_id: z.ZodOptional<z.ZodString>;
+    start_line: z.ZodOptional<z.ZodNumber>;
+    end_line: z.ZodOptional<z.ZodNumber>;
+    pattern: z.ZodOptional<z.ZodString>;
+    flags: z.ZodOptional<z.ZodString>;
+    context: z.ZodOptional<z.ZodNumber>;
+    offset: z.ZodOptional<z.ZodNumber>;
+    limit: z.ZodOptional<z.ZodNumber>;
+}, "strip", z.ZodTypeAny, {
+    action: "read" | "search" | "info" | "list";
+    pattern?: string | undefined;
+    context?: number | undefined;
+    flags?: string | undefined;
+    content_id?: string | undefined;
+    start_line?: number | undefined;
+    end_line?: number | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}, {
+    action: "read" | "search" | "info" | "list";
+    pattern?: string | undefined;
+    context?: number | undefined;
+    flags?: string | undefined;
+    content_id?: string | undefined;
+    start_line?: number | undefined;
+    end_line?: number | undefined;
+    offset?: number | undefined;
+    limit?: number | undefined;
+}>;
+export declare const ARTIFACT_TOOL_NAME = "artifact_tool";
+export declare const CONTENT_READER_NAME = "content_reader";
+export type ArtifactToolInput = z.infer<typeof artifactToolSchema>;
+export type ContentReaderInput = z.infer<typeof contentReaderSchema>;

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

@@ -0,0 +1,16 @@
+/**
+ * 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 { DynamicStructuredTool } from '@langchain/core/tools';
+import type { ArtifactToolConfig, ContentReaderToolConfig } from './types';
+export declare function createArtifactTool(config: ArtifactToolConfig): DynamicStructuredTool;
+export declare function createContentReaderTool(config: ContentReaderToolConfig): DynamicStructuredTool;
+export { ARTIFACT_TOOL_NAME, CONTENT_READER_NAME, ARTIFACT_WRITE_ACTIONS, CONTENT_READ_ACTIONS, } from './schema';

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

@@ -0,0 +1,127 @@
+/**
+ * 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];
+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;
+/** 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/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@illuma-ai/agents",
-  "version": "1.4.0-alpha.2",
+  "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

@@ -27,6 +27,7 @@ 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>;