@librechat/agents 4.0.2 → 4.0.4

package/src/tools/GitHubCompare.ts

@@ -0,0 +1,319 @@
+import { DynamicStructuredTool } from '@langchain/core/tools';
+import { INTENT_PROPERTY } from '@/tools/intentArg';
+
+export const GitHubCompareToolName = 'github_compare';
+export const GitHubCompareToolDescription =
+  'Read-only GitHub comparison of two full commit SHAs in a public repository. Returns the merge-base, relation and commit counts without Git, a worktree, or worker admission. Does not fetch code or execute commands. Private repositories and arbitrary URLs are not supported.';
+export const GitHubCompareToolSchema = {
+  type: 'object',
+  properties: {
+    intent: { ...INTENT_PROPERTY },
+    owner: { type: 'string', description: 'GitHub repository owner.' },
+    repo: { type: 'string', description: 'GitHub repository name.' },
+    base: {
+      type: 'string',
+      description: 'Full lowercase base commit SHA, not a moving branch.',
+    },
+    head: {
+      type: 'string',
+      description: 'Full lowercase head commit SHA, not a moving branch.',
+    },
+  },
+  required: ['owner', 'repo', 'base', 'head'],
+} as const;
+export const GitHubCompareToolDefinition = {
+  name: GitHubCompareToolName,
+  description: GitHubCompareToolDescription,
+  parameters: GitHubCompareToolSchema,
+} as const;
+
+export interface GitHubComparisonInput {
+  owner: string;
+  repo: string;
+  base: string;
+  head: string;
+}
+
+export interface GitHubComparison {
+  base: string;
+  head: string;
+  mergeBase: string;
+  status: 'ahead' | 'behind' | 'identical' | 'diverged';
+  aheadBy: number;
+  behindBy: number;
+  totalCommits: number;
+}
+
+export interface GitHubCompareOptions {
+  /** Caller-owned transport, including proxy and instrumentation policy. */
+  fetch: typeof fetch;
+  /** Entire request budget, including body reads. Defaults to 10 seconds; maximum 30 seconds. */
+  timeoutMs?: number;
+}
+
+export type GitHubComparisonErrorCode =
+  | 'INVALID_INPUT'
+  | 'INVALID_CONFIGURATION'
+  | 'HTTP_ERROR'
+  | 'INVALID_RESPONSE'
+  | 'RESPONSE_TOO_LARGE'
+  | 'TRANSPORT_ERROR';
+
+export class GitHubComparisonError extends Error {
+  constructor(
+    public readonly code: GitHubComparisonErrorCode,
+    message: string,
+    public readonly status?: number
+  ) {
+    super(message);
+    this.name = 'GitHubComparisonError';
+  }
+}
+
+interface GitHubComparisonResponse {
+  base_commit?: { sha?: string };
+  merge_base_commit?: { sha?: string };
+  status?: GitHubComparison['status'];
+  ahead_by?: number;
+  behind_by?: number;
+  total_commits?: number;
+}
+
+const SHA = /^[a-f0-9]{40}$/;
+const REPO = /^[A-Za-z0-9][A-Za-z0-9_.-]{0,99}$/;
+const MAX_RESPONSE_BYTES = 2 * 1024 * 1024;
+
+function awaitWithSignal<T>(
+  operation: () => Promise<T>,
+  signal: AbortSignal
+): Promise<T> {
+  signal.throwIfAborted();
+  return new Promise<T>((resolve, reject) => {
+    const onAbort = (): void => {
+      signal.removeEventListener('abort', onAbort);
+      reject(signal.reason);
+    };
+    signal.addEventListener('abort', onAbort, { once: true });
+    try {
+      operation().then(
+        (value) => {
+          signal.removeEventListener('abort', onAbort);
+          resolve(value);
+        },
+        (error) => {
+          signal.removeEventListener('abort', onAbort);
+          reject(error);
+        }
+      );
+    } catch (error) {
+      signal.removeEventListener('abort', onAbort);
+      reject(error);
+    }
+  });
+}
+
+function cancelBody(response: Response): void {
+  void response.body?.cancel().catch(() => undefined);
+}
+
+async function readResponse(
+  response: Response,
+  signal: AbortSignal
+): Promise<string> {
+  const reader = response.body?.getReader();
+  if (reader == null) {
+    throw new GitHubComparisonError(
+      'INVALID_RESPONSE',
+      'GitHub comparison returned an invalid response.'
+    );
+  }
+  const chunks: Uint8Array[] = [];
+  let bytes = 0;
+  try {
+    for (;;) {
+      const item = await awaitWithSignal(() => reader.read(), signal);
+      if (item.done) {
+        break;
+      }
+      bytes += item.value.byteLength;
+      if (bytes > MAX_RESPONSE_BYTES) {
+        throw new GitHubComparisonError(
+          'RESPONSE_TOO_LARGE',
+          'GitHub comparison response exceeded its bound.'
+        );
+      }
+      chunks.push(item.value);
+    }
+    return Buffer.concat(chunks, bytes).toString('utf8');
+  } finally {
+    void reader.cancel().catch(() => undefined);
+    reader.releaseLock();
+  }
+}
+
+function parseComparison(
+  text: string,
+  input: GitHubComparisonInput
+): GitHubComparison {
+  let data: GitHubComparisonResponse | null;
+  try {
+    data = JSON.parse(text) as GitHubComparisonResponse | null;
+  } catch {
+    throw new GitHubComparisonError(
+      'INVALID_RESPONSE',
+      'GitHub comparison returned an invalid response.'
+    );
+  }
+  const mergeBase = data?.merge_base_commit?.sha;
+  const status = data?.status;
+  const aheadBy = data?.ahead_by;
+  const behindBy = data?.behind_by;
+  const totalCommits = data?.total_commits;
+  if (
+    data?.base_commit?.sha !== input.base ||
+    typeof mergeBase !== 'string' ||
+    !SHA.test(mergeBase) ||
+    (status !== 'ahead' &&
+      status !== 'behind' &&
+      status !== 'identical' &&
+      status !== 'diverged') ||
+    typeof aheadBy !== 'number' ||
+    !Number.isSafeInteger(aheadBy) ||
+    aheadBy < 0 ||
+    typeof behindBy !== 'number' ||
+    !Number.isSafeInteger(behindBy) ||
+    behindBy < 0 ||
+    typeof totalCommits !== 'number' ||
+    !Number.isSafeInteger(totalCommits) ||
+    totalCommits < 0
+  ) {
+    throw new GitHubComparisonError(
+      'INVALID_RESPONSE',
+      'GitHub comparison returned an invalid response.'
+    );
+  }
+  return {
+    base: input.base,
+    head: input.head,
+    mergeBase,
+    status,
+    aheadBy,
+    behindBy,
+    totalCommits,
+  };
+}
+
+export async function compareGitHubCommits(
+  input: GitHubComparisonInput,
+  options: GitHubCompareOptions,
+  signal?: AbortSignal
+): Promise<GitHubComparison> {
+  signal?.throwIfAborted();
+  if (
+    typeof input.owner !== 'string' ||
+    !REPO.test(input.owner) ||
+    typeof input.repo !== 'string' ||
+    !REPO.test(input.repo) ||
+    typeof input.base !== 'string' ||
+    !SHA.test(input.base) ||
+    typeof input.head !== 'string' ||
+    !SHA.test(input.head)
+  ) {
+    throw new GitHubComparisonError(
+      'INVALID_INPUT',
+      'Supply a repository and full lowercase commit SHAs.'
+    );
+  }
+  const timeoutMs = options.timeoutMs ?? 10000;
+  if (
+    typeof options.fetch !== 'function' ||
+    !Number.isSafeInteger(timeoutMs) ||
+    timeoutMs < 1 ||
+    timeoutMs > 30000
+  ) {
+    throw new GitHubComparisonError(
+      'INVALID_CONFIGURATION',
+      'Supply a GitHub transport and a timeout between 1 and 30000 ms.'
+    );
+  }
+  const timeout = new AbortController();
+  const timer = setTimeout(
+    () =>
+      timeout.abort(
+        new DOMException('GitHub comparison timed out.', 'TimeoutError')
+      ),
+    timeoutMs
+  );
+  timer.unref();
+  let pendingResponse: Response | undefined;
+  const requestSignal =
+    signal == null ? timeout.signal : AbortSignal.any([signal, timeout.signal]);
+  try {
+    const response = await awaitWithSignal(
+      () =>
+        options
+          .fetch(
+            `https://api.github.com/repos/${encodeURIComponent(input.owner)}/${encodeURIComponent(input.repo)}/compare/${input.base}...${input.head}?per_page=1&page=2`,
+            {
+              method: 'GET',
+              redirect: 'error',
+              credentials: 'omit',
+              signal: requestSignal,
+              headers: {
+                Accept: 'application/vnd.github+json',
+                'X-GitHub-Api-Version': '2022-11-28',
+              },
+            }
+          )
+          .then((response) => {
+            pendingResponse = response;
+            if (requestSignal.aborted) {
+              pendingResponse = undefined;
+              cancelBody(response);
+              requestSignal.throwIfAborted();
+            }
+            return response;
+          }),
+      requestSignal
+    );
+    if (!response.ok) {
+      throw new GitHubComparisonError(
+        'HTTP_ERROR',
+        `GitHub comparison unavailable (HTTP ${response.status}).`,
+        response.status
+      );
+    }
+    pendingResponse = undefined;
+    const text = await readResponse(response, requestSignal);
+    requestSignal.throwIfAborted();
+    return parseComparison(text, input);
+  } catch (error) {
+    requestSignal.throwIfAborted();
+    if (error instanceof GitHubComparisonError) {
+      throw error;
+    }
+    throw new GitHubComparisonError(
+      'TRANSPORT_ERROR',
+      'GitHub comparison transport failed.'
+    );
+  } finally {
+    if (pendingResponse != null) {
+      cancelBody(pendingResponse);
+    }
+    clearTimeout(timer);
+  }
+}
+
+export class GitHubCompareTool extends DynamicStructuredTool {
+  constructor(options: GitHubCompareOptions) {
+    super({
+      name: GitHubCompareToolName,
+      description: GitHubCompareToolDescription,
+      schema: structuredClone(GitHubCompareToolSchema),
+      func: async (input: GitHubComparisonInput, _manager, config) =>
+        JSON.stringify(
+          await compareGitHubCommits(input, options, config?.signal)
+        ),
+    });
+  }
+}

package/src/tools/SubagentTool.ts

@@ -1,5 +1,6 @@
 import type { JsonSchemaType, LCTool } from '@/types/tools';
 import type { SubagentConfig } from '@/types';
+import { buildSubagentHostArgProperties } from '@/tools/subagent/hostArgs';
 import { INTENT_PROPERTY } from '@/tools/intentArg';
 import { Constants } from '@/common';
 
@@ -33,6 +34,9 @@ const RUN_IN_BACKGROUND_PROP_DESCRIPTION =
 const SUBAGENT_THREAD_PROP_DESCRIPTION =
   'Continue a host-owned child thread using a fresh execution lease. The saved thread must belong to this scope and subagent type. Only available with run_in_background.';
 
+const HOST_ARGS_DESCRIPTION =
+  '\n\nOPTIONAL ARGUMENTS:\n- Some types accept extra arguments, listed in brackets after the type. Each is optional: omit it to let the host choose. Where values are listed, pass one listed for the selected type; where it says any text, pass a short value of your own.';
+
 export const SubagentToolSchema = {
   type: 'object',
   properties: {
@@ -69,8 +73,13 @@ export function buildSubagentToolParams(
   description: string;
 } {
   const types = configs.map((c) => c.type);
+  const hostArgs = buildSubagentHostArgProperties(configs);
   const typeDescriptions = configs
-    .map((c) => `- "${c.type}" (${c.name}): ${c.description}`)
+    .map((c) => {
+      const summary = hostArgs.summaries.get(c.type);
+      const line = `- "${c.type}" (${c.name}): ${c.description}`;
+      return summary == null ? line : `${line} [optional ${summary}]`;
+    })
     .join('\n');
 
   return {
@@ -96,8 +105,7 @@ export function buildSubagentToolParams(
             },
           }
           : {}),
-        ...(options.background === true &&
-        options.threadContinuation === true
+        ...(options.background === true && options.threadContinuation === true
           ? {
             subagent_thread_id: {
               type: 'string',
@@ -105,10 +113,13 @@ export function buildSubagentToolParams(
             },
           }
           : {}),
+        ...hostArgs.properties,
       },
       required: ['description', 'subagent_type'],
     },
     description: `${SubagentToolDescription}${
+      hostArgs.summaries.size > 0 ? HOST_ARGS_DESCRIPTION : ''
+    }${
       options.background === true
         ? '\n\nBACKGROUND EXECUTION:\n- Set run_in_background to true when you do not need the result immediately. The call returns a background_task_id; use the host background-task tools to poll, steer, queue, interrupt, or cancel it.'
         : ''

package/src/tools/ToolNode.ts

@@ -130,6 +130,7 @@ import {
 } from '@/tools/local';
 import { stripCodeSessionFileSummary } from '@/tools/CodeSessionFileSummary';
 import { Constants, GraphEvents, CODE_EXECUTION_TOOLS } from '@/common';
+import { ProviderTextProtectionError } from '@/protection/providerText';
 import { formatToolErrorContent } from '@/tools/toolErrorContent';
 import { PreparedSubagentError } from '@/tools/preparedSubagents';
 import { attachRunStepResumeState } from '@/tools/runStepResume';
@@ -2146,7 +2147,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
        */
       if (
         e instanceof StreamLimitExceededError ||
-        e instanceof PreparedSubagentError
+        e instanceof PreparedSubagentError ||
+        e instanceof ProviderTextProtectionError
       ) {
         throw e;
       }
@@ -3486,7 +3488,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (
       signal?.aborted === true &&
       (signal.reason instanceof StreamLimitExceededError ||
-        signal.reason instanceof PreparedSubagentError)
+        signal.reason instanceof PreparedSubagentError ||
+        signal.reason instanceof ProviderTextProtectionError)
     ) {
       throw signal.reason;
     }
@@ -5467,7 +5470,8 @@ export class ToolNode<T = any> extends RunnableCallable<T, T> {
     if (
       composedSignal?.aborted === true &&
       (composedSignal.reason instanceof StreamLimitExceededError ||
-        composedSignal.reason instanceof PreparedSubagentError)
+        composedSignal.reason instanceof PreparedSubagentError ||
+        composedSignal.reason instanceof ProviderTextProtectionError)
     ) {
       throw composedSignal.reason;
     }

package/src/tools/subagent/SubagentExecutionRegistry.ts

@@ -63,6 +63,8 @@ export type SubagentInvocationBinding = Readonly<{
   description: string;
   subagentType: string;
   configId?: string;
+  /** Value-free identity of the call's validated host arguments. */
+  hostArgsDigest?: string;
 }>;
 
 export type SubagentSettlementBinding = Readonly<{
@@ -340,7 +342,8 @@ function assertCompatibleResumeExecution(
     current.parentToolCallId === next.parentToolCallId &&
     current.childRunId === next.childRunId &&
     current.subagentType === next.subagentType &&
-    current.configId === next.configId
+    current.configId === next.configId &&
+    current.hostArgsDigest === next.hostArgsDigest
   ) {
     return;
   }
@@ -354,7 +357,8 @@ function assertSameInvocation(
   if (
     current.description === next.description &&
     current.subagentType === next.subagentType &&
-    current.configId === next.configId
+    current.configId === next.configId &&
+    current.hostArgsDigest === next.hostArgsDigest
   ) {
     return;
   }