@librechat/agents 3.1.77-dev.1 → 3.1.78-dev.0

package/src/tools/local/__tests__/editStrategies.test.ts

@@ -0,0 +1,134 @@
+import { describe, it, expect } from '@jest/globals';
+import { applyEdit, locateEdit } from '../editStrategies';
+
+/**
+ * Focused unit tests for the fuzzy edit-matching chain. The chain is
+ * what determines whether `edit_file` succeeds or silently corrupts a
+ * file when the model's `oldString` doesn't byte-match the on-disk
+ * content (different indentation, trailing whitespace, etc.). Pinning
+ * the strategy boundaries here so a regression in any one strategy
+ * surfaces fast.
+ *
+ * Order of strategies (defined in editStrategies.ts):
+ *   1. exact
+ *   2. line-trimmed
+ *   3. whitespace-normalized
+ *   4. indentation-flexible
+ */
+
+describe('editStrategies › locateEdit', () => {
+  it('returns an exact-strategy match for a literal byte-equal substring', () => {
+    const source = 'one\ntwo\nthree\n';
+    const m = locateEdit(source, 'two');
+    expect(m).not.toBeNull();
+    expect(m?.strategy).toBe('exact');
+    expect(applyEdit(source, m!, '2')).toBe('one\n2\nthree\n');
+  });
+
+  it('matches at the very start of the source', () => {
+    const source = 'first\nsecond\n';
+    const m = locateEdit(source, 'first');
+    expect(m).not.toBeNull();
+    expect(m?.strategy).toBe('exact');
+    expect(m?.start).toBe(0);
+  });
+
+  it('matches at the very end of the source (no trailing newline)', () => {
+    const source = 'a\nb\nlast';
+    const m = locateEdit(source, 'last');
+    expect(m).not.toBeNull();
+    expect(m?.strategy).toBe('exact');
+    expect(applyEdit(source, m!, 'LAST')).toBe('a\nb\nLAST');
+  });
+
+  it('falls back to line-trimmed when the model lost trailing whitespace inside a multi-line needle', () => {
+    // Source has trailing tab on the second line; needle has none.
+    // Multi-line needle so the exact strategy can't match (the source
+    // line literally has the tab). Line-trimmed compares trimEnd vs
+    // trimEnd and lets it through.
+    const source = 'fn foo() {\n  return 42\t\n}\n';
+    const m = locateEdit(source, 'fn foo() {\n  return 42\n}');
+    expect(m).not.toBeNull();
+    expect(['line-trimmed', 'whitespace-normalized']).toContain(m?.strategy);
+  });
+
+  it('falls back to whitespace-normalized when interior whitespace differs', () => {
+    // Source uses tabs, needle uses spaces.
+    const source = 'if\t(x)\t{\n\treturn\ty;\n}';
+    const m = locateEdit(source, 'if (x) {\n  return y;\n}');
+    expect(m).not.toBeNull();
+    expect(['whitespace-normalized', 'line-trimmed', 'exact']).toContain(
+      m?.strategy
+    );
+  });
+
+  it('falls back to indentation-flexible when block leading indent differs', () => {
+    // Source is indented by 4 spaces, needle by 2 — semantically the
+    // same block, lexically different indent.
+    const source = '    function go() {\n        return 1;\n    }\n';
+    const m = locateEdit(source, '  function go() {\n    return 1;\n  }');
+    expect(m).not.toBeNull();
+    // Any of the looser strategies could legitimately win here; what
+    // matters is that the chain finds *a* match instead of giving up.
+    expect(m?.strategy).not.toBe('exact');
+  });
+
+  it('returns null when nothing in the chain matches', () => {
+    const source = 'alpha\nbeta\ngamma\n';
+    const m = locateEdit(source, 'this string is nowhere in the source');
+    expect(m).toBeNull();
+  });
+
+  it('rejects exact-strategy match when oldString appears more than once (ambiguous)', () => {
+    // The exact strategy explicitly returns null on >1 hit so an
+    // ambiguous edit can't silently pick the wrong span. Pinning
+    // because the audit-of-audit (follow-up F2) flagged that this
+    // boundary was claimed in the commit message but not actually
+    // covered by a test.
+    //
+    // (Whether the *looser* strategies — line-trimmed,
+    // whitespace-normalized, indentation-flexible — should also fail
+    // closed on multi-match is a separate design call: today they
+    // reject duplicate matches at their OWN granularity but the
+    // chain may then fall through to a strategy that picks one
+    // unambiguously. Out of scope for this test.)
+    const source = 'foo bar\nfoo bar\nbaz';
+    expect(locateEdit(source, 'foo bar')).toBeNull();
+  });
+
+  it('returns null on empty oldString (no anchor to locate)', () => {
+    const source = 'a\nb\n';
+    const m = locateEdit(source, '');
+    expect(m).toBeNull();
+  });
+
+  it('handles multi-line needles spanning a blank line', () => {
+    const source = 'before\n\nafter\n';
+    const m = locateEdit(source, 'before\n\nafter');
+    expect(m).not.toBeNull();
+    expect(m?.strategy).toBe('exact');
+  });
+
+  it('handles unicode content (emoji, combining characters)', () => {
+    const source = 'header\n  // ✅ done — café\nfooter\n';
+    const m = locateEdit(source, '  // ✅ done — café');
+    expect(m).not.toBeNull();
+    expect(m?.strategy).toBe('exact');
+  });
+});
+
+describe('editStrategies › applyEdit', () => {
+  it('produces the new source by splicing newString into the matched span', () => {
+    const source = 'aaa BAR ccc';
+    const m = locateEdit(source, 'BAR');
+    expect(m).not.toBeNull();
+    expect(applyEdit(source, m!, 'baz')).toBe('aaa baz ccc');
+  });
+
+  it('is a no-op when newString equals the matched span', () => {
+    const source = 'x y z';
+    const m = locateEdit(source, 'y');
+    expect(m).not.toBeNull();
+    expect(applyEdit(source, m!, 'y')).toBe('x y z');
+  });
+});

package/src/tools/local/attachments.ts

@@ -0,0 +1,251 @@
+/**
+ * Detects whether a file on disk is an LLM-renderable attachment
+ * (image / PDF) and produces the LangChain `MessageContentComplex[]`
+ * payload a `ToolMessage` needs to actually surface those bytes to
+ * the vision-capable model.
+ *
+ * Same approach as LibreChat's `api/server/utils/files.js`: sniff the
+ * magic bytes (NOT the extension) so a mislabelled `.png` that's
+ * really a binary blob doesn't get embedded as an image. Inlined for
+ * the five formats we actually care about (PNG / JPEG / GIF / WebP /
+ * PDF) instead of pulling the ESM-only `file-type` package — keeps
+ * the test setup CJS-clean.
+ *
+ * Provider compatibility:
+ *   - Anthropic: tool_result content arrays accept `image` / `image_url`
+ *     blocks; LangChain's anthropic adapter at
+ *     `node_modules/@langchain/anthropic/dist/utils/message_inputs.js`
+ *     converts them to native `image` source blocks.
+ *   - OpenAI Chat Completions: image_url blocks in tool messages are
+ *     accepted on vision-capable models.
+ *   - OpenAI Responses API: tool messages are flattened to plain text;
+ *     image_url blocks degrade to a JSON description (still useful as
+ *     a textual hint to the model).
+ *   - Google: image blocks in tool responses are accepted on Gemini
+ *     vision models.
+ *
+ * Configuration:
+ *   - `local.attachReadAttachments` (default `'images-only'`) controls
+ *     which file kinds are returned as inline attachments. Other kinds
+ *     fall through to the existing binary-stub path.
+ *   - `local.maxAttachmentBytes` (default 5 MB) caps the pre-encoding
+ *     size; oversize attachments degrade to a stub describing the
+ *     refusal so the model isn't surprised.
+ */
+
+import { open as fsOpen, readFile as fsReadFile } from 'fs/promises';
+import type { WorkspaceFS } from './workspaceFS';
+
+/**
+ * Magic-byte sniff for the small set of image/PDF formats we care
+ * about. We avoided pulling in `file-type` (ESM-only, awkward under
+ * ts-jest) since the universe of attachments we want to embed is
+ * tiny: PNG, JPEG, GIF, WebP, PDF. All have well-known signatures in
+ * the first 12 bytes.
+ *
+ * Returns `undefined` on no match — caller treats as text/unknown.
+ */
+function sniffMime(buffer: Buffer): string | undefined {
+  if (buffer.length < 4) return undefined;
+  // PNG: 89 50 4E 47 0D 0A 1A 0A
+  if (
+    buffer.length >= 8 &&
+    buffer[0] === 0x89 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x4e &&
+    buffer[3] === 0x47 &&
+    buffer[4] === 0x0d &&
+    buffer[5] === 0x0a &&
+    buffer[6] === 0x1a &&
+    buffer[7] === 0x0a
+  ) {
+    return 'image/png';
+  }
+  // JPEG: FF D8 FF
+  if (buffer[0] === 0xff && buffer[1] === 0xd8 && buffer[2] === 0xff) {
+    return 'image/jpeg';
+  }
+  // GIF: "GIF87a" or "GIF89a"
+  if (
+    buffer.length >= 6 &&
+    buffer[0] === 0x47 &&
+    buffer[1] === 0x49 &&
+    buffer[2] === 0x46 &&
+    buffer[3] === 0x38 &&
+    (buffer[4] === 0x37 || buffer[4] === 0x39) &&
+    buffer[5] === 0x61
+  ) {
+    return 'image/gif';
+  }
+  // WebP: "RIFF" .... "WEBP"
+  if (
+    buffer.length >= 12 &&
+    buffer[0] === 0x52 &&
+    buffer[1] === 0x49 &&
+    buffer[2] === 0x46 &&
+    buffer[3] === 0x46 &&
+    buffer[8] === 0x57 &&
+    buffer[9] === 0x45 &&
+    buffer[10] === 0x42 &&
+    buffer[11] === 0x50
+  ) {
+    return 'image/webp';
+  }
+  // PDF: "%PDF-"
+  if (
+    buffer.length >= 5 &&
+    buffer[0] === 0x25 &&
+    buffer[1] === 0x50 &&
+    buffer[2] === 0x44 &&
+    buffer[3] === 0x46 &&
+    buffer[4] === 0x2d
+  ) {
+    return 'application/pdf';
+  }
+  return undefined;
+}
+
+const SUPPORTED_IMAGE_MIMES = new Set<string>([
+  'image/png',
+  'image/jpeg',
+  'image/gif',
+  'image/webp',
+]);
+
+/** Mime types that get returned to the model as inline attachments. */
+const SUPPORTED_ATTACHMENT_MIMES = new Set<string>([
+  ...SUPPORTED_IMAGE_MIMES,
+  'application/pdf',
+]);
+
+export type AttachmentMode = 'images-only' | 'images-and-pdf' | 'off';
+
+export type Attachment =
+  | {
+      kind: 'image';
+      mime: string;
+      bytes: number;
+      dataUrl: string;
+    }
+  | {
+      kind: 'pdf';
+      mime: 'application/pdf';
+      bytes: number;
+      dataUrl: string;
+    }
+  | {
+      kind: 'binary';
+      mime: string;
+      bytes: number;
+    }
+  | {
+      kind: 'oversize';
+      mime: string;
+      bytes: number;
+      maxBytes: number;
+    }
+  | {
+      kind: 'text-or-unknown';
+      bytes: number;
+    };
+
+export async function classifyAttachment(args: {
+  path: string;
+  bytes: number;
+  mode: AttachmentMode;
+  maxBytes: number;
+  /**
+   * WorkspaceFS to route I/O through — defaults to host fs/promises
+   * for backward compat. Manual review (finding F): without this
+   * routing, custom/remote FS implementations could either fail to
+   * embed valid attachments or accidentally read a host path with
+   * the same absolute name (since `read_file` itself does go through
+   * the configured WorkspaceFS).
+   */
+  fs?: WorkspaceFS;
+}): Promise<Attachment> {
+  if (args.bytes === 0) {
+    return { kind: 'text-or-unknown', bytes: 0 };
+  }
+
+  // MIME sniffing only needs the first 12 bytes — read just the
+  // header so a 9 MB PNG (under the 10 MB read cap, over the 5 MB
+  // attachment cap) doesn't pull the whole buffer into memory before
+  // we discover it's oversize. Full read happens only when we're
+  // about to base64-embed.
+  const open = args.fs?.open ?? fsOpen;
+  const handle = await open(args.path, 'r');
+  const header = Buffer.alloc(12);
+  let mime: string | undefined;
+  try {
+    await handle.read(header, 0, 12, 0);
+    mime = sniffMime(header);
+  } finally {
+    await handle.close();
+  }
+
+  if (mime == null) {
+    return { kind: 'text-or-unknown', bytes: args.bytes };
+  }
+
+  const wantsImage =
+    args.mode === 'images-only' || args.mode === 'images-and-pdf';
+  const wantsPdf = args.mode === 'images-and-pdf';
+
+  const isImage = wantsImage && SUPPORTED_IMAGE_MIMES.has(mime);
+  const isPdf = wantsPdf && mime === 'application/pdf';
+
+  if (!isImage && !isPdf) {
+    // Both branches returned identical values pre-fix (audit-of-audit
+    // finding #3). The SUPPORTED_ATTACHMENT_MIMES check was dead code —
+    // collapsing to a single return.
+    return { kind: 'binary', mime, bytes: args.bytes };
+  }
+
+  if (args.bytes > args.maxBytes) {
+    return {
+      kind: 'oversize',
+      mime,
+      bytes: args.bytes,
+      maxBytes: args.maxBytes,
+    };
+  }
+
+  const readFile = args.fs?.readFile ?? fsReadFile;
+  const buffer = (await readFile(args.path)) as Buffer;
+  const base64 = buffer.toString('base64');
+  const dataUrl = `data:${mime};base64,${base64}`;
+
+  if (isImage) {
+    return { kind: 'image', mime, bytes: args.bytes, dataUrl };
+  }
+  return {
+    kind: 'pdf',
+    mime: 'application/pdf' as const,
+    bytes: args.bytes,
+    dataUrl,
+  };
+}
+
+/** Build the LangChain content array for an image attachment. */
+export function imageAttachmentContent(
+  path: string,
+  attachment: Extract<Attachment, { kind: 'image' }>
+): Array<{
+  type: 'text' | 'image_url';
+  text?: string;
+  image_url?: { url: string };
+}> {
+  return [
+    {
+      type: 'text',
+      text:
+        `Read ${path} (${attachment.mime}, ${attachment.bytes} bytes). ` +
+        'The image is attached below for vision-capable models.',
+    },
+    {
+      type: 'image_url',
+      image_url: { url: attachment.dataUrl },
+    },
+  ];
+}

package/src/tools/local/bashAst.ts

@@ -0,0 +1,151 @@
+import type * as t from '@/types';
+
+export type BashAstFinding = {
+  code: string;
+  message: string;
+  severity: 'warn' | 'deny';
+};
+
+/**
+ * Categorical-hazard checks layered on top of the existing dangerous-
+ * command regex set. These match command-shape signatures that
+ * claude-code's tree-sitter AST validator catches via categorical
+ * deny-lists (command substitution, zsh-only privileged commands,
+ * /proc/<pid>/environ access, IFS injection, etc.).
+ *
+ * This is *not* a real AST parser. It is a deliberately conservative
+ * heuristic pass intended for the local engine's `bashAst: 'auto' |
+ * 'strict'` modes; a future PR can swap in a true tree-sitter-bash
+ * pass behind the same config field without changing the public API.
+ *
+ * `runBashAstChecks` runs on the *quote-stripped* command (so quoted
+ * strings inside the script don't generate false positives) and
+ * returns one finding per matched category.
+ */
+
+const COMMAND_SUBSTITUTION_PATTERNS: { code: string; rx: RegExp }[] = [
+  { code: 'cmd-subst-dollar-paren', rx: /\$\(/ },
+  { code: 'cmd-subst-backtick', rx: /`[^`]*`/ },
+  { code: 'cmd-subst-process-sub', rx: /[<>]\(/ },
+  { code: 'cmd-subst-zsh-eq', rx: /(?:^|\s)=[A-Za-z_]/ },
+];
+
+const ZSH_DANGEROUS_BUILTINS = [
+  'zmodload',
+  'emulate',
+  'sysopen',
+  'sysread',
+  'syswrite',
+  'ztcp',
+  'zsocket',
+  'zf_rm',
+  'zselect',
+];
+
+const STRICT_DENIED_BUILTINS = [
+  'eval',
+  'exec',
+];
+
+function rxForBuiltin(name: string): RegExp {
+  return new RegExp(`\\b${name}\\b`);
+}
+
+const PROC_ENVIRON_RX = /\/proc\/(?:\d+|self|\$[A-Za-z_])\/environ\b/;
+const IFS_INJECTION_RX = /\bIFS\s*=/;
+const HEX_ESCAPE_OBFUSCATION_RX = /\\x[0-9a-fA-F]{2}/;
+const SOURCE_FROM_VAR_RX = /(?:^|\s)(?:source|\.)\s+["']?\$[A-Za-z_]/;
+
+export function runBashAstChecks(
+  command: string,
+  mode: t.LocalBashAstMode = 'off'
+): BashAstFinding[] {
+  if (mode === 'off') {
+    return [];
+  }
+  const findings: BashAstFinding[] = [];
+  const strict = mode === 'strict';
+
+  for (const { code, rx } of COMMAND_SUBSTITUTION_PATTERNS) {
+    if (rx.test(command)) {
+      findings.push({
+        code,
+        message:
+          'Command substitution can mask intent and exfiltrate variables; not allowed under bashAst.',
+        severity: strict ? 'deny' : 'warn',
+      });
+    }
+  }
+
+  for (const builtin of ZSH_DANGEROUS_BUILTINS) {
+    if (rxForBuiltin(builtin).test(command)) {
+      findings.push({
+        code: `zsh-builtin-${builtin}`,
+        message: `Zsh privileged builtin "${builtin}" is denied.`,
+        severity: 'deny',
+      });
+    }
+  }
+
+  if (PROC_ENVIRON_RX.test(command)) {
+    findings.push({
+      code: 'proc-environ-read',
+      message: 'Reads from /proc/<pid>/environ are denied — leaks host secrets.',
+      severity: 'deny',
+    });
+  }
+
+  if (IFS_INJECTION_RX.test(command)) {
+    findings.push({
+      code: 'ifs-injection',
+      message: 'Inline IFS reassignment is suspicious; review the command.',
+      severity: strict ? 'deny' : 'warn',
+    });
+  }
+
+  if (HEX_ESCAPE_OBFUSCATION_RX.test(command)) {
+    findings.push({
+      code: 'hex-escape',
+      message: 'Hex-escaped bytes (\\xNN) often hide intent; review the command.',
+      severity: strict ? 'deny' : 'warn',
+    });
+  }
+
+  if (SOURCE_FROM_VAR_RX.test(command)) {
+    findings.push({
+      code: 'source-from-variable',
+      message: 'Sourcing a script from an unbound variable is denied.',
+      severity: 'deny',
+    });
+  }
+
+  if (strict) {
+    for (const builtin of STRICT_DENIED_BUILTINS) {
+      if (rxForBuiltin(builtin).test(command)) {
+        findings.push({
+          code: `strict-${builtin}`,
+          message: `In strict mode, "${builtin}" is denied.`,
+          severity: 'deny',
+        });
+      }
+    }
+  }
+
+  return findings;
+}
+
+export function bashAstFindingsToErrors(
+  findings: BashAstFinding[]
+): { errors: string[]; warnings: string[] } {
+  const errors: string[] = [];
+  const warnings: string[] = [];
+  for (const f of findings) {
+    const formatted = `[bashAst:${f.code}] ${f.message}`;
+    if (f.severity === 'deny') {
+      errors.push(formatted);
+    } else {
+      warnings.push(formatted);
+    }
+  }
+  return { errors, warnings };
+}