@librechat/agents 3.4.6 → 3.5.0

package/src/tools/__tests__/intentArg.test.ts

@@ -1,357 +0,0 @@
-import { describe, it, expect } from '@jest/globals';
-import type { JsonSchemaType } from '@/types';
-import {
-  INTENT_ARG,
-  INTENT_PROPERTY,
-  INTENT_DESCRIPTION,
-  INTENT_LABEL_MARKER,
-  withoutIntent,
-  withIntent,
-  readIntent,
-  stripIntent,
-  applyOutcome,
-  readOutcomeFields,
-  resolveToolOutcome,
-} from '../intentArg';
-import { ReadFileToolSchema } from '../ReadFile';
-
-describe('withIntent', () => {
-  const base: JsonSchemaType = {
-    type: 'object',
-    properties: {
-      query: { type: 'string', description: 'Search query' },
-      limit: { type: 'number' },
-    },
-    required: ['query'],
-  };
-
-  it('prepends intent as the FIRST property key', () => {
-    const next = withIntent(base);
-    expect(Object.keys(next.properties ?? {})).toEqual(['intent', 'query', 'limit']);
-    expect(next.properties?.[INTENT_ARG]).toEqual(INTENT_PROPERTY);
-    /**
-     * Must be a copy, not the frozen canonical instance: LangChain's
-     * JSON-schema validator stamps `__absolute_uri__` onto subschemas,
-     * which throws on a frozen object.
-     */
-    expect(next.properties?.[INTENT_ARG]).not.toBe(INTENT_PROPERTY);
-    expect(Object.isFrozen(next.properties?.[INTENT_ARG])).toBe(false);
-  });
-
-  it('never mutates the input schema', () => {
-    const frozen = Object.freeze<JsonSchemaType>({
-      type: 'object',
-      properties: Object.freeze({ query: { type: 'string' } }),
-    }) as JsonSchemaType;
-    const next = withIntent(frozen);
-    expect(next).not.toBe(frozen);
-    expect(Object.keys(frozen.properties ?? {})).toEqual(['query']);
-    expect(Object.keys(next.properties ?? {})).toEqual(['intent', 'query']);
-  });
-
-  it('does not add intent to required', () => {
-    const next = withIntent(base);
-    expect(next.required).toEqual(['query']);
-  });
-
-  it('is idempotent when intent already exists (position preserved)', () => {
-    const once = withIntent(base);
-    const twice = withIntent(once);
-    expect(twice).toBe(once);
-    expect(Object.keys(twice.properties ?? {})[0]).toBe('intent');
-  });
-
-  it('handles a schema with no properties', () => {
-    const next = withIntent({ type: 'object', properties: {} });
-    expect(Object.keys(next.properties ?? {})).toEqual(['intent']);
-  });
-
-  it('handles an undefined schema', () => {
-    const next = withIntent(undefined);
-    expect(next.type).toBe('object');
-    expect(Object.keys(next.properties ?? {})).toEqual(['intent']);
-  });
-
-  it('carries the model-facing instruction', () => {
-    expect(INTENT_PROPERTY.description).toBe(INTENT_DESCRIPTION);
-    expect(INTENT_DESCRIPTION).toContain('FIRST');
-    /** Sibling differentiation is the headline case; models emit identical
-     *  labels for parallel calls without it. */
-    expect(INTENT_DESCRIPTION).toContain('Sibling calls to one tool must differ');
-  });
-
-  it('opens with the exported marker so host strip passes can key on it', () => {
-    expect(INTENT_DESCRIPTION.startsWith(INTENT_LABEL_MARKER)).toBe(true);
-  });
-
-  it('stays terse — it is repeated per tool, per request', () => {
-    expect(INTENT_DESCRIPTION.length).toBeLessThanOrEqual(300);
-  });
-});
-
-describe('withoutIntent', () => {
-  it('removes the injected label — the opt-out for embedders that render none', () => {
-    const withLabel = withIntent({
-      type: 'object',
-      properties: { query: { type: 'string' } },
-      required: ['query'],
-    });
-    const stripped = withoutIntent(withLabel);
-    expect(Object.keys(stripped?.properties ?? {})).toEqual(['query']);
-    expect(stripped?.required).toEqual(['query']);
-  });
-
-  it('never removes a tool-owned business `intent` parameter', () => {
-    const business: JsonSchemaType = {
-      type: 'object',
-      properties: { intent: { type: 'string', description: 'CRM intent category' } },
-      required: ['intent'],
-    };
-    expect(withoutIntent(business)).toBe(business);
-  });
-
-  it('is a no-op on schemas without the label', () => {
-    const plain: JsonSchemaType = { type: 'object', properties: { q: { type: 'string' } } };
-    expect(withoutIntent(plain)).toBe(plain);
-    expect(withoutIntent(undefined)).toBeUndefined();
-  });
-
-  it('prunes intent from `required` too, so the schema stays valid', () => {
-    /** Strict-mode normalization lists every property in `required`; leaving
-     *  a dangling entry yields invalid JSON Schema the provider rejects. */
-    const strict: JsonSchemaType = {
-      type: 'object',
-      properties: { intent: { ...INTENT_PROPERTY }, path: { type: 'string' } },
-      required: ['intent', 'path'],
-    };
-    const stripped = withoutIntent(strict);
-    expect(Object.keys(stripped?.properties ?? {})).toEqual(['path']);
-    expect(stripped?.required).toEqual(['path']);
-  });
-
-  it('drops `required` entirely when intent was its only entry', () => {
-    const onlyIntent: JsonSchemaType = {
-      type: 'object',
-      properties: { intent: { ...INTENT_PROPERTY } },
-      required: ['intent'],
-    };
-    const stripped = withoutIntent(onlyIntent);
-    expect(stripped?.required).toBeUndefined();
-    expect(Object.keys(stripped?.properties ?? {})).toEqual([]);
-  });
-
-  it('accepts a readonly `as const` native schema without a cast', () => {
-    /** ReadFileToolSchema is declared `as const`, so `required` is a readonly
-     *  tuple — this call is the compile-time assertion that the advertised
-     *  opt-out is usable on the schemas it exists for. */
-    const stripped = withoutIntent(ReadFileToolSchema);
-    expect(Object.keys(stripped?.properties ?? {})).toEqual(['path']);
-    expect(stripped?.required).toEqual(['path']);
-  });
-
-  it('round-trips with withIntent', () => {
-    const base: JsonSchemaType = { type: 'object', properties: { q: { type: 'string' } } };
-    expect(withoutIntent(withIntent(base))).toEqual(base);
-  });
-});
-
-describe('readIntent', () => {
-  it('reads from object args', () => {
-    expect(readIntent({ intent: 'Searching for OAuth handling' })).toBe(
-      'Searching for OAuth handling'
-    );
-  });
-
-  it('reads from stringified JSON args', () => {
-    expect(readIntent('{"intent":"Searching for OAuth handling","query":"oauth"}')).toBe(
-      'Searching for OAuth handling'
-    );
-  });
-
-  it('returns undefined for absent, empty, or non-string intents', () => {
-    expect(readIntent({ query: 'oauth' })).toBeUndefined();
-    expect(readIntent({ intent: '' })).toBeUndefined();
-    expect(readIntent({ intent: '   ' })).toBeUndefined();
-    expect(readIntent({ intent: 42 })).toBeUndefined();
-    expect(readIntent(undefined)).toBeUndefined();
-    expect(readIntent('not json')).toBeUndefined();
-    expect(readIntent('{"intent": broken')).toBeUndefined();
-  });
-});
-
-describe('stripIntent', () => {
-  it('removes the key from object args', () => {
-    expect(stripIntent({ intent: 'Searching', query: 'oauth' })).toEqual({ query: 'oauth' });
-  });
-
-  it('parses and strips stringified args', () => {
-    expect(stripIntent('{"intent":"Searching","query":"oauth"}')).toEqual({ query: 'oauth' });
-  });
-
-  it('returns args unchanged when the key is absent', () => {
-    const args = { query: 'oauth' };
-    expect(stripIntent(args)).toBe(args);
-    expect(stripIntent('plain string')).toBe('plain string');
-    expect(stripIntent(undefined)).toBeUndefined();
-  });
-});
-
-describe('applyOutcome', () => {
-  const intent = 'Searching for OAuth handling';
-
-  it('prefers a tool-supplied outcome (full replacement)', () => {
-    expect(
-      applyOutcome(intent, {
-        outcome: 'Found 12 results for OAuth handling',
-        outcome_patch: { from: 'Searching', to: 'Searched' },
-      })
-    ).toBe('Found 12 results for OAuth handling');
-  });
-
-  it('ignores a blank outcome', () => {
-    expect(applyOutcome(intent, { outcome: '  ' })).toBe(intent);
-  });
-
-  it('applies outcome_patch to the first occurrence only, case-sensitive', () => {
-    expect(
-      applyOutcome('Searching for Searching patterns', {
-        outcome_patch: { from: 'Searching', to: 'Searched' },
-      })
-    ).toBe('Searched for Searching patterns');
-    expect(
-      applyOutcome(intent, { outcome_patch: { from: 'searching', to: 'searched' } })
-    ).toBe(intent);
-  });
-
-  it('ignores a patch whose from is empty or absent from the intent', () => {
-    expect(applyOutcome(intent, { outcome_patch: { from: '', to: 'x' } })).toBe(intent);
-    expect(applyOutcome(intent, { outcome_patch: { from: 'Grepping', to: 'Grepped' } })).toBe(
-      intent
-    );
-  });
-
-  /**
-   * There is no mechanical tense rewrite: a closed English verb list would
-   * never fire for non-English labels, and would fire for some siblings but
-   * not others inside one group. Completion is a UI state, not a tense.
-   */
-  it('returns the intent unchanged when the tool authored no outcome', () => {
-    for (const label of [
-      'Reading the callback router',
-      'Recording the OAuth callback location',
-      'searching for OAuth handling',
-      'Buscando el manejo de OAuth',
-      'Searching',
-    ]) {
-      expect(applyOutcome(label)).toBe(label);
-    }
-  });
-
-  it('returns undefined with neither intent nor outcome', () => {
-    expect(applyOutcome(undefined)).toBeUndefined();
-    expect(applyOutcome('')).toBeUndefined();
-    expect(applyOutcome(undefined, { outcome_patch: { from: 'a', to: 'b' } })).toBeUndefined();
-  });
-
-  it('returns the outcome even without an intent', () => {
-    expect(applyOutcome(undefined, { outcome: 'Found 12 results' })).toBe('Found 12 results');
-  });
-});
-
-describe('resolveToolOutcome', () => {
-  const args = { intent: 'Searching for OAuth handling', query: 'oauth' };
-
-  it('returns undefined when the tool authored no outcome fields', () => {
-    expect(resolveToolOutcome(args)).toBeUndefined();
-    expect(resolveToolOutcome(args, {})).toBeUndefined();
-    expect(resolveToolOutcome(args, null)).toBeUndefined();
-  });
-
-  it('resolves a tool-supplied outcome', () => {
-    expect(resolveToolOutcome(args, { outcome: 'Found 12 results' })).toBe('Found 12 results');
-  });
-
-  it('resolves a patch against the intent read from args', () => {
-    expect(
-      resolveToolOutcome(args, { outcome_patch: { from: 'Searching', to: 'Searched' } })
-    ).toBe('Searched for OAuth handling');
-  });
-
-  it('returns undefined for a patch with no intent in the args', () => {
-    expect(
-      resolveToolOutcome({ query: 'oauth' }, { outcome_patch: { from: 'a', to: 'b' } })
-    ).toBeUndefined();
-  });
-
-  it('collapses the label to a bounded single line', () => {
-    expect(
-      resolveToolOutcome(args, { outcome: 'Found 12 results\n  for   "OAuth handling"' })
-    ).toBe('Found 12 results for "OAuth handling"');
-    const oversized = resolveToolOutcome(args, { outcome: `Found ${'x'.repeat(500)}` });
-    expect(oversized?.length).toBe(256);
-    expect(oversized?.endsWith('…')).toBe(true);
-    expect(resolveToolOutcome(args, { outcome: ' \n \t ' })).toBe(
-      'Searching for OAuth handling'
-    );
-  });
-
-  it('keeps $-token replacement text literal', () => {
-    expect(
-      resolveToolOutcome(args, {
-        outcome_patch: { from: 'Searching', to: 'Found $& via $\' and $$' },
-      })
-    ).toBe('Found $& via $\' and $$ for OAuth handling');
-  });
-
-  it('labels failed calls only with tool-authored text', () => {
-    expect(resolveToolOutcome(args, { outcome: 'Search failed for OAuth' }, { isError: true })).toBe(
-      'Search failed for OAuth'
-    );
-    expect(
-      resolveToolOutcome(
-        args,
-        { outcome_patch: { from: 'Searching', to: 'Search failed' } },
-        { isError: true }
-      )
-    ).toBe('Search failed for OAuth handling');
-  });
-
-  it('never reuses the in-flight intent as a failed call\'s settled label', () => {
-    expect(
-      resolveToolOutcome(
-        args,
-        { outcome_patch: { from: 'searching', to: 'searched' } },
-        { isError: true }
-      )
-    ).toBeUndefined();
-    expect(
-      resolveToolOutcome(
-        { query: 'oauth' },
-        { outcome_patch: { from: 'Searching', to: 'Searched' } },
-        { isError: true }
-      )
-    ).toBeUndefined();
-  });
-});
-
-describe('readOutcomeFields', () => {
-  it('reads valid fields from an artifact-shaped object', () => {
-    expect(readOutcomeFields({ outcome: 'Found 12 results', other: 1 })).toEqual({
-      outcome: 'Found 12 results',
-      outcome_patch: undefined,
-    });
-    expect(readOutcomeFields({ outcome_patch: { from: 'a', to: 'b' } })).toEqual({
-      outcome: undefined,
-      outcome_patch: { from: 'a', to: 'b' },
-    });
-  });
-
-  it('rejects malformed fields', () => {
-    expect(readOutcomeFields(undefined)).toBeUndefined();
-    expect(readOutcomeFields('outcome')).toBeUndefined();
-    expect(readOutcomeFields({ outcome: 42 })).toBeUndefined();
-    expect(readOutcomeFields({ outcome: '  ' })).toBeUndefined();
-    expect(readOutcomeFields({ outcome_patch: { from: 'a' } })).toBeUndefined();
-    expect(readOutcomeFields({ outcome_patch: 'Searched' })).toBeUndefined();
-  });
-});

package/src/tools/__tests__/intentCoverage.test.ts

@@ -1,139 +0,0 @@
-import { describe, it, expect } from '@jest/globals';
-import type { CloudflareSandboxRuntime } from '@/types';
-import {
-  CLOUDFLARE_CODING_TOOL_NAMES,
-  createCloudflareCodingTools,
-} from '../cloudflare/CloudflareSandboxTools';
-import {
-  createLocalCodingTools,
-  createLocalCodingToolDefinitions,
-} from '../local/LocalCodingTools';
-import {
-  BashExecutionToolSchema,
-  buildBashExecutionToolSchema,
-} from '../BashExecutor';
-import {
-  CodeExecutionToolSchema,
-  buildCodeExecutionToolSchema,
-} from '../CodeExecutor';
-import {
-  SubagentToolSchema,
-  createSubagentToolDefinition,
-} from '../SubagentTool';
-import { BashProgrammaticToolCallingSchema } from '../BashProgrammaticToolCalling';
-import { ProgrammaticToolCallingSchema } from '../ProgrammaticToolCalling';
-import { WebSearchToolSchema } from '../search/schema';
-import { LOCAL_CODING_BUNDLE_NAMES } from '@/common';
-import { ReadFileToolDefinition } from '../ReadFile';
-import { ToolSearchToolSchema } from '../ToolSearch';
-import { SkillToolDefinition } from '../SkillTool';
-import { createSearchTool } from '../search/tool';
-import { INTENT_ARG } from '../intentArg';
-
-type SchemaLike = {
-  properties?: Record<string, unknown>;
-  required?: readonly string[];
-};
-
-function firstKey(schema: SchemaLike | undefined): string | undefined {
-  return Object.keys(schema?.properties ?? {})[0];
-}
-
-function expectIntentFirst(name: string, schema: SchemaLike | undefined): void {
-  expect(`${name}:${firstKey(schema)}`).toBe(`${name}:${INTENT_ARG}`);
-  expect(schema?.required ?? []).not.toContain(INTENT_ARG);
-}
-
-const stubSandbox: CloudflareSandboxRuntime = {
-  exec: () => Promise.reject(new Error('schema-only stub')),
-  readFile: () => Promise.reject(new Error('schema-only stub')),
-  writeFile: () => Promise.reject(new Error('schema-only stub')),
-  mkdir: () => Promise.reject(new Error('schema-only stub')),
-  listFiles: () => Promise.reject(new Error('schema-only stub')),
-  deleteFile: () => Promise.reject(new Error('schema-only stub')),
-};
-
-/**
- * Coverage pin for the tool-intent capability: every native coding tool, on
- * every engine, must emit `intent` as the FIRST schema property (and never
- * require it). Mirrors the `LOCAL_CODING_BUNDLE_NAMES` pin so "did we get
- * them all" is a failing test rather than a review question.
- */
-describe('intent coverage', () => {
-  it('every local bundle tool emits intent as its first schema property', () => {
-    const tools = createLocalCodingTools();
-    expect(tools.map((tool) => tool.name).sort()).toEqual(
-      [...LOCAL_CODING_BUNDLE_NAMES].sort()
-    );
-    for (const tool of tools) {
-      expectIntentFirst(tool.name, tool.schema as SchemaLike);
-    }
-  });
-
-  it('every local registry definition emits intent first', () => {
-    for (const def of createLocalCodingToolDefinitions()) {
-      expectIntentFirst(def.name, def.parameters);
-    }
-  });
-
-  it('every cloudflare bundle tool emits intent first', () => {
-    const tools = createCloudflareCodingTools({ sandbox: stubSandbox });
-    expect(tools.map((tool) => tool.name).sort()).toEqual(
-      [...CLOUDFLARE_CODING_TOOL_NAMES].sort()
-    );
-    for (const tool of tools) {
-      expectIntentFirst(tool.name, tool.schema as SchemaLike);
-    }
-  });
-
-  it('shared execution schemas emit intent first (all engines)', () => {
-    expectIntentFirst('bash_tool', BashExecutionToolSchema);
-    expectIntentFirst('execute_code', CodeExecutionToolSchema);
-    expectIntentFirst(
-      'bash_tool:stateful',
-      buildBashExecutionToolSchema({ statefulSessions: true })
-    );
-    expectIntentFirst(
-      'execute_code:stateful',
-      buildCodeExecutionToolSchema({ statefulSessions: true })
-    );
-    expectIntentFirst(
-      'run_tools_with_code',
-      ProgrammaticToolCallingSchema
-    );
-    expectIntentFirst(
-      'run_tools_with_bash',
-      BashProgrammaticToolCallingSchema
-    );
-  });
-
-  it('read_file, skill, subagent, tool_search, and web_search emit intent first', () => {
-    expectIntentFirst('read_file', ReadFileToolDefinition.parameters);
-    expectIntentFirst('skill', SkillToolDefinition.parameters);
-    expectIntentFirst('subagent', SubagentToolSchema);
-    expectIntentFirst(
-      'subagent:runtime',
-      createSubagentToolDefinition([
-        { type: 'researcher', name: 'Researcher', description: 'Researches' },
-      ]).parameters
-    );
-    expectIntentFirst('tool_search', ToolSearchToolSchema);
-    expectIntentFirst('web_search', WebSearchToolSchema);
-  });
-
-  it('the createSearchTool FACTORY emits intent first (runtime schema, not the static def)', () => {
-    const serperTool = createSearchTool({
-      searchProvider: 'serper',
-      scraperProvider: 'serper',
-      serperApiKey: 'test-key',
-    });
-    expectIntentFirst('web_search:serper', serperTool.schema as SchemaLike);
-    const searxngTool = createSearchTool({
-      searchProvider: 'searxng',
-      scraperProvider: 'serper',
-      serperApiKey: 'test-key',
-      searxngInstanceUrl: 'http://localhost:8080',
-    });
-    expectIntentFirst('web_search:searxng', searxngTool.schema as SchemaLike);
-  });
-});

package/src/tools/__tests__/localToolNames.test.ts

@@ -1,75 +0,0 @@
-import { describe, it, expect } from '@jest/globals';
-import {
-  createLocalCodingTools,
-  createLocalCodingToolDefinitions,
-  LocalEditFileToolName,
-  LocalGlobSearchToolName,
-  LocalGrepSearchToolName,
-  LocalListDirectoryToolName,
-  LocalWriteFileToolName,
-} from '../local/LocalCodingTools';
-import {
-  Constants,
-  LOCAL_CODING_BUNDLE_NAMES,
-  LOCAL_CODING_TOOL_NAMES,
-} from '@/common';
-import { CompileCheckToolName } from '../local/CompileCheckTool';
-
-/**
- * Pins the tool name surface so a typo upstream — in factories,
- * registry definitions, the policy hook, or LibreChat's icon map —
- * gets caught at build time. The wire-level strings have to match
- * what consumer UIs already special-case (`bash_tool`, `read_file`,
- * `execute_code`, `run_tools_with_code`) and what they may add icons
- * for next (write_file, edit_file, grep_search, glob_search,
- * list_directory, compile_check).
- */
-describe('local coding tool names', () => {
-  it('the per-file Local*ToolName aliases point at canonical Constants', () => {
-    expect(LocalWriteFileToolName).toBe(Constants.WRITE_FILE);
-    expect(LocalEditFileToolName).toBe(Constants.EDIT_FILE);
-    expect(LocalGrepSearchToolName).toBe(Constants.GREP_SEARCH);
-    expect(LocalGlobSearchToolName).toBe(Constants.GLOB_SEARCH);
-    expect(LocalListDirectoryToolName).toBe(Constants.LIST_DIRECTORY);
-    expect(CompileCheckToolName).toBe(Constants.COMPILE_CHECK);
-  });
-
-  it('canonical strings match what consumer UIs (e.g. LibreChat icon map) recognise', () => {
-    expect(Constants.READ_FILE).toBe('read_file');
-    expect(Constants.WRITE_FILE).toBe('write_file');
-    expect(Constants.EDIT_FILE).toBe('edit_file');
-    expect(Constants.GREP_SEARCH).toBe('grep_search');
-    expect(Constants.GLOB_SEARCH).toBe('glob_search');
-    expect(Constants.LIST_DIRECTORY).toBe('list_directory');
-    expect(Constants.COMPILE_CHECK).toBe('compile_check');
-    expect(Constants.BASH_TOOL).toBe('bash_tool');
-    expect(Constants.EXECUTE_CODE).toBe('execute_code');
-    expect(Constants.PROGRAMMATIC_TOOL_CALLING).toBe('run_tools_with_code');
-    expect(Constants.BASH_PROGRAMMATIC_TOOL_CALLING).toBe(
-      'run_tools_with_bash'
-    );
-  });
-
-  it('LOCAL_CODING_BUNDLE_NAMES matches every name the bundle ships', () => {
-    const tools = createLocalCodingTools();
-    const bundleNames = tools.map((t) => t.name).sort();
-    const advertisedNames = [...LOCAL_CODING_BUNDLE_NAMES].sort();
-    expect(bundleNames).toEqual(advertisedNames);
-  });
-
-  it('LOCAL_CODING_TOOL_NAMES matches the registry-definitions list (local-only tools)', () => {
-    const defs = createLocalCodingToolDefinitions();
-    const defNames = defs.map((d) => d.name).sort();
-    const advertisedNames = [...LOCAL_CODING_TOOL_NAMES].sort();
-    expect(defNames).toEqual(advertisedNames);
-  });
-
-  it('LOCAL_CODING_BUNDLE_NAMES is a strict superset of LOCAL_CODING_TOOL_NAMES', () => {
-    for (const name of LOCAL_CODING_TOOL_NAMES) {
-      expect(LOCAL_CODING_BUNDLE_NAMES).toContain(name);
-    }
-    expect(LOCAL_CODING_BUNDLE_NAMES.length).toBeGreaterThan(
-      LOCAL_CODING_TOOL_NAMES.length
-    );
-  });
-});