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

33.6 KB
Raw Blame
import { ErrorTypes } from 'librechat-data-provider';
import type { AppConfig } from '@librechat/data-schemas';
import type { CodeExecutionContext, CodeEnvironmentConfig } from '~/agents/execution';
import {
  CodeWorkspaceSelectionError,
  isNativeSandboxProfile,
  resolveCodeExecutionWorkspaceContext,
  supportsProgrammaticCodeExecution,
} from './capabilities';
import { requiresCodeWorkspaceCapabilities } from '~/agents/tools';

const context: CodeExecutionContext = {
  baseUrl: 'https://bridge.example',
  codeSessionKey: 'session',
  executionProfile: 'stateful',
  statefulSessions: true,
  environmentId: 'personal',
  environmentType: 'attached',
  bridgeWorkerId: 'worker',
};
const environments: CodeEnvironmentConfig[] = [
  {
    id: 'personal',
    name: 'Personal',
    type: 'attached',
    owner: 'principal',
    baseURL: context.baseUrl,
    workerId: 'worker',
    controlPlaneId: 'control-plane',
  },
  {
    id: 'control-plane',
    name: 'Control plane',
    type: 'attached',
    owner: 'deployment',
    baseURL: context.baseUrl,
    pairing: { allowPrincipalWorkers: true, tokenEnv: 'TEST_CODE_CAPABILITY_TOKEN' },
  },
];

const deploymentConfig = {
  endpoints: { agents: { statefulCodeSessions: { environments: [environments[1]] } } },
} as AppConfig;
const getAppConfig = jest.fn(async () => deploymentConfig);

describe('supportsProgrammaticCodeExecution', () => {
  beforeEach(() => {
    getAppConfig.mockClear();
  });

  afterEach(() => {
    delete process.env.TEST_CODE_CAPABILITY_TOKEN;
    delete process.env.TEST_PRIVATE_CAPABILITY_SECRET;
  });

  it.each([false, true, undefined])('requires explicit support: %s', async (statefulWorkspace) => {
    process.env.TEST_CODE_CAPABILITY_TOKEN = `token-${statefulWorkspace}`;
    const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(
      new Response(
        JSON.stringify({
          protocolVersion: 1,
          workerId: 'worker',
          online: true,
          ready: true,
          leaseExpiresInMs: 45_000,
          capabilities: { statefulWorkspace, sandboxProfile: 'native-srt', runtimes: ['bash'] },
        }),
      ),
    );
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(
      statefulWorkspace === true,
    );
    expect(getAppConfig).toHaveBeenCalledWith({ baseOnly: true });
    expect(fetchSpy).toHaveBeenCalledWith(
      'https://bridge.example/bridge/workers/worker/status',
      expect.objectContaining({ headers: { Authorization: `Bearer token-${statefulWorkspace}` } }),
    );
  });

  it.each([
    { runtimes: [], supported: false },
    { runtimes: ['py'], supported: false },
    { runtimes: undefined, supported: false },
    { runtimes: ['py', 'bash'], supported: true },
  ])('requires advertised Bash support: $runtimes', async ({ runtimes, supported }) => {
    process.env.TEST_CODE_CAPABILITY_TOKEN = `runtimes-${JSON.stringify(runtimes)}`;
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(
      new Response(
        JSON.stringify({
          protocolVersion: 1,
          workerId: 'worker',
          online: true,
          ready: true,
          leaseExpiresInMs: 45_000,
          capabilities: { statefulWorkspace: true, sandboxProfile: 'native-srt', runtimes },
        }),
      ),
    );
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(
      supported,
    );
  });

  it('refreshes worker capabilities after the cached status expires', async () => {
    process.env.TEST_CODE_CAPABILITY_TOKEN = 'capability-transition-token';
    const startedAt = Date.now();
    const now = jest.spyOn(Date, 'now').mockReturnValue(startedAt);
    const status = (runtimes: string[]) =>
      new Response(
        JSON.stringify({
          protocolVersion: 1,
          workerId: 'worker',
          online: true,
          ready: true,
          leaseExpiresInMs: 45_000,
          capabilities: { statefulWorkspace: true, sandboxProfile: 'native-srt', runtimes },
        }),
      );
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockResolvedValueOnce(status(['bash']))
      .mockResolvedValueOnce(status(['py']));
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(true);
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(true);
    expect(fetchSpy).toHaveBeenCalledTimes(1);
    now.mockReturnValue(startedAt + 2_001);
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(
      false,
    );
    expect(fetchSpy).toHaveBeenCalledTimes(2);
  });

  it('disables PTC when discovery fails', async () => {
    process.env.TEST_CODE_CAPABILITY_TOKEN = 'failed-token';
    jest.spyOn(globalThis, 'fetch').mockRejectedValue(new Error('offline'));
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(
      false,
    );
  });

  it('does not poll managed environments or environments without status credentials', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));
    expect(
      await supportsProgrammaticCodeExecution({ ...context, environmentType: 'managed' }),
    ).toBe(true);
    expect(await supportsProgrammaticCodeExecution()).toBe(true);
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(
      false,
    );
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('suppresses generic programmatic Bash after an attached workspace is selected', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));

    expect(
      await supportsProgrammaticCodeExecution(
        {
          ...context,
          codeWorkspace: {
            environmentId: 'personal',
            workspaceId: 'project-a',
            operations: ['read_file', 'execute_command'],
          },
        },
        environments,
        getAppConfig,
      ),
    ).toBe(false);
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it.each([
    {
      languages: ['bash'],
      operation: 'execute_command',
      workspaceId: 'project-a',
      supported: true,
    },
    {
      languages: undefined,
      operation: 'execute_command',
      workspaceId: 'project-a',
      supported: false,
    },
    {
      languages: ['python'],
      operation: 'execute_command',
      workspaceId: 'project-a',
      supported: false,
    },
    { languages: ['bash'], operation: 'read_file', workspaceId: 'project-a', supported: false },
    { languages: ['bash'], operation: 'execute_command', workspaceId: 'removed', supported: false },
  ])(
    'gates selected project PTC using the live capability: %j',
    async ({ languages, operation, workspaceId, supported }) => {
      process.env.TEST_CODE_CAPABILITY_TOKEN = JSON.stringify({
        languages,
        operation,
        workspaceId,
      });
      jest.spyOn(globalThis, 'fetch').mockResolvedValue(
        new Response(
          JSON.stringify({
            protocolVersion: 1,
            workerId: 'worker',
            online: true,
            ready: true,
            leaseExpiresInMs: 45000,
            capabilities: {
              statefulWorkspace: false,
              sandboxProfile: 'anthropic-srt',
              runtimes: [],
              workspaceTools: {
                protocolVersion: 1,
                operations: ['execute_command', 'read_file'],
                programmaticLanguages: languages,
                workspaces: [{ id: 'project-a', operations: [operation] }],
              },
            },
          }),
        ),
      );
      expect(
        await supportsProgrammaticCodeExecution(
          {
            ...context,
            codeWorkspace: {
              environmentId: 'personal',
              workspaceId,
              operations: ['execute_command', 'read_file'],
            },
          },
          environments,
          getAppConfig,
        ),
      ).toBe(supported);
    },
  );

  it('does not send credentials to a different execution route', async () => {
    process.env.TEST_CODE_CAPABILITY_TOKEN = 'route-token';
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));
    expect(
      await supportsProgrammaticCodeExecution(
        { ...context, baseUrl: 'https://different.example' },
        environments,
        getAppConfig,
      ),
    ).toBe(false);
    expect(fetchSpy).not.toHaveBeenCalled();
  });
  it('rejects a deployment environment override that redirects a process secret', async () => {
    process.env.TEST_PRIVATE_CAPABILITY_SECRET = 'must-not-leave-the-process';
    const override: CodeEnvironmentConfig = {
      ...environments[1],
      baseURL: 'https://attacker.example',
      pairing: {
        workerId: 'worker',
        allowPrincipalWorkers: false,
        tokenEnv: 'TEST_PRIVATE_CAPABILITY_SECRET',
      },
    };
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));
    expect(
      await supportsProgrammaticCodeExecution(
        {
          ...context,
          environmentId: override.id,
          baseUrl: override.baseURL,
        },
        [override],
        getAppConfig,
      ),
    ).toBe(false);
    expect(getAppConfig).toHaveBeenCalledWith({ baseOnly: true });
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('uses only deployment credentials even if the effective control plane names another secret', async () => {
    process.env.TEST_CODE_CAPABILITY_TOKEN = 'deployment-only-token';
    process.env.TEST_PRIVATE_CAPABILITY_SECRET = 'must-not-leave-the-process';
    const override: CodeEnvironmentConfig = {
      ...environments[1],
      baseURL: 'https://attacker.example',
      pairing: { allowPrincipalWorkers: true, tokenEnv: 'TEST_PRIVATE_CAPABILITY_SECRET' },
    };
    const fetchSpy = jest.spyOn(globalThis, 'fetch').mockResolvedValue(
      new Response(
        JSON.stringify({
          protocolVersion: 1,
          workerId: 'worker',
          online: true,
          ready: true,
          leaseExpiresInMs: 45_000,
          capabilities: {
            statefulWorkspace: true,
            sandboxProfile: 'native-srt',
            runtimes: ['bash'],
          },
        }),
      ),
    );
    expect(
      await supportsProgrammaticCodeExecution(context, [environments[0], override], getAppConfig),
    ).toBe(true);
    expect(fetchSpy).toHaveBeenCalledWith(
      'https://bridge.example/bridge/workers/worker/status',
      expect.objectContaining({ headers: { Authorization: 'Bearer deployment-only-token' } }),
    );
    expect(JSON.stringify(fetchSpy.mock.calls)).not.toContain('must-not-leave-the-process');
  });

  it('requires the control plane in effective config before reading deployment config', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));
    expect(await supportsProgrammaticCodeExecution(context, [environments[0]], getAppConfig)).toBe(
      false,
    );
    expect(getAppConfig).not.toHaveBeenCalled();
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('fails closed when deployment configuration cannot be loaded', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));
    expect(
      await supportsProgrammaticCodeExecution(context, environments, async () => {
        throw new Error('unavailable');
      }),
    ).toBe(false);
    expect(fetchSpy).not.toHaveBeenCalled();
  });
});

describe('resolveCodeExecutionWorkspaceContext', () => {
  beforeEach(() => {
    getAppConfig.mockClear();
    process.env.TEST_CODE_CAPABILITY_TOKEN = `workspace-${Math.random()}`;
  });

  afterEach(() => {
    delete process.env.TEST_CODE_CAPABILITY_TOKEN;
  });

  function workspaceStatus(
    workspaces: unknown[],
    statefulWorkspace: boolean = true,
    maxCommandTimeoutMs?: number,
    operations: string[] = ['read_file', 'list_files', 'execute_command'],
  ): Response {
    return new Response(
      JSON.stringify({
        protocolVersion: 1,
        workerId: 'worker',
        online: true,
        ready: true,
        leaseExpiresInMs: 45_000,
        maxCommandTimeoutMs,
        capabilities: {
          statefulWorkspace,
          sandboxProfile: 'native-srt',
          runtimes: ['bash'],
          workspaceTools: {
            protocolVersion: 1,
            operations,
            workspaces,
          },
        },
      }),
    );
  }

  it.each([
    ['skill'],
    ['tool_search'],
    ['web_search'],
    ['lookup_mcp_example'],
    ['skill', 'lookup_mcp_example'],
    [],
  ])('does not probe worker status for host-only tools: %j', async (...toolNames) => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new DOMException('Status request timed out', 'TimeoutError'));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requiresLiveCapabilities: requiresCodeWorkspaceCapabilities(toolNames),
        persistedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).resolves.toBe(context);
    expect(fetchSpy).not.toHaveBeenCalled();
    expect(getAppConfig).not.toHaveBeenCalled();
  });

  it.each([
    'bash_tool',
    'execute_code',
    'run_tools_with_bash',
    'run_tools_with_code',
    'read_file',
    'create_file',
    'edit_file',
    'search_workspace',
    'list_workspace_files',
  ])('still validates live workspace capabilities for %s', async (toolName) => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new DOMException('Status request timed out', 'TimeoutError'));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requiresLiveCapabilities: requiresCodeWorkspaceCapabilities(['skill', toolName]),
        persistedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).rejects.toMatchObject({ reason: 'worker_unavailable' });
    expect(fetchSpy).toHaveBeenCalledTimes(2);
  });

  it('still enforces the sealed selection for host-only tools', async () => {
    const fetchSpy = jest.spyOn(globalThis, 'fetch');

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requiresLiveCapabilities: false,
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'project-b' }],
        persistedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).rejects.toMatchObject({ reason: 'locked' });
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('binds the exact advertised workspace and its operation ceiling', async () => {
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(
      workspaceStatus(
        [
          { id: 'project-a', name: 'Project A' },
          { id: 'docs', operations: ['read_file', 'list_files'] },
        ],
        true,
        120_000,
      ),
    );

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [
          { environmentId: 'another-machine', workspaceId: 'other-project' },
          { environmentId: 'personal', workspaceId: 'docs' },
        ],
        environments,
        getAppConfig,
      }),
    ).resolves.toMatchObject({
      codeSessionKey: 'session',
      codeWorkspace: {
        environmentId: 'personal',
        workspaceId: 'docs',
        operations: ['read_file', 'list_files'],
        maxCommandTimeoutMs: 120_000,
      },
    });
  });

  it('selects a workspace from a newer worker with only the operations this build knows', async () => {
    jest
      .spyOn(globalThis, 'fetch')
      .mockResolvedValue(
        workspaceStatus(
          [{ id: 'docs', operations: ['read_file', 'stream_logs', 'import_file', 'write_file'] }],
          true,
          undefined,
          ['read_file', 'write_file', 'import_file', 'stream_logs', 'execute_command'],
        ),
      );

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
        environments,
        getAppConfig,
      }),
    ).resolves.toMatchObject({
      codeWorkspace: {
        workspaceId: 'docs',
        operations: ['read_file', 'import_file', 'write_file'],
      },
    });
  });

  it('carries the worker edit features into the selected workspace', async () => {
    const response = workspaceStatus([{ id: 'docs' }]);
    const body = await response.json();
    body.capabilities.workspaceTools.editFileFeatures = ['expected_base_sha256', 'tolerant_match'];
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify(body)));

    const resolved = await resolveCodeExecutionWorkspaceContext({
      context,
      requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
      environments,
      getAppConfig,
    });

    expect(resolved.codeWorkspace?.editFileFeatures).toEqual([
      'expected_base_sha256',
      'tolerant_match',
    ]);
  });

  it.each([
    { sandboxProfile: 'anthropic-srt', nativeSandbox: true },
    { sandboxProfile: 'anthropic-srt:trusted-vm', nativeSandbox: true },
    { sandboxProfile: 'anthropic-srt-custom', nativeSandbox: undefined },
    { sandboxProfile: 'native-srt', nativeSandbox: undefined },
    { sandboxProfile: 'oci-docker', nativeSandbox: undefined },
  ])(
    'marks the native sandbox only for its advertised profile: $sandboxProfile',
    async ({ sandboxProfile, nativeSandbox }) => {
      const response = workspaceStatus([{ id: 'docs' }]);
      const body = await response.json();
      body.capabilities.sandboxProfile = sandboxProfile;
      jest.spyOn(globalThis, 'fetch').mockResolvedValue(new Response(JSON.stringify(body)));

      const resolved = await resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
        environments,
        getAppConfig,
      });

      expect(resolved.codeWorkspace?.nativeSandbox).toBe(nativeSandbox);
      expect(isNativeSandboxProfile(sandboxProfile)).toBe(nativeSandbox === true);
    },
  );

  it('carries validated project metadata from the selected workspace', async () => {
    const environment = {
      fingerprint: 'a'.repeat(64),
      repo: 'example/app',
      ref: 'dev',
      actions: ['typecheck'],
    };
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(
      workspaceStatus([
        { id: 'docs', environment },
        { id: 'other', environment: { ...environment, actions: ['other'] } },
      ]),
    );
    const resolved = await resolveCodeExecutionWorkspaceContext({
      context,
      requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
      environments,
      getAppConfig,
    });
    expect(resolved.codeWorkspace?.environment).toEqual(environment);
  });

  it.each([
    { checkout: 'source', linkedWorktrees: undefined, lanes: true },
    { checkout: 'source', linkedWorktrees: true, lanes: true },
    { checkout: 'source', linkedWorktrees: false, lanes: false },
    { checkout: 'isolated', linkedWorktrees: undefined, lanes: false },
    { checkout: 'isolated', linkedWorktrees: true, lanes: false },
    { checkout: 'isolated', linkedWorktrees: false, lanes: false },
  ] as const)(
    'honors checkout $checkout with linkedWorktrees=$linkedWorktrees',
    async ({ checkout, linkedWorktrees, lanes }) => {
      jest.spyOn(globalThis, 'fetch').mockResolvedValue(
        workspaceStatus([
          {
            id: 'worktree',
            workspaceInstances: ['git_worktree'],
            workspaceScopes: ['git_linked_worktree'],
          },
        ]),
      );
      const resolved = await resolveCodeExecutionWorkspaceContext({
        context: {
          ...context,
          conversationWorkspaceInstanceId: 'c'.repeat(64),
          codeEnvironmentConfigSchema: {
            workspaces: { allowCheckoutSelection: true, linkedWorktrees },
          },
        },
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'worktree', checkout }],
        environments,
        getAppConfig,
      });
      expect(resolved.codeWorkspace?.checkout).toBe(checkout);
      expect(resolved.codeWorkspace?.workspaceInstanceId).toBe(
        checkout === 'isolated' ? 'c'.repeat(64) : undefined,
      );
      expect(resolved.codeWorkspace?.linkedWorktrees).toBe(lanes ? true : undefined);
    },
  );

  it.each([
    { enabled: false, capable: true, instance: 'c'.repeat(64) },
    { enabled: true, capable: false, instance: 'c'.repeat(64) },
    { enabled: true, capable: true, instance: undefined },
  ])(
    'refuses unsupported isolation instead of executing in the source: %j',
    async ({ enabled, capable, instance }) => {
      jest
        .spyOn(globalThis, 'fetch')
        .mockResolvedValue(
          workspaceStatus([
            { id: 'worktree', ...(capable ? { workspaceInstances: ['git_worktree'] } : {}) },
          ]),
        );
      await expect(
        resolveCodeExecutionWorkspaceContext({
          context: {
            ...context,
            conversationWorkspaceInstanceId: instance,
            codeEnvironmentConfigSchema: { workspaces: { allowCheckoutSelection: enabled } },
          },
          requestedSelections: [
            { environmentId: 'personal', workspaceId: 'worktree', checkout: 'isolated' },
          ],
          environments,
          getAppConfig,
        }),
      ).rejects.toMatchObject({ reason: 'unsupported' });
    },
  );

  it('refuses a checkout choice that changes the sealed decision', async () => {
    const selection = { environmentId: 'personal', workspaceId: 'worktree' };
    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        persistedSelections: [{ ...selection, checkout: 'isolated' }],
        requestedSelections: [{ ...selection, checkout: 'source' }],
        environments,
        getAppConfig,
      }),
    ).rejects.toMatchObject({ reason: 'locked' });
  });

  it('activates a server-derived instance only when the worker advertises worktree support', async () => {
    const workspaceInstanceId = 'c'.repeat(64);
    jest
      .spyOn(globalThis, 'fetch')
      .mockResolvedValue(
        workspaceStatus([
          { id: 'worktree', workspaceInstances: ['git_worktree'] },
          { id: 'legacy' },
        ]),
      );

    const supported = await resolveCodeExecutionWorkspaceContext({
      context: { ...context, conversationWorkspaceInstanceId: workspaceInstanceId },
      requestedSelections: [{ environmentId: 'personal', workspaceId: 'worktree' }],
      environments,
      getAppConfig,
    });
    const legacy = await resolveCodeExecutionWorkspaceContext({
      context: { ...context, conversationWorkspaceInstanceId: workspaceInstanceId },
      requestedSelections: [{ environmentId: 'personal', workspaceId: 'legacy' }],
      environments,
      getAppConfig,
    });

    expect(supported.codeWorkspace?.workspaceInstanceId).toBe(workspaceInstanceId);
    expect(legacy.codeWorkspace).not.toHaveProperty('workspaceInstanceId');
  });

  it('routes linked worktrees into lanes unless disabled or a conversation instance owns the checkout', async () => {
    const workspaceInstanceId = 'c'.repeat(64);
    jest.spyOn(globalThis, 'fetch').mockImplementation(async () =>
      workspaceStatus([
        {
          id: 'lanes',
          workspaceInstances: ['git_worktree'],
          workspaceScopes: ['git_linked_worktree'],
        },
        { id: 'legacy' },
      ]),
    );
    const resolve = (workspaceId: string, instanceId?: string, linkedWorktrees = true) =>
      resolveCodeExecutionWorkspaceContext({
        context: {
          ...context,
          codeEnvironmentConfigSchema: {
            workspaces: { linkedWorktrees, allowCheckoutSelection: false },
          },
          ...(instanceId ? { conversationWorkspaceInstanceId: instanceId } : {}),
        },
        requestedSelections: [{ environmentId: 'personal', workspaceId }],
        environments,
        getAppConfig,
      });

    const lanes = await resolve('lanes');
    const disabled = await resolve('lanes', undefined, false);
    const unconfigured = await resolveCodeExecutionWorkspaceContext({
      context,
      requestedSelections: [{ environmentId: 'personal', workspaceId: 'lanes' }],
      environments,
      getAppConfig,
    });
    const instance = await resolve('lanes', workspaceInstanceId);
    const legacy = await resolve('legacy');

    expect(lanes.codeWorkspace?.linkedWorktrees).toBe(true);
    expect(disabled.codeWorkspace).not.toHaveProperty('linkedWorktrees');
    expect(unconfigured.codeWorkspace?.linkedWorktrees).toBe(true);
    expect(instance.codeWorkspace?.workspaceInstanceId).toBe(workspaceInstanceId);
    expect(instance.codeWorkspace).not.toHaveProperty('linkedWorktrees');
    expect(legacy.codeWorkspace).not.toHaveProperty('linkedWorktrees');
  });

  it('admits native workspace tools without enabling programmatic runtime execution', async () => {
    jest
      .spyOn(globalThis, 'fetch')
      .mockResolvedValue(workspaceStatus([{ id: 'docs', operations: ['read_file'] }], false));
    const resolved = await resolveCodeExecutionWorkspaceContext({
      context,
      requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
      environments,
      getAppConfig,
    });
    expect(resolved.codeWorkspace).toEqual({
      environmentId: 'personal',
      workspaceId: 'docs',
      operations: ['read_file'],
    });
    expect(await supportsProgrammaticCodeExecution(context, environments, getAppConfig)).toBe(
      false,
    );
    expect(await supportsProgrammaticCodeExecution(resolved, environments, getAppConfig)).toBe(
      false,
    );
  });

  it.each([false, true])(
    'fails closed without native workspace capabilities (ready: %s)',
    async (ready) => {
      jest.spyOn(globalThis, 'fetch').mockResolvedValue(
        new Response(
          JSON.stringify({
            protocolVersion: 1,
            workerId: 'worker',
            online: true,
            ready,
            leaseExpiresInMs: 45_000,
            capabilities: { statefulWorkspace: false, sandboxProfile: 'native-srt', runtimes: [] },
          }),
        ),
      );
      await expect(
        resolveCodeExecutionWorkspaceContext({
          context,
          requestedSelections: [{ environmentId: 'personal', workspaceId: 'docs' }],
          environments,
          getAppConfig,
        }),
      ).rejects.toMatchObject({ reason: ready ? 'unsupported' : 'worker_unavailable' });
    },
  );

  it.each(['worker', 'replacement', undefined])(
    'pins deployment worker identity: %s',
    async (workerId) => {
      const fetch = jest
        .spyOn(globalThis, 'fetch')
        .mockResolvedValue(workspaceStatus([{ id: 'project-a' }]));
      const deploymentEnvironment: CodeEnvironmentConfig = {
        id: 'fixed',
        name: 'Fixed VM',
        type: 'attached',
        owner: 'deployment',
        baseURL: context.baseUrl,
        pairing: { workerId, tokenEnv: 'TEST_CODE_CAPABILITY_TOKEN', allowPrincipalWorkers: false },
      };
      const pending = resolveCodeExecutionWorkspaceContext({
        context: { ...context, environmentId: 'fixed' },
        requestedSelections: [{ environmentId: 'fixed', workspaceId: 'project-a' }],
        environments: [
          {
            ...deploymentEnvironment,
            pairing: {
              workerId: 'worker',
              tokenEnv: 'TEST_CODE_CAPABILITY_TOKEN',
              allowPrincipalWorkers: false,
            },
          },
        ],
        getAppConfig: jest.fn(
          async () =>
            ({
              endpoints: {
                agents: { statefulCodeSessions: { environments: [deploymentEnvironment] } },
              },
            }) as AppConfig,
        ),
      });
      if (workerId === 'worker') {
        await expect(pending).resolves.toMatchObject({
          codeWorkspace: { workspaceId: 'project-a' },
        });
      } else {
        await expect(pending).rejects.toMatchObject({ reason: 'worker_unavailable' });
        expect(fetch).not.toHaveBeenCalled();
      }
    },
  );

  it('uses the persisted binding when the request omits one', async () => {
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(workspaceStatus([{ id: 'project-a' }]));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        persistedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).resolves.toMatchObject({
      codeWorkspace: { environmentId: 'personal', workspaceId: 'project-a' },
    });
  });

  it('accepts an equivalent retry regardless of selection order', async () => {
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(workspaceStatus([{ id: 'project-a' }]));
    const personal = { environmentId: 'personal', workspaceId: 'project-a' };
    const team = { environmentId: 'team', workspaceId: 'project-b' };

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [team, personal],
        persistedSelections: [personal, team],
        environments,
        getAppConfig,
      }),
    ).resolves.toMatchObject({ codeWorkspace: personal });
  });

  it('rejects a request that changes a persisted workspace before contacting Code API', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'project-b' }],
        persistedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).rejects.toMatchObject({ reason: 'locked' });
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('rejects changed agent ownership on a sealed selection before contacting Code API', async () => {
    const fetchSpy = jest.spyOn(globalThis, 'fetch');
    const selected = { environmentId: 'personal', workspaceId: 'project-a' };
    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ ...selected, agentIds: ['reviewer'] }],
        persistedSelections: [{ ...selected, agentIds: ['primary'] }],
        environments,
        getAppConfig,
      }),
    ).rejects.toMatchObject({ reason: 'locked' });
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('fails when the saved workspace disappears instead of selecting another', async () => {
    jest.spyOn(globalThis, 'fetch').mockResolvedValue(workspaceStatus([{ id: 'replacement' }]));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).rejects.toEqual(
      expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({
        reason: 'missing',
        code: ErrorTypes.CODE_WORKSPACE_UNAVAILABLE,
        status: 409,
        statusCode: 409,
      }),
    );
  });

  it('requires a binding for the executing environment before contacting Code API', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ environmentId: 'another-machine', workspaceId: 'project-a' }],
        environments,
        getAppConfig,
      }),
    ).rejects.toEqual(
      expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({
        reason: 'required',
      }),
    );
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('rejects malformed selections before contacting Code API', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [
          {
            environmentId: 'personal',
            workspaceId: 'project-a',
            operations: ['execute_command'],
          },
        ],
        environments,
        getAppConfig,
      }),
    ).rejects.toEqual(
      expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({ reason: 'invalid' }),
    );
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('rejects duplicate environment bindings before contacting Code API', async () => {
    const fetchSpy = jest
      .spyOn(globalThis, 'fetch')
      .mockRejectedValue(new Error('Unexpected status request'));

    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [
          { environmentId: 'personal', workspaceId: 'project-a' },
          { environmentId: 'personal', workspaceId: 'project-b' },
        ],
        environments,
        getAppConfig,
      }),
    ).rejects.toEqual(
      expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({ reason: 'invalid' }),
    );
    expect(fetchSpy).not.toHaveBeenCalled();
  });

  it('returns an explicit unavailable error when deployment configuration cannot be loaded', async () => {
    await expect(
      resolveCodeExecutionWorkspaceContext({
        context,
        requestedSelections: [{ environmentId: 'personal', workspaceId: 'project-a' }],
        environments,
        getAppConfig: async () => {
          throw new Error('configuration unavailable');
        },
      }),
    ).rejects.toEqual(
      expect.objectContaining<Partial<CodeWorkspaceSelectionError>>({
        reason: 'worker_unavailable',
      }),
    );
  });
});