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

20.4 KB
Raw Blame
import type { IConversation } from '@librechat/data-schemas';
import type { Response } from 'express';
import type { ServerRequest } from '~/types';
import {
  createSubagentControlHandler,
  createSubagentControlReceiptHandler,
  isValidSubagentControlRequest,
} from './control';
import { controlFingerprint, SubagentTaskOwnerUnavailableError } from './subagentTaskRouting';

const parentConversationId = 'parent-conversation';
const threadId = 'child-thread';
const taskId = 'task-1';
const parent = {
  conversationId: parentConversationId,
  user: 'user-1',
  tenantId: 'tenant-1',
} as IConversation;
const child = {
  conversationId: threadId,
  user: 'user-1',
  tenantId: 'tenant-1',
  subagentThread: {
    rootConversationId: parentConversationId,
    parentConversationId,
    parentMessageId: 'parent-message',
    parentToolCallId: 'parent-tool-call',
    parentAgentId: 'parent-agent',
    subagentType: 'researcher',
    subagentKind: 'agent',
    depth: 1,
  },
  subagentThreadLease: {
    token: 'lease-token',
    taskId,
    expiresAt: new Date('2099-08-24T12:00:00.000Z'),
  },
} as IConversation;

const response = () => {
  const json = jest.fn();
  const status = jest.fn(() => ({ json }));
  return { value: { status } as unknown as Response, status, json };
};

const request = (body: Record<string, unknown>): ServerRequest =>
  ({
    params: { parentConversationId, threadId },
    body,
    user: { id: 'user-1', tenantId: 'tenant-1' },
  }) as ServerRequest;

const dependencies = (controlTask = jest.fn()) => ({
  getConvoOwnership: jest.fn().mockResolvedValue(parent),
  getSubagentThreadForParent: jest.fn().mockResolvedValue(child),
  getMessages: jest
    .fn()
    .mockResolvedValue([{ messageId: `${taskId}:user`, subagentTask: { status: 'running' } }]),
  getSubagentTaskControlReceipt: jest.fn().mockResolvedValue(null),
  recordSubagentTaskControlReceipt: jest.fn().mockResolvedValue(true),
  store: { controlTask },
});

describe('subagent control handler', () => {
  it('rejects fields outside the action-specific public control contract', () => {
    expect(
      isValidSubagentControlRequest({
        taskId,
        invocationId: 'invocation-1',
        action: 'queue',
        message: 'Check the primary source.',
      }),
    ).toBe(true);
    expect(
      isValidSubagentControlRequest({
        taskId,
        invocationId: 'invocation-1',
        action: 'queue',
        message: 'Check the primary source.',
        answers: ['unrelated moderation input'],
      }),
    ).toBe(false);
    expect(
      isValidSubagentControlRequest({
        taskId,
        invocationId: 'invocation-1',
        action: 'cancel',
        message: 'unused',
      }),
    ).toBe(false);
  });

  it('returns one bounded public accepted receipt from the authorized live owner', async () => {
    const controlTask = jest.fn().mockResolvedValue({
      status: 'accepted',
      controlId: 'control-1',
      task: { taskId, threadId, status: 'running' },
    });
    const deps = dependencies(controlTask);
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'queue',
        message: 'Check the primary source.',
      }),
      res.value,
    );

    expect(controlTask).toHaveBeenCalledWith(
      JSON.stringify({
        version: 1,
        userId: 'user-1',
        parentConversationId,
        tenantId: 'tenant-1',
      }),
      taskId,
      { action: 'queue', message: 'Check the primary source.' },
      'invocation-1',
    );
    expect(res.status).toHaveBeenCalledWith(200);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        controlId: 'control-1',
        action: 'queue',
        status: 'accepted',
      }),
    });
    expect(JSON.stringify(res.json.mock.calls[0][0])).not.toContain('task');
    expect(deps.getMessages).toHaveBeenCalledWith(
      {
        user: 'user-1',
        tenantId: 'tenant-1',
        conversationId: threadId,
        messageId: `${taskId}:user`,
      },
      '+subagentTask',
    );
  });

  it('returns the durable applied receipt when settlement races the owner response', async () => {
    const command = { action: 'queue' as const, message: 'Check the primary source.' };
    const controlTask = jest.fn().mockResolvedValue({
      status: 'accepted',
      controlId: 'control-1',
      task: { taskId, threadId, status: 'running' },
    });
    const deps = dependencies(controlTask);
    deps.getSubagentTaskControlReceipt.mockResolvedValueOnce(null).mockResolvedValueOnce({
      invocationId: 'invocation-race',
      fingerprint: controlFingerprint(command),
      controlId: 'control-1',
      action: 'queue',
      status: 'applied',
      boundary: 'turn',
      createdAt: new Date('2026-08-24T12:00:00.000Z'),
      updatedAt: new Date('2026-08-24T12:00:01.000Z'),
    });
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(request({ taskId, invocationId: 'invocation-race', ...command }), res.value);

    expect(res.status).toHaveBeenCalledWith(200);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-race',
        status: 'applied',
        boundary: 'turn',
      }),
    });
    expect(deps.getSubagentTaskControlReceipt).toHaveBeenCalledTimes(2);
  });

  it('fails parent authorization closed without contacting a task owner', async () => {
    const deps = dependencies();
    deps.getConvoOwnership.mockResolvedValue(null);
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'cancel_message',
        controlId: 'queued-control',
      }),
      res.value,
    );

    expect(deps.store.controlTask).not.toHaveBeenCalled();
    expect(res.status).toHaveBeenCalledWith(404);
  });

  it('reads a tenantless task seed only from tenantless rows', async () => {
    const controlTask = jest.fn().mockResolvedValue({
      status: 'accepted',
      controlId: 'control-1',
      task: { taskId, threadId, status: 'running' },
    });
    const deps = dependencies(controlTask);
    deps.getConvoOwnership.mockResolvedValue({ ...parent, tenantId: undefined });
    deps.getSubagentThreadForParent.mockResolvedValue({ ...child, tenantId: undefined });
    const req = request({
      taskId,
      invocationId: 'invocation-1',
      action: 'queue',
      message: 'Check the primary source.',
    });
    req.user = { id: 'user-1' } as ServerRequest['user'];
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(req, res.value);

    expect(deps.getMessages).toHaveBeenCalledWith(
      expect.objectContaining({
        user: 'user-1',
        conversationId: threadId,
        messageId: `${taskId}:user`,
        tenantId: { $exists: false },
      }),
      '+subagentTask',
    );
    expect(controlTask).toHaveBeenCalledTimes(1);
  });

  it('returns an authoritative rejection when the selected task is no longer live', async () => {
    const deps = dependencies(
      jest.fn().mockResolvedValue({
        status: 'not_running',
        task: { taskId, threadId, status: 'completed' },
      }),
    );
    deps.getSubagentThreadForParent.mockResolvedValue({
      ...child,
      subagentThreadLease: undefined,
    });
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'cancel_message',
        controlId: 'queued-control',
      }),
      res.value,
    );

    expect(deps.store.controlTask).toHaveBeenCalledWith(
      expect.any(String),
      taskId,
      { action: 'cancel_message', controlId: 'queued-control' },
      'invocation-1',
    );
    expect(res.status).toHaveBeenCalledWith(200);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        controlId: 'queued-control',
        action: 'cancel_message',
        status: 'rejected',
        reason: 'task_not_running',
      }),
    });
  });

  it('replays the durable authoritative receipt before rejecting an expired lease', async () => {
    const deps = dependencies();
    deps.getSubagentThreadForParent.mockResolvedValue({
      ...child,
      subagentThreadLease: undefined,
    });
    deps.getSubagentTaskControlReceipt.mockResolvedValue({
      invocationId: 'invocation-1',
      fingerprint: controlFingerprint({ action: 'queue', message: 'Check the primary source.' }),
      controlId: 'control-1',
      action: 'queue',
      status: 'applied',
      createdAt: new Date('2026-08-24T12:00:00.000Z'),
      updatedAt: new Date('2026-08-24T12:00:01.000Z'),
      boundary: 'turn',
      message: 'Check the primary source.',
    });
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'queue',
        message: 'Check the primary source.',
      }),
      res.value,
    );

    expect(deps.store.controlTask).not.toHaveBeenCalled();
    expect(deps.recordSubagentTaskControlReceipt).not.toHaveBeenCalled();
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        status: 'applied',
        boundary: 'turn',
      }),
    });
    expect(JSON.stringify(res.json.mock.calls[0][0])).not.toContain('fingerprint');
  });

  it('never exposes a private reservation as an accepted public receipt', async () => {
    const controlTask = jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError());
    const deps = dependencies(controlTask);
    deps.getSubagentTaskControlReceipt.mockResolvedValue({
      invocationId: 'invocation-1',
      fingerprint: controlFingerprint({ action: 'queue', message: 'Check the primary source.' }),
      action: 'queue',
      status: 'reserved',
      createdAt: new Date('2026-08-24T12:00:00.000Z'),
      updatedAt: new Date('2026-08-24T12:00:00.000Z'),
      message: 'Check the primary source.',
    });
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'queue',
        message: 'Check the primary source.',
      }),
      res.value,
    );

    expect(controlTask).toHaveBeenCalledTimes(1);
    expect(res.status).toHaveBeenCalledWith(503);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        status: 'failed',
        reason: 'owner_unavailable',
      }),
    });
    expect(JSON.stringify(res.json.mock.calls[0][0])).not.toContain('reserved');
  });

  it('rejects invocation-id reuse with different command content', async () => {
    const deps = dependencies();
    deps.getSubagentTaskControlReceipt.mockResolvedValue({
      invocationId: 'invocation-1',
      fingerprint: controlFingerprint({ action: 'queue', message: 'Original command.' }),
      controlId: 'control-1',
      action: 'queue',
      status: 'accepted',
      createdAt: new Date('2026-08-24T12:00:00.000Z'),
      updatedAt: new Date('2026-08-24T12:00:00.000Z'),
      message: 'Original command.',
    });
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'queue',
        message: 'Different command.',
      }),
      res.value,
    );

    expect(deps.store.controlTask).not.toHaveBeenCalled();
    expect(deps.recordSubagentTaskControlReceipt).not.toHaveBeenCalled();
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        status: 'rejected',
        reason: 'invalid_command',
      }),
    });
  });

  it('preserves a missing cancel_message target in the authoritative rejection', async () => {
    const deps = dependencies(
      jest.fn().mockResolvedValue({
        status: 'control_not_found',
        task: { taskId, threadId, status: 'running' },
      }),
    );
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'cancel_message',
        controlId: 'missing-control',
      }),
      res.value,
    );

    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        controlId: 'missing-control',
        action: 'cancel_message',
        status: 'rejected',
        reason: 'control_not_found',
      }),
    });
  });

  it('makes owner unavailability explicit so the same invocation can be retried', async () => {
    const deps = dependencies(jest.fn().mockRejectedValue(new SubagentTaskOwnerUnavailableError()));
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({ taskId, invocationId: 'invocation-1', action: 'interrupt', message: 'Stop.' }),
      res.value,
    );

    expect(res.status).toHaveBeenCalledWith(503);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        status: 'failed',
        reason: 'owner_unavailable',
      }),
    });
  });

  it('returns a retryable failure when routing cannot resolve a live owner', async () => {
    const deps = dependencies(
      jest.fn().mockResolvedValue({
        status: 'not_found',
        task: { taskId, threadId, status: 'running' },
      }),
    );
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({ taskId, invocationId: 'invocation-1', action: 'queue', message: 'Continue.' }),
      res.value,
    );

    expect(res.status).toHaveBeenCalledWith(503);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        status: 'failed',
        reason: 'owner_unavailable',
      }),
    });
  });

  it('rejects a task result owned by a sibling child thread', async () => {
    const deps = dependencies(
      jest.fn().mockResolvedValue({
        status: 'accepted',
        controlId: 'control-1',
        task: { taskId, threadId: 'sibling-thread', status: 'running' },
      }),
    );
    const handler = createSubagentControlHandler(deps);
    const res = response();
    deps.getSubagentThreadForParent.mockResolvedValue({
      ...child,
      subagentThreadLease: undefined,
    });
    deps.getMessages.mockResolvedValue([]);

    await handler(
      request({ taskId, invocationId: 'invocation-1', action: 'queue', message: 'Continue.' }),
      res.value,
    );

    expect(res.status).toHaveBeenCalledWith(404);
    expect(res.json).toHaveBeenCalledWith({ error: 'Conversation not found' });
    expect(deps.store.controlTask).not.toHaveBeenCalled();
  });

  it('keeps a live pre-seed control retryable without applying it', async () => {
    const deps = dependencies();
    deps.getMessages.mockResolvedValue([]);
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({ taskId, invocationId: 'invocation-1', action: 'queue', message: 'Continue.' }),
      res.value,
    );

    expect(deps.store.controlTask).not.toHaveBeenCalled();
    expect(res.status).toHaveBeenCalledWith(503);
    expect(res.json).toHaveBeenCalledWith({
      receipt: expect.objectContaining({
        invocationId: 'invocation-1',
        status: 'failed',
        reason: 'owner_unavailable',
      }),
    });
  });

  it('rejects malformed controls before authorization or routing', async () => {
    const deps = dependencies();
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({ taskId, invocationId: 'invocation-1', action: 'steer', message: ' ' }),
      res.value,
    );

    expect(deps.getConvoOwnership).not.toHaveBeenCalled();
    expect(res.status).toHaveBeenCalledWith(400);
  });

  it('rejects task ids beyond the durable storage bound before authorization', async () => {
    const deps = dependencies();
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId: 't'.repeat(257),
        invocationId: 'invocation-1',
        action: 'cancel',
      }),
      res.value,
    );

    expect(deps.getConvoOwnership).not.toHaveBeenCalled();
    expect(res.status).toHaveBeenCalledWith(400);
  });

  it.each(['parentConversationId', 'threadId'] as const)(
    'rejects %s beyond the downstream storage bound before authorization',
    async (field) => {
      const deps = dependencies();
      const handler = createSubagentControlHandler(deps);
      const req = request({
        taskId,
        invocationId: 'invocation-1',
        action: 'cancel',
      });
      (req.params as Record<string, string>)[field] = 'c'.repeat(257);
      const res = response();

      await handler(req, res.value);

      expect(deps.getConvoOwnership).not.toHaveBeenCalled();
      expect(res.status).toHaveBeenCalledWith(400);
    },
  );

  it('rejects control ids beyond the durable receipt bound before authorization', async () => {
    const deps = dependencies();
    const handler = createSubagentControlHandler(deps);
    const res = response();

    await handler(
      request({
        taskId,
        invocationId: 'invocation-1',
        action: 'cancel_message',
        controlId: 'c'.repeat(257),
      }),
      res.value,
    );

    expect(deps.getConvoOwnership).not.toHaveBeenCalled();
    expect(res.status).toHaveBeenCalledWith(400);
  });
});

describe('parent-authorized retained control body', () => {
  const readRequest = () =>
    ({
      ...request({}),
      params: { parentConversationId, threadId, taskId, invocationId: 'invocation-1' },
    }) as ServerRequest;
  it('returns the retained body without private replay fields or invoking control', async () => {
    const deps = dependencies();
    deps.getSubagentTaskControlReceipt.mockResolvedValue({
      invocationId: 'invocation-1',
      fingerprint: 'private',
      action: 'queue',
      status: 'accepted',
      message: '界'.repeat(4096),
      createdAt: new Date(0),
      updatedAt: new Date(1),
    });
    const res = response();
    await createSubagentControlReceiptHandler(deps)(readRequest(), res.value);
    expect(res.status).toHaveBeenCalledWith(200);
    expect(res.json.mock.calls[0][0].receipt.message).toBe('界'.repeat(4096));
    expect(res.json.mock.calls[0][0].receipt).not.toHaveProperty('fingerprint');
    expect(deps.store.controlTask).not.toHaveBeenCalled();
  });
  it.each(['parent', 'child', 'tenant'] as const)(
    'does not read a body without its authorized %s',
    async (missing) => {
      const deps = dependencies();
      if (missing === 'parent') deps.getConvoOwnership.mockResolvedValue(null);
      if (missing === 'child') deps.getSubagentThreadForParent.mockResolvedValue(null);
      if (missing === 'tenant')
        deps.getSubagentThreadForParent.mockResolvedValue({ ...child, tenantId: 'other' });
      const res = response();
      await createSubagentControlReceiptHandler(deps)(readRequest(), res.value);
      expect(res.status).toHaveBeenCalledWith(404);
      expect(deps.getSubagentTaskControlReceipt).not.toHaveBeenCalled();
    },
  );
  it('requires an active source receipt from the storage boundary', async () => {
    const deps = dependencies();
    const res = response();
    await createSubagentControlReceiptHandler(deps)(readRequest(), res.value);
    expect(res.status).toHaveBeenCalledWith(404);
    expect(deps.getSubagentTaskControlReceipt).toHaveBeenCalledWith({
      userId: 'user-1',
      conversationId: threadId,
      taskId,
      invocationId: 'invocation-1',
      tenantId: 'tenant-1',
      activeOnly: true,
    });
    expect(deps.getMessages).not.toHaveBeenCalled();
  });
  it('sanitizes unexpected body storage failures', async () => {
    const deps = dependencies();
    deps.getSubagentTaskControlReceipt.mockRejectedValue(new Error('private storage content'));
    const res = response();
    await createSubagentControlReceiptHandler(deps)(readRequest(), res.value);
    expect(res.status).toHaveBeenCalledWith(503);
    expect(JSON.stringify(res.json.mock.calls)).not.toContain('private');
  });
});