@librechat/agents 3.1.77 → 3.1.78

package/src/scripts/local_engine_workspace.ts

@@ -0,0 +1,258 @@
+/**
+ * src/scripts/local_engine_workspace.ts
+ *
+ * Live demo of the workspace boundary + HITL "ask the user when the
+ * agent wants to leave the workspace" flow.
+ *
+ * Setup:
+ *   - workspace.root  = a temp dir
+ *   - additionalRoots = a sibling temp dir (sim. monorepo)
+ *   - allowReadOutside = true (so the file tool's hard clamp lets the
+ *     hook be the gate)
+ *   - createWorkspacePolicyHook with outsideRead='ask'
+ *   - humanInTheLoop.enabled = true
+ *
+ * The agent is then asked to read three files:
+ *   1. one inside the workspace      → expect: PreToolUse 'allow', tool runs
+ *   2. one inside the additional root → expect: PreToolUse 'allow', tool runs
+ *   3. one truly outside              → expect: PreToolUse 'ask' interrupt
+ *      → script auto-approves on resume → tool runs
+ *
+ * Asserts that the host received the interrupt for case (3) and that
+ * the resume completed cleanly. Verifies the existing HITL machinery
+ * (#134) does the lifting end-to-end with the new policy hook.
+ *
+ * Run with: `npm run local:workspace`
+ */
+import { config } from 'dotenv';
+config();
+import { tmpdir } from 'os';
+import { join } from 'path';
+import { mkdtemp, rm, writeFile } from 'fs/promises';
+import { MemorySaver } from '@langchain/langgraph';
+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 { HookRegistry, createWorkspacePolicyHook } from '@/hooks';
+import { getLLMConfig } from '@/utils/llmConfig';
+import { getArgs } from '@/scripts/args';
+import { GraphEvents, Providers } from '@/common';
+import { Run } from '@/run';
+
+async function main(): Promise<void> {
+  const { userName, provider } = await getArgs();
+  const workspace = await mkdtemp(join(tmpdir(), 'lc-ws-demo-'));
+  const sibling = await mkdtemp(join(tmpdir(), 'lc-ws-extra-'));
+  const outside = await mkdtemp(join(tmpdir(), 'lc-ws-outside-'));
+  console.log(`[ws] workspace root: ${workspace}`);
+  console.log(`[ws] additional root: ${sibling}`);
+  console.log(`[ws] outside root  : ${outside}`);
+
+  await writeFile(join(workspace, 'inside.txt'), 'INSIDE\n', 'utf8');
+  await writeFile(join(sibling, 'sibling.txt'), 'SIBLING\n', 'utf8');
+  await writeFile(join(outside, 'secret.txt'), 'SECRET\n', 'utf8');
+
+  const hookRegistry = new HookRegistry();
+  hookRegistry.register('PreToolUse', {
+    hooks: [
+      createWorkspacePolicyHook({
+        root: workspace,
+        additionalRoots: [sibling],
+        outsideRead: 'ask',
+        outsideWrite: 'ask',
+        reason: 'workspace-policy: {tool} wants outside paths {paths}',
+      }),
+    ],
+  });
+
+  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(Providers.ANTHROPIC);
+  const checkpointer = new MemorySaver();
+  const conversation: BaseMessage[] = [];
+
+  const buildRun = async (): Promise<Run<t.IState>> => {
+    const runConfig: t.RunConfig = {
+      runId: `local-engine-ws-${Date.now()}`,
+      graphConfig: {
+        type: 'standard',
+        llmConfig: { ...llmConfig, promptCache: true },
+        compileOptions: { checkpointer },
+        instructions:
+          `You are ${userName}'s assistant. The host has a workspace policy ` +
+          'on `read_file`. If a read is outside the workspace, the host will ' +
+          'ask the user to approve. After approval, retry the read.',
+      },
+      toolExecution: {
+        engine: 'local',
+        local: {
+          workspace: {
+            root: workspace,
+            additionalRoots: [sibling],
+            allowReadOutside: true,
+          },
+          timeoutMs: 30_000,
+        },
+      },
+      hooks: hookRegistry,
+      humanInTheLoop: { enabled: true },
+      returnContent: true,
+      skipCleanup: true,
+      customHandlers,
+    };
+    return Run.create<t.IState>(runConfig);
+  };
+
+  const threadId = `ws-thread-${Date.now()}`;
+  const streamConfig = {
+    configurable: { provider, thread_id: threadId },
+    streamMode: 'values',
+    version: 'v2' as const,
+  };
+
+  const userMessage = new HumanMessage(
+    `Hi ${userName}. Please call \`read_file\` on each of these in order:\n` +
+      `  1. \`inside.txt\` (relative)\n` +
+      `  2. \`${join(sibling, 'sibling.txt')}\` (sibling root, should be allowed)\n` +
+      `  3. \`${join(outside, 'secret.txt')}\` (outside the workspace)\n\n` +
+      `For each, tell me what's in it. If a call is blocked or asks for approval, just retry it once.`
+  );
+  conversation.push(userMessage);
+  console.log('====== USER ======\n' + userMessage.content + '\n');
+
+  // First run — likely to interrupt on the third read.
+  let run = await buildRun();
+  await run.processStream(
+    { messages: conversation },
+    streamConfig as Parameters<typeof run.processStream>[1]
+  );
+  let finalMessages = run.getRunMessages();
+  if (finalMessages) conversation.push(...finalMessages);
+
+  let interrupt = run.getInterrupt();
+  let resumes = 0;
+  while (interrupt != null && resumes < 4) {
+    resumes++;
+    const payload = interrupt.payload as t.ToolApprovalInterruptPayload;
+    console.log(
+      `\n====== INTERRUPT raised (resume #${resumes}) ======\n` +
+        `payload.action_requests = ${JSON.stringify(
+          payload.action_requests,
+          null,
+          2
+        )}`
+    );
+
+    // Auto-approve every action request.
+    const decisions: t.ToolApprovalDecision[] = payload.action_requests.map(
+      (req) => ({ tool_call_id: req.tool_call_id, type: 'approve' })
+    );
+    console.log(
+      `[ws] auto-approving ${decisions.length} tool call(s) and resuming`
+    );
+
+    run = await buildRun();
+    await run.resume(
+      decisions,
+      streamConfig as Parameters<typeof run.processStream>[1]
+    );
+    finalMessages = run.getRunMessages();
+    if (finalMessages) conversation.push(...finalMessages);
+    interrupt = run.getInterrupt();
+  }
+
+  console.log('\n====== TOOL MESSAGES IN HISTORY ======');
+  let askesObserved = 0;
+  let successesObserved = 0;
+  for (const msg of conversation) {
+    if (msg instanceof ToolMessage) {
+      const head =
+        typeof msg.content === 'string'
+          ? msg.content.slice(0, 200)
+          : JSON.stringify(msg.content).slice(0, 200);
+      console.log(`- ${msg.name} (${msg.status}): ${head.replace(/\n/g, ' ⏎ ')}`);
+      if (msg.status === 'error') askesObserved++;
+      if (msg.status === 'success') successesObserved++;
+    }
+  }
+
+  console.log('\n====== ASSISTANT FINAL TEXT ======');
+  const lastAssistant = [...conversation]
+    .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)
+    );
+  }
+
+  console.log('\n====== ASSERTIONS ======');
+  console.log(`HITL interrupts handled: ${resumes}`);
+  console.log(`successful tool messages: ${successesObserved}`);
+  if (resumes === 0) {
+    console.error('[ws] expected at least one HITL interrupt; got 0');
+    process.exitCode = 1;
+  }
+  if (successesObserved < 2) {
+    console.error('[ws] expected at least 2 successful reads; got', successesObserved);
+    process.exitCode = 1;
+  } else {
+    console.log(`[ws] workspace + HITL flow ✔`);
+  }
+
+  await Promise.all([
+    rm(workspace, { recursive: true, force: true }),
+    rm(sibling, { recursive: true, force: true }),
+    rm(outside, { 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/subagent-configurable-inheritance.ts

@@ -0,0 +1,252 @@
+import { config } from 'dotenv';
+config();
+
+import { HumanMessage } from '@langchain/core/messages';
+import type * as t from '@/types';
+import { ChatModelStreamHandler } from '@/stream';
+import { ToolEndHandler, ModelEndHandler } from '@/events';
+import { Providers, GraphEvents } from '@/common';
+import { Run } from '@/run';
+
+/**
+ * Live verification that host-set fields on the parent's outer
+ * `configurable` (e.g. `requestBody`, `user`, `userMCPAuthMap`)
+ * propagate into the subagent's `ON_TOOL_EXECUTE` dispatches.
+ *
+ * Pass criteria: when the SUBAGENT calls the calculator tool, the
+ * `data.configurable` arriving at the parent's ON_TOOL_EXECUTE
+ * handler contains every key the parent put on its outer
+ * configurable (with `thread_id` overridden to a child run id).
+ */
+const apiKey = process.env.OPENAI_API_KEY!;
+if (!apiKey) {
+  console.error('Missing OPENAI_API_KEY');
+  process.exit(1);
+}
+
+const calculatorDef: t.LCTool = {
+  name: 'calculator',
+  description: 'Evaluate a math expression. Use for any arithmetic.',
+  parameters: {
+    type: 'object',
+    properties: {
+      expression: {
+        type: 'string',
+        description: "A JS math expression, e.g. '42 * 58'",
+      },
+    },
+    required: ['expression'],
+  },
+};
+
+type ConfigurableSnapshot = {
+  agentId: string | undefined;
+  configurable: Record<string, unknown> | undefined;
+  metadata: Record<string, unknown> | undefined;
+};
+
+async function main() {
+  console.log('=== Subagent parentConfigurable inheritance — live ===\n');
+
+  // Parent has NO tools — it can only delegate via the math subagent.
+  // The math subagent has the calculator. This forces the spawn-subagent
+  // path so we can observe the subagent's `ON_TOOL_EXECUTE` dispatch.
+  const mathSubagentInputs: t.AgentInputs = {
+    agentId: 'math-worker',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o', apiKey },
+    instructions:
+      'You compute arithmetic. Always use the calculator tool — never estimate. Return the final numeric result as plain text.',
+    maxContextTokens: 8000,
+    toolDefinitions: [calculatorDef],
+  };
+
+  const parentAgent: t.AgentInputs = {
+    agentId: 'supervisor',
+    provider: Providers.OPENAI,
+    clientOptions: { modelName: 'gpt-4o', apiKey },
+    instructions: `You delegate arithmetic to the "math" subagent. You have NO calculator yourself. For any math task, spawn the "math" subagent with the full task as its description, then echo the subagent's text result back to the user.`,
+    maxContextTokens: 8000,
+    // No toolDefinitions on the parent — only the subagent gets the calculator.
+    subagentConfigs: [
+      {
+        type: 'math',
+        name: 'math',
+        description:
+          'A focused arithmetic worker that uses the calculator tool to compute numerical results.',
+        agentInputs: mathSubagentInputs,
+      },
+    ],
+  };
+
+  const parentSnapshots: ConfigurableSnapshot[] = [];
+  const subagentSnapshots: ConfigurableSnapshot[] = [];
+
+  const customHandlers: Record<string, t.EventHandler> = {
+    [GraphEvents.CHAT_MODEL_STREAM]: new ChatModelStreamHandler(),
+    [GraphEvents.TOOL_END]: new ToolEndHandler(),
+    [GraphEvents.CHAT_MODEL_END]: new ModelEndHandler(),
+    [GraphEvents.ON_TOOL_EXECUTE]: {
+      handle: (_event, rawData): void => {
+        const data = rawData as t.ToolExecuteBatchRequest;
+        const snapshot: ConfigurableSnapshot = {
+          agentId: data.agentId,
+          configurable: data.configurable as Record<string, unknown> | undefined,
+          metadata: data.metadata as Record<string, unknown> | undefined,
+        };
+        const callsLabel = data.toolCalls.map((c) => c.name).join(',');
+        // Parent and subagent have different agent IDs in this script
+        // (parent: 'supervisor', subagent: 'math-worker'). With a self-spawn
+        // subagent both would be the same; this script uses a non-self
+        // subagent precisely so we can distinguish reliably.
+        const isSubagent = data.agentId !== 'supervisor';
+        const metadataRunId = (data.metadata as { run_id?: string } | undefined)
+          ?.run_id;
+        if (isSubagent) {
+          subagentSnapshots.push(snapshot);
+        } else {
+          parentSnapshots.push(snapshot);
+        }
+        console.log(
+          `[ON_TOOL_EXECUTE] origin=${isSubagent ? 'SUBAGENT' : 'PARENT'} agentId=${data.agentId} calls=${callsLabel}`
+        );
+        console.log(
+          `  metadata keys: ${Object.keys(data.metadata ?? {}).join(',') || '<none>'}`
+        );
+        console.log(
+          `  metadata.run_id="${metadataRunId ?? '<none>'}" configurable.run_id="${(data.configurable as { run_id?: string } | undefined)?.run_id ?? '<none>'}" configurable.thread_id="${(data.configurable as { thread_id?: string } | undefined)?.thread_id ?? '<none>'}"`
+        );
+        const results: t.ToolExecuteResult[] = data.toolCalls.map((call) => {
+          const args = call.args as { expression?: string };
+          const expression = args.expression ?? '';
+          let content: string;
+          try {
+            // eslint-disable-next-line no-eval
+            const result = eval(expression);
+            content = `${expression} = ${result}`;
+          } catch (err) {
+            content = `Error: ${String(err)}`;
+          }
+          return {
+            toolCallId: call.id!,
+            status: 'success',
+            content,
+          };
+        });
+        data.resolve(results);
+      },
+    },
+  };
+
+  const run = await Run.create<t.IState>({
+    runId: `sub-cfg-inherit-${Date.now()}`,
+    graphConfig: { type: 'standard', agents: [parentAgent] },
+    customHandlers,
+  });
+
+  const question = new HumanMessage(
+    'Compute (42 * 58) + (13 ** 3). Use the self subagent, and have it use the calculator.'
+  );
+
+  // Parent's outer configurable carries host-set fields AND explicit
+  // run-identity fields so we can verify whether LangGraph respects or
+  // overwrites parent's `run_id` / `parent_run_id` when we forward them
+  // into the child's `workflow.invoke`.
+  const outerConfigurable = {
+    thread_id: 'parent-thread-conv-xyz',
+    run_id: 'parent-run-id-001',
+    parent_run_id: 'grandparent-run-id-000',
+    user_id: 'user_abc',
+    user: { id: 'user_abc', email: 'a@b.c', role: 'USER' },
+    requestBody: {
+      messageId: 'msg-response-id-001',
+      conversationId: 'parent-thread-conv-xyz',
+      parentMessageId: 'user-message-id-000',
+    },
+    userMCPAuthMap: { 'mcp-github': { token: 'abc' } },
+  };
+
+  console.log('User:', question.content);
+  console.log('Parent outer configurable keys:', Object.keys(outerConfigurable));
+  console.log();
+
+  await run.processStream(
+    { messages: [question] },
+    {
+      configurable: outerConfigurable,
+      version: 'v2' as const,
+    }
+  );
+
+  console.log('\n=== Verification ===');
+  console.log(
+    `Parent ON_TOOL_EXECUTE dispatches captured: ${parentSnapshots.length}`
+  );
+  console.log(
+    `Subagent ON_TOOL_EXECUTE dispatches captured: ${subagentSnapshots.length}`
+  );
+
+  if (subagentSnapshots.length === 0) {
+    console.error(
+      '\n❌ FAIL: subagent never invoked a tool — model may not have spawned the subagent.'
+    );
+    process.exit(2);
+  }
+
+  const expectedHostKeys = ['user_id', 'user', 'requestBody', 'userMCPAuthMap'];
+  let allPassed = true;
+  subagentSnapshots.forEach((snap, idx) => {
+    const cfg = snap.configurable ?? {};
+    const meta = snap.metadata ?? {};
+    console.log(
+      `\nSubagent dispatch #${idx + 1} (agentId=${snap.agentId}, metadata.run_id=${(meta as { run_id?: string }).run_id ?? '-'}):`
+    );
+
+    // Host-set fields must propagate.
+    for (const key of expectedHostKeys) {
+      const present = key in cfg;
+      const value = cfg[key];
+      console.log(
+        `  ${present ? '✅' : '❌'} ${key} = ${JSON.stringify(value)}`
+      );
+      if (!present) allPassed = false;
+    }
+
+    // Run-identity fields: with full inheritance we expect parent's
+    // values to flow through. LangGraph runtime MAY overwrite them at
+    // child-invoke time — the script logs what actually arrived so we
+    // can see empirically what propagates.
+    console.log(`  ⓘ thread_id observed: "${cfg.thread_id as string}" (parent's: "${outerConfigurable.thread_id}")`);
+    console.log(`  ⓘ run_id observed:    "${cfg.run_id as string}" (parent's: "${outerConfigurable.run_id}")`);
+    console.log(`  ⓘ parent_run_id observed: "${cfg.parent_run_id as string}" (parent's: "${outerConfigurable.parent_run_id}")`);
+
+    const threadInherited = cfg.thread_id === outerConfigurable.thread_id;
+    const runInherited = cfg.run_id === outerConfigurable.run_id;
+    const parentRunInherited =
+      cfg.parent_run_id === outerConfigurable.parent_run_id;
+    console.log(
+      `  ${threadInherited ? '✅' : '⚠️ '} thread_id inherited from parent: ${threadInherited}`
+    );
+    console.log(
+      `  ${runInherited ? '✅' : '⚠️ '} run_id inherited from parent: ${runInherited}`
+    );
+    console.log(
+      `  ${parentRunInherited ? '✅' : '⚠️ '} parent_run_id inherited from parent: ${parentRunInherited}`
+    );
+  });
+
+  if (allPassed) {
+    console.log(
+      '\n✅ Host-set fields propagate. (Run-identity inheritance is informational — see ⚠️ markers above for any LangGraph-runtime overwrites.)'
+    );
+    process.exit(0);
+  } else {
+    console.log('\n❌ FAIL: at least one expected host-set key was missing.');
+    process.exit(1);
+  }
+}
+
+main().catch((err) => {
+  console.error('Script error:', err);
+  process.exit(1);
+});