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

🗂️ feat: Record Lane Git State and Serve Conversation Pull Requests (#16793)

Marco Berettaae44437e1639
diff --git a/api/server/routes/__test-utils__/convos-route-mocks.js b/api/server/routes/__test-utils__/convos-route-mocks.js
index bd86738d13..ce6a630d93 100644
--- a/api/server/routes/__test-utils__/convos-route-mocks.js
+++ b/api/server/routes/__test-utils__/convos-route-mocks.js
@@ -147,6 +147,11 @@ module.exports = {
() => (_req, res) => res.status(200).json({ tasks: [] }),
),
createBackgroundTaskPolicyMiddleware: jest.fn(() => (_req, _res, next) => next()),
+ createGitHubPullRequestSource: jest.fn(() => ({ find: jest.fn() })),
+ createPullRequestLookup: jest.fn(() => jest.fn()),
+ createConversationPullRequestHandler: jest.fn(
+ () => (_req, res) => res.status(200).json({ pullRequest: null }),
+ ),
createBackgroundTaskCancelHandler: jest.fn(
() => (_req, res) => res.status(200).json({ results: [] }),
),
diff --git a/api/server/routes/__tests__/convos.spec.js b/api/server/routes/__tests__/convos.spec.js
index 1cc49c7430..0c448a67ab 100644
--- a/api/server/routes/__tests__/convos.spec.js
+++ b/api/server/routes/__tests__/convos.spec.js
@@ -237,6 +237,21 @@ describe('Convos Routes', () => {
});
});
+ describe('GET /:conversationId/pull-request', () => {
+ it('is registered and reaches the pull request handler', async () => {
+ const response = await request(app).get('/api/convos/ordinary/pull-request');
+
+ expect(response.status).toBe(200);
+ expect(response.body).toEqual({ pullRequest: null });
+ });
+
+ it('does not fall through to the conversation read', async () => {
+ await request(app).get('/api/convos/ordinary/pull-request');
+
+ expect(getConvo).not.toHaveBeenCalled();
+ });
+ });
+
describe('POST /import', () => {
const { importConversations } = require('~/server/utils/import');
diff --git a/api/server/routes/convos.js b/api/server/routes/convos.js
index ebb02973b9..4c05abb57f 100644
--- a/api/server/routes/convos.js
+++ b/api/server/routes/convos.js
@@ -19,6 +19,9 @@ const {
createBackgroundTaskIndexHandler,
createBackgroundTaskCancelHandler,
createBackgroundTaskPolicyMiddleware,
+ createConversationPullRequestHandler,
+ createGitHubPullRequestSource,
+ createPullRequestLookup,
backgroundTaskRegistry,
createSubagentThreadViewHandler,
createGeneratedTitleHandler,
@@ -167,6 +170,12 @@ const backgroundTaskIndexHandler = createBackgroundTaskIndexHandler({
const backgroundTaskCancelHandler = createBackgroundTaskCancelHandler({
registry: backgroundTaskRegistry,
});
+const conversationPullRequestHandler = createConversationPullRequestHandler({
+ getConvoLaneGit: db.getConvoLaneGit,
+ getAppConfig,
+ lookup: createPullRequestLookup({ source: createGitHubPullRequestSource({ fetchFn: fetch }) }),
+ env: process.env,
+});
router.use(requireJwtAuth);
const isValidProjectFilter = (projectId) =>
@@ -239,6 +248,7 @@ router.post(
subagentControlHandler,
);
router.get('/:parentConversationId/subagents', parentSubagentIndexHandler);
+router.get('/:conversationId/pull-request', conversationPullRequestHandler);
router.get('/:conversationId/background-tasks', backgroundTaskPolicy, backgroundTaskIndexHandler);
router.post(
'/:conversationId/background-tasks/cancel',
diff --git a/api/server/services/ToolService.js b/api/server/services/ToolService.js
index 77af238288..cd1c63132a 100644
--- a/api/server/services/ToolService.js
+++ b/api/server/services/ToolService.js
@@ -50,6 +50,7 @@ const {
AGENT_EXPECTED_MCP_TOOLS_UNAVAILABLE,
isFatalAgentInitializationError,
codeExecutionAuthHeaders,
+ createLaneGitRecorder,
createAttachedWorkspaceBashTool,
createRepositoryInstructionSource,
createRepositoryInstructionLoader,
@@ -130,7 +131,13 @@ const { createOpenIDSessionTokenProvider } = require('~/server/services/OpenIDSe
const { getMCPRequestContext } = require('~/server/services/MCPRequestContext');
const { recordUsage } = require('~/server/services/Threads');
const { loadTools } = require('~/app/clients/tools/util');
-const { findPluginAuthsByKeys, getRoleByName } = require('~/models');
+const {
+ findPluginAuthsByKeys,
+ getRoleByName,
+ setConvoLaneGit,
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq,
+} = require('~/models');
const { getFlowStateManager, getMCPServersRegistry } = require('~/config');
const { getLogStores } = require('~/cache');
@@ -2386,6 +2393,19 @@ async function loadToolsForExecution({
baseUrl: codeExecutionContext.baseUrl,
workspaceId: codeExecutionContext.codeWorkspace.workspaceId,
workspaceInstanceId: codeExecutionContext.codeWorkspace.workspaceInstanceId,
+ onLaneGit: await createLaneGitRecorder({
+ enabled: req.config?.endpoints?.agents?.pullRequests?.enabled === true,
+ user: req.user.id,
+ conversationId: conversationId ?? runtimeRequestBody?.conversationId,
+ repo: codeExecutionContext.codeWorkspace.environment?.repo,
+ workspace: {
+ environmentId: codeExecutionContext.codeWorkspace.environmentId,
+ workspaceId: codeExecutionContext.codeWorkspace.workspaceId,
+ },
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq,
+ setConvoLaneGit,
+ }),
linkedWorktrees: codeExecutionContext.codeWorkspace.linkedWorktrees,
nativeSandbox: codeExecutionContext.codeWorkspace.nativeSandbox,
environment: codeExecutionContext.codeWorkspace.environment,
diff --git a/api/server/services/__tests__/ToolService.spec.js b/api/server/services/__tests__/ToolService.spec.js
index df7cbed6be..29d18e3b80 100644
--- a/api/server/services/__tests__/ToolService.spec.js
+++ b/api/server/services/__tests__/ToolService.spec.js
@@ -22,6 +22,11 @@ const mockGetCachedTools = jest.fn();
const mockSendEvent = jest.fn();
const mockEmitChunk = jest.fn();
const mockCreateAttachedWorkspaceBashTool = jest.fn(() => ({ name: AgentConstants.BASH_TOOL }));
+const mockLaneGitRecorder = jest.fn();
+const mockCreateLaneGitRecorder = jest.fn(() => mockLaneGitRecorder);
+const mockSetConvoLaneGit = jest.fn();
+const mockGetConvoLaneContext = jest.fn();
+const mockReserveConvoLaneGitSeq = jest.fn();
const attachedWorkspaceOperations = [
'read_file',
'search_text',
@@ -121,6 +126,7 @@ jest.mock('@librechat/api', () => ({
resolveCodeExecutionWorkspaceContext: (...args) =>
mockResolveCodeExecutionWorkspaceContext(...args),
createAttachedWorkspaceBashTool: (...args) => mockCreateAttachedWorkspaceBashTool(...args),
+ createLaneGitRecorder: (...args) => mockCreateLaneGitRecorder(...args),
}));
const mockLoadToolsUtil = jest.fn();
@@ -171,6 +177,9 @@ const mockGetRoleByName = jest.fn();
jest.mock('~/models', () => ({
findPluginAuthsByKeys: jest.fn(),
getRoleByName: (...args) => mockGetRoleByName(...args),
+ setConvoLaneGit: (...args) => mockSetConvoLaneGit(...args),
+ getConvoLaneContext: (...args) => mockGetConvoLaneContext(...args),
+ reserveConvoLaneGitSeq: (...args) => mockReserveConvoLaneGitSeq(...args),
}));
jest.mock('~/config', () => ({
getFlowStateManager: jest.fn(() => mockFlowManager),
@@ -3221,6 +3230,7 @@ describe('ToolService - Action Capability Gating', () => {
authHeaders: expect.any(Function),
baseUrl: 'http://attached-code.test/v1',
workspaceId: 'project-a',
+ onLaneGit: mockLaneGitRecorder,
gitIdentity: { name: 'LibreChat Agent', email: '[email protected]' },
maxTimeoutMs: 65_000,
defaultTimeoutMs: 60_000,
@@ -3243,6 +3253,108 @@ describe('ToolService - Action Capability Gating', () => {
expect(result.loadedTools).toContainEqual({ name: AgentConstants.BASH_TOOL });
});
+ it('records the lane for the requesting user and the resolved conversation', async () => {
+ const capabilities = [
+ AgentCapabilities.tools,
+ AgentCapabilities.execute_code,
+ AgentCapabilities.stateful_code_sessions,
+ ];
+ const req = createMockReq(capabilities);
+ req.config.endpoints[EModelEndpoint.agents].pullRequests = { enabled: true };
+ req.body = {
+ conversationId: 'body-convo',
+ codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
+ };
+ mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
+ mockResolveCodeExecutionContext.mockReturnValueOnce({
+ baseUrl: 'http://attached-code.test/v1',
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ statefulSessions: true,
+ environmentType: 'attached',
+ environmentId: 'personal-machine',
+ bridgeWorkerId: 'worker-abc',
+ });
+ mockCreateLaneGitRecorder.mockClear();
+
+ await loadToolsForExecution({
+ req,
+ res: {},
+ agent: {
+ id: 'attached-agent',
+ tools: [Tools.execute_code],
+ stateful_code_sessions: true,
+ stateful_code_environment: 'agent-user',
+ },
+ conversationId: 'resolved-convo',
+ toolNames: [AgentConstants.BASH_TOOL],
+ toolRegistry: new Map([[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }]]),
+ actionsEnabled: false,
+ });
+
+ expect(mockCreateLaneGitRecorder).toHaveBeenCalledWith(
+ expect.objectContaining({
+ enabled: true,
+ user: req.user.id,
+ conversationId: 'resolved-convo',
+ workspace: { environmentId: 'personal-machine', workspaceId: 'project-a' },
+ getConvoLaneContext: expect.any(Function),
+ reserveConvoLaneGitSeq: expect.any(Function),
+ setConvoLaneGit: expect.any(Function),
+ }),
+ );
+ const { setConvoLaneGit } = mockCreateLaneGitRecorder.mock.calls[0][0];
+ const input = { user: 'u', conversationId: 'c', laneGit: { branch: 'main', head: null } };
+ await setConvoLaneGit(input);
+ expect(mockSetConvoLaneGit).toHaveBeenCalledWith(input);
+ });
+
+ it.each([
+ ['unset', undefined],
+ ['disabled', { enabled: false }],
+ ])('does not enable lane recording when pull requests are %s', async (_label, setting) => {
+ const capabilities = [
+ AgentCapabilities.tools,
+ AgentCapabilities.execute_code,
+ AgentCapabilities.stateful_code_sessions,
+ ];
+ const req = createMockReq(capabilities);
+ if (setting) req.config.endpoints[EModelEndpoint.agents].pullRequests = setting;
+ req.body = {
+ codeWorkspaces: [{ environmentId: 'personal-machine', workspaceId: 'project-a' }],
+ };
+ mockGetEndpointsConfig.mockResolvedValue(createEndpointsConfig(capabilities));
+ mockResolveCodeExecutionContext.mockReturnValueOnce({
+ baseUrl: 'http://attached-code.test/v1',
+ codeSessionKey: 'execute_code:stateful:attached',
+ executionProfile: 'stateful',
+ statefulSessions: true,
+ environmentType: 'attached',
+ environmentId: 'personal-machine',
+ bridgeWorkerId: 'worker-abc',
+ });
+ mockCreateLaneGitRecorder.mockClear();
+
+ await loadToolsForExecution({
+ req,
+ res: {},
+ agent: {
+ id: 'attached-agent',
+ tools: [Tools.execute_code],
+ stateful_code_sessions: true,
+ stateful_code_environment: 'agent-user',
+ },
+ conversationId: 'resolved-convo',
+ toolNames: [AgentConstants.BASH_TOOL],
+ toolRegistry: new Map([[AgentConstants.BASH_TOOL, { name: AgentConstants.BASH_TOOL }]]),
+ actionsEnabled: false,
+ });
+
+ expect(mockCreateLaneGitRecorder).toHaveBeenCalledWith(
+ expect.objectContaining({ enabled: false }),
+ );
+ });
+
it('passes negotiated lane and native sandbox capabilities to the attached bash tool', async () => {
const capabilities = [
AgentCapabilities.tools,
diff --git a/librechat.example.yaml b/librechat.example.yaml
index a40971434a..28ff605949 100644
--- a/librechat.example.yaml
+++ b/librechat.example.yaml
@@ -922,6 +922,34 @@ endpoints:
# completionReceiptBatching: true
# # Allow owners to cooperatively cancel ordinary background tools, including BYOM Bash.
# ordinaryToolCancellation: false
+ # # (optional) Show a conversation's pull request in the chat header. Off by default. It needs
+ # # a code worker built from LibreChat-AI/code-interpreter#311 or later that reports its
+ # # branch, with CODEAPI_BRIDGE_LANE_GIT=true set on the Code API; without both, every chat
+ # # simply shows no pull request. It also needs a GitHub token held on the server. Use a
+ # # fine-grained token limited to the repositories involved, with read-only "Pull requests",
+ # # "Checks" and "Contents" permissions. Without "Checks" every matched pull request fails to
+ # # load, and without "Contents" a chat whose branch has moved on since its last command does.
+ # pullRequests:
+ # enabled: false
+ # # Environment variable reference only, never the token itself.
+ # token: "${GITHUB_PULL_REQUEST_TOKEN}"
+ # # Repositories the token may be used for, as owner/name or owner/*. Required: a worker
+ # # reports its own repository, and only these are ever looked up with the server's token.
+ # allowedRepositories: ["LibreChat-AI/LibreChat"]
+ # # Seconds a looked-up pull request is reused before GitHub is asked again (5 to 3600).
+ # cacheTtlSeconds: 30
+ # # Results cached per credential before the oldest is evicted (10 to 100000). Raise it when many
+ # # repositories and branches are active at once, or fresh results are evicted and GitHub is asked again.
+ # cacheMaxEntries: 500
+ # # Credentials cached at once (1 to 10000), deployment-wide; the one idle longest is dropped
+ # # past it. When principals configure different values, the largest applies.
+ # cacheMaxCredentials: 256
+ # # Bounds on one lookup. A repository with many check runs reads one page of 100 per request.
+ # requestTimeoutSeconds: 10 # longest single GitHub request (1 to 60)
+ # lookupTimeoutSeconds: 30 # longest the whole lookup may take (1 to 120)
+ # maxCheckRunPages: 10 # pages read before checks are reported as running (1 to 50)
+ # maxCandidatePullRequests: 10 # pull requests listed per state when matching a reused branch (1 to 100)
+ # maxHeadComparisons: 3 # candidates compared with the chat's last commit (0 to 20)
# # "run_in_background" makes Code Interpreter tools eligible by default and enables per-tool MCP opt-in.
# # "tool_intents" enables live model-written labels for native tools and opted-in MCP tools.
# # (optional) Require user approval before matching tool calls. Disabled by default.
diff --git a/packages/api/src/code/command.ts b/packages/api/src/code/command.ts
index 88154a05d5..593f96d294 100644
--- a/packages/api/src/code/command.ts
+++ b/packages/api/src/code/command.ts
@@ -14,7 +14,11 @@ import type {
import type { createBashProgrammaticToolCallingSchema } from '@librechat/agents';
import type { DynamicStructuredTool } from '@librechat/agents/langchain/tools';
import type { LCTool } from '@librechat/agents';
-import type { WorkspaceAdmissionOptions, WorkspaceExecuteCommandResult } from './workspace';
+import type {
+ WorkspaceAdmissionOptions,
+ WorkspaceExecuteCommandResult,
+ WorkspaceLaneGit,
+} from './workspace';
import type { CodeExecutionContext } from '~/agents/execution';
import type { CodeBridgeFetch } from './bridge';
import {
@@ -468,11 +472,15 @@ export function createAttachedWorkspaceBashTool({
minCommandAdmissionMs,
linkedWorktrees = false,
nativeSandbox = false,
+ onLaneGit,
fetchImpl,
}: {
baseUrl: string;
authHeaders: () => Promise<Record<string, string>> | Record<string, string>;
workspaceId: string;
+ /** Receives the lane's branch and head when a finished command reports them. It is not awaited
+ * and must not throw: a failure here never changes the command's result. */
+ onLaneGit?: (laneGit: WorkspaceLaneGit) => void;
workspaceInstanceId?: string;
/** The worker runs each `.worktrees/<name>` in its own lane; a matching `cwd` is routed there. */
linkedWorktrees?: boolean;
@@ -609,6 +617,7 @@ export function createAttachedWorkspaceBashTool({
throw new Error('Attached workspace returned an unexpected command result.');
}
logger.debug('[BYOMCommand] transport completed', trace);
+ if (result.laneGit != null) onLaneGit?.(result.laneGit);
let content = formatCommandResult(
result,
selectedTimeoutMs,
diff --git a/packages/api/src/code/index.ts b/packages/api/src/code/index.ts
index 237e3a0456..b6adfe6825 100644
--- a/packages/api/src/code/index.ts
+++ b/packages/api/src/code/index.ts
@@ -5,6 +5,7 @@ export * from './bridge';
export * from './lifecycle';
export * from './workspace';
export * from './command';
+export * from './lane';
export * from './capabilities';
export * from './decision';
export * from './inheritance';
diff --git a/packages/api/src/code/lane.spec.ts b/packages/api/src/code/lane.spec.ts
new file mode 100644
index 0000000000..922003e573
--- /dev/null
+++ b/packages/api/src/code/lane.spec.ts
@@ -0,0 +1,607 @@
+import { logger } from '@librechat/data-schemas';
+import type { CodeBridgeFetch } from './bridge';
+import { createLaneGitRecorder as createRecorder } from './lane';
+import { createAttachedWorkspaceBashTool } from './command';
+
+jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
+ logger: { warn: jest.fn(), debug: jest.fn(), info: jest.fn(), error: jest.fn() },
+}));
+
+type RecorderOptions = Parameters<typeof createRecorder>[0];
+
+/** Places the recorder once, as the tool does, then reports through it in call order. */
+const createLaneGitRecorder = (options: Omit<RecorderOptions, 'enabled'>) => {
+ const ready = createRecorder({ enabled: true, ...options });
+ return (laneGit: Parameters<NonNullable<Awaited<typeof ready>>>[0]) =>
+ ready.then((record) => (record ? record(laneGit) : false));
+};
+
+const head = 'a'.repeat(40);
+const laneGit = { branch: 'feat/pr-chip', head };
+
+/** A reserver that hands out 1, 2, 3 ... like the database counter does. */
+const counter = () => {
+ let next = 0;
+ return jest.fn(async () => ++next);
+};
+
+describe('createLaneGitRecorder', () => {
+ const make = (overrides: Record<string, unknown> = {}) => {
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const reserveConvoLaneGitSeq = counter();
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'c1',
+ reserveConvoLaneGitSeq,
+ setConvoLaneGit,
+ ...overrides,
+ });
+ return { record, setConvoLaneGit, reserveConvoLaneGitSeq };
+ };
+
+ it('writes the reported state with a reserved sequence number', async () => {
+ const { record, setConvoLaneGit, reserveConvoLaneGitSeq } = make();
+ await expect(record?.(laneGit)).resolves.toBe(true);
+ expect(reserveConvoLaneGitSeq).toHaveBeenCalledWith('u1', 'c1');
+ expect(setConvoLaneGit).toHaveBeenCalledWith({
+ user: 'u1',
+ conversationId: 'c1',
+ laneGit,
+ seq: 1,
+ });
+ });
+
+ it.each([
+ ['a missing user', { user: undefined, conversationId: 'c1' }],
+ ['an empty user', { user: '', conversationId: 'c1' }],
+ ['a missing conversation', { user: 'u1', conversationId: undefined }],
+ ['an empty conversation', { user: 'u1', conversationId: '' }],
+ ])('does not record with %s', async (_label, ids) => {
+ const setConvoLaneGit = jest.fn();
+ const record = await createRecorder({
+ enabled: true,
+ ...ids,
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ } as RecorderOptions);
+ expect(record).toBeUndefined();
+ expect(setConvoLaneGit).not.toHaveBeenCalled();
+ });
+
+ it('stores a plain owner/name repository with the lane', async () => {
+ const { record, setConvoLaneGit } = make({ repo: 'LibreChat-AI/LibreChat' });
+ await record?.(laneGit);
+ expect(setConvoLaneGit).toHaveBeenCalledWith(
+ expect.objectContaining({ repo: 'LibreChat-AI/LibreChat' }),
+ );
+ });
+
+ it.each(['../x', 'o/..', 'a b/c', 'owner', 'o/r/extra', 'x'.repeat(300)])(
+ 'drops the unsafe repository %s but still records the lane',
+ async (repo) => {
+ const { record, setConvoLaneGit } = make({ repo });
+ await record?.(laneGit);
+ expect(setConvoLaneGit).toHaveBeenCalledTimes(1);
+ expect(setConvoLaneGit.mock.calls[0][0]).not.toHaveProperty('repo');
+ },
+ );
+
+ it('swallows a write failure and logs only safe metadata', async () => {
+ const setConvoLaneGit = jest.fn().mockRejectedValue(new Error('mongodb://user:secret@host'));
+ const { record } = make({ setConvoLaneGit });
+ await expect(record?.(laneGit)).resolves.toBe(false);
+ expect(logger.warn).toHaveBeenCalledTimes(1);
+ expect(JSON.stringify((logger.warn as jest.Mock).mock.calls)).not.toContain('secret');
+ });
+
+ it('swallows a reservation failure and writes nothing', async () => {
+ const reserveConvoLaneGitSeq = jest.fn().mockRejectedValue(new Error('mongodb://u:secret@h'));
+ const { record, setConvoLaneGit } = make({ reserveConvoLaneGitSeq });
+ await expect(record?.(laneGit)).resolves.toBe(false);
+ expect(setConvoLaneGit).not.toHaveBeenCalled();
+ expect(JSON.stringify((logger.warn as jest.Mock).mock.calls)).not.toContain('secret');
+ });
+
+ it('writes nothing when the conversation is not saved yet', async () => {
+ const { record, setConvoLaneGit } = make({
+ reserveConvoLaneGitSeq: jest.fn().mockResolvedValue(null),
+ });
+ await expect(record?.(laneGit)).resolves.toBe(false);
+ expect(setConvoLaneGit).not.toHaveBeenCalled();
+ });
+});
+
+describe('attached bash tool lane reporting', () => {
+ const response = (extra: Record<string, unknown> = {}) =>
+ Response.json({
+ protocolVersion: 1,
+ operation: 'execute_command',
+ workspaceId: 'project-a',
+ exitCode: 0,
+ stdout: 'ok',
+ stderr: '',
+ truncated: false,
+ timedOut: false,
+ ...extra,
+ });
+ const build = (fetchImpl: CodeBridgeFetch, onLaneGit?: jest.Mock) =>
+ createAttachedWorkspaceBashTool({
+ baseUrl: 'https://code.example.com/v1',
+ authHeaders: () => ({}),
+ workspaceId: 'project-a',
+ onLaneGit,
+ fetchImpl,
+ });
+
+ it('hands the reported branch and head to the recorder', async () => {
+ const onLaneGit = jest.fn();
+ await build(
+ jest.fn(async () => response({ laneGit })),
+ onLaneGit,
+ ).invoke({ command: 'git status' });
+ expect(onLaneGit).toHaveBeenCalledWith(laneGit);
+ });
+
+ it('hands over a detached lane as nulls, not as unknown', async () => {
+ const onLaneGit = jest.fn();
+ const detached = { branch: null, head: null };
+ await build(
+ jest.fn(async () => response({ laneGit: detached })),
+ onLaneGit,
+ ).invoke({ command: 'git status' });
+ expect(onLaneGit).toHaveBeenCalledWith(detached);
+ });
+
+ it('does not call the recorder when the worker sent no laneGit', async () => {
+ const onLaneGit = jest.fn();
+ await build(
+ jest.fn(async () => response()),
+ onLaneGit,
+ ).invoke({ command: 'ls' });
+ expect(onLaneGit).not.toHaveBeenCalled();
+ });
+
+ it('still returns the command output when no recorder is configured', async () => {
+ const output = await build(jest.fn(async () => response({ laneGit }))).invoke({
+ command: 'ls',
+ });
+ expect(String(output)).toContain('ok');
+ });
+});
+
+describe('createLaneGitRecorder ordering', () => {
+ const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+
+ it('takes sequence numbers in report order and writes each with its own', async () => {
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-1',
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ });
+ await Promise.all([record?.({ branch: 'a', head }), record?.({ branch: 'b', head })]);
+ const writes = setConvoLaneGit.mock.calls.map(([call]) => [call.laneGit.branch, call.seq]);
+ expect(writes.sort()).toEqual([
+ ['a', 1],
+ ['b', 2],
+ ]);
+ });
+
+ it('gives a later report the higher number even when the first reservation is slow', async () => {
+ let issued = 0;
+ const releases: Array<() => void> = [];
+ /** The first reservation takes longer than any later one, as a slow replica round trip can. */
+ const reserve = jest.fn(
+ () =>
+ new Promise<number>((resolve) => {
+ const slow = issued === 0;
+ issued += 1;
+ const number = issued;
+ if (slow) releases.push(() => resolve(number));
+ else resolve(number);
+ }),
+ );
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-slow',
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit,
+ });
+ const first = record?.({ branch: 'first', head });
+ const second = record?.({ branch: 'second', head });
+ await flush();
+ expect(reserve).toHaveBeenCalledTimes(1);
+ releases[0]();
+ await Promise.all([first, second]);
+ const bySeq = setConvoLaneGit.mock.calls
+ .map(([call]) => [call.seq, call.laneGit.branch])
+ .sort();
+ expect(bySeq).toEqual([
+ [1, 'first'],
+ [2, 'second'],
+ ]);
+ });
+
+ it('does not wait for one write to finish before reserving the next report', async () => {
+ const reserve = counter();
+ const releases: Array<() => void> = [];
+ const setConvoLaneGit = jest.fn(
+ () => new Promise<boolean>((resolve) => releases.push(() => resolve(true))),
+ );
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-2',
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit,
+ });
+ void record?.({ branch: 'a', head });
+ void record?.({ branch: 'b', head });
+ await flush();
+ expect(reserve).toHaveBeenCalledTimes(2);
+ expect(setConvoLaneGit).toHaveBeenCalledTimes(2);
+ releases.forEach((release) => release());
+ });
+
+ it('orders reservations across recorders built for the same conversation', async () => {
+ const reserve = counter();
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const make = () =>
+ createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-3',
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit,
+ });
+ await Promise.all([make()?.({ branch: 'a', head }), make()?.({ branch: 'b', head })]);
+ const bySeq = setConvoLaneGit.mock.calls
+ .map(([call]) => [call.seq, call.laneGit.branch])
+ .sort();
+ expect(bySeq).toEqual([
+ [1, 'a'],
+ [2, 'b'],
+ ]);
+ });
+
+ it('does not make one conversation or one user wait for another', async () => {
+ const releases: Array<() => void> = [];
+ const reserve = jest.fn(
+ () => new Promise<number>((resolve) => releases.push(() => resolve(1))),
+ );
+ const make = (user: string, conversationId: string) =>
+ createLaneGitRecorder({
+ user,
+ conversationId,
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit: jest.fn().mockResolvedValue(true),
+ });
+ void make('u1', 'order-4')?.({ branch: 'a', head });
+ void make('u1', 'order-5')?.({ branch: 'b', head });
+ void make('u2', 'order-4')?.({ branch: 'c', head });
+ await flush();
+ expect(reserve).toHaveBeenCalledTimes(3);
+ releases.forEach((release) => release());
+ });
+
+ it('keeps reserving after one reservation fails', async () => {
+ const reserve = jest.fn().mockRejectedValueOnce(new Error('db down')).mockResolvedValue(7);
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-6',
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit,
+ });
+ await expect(record?.({ branch: 'a', head })).resolves.toBe(false);
+ await expect(record?.({ branch: 'b', head })).resolves.toBe(true);
+ expect(setConvoLaneGit.mock.calls[0][0]).toMatchObject({ seq: 7 });
+ });
+
+ it('reports a write the database rejected as not applied, so a stale report is not remembered', async () => {
+ const setConvoLaneGit = jest.fn().mockResolvedValueOnce(false).mockResolvedValue(true);
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-7',
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ });
+ await expect(record?.(laneGit)).resolves.toBe(false);
+ await expect(record?.(laneGit)).resolves.toBe(true);
+ expect(setConvoLaneGit).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not skip a report that repeats the last one, since another writer may have changed the lane', async () => {
+ const reserve = counter();
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-8',
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit,
+ });
+ await record?.(laneGit);
+ await record?.(laneGit);
+ expect(reserve).toHaveBeenCalledTimes(2);
+ expect(setConvoLaneGit).toHaveBeenCalledTimes(2);
+ });
+
+ it('lets a recorder restore its state after another recorder changed the same conversation', async () => {
+ const written: string[] = [];
+ const setConvoLaneGit = jest.fn(
+ async ({ laneGit: reported }: { laneGit: { branch: string | null } }) => {
+ written.push(String(reported.branch));
+ return true;
+ },
+ );
+ const reserve = counter();
+ const make = () =>
+ createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-shared',
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit,
+ });
+ const first = make();
+ const second = make();
+ await first?.({ branch: 'x', head });
+ await second?.({ branch: 'y', head });
+ await first?.({ branch: 'x', head });
+ expect(written).toEqual(['x', 'y', 'x']);
+ });
+
+ it('writes again once the state changes, including back to an earlier one', async () => {
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'order-9',
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ });
+ await record?.({ branch: 'a', head });
+ await record?.({ branch: 'b', head });
+ await record?.({ branch: 'a', head });
+ expect(setConvoLaneGit.mock.calls.map(([call]) => call.laneGit.branch)).toEqual([
+ 'a',
+ 'b',
+ 'a',
+ ]);
+ });
+
+ it('orders reservations by the visible conversation two subagent threads share', async () => {
+ const releases: Array<() => void> = [];
+ const reserve = jest.fn(
+ () => new Promise<number>((resolve) => releases.push(() => resolve(releases.length))),
+ );
+ const getConvoLaneContext = jest
+ .fn()
+ .mockResolvedValue({ subagentThread: { rootConversationId: 'shared-root' } });
+ const make = (conversationId: string) =>
+ createLaneGitRecorder({
+ user: 'u1',
+ conversationId,
+ workspace: { environmentId: 'code-mac', workspaceId: 'primary' },
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit: jest.fn().mockResolvedValue(true),
+ });
+ void make('child-a')?.({ branch: 'a', head });
+ void make('child-b')?.({ branch: 'b', head });
+ await flush();
+ expect(reserve).toHaveBeenCalledTimes(1);
+ releases[0]();
+ await flush();
+ expect(reserve).toHaveBeenCalledTimes(2);
+ releases[1]();
+ });
+
+ it('does not make threads of different visible conversations wait for each other', async () => {
+ const releases: Array<() => void> = [];
+ const reserve = jest.fn(
+ () => new Promise<number>((resolve) => releases.push(() => resolve(1))),
+ );
+ const getConvoLaneContext = jest.fn(async (_user: string, id: string) => ({
+ subagentThread: { rootConversationId: id === 'child-a' ? 'root-a' : 'root-b' },
+ }));
+ const make = (conversationId: string) =>
+ createLaneGitRecorder({
+ user: 'u1',
+ conversationId,
+ workspace: { environmentId: 'code-mac', workspaceId: 'primary' },
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit: jest.fn().mockResolvedValue(true),
+ });
+ void make('child-a')?.({ branch: 'a', head });
+ void make('child-b')?.({ branch: 'b', head });
+ await flush();
+ expect(reserve).toHaveBeenCalledTimes(2);
+ releases.forEach((release) => release());
+ });
+});
+
+describe('createLaneGitRecorder target conversation', () => {
+ const workspace = { environmentId: 'code-mac', workspaceId: 'primary' };
+ const build = (overrides: Record<string, unknown> = {}) => {
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const reserveConvoLaneGitSeq = counter();
+ const record = createLaneGitRecorder({
+ user: 'u1',
+ conversationId: 'target-1',
+ workspace,
+ reserveConvoLaneGitSeq,
+ setConvoLaneGit,
+ ...overrides,
+ });
+ return { record, setConvoLaneGit, reserveConvoLaneGitSeq };
+ };
+ const written = (setConvoLaneGit: jest.Mock) => setConvoLaneGit.mock.calls.map(([call]) => call);
+
+ it('passes the workspace it ran in, so a stale writer can be fenced', async () => {
+ const { record, setConvoLaneGit } = build();
+ await record(laneGit);
+ expect(written(setConvoLaneGit)[0]).toMatchObject({
+ conversationId: 'target-1',
+ workspace: { ...workspace },
+ });
+ expect(written(setConvoLaneGit)[0].workspace.required).not.toBe(true);
+ });
+
+ it('records a subagent thread on the visible conversation, and requires its workspace to match', async () => {
+ const getConvoLaneContext = jest.fn().mockResolvedValue({
+ subagentThread: { rootConversationId: 'visible-root', parentConversationId: 'mid' },
+ codeAttachmentEpoch: 0,
+ });
+ const { record, setConvoLaneGit, reserveConvoLaneGitSeq } = build({
+ conversationId: 'child-thread',
+ getConvoLaneContext,
+ });
+ await record(laneGit);
+ expect(getConvoLaneContext).toHaveBeenCalledWith('u1', 'child-thread');
+ expect(reserveConvoLaneGitSeq).toHaveBeenCalledWith('u1', 'visible-root');
+ expect(written(setConvoLaneGit)[0]).toMatchObject({
+ conversationId: 'visible-root',
+ workspace: { ...workspace, required: true },
+ });
+ });
+
+ it('records an ordinary conversation on itself', async () => {
+ const getConvoLaneContext = jest.fn().mockResolvedValue({ codeAttachmentEpoch: 0 });
+ const { record, setConvoLaneGit } = build({ conversationId: 'plain', getConvoLaneContext });
+ await record(laneGit);
+ expect(written(setConvoLaneGit)[0].conversationId).toBe('plain');
+ });
+
+ it('looks the conversation up once however many reports follow', async () => {
+ const getConvoLaneContext = jest.fn().mockResolvedValue({
+ subagentThread: { rootConversationId: 'visible-root' },
+ codeAttachmentEpoch: 0,
+ });
+ const { record, setConvoLaneGit } = build({ conversationId: 'child-2', getConvoLaneContext });
+ await record({ branch: 'a', head });
+ await record({ branch: 'b', head });
+ expect(getConvoLaneContext).toHaveBeenCalledTimes(1);
+ expect(written(setConvoLaneGit).map((call) => call.conversationId)).toEqual([
+ 'visible-root',
+ 'visible-root',
+ ]);
+ });
+
+ it('records nothing when it cannot place the conversation, rather than guess', async () => {
+ const getConvoLaneContext = jest
+ .fn()
+ .mockRejectedValue(new Error('mongodb://user:secret@host'));
+ const setConvoLaneGit = jest.fn();
+ const record = await createRecorder({
+ enabled: true,
+ user: 'u1',
+ conversationId: 'child-3',
+ workspace,
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ });
+ expect(record).toBeUndefined();
+ expect(setConvoLaneGit).not.toHaveBeenCalled();
+ expect(JSON.stringify((logger.warn as jest.Mock).mock.calls)).not.toContain('secret');
+ });
+
+ it('does not write a subagent lane to the parent without a workspace to verify it against', async () => {
+ const getConvoLaneContext = jest.fn().mockResolvedValue({
+ subagentThread: { rootConversationId: 'visible-root' },
+ codeAttachmentEpoch: 0,
+ });
+ const setConvoLaneGit = jest.fn();
+ const record = await createRecorder({
+ enabled: true,
+ user: 'u1',
+ conversationId: 'child-4',
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ });
+ expect(record).toBeUndefined();
+ expect(setConvoLaneGit).not.toHaveBeenCalled();
+ });
+
+ it('places a conversation that is not saved yet on itself at epoch 0', async () => {
+ const getConvoLaneContext = jest.fn().mockResolvedValue(null);
+ const { record, setConvoLaneGit } = build({ getConvoLaneContext });
+ await record(laneGit);
+ expect(written(setConvoLaneGit)[0]).toMatchObject({
+ conversationId: 'target-1',
+ workspace: { ...workspace, epoch: 0 },
+ });
+ });
+});
+
+describe('createLaneGitRecorder placement timing', () => {
+ const flush = () => new Promise<void>((resolve) => setImmediate(resolve));
+ const workspace = { environmentId: 'code-mac', workspaceId: 'primary' };
+
+ it('settles placement before any report, so a slow lookup cannot reorder reports', async () => {
+ let release: () => void = () => undefined;
+ const getConvoLaneContext = jest.fn(
+ () =>
+ new Promise<{ codeAttachmentEpoch: number }>((resolve) => {
+ release = () => resolve({ codeAttachmentEpoch: 0 });
+ }),
+ );
+ const reserve = counter();
+ const pending = createRecorder({
+ enabled: true,
+ user: 'u1',
+ conversationId: 'slow-lookup',
+ workspace,
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq: reserve,
+ setConvoLaneGit: jest.fn().mockResolvedValue(true),
+ });
+ await flush();
+ expect(reserve).not.toHaveBeenCalled();
+ release();
+ const record = await pending;
+ expect(record).toBeDefined();
+ await record?.({ branch: 'a', head });
+ expect(reserve).toHaveBeenCalledTimes(1);
+ });
+
+ it('carries the epoch read at creation into every write, even if the chat moves later', async () => {
+ const getConvoLaneContext = jest.fn().mockResolvedValue({ codeAttachmentEpoch: 3 });
+ const setConvoLaneGit = jest.fn().mockResolvedValue(true);
+ const record = await createRecorder({
+ enabled: true,
+ user: 'u1',
+ conversationId: 'epoch-1',
+ workspace,
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq: counter(),
+ setConvoLaneGit,
+ });
+ await record?.({ branch: 'a', head });
+ await record?.({ branch: 'b', head });
+ expect(setConvoLaneGit.mock.calls.map(([call]) => call.workspace.epoch)).toEqual([3, 3]);
+ expect(getConvoLaneContext).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('createLaneGitRecorder when pull requests are off', () => {
+ it('reads and records nothing', async () => {
+ const getConvoLaneContext = jest.fn();
+ const reserveConvoLaneGitSeq = counter();
+ const setConvoLaneGit = jest.fn();
+ const record = await createRecorder({
+ enabled: false,
+ user: 'u1',
+ conversationId: 'off-1',
+ workspace: { environmentId: 'code-mac', workspaceId: 'primary' },
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq,
+ setConvoLaneGit,
+ });
+ expect(record).toBeUndefined();
+ expect(getConvoLaneContext).not.toHaveBeenCalled();
+ expect(reserveConvoLaneGitSeq).not.toHaveBeenCalled();
+ });
+});
diff --git a/packages/api/src/code/lane.ts b/packages/api/src/code/lane.ts
new file mode 100644
index 0000000000..61368ecb27
--- /dev/null
+++ b/packages/api/src/code/lane.ts
@@ -0,0 +1,168 @@
+import { logger } from '@librechat/data-schemas';
+import type { WorkspaceLaneGit } from './workspace';
+import { getSafeErrorMetadata } from '~/utils';
+
+/**
+ * The workspace a command ran in. `required` demands the conversation have it recorded, and
+ * `epoch` is the attachment epoch read when the tool was created.
+ */
+export type LaneWorkspace = {
+ environmentId: string;
+ workspaceId: string;
+ required?: boolean;
+ epoch?: number;
+};
+
+export type LaneGitWriter = (input: {
+ user: string;
+ conversationId: string;
+ laneGit: WorkspaceLaneGit;
+ repo?: string;
+ /** Reserved when the command settled; the database ignores a report below the one it holds. */
+ seq: number;
+ /** The database ignores the report once the conversation is no longer on this workspace. */
+ workspace?: LaneWorkspace;
+}) => Promise<boolean>;
+
+/** Draws the next report sequence number from the database, so every replica shares one order. */
+export type LaneSeqReserver = (user: string, conversationId: string) => Promise<number | null>;
+
+/**
+ * Reads what the recorder needs to place and fence its reports: the subagent route of the
+ * conversation and its workspace attachment epoch. Null when the conversation is not saved yet.
+ */
+export type LaneContextReader = (
+ user: string,
+ conversationId: string,
+) => Promise<{
+ subagentThread?: { rootConversationId?: string | null } | null;
+ codeAttachmentEpoch?: number;
+} | null>;
+
+const REPO_PATTERN = /^[A-Za-z0-9_.-]+\/[A-Za-z0-9_.-]+$/;
+const MAX_REPO_LENGTH = 256;
+
+const isSafeRepo = (repo: string | undefined): repo is string =>
+ repo != null &&
+ repo.length <= MAX_REPO_LENGTH &&
+ REPO_PATTERN.test(repo) &&
+ repo.split('/').every((segment) => segment !== '.' && segment !== '..');
+
+type Placement = { conversationId: string; required: boolean; epoch: number };
+type Reservation = Placement & { seq: number };
+
+/**
+ * The tail of each visible conversation's pending sequence reservations in this process, keyed by
+ * the conversation the write lands on (the root of a subagent thread, not the thread). Two
+ * threads of one conversation therefore share a chain, and numbers are drawn one at a time in
+ * report order, so one process never takes a lower number for a later report. Writes are not
+ * queued: each carries its number and the database ignores a lower one, so a slow or reordered
+ * write cannot replace a newer state, here or on another replica. Entries leave the map as soon
+ * as their chain drains.
+ */
+const reservationTails = new Map<string, Promise<unknown>>();
+
+/**
+ * Builds the recorder for one tool, placing it once, here, so no report waits on a lookup that
+ * could let a later report take an earlier turn. The conversation's route and attachment epoch
+ * are read when the tool is created: a subagent thread is a hidden child of the conversation the
+ * user sees, its commands run on the parent's machine, so its lane belongs to the visible root
+ * and that write must match the root's recorded workspace; the epoch fences out a report that
+ * outlives a move of the workspace, even one that moved away and back. A conversation not saved
+ * yet is placed on itself at epoch 0. When the context cannot be read nothing is recorded: the
+ * branch is a header affordance, so a database outage never fails or delays the tool call.
+ * Resolves to undefined when there is nothing to record against.
+ */
+export async function createLaneGitRecorder({
+ enabled,
+ user,
+ conversationId,
+ repo,
+ workspace,
+ getConvoLaneContext,
+ reserveConvoLaneGitSeq,
+ setConvoLaneGit,
+}: {
+ /** Whether the deployment shows pull requests; when it does not, nothing is read or recorded. */
+ enabled: boolean;
+ user: string | undefined;
+ conversationId: string | undefined;
+ repo?: string;
+ workspace?: { environmentId: string; workspaceId: string };
+ getConvoLaneContext?: LaneContextReader;
+ reserveConvoLaneGitSeq: LaneSeqReserver;
+ setConvoLaneGit: LaneGitWriter;
+}): Promise<((laneGit: WorkspaceLaneGit) => Promise<boolean>) | undefined> {
+ if (!enabled || !user || !conversationId) return undefined;
+ const safeRepo = isSafeRepo(repo) ? repo : undefined;
+
+ let placed: Placement;
+ try {
+ const context = getConvoLaneContext ? await getConvoLaneContext(user, conversationId) : null;
+ const root = context?.subagentThread?.rootConversationId;
+ placed = {
+ conversationId: root || conversationId,
+ required: Boolean(root),
+ epoch: context?.codeAttachmentEpoch ?? 0,
+ };
+ } catch (error) {
+ logger.warn('[LaneGit] Failed to place a lane recorder', getSafeErrorMetadata(error));
+ return undefined;
+ }
+ if (placed.required && workspace == null) return undefined;
+ const queueKey = `${user}\0${placed.conversationId}`;
+
+ /** Never rejects, so a failed reservation cannot stall the ones queued behind it. */
+ const reserve = async (): Promise<Reservation | null> => {
+ try {
+ const seq = await reserveConvoLaneGitSeq(user, placed.conversationId);
+ return seq == null ? null : { ...placed, seq };
+ } catch (error) {
+ logger.warn('[LaneGit] Failed to reserve a lane report', getSafeErrorMetadata(error));
+ return null;
+ }
+ };
+
+ const write = async (laneGit: WorkspaceLaneGit, reserved: Reservation): Promise<boolean> => {
+ try {
+ return await setConvoLaneGit({
+ user,
+ conversationId: reserved.conversationId,
+ laneGit,
+ ...(safeRepo ? { repo: safeRepo } : {}),
+ seq: reserved.seq,
+ ...(workspace
+ ? {
+ workspace: {
+ ...workspace,
+ ...(reserved.required ? { required: true } : {}),
+ epoch: reserved.epoch,
+ },
+ }
+ : {}),
+ });
+ } catch (error) {
+ logger.warn('[LaneGit] Failed to record lane state', getSafeErrorMetadata(error));
+ return false;
+ }
+ };
+
+ /**
+ * Fire-and-forget for the command: it never throws and is never awaited. Each report takes its
+ * sequence number from the database in report order and is written with it, so the newest report
+ * wins whatever order the writes land in. Every report is written, repeats included, because
+ * another recorder (a sibling thread, another replica) may have changed the lane since this one
+ * last wrote, and the database already ignores a write that changes nothing the reader can see.
+ * Resolves to whether the write applied, which is false when a newer report is already stored
+ * and for a conversation not saved yet. A repo that is not a plain `owner/name` is dropped.
+ */
+ return (laneGit) => {
+ const previous = reservationTails.get(queueKey) ?? Promise.resolve();
+ const reservation = previous.then(() => reserve());
+ reservationTails.set(queueKey, reservation);
+ void reservation.then(() => {
+ if (reservationTails.get(queueKey) === reservation) reservationTails.delete(queueKey);
+ });
+ return reservation.then((reserved) => (reserved == null ? false : write(laneGit, reserved)));
+ };
+}
diff --git a/packages/api/src/index.ts b/packages/api/src/index.ts
index b5d05ebf3f..54ba5cd185 100644
--- a/packages/api/src/index.ts
+++ b/packages/api/src/index.ts
@@ -11,6 +11,7 @@ export * from './artifacts';
export * from './admin';
export * from './cdn';
export * from './code';
+export * from './pulls';
/* Auth */
export * from './auth';
/* API Keys */
diff --git a/packages/api/src/pulls/github.spec.ts b/packages/api/src/pulls/github.spec.ts
new file mode 100644
index 0000000000..2351923b34
--- /dev/null
+++ b/packages/api/src/pulls/github.spec.ts
@@ -0,0 +1,679 @@
+import { createGitHubPullRequestSource, summarizeChecks } from './github';
+import { PullRequestSourceError } from './types';
+
+const sha = 'a'.repeat(40);
+const pull = (overrides: Record<string, unknown> = {}) => ({
+ number: 7,
+ title: 'Simplify single tool',
+ html_url: 'https://github.com/o/r/pull/7',
+ state: 'open',
+ merged: false,
+ draft: false,
+ additions: 12,
+ deletions: 3,
+ mergeable: true,
+ head: { sha },
+ ...overrides,
+});
+const listed = (state = 'open') => [{ number: 7, state, head: { sha } }];
+const json = (body: unknown, init?: ResponseInit) => Response.json(body, init);
+
+function sourceFor(routes: Record<string, () => Response>) {
+ const fetchFn = jest.fn(async (input: string) => {
+ const url = String(input);
+ const key = Object.keys(routes).find((fragment) => url.includes(fragment));
+ /** Unless a test says otherwise, no pull request carries the recorded commit. */
+ if (key == null && /\/commits\/[a-f0-9]+\/pulls\?/.test(url)) return json([]);
+ if (key == null) throw new Error(`unexpected ${url}`);
+ return routes[key]();
+ });
+ return { fetchFn, source: createGitHubPullRequestSource({ fetchFn }) };
+}
+
+const find = (source: ReturnType<typeof createGitHubPullRequestSource>) =>
+ source.find({ repo: 'o/r', branch: 'feat/x', token: 't' });
+
+describe('summarizeChecks', () => {
+ it.each([
+ ['none', []],
+ ['passing', [{ status: 'completed', conclusion: 'success' }]],
+ ['passing', [{ status: 'completed', conclusion: 'skipped' }]],
+ ['running', [{ status: 'in_progress', conclusion: null }]],
+ ['failing', [{ status: 'completed', conclusion: 'failure' }]],
+ [
+ 'failing',
+ [
+ { status: 'in_progress', conclusion: null },
+ { status: 'completed', conclusion: 'timed_out' },
+ ],
+ ],
+ ])('reports %s', (expected, runs) => {
+ expect(summarizeChecks(runs)).toBe(expected);
+ });
+});
+
+describe('createGitHubPullRequestSource', () => {
+ const routes = (pullBody = pull(), checks: unknown = { check_runs: [] }) => ({
+ '/pulls?state=open': () => json(listed()),
+ '/pulls/7': () => json(pullBody),
+ '/check-runs': () => json(checks),
+ });
+
+ it('maps an open, mergeable pull request with passing checks', async () => {
+ const { source } = sourceFor(
+ routes(pull(), { check_runs: [{ status: 'completed', conclusion: 'success' }] }),
+ );
+ await expect(find(source)).resolves.toEqual({
+ number: 7,
+ title: 'Simplify single tool',
+ url: 'https://github.com/o/r/pull/7',
+ additions: 12,
+ deletions: 3,
+ state: 'open',
+ isDraft: false,
+ mergeable: 'clean',
+ checks: 'passing',
+ });
+ });
+
+ it('reports conflicts only while the pull request is open', async () => {
+ const open = sourceFor(routes(pull({ mergeable: false })));
+ await expect(find(open.source)).resolves.toMatchObject({ mergeable: 'conflicting' });
+ const merged = sourceFor(routes(pull({ state: 'closed', merged: true, mergeable: false })));
+ await expect(find(merged.source)).resolves.toMatchObject({
+ state: 'merged',
+ mergeable: 'unknown',
+ });
+ });
+
+ it('keeps mergeable unknown while GitHub is still computing it', async () => {
+ const { source } = sourceFor(routes(pull({ mergeable: null })));
+ await expect(find(source)).resolves.toMatchObject({ mergeable: 'unknown' });
+ });
+
+ it('carries draft state', async () => {
+ const { source } = sourceFor(routes(pull({ draft: true })));
+ await expect(find(source)).resolves.toMatchObject({ isDraft: true });
+ });
+
+ it('asks for the open pull request first, so closed history cannot hide it', async () => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json(listed()),
+ '/pulls/7': () => json(pull()),
+ '/check-runs': () => json({ check_runs: [] }),
+ });
+ await expect(find(source)).resolves.toMatchObject({ number: 7 });
+ const urls = fetchFn.mock.calls.map(([url]) => String(url));
+ expect(urls[0]).toContain('state=open');
+ expect(urls.some((url) => url.includes('state=closed'))).toBe(false);
+ });
+
+ it('falls back to the most recently updated closed pull request when none is open', async () => {
+ const { source } = sourceFor({
+ '/pulls?state=open': () => json([]),
+ '/pulls?state=closed': () => json([{ number: 9, state: 'closed', head: { sha } }]),
+ '/pulls/9': () => json(pull({ number: 9, state: 'closed', merged: true })),
+ '/check-runs': () => json({ check_runs: [] }),
+ });
+ await expect(find(source)).resolves.toMatchObject({ number: 9, state: 'merged' });
+ });
+
+ it('returns null when the branch has no pull request or the repository is not visible', async () => {
+ const none = sourceFor({
+ '/pulls?state=open': () => json([]),
+ '/pulls?state=closed': () => json([]),
+ });
+ await expect(find(none.source)).resolves.toBeNull();
+ const hidden = sourceFor({ '/pulls?state=open': () => new Response('', { status: 404 }) });
+ await expect(find(hidden.source)).resolves.toBeNull();
+ expect(hidden.fetchFn).toHaveBeenCalledTimes(1);
+ });
+
+ it('queries only a plain owner/name and never contacts GitHub otherwise', async () => {
+ const { source, fetchFn } = sourceFor({});
+ await expect(source.find({ repo: 'o/r', branch: '', token: 't' })).resolves.toBeNull();
+ for (const repo of ['../x', 'o/..', './x', 'o/.', 'a b/c', 'o', 'o/r/extra']) {
+ await expect(source.find({ repo, branch: 'main', token: 't' })).resolves.toBeNull();
+ }
+ expect(fetchFn).not.toHaveBeenCalled();
+ });
+
+ it('encodes the branch in the head filter', async () => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json([]),
+ '/pulls?state=closed': () => json([]),
+ });
+ await source.find({ repo: 'o/r', branch: 'feat/a&b=c', token: 't' });
+ const url = String(fetchFn.mock.calls[0][0]);
+ expect(url).toContain('head=o%3Afeat%2Fa%26b%3Dc');
+ });
+
+ it.each([
+ ['a 429', new Response('', { status: 429 })],
+ [
+ 'a 403 with no quota left',
+ new Response('', { status: 403, headers: { 'x-ratelimit-remaining': '0' } }),
+ ],
+ ])('maps %s to RATE_LIMITED', async (_label, response) => {
+ const { source } = sourceFor({ '/pulls?state=open': () => response });
+ await expect(find(source)).rejects.toMatchObject({ code: 'RATE_LIMITED' });
+ });
+
+ it.each([
+ ['a 500', () => new Response('boom', { status: 500 })],
+ ['a plain 403', () => new Response('', { status: 403 })],
+ ['a malformed list', () => json({ not: 'a list' })],
+ ])('maps %s to UPSTREAM_ERROR', async (_label, respond) => {
+ const { source } = sourceFor({ '/pulls?state=open': respond });
+ await expect(find(source)).rejects.toBeInstanceOf(PullRequestSourceError);
+ await expect(find(source)).rejects.toMatchObject({ code: 'UPSTREAM_ERROR' });
+ });
+
+ it('maps a network failure to UPSTREAM_ERROR without keeping its text', async () => {
+ const source = createGitHubPullRequestSource({
+ fetchFn: jest.fn().mockRejectedValue(new Error('connect ECONNREFUSED token=secret')),
+ });
+ const error = await find(source).catch((caught: Error) => caught);
+ expect(error).toMatchObject({ code: 'UPSTREAM_ERROR' });
+ expect(String((error as Error).message)).not.toContain('secret');
+ });
+
+ it.each([
+ ['a non-github host', 'https://evil.example/o/r/pull/7'],
+ ['a javascript url', 'javascript:alert(1)'],
+ ['plain http', 'http://github.com/o/r/pull/7'],
+ ])('rejects %s as the pull request page', async (_label, html_url) => {
+ const { source } = sourceFor(routes(pull({ html_url })));
+ await expect(find(source)).rejects.toMatchObject({ code: 'UPSTREAM_ERROR' });
+ });
+
+ it('bounds the title', async () => {
+ const { source } = sourceFor(routes(pull({ title: 'x'.repeat(1000) })));
+ const result = await find(source);
+ expect(result?.title).toHaveLength(256);
+ });
+});
+
+describe('check runs across pages', () => {
+ const run = (conclusion: string | null, status = 'completed') => ({ status, conclusion });
+ const passing = (count: number) => Array.from({ length: count }, () => run('success'));
+
+ function sourceWithPages(pages: unknown[][], totalCount: number) {
+ const fetchFn = jest.fn(async (input: string) => {
+ const url = String(input);
+ if (url.includes('/pulls?state=open')) return json(listed());
+ if (url.includes('/pulls/7')) return json(pull());
+ if (url.includes('/check-runs')) {
+ const page = Number(new URL(url).searchParams.get('page') ?? '1');
+ return json({ total_count: totalCount, check_runs: pages[page - 1] ?? [] });
+ }
+ throw new Error(`unexpected ${url}`);
+ });
+ return { fetchFn, source: createGitHubPullRequestSource({ fetchFn }) };
+ }
+
+ it('reads every page, so a failure past the first hundred still turns the rollup red', async () => {
+ const { source } = sourceWithPages([passing(100), [run('failure')]], 101);
+ await expect(find(source)).resolves.toMatchObject({ checks: 'failing' });
+ });
+
+ it('reads every page, so a check still running past the first hundred is not called passing', async () => {
+ const { source } = sourceWithPages([passing(100), [run(null, 'in_progress')]], 101);
+ await expect(find(source)).resolves.toMatchObject({ checks: 'running' });
+ });
+
+ it('stops after a bounded number of pages and never calls an incomplete rollup passing', async () => {
+ const pages = Array.from({ length: 60 }, () => passing(100));
+ const { source, fetchFn } = sourceWithPages(pages, 6000);
+ await expect(find(source)).resolves.toMatchObject({ checks: 'running' });
+ const checkCalls = fetchFn.mock.calls.filter(([url]) => String(url).includes('/check-runs'));
+ expect(checkCalls.length).toBeLessThanOrEqual(10);
+ });
+
+ it('makes one request when every check run fits on the first page', async () => {
+ const { source, fetchFn } = sourceWithPages([passing(3)], 3);
+ await expect(find(source)).resolves.toMatchObject({ checks: 'passing' });
+ const checkCalls = fetchFn.mock.calls.filter(([url]) => String(url).includes('/check-runs'));
+ expect(checkCalls).toHaveLength(1);
+ });
+});
+
+describe('rate limit back-off hint', () => {
+ it('carries retry-after as milliseconds', async () => {
+ const { source } = sourceFor({
+ '/pulls?state=open': () =>
+ new Response('', { status: 429, headers: { 'retry-after': '30' } }),
+ });
+ await expect(find(source)).rejects.toMatchObject({
+ code: 'RATE_LIMITED',
+ retryAfterMs: 30_000,
+ });
+ });
+
+ it('derives the wait from the quota reset when there is no retry-after', async () => {
+ const reset = Math.floor(Date.now() / 1000) + 120;
+ const { source } = sourceFor({
+ '/pulls?state=open': () =>
+ new Response('', {
+ status: 403,
+ headers: { 'x-ratelimit-remaining': '0', 'x-ratelimit-reset': String(reset) },
+ }),
+ });
+ const error = (await find(source).catch((caught: unknown) => caught)) as {
+ code: string;
+ retryAfterMs?: number;
+ };
+ expect(error.code).toBe('RATE_LIMITED');
+ expect(error.retryAfterMs).toBeGreaterThan(100_000);
+ expect(error.retryAfterMs).toBeLessThanOrEqual(120_000);
+ });
+
+ it('leaves the hint out when GitHub gives none', async () => {
+ const { source } = sourceFor({ '/pulls?state=open': () => new Response('', { status: 429 }) });
+ const error = (await find(source).catch((caught: unknown) => caught)) as {
+ retryAfterMs?: number;
+ };
+ expect(error.retryAfterMs).toBeUndefined();
+ });
+});
+
+describe('lookup bounds', () => {
+ const run = (conclusion: string | null, status = 'completed') => ({ status, conclusion });
+ const everyRoute = (url: string, checks: () => Response) => {
+ if (url.includes('/pulls?state=open')) return json(listed());
+ if (url.includes('/pulls/7')) return json(pull());
+ if (url.includes('/check-runs')) return checks();
+ throw new Error(`unexpected ${url}`);
+ };
+ const aborts = (init?: RequestInit) =>
+ new Promise<Response>((_resolve, reject) => {
+ init?.signal?.addEventListener('abort', () => reject(new Error('aborted')));
+ });
+
+ it('stops reading check runs at the configured page limit and calls the rollup incomplete', async () => {
+ const fetchFn = jest.fn(async (url: string) =>
+ everyRoute(url, () =>
+ json({ total_count: 6000, check_runs: Array.from({ length: 100 }, () => run('success')) }),
+ ),
+ );
+ const source = createGitHubPullRequestSource({ fetchFn });
+ const result = await source.find({
+ repo: 'o/r',
+ branch: 'feat/x',
+ token: 't',
+ limits: { maxCheckRunPages: 2 },
+ });
+ expect(result).toMatchObject({ checks: 'running' });
+ expect(fetchFn.mock.calls.filter(([url]) => String(url).includes('/check-runs'))).toHaveLength(
+ 2,
+ );
+ });
+
+ it('gives up on one request that outlives the configured request timeout', async () => {
+ const fetchFn = jest.fn((_url: string, init?: RequestInit) => aborts(init));
+ const source = createGitHubPullRequestSource({ fetchFn });
+ const started = Date.now();
+ await expect(
+ source.find({
+ repo: 'o/r',
+ branch: 'feat/x',
+ token: 't',
+ limits: { requestTimeoutMs: 20, lookupTimeoutMs: 5_000 },
+ }),
+ ).rejects.toMatchObject({ code: 'UPSTREAM_ERROR' });
+ expect(Date.now() - started).toBeLessThan(2_000);
+ });
+
+ it('bounds the whole lookup, not only each request', async () => {
+ let calls = 0;
+ const fetchFn = jest.fn((url: string, init?: RequestInit) => {
+ calls += 1;
+ if (calls === 1 && url.includes('/pulls?state=open')) return Promise.resolve(json(listed()));
+ return aborts(init);
+ });
+ const source = createGitHubPullRequestSource({ fetchFn });
+ const started = Date.now();
+ await expect(
+ source.find({
+ repo: 'o/r',
+ branch: 'feat/x',
+ token: 't',
+ limits: { requestTimeoutMs: 10_000, lookupTimeoutMs: 30 },
+ }),
+ ).rejects.toMatchObject({ code: 'UPSTREAM_ERROR' });
+ expect(Date.now() - started).toBeLessThan(2_000);
+ });
+
+ it("keeps today's defaults when no limits are given", async () => {
+ const seen: Array<AbortSignal | null | undefined> = [];
+ const fetchFn = jest.fn(async (url: string, init?: RequestInit) => {
+ seen.push(init?.signal);
+ return everyRoute(url, () => json({ total_count: 0, check_runs: [] }));
+ });
+ const source = createGitHubPullRequestSource({ fetchFn });
+ await expect(find(source)).resolves.toMatchObject({ number: 7 });
+ expect(seen.every((signal) => signal != null && !signal.aborted)).toBe(true);
+ });
+});
+
+describe('matching the recorded head', () => {
+ const recorded = 'c'.repeat(40);
+ const compare = (status: string) => () => json({ status });
+ const findWith = (
+ source: ReturnType<typeof createGitHubPullRequestSource>,
+ head?: string | null,
+ ) => source.find({ repo: 'o/r', branch: 'feat/x', head, token: 't' });
+
+ const routes = (status: string) => ({
+ '/pulls?state=open': () => json(listed()),
+ '/compare/': compare(status),
+ '/pulls/7': () => json(pull()),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+
+ it('accepts the pull request whose head is the recorded commit, without a comparison', async () => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json([{ number: 7, state: 'open', head: { sha: recorded } }]),
+ '/pulls/7': () => json(pull({ head: { sha: recorded } })),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+ await expect(findWith(source, recorded)).resolves.toMatchObject({ number: 7 });
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/compare/'))).toBe(false);
+ });
+
+ it.each(['ahead', 'identical'])(
+ 'accepts a pull request that is, or builds on, the recorded commit (%s)',
+ async (status) => {
+ const { source } = sourceFor(routes(status));
+ await expect(findWith(source, recorded)).resolves.toMatchObject({ number: 7 });
+ },
+ );
+
+ it('rejects a pull request whose head is older than the recorded commit (behind)', async () => {
+ const { source } = sourceFor({ ...routes('behind'), '/pulls?state=closed': () => json([]) });
+ await expect(findWith(source, recorded)).resolves.toBeNull();
+ });
+
+ it('asks GitHub to compare the recorded commit to the candidate, in that order', async () => {
+ const { source, fetchFn } = sourceFor(routes('ahead'));
+ await findWith(source, recorded);
+ const url = String(
+ fetchFn.mock.calls.map(([u]) => String(u)).find((u) => u.includes('/compare/')),
+ );
+ expect(url).toContain(`/compare/${recorded}...${sha}`);
+ });
+
+ it('rejects a pull request whose commits diverged from the recorded head', async () => {
+ const { source } = sourceFor({ ...routes('diverged'), '/pulls?state=closed': () => json([]) });
+ await expect(findWith(source, recorded)).resolves.toBeNull();
+ });
+
+ it('treats a recorded commit GitHub no longer knows as no match', async () => {
+ const { source } = sourceFor({
+ ...routes('ahead'),
+ '/compare/': () => new Response('', { status: 404 }),
+ '/pulls?state=closed': () => json([]),
+ });
+ await expect(findWith(source, recorded)).resolves.toBeNull();
+ });
+
+ it('falls back to a closed pull request that matches when the open one does not', async () => {
+ const { source } = sourceFor({
+ '/pulls?state=open': () => json([{ number: 9, state: 'open', head: { sha } }]),
+ '/pulls?state=closed': () => json([{ number: 7, state: 'closed', head: { sha: recorded } }]),
+ '/compare/': compare('diverged'),
+ '/pulls/7': () => json(pull({ state: 'closed', merged: true, head: { sha: recorded } })),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+ await expect(findWith(source, recorded)).resolves.toMatchObject({
+ number: 7,
+ state: 'merged',
+ });
+ });
+
+ it('compares as many candidates as configured, no more', async () => {
+ const many = Array.from({ length: 10 }, (_, index) => ({
+ number: index + 1,
+ state: 'open',
+ head: { sha },
+ }));
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json(many),
+ '/pulls?state=closed': () => json(many),
+ '/compare/': compare('diverged'),
+ });
+ await expect(
+ source.find({
+ repo: 'o/r',
+ branch: 'feat/x',
+ head: recorded,
+ token: 't',
+ limits: { maxHeadComparisons: 5 },
+ }),
+ ).resolves.toBeNull();
+ expect(fetchFn.mock.calls.filter(([u]) => String(u).includes('/compare/'))).toHaveLength(5);
+ });
+
+ it('lists as many candidate pull requests as configured', async () => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json([]),
+ '/pulls?state=closed': () => json([]),
+ });
+ await source.find({
+ repo: 'o/r',
+ branch: 'feat/x',
+ head: recorded,
+ token: 't',
+ limits: { maxCandidatePullRequests: 40 },
+ });
+ const urls = fetchFn.mock.calls.map(([u]) => String(u));
+ expect(urls.every((u) => u.includes('per_page=40'))).toBe(true);
+ });
+
+ it('limits how many candidates it compares', async () => {
+ const many = Array.from({ length: 10 }, (_, index) => ({
+ number: index + 1,
+ state: 'open',
+ head: { sha },
+ }));
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json(many),
+ '/pulls?state=closed': () => json(many),
+ '/compare/': compare('diverged'),
+ });
+ await expect(findWith(source, recorded)).resolves.toBeNull();
+ const compares = fetchFn.mock.calls.filter(([url]) => String(url).includes('/compare/'));
+ expect(compares.length).toBeLessThanOrEqual(3);
+ });
+
+ it.each([null, undefined])('does not compare when no head was recorded (%s)', async (head) => {
+ const { source, fetchFn } = sourceFor(routes('diverged'));
+ await expect(findWith(source, head)).resolves.toMatchObject({ number: 7 });
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/compare/'))).toBe(false);
+ });
+
+ it('ignores a recorded head that is not a commit id rather than putting it in a path', async () => {
+ const { source, fetchFn } = sourceFor(routes('diverged'));
+ await expect(findWith(source, '../../etc')).resolves.toMatchObject({ number: 7 });
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/compare/'))).toBe(false);
+ });
+});
+
+describe('check runs follow the current head of the pull request', () => {
+ const newer = 'd'.repeat(40);
+
+ it('reads checks for the head the detail reports, not the one the list saw', async () => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json(listed()),
+ '/pulls/7': () => json(pull({ head: { sha: newer } })),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+ await expect(find(source)).resolves.toMatchObject({ number: 7 });
+ const urls = fetchFn.mock.calls.map(([url]) => String(url));
+ expect(urls.some((url) => url.includes(`/commits/${newer}/check-runs`))).toBe(true);
+ expect(urls.some((url) => url.includes(`/commits/${sha}/check-runs`))).toBe(false);
+ });
+
+ it('reads the detail before the checks, so they describe the same commit', async () => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json(listed()),
+ '/pulls/7': () => json(pull()),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+ await find(source);
+ const urls = fetchFn.mock.calls.map(([url]) => String(url));
+ expect(urls.findIndex((url) => url.includes('/pulls/7'))).toBeLessThan(
+ urls.findIndex((url) => url.includes('/check-runs')),
+ );
+ });
+
+ it.each([
+ ['a missing head', { head: undefined }],
+ ['a head without a sha', { head: {} }],
+ ['a head that is not a commit id', { head: { sha: '../../x' } }],
+ ])('rejects a pull request detail with %s', async (_label, overrides) => {
+ const { source, fetchFn } = sourceFor({
+ '/pulls?state=open': () => json(listed()),
+ '/pulls/7': () => json(pull(overrides)),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+ await expect(find(source)).rejects.toMatchObject({ code: 'UPSTREAM_ERROR' });
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/check-runs'))).toBe(false);
+ });
+});
+
+describe('a head that moves after the candidate was listed', () => {
+ const recorded = 'c'.repeat(40);
+ const moved = 'd'.repeat(40);
+ const base = {
+ '/pulls?state=open': () => json([{ number: 7, state: 'open', head: { sha: recorded } }]),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ };
+ const run = (source: ReturnType<typeof createGitHubPullRequestSource>) =>
+ source.find({ repo: 'o/r', branch: 'feat/x', head: recorded, token: 't' });
+
+ it('returns nothing when the detail head no longer contains the recorded commit', async () => {
+ const { source } = sourceFor({
+ ...base,
+ '/compare/': () => json({ status: 'diverged' }),
+ '/pulls/7': () => json(pull({ head: { sha: moved } })),
+ });
+ await expect(run(source)).resolves.toBeNull();
+ });
+
+ it('keeps the pull request when the moved head still builds on the recorded commit', async () => {
+ const { source, fetchFn } = sourceFor({
+ ...base,
+ '/compare/': () => json({ status: 'ahead' }),
+ '/pulls/7': () => json(pull({ head: { sha: moved } })),
+ });
+ await expect(run(source)).resolves.toMatchObject({ number: 7 });
+ expect(
+ fetchFn.mock.calls.some(([url]) => String(url).includes(`/commits/${moved}/check-runs`)),
+ ).toBe(true);
+ });
+
+ it('spends the comparison budget on the moved head too, and stops when it is spent', async () => {
+ const { source, fetchFn } = sourceFor({
+ ...base,
+ '/compare/': () => json({ status: 'ahead' }),
+ '/pulls/7': () => json(pull({ head: { sha: moved } })),
+ });
+ await expect(
+ source.find({
+ repo: 'o/r',
+ branch: 'feat/x',
+ head: recorded,
+ token: 't',
+ limits: { maxHeadComparisons: 0 },
+ }),
+ ).resolves.toBeNull();
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/compare/'))).toBe(false);
+ });
+
+ it('does not compare again when the detail head is the one that matched', async () => {
+ const { source, fetchFn } = sourceFor({
+ ...base,
+ '/pulls/7': () => json(pull({ head: { sha: recorded } })),
+ });
+ await expect(run(source)).resolves.toMatchObject({ number: 7 });
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/compare/'))).toBe(false);
+ });
+});
+
+describe('a pull request whose head is in a fork', () => {
+ const recorded = 'c'.repeat(40);
+ const forked = (overrides: Record<string, unknown> = {}) => ({
+ number: 12,
+ state: 'open',
+ head: { sha: recorded, ref: 'feat/x' },
+ ...overrides,
+ });
+ const routes = (found: unknown[], status = 200) => ({
+ '/pulls?state=open': () => json([]),
+ '/pulls?state=closed': () => json([]),
+ '/pulls?per_page': () => json(found, { status }),
+ '/pulls/12': () => json(pull({ number: 12, head: { sha: recorded } })),
+ });
+ const run = (source: ReturnType<typeof createGitHubPullRequestSource>) =>
+ source.find({ repo: 'o/r', branch: 'feat/x', head: recorded, token: 't' });
+
+ it('finds it through the recorded commit when the owner-scoped lists are empty', async () => {
+ const { source, fetchFn } = sourceFor({
+ ...routes([forked()]),
+ '/check-runs': () => json({ total_count: 0, check_runs: [] }),
+ });
+ await expect(run(source)).resolves.toMatchObject({ number: 12 });
+ expect(
+ fetchFn.mock.calls.some(([url]) => String(url).includes(`/commits/${recorded}/pulls`)),
+ ).toBe(true);
+ });
+
+ it('ignores a pull request for the commit that is on another branch', async () => {
+ const { source } = sourceFor(routes([forked({ head: { sha: recorded, ref: 'other' } })]));
+ await expect(run(source)).resolves.toBeNull();
+ });
+
+ it('treats a commit GitHub does not know as no pull request', async () => {
+ const { source } = sourceFor(routes([], 422));
+ await expect(run(source)).resolves.toBeNull();
+ });
+
+ it('does not ask without a recorded commit', async () => {
+ const { source, fetchFn } = sourceFor(routes([forked()]));
+ await expect(source.find({ repo: 'o/r', branch: 'feat/x', token: 't' })).resolves.toBeNull();
+ expect(fetchFn.mock.calls.some(([url]) => String(url).includes('/commits/'))).toBe(false);
+ });
+});
+
+describe('a secondary rate limit without limiting headers', () => {
+ const secondary = () =>
+ new Response(
+ JSON.stringify({ message: 'You have exceeded a secondary rate limit. Please wait.' }),
+ { status: 403 },
+ );
+
+ it('is a rate limit that waits at least a minute', async () => {
+ const { source } = sourceFor({ '/pulls?state=open': secondary });
+ const error = await find(source).catch((caught) => caught);
+ expect(error.code).toBe('RATE_LIMITED');
+ expect(error.retryAfterMs).toBeGreaterThanOrEqual(60_000);
+ });
+
+ it('leaves an ordinary 403 as an upstream error', async () => {
+ const { source } = sourceFor({
+ '/pulls?state=open': () =>
+ new Response(JSON.stringify({ message: 'Resource not accessible by token' }), {
+ status: 403,
+ }),
+ });
+ await expect(find(source)).rejects.toMatchObject({ code: 'UPSTREAM_ERROR' });
+ });
+
+ it('does not put the response text in the error', async () => {
+ const { source } = sourceFor({ '/pulls?state=open': secondary });
+ const error = await find(source).catch((caught) => caught);
+ expect(JSON.stringify(error)).not.toContain('secondary rate limit');
+ expect(String(error.message)).not.toContain('secondary');
+ });
+});
diff --git a/packages/api/src/pulls/github.ts b/packages/api/src/pulls/github.ts
new file mode 100644
index 0000000000..2b273c0b9a
--- /dev/null
+++ b/packages/api/src/pulls/github.ts
@@ -0,0 +1,410 @@
+import type {
+ PullRequestChecks,
+ PullRequestMergeable,
+ PullRequestState,
+ TConversationPullRequest,
+} from 'librechat-data-provider';
+import type { PullRequestSource } from './types';
+import { PullRequestSourceError } from './types';
+
+const GITHUB_API_BASE = 'https://api.github.com';
+/** Defaults for the operator bounds in `endpoints.agents.pullRequests`. */
+const DEFAULT_REQUEST_TIMEOUT_MS = 10_000;
+const DEFAULT_LOOKUP_TIMEOUT_MS = 30_000;
+const DEFAULT_MAX_CHECK_RUN_PAGES = 10;
+const CHECK_RUN_PAGE_SIZE = 100;
+const DEFAULT_MAX_CANDIDATE_PULL_REQUESTS = 10;
+const DEFAULT_MAX_HEAD_COMPARISONS = 3;
+/**
+ * Comparing `recorded...candidate`: `ahead` means the candidate builds on the recorded commit and
+ * `identical` that it is the recorded commit. `behind` means the candidate does not contain it
+ * (the recorded commit is newer), and `diverged` that the histories split, so neither matches.
+ */
+const CONTAINS_RECORDED_STATUSES = new Set(['ahead', 'identical']);
+const COMMIT_ID = /^(?:[a-f0-9]{40}|[a-f0-9]{64})$/;
+const MAX_TITLE_LENGTH = 256;
+const REPO_PATTERN = /^([A-Za-z0-9_.-]+)\/([A-Za-z0-9_.-]+)$/;
+const FAILING_CONCLUSIONS = new Set([
+ 'failure',
+ 'timed_out',
+ 'cancelled',
+ 'action_required',
+ 'startup_failure',
+ 'stale',
+]);
+
+/** The only part of `fetch` this module calls, so any compatible client can be injected. */
+export type PullRequestFetch = (input: string, init?: RequestInit) => Promise<Response>;
+
+type GitHubPull = {
+ number: number;
+ title: string;
+ url: string;
+ state: 'open' | 'closed';
+ merged: boolean;
+ draft: boolean;
+ additions: number;
+ deletions: number;
+ mergeable: boolean | null;
+ /** The head this detail describes; the check runs are read for this same commit. */
+ headSha: string;
+};
+
+type GitHubCheckRun = { status: string; conclusion: string | null };
+
+const isRecord = (value: unknown): value is Record<string, unknown> =>
+ value != null && typeof value === 'object' && !Array.isArray(value);
+
+const isCount = (value: unknown): value is number =>
+ typeof value === 'number' && Number.isSafeInteger(value) && value >= 0;
+
+/** The URL ends up in an href, so only a plain https github.com page is accepted. */
+function isGitHubPageUrl(value: unknown): value is string {
+ if (typeof value !== 'string') return false;
+ try {
+ const url = new URL(value);
+ return url.protocol === 'https:' && url.hostname === 'github.com';
+ } catch {
+ return false;
+ }
+}
+
+function parsePull(value: unknown): GitHubPull {
+ if (
+ !isRecord(value) ||
+ !isCount(value.number) ||
+ typeof value.title !== 'string' ||
+ !isGitHubPageUrl(value.html_url) ||
+ (value.state !== 'open' && value.state !== 'closed') ||
+ typeof value.merged !== 'boolean' ||
+ typeof value.draft !== 'boolean' ||
+ !isCount(value.additions) ||
+ !isCount(value.deletions) ||
+ (value.mergeable !== null && typeof value.mergeable !== 'boolean') ||
+ !isRecord(value.head) ||
+ typeof value.head.sha !== 'string' ||
+ !COMMIT_ID.test(value.head.sha)
+ ) {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ return {
+ number: value.number,
+ title: value.title,
+ url: value.html_url,
+ state: value.state,
+ merged: value.merged,
+ draft: value.draft,
+ additions: value.additions,
+ deletions: value.deletions,
+ mergeable: value.mergeable,
+ headSha: value.head.sha,
+ };
+}
+
+type ListItem = { number: number; state: string; sha: string };
+
+function parseListItem(value: unknown): ListItem {
+ if (
+ !isRecord(value) ||
+ !isCount(value.number) ||
+ typeof value.state !== 'string' ||
+ !isRecord(value.head) ||
+ typeof value.head.sha !== 'string' ||
+ !/^[a-f0-9]{40,64}$/.test(value.head.sha)
+ ) {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ return { number: value.number, state: value.state, sha: value.head.sha };
+}
+
+type CheckRunPage = { runs: GitHubCheckRun[]; total?: number };
+
+function parseCheckRuns(value: unknown): CheckRunPage {
+ if (!isRecord(value) || !Array.isArray(value.check_runs)) {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ const runs = value.check_runs.map((run) => {
+ if (!isRecord(run) || typeof run.status !== 'string') {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ return {
+ status: run.status,
+ conclusion: typeof run.conclusion === 'string' ? run.conclusion : null,
+ };
+ });
+ return { runs, ...(isCount(value.total_count) ? { total: value.total_count } : {}) };
+}
+
+/**
+ * A failed check outranks one still running, so the header turns red as soon as it is known.
+ * An `incomplete` rollup (more runs than were read) is never reported as passing.
+ */
+export function summarizeChecks(
+ runs: readonly GitHubCheckRun[],
+ incomplete = false,
+): PullRequestChecks {
+ if (runs.length === 0 && !incomplete) return 'none';
+ if (runs.some((run) => run.conclusion != null && FAILING_CONCLUSIONS.has(run.conclusion))) {
+ return 'failing';
+ }
+ if (incomplete || runs.some((run) => run.status !== 'completed')) return 'running';
+ return 'passing';
+}
+
+function summarizeState(pull: GitHubPull): PullRequestState {
+ return pull.merged ? 'merged' : pull.state;
+}
+
+/** Conflict state only means something while the pull request is open. */
+function summarizeMergeable(pull: GitHubPull): PullRequestMergeable {
+ if (summarizeState(pull) !== 'open' || pull.mergeable == null) return 'unknown';
+ return pull.mergeable ? 'clean' : 'conflicting';
+}
+
+export function toConversationPullRequest(
+ pull: GitHubPull,
+ runs: readonly GitHubCheckRun[],
+ incomplete = false,
+): TConversationPullRequest {
+ return {
+ number: pull.number,
+ title: pull.title.slice(0, MAX_TITLE_LENGTH),
+ url: pull.url,
+ additions: pull.additions,
+ deletions: pull.deletions,
+ state: summarizeState(pull),
+ isDraft: pull.draft,
+ mergeable: summarizeMergeable(pull),
+ checks: summarizeChecks(runs, incomplete),
+ };
+}
+
+/** GitHub asks for at least a minute when a secondary limit names no wait. */
+const SECONDARY_LIMIT_WAIT_MS = 60_000;
+const SECONDARY_LIMIT_MESSAGE = /secondary rate limit|abuse detection/i;
+const MAX_ERROR_BODY_CHARS = 2_000;
+
+function isRateLimited(response: Response): boolean {
+ return (
+ response.status === 429 ||
+ (response.status === 403 &&
+ (response.headers.get('x-ratelimit-remaining') === '0' ||
+ response.headers.get('retry-after') != null))
+ );
+}
+
+/**
+ * A secondary limit can arrive as a 403 with neither limiting header, told apart only by its
+ * message. The body is read bounded and only matched, never stored or returned.
+ */
+async function isSecondaryLimit(response: Response): Promise<boolean> {
+ if (response.status !== 403) return false;
+ try {
+ const text = (await response.text()).slice(0, MAX_ERROR_BODY_CHARS);
+ return SECONDARY_LIMIT_MESSAGE.test(text);
+ } catch {
+ return false;
+ }
+}
+
+/** How long GitHub asked callers to wait: `retry-after` seconds, else the quota reset time. */
+function retryAfterMs(response: Response): number | undefined {
+ const retryAfter = Number(response.headers.get('retry-after'));
+ if (response.headers.get('retry-after') != null && Number.isFinite(retryAfter)) {
+ return Math.max(0, retryAfter * 1000);
+ }
+ const reset = Number(response.headers.get('x-ratelimit-reset'));
+ if (response.headers.get('x-ratelimit-reset') != null && Number.isFinite(reset)) {
+ return Math.max(0, reset * 1000 - Date.now());
+ }
+ return undefined;
+}
+
+/**
+ * Reads pull requests through GitHub's REST API with a token the caller supplies. Only the
+ * decision (absent, rate limited, failed) leaves this module; response bodies and error text
+ * never do.
+ */
+/** `.` and `..` match the character class but would rewrite the API path. */
+const isPathSegment = (value: string): boolean => value !== '.' && value !== '..';
+
+export function createGitHubPullRequestSource({
+ fetchFn,
+ apiBase = GITHUB_API_BASE,
+}: {
+ /** The deployment's HTTP client, so proxying and instrumentation are decided by the caller. */
+ fetchFn: PullRequestFetch;
+ apiBase?: string;
+}): PullRequestSource {
+ /** One lookup's credential and deadlines, shared by every request it makes. */
+ type Lookup = {
+ token: string;
+ requestTimeoutMs: number;
+ /** Aborts when the whole lookup runs out of time. */
+ deadline: AbortSignal;
+ maxCheckRunPages: number;
+ maxCandidatePullRequests: number;
+ maxHeadComparisons: number;
+ };
+
+ async function getJson(
+ pathname: string,
+ lookup: Lookup,
+ /** Statuses that mean "nothing there" for this request, besides 404. */
+ absent: readonly number[] = [],
+ ): Promise<unknown | null> {
+ let response: Response;
+ try {
+ response = await fetchFn(`${apiBase}${pathname}`, {
+ headers: {
+ Accept: 'application/vnd.github+json',
+ Authorization: `Bearer ${lookup.token}`,
+ 'X-GitHub-Api-Version': '2022-11-28',
+ 'User-Agent': 'LibreChat-Pull-Requests',
+ },
+ signal: AbortSignal.any([AbortSignal.timeout(lookup.requestTimeoutMs), lookup.deadline]),
+ });
+ } catch {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ if (response.ok) {
+ try {
+ return await response.json();
+ } catch {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ }
+ if (isRateLimited(response)) {
+ throw new PullRequestSourceError('RATE_LIMITED', retryAfterMs(response));
+ }
+ if (await isSecondaryLimit(response)) {
+ throw new PullRequestSourceError('RATE_LIMITED', SECONDARY_LIMIT_WAIT_MS);
+ }
+ /** A repository the token cannot see is indistinguishable from one without pull requests. */
+ if (response.status === 404 || absent.includes(response.status)) return null;
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+
+ /** Reads every page up to a bound, so a failure on a later page still shows. */
+ async function readCheckRuns(
+ pathname: string,
+ lookup: Lookup,
+ ): Promise<{ runs: GitHubCheckRun[]; incomplete: boolean }> {
+ const runs: GitHubCheckRun[] = [];
+ for (let page = 1; page <= lookup.maxCheckRunPages; page++) {
+ const body = await getJson(
+ `${pathname}?per_page=${CHECK_RUN_PAGE_SIZE}&page=${page}`,
+ lookup,
+ );
+ if (body == null) return { runs, incomplete: false };
+ const parsed = parseCheckRuns(body);
+ runs.push(...parsed.runs);
+ const done =
+ parsed.total != null
+ ? runs.length >= parsed.total || parsed.runs.length === 0
+ : parsed.runs.length < CHECK_RUN_PAGE_SIZE;
+ if (done) return { runs, incomplete: false };
+ }
+ return { runs, incomplete: true };
+ }
+
+ return {
+ async find({ repo, branch, head: recordedHead, token, limits }) {
+ const lookup: Lookup = {
+ token,
+ requestTimeoutMs: limits?.requestTimeoutMs ?? DEFAULT_REQUEST_TIMEOUT_MS,
+ deadline: AbortSignal.timeout(limits?.lookupTimeoutMs ?? DEFAULT_LOOKUP_TIMEOUT_MS),
+ maxCheckRunPages: limits?.maxCheckRunPages ?? DEFAULT_MAX_CHECK_RUN_PAGES,
+ maxCandidatePullRequests:
+ limits?.maxCandidatePullRequests ?? DEFAULT_MAX_CANDIDATE_PULL_REQUESTS,
+ maxHeadComparisons: limits?.maxHeadComparisons ?? DEFAULT_MAX_HEAD_COMPARISONS,
+ };
+ const match = REPO_PATTERN.exec(repo);
+ if (match == null || branch.length === 0) return null;
+ const [, owner, name] = match;
+ if (!isPathSegment(owner) || !isPathSegment(name)) return null;
+ const base = `/repos/${encodeURIComponent(owner)}/${encodeURIComponent(name)}`;
+ const headFilter = encodeURIComponent(`${owner}:${branch}`);
+ /** `undefined`: the repository is not visible. An empty list: it is, and nothing matched. */
+ const listPulls = async (state: 'open' | 'closed', perPage: number) => {
+ const listed = await getJson(
+ `${base}/pulls?state=${state}&sort=updated&direction=desc&per_page=${perPage}&head=${headFilter}`,
+ lookup,
+ );
+ if (listed == null) return undefined;
+ if (!Array.isArray(listed)) throw new PullRequestSourceError('UPSTREAM_ERROR');
+ return listed.map(parseListItem);
+ };
+ const recorded =
+ typeof recordedHead === 'string' && COMMIT_ID.test(recordedHead) ? recordedHead : undefined;
+ let comparisons = 0;
+ /**
+ * A branch name can be deleted and reused, so with a recorded commit a pull request counts
+ * only when its head is that commit or builds on it. A commit GitHub no longer knows is no
+ * match, and both the candidates listed and the comparisons made are bounded by config.
+ */
+ /** Every comparison, the first match and the revalidation of a moved head alike, spends the
+ * same configured budget. */
+ const contains = async (headSha: string): Promise<boolean> => {
+ if (recorded == null || headSha === recorded) return true;
+ if (comparisons >= lookup.maxHeadComparisons) return false;
+ comparisons += 1;
+ const comparison = await getJson(`${base}/compare/${recorded}...${headSha}`, lookup);
+ if (comparison == null) return false;
+ if (!isRecord(comparison) || typeof comparison.status !== 'string') {
+ throw new PullRequestSourceError('UPSTREAM_ERROR');
+ }
+ return CONTAINS_RECORDED_STATUSES.has(comparison.status);
+ };
+ const matches = (candidate: ListItem): Promise<boolean> => contains(candidate.sha);
+ const choose = async (candidates: ListItem[]): Promise<ListItem | null> => {
+ for (const candidate of candidates) {
+ if (await matches(candidate)) return candidate;
+ }
+ return null;
+ };
+ /** Open first on its own, so closed history on a reused branch name cannot hide it. */
+ const open = await listPulls('open', lookup.maxCandidatePullRequests);
+ if (open === undefined) return null;
+ /**
+ * The head filter names the repository's own owner, so a pull request from a fork is not in
+ * these lists. The recorded commit finds it instead: GitHub lists the pull requests that
+ * carry a commit whatever fork they come from, and the branch name narrows them.
+ */
+ const forkCandidates = async (): Promise<ListItem[]> => {
+ if (recorded == null) return [];
+ const found = await getJson(
+ `${base}/commits/${recorded}/pulls?per_page=${lookup.maxCandidatePullRequests}`,
+ lookup,
+ [422],
+ );
+ if (found == null) return [];
+ if (!Array.isArray(found)) throw new PullRequestSourceError('UPSTREAM_ERROR');
+ return found
+ .filter((item) => isRecord(item) && isRecord(item.head) && item.head.ref === branch)
+ .map(parseListItem)
+ .sort((a, b) => Number(a.state !== 'open') - Number(b.state !== 'open'));
+ };
+ const chosen =
+ (await choose(open)) ??
+ (await choose(
+ (await listPulls('closed', recorded == null ? 1 : lookup.maxCandidatePullRequests)) ?? [],
+ )) ??
+ (await choose(await forkCandidates()));
+ if (chosen == null) return null;
+
+ /**
+ * The detail comes first and its head decides which commit's checks are read. Listing,
+ * detail and checks are separate requests, so a push between them could otherwise pair
+ * today's line counts and mergeability with yesterday's checks.
+ */
+ const detail = await getJson(`${base}/pulls/${chosen.number}`, lookup);
+ if (detail == null) return null;
+ const pull = parsePull(detail);
+ /** A push between the list and the detail can move the head off the recorded commit. */
+ if (pull.headSha !== chosen.sha && !(await contains(pull.headSha))) return null;
+ const checks = await readCheckRuns(`${base}/commits/${pull.headSha}/check-runs`, lookup);
+ return toConversationPullRequest(pull, checks.runs, checks.incomplete);
+ },
+ };
+}
diff --git a/packages/api/src/pulls/handler.spec.ts b/packages/api/src/pulls/handler.spec.ts
new file mode 100644
index 0000000000..ec862de7b4
--- /dev/null
+++ b/packages/api/src/pulls/handler.spec.ts
@@ -0,0 +1,283 @@
+import type { TConversationPullRequest } from 'librechat-data-provider';
+import type { Response } from 'express';
+import type { ServerRequest } from '~/types';
+import { createConversationPullRequestHandler, resolveTokenReference } from './handler';
+
+jest.mock('@librechat/data-schemas', () => ({
+ ...jest.requireActual('@librechat/data-schemas'),
+ logger: { warn: jest.fn(), debug: jest.fn(), info: jest.fn(), error: jest.fn() },
+}));
+
+const pr: TConversationPullRequest = {
+ number: 7,
+ title: 't',
+ url: 'https://github.com/o/r/pull/7',
+ additions: 1,
+ deletions: 2,
+ state: 'open',
+ isDraft: false,
+ mergeable: 'clean',
+ checks: 'passing',
+};
+
+const enabled = {
+ enabled: true,
+ token: '${GH_TOKEN}',
+ cacheTtlSeconds: 30,
+ allowedRepositories: ['o/r'],
+};
+const configWith = (pullRequests?: Record<string, unknown>) => ({
+ endpoints: { agents: { pullRequests } },
+});
+
+type Lane = { branch: string | null; head: string | null; repo?: string } | null;
+
+function setup(
+ options: {
+ settings?: Record<string, unknown> | null;
+ laneGit?: Lane;
+ lookup?: jest.Mock;
+ env?: Record<string, string | undefined>;
+ } = {},
+) {
+ /** `null` means the block is absent; omitting the option means the enabled default. */
+ const settings = options.settings === undefined ? enabled : (options.settings ?? undefined);
+ const laneGit: Lane =
+ options.laneGit === undefined ? { branch: 'feat/x', head: null, repo: 'o/r' } : options.laneGit;
+ const lookup = options.lookup ?? jest.fn().mockResolvedValue({ ok: true, value: pr });
+ const env = options.env ?? { GH_TOKEN: 'ghp_secret' };
+ const getConvoLaneGit = jest.fn().mockResolvedValue(laneGit);
+ const handler = createConversationPullRequestHandler({
+ getConvoLaneGit,
+ getAppConfig: jest.fn().mockResolvedValue(configWith(settings)),
+ lookup,
+ env,
+ });
+ const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
+ const run = (params: { conversationId?: string } = { conversationId: 'c1' }, user = 'u1') =>
+ handler({ user: { id: user }, params } as unknown as ServerRequest, res as unknown as Response);
+ return { run, res, getConvoLaneGit, lookup };
+}
+
+describe('resolveTokenReference', () => {
+ it.each([
+ ['${GH_TOKEN}', { GH_TOKEN: ' abc ' }, 'abc'],
+ ['${GH_TOKEN}', {}, null],
+ ['${GH_TOKEN}', { GH_TOKEN: ' ' }, null],
+ ['literal-token', { 'literal-token': 'x' }, null],
+ [undefined, { GH_TOKEN: 'x' }, null],
+ ])('resolves %s', (reference, env, expected) => {
+ expect(resolveTokenReference(reference, env)).toBe(expected);
+ });
+});
+
+describe('createConversationPullRequestHandler', () => {
+ it('returns the pull request for the owner-scoped branch', async () => {
+ const { run, res, getConvoLaneGit, lookup } = setup();
+ await run();
+ expect(getConvoLaneGit).toHaveBeenCalledWith('u1', 'c1');
+ expect(lookup).toHaveBeenCalledWith({
+ repo: 'o/r',
+ branch: 'feat/x',
+ token: 'ghp_secret',
+ head: null,
+ ttlMs: 30_000,
+ cacheMaxEntries: 500,
+ cacheMaxCredentials: 256,
+ limits: {
+ requestTimeoutMs: 10_000,
+ lookupTimeoutMs: 30_000,
+ maxCheckRunPages: 10,
+ maxCandidatePullRequests: 10,
+ maxHeadComparisons: 3,
+ },
+ });
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith({ pullRequest: pr });
+ });
+
+ it('passes the configured lookup bounds to GitHub', async () => {
+ const { run, lookup } = setup({
+ settings: {
+ ...enabled,
+ requestTimeoutSeconds: 3,
+ lookupTimeoutSeconds: 8,
+ maxCheckRunPages: 4,
+ maxCandidatePullRequests: 25,
+ maxHeadComparisons: 6,
+ cacheMaxEntries: 77,
+ cacheMaxCredentials: 12,
+ },
+ });
+ await run();
+ expect(lookup).toHaveBeenCalledWith(
+ expect.objectContaining({
+ cacheMaxEntries: 77,
+ cacheMaxCredentials: 12,
+ limits: {
+ requestTimeoutMs: 3_000,
+ lookupTimeoutMs: 8_000,
+ maxCheckRunPages: 4,
+ maxCandidatePullRequests: 25,
+ maxHeadComparisons: 6,
+ },
+ }),
+ );
+ });
+
+ it('passes the recorded head so the pull request can be matched to what the chat ran', async () => {
+ const head = 'a'.repeat(40);
+ const { run, lookup } = setup({ laneGit: { branch: 'feat/x', head, repo: 'o/r' } });
+ await run();
+ expect(lookup).toHaveBeenCalledWith(expect.objectContaining({ head }));
+ });
+
+ describe('repository allowlist', () => {
+ const lane = (repo: string) => ({ branch: 'feat/x', head: null, repo });
+
+ it.each([
+ ['an exact match', ['o/r'], 'o/r'],
+ ['a different case', ['O/R'], 'o/r'],
+ ['an owner wildcard', ['o/*'], 'o/r'],
+ ['one of several', ['x/y', 'o/r'], 'o/r'],
+ ])('looks up a repository allowed by %s', async (_label, allowedRepositories, repo) => {
+ const { run, lookup } = setup({
+ settings: { ...enabled, allowedRepositories },
+ laneGit: lane(repo),
+ });
+ await run();
+ expect(lookup).toHaveBeenCalledTimes(1);
+ });
+
+ it.each([
+ ['another repository', ['o/r'], 'o/other'],
+ ['another owner', ['o/*'], 'x/r'],
+ ['a prefix of an allowed owner', ['org/*'], 'organization/r'],
+ ['an empty allowlist', [], 'o/r'],
+ ])('answers null without using the token for %s', async (_label, allowedRepositories, repo) => {
+ const { run, res, lookup } = setup({
+ settings: { ...enabled, allowedRepositories },
+ laneGit: lane(repo),
+ });
+ await run();
+ expect(lookup).not.toHaveBeenCalled();
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith({ pullRequest: null });
+ });
+
+ it('does not reveal whether a disallowed repository exists', async () => {
+ const allowed = setup({ laneGit: lane('o/r') });
+ const denied = setup({ laneGit: lane('secret/private') });
+ await denied.run();
+ await allowed.run();
+ expect(denied.res.json).toHaveBeenCalledWith({ pullRequest: null });
+ expect(JSON.stringify(denied.res.json.mock.calls)).not.toContain('secret');
+ });
+ });
+
+ it('answers null, and never touches GitHub, when the feature is off', async () => {
+ for (const settings of [null, { enabled: false }]) {
+ const { run, res, lookup } = setup({ settings });
+ await run();
+ expect(lookup).not.toHaveBeenCalled();
+ expect(res.json).toHaveBeenCalledWith({ pullRequest: null });
+ }
+ });
+
+ it('starts the config and the owner-scoped lane reads together, not one after the other', async () => {
+ const order: string[] = [];
+ let releaseConfig: (config: unknown) => void = () => undefined;
+ const getAppConfig = jest.fn(
+ () =>
+ new Promise((resolve) => {
+ order.push('config:start');
+ releaseConfig = resolve;
+ }),
+ );
+ const getConvoLaneGit = jest.fn(async () => {
+ order.push('lane:start');
+ return { branch: 'feat/x', head: null, repo: 'o/r' };
+ });
+ const handler = createConversationPullRequestHandler({
+ getConvoLaneGit,
+ getAppConfig: getAppConfig as never,
+ lookup: jest.fn().mockResolvedValue({ ok: true, value: pr }),
+ env: { GH_TOKEN: 'ghp_secret' },
+ });
+ const res = { status: jest.fn().mockReturnThis(), json: jest.fn() };
+ const done = handler(
+ { user: { id: 'u1' }, params: { conversationId: 'c1' } } as unknown as ServerRequest,
+ res as unknown as Response,
+ );
+ await new Promise((resolve) => setImmediate(resolve));
+ expect(order).toEqual(['config:start', 'lane:start']);
+ releaseConfig(configWith(enabled));
+ await done;
+ expect(res.json).toHaveBeenCalledWith({ pullRequest: pr });
+ });
+
+ it.each([
+ ['no stored lane', null],
+ ['a detached lane', { branch: null, head: null, repo: 'o/r' }],
+ ['a lane with no repository', { branch: 'main', head: null }],
+ ])('answers null for %s without calling GitHub', async (_label, laneGit) => {
+ const { run, res, lookup } = setup({ laneGit });
+ await run();
+ expect(lookup).not.toHaveBeenCalled();
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith({ pullRequest: null });
+ });
+
+ it('answers null when the branch has no pull request', async () => {
+ const { run, res } = setup({ lookup: jest.fn().mockResolvedValue({ ok: true, value: null }) });
+ await run();
+ expect(res.status).toHaveBeenCalledWith(200);
+ expect(res.json).toHaveBeenCalledWith({ pullRequest: null });
+ });
+
+ it('is a 404 for a missing or oversized conversation id', async () => {
+ for (const conversationId of [undefined, '', ' ', 'x'.repeat(257)]) {
+ const { run, res, getConvoLaneGit } = setup();
+ await run({ conversationId });
+ expect(res.status).toHaveBeenCalledWith(404);
+ expect(getConvoLaneGit).not.toHaveBeenCalled();
+ }
+ });
+
+ it('reports a missing token as NOT_CONFIGURED without leaking config', async () => {
+ const { run, res, lookup } = setup({ env: {} });
+ await run();
+ expect(lookup).not.toHaveBeenCalled();
+ expect(res.status).toHaveBeenCalledWith(503);
+ expect(res.json).toHaveBeenCalledWith({
+ error: 'Pull requests are not configured',
+ code: 'NOT_CONFIGURED',
+ });
+ });
+
+ it.each(['RATE_LIMITED', 'UPSTREAM_ERROR'])(
+ 'maps a %s failure to a 503 with its code',
+ async (code) => {
+ const { run, res } = setup({
+ lookup: jest.fn().mockResolvedValue({ ok: false, error: { code } }),
+ });
+ await run();
+ expect(res.status).toHaveBeenCalledWith(503);
+ expect(res.json).toHaveBeenCalledWith(expect.objectContaining({ code }));
+ },
+ );
+
+ it('answers 500 with fixed text when storage throws, never the exception', async () => {
+ const { run, res, getConvoLaneGit } = setup();
+ getConvoLaneGit.mockRejectedValue(new Error('mongodb://user:secret@host'));
+ await run();
+ expect(res.status).toHaveBeenCalledWith(500);
+ expect(JSON.stringify(res.json.mock.calls)).not.toContain('secret');
+ });
+
+ it('never puts the token in a response', async () => {
+ const { run, res } = setup();
+ await run();
+ expect(JSON.stringify(res.json.mock.calls)).not.toContain('ghp_secret');
+ });
+});
diff --git a/packages/api/src/pulls/handler.ts b/packages/api/src/pulls/handler.ts
new file mode 100644
index 0000000000..42a7209783
--- /dev/null
+++ b/packages/api/src/pulls/handler.ts
@@ -0,0 +1,129 @@
+import { logger } from '@librechat/data-schemas';
+import { EModelEndpoint } from 'librechat-data-provider';
+import type { TAgentsEndpoint, TConversationPullRequestResponse } from 'librechat-data-provider';
+import type { AppConfig } from '@librechat/data-schemas';
+import type { Response } from 'express';
+import type { GetAppConfigOptions } from '~/app/service';
+import type { PullRequestLookup } from './types';
+import type { ServerRequest } from '~/types';
+import { getAppConfigOptionsFromUser } from '~/app/service';
+import { getSafeErrorMetadata } from '~/utils';
+
+const MAX_CONVERSATION_ID_LENGTH = 256;
+const TOKEN_REFERENCE = /^\$\{([A-Za-z_][A-Za-z0-9_]*)\}$/;
+
+export type ConversationLaneGit = { branch: string | null; head: string | null; repo?: string };
+
+/** Resolves `${NAME}` against the environment; the config never holds the token itself. */
+export function resolveTokenReference(
+ reference: string | undefined,
+ env: Readonly<Record<string, string | undefined>>,
+): string | null {
+ const name = reference == null ? undefined : TOKEN_REFERENCE.exec(reference)?.[1];
+ if (name == null) return null;
+ return env[name]?.trim() || null;
+}
+
+/** `owner/name` or `owner/*`, compared without case as GitHub does. Nothing else matches. */
+export function isAllowedRepository(repo: string, allowed: readonly string[] | undefined): boolean {
+ const [owner, name] = repo.toLowerCase().split('/');
+ return (allowed ?? []).some((entry) => {
+ const [allowedOwner, allowedName] = entry.toLowerCase().split('/');
+ return allowedOwner === owner && (allowedName === '*' || allowedName === name);
+ });
+}
+
+const validConversationId = (value: string | undefined): value is string =>
+ value != null && value.trim() !== '' && value.length <= MAX_CONVERSATION_ID_LENGTH;
+
+const NONE: TConversationPullRequestResponse = { pullRequest: null };
+
+/**
+ * Serves the pull request of the branch a conversation's code workspace last reported. The
+ * stored branch is read owner-scoped, so another user's conversation is indistinguishable from
+ * one without a pull request. Failures answer with a stable code and never with upstream text.
+ */
+export function createConversationPullRequestHandler(deps: {
+ getConvoLaneGit: (user: string, conversationId: string) => Promise<ConversationLaneGit | null>;
+ getAppConfig: (options: GetAppConfigOptions) => Promise<AppConfig>;
+ lookup: PullRequestLookup;
+ env: Readonly<Record<string, string | undefined>>;
+}) {
+ return async (req: ServerRequest, res: Response): Promise<void> => {
+ const userId = req.user?.id;
+ const { conversationId } = req.params as { conversationId?: string };
+ if (!userId || !validConversationId(conversationId)) {
+ res.status(404).json({ error: 'Conversation not found' });
+ return;
+ }
+ try {
+ /**
+ * Config and the owner-scoped lane are independent, so they load together. The lane is only
+ * used when the resolved config turns the feature on, which keeps a disabled deployment's
+ * answer the same as before.
+ */
+ const [appConfig, laneGit] = await Promise.all([
+ deps.getAppConfig({
+ ...getAppConfigOptionsFromUser(req.user),
+ skipRuntimeAugmentation: true,
+ failClosed: true,
+ }),
+ deps.getConvoLaneGit(userId, conversationId),
+ ]);
+ const settings = (appConfig.endpoints?.[EModelEndpoint.agents] as TAgentsEndpoint | undefined)
+ ?.pullRequests;
+ if (settings?.enabled !== true) {
+ res.status(200).json(NONE);
+ return;
+ }
+
+ if (laneGit?.branch == null || laneGit.repo == null) {
+ res.status(200).json(NONE);
+ return;
+ }
+
+ /** The repository comes from the worker, so it is never used with the token unless the
+ * administrator named it. A repository that is not allowed looks like one without a pull
+ * request. */
+ if (!isAllowedRepository(laneGit.repo, settings.allowedRepositories)) {
+ res.status(200).json(NONE);
+ return;
+ }
+
+ const token = resolveTokenReference(settings.token, deps.env);
+ if (token == null) {
+ logger.warn('[PullRequests] Enabled without a usable token reference');
+ res.status(503).json({ error: 'Pull requests are not configured', code: 'NOT_CONFIGURED' });
+ return;
+ }
+
+ const result = await deps.lookup({
+ repo: laneGit.repo,
+ branch: laneGit.branch,
+ head: laneGit.head,
+ token,
+ ttlMs: (settings.cacheTtlSeconds ?? 30) * 1000,
+ cacheMaxEntries: settings.cacheMaxEntries ?? 500,
+ cacheMaxCredentials: settings.cacheMaxCredentials ?? 256,
+ limits: {
+ requestTimeoutMs: (settings.requestTimeoutSeconds ?? 10) * 1000,
+ lookupTimeoutMs: (settings.lookupTimeoutSeconds ?? 30) * 1000,
+ maxCheckRunPages: settings.maxCheckRunPages ?? 10,
+ maxCandidatePullRequests: settings.maxCandidatePullRequests ?? 10,
+ maxHeadComparisons: settings.maxHeadComparisons ?? 3,
+ },
+ });
+ if (!result.ok) {
+ res.status(503).json({
+ error: 'Pull request lookup is unavailable',
+ code: result.error.code,
+ });
+ return;
+ }
+ res.status(200).json({ pullRequest: result.value });
+ } catch (error) {
+ logger.error('[PullRequests] Handler failed', getSafeErrorMetadata(error));
+ res.status(500).json({ error: 'Failed to load the pull request' });
+ }
+ };
+}
diff --git a/packages/api/src/pulls/index.ts b/packages/api/src/pulls/index.ts
new file mode 100644
index 0000000000..f6fca52670
--- /dev/null
+++ b/packages/api/src/pulls/index.ts
@@ -0,0 +1,4 @@
+export * from './types';
+export * from './github';
+export * from './lookup';
+export * from './handler';
diff --git a/packages/api/src/pulls/lookup.spec.ts b/packages/api/src/pulls/lookup.spec.ts
new file mode 100644
index 0000000000..319d7c30ff
--- /dev/null
+++ b/packages/api/src/pulls/lookup.spec.ts
@@ -0,0 +1,404 @@
+import type { TConversationPullRequest } from 'librechat-data-provider';
+import type { PullRequestSource } from './types';
+import { createPullRequestLookup } from './lookup';
+import { PullRequestSourceError } from './types';
+
+const value: TConversationPullRequest = {
+ number: 1,
+ title: 't',
+ url: 'https://github.com/o/r/pull/1',
+ additions: 1,
+ deletions: 0,
+ state: 'open',
+ isDraft: false,
+ mergeable: 'clean',
+ checks: 'passing',
+};
+const input = { repo: 'o/r', branch: 'main', token: 't', ttlMs: 30_000 };
+
+describe('createPullRequestLookup', () => {
+ it('reuses a result within its lifetime and asks again after it', async () => {
+ let clock = 0;
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await expect(lookup(input)).resolves.toEqual({ ok: true, value });
+ clock = 29_999;
+ await lookup(input);
+ expect(find).toHaveBeenCalledTimes(1);
+ clock = 30_001;
+ await lookup(input);
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('caches a documented absence', async () => {
+ const find = jest.fn().mockResolvedValue(null);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await expect(lookup(input)).resolves.toEqual({ ok: true, value: null });
+ await lookup(input);
+ expect(find).toHaveBeenCalledTimes(1);
+ });
+
+ it('shares one request between concurrent callers', async () => {
+ let release: (pr: TConversationPullRequest) => void = () => undefined;
+ const find = jest.fn(
+ () =>
+ new Promise<TConversationPullRequest>((resolve) => {
+ release = resolve;
+ }),
+ );
+ const lookup = createPullRequestLookup({ source: { find } });
+ const first = lookup(input);
+ const second = lookup(input);
+ release(value);
+ await expect(Promise.all([first, second])).resolves.toEqual([
+ { ok: true, value },
+ { ok: true, value },
+ ]);
+ expect(find).toHaveBeenCalledTimes(1);
+ });
+
+ it('keys by repository and branch', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup(input);
+ await lookup({ ...input, branch: 'other' });
+ await lookup({ ...input, repo: 'o/other' });
+ expect(find).toHaveBeenCalledTimes(3);
+ });
+
+ it('returns a failure as a coded result and retries it sooner than a success', async () => {
+ let clock = 0;
+ const find = jest
+ .fn()
+ .mockRejectedValueOnce(new PullRequestSourceError('RATE_LIMITED'))
+ .mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await expect(lookup(input)).resolves.toEqual({
+ ok: false,
+ error: { code: 'RATE_LIMITED' },
+ });
+ clock = 5_000;
+ await expect(lookup(input)).resolves.toMatchObject({ ok: false });
+ expect(find).toHaveBeenCalledTimes(1);
+ clock = 10_001;
+ await expect(lookup(input)).resolves.toEqual({ ok: true, value });
+ });
+
+ it('turns an unexpected exception into UPSTREAM_ERROR without its text', async () => {
+ const source: PullRequestSource = {
+ find: jest.fn().mockRejectedValue(new Error('mongodb://user:secret@host')),
+ };
+ const result = await createPullRequestLookup({ source })(input);
+ expect(result).toEqual({ ok: false, error: { code: 'UPSTREAM_ERROR' } });
+ expect(JSON.stringify(result)).not.toContain('secret');
+ });
+
+ it('evicts the oldest entry past its bound', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, maxEntries: 2 });
+ await lookup({ ...input, branch: 'a' });
+ await lookup({ ...input, branch: 'b' });
+ await lookup({ ...input, branch: 'c' });
+ await lookup({ ...input, branch: 'a' });
+ expect(find).toHaveBeenCalledTimes(4);
+ });
+});
+
+describe('credential scoping', () => {
+ it('never serves a result fetched with one credential to another', async () => {
+ const find = jest.fn(async ({ token }: { token: string }) =>
+ token === 'tenant-a' ? value : null,
+ );
+ const lookup = createPullRequestLookup({ source: { find } });
+ await expect(lookup({ ...input, token: 'tenant-a' })).resolves.toEqual({ ok: true, value });
+ await expect(lookup({ ...input, token: 'tenant-b' })).resolves.toEqual({
+ ok: true,
+ value: null,
+ });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('still reuses a result for the same credential', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, token: 'tenant-a' });
+ await lookup({ ...input, token: 'tenant-a' });
+ expect(find).toHaveBeenCalledTimes(1);
+ });
+
+ it('does not share an in-flight request between credentials', async () => {
+ const releases: Array<() => void> = [];
+ const find = jest.fn(
+ ({ token }: { token: string }) =>
+ new Promise<TConversationPullRequest | null>((resolve) => {
+ releases.push(() => resolve(token === 'a' ? value : null));
+ }),
+ );
+ const lookup = createPullRequestLookup({ source: { find } });
+ const a = lookup({ ...input, token: 'a' });
+ const b = lookup({ ...input, token: 'b' });
+ expect(find).toHaveBeenCalledTimes(2);
+ releases.forEach((release) => release());
+ await expect(a).resolves.toEqual({ ok: true, value });
+ await expect(b).resolves.toEqual({ ok: true, value: null });
+ });
+});
+
+describe('rate limit cooldown', () => {
+ const limited = (retryAfterMs?: number) =>
+ new PullRequestSourceError('RATE_LIMITED', retryAfterMs);
+ const rateLimited = { ok: false, error: { code: 'RATE_LIMITED' } };
+
+ it('stops asking GitHub for every branch of the credential until the retry time', async () => {
+ let clock = 0;
+ const find = jest.fn().mockRejectedValueOnce(limited(60_000)).mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await expect(lookup(input)).resolves.toEqual(rateLimited);
+ clock = 30_000;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual(rateLimited);
+ expect(find).toHaveBeenCalledTimes(1);
+ clock = 60_001;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual({ ok: true, value });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not block a different credential', async () => {
+ const find = jest.fn().mockRejectedValueOnce(limited(60_000)).mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, token: 'a' });
+ await expect(lookup({ ...input, token: 'b', branch: 'other' })).resolves.toEqual({
+ ok: true,
+ value,
+ });
+ });
+
+ it('waits at least a short floor when GitHub gives no retry time', async () => {
+ let clock = 0;
+ const find = jest.fn().mockRejectedValueOnce(limited()).mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await lookup(input);
+ clock = 9_999;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual(rateLimited);
+ clock = 10_001;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual({ ok: true, value });
+ });
+
+ it('honors a reset GitHub reports well beyond ten minutes', async () => {
+ let clock = 0;
+ const find = jest
+ .fn()
+ .mockRejectedValueOnce(limited(40 * 60_000))
+ .mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await lookup(input);
+ clock = 39 * 60_000;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual(rateLimited);
+ expect(find).toHaveBeenCalledTimes(1);
+ clock = 40 * 60_000 + 1;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual({ ok: true, value });
+ });
+
+ it('caps a hint past the hour GitHub resets within, so one bad header cannot silence the feature for a day', async () => {
+ let clock = 0;
+ const find = jest
+ .fn()
+ .mockRejectedValueOnce(limited(24 * 60 * 60_000))
+ .mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await lookup(input);
+ clock = 60 * 60_000 - 1;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual(rateLimited);
+ clock = 60 * 60_000 + 1;
+ await expect(lookup({ ...input, branch: 'other' })).resolves.toEqual({ ok: true, value });
+ });
+
+ it('keeps serving a cached result while the credential is cooling down', async () => {
+ let clock = 0;
+ const find = jest.fn().mockResolvedValueOnce(value).mockRejectedValueOnce(limited(60_000));
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await lookup(input);
+ await lookup({ ...input, branch: 'other' });
+ clock = 5_000;
+ await expect(lookup(input)).resolves.toEqual({ ok: true, value });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+});
+
+describe('lookup policy scoping', () => {
+ it('does not serve a result read under a tighter page limit to a caller allowing more', async () => {
+ const incomplete = { ...value, checks: 'running' as const };
+ const find = jest.fn(async ({ limits }: { limits?: { maxCheckRunPages?: number } }) =>
+ limits?.maxCheckRunPages === 1 ? incomplete : { ...value, checks: 'failing' as const },
+ );
+ const lookup = createPullRequestLookup({ source: { find } });
+ await expect(lookup({ ...input, limits: { maxCheckRunPages: 1 } })).resolves.toEqual({
+ ok: true,
+ value: incomplete,
+ });
+ await expect(lookup({ ...input, limits: { maxCheckRunPages: 50 } })).resolves.toMatchObject({
+ value: { checks: 'failing' },
+ });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('honors the shorter freshness of a caller instead of the longer one another set', async () => {
+ let clock = 0;
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find }, now: () => clock });
+ await lookup({ ...input, ttlMs: 3_600_000 });
+ clock = 6_000;
+ await lookup({ ...input, ttlMs: 5_000 });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('does not share an in-flight request between different policies', async () => {
+ const find = jest.fn(() => new Promise<null>(() => undefined));
+ const lookup = createPullRequestLookup({ source: { find } });
+ void lookup({ ...input, limits: { maxCheckRunPages: 1 } });
+ void lookup({ ...input, limits: { maxCheckRunPages: 2 } });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('keys by the recorded head, so a reused branch name does not share a result', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, head: 'a'.repeat(40) });
+ await lookup({ ...input, head: 'b'.repeat(40) });
+ await lookup({ ...input, head: 'a'.repeat(40) });
+ expect(find).toHaveBeenCalledTimes(2);
+ });
+
+ it('treats an unchanged policy as the same entry', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, limits: { maxCheckRunPages: 3, requestTimeoutMs: 5_000 } });
+ await lookup({ ...input, limits: { requestTimeoutMs: 5_000, maxCheckRunPages: 3 } });
+ expect(find).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('lookup policy scoping of the history search', () => {
+ it.each([['maxCandidatePullRequests'], ['maxHeadComparisons']])(
+ 'does not share a result between callers with different %s',
+ async (field) => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, limits: { [field]: 3 } });
+ await lookup({ ...input, limits: { [field]: 30 } });
+ expect(find).toHaveBeenCalledTimes(2);
+ },
+ );
+});
+
+describe('cache capacity from the caller', () => {
+ const branches = ['a', 'b', 'c'];
+ const fill = async (
+ lookup: ReturnType<typeof createPullRequestLookup>,
+ cacheMaxEntries?: number,
+ ) => {
+ for (const branch of branches) await lookup({ ...input, branch, cacheMaxEntries });
+ await lookup({ ...input, branch: 'a', cacheMaxEntries });
+ };
+
+ it('evicts fresh entries once the configured capacity is exceeded', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ await fill(createPullRequestLookup({ source: { find } }), 2);
+ expect(find).toHaveBeenCalledTimes(4);
+ });
+
+ it('keeps them while the configured capacity is large enough', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ await fill(createPullRequestLookup({ source: { find } }), 10);
+ expect(find).toHaveBeenCalledTimes(3);
+ });
+
+ it('falls back to its own default capacity when the caller gives none', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ await fill(createPullRequestLookup({ source: { find } }));
+ expect(find).toHaveBeenCalledTimes(3);
+ });
+
+ it('does not treat the capacity as part of the answer, so callers with different ones share an entry', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, cacheMaxEntries: 5 });
+ await lookup({ ...input, cacheMaxEntries: 50 });
+ expect(find).toHaveBeenCalledTimes(1);
+ });
+});
+
+describe('cache capacity per credential', () => {
+ it("does not let one credential's small capacity evict another credential's entries", async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, token: 'big', branch: 'keep', cacheMaxEntries: 100 });
+ for (const branch of ['a', 'b', 'c', 'd']) {
+ await lookup({ ...input, token: 'small', branch, cacheMaxEntries: 2 });
+ }
+ const before = find.mock.calls.length;
+ await lookup({ ...input, token: 'big', branch: 'keep', cacheMaxEntries: 100 });
+ expect(find).toHaveBeenCalledTimes(before);
+ });
+
+ it('bounds the credentials it keeps, dropping the one idle longest', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ await lookup({ ...input, token: 'first' });
+ for (let index = 0; index < 256; index += 1) {
+ await lookup({ ...input, token: `other-${index}` });
+ }
+ const before = find.mock.calls.length;
+ await lookup({ ...input, token: 'first' });
+ expect(find).toHaveBeenCalledTimes(before + 1);
+ });
+
+ it('keeps more credentials when the caller configures a larger bound', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ const call = (token: string) => lookup({ ...input, token, cacheMaxCredentials: 300 });
+ await call('first');
+ for (let index = 0; index < 256; index += 1) await call(`other-${index}`);
+ const before = find.mock.calls.length;
+ await call('first');
+ expect(find).toHaveBeenCalledTimes(before);
+ });
+
+ it('drops credentials past the configured bound', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ const call = (token: string) => lookup({ ...input, token, cacheMaxCredentials: 2 });
+ await call('a');
+ await call('b');
+ await call('c');
+ const before = find.mock.calls.length;
+ await call('a');
+ expect(find).toHaveBeenCalledTimes(before + 1);
+ });
+
+ it('does not let a caller with a small bound evict the credentials of one with a large bound', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ for (const token of ['a', 'b', 'c']) {
+ await lookup({ ...input, token, cacheMaxCredentials: 100 });
+ }
+ await lookup({ ...input, token: 'small', cacheMaxCredentials: 1 });
+ const before = find.mock.calls.length;
+ for (const token of ['a', 'b', 'c']) {
+ await lookup({ ...input, token, cacheMaxCredentials: 100 });
+ }
+ expect(find).toHaveBeenCalledTimes(before);
+ });
+
+ it('counts a cache hit as use, so an active credential is not the one dropped', async () => {
+ const find = jest.fn().mockResolvedValue(value);
+ const lookup = createPullRequestLookup({ source: { find } });
+ const call = (token: string) => lookup({ ...input, token, cacheMaxCredentials: 2 });
+ await call('active');
+ await call('idle');
+ await call('active');
+ await call('newcomer');
+ const before = find.mock.calls.length;
+ await call('active');
+ expect(find).toHaveBeenCalledTimes(before);
+ });
+});
diff --git a/packages/api/src/pulls/lookup.ts b/packages/api/src/pulls/lookup.ts
new file mode 100644
index 0000000000..c53fecd324
--- /dev/null
+++ b/packages/api/src/pulls/lookup.ts
@@ -0,0 +1,161 @@
+import { createHash } from 'node:crypto';
+import { logger } from '@librechat/data-schemas';
+import type { PullRequestLookup, PullRequestLookupResult, PullRequestSource } from './types';
+import { PullRequestSourceError } from './types';
+import { getSafeErrorMetadata } from '~/utils';
+
+/** A failed lookup is remembered briefly so a failing upstream is not hammered by every poll. */
+const FAILURE_TTL_MS = 10_000;
+/** Used when GitHub rate limits a credential without saying when to come back. */
+const MIN_COOLDOWN_MS = 10_000;
+/** GitHub's primary limit resets within the hour; a larger hint is malformed and is capped. */
+const MAX_COOLDOWN_MS = 60 * 60_000;
+const DEFAULT_MAX_ENTRIES = 500;
+/** Credentials with a cache partition at once unless configured; the least recently used goes. */
+const DEFAULT_MAX_PARTITIONS = 256;
+
+type Entry = { result: PullRequestLookupResult; expiresAt: number };
+
+/** Keys carry a digest, never the token, so no credential is held in a map key or a heap dump. */
+const scopeOf = (token: string): string =>
+ createHash('sha256').update(token).digest('hex').slice(0, 32);
+
+/**
+ * Caches lookups per credential, repository, branch, recorded commit and lookup policy, and shares
+ * one in-flight request between concurrent callers with all of those in common. Each credential
+ * has its own bounded partition, sized by the capacity its callers ask for. What a token can see is part of the answer (a
+ * private repository is a pull request for one tenant and nothing for another), so the credential
+ * scopes both the cache and the in-flight map. A rate limit applies to the credential, not the
+ * branch, so it starts a cooldown for every branch under that credential. Callers must have
+ * authorized the conversation before asking.
+ */
+export function createPullRequestLookup({
+ source,
+ now = Date.now,
+ maxEntries = DEFAULT_MAX_ENTRIES,
+}: {
+ source: PullRequestSource;
+ now?: () => number;
+ maxEntries?: number;
+}): PullRequestLookup {
+ /** One bounded partition per credential, so a capacity setting only ever evicts entries
+ * fetched with its own credential. */
+ const partitions = new Map<string, Map<string, Entry>>();
+ const inflight = new Map<string, Promise<PullRequestLookupResult>>();
+ const cooldowns = new Map<string, number>();
+ const rateLimited: PullRequestLookupResult = { ok: false, error: { code: 'RATE_LIMITED' } };
+
+ /**
+ * The credential bound is one deployment-wide number. Callers may carry different configured
+ * values (per-principal config), and one asking for a small bound must not evict the credentials
+ * of another, so the largest value asked for so far applies.
+ */
+ let credentialBound = 0;
+
+ /** Recency of use orders the partitions, so the one idle longest is the one dropped. */
+ function touch(scope: string): Map<string, Entry> | undefined {
+ const partition = partitions.get(scope);
+ if (partition == null) return undefined;
+ partitions.delete(scope);
+ partitions.set(scope, partition);
+ return partition;
+ }
+
+ function partitionOf(scope: string, credentials: number): Map<string, Entry> {
+ credentialBound = Math.max(credentialBound, credentials);
+ const partition = touch(scope) ?? new Map<string, Entry>();
+ partitions.set(scope, partition);
+ while (partitions.size > credentialBound) {
+ const idle = partitions.keys().next();
+ if (idle.done) break;
+ partitions.delete(idle.value);
+ }
+ return partition;
+ }
+
+ function remember(
+ scope: string,
+ key: string,
+ result: PullRequestLookupResult,
+ ttlMs: number,
+ capacity: number,
+ credentials: number,
+ ): void {
+ const lifetime = result.ok ? ttlMs : Math.min(ttlMs, FAILURE_TTL_MS);
+ const entries = partitionOf(scope, credentials);
+ entries.delete(key);
+ entries.set(key, { result, expiresAt: now() + lifetime });
+ while (entries.size > capacity) {
+ const oldest = entries.keys().next();
+ if (oldest.done) break;
+ entries.delete(oldest.value);
+ }
+ }
+
+ function startCooldown(scope: string, retryAfterMs?: number): void {
+ const wait = Math.min(MAX_COOLDOWN_MS, Math.max(MIN_COOLDOWN_MS, retryAfterMs ?? 0));
+ cooldowns.set(scope, now() + wait);
+ for (const [other, until] of cooldowns) {
+ if (until <= now()) cooldowns.delete(other);
+ }
+ }
+
+ return async ({
+ repo,
+ branch,
+ head,
+ token,
+ ttlMs,
+ limits,
+ cacheMaxEntries,
+ cacheMaxCredentials,
+ }) => {
+ const scope = scopeOf(token);
+ /** Everything that changes the answer or how long it may be reused is part of the key. */
+ const policy = [
+ ttlMs,
+ limits?.requestTimeoutMs,
+ limits?.lookupTimeoutMs,
+ limits?.maxCheckRunPages,
+ limits?.maxCandidatePullRequests,
+ limits?.maxHeadComparisons,
+ ].join(',');
+ const key = `${scope}\0${repo}#${branch}\0${head ?? ''}\0${policy}`;
+ const cached = touch(scope)?.get(key);
+ if (cached != null && cached.expiresAt > now()) return cached.result;
+ const pending = inflight.get(key);
+ if (pending != null) return pending;
+ const until = cooldowns.get(scope);
+ if (until != null) {
+ if (until > now()) return rateLimited;
+ cooldowns.delete(scope);
+ }
+
+ const run = (async (): Promise<PullRequestLookupResult> => {
+ let result: PullRequestLookupResult;
+ try {
+ result = { ok: true, value: await source.find({ repo, branch, head, token, limits }) };
+ } catch (error) {
+ if (!(error instanceof PullRequestSourceError)) {
+ logger.warn('[PullRequests] Lookup failed', getSafeErrorMetadata(error));
+ }
+ const code = error instanceof PullRequestSourceError ? error.code : 'UPSTREAM_ERROR';
+ if (error instanceof PullRequestSourceError && error.code === 'RATE_LIMITED') {
+ startCooldown(scope, error.retryAfterMs);
+ }
+ result = { ok: false, error: { code } };
+ }
+ remember(
+ scope,
+ key,
+ result,
+ ttlMs,
+ cacheMaxEntries ?? maxEntries,
+ cacheMaxCredentials ?? DEFAULT_MAX_PARTITIONS,
+ );
+ return result;
+ })().finally(() => inflight.delete(key));
+ inflight.set(key, run);
+ return run;
+ };
+}
diff --git a/packages/api/src/pulls/types.ts b/packages/api/src/pulls/types.ts
new file mode 100644
index 0000000000..e177e67bc6
--- /dev/null
+++ b/packages/api/src/pulls/types.ts
@@ -0,0 +1,64 @@
+import type { TConversationPullRequest } from 'librechat-data-provider';
+
+/** Stable, user-safe reasons a lookup could not answer. None carries upstream text. */
+export const PULL_REQUEST_ERROR_CODES = [
+ 'NOT_CONFIGURED',
+ 'RATE_LIMITED',
+ 'UPSTREAM_ERROR',
+] as const;
+export type PullRequestErrorCode = (typeof PULL_REQUEST_ERROR_CODES)[number];
+
+/** Thrown by a source for an operational failure; the lookup translates it into a result. */
+export class PullRequestSourceError extends Error {
+ constructor(
+ public readonly code: PullRequestErrorCode,
+ /** For `RATE_LIMITED`: how long GitHub asked callers to wait, when it said. */
+ public readonly retryAfterMs?: number,
+ ) {
+ super(`Pull request lookup failed: ${code}`);
+ this.name = 'PullRequestSourceError';
+ }
+}
+
+/** Operator bounds on one lookup; each defaults to the value the feature shipped with. */
+export type PullRequestLookupLimits = {
+ /** Longest one GitHub request may take. */
+ requestTimeoutMs?: number;
+ /** Longest the whole lookup, every request together, may take. */
+ lookupTimeoutMs?: number;
+ /** Most pages of check runs read before the rollup is reported as still running. */
+ maxCheckRunPages?: number;
+ /** Most pull requests listed per state when searching a branch's history for the match. */
+ maxCandidatePullRequests?: number;
+ /** Most candidates compared with the recorded commit before the search gives up. */
+ maxHeadComparisons?: number;
+};
+
+export type PullRequestFindInput = {
+ /** `owner/name`. */
+ repo: string;
+ branch: string;
+ /** The commit the conversation last ran at; a pull request must carry it to be the match. */
+ head?: string | null;
+ token: string;
+ limits?: PullRequestLookupLimits;
+};
+
+/** Finds the pull request for a branch. Null is a documented absence, not a failure. */
+export type PullRequestSource = {
+ find(input: PullRequestFindInput): Promise<TConversationPullRequest | null>;
+};
+
+export type PullRequestLookupResult =
+ | { ok: true; value: TConversationPullRequest | null }
+ | { ok: false; error: { code: PullRequestErrorCode } };
+
+export type PullRequestLookupInput = PullRequestFindInput & {
+ ttlMs: number;
+ /** Entries the shared cache holds before it evicts the oldest; the lookup's own default if omitted. */
+ cacheMaxEntries?: number;
+ /** Credentials cached at once; the lookup's own default if omitted. */
+ cacheMaxCredentials?: number;
+};
+
+export type PullRequestLookup = (input: PullRequestLookupInput) => Promise<PullRequestLookupResult>;
diff --git a/packages/data-provider/src/config.spec.ts b/packages/data-provider/src/config.spec.ts
index 7123e83c4c..99fb5de8b0 100644
--- a/packages/data-provider/src/config.spec.ts
+++ b/packages/data-provider/src/config.spec.ts
@@ -1125,25 +1125,93 @@ describe('agent pull request config', () => {
version: '1.0',
endpoints: { agents: { pullRequests: {} } },
});
- expect(empty.endpoints?.agents?.pullRequests).toEqual({ enabled: false, cacheTtlSeconds: 30 });
+ expect(empty.endpoints?.agents?.pullRequests).toEqual({
+ enabled: false,
+ cacheTtlSeconds: 30,
+ requestTimeoutSeconds: 10,
+ lookupTimeoutSeconds: 30,
+ maxCheckRunPages: 10,
+ maxCandidatePullRequests: 10,
+ maxHeadComparisons: 3,
+ cacheMaxEntries: 500,
+ cacheMaxCredentials: 256,
+ });
});
- it('accepts an enabled block with an environment variable reference', () => {
- const result = parse({ enabled: true, token: '${GITHUB_PULL_REQUEST_TOKEN}' });
- expect(result.success).toBe(true);
+ const enabled = {
+ enabled: true,
+ token: '${GITHUB_PULL_REQUEST_TOKEN}',
+ allowedRepositories: ['LibreChat-AI/LibreChat'],
+ };
+
+ it('accepts an enabled block with a token reference and an allowed repository', () => {
+ expect(parse(enabled).success).toBe(true);
});
it('requires a token reference when enabled', () => {
- expect(parse({ enabled: true }).success).toBe(false);
+ expect(parse({ ...enabled, token: undefined }).success).toBe(false);
+ });
+
+ it('requires at least one allowed repository when enabled, so a worker cannot name its own', () => {
+ expect(parse({ ...enabled, allowedRepositories: undefined }).success).toBe(false);
+ expect(parse({ ...enabled, allowedRepositories: [] }).success).toBe(false);
+ });
+
+ it.each(['LibreChat-AI/*', 'o/r', 'My.Org/my_repo-2'])('accepts the repository %s', (repo) => {
+ expect(parse({ ...enabled, allowedRepositories: [repo] }).success).toBe(true);
});
+ it.each(['*/*', '*', 'owner', 'o/r/extra', '../x', 'o/..', 'a b/c', 'o/*x', ''])(
+ 'rejects %p as an allowed repository',
+ (repo) => {
+ expect(parse({ ...enabled, allowedRepositories: [repo] }).success).toBe(false);
+ },
+ );
+
it.each(['ghp_abcdef', '${bad name}', '$GITHUB_TOKEN', '${}'])(
'rejects %s as a token because only a reference is allowed',
(token) => {
- expect(parse({ enabled: true, token }).success).toBe(false);
+ expect(parse({ ...enabled, token }).success).toBe(false);
},
);
+ it.each([
+ ['requestTimeoutSeconds', 0],
+ ['requestTimeoutSeconds', 61],
+ ['lookupTimeoutSeconds', 0],
+ ['lookupTimeoutSeconds', 121],
+ ['maxCheckRunPages', 0],
+ ['maxCheckRunPages', 51],
+ ['maxCheckRunPages', 1.5],
+ ['maxCandidatePullRequests', 0],
+ ['maxCandidatePullRequests', 101],
+ ['maxHeadComparisons', -1],
+ ['maxHeadComparisons', 21],
+ ['maxHeadComparisons', 1.5],
+ ['cacheMaxEntries', 9],
+ ['cacheMaxEntries', 100_001],
+ ['cacheMaxEntries', 1.5],
+ ['cacheMaxCredentials', 0],
+ ['cacheMaxCredentials', 10_001],
+ ['cacheMaxCredentials', 1.5],
+ ])('rejects %s of %s', (field, value) => {
+ expect(parse({ [field]: value }).success).toBe(false);
+ });
+
+ it('accepts the documented bounds', () => {
+ expect(
+ parse({
+ requestTimeoutSeconds: 60,
+ lookupTimeoutSeconds: 120,
+ maxCheckRunPages: 50,
+ maxCandidatePullRequests: 100,
+ maxHeadComparisons: 20,
+ cacheMaxEntries: 100_000,
+ }).success,
+ ).toBe(true);
+ expect(parse({ maxHeadComparisons: 0 }).success).toBe(true);
+ });
+
it.each([4, 3601, 1.5])('rejects a cache lifetime of %s seconds', (cacheTtlSeconds) => {
expect(parse({ cacheTtlSeconds }).success).toBe(false);
});
diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.ts
index 38e7fdfb27..05d522b8cd 100644
--- a/packages/data-provider/src/config.ts
+++ b/packages/data-provider/src/config.ts
@@ -498,6 +498,17 @@ const skillSyncTenantIdSchema = z
message: 'must not be the reserved system tenant id',
});
+/** `owner/name`, or `owner/*` for every repository of one owner; never a bare `*`. */
+const pullRequestRepositorySchema = z
+ .string()
+ .trim()
+ .regex(/^[A-Za-z0-9_.-]+\/(?:[A-Za-z0-9_.-]+|\*)$/, {
+ message: 'must be owner/name or owner/*',
+ })
+ .refine((value) => value.split('/').every((segment) => segment !== '.' && segment !== '..'), {
+ message: 'must not contain dot segments',
+ });
+
const pullRequestTokenReferenceSchema = z
.string()
.trim()
@@ -1851,8 +1862,31 @@ export const agentsEndpointSchema = baseEndpointSchema
/** Environment variable reference holding a read-only GitHub token, e.g.
* `${GITHUB_PULL_REQUEST_TOKEN}`. Never the token itself. */
token: pullRequestTokenReferenceSchema.optional(),
+ /** Repositories the token may be used for, as `owner/name` or `owner/*`. A worker reports
+ * its own repository, so without this list a user could point the server's token at any
+ * repository it can read. */
+ allowedRepositories: z.array(pullRequestRepositorySchema).max(256).optional(),
/** Seconds a looked-up pull request is reused before GitHub is asked again. */
cacheTtlSeconds: z.number().int().min(5).max(3600).optional().default(30),
+ /** Pull requests cached per credential before the oldest is evicted. Size it to the
+ * distinct repository and branch combinations seen within one cache lifetime, or fresh
+ * results are evicted and GitHub is asked again. */
+ cacheMaxEntries: z.number().int().min(10).max(100_000).optional().default(500),
+ /** Credentials whose results are cached at once; past it the one idle longest is dropped.
+ * Deployment-wide: when principals configure different values, the largest applies.
+ * Raise it when many tenants each configure their own token. */
+ cacheMaxCredentials: z.number().int().min(1).max(10_000).optional().default(256),
+ /** Longest one GitHub request may take. Raise it behind a slow proxy. */
+ requestTimeoutSeconds: z.number().int().min(1).max(60).optional().default(10),
+ /** Longest a whole lookup, every request together, may hold the header request. */
+ lookupTimeoutSeconds: z.number().int().min(1).max(120).optional().default(30),
+ /** Pages of 100 check runs read before the rollup is reported as still running. */
+ maxCheckRunPages: z.number().int().min(1).max(50).optional().default(10),
+ /** Pull requests listed per state when matching a branch's history to the commit a chat
+ * last ran at. Raise it for branch names that are reused many times. */
+ maxCandidatePullRequests: z.number().int().min(1).max(100).optional().default(10),
+ /** Candidates compared with that commit before the search gives up. Each is one request. */
+ maxHeadComparisons: z.number().int().min(0).max(20).optional().default(3),
})
.superRefine((value, ctx) => {
if (value.enabled && !value.token) {
@@ -1862,6 +1896,13 @@ export const agentsEndpointSchema = baseEndpointSchema
message: 'A token reference is required when pull requests are enabled',
});
}
+ if (value.enabled && (value.allowedRepositories?.length ?? 0) === 0) {
+ ctx.addIssue({
+ code: z.ZodIssueCode.custom,
+ path: ['allowedRepositories'],
+ message: 'At least one allowed repository is required when pull requests are enabled',
+ });
+ }
})
.optional(),
/** Conversational background-task delivery policy. Automatic completion wakeups are
diff --git a/packages/data-schemas/src/methods/conversation.spec.ts b/packages/data-schemas/src/methods/conversation.spec.ts
index 3498cf9e7f..6215f558d7 100644
--- a/packages/data-schemas/src/methods/conversation.spec.ts
+++ b/packages/data-schemas/src/methods/conversation.spec.ts
@@ -1679,6 +1679,63 @@ describe('Conversation Operations', () => {
});
};
+ describe('stale lane state', () => {
+ const lane = { branch: 'feat/old', head: 'a'.repeat(40), repo: 'o/old' };
+ const stored = (conversationId: string) =>
+ methods.getConvoCodeEnvironmentDecision('user123', conversationId);
+
+ it('is cleared when the chat moves to another workspace', async () => {
+ const conversationId = await seedDecision({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [mac],
+ laneGit: lane,
+ });
+ await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toEqual(lane);
+ await moveFromStored(conversationId, [team]);
+ await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toBeNull();
+ });
+
+ it('is cleared when the chat leaves attached execution', async () => {
+ const conversationId = await seedDecision({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [mac],
+ laneGit: lane,
+ });
+ const decision = await stored(conversationId);
+ await methods.replaceConvoCodeEnvironmentDecision({
+ user: 'user123',
+ conversationId,
+ expected: {
+ codeEnvironmentMode: decision?.codeEnvironmentMode,
+ codeWorkspaces: decision?.codeWorkspaces,
+ codeEnvironmentRevision: decision?.codeEnvironmentRevision,
+ },
+ codeEnvironmentMode: 'without_attached',
+ });
+ await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toBeNull();
+ });
+
+ it('is kept when the move is refused', async () => {
+ const conversationId = await seedDecision({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [mac],
+ laneGit: lane,
+ });
+ await methods.replaceConvoCodeEnvironmentDecision({
+ user: 'user123',
+ conversationId,
+ expected: {
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [team],
+ codeEnvironmentRevision: 99,
+ },
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [vm],
+ });
+ await expect(methods.getConvoLaneGit('user123', conversationId)).resolves.toEqual(lane);
+ });
+ });
+
it('replaces the decision it read without disturbing timestamps', async () => {
const conversationId = await seedDecision({
codeEnvironmentMode: 'attached',
@@ -9359,6 +9416,353 @@ describe('Conversation Operations', () => {
});
});
+describe('laneGit', () => {
+ const seed = async (user = 'lane-user') => {
+ const conversationId = uuidv4();
+ await Conversation.create({ conversationId, user, title: 'Lane test', endpoint: 'agents' });
+ return conversationId;
+ };
+ const head = 'a'.repeat(40);
+ /** A write with a sequence number drawn from the database, as the recorder draws one. */
+ const record = async (
+ input: Omit<Parameters<typeof methods.setConvoLaneGit>[0], 'seq'> & { seq?: number },
+ ) => {
+ const seq =
+ input.seq ?? (await methods.reserveConvoLaneGitSeq(input.user, input.conversationId));
+ if (seq == null) return false;
+ return methods.setConvoLaneGit({ ...input, seq });
+ };
+
+ it('stores the reported branch and head for the owner and reads them back', async () => {
+ const conversationId = await seed();
+ const laneGit = { branch: 'feat/pr-chip', head };
+ await expect(record({ user: 'lane-user', conversationId, laneGit })).resolves.toBe(true);
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(laneGit);
+ });
+
+ it('does not write for another owner or an unknown conversation', async () => {
+ const conversationId = await seed();
+ const laneGit = { branch: 'main', head };
+ await expect(record({ user: 'intruder', conversationId, laneGit })).resolves.toBe(false);
+ await expect(record({ user: 'lane-user', conversationId: uuidv4(), laneGit })).resolves.toBe(
+ false,
+ );
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
+ await expect(methods.getConvoLaneGit('intruder', conversationId)).resolves.toBeNull();
+ });
+
+ it('ignores a report with a lower sequence number, so a delayed write cannot win', async () => {
+ const conversationId = await seed();
+ const user = 'lane-user';
+ const first = await methods.reserveConvoLaneGitSeq(user, conversationId);
+ const second = await methods.reserveConvoLaneGitSeq(user, conversationId);
+ const newer = { branch: 'newer', head };
+ const older = { branch: 'older', head: 'b'.repeat(40) };
+ await expect(
+ methods.setConvoLaneGit({ user, conversationId, laneGit: newer, seq: second as number }),
+ ).resolves.toBe(true);
+ await expect(
+ methods.setConvoLaneGit({ user, conversationId, laneGit: older, seq: first as number }),
+ ).resolves.toBe(false);
+ await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual(newer);
+ });
+
+ it('issues increasing numbers per conversation and none for an unknown one', async () => {
+ const conversationId = await seed();
+ const other = await seed();
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(1);
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(2);
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', other)).toBe(1);
+ expect(await methods.reserveConvoLaneGitSeq('intruder', conversationId)).toBeNull();
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', uuidv4())).toBeNull();
+ });
+
+ it('issues distinct numbers to reservations made at the same time', async () => {
+ const conversationId = await seed();
+ const numbers = await Promise.all(
+ Array.from({ length: 12 }, () => methods.reserveConvoLaneGitSeq('lane-user', conversationId)),
+ );
+ expect(new Set(numbers).size).toBe(12);
+ expect(Math.min(...(numbers as number[]))).toBe(1);
+ expect(Math.max(...(numbers as number[]))).toBe(12);
+ });
+
+ it('is not skewed by the clocks of the processes that report', async () => {
+ const conversationId = await seed();
+ const user = 'lane-user';
+ const early = await methods.reserveConvoLaneGitSeq(user, conversationId);
+ const later = await methods.reserveConvoLaneGitSeq(user, conversationId);
+ /** An older report from a replica whose clock runs far ahead still carries the lower number. */
+ await expect(
+ methods.setConvoLaneGit({
+ user,
+ conversationId,
+ laneGit: { branch: 'later', head },
+ seq: later as number,
+ }),
+ ).resolves.toBe(true);
+ await expect(
+ methods.setConvoLaneGit({
+ user,
+ conversationId,
+ laneGit: { branch: 'early-but-future-clock', head },
+ seq: early as number,
+ }),
+ ).resolves.toBe(false);
+ await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual({
+ branch: 'later',
+ head,
+ });
+ });
+
+ it('does not expose the sequence number or the counter through the read', async () => {
+ const conversationId = await seed();
+ await record({ user: 'lane-user', conversationId, laneGit: { branch: 'main', head } });
+ const stored = await methods.getConvoLaneGit('lane-user', conversationId);
+ expect(stored).not.toHaveProperty('seq');
+ const read = await Conversation.findOne({ conversationId }).lean();
+ expect(read).not.toHaveProperty('laneGitSeq');
+ });
+
+ it('replaces the stored state when the branch or head changes', async () => {
+ const conversationId = await seed();
+ const user = 'lane-user';
+ await record({ user, conversationId, laneGit: { branch: 'main', head } });
+ const next = { branch: 'feat/x', head: 'b'.repeat(40) };
+ await expect(record({ user, conversationId, laneGit: next })).resolves.toBe(true);
+ await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual(next);
+ });
+
+ it('stores the repository with the lane and replaces it when the repository changes', async () => {
+ const conversationId = await seed();
+ const user = 'lane-user';
+ const laneGit = { branch: 'main', head };
+ await expect(record({ user, conversationId, laneGit, repo: 'o/r' })).resolves.toBe(true);
+ await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual({
+ ...laneGit,
+ repo: 'o/r',
+ });
+ await expect(record({ user, conversationId, laneGit, repo: 'o/other' })).resolves.toBe(true);
+ await expect(methods.getConvoLaneGit(user, conversationId)).resolves.toEqual({
+ ...laneGit,
+ repo: 'o/other',
+ });
+ });
+
+ describe('workspace fence', () => {
+ const mac = { environmentId: 'code-mac', workspaceId: 'primary' };
+ const team = { environmentId: 'code-team', workspaceId: 'shared' };
+ const seedRaw = async (decision: Record<string, unknown>) => {
+ const conversationId = uuidv4();
+ await Conversation.collection.insertOne({
+ conversationId,
+ user: 'lane-user',
+ title: 'Fence',
+ endpoint: 'agents',
+ messages: [],
+ ...decision,
+ });
+ return conversationId;
+ };
+ const write = (conversationId: string, workspace: Record<string, unknown>) =>
+ record({
+ user: 'lane-user',
+ conversationId,
+ laneGit: { branch: 'feat/x', head },
+ workspace: workspace as never,
+ });
+
+ it('records for the workspace the conversation is attached to', async () => {
+ const conversationId = await seedRaw({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [mac],
+ });
+ await expect(write(conversationId, mac)).resolves.toBe(true);
+ });
+
+ it('refuses a report from a workspace the conversation moved away from', async () => {
+ const conversationId = await seedRaw({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [team],
+ });
+ await expect(write(conversationId, mac)).resolves.toBe(false);
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
+ });
+
+ it('refuses a report once the conversation has left attached execution', async () => {
+ const conversationId = await seedRaw({ codeEnvironmentMode: 'without_attached' });
+ await expect(write(conversationId, mac)).resolves.toBe(false);
+ });
+
+ it('does not let a write queued before a move repopulate the cleared lane', async () => {
+ const conversationId = await seedRaw({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [mac],
+ laneGit: { branch: 'old', head, repo: 'o/old', seq: 1 },
+ });
+ const stored = await methods.getConvoCodeEnvironmentDecision('lane-user', conversationId);
+ await methods.replaceConvoCodeEnvironmentDecision({
+ user: 'lane-user',
+ conversationId,
+ expected: {
+ codeEnvironmentMode: stored?.codeEnvironmentMode,
+ codeWorkspaces: stored?.codeWorkspaces,
+ codeEnvironmentRevision: stored?.codeEnvironmentRevision,
+ },
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [team],
+ });
+ await expect(write(conversationId, mac)).resolves.toBe(false);
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
+ });
+
+ it('records when no workspace is stored yet, as for an agent default workspace', async () => {
+ const conversationId = await seedRaw({});
+ await expect(write(conversationId, mac)).resolves.toBe(true);
+ });
+
+ it('refuses an unrecorded workspace when the caller requires a recorded one', async () => {
+ const conversationId = await seedRaw({});
+ await expect(write(conversationId, { ...mac, required: true })).resolves.toBe(false);
+ });
+
+ it('accepts a required workspace that matches the recorded one', async () => {
+ const conversationId = await seedRaw({
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: [mac, team],
+ });
+ await expect(write(conversationId, { ...team, required: true })).resolves.toBe(true);
+ });
+ });
+
+ describe('retention', () => {
+ const lane = { branch: 'feat/x', head, seq: 1 };
+ const seedExpiry = async (expiredAt: Date | null) => {
+ const conversationId = uuidv4();
+ await Conversation.collection.insertOne({
+ conversationId,
+ user: 'lane-user',
+ title: 'Retention',
+ endpoint: 'agents',
+ messages: [],
+ laneGit: lane,
+ laneGitSeq: 1,
+ expiredAt,
+ });
+ return conversationId;
+ };
+ const past = () => new Date(Date.now() - 60_000);
+ const future = () => new Date(Date.now() + 3_600_000);
+
+ it('does not serve the lane of an expired temporary chat', async () => {
+ const conversationId = await seedExpiry(past());
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
+ });
+
+ it('does not reserve a number for, or write to, an expired temporary chat', async () => {
+ const conversationId = await seedExpiry(past());
+ await expect(methods.reserveConvoLaneGitSeq('lane-user', conversationId)).resolves.toBeNull();
+ await expect(
+ methods.setConvoLaneGit({
+ user: 'lane-user',
+ conversationId,
+ laneGit: { branch: 'later', head },
+ seq: 99,
+ }),
+ ).resolves.toBe(false);
+ });
+
+ it.each([
+ ['no expiry', null],
+ ['an expiry in the future', future()],
+ ])('still serves, reserves for and writes to a chat with %s', async (_label, expiredAt) => {
+ const conversationId = await seedExpiry(expiredAt);
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toMatchObject({
+ branch: 'feat/x',
+ });
+ const seq = await methods.reserveConvoLaneGitSeq('lane-user', conversationId);
+ expect(seq).toBe(2);
+ await expect(
+ methods.setConvoLaneGit({
+ user: 'lane-user',
+ conversationId,
+ laneGit: { branch: 'later', head },
+ seq: seq as number,
+ }),
+ ).resolves.toBe(true);
+ });
+ });
+
+ it('keeps a detached or empty lane distinct from an unknown one', async () => {
+ const conversationId = await seed();
+ const laneGit = { branch: null, head: null };
+ await expect(record({ user: 'lane-user', conversationId, laneGit })).resolves.toBe(true);
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(laneGit);
+ });
+
+ describe('server-written only', () => {
+ const kept = { branch: 'kept', head };
+ const seedWithLane = async () => {
+ const conversationId = await seed();
+ await record({ user: 'lane-user', conversationId, laneGit: kept });
+ return conversationId;
+ };
+
+ it('is not overwritten by a generic save', async () => {
+ const conversationId = await seedWithLane();
+ await saveConvo(
+ { userId: 'lane-user' },
+ { conversationId, laneGit: { branch: 'forged', head: null } },
+ );
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(kept);
+ });
+
+ it('is not cleared by a generic save', async () => {
+ const conversationId = await seedWithLane();
+ await saveConvo({ userId: 'lane-user' }, { conversationId }, { unsetFields: { laneGit: 1 } });
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual(kept);
+ });
+
+ it('is not accepted from a bulk import', async () => {
+ const imported = uuidv4();
+ await methods.bulkSaveConvos([
+ {
+ conversationId: imported,
+ user: 'lane-user',
+ title: 'Imported',
+ laneGit: { branch: 'x', head: null },
+ },
+ ]);
+ await expect(methods.getConvoLaneGit('lane-user', imported)).resolves.toBeNull();
+ });
+
+ it('keeps the sequence counter out of generic saves, unset fields and imports', async () => {
+ const conversationId = await seedWithLane();
+ const before = await methods.reserveConvoLaneGitSeq('lane-user', conversationId);
+ await saveConvo({ userId: 'lane-user' }, { conversationId, laneGitSeq: 0 });
+ await saveConvo(
+ { userId: 'lane-user' },
+ { conversationId },
+ { unsetFields: { laneGitSeq: 1 } },
+ );
+ const imported = uuidv4();
+ await methods.bulkSaveConvos([
+ { conversationId: imported, user: 'lane-user', title: 'Imported', laneGitSeq: 99 },
+ ]);
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(
+ (before as number) + 1,
+ );
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', imported)).toBe(1);
+ });
+
+ it('is excluded from ordinary conversation reads', async () => {
+ const conversationId = await seedWithLane();
+ const read = await Conversation.findOne({ conversationId }).lean();
+ expect(read).not.toHaveProperty('laneGit');
+ });
+ });
+});
+
describe('stampForcedRetention', () => {
const ephemeral = { retentionMode: RetentionMode.EPHEMERAL, temporaryChatRetention: 1 };
let userId: string;
@@ -9509,3 +9913,199 @@ describe('stampForcedRetention', () => {
},
);
});
+
+describe('laneGit review hardening', () => {
+ const head = 'a'.repeat(40);
+ const mac = { environmentId: 'code-mac', workspaceId: 'primary' };
+ const team = { environmentId: 'code-team', workspaceId: 'shared' };
+ const seedAttached = async (
+ workspaces: Array<{ environmentId: string; workspaceId: string }>,
+ ) => {
+ const conversationId = uuidv4();
+ await Conversation.collection.insertOne({
+ conversationId,
+ user: 'lane-user',
+ title: 'Hardening',
+ endpoint: 'agents',
+ messages: [],
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: workspaces,
+ });
+ return conversationId;
+ };
+ const move = async (
+ conversationId: string,
+ codeWorkspaces: Array<{ environmentId: string; workspaceId: string }>,
+ ) => {
+ const stored = await methods.getConvoCodeEnvironmentDecision('lane-user', conversationId);
+ return methods.replaceConvoCodeEnvironmentDecision({
+ user: 'lane-user',
+ conversationId,
+ expected: {
+ codeEnvironmentMode: stored?.codeEnvironmentMode,
+ codeWorkspaces: stored?.codeWorkspaces,
+ codeEnvironmentRevision: stored?.codeEnvironmentRevision,
+ },
+ codeEnvironmentMode: 'attached',
+ codeWorkspaces: codeWorkspaces as never,
+ });
+ };
+
+ describe('dotted import and save keys', () => {
+ it('does not let an import set a lane through dotted keys', async () => {
+ const imported = uuidv4();
+ await methods.bulkSaveConvos([
+ {
+ conversationId: imported,
+ user: 'lane-user',
+ title: 'Imported',
+ 'laneGit.branch': 'forged',
+ 'laneGit.repo': 'o/forged',
+ 'laneGit.seq': 999,
+ 'laneGitSeq.x': 1,
+ 'codeAttachmentEpoch.x': 5,
+ },
+ ]);
+ await expect(methods.getConvoLaneGit('lane-user', imported)).resolves.toBeNull();
+ const raw = await Conversation.collection.findOne({ conversationId: imported });
+ expect(raw).not.toHaveProperty('laneGit');
+ expect(raw).not.toHaveProperty('codeAttachmentEpoch');
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', imported)).toBe(1);
+ });
+
+ it('does not let a save set a lane through dotted keys or unset keys', async () => {
+ const conversationId = uuidv4();
+ await Conversation.create({ conversationId, user: 'lane-user', endpoint: 'agents' });
+ const seq = (await methods.reserveConvoLaneGitSeq('lane-user', conversationId)) as number;
+ await methods.setConvoLaneGit({
+ user: 'lane-user',
+ conversationId,
+ laneGit: { branch: 'kept', head },
+ seq,
+ });
+ await saveConvo(
+ { userId: 'lane-user' },
+ { conversationId, 'laneGit.branch': 'forged', 'laneGit.seq': 999 },
+ { unsetFields: { 'laneGit.repo': 1, 'laneGit.head': 1 } },
+ );
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toEqual({
+ branch: 'kept',
+ head,
+ });
+ expect(await methods.reserveConvoLaneGitSeq('lane-user', conversationId)).toBe(seq + 1);
+ });
+ });
+
+ describe('attachment epoch', () => {
+ const write = (
+ conversationId: string,
+ epoch: number | undefined,
+ workspace: { environmentId: string; workspaceId: string },
+ ) =>
+ methods.reserveConvoLaneGitSeq('lane-user', conversationId).then((seq) =>
+ methods.setConvoLaneGit({
+ user: 'lane-user',
+ conversationId,
+ laneGit: { branch: 'feat/x', head },
+ seq: seq as number,
+ workspace: { ...workspace, ...(epoch == null ? {} : { epoch }) },
+ }),
+ );
+
+ it('reads as zero until the conversation is moved, then advances on every move', async () => {
+ const conversationId = await seedAttached([mac]);
+ expect(
+ (await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch ?? 0,
+ ).toBe(0);
+ await move(conversationId, [team]);
+ expect(
+ (await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch,
+ ).toBe(1);
+ await move(conversationId, [mac]);
+ expect(
+ (await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch,
+ ).toBe(2);
+ });
+
+ it('applies a report from the epoch it was captured in', async () => {
+ const conversationId = await seedAttached([mac]);
+ await expect(write(conversationId, 0, mac)).resolves.toBe(true);
+ });
+
+ it('refuses a report from before a move away and back to the same workspace', async () => {
+ const conversationId = await seedAttached([mac]);
+ await move(conversationId, [team]);
+ await move(conversationId, [mac]);
+ await expect(write(conversationId, 0, mac)).resolves.toBe(false);
+ await expect(methods.getConvoLaneGit('lane-user', conversationId)).resolves.toBeNull();
+ await expect(write(conversationId, 2, mac)).resolves.toBe(true);
+ });
+
+ it('is not advanced by admitting a generation', async () => {
+ const conversationId = await seedAttached([mac]);
+ await methods.readAdmittedConvoCodeEnvironmentDecision('lane-user', conversationId);
+ await methods.readAdmittedConvoCodeEnvironmentDecision('lane-user', conversationId);
+ await expect(write(conversationId, 0, mac)).resolves.toBe(true);
+ });
+
+ it('keeps the epoch out of generic saves, unset fields and ordinary reads', async () => {
+ const conversationId = await seedAttached([mac]);
+ await move(conversationId, [team]);
+ await saveConvo(
+ { userId: 'lane-user' },
+ { conversationId, codeAttachmentEpoch: 0 },
+ { unsetFields: { codeAttachmentEpoch: 1 } },
+ );
+ expect(
+ (await methods.getConvoLaneContext('lane-user', conversationId))?.codeAttachmentEpoch,
+ ).toBe(1);
+ const read = await Conversation.findOne({ conversationId }).lean();
+ expect(read).not.toHaveProperty('codeAttachmentEpoch');
+ });
+ });
+
+ describe('subagent thread epoch', () => {
+ const seedThread = async (rootId: string) => {
+ const conversationId = uuidv4();
+ await Conversation.collection.insertOne({
+ conversationId,
+ user: 'lane-user',
+ title: 'Thread',
+ endpoint: 'agents',
+ messages: [],
+ subagentThread: { rootConversationId: rootId, parentConversationId: rootId },
+ });
+ return conversationId;
+ };
+
+ it("reads the epoch of the visible root the report is written to, not the thread's own", async () => {
+ const rootId = await seedAttached([mac]);
+ await move(rootId, [team]);
+ const threadId = await seedThread(rootId);
+ await expect(methods.getConvoLaneContext('lane-user', threadId)).resolves.toMatchObject({
+ codeAttachmentEpoch: 1,
+ subagentThread: { rootConversationId: rootId },
+ });
+ });
+
+ it('reads zero when the root is gone, so the write is refused rather than guessed', async () => {
+ const threadId = await seedThread(uuidv4());
+ await expect(methods.getConvoLaneContext('lane-user', threadId)).resolves.toMatchObject({
+ codeAttachmentEpoch: 0,
+ });
+ });
+ });
+
+ describe('lane context', () => {
+ it('returns the subagent route and the epoch in one read, owner-scoped', async () => {
+ const conversationId = await seedAttached([mac]);
+ await move(conversationId, [team]);
+ await expect(methods.getConvoLaneContext('lane-user', conversationId)).resolves.toMatchObject(
+ {
+ codeAttachmentEpoch: 1,
+ },
+ );
+ await expect(methods.getConvoLaneContext('intruder', conversationId)).resolves.toBeNull();
+ });
+ });
+});
diff --git a/packages/data-schemas/src/methods/conversation.ts b/packages/data-schemas/src/methods/conversation.ts
index 6baa5c0442..1391d71b4e 100644
--- a/packages/data-schemas/src/methods/conversation.ts
+++ b/packages/data-schemas/src/methods/conversation.ts
@@ -63,14 +63,30 @@ const ACTOR_CHECKPOINT_FIELDS = [
'agentEventActorSuspension',
] as const;
-function stripActorCheckpointFields(record: Record<string, unknown>): void {
+/** Removes each field and every dotted path beneath it, which Mongo reads as a write to the field. */
+function stripFields(record: Record<string, unknown>, fields: readonly string[]): void {
for (const key of Object.keys(record)) {
- if (ACTOR_CHECKPOINT_FIELDS.some((field) => key === field || key.startsWith(`${field}.`))) {
+ if (fields.some((field) => key === field || key.startsWith(`${field}.`))) {
delete record[key];
}
}
}
+function stripActorCheckpointFields(record: Record<string, unknown>): void {
+ stripFields(record, ACTOR_CHECKPOINT_FIELDS);
+}
+
+/** Written only by the lane methods, so no save, unset or import may reach them. */
+const LANE_PRIVATE_FIELDS = ['laneGit', 'laneGitSeq', 'codeAttachmentEpoch'] as const;
+
+/** What a lane recorder needs to place and fence its writes, read once when its tool is created. */
+export type ConvoLaneContext = {
+ subagentThread?: IConversation['subagentThread'] | null;
+ /** Counts the owner's moves and detaches of the workspace the report is written to (the visible
+ * root for a subagent thread); 0 until the first. */
+ codeAttachmentEpoch: number;
+};
+
const AGENT_EVENT_ACTOR_RECEIPT_RETENTION_MS = 90 * 24 * 60 * 60_000;
const MAX_AGENT_EVENT_ACTOR_SUSPENSION_BYTES = 64 * 1_024;
/** MeiliSearch's default `pagination.maxTotalHits` ceiling. */
@@ -329,6 +345,28 @@ export interface ConversationMethods {
IConversation,
'conversationId' | 'codeEnvironmentMode' | 'codeWorkspaces' | 'codeEnvironmentRevision'
> | null>;
+ reserveConvoLaneGitSeq(user: string, conversationId: string): Promise<number | null>;
+ getConvoLaneContext(user: string, conversationId: string): Promise<ConvoLaneContext | null>;
+ setConvoLaneGit(input: {
+ user: string;
+ conversationId: string;
+ laneGit: Pick<NonNullable<IConversation['laneGit']>, 'branch' | 'head'>;
+ repo?: string;
+ /** Reserved with `reserveConvoLaneGitSeq` when the command settled. */
+ seq: number;
+ /** The workspace the command ran in; the write applies only while the chat is still on it. */
+ workspace?: {
+ environmentId: string;
+ workspaceId: string;
+ required?: boolean;
+ /** The attachment epoch read when the tool was created; see `getConvoLaneContext`. */
+ epoch?: number;
+ };
+ }): Promise<boolean>;
+ getConvoLaneGit(
+ user: string,
+ conversationId: string,
+ ): Promise<Omit<NonNullable<IConversation['laneGit']>, 'seq'> | null>;
addConvoToolApprovalAllows(input: {
user: string;
conversationId: string;
@@ -2452,6 +2490,7 @@ export function createConversationMethods(
}
/* Remembered tool approvals are granted only by a validated resume. */
delete update.toolApprovalAllows;
+ stripFields(update, LANE_PRIVATE_FIELDS);
/** Ordinary saves may seed a decision, but only an explicit move may replace it. */
const decisionOnInsert = {
...(convo.codeEnvironmentMode != null && {
@@ -2477,6 +2516,7 @@ export function createConversationMethods(
delete unsetFields.titleSetByUser;
delete unsetFields.titleRevision;
delete unsetFields.toolApprovalAllows;
+ stripFields(unsetFields, LANE_PRIVATE_FIELDS);
delete unsetFields.codeEnvironmentRevision;
delete unsetFields.codeEnvironmentMode;
delete unsetFields.codeWorkspaces;
@@ -3003,6 +3043,177 @@ export function createConversationMethods(
return result.matchedCount === 1;
}
+ /**
+ * Reserve the next lane report sequence number for an owner's conversation. The counter lives in
+ * the database, so every replica draws from one order that no process clock can skew, and the
+ * number is taken when a command settles, before its write is attempted. Resolves to null when
+ * the conversation does not exist yet for this owner.
+ */
+ async function reserveConvoLaneGitSeq(
+ user: string,
+ conversationId: string,
+ ): Promise<number | null> {
+ const Conversation = mongoose.models.Conversation as Model<IConversation>;
+ const reserved = await withoutMeiliIndexing(
+ Conversation.findOneAndUpdate(
+ { user, conversationId, ...activeExpirationFilter<IConversation>() },
+ { $inc: { laneGitSeq: 1 } },
+ { new: true, timestamps: false },
+ ),
+ )
+ .select('laneGitSeq')
+ .lean<Pick<IConversation, 'laneGitSeq'> | null>();
+ return reserved?.laneGitSeq ?? null;
+ }
+
+ /**
+ * The route and attachment epoch a lane recorder needs, in one owner-scoped read. A subagent
+ * thread's route names the visible conversation its lane belongs to. The epoch advances only
+ * when the owner moves or detaches the workspace (never when a generation is admitted), so a
+ * report captured before a move away and back to the same workspace still reads as stale.
+ * Resolves to null for a conversation that does not exist yet, or is not this owner's.
+ */
+ async function getConvoLaneContext(
+ user: string,
+ conversationId: string,
+ ): Promise<ConvoLaneContext | null> {
+ const Conversation = mongoose.models.Conversation as Model<IConversation>;
+ const stored = await Conversation.findOne(
+ { user, conversationId, ...activeExpirationFilter<IConversation>() },
+ 'subagentThread +codeAttachmentEpoch',
+ ).lean<Pick<IConversation, 'subagentThread' | 'codeAttachmentEpoch'>>();
+ if (stored == null) return null;
+ const rootId = stored.subagentThread?.rootConversationId;
+ /** A thread's report is written to its visible root, so it is fenced by the root's epoch. */
+ const fenced =
+ rootId && rootId !== conversationId
+ ? await Conversation.findOne(
+ { user, conversationId: rootId, ...activeExpirationFilter<IConversation>() },
+ '+codeAttachmentEpoch',
+ ).lean<Pick<IConversation, 'codeAttachmentEpoch'>>()
+ : stored;
+ return {
+ subagentThread: stored.subagentThread ?? null,
+ codeAttachmentEpoch: fenced?.codeAttachmentEpoch ?? 0,
+ };
+ }
+
+ /**
+ * Record the branch and head a conversation's code lane last reported. Owner-scoped and fenced
+ * by the sequence number reserved when the command settled: the write matches only while the
+ * stored report carries a lower one, so a delayed older report, from this process or another
+ * replica, can never replace a newer state. When the caller names the workspace the command ran
+ * in, the write also matches only while the conversation is still attached to it, so a report
+ * queued before a move or detach cannot bring the old workspace's lane back. A conversation
+ * with no stored workspace (an agent default) accepts the report unless the caller requires a
+ * recorded one. Server-written only: generic saves and imports cannot set it. An expired
+ * temporary chat is treated as gone, here and in the reservation and the read, the way every
+ * other owner-scoped conversation access treats it. Resolves to whether the write applied; false
+ * means a newer report is already stored, the workspace no longer matches, or there is no such
+ * conversation for this owner.
+ */
+ async function setConvoLaneGit({
+ user,
+ conversationId,
+ laneGit,
+ repo,
+ seq,
+ workspace,
+ }: {
+ user: string;
+ conversationId: string;
+ laneGit: Pick<NonNullable<IConversation['laneGit']>, 'branch' | 'head'>;
+ repo?: string;
+ seq: number;
+ workspace?: { environmentId: string; workspaceId: string; required?: boolean; epoch?: number };
+ }): Promise<boolean> {
+ const Conversation = mongoose.models.Conversation as Model<IConversation>;
+ const next = {
+ branch: laneGit.branch,
+ head: laneGit.head,
+ ...(repo ? { repo } : {}),
+ seq,
+ };
+ const epochFence =
+ workspace?.epoch == null
+ ? []
+ : [
+ {
+ codeAttachmentEpoch: workspace.epoch === 0 ? { $in: [null, 0] } : workspace.epoch,
+ },
+ ];
+ const workspaceFence =
+ workspace == null
+ ? []
+ : [
+ ...epochFence,
+ {
+ $or: [
+ {
+ codeWorkspaces: {
+ $elemMatch: {
+ environmentId: workspace.environmentId,
+ workspaceId: workspace.workspaceId,
+ },
+ },
+ },
+ ...(workspace.required === true
+ ? []
+ : [
+ {
+ codeEnvironmentMode: { $ne: 'without_attached' },
+ $or: [
+ { codeWorkspaces: { $exists: false } },
+ { codeWorkspaces: null },
+ { codeWorkspaces: { $size: 0 } },
+ ],
+ },
+ ]),
+ ],
+ },
+ ];
+ const result = await withoutMeiliIndexing(
+ Conversation.updateOne(
+ {
+ user,
+ conversationId,
+ ...activeExpirationFilter<IConversation>(),
+ $and: [
+ {
+ $or: [
+ { 'laneGit.seq': { $exists: false } },
+ { 'laneGit.seq': null },
+ { 'laneGit.seq': { $lt: seq } },
+ ],
+ },
+ ...workspaceFence,
+ ],
+ },
+ { $set: { laneGit: next } },
+ { timestamps: false },
+ ),
+ );
+ return result.modifiedCount === 1;
+ }
+
+ /** The last reported lane state, or null when the conversation has none or is not the owner's. */
+ async function getConvoLaneGit(
+ user: string,
+ conversationId: string,
+ ): Promise<Omit<NonNullable<IConversation['laneGit']>, 'seq'> | null> {
+ const Conversation = mongoose.models.Conversation as Model<IConversation>;
+ const stored = await Conversation.findOne({
+ user,
+ conversationId,
+ ...activeExpirationFilter<IConversation>(),
+ })
+ .select('laneGit')
+ .lean<Pick<IConversation, 'laneGit'> | null>();
+ if (stored?.laneGit == null) return null;
+ const { branch, head, repo } = stored.laneGit;
+ return { branch, head, ...(repo ? { repo } : {}) };
+ }
+
async function readAdmittedConvoCodeEnvironmentDecision(user: string, conversationId: string) {
const Conversation = mongoose.models.Conversation as Model<IConversation>;
return withoutMeiliIndexing(
@@ -3054,12 +3265,17 @@ export function createConversationMethods(
codeWorkspaces: expected.codeWorkspaces ?? { $in: [null] },
codeEnvironmentRevision: expected.codeEnvironmentRevision ?? { $in: [null] },
},
+ /** The reported lane belongs to the workspace being replaced, so it goes with it. */
codeEnvironmentMode === 'attached'
- ? { $set: { codeEnvironmentMode, codeWorkspaces }, $inc: { codeEnvironmentRevision: 1 } }
+ ? {
+ $set: { codeEnvironmentMode, codeWorkspaces },
+ $unset: { laneGit: 1 },
+ $inc: { codeEnvironmentRevision: 1, codeAttachmentEpoch: 1 },
+ }
: {
$set: { codeEnvironmentMode },
- $unset: { codeWorkspaces: 1 },
- $inc: { codeEnvironmentRevision: 1 },
+ $unset: { codeWorkspaces: 1, laneGit: 1 },
+ $inc: { codeEnvironmentRevision: 1, codeAttachmentEpoch: 1 },
},
{ new: true, timestamps: false },
).lean<IConversation>();
@@ -3150,6 +3366,7 @@ export function createConversationMethods(
delete sanitized.codeApprovalMode;
delete sanitized.initial_agent_id;
delete sanitized.toolApprovalAllows;
+ stripFields(sanitized, LANE_PRIVATE_FIELDS);
delete sanitized.codeEnvironmentRevision;
stripActorCheckpointFields(sanitized);
if (typeof sanitized.user === 'string' && typeof sanitized.chatProjectId === 'string') {
@@ -4232,6 +4449,10 @@ export function createConversationMethods(
appendConvoMessageReference,
getConvoCodeEnvironmentDecision,
addConvoToolApprovalAllows,
+ reserveConvoLaneGitSeq,
+ setConvoLaneGit,
+ getConvoLaneGit,
+ getConvoLaneContext,
readAdmittedConvoCodeEnvironmentDecision,
replaceConvoCodeEnvironmentDecision,
bulkSaveConvos,
diff --git a/packages/data-schemas/src/schema/convo.ts b/packages/data-schemas/src/schema/convo.ts
index c0d940bbcf..8aa5f4d603 100644
--- a/packages/data-schemas/src/schema/convo.ts
+++ b/packages/data-schemas/src/schema/convo.ts
@@ -47,6 +47,27 @@ const convoSchema: Schema<IConversation> = new Schema(
/** Exact tool names the owner chose to auto-approve for this conversation.
* Server-written only, through `addConvoToolApprovalAllows`. */
toolApprovalAllows: { type: [String], default: undefined },
+ /** Branch and head of the code lane, as the worker last reported them. Server-written only,
+ * through `setConvoLaneGit`, and excluded from ordinary conversation reads. */
+ laneGit: {
+ type: {
+ branch: { type: String, default: null },
+ head: { type: String, default: null },
+ repo: { type: String, default: undefined },
+ /** Sequence number reserved when the command settled; fences out an older report. */
+ seq: { type: Number, default: undefined },
+ },
+ _id: false,
+ default: undefined,
+ select: false,
+ },
+ /** Counter that issues `laneGit.seq`, shared by every replica. Server-written only, through
+ * `reserveConvoLaneGitSeq`, and excluded from ordinary conversation reads. */
+ laneGitSeq: { type: Number, default: undefined, select: false },
+ /** Counts the owner's moves and detaches of the conversation's workspace. A lane report
+ * carries the value read when its tool was created and applies only while it still matches,
+ * so moving away and back cannot revive an older report. Server-written only. */
+ codeAttachmentEpoch: { type: Number, default: undefined, select: false },
agent_id: {
type: String,
},
diff --git a/packages/data-schemas/src/types/convo.ts b/packages/data-schemas/src/types/convo.ts
index 66b0b21dd7..fe0d4938c4 100644
--- a/packages/data-schemas/src/types/convo.ts
+++ b/packages/data-schemas/src/types/convo.ts
@@ -21,6 +21,16 @@ export const MAX_AGENT_EVENT_ACTOR_ENCODING_LENGTH = 128;
*/
export const AGENT_EVENT_ACTOR_SUMMARY_VERSION = 1;
+/** Branch and head commit the conversation's code lane last reported; null when it has none. */
+export interface IConversationLaneGit {
+ branch: string | null;
+ head: string | null;
+ /** `owner/name` of the lane's repository, as its worker registered it. */
+ repo?: string;
+ /** Reserved sequence number; internal, never returned by `getConvoLaneGit`. */
+ seq?: number;
+}
+
export interface ISubagentThreadLease {
token: string;
taskId: string;
@@ -290,6 +300,12 @@ export interface IConversation extends Document {
codeWorkspaces?: CodeWorkspaceSelection[];
/** Exact tool names auto-approved for this conversation; server-written only. */
toolApprovalAllows?: string[];
+ /** Last lane branch and head a command reported; server-written only and excluded from reads. */
+ laneGit?: IConversationLaneGit;
+ /** Counter behind `laneGit.seq`; server-written only and excluded from reads. */
+ laneGitSeq?: number;
+ /** Moves and detaches of the workspace; fences lane reports from an earlier attachment. */
+ codeAttachmentEpoch?: number;
/** Immutable primary persisted-agent attribution for Insights. */
initial_agent_id?: string | null;
subagentThread?: TSubagentThreadLineage;