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
TypeScript aianthropicartifactsawsazurechatgptchatgpt-cloneclaudeclonedeepseekgeminigooglegpt-5librechatmcpo1openairesponses-apivisionwebui
🪝 feat: Human-in-the-Loop Runtime - Tool Approval + Ask-User-Question (Slice B) (#13942)
Danny Avila6dbf9d5ad392
diff --git a/api/package.json b/api/package.jsonindex b044b49670..8f6e983b49 100644--- a/api/package.json+++ b/api/package.json@@ -46,7 +46,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^2.8.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.2.52",+ "@librechat/agents": "^3.2.53","@librechat/api": "*","@librechat/data-schemas": "*","@microsoft/microsoft-graph-client": "^3.0.7",diff --git a/api/server/controllers/agents/__tests__/jobReplacement.spec.js b/api/server/controllers/agents/__tests__/jobReplacement.spec.jsindex 7f7a775b75..c4247fcf30 100644--- a/api/server/controllers/agents/__tests__/jobReplacement.spec.js+++ b/api/server/controllers/agents/__tests__/jobReplacement.spec.js@@ -288,3 +288,331 @@ describe('Job Replacement Detection', () => {});});});++/**+ * HITL terminal-side-effect guards (PR #13942).+ *+ * Jobs are keyed by streamId == conversationId, so a NEW request REPLACES the running+ * one on the same conversation. The replaced generation's tail (its pause attempt, its+ * checkpoint prune, its resume catch-path terminal writes) must not clobber the live+ * generation's state. Each guard re-reads the live job and compares createdAt against the+ * generation's own captured identity before acting. These mirror the predicates in+ * client.js (handleRunInterrupt / chatCompletion finally) and resume.js.+ */+describe('HITL Terminal-Side-Effect Guards', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ describe('F22 — pause is skipped when the generation was replaced', () => {+ // Mirrors client.js handleRunInterrupt pre-check, run BEFORE approvals.pause.+ const shouldPause = async ({ jobCreatedAt, streamId }) => {+ if (jobCreatedAt != null) {+ const liveJob = await mockGenerationJobManager.getJob(streamId);+ if (!liveJob || liveJob.createdAt !== jobCreatedAt) {+ return false;+ }+ }+ return true;+ };++ it('does not pause when a newer job replaced this one', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 2000 });+ expect(await shouldPause({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(false);+ });++ it('does not pause when the job is already gone', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(null);+ expect(await shouldPause({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(false);+ });++ it('pauses when this is still the live job', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 1000 });+ expect(await shouldPause({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(true);+ });++ it('pauses without a lookup when identity is unknown (legacy job)', async () => {+ expect(await shouldPause({ jobCreatedAt: null, streamId: 'c1' })).toBe(true);+ expect(mockGenerationJobManager.getJob).not.toHaveBeenCalled();+ });+ });++ describe('F21 — checkpoint prune is skipped when the generation was replaced', () => {+ // Mirrors client.js chatCompletion finally: prune only when NOT replaced.+ const shouldPrune = async ({ resumableStreamId, jobCreatedAt }) => {+ let replaced = false;+ if (resumableStreamId && jobCreatedAt != null) {+ const liveJob = await mockGenerationJobManager.getJob(resumableStreamId);+ replaced = !liveJob || liveJob.createdAt !== jobCreatedAt;+ }+ return !replaced;+ };++ it('skips the prune when a newer job replaced this one', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 2000 });+ expect(await shouldPrune({ resumableStreamId: 'c1', jobCreatedAt: 1000 })).toBe(false);+ });++ it('prunes when this is still the live job', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 1000 });+ expect(await shouldPrune({ resumableStreamId: 'c1', jobCreatedAt: 1000 })).toBe(true);+ });++ it('prunes without a lookup when there is no resumable stream id', async () => {+ expect(await shouldPrune({ resumableStreamId: undefined, jobCreatedAt: 1000 })).toBe(true);+ expect(mockGenerationJobManager.getJob).not.toHaveBeenCalled();+ });+ });++ describe('F24 — resume catch-path terminal writes are skipped when replaced', () => {+ // Mirrors resume.js: stillLive gate around emitError/completeJob/deleteAgentCheckpoint.+ const stillLive = async ({ streamId, jobCreatedAt }) => {+ let live = true;+ try {+ const liveJob = await mockGenerationJobManager.getJob(streamId);+ live = !!liveJob && liveJob.createdAt === jobCreatedAt;+ } catch {+ live = true; // read failed — fail open and run the terminal writes+ }+ return live;+ };++ it('runs terminal writes when this is still the live job', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 1000 });+ expect(await stillLive({ streamId: 'c1', jobCreatedAt: 1000 })).toBe(true);+ });++ it('skips terminal writes when a newer job replaced this one', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 2000 });+ expect(await stillLive({ streamId: 'c1', jobCreatedAt: 1000 })).toBe(false);+ });++ it('fails open (runs terminal writes) when the liveness read throws', async () => {+ mockGenerationJobManager.getJob.mockRejectedValue(new Error('store down'));+ expect(await stillLive({ streamId: 'c1', jobCreatedAt: 1000 })).toBe(true);+ });+ });++ describe('F23 — resumed turn sources files from the job, not the racy DB row', () => {+ // Mirrors resume.js: prefer the body, then job.metadata.userMessage.files, then DB.+ const resolveFiles = ({ bodyFiles, metaFiles, dbFiles }) => {+ if (Array.isArray(bodyFiles) && bodyFiles.length > 0) {+ return bodyFiles;+ }+ if (Array.isArray(metaFiles) && metaFiles.length > 0) {+ return metaFiles;+ }+ return Array.isArray(dbFiles) && dbFiles.length > 0 ? dbFiles : undefined;+ };++ it('prefers job-metadata files over the DB row (no DB-save race)', () => {+ expect(+ resolveFiles({+ bodyFiles: [],+ metaFiles: [{ file_id: 'meta' }],+ dbFiles: [{ file_id: 'db' }],+ }),+ ).toEqual([{ file_id: 'meta' }]);+ });++ it('falls back to the DB row when the job has no persisted files (older job)', () => {+ expect(+ resolveFiles({ bodyFiles: [], metaFiles: undefined, dbFiles: [{ file_id: 'db' }] }),+ ).toEqual([{ file_id: 'db' }]);+ });++ it('keeps files already present on the resume body', () => {+ expect(+ resolveFiles({+ bodyFiles: [{ file_id: 'body' }],+ metaFiles: [{ file_id: 'meta' }],+ dbFiles: [],+ }),+ ).toEqual([{ file_id: 'body' }]);+ });+ });+});++/**+ * Round-18 follow-ups to the guards above (Codex review 4594099963).+ */+describe('HITL Resume Fidelity Guards (round 18)', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ describe('G1 — resume re-checks ownership AGAIN right before terminal writes', () => {+ // The start-of-finalize guard can go stale across saveMessage + title generation,+ // so resume.js re-reads the live job immediately before emitDone/completeJob/prune.+ // Same predicate as the catch-path (F24), applied at the success path's second point.+ const stillLiveBeforeFinalize = async ({ streamId, jobCreatedAt }) => {+ const liveJob = await mockGenerationJobManager.getJob(streamId);+ return !!liveJob && liveJob.createdAt === jobCreatedAt;+ };++ it('runs terminal writes when still the live job at the second check', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 1000 });+ expect(await stillLiveBeforeFinalize({ streamId: 'c1', jobCreatedAt: 1000 })).toBe(true);+ });++ it('skips terminal writes when replaced DURING finalize (after the first check passed)', async () => {+ // First check passed earlier with createdAt 1000; a new request replaced it to 2000+ // while saveMessage + title generation awaited. The second check must catch it.+ mockGenerationJobManager.getJob.mockResolvedValue({ createdAt: 2000 });+ expect(await stillLiveBeforeFinalize({ streamId: 'c1', jobCreatedAt: 1000 })).toBe(false);+ });+ });++ describe('G2 — uploaded files are seeded into the AWAITED preliminary user message', () => {+ // Mirrors getPreliminaryUserMessage: files from the request are persisted on the+ // preliminary (awaited, pre-run) metadata so they land before any interrupt emits.+ const buildPreliminaryUserMessage = ({ messageId, files }) => {+ if (typeof messageId !== 'string' || messageId.length === 0) {+ return null;+ }+ return {+ messageId,+ ...(Array.isArray(files) && files.length > 0 && { files }),+ };+ };++ it('includes files when the request carries them', () => {+ const msg = buildPreliminaryUserMessage({ messageId: 'm1', files: [{ file_id: 'a' }] });+ expect(msg.files).toEqual([{ file_id: 'a' }]);+ });++ it('omits files when none were uploaded (no empty array)', () => {+ const msg = buildPreliminaryUserMessage({ messageId: 'm1', files: [] });+ expect(msg).not.toHaveProperty('files');+ });+ });++ describe('G3 — resume replays pre-pause discovered deferred tools', () => {+ // Mirrors createRun's merge: discovered set is union(message-extracted, replayed),+ // gated entirely on the agent actually having deferred tools.+ const resolveDiscovered = ({ hasAnyDeferredTools, messageExtracted, replayed }) => {+ const set = new Set();+ if (hasAnyDeferredTools) {+ for (const n of messageExtracted ?? []) {+ set.add(n);+ }+ for (const n of replayed ?? []) {+ set.add(n);+ }+ }+ return set;+ };++ it('replays captured names on resume (messages empty) so the paused tool is present', () => {+ const set = resolveDiscovered({+ hasAnyDeferredTools: true,+ messageExtracted: [],+ replayed: ['deep_tool'],+ });+ expect(set.has('deep_tool')).toBe(true);+ });++ it('unions replayed names with message-extracted names', () => {+ const set = resolveDiscovered({+ hasAnyDeferredTools: true,+ messageExtracted: ['from_history'],+ replayed: ['deep_tool'],+ });+ expect([...set].sort()).toEqual(['deep_tool', 'from_history']);+ });++ it('is inert when the agent has no deferred tools', () => {+ const set = resolveDiscovered({+ hasAnyDeferredTools: false,+ messageExtracted: ['x'],+ replayed: ['deep_tool'],+ });+ expect(set.size).toBe(0);+ });+ });++ describe("H3 — resume replays the paused turn's model parameters (ephemeral agents)", () => {+ // Mirrors restoreResumeContext: spread persisted model_parameters back onto the body,+ // excluding `model` (replayed via the fingerprinted RESUME_CONTEXT_KEYS path).+ const replayModelParameters = (body, resumeContext) => {+ const params = resumeContext?.model_parameters;+ if (params && typeof params === 'object') {+ const { model: _model, ...rest } = params;+ Object.assign(body, rest);+ }+ return body;+ };++ it('restores non-default params (temperature, max tokens) onto the resume body', () => {+ const body = { conversationId: 'c1', endpoint: 'agents' };+ replayModelParameters(body, {+ model_parameters: { model: 'gpt-4o', temperature: 0.2, max_tokens: 1024 },+ });+ expect(body).toMatchObject({ temperature: 0.2, max_tokens: 1024 });+ });++ it('does NOT overwrite model (kept consistent with the resume fingerprint)', () => {+ const body = { model: 'pinned-model' };+ replayModelParameters(body, { model_parameters: { model: 'other-model', temperature: 0.9 } });+ expect(body.model).toBe('pinned-model');+ });++ it('overwrites a client-supplied param with the captured authoritative value', () => {+ const body = { temperature: 1.0 }; // crafted/stale client value+ replayModelParameters(body, { model_parameters: { temperature: 0.2 } });+ expect(body.temperature).toBe(0.2);+ });++ it('is a no-op when nothing was captured', () => {+ const body = { conversationId: 'c1' };+ replayModelParameters(body, {});+ expect(body).toEqual({ conversationId: 'c1' });+ });+ });++ describe('J2 — pause unfinished-save is skipped once a fast resume took over', () => {+ // Mirrors request.js: only mark the paused row unfinished while the job is STILL paused+ // on THIS generation's action. A claim transitions it out of requires_action and a+ // replacement bumps createdAt — either means a /resume now owns the row, so marking it+ // unfinished would clobber the resumed turn's completed content. Fail open on read error.+ const shouldMarkUnfinished = async ({ jobCreatedAt, streamId }) => {+ let stillPaused = true;+ try {+ const liveJob = await mockGenerationJobManager.getJob(streamId);+ stillPaused =+ !!liveJob &&+ liveJob.status === 'requires_action' &&+ (jobCreatedAt == null || liveJob.createdAt === jobCreatedAt);+ } catch {+ stillPaused = true;+ }+ return stillPaused;+ };++ it('marks unfinished while still paused on this generation', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({+ status: 'requires_action',+ createdAt: 1000,+ });+ expect(await shouldMarkUnfinished({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(true);+ });++ it('skips the unfinished-save once a fast resume claimed it (no longer requires_action)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({ status: 'running', createdAt: 1000 });+ expect(await shouldMarkUnfinished({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(false);+ });++ it('skips the unfinished-save when a newer request replaced the job', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue({+ status: 'requires_action',+ createdAt: 2000,+ });+ expect(await shouldMarkUnfinished({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(false);+ });++ it('fails open (marks unfinished) when the liveness read throws', async () => {+ mockGenerationJobManager.getJob.mockRejectedValue(new Error('store down'));+ expect(await shouldMarkUnfinished({ jobCreatedAt: 1000, streamId: 'c1' })).toBe(true);+ });+ });+});diff --git a/api/server/controllers/agents/__tests__/resume.spec.js b/api/server/controllers/agents/__tests__/resume.spec.jsnew file mode 100644index 0000000000..dc07de7c7d--- /dev/null+++ b/api/server/controllers/agents/__tests__/resume.spec.js@@ -0,0 +1,1114 @@+/**+ * Integration tests for the HITL resume controller (POST /agents/chat/resume).+ *+ * Drives the real `ResumeAgentController` end-to-end over supertest with the SDK+ * run, durable checkpointer, Mongo, and concurrency cache mocked out. The pure+ * decision/liveness helpers (`isPendingActionStale`, `mapToolApprovalResolutions`,+ * `findUndecidedToolCalls`, `findDisallowedDecisions`, `buildAbortedResponseMetadata`,+ * `sanitizeMessageForTransmit`) run for real via `requireActual`, so the test+ * exercises the actual guard ladder and the pause -> approve -> resume -> finalize+ * lifecycle rather than re-implemented stubs.+ *+ * Covers:+ * - the authorization / staleness / agent-and-endpoint / actionId guard ladder+ * - tool_approval validation (undecided, policy-disallowed decision)+ * - ask_user_question answer requirement+ * - concurrency gate (429) and the atomic single-winner claim (409)+ * - the happy path: ACK, run reconstruction, resumeCompletion, finalize (save the+ * now-finished response, emit done, complete job, prune checkpoint)+ * - re-pause (no double finalize), abort-during-resume (no double finalize),+ * and the resume-failure terminal path+ */++const express = require('express');+const request = require('supertest');+const { Constants } = require('librechat-data-provider');++const USER_ID = 'user-1';+const TENANT_ID = 'tenant-1';+const AGENT_ID = 'agent-abc';+const CONVO_ID = 'convo-123';+const ACTION_ID = 'action-xyz';+const RESPONSE_MSG_ID = 'resp-1';+const USER_MSG_ID = 'umsg-1';+const THREAD_PARENT_ID = 'thread-parent-1';++const mockLogger = {+ debug: jest.fn(),+ warn: jest.fn(),+ error: jest.fn(),+ info: jest.fn(),+};++const mockJobStore = {+ getJob: jest.fn(),+ updateJob: jest.fn(),+};++const mockGenerationJobManager = {+ getJob: jest.fn(),+ getJobStore: jest.fn(() => mockJobStore),+ getResumeState: jest.fn(),+ setContentParts: jest.fn(),+ emitChunk: jest.fn(),+ emitDone: jest.fn(),+ emitError: jest.fn(),+ completeJob: jest.fn(),+ expireApproval: jest.fn(),+ approvals: { resolve: jest.fn() },+};++const mockDeleteAgentCheckpoint = jest.fn();+const mockDecrementPendingRequest = jest.fn();+const mockCheckAndIncrementPendingRequest = jest.fn();++const mockSaveMessage = jest.fn();+const mockGetConvo = jest.fn();+const mockGetMessages = jest.fn();+const mockDisposeClient = jest.fn();+const mockGetMCPRequestContext = jest.fn();+const mockCleanupMCPRequestContextForReq = jest.fn();++jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),+ logger: mockLogger,+}));++jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),+ GenerationJobManager: mockGenerationJobManager,+ deleteAgentCheckpoint: (...args) => mockDeleteAgentCheckpoint(...args),+ decrementPendingRequest: (...args) => mockDecrementPendingRequest(...args),+ checkAndIncrementPendingRequest: (...args) => mockCheckAndIncrementPendingRequest(...args),+}));++jest.mock('~/models', () => ({+ saveMessage: (...args) => mockSaveMessage(...args),+ getConvo: (...args) => mockGetConvo(...args),+ getMessages: (...args) => mockGetMessages(...args),+}));++jest.mock('~/server/cleanup', () => ({+ disposeClient: (...args) => mockDisposeClient(...args),+}));++jest.mock('~/server/services/MCPRequestContext', () => ({+ getMCPRequestContext: (...args) => mockGetMCPRequestContext(...args),+ cleanupMCPRequestContextForReq: (...args) => mockCleanupMCPRequestContextForReq(...args),+}));++// Import after mocks+const ResumeAgentController = require('~/server/controllers/agents/resume');++/** Drain the microtask + immediate queues so the post-ACK continuation settles. */+const flush = () => new Promise((resolve) => setImmediate(resolve));++/** A live, resolvable paused tool-approval job (single tool call `tc1`). */+function makeToolApprovalJob(overrides = {}) {+ const metaOverrides = overrides.metadata ?? {};+ const pendingOverrides = metaOverrides.pendingAction ?? {};+ return {+ status: 'requires_action',+ abortController: new AbortController(),+ ...overrides,+ metadata: {+ userId: USER_ID,+ tenantId: TENANT_ID,+ agent_id: AGENT_ID,+ endpoint: 'agents',+ responseMessageId: RESPONSE_MSG_ID,+ sender: 'TestAgent',+ iconURL: 'https://example.com/icon.png',+ model: 'claude-test',+ isTemporary: false,+ userMessage: {+ messageId: USER_MSG_ID,+ parentMessageId: THREAD_PARENT_ID,+ text: 'please run the tool',+ },+ ...metaOverrides,+ pendingAction: {+ actionId: ACTION_ID,+ expiresAt: Date.now() + 60_000,+ payload: {+ type: 'tool_approval',+ action_requests: [{ tool_call_id: 'tc1' }],+ review_configs: [{ tool_call_id: 'tc1', allowed_decisions: ['approve', 'reject'] }],+ },+ ...pendingOverrides,+ },+ },+ };+}++/** A live, resolvable paused ask-user-question job. */+function makeAskUserJob(overrides = {}) {+ const job = makeToolApprovalJob(overrides);+ job.metadata.pendingAction.payload = {+ type: 'ask_user_question',+ question: 'What should I name the file?',+ };+ return job;+}++/** A mock reconstructed client for the post-ACK path. */+function makeClient(overrides = {}) {+ return {+ sender: 'TestAgent',+ contentParts: [{ type: 'text', text: 'resumed answer' }],+ artifactPromises: [],+ pendingApproval: false,+ buildResponseMetadata: jest.fn(() => null),+ resumeCompletion: jest.fn().mockResolvedValue(undefined),+ ...overrides,+ };+}++describe('ResumeAgentController (POST /agents/chat/resume)', () => {+ let app;+ let mockInitializeClient;+ let mockAddTitle;+ let capturedInit;+ let settle;+ let settled;++ beforeEach(() => {+ jest.clearAllMocks();++ capturedInit = null;+ mockCheckAndIncrementPendingRequest.mockResolvedValue({ allowed: true });+ mockDecrementPendingRequest.mockResolvedValue(undefined);+ mockDeleteAgentCheckpoint.mockResolvedValue(undefined);+ mockCleanupMCPRequestContextForReq.mockResolvedValue(undefined);+ mockSaveMessage.mockResolvedValue(undefined);+ mockGetConvo.mockResolvedValue(null);+ mockGetMessages.mockResolvedValue([]);+ mockJobStore.getJob.mockResolvedValue({ tokenUsage: null, contextUsage: null });+ mockJobStore.updateJob.mockResolvedValue(undefined);+ mockGenerationJobManager.getResumeState.mockResolvedValue({ aggregatedContent: [] });+ mockGenerationJobManager.emitDone.mockResolvedValue(undefined);+ mockGenerationJobManager.emitError.mockResolvedValue(undefined);+ mockGenerationJobManager.emitChunk.mockResolvedValue(undefined);+ mockGenerationJobManager.completeJob.mockResolvedValue(undefined);+ mockGenerationJobManager.approvals.resolve.mockResolvedValue(true);++ // `decrementPendingRequest` runs in the controller's `finally` on every+ // post-ACK path, so resolving on it signals the async continuation is done.+ settled = new Promise((resolve) => {+ settle = resolve;+ });+ mockDecrementPendingRequest.mockImplementation(async () => {+ settle();+ });++ mockAddTitle = jest.fn().mockResolvedValue(undefined);+ mockInitializeClient = jest.fn(async ({ req }) => {+ // Capture the request state the controller seeds BEFORE reconstruction.+ capturedInit = {+ parentMessageId: req.body.parentMessageId,+ files: req.body.files,+ conversationCreatedAt: req.conversationCreatedAt,+ timezone: req.body.timezone,+ };+ return { client: makeClient(), userMCPAuthMap: { server1: { token: 't' } } };+ });++ app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ req.user = { id: USER_ID, tenantId: TENANT_ID };+ req.config = {+ endpoints: { agents: { checkpointer: { type: 'mongo' } } },+ interfaceConfig: {},+ };+ next();+ });+ app.post('/api/agents/chat/resume', (req, res, next) =>+ ResumeAgentController(req, res, next, mockInitializeClient, mockAddTitle),+ );+ });++ const post = (body) => request(app).post('/api/agents/chat/resume').send(body);++ const approveBody = (extra = {}) => ({+ conversationId: CONVO_ID,+ actionId: ACTION_ID,+ agent_id: AGENT_ID,+ endpoint: 'agents',+ decisions: [{ tool_call_id: 'tc1', decision: 'approve' }],+ ...extra,+ });++ describe('temporal context restore', () => {+ it('restores req.conversationCreatedAt from the convo before initializeClient', async () => {+ // Temporal prompt vars must resolve against the paused anchor, not resume wall-clock.+ mockGetConvo.mockResolvedValue({ createdAt: new Date('2020-01-02T03:04:05.000Z') });+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled;+ expect(capturedInit.conversationCreatedAt).toBe('2020-01-02T03:04:05.000Z');+ });++ it('leaves conversationCreatedAt unset when the convo lookup yields nothing', async () => {+ mockGetConvo.mockResolvedValue(null);+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled;+ expect(capturedInit.conversationCreatedAt).toBeUndefined();+ });+ });++ describe('MCP request-context lifecycle', () => {+ it('pre-seeds the run-scoped MCP context before initializeClient and tears it down after', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled; // the controller's finally has run++ // Seeded with a null `res` + cleanupOnResponse:false so the post-ACK tool load+ // finds the existing store instead of getting undefined (res is already finished).+ expect(mockGetMCPRequestContext).toHaveBeenCalledWith(expect.anything(), undefined, {+ cleanupOnResponse: false,+ });+ // ...and seeded BEFORE the client (hence tool loading) is built.+ expect(mockGetMCPRequestContext.mock.invocationCallOrder[0]).toBeLessThan(+ mockInitializeClient.mock.invocationCallOrder[0],+ );+ // ...then torn down exactly once in the finally.+ expect(mockCleanupMCPRequestContextForReq).toHaveBeenCalledTimes(1);+ });+ });++ describe('request guards (rejected before claiming the action)', () => {+ it('400 when conversationId is missing', async () => {+ const res = await post({ actionId: ACTION_ID });+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/conversationId is required/i);+ expect(mockGenerationJobManager.getJob).not.toHaveBeenCalled();+ });++ it('400 when conversationId is the "new" placeholder', async () => {+ const res = await post({ conversationId: 'new', actionId: ACTION_ID });+ expect(res.status).toBe(400);+ expect(mockGenerationJobManager.getJob).not.toHaveBeenCalled();+ });++ it('404 when there is no paused job for the conversation', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(null);+ const res = await post(approveBody());+ expect(res.status).toBe(404);+ expect(res.body.error).toMatch(/no paused generation/i);+ });++ it('403 when the job belongs to another user', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(+ makeToolApprovalJob({ metadata: { userId: 'someone-else' } }),+ );+ const res = await post(approveBody());+ expect(res.status).toBe(403);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('403 on a tenant mismatch', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(+ makeToolApprovalJob({ metadata: { tenantId: 'other-tenant' } }),+ );+ const res = await post(approveBody());+ expect(res.status).toBe(403);+ });++ it('403 when the resume omits the paused agent_id', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody({ agent_id: undefined }));+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/different agent/i);+ });++ it('403 when the resume claims a different agent_id', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody({ agent_id: 'agent-other' }));+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/different agent/i);+ });++ it('403 when the resume claims a different endpoint', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody({ endpoint: 'bedrock' }));+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/different endpoint/i);+ });++ it('403 when the resume OMITS the paused endpoint (no fall-through to ephemeral)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody({ endpoint: undefined }));+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/different endpoint/i);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('409 when the job is not in requires_action (already terminal; no expire)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob({ status: 'running' }));+ const res = await post(approveBody());+ expect(res.status).toBe(409);+ expect(res.body.error).toMatch(/no live pending action/i);+ // Already resolved/terminal — nothing to expire.+ expect(mockGenerationJobManager.expireApproval).not.toHaveBeenCalled();+ });++ it('409 AND drives expiry when the pending action has expired (stale)', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.expiresAt = Date.now() - 1_000;+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody());+ expect(res.status).toBe(409);+ expect(res.body.error).toMatch(/no live pending action/i);+ // The stale action is expired NOW (expire CAS + terminal SSE) so an attached SSE+ // client gets a terminal event instead of hanging until the periodic sweeper runs.+ expect(mockGenerationJobManager.expireApproval).toHaveBeenCalledWith(CONVO_ID, ACTION_ID);+ });++ it('400 when actionId is missing', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody({ actionId: undefined }));+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/actionId is required/i);+ });++ it('409 when actionId targets a stale action', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody({ actionId: 'stale-action' }));+ expect(res.status).toBe(409);+ expect(res.body.error).toMatch(/stale action/i);+ });++ it('400 when a tool call is left undecided', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.payload.action_requests = [+ { tool_call_id: 'tc1' },+ { tool_call_id: 'tc2' },+ ];+ job.metadata.pendingAction.payload.review_configs = [+ { tool_call_id: 'tc1', allowed_decisions: ['approve', 'reject'] },+ { tool_call_id: 'tc2', allowed_decisions: ['approve', 'reject'] },+ ];+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody()); // only decides tc1+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/must be decided/i);+ expect(res.body.undecided).toEqual(['tc2']);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('403 when a decision is not permitted by the tool policy', async () => {+ const job = makeToolApprovalJob();+ // Policy restricts tc1 to reject only; an `approve` must be refused.+ job.metadata.pendingAction.payload.review_configs = [+ { tool_call_id: 'tc1', allowed_decisions: ['reject'] },+ ];+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody());+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/not permitted/i);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('400 when an edit decision omits editedArguments', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.payload.review_configs = [+ { tool_call_id: 'tc1', allowed_decisions: ['approve', 'edit'] },+ ];+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(+ approveBody({ decisions: [{ tool_call_id: 'tc1', decision: 'edit' }] }),+ );+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/editedArguments/i);+ expect(res.body.incomplete).toEqual(['tc1']);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('400 when a respond decision omits responseText', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.payload.review_configs = [+ { tool_call_id: 'tc1', allowed_decisions: ['approve', 'respond'] },+ ];+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(+ approveBody({ decisions: [{ tool_call_id: 'tc1', decision: 'respond' }] }),+ );+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/responseText/i);+ });++ it('accepts a complete edit decision (editedArguments present)', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.payload.review_configs = [+ { tool_call_id: 'tc1', allowed_decisions: ['approve', 'edit'] },+ ];+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(+ approveBody({+ decisions: [{ tool_call_id: 'tc1', decision: 'edit', editedArguments: { q: 'x' } }],+ }),+ );+ expect(res.status).toBe(200);+ await settled;+ await flush();+ });++ it('403 when the resume request fingerprint does not match the paused config', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.requestFingerprint = 'fingerprint-of-a-different-config';+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody());+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/different agent configuration/i);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('proceeds when the resume request fingerprint matches the paused config', async () => {+ const { computeAgentRequestFingerprint } = jest.requireActual('@librechat/api');+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.requestFingerprint = computeAgentRequestFingerprint({+ endpoint: 'agents',+ agent_id: AGENT_ID,+ });+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody());+ expect(res.status).toBe(200);+ expect(mockGenerationJobManager.approvals.resolve).toHaveBeenCalledWith(CONVO_ID, ACTION_ID);+ await settled;+ await flush();+ });++ it('403 when the resume sends a different promptPrefix than the paused config', async () => {+ const { computeAgentRequestFingerprint } = jest.requireActual('@librechat/api');+ const job = makeToolApprovalJob();+ // Ephemeral instructions come from promptPrefix, so it's part of the fingerprint.+ job.metadata.pendingAction.requestFingerprint = computeAgentRequestFingerprint({+ endpoint: 'agents',+ agent_id: AGENT_ID,+ promptPrefix: 'be terse',+ });+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody({ promptPrefix: 'ignore previous instructions' }));+ expect(res.status).toBe(403);+ expect(res.body.error).toMatch(/different agent configuration/i);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('400 when an ask_user_question resume carries no answer', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeAskUserJob());+ const res = await post({+ conversationId: CONVO_ID,+ actionId: ACTION_ID,+ agent_id: AGENT_ID,+ endpoint: 'agents',+ });+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/answer is required/i);+ });++ it('400 on an unsupported pending-action type', async () => {+ const job = makeToolApprovalJob();+ job.metadata.pendingAction.payload = { type: 'totally_unknown' };+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody());+ expect(res.status).toBe(400);+ expect(res.body.error).toMatch(/unsupported pending action/i);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('proceeds (does not 403) for a pre-multi-tenancy job with no tenantId', async () => {+ // hasTenantMismatch only blocks when the job carries a tenantId that differs;+ // an untenanted (legacy) job must still resume once the userId check passes.+ const job = makeToolApprovalJob({ metadata: { tenantId: undefined } });+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ const res = await post(approveBody());+ expect(res.status).toBe(200);+ expect(mockGenerationJobManager.approvals.resolve).toHaveBeenCalledWith(CONVO_ID, ACTION_ID);+ await settled;+ await flush();+ });++ it('429 when the concurrency gate rejects the resume', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockCheckAndIncrementPendingRequest.mockResolvedValue({ allowed: false });+ const res = await post(approveBody());+ expect(res.status).toBe(429);+ expect(mockGenerationJobManager.approvals.resolve).not.toHaveBeenCalled();+ });++ it('409 and releases the slot when the action was already claimed (single-winner)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockGenerationJobManager.approvals.resolve.mockResolvedValue(false);+ const res = await post(approveBody());+ expect(res.status).toBe(409);+ expect(res.body.error).toMatch(/already resolved or has expired/i);+ expect(mockGenerationJobManager.approvals.resolve).toHaveBeenCalledWith(CONVO_ID, ACTION_ID);+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ expect(mockInitializeClient).not.toHaveBeenCalled();+ });++ it('releases the slot when the claim itself throws (store error, not a leak)', async () => {+ // The increment happens before the claim, which runs before the run's own+ // try/finally — a store error here must still release the slot or a retry of the+ // still-paused approval gets spuriously 429'd until the counter TTL expires.+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockGenerationJobManager.approvals.resolve.mockRejectedValue(new Error('redis down'));+ const res = await post(approveBody());+ expect(res.status).toBe(500);+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ expect(mockInitializeClient).not.toHaveBeenCalled();+ });+ });++ describe('happy path: approve -> reconstruct -> resume -> finalize', () => {+ it('ACKs immediately and claims the action atomically with the submitted actionId', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const res = await post(approveBody());+ expect(res.status).toBe(200);+ expect(res.body).toEqual({+ streamId: CONVO_ID,+ conversationId: CONVO_ID,+ status: 'resuming',+ });+ expect(mockGenerationJobManager.approvals.resolve).toHaveBeenCalledWith(CONVO_ID, ACTION_ID);+ await settled;+ await flush();+ });++ it('seeds the thread parent before reconstruction and maps the decision to the SDK', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ await post(approveBody());+ await settled;+ await flush();++ // initializeAgent scopes thread files off req.body.parentMessageId, seeded+ // from the paused user message's parent before initializeClient runs.+ expect(capturedInit.parentMessageId).toBe(THREAD_PARENT_ID);++ expect(mockInitializeClient).toHaveBeenCalledTimes(1);+ const client = await mockInitializeClient.mock.results[0].value.then((r) => r.client);+ expect(client.resumeCompletion).toHaveBeenCalledWith(+ expect.objectContaining({+ resumeValue: { tc1: { type: 'approve' } },+ userMCPAuthMap: { server1: { token: 't' } },+ }),+ );+ });++ it('restores the paused user message files before reconstruction (execute-code files)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ // The resume body carries no files; the controller must source them from the+ // persisted user message so an approved code/read-file tool keeps its uploads.+ mockGetMessages.mockResolvedValue([{ files: [{ file_id: 'f1' }] }]);++ await post(approveBody());+ await settled;+ await flush();++ expect(capturedInit.files).toEqual([{ file_id: 'f1' }]);+ });++ it('ignores client-supplied resume files, sourcing from the paused job (security)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ // The paused turn's authoritative files (DB row); a crafted client tries to swap them.+ mockGetMessages.mockResolvedValue([{ files: [{ file_id: 'paused' }] }]);++ await post(approveBody({ files: [{ file_id: 'attacker-supplied' }] }));+ await settled;+ await flush();++ // The crafted client files must NOT reach initializeAgent — only the paused set.+ expect(capturedInit.files).toEqual([{ file_id: 'paused' }]);+ });++ it('clears client-supplied resume files when the paused turn had none (security)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockGetMessages.mockResolvedValue([{ files: [] }]); // the paused turn had no files++ await post(approveBody({ files: [{ file_id: 'attacker-supplied' }] }));+ await settled;+ await flush();++ expect(capturedInit.files).toEqual([]);+ });++ it('prefers job-metadata files over both the client body and the DB row', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(+ makeToolApprovalJob({+ metadata: {+ userMessage: {+ messageId: USER_MSG_ID,+ parentMessageId: THREAD_PARENT_ID,+ text: 'x',+ files: [{ file_id: 'meta' }],+ },+ },+ }),+ );+ mockGetMessages.mockResolvedValue([{ files: [{ file_id: 'db' }] }]);++ await post(approveBody({ files: [{ file_id: 'attacker-supplied' }] }));+ await settled;+ await flush();++ expect(capturedInit.files).toEqual([{ file_id: 'meta' }]);+ });++ it('carries the restored files onto the final requestMessage (user bubble keeps attachments)', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ // job.metadata.userMessage is persisted without files; the final SSE must still+ // carry the restored uploads or the user bubble loses its attachments on resume.+ mockGetMessages.mockResolvedValue([{ files: [{ file_id: 'f1', filename: 'a.pdf' }] }]);++ await post(approveBody());+ await settled;+ await flush();++ const [, finalEvent] = mockGenerationJobManager.emitDone.mock.calls[0];+ expect(finalEvent.requestMessage).toMatchObject({+ messageId: USER_MSG_ID,+ isCreatedByUser: true,+ files: [{ file_id: 'f1', filename: 'a.pdf' }],+ });+ });++ it('persists the finished response, emits done, completes the job, and prunes the checkpoint', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.objectContaining({ userId: USER_ID, isTemporary: false }),+ expect.objectContaining({+ messageId: RESPONSE_MSG_ID,+ parentMessageId: USER_MSG_ID,+ conversationId: CONVO_ID,+ content: [{ type: 'text', text: 'resumed answer' }],+ unfinished: false,+ error: false,+ isCreatedByUser: false,+ user: USER_ID,+ agent_id: AGENT_ID,+ }),+ expect.objectContaining({+ context: 'api/server/controllers/agents/resume.js - resumed response end',+ }),+ );++ // Assert the finalEvent STRUCTURE, not just the hardcoded `final: true` literal —+ // a `final: true`-only check would still pass if the entire content / title /+ // requestMessage build in finalizeResumedTurn were deleted.+ const [doneStreamId, finalEvent] = mockGenerationJobManager.emitDone.mock.calls[0];+ expect(doneStreamId).toBe(CONVO_ID);+ expect(finalEvent).toMatchObject({+ final: true,+ conversation: { conversationId: CONVO_ID },+ responseMessage: {+ messageId: RESPONSE_MSG_ID,+ content: [{ type: 'text', text: 'resumed answer' }],+ unfinished: false,+ },+ requestMessage: { messageId: USER_MSG_ID, isCreatedByUser: true },+ });+ expect(typeof finalEvent.title).toBe('string');++ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(CONVO_ID);+ expect(mockDeleteAgentCheckpoint).toHaveBeenCalledWith(CONVO_ID, { type: 'mongo' });+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ expect(mockDisposeClient).toHaveBeenCalledTimes(1);+ });++ it('skips finalization (no save/emitDone/complete) when the job was replaced mid-resume', async () => {+ // The paused job has createdAt 1000; a concurrent request reused this conversationId,+ // so the live job now has a different createdAt — finalizing would clobber the newer+ // turn's job. The finally still runs (slot release), so `settled` resolves.+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob({ createdAt: 1000 }));+ mockJobStore.getJob.mockResolvedValue({+ tokenUsage: null,+ contextUsage: null,+ createdAt: 2000,+ });+ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).not.toHaveBeenCalled();+ expect(mockGenerationJobManager.emitDone).not.toHaveBeenCalled();+ expect(mockGenerationJobManager.completeJob).not.toHaveBeenCalled();+ });++ it('does not release the slot in the finally when the client already released it on pause', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ // Simulate handleRunInterrupt having released the concurrency slot on a re-pause.+ mockInitializeClient.mockResolvedValue({+ client: makeClient({ pendingRequestReleased: true }),+ userMCPAuthMap: {},+ });+ let disposed;+ const disposedP = new Promise((resolve) => {+ disposed = resolve;+ });+ mockDisposeClient.mockImplementation(() => disposed());++ await post(approveBody());+ await disposedP;+ await flush();++ // The finally must NOT double-release — handleRunInterrupt already did.+ expect(mockDecrementPendingRequest).not.toHaveBeenCalled();+ });++ it('persists tool artifacts produced by the resumed continuation as attachments', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const artifact = { type: 'image', file_id: 'img-1' };+ // The lean resume path bypasses BaseClient.sendMessage's artifact await, so the+ // controller must await client.artifactPromises itself (and drop null results).+ mockInitializeClient.mockResolvedValue({+ client: makeClient({+ artifactPromises: [Promise.resolve(artifact), Promise.resolve(null)],+ }),+ userMCPAuthMap: {},+ });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ attachments: [artifact] }),+ expect.anything(),+ );+ });++ it('falls back to the aggregated store content when the live client content is empty', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ // No live content on the rebuilt client → the saved response must use the+ // pre-pause aggregated content from the store, not an empty array.+ mockInitializeClient.mockResolvedValue({+ client: makeClient({ contentParts: [] }),+ userMCPAuthMap: {},+ });+ mockGenerationJobManager.getResumeState.mockResolvedValue({+ aggregatedContent: [{ type: 'text', text: 'from-store' }],+ });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ content: [{ type: 'text', text: 'from-store' }] }),+ expect.anything(),+ );+ });++ it('strips malformed tool_call parts from the saved content', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockInitializeClient.mockResolvedValue({+ client: makeClient({+ contentParts: [+ { type: 'text', text: 'kept' },+ { type: 'tool_call' }, // malformed: no tool_call payload — must be filtered+ ],+ }),+ userMCPAuthMap: {},+ });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ content: [{ type: 'text', text: 'kept' }] }),+ expect.anything(),+ );+ });++ it('merges previously persisted attachments with the resumed segment artifacts', async () => {+ const priorArtifact = { type: 'image', file_id: 'prior-1' };+ const newArtifact = { type: 'image', file_id: 'new-1' };+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ // An earlier pause segment already saved an attachment on the response row.+ mockGetMessages.mockResolvedValue([{ attachments: [priorArtifact] }]);+ mockInitializeClient.mockResolvedValue({+ client: makeClient({ artifactPromises: [Promise.resolve(newArtifact)] }),+ userMCPAuthMap: {},+ });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ attachments: [priorArtifact, newArtifact] }),+ expect.anything(),+ );+ });++ it('persists the resumed run context calibration (contextMeta) onto the saved response', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const contextMeta = { calibrationRatio: 0.8 };+ mockInitializeClient.mockResolvedValue({+ client: makeClient({ contextMeta }),+ userMCPAuthMap: {},+ });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ contextMeta }),+ expect.anything(),+ );+ });++ it('carries manualSkills/alwaysAppliedSkills onto the resumed requestMessage', async () => {+ const job = makeToolApprovalJob();+ job.metadata.userMessage.manualSkills = ['skill-a'];+ job.metadata.userMessage.alwaysAppliedSkills = ['skill-b'];+ mockGenerationJobManager.getJob.mockResolvedValue(job);++ await post(approveBody());+ await settled;+ await flush();++ const [, finalEvent] = mockGenerationJobManager.emitDone.mock.calls[0];+ expect(finalEvent.requestMessage).toMatchObject({+ manualSkills: ['skill-a'],+ alwaysAppliedSkills: ['skill-b'],+ });+ });++ it('attaches client response metadata to the saved message when present', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ const contextUsage = { tokenCount: 1234 };+ mockInitializeClient.mockResolvedValue({+ client: makeClient({ buildResponseMetadata: jest.fn(() => ({ contextUsage })) }),+ userMCPAuthMap: {},+ });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ metadata: expect.objectContaining({ contextUsage }) }),+ expect.anything(),+ );+ });++ it('resumes an ask_user_question with the free-form answer', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeAskUserJob());+ const res = await post({+ conversationId: CONVO_ID,+ actionId: ACTION_ID,+ agent_id: AGENT_ID,+ endpoint: 'agents',+ answer: 'call it report.pdf',+ });+ expect(res.status).toBe(200);+ await settled;+ await flush();++ const client = await mockInitializeClient.mock.results[0].value.then((r) => r.client);+ expect(client.resumeCompletion).toHaveBeenCalledWith(+ expect.objectContaining({ resumeValue: { answer: 'call it report.pdf' } }),+ );+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(CONVO_ID);+ });++ it('generates a title for a first-turn pause before completing the stream', async () => {+ const job = makeToolApprovalJob();+ job.metadata.userMessage.parentMessageId = Constants.NO_PARENT;+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ mockGetConvo.mockResolvedValue({ title: 'New Chat' });++ await post(approveBody());+ await settled;+ await flush();++ expect(mockAddTitle).toHaveBeenCalledTimes(1);+ // Title is emitted (and the job completed) — order matters but both must happen.+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(CONVO_ID);+ });++ it('still finalizes the turn when first-turn title generation throws', async () => {+ const job = makeToolApprovalJob();+ job.metadata.userMessage.parentMessageId = Constants.NO_PARENT;+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ mockGetConvo.mockResolvedValue({ title: 'New Chat' });+ // Title generation is best-effort: a throw must not break the resumed turn.+ mockAddTitle.mockRejectedValue(new Error('title service down'));++ await post(approveBody());+ await settled;+ await flush();++ expect(mockLogger.error).toHaveBeenCalled();+ expect(mockSaveMessage).toHaveBeenCalledTimes(1);+ expect(mockGenerationJobManager.emitDone).toHaveBeenCalledWith(CONVO_ID, expect.any(Object));+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(CONVO_ID);+ });+ });++ describe('non-finalizing outcomes', () => {+ it('re-pause: does not finalize when the run pauses again', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockInitializeClient.mockResolvedValue({+ client: makeClient({ pendingApproval: true }),+ userMCPAuthMap: {},+ });++ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled;+ await flush();++ // It persists progress (unfinished) but must NOT finalize the turn.+ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ unfinished: true }),+ expect.anything(),+ );+ expect(mockGenerationJobManager.emitDone).not.toHaveBeenCalled();+ expect(mockGenerationJobManager.completeJob).not.toHaveBeenCalled();+ expect(mockDeleteAgentCheckpoint).not.toHaveBeenCalled();+ // The slot is still released and the client disposed.+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ expect(mockDisposeClient).toHaveBeenCalledTimes(1);+ });++ it('re-pause: persists the segment content (unfinished) so an expiring re-pause keeps it', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockInitializeClient.mockResolvedValue({+ client: makeClient({+ pendingApproval: true,+ contentParts: [{ type: 'text', text: 'streamed this segment' }],+ artifactPromises: [],+ }),+ userMCPAuthMap: {},+ });++ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled;+ await flush();++ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({+ content: [{ type: 'text', text: 'streamed this segment' }],+ unfinished: true,+ }),+ expect.objectContaining({+ context: 'api/server/controllers/agents/resume.js - re-pause progress persist',+ }),+ );+ expect(mockGenerationJobManager.emitDone).not.toHaveBeenCalled();+ });++ it('re-pause: persists artifacts produced before pausing again (unfinished)', async () => {+ const artifact = { type: 'image', file_id: 'seg-1' };+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockInitializeClient.mockResolvedValue({+ client: makeClient({+ pendingApproval: true,+ artifactPromises: [Promise.resolve(artifact)],+ }),+ userMCPAuthMap: {},+ });++ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled;+ await flush();++ // No finalize, but the segment's artifact is persisted unfinished so the next+ // resume's finalize can merge it (otherwise the fresh client drops it).+ expect(mockGenerationJobManager.emitDone).not.toHaveBeenCalled();+ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.anything(),+ expect.objectContaining({ attachments: [artifact], unfinished: true }),+ expect.objectContaining({+ context: 'api/server/controllers/agents/resume.js - re-pause progress persist',+ }),+ );+ });++ it('abort-during-resume: lets the abort route finalize, does not double-save', async () => {+ const job = makeToolApprovalJob();+ mockGenerationJobManager.getJob.mockResolvedValue(job);+ mockInitializeClient.mockImplementation(async () => {+ job.abortController.abort();+ return { client: makeClient(), userMCPAuthMap: {} };+ });++ const res = await post(approveBody());+ expect(res.status).toBe(200);+ await settled;+ await flush();++ expect(mockSaveMessage).not.toHaveBeenCalled();+ expect(mockGenerationJobManager.emitDone).not.toHaveBeenCalled();+ expect(mockGenerationJobManager.completeJob).not.toHaveBeenCalled();+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ });++ it('resume failure: emits an error, finalizes the job, and prunes the checkpoint', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockInitializeClient.mockResolvedValue({+ client: makeClient({+ resumeCompletion: jest.fn().mockRejectedValue(new Error('boom')),+ }),+ userMCPAuthMap: {},+ });++ const res = await post(approveBody());+ expect(res.status).toBe(200); // already ACKed before the failure+ await settled;+ await flush();++ expect(mockGenerationJobManager.emitError).toHaveBeenCalledWith(CONVO_ID, 'boom');+ expect(mockGenerationJobManager.completeJob).toHaveBeenCalledWith(CONVO_ID, 'boom');+ expect(mockDeleteAgentCheckpoint).toHaveBeenCalledWith(CONVO_ID, { type: 'mongo' });+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ expect(mockSaveMessage).not.toHaveBeenCalled();+ });++ it('forces a terminal job state when completeJob also fails during a resume error', async () => {+ mockGenerationJobManager.getJob.mockResolvedValue(makeToolApprovalJob());+ mockInitializeClient.mockResolvedValue({+ client: makeClient({+ resumeCompletion: jest.fn().mockRejectedValue(new Error('boom')),+ }),+ userMCPAuthMap: {},+ });+ // The error path's completeJob also fails → last-resort updateJob must force a+ // terminal state so the job isn't orphaned in `running`.+ mockGenerationJobManager.completeJob.mockRejectedValue(new Error('complete failed'));++ await post(approveBody());+ await settled;+ await flush();++ expect(mockJobStore.updateJob).toHaveBeenCalledWith(+ CONVO_ID,+ expect.objectContaining({ status: 'error', error: 'Resume failed' }),+ );+ expect(mockDecrementPendingRequest).toHaveBeenCalledWith(USER_ID);+ });+ });+});diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex df2515c2ab..f9432ae821 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -33,6 +33,13 @@ const {GenerationJobManager,getTransactionsConfig,resolveRecursionLimit,+ buildPendingAction,+ computeAgentRequestFingerprint,+ extractDiscoveredToolsFromHistory,+ pickResumeContext,+ getApprovalTtlMs,+ isHITLEnabled,+ deleteAgentCheckpoint,getRequestMemories,createMemoryProcessor,agentHasInlineMemoryTools,@@ -54,6 +61,7 @@ const {hasUrlContextTool,appendYouTubeVideoParts,resolveYouTubeInjectionConfig,+ decrementPendingRequest,} = require('@librechat/api');const {Callback,@@ -69,6 +77,7 @@ const {Permissions,VisionModes,ContentTypes,+ ApprovalEvents,EModelEndpoint,PermissionTypes,AgentCapabilities,@@ -1165,6 +1174,150 @@ class AgentClient extends BaseClient {* @param {Record<string, Record<string, string>>} [params.userMCPAuthMap]* @param {AbortController} [params.abortController]*/+ /**+ * @deprecated Agent Chain — strip hidden intermediate sequential-agent content+ * before persistence, keeping only the last part + tool_call parts. Mirrors the+ * chat path so a HITL resume doesn't persist/emit intermediate outputs the+ * agent's `hide_sequential_outputs` setting is meant to hide.+ */+ applyHideSequentialOutputsFilter() {+ if (!this.options.agent?.hide_sequential_outputs || !Array.isArray(this.contentParts)) {+ return;+ }+ this.contentParts = this.contentParts.filter(+ (part, index) =>+ index >= this.contentParts.length - 1 ||+ part.type === ContentTypes.TOOL_CALL ||+ part.tool_call_ids,+ );+ }++ /**+ * Surface any human-in-the-loop interrupt the SDK captured during the most+ * recent `processStream` / `resume`. When the run paused for tool approval (or+ * an ask-user question), mark the job `requires_action`, persist the pending+ * review record, and emit it to live clients — then set `this.pendingApproval`+ * so the controller leaves the turn unfinalized for the resume route to continue.+ *+ * No-op when the run completed without an interrupt, or when the job was aborted+ * between the interrupt firing and this mark (a late interrupt must not pause a+ * dead job — the atomic `pause` transition returns false and we drop it).+ *+ * @param {AgentRun} run+ * @param {string} [streamId]+ */+ async handleRunInterrupt(run, streamId) {+ if (!streamId || typeof run?.getInterrupt !== 'function') {+ return;+ }+ const interrupt = run.getInterrupt();+ if (!interrupt?.payload) {+ return;+ }++ const appConfig = this.options.req?.config;+ const checkpointerCfg = appConfig?.endpoints?.[EModelEndpoint.agents]?.checkpointer;+ // Persist the resolved model parameters (temperature, max tokens, custom endpoint+ // params, …) so an ephemeral-agent resume continues with the SAME settings the run+ // paused on. The resume payload omits them and they aren't part of the fingerprint, so+ // without this the rebuilt ephemeral run falls back to defaults. (Saved agents source+ // these from the DB record server-side, so this is belt-and-suspenders for them.)+ const resumeContext = pickResumeContext(this.options.req?.body);+ const resolvedModelParameters = this.options.agent?.model_parameters;+ if (resolvedModelParameters && typeof resolvedModelParameters === 'object') {+ resumeContext.model_parameters = resolvedModelParameters;+ }+ const pendingAction = buildPendingAction(interrupt.payload, {+ streamId,+ conversationId: this.conversationId,+ // runId mirrors the LangGraph checkpoint namespace when the SDK provides it+ // (its documented meaning), falling back to the response message id.+ runId: interrupt.checkpointNs ?? this.responseMessageId,+ responseMessageId: this.responseMessageId,+ interruptId: interrupt.interruptId,+ // thread_id was bound to conversationId at run config (config.configurable);+ // fall back to it when the SDK doesn't echo threadId on the interrupt.+ threadId: interrupt.threadId ?? this.conversationId,+ ttlMs: getApprovalTtlMs(checkpointerCfg),+ // Pin the graph-determining request fields so resume can't rebuild this paused+ // run on a different agent/tool set (esp. ephemeral agents, whose agent_id is+ // undefined so the id guard can't tell two configs apart).+ requestFingerprint: computeAgentRequestFingerprint(this.options.req?.body ?? {}),+ // Persist those same fields verbatim so the resume route can REPLAY them — a+ // reload/cross-replica resume can't reconstruct the ephemeral config client-side,+ // so the server restores it and rebuilds the same graph (and the fingerprint matches).+ resumeContext,+ });++ // Job-replacement guard: streamId == conversationId is reused per conversation, so a+ // newer request can replace this run's job. If this (older) run hits an interrupt+ // after a replacement, pausing would flip the NEWER job to requires_action with this+ // stale run's pending action, blocking fresh work behind the wrong approval. Only+ // pause when the live job is still the one THIS run created (mirrors request.js).+ if (this.jobCreatedAt != null) {+ const liveJob = await GenerationJobManager.getJobStore().getJob(streamId);+ if (!liveJob || liveJob.createdAt !== this.jobCreatedAt) {+ logger.debug(`[AgentClient] Interrupt fired but job ${streamId} was replaced; not pausing`);+ return;+ }+ }++ const paused = await GenerationJobManager.approvals.pause(streamId, pendingAction);+ if (!paused) {+ logger.debug(+ `[AgentClient] Interrupt fired but job ${streamId} was not running; not pausing`,+ );+ return;+ }++ // Capture deferred tools discovered (via tool_search) earlier in THIS turn so resume+ // can replay them into createRun. The resumed graph is rebuilt with `messages: []`+ // (state comes from the checkpoint), so the in-turn tool_search results that mark a+ // deferred tool discovered aren't present there — without this the paused deferred+ // tool would be missing from the rebuilt schema-only toolMap and resume would fail+ // with "unknown tool". Inert for non-deferred turns (the set comes back empty).+ try {+ const runMessages =+ typeof run.getRunMessages === 'function' ? run.getRunMessages() : undefined;+ if (Array.isArray(runMessages) && runMessages.length > 0) {+ const discovered = extractDiscoveredToolsFromHistory(runMessages);+ if (discovered.size > 0) {+ await GenerationJobManager.updateMetadata(streamId, {+ discoveredTools: Array.from(discovered),+ });+ }+ }+ } catch (err) {+ logger.warn(+ `[AgentClient] Failed to capture discovered tools for resume on ${streamId}`,+ err?.message ?? err,+ );+ }++ this.pendingApproval = pendingAction;+ // Release the concurrency slot this request held the MOMENT the turn is durably+ // paused — before the approval card is emitted — so the user's `/resume` can+ // re-acquire one immediately. Otherwise a fast Approve races the HTTP-driver+ // teardown (request.js pause branch / resume.js finally) that would otherwise+ // release it, and `/resume` 429s under LIMIT_CONCURRENT_MESSAGES. Idempotent via+ // the flag; if it fails here, the teardown still releases (it checks the flag).+ if (!this.pendingRequestReleased) {+ try {+ await decrementPendingRequest(this.options.req?.user?.id);+ this.pendingRequestReleased = true;+ } catch (err) {+ logger.error(`[AgentClient] Failed to release request slot on pause ${streamId}`, err);+ }+ }+ await GenerationJobManager.emitChunk(streamId, {+ event: ApprovalEvents.ON_PENDING_ACTION,+ data: pendingAction,+ });+ logger.debug(+ `[AgentClient] Paused ${streamId} for ${interrupt.payload.type} (action ${pendingAction.actionId})`,+ );+ }+async chatCompletion({ payload, userMCPAuthMap, abortController = null }) {/** @type {Partial<GraphRunnableConfig>} */let config;@@ -1405,6 +1558,11 @@ class AgentClient extends BaseClient {run = await createRun({agents,messages,+ // This controller implements the full HITL pause/resume lifecycle (handleRunInterrupt+ // persists the pending action; the /resume route rebuilds + continues the run), so it+ // opts into the tool-approval wiring. Non-resumable callers (OpenAI-compat, Responses)+ // leave this off so an approval-gated tool can't pause where there's no resume path.+ hitlCapable: true,indexTokenCountMap,initialSummary,initialSessions,@@ -1452,16 +1610,29 @@ class AgentClient extends BaseClient {/** @deprecated Agent Chain */config.configurable.last_agent_id = agents[agents.length - 1].id;++ // HITL: clear any checkpoint orphaned by a prior paused turn in this+ // conversation (one that expired or was aborted while paused) so this fresh+ // turn starts clean instead of rehydrating a stale interrupt — thread_id is+ // the stable conversationId. No-op when HITL is off or nothing is orphaned.+ if (streamId && isHITLEnabled(agentsEConfig?.toolApproval)) {+ await deleteAgentCheckpoint(this.conversationId, agentsEConfig?.checkpointer);+ }+await run.processStream({ messages }, config, {callbacks: {[Callback.TOOL_ERROR]: logToolError,},});+ // HITL: if the run paused for tool approval, mark the job+ // `requires_action` + emit the prompt and leave the turn unfinalized+ // (the resume route continues it). No-op when the run completed.+ await this.handleRunInterrupt(run, streamId);+config.signal = null;};- const hideSequentialOutputs = config.configurable.hide_sequential_outputs;await runAgents(initialMessages);/**@@ -1501,20 +1672,7 @@ class AgentClient extends BaseClient {this.contentParts.unshift(...manualParts);}- /** @deprecated Agent Chain */- if (hideSequentialOutputs) {- this.contentParts = this.contentParts.filter((part, index) => {- // Include parts that are either:- // 1. At or after the finalContentStart index- // 2. Of type tool_call- // 3. Have tool_call_ids property- return (- index >= this.contentParts.length - 1 ||- part.type === ContentTypes.TOOL_CALL ||- part.tool_call_ids- );- });- }+ this.applyHideSequentialOutputsFilter();} catch (err) {if (abortController.signal.aborted) {logger.debug(@@ -1584,12 +1742,292 @@ class AgentClient extends BaseClient {this._resolveRun(this.run ?? null);this._resolveRun = null;}++ // HITL: a turn that completed (or errored) without pausing leaves a dead+ // checkpoint. thread_id is the conversationId — stable across turns — so it+ // MUST be pruned before the next turn, or LangGraph would resume this turn's+ // state instead of starting fresh. Skip when paused (the checkpoint is needed+ // to resume) or when HITL is off (none was written). The Mongo TTL is the backstop.+ const agentsEConfig = appConfig?.endpoints?.[EModelEndpoint.agents];+ if (!this.pendingApproval && isHITLEnabled(agentsEConfig?.toolApproval)) {+ try {+ // Job-replacement guard: only prune if THIS generation is still the live job.+ // A newer request can replace this one on the same conversationId; if this+ // (older) run's finally lands after the newer run paused, pruning by+ // conversationId would delete the NEWER run's checkpoint and break its /resume.+ const resumableStreamId = this.options.req?._resumableStreamId;+ let replaced = false;+ if (resumableStreamId && this.jobCreatedAt != null) {+ const liveJob = await GenerationJobManager.getJobStore().getJob(resumableStreamId);+ replaced = !liveJob || liveJob.createdAt !== this.jobCreatedAt;+ }+ if (replaced) {+ logger.debug('[AgentClient] Skipping checkpoint prune — job was replaced', {+ streamId: resumableStreamId,+ });+ } else {+ await deleteAgentCheckpoint(this.conversationId, agentsEConfig?.checkpointer);+ }+ } catch (err) {+ logger.warn('[AgentClient] Failed to prune checkpoint after completion', err);+ }+ }+run = null;config = null;memoryPromise = null;}}+ /**+ * Resume a run that paused for human-in-the-loop review.+ *+ * The original run lives in a detached background task that exits when the run+ * pauses, so resume REBUILDS the run on a fresh graph bound to the same+ * `thread_id` (= conversationId) and the durable checkpointer. LangGraph rehydrates+ * the paused graph state from the checkpoint; `run.resume(value)` re-enters the+ * interrupted node with the user's decision. State comes from the checkpoint, so+ * no message history is rebuilt here — `createRun` only needs the agent(s) to+ * reconstruct the graph structure.+ *+ * `seedContent` is the content streamed before the pause (the assistant message ++ * its tool call). In Redis mode the job store's append log already spans the pause,+ * so the finalized message is complete regardless; seeding keeps the in-memory store+ * complete too. The run drives events through the same `streamId`, so the client's+ * open SSE receives the continuation live.+ *+ * Unlike `chatCompletion`, this does NOT prune the checkpoint in its `finally` — the+ * resume controller owns checkpoint lifecycle (it must also clean up on failures that+ * happen before this method runs, and keep the checkpoint on a re-pause).+ *+ * @param {object} params+ * @param {Agents.ToolApprovalDecisionMap | { answer: string }} params.resumeValue+ * @param {Array} [params.seedContent] - content aggregated before the pause+ * @param {AbortController} [params.abortController]+ * @param {Pick<import('@langchain/langgraph').Command, 'update' | 'goto'>} [params.commandOptions]+ */+ async resumeCompletion({+ resumeValue,+ seedContent = [],+ abortController = null,+ commandOptions,+ userMCPAuthMap,+ discoveredToolNames,+ }) {+ /** @type {Partial<GraphRunnableConfig>} */+ let config;+ /** @type {ReturnType<createRun>} */+ let run;+ const appConfig = this.options.req.config;+ const balanceConfig = getBalanceConfig(appConfig);+ const transactionsConfig = getTransactionsConfig(appConfig);+ try {+ if (!abortController) {+ abortController = new AbortController();+ }++ /** @type {AppConfig['endpoints']['agents']} */+ const agentsEConfig = appConfig.endpoints?.[EModelEndpoint.agents];++ config = {+ runName: 'AgentRun',+ configurable: {+ thread_id: this.conversationId,+ last_agent_index: this.agentConfigs?.size ?? 0,+ user_id: this.user ?? this.options.req.user?.id,+ hide_sequential_outputs: this.options.agent.hide_sequential_outputs,+ requestBody: {+ messageId: this.responseMessageId,+ conversationId: this.conversationId,+ parentMessageId: this.parentMessageId,+ },+ user: createSafeUser(this.options.req.user),+ },+ recursionLimit: resolveRecursionLimit(agentsEConfig, this.options.agent),+ signal: abortController.signal,+ streamMode: 'values',+ version: 'v2',+ };++ // Seed pre-pause content so the in-memory job store reports the complete turn+ // (Redis aggregates across the pause via its append log; this covers in-memory).+ if (Array.isArray(seedContent) && seedContent.length > 0) {+ this.contentParts.push(...seedContent);+ }++ const tokenCounter = createTokenCounter(this.getEncoding());+ const agents = [this.options.agent];+ if (this.agentConfigs && this.agentConfigs.size > 0) {+ agents.push(...this.agentConfigs.values());+ }++ // Re-prime skill files invoked in the pre-pause segment (mirrors the normal path's+ // `primeInvokedSkills(payload)`), so an approved code/file-backed tool keeps the+ // injected skill-file session refs instead of running without them. The pre-pause+ // content carries the `skill` tool_calls, so it stands in for the message payload.+ let skillSessions;+ if (+ typeof this.options.primeInvokedSkills === 'function' &&+ Array.isArray(seedContent) &&+ seedContent.length > 0+ ) {+ try {+ const primed = await this.options.primeInvokedSkills([+ { role: 'assistant', content: seedContent },+ ]);+ skillSessions = primed?.initialSessions;+ } catch (err) {+ logger.warn(+ '[api/server/controllers/agents/client.js #resumeCompletion] Failed to re-prime skill sessions',+ err?.message ?? err,+ );+ }+ }++ // Seed code-env / skill tool sessions so an approved code/file/skill-backed tool+ // runs with the same uploaded-file context the pre-pause run had — the rebuilt+ // graph otherwise has no `Graph.sessions` entries (especially cross-replica).+ const initialSessions = buildInitialToolSessions({ skillSessions, agents });++ run = await createRun({+ agents,+ // State (messages, tool calls) is rehydrated from the checkpoint by+ // run.resume; createRun only needs the agents to rebuild the graph.+ messages: [],+ // The resumed run can pause AGAIN (another tool, a follow-up question), and this+ // controller owns that lifecycle, so it must keep the HITL wiring on the rebuilt run.+ hitlCapable: true,+ // Replay deferred tools discovered before the pause. With `messages: []` the+ // discovery scan finds nothing, so a deferred tool the paused call targets+ // would be absent from the rebuilt toolMap; these names (captured at pause)+ // force it back in. Undefined/empty for non-deferred turns — a harmless no-op.+ discoveredToolNames,+ initialSessions,+ runId: this.responseMessageId,+ signal: abortController.signal,+ customHandlers: this.options.eventHandlers,+ requestBody: config.configurable.requestBody,+ user: createSafeUser(this.options.req?.user),+ tenantId: this.options.req?.user?.tenantId,+ summarizationConfig: appConfig?.summarization,+ appConfig,+ tokenCounter,+ subagentUsageSink: createSubagentUsageSink(+ this.collectedUsage,+ this.buildSubagentUsageEmitter(appConfig),+ ),+ });++ if (!run) {+ throw new Error('Failed to create run for resume');+ }++ this.run = run;+ if (this._resolveRun) {+ this._resolveRun(run);+ this._resolveRun = null;+ }++ const streamId = this.options.req?._resumableStreamId;+ // Do NOT cache the rebuilt graph on resume: it was created with `messages: []`, so+ // RedisJobStore.getContentParts() (which prefers a cached graph over reconstructing+ // from the chunk log) would return only the resumed segment and drop the pre-pause+ // assistant/tool-call content on a same-replica reload/status poll. Skipping it makes+ // introspection fall back to the durable chunk reconstruction, which is complete.+ // `setContentParts` still points the in-memory store at the seeded client content.+ if (streamId && this.contentParts) {+ GenerationJobManager.setContentParts(streamId, this.contentParts);+ }++ // Carry the user's MCP auth into the rebuilt run so an approved MCP tool executes+ // with the same OAuth/user credentials it had before the pause.+ if (userMCPAuthMap != null) {+ config.configurable.userMCPAuthMap = userMCPAuthMap;+ }++ /** @deprecated Agent Chain */+ config.configurable.last_agent_id = agents[agents.length - 1].id;++ await run.resume(+ resumeValue,+ config,+ { callbacks: { [Callback.TOOL_ERROR]: logToolError } },+ commandOptions,+ );++ config.signal = null;++ // The model may pause AGAIN (another tool needs approval, or a follow-up+ // question). Re-arm the same interrupt gate so the cycle can repeat.+ await this.handleRunInterrupt(run, streamId);++ // Mirror chatCompletion: strip hidden intermediate sequential-agent content+ // before resume finalize/re-pause persistence reads `this.contentParts`, so a+ // resumed sequential chain doesn't persist/emit outputs hide_sequential_outputs+ // is meant to hide.+ this.applyHideSequentialOutputsFilter();+ } catch (err) {+ if (abortController.signal.aborted) {+ logger.debug(+ '[api/server/controllers/agents/client.js #resumeCompletion] Aborted by user',+ {+ conversationId: this.conversationId,+ name: err?.name,+ code: err?.code,+ },+ );+ } else {+ logger.error(+ '[api/server/controllers/agents/client.js #resumeCompletion] Unhandled error',+ err,+ );+ this.contentParts.push({+ type: ContentTypes.ERROR,+ [ContentTypes.ERROR]: `An error occurred while resuming the request${err?.message ? `: ${err.message}` : ''}`,+ });+ }+ } finally {+ const ratio = this.run?.getCalibrationRatio() ?? 0;+ if (ratio > 0 && ratio !== 1) {+ this.contextMeta = {+ calibrationRatio: Math.round(ratio * 1000) / 1000,+ encoding: this.getEncoding(),+ };+ } else {+ this.contextMeta = undefined;+ }++ this.finalizeSubagentContent();++ if (this.pendingSubagentEmits.length > 0) {+ await Promise.allSettled(this.pendingSubagentEmits);+ this.pendingSubagentEmits = [];+ }++ try {+ const wasAborted = abortController?.signal?.aborted;+ if (!wasAborted) {+ await this.recordCollectedUsage({+ context: 'message',+ balance: balanceConfig,+ transactions: transactionsConfig,+ });+ }+ } catch (err) {+ logger.error(+ '[api/server/controllers/agents/client.js #resumeCompletion] Error in cleanup phase',+ err,+ );+ }+ if (this._resolveRun) {+ this._resolveRun(this.run ?? null);+ this._resolveRun = null;+ }+ run = null;+ config = null;+ }+ }+/*** Resolves with the agent run once it is initialized, or `null` if* initialization fails. Lets immediate-mode title generation await the rundiff --git a/api/server/controllers/agents/client.test.js b/api/server/controllers/agents/client.test.jsindex 1320e362c1..1646a448a7 100644--- a/api/server/controllers/agents/client.test.js+++ b/api/server/controllers/agents/client.test.js@@ -48,6 +48,32 @@ jest.mock('~/config', () => ({})),}));+describe('AgentClient - applyHideSequentialOutputsFilter', () => {+ const textPart = (text) => ({ type: ContentTypes.TEXT, text });+ const toolCallPart = (id) => ({ type: ContentTypes.TOOL_CALL, tool_call: { id } });++ it('keeps only the last part + tool_call parts when hide_sequential_outputs is on', () => {+ const ctx = {+ options: { agent: { hide_sequential_outputs: true } },+ contentParts: [+ textPart('intermediate'),+ toolCallPart('tc1'),+ textPart('reasoning'),+ textPart('final'),+ ],+ };+ AgentClient.prototype.applyHideSequentialOutputsFilter.call(ctx);+ expect(ctx.contentParts).toEqual([toolCallPart('tc1'), textPart('final')]);+ });++ it('is a no-op when hide_sequential_outputs is off', () => {+ const parts = [textPart('a'), textPart('b')];+ const ctx = { options: { agent: { hide_sequential_outputs: false } }, contentParts: parts };+ AgentClient.prototype.applyHideSequentialOutputsFilter.call(ctx);+ expect(ctx.contentParts).toEqual([textPart('a'), textPart('b')]);+ });+});+describe('AgentClient - titleConvo', () => {let client;let mockRun;diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex 0b8c0cee1a..81213a23d9 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -94,7 +94,10 @@ function getPreliminaryResponseMessageId({ messageId, responseMessageId }) {return `${messageId.replace(/_+$/, '')}_`;}-function getPreliminaryUserMessage({ messageId, parentMessageId, text, quotes }, conversationId) {+function getPreliminaryUserMessage(+ { messageId, parentMessageId, text, quotes, files, manualSkills, alwaysAppliedSkills },+ conversationId,+) {if (typeof messageId !== 'string' || messageId.length === 0) {return null;}@@ -113,6 +116,17 @@ function getPreliminaryUserMessage({ messageId, parentMessageId, text, quotes },conversationId,text,...(referencedQuotes != null && { quotes: referencedQuotes }),+ // Persist the turn's uploaded files on this AWAITED preliminary write so they land on+ // job.metadata.userMessage BEFORE the run can reach its first interrupt. onStart's+ // later writes are fire-and-forget, so a fast approval could otherwise read the job+ // and resume an approved code/read-file tool without the paused turn's uploads.+ ...(Array.isArray(files) && files.length > 0 && { files }),+ // Carry skill selections so a HITL-resumed turn's reconstructed `requestMessage`+ // keeps its skill pills — the client's final handler replaces the user bubble from+ // this object, and they'd otherwise vanish until a full reload refetches the row.+ ...(Array.isArray(manualSkills) && manualSkills.length > 0 && { manualSkills }),+ ...(Array.isArray(alwaysAppliedSkills) &&+ alwaysAppliedSkills.length > 0 && { alwaysAppliedSkills }),};}@@ -248,6 +262,12 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitendpoint: endpointOption.endpoint,iconURL: endpointIconURL,model: responseModel,+ // Persist the originating agent so a HITL resume can refuse to rebuild this+ // paused run on a different agent (see resume.js).+ agent_id: endpointOption.agent_id ?? req.body?.agent_id,+ // Persist temporary-chat state so a HITL resume keeps the resumed response+ // non-persisted instead of trusting the resume request to re-send the flag.+ isTemporary: req.body?.isTemporary,responseMessageId: preliminaryResponseMessageId,userMessage: preliminaryUserMessage,});@@ -344,6 +364,10 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit}client = result.client;+ // Tag the client with THIS generation's identity so HITL terminal side-effects+ // (pause CAS, checkpoint prune) can tell whether a newer request has since replaced+ // this job on the same conversationId before acting on it.+ client.jobCreatedAt = jobCreatedAt;// Resolve title timing from the public agents endpoint first, then fall// back to the agent's actual backing provider/custom endpoint.@@ -450,12 +474,44 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitconversationId: userMsg.conversationId,text: userMsg.text,quotes: userMsg.quotes,+ // Persist the turn's uploaded files here (authoritative job metadata) so a+ // HITL resume sources them from the job, not the user DB row — which the+ // approval prompt can race (the row save may still be in flight when a fast+ // /resume reads it). Without this an approved tool run can rebuild without the+ // paused turn's files.+ ...(Array.isArray(req.body?.files) &&+ req.body.files.length > 0 && { files: req.body.files }),+ // Skill selections aren't on `userMsg` yet at onStart (BaseClient adds them+ // later), so source them from the request — otherwise this update overwrites+ // the preliminary metadata and a HITL-resumed turn loses its skill pills.+ ...(Array.isArray(req.body?.manualSkills) &&+ req.body.manualSkills.length > 0 && { manualSkills: req.body.manualSkills }),+ ...(Array.isArray(req.body?.alwaysAppliedSkills) &&+ req.body.alwaysAppliedSkills.length > 0 && {+ alwaysAppliedSkills: req.body.alwaysAppliedSkills,+ }),},});GenerationJobManager.emitChunk(streamId, {created: true,- message: userMessage,+ // Skill selections aren't on `userMessage` yet at onStart (BaseClient adds+ // them later), so attach them from the request — this is the message+ // `trackUserMessage` persists as the authoritative job.metadata.userMessage,+ // and it's what the live client renders the user bubble from.+ message: {+ ...userMessage,+ // Carry files so trackUserMessage (the authoritative writer) persists them on+ // job.metadata.userMessage for a HITL resume (see the updateMetadata above).+ ...(Array.isArray(req.body?.files) &&+ req.body.files.length > 0 && { files: req.body.files }),+ ...(Array.isArray(req.body?.manualSkills) &&+ req.body.manualSkills.length > 0 && { manualSkills: req.body.manualSkills }),+ ...(Array.isArray(req.body?.alwaysAppliedSkills) &&+ req.body.alwaysAppliedSkills.length > 0 && {+ alwaysAppliedSkills: req.body.alwaysAppliedSkills,+ }),+ },streamId,});};@@ -503,6 +559,99 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitconst response = await sendPromise;+ // HITL: the turn paused for human review (see AgentClient.handleRunInterrupt).+ // The job is already `requires_action` with the pending action persisted and+ // emitted to the client; the resume route owns finishing this turn. Settle the+ // in-flight user-message / conversation save, then tear down WITHOUT saving a+ // partial response, emitting a terminal event, or completing the job.+ if (client?.pendingApproval) {+ if (response?.databasePromise) {+ try {+ await response.databasePromise;+ } catch (dbErr) {+ logger.error(+ '[ResumableAgentController] Error settling databasePromise on HITL pause',+ dbErr,+ );+ }+ delete response.databasePromise;+ }+ // BaseClient saved the response as completed (unfinished:false), but the turn+ // is paused awaiting a decision. Re-mark it unfinished so an expired / never-+ // resumed approval doesn't leave a "finished" response in history; the resume+ // path overwrites it with the full completed message on success.+ if (response?.messageId) {+ // Guard against a fast /resume: the user can approve the instant the+ // pending-action SSE lands, and resume.js can then claim + finalize — saving+ // the COMPLETED response — while we're still awaiting `response.databasePromise`+ // above. Marking the row unfinished now would clobber that completed content+ // with this stale pre-pause response. Only mark unfinished while the job is+ // STILL paused on THIS generation's action: a claim transitions it out of+ // `requires_action`, and a replacement bumps `createdAt`. Fail open on a read+ // error so a genuinely never-resumed approval isn't left looking "finished".+ let stillPaused = true;+ try {+ const liveJob = await GenerationJobManager.getJob(streamId);+ stillPaused =+ !!liveJob &&+ liveJob.status === 'requires_action' &&+ (client?.jobCreatedAt == null || liveJob.createdAt === client.jobCreatedAt);+ } catch (readErr) {+ logger.warn(+ '[ResumableAgentController] Pause unfinished-save liveness check failed; proceeding',+ readErr?.message ?? readErr,+ );+ }+ if (!stillPaused) {+ logger.debug(+ `[ResumableAgentController] Skipping pause unfinished-save — ${streamId} already resumed/replaced`,+ );+ } else {+ try {+ await saveMessage(+ {+ userId,+ isTemporary: req?.body?.isTemporary,+ interfaceConfig: req?.config?.interfaceConfig,+ },+ {+ ...response,+ endpoint: endpointOption.endpoint,+ unfinished: true,+ user: userId,+ },+ {+ context:+ 'api/server/controllers/agents/request.js - HITL pause (mark unfinished)',+ },+ );+ } catch (saveErr) {+ logger.error(+ '[ResumableAgentController] Failed to mark paused response unfinished',+ saveErr,+ );+ }+ }+ }+ titleAbortController.abort();+ acceptsTitleEvents = false;+ resolveConvoReady();+ // handleRunInterrupt already released the concurrency slot the moment it paused+ // (so a fast /resume isn't 429'd); only release here if that didn't happen.+ // Always run the MCP request-context cleanup.+ await cleanupMCPRequestContextForReq(req);+ if (!client?.pendingRequestReleased) {+ await decrementPendingRequest(userId);+ }+ if (client) {+ disposeClient(client);+ }+ logger.debug(+ `[ResumableAgentController] Turn paused for approval; awaiting resume: ${streamId}`,+ );+ return;+ }+const messageId = response.messageId;const endpoint = endpointOption.endpoint;response.endpoint = endpoint;diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.jsnew file mode 100644index 0000000000..cc7512dc6f--- /dev/null+++ b/api/server/controllers/agents/resume.js@@ -0,0 +1,700 @@+const { logger } = require('@librechat/data-schemas');+const { Constants, EModelEndpoint } = require('librechat-data-provider');+const {+ GenerationJobManager,+ isPendingActionStale,+ mapToolApprovalResolutions,+ mapAskUserAnswer,+ findUndecidedToolCalls,+ findDisallowedDecisions,+ findIncompleteDecisions,+ computeAgentRequestFingerprint,+ deleteAgentCheckpoint,+ buildAbortedResponseMetadata,+ sanitizeMessageForTransmit,+ filterMalformedContentParts,+ decrementPendingRequest,+ checkAndIncrementPendingRequest,+} = require('@librechat/api');+const { disposeClient } = require('~/server/cleanup');+const {+ getMCPRequestContext,+ cleanupMCPRequestContextForReq,+} = require('~/server/services/MCPRequestContext');+const { saveMessage, getConvo, getMessages } = require('~/models');++/** De-duplicate a merged attachment list by a stable artifact identity. */+function mergeAttachments(existing, incoming) {+ const seen = new Set();+ const out = [];+ for (const attachment of [...(existing ?? []), ...(incoming ?? [])]) {+ if (!attachment) {+ continue;+ }+ const key =+ attachment.file_id ??+ attachment.filepath ??+ attachment.filename ??+ JSON.stringify(attachment);+ if (seen.has(key)) {+ continue;+ }+ seen.add(key);+ out.push(attachment);+ }+ return out;+}++/**+ * Resolve the current segment's tool artifacts and merge them with any already+ * persisted on the response row. A resumed turn can span multiple pause segments;+ * each rebuilt client has its own `artifactPromises`, and the final finalize would+ * otherwise OVERWRITE the row's attachments with only the last segment's. Reading+ * the persisted row and merging keeps every segment's artifacts on the saved message.+ */+async function resolveAccumulatedAttachments({ client, conversationId, responseMessageId }) {+ const promises = Array.isArray(client?.artifactPromises) ? client.artifactPromises : [];+ const resolved = promises.length > 0 ? (await Promise.all(promises)).filter(Boolean) : [];+ let existing = [];+ if (responseMessageId) {+ try {+ const [row] = await getMessages(+ { conversationId, messageId: responseMessageId },+ 'attachments',+ );+ existing = Array.isArray(row?.attachments) ? row.attachments : [];+ } catch (err) {+ logger.warn(+ '[ResumeAgentController] Failed to read prior attachments for merge',+ err?.message ?? err,+ );+ }+ }+ return mergeAttachments(existing, resolved);+}++/** Resolve the segment's content for an unfinished save (mirrors finalize's source). */+async function resolveSegmentContent(client, streamId) {+ const liveContent = Array.isArray(client?.contentParts) ? client.contentParts : [];+ const rawContent =+ liveContent.length > 0+ ? liveContent+ : ((await GenerationJobManager.getResumeState(streamId))?.aggregatedContent ?? []);+ return filterMalformedContentParts(rawContent);+}++/**+ * A resumed segment that streamed content / produced artifacts and then paused AGAIN+ * must persist that progress before returning. The next resume rebuilds a fresh client+ * (empty `contentParts`/`artifactPromises`), so without this an approval that later+ * expires or is reaped would leave only the EARLIER pause's content on the saved row —+ * the user loses everything streamed during this segment. Saved as a partial (`$set`,+ * still `unfinished`) so a subsequent successful resume overwrites it on finalize.+ */+async function persistRePauseProgress({ req, client, job, streamId, conversationId }) {+ const userId = req.user.id;+ const meta = job.metadata ?? {};+ const responseMessageId = meta.responseMessageId ?? client.responseMessageId;+ if (!responseMessageId) {+ return;+ }+ const content = await resolveSegmentContent(client, streamId);+ const attachments = await resolveAccumulatedAttachments({+ client,+ conversationId,+ responseMessageId,+ });+ if (content.length === 0 && attachments.length === 0) {+ return;+ }+ try {+ await saveMessage(+ {+ userId,+ isTemporary: meta.isTemporary ?? req.body?.isTemporary,+ interfaceConfig: req?.config?.interfaceConfig,+ },+ {+ messageId: responseMessageId,+ conversationId,+ ...(content.length > 0 && { content }),+ ...(attachments.length > 0 && { attachments }),+ unfinished: true,+ user: userId,+ },+ { context: 'api/server/controllers/agents/resume.js - re-pause progress persist' },+ );+ } catch (err) {+ logger.error('[ResumeAgentController] Failed to persist re-pause progress', err);+ }+}++/** Untenanted jobs (pre-multi-tenancy) remain accessible if the userId check passes. */+function hasTenantMismatch(job, user) {+ return job.metadata?.tenantId != null && job.metadata.tenantId !== user.tenantId;+}++/**+ * Build the SDK resume value from the wire decision payload, validating against the+ * pending action. Returns `{ resumeValue }` on success or `{ error }` with an HTTP+ * status for the route to surface.+ */+function resolveResumeValue(pendingAction, body) {+ const payload = pendingAction.payload;+ if (payload?.type === 'tool_approval') {+ const resolutions = Array.isArray(body.decisions) ? body.decisions : [];+ const undecided = findUndecidedToolCalls(payload, resolutions);+ if (undecided.length > 0) {+ return { status: 400, error: 'Every paused tool call must be decided', undecided };+ }+ // Enforce the policy's per-tool allowed_decisions — a crafted POST must not+ // approve a tool the policy restricted to (e.g.) reject/respond.+ const disallowed = findDisallowedDecisions(payload, resolutions);+ if (disallowed.length > 0) {+ return { status: 403, error: 'Decision not permitted for one or more tools', disallowed };+ }+ // `edit`/`respond` must carry their payload — otherwise toSdkDecision's defensive+ // defaults ({} / '') would resume with an empty input/result the user didn't approve.+ const incomplete = findIncompleteDecisions(resolutions);+ if (incomplete.length > 0) {+ return {+ status: 400,+ error: 'edit requires editedArguments and respond requires responseText',+ incomplete,+ };+ }+ return { resumeValue: mapToolApprovalResolutions(resolutions) };+ }+ if (payload?.type === 'ask_user_question') {+ if (typeof body.answer !== 'string' || body.answer.length === 0) {+ return { status: 400, error: 'An answer is required' };+ }+ return { resumeValue: mapAskUserAnswer({ answer: body.answer }) };+ }+ return { status: 400, error: 'Unsupported pending action type' };+}++/**+ * Finalize a resumed turn that ran to completion: persist the (now complete)+ * response message, emit the terminal event over the existing SSE, complete the+ * job, and prune the checkpoint. Mirrors the abort route's save shape but for a+ * successful finish. Best-effort title generation for a first-turn pause.+ */+async function finalizeResumedTurn({ req, client, job, streamId, conversationId, addTitle }) {+ const userId = req.user.id;+ const checkpointerCfg = req.config?.endpoints?.[EModelEndpoint.agents]?.checkpointer;+ const meta = job.metadata ?? {};+ const userMessage = meta.userMessage;+ // The response hangs off the user message; the *user* message's own parent decides+ // whether this is the first turn of the conversation (title eligibility).+ const parentMessageId = userMessage?.messageId ?? Constants.NO_PARENT;+ const isFirstTurn = (userMessage?.parentMessageId ?? Constants.NO_PARENT) === Constants.NO_PARENT;+ const responseMessageId = meta.responseMessageId ?? `${userMessage?.messageId ?? 'resumed'}_`;+ // Sourced from the paused job (persisted at creation), not the resume body — a+ // temporary chat must stay temporary on resume so its messages aren't persisted.+ const isTemporary = meta.isTemporary ?? req.body?.isTemporary;++ // Read the raw job data BEFORE completeJob deletes it — its tracked token/context+ // usage backs the response message's cost rollup (parity with normal completion).+ const jobData = await GenerationJobManager.getJobStore().getJob(streamId);++ // Job-replacement guard (mirrors the normal request path): jobs are keyed by streamId+ // (== conversationId), so a new/concurrent request reusing this conversation overwrites+ // the record with a fresh createdAt. If that happened while we were resuming, finalizing+ // now would emit `done` to / complete / delete the NEWER turn's job. Skip all terminal+ // side effects when the job we paused is no longer the live one; the caller's `finally`+ // still disposes the client + releases the slot.+ if (!jobData || jobData.createdAt !== job.createdAt) {+ logger.warn(+ `[ResumeAgentController] Skipping resumed finalization — job ${streamId} was replaced`,+ );+ return;+ }+ // Prefer the resumed run's live content: it's complete (seeded with the pre-pause+ // content) and avoids a Redis re-read that can race appendChunk writes still in+ // flight. Fall back to the aggregated store content only when the live array is empty.+ const liveContent = Array.isArray(client?.contentParts) ? client.contentParts : [];+ const rawContent =+ liveContent.length > 0+ ? liveContent+ : ((await GenerationJobManager.getResumeState(streamId))?.aggregatedContent ?? []);+ // Parity with the normal agents path (AgentClient strips these before saving):+ // drop empty/malformed tool_call parts so a resumed turn can't persist an invalid+ // part that breaks reload/rendering.+ const content = filterMalformedContentParts(rawContent);++ const responseMessage = {+ messageId: responseMessageId,+ parentMessageId,+ conversationId,+ content,+ sender: meta.sender ?? client?.sender ?? 'AI',+ endpoint: meta.endpoint,+ iconURL: meta.iconURL,+ model: meta.model,+ unfinished: false,+ error: false,+ isCreatedByUser: false,+ user: userId,+ };+ if (meta.agent_id ?? req.body?.agent_id) {+ responseMessage.agent_id = meta.agent_id ?? req.body.agent_id;+ }+ // Persist tool artifacts (code files, images, UI resources) the resumed continuation+ // produced — BaseClient.sendMessage awaits these before saving, but the lean resume+ // path bypasses it, so do it here or they vanish on reload / for late subscribers.+ // MERGE with any already on the row (earlier pause segments) rather than overwrite —+ // the final segment's client only holds its own segment's artifacts.+ const attachments = await resolveAccumulatedAttachments({+ client,+ conversationId,+ responseMessageId,+ });+ if (attachments.length > 0) {+ responseMessage.attachments = attachments;+ }++ // Response metadata: the resume client only sees POST-resume usage, while the job's+ // tracked tokenUsage is cumulative across the pause. Take the cumulative usage (++ // summary marker) from the job, and contextUsage / thoughtSignatures from the client+ // (which the abort-only helper drops). Cumulative usage wins so cost isn't underreported.+ const clientMeta = client?.buildResponseMetadata?.() ?? null;+ const cumulativeMeta = jobData ? buildAbortedResponseMetadata(jobData) : null;+ const responseMetadata = {+ ...(clientMeta ?? {}),+ ...(cumulativeMeta?.usage ? { usage: cumulativeMeta.usage } : {}),+ ...(cumulativeMeta?.summaryUsedTokens != null+ ? { summaryUsedTokens: cumulativeMeta.summaryUsedTokens }+ : {}),+ };+ if (Object.keys(responseMetadata).length > 0) {+ responseMessage.metadata = responseMetadata;+ }+ // Carry the resumed run's context-window calibration (BaseClient.sendMessage persists+ // this on the response). Without it, the NEXT turn can't seed its pruner from this+ // run and falls back to uncalibrated token accounting.+ if (client?.contextMeta != null) {+ responseMessage.contextMeta = client.contextMeta;+ }++ await saveMessage(+ { userId, isTemporary, interfaceConfig: req?.config?.interfaceConfig },+ responseMessage,+ { context: 'api/server/controllers/agents/resume.js - resumed response end' },+ );++ const convo = await getConvo(userId, conversationId);+ const conversation = { ...(convo ?? {}), conversationId };++ // First-turn pause: the title was deferred when the turn paused. Generate it BEFORE+ // completing the stream so the `title` event still reaches the live client (emitChunk+ // no-ops once completeJob tears down the runtime) and the final event carries the real+ // title instead of "New Chat". Best-effort — a failure must not fail the resumed turn.+ if (+ addTitle &&+ isFirstTurn &&+ !isTemporary &&+ userMessage?.text &&+ (!convo || !convo.title || convo.title === 'New Chat')+ ) {+ try {+ await addTitle(req, {+ text: userMessage.text,+ conversationId,+ client,+ onTitleGenerated: ({ conversationId: titleConvoId, title }) => {+ conversation.title = title;+ return GenerationJobManager.emitChunk(streamId, {+ event: 'title',+ data: { conversationId: titleConvoId, title },+ });+ },+ });+ } catch (err) {+ logger.error('[ResumeAgentController] Title generation failed after resume', err);+ }+ }+ conversation.title = conversation.title || 'New Chat';++ // Re-check ownership immediately before the terminal writes. The start-of-function+ // guard can go stale across the awaits above: saveMessage and (first-turn) title+ // generation can take long enough for a new request to replace this job on the same+ // conversationId (streamId == conversationId). Without this second read, emitDone /+ // completeJob / prune below would emit `done` to and tear down the REPLACEMENT job —+ // the same hazard the catch-path guard prevents on the failure path.+ const liveJobBeforeFinalize = await GenerationJobManager.getJobStore().getJob(streamId);+ if (!liveJobBeforeFinalize || liveJobBeforeFinalize.createdAt !== job.createdAt) {+ logger.warn(+ `[ResumeAgentController] Skipping resumed terminal writes — job ${streamId} was replaced mid-finalize`,+ );+ return;+ }++ const finalEvent = {+ final: true,+ conversation,+ title: conversation.title,+ requestMessage: userMessage+ ? sanitizeMessageForTransmit({+ ...userMessage,+ conversationId,+ isCreatedByUser: true,+ // job.metadata.userMessage is persisted without files; carry the restored+ // uploads (seeded onto req.body.files before reconstruction) so the final SSE+ // doesn't blank the user bubble's attachments — matching the normal path.+ ...(Array.isArray(req.body?.files) && req.body.files.length > 0+ ? { files: req.body.files }+ : {}),+ })+ : null,+ responseMessage: { ...responseMessage },+ };++ await GenerationJobManager.emitDone(streamId, finalEvent);+ // Awaited (not fire-and-forget) so the job's terminal write lands before the+ // checkpoint prune, and so a failure here doesn't race the controller's error path.+ try {+ await GenerationJobManager.completeJob(streamId);+ } catch (completeErr) {+ logger.error('[ResumeAgentController] Failed to complete resumed turn', completeErr);+ }+ await deleteAgentCheckpoint(conversationId, checkpointerCfg);+}++/**+ * Resume a generation that paused for human-in-the-loop review.+ *+ * The original run lives in a detached background task that exits when the run+ * pauses, so this REBUILDS the run from the durable checkpoint (same `thread_id`)+ * and continues it with the user's decision. The continuation streams over the+ * client's existing SSE (events flow through the same `streamId`).+ *+ * Flow: authorize → map decisions → atomically claim the resume (single-winner) →+ * ACK → reconstruct the client → `resumeCompletion` → finalize (or re-pause).+ *+ * Shares chat.js's middleware (auth, agent access, `buildEndpointOption`) so the+ * agent/endpoint are reconstructed from the request exactly like a normal turn.+ *+ * @param {express.Request} req+ * @param {express.Response} res+ * @param {express.NextFunction} next+ * @param {Function} initializeClient+ * @param {Function} addTitle+ */+const ResumeAgentController = async (req, res, next, initializeClient, addTitle) => {+ const userId = req.user.id;+ const { conversationId, actionId } = req.body;+ const streamId = conversationId;++ if (!streamId || streamId === 'new') {+ return res.status(400).json({ error: 'conversationId is required to resume' });+ }++ const job = await GenerationJobManager.getJob(streamId);+ if (!job) {+ return res.status(404).json({ error: 'No paused generation for this conversation' });+ }+ if (job.metadata?.userId && job.metadata.userId !== userId) {+ return res.status(403).json({ error: 'Unauthorized' });+ }+ if (hasTenantMismatch(job, req.user)) {+ return res.status(403).json({ error: 'Unauthorized' });+ }++ // The resume must rebuild the SAME agent/endpoint that paused. Require an EXACT+ // agent_id match when the paused job had one — a request that omits agent_id (or+ // claims an ephemeral / non-agents endpoint) must not rebuild the claimed checkpoint+ // on a different graph. The conversation's agent is stable, so a correct client always+ // sends the right one.+ const originalAgentId = job.metadata?.agent_id;+ if (originalAgentId && req.body.agent_id !== originalAgentId) {+ return res.status(403).json({ error: 'Cannot resume with a different agent' });+ }+ // Require an EXACT endpoint match (like agent_id): a request that OMITS endpoint must+ // not fall through — the shared chat middleware treats a missing/non-agents endpoint+ // as the ephemeral agent, so omitting it could rebuild the claimed checkpoint on a+ // different graph. A correct client always echoes the paused endpoint.+ const originalEndpoint = job.metadata?.endpoint;+ if (originalEndpoint && req.body.endpoint !== originalEndpoint) {+ return res.status(403).json({ error: 'Cannot resume on a different endpoint' });+ }++ const pendingAction = job.metadata?.pendingAction;+ if (job.status !== 'requires_action') {+ return res.status(409).json({ error: 'No live pending action to resume' });+ }+ if (isPendingActionStale({ pendingAction })) {+ // The action expired between the pending-action SSE and this submit. Drive the expiry+ // NOW (expire CAS + terminal SSE) instead of waiting for the periodic sweeper —+ // otherwise the job sits `requires_action` with a dead action and any attached SSE+ // client never gets a terminal event, so the stream appears to hang even though the+ // UI already reported the action as expired.+ try {+ await GenerationJobManager.expireApproval(streamId, pendingAction?.actionId);+ } catch (err) {+ logger.warn(+ '[ResumeAgentController] Failed to expire stale action on submit',+ err?.message ?? err,+ );+ }+ return res.status(409).json({ error: 'No live pending action to resume' });+ }+ // Require the actionId the UI sends: without it, a stale/malformed client could+ // resolve whatever action is currently pending (e.g. answer a different question).+ if (!actionId) {+ return res.status(400).json({ error: 'actionId is required to resume' });+ }+ if (pendingAction.actionId !== actionId) {+ return res.status(409).json({ error: 'This decision targets a stale action' });+ }++ // Pin the graph identity: the resume must rebuild the SAME agent/graph + tool set the+ // run paused on. The agent_id + endpoint guards above cover saved agents; the+ // fingerprint additionally catches an ephemeral-agent config swap (its agent_id is+ // undefined, so the id guard can't tell two ephemeral configs apart). Enforced only+ // when the paused action carries a fingerprint (in-flight pauses from before this+ // change won't), and recomputed from the resume body's graph-determining fields.+ const pinnedFingerprint = pendingAction.requestFingerprint;+ if (pinnedFingerprint && pinnedFingerprint !== computeAgentRequestFingerprint(req.body ?? {})) {+ return res.status(403).json({ error: 'Cannot resume with a different agent configuration' });+ }++ const mapped = resolveResumeValue(pendingAction, req.body);+ if (mapped.error) {+ return res.status(mapped.status).json({+ error: mapped.error,+ ...(mapped.undecided && { undecided: mapped.undecided }),+ ...(mapped.disallowed && { disallowed: mapped.disallowed }),+ ...(mapped.incomplete && { incomplete: mapped.incomplete }),+ });+ }++ // Count the resume against the concurrency limit. The original turn released its slot+ // when it paused, so resuming must re-acquire one — otherwise pausing several turns+ // and resuming them at once would bypass LIMIT_CONCURRENT_MESSAGES.+ const { allowed } = await checkAndIncrementPendingRequest(userId);+ if (!allowed) {+ return res.status(429).json({ error: 'Too many concurrent requests' });+ }++ // Atomically claim the resume. The single winner drives the run; a racing second+ // submit (double-click, two tabs) gets false and must not re-drive — that would+ // re-execute tools and double-bill.+ //+ // The claim runs AFTER the slot increment above but BEFORE the run's own try/finally+ // that releases it, so a store/Redis error here (unlike the clean `!claimed` branch)+ // would leak the concurrency slot until the counter TTL expires — spuriously 429'ing+ // the user when they retry the still-paused approval. Release the slot on that path too.+ let claimed;+ try {+ claimed = await GenerationJobManager.approvals.resolve(streamId, pendingAction.actionId);+ } catch (err) {+ await decrementPendingRequest(userId);+ logger.error('[ResumeAgentController] Failed to claim resume', err);+ return res.status(500).json({ error: 'Failed to resume' });+ }+ if (!claimed) {+ await decrementPendingRequest(userId);+ return res.status(409).json({ error: 'This action was already resolved or has expired' });+ }++ // Seed the run-scoped MCP request-context store BEFORE the ACK: once `res.json`+ // finishes the response, a later `getMCPRequestContext(req, res)` (from tool loading)+ // sees `res` as ended and returns undefined, leaving the resumed run without its MCP+ // connection store — approved MCP / OAuth-overlay tools would then run without their+ // request-scoped connections. Pre-seeding with a null `res` + `cleanupOnResponse:false`+ // mirrors the normal stream path (request.js); torn down in the `finally` below.+ req._resumableStreamId = streamId;+ getMCPRequestContext(req, undefined, { cleanupOnResponse: false });++ // ACK immediately; the continuation streams over the client's existing SSE.+ res.json({ streamId, conversationId, status: 'resuming' });++ // Seed the original thread parent BEFORE initializeClient: initializeAgent scopes+ // thread files / code artifacts off `req.body.parentMessageId`, and the resume body+ // doesn't carry it. This is the user message's parent (the thread position);+ // `client.parentMessageId` below is a different value — the response's parent, i.e.+ // the user message id.+ req.body.parentMessageId = job.metadata.userMessage?.parentMessageId ?? Constants.NO_PARENT;++ // Restore the paused user message's OWN uploaded files. initializeAgent rebuilds+ // code/file sessions by walking the conversation from `parentMessageId`, but+ // execute-code files are excluded from that lookup, so files uploaded on the paused+ // turn would be dropped — an approved code/read-file tool would resume without them.+ //+ // SECURITY: ALWAYS source files from the paused job, never from the `/resume` body.+ // `files` is not pinned by the resume fingerprint or replayed via resumeContext, so+ // honoring a client-supplied `files` array would let a crafted/buggy client resume an+ // approved code/read-file tool against a DIFFERENT file set than the one the user+ // approved. A resume reconstructs the SAME paused turn, so there is no legitimate+ // reason for the client to supply its own files. Prefer the files persisted on the JOB+ // at onStart (race-free), fall back to the DB row for older jobs, and CLEAR otherwise+ // so a client-supplied set can never leak through.+ const metaFiles = job.metadata.userMessage?.files;+ if (Array.isArray(metaFiles) && metaFiles.length > 0) {+ req.body.files = metaFiles;+ } else {+ let restoredFiles = false;+ const pausedUserMessageId = job.metadata.userMessage?.messageId;+ if (pausedUserMessageId) {+ try {+ const [row] = await getMessages(+ { conversationId, messageId: pausedUserMessageId },+ 'files',+ );+ if (Array.isArray(row?.files) && row.files.length > 0) {+ req.body.files = row.files;+ restoredFiles = true;+ }+ } catch (err) {+ logger.warn(+ '[ResumeAgentController] Failed to restore paused user message files',+ err?.message ?? err,+ );+ }+ }+ if (!restoredFiles) {+ // No paused files (or the lookup failed): drop any client-supplied files so a+ // crafted resume body can't inject a file set the paused turn never had.+ req.body.files = [];+ }+ }++ // Restore the conversation's createdAt so temporal prompt vars ({{current_datetime}},+ // {{iso_datetime}}, ...) resolve against the SAME anchor the paused graph used rather+ // than the resume wall-clock. initializeAgent reads `req.conversationCreatedAt`; the+ // normal path sets it from the convo timestamp (resolveConversationCreatedAt), so mirror+ // that here. (The original `timezone` is replayed onto req.body via RESUME_CONTEXT_KEYS.)+ try {+ const resumedConvo = await getConvo(userId, conversationId);+ const createdAt = resumedConvo?.createdAt ? new Date(resumedConvo.createdAt) : null;+ if (createdAt && !Number.isNaN(createdAt.getTime())) {+ req.conversationCreatedAt = createdAt.toISOString();+ }+ } catch (err) {+ logger.warn(+ '[ResumeAgentController] Failed to restore conversation timestamp anchor',+ err?.message ?? err,+ );+ }++ let client = null;+ try {+ const result = await initializeClient({+ req,+ res,+ endpointOption: req.body.endpointOption,+ signal: job.abortController.signal,+ });+ client = result.client;++ // Bind the rebuilt client to the in-flight turn's identity (no new user message).+ client.conversationId = streamId;+ // The resume operates on the SAME job (it moved it running again), so its identity is+ // the paused job's createdAt — used by the re-pause CAS pre-check + checkpoint prune to+ // avoid acting on a job a newer request has since replaced.+ client.jobCreatedAt = job.createdAt;+ client.responseMessageId = job.metadata.responseMessageId;+ client.parentMessageId = job.metadata.userMessage?.messageId ?? Constants.NO_PARENT;+ // Read the pre-pause content BEFORE swapping the store's content reference: the+ // in-memory store's setContentParts REPLACES the stored array, so reading the+ // resume state afterward would see the new (empty) client array and lose the seed.+ const resumeState = await GenerationJobManager.getResumeState(streamId);+ const seedContent = resumeState?.aggregatedContent ?? [];+ if (client.contentParts) {+ GenerationJobManager.setContentParts(streamId, client.contentParts);+ }++ await client.resumeCompletion({+ resumeValue: mapped.resumeValue,+ seedContent,+ abortController: job.abortController,+ // Carry the user's MCP auth so approved MCP tools run with their credentials.+ userMCPAuthMap: result.userMCPAuthMap,+ // Replay deferred tools discovered before the pause (captured at pause). The rebuilt+ // graph passes `messages: []`, so without these an approved deferred tool would be+ // absent from the schema-only toolMap and resume would fail with "unknown tool".+ discoveredToolNames: job.metadata?.discoveredTools,+ });++ // The model may pause AGAIN (another tool, or a follow-up question). The pending+ // action is already persisted + emitted; leave the job `requires_action`.+ if (client.pendingApproval) {+ logger.debug(`[ResumeAgentController] Re-paused for approval: ${streamId}`);+ // Persist this segment's content + artifacts before the fresh client (next+ // resume) drops them, so an expiring re-pause doesn't lose them; finalize later+ // overwrites content and merges attachments onto the saved message.+ await persistRePauseProgress({ req, client, job, streamId, conversationId });+ return;+ }++ // If the user aborted mid-resume, the abort route already emitted the terminal+ // event and finalized the job — don't double-save / double-finalize here.+ if (job.abortController.signal.aborted) {+ logger.debug(+ `[ResumeAgentController] Aborted during resume; abort route finalizes: ${streamId}`,+ );+ return;+ }++ await finalizeResumedTurn({ req, client, job, streamId, conversationId, addTitle });+ } catch (err) {+ logger.error('[ResumeAgentController] Resume failed', err);+ // Job-replacement guard (mirrors finalizeResumedTurn's success-path guard): if a+ // newer request reused this conversationId while the resume was failing, do NOT emit+ // the error to / complete / prune the NEWER turn's job. The finally still releases+ // the slot + disposes. Proceed with finalization if the replacement check itself fails.+ let stillLive = true;+ try {+ const liveJob = await GenerationJobManager.getJobStore().getJob(streamId);+ stillLive = !!liveJob && liveJob.createdAt === job.createdAt;+ } catch (readErr) {+ logger.warn('[ResumeAgentController] Replacement check failed; finalizing anyway', readErr);+ }+ if (!stillLive) {+ logger.warn(+ `[ResumeAgentController] Skipping failed-resume finalization — job ${streamId} was replaced`,+ );+ } else {+ try {+ await GenerationJobManager.emitError(streamId, err?.message ?? 'Resume failed');+ } catch (emitErr) {+ logger.error('[ResumeAgentController] Failed to emit resume error', emitErr);+ }+ try {+ await GenerationJobManager.completeJob(streamId, err?.message ?? 'Resume failed');+ } catch (completeErr) {+ logger.error('[ResumeAgentController] Failed to finalize failed resume', completeErr);+ // Last resort: force a terminal state so the job isn't orphaned in `running`.+ await GenerationJobManager.getJobStore()+ .updateJob(streamId, {+ status: 'error',+ completedAt: Date.now(),+ error: 'Resume failed',+ })+ .catch((updErr) =>+ logger.error('[ResumeAgentController] Fallback job finalize failed', updErr),+ );+ }+ await deleteAgentCheckpoint(+ conversationId,+ req.config?.endpoints?.[EModelEndpoint.agents]?.checkpointer,+ );+ }+ } finally {+ // Tear down the MCP request-context store seeded before the ACK (parity with+ // request.js's finishResumableRequest). No-op if it was never seeded.+ await cleanupMCPRequestContextForReq(req);+ // Release the concurrency slot taken above — UNLESS handleRunInterrupt already+ // released it on a re-pause (so a fast /resume isn't 429'd). On a normal finish or+ // error it didn't, so release here. A re-pause re-acquires its own slot next resume.+ if (!client?.pendingRequestReleased) {+ await decrementPendingRequest(userId);+ }+ if (client) {+ disposeClient(client);+ }+ }+};++module.exports = ResumeAgentController;diff --git a/api/server/middleware/moderateText.js b/api/server/middleware/moderateText.jsindex 1aed0991ad..3356f75921 100644--- a/api/server/middleware/moderateText.js+++ b/api/server/middleware/moderateText.js@@ -17,8 +17,17 @@ async function moderateText(req, res, next) {* `getReferencedQuotes` first (matching `BaseClient`); moderating the merged* string also covers content split across a quote and the typed body. The* moderation API accepts an array of inputs.+ *+ * `answer` covers the HITL resume payload (POST /agents/chat/resume) for an+ * ask-user question — the user's free-form text — so it's moderated like a typed+ * message. A tool-approval resume carries no user text and is skipped below.*/- const safeText = typeof text === 'string' ? text : '';+ let safeText = '';+ if (typeof text === 'string') {+ safeText = text;+ } else if (typeof req.body.answer === 'string') {+ safeText = req.body.answer;+ }const inputs = [];if (safeText.length > 0) {inputs.push(safeText);@@ -28,7 +37,36 @@ async function moderateText(req, res, next) {inputs.push(...quotes);inputs.push(mergeQuotedText(safeText, quotes));}- const input = inputs.length > 1 ? inputs : (inputs[0] ?? text);+ // A tool-approval resume can carry user-authored text in `decisions[]`: the+ // `respond` substitute result, a `reject` reason, and `edit`ed tool arguments —+ // moderate all of them like typed text (edited args stringified).+ if (Array.isArray(req.body.decisions)) {+ for (const decision of req.body.decisions) {+ if (typeof decision?.responseText === 'string' && decision.responseText.length > 0) {+ inputs.push(decision.responseText);+ }+ if (typeof decision?.reason === 'string' && decision.reason.length > 0) {+ inputs.push(decision.reason);+ }+ if (decision?.editedArguments != null) {+ try {+ const edited = JSON.stringify(decision.editedArguments);+ if (typeof edited === 'string' && edited.length > 0) {+ inputs.push(edited);+ }+ } catch {+ /* ignore unstringifiable edited args */+ }+ }+ }+ }+ // Nothing to moderate (e.g. a tool-approval resume with no `respond` text) —+ // don't post an empty/undefined `input`, which the moderation API rejects and which+ // would otherwise deny the request.+ if (inputs.length === 0) {+ return next();+ }+ const input = inputs.length > 1 ? inputs : inputs[0];const response = await axios.post(process.env.OPENAI_MODERATION_REVERSE_PROXY || 'https://api.openai.com/v1/moderations',diff --git a/api/server/routes/agents/__tests__/abort.spec.js b/api/server/routes/agents/__tests__/abort.spec.jsindex 9fe007596c..15efb19a39 100644--- a/api/server/routes/agents/__tests__/abort.spec.js+++ b/api/server/routes/agents/__tests__/abort.spec.js@@ -293,6 +293,40 @@ describe('Agent Abort Endpoint', () => {);});+ it('saves the aborted partial as temporary from job metadata, not the request body', async () => {+ const jobStreamId = 'test-stream-123';++ mockGenerationJobManager.getJob.mockResolvedValue({+ metadata: { userId: 'test-user-123' },+ });++ // The job was a temporary chat; the stop button posts only conversationId.+ mockGenerationJobManager.abortJob.mockResolvedValue({+ success: true,+ jobData: {+ userMessage: { messageId: 'user-msg-123' },+ responseMessageId: 'response-msg-456',+ conversationId: jobStreamId,+ isTemporary: true,+ },+ content: [{ type: 'text', text: 'Partial...' }],+ text: 'Partial...',+ });++ mockSaveMessage.mockResolvedValue();++ const response = await request(app)+ .post('/api/agents/chat/abort')+ .send({ conversationId: jobStreamId }); // no isTemporary in body++ expect(response.status).toBe(200);+ expect(mockSaveMessage).toHaveBeenCalledWith(+ expect.objectContaining({ isTemporary: true }),+ expect.anything(),+ expect.anything(),+ );+ });+it('should handle saveMessage errors gracefully', async () => {const jobStreamId = 'test-stream-123';diff --git a/api/server/routes/agents/chat.js b/api/server/routes/agents/chat.jsindex 8ffbde6552..9463406652 100644--- a/api/server/routes/agents/chat.js+++ b/api/server/routes/agents/chat.js@@ -1,5 +1,12 @@const express = require('express');-const { createMessageFilterPii, generateCheckAccess, skipAgentCheck } = require('@librechat/api');+const { logger } = require('@librechat/data-schemas');+const {+ createMessageFilterPii,+ generateCheckAccess,+ skipAgentCheck,+ applyResumeContext,+ GenerationJobManager,+} = require('@librechat/api');const { PermissionTypes, Permissions, PermissionBits } = require('librechat-data-provider');const {moderateText,@@ -10,6 +17,7 @@ const {} = require('~/server/middleware');const { initializeClient } = require('~/server/services/Endpoints/agents');const AgentController = require('~/server/controllers/agents/request');+const ResumeController = require('~/server/controllers/agents/resume');const addTitle = require('~/server/services/Endpoints/agents/title');const { getRoleByName } = require('~/models');@@ -25,6 +33,45 @@ const checkAgentResourceAccess = canAccessAgentFromBody({requiredPermission: PermissionBits.VIEW,});+/**+ * Replay the paused turn's graph-determining config onto a resume request BEFORE the+ * rest of the chain (PII filter, agent-access, buildEndpointOption) reads it. The client+ * can't reliably re-send the ephemeral-agent config after a reload/cross-session, so the+ * server restores it from the pending action — the resume then rebuilds the SAME+ * agent/graph the run paused on (and a crafted resume can't swap the tool set). No-op for+ * every non-resume route.+ */+const restoreResumeContext = async (req, res, next) => {+ if (req.path !== '/resume') {+ return next();+ }+ try {+ const streamId = req.body?.conversationId;+ if (streamId) {+ const job = await GenerationJobManager.getJob(streamId);+ const resumeContext = job?.metadata?.pendingAction?.resumeContext;+ applyResumeContext(req.body, resumeContext);+ // Replay the paused turn's resolved model parameters. Ephemeral agents derive these+ // (temperature, max tokens, custom endpoint params) from the request body, which the+ // resume payload omits — without this the continuation runs with defaults. They're+ // scattered top-level fields (folded into model_parameters by buildOptions' rest+ // spread), not part of the RESUME_CONTEXT_KEYS allowlist, so merge them back here.+ // Authoritative: overwrites any client-supplied values with the captured set.+ // `model` is excluded — it's replayed via RESUME_CONTEXT_KEYS to the exact value the+ // resume fingerprint was pinned on, so overwriting it here could trip that check.+ const resumedModelParameters = resumeContext?.model_parameters;+ if (resumedModelParameters && typeof resumedModelParameters === 'object') {+ const { model: _replayedModel, ...replayParams } = resumedModelParameters;+ Object.assign(req.body, replayParams);+ }+ }+ } catch (err) {+ logger.warn('[agents/chat] Failed to restore resume context', err?.message ?? err);+ }+ next();+};++router.use(restoreResumeContext);router.use(createMessageFilterPii({ getConfig: (req) => req.config?.messageFilter?.pii }));router.use(moderateText);router.use(checkAgentAccess);@@ -36,6 +83,21 @@ const controller = async (req, res, next) => {await AgentController(req, res, next, initializeClient, addTitle);};+const resumeController = async (req, res, next) => {+ await ResumeController(req, res, next, initializeClient, addTitle);+};++/**+ * @route POST /resume+ * @desc Resume a generation paused for human-in-the-loop review (tool approval or+ * ask-user answer). Shares this router's middleware so the agent/endpoint are+ * reconstructed from the request exactly like a normal turn. Declared before+ * `/:endpoint` so it is not captured as an ephemeral endpoint name.+ * @access Private+ * @returns {void}+ */+router.post('/resume', resumeController);+/*** @route POST / (regular endpoint)* @desc Chat with an assistantdiff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.jsindex 7fb23f6c66..fe36869983 100644--- a/api/server/routes/agents/index.js+++ b/api/server/routes/agents/index.js@@ -5,6 +5,8 @@ const {hasPersistableAbortContent,buildAbortedResponseMetadata,isPendingActionStale,+ isHITLEnabled,+ deleteAgentCheckpoint,} = require('@librechat/api');const { createSseStreamTelemetry } = require('@librechat/api/telemetry');const { logger } = require('@librechat/data-schemas');@@ -231,7 +233,7 @@ router.get('/chat/status/:conversationId', async (req, res) => {* @access Private* @description Mounted before chatRouter to bypass buildEndpointOption middleware*/-router.post('/chat/abort', async (req, res) => {+router.post('/chat/abort', configMiddleware, async (req, res) => {logger.debug(`[AgentStream] ========== ABORT ENDPOINT HIT ==========`);logger.debug(`[AgentStream] Method: ${req.method}, Path: ${req.path}`);logger.debug(`[AgentStream] Body:`, req.body);@@ -288,6 +290,17 @@ router.post('/chat/abort', async (req, res) => {abortResultResponseMessageId: abortResult.jobData?.responseMessageId,});+ // HITL: prune the durable checkpoint of a run aborted while paused, so a new turn+ // in this conversation can't rehydrate the stale interrupt before the Mongo TTL+ // reclaims it (thread_id is the stable conversationId). Idempotent / no-op when+ // HITL is off or nothing was written.+ const agentsCfg = req.config?.endpoints?.agents;+ if (isHITLEnabled(agentsCfg?.toolApproval)) {+ await deleteAgentCheckpoint(jobStreamId, agentsCfg?.checkpointer).catch((err) =>+ logger.error(`[AgentStream] Failed to prune checkpoint on abort: ${jobStreamId}`, err),+ );+ }+// CRITICAL: Save partial response BEFORE returning to prevent race condition.// If user sends a follow-up immediately after abort, the parentMessageId must exist in DB.// Only save if we have a valid responseMessageId (skip early aborts before generation started)@@ -327,7 +340,10 @@ router.post('/chat/abort', async (req, res) => {await saveMessage({userId: req?.user?.id,- isTemporary: req?.body?.isTemporary,+ // Source from the job, not the request: the stop button posts only the+ // conversationId, so trusting req.body.isTemporary would persist an aborted+ // temporary-chat partial as a normal (orphaned) message.+ isTemporary: jobData?.isTemporary ?? req?.body?.isTemporary,interfaceConfig: req?.config?.interfaceConfig,},responseMessage,diff --git a/client/src/components/Chat/Messages/Content/ApprovalContext.tsx b/client/src/components/Chat/Messages/Content/ApprovalContext.tsxnew file mode 100644index 0000000000..aed523c42d--- /dev/null+++ b/client/src/components/Chat/Messages/Content/ApprovalContext.tsx@@ -0,0 +1,292 @@+import { createContext, useCallback, useContext, useMemo, useRef, useState } from 'react';+import { Constants } from 'librechat-data-provider';+import type { Agents } from 'librechat-data-provider';+import {+ useSubmitToolApprovalMutation,+ useSubmitAskAnswerMutation,+ type ResumeAgentFields,+} from '~/data-provider';+import { ChatContext } from '~/Providers/ChatContext';+import { useGetEphemeralAgent } from '~/store/agents';++/** Per-action submission lifecycle, surfaced to the cards so they can disable+ * controls and explain a terminal outcome. */+type ActionStatus = 'idle' | 'submitting' | 'submitted' | 'expired' | 'error';++interface ApprovalContextValue {+ /** Record (or clear) a card's decision for its tool_call within an action. */+ setDecision: (+ actionId: string,+ toolCallId: string,+ decision: Agents.ToolApprovalResolution | null,+ ) => void;+ /** Current decision a card holds, if any (drives selected-state styling). */+ getDecision: (actionId: string, toolCallId: string) => Agents.ToolApprovalResolution | undefined;+ /** Every recorded decision for an action, in registration order (the submit batch). */+ getDecisions: (actionId: string) => Agents.ToolApprovalResolution[];+ /** Declare that a tool_call belongs to an action so submit can require all. */+ registerToolCall: (actionId: string, toolCallId: string) => void;+ /** Drop a tool_call's registration when its card unmounts, so a resolved/removed+ * card can't keep `isReady` false and wedge the batch submit. */+ unregisterToolCall: (actionId: string, toolCallId: string) => void;+ /** The first-registered tool_call for an action — the single card that owns+ * the batch submit button (avoids N buttons across sibling cards). */+ getLeadToolCallId: (actionId: string) => string | undefined;+ /** Number of tool calls paused under an action (for a "1 of N" label). */+ getRegisteredCount: (actionId: string) => number;+ /** True once every registered tool_call in the action has a decision. */+ isReady: (actionId: string) => boolean;+ /** Lifecycle status for an action (so cards can disable / show messages). */+ getStatus: (actionId: string) => ActionStatus;+ /** Set an action's submission status (driven by the cards' submit via `useResumeSubmit`). */+ setStatus: (actionId: string, status: ActionStatus) => void;+}++const ApprovalContext = createContext<ApprovalContextValue | null>(null);++/** Cards call this; outside a provider it degrades to inert no-ops so a tool+ * call without an active approval never crashes. */+export const useApprovalContext = (): ApprovalContextValue => {+ const ctx = useContext(ApprovalContext);+ return ctx ?? FALLBACK;+};++const FALLBACK: ApprovalContextValue = {+ setDecision: () => undefined,+ getDecision: () => undefined,+ getDecisions: () => [],+ registerToolCall: () => undefined,+ unregisterToolCall: () => undefined,+ getLeadToolCallId: () => undefined,+ getRegisteredCount: () => 0,+ isReady: () => false,+ getStatus: () => 'idle',+ setStatus: () => undefined,+};++const isExpiredError = (error: unknown): boolean => {+ const status = (error as { response?: { status?: number } } | undefined)?.response?.status;+ return status === 409;+};++/**+ * Coordinates human-in-the-loop decisions for a single response message.+ *+ * An action may pause multiple tool calls (same `actionId`); each `ToolApproval`+ * card registers its `tool_call_id` and records a decision here, and the lead card+ * submits ONCE with the full `decisions[]` covering every paused call (the server+ * rejects a partial batch).+ *+ * Intentionally PURE state — it does NOT read `ChatContext`, the agent store, or+ * React Query. Message content renders in places without those providers (shared /+ * exported views, tests), so the provider must be safe to mount anywhere. The+ * context-dependent submit lives in {@link useResumeSubmit}, which the cards call —+ * and the cards only render inside a live chat view where those providers exist.+ */+export default function ApprovalProvider({ children }: { children: React.ReactNode }) {+ /** actionId → (tool_call_id → resolution). Mutable ref + a version bump so+ * reads are synchronous for `isReady`/submit while renders stay cheap. */+ const decisionsRef = useRef(new Map<string, Map<string, Agents.ToolApprovalResolution>>());+ const registeredRef = useRef(new Map<string, Set<string>>());+ const [, bump] = useState(0);+ const rerender = useCallback(() => bump((v) => v + 1), []);+ const [statusByAction, setStatusByAction] = useState<Record<string, ActionStatus>>({});++ const registerToolCall = useCallback(+ (actionId: string, toolCallId: string) => {+ const set = registeredRef.current.get(actionId) ?? new Set<string>();+ if (set.has(toolCallId)) {+ return;+ }+ set.add(toolCallId);+ registeredRef.current.set(actionId, set);+ /** A newly-registered call shifts the lead / "of N" count for sibling+ * cards — re-render so they reflect it. */+ rerender();+ },+ [rerender],+ );++ const unregisterToolCall = useCallback(+ (actionId: string, toolCallId: string) => {+ const set = registeredRef.current.get(actionId);+ if (!set || !set.has(toolCallId)) {+ return;+ }+ set.delete(toolCallId);+ // Also drop any decision it held so a stale entry can't linger.+ decisionsRef.current.get(actionId)?.delete(toolCallId);+ if (set.size === 0) {+ registeredRef.current.delete(actionId);+ decisionsRef.current.delete(actionId);+ }+ rerender();+ },+ [rerender],+ );++ const getLeadToolCallId = useCallback(+ (actionId: string) => registeredRef.current.get(actionId)?.values().next().value,+ [],+ );++ const getRegisteredCount = useCallback(+ (actionId: string) => registeredRef.current.get(actionId)?.size ?? 0,+ [],+ );++ const setDecision = useCallback(+ (actionId: string, toolCallId: string, decision: Agents.ToolApprovalResolution | null) => {+ const map = decisionsRef.current.get(actionId) ?? new Map();+ if (decision == null) {+ map.delete(toolCallId);+ } else {+ map.set(toolCallId, decision);+ }+ decisionsRef.current.set(actionId, map);+ rerender();+ },+ [rerender],+ );++ const getDecision = useCallback(+ (actionId: string, toolCallId: string) => decisionsRef.current.get(actionId)?.get(toolCallId),+ [],+ );++ const getDecisions = useCallback(+ (actionId: string) => Array.from(decisionsRef.current.get(actionId)?.values() ?? []),+ [],+ );++ const isReady = useCallback((actionId: string) => {+ const registered = registeredRef.current.get(actionId);+ const decided = decisionsRef.current.get(actionId);+ if (!registered || registered.size === 0) {+ return false;+ }+ for (const toolCallId of registered) {+ if (!decided?.has(toolCallId)) {+ return false;+ }+ }+ return true;+ }, []);++ const getStatus = useCallback(+ (actionId: string): ActionStatus => statusByAction[actionId] ?? 'idle',+ [statusByAction],+ );++ const setStatus = useCallback((actionId: string, status: ActionStatus) => {+ setStatusByAction((prev) => ({ ...prev, [actionId]: status }));+ }, []);++ const value = useMemo<ApprovalContextValue>(+ () => ({+ setDecision,+ getDecision,+ getDecisions,+ registerToolCall,+ unregisterToolCall,+ getLeadToolCallId,+ getRegisteredCount,+ isReady,+ getStatus,+ setStatus,+ }),+ [+ setDecision,+ getDecision,+ getDecisions,+ registerToolCall,+ unregisterToolCall,+ getLeadToolCallId,+ getRegisteredCount,+ isReady,+ getStatus,+ setStatus,+ ],+ );++ return <ApprovalContext.Provider value={value}>{children}</ApprovalContext.Provider>;+}++/**+ * Submit hook for the approval cards. Sources the resume body's agent/endpoint+ * fields from the active conversation (so the route's shared `buildEndpointOption`+ * middleware reconstructs the same agent) and fires the resume mutation, threading+ * the result back into the action's status.+ *+ * Reads `ChatContext` / the agent store / React Query. The cards render it from+ * live chat views but ALSO from contexts without a `ChatContext.Provider` (e.g. a+ * subagent tool paused inside a portaled dialog, or a search/citation render that+ * passes chat context as a prop), so it reads the context non-throwingly: with no+ * conversation, `buildResumeFields` returns null and the controls are inert rather+ * than crashing.+ */+export function useResumeSubmit() {+ const conversation = useContext(ChatContext)?.conversation;+ const getEphemeralAgent = useGetEphemeralAgent();+ const approvalMutation = useSubmitToolApprovalMutation();+ const askMutation = useSubmitAskAnswerMutation();+ const { getDecisions, isReady, setStatus } = useApprovalContext();++ const buildResumeFields = useCallback((): ResumeAgentFields | null => {+ const conversationId = conversation?.conversationId;+ if (!conversationId || conversationId === Constants.NEW_CONVO) {+ return null;+ }+ return {+ conversationId,+ endpoint: conversation?.endpoint,+ endpointType: conversation?.endpointType,+ agent_id: conversation?.agent_id,+ model: conversation?.model,+ spec: conversation?.spec,+ // Ephemeral agents derive their instructions from promptPrefix — re-send it so+ // the resumed run rebuilds the same graph and matches the server fingerprint.+ promptPrefix: conversation?.promptPrefix,+ ephemeralAgent: getEphemeralAgent(conversationId),+ };+ }, [conversation, getEphemeralAgent]);++ const submitToolApproval = useCallback(+ (actionId: string) => {+ const fields = buildResumeFields();+ const decisions = getDecisions(actionId);+ if (!fields || decisions.length === 0 || !isReady(actionId)) {+ return;+ }+ setStatus(actionId, 'submitting');+ approvalMutation.mutate(+ { ...fields, actionId, decisions },+ {+ onSuccess: () => setStatus(actionId, 'submitted'),+ onError: (error) => setStatus(actionId, isExpiredError(error) ? 'expired' : 'error'),+ },+ );+ },+ [approvalMutation, buildResumeFields, getDecisions, isReady, setStatus],+ );++ const submitAskAnswer = useCallback(+ (actionId: string, answer: string) => {+ const fields = buildResumeFields();+ if (!fields || answer.length === 0) {+ return;+ }+ setStatus(actionId, 'submitting');+ askMutation.mutate(+ { ...fields, actionId, answer },+ {+ onSuccess: () => setStatus(actionId, 'submitted'),+ onError: (error) => setStatus(actionId, isExpiredError(error) ? 'expired' : 'error'),+ },+ );+ },+ [askMutation, buildResumeFields, setStatus],+ );++ return { submitToolApproval, submitAskAnswer };+}diff --git a/client/src/components/Chat/Messages/Content/AskUserQuestion.tsx b/client/src/components/Chat/Messages/Content/AskUserQuestion.tsxnew file mode 100644index 0000000000..55f85b26af--- /dev/null+++ b/client/src/components/Chat/Messages/Content/AskUserQuestion.tsx@@ -0,0 +1,93 @@+import { useState } from 'react';+import { TriangleAlert } from 'lucide-react';+import { Button, TextareaAutosize } from '@librechat/client';+import type { Agents } from 'librechat-data-provider';+import { useApprovalContext, useResumeSubmit } from './ApprovalContext';+import { useLocalize } from '~/hooks';++/**+ * Renders an `ask_user_question` pause: the prompt, optional description, any+ * curated option buttons, and a free-form text answer. Each path submits the+ * answer through {@link useApprovalContext} to resume the paused run; the+ * continuation arrives on the existing SSE.+ */+export default function AskUserQuestion({+ actionId,+ question,+}: {+ actionId: string;+ question: Agents.AskUserQuestionRequest;+}) {+ const localize = useLocalize();+ const { getStatus } = useApprovalContext();+ const { submitAskAnswer } = useResumeSubmit();+ const [answer, setAnswer] = useState('');++ const status = getStatus(actionId);+ const locked = status === 'submitting' || status === 'submitted' || status === 'expired';++ if (status === 'submitted') {+ return null;+ }++ const trimmed = answer.trim();++ return (+ <div className="my-2 flex w-full flex-col gap-2 rounded-lg border border-border-light bg-surface-secondary p-3">+ <p className="text-sm font-medium text-text-primary">{question.question}</p>+ {question.description != null && question.description.length > 0 && (+ <p className="text-sm text-text-secondary">{question.description}</p>+ )}++ {question.options != null && question.options.length > 0 && (+ <div className="flex flex-wrap gap-2">+ {question.options.map((option) => (+ <Button+ key={option.value}+ size="sm"+ variant="outline"+ disabled={locked}+ onClick={() => submitAskAnswer(actionId, option.value)}+ >+ {option.label}+ </Button>+ ))}+ </div>+ )}++ <TextareaAutosize+ value={answer}+ disabled={locked}+ onChange={(e) => setAnswer(e.target.value)}+ minRows={2}+ maxRows={12}+ placeholder={localize('com_ui_your_answer')}+ className="w-full resize-none rounded-md border border-border-light bg-surface-primary p-2 text-sm"+ aria-label={localize('com_ui_your_answer')}+ />++ <div className="flex items-center gap-3">+ <Button+ size="sm"+ variant="submit"+ disabled={trimmed.length === 0 || locked}+ onClick={() => submitAskAnswer(actionId, trimmed)}+ >+ {status === 'submitting' ? localize('com_ui_submitting') : localize('com_ui_submit')}+ </Button>+ {status === 'expired' && (+ <span className="flex items-center text-xs text-text-warning">+ <TriangleAlert className="mr-1.5 h-4 w-4" aria-hidden="true" />+ {localize('com_ui_approval_expired')}+ </span>+ )}+ {status === 'error' && (+ <span className="flex items-center text-xs text-text-warning">+ <TriangleAlert className="mr-1.5 h-4 w-4" aria-hidden="true" />+ {localize('com_ui_approval_error')}+ </span>+ )}+ </div>+ </div>+ );+}diff --git a/client/src/components/Chat/Messages/Content/ContentParts.tsx b/client/src/components/Chat/Messages/Content/ContentParts.tsxindex 00569c11f5..148c8a3e2d 100644--- a/client/src/components/Chat/Messages/Content/ContentParts.tsx+++ b/client/src/components/Chat/Messages/Content/ContentParts.tsx@@ -12,6 +12,7 @@ import { mapAttachments, groupSequentialToolCalls } from '~/utils';import { MessageContext, SearchContext } from '~/Providers';import PendingSkillCall from './Parts/PendingSkillCall';import { EditTextPart, EmptyText } from './Parts';+import ApprovalProvider from './ApprovalContext';import MemoryArtifacts from './MemoryArtifacts';import ToolCallGroup from './ToolCallGroup';import Container from './Container';@@ -373,7 +374,7 @@ const ContentParts = memo(function ContentParts({const hasParallelContent = safeContent.some((part) => part?.groupId != null);if (hasParallelContent) {return (- <>+ <ApprovalProvider>{renderPendingSkills()}<ParallelContentRenderercontent={content}@@ -385,41 +386,43 @@ const ContentParts = memo(function ContentParts({isSubmitting={effectiveIsSubmitting}renderPart={renderPart}/>- </>+ </ApprovalProvider>);}// Sequential content: render parts in order (90% of cases)return (- <SearchContext.Provider value={{ searchResults }}>- <MemoryArtifacts attachments={attachments} />- {renderPendingSkills()}- {showEmptyCursor && (- <Container>- <EmptyText />- </Container>- )}- {groupedParts.map((group) => {- if (group.type === 'single') {- const { part, idx } = group.part;- return renderPart(part, idx, idx === lastContentIdx);- }- const { groupId } = group;- return (- <ToolCallGroup- key={`tool-group-${groupId}`}- parts={group.parts}- isSubmitting={effectiveIsSubmitting}- isLast={group.parts.some((p) => p.idx === lastContentIdx)}- renderPart={renderGroupedPart}- lastContentIdx={lastContentIdx}- groupAttachments={group.groupAttachments}- initialExpansionState={toolGroupExpansionRef.current.get(groupId)}- onExpansionChange={(state) => handleGroupExpansionChange(groupId, state)}- />- );- })}- </SearchContext.Provider>+ <ApprovalProvider>+ <SearchContext.Provider value={{ searchResults }}>+ <MemoryArtifacts attachments={attachments} />+ {renderPendingSkills()}+ {showEmptyCursor && (+ <Container>+ <EmptyText />+ </Container>+ )}+ {groupedParts.map((group) => {+ if (group.type === 'single') {+ const { part, idx } = group.part;+ return renderPart(part, idx, idx === lastContentIdx);+ }+ const { groupId } = group;+ return (+ <ToolCallGroup+ key={`tool-group-${groupId}`}+ parts={group.parts}+ isSubmitting={effectiveIsSubmitting}+ isLast={group.parts.some((p) => p.idx === lastContentIdx)}+ renderPart={renderGroupedPart}+ lastContentIdx={lastContentIdx}+ groupAttachments={group.groupAttachments}+ initialExpansionState={toolGroupExpansionRef.current.get(groupId)}+ onExpansionChange={(state) => handleGroupExpansionChange(groupId, state)}+ />+ );+ })}+ </SearchContext.Provider>+ </ApprovalProvider>);});diff --git a/client/src/components/Chat/Messages/Content/Part.tsx b/client/src/components/Chat/Messages/Content/Part.tsxindex 6df833370a..6998cdbe5f 100644--- a/client/src/components/Chat/Messages/Content/Part.tsx+++ b/client/src/components/Chat/Messages/Content/Part.tsx@@ -22,16 +22,19 @@ import {BashCall,SubagentCall,} from './Parts';+import { getAskUserQuestionPart } from '~/utils/approval';+import { isBashProgrammaticToolCall } from './routing';import { ErrorMessage } from './MessageContent';+import AskUserQuestion from './AskUserQuestion';import RetrievalCall from './RetrievalCall';import { getCachedPreview } from '~/utils';+import ToolApproval from './ToolApproval';import AgentHandoff from './AgentHandoff';import CodeAnalyze from './CodeAnalyze';import Container from './Container';import WebSearch from './WebSearch';import ToolCall from './ToolCall';import Image from './Image';-import { isBashProgrammaticToolCall } from './routing';type PartProps = {part?: TMessageContentParts;@@ -58,6 +61,16 @@ const Part = memo(function Part({return null;}+ const askUserQuestion = getAskUserQuestionPart(part);+ if (askUserQuestion) {+ return (+ <AskUserQuestion+ actionId={askUserQuestion.ask_user_question.actionId}+ question={askUserQuestion.ask_user_question.question}+ />+ );+ }+if (part.type === ContentTypes.ERROR) {return (<ErrorMessage@@ -136,164 +149,183 @@ const Part = memo(function Part({const isToolCall ='args' in toolCall && (!toolCall.type || toolCall.type === ToolCallTypes.TOOL_CALL);- if (isToolCall && isBashProgrammaticToolCall(toolCall.name, toolCall.args)) {- return (- <BashCall- args={toolCall.args}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- commandField="code"- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );- } else if (- isToolCall &&- (toolCall.name === Tools.execute_code ||- toolCall.name === Constants.PROGRAMMATIC_TOOL_CALLING ||- toolCall.name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING)- ) {- return (- <ExecuteCode- attachments={attachments}- isSubmitting={isSubmitting}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- args={toolCall.args}- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );- } else if (- isToolCall &&- (toolCall.name === 'image_gen_oai' ||- toolCall.name === 'image_edit_oai' ||- toolCall.name === 'gemini_image_gen')- ) {- return (- <ImageGen- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- toolName={toolCall.name}- args={typeof toolCall.args === 'string' ? toolCall.args : ''}- output={toolCall.output ?? ''}- attachments={attachments}- hideAttachments={hideAttachments}- />- );- } else if (isToolCall && toolCall.name === 'skill') {- return (- <SkillCall- args={toolCall.args}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );- } else if (isToolCall && toolCall.name === Constants.SUBAGENT) {- /** `subagent_content` is the aggregated content-parts array the- * backend writes onto the tool_call at message-save time so the- * child's activity survives a page refresh. Not present on older- * runs recorded before the persistence path existed — those fall- * back to the Recoil atom (live session) or the raw tool output- * inside `SubagentCall`. */- const persistedContent = (- toolCall as unknown as {- subagent_content?: TMessageContentParts[];+ if (isToolCall) {+ const card = (() => {+ if (isBashProgrammaticToolCall(toolCall.name, toolCall.args)) {+ return (+ <BashCall+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ commandField="code"+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ } else if (+ toolCall.name === Tools.execute_code ||+ toolCall.name === Constants.PROGRAMMATIC_TOOL_CALLING ||+ toolCall.name === Constants.BASH_PROGRAMMATIC_TOOL_CALLING+ ) {+ return (+ <ExecuteCode+ attachments={attachments}+ isSubmitting={isSubmitting}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ args={toolCall.args}+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ } else if (+ toolCall.name === 'image_gen_oai' ||+ toolCall.name === 'image_edit_oai' ||+ toolCall.name === 'gemini_image_gen'+ ) {+ return (+ <ImageGen+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ toolName={toolCall.name}+ args={typeof toolCall.args === 'string' ? toolCall.args : ''}+ output={toolCall.output ?? ''}+ attachments={attachments}+ hideAttachments={hideAttachments}+ />+ );+ } else if (toolCall.name === 'skill') {+ return (+ <SkillCall+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ } else if (toolCall.name === Constants.SUBAGENT) {+ /** `subagent_content` is the aggregated content-parts array the+ * backend writes onto the tool_call at message-save time so the+ * child's activity survives a page refresh. Not present on older+ * runs recorded before the persistence path existed — those fall+ * back to the Recoil atom (live session) or the raw tool output+ * inside `SubagentCall`. */+ const persistedContent = (+ toolCall as unknown as {+ subagent_content?: TMessageContentParts[];+ }+ ).subagent_content;+ return (+ <SubagentCall+ toolCallId={toolCall.id ?? ''}+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ persistedContent={persistedContent}+ hideAttachments={hideAttachments}+ />+ );+ } else if (toolCall.name === 'read_file') {+ return (+ <ReadFileCall+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ } else if (toolCall.name === 'create_file' || toolCall.name === 'edit_file') {+ return (+ <FileAuthoringCall+ toolName={toolCall.name}+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ } else if (toolCall.name === Tools.bash_tool) {+ return (+ <BashCall+ args={toolCall.args}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ } else if (toolCall.name === Tools.web_search) {+ return (+ <WebSearch+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ isLast={isLast}+ onExpand={onToolExpand}+ />+ );+ } else if (toolCall.name === 'file_search' || toolCall.name === 'retrieval') {+ return (+ <RetrievalCall+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ output={toolCall.output ?? undefined}+ attachments={attachments}+ onExpand={onToolExpand}+ />+ );+ } else if (toolCall.name?.startsWith(Constants.LC_TRANSFER_TO_)) {+ return <AgentHandoff args={toolCall.args ?? ''} name={toolCall.name || ''} />;}- ).subagent_content;- return (- <SubagentCall- toolCallId={toolCall.id ?? ''}- args={toolCall.args}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- persistedContent={persistedContent}- hideAttachments={hideAttachments}- />- );- } else if (isToolCall && toolCall.name === 'read_file') {- return (- <ReadFileCall- args={toolCall.args}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );- } else if (isToolCall && (toolCall.name === 'create_file' || toolCall.name === 'edit_file')) {- return (- <FileAuthoringCall- toolName={toolCall.name}- args={toolCall.args}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );- } else if (isToolCall && toolCall.name === Tools.bash_tool) {- return (- <BashCall- args={toolCall.args}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );- } else if (isToolCall && toolCall.name === Tools.web_search) {- return (- <WebSearch- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- isLast={isLast}- onExpand={onToolExpand}- />- );- } else if (isToolCall && (toolCall.name === 'file_search' || toolCall.name === 'retrieval')) {- return (- <RetrievalCall- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- output={toolCall.output ?? undefined}- attachments={attachments}- onExpand={onToolExpand}- />- );- } else if (isToolCall && toolCall.name?.startsWith(Constants.LC_TRANSFER_TO_)) {- return <AgentHandoff args={toolCall.args ?? ''} name={toolCall.name || ''} />;- } else if (isToolCall) {- return (- <ToolCall- args={toolCall.args ?? ''}- name={toolCall.name || ''}- output={toolCall.output ?? ''}- initialProgress={toolCall.progress ?? 0.1}- isSubmitting={isSubmitting}- attachments={attachments}- auth={toolCall.auth}- isLast={isLast}- hideAttachments={hideAttachments}- onExpand={onToolExpand}- />- );+ return (+ <ToolCall+ args={toolCall.args ?? ''}+ name={toolCall.name || ''}+ output={toolCall.output ?? ''}+ initialProgress={toolCall.progress ?? 0.1}+ isSubmitting={isSubmitting}+ attachments={attachments}+ auth={toolCall.auth}+ isLast={isLast}+ hideAttachments={hideAttachments}+ onExpand={onToolExpand}+ />+ );+ })();++ /** Render approval controls for ANY paused agent tool — not just the generic+ * card — so a HITL policy that gates a specialized tool (bash, code, file…)+ * still surfaces approve/reject/edit/respond. Only while the call is unresolved+ * (no output yet). */+ if (toolCall.approval != null && (toolCall.output?.length ?? 0) === 0) {+ return (+ <>+ {card}+ <ToolApproval+ approval={toolCall.approval}+ toolCallId={toolCall.id ?? ''}+ args={toolCall.args}+ />+ </>+ );+ }+ return card;} else if (toolCall.type === ToolCallTypes.CODE_INTERPRETER) {const code_interpreter = toolCall[ToolCallTypes.CODE_INTERPRETER];return (diff --git a/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsx b/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsxindex 23f5537e24..69060ca939 100644--- a/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsx+++ b/client/src/components/Chat/Messages/Content/Parts/SubagentCall.tsx@@ -3,19 +3,18 @@ import { useRecoilValue } from 'recoil';import { ContentTypes, EModelEndpoint } from 'librechat-data-provider';import { ArrowDown, ChevronRight, Maximize2, Minimize2, Users } from 'lucide-react';import { OGDialog, OGDialogContent, OGDialogTitle, OGDialogDescription } from '@librechat/client';--import type { TAttachment, TMessage, TMessageContentParts } from 'librechat-data-provider';+import type { Agents, TAttachment, TMessage, TMessageContentParts } from 'librechat-data-provider';import type { PartWithIndex } from '~/components/Chat/Messages/Content/ParallelContent';import type { SubagentTickerLine } from '~/utils/subagentContent';-import ToolCallGroup from '~/components/Chat/Messages/Content/ToolCallGroup';import MarkdownLite from '~/components/Chat/Messages/Content/MarkdownLite';+import ToolApproval from '~/components/Chat/Messages/Content/ToolApproval';import { cn, groupSequentialToolCalls, parseToolName } from '~/utils';import Container from '~/components/Chat/Messages/Content/Container';import ToolCall from '~/components/Chat/Messages/Content/ToolCall';import { MessageContext } from '~/Providers/MessageContext';-import { subagentProgressByToolCallId } from '~/store';import MessageIcon from '~/components/Share/MessageIcon';+import { subagentProgressByToolCallId } from '~/store';import { useAgentsMapContext } from '~/Providers';import { AttachmentGroup } from './Attachment';import { useLocalize } from '~/hooks';@@ -841,15 +840,17 @@ function SubagentDialogPart({const tc = (part as {[ContentTypes.TOOL_CALL]?: {+ id?: string;args?: string | Record<string, unknown>;output?: string;name?: string;progress?: number;+ approval?: Agents.ToolCall['approval'];};})[ContentTypes.TOOL_CALL];if (!tc) return null;- return (+ const toolCall = (<ToolCallargs={tc.args ?? ''}output={tc.output ?? ''}@@ -860,6 +861,19 @@ function SubagentDialogPart({onExpand={onToolExpand}/>);+ // Surface approve/reject/edit controls for a tool paused INSIDE this subagent —+ // its tool_call lives in subagent_content, not as a top-level message part, so the+ // top-level Part.tsx render never sees it. Only while unresolved (no output yet).+ // The dialog portals but React context still flows, so ToolApproval resolves here.+ if (tc.approval != null && (tc.output?.length ?? 0) === 0) {+ return (+ <>+ {toolCall}+ <ToolApproval approval={tc.approval} toolCallId={tc.id ?? ''} args={tc.args} />+ </>+ );+ }+ return toolCall;}return null;}diff --git a/client/src/components/Chat/Messages/Content/ToolApproval.tsx b/client/src/components/Chat/Messages/Content/ToolApproval.tsxnew file mode 100644index 0000000000..1068eadd1e--- /dev/null+++ b/client/src/components/Chat/Messages/Content/ToolApproval.tsx@@ -0,0 +1,273 @@+import { useEffect, useMemo, useState } from 'react';+import { Button, TextareaAutosize } from '@librechat/client';+import { Check, X, Pencil, MessageSquare, TriangleAlert } from 'lucide-react';+import type { Agents } from 'librechat-data-provider';+import type { TranslationKeys } from '~/hooks';+import { useApprovalContext, useResumeSubmit } from './ApprovalContext';+import { useLocalize } from '~/hooks';+import { cn, logger } from '~/utils';++/**+ * The resume route rejects an `edit` whose `editedArguments` isn't a plain object+ * (`findIncompleteDecisions`), so mirror that here — `JSON.parse` alone also accepts+ * `null`/arrays/primitives, which would enable Submit for a value that can only 400.+ */+function isPlainObject(value: unknown): value is Record<string, unknown> {+ return typeof value === 'object' && value !== null && !Array.isArray(value);+}++type DecisionType = Agents.ToolApprovalDecisionType;++const DECISION_ICON: Record<DecisionType, React.ComponentType<{ className?: string }>> = {+ approve: Check,+ reject: X,+ edit: Pencil,+ respond: MessageSquare,+};++const DECISION_LABEL: Record<DecisionType, TranslationKeys> = {+ approve: 'com_ui_approve',+ reject: 'com_ui_reject',+ edit: 'com_ui_edit',+ respond: 'com_ui_respond',+};++/** Pretty-print tool args as JSON for the `edit` textarea seed. */+function seedArgs(args: string | Record<string, unknown> | undefined): string {+ if (args == null) {+ return '{}';+ }+ if (typeof args === 'string') {+ try {+ return JSON.stringify(JSON.parse(args), null, 2);+ } catch {+ return args;+ }+ }+ try {+ return JSON.stringify(args, null, 2);+ } catch (e) {+ logger.error('ToolApproval - failed to stringify args', e);+ return '{}';+ }+}++/**+ * Renders approve / reject / edit / respond controls for a paused tool call,+ * scoped to the decisions the server allows. Records its decision in the+ * batch {@link useApprovalContext}; the lead card additionally renders the+ * single submit button covering every paused call in the action.+ */+export default function ToolApproval({+ approval,+ toolCallId,+ args,+}: {+ approval: NonNullable<Agents.ToolCall['approval']>;+ toolCallId: string;+ args: string | Record<string, unknown> | undefined;+}) {+ const localize = useLocalize();+ const { actionId, allowed_decisions: allowedDecisions, description } = approval;+ const {+ registerToolCall,+ unregisterToolCall,+ setDecision,+ isReady,+ getStatus,+ getLeadToolCallId,+ getRegisteredCount,+ } = useApprovalContext();+ const { submitToolApproval } = useResumeSubmit();++ const [active, setActive] = useState<DecisionType | null>(null);+ const [editText, setEditText] = useState(() => seedArgs(args));+ const [responseText, setResponseText] = useState('');+ const [reason, setReason] = useState('');++ useEffect(() => {+ registerToolCall(actionId, toolCallId);+ // Drop the registration when this card unmounts (e.g. the tool resolved and the+ // card was replaced) so a stale entry can't keep the batch's `isReady` false.+ return () => unregisterToolCall(actionId, toolCallId);+ }, [registerToolCall, unregisterToolCall, actionId, toolCallId]);++ const status = getStatus(actionId);+ const locked = status === 'submitting' || status === 'submitted' || status === 'expired';++ /** Recompute and store this card's decision whenever inputs change. A null+ * resolution (e.g. invalid edit JSON) clears it so submit stays disabled. */+ useEffect(() => {+ if (locked) {+ return;+ }+ if (active == null) {+ setDecision(actionId, toolCallId, null);+ return;+ }+ if (active === 'approve') {+ setDecision(actionId, toolCallId, { tool_call_id: toolCallId, decision: 'approve' });+ return;+ }+ if (active === 'reject') {+ setDecision(actionId, toolCallId, {+ tool_call_id: toolCallId,+ decision: 'reject',+ reason: reason.trim() || undefined,+ });+ return;+ }+ if (active === 'respond') {+ const trimmed = responseText.trim();+ setDecision(+ actionId,+ toolCallId,+ trimmed.length > 0+ ? { tool_call_id: toolCallId, decision: 'respond', responseText: trimmed }+ : null,+ );+ return;+ }+ if (active === 'edit') {+ try {+ const parsed = JSON.parse(editText) as unknown;+ setDecision(+ actionId,+ toolCallId,+ isPlainObject(parsed)+ ? { tool_call_id: toolCallId, decision: 'edit', editedArguments: parsed }+ : null,+ );+ } catch {+ setDecision(actionId, toolCallId, null);+ }+ }+ }, [active, editText, responseText, reason, locked, setDecision, actionId, toolCallId]);++ const editIsValid = useMemo(() => {+ if (active !== 'edit') {+ return true;+ }+ try {+ return isPlainObject(JSON.parse(editText));+ } catch {+ return false;+ }+ }, [active, editText]);++ const isLead = getLeadToolCallId(actionId) === toolCallId;+ const count = getRegisteredCount(actionId);+ const ready = isReady(actionId);++ const submitLabel = useMemo(() => {+ if (status === 'submitting') {+ return localize('com_ui_submitting');+ }+ if (count > 1) {+ return localize('com_ui_submit_decisions', { 0: count });+ }+ return localize('com_ui_submit');+ }, [status, count, localize]);++ if (status === 'submitted') {+ return null;+ }++ return (+ <div className="my-2 flex w-full flex-col gap-2 rounded-lg border border-border-light bg-surface-secondary p-3">+ {description != null && description.length > 0 && (+ <p className="text-sm text-text-secondary">{description}</p>+ )}+ <div className="flex flex-wrap gap-2">+ {allowedDecisions.map((decision) => {+ const Icon = DECISION_ICON[decision];+ return (+ <Button+ key={decision}+ size="sm"+ variant={active === decision ? 'default' : 'outline'}+ disabled={locked}+ aria-pressed={active === decision}+ onClick={() => setActive((prev) => (prev === decision ? null : decision))}+ className="inline-flex items-center gap-1.5"+ >+ <Icon className="h-4 w-4" aria-hidden="true" />+ {localize(DECISION_LABEL[decision])}+ </Button>+ );+ })}+ </div>++ {active === 'edit' && (+ <div className="flex flex-col gap-1">+ <TextareaAutosize+ value={editText}+ disabled={locked}+ onChange={(e) => setEditText(e.target.value)}+ minRows={3}+ maxRows={16}+ className={cn(+ 'w-full resize-none rounded-md border bg-surface-primary p-2 font-mono text-xs',+ editIsValid ? 'border-border-light' : 'border-red-500',+ )}+ aria-label={localize('com_ui_edit')}+ />+ {!editIsValid && (+ <span className="text-xs text-text-warning">{localize('com_ui_invalid_json')}</span>+ )}+ </div>+ )}++ {active === 'respond' && (+ <TextareaAutosize+ value={responseText}+ disabled={locked}+ onChange={(e) => setResponseText(e.target.value)}+ minRows={2}+ maxRows={12}+ placeholder={localize('com_ui_tool_response_placeholder')}+ className="w-full resize-none rounded-md border border-border-light bg-surface-primary p-2 text-sm"+ aria-label={localize('com_ui_respond')}+ />+ )}++ {active === 'reject' && (+ <TextareaAutosize+ value={reason}+ disabled={locked}+ onChange={(e) => setReason(e.target.value)}+ minRows={1}+ maxRows={6}+ placeholder={localize('com_ui_reject_reason_placeholder')}+ className="w-full resize-none rounded-md border border-border-light bg-surface-primary p-2 text-sm"+ aria-label={localize('com_ui_reject')}+ />+ )}++ {isLead && (+ <div className="mt-1 flex items-center gap-3">+ <Button+ size="sm"+ variant="submit"+ disabled={!ready || locked}+ onClick={() => submitToolApproval(actionId)}+ >+ {submitLabel}+ </Button>+ {status === 'expired' && (+ <span className="flex items-center text-xs text-text-warning">+ <TriangleAlert className="mr-1.5 h-4 w-4" aria-hidden="true" />+ {localize('com_ui_approval_expired')}+ </span>+ )}+ {status === 'error' && (+ <span className="flex items-center text-xs text-text-warning">+ <TriangleAlert className="mr-1.5 h-4 w-4" aria-hidden="true" />+ {localize('com_ui_approval_error')}+ </span>+ )}+ </div>+ )}+ </div>+ );+}diff --git a/client/src/data-provider/SSE/mutations.ts b/client/src/data-provider/SSE/mutations.tsindex 0861babbe9..2d95bb377b 100644--- a/client/src/data-provider/SSE/mutations.ts+++ b/client/src/data-provider/SSE/mutations.ts@@ -1,5 +1,6 @@import { useMutation } from '@tanstack/react-query';-import { apiBaseUrl, request } from 'librechat-data-provider';+import { apiBaseUrl, request, EModelEndpoint } from 'librechat-data-provider';+import type { Agents, TEphemeralAgent } from 'librechat-data-provider';export interface AbortStreamParams {/** The stream ID to abort (if known) */@@ -40,3 +41,102 @@ export function useAbortStreamMutation() {mutationFn: abortStream,});}++/**+ * Agent/endpoint selection fields the resume route needs so its shared+ * `buildEndpointOption` middleware can reconstruct the same agent that paused.+ * Mirrors the fields a normal `POST /api/agents/chat` message carries; sourced+ * from the active conversation (and the conversation's ephemeral-agent state).+ */+export interface ResumeAgentFields {+ conversationId: string;+ endpoint?: EModelEndpoint | string | null;+ endpointType?: EModelEndpoint | string | null;+ agent_id?: string | null;+ model?: string | null;+ spec?: string | null;+ /** Ephemeral agents derive instructions from this; re-sent so resume rebuilds the+ * same graph (and matches the server's request fingerprint). */+ promptPrefix?: string | null;+ ephemeralAgent?: TEphemeralAgent | null;+ isTemporary?: boolean;+}++/** Successful resume ACK. The continuation streams over the existing SSE. */+export interface ResumeResponse {+ streamId: string;+ conversationId: string;+ status: 'resuming';+}++/**+ * Shared base for both resume payloads: the agent selection fields, plus the+ * `endpoint` defaulted to `agents` (the resume route lives under the agents+ * router and `buildEndpointOption` keys off it).+ */+const buildResumeBase = (fields: ResumeAgentFields) => ({+ ...fields,+ endpoint: fields.endpoint ?? EModelEndpoint.agents,+});++export interface SubmitToolApprovalParams extends ResumeAgentFields {+ /** Identifies the paused action; the server 409s a stale/mismatched id. */+ actionId: string;+ /** One entry per paused tool_call_id — the server 400s a partial batch. */+ decisions: Agents.ToolApprovalResolution[];+}++/**+ * Submit a batch of tool-approval decisions to resume a paused generation.+ * POSTs to the shared resume route; the continuation streams over the existing+ * SSE connection (this only fires the POST — it does not open a new stream).+ */+export const submitToolApproval = async (+ params: SubmitToolApprovalParams,+): Promise<ResumeResponse> => {+ const { actionId, decisions, ...fields } = params;+ return request.post(`${apiBaseUrl()}/api/agents/chat/resume`, {+ ...buildResumeBase(fields),+ actionId,+ decisions,+ }) as Promise<ResumeResponse>;+};++/**+ * React Query mutation hook for submitting tool-approval decisions.+ * Mirrors {@link useAbortStreamMutation}; the resumed stream arrives on the SSE.+ */+export function useSubmitToolApprovalMutation() {+ return useMutation({+ mutationFn: submitToolApproval,+ });+}++export interface SubmitAskAnswerParams extends ResumeAgentFields {+ actionId: string;+ /** Free-form answer to the agent's ask-user question. */+ answer: string;+}++/**+ * Submit an ask-user-question answer to resume a paused generation.+ * POSTs to the shared resume route; the continuation streams over the existing SSE.+ */+export const submitAskAnswer = async (params: SubmitAskAnswerParams): Promise<ResumeResponse> => {+ const { actionId, answer, ...fields } = params;+ return request.post(`${apiBaseUrl()}/api/agents/chat/resume`, {+ ...buildResumeBase(fields),+ actionId,+ answer,+ }) as Promise<ResumeResponse>;+};++/**+ * React Query mutation hook for submitting an ask-user answer.+ * Mirrors {@link useAbortStreamMutation}; the resumed stream arrives on the SSE.+ */+export function useSubmitAskAnswerMutation() {+ return useMutation({+ mutationFn: submitAskAnswer,+ });+}diff --git a/client/src/data-provider/SSE/queries.ts b/client/src/data-provider/SSE/queries.tsindex 8cd116394b..3f9830712f 100644--- a/client/src/data-provider/SSE/queries.ts+++ b/client/src/data-provider/SSE/queries.ts@@ -1,6 +1,6 @@import { useEffect, useMemo, useState } from 'react';-import { apiBaseUrl, QueryKeys, request, dataService } from 'librechat-data-provider';import { useQuery, useQueries, useQueryClient } from '@tanstack/react-query';+import { apiBaseUrl, QueryKeys, request, dataService } from 'librechat-data-provider';import type { Agents, TConversation } from 'librechat-data-provider';import { isNotFoundError, updateConvoInAllQueries } from '~/utils';import { useGetStartupConfig } from '../Endpoints';@@ -8,10 +8,13 @@ import { useGetStartupConfig } from '../Endpoints';export interface StreamStatusResponse {active: boolean;streamId?: string;- status?: 'running' | 'complete' | 'error' | 'aborted';+ status?: 'running' | 'complete' | 'error' | 'aborted' | 'requires_action';aggregatedContent?: Array<{ type: string; text?: string }>;createdAt?: number;resumeState?: Agents.ResumeState;+ /** Live pending approval when `status === 'requires_action'`; mirrors+ * `resumeState.pendingAction`, surfaced top-level for the resume-on-load path. */+ pendingAction?: Agents.PendingAction;}export const streamStatusQueryKey = (conversationId: string) => ['streamStatus', conversationId];diff --git a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsxindex fdb6d79c9f..03a5a9b3d1 100644--- a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx+++ b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx@@ -261,6 +261,62 @@ describe('useResumeOnLoad', () => {);});+ it('strips the paused user/assistant rows from submission.messages (no duplicate on resume)', async () => {+ const observedSubmissions: Array<TSubmission | null> = [];+ mockUseStreamStatus.mockReturnValue({+ isSuccess: true,+ isFetching: false,+ data: {+ active: true,+ status: 'running',+ streamId: CONVERSATION_ID,+ resumeState: {+ runSteps: [],+ aggregatedContent: [{ type: 'text', text: 'Streaming...' }],+ responseMessageId: RESPONSE_MESSAGE_ID,+ conversationId: CONVERSATION_ID,+ sender: 'Agent',+ userMessage: {+ messageId: USER_MESSAGE_ID,+ parentMessageId: Constants.NO_PARENT,+ conversationId: CONVERSATION_ID,+ text: 'Hello',+ },+ },+ },+ });++ renderUseResumeOnLoad({+ // The reloaded DB array already holds the paused user row + the partial+ // (unfinished) assistant row under the same ids the resume re-supplies.+ messages: [+ buildUserMessage(CONVERSATION_ID),+ {+ messageId: RESPONSE_MESSAGE_ID,+ parentMessageId: USER_MESSAGE_ID,+ conversationId: CONVERSATION_ID,+ text: '',+ isCreatedByUser: false,+ unfinished: true,+ } as TMessage,+ ],+ onSubmission: (currentSubmission) => observedSubmissions.push(currentSubmission),+ });++ await act(async () => {+ await Promise.resolve();+ });++ const submission = observedSubmissions[observedSubmissions.length - 1];+ const ids = (submission?.messages ?? []).map((m) => m.messageId);+ // Stripped from the flat array (re-supplied via the placeholders + final event)...+ expect(ids).not.toContain(USER_MESSAGE_ID);+ expect(ids).not.toContain(RESPONSE_MESSAGE_ID);+ // ...but still carried on the placeholders for re-insertion.+ expect(submission?.userMessage?.messageId).toBe(USER_MESSAGE_ID);+ expect(submission?.initialResponse?.messageId).toBe(RESPONSE_MESSAGE_ID);+ });+it('restores the branch that owns a pending OAuth resume user message', async () => {const rootUser = buildUserMessage(CONVERSATION_ID, 'root-user');const branchOneResponse = {diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.tsindex 501f8a73c5..e898a261f8 100644--- a/client/src/hooks/SSE/useResumableSSE.ts+++ b/client/src/hooks/SSE/useResumableSSE.ts@@ -12,6 +12,7 @@ import {apiBaseUrl,UsageEvents,createPayload,+ ApprovalEvents,ViolationTypes,removeNullishValues,} from 'librechat-data-provider';@@ -29,10 +30,13 @@ import type { TResData } from '~/common';import {logger,clearAllDrafts,+ applyPendingAction,removeConvoFromAllQueries,upsertConvoInAllQueries,+ countTaggedApprovalParts,countTrailingOutputChars,markStreamStartFailedMetadata,+ findPendingActionMessageIndex,} from '~/utils';import {useGetUserBalance,@@ -449,6 +453,9 @@ export default function useResumableSSE(const submissionRef = useRef<TSubmission | null>(null);const optimisticStreamIdsRef = useRef(new Set<string>());const createdStreamIdsRef = useRef(new Set<string>());+ /** Pending action whose tool-call content part hasn't rendered yet — retried+ * on the next frame so a fast pause-before-render race still attaches. */+ const pendingActionRetryRef = useRef<number | null>(null);const {stepHandler,@@ -509,6 +516,60 @@ export default function useResumableSSE(}};+ /**+ * Maps a pending action onto the in-flight response message so the+ * approval / ask-user UI renders. Syncs the result back into the step+ * handler's map so subsequent deltas build on the approval-tagged content+ * rather than clobbering it.+ *+ * If the mapping is a no-op (the paused tool-call content part hasn't+ * rendered yet — a pause-before-render race), retry on subsequent frames+ * so the approval still attaches. `ask_user_question` always applies (it+ * appends a synthetic part), so only `tool_approval` ever retries.+ */+ // Keep retrying across frames (not just once): Recoil/React message updates from+ // the preceding created/step events are async and can take several frames under+ // load, so a single retry would drop a valid pause and leave the run with no+ // approval controls. Bounded so a genuinely-absent target can't spin forever.+ const PENDING_ACTION_MAX_RETRY_FRAMES = 120;+ const applyPendingActionToMessages = (pendingAction: Agents.PendingAction, attempt = 0) => {+ const retryNextFrame = () => {+ if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {+ pendingActionRetryRef.current = requestAnimationFrame(() =>+ applyPendingActionToMessages(pendingAction, attempt + 1),+ );+ }+ };+ const messages = getMessages() ?? [];+ const index = findPendingActionMessageIndex(messages, pendingAction);+ if (index < 0) {+ retryNextFrame();+ return;+ }+ const updated = applyPendingAction(messages[index], pendingAction);+ const changed = updated !== messages[index];+ if (changed) {+ const nextMessages = [...messages];+ nextMessages[index] = updated;+ setMessages(nextMessages);+ syncStepMessage(updated);+ }+ // A `tool_approval` pause can carry several `action_requests` whose tool-call+ // parts render on different frames; tagging only the first to arrive would leave+ // late siblings with no approval card, and the resume route then 400s the partial+ // batch ("every paused tool call must be decided"). Keep retrying (bounded) until+ // EVERY paused call is tagged. `ask_user_question` applies its single synthetic+ // part in one shot, so it only needs the original "did anything change" retry.+ if (pendingAction.payload.type === 'tool_approval') {+ const expected = pendingAction.payload.action_requests.length;+ if (countTaggedApprovalParts(updated, pendingAction.actionId) < expected) {+ retryNextFrame();+ }+ } else if (!changed) {+ retryNextFrame();+ }+ };+const baseUrl = `${apiBaseUrl()}/api/agents/chat/stream/${encodeURIComponent(currentStreamId)}`;const url = isResume ? `${baseUrl}?resume=true` : baseUrl;logger.log('ResumableSSE', 'Subscribing to stream:', url, { isResume });@@ -614,6 +675,12 @@ export default function useResumableSSE(return;}+ if (data.event === ApprovalEvents.ON_PENDING_ACTION) {+ applyPendingActionToMessages(data.data as Agents.PendingAction);+ setIsSubmitting(true);+ return;+ }+if (data.event != null) {if (data.event === StepEvents.ON_MESSAGE_DELTA ||@@ -749,6 +816,15 @@ export default function useResumableSSE(}}+ /**+ * Re-pause on reconnect: the run is parked on a human-review+ * interrupt. Re-apply the pending action so the approval / ask-user+ * controls render after a reload or dropped connection.+ */+ if (data.resumeState?.pendingAction) {+ applyPendingActionToMessages(data.resumeState.pendingAction as Agents.PendingAction);+ }+if (data.resumeState?.titleEvent) {titleHandler(data.resumeState.titleEvent);}@@ -763,6 +839,10 @@ export default function useResumableSSE(contextHandler(replayEvent.data, resumeSubmission);} else if (replayEvent.event === UsageEvents.ON_TOKEN_USAGE) {usageHandler(replayEvent.data, resumeSubmission);+ } else if (replayEvent.event === ApprovalEvents.ON_PENDING_ACTION) {+ // A pause that landed after the resume snapshot must still render its+ // controls (mirror the live handler), not fall through to stepHandler.+ applyPendingActionToMessages(replayEvent.data as Agents.PendingAction);} else if (replayEvent.event != null) {if (replayEvent.event === StepEvents.ON_MESSAGE_DELTA ||@@ -784,6 +864,12 @@ export default function useResumableSSE(contextHandler(pendingEvent.data, resumeSubmission);} else if (pendingEvent.event === UsageEvents.ON_TOKEN_USAGE) {usageHandler(pendingEvent.data, resumeSubmission);+ } else if (pendingEvent.event === ApprovalEvents.ON_PENDING_ACTION) {+ // In-memory mode can surface a pause that landed between getResumeState()+ // and the subscription here; route it to the same handler as a live event+ // so the approval / ask-user controls render (else the stream sits paused+ // with no UI until a full status reload).+ applyPendingActionToMessages(pendingEvent.data as Agents.PendingAction);} else if (pendingEvent.event != null) {if (pendingEvent.event === StepEvents.ON_MESSAGE_DELTA ||@@ -1289,6 +1375,10 @@ export default function useResumableSSE(clearTimeout(reconnectTimeoutRef.current);reconnectTimeoutRef.current = null;}+ if (pendingActionRetryRef.current != null) {+ cancelAnimationFrame(pendingActionRetryRef.current);+ pendingActionRetryRef.current = null;+ }// Reset reconnect counter before closing (so abort handler doesn't think we're reconnecting)reconnectAttemptRef.current = 0;if (sseRef.current) {diff --git a/client/src/hooks/SSE/useResumeOnLoad.ts b/client/src/hooks/SSE/useResumeOnLoad.tsindex 97c1bc91c0..abd7f748cf 100644--- a/client/src/hooks/SSE/useResumeOnLoad.ts+++ b/client/src/hooks/SSE/useResumeOnLoad.ts@@ -3,7 +3,7 @@ import { useSetRecoilState, useRecoilValue, useRecoilCallback } from 'recoil';import { Constants, tMessageSchema, isAssistantsEndpoint } from 'librechat-data-provider';import type { TMessage, TConversation, TSubmission, Agents } from 'librechat-data-provider';import type { StreamStatusResponse } from '~/data-provider';-import { getBranchSiblingIndexesForTarget } from '~/utils';+import { getBranchSiblingIndexesForTarget, applyPendingAction } from '~/utils';import { useStreamStatus } from '~/data-provider';import store from '~/store';@@ -130,7 +130,7 @@ function buildSubmissionFromResumeState(// ALWAYS use aggregatedContent from resumeState - it has the latest content from the running job.// DB content may be stale (saved at disconnect, but generation continued).- const initialResponse: TMessage = {+ let initialResponse: TMessage = {messageId: existingResponseMessage?.messageId ?? responseMessageId,parentMessageId: existingResponseMessage?.parentMessageId ?? userMessage.messageId,conversationId,@@ -144,14 +144,33 @@ function buildSubmissionFromResumeState(iconURL: preferDefinedString(existingResponseMessage?.iconURL, resumeState.iconURL),} as TMessage;+ // Re-paused turn: seed the approval / ask-user controls straight onto the+ // placeholder so they render on load without waiting for the SSE sync replay.+ if (resumeState.pendingAction) {+ initialResponse = applyPendingAction(initialResponse, resumeState.pendingAction);+ }+const conversation: TConversation = {conversationId,title: 'Resumed Chat',endpoint: null,} as TConversation;+ // On reload, `messages` is the full DB array, which already holds the paused user+ // row and the partial (unfinished) assistant row under the same ids that+ // `userMessage` / `initialResponse` (and the resume final event's request/response+ // messages) re-supply. Strip them so createdHandler/finalHandler — which build+ // `[...messages, requestMessage, responseMessage]` — don't append a duplicate pair.+ const pausedResponseIdUnpadded = initialResponse.messageId.replace(/_+$/, '');+ const dedupedMessages = messages.filter(+ (m) =>+ m.messageId !== userMessage.messageId &&+ m.messageId !== initialResponse.messageId &&+ m.messageId !== pausedResponseIdUnpadded,+ );+return {- messages,+ messages: dedupedMessages,userMessage,initialResponse,conversation,diff --git a/client/src/hooks/SSE/useSSE.ts b/client/src/hooks/SSE/useSSE.tsindex 8f18f1d556..f1f17eaee1 100644--- a/client/src/hooks/SSE/useSSE.ts+++ b/client/src/hooks/SSE/useSSE.ts@@ -7,16 +7,23 @@ import {UsageEvents,StepEvents,createPayload,+ ApprovalEvents,removeNullishValues,} from 'librechat-data-provider';-import type { TMessage, TPayload, TSubmission, EventSubmission } from 'librechat-data-provider';+import type {+ Agents,+ TMessage,+ TPayload,+ TSubmission,+ EventSubmission,+} from 'librechat-data-provider';import type { EventHandlerParams } from './useEventHandlers';import type { TResData } from '~/common';+import { clearAllDrafts, applyPendingAction, findPendingActionMessageIndex } from '~/utils';import { useGetStartupConfig, useGetUserBalance } from '~/data-provider';import { useAuthContext } from '~/hooks/AuthContext';import useEventHandlers from './useEventHandlers';import useUsageHandler from './useUsageHandler';-import { clearAllDrafts } from '~/utils';import store from '~/store';type ChatHelpers = Pick<@@ -137,6 +144,18 @@ export default function useSSE(contextHandler(data.data, { ...submission, userMessage });} else if (data.event === UsageEvents.ON_TOKEN_USAGE) {usageHandler(data.data, { ...submission, userMessage });+ } else if (data.event === ApprovalEvents.ON_PENDING_ACTION) {+ const pendingAction = data.data as Agents.PendingAction;+ const messages = getMessages() ?? [];+ const index = findPendingActionMessageIndex(messages, pendingAction);+ if (index >= 0) {+ const updated = applyPendingAction(messages[index], pendingAction);+ if (updated !== messages[index]) {+ const nextMessages = [...messages];+ nextMessages[index] = updated;+ setMessages(nextMessages);+ }+ }} else if (data.event != null) {if (data.event === StepEvents.ON_MESSAGE_DELTA ||diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex e7af1f886a..1c32ffa291 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -829,6 +829,9 @@"com_ui_api_keys_empty_text": "API keys let external applications run your agents through the OpenAI-compatible API. Create a key to get started.","com_ui_api_keys_empty_title": "Connect your agents to external apps","com_ui_api_keys_load_error": "Failed to load API keys",+ "com_ui_approval_error": "Something went wrong submitting your decision. Please try again.",+ "com_ui_approval_expired": "This request expired or was already handled.",+ "com_ui_approve": "Approve","com_ui_archive": "Archive","com_ui_archive_delete_error": "Failed to delete archived conversation","com_ui_archive_error": "Failed to archive conversation",@@ -1228,6 +1231,7 @@"com_ui_initializing": "Initializing...","com_ui_input": "Input","com_ui_instructions": "Instructions",+ "com_ui_invalid_json": "Invalid JSON","com_ui_invocation_auto": "Auto","com_ui_invocation_auto_info": "The skill is automatically applied by the agent when relevant to the conversation","com_ui_invocation_both": "Both",@@ -1505,6 +1509,8 @@"com_ui_regenerating": "Regenerating...","com_ui_region": "Region","com_ui_reinitialize": "Reinitialize",+ "com_ui_reject": "Reject",+ "com_ui_reject_reason_placeholder": "Optional: reason for rejecting (shared with the agent)","com_ui_relevance": "Relevance","com_ui_remote_access": "Remote Access","com_ui_remote_agent_role_editor": "Editor",@@ -1534,6 +1540,7 @@"com_ui_reset_var": "Reset {{0}}","com_ui_reset_zoom": "Reset Zoom","com_ui_resource": "resource",+ "com_ui_respond": "Respond","com_ui_response": "Response","com_ui_result": "Result","com_ui_result_found": "{{count}} result found",@@ -1794,6 +1801,8 @@"com_ui_subagent_ticker_writing": "Writing","com_ui_subagent_waiting": "Waiting for first update…","com_ui_submit": "Submit",+ "com_ui_submit_decisions": "Submit {{0}} decisions",+ "com_ui_submitting": "Submitting…","com_ui_summarized": "Summarized","com_ui_summarizing": "Summarizing...","com_ui_support_contact": "Support Contact",@@ -1825,6 +1834,7 @@"com_ui_tool_name_image_edit": "Image Edit","com_ui_tool_name_image_gen": "Image Generation","com_ui_tool_name_web_search": "Web Search",+ "com_ui_tool_response_placeholder": "Type a substitute result to return to the agent","com_ui_tools": "Tools","com_ui_tools_and_actions": "Tools and Actions","com_ui_transferred_to": "Transferred to",@@ -1927,6 +1937,7 @@"com_ui_xhigh": "Extra High","com_ui_yes": "Yes","com_ui_you": "You",+ "com_ui_your_answer": "Type your answer…","com_ui_your_api_key": "Your API Key","com_ui_your_projects": "Your projects","com_ui_zoom": "Zoom",diff --git a/client/src/utils/approval.spec.ts b/client/src/utils/approval.spec.tsnew file mode 100644index 0000000000..49265a9995--- /dev/null+++ b/client/src/utils/approval.spec.ts@@ -0,0 +1,299 @@+import { ContentTypes } from 'librechat-data-provider';+import type { Agents, TMessage, TMessageContentParts } from 'librechat-data-provider';+import {+ ASK_USER_QUESTION,+ applyPendingAction,+ countTaggedApprovalParts,+ getAskUserQuestionPart,+ findPendingActionMessageIndex,+} from './approval';++const toolCallPart = (id: string, extra: Record<string, unknown> = {}): TMessageContentParts =>+ ({+ type: ContentTypes.TOOL_CALL,+ [ContentTypes.TOOL_CALL]: { id, name: 'search', args: '{}', ...extra },+ }) as unknown as TMessageContentParts;++const textPart = (text: string): TMessageContentParts =>+ ({ type: ContentTypes.TEXT, text }) as unknown as TMessageContentParts;++const msg = (over: Partial<TMessage> = {}): TMessage =>+ ({ messageId: 'm1', isCreatedByUser: false, content: [], ...over }) as unknown as TMessage;++const toolApprovalAction = (over: Record<string, unknown> = {}): Agents.PendingAction =>+ ({+ actionId: 'a1',+ streamId: 's1',+ createdAt: 0,+ payload: {+ type: 'tool_approval',+ action_requests: [+ { name: 'search', arguments: '{}', tool_call_id: 'tc1', description: 'Run search' },+ ],+ review_configs: [+ { action_name: 'search', tool_call_id: 'tc1', allowed_decisions: ['approve', 'reject'] },+ ],+ },+ ...over,+ }) as unknown as Agents.PendingAction;++const askAction = (over: Record<string, unknown> = {}): Agents.PendingAction =>+ ({+ actionId: 'a1',+ streamId: 's1',+ createdAt: 0,+ payload: { type: 'ask_user_question', question: { question: 'What name?' } },+ ...over,+ }) as unknown as Agents.PendingAction;++const getToolCall = (part: TMessageContentParts | undefined) =>+ (part as unknown as { tool_call?: Agents.ToolCall & { approval?: unknown } })?.tool_call;++describe('applyPendingAction — tool_approval', () => {+ it('joins by tool_call_id (not position) and sets approval from the matching request + review', () => {+ // tc1 is the SECOND part — a by-position join would mis-target the first.+ const message = msg({ content: [toolCallPart('tcX'), toolCallPart('tc1')] });+ const result = applyPendingAction(message, toolApprovalAction());++ expect(result).not.toBe(message); // new reference: something changed+ expect(getToolCall(result.content?.[0] as TMessageContentParts)?.approval).toBeUndefined();+ expect(getToolCall(result.content?.[1] as TMessageContentParts)?.approval).toEqual({+ actionId: 'a1',+ allowed_decisions: ['approve', 'reject'],+ description: 'Run search',+ });+ });++ it('leaves a completed tool call (with output) untouched and returns the same message reference', () => {+ const message = msg({ content: [toolCallPart('tc1', { output: 'already ran' })] });+ const result = applyPendingAction(message, toolApprovalAction());+ expect(result).toBe(message);+ });++ it('defaults allowed_decisions to [] when no review config matches the tool call', () => {+ const action = toolApprovalAction({+ payload: {+ type: 'tool_approval',+ action_requests: [{ name: 'search', arguments: '{}', tool_call_id: 'tc1' }],+ review_configs: [], // no config for tc1+ },+ });+ const message = msg({ content: [toolCallPart('tc1')] });+ const result = applyPendingAction(message, action);+ expect(getToolCall(result.content?.[0] as TMessageContentParts)?.approval).toMatchObject({+ allowed_decisions: [],+ });+ });++ it('returns the same message when content is empty or not an array', () => {+ const empty = msg({ content: [] });+ expect(applyPendingAction(empty, toolApprovalAction())).toBe(empty);+ const nonArray = msg({ content: undefined as unknown as TMessageContentParts[] });+ expect(applyPendingAction(nonArray, toolApprovalAction())).toBe(nonArray);+ });++ it('returns the same message when no tool call matches the pending request', () => {+ const message = msg({ content: [toolCallPart('other')] });+ expect(applyPendingAction(message, toolApprovalAction())).toBe(message);+ });+});++describe('countTaggedApprovalParts', () => {+ const twoToolAction = () =>+ toolApprovalAction({+ payload: {+ type: 'tool_approval',+ action_requests: [+ { name: 'search', arguments: '{}', tool_call_id: 'tc1' },+ { name: 'search', arguments: '{}', tool_call_id: 'tc2' },+ ],+ review_configs: [],+ },+ });++ it('counts tagged parts so a partial multi-tool apply is detectable (1 of 2)', () => {+ const action = twoToolAction();+ // Only tc1 has rendered when the action is first applied → 1 < 2, retry should continue.+ const partial = applyPendingAction(msg({ content: [toolCallPart('tc1')] }), action);+ expect(countTaggedApprovalParts(partial, 'a1')).toBe(1);+ // Both siblings present → both tagged → retry can stop.+ const full = applyPendingAction(+ msg({ content: [toolCallPart('tc1'), toolCallPart('tc2')] }),+ action,+ );+ expect(countTaggedApprovalParts(full, 'a1')).toBe(2);+ });++ it('returns 0 when nothing is tagged or content is not an array', () => {+ expect(countTaggedApprovalParts(msg({ content: [toolCallPart('tc1')] }), 'a1')).toBe(0);+ expect(countTaggedApprovalParts(msg({ content: [textPart('hi')] }), 'a1')).toBe(0);+ expect(+ countTaggedApprovalParts(+ msg({ content: undefined as unknown as TMessageContentParts[] }),+ 'a1',+ ),+ ).toBe(0);+ });++ it('ignores parts tagged with a different actionId', () => {+ const tagged = applyPendingAction(+ msg({ content: [toolCallPart('tc1')] }),+ toolApprovalAction(),+ );+ expect(countTaggedApprovalParts(tagged, 'a1')).toBe(1);+ expect(countTaggedApprovalParts(tagged, 'other-action')).toBe(0);+ });+});++describe('applyPendingAction — subagent-nested tool calls', () => {+ const subagentMsg = (childId: string): TMessage =>+ msg({+ content: [+ {+ type: ContentTypes.TOOL_CALL,+ [ContentTypes.TOOL_CALL]: {+ id: 'sub1',+ name: 'subagent',+ args: '{}',+ subagent_content: [toolCallPart(childId)],+ },+ } as unknown as TMessageContentParts,+ ],+ });++ const childAction = () =>+ toolApprovalAction({+ payload: {+ type: 'tool_approval',+ action_requests: [{ name: 'search', arguments: '{}', tool_call_id: 'child-tc1' }],+ review_configs: [+ {+ action_name: 'search',+ tool_call_id: 'child-tc1',+ allowed_decisions: ['approve', 'reject'],+ },+ ],+ },+ });++ it('tags a tool paused inside a subagent and makes it countable', () => {+ const message = subagentMsg('child-tc1');+ const result = applyPendingAction(message, childAction());+ expect(result).not.toBe(message); // new reference++ const parentToolCall = getToolCall(result.content?.[0] as TMessageContentParts) as+ | { subagent_content?: TMessageContentParts[] }+ | undefined;+ const nested = parentToolCall?.subagent_content?.[0];+ expect(getToolCall(nested)?.approval).toMatchObject({ actionId: 'a1' });+ // The retry loop's "all tagged" check is now reachable for the nested call.+ expect(countTaggedApprovalParts(result, 'a1')).toBe(1);+ });++ it('returns the same message when no nested tool call matches', () => {+ const message = subagentMsg('child-other');+ expect(applyPendingAction(message, childAction())).toBe(message);+ expect(countTaggedApprovalParts(message, 'a1')).toBe(0);+ });+});++describe('applyPendingAction — ask_user_question', () => {+ it('appends a synthetic ask-user-question part carrying the actionId and question', () => {+ const message = msg({ content: [textPart('hello')] });+ const result = applyPendingAction(message, askAction());+ expect(result.content).toHaveLength(2);+ const part = getAskUserQuestionPart(result.content?.[1] as TMessageContentParts);+ expect(part?.[ASK_USER_QUESTION]).toMatchObject({+ actionId: 'a1',+ question: { question: 'What name?' },+ });+ });++ it('is idempotent on replay: the same actionId replaces in place rather than stacking', () => {+ const once = applyPendingAction(msg({ content: [] }), askAction());+ const twice = applyPendingAction(once, askAction());+ expect(twice.content).toHaveLength(1); // not duplicated++ const other = applyPendingAction(twice, askAction({ actionId: 'a2' }));+ expect(other.content).toHaveLength(2); // a different action does append+ });++ it('coerces non-array content to a single-part array', () => {+ const message = msg({ content: undefined as unknown as TMessageContentParts[] });+ const result = applyPendingAction(message, askAction());+ expect(result.content).toHaveLength(1);+ });+});++describe('applyPendingAction — unsupported type', () => {+ it('returns the original message unchanged', () => {+ const message = msg({ content: [textPart('hi')] });+ const action = {+ actionId: 'a1',+ payload: { type: 'mystery' },+ } as unknown as Agents.PendingAction;+ expect(applyPendingAction(message, action)).toBe(message);+ });+});++describe('getAskUserQuestionPart', () => {+ it('returns the typed part for an ask-user-question synthetic part', () => {+ const appended = applyPendingAction(msg({ content: [] }), askAction());+ const part = getAskUserQuestionPart(appended.content?.[0] as TMessageContentParts);+ expect(part?.type).toBe(ASK_USER_QUESTION);+ expect(part?.[ASK_USER_QUESTION].actionId).toBe('a1');+ });++ it('returns undefined for a non-ask part, undefined, or a wrong type', () => {+ expect(getAskUserQuestionPart(toolCallPart('tc1'))).toBeUndefined();+ expect(getAskUserQuestionPart(undefined)).toBeUndefined();+ expect(getAskUserQuestionPart(textPart('x'))).toBeUndefined();+ });+});++describe('findPendingActionMessageIndex', () => {+ const assistant = (messageId: string) => msg({ messageId, isCreatedByUser: false });+ const user = (messageId: string) => msg({ messageId, isCreatedByUser: true });++ it('returns the index of the assistant message matching responseMessageId exactly', () => {+ const messages = [user('u1'), assistant('r1'), assistant('r2')];+ const idx = findPendingActionMessageIndex(+ messages,+ toolApprovalAction({ responseMessageId: 'r1' }),+ );+ expect(idx).toBe(1);+ });++ it('returns -1 (retry) when a provided responseMessageId matches only a user message', () => {+ // `<userMsg>_` style ids could collide with the user bubble — never resolve to it;+ // -1 makes the caller retry on the next frame once the assistant placeholder renders.+ const messages = [user('shared'), assistant('r-last')];+ const idx = findPendingActionMessageIndex(+ messages,+ toolApprovalAction({ responseMessageId: 'shared' }),+ );+ expect(idx).toBe(-1);+ });++ it('returns -1 (retry) when a provided responseMessageId is not found at all', () => {+ // Provided-but-absent means the in-flight assistant placeholder is not in the list+ // yet — defer rather than attach the prompt/approval to a prior reply.+ const messages = [assistant('r1'), user('u1'), assistant('r2')];+ const idx = findPendingActionMessageIndex(+ messages,+ toolApprovalAction({ responseMessageId: 'missing' }),+ );+ expect(idx).toBe(-1);+ });++ it('falls back to the last assistant message only when no responseMessageId is provided', () => {+ const messages = [assistant('r1'), user('u1'), assistant('r2')];+ const idx = findPendingActionMessageIndex(messages, toolApprovalAction());+ expect(idx).toBe(2);+ });++ it('returns -1 for an empty list or when no assistant message exists', () => {+ expect(findPendingActionMessageIndex([], toolApprovalAction())).toBe(-1);+ expect(findPendingActionMessageIndex([user('u1')], toolApprovalAction())).toBe(-1);+ });+});diff --git a/client/src/utils/approval.ts b/client/src/utils/approval.tsnew file mode 100644index 0000000000..6fdf29b8d9--- /dev/null+++ b/client/src/utils/approval.ts@@ -0,0 +1,273 @@+import { ContentTypes } from 'librechat-data-provider';+import type { Agents, TMessage, TMessageContentParts } from 'librechat-data-provider';++/**+ * UI-only content-part type used to render an `ask_user_question` pause inline+ * with the assistant's other content parts. It rides on the standard `content`+ * array (which `Agents.MessageContentComplex` allows for arbitrary `type`+ * strings), so it survives SSE, sync, and DB rehydration without a new wire+ * type or an extra field on `TMessage`.+ */+export const ASK_USER_QUESTION = 'ask_user_question' as const;++/** Shape of the synthetic content part carrying an ask-user pending action. */+export interface AskUserQuestionPart {+ type: typeof ASK_USER_QUESTION;+ [ASK_USER_QUESTION]: {+ actionId: string;+ question: Agents.AskUserQuestionRequest;+ };+}++/**+ * The synthetic type isn't in the `ContentTypes` union, so this reads the+ * `type` field through a cast rather than a type-predicate (which TS rejects+ * because `AskUserQuestionPart` isn't assignable to the strict+ * `TMessageContentParts` union).+ */+const isAskUserQuestionPart = (part: TMessageContentParts | undefined): boolean =>+ (part as { type?: string } | undefined)?.type === ASK_USER_QUESTION &&+ part != null &&+ ASK_USER_QUESTION in part;++const getToolCallId = (part: TMessageContentParts | undefined): string =>+ (part?.[ContentTypes.TOOL_CALL] as Agents.ToolCall | undefined)?.id ?? '';++/** A tool-call value that may carry approval state and/or nested subagent content. */+type ToolCallWithApproval = Agents.ToolCall & {+ approval?: unknown;+ subagent_content?: TMessageContentParts[];+};++/**+ * Tags one tool-call part with the pending action's approval when it matches an+ * `action_request` (joined by `tool_call_id`, NOT position) and is still unresolved.+ *+ * Recurses into a subagent's `subagent_content`: a tool paused INSIDE a subagent+ * lives there, not as a top-level part, so without this the approval never attaches+ * and the user gets no controls. Returns a NEW part only when something changed.+ */+function tagApprovalOnPart(+ part: TMessageContentParts,+ actionId: string,+ requestByToolCallId: Map<string, Agents.ToolApprovalRequest>,+ reviewByToolCallId: Map<string, Agents.ToolReviewConfig>,+): { part: TMessageContentParts; changed: boolean } {+ if (part?.type !== ContentTypes.TOOL_CALL) {+ return { part, changed: false };+ }+ const toolCall = part[ContentTypes.TOOL_CALL] as ToolCallWithApproval | undefined;+ if (!toolCall) {+ return { part, changed: false };+ }++ let nextToolCall = toolCall;+ let changed = false;++ // Descend into nested subagent tool calls first.+ if (Array.isArray(toolCall.subagent_content) && toolCall.subagent_content.length > 0) {+ let nestedChanged = false;+ const nextNested = toolCall.subagent_content.map((nestedPart) => {+ const res = tagApprovalOnPart(nestedPart, actionId, requestByToolCallId, reviewByToolCallId);+ if (res.changed) {+ nestedChanged = true;+ }+ return res.part;+ });+ if (nestedChanged) {+ nextToolCall = { ...nextToolCall, subagent_content: nextNested };+ changed = true;+ }+ }++ // Tag this call itself when it's one of the paused requests and still unresolved+ // (an `output` means the pause already resolved — leave it alone).+ const toolCallId = getToolCallId(part);+ const request = toolCallId ? requestByToolCallId.get(toolCallId) : undefined;+ if (request && (nextToolCall.output?.length ?? 0) === 0) {+ const reviewConfig = reviewByToolCallId.get(toolCallId);+ nextToolCall = {+ ...nextToolCall,+ approval: {+ actionId,+ allowed_decisions: reviewConfig?.allowed_decisions ?? [],+ description: request.description,+ },+ };+ changed = true;+ }++ if (!changed) {+ return { part, changed: false };+ }+ return {+ part: { ...part, [ContentTypes.TOOL_CALL]: nextToolCall } as TMessageContentParts,+ changed: true,+ };+}++/**+ * Maps a tool-approval pending action onto a message's tool-call content parts,+ * including tool calls nested inside subagents (see {@link tagApprovalOnPart}).+ *+ * Returns a NEW message only when something changed (referential stability lets+ * React bail out of needless re-renders); otherwise the original is returned.+ */+function applyToolApproval(+ message: TMessage,+ actionId: string,+ payload: Agents.ToolApprovalInterruptPayload,+): TMessage {+ const content = message.content;+ if (!Array.isArray(content) || content.length === 0) {+ return message;+ }++ const reviewByToolCallId = new Map<string, Agents.ToolReviewConfig>();+ for (const config of payload.review_configs) {+ reviewByToolCallId.set(config.tool_call_id, config);+ }+ const requestByToolCallId = new Map<string, Agents.ToolApprovalRequest>();+ for (const requestItem of payload.action_requests) {+ requestByToolCallId.set(requestItem.tool_call_id, requestItem);+ }++ let changed = false;+ const nextContent = content.map((part) => {+ const res = tagApprovalOnPart(part, actionId, requestByToolCallId, reviewByToolCallId);+ if (res.changed) {+ changed = true;+ }+ return res.part;+ });++ if (!changed) {+ return message;+ }+ return { ...message, content: nextContent };+}++/**+ * Appends (or refreshes) an ask-user-question content part for the pending+ * action. Idempotent: replaces an existing part with the same `actionId` rather+ * than stacking duplicates on reconnect/replay.+ */+function applyAskUserQuestion(+ message: TMessage,+ actionId: string,+ payload: Agents.AskUserQuestionInterruptPayload,+): TMessage {+ const content = Array.isArray(message.content) ? message.content : [];+ const askPart = {+ type: ASK_USER_QUESTION,+ [ASK_USER_QUESTION]: { actionId, question: payload.question },+ } as unknown as TMessageContentParts;++ const existingIdx = content.findIndex(+ (part) =>+ isAskUserQuestionPart(part) &&+ (part as unknown as AskUserQuestionPart)[ASK_USER_QUESTION].actionId === actionId,+ );+ if (existingIdx >= 0) {+ const nextContent = [...content];+ nextContent[existingIdx] = askPart;+ return { ...message, content: nextContent };+ }+ return { ...message, content: [...content, askPart] };+}++/**+ * Applies a {@link Agents.PendingAction} onto the target response message,+ * dispatching on the interrupt type. Pure — returns a new message only when the+ * mapping actually changed something.+ */+export function applyPendingAction(+ message: TMessage,+ pendingAction: Agents.PendingAction,+): TMessage {+ const { payload, actionId } = pendingAction;+ if (payload.type === 'tool_approval') {+ return applyToolApproval(message, actionId, payload);+ }+ if (payload.type === 'ask_user_question') {+ return applyAskUserQuestion(message, actionId, payload);+ }+ return message;+}++/**+ * Counts the tool-call content parts already tagged with this action's approval —+ * i.e. how many of a tool-approval pending action's `action_requests` have rendered+ * and been mapped. A multi-tool pause can render its sibling cards across several+ * frames, so the SSE retry compares this against `action_requests.length` to know+ * whether EVERY paused call is tagged yet.+ */+export function countTaggedApprovalParts(message: TMessage, actionId: string): number {+ const content = message.content;+ if (!Array.isArray(content)) {+ return 0;+ }+ const countIn = (parts: TMessageContentParts[]): number => {+ let count = 0;+ for (const part of parts) {+ if (part?.type !== ContentTypes.TOOL_CALL) {+ continue;+ }+ const toolCall = part[ContentTypes.TOOL_CALL] as ToolCallWithApproval | undefined;+ if ((toolCall?.approval as { actionId?: string } | undefined)?.actionId === actionId) {+ count += 1;+ }+ // Nested subagent tool calls count too, so the retry loop's "all tagged" check+ // is reachable for a tool paused inside a subagent.+ if (Array.isArray(toolCall?.subagent_content)) {+ count += countIn(toolCall.subagent_content);+ }+ }+ return count;+ };+ return countIn(content);+}++/** Returns the ask-user-question synthetic part when `part` is one, else undefined. */+export function getAskUserQuestionPart(+ part: TMessageContentParts | undefined,+): AskUserQuestionPart | undefined {+ return isAskUserQuestionPart(part) ? (part as unknown as AskUserQuestionPart) : undefined;+}++/**+ * Resolves the assistant response message a pending action targets within+ * `messages`. Returns the index, or -1 when the assistant placeholder isn't present+ * yet (the caller retries on the next frame).+ *+ * Only ever matches an ASSISTANT message. The `responseMessageId` for a fresh turn+ * is the user message id with a trailing underscore (`<userMsg>_`), so a naive+ * underscore-strip would resolve to the just-created USER message before the+ * assistant placeholder exists — appending the prompt to the wrong bubble and never+ * triggering the retry. Matching strictly on assistant messages avoids that.+ */+export function findPendingActionMessageIndex(+ messages: TMessage[],+ pendingAction: Agents.PendingAction,+): number {+ const isAssistant = (message: TMessage | undefined) => message?.isCreatedByUser === false;+ const { responseMessageId } = pendingAction;+ if (responseMessageId) {+ // When the id is provided, ONLY an exact assistant match counts. A miss means the+ // assistant placeholder for this turn hasn't been inserted yet — return -1 so the+ // caller retries on the next frame. Falling back to the last assistant here would+ // attach the prompt/approval to a PRIOR reply (applyAskUserQuestion always appends),+ // and the retry would never run. The id is the in-flight response, so once it renders+ // the retry resolves it.+ return messages.findIndex(+ (message) => message.messageId === responseMessageId && isAssistant(message),+ );+ }+ /** No responseMessageId: best-effort to the last assistant (the in-flight placeholder). */+ for (let i = messages.length - 1; i >= 0; i--) {+ if (isAssistant(messages[i])) {+ return i;+ }+ }+ return -1;+}diff --git a/client/src/utils/index.ts b/client/src/utils/index.tsindex ea322b047f..43dc5baeea 100644--- a/client/src/utils/index.ts+++ b/client/src/utils/index.ts@@ -38,6 +38,7 @@ export * from './previewCache';export * from './groupToolCalls';export * from './toolLabels';export * from './favoritesError';+export * from './approval';export { default as cn } from './cn';export { default as logger } from './logger';export { default as getLoginError } from './getLoginError';diff --git a/package-lock.json b/package-lock.jsonindex e61012372b..e7ac78345b 100644--- a/package-lock.json+++ b/package-lock.json@@ -61,7 +61,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^2.8.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.2.52",+ "@librechat/agents": "^3.2.53","@librechat/api": "*","@librechat/data-schemas": "*","@microsoft/microsoft-graph-client": "^3.0.7",@@ -9511,13 +9511,13 @@}},"node_modules/@langchain/langgraph": {- "version": "1.4.5",- "resolved": "https://registry.npmjs.org/@langchain/langgraph/-/langgraph-1.4.5.tgz",- "integrity": "sha512-V+o29JPBaMoK/e+8R/m81XaC8h5iNuwWymvgLFhXfJbf7E2xt2mQUkcVXTi4cudGRHbRd14kidCpfaQbfPoYCw==",+ "version": "1.4.7",+ "resolved": "https://registry.npmjs.org/@langchain/langgraph/-/langgraph-1.4.7.tgz",+ "integrity": "sha512-2tcyf3QGC7v89kqSxMCtRvzg/3L/4yHtOaWC49A8KieCciWJs7LGaxHoPB6QRxXyUgyR+Zg9Q1ss/XJIE+JuSQ==","license": "MIT","dependencies": {- "@langchain/langgraph-checkpoint": "^1.1.2",- "@langchain/langgraph-sdk": "~1.9.24",+ "@langchain/langgraph-checkpoint": "^1.1.3",+ "@langchain/langgraph-sdk": "~1.9.25","@langchain/protocol": "^0.0.18","@standard-schema/spec": "1.1.0"},@@ -9526,19 +9526,13 @@},"peerDependencies": {"@langchain/core": "^1.1.48",- "zod": "^3.25.32 || ^4.2.0",- "zod-to-json-schema": "^3.x"- },- "peerDependenciesMeta": {- "zod-to-json-schema": {- "optional": true- }+ "zod": "^3.25.32 || ^4.2.0"}},"node_modules/@langchain/langgraph-checkpoint": {- "version": "1.1.2",- "resolved": "https://registry.npmjs.org/@langchain/langgraph-checkpoint/-/langgraph-checkpoint-1.1.2.tgz",- "integrity": "sha512-m5Xd7W3G9JrlEhFZ5WAcqZPgE46R9gr1gFDFaVqEKeuwin3tgEp0jlPbru+iFXCug338DcQjFS/Kuuci21ydvw==",+ "version": "1.1.3",+ "resolved": "https://registry.npmjs.org/@langchain/langgraph-checkpoint/-/langgraph-checkpoint-1.1.3.tgz",+ "integrity": "sha512-wgzdQNeEsdw1e+4lvlj0tdq/RYR/k1vPin10g0ymGoehZDDgd9nvIllGXSXN4TFgF9sf5qQP/KTkOcLfeseIhA==","license": "MIT","engines": {"node": ">=18"@@ -9547,10 +9541,72 @@"@langchain/core": "^1.1.48"}},+ "node_modules/@langchain/langgraph-checkpoint-mongodb": {+ "version": "1.4.0",+ "resolved": "https://registry.npmjs.org/@langchain/langgraph-checkpoint-mongodb/-/langgraph-checkpoint-mongodb-1.4.0.tgz",+ "integrity": "sha512-CFTrK7LrhyjotGn2YEyqYQIT1YDnw8rGC3ZTApkPvLHAW1BpVwC5N2WhA/StGOCqbCNx1HZkskLtBFhjkcKGwA==",+ "license": "MIT",+ "dependencies": {+ "mongodb": "^6.21.0"+ },+ "engines": {+ "node": ">=18"+ },+ "peerDependencies": {+ "@langchain/core": "^1.1.44",+ "@langchain/langgraph-checkpoint": "^1.0.0"+ }+ },+ "node_modules/@langchain/langgraph-checkpoint-mongodb/node_modules/mongodb": {+ "version": "6.21.0",+ "resolved": "https://registry.npmjs.org/mongodb/-/mongodb-6.21.0.tgz",+ "integrity": "sha512-URyb/VXMjJ4da46OeSXg+puO39XH9DeQpWCslifrRn9JWugy0D+DvvBvkm2WxmHe61O/H19JM66p1z7RHVkZ6A==",+ "license": "Apache-2.0",+ "dependencies": {+ "@mongodb-js/saslprep": "^1.3.0",+ "bson": "^6.10.4",+ "mongodb-connection-string-url": "^3.0.2"+ },+ "engines": {+ "node": ">=16.20.1"+ },+ "peerDependencies": {+ "@aws-sdk/credential-providers": "^3.188.0",+ "@mongodb-js/zstd": "^1.1.0 || ^2.0.0",+ "gcp-metadata": "^5.2.0",+ "kerberos": "^2.0.1",+ "mongodb-client-encryption": ">=6.0.0 <7",+ "snappy": "^7.3.2",+ "socks": "^2.7.1"+ },+ "peerDependenciesMeta": {+ "@aws-sdk/credential-providers": {+ "optional": true+ },+ "@mongodb-js/zstd": {+ "optional": true+ },+ "gcp-metadata": {+ "optional": true+ },+ "kerberos": {+ "optional": true+ },+ "mongodb-client-encryption": {+ "optional": true+ },+ "snappy": {+ "optional": true+ },+ "socks": {+ "optional": true+ }+ }+ },"node_modules/@langchain/langgraph-sdk": {- "version": "1.9.24",- "resolved": "https://registry.npmjs.org/@langchain/langgraph-sdk/-/langgraph-sdk-1.9.24.tgz",- "integrity": "sha512-WhM6QdxNipndQjl5nkvqnBt9Wl16oO2p0KiVhndAFLJMwO3bZLEx++lwtbqUFQu1sHyNxiWixgRGm8qZsuHCeA==",+ "version": "1.9.25",+ "resolved": "https://registry.npmjs.org/@langchain/langgraph-sdk/-/langgraph-sdk-1.9.25.tgz",+ "integrity": "sha512-mRKW8zyQUaHox+HirRFMRrPqOvNbQI3xeXDt6kkk4PbBg77V92bsO1WzUVNrmJ81zCkvxyOrWSK8D6ioCj0a8A==","license": "MIT","dependencies": {"@langchain/protocol": "^0.0.18",@@ -9823,9 +9879,9 @@}},"node_modules/@librechat/agents": {- "version": "3.2.52",- "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.2.52.tgz",- "integrity": "sha512-NS/yXn412h1/JZ5LQpDGxIpW0Pb3r6zDKpAyH/U88CLcSAXwStivU7JouAphtdemJOGQpmGSv7IXpBM7wY0tOw==",+ "version": "3.2.53",+ "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.2.53.tgz",+ "integrity": "sha512-GQ4n14AUUzISgcQMCCBkDfiUEWWujWOoeaIx1D9BgaYo6k1IW/mV1epthpGYbARQNaM7FiKVJFINs3CMJXfBXA==","license": "MIT","dependencies": {"@anthropic-ai/sdk": "^0.103.0",@@ -9838,7 +9894,7 @@"@langchain/google-gauth": "2.2.0","@langchain/google-genai": "2.2.0","@langchain/google-vertexai": "2.2.0",- "@langchain/langgraph": "^1.4.5",+ "@langchain/langgraph": "^1.4.6","@langchain/mistralai": "^1.2.0","@langchain/openai": "1.5.3","@langchain/textsplitters": "^1.0.1",@@ -42288,6 +42344,9 @@"name": "@librechat/api","version": "1.7.34","license": "ISC",+ "dependencies": {+ "@langchain/langgraph-checkpoint-mongodb": "^1.4.0"+ },"devDependencies": {"@babel/preset-env": "^7.29.5","@babel/preset-react": "^7.18.6",@@ -42346,7 +42405,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^2.8.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.2.52",+ "@librechat/agents": "^3.2.53","@librechat/data-schemas": "*","@modelcontextprotocol/sdk": "^1.29.0","@opentelemetry/api": "^1.9.0",diff --git a/packages/api/package.json b/packages/api/package.jsonindex 35f0d42ef2..0e7c0f098f 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -113,7 +113,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^2.8.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.2.52",+ "@librechat/agents": "^3.2.53","@librechat/data-schemas": "*","@modelcontextprotocol/sdk": "^1.29.0","@opentelemetry/api": "^1.9.0",@@ -163,5 +163,8 @@"undici": "^7.24.1","yauzl": "^3.2.1","zod": "^3.22.4"+ },+ "dependencies": {+ "@langchain/langgraph-checkpoint-mongodb": "^1.4.0"}}diff --git a/packages/api/src/agents/__tests__/run-summarization.test.ts b/packages/api/src/agents/__tests__/run-summarization.test.tsindex e4b3a85dbb..d67d904b58 100644--- a/packages/api/src/agents/__tests__/run-summarization.test.ts+++ b/packages/api/src/agents/__tests__/run-summarization.test.ts@@ -69,6 +69,11 @@ jest.mock('@librechat/agents', () => {};});+// Stub the durable checkpointer so the HITL-enabled path doesn't need a live Mongo.+jest.mock('~/agents/checkpointer', () => ({+ getAgentCheckpointer: jest.fn().mockResolvedValue({}),+}));+import { Run } from '@librechat/agents';/** Minimal RunAgent factory */@@ -1853,3 +1858,149 @@ describe('toolOutputReferences gating', () => {expect(callArgs).not.toHaveProperty('toolOutputReferences');});});++// ---------------------------------------------------------------------------+// Suite: deferred-tool replay on HITL resume (Codex G3)+//+// The resume path rebuilds the graph with `messages: []` (state comes from the+// durable checkpoint), so the in-turn `tool_search` results that mark a deferred+// tool discovered aren't on the critical path. createRun's `discoveredToolNames`+// input replays those names — captured at pause — so the paused deferred tool is+// promoted back into `toolDefinitions` (and `defer_loading` flipped) and is present+// in the rebuilt schema-only toolMap. Without it, the approved tool would be missing+// and resume would fail with "unknown tool".+// ---------------------------------------------------------------------------+describe('createRun deferred-tool replay (HITL resume)', () => {+ /** Agent whose discoverable `deep_tool` lives ONLY in the registry (deferred). */+ const makeDeferredAgent = (registryExtra: Array<[string, Record<string, unknown>]> = []) => {+ const toolRegistry = new Map<string, Record<string, unknown>>([+ ['deep_tool', { name: 'deep_tool', defer_loading: true }],+ ...registryExtra,+ ]);+ return makeAgent({+ hasDeferredTools: true,+ // tool_search is in definitions; the discoverable deep_tool is NOT (deferred).+ toolDefinitions: [{ name: 'tool_search' }],+ toolRegistry,+ });+ };++ const captureAgents = async (+ agent: ReturnType<typeof makeAgent>,+ extra: Record<string, unknown>,+ ) => {+ const signal = new AbortController().signal;+ await createRun({+ agents: [agent] as never,+ signal,+ streaming: true,+ streamUsage: true,+ ...extra,+ });+ const createMock = Run.create as jest.Mock;+ const callArgs = createMock.mock.calls[0][0];+ return callArgs.graphConfig.agents as Array<Record<string, unknown>>;+ };++ const defNames = (agents: Array<Record<string, unknown>>): string[] =>+ (agents[0].toolDefinitions as Array<{ name: string }>).map((d) => d.name);++ it('promotes a replayed discovered tool into toolDefinitions when messages is empty (resume)', async () => {+ const agents = await captureAgents(makeDeferredAgent(), {+ messages: [],+ discoveredToolNames: ['deep_tool'],+ });+ expect(defNames(agents)).toContain('deep_tool');+ });++ it('does NOT include the deferred tool without replayed names (the bug being fixed)', async () => {+ const agents = await captureAgents(makeDeferredAgent(), { messages: [] });+ expect(defNames(agents)).not.toContain('deep_tool');+ });++ it('flips defer_loading=false on the replayed tool so the model binds it', async () => {+ const agents = await captureAgents(makeDeferredAgent(), {+ messages: [],+ discoveredToolNames: ['deep_tool'],+ });+ const registry = agents[0].toolRegistry as Map<string, { defer_loading?: boolean }>;+ expect(registry.get('deep_tool')?.defer_loading).toBe(false);+ });++ it('unions replayed names with names extracted from message history', async () => {+ const toolSearchResult = {+ _getType: () => 'tool',+ name: 'tool_search',+ content: JSON.stringify({ tools: [{ name: 'from_history' }] }),+ };+ const agents = await captureAgents(+ makeDeferredAgent([['from_history', { name: 'from_history', defer_loading: true }]]),+ { messages: [toolSearchResult], discoveredToolNames: ['deep_tool'] },+ );+ const names = defNames(agents);+ expect(names).toContain('deep_tool'); // replayed+ expect(names).toContain('from_history'); // extracted from messages+ });++ it('ignores replayed names when the agent has no deferred tools (inert)', async () => {+ const agents = await captureAgents(+ makeAgent({ hasDeferredTools: false, toolDefinitions: [], toolRegistry: new Map() }),+ { messages: [], discoveredToolNames: ['deep_tool'] },+ );+ expect(defNames(agents)).not.toContain('deep_tool');+ });+});++// ---------------------------------------------------------------------------+// Suite: HITL wiring gated to resumable callers (Codex J3)+//+// The tool-approval wiring (humanInTheLoop switch + PreToolUse hook) must engage ONLY for+// callers that implement the pause/resume lifecycle. AgentClient passes hitlCapable: true;+// the OpenAI-compatible + Responses controllers don't, so an approval-gated tool can't+// pause on a route with no approval surface or resume endpoint.+// ---------------------------------------------------------------------------+describe('HITL wiring is gated on hitlCapable', () => {+ const hitlAppConfig = {+ config: {},+ fileStrategy: FileSources.local,+ imageOutputType: 'png',+ endpoints: {+ [EModelEndpoint.agents]: { toolApproval: { enabled: true } },+ },+ } as unknown as AppConfig;++ const runAndGetConfig = async (extra: Record<string, unknown>) => {+ await createRun({+ agents: [makeAgent()] as never,+ signal: new AbortController().signal,+ appConfig: hitlAppConfig,+ streaming: true,+ streamUsage: true,+ ...extra,+ });+ const createMock = Run.create as jest.Mock;+ return createMock.mock.calls[0][0] as Record<string, unknown>;+ };++ it('attaches humanInTheLoop when the caller is hitlCapable and approval is enabled', async () => {+ const config = await runAndGetConfig({ hitlCapable: true });+ expect(config.humanInTheLoop).toBeDefined();+ expect(config.hooks).toBeDefined();+ });++ it('does NOT attach HITL for a non-resumable caller even when approval is enabled', async () => {+ const config = await runAndGetConfig({ hitlCapable: false });+ expect(config).not.toHaveProperty('humanInTheLoop');+ expect(config.graphConfig).toBeDefined();+ // No checkpointer either — the run is identical to the no-HITL path.+ expect(+ (config.graphConfig as { compileOptions?: { checkpointer?: unknown } }).compileOptions+ ?.checkpointer,+ ).toBeUndefined();+ });++ it('defaults to non-HITL when hitlCapable is omitted', async () => {+ const config = await runAndGetConfig({});+ expect(config).not.toHaveProperty('humanInTheLoop');+ });+});diff --git a/packages/api/src/agents/checkpointer.integration.spec.ts b/packages/api/src/agents/checkpointer.integration.spec.tsnew file mode 100644index 0000000000..ae10502608--- /dev/null+++ b/packages/api/src/agents/checkpointer.integration.spec.ts@@ -0,0 +1,109 @@+import mongoose from 'mongoose';+import { MongoMemoryServer } from 'mongodb-memory-server';+import { emptyCheckpoint } from '@langchain/langgraph-checkpoint';+import {+ getAgentCheckpointer,+ deleteAgentCheckpoint,+ __resetCheckpointerForTests,+} from './checkpointer';++/**+ * Integration tests for the durable Mongo checkpointer seam, against a real+ * (in-memory) MongoDB. The unit spec covers config/selection with no connection;+ * this proves the part that actually matters for correctness — that a checkpoint+ * written for a thread can be read back and that `deleteAgentCheckpoint` truly+ * prunes it (the cross-turn isolation guarantee), scoped to a single thread.+ */++const MONGO_CFG = { type: 'mongo' as const, ttl: 3600 };++/** Minimal LangGraph put() args for an empty checkpoint under a thread. */+function putArgs(threadId: string) {+ const config = { configurable: { thread_id: threadId, checkpoint_ns: '' } };+ const metadata = { source: 'input' as const, step: -1, writes: null, parents: {} };+ return { config, checkpoint: emptyCheckpoint(), metadata };+}++const readConfig = (threadId: string) => ({+ configurable: { thread_id: threadId, checkpoint_ns: '' },+});++let mongoServer: MongoMemoryServer;++beforeAll(async () => {+ mongoServer = await MongoMemoryServer.create();+ await mongoose.connect(mongoServer.getUri());+}, 60000);++afterAll(async () => {+ await mongoose.disconnect();+ await mongoServer.stop();+});++beforeEach(() => {+ // Force a fresh saver build (+ setup) against the live connection each test.+ __resetCheckpointerForTests();+});++afterEach(async () => {+ await mongoose.connection.dropDatabase();+});++describe('checkpointer (mongodb-memory-server integration)', () => {+ it('builds a real MongoDBSaver when Mongo is connected', async () => {+ const saver = await getAgentCheckpointer(MONGO_CFG);+ expect(saver).toBeDefined();+ // setup() created the checkpoint collection with a TTL index on `upserted_at`.+ const indexes = await mongoose.connection.db!.collection('agent_checkpoints').indexes();+ const ttlIndex = indexes.find((idx) => idx.expireAfterSeconds != null);+ expect(ttlIndex).toBeDefined();+ expect(ttlIndex?.expireAfterSeconds).toBe(3600);+ });++ it('returns undefined for the memory type (SDK MemorySaver fallback) even when connected', async () => {+ expect(await getAgentCheckpointer({ type: 'memory' })).toBeUndefined();+ });++ it('memoizes one saver per resolved config', async () => {+ const a = await getAgentCheckpointer(MONGO_CFG);+ const b = await getAgentCheckpointer(MONGO_CFG);+ expect(a).toBe(b);+ });++ it('deleteAgentCheckpoint prunes a thread’s persisted checkpoint', async () => {+ const saver = await getAgentCheckpointer(MONGO_CFG);+ expect(saver).toBeDefined();++ const threadId = `convo-${new mongoose.Types.ObjectId().toString()}`;+ const { config, checkpoint, metadata } = putArgs(threadId);+ await saver!.put(config, checkpoint, metadata);++ // The checkpoint is durably readable before pruning…+ expect(await saver!.getTuple(readConfig(threadId))).toBeDefined();++ await deleteAgentCheckpoint(threadId, MONGO_CFG);++ // …and gone after (so turn N+1 on the same conversationId can't rehydrate it).+ expect(await saver!.getTuple(readConfig(threadId))).toBeUndefined();+ });++ it('prunes only the targeted thread, leaving other conversations intact', async () => {+ const saver = await getAgentCheckpointer(MONGO_CFG);+ const threadA = `convo-${new mongoose.Types.ObjectId().toString()}`;+ const threadB = `convo-${new mongoose.Types.ObjectId().toString()}`;++ const a = putArgs(threadA);+ const b = putArgs(threadB);+ await saver!.put(a.config, a.checkpoint, a.metadata);+ await saver!.put(b.config, b.checkpoint, b.metadata);++ await deleteAgentCheckpoint(threadA, MONGO_CFG);++ expect(await saver!.getTuple(readConfig(threadA))).toBeUndefined();+ expect(await saver!.getTuple(readConfig(threadB))).toBeDefined();+ });++ it('deleteAgentCheckpoint is a no-op for an undefined threadId', async () => {+ await expect(deleteAgentCheckpoint(undefined, MONGO_CFG)).resolves.toBeUndefined();+ });+});diff --git a/packages/api/src/agents/checkpointer.spec.ts b/packages/api/src/agents/checkpointer.spec.tsnew file mode 100644index 0000000000..cfadc2df73--- /dev/null+++ b/packages/api/src/agents/checkpointer.spec.ts@@ -0,0 +1,72 @@+import {+ resolveCheckpointerConfig,+ getApprovalTtlMs,+ getAgentCheckpointer,+ deleteAgentCheckpoint,+ DEFAULT_CHECKPOINT_TTL_SECONDS,+ __resetCheckpointerForTests,+} from './checkpointer';++beforeEach(() => {+ __resetCheckpointerForTests();+});++describe('resolveCheckpointerConfig', () => {+ test('applies defaults when nothing is configured', () => {+ expect(resolveCheckpointerConfig(undefined)).toEqual({+ type: 'mongo',+ ttlSeconds: DEFAULT_CHECKPOINT_TTL_SECONDS,+ checkpointCollectionName: 'agent_checkpoints',+ checkpointWritesCollectionName: 'agent_checkpoint_writes',+ });+ });++ test('honors explicit type, ttl, and collection overrides', () => {+ expect(+ resolveCheckpointerConfig({+ type: 'memory',+ ttl: 60,+ checkpointCollectionName: 'cp',+ checkpointWritesCollectionName: 'cpw',+ }),+ ).toEqual({+ type: 'memory',+ ttlSeconds: 60,+ checkpointCollectionName: 'cp',+ checkpointWritesCollectionName: 'cpw',+ });+ });++ test('falls back to the default ttl for non-positive values', () => {+ expect(resolveCheckpointerConfig({ ttl: 0 }).ttlSeconds).toBe(DEFAULT_CHECKPOINT_TTL_SECONDS);+ expect(resolveCheckpointerConfig({ ttl: -5 }).ttlSeconds).toBe(DEFAULT_CHECKPOINT_TTL_SECONDS);+ });+});++describe('getApprovalTtlMs', () => {+ test('converts the resolved ttl to milliseconds', () => {+ expect(getApprovalTtlMs(undefined)).toBe(DEFAULT_CHECKPOINT_TTL_SECONDS * 1000);+ expect(getApprovalTtlMs({ ttl: 60 })).toBe(60_000);+ });+});++describe('getAgentCheckpointer', () => {+ test('returns undefined for the in-memory type (SDK MemorySaver fallback)', async () => {+ await expect(getAgentCheckpointer({ type: 'memory' })).resolves.toBeUndefined();+ });++ test('returns undefined when Mongo is not connected', async () => {+ // No mongoose connection is established in the unit test env (readyState 0).+ await expect(getAgentCheckpointer(undefined)).resolves.toBeUndefined();+ });+});++describe('deleteAgentCheckpoint', () => {+ test('is a no-op (no throw) for a missing threadId', async () => {+ await expect(deleteAgentCheckpoint(undefined)).resolves.toBeUndefined();+ });++ test('is a no-op (no throw) when no durable saver is available', async () => {+ await expect(deleteAgentCheckpoint('conversation-1')).resolves.toBeUndefined();+ });+});diff --git a/packages/api/src/agents/checkpointer.ts b/packages/api/src/agents/checkpointer.tsnew file mode 100644index 0000000000..6a99a616aa--- /dev/null+++ b/packages/api/src/agents/checkpointer.ts@@ -0,0 +1,171 @@+import mongoose from 'mongoose';+import { logger } from '@librechat/data-schemas';+import { MongoDBSaver } from '@langchain/langgraph-checkpoint-mongodb';+import type { TCheckpointerConfig } from 'librechat-data-provider';++/**+ * Durable checkpointing for human-in-the-loop (HITL) resume.+ *+ * This is the seam between LibreChat and LangGraph's checkpoint machinery. A run+ * that pauses for tool approval suspends its graph state to a checkpoint; resuming+ * rebuilds that state on a *fresh* `Run` (see `agents/run.ts`), which only works if+ * the checkpoint outlives the original request — across a restart, or on another+ * replica. So HITL needs a durable saver, not the SDK's process-local `MemorySaver`.+ *+ * Two adapters sit behind the one interface ({@link getAgentCheckpointer}):+ * - `MongoDBSaver` over the app's existing Mongo connection (the default), and+ * - `undefined`, which lets the SDK install its own in-process `MemorySaver`+ * (single-process / dev, or whenever Mongo isn't ready yet).+ *+ * Storage is bounded two ways: a Mongo TTL index reclaims runs that are never+ * resolved ({@link DEFAULT_CHECKPOINT_TTL_SECONDS}), and {@link deleteAgentCheckpoint}+ * prunes a thread's checkpoints eagerly on every terminal transition.+ */++/** Default approval window and checkpoint TTL: 24h. */+export const DEFAULT_CHECKPOINT_TTL_SECONDS = 86400;++const DEFAULT_CHECKPOINT_COLLECTION = 'agent_checkpoints';+const DEFAULT_CHECKPOINT_WRITES_COLLECTION = 'agent_checkpoint_writes';++/** Checkpointer settings with all defaults applied. */+export interface ResolvedCheckpointerConfig {+ type: 'mongo' | 'memory';+ /** Approval window / TTL in seconds. */+ ttlSeconds: number;+ checkpointCollectionName: string;+ checkpointWritesCollectionName: string;+}++/**+ * Apply defaults to the YAML `endpoints.agents.checkpointer` block. Mirrors+ * {@link resolveRecursionLimit} — the schema stays descriptive, defaults live here.+ */+export function resolveCheckpointerConfig(+ cfg: TCheckpointerConfig | undefined,+): ResolvedCheckpointerConfig {+ return {+ type: cfg?.type ?? 'mongo',+ ttlSeconds:+ typeof cfg?.ttl === 'number' && cfg.ttl > 0 ? cfg.ttl : DEFAULT_CHECKPOINT_TTL_SECONDS,+ checkpointCollectionName: cfg?.checkpointCollectionName ?? DEFAULT_CHECKPOINT_COLLECTION,+ checkpointWritesCollectionName:+ cfg?.checkpointWritesCollectionName ?? DEFAULT_CHECKPOINT_WRITES_COLLECTION,+ };+}++/** Approval-window milliseconds from the resolved config; drives pending-action expiry. */+export function getApprovalTtlMs(cfg: TCheckpointerConfig | undefined): number {+ return resolveCheckpointerConfig(cfg).ttlSeconds * 1000;+}++/**+ * One saver per process, built lazily on first use so `setup()` (index creation)+ * runs exactly once. Keyed by the resolved settings so a config change rebuilds.+ */+let saverPromise: Promise<MongoDBSaver | undefined> | undefined;+let cachedKey: string | undefined;++function settingsKey(resolved: ResolvedCheckpointerConfig): string {+ return `${resolved.checkpointCollectionName}|${resolved.checkpointWritesCollectionName}|${resolved.ttlSeconds}`;+}++/**+ * The durable saver to hand to `graphConfig.compileOptions.checkpointer`, or+ * `undefined` to let the SDK fall back to its in-process `MemorySaver`.+ *+ * Returns `undefined` (without caching) when the config selects `memory` or when+ * Mongo isn't connected yet, so a later run retries once the connection is up.+ * The SDK types the checkpointer as `unknown`, so a `MongoDBSaver` passes directly.+ */+export async function getAgentCheckpointer(+ cfg: TCheckpointerConfig | undefined,+): Promise<MongoDBSaver | undefined> {+ const resolved = resolveCheckpointerConfig(cfg);+ if (resolved.type === 'memory') {+ return undefined;+ }+ if (mongoose.connection.readyState !== 1) {+ logger.warn(+ '[checkpointer] Mongoose not connected; HITL runs will use an in-process checkpointer this turn (paused runs will not survive a restart or resolve on another replica).',+ );+ return undefined;+ }++ const key = settingsKey(resolved);+ if (!saverPromise || cachedKey !== key) {+ cachedKey = key;+ saverPromise = buildMongoSaver(resolved);+ }+ return saverPromise;+}++async function buildMongoSaver(+ resolved: ResolvedCheckpointerConfig,+): Promise<MongoDBSaver | undefined> {+ try {+ const saver = new MongoDBSaver({+ // mongoose vends the live MongoClient; reuse it instead of opening a second+ // connection. The driver type is structurally identical but resolves to a+ // different `mongodb` copy than checkpoint-mongodb's, hence the cast.+ client: mongoose.connection.getClient() as unknown as ConstructorParameters<+ typeof MongoDBSaver+ >[0]['client'],+ checkpointCollectionName: resolved.checkpointCollectionName,+ checkpointWritesCollectionName: resolved.checkpointWritesCollectionName,+ // TTL index on `upserted_at`: an unresolved paused run is reclaimed after the+ // approval window, so a forgotten approval can never leak checkpoints forever.+ ttl: resolved.ttlSeconds,+ });+ const errors = await saver.setup();+ if (errors.length > 0) {+ logger.warn(+ '[checkpointer] MongoDBSaver.setup() reported errors (checkpoint indexes may be incomplete):',+ errors,+ );+ }+ logger.info('[checkpointer] Durable Mongo checkpointer ready for HITL resume');+ return saver;+ } catch (err) {+ // Reset so a later run can retry rather than being stuck on a failed build.+ saverPromise = undefined;+ cachedKey = undefined;+ logger.error(+ '[checkpointer] Failed to initialize Mongo checkpointer; falling back to in-process checkpointer:',+ err,+ );+ return undefined;+ }+}++/**+ * Prune a thread's checkpoints on a terminal transition — natural completion,+ * abort, or expiry — so the durable store stays bounded. The TTL index is the+ * safety net; this is the eager cleanup. No-op in memory mode or before any run+ * has built the saver (nothing to delete).+ *+ * @param threadId - the LangGraph `thread_id` (LibreChat's conversationId).+ */+export async function deleteAgentCheckpoint(+ threadId: string | undefined,+ cfg?: TCheckpointerConfig,+): Promise<void> {+ if (!threadId) {+ return;+ }+ const saver = await getAgentCheckpointer(cfg);+ if (!saver) {+ return;+ }+ try {+ await saver.deleteThread(threadId);+ } catch (err) {+ logger.warn(`[checkpointer] Failed to delete checkpoints for thread ${threadId}:`, err);+ }+}++/** Test-only: drop the memoized saver so a fresh build is forced. */+export function __resetCheckpointerForTests(): void {+ saverPromise = undefined;+ cachedKey = undefined;+}diff --git a/packages/api/src/agents/hitl/index.ts b/packages/api/src/agents/hitl/index.tsindex 62d5b849e4..690ccb1828 100644--- a/packages/api/src/agents/hitl/index.ts+++ b/packages/api/src/agents/hitl/index.ts@@ -1 +1,3 @@export * from './policy';+export * from './runtime';+export * from './resume';diff --git a/packages/api/src/agents/hitl/policy.spec.ts b/packages/api/src/agents/hitl/policy.spec.tsindex 369922a5ff..579b0503ef 100644--- a/packages/api/src/agents/hitl/policy.spec.ts+++ b/packages/api/src/agents/hitl/policy.spec.ts@@ -1,12 +1,41 @@import type { Agents, TToolApprovalPolicy } from 'librechat-data-provider';import {+ resolveToolApprovalPolicy,isHITLEnabled,mapToolApprovalPolicy,buildToolApprovalPayload,buildAskUserQuestionPayload,buildPendingAction,+ computeAgentRequestFingerprint,+ pickResumeContext,+ applyResumeContext,} from './policy';+describe('resolveToolApprovalPolicy', () => {+ test('returns the endpoint policy unchanged (single layer wired today)', () => {+ const endpoint: TToolApprovalPolicy = { enabled: true, mode: 'default', deny: ['rm'] };+ // Identity, not a copy — the resolver is a passthrough until more layers ship.+ expect(resolveToolApprovalPolicy({ endpoint })).toBe(endpoint);+ });++ test('returns undefined when there is no endpoint policy', () => {+ expect(resolveToolApprovalPolicy({})).toBeUndefined();+ expect(resolveToolApprovalPolicy({ endpoint: undefined })).toBeUndefined();+ });++ test('ignores the reserved agent/skills layers for now (behaviour-preserving)', () => {+ const endpoint: TToolApprovalPolicy = { enabled: true, mode: 'bypass' };+ const resolved = resolveToolApprovalPolicy({+ endpoint,+ agent: { enabled: true, mode: 'default', ask: ['shell'] },+ skills: [{ deny: ['delete_*'] }],+ });+ // Until merge lands, the result must still be exactly the endpoint policy so+ // enabling the seam can't change runtime behaviour.+ expect(resolved).toBe(endpoint);+ });+});+describe('isHITLEnabled', () => {test('default-off when no policy configured', () => {expect(isHITLEnabled(undefined)).toBe(false);@@ -227,3 +256,178 @@ describe('buildPendingAction', () => {expect(action.expiresAt).toBeLessThanOrEqual(after);});});++describe('computeAgentRequestFingerprint', () => {+ it('is stable for the same graph-determining fields (ignoring other body keys)', () => {+ const a = computeAgentRequestFingerprint({+ endpoint: 'agents',+ agent_id: 'agent-1',+ model: 'gpt',+ });+ // Extra/unknown fields on the body must not change the fingerprint.+ const b = computeAgentRequestFingerprint({+ endpoint: 'agents',+ agent_id: 'agent-1',+ model: 'gpt',+ ...({ conversationId: 'c', decisions: [] } as Record<string, unknown>),+ });+ expect(a).toBe(b);+ });++ it('differs when a graph-determining field changes', () => {+ const base = { endpoint: 'agents', agent_id: 'agent-1', model: 'gpt' };+ expect(computeAgentRequestFingerprint(base)).not.toBe(+ computeAgentRequestFingerprint({ ...base, model: 'other' }),+ );+ expect(computeAgentRequestFingerprint(base)).not.toBe(+ computeAgentRequestFingerprint({ ...base, agent_id: 'agent-2' }),+ );+ });++ it('differs when promptPrefix changes (ephemeral instructions)', () => {+ const base = { endpoint: 'agents', promptPrefix: 'be terse' };+ expect(computeAgentRequestFingerprint(base)).not.toBe(+ computeAgentRequestFingerprint({ ...base, promptPrefix: 'be verbose' }),+ );+ // null vs absent are treated the same+ expect(computeAgentRequestFingerprint({ endpoint: 'agents' })).toBe(+ computeAgentRequestFingerprint({ endpoint: 'agents', promptPrefix: null }),+ );+ });++ it('normalizes ephemeralAgent so key/array order does not matter', () => {+ const x = computeAgentRequestFingerprint({+ endpoint: 'agents',+ ephemeralAgent: { mcp: ['b', 'a'], execute_code: true },+ });+ const y = computeAgentRequestFingerprint({+ endpoint: 'agents',+ ephemeralAgent: { execute_code: true, mcp: ['a', 'b'] },+ });+ expect(x).toBe(y);+ });++ it('distinguishes a different ephemeral capability set (the swap it guards against)', () => {+ const a = computeAgentRequestFingerprint({+ endpoint: 'agents',+ ephemeralAgent: { execute_code: true },+ });+ const b = computeAgentRequestFingerprint({+ endpoint: 'agents',+ ephemeralAgent: { execute_code: false, mcp: ['evil'] },+ });+ expect(a).not.toBe(b);+ });+});++describe('pickResumeContext / applyResumeContext', () => {+ it('picks only the graph-determining fields (incl. addedConvo + timezone), dropping unrelated keys', () => {+ const ctx = pickResumeContext({+ endpoint: 'agents',+ agent_id: 'a1',+ model: 'gpt',+ promptPrefix: 'be terse',+ ephemeralAgent: { execute_code: true },+ addedConvo: { agent_id: 'secondary' },+ // Feeds temporal prompt vars; must round-trip so resume compiles the same prompt.+ timezone: 'America/New_York',+ // Graph-determining: skill allowed-tools union into the tool set.+ manualSkills: ['code-reviewer'],+ conversationId: 'c',+ decisions: [],+ actionId: 'x',+ });+ expect(ctx).toEqual({+ endpoint: 'agents',+ agent_id: 'a1',+ model: 'gpt',+ promptPrefix: 'be terse',+ ephemeralAgent: { execute_code: true },+ addedConvo: { agent_id: 'secondary' },+ timezone: 'America/New_York',+ manualSkills: ['code-reviewer'],+ });+ });++ it('replays a dropped manualSkills and drops a client-injected one', () => {+ // Reload case: the resume client lost manualSkills; the server restores it.+ const restored: Record<string, unknown> = { conversationId: 'c', actionId: 'x' };+ applyResumeContext(restored, { endpoint: 'agents', manualSkills: ['code-reviewer'] });+ expect(restored.manualSkills).toEqual(['code-reviewer']);+ // Security: a paused turn with no manual skill can't be made to inject one.+ const injected: Record<string, unknown> = { conversationId: 'c', manualSkills: ['evil-skill'] };+ applyResumeContext(injected, { endpoint: 'agents', agent_id: 'a1' });+ expect('manualSkills' in injected).toBe(false);+ });++ it('omits absent (undefined) fields but keeps explicit null', () => {+ const ctx = pickResumeContext({ endpoint: 'agents', ephemeralAgent: null });+ expect(ctx).toEqual({ endpoint: 'agents', ephemeralAgent: null });+ expect('agent_id' in ctx).toBe(false);+ });++ it('replays the persisted context onto a body, overwriting what the client sent', () => {+ // The reload case: the client lost ephemeralAgent (null); the server restores it.+ const body: Record<string, unknown> = {+ conversationId: 'c',+ actionId: 'x',+ ephemeralAgent: null,+ promptPrefix: 'tampered',+ };+ applyResumeContext(body, {+ endpoint: 'agents',+ ephemeralAgent: { execute_code: true, mcp: ['srv'] },+ promptPrefix: 'original',+ });+ expect(body.ephemeralAgent).toEqual({ execute_code: true, mcp: ['srv'] });+ expect(body.promptPrefix).toBe('original');+ expect(body.endpoint).toBe('agents');+ // Non-context fields are untouched.+ expect(body.conversationId).toBe('c');+ expect(body.actionId).toBe('x');+ });++ it('drops graph-determining fields the client sent that the persisted context lacks', () => {+ // Security: the paused turn carried no addedConvo/spec, so a crafted resume must not+ // be able to inject them (addedConvo isn't covered by the fingerprint). Any+ // RESUME_CONTEXT_KEY absent from the persisted context is cleared from the body.+ const body: Record<string, unknown> = {+ conversationId: 'c',+ actionId: 'x',+ addedConvo: { agent_id: 'injected-secondary' },+ spec: 'injected-spec',+ };+ applyResumeContext(body, { endpoint: 'agents', agent_id: 'a1' });+ // Persisted keys are restored...+ expect(body.endpoint).toBe('agents');+ expect(body.agent_id).toBe('a1');+ // ...and client-injected graph-determining fields absent from the context are gone.+ expect('addedConvo' in body).toBe(false);+ expect('spec' in body).toBe(false);+ // Non-context fields are untouched.+ expect(body.conversationId).toBe('c');+ expect(body.actionId).toBe('x');+ });++ it('is a no-op for a null/undefined context', () => {+ const body: Record<string, unknown> = { ephemeralAgent: null };+ applyResumeContext(body, undefined);+ expect(body.ephemeralAgent).toBeNull();+ });++ it('round-trips through buildPendingAction so replay restores the original body', () => {+ const original = {+ endpoint: 'agents',+ ephemeralAgent: { execute_code: true },+ promptPrefix: 'p',+ };+ const action = buildPendingAction(+ { type: 'ask_user_question', question: { question: 'q' } } as Agents.HumanInterruptPayload,+ { streamId: 's', resumeContext: pickResumeContext(original) },+ );+ const reloadedBody: Record<string, unknown> = { ephemeralAgent: null };+ applyResumeContext(reloadedBody, action.resumeContext);+ expect(reloadedBody.ephemeralAgent).toEqual({ execute_code: true });+ expect(reloadedBody.promptPrefix).toBe('p');+ });+});diff --git a/packages/api/src/agents/hitl/policy.ts b/packages/api/src/agents/hitl/policy.tsindex bfe0543c7c..795b435aff 100644--- a/packages/api/src/agents/hitl/policy.ts+++ b/packages/api/src/agents/hitl/policy.ts@@ -1,4 +1,4 @@-import { randomUUID } from 'crypto';+import { randomUUID, createHash } from 'crypto';import type { Agents, TToolApprovalPolicy } from 'librechat-data-provider';import type { ToolPolicyConfig } from '@librechat/agents';@@ -11,6 +11,54 @@ import type { ToolPolicyConfig } from '@librechat/agents';*/const DEFAULT_REVIEW_DECISIONS: Agents.ToolApprovalDecisionType[] = ['approve', 'reject', 'edit'];+/**+ * Layered sources that combine into the effective tool-approval policy for a turn.+ *+ * Only {@link ToolApprovalPolicyLayers.endpoint} is consumed today; `agent` and+ * `skills` are reserved seams so future per-agent / per-skill plumbing lands in+ * {@link resolveToolApprovalPolicy} rather than being threaded through the run+ * call site.+ */+export interface ToolApprovalPolicyLayers {+ /**+ * App/endpoint policy — `endpoints.agents.toolApproval` from librechat.yaml.+ * The baseline, and the sole owner of the `enabled` kill switch.+ */+ endpoint?: TToolApprovalPolicy;+ /**+ * Per-agent override (not yet wired). Layered over `endpoint` to refine+ * `mode`/`allow`/`deny`/`ask`/`reason` for a specific agent. Must NOT flip+ * `enabled` — enablement stays endpoint-level by design.+ */+ agent?: TToolApprovalPolicy;+ /**+ * Skill-contributed policy (not yet wired). May only TIGHTEN — contribute+ * `ask`/`deny` entries — never grant `bypass` or widen `allow`, so a selected+ * skill can never silently auto-approve a tool.+ */+ skills?: TToolApprovalPolicy[];+}++/**+ * Resolve the effective tool-approval policy for a turn from its layered sources.+ *+ * This is the single seam where policy sources combine, kept out of the run call+ * site so adding per-agent or per-skill policy later is a change to ONE function+ * rather than to `createRun`. Intended precedence once those layers are wired:+ * - `endpoint` is the baseline and owns the `enabled` kill switch;+ * - `agent` overrides `mode`/`allow`/`deny`/`ask`/`reason`;+ * - `skills` may only tighten (add `ask`/`deny`), never loosen.+ *+ * Today only `endpoint` is consumed, so the result is identical to reading+ * `endpoints.agents.toolApproval` directly — `agent`/`skills` are accepted but+ * not yet merged. Behaviour-preserving until those layers ship.+ */+export function resolveToolApprovalPolicy(+ layers: ToolApprovalPolicyLayers,+): TToolApprovalPolicy | undefined {+ return layers.endpoint;+}+/*** Whether the HITL machinery should run for this policy.*@@ -121,6 +169,127 @@ export interface PendingActionContext {interruptId?: string;/** LangGraph `thread_id` (`RunInterruptResult.threadId`) for cross-process resume. */threadId?: string;+ /** Fingerprint of the graph-determining request fields; see {@link computeAgentRequestFingerprint}. */+ requestFingerprint?: string;+ /** Graph-determining fields to replay on resume; see {@link RESUME_CONTEXT_KEYS}. */+ resumeContext?: Record<string, unknown>;+}++/** Request fields that decide which agent/graph + tool set a turn runs. */+export interface AgentRequestFingerprintFields {+ endpoint?: string | null;+ endpointType?: string | null;+ agent_id?: string | null;+ model?: string | null;+ spec?: string | null;+ /** Ephemeral agents derive their system instructions from this; pin it too. */+ promptPrefix?: string | null;+ ephemeralAgent?: Record<string, unknown> | null;+}++/** Stable, order-independent serialization of the ephemeral capability config. */+function normalizeEphemeralAgent(ephemeral: Record<string, unknown> | null | undefined): unknown {+ if (ephemeral == null || typeof ephemeral !== 'object') {+ return null;+ }+ const out: Record<string, unknown> = {};+ for (const key of Object.keys(ephemeral).sort()) {+ const value = ephemeral[key];+ out[key] = Array.isArray(value) ? [...value].sort() : value;+ }+ return out;+}++/**+ * Fingerprint the request fields that determine which agent/graph + tool set a turn+ * runs. Persisted on the pending action at pause time and recomputed on resume; a+ * mismatch means the resume would rebuild a DIFFERENT graph. This is the guard that+ * catches an ephemeral-agent config swap — those have an undefined `agent_id`, so the+ * id check alone can't tell two ephemeral configs apart.+ */+/**+ * Request fields that determine the agent/graph + tool set, persisted with the pending+ * action so the resume can REPLAY them server-side. The client can't reliably re-send+ * these after a reload (e.g. the ephemeralAgent state resets), so replaying them from+ * the job guarantees the rebuilt run is the SAME graph the pause used — durable resume+ * works across reloads/replicas, and a crafted resume can't swap the tool set.+ */+export const RESUME_CONTEXT_KEYS = [+ 'endpoint',+ 'endpointType',+ 'agent_id',+ 'spec',+ 'model',+ 'promptPrefix',+ 'ephemeralAgent',+ // The agents build reads addedConvo into endpointOption to add parallel/secondary+ // agents; the resume POST can't reconstruct it, so replay it from the paused request.+ 'addedConvo',+ // Feeds temporal prompt vars ({{current_datetime}} etc.) via initializeAgent. The+ // resume POST omits it, so without replay a different-tz client (or none) compiles a+ // different system prompt than the paused graph. Replay-only — not in the fingerprint.+ 'timezone',+ // Manually-selected skills union their allowed-tools into the tool set before tools+ // load (initializeAgent → resolveManualSkills), so they're graph-determining. The+ // resume POST can't reliably re-send them after a reload; replay them, and the+ // delete-absent half of applyResumeContext stops a crafted resume from injecting a+ // different skill's tools (manualSkills isn't covered by the fingerprint). Replay-only.+ // (alwaysAppliedSkills is NOT here — it's resolved server-side from the DB, not req.body.)+ 'manualSkills',+] as const;++export type ResumeContext = Partial<Record<(typeof RESUME_CONTEXT_KEYS)[number], unknown>>;++/** Extract the graph-determining fields from a request body for durable replay. */+export function pickResumeContext(body: Record<string, unknown> | undefined | null): ResumeContext {+ const ctx: ResumeContext = {};+ if (body == null) {+ return ctx;+ }+ for (const key of RESUME_CONTEXT_KEYS) {+ if (body[key] !== undefined) {+ ctx[key] = body[key];+ }+ }+ return ctx;+}++/**+ * Replay a persisted resume context onto a request body so the rebuilt run matches the+ * paused one. Every graph-determining field is forced to the persisted value: a key the+ * context HAS overwrites whatever the client sent; a key it LACKS is deleted from the+ * body. The delete is the security half — without it, a field the paused turn never+ * carried (e.g. `addedConvo`, which {@link computeAgentRequestFingerprint} does NOT+ * cover) could be injected by a crafted resume to rebuild the paused single-agent+ * checkpoint as a different multi-agent graph/tool set.+ */+export function applyResumeContext(+ body: Record<string, unknown> | undefined | null,+ ctx: ResumeContext | undefined | null,+): void {+ if (body == null || ctx == null) {+ return;+ }+ for (const key of RESUME_CONTEXT_KEYS) {+ if (ctx[key] !== undefined) {+ body[key] = ctx[key];+ } else {+ delete body[key];+ }+ }+}++export function computeAgentRequestFingerprint(fields: AgentRequestFingerprintFields): string {+ const canonical = JSON.stringify({+ endpoint: fields.endpoint ?? null,+ endpointType: fields.endpointType ?? null,+ agent_id: fields.agent_id ?? null,+ model: fields.model ?? null,+ spec: fields.spec ?? null,+ promptPrefix: fields.promptPrefix ?? null,+ ephemeralAgent: normalizeEphemeralAgent(fields.ephemeralAgent),+ });+ return createHash('sha256').update(canonical).digest('hex');}/**@@ -146,5 +315,7 @@ export function buildPendingAction(expiresAt: typeof ctx.ttlMs === 'number' ? createdAt + ctx.ttlMs : undefined,interruptId: ctx.interruptId,threadId: ctx.threadId,+ requestFingerprint: ctx.requestFingerprint,+ resumeContext: ctx.resumeContext,};}diff --git a/packages/api/src/agents/hitl/resume.spec.ts b/packages/api/src/agents/hitl/resume.spec.tsnew file mode 100644index 0000000000..f164366cf7--- /dev/null+++ b/packages/api/src/agents/hitl/resume.spec.ts@@ -0,0 +1,171 @@+import type { Agents } from 'librechat-data-provider';+import {+ mapToolApprovalResolutions,+ mapAskUserAnswer,+ findUndecidedToolCalls,+ findDisallowedDecisions,+ findIncompleteDecisions,+} from './resume';++describe('mapToolApprovalResolutions', () => {+ test('maps each decision type to the SDK discriminated shape, keyed by tool_call_id', () => {+ const resolutions: Agents.ToolApprovalResolution[] = [+ { tool_call_id: 'a', decision: 'approve' },+ { tool_call_id: 'b', decision: 'reject', reason: 'no' },+ { tool_call_id: 'c', decision: 'edit', editedArguments: { x: 1 } },+ { tool_call_id: 'd', decision: 'respond', responseText: 'done' },+ ];++ expect(mapToolApprovalResolutions(resolutions)).toEqual({+ a: { type: 'approve' },+ b: { type: 'reject', reason: 'no' },+ c: { type: 'edit', updatedInput: { x: 1 } },+ d: { type: 'respond', responseText: 'done' },+ });+ });++ test('defaults missing edit args to {} and missing respond text to "" rather than throwing', () => {+ const resolutions: Agents.ToolApprovalResolution[] = [+ { tool_call_id: 'a', decision: 'edit' },+ { tool_call_id: 'b', decision: 'respond' },+ ];+ expect(mapToolApprovalResolutions(resolutions)).toEqual({+ a: { type: 'edit', updatedInput: {} },+ b: { type: 'respond', responseText: '' },+ });+ });++ test('fails closed (reject) on an unrecognized decision', () => {+ const resolutions = [+ { tool_call_id: 'a', decision: 'nonsense' as Agents.ToolApprovalDecisionType },+ ];+ expect(mapToolApprovalResolutions(resolutions)).toEqual({+ a: { type: 'reject', reason: 'Unrecognized approval decision' },+ });+ });++ test('last write wins when the same tool_call_id appears twice', () => {+ const resolutions: Agents.ToolApprovalResolution[] = [+ { tool_call_id: 'a', decision: 'approve' },+ { tool_call_id: 'a', decision: 'reject' },+ ];+ expect(mapToolApprovalResolutions(resolutions)).toEqual({ a: { type: 'reject' } });+ });+});++describe('mapAskUserAnswer', () => {+ test('passes the answer through unchanged', () => {+ expect(mapAskUserAnswer({ answer: 'staging' })).toEqual({ answer: 'staging' });+ });+});++describe('findUndecidedToolCalls', () => {+ const payload: Agents.ToolApprovalInterruptPayload = {+ type: 'tool_approval',+ action_requests: [+ { tool_call_id: 'a', name: 'read', arguments: {} },+ { tool_call_id: 'b', name: 'write', arguments: {} },+ ],+ review_configs: [],+ };++ test('returns the tool_call_ids with no decision', () => {+ expect(findUndecidedToolCalls(payload, [{ tool_call_id: 'a', decision: 'approve' }])).toEqual([+ 'b',+ ]);+ });++ test('returns [] when every requested tool call is decided', () => {+ expect(+ findUndecidedToolCalls(payload, [+ { tool_call_id: 'a', decision: 'approve' },+ { tool_call_id: 'b', decision: 'reject' },+ ]),+ ).toEqual([]);+ });++ test('ignores resolutions for tool calls not in the action', () => {+ expect(+ findUndecidedToolCalls(payload, [+ { tool_call_id: 'a', decision: 'approve' },+ { tool_call_id: 'b', decision: 'approve' },+ { tool_call_id: 'z', decision: 'approve' },+ ]),+ ).toEqual([]);+ });+});++describe('findDisallowedDecisions', () => {+ const payload: Agents.ToolApprovalInterruptPayload = {+ type: 'tool_approval',+ action_requests: [+ { tool_call_id: 'a', name: 'read', arguments: {} },+ { tool_call_id: 'b', name: 'write', arguments: {} },+ ],+ review_configs: [+ { action_name: 'read', tool_call_id: 'a', allowed_decisions: ['approve', 'reject'] },+ { action_name: 'write', tool_call_id: 'b', allowed_decisions: ['reject', 'respond'] },+ ],+ };++ test('returns [] when every decision is permitted by its review config', () => {+ expect(+ findDisallowedDecisions(payload, [+ { tool_call_id: 'a', decision: 'approve' },+ { tool_call_id: 'b', decision: 'respond', responseText: 'x' },+ ]),+ ).toEqual([]);+ });++ test('flags a decision the policy does not allow for that tool', () => {+ // `b` is restricted to reject/respond — approving it must be rejected.+ expect(+ findDisallowedDecisions(payload, [+ { tool_call_id: 'a', decision: 'approve' },+ { tool_call_id: 'b', decision: 'approve' },+ ]),+ ).toEqual(['b']);+ });++ test('fails closed for a tool_call_id with no matching review config', () => {+ expect(findDisallowedDecisions(payload, [{ tool_call_id: 'z', decision: 'approve' }])).toEqual([+ 'z',+ ]);+ });+});++describe('findIncompleteDecisions', () => {+ it('flags an edit decision without editedArguments', () => {+ expect(findIncompleteDecisions([{ tool_call_id: 'a', decision: 'edit' }])).toEqual(['a']);+ });++ it('flags an edit decision whose editedArguments is not a plain object', () => {+ expect(+ findIncompleteDecisions([+ {+ tool_call_id: 'a',+ decision: 'edit',+ editedArguments: [] as unknown as Record<string, unknown>,+ },+ ]),+ ).toEqual(['a']);+ });++ it('flags a respond decision without responseText (or empty)', () => {+ expect(findIncompleteDecisions([{ tool_call_id: 'a', decision: 'respond' }])).toEqual(['a']);+ expect(+ findIncompleteDecisions([{ tool_call_id: 'b', decision: 'respond', responseText: '' }]),+ ).toEqual(['b']);+ });++ it('accepts complete edit/respond and ignores approve/reject', () => {+ expect(+ findIncompleteDecisions([+ { tool_call_id: 'a', decision: 'edit', editedArguments: { q: 1 } },+ { tool_call_id: 'b', decision: 'respond', responseText: 'done' },+ { tool_call_id: 'c', decision: 'approve' },+ { tool_call_id: 'd', decision: 'reject', reason: 'no' },+ ]),+ ).toEqual([]);+ });+});diff --git a/packages/api/src/agents/hitl/resume.ts b/packages/api/src/agents/hitl/resume.tsnew file mode 100644index 0000000000..3f34331002--- /dev/null+++ b/packages/api/src/agents/hitl/resume.ts@@ -0,0 +1,119 @@+import type {+ ToolApprovalDecision,+ ToolApprovalDecisionMap,+ AskUserQuestionResolution,+} from '@librechat/agents';+import type { Agents } from 'librechat-data-provider';++/**+ * Translate the host-facing approval wire format into the SDK's resume value.+ *+ * The wire format ({@link Agents.ToolApprovalResolution}) is shaped for the UI —+ * a flat `decision` string plus optional `editedArguments` / `responseText`. The+ * SDK consumes a discriminated {@link ToolApprovalDecision} per tool call. This is+ * the single adapter between the two; the resume route maps once, here, instead of+ * branching on `decision` at the call site.+ *+ * Returns the map form (keyed by `tool_call_id`) so a batch that calls the same+ * tool twice resolves unambiguously — by-position ordering breaks with duplicates.+ */+export function mapToolApprovalResolutions(+ resolutions: readonly Agents.ToolApprovalResolution[],+): ToolApprovalDecisionMap {+ const decisions: ToolApprovalDecisionMap = {};+ for (const resolution of resolutions) {+ decisions[resolution.tool_call_id] = toSdkDecision(resolution);+ }+ return decisions;+}++function toSdkDecision(resolution: Agents.ToolApprovalResolution): ToolApprovalDecision {+ switch (resolution.decision) {+ case 'approve':+ return { type: 'approve' };+ case 'reject':+ return { type: 'reject', reason: resolution.reason };+ case 'edit':+ // `editedArguments` is required for edit on the wire; default to {} so a+ // malformed payload re-runs the tool with empty args rather than throwing.+ return { type: 'edit', updatedInput: resolution.editedArguments ?? {} };+ case 'respond':+ return { type: 'respond', responseText: resolution.responseText ?? '' };+ default:+ // Unknown decision (forward-compat / malformed): fail closed by rejecting,+ // never by silently approving a tool the user didn't sanction.+ return { type: 'reject', reason: 'Unrecognized approval decision' };+ }+}++/** Translate the ask-user wire answer into the SDK's resume value. */+export function mapAskUserAnswer(+ resolution: Agents.AskUserQuestionResolution,+): AskUserQuestionResolution {+ return { answer: resolution.answer };+}++/**+ * Validate that a set of resolutions covers exactly the tool calls a pending+ * `tool_approval` action is waiting on. Returns the list of `tool_call_id`s that+ * were requested but not decided (empty when the batch is fully resolved), so the+ * resume route can 400 a partial submission instead of driving a half-decided run.+ */+export function findUndecidedToolCalls(+ payload: Agents.ToolApprovalInterruptPayload,+ resolutions: readonly Agents.ToolApprovalResolution[],+): string[] {+ const decided = new Set(resolutions.map((r) => r.tool_call_id));+ return payload.action_requests.map((a) => a.tool_call_id).filter((id) => !decided.has(id));+}++/**+ * Enforce the policy's per-tool `allowed_decisions`. Returns the `tool_call_id`s+ * whose submitted decision is NOT one the interrupt's `review_configs` permits for+ * that tool — so the resume route can reject a crafted request that, e.g., approves+ * a tool the policy restricted to `reject`/`respond`. A resolution for a tool with+ * no matching review_config (shouldn't happen) is treated as disallowed (fail closed).+ */+export function findDisallowedDecisions(+ payload: Agents.ToolApprovalInterruptPayload,+ resolutions: readonly Agents.ToolApprovalResolution[],+): string[] {+ const allowedByToolCallId = new Map<string, Set<Agents.ToolApprovalDecisionType>>();+ for (const config of payload.review_configs) {+ allowedByToolCallId.set(config.tool_call_id, new Set(config.allowed_decisions));+ }+ return resolutions+ .filter((r) => !allowedByToolCallId.get(r.tool_call_id)?.has(r.decision))+ .map((r) => r.tool_call_id);+}++/**+ * Enforce that `edit` and `respond` decisions carry their required payload. Returns+ * the `tool_call_id`s whose decision is structurally incomplete:+ * - `edit` without an object `editedArguments`, or+ * - `respond` without a non-empty `responseText`.+ *+ * Without this, {@link toSdkDecision}'s defensive defaults (`{}` / `''`) would turn a+ * crafted or buggy submission into an empty tool input or an empty synthetic result —+ * resuming the run with behavior the user never actually approved. The route rejects+ * these (400) rather than mapping them.+ */+export function findIncompleteDecisions(+ resolutions: readonly Agents.ToolApprovalResolution[],+): string[] {+ return resolutions+ .filter((r) => {+ if (r.decision === 'edit') {+ return (+ r.editedArguments == null ||+ typeof r.editedArguments !== 'object' ||+ Array.isArray(r.editedArguments)+ );+ }+ if (r.decision === 'respond') {+ return typeof r.responseText !== 'string' || r.responseText.length === 0;+ }+ return false;+ })+ .map((r) => r.tool_call_id);+}diff --git a/packages/api/src/agents/hitl/runtime.spec.ts b/packages/api/src/agents/hitl/runtime.spec.tsnew file mode 100644index 0000000000..79d4ef05f6--- /dev/null+++ b/packages/api/src/agents/hitl/runtime.spec.ts@@ -0,0 +1,29 @@+import { HookRegistry } from '@librechat/agents';+import { buildHITLRunWiring } from './runtime';++describe('buildHITLRunWiring', () => {+ test('returns undefined when HITL is disabled (the default)', () => {+ expect(buildHITLRunWiring(undefined)).toBeUndefined();+ expect(buildHITLRunWiring({})).toBeUndefined();+ expect(buildHITLRunWiring({ enabled: false })).toBeUndefined();+ expect(buildHITLRunWiring({ mode: 'default', allow: ['read_*'] })).toBeUndefined();+ });++ test('returns the run wiring when enabled', () => {+ const wiring = buildHITLRunWiring({ enabled: true });+ expect(wiring).toBeDefined();+ expect(wiring?.humanInTheLoop).toEqual({ enabled: true });+ expect(wiring?.hooks).toBeInstanceOf(HookRegistry);+ });++ test('registers exactly one PreToolUse policy hook', () => {+ const wiring = buildHITLRunWiring({ enabled: true, mode: 'bypass', allow: ['x'] });+ const matchers = wiring?.hooks.getMatchers('PreToolUse') ?? [];+ expect(matchers).toHaveLength(1);+ });++ test('an enabled policy with no lists still wires (every tool falls through to ask)', () => {+ const wiring = buildHITLRunWiring({ enabled: true });+ expect(wiring?.hooks.getMatchers('PreToolUse')).toHaveLength(1);+ });+});diff --git a/packages/api/src/agents/hitl/runtime.ts b/packages/api/src/agents/hitl/runtime.tsnew file mode 100644index 0000000000..bbc350fc3d--- /dev/null+++ b/packages/api/src/agents/hitl/runtime.ts@@ -0,0 +1,41 @@+import { HookRegistry, createToolPolicyHook } from '@librechat/agents';+import type { TToolApprovalPolicy } from 'librechat-data-provider';+import { isHITLEnabled, mapToolApprovalPolicy } from './policy';++/**+ * The HITL fragment spread onto a `RunConfig` when tool approval is enabled.+ *+ * Kept as one object so the run seam attaches the opt-in switch and the policy+ * hook together — they're meaningless apart. The checkpointer is resolved+ * separately (it's an async, process-wide singleton) and merged into+ * `graphConfig.compileOptions` at the call site.+ */+export interface HITLRunWiring {+ humanInTheLoop: { enabled: true };+ hooks: HookRegistry;+}++/**+ * Assemble the run-level HITL wiring for a tool-approval policy, or `undefined`+ * when HITL is disabled (the default) — in which case the run attaches nothing+ * and behaves exactly as it did before this feature.+ *+ * The returned `hooks` registry carries a single `PreToolUse` policy hook built+ * from {@link mapToolApprovalPolicy}. An enabled policy with no allow/deny/ask+ * lists falls through to `mode: 'default'`, i.e. every tool prompts — the safe+ * default for "HITL on, nothing else specified".+ */+export function buildHITLRunWiring(+ policy: TToolApprovalPolicy | undefined,+): HITLRunWiring | undefined {+ if (!isHITLEnabled(policy)) {+ return undefined;+ }++ const registry = new HookRegistry();+ registry.register('PreToolUse', {+ hooks: [createToolPolicyHook(mapToolApprovalPolicy(policy) ?? {})],+ });++ return { humanInTheLoop: { enabled: true }, hooks: registry };+}diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex a94eb39d9d..28c70bb538 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -3,6 +3,7 @@ export * from './attachments';export * from './chain';export * from './client';export * from './config';+export * from './checkpointer';export * from './contact';export * from './context';export * from './discovery';diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.tsindex e23f8270e9..810b56e1e3 100644--- a/packages/api/src/agents/run.ts+++ b/packages/api/src/agents/run.ts@@ -36,9 +36,12 @@ import type { SubagentUsageEvent } from '~/agents/usage';import type * as t from '~/types';import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';import { getProviderConfig } from '~/endpoints/config/providers';+import { resolveToolApprovalPolicy } from '~/agents/hitl/policy';import { extractDefaultParams } from '~/endpoints/openai/llm';import { resolveHeaders, createSafeUser } from '~/utils/env';+import { getAgentCheckpointer } from '~/agents/checkpointer';import { getOpenAIConfig } from '~/endpoints/openai/config';+import { buildHITLRunWiring } from '~/agents/hitl/runtime';import { buildLangfuseConfig } from '~/langfuse/config';import { resolveConfigHeaders } from '~/utils/headers';import { applyTestRunHook } from '~/agents/testHook';@@ -870,6 +873,7 @@ export async function createRun({signal,agents,messages,+ discoveredToolNames,requestBody,user,tenantId,@@ -882,6 +886,7 @@ export async function createRun({calibrationRatio,appConfig,subagentUsageSink,+ hitlCapable = false,streaming = true,streamUsage = true,}: {@@ -895,6 +900,16 @@ export async function createRun({tenantId?: string;/** Message history for extracting previously discovered tools */messages?: BaseMessage[];+ /**+ * Pre-discovered deferred-tool names to force-load directly, bypassing message+ * extraction. The HITL resume path rebuilds the graph with `messages: []` (state+ * comes from the durable checkpoint), so the in-turn `tool_search` results that+ * would normally mark a deferred tool discovered aren't present — without this the+ * paused tool would be absent from the rebuilt schema-only toolMap and resume would+ * fail with "unknown tool". Captured at pause via `extractDiscoveredToolsFromHistory`+ * and replayed here. Merged with (not replacing) any names extracted from `messages`.+ */+ discoveredToolNames?: string[];summarizationConfig?: SummarizationConfig;/** Cross-run summary from formatAgentMessages, forwarded to AgentContext */initialSummary?: { text: string; tokenCount: number };@@ -914,6 +929,15 @@ export async function createRun({* Switch to the `RunConfig` pick once the dependency is bumped.*/subagentUsageSink?: (event: SubagentUsageEvent) => void;+ /**+ * Whether the caller implements the HITL pause/resume lifecycle (inspects+ * `run.getInterrupt()`, persists a pending action, exposes a resume route). Gates the+ * tool-approval wiring: only AgentClient (chat + resume) sets this. The OpenAI-compatible+ * and Responses controllers leave it false, so an approval-gated tool can't pause on a+ * route that has no approval surface or resume endpoint (it would otherwise emit a normal+ * final response / `[DONE]` with the tool call left unresolved).+ */+ hitlCapable?: boolean;} & Pick<RunConfig,'tokenCounter' | 'customHandlers' | 'indexTokenCountMap' | 'initialSessions'@@ -928,10 +952,22 @@ export async function createRun({*/const hasAnyDeferredTools = agents.some((agent) => agent.hasDeferredTools === true);- const discoveredTools =- hasAnyDeferredTools && messages?.length- ? extractDiscoveredToolsFromHistory(messages)- : new Set<string>();+ const discoveredTools = new Set<string>();+ if (hasAnyDeferredTools) {+ // Normal path: extract from this run's message history (tool_search results).+ if (messages?.length) {+ for (const name of extractDiscoveredToolsFromHistory(messages)) {+ discoveredTools.add(name);+ }+ }+ // Resume path: replay names captured at pause, since `messages` is empty (the+ // paused run's tool_search results live only in the checkpoint, not here).+ if (discoveredToolNames?.length) {+ for (const name of discoveredToolNames) {+ discoveredTools.add(name);+ }+ }+ }const buildAgentInput = (agent: RunAgent, opts: { isSubagent?: boolean } = {}): AgentInputs => {const isSubagent = opts.isSubagent === true;@@ -1134,6 +1170,34 @@ export async function createRun({*/const enableToolOutputReferences = anyAgentHasCodeEnv(agents);+ /**+ * Human-in-the-loop tool approval — OFF by default. When the agents endpoint+ * opts in (`toolApproval.enabled`), attach the `PreToolUse` policy hook + the+ * `humanInTheLoop` switch, and bind a durable checkpointer so a run that pauses+ * for review can be rebuilt and resumed on any worker (see `agents/checkpointer.ts`+ * and the resume route). When disabled, nothing attaches and the run is identical+ * to before this feature shipped.+ */+ const agentsEndpointConfig = appConfig?.endpoints?.[EModelEndpoint.agents];+ // Resolve the effective policy through the single seam so per-agent / per-skill+ // sources can layer in later without touching this call site (see+ // `resolveToolApprovalPolicy`). Only the endpoint layer is wired today, so this+ // is identical to reading `toolApproval` directly.+ const toolApprovalPolicy = resolveToolApprovalPolicy({+ endpoint: agentsEndpointConfig?.toolApproval,+ });+ // Gate HITL to callers that actually implement the pause/resume lifecycle. The+ // OpenAI-compatible + Responses controllers also call createRun/processStream but never+ // inspect `run.getInterrupt()` or persist a pending action — so an approval-gated tool+ // would pause with no approval surface or resume endpoint, and the route would emit a+ // normal final response / `[DONE]` with the tool call dangling. Only AgentClient (chat ++ // resume) passes `hitlCapable`; without it the run is identical to the no-HITL path.+ const hitl = hitlCapable ? buildHITLRunWiring(toolApprovalPolicy) : undefined;+ if (hitl) {+ const checkpointer = await getAgentCheckpointer(agentsEndpointConfig?.checkpointer);+ graphConfig.compileOptions = { ...graphConfig.compileOptions, checkpointer };+ }+/*** Built as a variable (not an inline literal) so the extra* `subagentUsageSink` field passes assignability against SDK versions@@ -1159,6 +1223,10 @@ export async function createRun({...(enableToolOutputReferences && {toolOutputReferences: { enabled: true },}),+ // HITL opt-in: the `humanInTheLoop` switch + the PreToolUse policy hook. Spread+ // here (not just `compileOptions.checkpointer` above) so an `ask` decision raises+ // a real interrupt — without these the run would never pause. Absent when disabled.+ ...(hitl && { humanInTheLoop: hitl.humanInTheLoop, hooks: hitl.hooks }),};const run = await Run.create(runConfig);diff --git a/packages/api/src/middleware/messageFilterPii.spec.ts b/packages/api/src/middleware/messageFilterPii.spec.tsindex c67227ff2d..fc5c4f3ff6 100644--- a/packages/api/src/middleware/messageFilterPii.spec.ts+++ b/packages/api/src/middleware/messageFilterPii.spec.ts@@ -89,6 +89,47 @@ describe('messageFilterPii middleware', () => {expect(capturedRes.status).toBe(400);});+ const SK = 'sk-proj-FAKE1234567890ABCDEF';++ it('rejects a resume ask-user answer containing a blocked token', () => {+ const { capturedRes, nextCalls } = runMiddleware({}, { answer: `the key is ${SK}` });+ expect(nextCalls).toBe(0);+ expect(capturedRes.status).toBe(400);+ });++ it('rejects a tool-approval decision responseText containing a blocked token', () => {+ const { capturedRes, nextCalls } = runMiddleware(+ {},+ { decisions: [{ tool_call_id: 'a', decision: 'respond', responseText: `use ${SK}` }] },+ );+ expect(nextCalls).toBe(0);+ expect(capturedRes.status).toBe(400);+ });++ it('rejects a reject-reason containing a blocked token', () => {+ const { capturedRes, nextCalls } = runMiddleware(+ {},+ { decisions: [{ tool_call_id: 'a', decision: 'reject', reason: `leaked ${SK}` }] },+ );+ expect(nextCalls).toBe(0);+ expect(capturedRes.status).toBe(400);+ });++ it('rejects edited tool arguments containing a blocked token (stringified)', () => {+ const { capturedRes, nextCalls } = runMiddleware(+ {},+ { decisions: [{ tool_call_id: 'a', decision: 'edit', editedArguments: { token: SK } }] },+ );+ expect(nextCalls).toBe(0);+ expect(capturedRes.status).toBe(400);+ });++ it('passes a clean resume answer through', () => {+ const { capturedRes, nextCalls } = runMiddleware({}, { answer: 'name it report.pdf' });+ expect(nextCalls).toBe(1);+ expect(capturedRes.status).toBeUndefined();+ });+it('honors a starterPatterns subset (sk passes when only bearer is enabled)', () => {const { capturedRes, nextCalls } = runMiddleware({ starterPatterns: ['bearer_header'] },diff --git a/packages/api/src/middleware/messageFilterPii.ts b/packages/api/src/middleware/messageFilterPii.tsindex ff322cba8f..b2140950c9 100644--- a/packages/api/src/middleware/messageFilterPii.ts+++ b/packages/api/src/middleware/messageFilterPii.ts@@ -141,6 +141,36 @@ export function createMessageFilterPii(options: CreateMessageFilterPiiOptions):candidates.push(...quotes);candidates.push(mergeQuotedText(text, quotes));}+ /**+ * The shared `/agents/chat/resume` route carries user-authored text in different+ * fields than a typed message: an ask-user `answer`, and a tool-approval decision's+ * `respond` text, `reject` reason, and edited tool arguments. Scan them too — else a+ * blocked token could ride a resume payload straight back into the model/tool,+ * bypassing the filter the typed path enforces.+ */+ if (typeof req.body?.answer === 'string' && req.body.answer.length > 0) {+ candidates.push(req.body.answer);+ }+ if (Array.isArray(req.body?.decisions)) {+ for (const decision of req.body.decisions) {+ if (typeof decision?.responseText === 'string' && decision.responseText.length > 0) {+ candidates.push(decision.responseText);+ }+ if (typeof decision?.reason === 'string' && decision.reason.length > 0) {+ candidates.push(decision.reason);+ }+ if (decision?.editedArguments != null) {+ try {+ const edited = JSON.stringify(decision.editedArguments);+ if (edited.length > 0) {+ candidates.push(edited);+ }+ } catch {+ /* ignore unstringifiable edited args */+ }+ }+ }+ }if (candidates.length === 0) {next();return;diff --git a/packages/api/src/stream/GenerationJobManager.ts b/packages/api/src/stream/GenerationJobManager.tsindex 1986641189..1509335276 100644--- a/packages/api/src/stream/GenerationJobManager.ts+++ b/packages/api/src/stream/GenerationJobManager.ts@@ -2,6 +2,7 @@ import { logger, getTenantId, SYSTEM_TENANT_ID } from '@librechat/data-schemas';import {Constants,UsageEvents,+ ApprovalEvents,parseTextParts,reconcileContextUsage,promptTokensFromUsage,@@ -28,12 +29,15 @@ import {setGenerationJobsInFlight,recordGenerationJob,} from '~/app/metrics';+import { isPendingActionStale, isPendingActionExpired } from './interfaces/IJobStore';import { InMemoryEventTransport } from './implementations/InMemoryEventTransport';import { InMemoryJobStore } from './implementations/InMemoryJobStore';import { filterPersistableAbortContent } from './abortContent';-import { isPendingActionStale } from './interfaces/IJobStore';import { ApprovalLifecycle } from './ApprovalLifecycle';+/** Terminal error surfaced to a client still attached when its approval window lapses. */+const APPROVAL_EXPIRED_ERROR = 'Approval expired before a decision was made';+/** Error surfaced to any client still attached when a stale/hung job is reaped. */const REAPED_JOB_ERROR = 'Generation timed out';const OAUTH_TOOL_CALL_PREFIX = `oauth${Constants.mcp_delimiter}`;@@ -492,6 +496,14 @@ class GenerationJobManagerClass {iconURL: jobData.iconURL,model: jobData.model,promptTokens: jobData.promptTokens,+ // Surface the originating agent so the resume route can refuse to rebuild a+ // paused run on a different agent.+ agent_id: jobData.agent_id,+ // Surface whether the turn was temporary so a resume keeps it non-persisted.+ isTemporary: jobData.isTemporary,+ // Surface deferred tools discovered before the pause so the resume route can+ // replay them into createRun (the rebuilt graph passes `messages: []`).+ discoveredTools: jobData.discoveredTools,// Surface the pending review so status/resume routes built on the// facade can render the prompt for a `requires_action` job.pendingAction: jobData.pendingAction,@@ -1052,6 +1064,31 @@ class GenerationJobManagerClass {skipBufferReplay: true,});+ // Close the snapshot→subscribe race: getResumeState() snapshots BEFORE we attach the+ // subscription, so a pause that becomes durable in that window is in neither+ // resumeState.pendingAction nor (Redis mode) pendingEvents — and trackReplayEvent does+ // not persist approval events — leaving the client attached to a paused job with no+ // approval UI. Re-read the live job AFTER subscribing; if it is now requires_action and+ // the snapshot didn't already carry the action, surface it as a pending event so the+ // approval prompt renders. Idempotent: a pause landing AFTER attach is delivered live+ // too, and the client's handler just sets the current action, so a duplicate is benign.+ if (!resumeState?.pendingAction) {+ const liveJob = await this.jobStore.getJob(streamId);+ if (+ liveJob?.status === 'requires_action' &&+ liveJob.pendingAction != null &&+ !isPendingActionStale(liveJob)+ ) {+ pendingEvents = [+ ...pendingEvents,+ {+ event: ApprovalEvents.ON_PENDING_ACTION,+ data: liveJob.pendingAction as unknown as Record<string, unknown>,+ },+ ];+ }+ }+return { subscription, resumeState, pendingEvents };}@@ -1351,6 +1388,11 @@ class GenerationJobManagerClass {}const { message } = event;+ const extra = message as {+ manualSkills?: string[];+ alwaysAppliedSkills?: string[];+ files?: unknown[];+ };const updates: Partial<SerializableJobData> = {createdEventEmitted: true,userMessage: {@@ -1359,6 +1401,19 @@ class GenerationJobManagerClass {conversationId: message.conversationId,text: message.text,quotes: message.quotes,+ // Persist the turn's uploaded files so a HITL resume sources them from the job+ // (this authoritative writer), not a user DB row whose save can still be racing+ // the approval prompt.+ ...(Array.isArray(extra.files) && extra.files.length > 0 && { files: extra.files }),+ // Carry skill selections so a HITL resume's reconstructed requestMessage keeps+ // its pills — this is the authoritative writer of job.metadata.userMessage and+ // would otherwise drop them (the emitted created message includes them).+ ...(Array.isArray(extra.manualSkills) &&+ extra.manualSkills.length > 0 && { manualSkills: extra.manualSkills }),+ ...(Array.isArray(extra.alwaysAppliedSkills) &&+ extra.alwaysAppliedSkills.length > 0 && {+ alwaysAppliedSkills: extra.alwaysAppliedSkills,+ }),},};@@ -1398,9 +1453,18 @@ class GenerationJobManagerClass {if (metadata.model) {updates.model = metadata.model;}+ if (metadata.agent_id) {+ updates.agent_id = metadata.agent_id;+ }+ if (metadata.isTemporary !== undefined) {+ updates.isTemporary = metadata.isTemporary;+ }if (metadata.promptTokens !== undefined) {updates.promptTokens = metadata.promptTokens;}+ if (metadata.discoveredTools) {+ updates.discoveredTools = metadata.discoveredTools;+ }await this.jobStore.updateJob(streamId, updates);}@@ -1598,7 +1662,97 @@ class GenerationJobManagerClass {* Cleanup expired jobs.* Also cleans up any orphaned runtime state, buffers, and event transport entries.*/+ /**+ * Expire any locally-tracked approval whose window has lapsed: drive the atomic+ * `requires_action → aborted` transition and, if this caller won it, emit a+ * terminal error so a connected SSE client closes. Only streams this replica has+ * runtime for are scanned — those are exactly the ones with a client subscribed+ * here; a paused job on another replica is finalized by that replica's sweep (and+ * the store's own cleanup). The durable checkpoint is reclaimed by its Mongo TTL+ * index, which shares the approval window, so no cross-layer delete is needed here.+ */+ /**+ * Expire a single observed-stale pending approval NOW (immediate, not via the periodic+ * sweep): run the `requires_action → aborted` CAS — pinned to `actionId` so a concurrent+ * resolve + re-pause on a fresh action isn't aborted — and, on success, emit the terminal+ * `APPROVAL_EXPIRED_ERROR` so any attached SSE client gets a terminal event instead of a+ * hung stream. Used by the periodic sweeper and by the resume route, which observes a+ * just-expired action when the user submits a decision after the TTL lapsed. Returns true+ * if this call expired the action.+ */+ async expireApproval(streamId: string, actionId?: string): Promise<boolean> {+ const expired = await this._approvals.expire(streamId, actionId);+ if (!expired) {+ return false;+ }+ try {+ await this.emitError(streamId, APPROVAL_EXPIRED_ERROR);+ } catch (err) {+ logger.error(`[GenerationJobManager] Failed to notify expired approval ${streamId}`, err);+ }+ this.runningJobs.delete(streamId);+ return true;+ }++ private async expireStaleApprovals(): Promise<void> {+ let changed = false;+ for (const streamId of this.runtimeState.keys()) {+ let job: SerializableJobData | null;+ try {+ job = await this.jobStore.getJob(streamId);+ } catch (err) {+ logger.error(+ `[GenerationJobManager] Failed to read job during approval expiry sweep: ${streamId}`,+ err,+ );+ continue;+ }+ // Loser-replica relay: in a multi-replica deployment another replica's store+ // cleanup (`cleanupRequiresActionIndex`) can win the requires_action → aborted+ // approval-expiry CAS — it sets the hash error but cannot emit (the store has no+ // event transport). A client subscribed on THIS replica would then never get a+ // terminal event until the reap path. If the job is already aborted *for approval+ // expiry* and we haven't emitted here, relay the terminal error to our subscriber.+ // The `errorEvent` flag (set by emitError) keeps this idempotent vs the win path.+ const runtime = this.runtimeState.get(streamId);+ if (+ job?.status === 'aborted' &&+ job.error === APPROVAL_EXPIRED_ERROR &&+ !runtime?.errorEvent+ ) {+ try {+ await this.emitError(streamId, APPROVAL_EXPIRED_ERROR);+ } catch (err) {+ logger.error(`[GenerationJobManager] Failed to relay expired approval ${streamId}`, err);+ }+ changed = this.runningJobs.delete(streamId) || changed;+ continue;+ }+ if (!job || job.status !== 'requires_action' || !isPendingActionExpired(job)) {+ continue;+ }+ // Pass the OBSERVED action id so the expire CAS only fires for the action we read+ // as stale. Between this read and the CAS, the user could resolve it and the run+ // re-pause on a fresh action; without the id, the CAS (status-only) would abort+ // that valid new pause and leave it terminal.+ const didExpire = await this.expireApproval(streamId, job.pendingAction?.actionId);+ if (!didExpire) {+ continue;+ }+ changed = true;+ logger.debug(`[GenerationJobManager] Expired pending approval: ${streamId}`);+ }+ if (changed) {+ this.syncRunningJobMetrics();+ }+ }+private async cleanup(): Promise<void> {+ // Finalize approvals whose window lapsed before the store's own cleanup, so a+ // client still attached to a paused stream gets a terminal event instead of a+ // connection that hangs open until it gives up.+ await this.expireStaleApprovals();+const count = await this.jobStore.cleanup();let runningJobsChanged = false;diff --git a/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts b/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.tsindex 55229ebc5e..5dd3cfb164 100644--- a/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts+++ b/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts@@ -287,6 +287,184 @@ describe('RedisJobStore Integration Tests', () => {await store.destroy();});+ test('appendChunk preserves a paused job’s extended TTL (does not reset to running)', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient, { runningTtl: 60 });+ await store.initialize();++ const streamId = `paused-chunk-ttl-${Date.now()}`;+ const chunkKey = `stream:{${streamId}}:chunks`;++ await store.createJob(streamId, 'user-1', streamId);+ await store.appendChunk(streamId, { event: 'on_message_delta', data: { text: 'hello' } });++ // Pause: transitionStatus extends the chunk-key TTL to the long approval window.+ await store.transitionStatus(streamId, {+ from: 'running',+ to: 'requires_action',+ patch: { pendingAction: buildPendingAction(streamId) },+ });+ expect(await ioredisClient.ttl(chunkKey)).toBeGreaterThan(60);++ // The on_pending_action chunk is appended AFTER the pause. The bug Codex flagged was+ // that appendChunk unconditionally reset the TTL back to the (short) running TTL,+ // evicting the pre-pause content before resume. It must now leave the long TTL intact.+ await store.appendChunk(streamId, {+ event: 'on_pending_action',+ data: buildPendingAction(streamId),+ });+ expect(await ioredisClient.ttl(chunkKey)).toBeGreaterThan(60);+ // The chunk was still appended (XADD ran), so resume can read the full stream.+ expect(await ioredisClient.xlen(chunkKey)).toBeGreaterThanOrEqual(2);++ await store.destroy();+ });++ test('saveRunSteps preserves a paused job’s extended TTL (does not reset to running)', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient, { runningTtl: 60 });+ await store.initialize();++ const streamId = `paused-runsteps-ttl-${Date.now()}`;+ const runStepsKey = `stream:{${streamId}}:runsteps`;++ await store.createJob(streamId, 'user-1', streamId);+ await store.saveRunSteps!(streamId, [{ id: 'step-1', type: 'tool_call' }] as never);++ // Pause: transitionStatus extends the run-steps key TTL to the long approval window.+ await store.transitionStatus(streamId, {+ from: 'running',+ to: 'requires_action',+ patch: { pendingAction: buildPendingAction(streamId) },+ });+ expect(await ioredisClient.ttl(runStepsKey)).toBeGreaterThan(60);++ // A run-step save landing AFTER the pause must NOT reset the key to the running TTL,+ // or a reload of the still-live approval after that window loses the tool timeline.+ await store.saveRunSteps!(streamId, [+ { id: 'step-1', type: 'tool_call' },+ { id: 'step-2', type: 'tool_call' },+ ] as never);+ expect(await ioredisClient.ttl(runStepsKey)).toBeGreaterThan(60);+ // The save still landed, so resume can read the full timeline.+ const steps = await store.getRunSteps(streamId);+ expect(steps.length).toBe(2);++ await store.destroy();+ });++ test('appendChunk gives the approval TTL when the chunk key did not exist at pause time', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient, { runningTtl: 60 });+ await store.initialize();++ const streamId = `paused-no-chunk-${Date.now()}`;+ const chunkKey = `stream:{${streamId}}:chunks`;++ // The job pauses BEFORE any chunk was persisted (ask-user pause with no prior+ // delta, or the first appendChunk still in flight because emitChunk is+ // fire-and-forget). The pause's `EXPIRE chunks` is a no-op because the key+ // does not exist yet, so the chunk stream carries no extended TTL.+ await store.createJob(streamId, 'user-1', streamId);+ await store.transitionStatus(streamId, {+ from: 'running',+ to: 'requires_action',+ patch: { pendingAction: buildPendingAction(streamId) },+ });+ expect(await ioredisClient.exists(chunkKey)).toBe(0);++ // The first chunk lands AFTER the pause. The bug Codex re-raised: appendChunk+ // would create the stream with only the short running TTL (60s), so the+ // aggregated tool-call content is evicted before the 24h approval window ends.+ // The fix reads the paused window from the job key and bumps the chunk TTL to it.+ await store.appendChunk(streamId, {+ event: 'on_pending_action',+ data: buildPendingAction(streamId),+ });++ expect(await ioredisClient.ttl(chunkKey)).toBeGreaterThan(60);+ expect(await ioredisClient.xlen(chunkKey)).toBeGreaterThanOrEqual(1);++ await store.destroy();+ });++ test('appendChunk keeps a normally-running job on the short running TTL (no inflation)', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient, { runningTtl: 60 });+ await store.initialize();++ const streamId = `running-no-inflate-${Date.now()}`;+ const chunkKey = `stream:{${streamId}}:chunks`;++ // A normal running job: the job key carries the running TTL (set by createJob),+ // NOT the long approval window. appendChunk must settle the chunk TTL on the+ // short running TTL — never max it against the job key — so a live stream is+ // not inflated to the 24h approval window.+ await store.createJob(streamId, 'user-1', streamId);+ await store.appendChunk(streamId, {+ event: 'on_message_delta',+ data: { text: 'hello' },+ });++ const ttl = await ioredisClient.ttl(chunkKey);+ expect(ttl).toBeGreaterThan(0);+ expect(ttl).toBeLessThanOrEqual(60);++ await store.destroy();+ });++ test('createJob clears stale per-turn identity (agent_id, isTemporary) from a reused hash', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `stale-agent-${Date.now()}`;+ // Turn 1: a saved agent in a temporary chat that discovered a deferred tool.+ await store.createJob(streamId, 'user-1', streamId);+ await store.updateJob(streamId, {+ agent_id: 'saved-agent-1',+ isTemporary: true,+ discoveredTools: ['deep_tool'],+ });+ const turn1 = await store.getJob(streamId);+ expect(turn1?.agent_id).toBe('saved-agent-1');+ expect(turn1?.isTemporary).toBe(true);+ expect(turn1?.discoveredTools).toEqual(['deep_tool']);++ // Turn 2 on the SAME conversation switches to an ephemeral / non-temporary turn.+ // The hash is keyed by conversationId, so without clearing, the old agent_id and+ // isTemporary would survive — the resume guard would reject the valid pause as a+ // different agent, and the resumed response would be saved as temporary. The stale+ // discoveredTools would also force-load deferred tools this turn never discovered.+ await store.createJob(streamId, 'user-1', streamId);+ const turn2 = await store.getJob(streamId);+ expect(turn2?.agent_id).toBeUndefined();+ expect(turn2?.isTemporary).toBeUndefined();+ expect(turn2?.discoveredTools).toBeUndefined();++ await store.destroy();+ });+test('should not drop paused jobs from user tracking when cleanup sees a stale running index', async () => {if (!ioredisClient) {return;diff --git a/packages/api/src/stream/__tests__/pendingAction.spec.ts b/packages/api/src/stream/__tests__/pendingAction.spec.tsindex de4136a513..4edfed9619 100644--- a/packages/api/src/stream/__tests__/pendingAction.spec.ts+++ b/packages/api/src/stream/__tests__/pendingAction.spec.ts@@ -172,6 +172,21 @@ describe('ApprovalLifecycle via GenerationJobManager.approvals (in-memory)', ()expect(await manager.approvals.expire(streamId)).toBe(false);});+ test('a mismatched expectedActionId no-ops (protects a re-paused action from a stale sweep)', async () => {+ const streamId = 'stream-expire-mismatch';+ await manager.createJob(streamId, 'user-1');+ await manager.approvals.pause(streamId, buildAction(streamId, { actionId: 'action-A' }));++ // A sweep that observed an OLDER (now-resolved) action must not abort the current+ // pause — its CAS only fires when the live pendingActionId still matches.+ expect(await manager.approvals.expire(streamId, 'stale-other-action')).toBe(false);+ expect(await manager.getJobStatus(streamId)).toBe('requires_action');++ // The matching id still expires it.+ expect(await manager.approvals.expire(streamId, 'action-A')).toBe(true);+ expect(await manager.getJobStatus(streamId)).toBe('aborted');+ });+test('sets completedAt so terminal cleanup can reclaim the job', async () => {const streamId = 'stream-expire-completed';await manager.createJob(streamId, 'user-1');@@ -249,3 +264,88 @@ describe('InMemoryJobStore — approval expiry cleanup', () => {expect(await store.getJob('s1')).toBeNull();});});++describe('GenerationJobManager HITL resume metadata (round 19)', () => {+ let manager: GenerationJobManagerClass;++ beforeEach(() => {+ manager = new GenerationJobManagerClass();+ manager.configure({+ jobStore: new InMemoryJobStore({ ttlAfterComplete: 60000 }),+ eventTransport: new InMemoryEventTransport(),+ isRedis: false,+ cleanupOnComplete: false,+ });+ manager.initialize();+ });++ afterEach(async () => {+ await manager.destroy();+ });++ function buildAction(streamId: string) {+ const payload = buildToolApprovalPayload([+ { name: 'shell', arguments: { command: 'ls' }, tool_call_id: 'call_abc' },+ ]);+ return buildPendingAction(payload, {+ streamId,+ conversationId: streamId,+ runId: 'run-1',+ responseMessageId: 'msg-1',+ });+ }++ // H1: round-18 captured discoveredTools but the metadata allowlists (updateMetadata,+ // Redis deserialize, buildJobFacade) dropped it, so resume replayed `undefined`.+ test('updateMetadata persists discoveredTools and the job facade exposes them', async () => {+ const streamId = 'stream-discovered';+ await manager.createJob(streamId, 'user-1');+ await manager.updateMetadata(streamId, { discoveredTools: ['deep_tool', 'other_tool'] });+ const job = await manager.getJob(streamId);+ expect(job?.metadata.discoveredTools).toEqual(['deep_tool', 'other_tool']);+ });++ // H4: a pause that lands AFTER the resume snapshot but before the subscription must+ // still reach the client. subscribeWithResume re-reads the live job and surfaces it.+ test('subscribeWithResume surfaces a pause that the resume snapshot missed', async () => {+ const streamId = 'stream-race';+ await manager.createJob(streamId, 'user-1');+ const action = buildAction(streamId);+ await manager.approvals.pause(streamId, action);++ // Simulate the snapshot being taken BEFORE the pause: drop pendingAction from the+ // resume state even though the live job is now requires_action.+ const realGetResumeState = manager.getResumeState.bind(manager);+ jest.spyOn(manager, 'getResumeState').mockImplementation(async (id: string) => {+ const state = await realGetResumeState(id);+ return state ? { ...state, pendingAction: undefined } : state;+ });++ const result = await manager.subscribeWithResume(streamId, () => {});+ const pending = result.pendingEvents.find(+ (e) => 'event' in e && e.event === 'on_pending_action',+ );+ expect(pending).toBeDefined();+ expect((pending as unknown as { data: { actionId: string } }).data.actionId).toBe(+ action.actionId,+ );+ result.subscription?.unsubscribe();+ });++ // H4 negative: when the snapshot already carried the action, the re-read is skipped+ // (the client gets it via resumeState.pendingAction) — no duplicate pending event.+ test('does not re-surface the pending action when the snapshot already carried it', async () => {+ const streamId = 'stream-norace';+ await manager.createJob(streamId, 'user-1');+ const action = buildAction(streamId);+ await manager.approvals.pause(streamId, action);++ const result = await manager.subscribeWithResume(streamId, () => {});+ const pendingCount = result.pendingEvents.filter(+ (e) => 'event' in e && e.event === 'on_pending_action',+ ).length;+ expect(pendingCount).toBe(0);+ expect(result.resumeState?.pendingAction?.actionId).toBe(action.actionId);+ result.subscription?.unsubscribe();+ });+});diff --git a/packages/api/src/stream/implementations/RedisJobStore.ts b/packages/api/src/stream/implementations/RedisJobStore.tsindex 32d78ee487..6453ab4dcb 100644--- a/packages/api/src/stream/implementations/RedisJobStore.ts+++ b/packages/api/src/stream/implementations/RedisJobStore.ts@@ -39,6 +39,71 @@ const JOB_CAS_LUA ='redis.call("EXPIRE", KEYS[1], ttl) ' +'return 1';+/**+ * XADD a chunk + set the chunk-stream TTL to the right window WITHOUT ever shrinking it.+ *+ * During a live stream the running TTL is refreshed on every chunk. But a job paused+ * for HITL review must keep its chunk stream alive for the whole approval window, not+ * the ~20m running TTL — otherwise the pre-pause aggregated content (tool call + earlier+ * text) is evicted before the user resolves and `getResumeState()` loses it.+ *+ * `transitionStatus` extends the chunk-key TTL to the approval window at pause time, but+ * that alone is not enough:+ * 1. The pause's `EXPIRE chunks` is a no-op if the chunk key does not exist yet — and+ * `appendChunk` is fire-and-forget, so the first chunk's XADD can land AFTER the+ * pause, or an ask-user pause can occur before any chunk was ever persisted.+ * 2. The `on_pending_action` chunk (and any chunk that races in after the pause) would+ * otherwise reset an already-extended TTL back to the short running TTL.+ * So this script derives the target window itself: the running TTL normally, but when the+ * job hash is paused (`status == "requires_action"`) it takes the larger of the running+ * TTL and the job key's own remaining TTL (which `transitionStatus` set to the approval+ * window). It only ever EXTENDS — `cur < target` — so a normally-running stream keeps the+ * round-10 extend-only behavior and is never inflated to the approval window.+ *+ * Reading the paused window from the job key (rather than always max-ing against it) is+ * what keeps a normal running run on the short TTL: TTL(jobKey) is only the long approval+ * window while paused; for a running job the job key carries the running TTL, so target+ * stays `run`.+ *+ * KEYS: [chunks, job]+ * ARGV: [eventJson, runningTtl]+ */+const CHUNK_APPEND_LUA =+ 'redis.call("XADD", KEYS[1], "*", "event", ARGV[1]) ' ++ 'local run = tonumber(ARGV[2]) ' ++ 'local target = run ' ++ 'if redis.call("HGET", KEYS[2], "status") == "requires_action" then ' ++ 'local jt = redis.call("TTL", KEYS[2]) ' ++ 'if jt > target then target = jt end ' ++ 'end ' ++ 'local cur = redis.call("TTL", KEYS[1]) ' ++ 'if cur < target then redis.call("EXPIRE", KEYS[1], target) end ' ++ 'return 1';++/**+ * Persist the run-step timeline with the same paused-window TTL as the chunk stream.+ * `saveRunSteps` SETs (overwrites) the whole array, so unlike the chunk append there's no+ * prior key TTL worth preserving — but the write must still extend to the APPROVAL window+ * when the job is paused (`status == "requires_action"`). Otherwise a run-step save that+ * lands at/after a fast pause resets the key to the short running TTL, and a reload of a+ * still-live approval after that window loses the tool/run-step timeline even though the+ * approval remains resumable. Reads the paused window from the job key (which+ * `transitionStatus` set); a normally-running job keeps the short running TTL.+ *+ * KEYS: [runSteps, job]+ * ARGV: [runStepsJson, runningTtl]+ */+const RUNSTEPS_SAVE_LUA =+ 'redis.call("SET", KEYS[1], ARGV[1]) ' ++ 'local run = tonumber(ARGV[2]) ' ++ 'local target = run ' ++ 'if redis.call("HGET", KEYS[2], "status") == "requires_action" then ' ++ 'local jt = redis.call("TTL", KEYS[2]) ' ++ 'if jt > target then target = jt end ' ++ 'end ' ++ 'redis.call("EXPIRE", KEYS[1], target) ' ++ 'return 1';+/** Decision kinds the SDK can emit, used to sanity-check persisted records. */const KNOWN_INTERRUPT_TYPES = new Set(['tool_approval', 'ask_user_question']);@@ -206,14 +271,27 @@ export class RedisJobStore implements IJobStore {const key = KEYS.job(streamId);const userJobsKey = KEYS.userJobs(userId, tenantId);- // A reused streamId overlays onto any existing hash, so paused-run fields- // from a prior generation could survive. Drop the HITL fields so the fresh- // running job never exposes stale approval metadata and cleanup keys off the- // new createdAt rather than a leftover lastActiveAt.+ // A reused streamId overlays onto any existing hash, so per-turn fields from a+ // prior generation could survive. Drop the HITL fields so the fresh running job+ // never exposes stale approval metadata and cleanup keys off the new createdAt+ // rather than a leftover lastActiveAt. `agent_id` is included because+ // updateMetadata only writes it when truthy — without clearing it here, a+ // conversation that switches from a saved agent to an ephemeral/no-agent turn+ // would keep the old agent_id and the resume guard would reject the valid pause.const staleHitlFields: Array<keyof SerializableJobData> = ['pendingAction','pendingActionId','lastActiveAt',+ 'agent_id',+ // Same reasoning as agent_id: updateMetadata only writes isTemporary when the new+ // metadata carries it, so a prior temporary turn's isTemporary=1 would otherwise+ // survive and a later non-temporary resume would save its response as temporary.+ 'isTemporary',+ // Same reasoning again: handleRunInterrupt only writes discoveredTools when THIS+ // turn discovered ≥1 deferred tool, so a replacement turn that later pauses without+ // its own discovery would otherwise inherit the prior run's tool names and force-load+ // deferred tools it never discovered on resume.+ 'discoveredTools',];// For cluster mode, we can't pipeline keys on different slots@@ -630,6 +708,12 @@ export class RedisJobStore implements IJobStore {error: 'Approval expired before a decision was made',completedAt: Date.now(),},+ // Scope the CAS to the action we observed as stale: if the user resolved it+ // and the run re-paused on a fresh action between the read and here, the+ // pendingActionId no longer matches and this no-ops instead of aborting the+ // valid new pause. (Undefined for a missing/malformed pendingAction — nothing+ // to protect — so it falls back to the status-only check.)+ expectActionId: job.pendingAction?.actionId,});return 1;}@@ -937,14 +1021,24 @@ export class RedisJobStore implements IJobStore {*/async appendChunk(streamId: string, event: unknown): Promise<void> {const key = KEYS.chunks(streamId);- // Pipeline XADD + EXPIRE in a single round-trip.- // EXPIRE is O(1) and idempotent — refreshing TTL on every chunk is better than- // only setting it once, since the original approach could let the TTL expire- // during long-running streams.- const pipeline = this.redis.pipeline();- pipeline.xadd(key, '*', 'event', JSON.stringify(event));- pipeline.expire(key, this.ttl.running);- await pipeline.exec();+ const jobKey = KEYS.job(streamId);+ // XADD + derive-and-extend-only EXPIRE in a single atomic eval. Refreshing the TTL on+ // every chunk (vs only once) keeps the key alive through long streams, but it must+ // NEVER shrink an already-longer TTL — a paused (requires_action) job needs this key+ // to live for the whole approval window, and the on_pending_action append (or any+ // chunk that lands after the pause) would otherwise reset it to the short running TTL.+ // The script reads the paused window from the job key, so it bumps to the approval TTL+ // even when the pause's own EXPIRE no-op'd because this key didn't exist yet, while a+ // normally-running run still settles on the short running TTL. Both keys share the+ // {streamId} hash tag, so the 2-key eval stays on one slot under Redis Cluster.+ await this.redis.eval(+ CHUNK_APPEND_LUA,+ 2,+ key,+ jobKey,+ JSON.stringify(event),+ String(this.ttl.running),+ );}/**@@ -970,11 +1064,20 @@ export class RedisJobStore implements IJobStore {}/**- * Save run steps for resume state.+ * Save run steps for resume state. Uses the paused-window TTL script so a run-step save+ * landing at/after a HITL pause extends to the approval window instead of resetting the+ * key to the short running TTL (which would drop the tool timeline on a reload of a+ * still-live approval — mirrors the chunk-stream no-shrink behavior).*/async saveRunSteps(streamId: string, runSteps: Agents.RunStep[]): Promise<void> {- const key = KEYS.runSteps(streamId);- await this.redis.set(key, JSON.stringify(runSteps), 'EX', this.ttl.running);+ await this.redis.eval(+ RUNSTEPS_SAVE_LUA,+ 2,+ KEYS.runSteps(streamId),+ KEYS.job(streamId),+ JSON.stringify(runSteps),+ String(this.ttl.running),+ );}// ===== Consumer Group Methods =====@@ -1215,6 +1318,10 @@ export class RedisJobStore implements IJobStore {iconURL: data.iconURL || undefined,model: data.model || undefined,promptTokens: data.promptTokens ? parseInt(data.promptTokens, 10) : undefined,+ agent_id: data.agent_id || undefined,+ isTemporary: data.isTemporary != null ? data.isTemporary === '1' : undefined,+ // Deferred tools discovered before a HITL pause; replayed into createRun on resume.+ discoveredTools: data.discoveredTools ? JSON.parse(data.discoveredTools) : undefined,titleEvent: data.titleEvent || undefined,replayEvents: data.replayEvents || undefined,contextUsage: data.contextUsage || undefined,diff --git a/packages/api/src/stream/interfaces/IJobStore.ts b/packages/api/src/stream/interfaces/IJobStore.tsindex f3dcb752bf..9e55d543e1 100644--- a/packages/api/src/stream/interfaces/IJobStore.ts+++ b/packages/api/src/stream/interfaces/IJobStore.ts@@ -32,11 +32,25 @@ export interface SerializableJobData {/** Quoted excerpts referenced on this turn, carried so resumable/aborted* reconstructions of the user message keep their `MessageQuotes`. */quotes?: string[];+ /** Skill selections, carried so a HITL-resumed turn's requestMessage keeps its pills. */+ manualSkills?: string[];+ alwaysAppliedSkills?: string[];+ /** Uploaded files for the turn, carried so a HITL resume sources them from the job+ * rather than a user DB row whose save can still be racing the approval prompt. */+ files?: unknown[];};/** Response message ID for reconnection */responseMessageId?: string;+ /**+ * Deferred-tool names discovered (via `tool_search`) before a HITL pause, captured+ * so a resume can replay them into `createRun` — the rebuilt graph uses `messages: []`+ * (state comes from the checkpoint), so without these the paused deferred tool would be+ * absent from the schema-only toolMap and resume would fail with "unknown tool".+ */+ discoveredTools?: string[];+/** Whether the user-message created event has been emitted */createdEventEmitted?: boolean;@@ -67,6 +81,20 @@ export interface SerializableJobData {model?: string;promptTokens?: number;+ /**+ * Agent that initiated the run. Persisted so a HITL resume can verify it rebuilds+ * the SAME agent that paused — resuming Agent A's checkpoint on Agent B's graph+ * would mis-execute the paused tool calls.+ */+ agent_id?: string;++ /**+ * Whether the originating turn was a temporary (non-persisted) chat. Persisted so+ * a HITL resume keeps the resumed response temporary instead of saving it — the+ * resume request can't be trusted to re-send the flag.+ */+ isTemporary?: boolean;+/*** Set when status is `requires_action`. Describes the human review the* run is waiting on. Cleared by the resume path before the job returns to `running`.diff --git a/packages/api/src/types/stream.ts b/packages/api/src/types/stream.tsindex d43a1112f1..47a94d6ead 100644--- a/packages/api/src/types/stream.ts+++ b/packages/api/src/types/stream.ts@@ -20,6 +20,16 @@ export interface GenerationJobMetadata {model?: string;/** Prompt token count for abort token spending */promptTokens?: number;+ /** Agent that initiated the run; a HITL resume verifies it rebuilds the same agent. */+ agent_id?: string;+ /** Whether the originating turn was a temporary chat; a HITL resume keeps it so. */+ isTemporary?: boolean;+ /**+ * Deferred-tool names discovered (via `tool_search`) before a HITL pause. A resume+ * replays these into `createRun` because the rebuilt graph uses `messages: []`, so+ * without them the paused deferred tool would be missing from the schema-only toolMap.+ */+ discoveredTools?: string[];/** Set when the job is paused for human review (status === 'requires_action') */pendingAction?: Agents.PendingAction;}diff --git a/packages/data-provider/src/config.ts b/packages/data-provider/src/config.tsindex 01db2feeed..fefa3305a5 100644--- a/packages/data-provider/src/config.ts+++ b/packages/data-provider/src/config.ts@@ -801,6 +801,45 @@ export const toolApprovalPolicySchema = zexport type TToolApprovalPolicy = z.infer<typeof toolApprovalPolicySchema>;+/**+ * Durable checkpointer backing human-in-the-loop resume.+ *+ * When `toolApproval.enabled` is true, a run that pauses for review suspends its+ * LangGraph state to a checkpoint; resuming rebuilds that state on a *fresh* `Run`+ * — possibly on a different replica, or the same worker after a restart. That only+ * works if the checkpoint outlives the original request, so HITL needs a durable+ * saver, not the SDK's process-local `MemorySaver` fallback.+ *+ * Defaults are zero-config: with `toolApproval.enabled` on and no `checkpointer`+ * block, LibreChat persists checkpoints to its primary MongoDB, so resume works+ * across replicas out of the box.+ *+ * - `type: 'mongo'` (default) — persist to the app database; survives restarts and+ * resolves on any replica. A TTL index reclaims runs that are never resolved.+ * - `type: 'memory'` — process-local only. Paused runs do NOT survive a restart and+ * can only be resolved on the originating worker. Single-process / dev only.+ */+export const checkpointerTypeSchema = z.enum(['mongo', 'memory']);+export type TCheckpointerType = z.infer<typeof checkpointerTypeSchema>;++export const checkpointerSchema = z+ .object({+ type: checkpointerTypeSchema.optional(),+ /**+ * Approval window, in seconds: how long a paused run waits for a decision+ * before it is reclaimed. Drives both the Mongo TTL index on checkpoints and+ * the pending-action expiry, keeping the two layers in lockstep. Defaults to+ * 86400 (24h). Raise it for longer review windows.+ */+ ttl: z.number().int().positive().optional(),+ /** Advanced: override the Mongo collection names used for checkpoints. */+ checkpointCollectionName: z.string().optional(),+ checkpointWritesCollectionName: z.string().optional(),+ })+ .optional();++export type TCheckpointerConfig = z.infer<typeof checkpointerSchema>;+export const agentsEndpointSchema = baseEndpointSchema.omit({ baseURL: true }).merge(@@ -825,6 +864,9 @@ export const agentsEndpointSchema = baseEndpointSchemaremoteApi: remoteApiSchema.optional(),/** Human-in-the-loop tool approval policy. Off by default. */toolApproval: toolApprovalPolicySchema,+ /** Durable checkpointer backing HITL resume. Defaults to the app's MongoDB+ * when `toolApproval.enabled` is set; ignored otherwise. */+ checkpointer: checkpointerSchema,}),).default({diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.tsindex 6318dd651f..0e7463f924 100644--- a/packages/data-provider/src/types/agents.ts+++ b/packages/data-provider/src/types/agents.ts@@ -217,6 +217,11 @@ export namespace Agents {parentMessageId?: string;conversationId?: string;text?: string;+ /** Skill selections on the turn, carried so a HITL-resumed turn's reconstructed+ * requestMessage keeps its skill pills (they aren't on the DB row the client refetches+ * until reload). */+ manualSkills?: string[];+ alwaysAppliedSkills?: string[];}/** State data sent to reconnecting clients */@@ -403,6 +408,21 @@ export namespace Agents {* worker that didn't originate the run.*/threadId?: string;+ /**+ * Fingerprint of the request fields that determine the agent/graph + tool set+ * (endpoint, agent_id, model, spec, ephemeralAgent), captured at pause time. The+ * resume route recomputes it from the resume request and rejects a mismatch — the+ * guard that catches an ephemeral-agent config swap, where `agent_id` is undefined+ * so the id check can't.+ */+ requestFingerprint?: string;+ /**+ * Graph-determining request fields (endpoint, agent_id, model, spec, promptPrefix,+ * ephemeralAgent) captured at pause. The resume route REPLAYS these onto the request+ * before rebuilding the run, so a reload/cross-replica resume — where the client can+ * no longer reconstruct the ephemeral config — still rebuilds the same agent/graph.+ */+ resumeContext?: Record<string, unknown>;}/**diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.tsindex 1fdc07cd81..da386ac5f4 100644--- a/packages/data-provider/src/types/runs.ts+++ b/packages/data-provider/src/types/runs.ts@@ -48,6 +48,15 @@ export enum UsageEvents {ON_TOKEN_USAGE = 'on_token_usage',}+/**+ * Human-in-the-loop event names. Streamed to live clients when a run pauses for+ * tool approval (or an ask-user question). Reconnecting clients instead read the+ * same record from `resumeState.pendingAction` on the sync event / status route.+ */+export enum ApprovalEvents {+ ON_PENDING_ACTION = 'on_pending_action',+}+/** Mirrors TokenBudgetBreakdown from @librechat/agents (data-provider cannot import it). */export type TTokenBudgetBreakdown = {maxContextTokens: number;