@librechat/agents 3.1.77 → 3.1.78-dev.0

package/src/scripts/local_engine_hooks.ts

@@ -0,0 +1,226 @@
+/**
+ * src/scripts/local_engine_hooks.ts
+ *
+ * Live demonstration that PreToolUse / PostToolUse hooks now fire on
+ * the direct-path tools the local engine registers. Wires up:
+ *
+ *   - a `createToolPolicyHook` that DENIES `write_file` and `edit_file`
+ *     while allowing reads, `bash`, and the search tools, and
+ *   - an explicit `PostToolUse` hook that prefixes every successful
+ *     tool result with a "[reviewed]" tag so you can confirm it ran
+ *     against the in-process tools.
+ *
+ * The script asks the model to (a) write a file, (b) read it back. Step
+ * (a) should be blocked with a `Blocked: ...` ToolMessage and a
+ * `PermissionDenied` hook fire; step (b) should succeed with the
+ * "[reviewed]" prefix injected by `PostToolUse`.
+ *
+ * Run with: `npm run local:hooks`
+ */
+import { config } from 'dotenv';
+config();
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { HookRegistry, createToolPolicyHook } from '@/hooks';
+import type {
+  PostToolUseHookOutput,
+  PermissionDeniedHookOutput,
+} from '@/hooks';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { GraphEvents } from '@/common';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+async function main(): Promise<void> {
+  const { userName, provider } = await getArgs();
+  const cwd = await mkdtemp(join(tmpdir(), 'lc-local-hooks-'));
+  console.log(`[local_engine_hooks] workspace: ${cwd}`);
+
+  // Seed a file so read_file has something interesting to return.
+  await writeFile(
+    join(cwd, 'allowed.txt'),
+    'this is a pre-existing file the agent is allowed to read\n',
+    'utf8'
+  );
+
+  // --- HOOK SETUP ---
+  const denyEvents: { tool: string; reason?: string }[] = [];
+  const reviewedTools = new Set<string>();
+
+  const hookRegistry = new HookRegistry();
+
+  // PreToolUse policy: deny mutations, allow everything else.
+  hookRegistry.register('PreToolUse', {
+    hooks: [
+      createToolPolicyHook({
+        mode: 'bypass',
+        deny: ['write_file', 'edit_file'],
+        reason: 'this script blocks {tool} to demonstrate direct-path hooks',
+      }),
+    ],
+  });
+
+  // PostToolUse: tag successful results so we can see the hook running.
+  hookRegistry.register('PostToolUse', {
+    hooks: [
+      async ({
+        toolName,
+        toolOutput,
+      }): Promise<PostToolUseHookOutput> => {
+        reviewedTools.add(toolName);
+        const text =
+          typeof toolOutput === 'string'
+            ? toolOutput
+            : JSON.stringify(toolOutput);
+        return { updatedOutput: `[reviewed] ${text}` };
+      },
+    ],
+  });
+
+  // PermissionDenied: observational sink so we can prove the hook fired.
+  hookRegistry.register('PermissionDenied', {
+    hooks: [
+      async ({
+        toolName,
+        reason,
+      }): Promise<PermissionDeniedHookOutput> => {
+        denyEvents.push({ tool: toolName, reason });
+        return {};
+      },
+    ],
+  });
+
+  // --- STREAM HANDLERS ---
+  const { contentParts, aggregateContent } = createContentAggregator();
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    // Forward ON_RUN_STEP so the aggregator's stepMap is seeded
+    // before ON_RUN_STEP_COMPLETED arrives (issue #142).
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData): void => {
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        const cast = data as unknown as { result: t.ToolEndEvent };
+        const tc = (cast.result as { tool_call?: { name?: string } } | undefined)
+          ?.tool_call;
+        console.log(`====== ON_RUN_STEP_COMPLETED tool=${tc?.name ?? '?'} ======`);
+        aggregateContent({ event, data: cast });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (_event: string, data: t.StreamEventData): void => {
+        const obj = data as unknown as { name?: string; input?: unknown };
+        console.log(
+          `====== TOOL_START tool=${obj.name ?? '?'} input=${JSON.stringify(
+            obj.input
+          )} ======`
+        );
+      },
+    },
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  const runConfig: t.RunConfig = {
+    runId: 'local-engine-hooks-1',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      instructions:
+        'You are a coding assistant. The host has loaded a permissions policy. ' +
+        'When a tool call is denied you will see a ToolMessage starting with ' +
+        '`Blocked:` — DO NOT retry the same denied tool. If a write is denied, ' +
+        'just acknowledge the denial and continue with operations that are allowed.',
+    },
+    toolExecution: {
+      engine: 'local',
+      local: { cwd, timeoutMs: 30_000 },
+    },
+    hooks: hookRegistry,
+    returnContent: true,
+    skipCleanup: true,
+    customHandlers,
+  };
+  const run = await Run.create<t.IState>(runConfig);
+
+  const streamConfig = {
+    configurable: { provider, thread_id: 'local-engine-hooks-thread-1' },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  const userMessage = new HumanMessage(
+    `Hi ${userName}. Please do these two things in order:\n\n` +
+      '1. Use `write_file` to create `blocked.txt` with the content "should never land".\n' +
+      '2. Use `read_file` on `allowed.txt` and tell me what is inside.\n\n' +
+      'Then report whether each step succeeded.'
+  );
+  conversationHistory.push(userMessage);
+  console.log('====== USER ======\n' + userMessage.content + '\n');
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const finalMessages = run.getRunMessages();
+  if (finalMessages) {
+    conversationHistory.push(...finalMessages);
+  }
+
+  console.log('\n====== FINAL CONTENT PARTS ======');
+  console.dir(contentParts, { depth: null });
+
+  console.log('\n====== HOOK OBSERVATIONS ======');
+  console.log(
+    `PermissionDenied fired ${denyEvents.length} time(s):`,
+    denyEvents
+  );
+  console.log(
+    `PostToolUse saw tools: ${[...reviewedTools].join(', ') || '<none>'}`
+  );
+
+  // The deny-target file must NOT exist.
+  const fs = await import('fs/promises');
+  const exists = await fs
+    .stat(join(cwd, 'blocked.txt'))
+    .then(() => true)
+    .catch(() => false);
+  console.log(
+    `blocked.txt landed on disk? ${exists} ${
+      exists ? '(BUG)' : '(expected: false)'
+    }`
+  );
+
+  await rm(cwd, { recursive: true, force: true });
+}
+
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/scripts/local_engine_image.ts

@@ -0,0 +1,201 @@
+/**
+ * src/scripts/local_engine_image.ts
+ *
+ * Live demo of the local read_file tool returning an image as an
+ * inline `MessageContentComplex[]` attachment when
+ * `local.attachReadAttachments: 'images-only'` is set. We seed a tiny
+ * red square PNG into the workspace, ask the agent to read it, and
+ * verify the model receives the image bytes (not just a refusal stub).
+ *
+ * Best run with a vision-capable provider, e.g.:
+ *   npm run local:image -- --provider anthropic
+ */
+import { config } from 'dotenv';
+config();
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { copyFile, mkdtemp, rm, writeFile } from 'fs/promises';
+import { HumanMessage, ToolMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { GraphEvents } from '@/common';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+// Canonical 1x1 transparent PNG fallback if the system PNG isn't readable.
+const TINY_PNG_HEX =
+  '89504e470d0a1a0a0000000d49484452000000010000000108060000001f15' +
+  'c4890000000a49444154789c63000100000005000165be7e6e0000000049' +
+  '454e44ae426082';
+
+const SAMPLE_PNG_PATHS = [
+  '/System/Library/CoreServices/Certificate Assistant.app/Contents/Resources/droppedImage.png',
+  '/System/Library/CoreServices/Certificate Assistant.app/Contents/Resources/shapeimage_1.png',
+  '/System/Library/CoreServices/BluetoothUIServer.app/Contents/Resources/handoff.png',
+];
+
+async function main(): Promise<void> {
+  const { userName, provider } = await getArgs();
+  const cwd = await mkdtemp(join(tmpdir(), 'lc-local-image-'));
+  console.log(`[local_engine_image] workspace: ${cwd}`);
+
+  const pngPath = join(cwd, 'sample.png');
+  let copied = false;
+  for (const sample of SAMPLE_PNG_PATHS) {
+    try {
+      await copyFile(sample, pngPath);
+      copied = true;
+      break;
+    } catch {
+      // try next
+    }
+  }
+  if (!copied) {
+    await writeFile(pngPath, Buffer.from(TINY_PNG_HEX, 'hex'));
+  }
+  console.log(`[local_engine_image] wrote ${pngPath} (real-png=${copied})`);
+
+  const { aggregateContent } = createContentAggregator();
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    // Forward ON_RUN_STEP so the aggregator's stepMap is seeded
+    // before ON_RUN_STEP_COMPLETED arrives (issue #142).
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData): void => {
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({
+          event,
+          data: data as unknown as { result: t.ToolEndEvent },
+        });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (_event: string, data: t.StreamEventData): void => {
+        const obj = data as unknown as { name?: string; input?: unknown };
+        console.log(
+          `====== TOOL_START tool=${obj.name ?? '?'} input=${JSON.stringify(
+            obj.input
+          )} ======`
+        );
+      },
+    },
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  const runConfig: t.RunConfig = {
+    runId: 'local-engine-image-1',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      instructions:
+        `You are ${userName}'s assistant. When asked to inspect a file, ` +
+        'use `read_file`. The host has enabled inline image attachments, so ' +
+        'reading an image will deliver the actual image bytes to your vision ' +
+        'context. Describe the image you see.',
+    },
+    toolExecution: {
+      engine: 'local',
+      local: {
+        cwd,
+        attachReadAttachments: 'images-only',
+        timeoutMs: 30_000,
+      },
+    },
+    returnContent: true,
+    skipCleanup: true,
+    customHandlers,
+  };
+  const run = await Run.create<t.IState>(runConfig);
+
+  const streamConfig = {
+    configurable: { provider, thread_id: 'local-engine-image-thread-1' },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  const userMessage = new HumanMessage(
+    'Please call `read_file` on `sample.png` (in the working directory) and ' +
+      'then briefly describe what the image shows.'
+  );
+  conversationHistory.push(userMessage);
+  console.log('====== USER ======\n' + userMessage.content + '\n');
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const finalMessages = run.getRunMessages();
+  if (finalMessages) {
+    conversationHistory.push(...finalMessages);
+  }
+
+  console.log('\n====== TOOL MESSAGES IN HISTORY ======');
+  let imageBlockSeen = false;
+  for (const msg of conversationHistory) {
+    if (msg instanceof ToolMessage) {
+      const isArray = Array.isArray(msg.content);
+      const blocks = isArray
+        ? (msg.content as Array<{ type?: string; image_url?: { url?: string } }>)
+        : [];
+      const types = blocks.map((b) => b.type ?? '?').join(',');
+      const url = blocks.find((b) => b.type === 'image_url')?.image_url?.url;
+      console.log(
+        `- ToolMessage(name=${msg.name}, content=${
+          isArray ? `[${types}]` : typeof msg.content
+        }${url ? ` url=${url.slice(0, 40)}…` : ''})`
+      );
+      if (isArray && blocks.some((b) => b.type === 'image_url')) {
+        imageBlockSeen = true;
+      }
+    }
+  }
+  console.log(
+    `\nImage attachment landed in tool result: ${imageBlockSeen} ${
+      imageBlockSeen ? '✔' : '✖'
+    }`
+  );
+
+  console.log('\n====== ASSISTANT FINAL TEXT ======');
+  const lastAssistant = [...conversationHistory]
+    .reverse()
+    .find((m) => m._getType() === 'ai');
+  if (lastAssistant) {
+    const c = lastAssistant.content;
+    console.log(
+      typeof c === 'string'
+        ? c
+        : Array.isArray(c)
+          ? c
+            .map((b) => ('text' in b ? b.text : `<${b.type}>`))
+            .join(' ')
+          : JSON.stringify(c)
+    );
+  }
+
+  if (!imageBlockSeen) {
+    process.exitCode = 1;
+  }
+  await rm(cwd, { recursive: true, force: true });
+}
+
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});

package/src/scripts/local_engine_ptc.ts

@@ -0,0 +1,151 @@
+/**
+ * src/scripts/local_engine_ptc.ts
+ *
+ * Live exercise of the local engine's programmatic tool calling. Asks
+ * the model to use `run_tools_with_code` (Python) to do a multi-step
+ * coding workflow that calls `write_file`, `read_file`, and
+ * `edit_file` from inside a single Python program. The local engine
+ * stands up an in-process loopback HTTP bridge guarded by a per-Run
+ * bearer token (verified via `crypto.timingSafeEqual`), and the
+ * generated Python sends `x-librechat-bridge-token` on every call.
+ *
+ * Run with: `npm run local:ptc`
+ */
+import { config } from 'dotenv';
+config();
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdtemp, readdir, readFile, rm } from 'fs/promises';
+import { HumanMessage } from '@langchain/core/messages';
+import type { BaseMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler, createContentAggregator } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { GraphEvents } from '@/common';
+import { Run } from '@/run';
+
+const conversationHistory: BaseMessage[] = [];
+
+async function main(): Promise<void> {
+  const { userName, provider } = await getArgs();
+  const cwd = await mkdtemp(join(tmpdir(), 'lc-local-ptc-'));
+  console.log(`[local_engine_ptc] workspace: ${cwd}`);
+
+  const { contentParts, aggregateContent } = createContentAggregator();
+
+  const customHandlers = {
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    // Forward ON_RUN_STEP so the aggregator's stepMap is seeded
+    // before ON_RUN_STEP_COMPLETED arrives (issue #142).
+    [GraphEvents.ON_RUN_STEP]: {
+      handle: (event: GraphEvents.ON_RUN_STEP, data: t.StreamEventData): void => {
+        aggregateContent({ event, data: data as t.RunStep });
+      },
+    },
+    [GraphEvents.ON_RUN_STEP_COMPLETED]: {
+      handle: (
+        event: GraphEvents.ON_RUN_STEP_COMPLETED,
+        data: t.StreamEventData
+      ): void => {
+        console.log('====== ON_RUN_STEP_COMPLETED ======');
+        const cast = data as unknown as { result: t.ToolEndEvent };
+        const tc = (cast.result as { tool_call?: { name?: string } } | undefined)
+          ?.tool_call;
+        console.log(`tool=${tc?.name ?? '<unknown>'}`);
+        aggregateContent({ event, data: cast });
+      },
+    },
+    [GraphEvents.ON_MESSAGE_DELTA]: {
+      handle: (
+        event: GraphEvents.ON_MESSAGE_DELTA,
+        data: t.StreamEventData
+      ): void => {
+        aggregateContent({ event, data: data as t.MessageDeltaEvent });
+      },
+    },
+    [GraphEvents.TOOL_START]: {
+      handle: (_event: string, data: t.StreamEventData): void => {
+        const obj = data as unknown as { name?: string; input?: unknown };
+        console.log(
+          `====== TOOL_START tool=${obj.name ?? '?'} input=${JSON.stringify(
+            obj.input
+          )} ======`
+        );
+      },
+    },
+  };
+
+  const llmConfig = getLLMConfig(provider);
+
+  const runConfig: t.RunConfig = {
+    runId: 'local-engine-ptc-1',
+    graphConfig: {
+      type: 'standard',
+      llmConfig,
+      instructions:
+        'You are a coding assistant. Whenever you need to run multiple file/edit ' +
+        'operations together, prefer the `run_tools_with_code` tool with `lang: "py"` ' +
+        'over making many separate tool calls — it lets you sequence read_file/write_file/' +
+        'edit_file in a single Python program. Always use absolute or workspace-relative paths.',
+    },
+    toolExecution: {
+      engine: 'local',
+      local: { cwd, timeoutMs: 60_000 },
+    },
+    returnContent: true,
+    skipCleanup: true,
+    customHandlers,
+  };
+  const run = await Run.create<t.IState>(runConfig);
+
+  const streamConfig = {
+    configurable: { provider, thread_id: 'local-engine-ptc-thread-1' },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  const userMessage = new HumanMessage(
+    `Hi ${userName}. Use the \`run_tools_with_code\` tool with lang: "py" to do all of the following inside a SINGLE Python program (one tool call):\n\n` +
+      '1. Call `write_file` to create `notes.md` with the contents `# Notes\\n- first item\\n`.\n' +
+      '2. Call `read_file` to read it back.\n' +
+      '3. Call `edit_file` to change `first item` to `FIRST item`.\n' +
+      '4. Call `read_file` again and print the final contents.\n\n' +
+      'Print every intermediate value with `print(...)` so I can see them. Do not make multiple tool calls — everything must happen inside one `run_tools_with_code` invocation. After it returns, summarise what you did in one sentence.'
+  );
+  conversationHistory.push(userMessage);
+  console.log('====== USER ======\n' + userMessage.content + '\n');
+
+  await run.processStream({ messages: conversationHistory }, streamConfig);
+  const finalMessages = run.getRunMessages();
+  if (finalMessages) {
+    conversationHistory.push(...finalMessages);
+  }
+
+  console.log('\n====== FINAL CONTENT PARTS ======');
+  console.dir(contentParts, { depth: null });
+
+  console.log('\n====== WORKSPACE ON DISK ======');
+  const entries = await readdir(cwd, { withFileTypes: true });
+  for (const e of entries) {
+    if (!e.isFile()) continue;
+    const path = join(cwd, e.name);
+    const body = await readFile(path, 'utf8').catch(() => '<binary>');
+    console.log(`--- ${e.name} ---\n${body}\n`);
+  }
+
+  await rm(cwd, { recursive: true, force: true });
+}
+
+process.on('unhandledRejection', (reason) => {
+  console.error('Unhandled Rejection:', reason);
+  process.exit(1);
+});
+
+main().catch((err) => {
+  console.error(err);
+  process.exit(1);
+});