Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

12.2 KB
Raw Blame
import type {
  SubagentControlAction,
  SubagentControlReceipt,
  SubagentControlRequest,
  SubagentControlResponse,
} from 'librechat-data-provider';
import type {
  ConversationMethods,
  ISubagentTaskControlReceipt,
  MessageMethods,
} from '@librechat/data-schemas';
import type { SubagentTaskControlCommand, SubagentTaskControlResult } from '@librechat/agents';
import type { Response } from 'express';
import type { ServerRequest } from '~/types';
import { controlFingerprint, SubagentTaskOwnerUnavailableError } from './subagentTaskRouting';
import { createSubagentThreadScopeId } from './subagentThreads';

const MAX_THREAD_ID_BYTES = 256;
const MAX_TASK_ID_BYTES = 256;
const MAX_INVOCATION_ID_BYTES = 128;
const MAX_CONTROL_MESSAGE_CHARS = 4 * 1024;

type ControlStore = {
  controlTask(
    scopeId: string,
    taskId: string,
    command: SubagentTaskControlCommand,
    invocationId: string,
  ): Promise<SubagentTaskControlResult>;
};

type Dependencies = Pick<ConversationMethods, 'getConvoOwnership' | 'getSubagentThreadForParent'> &
  Pick<MessageMethods, 'getMessages' | 'getSubagentTaskControlReceipt'> & {
    store: ControlStore;
  };

type Params = {
  parentConversationId?: string;
  threadId?: string;
  taskId?: string;
  invocationId?: string;
};

const validId = (value: unknown, byteLimit = MAX_THREAD_ID_BYTES): value is string =>
  typeof value === 'string' && value.trim() !== '' && Buffer.byteLength(value, 'utf8') <= byteLimit;

const validAction = (value: unknown): value is SubagentControlAction =>
  value === 'steer' ||
  value === 'queue' ||
  value === 'interrupt' ||
  value === 'cancel' ||
  value === 'cancel_message';

const requestKeysForAction = (action: SubagentControlAction): Set<string> => {
  const keys = new Set(['taskId', 'invocationId', 'action']);
  if (action === 'cancel_message') keys.add('controlId');
  else if (action !== 'cancel') keys.add('message');
  return keys;
};

const commandFromRequest = (
  body: SubagentControlRequest,
): SubagentTaskControlCommand | undefined => {
  if (!validAction(body.action)) return undefined;
  if (body.action === 'cancel') return { action: 'cancel' };
  if (body.action === 'cancel_message') {
    return validId(body.controlId, MAX_TASK_ID_BYTES)
      ? { action: 'cancel_message', controlId: body.controlId }
      : undefined;
  }
  if (
    typeof body.message !== 'string' ||
    body.message.trim() === '' ||
    body.message.length > MAX_CONTROL_MESSAGE_CHARS
  ) {
    return undefined;
  }
  return { action: body.action, message: body.message };
};

/** Cheap structural admission shared by the Express route and authoritative
 * handler. It must run before filters, moderation, or owner routing. */
export const isValidSubagentControlRequest = (value: unknown): value is SubagentControlRequest => {
  if (value == null || typeof value !== 'object') return false;
  const body = value as Partial<SubagentControlRequest>;
  if (!validAction(body.action)) return false;
  const allowedKeys = requestKeysForAction(body.action);
  return (
    Object.keys(body).every((key) => allowedKeys.has(key)) &&
    validId(body.taskId, MAX_TASK_ID_BYTES) &&
    validId(body.invocationId, MAX_INVOCATION_ID_BYTES) &&
    commandFromRequest(body as SubagentControlRequest) != null
  );
};

const commandReceiptFields = (command: SubagentTaskControlCommand) => ({
  ...(command.action === 'cancel_message' ? { controlId: command.controlId } : {}),
  ...('message' in command ? { message: command.message } : {}),
});

const responseReceipt = (
  invocationId: string,
  command: SubagentTaskControlCommand,
  result: SubagentTaskControlResult,
): SubagentControlReceipt => {
  const now = new Date().toISOString();
  let status: SubagentControlReceipt['status'] = 'rejected';
  let reason: string | undefined;
  if (result.status === 'accepted')
    status = command.action === 'cancel_message' ? 'applied' : 'accepted';
  if (result.status === 'cancelled') status = 'applied';
  if (result.status === 'not_running') reason = 'task_not_running';
  if (result.status === 'control_not_found') reason = 'control_not_found';
  if (result.status === 'invalid') reason = 'invalid_command';
  if (result.status === 'not_found') {
    status = 'failed';
    reason = 'owner_unavailable';
  }
  return {
    invocationId,
    ...commandReceiptFields(command),
    ...(command.action !== 'cancel_message' &&
    result.status === 'accepted' &&
    result.controlId != null
      ? { controlId: result.controlId }
      : {}),
    action: command.action,
    status,
    createdAt: now,
    updatedAt: now,
    ...(reason == null ? {} : { reason }),
  };
};

const publicStoredReceipt = ({
  fingerprint: _fingerprint,
  createdAt,
  updatedAt,
  status,
  ...receipt
}: ISubagentTaskControlReceipt): SubagentControlReceipt => {
  if (status === 'reserved') {
    throw new SubagentTaskOwnerUnavailableError();
  }
  return {
    ...receipt,
    status,
    createdAt: createdAt.toISOString(),
    updatedAt: updatedAt.toISOString(),
  };
};

/** Applies one parent-authorized control to the live owner and returns only its public receipt. */
export function createSubagentControlHandler(deps: Dependencies) {
  return async (req: ServerRequest, res: Response): Promise<void> => {
    const userId = req.user?.id;
    const tenantId = req.user?.tenantId || undefined;
    const { parentConversationId, threadId } = req.params as Params;
    const body = (req.body ?? {}) as Partial<SubagentControlRequest>;
    const command = commandFromRequest(body as SubagentControlRequest);
    if (
      !userId ||
      !validId(parentConversationId, MAX_THREAD_ID_BYTES) ||
      !validId(threadId, MAX_THREAD_ID_BYTES) ||
      parentConversationId === threadId ||
      !isValidSubagentControlRequest(body) ||
      command == null
    ) {
      res.status(400).json({ error: 'Invalid subagent control request' });
      return;
    }

    try {
      const [parent, child] = await Promise.all([
        deps.getConvoOwnership(userId, parentConversationId, tenantId ?? null),
        deps.getSubagentThreadForParent({
          user: userId,
          parentConversationId,
          conversationId: threadId,
          ...(tenantId == null ? {} : { tenantId }),
        }),
      ]);
      if (
        parent == null ||
        child?.subagentThread?.parentConversationId !== parentConversationId ||
        parent.tenantId !== tenantId ||
        child.tenantId !== tenantId
      ) {
        res.status(404).json({ error: 'Conversation not found' });
        return;
      }
      const fingerprint = controlFingerprint(command);
      const existing = await deps.getSubagentTaskControlReceipt({
        userId,
        conversationId: threadId,
        taskId: body.taskId,
        invocationId: body.invocationId,
        ...(tenantId == null ? {} : { tenantId }),
      });
      /** `reserved` is a server-private at-most-once fence, not an authoritative
       * public receipt. Re-enter the task store so it can return owner-unavailable
       * without exposing false acceptance or reapplying the command. */
      if (existing != null && existing.status !== 'reserved') {
        const receipt =
          existing.fingerprint === fingerprint
            ? publicStoredReceipt(existing)
            : responseReceipt(body.invocationId, command, {
                status: 'invalid',
                message: 'This control invocation id was already used for a different command.',
              });
        res.status(200).json({ receipt } satisfies SubagentControlResponse);
        return;
      }
      const [taskInput] = await deps.getMessages(
        {
          user: userId,
          conversationId: threadId,
          messageId: `${body.taskId}:user`,
          ...(tenantId == null ? { tenantId: { $exists: false } } : { tenantId }),
        },
        '+subagentTask',
      );
      if (taskInput?.subagentTask == null) {
        if (
          child.subagentThreadLease?.taskId === body.taskId &&
          child.subagentThreadLease.expiresAt.getTime() > Date.now()
        ) {
          throw new SubagentTaskOwnerUnavailableError();
        }
        res.status(404).json({ error: 'Conversation not found' });
        return;
      }
      const scopeId = createSubagentThreadScopeId({
        userId,
        parentConversationId,
        ...(tenantId == null ? {} : { tenantId }),
      });
      /** Retry identity and durable settlement belong to the task store. Route
       * through that ledger even when the visible lease is stale instead of
       * synthesizing a rejection that can race the owner's delayed receipt. */
      const result = await deps.store.controlTask(scopeId, body.taskId, command, body.invocationId);
      if (result.status === 'not_found') {
        throw new SubagentTaskOwnerUnavailableError();
      }
      if ('task' in result && result.task.threadId !== threadId) {
        res.status(404).json({ error: 'Conversation not found' });
        return;
      }
      /** Routing returns the SDK task result, whose legacy `accepted` shape cannot
       * distinguish an accepted command from one that became applied during the
       * call. The durable ledger is authoritative after the store returns. */
      const settledReceipt = await deps.getSubagentTaskControlReceipt({
        userId,
        conversationId: threadId,
        taskId: body.taskId,
        invocationId: body.invocationId,
        ...(tenantId == null ? {} : { tenantId }),
      });
      const receipt =
        settledReceipt != null && settledReceipt.fingerprint === fingerprint
          ? publicStoredReceipt(settledReceipt)
          : responseReceipt(body.invocationId, command, result);
      res.status(200).json({ receipt } satisfies SubagentControlResponse);
    } catch (error) {
      if (error instanceof SubagentTaskOwnerUnavailableError) {
        const receipt: SubagentControlReceipt = {
          invocationId: body.invocationId,
          ...commandReceiptFields(command),
          action: command.action,
          status: 'failed',
          createdAt: new Date().toISOString(),
          updatedAt: new Date().toISOString(),
          reason: 'owner_unavailable',
        };
        res.status(503).json({ receipt } satisfies SubagentControlResponse);
        return;
      }
      res.status(500).json({ error: 'Failed to control subagent task' });
    }
  };
}

/** Reads one retained body through its parent without mutating or replaying the control. */
export function createSubagentControlReceiptHandler(
  deps: Pick<
    Dependencies,
    'getConvoOwnership' | 'getSubagentThreadForParent' | 'getSubagentTaskControlReceipt'
  >,
) {
  return async (req: ServerRequest, res: Response): Promise<void> => {
    const userId = req.user?.id;
    const tenantId = req.user?.tenantId || undefined;
    const { parentConversationId, threadId, taskId, invocationId } = req.params as Params;
    if (
      !userId ||
      !validId(parentConversationId) ||
      !validId(threadId) ||
      parentConversationId === threadId ||
      !validId(taskId, MAX_TASK_ID_BYTES) ||
      !validId(invocationId, MAX_INVOCATION_ID_BYTES)
    ) {
      res.status(400).json({ error: 'Invalid subagent control request' });
      return;
    }
    try {
      const [parent, child] = await Promise.all([
        deps.getConvoOwnership(userId, parentConversationId, tenantId ?? null),
        deps.getSubagentThreadForParent({
          user: userId,
          parentConversationId,
          conversationId: threadId,
          tenantId,
        }),
      ]);
      if (
        parent == null ||
        child?.subagentThread?.parentConversationId !== parentConversationId ||
        parent.tenantId !== tenantId ||
        child.tenantId !== tenantId
      ) {
        res.status(404).json({ error: 'Conversation not found' });
        return;
      }
      const receipt = await deps.getSubagentTaskControlReceipt({
        userId,
        conversationId: threadId,
        taskId,
        invocationId,
        tenantId,
        activeOnly: true,
      });
      if (receipt == null || receipt.status === 'reserved') {
        res.status(404).json({ error: 'Control not found' });
        return;
      }
      res
        .status(200)
        .json({ receipt: publicStoredReceipt(receipt) } satisfies SubagentControlResponse);
    } catch {
      res.status(503).json({ error: 'Subagent content unavailable' });
    }
  };
}