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: Mid-Run Steering and Queued Messages for Agent Runs (#14220)
Danny Avila9bb351ad9cff
diff --git a/api/app/clients/BaseClient.js b/api/app/clients/BaseClient.jsindex b7c5a8ae59..6d541e160f 100644--- a/api/app/clients/BaseClient.js+++ b/api/app/clients/BaseClient.js@@ -41,6 +41,16 @@ const collectHistoricalFileRefs = (message) => {if (Array.isArray(message.attachments)) {refs.push(...message.attachments);}+ /** Steer parts carry their own attachment refs inside assistant content;+ * collecting them here folds the steer replay stamp's lookup into this+ * single per-turn query (see `stampSteerPartMedia`). */+ if (Array.isArray(message.content)) {+ for (const part of message.content) {+ if (part?.type === ContentTypes.STEER && Array.isArray(part.files)) {+ refs.push(...part.files);+ }+ }+ }return refs;};@@ -1457,6 +1467,9 @@ class BaseClient {}}}+ /** Owner-scoped docs for THIS turn, including steer-part refs — the steer+ * replay stamp consumes this instead of issuing a second query. */+ this.authorizedHistoricalFiles = authorizedFilesById;/***diff --git a/api/app/clients/prompts/formatAgentMessages.spec.js b/api/app/clients/prompts/formatAgentMessages.spec.jsindex d8e9262ba9..5a4b6937ba 100644--- a/api/app/clients/prompts/formatAgentMessages.spec.js+++ b/api/app/clients/prompts/formatAgentMessages.spec.js@@ -511,4 +511,113 @@ describe('formatAgentMessages', () => {expect(assistant.additional_kwargs?.signatures).toBeUndefined();});});++ describe('steer content parts', () => {+ it('replays a steer between tool steps as a standalone HumanMessage', () => {+ const payload = [+ {+ role: 'assistant',+ content: [+ {+ type: ContentTypes.TEXT,+ [ContentTypes.TEXT]: 'Checking the weather.',+ tool_call_ids: ['t1'],+ },+ {+ type: ContentTypes.TOOL_CALL,+ tool_call: { id: 't1', name: 'search', args: '{}', output: 'sunny' },+ },+ {+ type: ContentTypes.STEER,+ [ContentTypes.STEER]: 'also check tomorrow',+ steerId: 's1',+ },+ {+ type: ContentTypes.TEXT,+ [ContentTypes.TEXT]: 'Checking tomorrow too.',+ tool_call_ids: ['t2'],+ },+ {+ type: ContentTypes.TOOL_CALL,+ tool_call: { id: 't2', name: 'search', args: '{}', output: 'rain' },+ },+ ],+ },+ ];++ const result = formatAgentMessages(payload);+ expect(result.map((m) => m.constructor)).toEqual([+ AIMessage,+ ToolMessage,+ HumanMessage,+ AIMessage,+ ToolMessage,+ ]);+ expect(result[2].content).toBe('also check tomorrow');+ expect(result[2].additional_kwargs).toEqual({ source: 'steer' });+ expect(result[3].tool_calls).toHaveLength(1);+ });++ it('flushes accumulated assistant text before the steer', () => {+ const payload = [+ {+ role: 'assistant',+ content: [+ { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Some prose so far.' },+ { type: ContentTypes.STEER, [ContentTypes.STEER]: 'change direction' },+ { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'New direction prose.' },+ ],+ },+ ];++ const result = formatAgentMessages(payload);+ expect(result.map((m) => m.constructor)).toEqual([AIMessage, HumanMessage, AIMessage]);+ expect(result[0].content).toBe('Some prose so far.');+ expect(result[1].content).toBe('change direction');+ expect(result[2].content).toEqual([+ { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'New direction prose.' },+ ]);+ });++ it('handles a steer as the final content part', () => {+ const payload = [+ {+ role: 'assistant',+ content: [+ { type: ContentTypes.TEXT, [ContentTypes.TEXT]: 'Answer text.' },+ { type: ContentTypes.STEER, [ContentTypes.STEER]: 'trailing steer' },+ ],+ },+ ];++ const result = formatAgentMessages(payload);+ expect(result.map((m) => m.constructor)).toEqual([AIMessage, HumanMessage]);+ expect(result[1].content).toBe('trailing steer');+ });++ it('prefers stamped media content for multimodal steers', () => {+ const media = [+ { type: 'text', text: 'see the chart' },+ { type: 'image_url', image_url: { url: 'data:image/png;base64,abc', detail: 'auto' } },+ ];+ const payload = [+ {+ role: 'assistant',+ content: [+ {+ type: ContentTypes.STEER,+ [ContentTypes.STEER]: 'see the chart',+ files: [{ file_id: 'f1' }],+ media,+ },+ ],+ },+ ];++ const result = formatAgentMessages(payload);+ expect(result).toHaveLength(1);+ expect(result[0]).toBeInstanceOf(HumanMessage);+ expect(result[0].content).toEqual(media);+ });+ });});diff --git a/api/app/clients/prompts/formatMessages.js b/api/app/clients/prompts/formatMessages.jsindex 8435ff5280..795c62c14f 100644--- a/api/app/clients/prompts/formatMessages.js+++ b/api/app/clients/prompts/formatMessages.js@@ -229,6 +229,43 @@ const formatAgentMessages = (payload) => {} else if (part.type === ContentTypes.THINK) {hasReasoning = true;continue;+ } else if (part.type === ContentTypes.STEER) {+ /*+ A mid-run steer: user speech persisted inline in the assistant message.+ Flush any accumulated assistant text first so ordering is preserved, then+ replay the steer as a standalone user message. `lastAIMessage` is NOT+ reset — the aggregator emits a fresh text-with-tool_call_ids part for any+ post-steer tool step, and preceding tool_call parts already pushed their+ ToolMessages, so the HumanMessage lands after them (valid provider order).+ */+ if (currentContent.length > 0) {+ if (currentContent.some((curr) => curr.type !== ContentTypes.TEXT)) {+ /** Non-text parts (images, files) must survive the flush intact —+ * folding to text here would drop them from replayed history. */+ messages.push(new AIMessage({ content: currentContent }));+ } else {+ const content = currentContent+ .reduce((acc, curr) => `${acc}${curr[ContentTypes.TEXT] ?? ''}\n`, '')+ .trim();+ if (content.length > 0) {+ messages.push(new AIMessage({ content }));+ }+ }+ currentContent = [];+ }+ messages.push(+ new HumanMessage({+ content:+ Array.isArray(part.media) && part.media.length > 0+ ? part.media+ : (part[ContentTypes.STEER] ?? ''),+ additional_kwargs: { source: 'steer' },+ }),+ );+ /** A post-steer tool_call must mint a FRESH assistant anchor —+ * attaching to the pre-steer one would emit its ToolMessage after+ * the HumanMessage while the call sat before it (invalid order). */+ lastAIMessage = null;} else if (part.type === ContentTypes.ERROR || part.type === ContentTypes.AGENT_UPDATE) {continue;} else {diff --git a/api/package.json b/api/package.jsonindex 312945cca4..3dedf01b8e 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.62",+ "@librechat/agents": "^3.2.63","@librechat/api": "*","@librechat/data-schemas": "*","@microsoft/microsoft-graph-client": "^3.0.7",diff --git a/api/server/controllers/agents/__tests__/steer.spec.js b/api/server/controllers/agents/__tests__/steer.spec.jsnew file mode 100644index 0000000000..a0108b3cbc--- /dev/null+++ b/api/server/controllers/agents/__tests__/steer.spec.js@@ -0,0 +1,194 @@+const express = require('express');+const request = require('supertest');++const mockHandleSteerRequest = jest.fn();+const mockCheckAccess = jest.fn();+const mockCheckPermission = jest.fn();+const mockHasCapability = jest.fn();+const mockGetAgent = jest.fn();+const mockLogger = { warn: jest.fn(), error: jest.fn(), debug: jest.fn(), info: jest.fn() };++jest.mock('@librechat/data-schemas', () => ({+ ...jest.requireActual('@librechat/data-schemas'),+ logger: mockLogger,+}));++jest.mock('@librechat/api', () => ({+ ...jest.requireActual('@librechat/api'),+ handleSteerRequest: (...args) => mockHandleSteerRequest(...args),+ checkAccess: (...args) => mockCheckAccess(...args),+}));++jest.mock('~/server/services/PermissionService', () => ({+ checkPermission: (...args) => mockCheckPermission(...args),+}));++jest.mock('~/server/middleware/roles/capabilities', () => ({+ hasCapability: (...args) => mockHasCapability(...args),+}));++jest.mock('~/models', () => ({+ getRoleByName: jest.fn(),+ getAgent: (...args) => mockGetAgent(...args),+ getFiles: jest.fn(),+ updateFilesUsage: jest.fn(),+}));++const { Permissions, PermissionTypes, PermissionBits } = require('librechat-data-provider');+const SteerController = require('~/server/controllers/agents/steer');++/**+ * The guard ladder itself (validation, file sanitization, ownership, enqueue+ * codes) is typed logic in `@librechat/api` and is covered against the REAL+ * in-memory job manager by `packages/api/src/agents/steering/__tests__/request.spec.ts`.+ * This spec only pins the thin wrapper contract: pass-through of user/body,+ * verbatim status/body serialization, and the 500 failure envelope.+ */+function buildApp(user = { id: 'user-1', tenantId: 'tenant-1' }) {+ const app = express();+ app.use(express.json());+ app.use((req, _res, next) => {+ req.user = user;+ next();+ });+ app.post('/chat/steer', SteerController);+ return app;+}++describe('SteerController (wrapper)', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ });++ it('serializes the handler result verbatim', async () => {+ mockHandleSteerRequest.mockResolvedValue({+ status: 202,+ body: { status: 'queued', steerId: 's1', position: 1, conversationId: 'c1' },+ });++ const res = await request(buildApp())+ .post('/chat/steer')+ .send({ conversationId: 'c1', text: 'hello', files: [{ file_id: 'f1' }] });++ expect(res.status).toBe(202);+ expect(res.body).toEqual({+ status: 'queued',+ steerId: 's1',+ position: 1,+ conversationId: 'c1',+ });+ expect(mockHandleSteerRequest).toHaveBeenCalledWith(+ { id: 'user-1', tenantId: 'tenant-1' },+ { conversationId: 'c1', text: 'hello', files: [{ file_id: 'f1' }] },+ {+ getFiles: expect.any(Function),+ updateFilesUsage: expect.any(Function),+ checkAgentAccess: expect.any(Function),+ },+ );+ });++ it('passes rejection statuses through untouched', async () => {+ mockHandleSteerRequest.mockResolvedValue({ status: 409, body: { code: 'RUN_PAUSED' } });++ const res = await request(buildApp()).post('/chat/steer').send({ conversationId: 'c1' });++ expect(res.status).toBe(409);+ expect(res.body.code).toBe('RUN_PAUSED');+ });++ it('500s with STEER_FAILED when the handler throws', async () => {+ mockHandleSteerRequest.mockRejectedValue(new Error('store down'));++ const res = await request(buildApp())+ .post('/chat/steer')+ .send({ conversationId: 'c1', text: 'x' });++ expect(res.status).toBe(500);+ expect(res.body.code).toBe('STEER_FAILED');+ expect(mockLogger.error).toHaveBeenCalled();+ });+});++describe('createAgentAccessCheck (chat-route parity via job identity)', () => {+ /** Posts a steer to capture the wired deps, then exercises the callback. */+ async function captureAccessCheck(user) {+ mockHandleSteerRequest.mockResolvedValue({ status: 202, body: {} });+ await request(buildApp(user)).post('/chat/steer').send({ conversationId: 'c1', text: 'x' });+ return mockHandleSteerRequest.mock.calls[0][2].checkAgentAccess;+ }++ const roleUser = { id: 'user-1', tenantId: 'tenant-1', role: 'USER' };++ beforeEach(() => {+ jest.clearAllMocks();+ mockCheckAccess.mockResolvedValue(true);+ mockHasCapability.mockResolvedValue(false);+ mockGetAgent.mockResolvedValue({ _id: 'oid-1', id: 'agent_abc' });+ mockCheckPermission.mockResolvedValue(true);+ });++ it('denies an agents run when the AGENTS:USE role gate fails, skipping resource calls', async () => {+ mockCheckAccess.mockResolvedValue(false);+ const check = await captureAccessCheck(roleUser);++ await expect(check({ agentId: 'agent_abc', endpoint: 'agents' })).resolves.toBe(false);+ expect(mockCheckAccess).toHaveBeenCalledWith(+ expect.objectContaining({+ permissionType: PermissionTypes.AGENTS,+ permissions: [Permissions.USE],+ }),+ );+ expect(mockGetAgent).not.toHaveBeenCalled();+ expect(mockCheckPermission).not.toHaveBeenCalled();+ });++ it('runs the VIEW resource check against the resolved agent', async () => {+ const check = await captureAccessCheck(roleUser);++ await expect(check({ agentId: 'agent_abc', endpoint: 'agents' })).resolves.toBe(true);+ expect(mockGetAgent).toHaveBeenCalledWith({ id: 'agent_abc' });+ expect(mockCheckPermission).toHaveBeenCalledWith(+ expect.objectContaining({+ userId: 'user-1',+ resourceId: 'oid-1',+ requiredPermission: PermissionBits.VIEW,+ }),+ );+ });++ it('denies when the agent is gone or the ACL check fails', async () => {+ const check = await captureAccessCheck(roleUser);++ mockGetAgent.mockResolvedValueOnce(null);+ await expect(check({ agentId: 'agent_abc', endpoint: 'agents' })).resolves.toBe(false);++ mockCheckPermission.mockResolvedValueOnce(false);+ await expect(check({ agentId: 'agent_abc', endpoint: 'agents' })).resolves.toBe(false);+ });++ it('honors the capability bypass without touching the agent or ACL', async () => {+ mockHasCapability.mockResolvedValue(true);+ const check = await captureAccessCheck(roleUser);++ await expect(check({ agentId: 'agent_abc', endpoint: 'agents' })).resolves.toBe(true);+ expect(mockGetAgent).not.toHaveBeenCalled();+ expect(mockCheckPermission).not.toHaveBeenCalled();+ });++ it('allows ephemeral runs with no role gate (skipAgentCheck parity for non-agents endpoints)', async () => {+ const check = await captureAccessCheck(roleUser);++ await expect(check({ agentId: undefined, endpoint: 'openAI' })).resolves.toBe(true);+ expect(mockCheckAccess).not.toHaveBeenCalled();+ expect(mockCheckPermission).not.toHaveBeenCalled();+ });++ it('applies both gates when metadata has a real agent but no endpoint yet', async () => {+ const check = await captureAccessCheck(roleUser);++ await expect(check({ agentId: 'agent_abc', endpoint: undefined })).resolves.toBe(true);+ expect(mockCheckAccess).toHaveBeenCalled();+ expect(mockCheckPermission).toHaveBeenCalled();+ });+});diff --git a/api/server/controllers/agents/client.js b/api/server/controllers/agents/client.jsindex 4a2768f809..81364f5559 100644--- a/api/server/controllers/agents/client.js+++ b/api/server/controllers/agents/client.js@@ -45,6 +45,11 @@ const {agentRequestsAskUserQuestion,attachAskUserQuestionArgs,createContentIndexOffsetHandlers,+ createSteerIndexOffsetHandlers,+ createSteerDrainHook,+ isSteeringSupported,+ buildSteerMedia,+ stampSteerPartMedia,getRequestMemories,getMemoryAgentId,createMemoryProcessor,@@ -79,6 +84,7 @@ const {} = require('@librechat/agents');const {Constants,+ SteerEvents,UsageEvents,Permissions,VisionModes,@@ -189,6 +195,11 @@ class AgentClient extends BaseClient {this.indexTokenCountMap = {};/** @type {Array<Record<string, unknown>> | null} */this.memoryPayload = null;+ /** Mutable content-index shift shared with the steer offset handlers.+ * Incremented each time a steer part is spliced into `contentParts`, so+ * SDK-emitted indices that arrive after an injection land past it.+ * @type {import('@librechat/api').SteerOffsetState} */+ this.steerOffsetState = { offset: 0 };/** @type {(messages: BaseMessage[]) => Promise<void>} */this.processMemory;}@@ -239,6 +250,78 @@ class AgentClient extends BaseClient {buffer.clear();}+ /**+ * Apply one drained steer to host state: append the steer content part at+ * the live content index, bump the shared index offset so subsequent SDK+ * step indices land past it, and emit `on_steer_applied` so the live client+ * replaces its pending chip with the inline part (the emitted chunk also+ * reaches the Redis chunk log for reconnect reconstruction).+ *+ * Runs BEFORE the drain hook's media encode so an abort during the encode+ * cannot lose the steer. File refs persist from the queue item (sanitized at+ * enqueue); replay/token accounting re-fetch owner-scoped and re-encode per+ * turn (stampSteerPartMedia), so unauthorized ids drop out there.+ *+ * @param {string} streamId+ * @param {import('@librechat/api').SteerQueueItem} item+ */+ async applySteerPart(streamId, item) {+ const index = this.contentParts.length;+ const part = {+ type: ContentTypes.STEER,+ [ContentTypes.STEER]: item.text,+ steerId: item.steerId,+ createdAt: item.createdAt,+ ...(item.files?.length && { files: item.files }),+ };+ this.contentParts.push(part);+ this.steerOffsetState.offset += 1;+ // durable: the chunk-log XADD is this event's recovery record — it must+ // commit before the publish or a cross-replica reconnect that missed the+ // pub/sub delivery reconstructs content without the steer part.+ await GenerationJobManager.emitChunk(+ streamId,+ {+ event: SteerEvents.ON_STEER_APPLIED,+ data: {+ steerId: item.steerId,+ index,+ part,+ responseMessageId: this.responseMessageId,+ conversationId: this.conversationId,+ },+ },+ { durable: true },+ );+ }++ /**+ * The `steering` fragment for `createRun`: the run-scoped PostToolBatch+ * drain hook, or `undefined` when there is no resumable job surface or the+ * installed SDK cannot inject hook messages (draining would drop them).+ *+ * @param {string | undefined} streamId+ */+ buildSteerWiring(streamId) {+ if (!streamId || !isSteeringSupported()) {+ return undefined;+ }+ return {+ hook: createSteerDrainHook({+ streamId,+ jobCreatedAt: this.jobCreatedAt,+ applySteer: (item) => this.applySteerPart(streamId, item),+ buildMedia: (item) =>+ buildSteerMedia({+ client: this,+ user: this.options.req?.user,+ item,+ getFiles: db.getFiles,+ }),+ }),+ };+ }+setOptions(_options) {}/**@@ -513,6 +596,42 @@ class AgentClient extends BaseClient {}payload = formattedMessages;+ if (this.options.resendFiles) {+ /** Persisted steer parts of past turns replay with their attachments:+ * one batched owner-scoped fetch, re-encoded per turn and stamped as a+ * transient `media` array (same resend semantics as message files).+ * The stamp lands after the loop above finalized its counts, so the+ * re-encoded media (minus the text part the steer part already counted)+ * is folded into the budget here — large steered attachments must+ * shrink the window like any other resent media. */+ const stamped = await stampSteerPartMedia({+ client: this,+ user: this.options.req?.user,+ payload,+ // addPreviousAttachments already fetched steer-part refs in its single+ // per-turn historical-files query — no second round trip.+ docsById: this.authorizedHistoricalFiles,+ getFiles: db.getFiles,+ });+ for (const { index, media, steerText } of stamped) {+ /** Count the FULL stamped content and subtract only the steer body+ * (already counted inside the assistant message): extracted file+ * context prepended into the text part must hit the budget too, or+ * large steered documents bypass pruning. */+ const fullTokens = countFormattedMessageTokens({ role: 'user', content: media }, encoding);+ const bodyTokens = steerText+ ? countFormattedMessageTokens(+ { role: 'user', content: [{ type: ContentTypes.TEXT, text: steerText }] },+ encoding,+ )+ : 0;+ const mediaTokens = Math.max(0, (fullTokens ?? 0) - (bodyTokens ?? 0));+ if (Number.isFinite(mediaTokens) && mediaTokens > 0) {+ indexTokenCountMap[index] = (indexTokenCountMap[index] ?? 0) + mediaTokens;+ promptTokenTotal += mediaTokens;+ }+ }+ }this.memoryPayload = hasFileContext ? memoryPayload : null;messages = orderedMessages;promptTokens = promptTokenTotal;@@ -1226,6 +1345,9 @@ class AgentClient extends BaseClient {(part, index) =>index >= this.contentParts.length - 1 ||part.type === ContentTypes.TOOL_CALL ||+ // Steer parts are user speech, not intermediate agent output — dropping+ // one would erase the user's words from the persisted turn.+ part.type === ContentTypes.STEER ||part.tool_call_ids,);}@@ -1366,6 +1488,13 @@ class AgentClient extends BaseClient {event: ApprovalEvents.ON_PENDING_ACTION,data: toClientPendingAction(pendingAction),});+ // Steers queued before this pause stay IN the store for the whole approval+ // window: `resumeState.pendingSteers` re-seeds the client's chips on+ // reload, and the resumed run drains them at its first tool boundary.+ // Draining here would leave the only copy in ephemeral client state — a+ // reload during the pause would silently lose the user's message. New+ // steers are rejected while paused (enqueue is status-guarded), and the+ // requires_action TTL extension keeps the queue key alive.logger.debug(`[AgentClient] Paused ${streamId} for ${interrupt.payload.type} (action ${pendingAction.actionId})`,);@@ -1608,6 +1737,7 @@ class AgentClient extends BaseClient {);}+ const streamId = this.options.req?._resumableStreamId;run = await createRun({agents,messages,@@ -1616,13 +1746,20 @@ class AgentClient extends BaseClient {// 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,+ // Mid-run steering: drain queued user messages at each tool-batch+ // boundary and inject them into graph state. The offset wrapper+ // shifts SDK content indices past any spliced steer parts.+ steering: this.buildSteerWiring(streamId),indexTokenCountMap,initialSummary,initialSessions,calibrationRatio,runId: this.responseMessageId,signal: abortController.signal,- customHandlers: this.options.eventHandlers,+ customHandlers: createSteerIndexOffsetHandlers(+ this.options.eventHandlers,+ this.steerOffsetState,+ ),requestBody: config.configurable.requestBody,user: createSafeUser(this.options.req?.user),tenantId: this.options.req?.user?.tenantId,@@ -1652,7 +1789,6 @@ class AgentClient extends BaseClient {this._resolveRun = null;}- const streamId = this.options.req?._resumableStreamId;if (streamId && run.Graph) {GenerationJobManager.setGraph(streamId, run.Graph);}@@ -1931,6 +2067,7 @@ class AgentClient extends BaseClient {// graph otherwise has no `Graph.sessions` entries (especially cross-replica).const initialSessions = buildInitialToolSessions({ skillSessions, agents });+ const streamId = this.options.req?._resumableStreamId;run = await createRun({agents,// State (messages, tool calls) is rehydrated from the checkpoint by@@ -1939,6 +2076,9 @@ class AgentClient extends BaseClient {// 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,+ // Steering stays live across a pause/resume cycle: steers queued while+ // the resumed segment runs drain at its tool-batch boundaries.+ steering: this.buildSteerWiring(streamId),// 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)@@ -1950,10 +2090,15 @@ class AgentClient extends BaseClient {// The rebuilt graph numbers content indices from 0, but the aggregator was// just seeded with the pre-pause parts at those same indices — shift every// resumed step index past the seed, or the new output merges into (or, on a- // type mismatch, is silently dropped against) the pre-pause content.- customHandlers: createContentIndexOffsetHandlers(- this.options.eventHandlers,- Array.isArray(seedContent) ? seedContent : [],+ // type mismatch, is silently dropped against) the pre-pause content. The+ // steer wrapper composes on top: resumed indices shift by seed + any+ // steer parts spliced in while the resumed segment streams.+ customHandlers: createSteerIndexOffsetHandlers(+ createContentIndexOffsetHandlers(+ this.options.eventHandlers,+ Array.isArray(seedContent) ? seedContent : [],+ ),+ this.steerOffsetState,),requestBody: config.configurable.requestBody,user: createSafeUser(this.options.req?.user),@@ -1977,7 +2122,6 @@ class AgentClient extends BaseClient {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-pausediff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.jsindex 81213a23d9..5b63c06ef8 100644--- a/api/server/controllers/agents/request.js+++ b/api/server/controllers/agents/request.js@@ -2,6 +2,7 @@ const { logger } = require('@librechat/data-schemas');const { Constants, ViolationTypes, isEphemeralAgentId } = require('librechat-data-provider');const {sendEvent,+ toPendingSteer,getViolationInfo,buildMessageFiles,getReferencedQuotes,@@ -756,6 +757,32 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTitawait titleEventPromise;}+ // Steers that never reached an injection boundary (queued after the last+ // tool batch, or the run had none). The close-and-drain atomically stops+ // new enqueues first — a steer POST racing this finalization gets 404+ // (client sends it as a normal message) instead of a 202 whose payload+ // completeJob would then silently clear. Reported on the final event so+ // the client converts them to queued follow-up messages.+ let pendingSteers;+ try {+ const leftoverSteers = await GenerationJobManager.steering.closeAndDrain(+ streamId,+ jobCreatedAt,+ );+ if (leftoverSteers.length > 0) {+ pendingSteers = leftoverSteers.map(toPendingSteer);+ // Parked BEFORE the final event: a client with no live subscriber+ // recovers these via /chat/status (claim-on-read) within the+ // recovery TTL — the SSE copy alone is transient.+ await GenerationJobManager.steering.park(streamId, pendingSteers, {+ userId,+ tenantId: req.user?.tenantId,+ });+ }+ } catch (err) {+ logger.warn(`[ResumableAgentController] Failed to drain leftover steers`, err);+ }+if (!wasAbortedBeforeComplete) {const finalEvent = {final: true,@@ -763,6 +790,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTittitle: conversation.title,requestMessage: sanitizeMessageForTransmit(userMessage),responseMessage: { ...response },+ ...(pendingSteers && { pendingSteers }),};logger.debug(`[ResumableAgentController] Emitting FINAL event`, {@@ -783,6 +811,7 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTittitle: conversation.title,requestMessage: sanitizeMessageForTransmit(userMessage),responseMessage: { ...response, unfinished: true },+ ...(pendingSteers && { pendingSteers }),};logger.debug(`[ResumableAgentController] Emitting ABORTED FINAL event`, {@@ -849,6 +878,31 @@ const ResumableAgentController = async (req, res, next, initializeClient, addTit// abortJob already handled emitDone and completeJob} else {logger.error(`[ResumableAgentController] Generation error for ${streamId}:`, error);+ // Close the steer queue BEFORE the error event reaches clients: a+ // steer POST racing this failure gets 404 (client queues or sends it)+ // instead of a 202 whose payload would vanish with the job. Text+ // recovery is client-side — acknowledged chips convert to queued.+ try {+ const erroredLeftovers = await GenerationJobManager.steering.closeAndDrain(+ streamId,+ jobCreatedAt,+ );+ if (erroredLeftovers.length > 0) {+ // The error event is a bare string — park the acknowledged+ // steers so a reloaded/disconnected client can still recover+ // them via /chat/status instead of losing them with the queue.+ await GenerationJobManager.steering.park(+ streamId,+ erroredLeftovers.map(toPendingSteer),+ { userId, tenantId: req.user?.tenantId },+ );+ }+ } catch (drainErr) {+ logger.warn(+ `[ResumableAgentController] Failed to close steer queue on error`,+ drainErr,+ );+ }await GenerationJobManager.emitError(streamId, error.message || 'Generation failed');GenerationJobManager.completeJob(streamId, error.message);}diff --git a/api/server/controllers/agents/resume.js b/api/server/controllers/agents/resume.jsindex 4c01063571..7f0fc2d106 100644--- a/api/server/controllers/agents/resume.js+++ b/api/server/controllers/agents/resume.js@@ -16,6 +16,7 @@ const {filterMalformedContentParts,decrementPendingRequest,checkAndIncrementPendingRequest,+ toPendingSteer,} = require('@librechat/api');const { disposeClient } = require('~/server/cleanup');const {@@ -343,6 +344,32 @@ async function finalizeResumedTurn({ req, client, job, streamId, conversationId,return;}+ // Steers that never reached an injection boundary during the resumed+ // segment — mirror the normal request path's terminal drain: the atomic+ // close (createdAt-guarded) rejects a steer POST racing this finalization,+ // and the leftovers ride the final event as queued follow-ups instead of+ // being 202-ACKed and then silently cleared by completeJob.+ let pendingSteers;+ try {+ const leftoverSteers = await GenerationJobManager.steering.closeAndDrain(+ streamId,+ job.createdAt,+ );+ if (leftoverSteers.length > 0) {+ pendingSteers = leftoverSteers.map(toPendingSteer);+ // Same no-subscriber recovery as the normal final path (claim-on-read+ // via /chat/status within the recovery TTL). NOTE: `job` is the manager+ // facade — owner fields live under `metadata` (a bare `job.userId` is+ // undefined and would make the parked payload unclaimable).+ await GenerationJobManager.steering.park(streamId, pendingSteers, {+ userId: job.metadata?.userId,+ tenantId: job.metadata?.tenantId,+ });+ }+ } catch (drainErr) {+ logger.warn('[ResumeAgentController] Failed to drain leftover steers', drainErr);+ }+const finalEvent = {final: true,conversation,@@ -361,6 +388,7 @@ async function finalizeResumedTurn({ req, client, job, streamId, conversationId,}): null,responseMessage: { ...responseMessage },+ ...(pendingSteers && { pendingSteers }),};await GenerationJobManager.emitDone(streamId, finalEvent);@@ -681,6 +709,25 @@ const ResumeAgentController = async (req, res, next, initializeClient, addTitle)`[ResumeAgentController] Skipping failed-resume finalization — job ${streamId} was replaced`,);} else {+ // A steer 202-accepted during the failed resume segment would otherwise+ // be silently cleared by completeJob's backstop — mirror the normal+ // request error path: close the queue BEFORE the error event (racing+ // steer POSTs get 404) and park the leftovers for /chat/status recovery.+ try {+ const leftoverSteers = await GenerationJobManager.steering.closeAndDrain(+ streamId,+ job.createdAt,+ );+ if (leftoverSteers.length > 0) {+ // Facade shape: owner fields are under `metadata` (see finalize).+ await GenerationJobManager.steering.park(streamId, leftoverSteers.map(toPendingSteer), {+ userId: job.metadata?.userId,+ tenantId: job.metadata?.tenantId,+ });+ }+ } catch (drainErr) {+ logger.warn('[ResumeAgentController] Failed to drain steers on resume failure', drainErr);+ }try {await GenerationJobManager.emitError(streamId, err?.message ?? 'Resume failed');} catch (emitErr) {diff --git a/api/server/controllers/agents/steer.js b/api/server/controllers/agents/steer.jsnew file mode 100644index 0000000000..baa86de010--- /dev/null+++ b/api/server/controllers/agents/steer.js@@ -0,0 +1,111 @@+const { checkAccess, handleSteerRequest, handleSteerCancel } = require('@librechat/api');+const { logger, ResourceCapabilityMap } = require('@librechat/data-schemas');+const {+ Permissions,+ ResourceType,+ PermissionBits,+ PermissionTypes,+ isAgentsEndpoint,+ isEphemeralAgentId,+} = require('librechat-data-provider');+const { checkPermission } = require('~/server/services/PermissionService');+const { hasCapability } = require('~/server/middleware/roles/capabilities');+const db = require('~/models');++/**+ * Steer-time agent authorization, mirroring the chat route's middlewares+ * (`checkAgentAccess` + `canAccessAgentFromBody`) against the ORIGINATING+ * run's identity from job metadata instead of the request body:+ * - role gate: AGENTS:USE via `checkAccess`, applied exactly when chat.js+ * would run it (`skipAgentCheck` skips non-agents endpoints);+ * - resource gate: `canAccessResource`'s capability bypass + `checkPermission`+ * VIEW on the resolved agent, skipped for ephemeral/no-agent runs.+ *+ * @param {import('express').Request} req+ * @returns {(run: import('@librechat/api').SteerRunContext) => Promise<boolean>}+ */+const createAgentAccessCheck =+ (req) =>+ async ({ agentId, endpoint }) => {+ const hasRealAgent = agentId != null && !isEphemeralAgentId(agentId);+ const roleGateApplies = endpoint == null ? hasRealAgent : isAgentsEndpoint(endpoint);+ if (roleGateApplies) {+ const roleAllowed = await checkAccess({+ req,+ user: req.user,+ permissionType: PermissionTypes.AGENTS,+ permissions: [Permissions.USE],+ getRoleByName: db.getRoleByName,+ });+ if (!roleAllowed) {+ return false;+ }+ }+ if (!hasRealAgent) {+ return true;+ }+ let bypass = false;+ try {+ bypass = await hasCapability(req.user, ResourceCapabilityMap[ResourceType.AGENT]);+ } catch {+ bypass = false;+ }+ if (bypass) {+ return true;+ }+ const agent = await db.getAgent({ id: agentId });+ if (!agent) {+ return false;+ }+ return checkPermission({+ userId: req.user.id,+ role: req.user.role,+ resourceType: ResourceType.AGENT,+ resourceId: agent._id,+ requiredPermission: PermissionBits.VIEW,+ });+ };++/**+ * POST /api/agents/chat/steer+ *+ * Thin wrapper: the full guard ladder (validation, file sanitization,+ * capability gate, ownership/tenant checks, agent access, owner-scoped file+ * resolve, status-guarded enqueue) lives in `@librechat/api`+ * (`handleSteerRequest`), which returns the HTTP status + JSON body to+ * serialize verbatim. DB access and permission services are injected here.+ */+const SteerController = async (req, res) => {+ try {+ const { status, body } = await handleSteerRequest(req.user ?? {}, req.body ?? {}, {+ getFiles: db.getFiles,+ updateFilesUsage: db.updateFilesUsage,+ checkAgentAccess: createAgentAccessCheck(req),+ });+ return res.status(status).json(body);+ } catch (error) {+ logger.error('[SteerController] Failed to queue steer', error);+ return res.status(500).json({ code: 'STEER_FAILED' });+ }+};++/**+ * POST /api/agents/chat/steer/cancel+ *+ * Removes a still-queued steer before injection. `removed: false` is not an+ * error — the cancel lost its race (already injected, or the run ended) and+ * the client defers to the events it will receive. No agent-access check:+ * a cancel injects nothing model-bound, so ownership checks suffice.+ */+const SteerCancelController = async (req, res) => {+ try {+ const { status, body } = await handleSteerCancel(req.user ?? {}, req.body ?? {});+ return res.status(status).json(body);+ } catch (error) {+ logger.error('[SteerCancelController] Failed to cancel steer', error);+ return res.status(500).json({ code: 'STEER_CANCEL_FAILED' });+ }+};++module.exports = SteerController;+module.exports.SteerCancelController = SteerCancelController;diff --git a/api/server/routes/agents/__tests__/abort.spec.js b/api/server/routes/agents/__tests__/abort.spec.jsindex c9cc6b5b0f..538e01b243 100644--- a/api/server/routes/agents/__tests__/abort.spec.js+++ b/api/server/routes/agents/__tests__/abort.spec.js@@ -47,6 +47,7 @@ jest.mock('~/server/middleware', () => ({req.user = { id: 'test-user-123' };next();},+ moderateText: (req, res, next) => next(),messageIpLimiter: (req, res, next) => next(),configMiddleware: (req, res, next) => next(),messageUserLimiter: (req, res, next) => next(),diff --git a/api/server/routes/agents/__tests__/streamTenant.spec.js b/api/server/routes/agents/__tests__/streamTenant.spec.jsindex 708a071228..55d96d8cc3 100644--- a/api/server/routes/agents/__tests__/streamTenant.spec.js+++ b/api/server/routes/agents/__tests__/streamTenant.spec.js@@ -39,6 +39,7 @@ jest.mock('~/server/middleware', () => ({req.user = { id: mockUserId, tenantId: mockTenantId };next();},+ moderateText: (req, res, next) => next(),messageIpLimiter: (req, res, next) => next(),configMiddleware: (req, res, next) => next(),messageUserLimiter: (req, res, next) => next(),diff --git a/api/server/routes/agents/index.js b/api/server/routes/agents/index.jsindex 81612197e8..759d9c0177 100644--- a/api/server/routes/agents/index.js+++ b/api/server/routes/agents/index.js@@ -9,17 +9,20 @@ const {isHITLEnabled,deleteAgentCheckpoint,attachAskUserQuestionArgs,+ createMessageFilterPii,} = require('@librechat/api');const { createSseStreamTelemetry } = require('@librechat/api/telemetry');const { logger } = require('@librechat/data-schemas');const {uaParser,checkBan,+ moderateText,requireJwtAuth,messageIpLimiter,configMiddleware,messageUserLimiter,} = require('~/server/middleware');+const SteerController = require('~/server/controllers/agents/steer');const { saveMessage } = require('~/models');const responses = require('./responses');const openai = require('./openai');@@ -193,7 +196,18 @@ router.get('/chat/status/:conversationId', async (req, res) => {const job = await GenerationJobManager.getJob(conversationId);if (!job) {- return res.json({ active: false });+ // The default completeJob path deletes the job record immediately, so the+ // jobless branch IS the common reload-after-terminal case — parked steers+ // live under their own bounded-TTL key and the claim authorizes against+ // the payload's stored owner (no job record is left to check).+ const claimed = await GenerationJobManager.steering.claim(conversationId, {+ userId: req.user.id,+ tenantId: req.user.tenantId,+ });+ return res.json({+ active: false,+ ...(claimed.length > 0 && { unrecoveredSteers: claimed }),+ });}if (job.metadata.userId !== req.user.id) {@@ -215,8 +229,23 @@ router.get('/chat/status/:conversationId', async (req, res) => {const pendingLive = job.status === 'requires_action' && !isPendingActionStale({ pendingAction });const isActive = job.status === 'running' || pendingLive;+ /** Acknowledged steers the terminal drains parked because no subscriber was+ * live to receive the final/abort event — claim-on-read (cleared once+ * returned) so the reloading client restores them as queued follow-ups. */+ let unrecoveredSteers;+ if (!isActive) {+ const claimed = await GenerationJobManager.steering.claim(conversationId, {+ userId: req.user.id,+ tenantId: req.user.tenantId,+ });+ if (claimed.length > 0) {+ unrecoveredSteers = claimed;+ }+ }+res.json({active: isActive,+ ...(unrecoveredSteers && { unrecoveredSteers }),streamId: conversationId,status: job.status,aggregatedContent: resumeState?.aggregatedContent ?? [],@@ -379,13 +408,58 @@ router.post('/chat/abort', configMiddleware, async (req, res) => {}}- return res.json({ success: true, aborted: jobStreamId });+ return res.json({+ success: true,+ aborted: jobStreamId,+ // Steers that never reached an injection boundary — restored client-side+ // as queued chips so the user's words aren't dropped with the abort.+ ...(abortResult.pendingSteers?.length > 0 && { pendingSteers: abortResult.pendingSteers }),+ });}logger.warn(`[AgentStream] Job not found for streamId: ${jobStreamId}`);return res.status(404).json({ error: 'Job not found', streamId: jobStreamId });});+/**+ * @route POST /chat/steer+ * @desc Queue a mid-run user message for injection at the next tool boundary+ * @access Private+ * @description Mounted before chatRouter to bypass buildEndpointOption middleware,+ * but a steer is model-bound user text, so it carries the same guards as a normal+ * message IN THE SAME ORDER as chat.js: the configured IP/user rate limiters,+ * the PII filter FIRST (blocked sensitive text must never reach the external+ * moderation endpoint), then `moderateText`.+ */+const steerLimiters = [];+if (isEnabled(LIMIT_MESSAGE_IP)) {+ steerLimiters.push(messageIpLimiter);+}+if (isEnabled(LIMIT_MESSAGE_USER)) {+ steerLimiters.push(messageUserLimiter);+}+router.post(+ '/chat/steer',+ configMiddleware,+ ...steerLimiters,+ createMessageFilterPii({ getConfig: (req) => req.config?.messageFilter?.pii }),+ moderateText,+ SteerController,+);++/**+ * @route POST /chat/steer/cancel+ * @desc Remove a still-queued steer before injection (no model-bound content,+ * so no PII/moderation pass — just the shared rate limiters)+ * @access Private+ */+router.post(+ '/chat/steer/cancel',+ configMiddleware,+ ...steerLimiters,+ SteerController.SteerCancelController,+);+router.use('/', v1);const chatRouter = express.Router();diff --git a/api/server/routes/files/files.js b/api/server/routes/files/files.jsindex bfd0faaf0d..fafa02e66d 100644--- a/api/server/routes/files/files.js+++ b/api/server/routes/files/files.js@@ -4,6 +4,7 @@ const { logger, SystemCapabilities } = require('@librechat/data-schemas');const {logAxiosError,refreshS3FileUrls,+ handleFilesUsageRequest,resolveUploadErrorMessage,verifyAgentUploadPermission,} = require('@librechat/api');@@ -138,6 +139,26 @@ router.get('/config', async (req, res) => {}});+/**+ * POST /files/usage+ *+ * Owner-scoped TTL touch for uploads held in a client-side queue (mid-run+ * queued messages), so the upload-window TTL cannot reap them before drain.+ * Thin wrapper: validation, cap, and best-effort semantics live in+ * `@librechat/api` (`handleFilesUsageRequest`).+ */+router.post('/usage', async (req, res) => {+ try {+ const { status, body } = await handleFilesUsageRequest(req.user ?? {}, req.body ?? {}, {+ updateFilesUsage: db.updateFilesUsage,+ });+ return res.status(status).json(body);+ } catch (error) {+ logger.error('[/files/usage] Failed to mark files used', error);+ return res.status(500).json({ code: 'FILES_USAGE_FAILED' });+ }+});+router.delete('/', async (req, res) => {try {const { files: _files } = req.body;diff --git a/api/server/routes/files/files.test.js b/api/server/routes/files/files.test.jsindex c2930f3294..6cd60d43d6 100644--- a/api/server/routes/files/files.test.js+++ b/api/server/routes/files/files.test.js@@ -936,4 +936,77 @@ describe('File Routes - Delete with Agent Access', () => {);});});++ describe('POST /files/usage', () => {+ it('marks owned files used and clears the upload TTL', async () => {+ const ownFileId = uuidv4();+ await createFile({+ user: otherUserId,+ file_id: ownFileId,+ filename: 'queued.png',+ filepath: '/uploads/queued.png',+ bytes: 10,+ type: 'image/png',+ });+ await File.updateOne({ file_id: ownFileId }, { $set: { expiresAt: new Date() } });++ const response = await request(app)+ .post('/files/usage')+ .send({ file_ids: [ownFileId] });++ expect(response.status).toBe(200);+ expect(response.body).toEqual({ marked: 1 });+ const marked = await File.findOne({ file_id: ownFileId }).lean();+ expect(marked.usage).toBe(1);+ expect(marked.expiresAt).toBeUndefined();+ });++ it("is owner-scoped: another user's file stays untouched (best-effort 200)", async () => {+ await File.updateOne({ file_id: fileId }, { $set: { expiresAt: new Date() } });++ const response = await request(app)+ .post('/files/usage')+ .send({ file_ids: [fileId] });++ expect(response.status).toBe(200);+ expect(response.body).toEqual({ marked: 0 });+ const untouched = await File.findOne({ file_id: fileId }).lean();+ expect(untouched.usage).toBe(0);+ expect(untouched.expiresAt).toBeDefined();+ });++ it('rejects a list over the cap', async () => {+ const file_ids = Array.from({ length: 11 }, () => uuidv4());+ const response = await request(app).post('/files/usage').send({ file_ids });+ expect(response.status).toBe(400);+ expect(response.body.code).toBe('TOO_MANY_FILES');+ });++ it('rejects invalid bodies', async () => {+ expect((await request(app).post('/files/usage').send({})).status).toBe(400);+ expect((await request(app).post('/files/usage').send({ file_ids: 'f1' })).status).toBe(400);+ expect(+ (+ await request(app)+ .post('/files/usage')+ .send({ file_ids: [1] })+ ).status,+ ).toBe(400);+ });++ it('rejects unauthenticated requests', async () => {+ const bareApp = express();+ bareApp.use(express.json());+ bareApp.use((req, res, next) => {+ req.app.locals = {};+ next();+ });+ bareApp.use('/files', router);++ const response = await request(bareApp)+ .post('/files/usage')+ .send({ file_ids: [fileId] });+ expect(response.status).toBe(401);+ });+ });});diff --git a/api/server/routes/files/index.js b/api/server/routes/files/index.jsindex ec00750a60..f7e2428c4c 100644--- a/api/server/routes/files/index.js+++ b/api/server/routes/files/index.js@@ -31,9 +31,10 @@ const initialize = async () => {const { fileUploadIpLimiter, fileUploadUserLimiter } = createFileLimiters();- /** Apply rate limiters to all POST routes (excluding /speech which is handled above) */+ /** Apply rate limiters to all POST routes (excluding /speech which is handled+ * above, and /usage — a metadata touch that must not consume upload quota) */router.use((req, res, next) => {- if (req.method === 'POST' && !req.path.startsWith('/speech')) {+ if (req.method === 'POST' && !req.path.startsWith('/speech') && req.path !== '/usage') {return fileUploadIpLimiter(req, res, (err) => {if (err) {return next(err);diff --git a/client/src/components/Chat/ChatView.tsx b/client/src/components/Chat/ChatView.tsxindex 5ab4efb1e9..c894e251d5 100644--- a/client/src/components/Chat/ChatView.tsx+++ b/client/src/components/Chat/ChatView.tsx@@ -11,6 +11,7 @@ import {useResumeOnLoad,useAdaptiveSSE,useChatHelpers,+ useQueueDrain,useLocalize,} from '~/hooks';import { ChatContext, AddedChatContext, ChatFormProvider, useFileMapContext } from '~/Providers';@@ -73,6 +74,9 @@ function ChatView({ index = 0, project }: { index?: number; project?: TChatProje// Wait for messages to load before resuming to avoid race conditionuseResumeOnLoad(conversationId, chatHelpers.getMessages, index, !isLoading);+ // Auto-send queued follow-up messages once a run finishes cleanly.+ useQueueDrain(index, conversationId, chatHelpers.ask);+let content: JSX.Element | null | undefined;const isLandingPage =(!messagesTree || messagesTree.length === 0) &&diff --git a/client/src/components/Chat/Input/ChatForm.tsx b/client/src/components/Chat/Input/ChatForm.tsxindex 894e234592..a37fe87084 100644--- a/client/src/components/Chat/Input/ChatForm.tsx+++ b/client/src/components/Chat/Input/ChatForm.tsx@@ -1,10 +1,11 @@import { memo, useRef, useMemo, useEffect, useState, useCallback } from 'react';import { useWatch } from 'react-hook-form';import { TextareaAutosize } from '@librechat/client';-import { useRecoilState, useRecoilValue } from 'recoil';+import { useRecoilState, useRecoilValue, useRecoilCallback } from 'recoil';import { Constants, isAssistantsEndpoint, isAgentsEndpoint } from 'librechat-data-provider';-import type { TConversation } from 'librechat-data-provider';+import type { TMessage, TConversation } from 'librechat-data-provider';import type { ExtendedFile, FileSetter, ConvoGenerator } from '~/common';+import type { QueuedMessageContext } from '~/hooks/Chat/useSteering';import {useTextarea,useAutoSave,@@ -25,10 +26,13 @@ import PendingManualSkillsChips from './PendingManualSkillsChips';import useAskAnswerMode from '~/hooks/Input/useAskAnswerMode';import AskUserQuestionPopover from './AskUserQuestionPopover';import { cn, getModelSpec, removeFocusRings } from '~/utils';+import DuringRunSendButton from './DuringRunSendButton';import { useGetStartupConfig } from '~/data-provider';import { mainTextareaId, BadgeItem } from '~/common';+import PendingSteerChips from './PendingSteerChips';import PendingQuoteChips from './PendingQuoteChips';import AttachFileChat from './Files/AttachFileChat';+import useSteering from '~/hooks/Chat/useSteering';import FileFormChat from './Files/FileFormChat';import TextareaHeader from './TextareaHeader';import PromptsCommand from './PromptsCommand';@@ -57,6 +61,7 @@ interface ChatFormProps {setFilesLoading: React.Dispatch<React.SetStateAction<boolean>>;newConversation: ConvoGenerator;handleStopGenerating: (e: React.MouseEvent<HTMLButtonElement>) => void;+ stopGenerating: () => void;}const ChatForm = memo(function ChatForm({@@ -70,6 +75,7 @@ const ChatForm = memo(function ChatForm({setFilesLoading,newConversation,handleStopGenerating,+ stopGenerating,}: ChatFormProps) {const submitButtonRef = useRef<HTMLButtonElement>(null);const textAreaRef = useRef<HTMLTextAreaElement>(null);@@ -181,6 +187,104 @@ const ChatForm = memo(function ChatForm({const { submitMessage, submitPrompt } = useSubmitMessage();+ /** Queued/steered sends carry their FULL submission context: explicit+ * (possibly empty) overrides stop `ask` from vacuuming quotes or skill+ * picks the user has staged in the composer for their NEXT message. */+ const sendNow = useCallback(+ (text: string, overrideFiles?: TMessage['files'], context?: QueuedMessageContext) =>+ submitMessage({+ text,+ overrideFiles,+ overrideQuotes: context?.quotes ?? [],+ overrideManualSkills: context?.manualSkills ?? [],+ }),+ [submitMessage],+ );+ /** Chip "Edit message" restore: quote chips + skill picks merge back into+ * their compose-time atoms (the chips above the textarea re-render them). */+ const restoreComposerContext = useRecoilCallback(+ ({ set }) =>+ (context?: QueuedMessageContext) => {+ const { quotes, manualSkills } = context ?? {};+ if (quotes != null && quotes.length > 0) {+ set(store.pendingQuotesByConvoId(conversationId), (prev) => [+ ...new Set([...prev, ...quotes]),+ ]);+ }+ if (manualSkills != null && manualSkills.length > 0) {+ set(store.pendingManualSkillsByConvoId(conversationId), (prev) => [+ ...new Set([...prev, ...manualSkills]),+ ]);+ }+ },+ [conversationId],+ );+ /** Chip "Edit message": the text replaces the composer draft and the chip's+ * attachments merge back into the composer file map (already uploaded, so+ * they restore as completed entries — same shape as draft recovery). */+ const editToComposer = useCallback(+ (text: string, chipFiles?: TMessage['files'], context?: QueuedMessageContext) => {+ methods.setValue('text', text, { shouldDirty: true });+ if (chipFiles != null && chipFiles.length > 0) {+ setFiles((prev) => {+ const next = new Map(prev);+ for (const file of chipFiles) {+ if (!file.file_id) {+ continue;+ }+ next.set(file.file_id, {+ file_id: file.file_id,+ filename: file.filename,+ filepath: file.filepath,+ type: file.type ?? '',+ height: file.height,+ width: file.width,+ size: file.bytes ?? 0,+ progress: 1,+ attached: true,+ });+ }+ return next;+ });+ }+ restoreComposerContext(context);+ textAreaRef.current?.focus();+ },+ [methods, setFiles, restoreComposerContext],+ );+ const steering = useSteering({+ index,+ conversationId,+ conversation,+ isSubmitting,+ answerModeActive: answerMode.active,+ files,+ setFiles,+ filesLoading,+ sendNow,+ stopGenerating,+ });++ /** ⌘/Ctrl+Enter = the non-default during-run action, ⌥/Alt+Enter =+ * interrupt & send — the counterpart of Enter's `submitDuringRun`. */+ const handleDuringRunModifier = useCallback(+ (kind: 'other' | 'interrupt') => {+ const text = methods.getValues('text');+ let consumed = false;+ if (kind === 'interrupt') {+ consumed = steering.interruptAndSend(text);+ } else if (steering.effectiveAction === 'steer') {+ consumed = steering.queueFromComposer(text);+ } else {+ consumed = steering.steerFromComposer(text);+ }+ if (consumed) {+ methods.reset();+ }+ },+ [methods, steering],+ );+const handleKeyUp = useHandleKeyUp({index,textAreaRef,@@ -200,6 +304,9 @@ const ChatForm = memo(function ChatForm({placeholder: answerMode.active? (answerMode.otherLabel ?? localize('com_ui_something_else')): placeholder,+ // Enter stays live during a run when it can steer/queue instead of send.+ allowSubmitWhileGenerating: steering.duringRunActive,+ onDuringRunModifier: steering.duringRunActive ? handleDuringRunModifier : undefined,});useQueryParams({ textAreaRef });@@ -244,6 +351,23 @@ const ChatForm = memo(function ChatForm({const isMoreThanThreeRows = visualRowCount > 3;+ /** One button slot while a run is generating: with composer text the send+ * button takes over (Enter steers/queues; hover reveals all actions);+ * clearing the text restores Stop. */+ const duringRunSlot =+ steering.duringRunActive && (textValue?.trim() ?? '') !== '' ? (+ <DuringRunSendButton+ ref={submitButtonRef}+ control={methods.control}+ steering={steering}+ getText={() => methods.getValues('text')}+ onConsumed={() => methods.reset()}+ disabled={filesLoading}+ />+ ) : (+ <StopButton stop={handleStopGenerating} setShowStopButton={setShowStopButton} />+ );+const baseClasses = useMemo(() =>cn(@@ -263,6 +387,14 @@ const ChatForm = memo(function ChatForm({if (answerMode.active && answerMode.submitText(data.text)) {return;}+ // During a run, a submit steers or queues per the effective action+ // instead of starting a new turn (which would be dropped anyway).+ if (steering.duringRunActive) {+ if (steering.submitDuringRun(data.text)) {+ methods.reset();+ }+ return;+ }return submitMessage(data);})}className={cn(@@ -318,6 +450,13 @@ const ChatForm = memo(function ChatForm({<TextareaHeader addedConvo={addedConvo} setAddedConvo={setAddedConvo} /><PendingManualSkillsChips conversationId={conversationId} />{quotesEnabled && <PendingQuoteChips conversationId={conversationId} />}+ {steering.enabled && (+ <PendingSteerChips+ conversationId={conversationId}+ steering={steering}+ onEditToComposer={editToComposer}+ />+ )}{/* WIP */}<EditBadgesisEditingChatBadges={isEditingBadges}@@ -430,22 +569,20 @@ const ChatForm = memo(function ChatForm({/>)}<div className={`${isRTL ? 'ml-2' : 'mr-2'}`}>- {isSubmitting && showStopButton && !answerMode.active ? (- <StopButton stop={handleStopGenerating} setShowStopButton={setShowStopButton} />- ) : (- endpoint && (- <SendButton- ref={submitButtonRef}- control={methods.control}- disabled={- filesLoading ||- disableInputs ||- isNotAppendable ||- (isSubmitting && !answerMode.active)- }- />- )- )}+ {isSubmitting && showStopButton && !answerMode.active+ ? duringRunSlot+ : endpoint && (+ <SendButton+ ref={submitButtonRef}+ control={methods.control}+ disabled={+ filesLoading ||+ disableInputs ||+ isNotAppendable ||+ (isSubmitting && !answerMode.active)+ }+ />+ )}</div></div>{TextToSpeech && automaticPlayback && <StreamAudio index={index} />}@@ -472,6 +609,7 @@ function ChatFormWrapper({ index = 0, placeholder }: { index?: number; placeholdsetFilesLoading,newConversation,handleStopGenerating,+ stopGenerating,} = useChatContext();/**@@ -512,6 +650,12 @@ function ChatFormWrapper({ index = 0, placeholder }: { index?: number; placehold[],);+ const stopRef = useRef(stopGenerating);+ stopRef.current = stopGenerating;+ const stableStop = useCallback(() => {+ void stopRef.current();+ }, []);+return (<ChatFormindex={index}@@ -524,6 +668,7 @@ function ChatFormWrapper({ index = 0, placeholder }: { index?: number; placeholdsetFilesLoading={setFilesLoading}newConversation={stableNewConversation}handleStopGenerating={stableHandleStop}+ stopGenerating={stableStop}/>);}diff --git a/client/src/components/Chat/Input/DuringRunSendButton.tsx b/client/src/components/Chat/Input/DuringRunSendButton.tsxnew file mode 100644index 0000000000..01f6d57fa1--- /dev/null+++ b/client/src/components/Chat/Input/DuringRunSendButton.tsx@@ -0,0 +1,147 @@+import React, { forwardRef } from 'react';+import * as Ariakit from '@ariakit/react';+import { useWatch } from 'react-hook-form';+import { SendIcon } from '@librechat/client';+import { Zap, Clock, OctagonPause } from 'lucide-react';+import type { Control } from 'react-hook-form';+import type { SteeringControls } from '~/hooks/Chat/useSteering';+import { isMacPlatform } from '~/utils/shortcuts';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';++const ROW_CLASS =+ 'flex w-full cursor-pointer items-center gap-2 rounded-lg px-2.5 py-1.5 text-sm text-text-primary hover:bg-surface-tertiary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-xheavy aria-disabled:cursor-not-allowed aria-disabled:opacity-50';++function Kbd({ children }: { children: React.ReactNode }) {+ return (+ <kbd className="ml-auto rounded-md bg-surface-tertiary px-1.5 py-0.5 font-sans text-xs text-text-secondary">+ {children}+ </kbd>+ );+}++type ActionRow = {+ key: string;+ label: string;+ kbd: string;+ icon: React.ReactNode;+ disabled?: boolean;+ onClick: () => void;+};++type DuringRunSendButtonProps = {+ control: Control<{ text: string }>;+ steering: SteeringControls;+ getText: () => string;+ onConsumed: () => void;+ /** External hold (e.g. uploads in flight), mirroring the normal send button. */+ disabled?: boolean;+};++/**+ * The send button while a run is generating: it takes over the send/stop slot+ * (and `submitButtonRef`, so Enter's synthetic click routes here) whenever the+ * composer holds text — submitting steers or queues per the effective action.+ * Hovering it reveals the full action list with its shortcuts: steer, queue+ * (⌘/Ctrl+Enter routes to the non-default action), and interrupt & send+ * (⌥/Alt+Enter). Clearing the composer restores the Stop button.+ */+const DuringRunSendButton = React.memo(+ forwardRef((props: DuringRunSendButtonProps, ref: React.ForwardedRef<HTMLButtonElement>) => {+ const localize = useLocalize();+ const { steering } = props;+ const data = useWatch({ control: props.control });+ const content = data?.text?.trim();+ const primary = steering.effectiveAction;+ const modEnter = isMacPlatform ? '⌘⏎' : 'Ctrl ⏎';+ const altEnter = isMacPlatform ? '⌥⏎' : 'Alt ⏎';++ const runAction = (action: (text: string) => boolean | void) => {+ const text = props.getText().trim();+ if (text.length === 0) {+ return;+ }+ if (action(text) !== false) {+ props.onConsumed();+ }+ };++ const steerRow: ActionRow = {+ key: 'steer',+ label: localize('com_ui_steer'),+ kbd: primary === 'steer' ? '⏎' : modEnter,+ icon: <Zap className="h-4 w-4 text-amber-500" aria-hidden="true" />,+ // Gate on availability, not the default action — the row exists to+ // override a queue-preferring default with an explicit steer.+ disabled: !steering.canSteer,+ onClick: () => runAction((text) => steering.steerFromComposer(text)),+ };+ const queueRow: ActionRow = {+ key: 'queue',+ label: localize('com_ui_queue'),+ kbd: primary === 'queue' ? '⏎' : modEnter,+ icon: <Clock className="h-4 w-4 text-cyan-500" aria-hidden="true" />,+ onClick: () => runAction((text) => steering.queueFromComposer(text)),+ };+ const interruptRow: ActionRow = {+ key: 'interrupt',+ label: localize('com_ui_interrupt_send'),+ kbd: altEnter,+ icon: <OctagonPause className="h-4 w-4 text-red-500" aria-hidden="true" />,+ onClick: () => runAction((text) => steering.interruptAndSend(text)),+ };+ const rows = primary === 'steer' ? [steerRow, queueRow] : [queueRow, steerRow];+ rows.push(interruptRow);++ const label =+ primary === 'steer' ? localize('com_ui_steer_send') : localize('com_ui_queue_send');++ return (+ <Ariakit.HovercardProvider placement="top-end" showTimeout={100} hideTimeout={150}>+ <Ariakit.HovercardAnchor+ render={+ <button+ ref={ref}+ aria-label={label}+ id="during-run-send-button"+ disabled={!content || props.disabled === true}+ className={cn(+ 'rounded-full bg-text-primary p-1.5 text-text-primary outline-offset-4 transition-all duration-200 disabled:cursor-not-allowed disabled:text-text-secondary disabled:opacity-10',+ )}+ data-testid="during-run-send-button"+ data-during-run-action={primary}+ type="submit"+ >+ <span data-state="closed">+ <SendIcon size={24} />+ </span>+ </button>+ }+ />+ <Ariakit.Hovercard+ portal+ gutter={8}+ unmountOnHide+ aria-label={localize('com_ui_during_run_actions')}+ className="z-50 min-w-[12rem] rounded-xl border border-border-light bg-surface-secondary p-1.5 text-text-primary shadow-lg outline-none"+ >+ {rows.map((row) => (+ <button+ key={row.key}+ type="button"+ className={ROW_CLASS}+ aria-disabled={row.disabled === true}+ onClick={row.disabled === true ? undefined : row.onClick}+ >+ {row.icon}+ {row.label}+ <Kbd>{row.kbd}</Kbd>+ </button>+ ))}+ </Ariakit.Hovercard>+ </Ariakit.HovercardProvider>+ );+ }),+);++export default DuringRunSendButton;diff --git a/client/src/components/Chat/Input/PendingSteerChips.tsx b/client/src/components/Chat/Input/PendingSteerChips.tsxnew file mode 100644index 0000000000..bce3d644d5--- /dev/null+++ b/client/src/components/Chat/Input/PendingSteerChips.tsx@@ -0,0 +1,320 @@+import { memo, useMemo } from 'react';+import { useRecoilValue } from 'recoil';+import * as Ariakit from '@ariakit/react';+import {+ X,+ Zap,+ Send,+ Clock,+ Pencil,+ Trash2,+ Paperclip,+ RotateCcw,+ MoreHorizontal,+} from 'lucide-react';+import type { TMessage } from 'librechat-data-provider';+import type { SteeringControls, QueuedMessageContext } from '~/hooks/Chat/useSteering';+import type { PendingSteer, QueuedMessage } from '~/store/families';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';+import store from '~/store';++const ROW_CLASS =+ 'flex w-full items-center gap-2 rounded-xl border border-border-light bg-surface-secondary px-3 py-2 text-sm text-text-primary';+const PRIMARY_BTN_CLASS =+ 'flex shrink-0 items-center gap-1.5 rounded-lg px-2 py-1 text-sm text-text-secondary hover:bg-surface-tertiary hover:text-text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-xheavy';+const ICON_BTN_CLASS =+ 'shrink-0 rounded-full p-1 text-text-secondary hover:bg-surface-tertiary hover:text-text-primary focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-xheavy';+const MENU_CLASS =+ 'z-50 min-w-[13rem] rounded-xl border border-border-light bg-surface-secondary p-1.5 text-text-primary shadow-lg outline-none';+const MENU_ITEM_CLASS =+ 'flex w-full cursor-pointer items-center gap-2 rounded-lg px-2 py-1.5 text-sm text-text-primary data-[active-item]:bg-surface-tertiary aria-disabled:cursor-not-allowed aria-disabled:opacity-50';++type MenuEntry = {+ key: string;+ label: string;+ icon: React.ReactNode;+ onClick: () => void;+};++/** Per-row "…" overflow menu (edit / mode toggle / conversions). */+function RowMenu({ label, entries }: { label: string; entries: MenuEntry[] }) {+ const menu = Ariakit.useMenuStore({ placement: 'top-end' });+ return (+ <>+ <Ariakit.MenuButton store={menu} aria-label={label} className={ICON_BTN_CLASS}>+ <MoreHorizontal className="h-4 w-4" aria-hidden="true" />+ </Ariakit.MenuButton>+ <Ariakit.Menu store={menu} portal gutter={6} className={MENU_CLASS}>+ {entries.map((entry) => (+ <Ariakit.MenuItem+ key={entry.key}+ className={MENU_ITEM_CLASS}+ onClick={() => {+ entry.onClick();+ menu.hide();+ }}+ >+ {entry.icon}+ {entry.label}+ </Ariakit.MenuItem>+ ))}+ </Ariakit.Menu>+ </>+ );+}++function AttachmentCount({ count, label }: { count: number; label: string }) {+ if (count === 0) {+ return null;+ }+ return (+ <span className="flex shrink-0 items-center gap-0.5 text-xs text-text-secondary">+ <Paperclip className="h-3.5 w-3.5" aria-hidden="true" />+ {count}+ <span className="sr-only">{label}</span>+ </span>+ );+}++/**+ * The overflow item that flips the Enter-during-run default. Shown as the+ * OPPOSITE of the current default (the action you would switch to), matching+ * the reference UX ("Turn on queueing" while steer is the default).+ */+function useDefaultToggleEntry(steering: SteeringControls): MenuEntry {+ const localize = useLocalize();+ return useMemo(() => {+ const next = steering.defaultAction === 'steer' ? 'queue' : 'steer';+ return {+ key: 'toggle-default',+ label:+ next === 'queue'+ ? localize('com_ui_turn_on_queueing')+ : localize('com_ui_turn_on_steering'),+ icon:+ next === 'queue' ? (+ <Clock className="h-4 w-4 text-cyan-500" aria-hidden="true" />+ ) : (+ <Zap className="h-4 w-4 text-amber-500" aria-hidden="true" />+ ),+ onClick: () => steering.setDefaultAction(next),+ };+ }, [steering, localize]);+}++function QueuedRow({+ message,+ steering,+ onEditToComposer,+}: {+ message: QueuedMessage;+ steering: SteeringControls;+ onEditToComposer: (+ text: string,+ files?: TMessage['files'],+ context?: QueuedMessageContext,+ ) => void;+}) {+ const localize = useLocalize();+ const toggleEntry = useDefaultToggleEntry(steering);+ const fileCount = message.files?.length ?? 0;+ const canSteerNow = steering.duringRunActive && steering.canSteer;+ const showPrimary = canSteerNow || !steering.duringRunActive;++ const entries: MenuEntry[] = [+ {+ key: 'edit',+ label: localize('com_ui_edit_message'),+ icon: <Pencil className="h-4 w-4" aria-hidden="true" />,+ onClick: () => {+ steering.removeQueued(message.id);+ onEditToComposer(message.text, message.files, {+ quotes: message.quotes,+ manualSkills: message.manualSkills,+ });+ },+ },+ toggleEntry,+ ];++ return (+ <div role="listitem" className={ROW_CLASS} data-testid="queued-message-row">+ <Clock className="h-4 w-4 shrink-0 text-cyan-500" aria-hidden="true" />+ <span className="min-w-0 flex-1 truncate" title={message.text}>+ {message.text}+ </span>+ <AttachmentCount+ count={fileCount}+ label={localize('com_ui_queued_attachment_count', { 0: String(fileCount) })}+ />+ {showPrimary && (+ <button+ type="button"+ className={PRIMARY_BTN_CLASS}+ onClick={() => steering.sendQueuedNow(message)}+ >+ {canSteerNow ? (+ <>+ <Zap className="h-4 w-4 text-amber-500" aria-hidden="true" />+ {localize('com_ui_steer')}+ </>+ ) : (+ <>+ <Send className="h-4 w-4" aria-hidden="true" />+ {localize('com_ui_send_now')}+ </>+ )}+ </button>+ )}+ <button+ type="button"+ aria-label={localize('com_ui_remove_queued')}+ onClick={() => steering.removeQueued(message.id)}+ className={ICON_BTN_CLASS}+ >+ <Trash2 className="h-4 w-4" aria-hidden="true" />+ </button>+ <RowMenu label={localize('com_ui_more_options')} entries={entries} />+ </div>+ );+}++function FailedSteerRow({+ steer,+ steering,+ onEditToComposer,+}: {+ steer: PendingSteer;+ steering: SteeringControls;+ onEditToComposer: (+ text: string,+ files?: TMessage['files'],+ context?: QueuedMessageContext,+ ) => void;+}) {+ const localize = useLocalize();+ const toggleEntry = useDefaultToggleEntry(steering);++ const entries: MenuEntry[] = [+ {+ key: 'edit',+ label: localize('com_ui_edit_message'),+ icon: <Pencil className="h-4 w-4" aria-hidden="true" />,+ onClick: () => {+ steering.removeSteer(steer.steerId);+ onEditToComposer(steer.text, steer.files, {+ quotes: steer.quotes,+ manualSkills: steer.manualSkills,+ });+ },+ },+ {+ key: 'queue',+ label: localize('com_ui_convert_to_queue'),+ icon: <Clock className="h-4 w-4 text-cyan-500" aria-hidden="true" />,+ onClick: () =>+ steering.convertSteerToQueue(steer.steerId, steer.text, steer.files, {+ quotes: steer.quotes,+ manualSkills: steer.manualSkills,+ }),+ },+ toggleEntry,+ ];++ return (+ <div+ role="listitem"+ className={cn(ROW_CLASS, 'border-red-500/60')}+ data-testid="steer-message-row"+ >+ <Zap className="h-4 w-4 shrink-0 text-red-500" aria-hidden="true" />+ <span className="min-w-0 flex-1 truncate" title={steer.text}>+ {steer.text}+ </span>+ <span className="shrink-0 text-xs text-red-500">{localize('com_ui_steer_failed')}</span>+ <button+ type="button"+ className={PRIMARY_BTN_CLASS}+ onClick={() =>+ steering.retrySteer(steer.steerId, steer.text, steer.files, {+ quotes: steer.quotes,+ manualSkills: steer.manualSkills,+ })+ }+ >+ <RotateCcw className="h-4 w-4" aria-hidden="true" />+ {localize('com_ui_steer_retry')}+ </button>+ <button+ type="button"+ aria-label={localize('com_ui_remove_queued')}+ onClick={() => steering.removeSteer(steer.steerId)}+ className={ICON_BTN_CLASS}+ >+ <X className="h-4 w-4" aria-hidden="true" />+ </button>+ <RowMenu label={localize('com_ui_more_options')} entries={entries} />+ </div>+ );+}++/**+ * Stacked rows above the composer for during-run messages, mirroring the+ * reference UI: each row shows the message, a primary action, delete, and an+ * overflow menu with Edit message + the default-mode toggle.+ * - Failed steer rows (Zap, red): the POST failed, so the text never entered+ * the thread — kept recoverable with retry / edit / queue actions.+ * (Sending/pending steers render in-thread as user messages instead.)+ * - Queued rows (Clock): client-side follow-ups auto-sent after the run.+ */+function PendingSteerChips({+ conversationId,+ steering,+ onEditToComposer,+}: {+ conversationId: string;+ steering: SteeringControls;+ onEditToComposer: (+ text: string,+ files?: TMessage['files'],+ context?: QueuedMessageContext,+ ) => void;+}) {+ const localize = useLocalize();+ const steers = useRecoilValue(store.pendingSteersByConvoId(conversationId));+ const queued = useRecoilValue(store.queuedMessagesByConvoId(steering.queueKey));+ const failedSteers = useMemo(() => steers.filter((steer) => steer.status === 'failed'), [steers]);++ if (failedSteers.length === 0 && queued.length === 0) {+ return null;+ }++ return (+ <div+ className="flex flex-col gap-1.5 px-2 pt-2"+ role="list"+ aria-label={localize('com_ui_queued_messages')}+ data-testid="pending-steer-chips"+ >+ {failedSteers.map((steer) => (+ <FailedSteerRow+ key={steer.steerId}+ steer={steer}+ steering={steering}+ onEditToComposer={onEditToComposer}+ />+ ))}+ {queued.map((message) => (+ <QueuedRow+ key={message.id}+ message={message}+ steering={steering}+ onEditToComposer={onEditToComposer}+ />+ ))}+ </div>+ );+}++export default memo(PendingSteerChips);diff --git a/client/src/components/Chat/Messages/Content/ContentParts.tsx b/client/src/components/Chat/Messages/Content/ContentParts.tsxindex 148c8a3e2d..2d9a17501a 100644--- a/client/src/components/Chat/Messages/Content/ContentParts.tsx+++ b/client/src/components/Chat/Messages/Content/ContentParts.tsx@@ -14,6 +14,7 @@ import PendingSkillCall from './Parts/PendingSkillCall';import { EditTextPart, EmptyText } from './Parts';import ApprovalProvider from './ApprovalContext';import MemoryArtifacts from './MemoryArtifacts';+import PendingSteers from './PendingSteers';import ToolCallGroup from './ToolCallGroup';import Container from './Container';import Part from './Part';@@ -149,6 +150,9 @@ const ContentParts = memo(function ContentParts({}: ContentPartsProps) {const attachmentMap = useMemo(() => mapAttachments(attachments ?? []), [attachments]);const effectiveIsSubmitting = isLatestMessage ? isSubmitting : false;+ /** In-thread slot for not-yet-applied steers, only on the live streaming+ * message — everywhere else the persisted STEER parts are the record. */+ const showPendingSteers = !isCreatedByUser && isLatestMessage === true && effectiveIsSubmitting;const toolGroupExpansionRef = useRef(new Map<string, ToolCallGroupExpansionState>());const fallbackScopeRef = useRef({ messageId, scope: 0 });if (fallbackScopeRef.current.messageId !== messageId) {@@ -386,6 +390,7 @@ const ContentParts = memo(function ContentParts({isSubmitting={effectiveIsSubmitting}renderPart={renderPart}/>+ {showPendingSteers && <PendingSteers conversationId={conversationId} />}</ApprovalProvider>);}@@ -421,6 +426,7 @@ const ContentParts = memo(function ContentParts({/>);})}+ {showPendingSteers && <PendingSteers conversationId={conversationId} />}</SearchContext.Provider></ApprovalProvider>);diff --git a/client/src/components/Chat/Messages/Content/Part.tsx b/client/src/components/Chat/Messages/Content/Part.tsxindex 9173d8c896..ee0942fe53 100644--- a/client/src/components/Chat/Messages/Content/Part.tsx+++ b/client/src/components/Chat/Messages/Content/Part.tsx@@ -21,6 +21,7 @@ import {FileAuthoringCall,BashCall,SubagentCall,+ SteerPart,} from './Parts';import { getAskUserQuestionPart } from '~/utils/approval';import AskUserQuestionCall from './AskUserQuestionCall';@@ -72,6 +73,17 @@ const Part = memo(function Part({);}+ if (part.type === ContentTypes.STEER) {+ return (+ <SteerPart+ steer={part[ContentTypes.STEER]}+ files={part.files}+ steerId={part.steerId}+ createdAt={part.createdAt}+ />+ );+ }+if (part.type === ContentTypes.ERROR) {return (<ErrorMessagediff --git a/client/src/components/Chat/Messages/Content/Parts/SteerPart.tsx b/client/src/components/Chat/Messages/Content/Parts/SteerPart.tsxnew file mode 100644index 0000000000..92937e792a--- /dev/null+++ b/client/src/components/Chat/Messages/Content/Parts/SteerPart.tsx@@ -0,0 +1,166 @@+import { memo, useMemo, useState, useCallback } from 'react';+import { X } from 'lucide-react';+import { useAtomValue } from 'jotai';+import { useRecoilValue } from 'recoil';+import type { TFile, TMessage } from 'librechat-data-provider';+import type { TMessageIcon } from '~/common';+import FilePreviewDialog from '~/components/Chat/Messages/Content/FilePreviewDialog';+import MessageTimestamp from '~/components/Chat/Messages/ui/MessageTimestamp';+import MarkdownLite from '~/components/Chat/Messages/Content/MarkdownLite';+import FileContainer from '~/components/Chat/Input/Files/FileContainer';+import MessageIcon from '~/components/Chat/Messages/MessageIcon';+import Image from '~/components/Chat/Messages/Content/Image';+import { useAuthContext } from '~/hooks/AuthContext';+import { fontSizeAtom } from '~/store/fontSize';+import { useShareContext } from '~/Providers';+import { useLocalize } from '~/hooks';+import { cn } from '~/utils';+import store from '~/store';++const USER_ICON: TMessageIcon = { isCreatedByUser: true };++/**+ * A mid-run steering message rendered as a standard user message inside the+ * assistant response — same icon, author header, and text presentation as any+ * user turn, placed where the words enter the run so the visible order equals+ * what the next turn replays (`ContentTypes.STEER` splits back into a+ * HumanMessage server-side). Renders identically as the optimistic entry+ * (`pending`, before the server applies it), as the persisted part live and+ * on reload, and in shared/search views.+ */+const SteerPart = memo(function SteerPart({+ steer,+ files,+ steerId,+ createdAt,+ pending = false,+ onCancel,+}: {+ steer: string;+ files?: TMessage['files'];+ /** Anchors the part for the message-nav rail (`#steer-<id>` rib target). */+ steerId?: string;+ createdAt?: number;+ pending?: boolean;+ /** Cancels a steer still waiting on its injection boundary (pending only). */+ onCancel?: () => void;+}) {+ const localize = useLocalize();+ const { user } = useAuthContext();+ const fontSize = useAtomValue(fontSizeAtom);+ const { isSharedConvo } = useShareContext();+ const usernameDisplay = useRecoilValue<boolean>(store.UsernameDisplay);+ const enableUserMsgMarkdown = useRecoilValue<boolean>(store.enableUserMsgMarkdown);++ /** The share surface must never label the SHARER's steers with the+ * viewer's identity; always the generic user label there. */+ const label = useMemo(() => {+ if (isSharedConvo === true || !usernameDisplay) {+ return localize('com_user_message');+ }+ return (user?.name ?? '') || user?.username || localize('com_user_message');+ }, [isSharedConvo, usernameDisplay, user?.name, user?.username, localize]);+ const timestamp = useMemo(+ () => (createdAt != null ? new Date(createdAt).toISOString() : null),+ [createdAt],+ );+ const imageFiles = useMemo(+ () => files?.filter((file) => file.type?.startsWith('image/')) ?? [],+ [files],+ );+ const otherFiles = useMemo(+ () => files?.filter((file) => !file.type?.startsWith('image/')) ?? [],+ [files],+ );+ const [selectedFile, setSelectedFile] = useState<Partial<TFile> | null>(null);+ const handlePreviewClose = useCallback((open: boolean) => {+ if (!open) {+ setSelectedFile(null);+ }+ }, []);++ if (typeof steer !== 'string' || steer.length === 0) {+ return null;+ }++ return (+ <div+ id={steerId ? `steer-${steerId}` : undefined}+ className={cn(+ /* Outdented past the response's icon column so the steer sits flush+ * with top-level message rows — it reads as a regular user message. */+ 'steer-render group relative my-4 -ml-9 flex w-[calc(100%+2.25rem)] gap-3',+ pending && 'opacity-80',+ )}+ data-testid="steer-part"+ data-steer-pending={pending || undefined}+ >+ <div className="relative flex flex-shrink-0 flex-col items-center">+ <div className="flex h-6 w-6 items-center justify-center overflow-hidden rounded-full">+ <MessageIcon iconData={USER_ICON} />+ </div>+ </div>+ <div className="user-turn relative flex w-11/12 flex-col">+ <h2 className={cn('select-none font-semibold', fontSize)}>+ {label}+ <MessageTimestamp value={timestamp} />+ {onCancel != null && (+ <button+ type="button"+ onClick={onCancel}+ aria-label={localize('com_ui_steer_cancel')}+ data-testid="steer-cancel"+ className="ml-2 rounded-full p-0.5 align-middle text-text-secondary opacity-0 transition-opacity duration-200 hover:bg-surface-tertiary hover:text-text-primary focus-visible:opacity-100 focus-visible:outline-none focus-visible:ring-2 focus-visible:ring-border-xheavy group-hover:opacity-100"+ >+ <X className="h-3.5 w-3.5" aria-hidden="true" />+ </button>+ )}+ </h2>+ <div className="flex flex-col items-start gap-2">+ {(imageFiles.length > 0 || otherFiles.length > 0) && (+ <div className="flex flex-wrap gap-2">+ {otherFiles.map((file) => (+ <FileContainer+ key={file.file_id}+ file={file as TFile}+ onClick={() => setSelectedFile(file)}+ />+ ))}+ {imageFiles.map((file) => (+ <Image+ key={file.file_id}+ imagePath={file.preview ?? file.filepath ?? ''}+ height={file.height ?? 1920}+ width={file.width ?? 1080}+ altText={file.filename ?? localize('com_ui_attached_image')}+ />+ ))}+ </div>+ )}+ <div+ className={cn(+ 'markdown prose message-content dark:prose-invert light w-full break-words',+ !enableUserMsgMarkdown && 'whitespace-pre-wrap',+ 'dark:text-gray-20',+ )}+ >+ {enableUserMsgMarkdown ? <MarkdownLite content={steer} /> : steer}+ </div>+ </div>+ </div>+ {otherFiles.length > 0 && (+ <FilePreviewDialog+ open={selectedFile !== null}+ onOpenChange={handlePreviewClose}+ fileName={selectedFile?.filename ?? ''}+ fileId={selectedFile?.file_id}+ filePath={selectedFile?.filepath}+ fileType={selectedFile?.type ?? undefined}+ fileSize={(selectedFile as TFile | null)?.bytes}+ />+ )}+ </div>+ );+});++export default SteerPart;diff --git a/client/src/components/Chat/Messages/Content/Parts/__tests__/SteerPart.test.tsx b/client/src/components/Chat/Messages/Content/Parts/__tests__/SteerPart.test.tsxnew file mode 100644index 0000000000..0e16340a12--- /dev/null+++ b/client/src/components/Chat/Messages/Content/Parts/__tests__/SteerPart.test.tsx@@ -0,0 +1,75 @@+import React from 'react';+import { RecoilRoot } from 'recoil';+import { render, screen } from '@testing-library/react';+import SteerPart from '../SteerPart';++let mockShareContext: { isSharedConvo?: boolean; shareId?: string } = {};++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => key,+}));++jest.mock('~/hooks/AuthContext', () => ({+ useAuthContext: () => ({ user: { name: 'Danny', username: 'danny' } }),+}));++jest.mock('~/Providers', () => ({+ useShareContext: () => mockShareContext,+}));++jest.mock('~/components/Chat/Messages/MessageIcon', () => ({+ __esModule: true,+ default: () => <div data-testid="user-icon" />,+}));++jest.mock('~/components/Chat/Messages/ui/MessageTimestamp', () => ({+ __esModule: true,+ default: () => null,+}));++jest.mock('~/components/Chat/Messages/Content/MarkdownLite', () => ({+ __esModule: true,+ default: ({ content }: { content: string }) => <span>{content}</span>,+}));++jest.mock('~/components/Chat/Input/Files/FileContainer', () => ({+ __esModule: true,+ default: () => null,+}));++jest.mock('~/components/Chat/Messages/Content/FilePreviewDialog', () => ({+ __esModule: true,+ default: () => null,+}));++jest.mock('~/components/Chat/Messages/Content/Image', () => ({+ __esModule: true,+ default: () => null,+}));++function renderPart() {+ return render(+ <RecoilRoot>+ <SteerPart steer="steered words" steerId="s1" createdAt={1} />+ </RecoilRoot>,+ );+}++describe('SteerPart author label', () => {+ beforeEach(() => {+ mockShareContext = {};+ });++ it('labels with the logged-in user name in the owner view (username display on)', () => {+ renderPart();+ expect(screen.getByText('Danny')).toBeInTheDocument();+ expect(screen.queryByText('com_user_message')).toBeNull();+ });++ it('labels with the generic user message in the share view, never the viewer identity', () => {+ mockShareContext = { isSharedConvo: true, shareId: 'share-1' };+ renderPart();+ expect(screen.queryByText('Danny')).toBeNull();+ expect(screen.getByText('com_user_message')).toBeInTheDocument();+ });+});diff --git a/client/src/components/Chat/Messages/Content/Parts/index.ts b/client/src/components/Chat/Messages/Content/Parts/index.tsindex 6d6bf470b7..9459572b10 100644--- a/client/src/components/Chat/Messages/Content/Parts/index.ts+++ b/client/src/components/Chat/Messages/Content/Parts/index.ts@@ -14,3 +14,4 @@ export { default as ReadFileCall } from './ReadFileCall';export { default as FileAuthoringCall } from './FileAuthoringCall';export { default as BashCall } from './BashCall';export { default as SubagentCall } from './SubagentCall';+export { default as SteerPart } from './SteerPart';diff --git a/client/src/components/Chat/Messages/Content/PendingSteers.tsx b/client/src/components/Chat/Messages/Content/PendingSteers.tsxnew file mode 100644index 0000000000..edf781993d--- /dev/null+++ b/client/src/components/Chat/Messages/Content/PendingSteers.tsx@@ -0,0 +1,96 @@+import { memo, useCallback } from 'react';+import { useRecoilValue, useRecoilCallback } from 'recoil';+import type { PendingSteer } from '~/store/families';+import { useCancelSteerMutation } from '~/data-provider';+import { SteerPart } from './Parts';+import store from '~/store';++/**+ * One not-yet-applied steer. Owns the cancel affordance so the mutation hook+ * (and its QueryClient requirement) only exists while a steer is actually+ * on screen — the parent slot renders on every streaming message.+ *+ * Cancel is optimistic: the entry leaves the thread immediately;+ * `removed: false` needs no handling (the steer already injected or the run+ * ended — the events own the outcome). Only a failed POST restores the+ * entry, since the server would still inject the supposedly-cancelled words.+ */+const PendingSteerItem = memo(function PendingSteerItem({+ steer,+ conversationId,+}: {+ steer: PendingSteer;+ conversationId: string;+}) {+ const cancelMutation = useCancelSteerMutation();++ const removeEntry = useRecoilCallback(+ ({ set }) =>+ (steerId: string) => {+ set(store.pendingSteersByConvoId(conversationId), (prev) =>+ prev.filter((item) => item.steerId !== steerId),+ );+ },+ [conversationId],+ );+ const restoreEntry = useRecoilCallback(+ ({ set }) =>+ (entry: PendingSteer) => {+ set(store.pendingSteersByConvoId(conversationId), (prev) =>+ prev.some((item) => item.steerId === entry.steerId) ? prev : [...prev, entry],+ );+ },+ [conversationId],+ );++ const cancelSteer = useCallback(() => {+ removeEntry(steer.steerId);+ cancelMutation.mutate(+ { conversationId, steerId: steer.steerId },+ { onError: () => restoreEntry(steer) },+ );+ }, [conversationId, steer, removeEntry, restoreEntry, cancelMutation]);++ return (+ <SteerPart+ steer={steer.text}+ files={steer.files}+ steerId={steer.steerId}+ createdAt={steer.createdAt}+ pending+ onCancel={steer.status === 'pending' ? cancelSteer : undefined}+ />+ );+});++/**+ * Steers the server hasn't applied yet, rendered in-thread at the end of the+ * streaming assistant message — the projected injection point, since the next+ * tool-batch boundary is always after everything streamed so far. A submitted+ * steer is part of the history the moment it's sent; `on_steer_applied`+ * then drops the optimistic entry as the persisted part lands at its+ * authoritative index. Failed steers leave the thread for the composer's+ * recovery row (retry / edit / queue).+ */+const PendingSteers = memo(function PendingSteers({+ conversationId,+}: {+ conversationId?: string | null;+}) {+ const convoKey = conversationId ?? '';+ const steers = useRecoilValue(store.pendingSteersByConvoId(convoKey));+ if (steers.length === 0 || !conversationId) {+ return null;+ }+ return (+ <>+ {steers.map((steer) =>+ steer.status === 'failed' ? null : (+ <PendingSteerItem key={steer.steerId} steer={steer} conversationId={conversationId} />+ ),+ )}+ </>+ );+});++export default PendingSteers;diff --git a/client/src/components/Chat/Messages/Content/__tests__/PendingSteers.test.tsx b/client/src/components/Chat/Messages/Content/__tests__/PendingSteers.test.tsxnew file mode 100644index 0000000000..4d45cafb0e--- /dev/null+++ b/client/src/components/Chat/Messages/Content/__tests__/PendingSteers.test.tsx@@ -0,0 +1,182 @@+import React from 'react';+import { RecoilRoot } from 'recoil';+import { render, screen, fireEvent, act } from '@testing-library/react';+import type { PendingSteer } from '~/store/families';+import PendingSteers from '../PendingSteers';+import store from '~/store';++const mockCancelMutate = jest.fn();++jest.mock('~/hooks', () => ({+ useLocalize: () => (key: string) => key,+}));++jest.mock('~/data-provider', () => ({+ useCancelSteerMutation: () => ({ mutate: mockCancelMutate }),+}));++jest.mock('~/hooks/AuthContext', () => ({+ useAuthContext: () => ({ user: { name: 'Danny', username: 'danny' } }),+}));++/** Stub the provider-backed leaves — these tests cover the slot's filtering+ * and the user-message presentation contract, not icon/markdown internals. */+jest.mock('~/components/Chat/Messages/MessageIcon', () => ({+ __esModule: true,+ default: () => <div data-testid="user-icon" />,+}));++jest.mock('~/components/Chat/Messages/ui/MessageTimestamp', () => ({+ __esModule: true,+ default: ({ value }: { value?: string | null }) => (+ <time data-testid="steer-timestamp">{value}</time>+ ),+}));++jest.mock('~/components/Chat/Messages/Content/MarkdownLite', () => ({+ __esModule: true,+ default: ({ content }: { content: string }) => <span>{content}</span>,+}));++jest.mock('~/components/Chat/Input/Files/FileContainer', () => ({+ __esModule: true,+ default: ({ file, onClick }: { file: { filename?: string }; onClick?: () => void }) => (+ <button type="button" data-testid="steer-file" onClick={onClick}>+ {file.filename}+ </button>+ ),+}));++jest.mock('~/components/Chat/Messages/Content/FilePreviewDialog', () => ({+ __esModule: true,+ default: ({ open, fileName }: { open: boolean; fileName: string }) =>+ open ? <div data-testid="steer-file-preview">{fileName}</div> : null,+}));++jest.mock('~/components/Chat/Messages/Content/Image', () => ({+ __esModule: true,++ default: ({ altText }: { altText: string }) => <img alt={altText} data-testid="steer-image" />,+}));++const CONVO_ID = 'convo-steers';++function renderSlot(steers: PendingSteer[], options?: { usernameDisplay?: boolean }) {+ return render(+ <RecoilRoot+ initializeState={({ set }) => {+ set(store.pendingSteersByConvoId(CONVO_ID), steers);+ if (options?.usernameDisplay != null) {+ set(store.UsernameDisplay, options.usernameDisplay);+ }+ }}+ >+ <PendingSteers conversationId={CONVO_ID} />+ </RecoilRoot>,+ );+}++describe('PendingSteers (in-thread optimistic steers)', () => {+ it('renders nothing when no steers are pending', () => {+ renderSlot([]);+ expect(screen.queryByTestId('steer-part')).toBeNull();+ });++ it('renders sending and pending steers as user-message parts, skipping failed ones', () => {+ renderSlot([+ { steerId: 's1', text: 'first correction', status: 'sending', createdAt: 1 },+ { steerId: 's2', text: 'second correction', status: 'pending', createdAt: 2 },+ { steerId: 's3', text: 'never sent', status: 'failed', createdAt: 3 },+ ]);+ const parts = screen.getAllByTestId('steer-part');+ expect(parts).toHaveLength(2);+ expect(screen.getByText('first correction')).toBeInTheDocument();+ expect(screen.getByText('second correction')).toBeInTheDocument();+ expect(screen.queryByText('never sent')).toBeNull();+ for (const part of parts) {+ expect(part).toHaveAttribute('data-steer-pending', 'true');+ }+ });++ it('presents the steer as a user message: icon and author name', () => {+ renderSlot([{ steerId: 's1', text: 'like you would say it', status: 'pending', createdAt: 1 }]);+ expect(screen.getByTestId('user-icon')).toBeInTheDocument();+ expect(screen.getByText('Danny')).toBeInTheDocument();+ });++ it('anchors each steer for the message-nav rail', () => {+ renderSlot([{ steerId: 's1', text: 'navigable words', status: 'pending', createdAt: 1 }]);+ const part = screen.getByTestId('steer-part');+ expect(part).toHaveAttribute('id', 'steer-s1');+ expect(part).toHaveClass('steer-render');+ });++ it('cancels a pending steer server-side and removes it from the thread', () => {+ renderSlot([+ { steerId: 's-ack', text: 'waiting on boundary', status: 'pending', createdAt: 1 },+ { steerId: 'local-1', text: 'still posting', status: 'sending', createdAt: 2 },+ ]);+ // Only the server-acknowledged steer is cancellable — a 'sending' entry+ // has no server id yet.+ const cancels = screen.getAllByTestId('steer-cancel');+ expect(cancels).toHaveLength(1);++ fireEvent.click(cancels[0]);+ expect(mockCancelMutate).toHaveBeenCalledWith(+ { conversationId: CONVO_ID, steerId: 's-ack' },+ expect.objectContaining({ onError: expect.any(Function) }),+ );+ expect(screen.queryByText('waiting on boundary')).toBeNull();+ expect(screen.getByText('still posting')).toBeInTheDocument();+ });++ it('restores the entry when the cancel POST fails', () => {+ renderSlot([{ steerId: 's-err', text: 'network flake', status: 'pending', createdAt: 1 }]);+ fireEvent.click(screen.getByTestId('steer-cancel'));+ expect(screen.queryByText('network flake')).toBeNull();++ const options = mockCancelMutate.mock.calls[0][1] as { onError: () => void };+ act(() => options.onError());+ expect(screen.getByText('network flake')).toBeInTheDocument();+ });++ it('falls back to the generic user label when username display is off', () => {+ renderSlot([{ steerId: 's1', text: 'anonymous words', status: 'pending', createdAt: 1 }], {+ usernameDisplay: false,+ });+ expect(screen.getByText('com_user_message')).toBeInTheDocument();+ });++ it('renders steer attachments', () => {+ renderSlot([+ {+ steerId: 's1',+ text: 'see attached',+ status: 'pending',+ createdAt: 1,+ files: [+ { file_id: 'f1', filename: 'notes.pdf', type: 'application/pdf' },+ { file_id: 'f2', filename: 'shot.png', type: 'image/png', filepath: '/images/shot.png' },+ ],+ },+ ]);+ expect(screen.getByTestId('steer-file')).toHaveTextContent('notes.pdf');+ expect(screen.getByTestId('steer-image')).toBeInTheDocument();+ });++ it('opens the file preview dialog when a non-image steer attachment is clicked', () => {+ renderSlot([+ {+ steerId: 's1',+ text: 'see attached',+ status: 'pending',+ createdAt: 1,+ files: [{ file_id: 'f1', filename: 'notes.pdf', type: 'application/pdf' }],+ },+ ]);+ expect(screen.queryByTestId('steer-file-preview')).toBeNull();++ fireEvent.click(screen.getByTestId('steer-file'));+ expect(screen.getByTestId('steer-file-preview')).toHaveTextContent('notes.pdf');+ });+});diff --git a/client/src/components/Chat/Messages/MessageNav.tsx b/client/src/components/Chat/Messages/MessageNav.tsxindex b25caf868e..e7a4cd2c86 100644--- a/client/src/components/Chat/Messages/MessageNav.tsx+++ b/client/src/components/Chat/Messages/MessageNav.tsx@@ -47,6 +47,26 @@ export function buildEntry(id: string, msg: TMessage): MessageEntry {}const USER_TURN_SELECTOR = '.user-turn';+const STEER_RENDER_CLASS = 'steer-render';+/** One query, document order: steer nodes interleave at their in-thread+ * position INSIDE the response that absorbed them. */+const ENTRY_NODE_SELECTOR = `.message-render, .${STEER_RENDER_CLASS}`;++/** Rail-relevant node: a message row or an in-thread steer part. The mutation+ * filter must match BOTH — a steer node swap (optimistic → persisted) or+ * removal (cancel) produces no `.message-render` mutation at all. */+function isEntryNode(node: HTMLElement): boolean {+ return (+ node.classList?.contains('message-render') === true ||+ node.classList?.contains(STEER_RENDER_CLASS) === true+ );+}++function containsEntryNode(node: HTMLElement): boolean {+ return (+ node.nodeType === 1 && (isEntryNode(node) || node.querySelector?.(ENTRY_NODE_SELECTOR) != null)+ );+}export function buildFallbackEntry(node: HTMLElement, id: string): MessageEntry {const isUser = node.querySelector(USER_TURN_SELECTOR) != null;@@ -58,8 +78,23 @@ export function buildFallbackEntry(node: HTMLElement, id: string): MessageEntry};}+/** A mid-run steer is a user message, so its rib reads as one; the preview+ * comes from the part's text body, skipping the author header. */+export function buildSteerEntry(node: HTMLElement, id: string): MessageEntry {+ const raw = (+ node.querySelector('.message-content')?.textContent ??+ node.textContent ??+ ''+ ).trim();+ return {+ id,+ isUser: true,+ preview: raw.slice(0, 80) + (raw.length > 80 ? '...' : ''),+ };+}+function getMessageEntries(root: ParentNode, messagesById: Map<string, TMessage>): MessageEntry[] {- const nodes = root.querySelectorAll<HTMLElement>('.message-render');+ const nodes = root.querySelectorAll<HTMLElement>(ENTRY_NODE_SELECTOR);const entries: MessageEntry[] = [];const seen = new Set<string>();for (let i = 0; i < nodes.length; i++) {@@ -69,6 +104,10 @@ function getMessageEntries(root: ParentNode, messagesById: Map<string, TMessage>continue;}seen.add(id);+ if (node.classList.contains(STEER_RENDER_CLASS)) {+ entries.push(buildSteerEntry(node, id));+ continue;+ }const msg = messagesById.get(id);entries.push(msg ? buildEntry(id, msg) : buildFallbackEntry(node, id));}@@ -267,6 +306,57 @@ function MessageNav({ scrollableRef }: { scrollableRef: React.RefObject<HTMLDivEmessagesByIdRef.current = messagesById;}, [messagesById]);+ const resolveEntryEl = useCallback(+ (id: string): HTMLElement | null => {+ if (id === MESSAGES_END_ID) {+ return scrollableRef.current?.querySelector<HTMLElement>('#' + MESSAGES_END_ID) ?? null;+ }+ return document.getElementById(id);+ },+ [scrollableRef],+ );++ /**+ * Re-point the observer at replaced DOM nodes. A steer part swaps its node+ * under the SAME id (optimistic entry → persisted part), which produces no+ * IntersectionObserver exit and — because the entry list dedupes on+ * (id, preview) — no entries change either, so the observer would keep+ * watching a detached node and the rib would stay lit forever. Runs from+ * the mutation-driven refresh regardless of entries identity; visibility is+ * dropped until the fresh node reports (the observer fires its initial+ * intersection immediately on observe, so a truly visible part re-lights+ * within a frame).+ */+ const reconcileObservedElements = useCallback(() => {+ const observer = observerRef.current;+ if (!observer) {+ return;+ }+ const observed = observedRef.current;+ const visibleSet = visibleSetRef.current;+ let visibilityChanged = false;+ for (const [id, el] of [...observed]) {+ const current = resolveEntryEl(id);+ if (current === el) {+ continue;+ }+ observer.unobserve(el);+ if (current) {+ observer.observe(current);+ observed.set(id, current);+ } else {+ observed.delete(id);+ }+ if (visibleSet.delete(id)) {+ visibilityChanged = true;+ }+ }+ if (visibilityChanged) {+ setCurrentId(getCurrentVisibleId());+ setVisibleIds(new Set(visibleSet));+ }+ }, [resolveEntryEl, getCurrentVisibleId]);+const refreshEntries = useCallback(() => {if (refreshTimerRef.current) {clearTimeout(refreshTimerRef.current);@@ -283,23 +373,14 @@ function MessageNav({ scrollableRef }: { scrollableRef: React.RefObject<HTMLDivE}return next;});+ reconcileObservedElements();}, 200);- }, [scrollableRef]);+ }, [scrollableRef, reconcileObservedElements]);useEffect(() => {refreshEntries();}, [messagesById, refreshEntries]);- const resolveEntryEl = useCallback(- (id: string): HTMLElement | null => {- if (id === MESSAGES_END_ID) {- return scrollableRef.current?.querySelector<HTMLElement>('#' + MESSAGES_END_ID) ?? null;- }- return document.getElementById(id);- },- [scrollableRef],- );-const scrollToStart = useCallback((id: string) => {const el = resolveEntryEl(id);@@ -730,7 +811,7 @@ function MessageNav({ scrollableRef }: { scrollableRef: React.RefObject<HTMLDivEconst m = mutations[i];if (m.type === 'attributes') {const target = m.target as HTMLElement;- if (target.nodeType === 1 && target.classList?.contains('message-render')) {+ if (target.nodeType === 1 && isEntryNode(target)) {refreshEntries();return;}@@ -738,21 +819,13 @@ function MessageNav({ scrollableRef }: { scrollableRef: React.RefObject<HTMLDivE}if (m.addedNodes.length || m.removedNodes.length) {for (let j = 0; j < m.addedNodes.length; j++) {- const n = m.addedNodes[j] as HTMLElement;- if (- n.nodeType === 1 &&- (n.classList?.contains('message-render') || n.querySelector?.('.message-render'))- ) {+ if (containsEntryNode(m.addedNodes[j] as HTMLElement)) {refreshEntries();return;}}for (let j = 0; j < m.removedNodes.length; j++) {- const n = m.removedNodes[j] as HTMLElement;- if (- n.nodeType === 1 &&- (n.classList?.contains('message-render') || n.querySelector?.('.message-render'))- ) {+ if (containsEntryNode(m.removedNodes[j] as HTMLElement)) {refreshEntries();return;}diff --git a/client/src/components/Chat/Messages/__tests__/MessageNav.spec.tsx b/client/src/components/Chat/Messages/__tests__/MessageNav.spec.tsxindex 8211b7c793..921e5776c8 100644--- a/client/src/components/Chat/Messages/__tests__/MessageNav.spec.tsx+++ b/client/src/components/Chat/Messages/__tests__/MessageNav.spec.tsx@@ -126,6 +126,7 @@ if (typeof (global as { PointerEvent?: unknown }).PointerEvent === 'undefined')import type { TMessage } from 'librechat-data-provider';import MessageNav, {buildEntry,+ buildSteerEntry,buildFallbackEntry,magnifyFalloff,ribDimsFor,@@ -404,6 +405,122 @@ describe('MessageNav', () => {});});+ describe('steer ribs', () => {+ function appendSteerNode(+ parent: Element,+ steerId: string,+ text: string,+ offsetTop: number,+ ): HTMLDivElement {+ const steer = document.createElement('div');+ steer.id = `steer-${steerId}`;+ steer.className = 'steer-render group relative';+ const header = document.createElement('h2');+ header.textContent = 'Danny';+ const body = document.createElement('div');+ body.className = 'message-content';+ body.textContent = text;+ steer.appendChild(header);+ steer.appendChild(body);+ Object.defineProperty(steer, 'offsetTop', { value: offsetTop, configurable: true });+ Object.defineProperty(steer, 'offsetHeight', { value: 40, configurable: true });+ parent.appendChild(steer);+ return steer;+ }++ it('buildSteerEntry reads the text body, skipping the author header', () => {+ const node = document.createElement('div');+ appendSteerNode(node, 's', 'actually use bun instead', 0);+ const entry = buildSteerEntry(node.firstElementChild as HTMLElement, 'steer-s');+ expect(entry).toEqual({+ id: 'steer-s',+ isUser: true,+ preview: 'actually use bun instead',+ });+ });++ it('buildSteerEntry truncates long steers and falls back to full node text', () => {+ const node = document.createElement('div');+ node.textContent = 'x'.repeat(100);+ const entry = buildSteerEntry(node, 'steer-long');+ expect(entry.preview.endsWith('...')).toBe(true);+ expect(entry.preview).toHaveLength(83);+ });++ it('interleaves a steer rib inside its response, labeled as a user message', () => {+ const messages = [+ buildMessage({ messageId: 'u1', text: 'first ask', isCreatedByUser: true }),+ buildMessage({ messageId: 'a1', text: 'long tool run' }),+ buildMessage({ messageId: 'u2', text: 'follow-up', isCreatedByUser: true }),+ buildMessage({ messageId: 'a2', text: 'second reply' }),+ ];+ mockUseGetMessagesByConvoId.mockReturnValue({ data: messages });+ const { scrollable } = buildDom(messages);+ const response = scrollable.querySelector('#a1') as HTMLElement;+ appendSteerNode(response, 's1', 'steer mid-run words', 350);++ const scrollableRef = { current: scrollable } as RefObject<HTMLDivElement>;+ const { container } = render(<MessageNav scrollableRef={scrollableRef} />);+ act(() => {+ jest.advanceTimersByTime(250);+ });++ const ids = Array.from(container.querySelectorAll('[data-msg-id]')).map((el) =>+ el.getAttribute('data-msg-id'),+ );+ expect(ids).toEqual(['u1', 'a1', 'steer-s1', 'u2', 'a2']);++ const steerRib = container.querySelector('[data-msg-id="steer-s1"]');+ expect(steerRib?.getAttribute('aria-label')).toMatch(/^com_ui_message_nav_go_to_user\|/);+ expect(steerRib?.getAttribute('aria-label')).toContain('steer mid-run words');+ expect(steerRib?.getAttribute('aria-label')).not.toContain('Danny');+ });++ it('un-lights a steer rib when its DOM node is replaced (pending → applied swap)', async () => {+ const messages = [+ buildMessage({ messageId: 'u1', text: 'first ask', isCreatedByUser: true }),+ buildMessage({ messageId: 'a1', text: 'long tool run' }),+ buildMessage({ messageId: 'u2', text: 'follow-up', isCreatedByUser: true }),+ ];+ mockUseGetMessagesByConvoId.mockReturnValue({ data: messages });+ const { scrollable } = buildDom(messages);+ const response = scrollable.querySelector('#a1') as HTMLElement;+ const pendingNode = appendSteerNode(response, 's1', 'swap me', 350);++ const scrollableRef = { current: scrollable } as RefObject<HTMLDivElement>;+ const { container } = render(<MessageNav scrollableRef={scrollableRef} />);+ act(() => {+ jest.advanceTimersByTime(250);+ });++ const io = MockIntersectionObserver.last();+ act(() => {+ io!.trigger([{ target: pendingNode, isIntersecting: true }]);+ jest.advanceTimersByTime(32);+ });+ const rib = container.querySelector('[data-msg-id="steer-s1"]') as HTMLElement;+ expect(rib.className).toContain('opacity-100');++ // The applied part replaces the optimistic node under the SAME id —+ // same entry list (id + preview unchanged), no observer exit event.+ act(() => {+ pendingNode.remove();+ appendSteerNode(response, 's1', 'swap me', 350);+ });+ // Let the MutationObserver microtask deliver (it schedules the+ // debounced refresh), then advance the debounce.+ await act(async () => {});+ act(() => {+ jest.advanceTimersByTime(250);+ });++ // Without node-level reconciliation the dead node keeps the rib lit+ // forever; after it, visibility drops until the fresh node reports.+ const ribAfter = container.querySelector('[data-msg-id="steer-s1"]') as HTMLElement;+ expect(ribAfter.className).toContain('opacity-40');+ });+ });+describe('accessibility', () => {it('labels the nav and chevron buttons via useLocalize', () => {const messages = [diff --git a/client/src/components/Nav/Settings/registry.tsx b/client/src/components/Nav/Settings/registry.tsxindex a2682963ab..195199b97e 100644--- a/client/src/components/Nav/Settings/registry.tsx+++ b/client/src/components/Nav/Settings/registry.tsx@@ -24,6 +24,7 @@ import BackupCodesItem from '../SettingsTabs/Account/BackupCodesItem';import { EngineSTTSetting, EngineTTSSetting } from './SpeechControls';import FontSizeSelector from '../SettingsTabs/Chat/FontSizeSelector';import AdvancedPrompts from '../SettingsTabs/Chat/AdvancedPrompts';+import DuringRunAction from '../SettingsTabs/Chat/DuringRunAction';import DeleteAccount from '../SettingsTabs/Account/DeleteAccount';import { ForkSettings } from '../SettingsTabs/Chat/ForkSettings';import ChatDirection from '../SettingsTabs/Chat/ChatDirection';@@ -138,6 +139,14 @@ export const registry: SettingEntry[] = [hoverCardText: 'com_nav_info_enter_to_send',}),},+ {+ id: 'duringRunDefaultAction',+ tab: CHAT,+ section: 'sending',+ labelKey: 'com_nav_during_run_action',+ keywords: ['steer', 'queue', 'interrupt', 'generating'],+ Component: DuringRunAction,+ },{id: 'saveDrafts',tab: CHAT,diff --git a/client/src/components/Nav/SettingsTabs/Chat/DuringRunAction.tsx b/client/src/components/Nav/SettingsTabs/Chat/DuringRunAction.tsxnew file mode 100644index 0000000000..60af50a842--- /dev/null+++ b/client/src/components/Nav/SettingsTabs/Chat/DuringRunAction.tsx@@ -0,0 +1,43 @@+import React from 'react';+import { useRecoilState } from 'recoil';+import { Button } from '@librechat/client';+import { useLocalize } from '~/hooks';+import store from '~/store';++/**+ * Toggles what Enter does while a run is generating: steer (inject the+ * message into the live run at the next tool boundary) or queue (send it as a+ * normal follow-up once the run finishes). The composer's during-run menu can+ * still override per send.+ */+const DuringRunAction = () => {+ const [action, setAction] = useRecoilState(store.duringRunDefaultAction);+ const localize = useLocalize();++ const toggle = () => {+ setAction((prev) => (prev === 'steer' ? 'queue' : 'steer'));+ };++ const label =+ action === 'steer'+ ? localize('com_nav_during_run_action_steer')+ : localize('com_nav_during_run_action_queue');++ return (+ <div className="flex items-center justify-between">+ <div className="flex items-center space-x-2">+ <span id="during-run-action-label">{localize('com_nav_during_run_action')}</span>+ </div>+ <Button+ variant="outline"+ aria-labelledby="during-run-action-label"+ onClick={toggle}+ data-testid="duringRunAction"+ >+ {label}+ </Button>+ </div>+ );+};++export default DuringRunAction;diff --git a/client/src/data-provider/Files/mutations.ts b/client/src/data-provider/Files/mutations.tsindex 715cd6457d..d98da899f9 100644--- a/client/src/data-provider/Files/mutations.ts+++ b/client/src/data-provider/Files/mutations.ts@@ -8,8 +8,8 @@ import {defaultOrderQuery,isAssistantsEndpoint,} from 'librechat-data-provider';-import type * as t from 'librechat-data-provider';import type { UseMutationResult } from '@tanstack/react-query';+import type * as t from 'librechat-data-provider';import { useLocalize } from '~/hooks';export const useUploadFileMutation = (@@ -138,6 +138,22 @@ export const useUploadFileMutation = (});};+/**+ * Owner-scoped usage touch for uploads entering the client-side queue, so the+ * upload-window TTL cannot reap them while the message waits out a long run.+ * Fire-and-forget: failures are tolerated (send-time marking is the backstop).+ */+export const useMarkFilesUsageMutation = (): UseMutationResult<+ t.TFilesUsageResponse, // response data+ unknown, // error+ t.TFilesUsageBody, // request+ unknown // context+> => {+ return useMutation([MutationKeys.fileUsage], {+ mutationFn: (body: t.TFilesUsageBody) => dataService.markFilesUsage(body),+ });+};+export const useDeleteFilesMutation = (_options?: t.DeleteMutationOptions,): UseMutationResult<diff --git a/client/src/data-provider/SSE/mutations.ts b/client/src/data-provider/SSE/mutations.tsindex 2d95bb377b..8b8aeb8e65 100644--- a/client/src/data-provider/SSE/mutations.ts+++ b/client/src/data-provider/SSE/mutations.ts@@ -1,6 +1,6 @@import { useMutation } from '@tanstack/react-query';import { apiBaseUrl, request, EModelEndpoint } from 'librechat-data-provider';-import type { Agents, TEphemeralAgent } from 'librechat-data-provider';+import type { Agents, TMessage, TEphemeralAgent, TPendingSteer } from 'librechat-data-provider';export interface AbortStreamParams {/** The stream ID to abort (if known) */@@ -13,6 +13,8 @@ export interface AbortStreamResponse {success: boolean;aborted?: string;error?: string;+ /** Steers that never reached an injection boundary; restored as queued chips. */+ pendingSteers?: TPendingSteer[];}/**@@ -140,3 +142,68 @@ export function useSubmitAskAnswerMutation() {mutationFn: submitAskAnswer,});}++export interface SteerMessageParams {+ conversationId: string;+ text: string;+ /** Attachment refs steered with the message (already uploaded). */+ files?: TMessage['files'];+}++/** Successful steer ACK: the server queued the message for mid-run injection. */+export interface SteerMessageResponse {+ status: 'queued';+ steerId: string;+ position: number;+ conversationId: string;+}++/**+ * Queue a mid-run steering message against the conversation's active run.+ * The server injects it at the next tool-batch boundary and streams an+ * `on_steer_applied` event over the existing SSE; this only fires the POST.+ * Rejections carry a `code` the caller degrades on (NO_ACTIVE_RUN → normal+ * send, RUN_PAUSED / STEER_UNSUPPORTED → client-side queue).+ */+export const steerMessage = async (params: SteerMessageParams): Promise<SteerMessageResponse> => {+ return request.post(+ `${apiBaseUrl()}/api/agents/chat/steer`,+ params,+ ) as Promise<SteerMessageResponse>;+};++/** React Query mutation hook for steering; the injection arrives on the SSE. */+export function useSteerMessageMutation() {+ return useMutation({+ mutationFn: steerMessage,+ });+}++export interface CancelSteerParams {+ conversationId: string;+ steerId: string;+}++export interface CancelSteerResponse {+ removed?: boolean;+}++/**+ * Cancels a still-queued steer before injection. `removed: false` means the+ * cancel lost its race (already injected, or the run ended) — not an error;+ * the client defers to the events it will receive.+ */+export const cancelSteerMessage = async (+ params: CancelSteerParams,+): Promise<CancelSteerResponse> => {+ return request.post(+ `${apiBaseUrl()}/api/agents/chat/steer/cancel`,+ params,+ ) as Promise<CancelSteerResponse>;+};++export function useCancelSteerMutation() {+ return useMutation({+ mutationFn: cancelSteerMessage,+ });+}diff --git a/client/src/data-provider/SSE/queries.ts b/client/src/data-provider/SSE/queries.tsindex 3f9830712f..3c20391547 100644--- a/client/src/data-provider/SSE/queries.ts+++ b/client/src/data-provider/SSE/queries.ts@@ -1,7 +1,7 @@import { useEffect, useMemo, useState } from 'react';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 type { Agents, TConversation, TPendingSteer } from 'librechat-data-provider';import { isNotFoundError, updateConvoInAllQueries } from '~/utils';import { useGetStartupConfig } from '../Endpoints';@@ -15,6 +15,9 @@ export interface StreamStatusResponse {/** Live pending approval when `status === 'requires_action'`; mirrors* `resumeState.pendingAction`, surfaced top-level for the resume-on-load path. */pendingAction?: Agents.PendingAction;+ /** Acknowledged steers a terminal drain parked because no subscriber was+ * live for the final/abort event — claim-on-read; restore as queued chips. */+ unrecoveredSteers?: TPendingSteer[];}export const streamStatusQueryKey = (conversationId: string) => ['streamStatus', conversationId];diff --git a/client/src/hooks/Chat/__tests__/abort.spec.tsx b/client/src/hooks/Chat/__tests__/abort.spec.tsxnew file mode 100644index 0000000000..45d481e493--- /dev/null+++ b/client/src/hooks/Chat/__tests__/abort.spec.tsx@@ -0,0 +1,276 @@+import React from 'react';+import { Constants } from 'librechat-data-provider';+import { act, renderHook, waitFor } from '@testing-library/react';+import { RecoilRoot, useSetRecoilState, useRecoilValue } from 'recoil';+import { QueryClient, QueryClientProvider } from '@tanstack/react-query';+import type { TSubmission, TConversation } from 'librechat-data-provider';+import type { RunEnd } from '~/store/families';+import useChatHelpers from '../useChatHelpers';+import { useAbortCleanup } from '../abort';+import store from '~/store';++const mockAbortMutateAsync = jest.fn();+const mockConvertSteersToQueued = jest.fn();++jest.mock('~/data-provider', () => ({+ useAbortStreamMutation: () => ({ mutateAsync: mockAbortMutateAsync }),+}));++jest.mock('~/hooks/Messages/useLatestMessage', () => ({+ useLatestMessage: () => null,+ useLatestMessageId: () => null,+}));++jest.mock('~/hooks/Chat/useChatFunctions', () => ({+ __esModule: true,+ default: () => ({ ask: jest.fn(), regenerate: jest.fn() }),+}));++jest.mock('~/hooks/useNewConvo', () => ({+ __esModule: true,+ default: () => ({ newConversation: jest.fn() }),+}));++jest.mock('~/hooks/Chat/useSteerConvert', () => ({+ __esModule: true,+ default: () => mockConvertSteersToQueued,+}));++const INDEX = 0;+const OTHER_INDEX = 1;++const submission = (id: string) =>+ ({ userMessage: { messageId: id, text: id } }) as unknown as TSubmission;++function setup() {+ const handles: {+ captureSubmission?: ReturnType<typeof useAbortCleanup>['captureSubmission'];+ clearSubmissionsUnlessReplaced?: ReturnType<+ typeof useAbortCleanup+ >['clearSubmissionsUnlessReplaced'];+ setSubmission?: (value: TSubmission | null) => void;+ setOtherSubmission?: (value: TSubmission | null) => void;+ } = {};+ const current: { submission: TSubmission | null; otherSubmission: TSubmission | null } = {+ submission: null,+ otherSubmission: null,+ };++ function Harness() {+ const cleanup = useAbortCleanup(INDEX);+ handles.captureSubmission = cleanup.captureSubmission;+ handles.clearSubmissionsUnlessReplaced = cleanup.clearSubmissionsUnlessReplaced;+ handles.setSubmission = useSetRecoilState(store.submissionByIndex(INDEX));+ handles.setOtherSubmission = useSetRecoilState(store.submissionByIndex(OTHER_INDEX));+ current.submission = useRecoilValue(store.submissionByIndex(INDEX));+ current.otherSubmission = useRecoilValue(store.submissionByIndex(OTHER_INDEX));+ return null;+ }++ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot+ initializeState={({ set }) => {+ // clearAllSubmissions iterates the registered conversation keys.+ set(store.conversationKeysAtom, [INDEX, OTHER_INDEX]);+ }}+ >+ <Harness />+ {children}+ </RecoilRoot>+ );+ renderHook(() => null, { wrapper });+ return { handles, current };+}++describe('useAbortCleanup', () => {+ it('clears all submissions when the captured submission is still current', async () => {+ const { handles, current } = setup();+ const aborted = submission('aborted-run');++ act(() => {+ handles.setSubmission!(aborted);+ handles.setOtherSubmission!(submission('added-pane'));+ });++ const captured = handles.captureSubmission!();+ expect(captured).toBe(aborted);++ act(() => {+ handles.clearSubmissionsUnlessReplaced!(captured);+ });++ await waitFor(() => expect(current.submission).toBeNull());+ expect(current.otherSubmission).toBeNull();+ });++ it('keeps a submission that replaced the aborted one while the abort was in flight', async () => {+ const { handles, current } = setup();+ const aborted = submission('aborted-run');+ const nextRun = submission('interrupt-follow-up');++ act(() => {+ handles.setSubmission!(aborted);+ });+ const captured = handles.captureSubmission!();++ // The final SSE fired the interrupt drain and started the next run+ // before the abort HTTP response resolved.+ act(() => {+ handles.setSubmission!(nextRun);+ });+ act(() => {+ handles.clearSubmissionsUnlessReplaced!(captured);+ });++ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(current.submission).toBe(nextRun);+ });++ it('keeps a new submission even when the abort started with none captured', async () => {+ const { handles, current } = setup();+ const nextRun = submission('drained-after-abort');++ const captured = handles.captureSubmission!();+ expect(captured).toBeNull();++ act(() => {+ handles.setSubmission!(nextRun);+ });+ act(() => {+ handles.clearSubmissionsUnlessReplaced!(captured);+ });++ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(current.submission).toBe(nextRun);+ });++ it('still clears when the submission was already nulled elsewhere', async () => {+ const { handles, current } = setup();+ const aborted = submission('aborted-run');++ act(() => {+ handles.setSubmission!(aborted);+ handles.setOtherSubmission!(submission('added-pane'));+ });+ const captured = handles.captureSubmission!();++ act(() => {+ handles.setSubmission!(null);+ });+ act(() => {+ handles.clearSubmissionsUnlessReplaced!(captured);+ });++ await waitFor(() => expect(current.otherSubmission).toBeNull());+ expect(current.submission).toBeNull();+ });+});++describe('useChatHelpers stopGenerating (abort steer targeting)', () => {+ const observed: { runEnd: RunEnd | null } = { runEnd: null };++ function setupStop(conversationId: string) {+ function RunEndProbe() {+ observed.runEnd = useRecoilValue(store.runEndByIndex(INDEX));+ return null;+ }+ const queryClient = new QueryClient();+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <QueryClientProvider client={queryClient}>+ <RecoilRoot+ initializeState={({ set }) => {+ set(store.conversationByIndex(INDEX), {+ conversationId,+ endpoint: 'agents',+ } as TConversation);+ // Arm interrupt & send so the abort response writes the drain signal.+ set(store.drainAfterAbortByIndex(INDEX), true);+ }}+ >+ <RunEndProbe />+ {children}+ </RecoilRoot>+ </QueryClientProvider>+ );+ return renderHook(() => useChatHelpers(INDEX), { wrapper });+ }++ beforeEach(() => {+ observed.runEnd = null;+ mockAbortMutateAsync.mockReset();+ mockConvertSteersToQueued.mockReset();+ jest.spyOn(console, 'log').mockImplementation(() => undefined);+ });++ afterEach(() => {+ jest.restoreAllMocks();+ });++ it('keeps chips and the drain signal on the new composer while claiming under the resolved id', async () => {+ const pendingSteers = [{ steerId: 's1', text: 'leftover words' }];+ mockAbortMutateAsync.mockResolvedValue({+ success: true,+ aborted: 'convo-resolved',+ pendingSteers,+ });++ const { result } = setupStop(String(Constants.NEW_CONVO));+ await act(async () => {+ await result.current.stopGenerating();+ });++ expect(mockAbortMutateAsync).toHaveBeenCalledWith({+ conversationId: String(Constants.NEW_CONVO),+ });+ // The user is still on /c/new (nothing navigated), so the chips and the+ // drain signal key under NEW_CONVO — but the parked server copy lives+ // under the RESOLVED job id and must be claimed there.+ expect(mockConvertSteersToQueued).toHaveBeenCalledWith(+ String(Constants.NEW_CONVO),+ pendingSteers,+ { claimParked: true, claimConversationId: 'convo-resolved' },+ );+ expect(observed.runEnd).toMatchObject({+ conversationId: String(Constants.NEW_CONVO),+ outcome: 'aborted',+ });+ });++ it('prefers the response resolved id over the client-held id for an existing conversation', async () => {+ const pendingSteers = [{ steerId: 's2', text: 'other leftover' }];+ mockAbortMutateAsync.mockResolvedValue({+ success: true,+ aborted: 'convo-resolved',+ pendingSteers,+ });++ const { result } = setupStop('convo-held');+ await act(async () => {+ await result.current.stopGenerating();+ });++ expect(mockConvertSteersToQueued).toHaveBeenCalledWith('convo-resolved', pendingSteers, {+ claimParked: true,+ claimConversationId: 'convo-resolved',+ });+ expect(observed.runEnd).toMatchObject({+ conversationId: 'convo-resolved',+ outcome: 'aborted',+ });+ });++ it('falls back to the client-held id when the response carries no resolved id', async () => {+ mockAbortMutateAsync.mockResolvedValue({ success: true, pendingSteers: [] });++ const { result } = setupStop('convo-held');+ await act(async () => {+ await result.current.stopGenerating();+ });++ expect(mockConvertSteersToQueued).toHaveBeenCalledWith('convo-held', [], {+ claimParked: true,+ claimConversationId: 'convo-held',+ });+ expect(observed.runEnd).toMatchObject({ conversationId: 'convo-held', outcome: 'aborted' });+ });+});diff --git a/client/src/hooks/Chat/__tests__/useQueueDrain.spec.tsx b/client/src/hooks/Chat/__tests__/useQueueDrain.spec.tsxnew file mode 100644index 0000000000..fce29c79a2--- /dev/null+++ b/client/src/hooks/Chat/__tests__/useQueueDrain.spec.tsx@@ -0,0 +1,318 @@+import React from 'react';+import { Constants } from 'librechat-data-provider';+import { act, renderHook, waitFor } from '@testing-library/react';+import { RecoilRoot, useRecoilValue, useSetRecoilState, type MutableSnapshot } from 'recoil';+import type { RunEnd, QueuedMessage } from '~/store/families';+import useQueueDrain from '../useQueueDrain';+import store from '~/store';++const INDEX = 0;+const CONVO_ID = 'convo-drain';++function setup(+ initialize?: (snapshot: MutableSnapshot) => void,+ activeConversationId: string | undefined = CONVO_ID,+) {+ const ask = jest.fn();+ const setters: {+ setRunEnd?: (value: RunEnd | null) => void;+ setIsSubmitting?: (value: boolean) => void;+ setQueue?: (value: { id: string; text: string; createdAt: number }[]) => void;+ setNewConvoQueue?: (value: { id: string; text: string; createdAt: number }[]) => void;+ setInterruptFlag?: (value: boolean) => void;+ queueRef?: { current: { id: string; text: string; createdAt: number }[] };+ } = {};++ function Harness() {+ setters.setRunEnd = useSetRecoilState(store.runEndByIndex(INDEX));+ setters.setIsSubmitting = useSetRecoilState(store.isSubmittingFamily(INDEX));+ setters.setQueue = useSetRecoilState(store.queuedMessagesByConvoId(CONVO_ID));+ setters.setNewConvoQueue = useSetRecoilState(+ store.queuedMessagesByConvoId(Constants.NEW_CONVO),+ );+ setters.setInterruptFlag = useSetRecoilState(store.drainAfterAbortByIndex(INDEX));+ useQueueDrain(INDEX, activeConversationId, ask);+ return null;+ }++ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot initializeState={initialize}>+ <Harness />+ {children}+ </RecoilRoot>+ );+ renderHook(() => null, { wrapper });+ return { ask, setters };+}++const emptyOverrides = { overrideFiles: [], overrideQuotes: [], overrideManualSkills: [] };++const queuedMessage = (id: string, text: string) => ({ id, text, createdAt: Date.now() });++const runEnd = (overrides: Partial<RunEnd> = {}): RunEnd => ({+ conversationId: CONVO_ID,+ outcome: 'completed',+ endedAt: Date.now(),+ ...overrides,+});++describe('useQueueDrain', () => {+ it('drains exactly one queued message on clean completion', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [+ queuedMessage('q1', 'first follow-up'),+ queuedMessage('q2', 'second follow-up'),+ ]);+ });++ act(() => {+ setters.setRunEnd!(runEnd());+ });++ await waitFor(() => expect(ask).toHaveBeenCalledTimes(1));+ expect(ask).toHaveBeenCalledWith({ text: 'first follow-up' }, emptyOverrides);+ });++ it('parks a mismatched signal instead of draining into the wrong conversation', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [queuedMessage('q1', 'stay put')]);+ }, 'some-other-convo');++ act(() => {+ setters.setRunEnd!(runEnd());+ });++ await new Promise((resolve) => setTimeout(resolve, 25));+ // Not sent through the mounted (wrong-conversation) sender; the signal is+ // parked under its own conversation, freeing the shared index slot.+ expect(ask).not.toHaveBeenCalled();+ });++ it('drains a parked signal when the user returns to that conversation', async () => {+ const { ask } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [queuedMessage('q1', 'welcome back')]);+ set(store.pendingRunEndByConvoId(CONVO_ID), runEnd());+ });++ await waitFor(() => expect(ask).toHaveBeenCalledTimes(1));+ expect(ask).toHaveBeenCalledWith({ text: 'welcome back' }, emptyOverrides);+ });++ it('passes a queued message`s attachments through as overrideFiles', async () => {+ const files = [{ file_id: 'f1', filepath: '/uploads/f1.png', type: 'image/png' }];+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [+ { ...queuedMessage('q1', 'with media'), files },+ ]);+ });++ act(() => {+ setters.setRunEnd!(runEnd());+ });++ await waitFor(() => expect(ask).toHaveBeenCalledTimes(1));+ expect(ask).toHaveBeenCalledWith(+ { text: 'with media' },+ { overrideFiles: files, overrideQuotes: [], overrideManualSkills: [] },+ );+ });++ it('passes carried quotes + manual skills through as overrides', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [+ {+ ...queuedMessage('q1', 'with context'),+ quotes: ['quoted excerpt'],+ manualSkills: ['skill-1'],+ },+ ]);+ });++ act(() => {+ setters.setRunEnd!(runEnd());+ });++ await waitFor(() => expect(ask).toHaveBeenCalledTimes(1));+ expect(ask).toHaveBeenCalledWith(+ { text: 'with context' },+ { overrideFiles: [], overrideQuotes: ['quoted excerpt'], overrideManualSkills: ['skill-1'] },+ );+ });++ it('does not drain on user abort or error outcomes', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [queuedMessage('q1', 'kept')]);+ });++ act(() => {+ setters.setRunEnd!(runEnd({ outcome: 'aborted' }));+ });+ act(() => {+ setters.setRunEnd!(runEnd({ outcome: 'error' }));+ });++ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(ask).not.toHaveBeenCalled();+ });++ it('drains on abort when the interrupt & send flag is armed, then disarms', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [queuedMessage('q1', 'interrupt text')]);+ set(store.drainAfterAbortByIndex(INDEX), true);+ });++ act(() => {+ setters.setRunEnd!(runEnd({ outcome: 'aborted' }));+ });+ await waitFor(() =>+ expect(ask).toHaveBeenCalledWith({ text: 'interrupt text' }, emptyOverrides),+ );++ // Flag consumed: a second abort does NOT drain+ act(() => {+ setters.setQueue!([queuedMessage('q2', 'still queued')]);+ setters.setRunEnd!(runEnd({ outcome: 'aborted' }));+ });+ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(ask).toHaveBeenCalledTimes(1);+ });++ it('waits for isSubmitting to flip false before draining', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [queuedMessage('q1', 'deferred')]);+ set(store.isSubmittingFamily(INDEX), true);+ });++ act(() => {+ setters.setRunEnd!(runEnd());+ });+ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(ask).not.toHaveBeenCalled();++ act(() => {+ setters.setIsSubmitting!(false);+ });+ await waitFor(() => expect(ask).toHaveBeenCalledWith({ text: 'deferred' }, emptyOverrides));+ });++ it('migrates a NEW_CONVO-keyed queue when the run started as a new conversation', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(Constants.NEW_CONVO), [+ queuedMessage('q1', 'queued before convo existed'),+ queuedMessage('q2', 'second'),+ ]);+ });++ act(() => {+ setters.setRunEnd!(runEnd({ startedAsNewConvo: true }));+ });++ await waitFor(() =>+ expect(ask).toHaveBeenCalledWith({ text: 'queued before convo existed' }, emptyOverrides),+ );+ });++ describe('early-aborted first turn (NEW_CONVO-keyed signal)', () => {+ const OPTIMISTIC_ID = 'optimistic-stream-id';++ function setupNewConvo(initialize?: (snapshot: MutableSnapshot) => void) {+ const ask = jest.fn();+ const setters: {+ setRunEnd?: (value: RunEnd | null) => void;+ setInterruptFlag?: (value: boolean) => void;+ } = {};+ const state: {+ newConvoQueue?: QueuedMessage[];+ parkedUnderOptimistic?: RunEnd | null;+ } = {};++ function Harness() {+ setters.setRunEnd = useSetRecoilState(store.runEndByIndex(INDEX));+ setters.setInterruptFlag = useSetRecoilState(store.drainAfterAbortByIndex(INDEX));+ state.newConvoQueue = useRecoilValue(store.queuedMessagesByConvoId(Constants.NEW_CONVO));+ state.parkedUnderOptimistic = useRecoilValue(store.pendingRunEndByConvoId(OPTIMISTIC_ID));+ useQueueDrain(INDEX, Constants.NEW_CONVO as string, ask);+ return null;+ }++ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot initializeState={initialize}>+ <Harness />+ {children}+ </RecoilRoot>+ );+ renderHook(() => null, { wrapper });+ return { ask, setters, state };+ }++ it('leaves the NEW_CONVO queue in place and parks nothing under the optimistic id', async () => {+ const { ask, setters, state } = setupNewConvo(({ set }) => {+ set(store.queuedMessagesByConvoId(Constants.NEW_CONVO), [+ queuedMessage('q1', 'queued during first turn'),+ ]);+ });++ act(() => {+ setters.setRunEnd!(+ runEnd({+ conversationId: Constants.NEW_CONVO as string,+ outcome: 'aborted',+ startedAsNewConvo: false,+ }),+ );+ });++ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(ask).not.toHaveBeenCalled();+ // The queue stays visible on the restored new-chat composer.+ expect(state.newConvoQueue).toEqual([+ expect.objectContaining({ id: 'q1', text: 'queued during first turn' }),+ ]);+ expect(state.parkedUnderOptimistic).toBeNull();+ });++ it('drains under NEW_CONVO when interrupt & send was armed', async () => {+ const { ask } = setupNewConvo(({ set }) => {+ set(store.queuedMessagesByConvoId(Constants.NEW_CONVO), [+ queuedMessage('q1', 'interrupted first turn'),+ ]);+ set(store.drainAfterAbortByIndex(INDEX), true);+ set(store.runEndByIndex(INDEX), {+ conversationId: Constants.NEW_CONVO as string,+ outcome: 'aborted',+ startedAsNewConvo: false,+ endedAt: Date.now(),+ });+ });++ await waitFor(() =>+ expect(ask).toHaveBeenCalledWith({ text: 'interrupted first turn' }, emptyOverrides),+ );+ expect(ask).toHaveBeenCalledTimes(1);+ });+ });++ it('consumes the run-end signal (no double fire on re-render)', async () => {+ const { ask, setters } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [+ queuedMessage('q1', 'one'),+ queuedMessage('q2', 'two'),+ ]);+ });++ act(() => {+ setters.setRunEnd!(runEnd());+ });+ await waitFor(() => expect(ask).toHaveBeenCalledTimes(1));++ // Toggling isSubmitting without a fresh runEnd must not drain again+ act(() => {+ setters.setIsSubmitting!(true);+ });+ act(() => {+ setters.setIsSubmitting!(false);+ });+ await new Promise((resolve) => setTimeout(resolve, 25));+ expect(ask).toHaveBeenCalledTimes(1);+ });+});diff --git a/client/src/hooks/Chat/__tests__/useSteerConvert.spec.tsx b/client/src/hooks/Chat/__tests__/useSteerConvert.spec.tsxnew file mode 100644index 0000000000..613e5aca37--- /dev/null+++ b/client/src/hooks/Chat/__tests__/useSteerConvert.spec.tsx@@ -0,0 +1,187 @@+import React from 'react';+import { act, renderHook } from '@testing-library/react';+import { RecoilRoot, useRecoilValue, type MutableSnapshot } from 'recoil';+import useSteerConvert from '../useSteerConvert';+import store from '~/store';++const mockFetchStreamStatus = jest.fn();+jest.mock('~/data-provider', () => ({+ fetchStreamStatus: (...args: unknown[]) => mockFetchStreamStatus(...args),+}));++const CONVO_ID = 'convo-steer-convert';++function setup(initialize?: (snapshot: MutableSnapshot) => void) {+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot initializeState={initialize}>{children}</RecoilRoot>+ );+ return renderHook(+ () => ({+ convert: useSteerConvert(),+ chips: useRecoilValue(store.pendingSteersByConvoId(CONVO_ID)),+ queue: useRecoilValue(store.queuedMessagesByConvoId(CONVO_ID)),+ applied: useRecoilValue(store.appliedSteerIdsByConvoId(CONVO_ID)),+ }),+ { wrapper },+ );+}++describe('useSteerConvert', () => {+ it('converts leftover steers to queued chips and drops their pending chips', () => {+ const { result } = setup(({ set }) => {+ set(store.pendingSteersByConvoId(CONVO_ID), [+ { steerId: 'srv-1', text: 'leftover', status: 'pending' as const, createdAt: 1 },+ { steerId: 'local-x', text: 'still sending', status: 'sending' as const, createdAt: 2 },+ ]);+ });+ act(() => {+ result.current.convert(CONVO_ID, [{ steerId: 'srv-1', text: 'leftover', createdAt: 1 }]);+ });+ expect(result.current.queue).toEqual([expect.objectContaining({ id: 'srv-1' })]);+ expect(result.current.chips).toEqual([expect.objectContaining({ steerId: 'local-x' })]);+ });++ it('restores quotes + manual skills from the local chip (server steers never carry them)', () => {+ const { result } = setup(({ set }) => {+ set(store.pendingSteersByConvoId(CONVO_ID), [+ {+ steerId: 'srv-ctx',+ text: 'carried',+ status: 'pending' as const,+ createdAt: 1,+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ },+ ]);+ });+ act(() => {+ result.current.convert(CONVO_ID, [{ steerId: 'srv-ctx', text: 'carried', createdAt: 1 }]);+ });+ expect(result.current.chips).toEqual([]);+ expect(result.current.queue).toEqual([+ expect.objectContaining({+ id: 'srv-ctx',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ ]);+ });++ it('adds no context fields when no local chip matches (fresh reload)', () => {+ const { result } = setup();+ act(() => {+ result.current.convert(CONVO_ID, [{ steerId: 'srv-plain', text: 'plain', createdAt: 1 }]);+ });+ expect(result.current.queue[0].quotes).toBeUndefined();+ expect(result.current.queue[0].manualSkills).toBeUndefined();+ });++ it('retains previously applied ids so a late 202 ACK still drops its chip', () => {+ const { result } = setup(({ set }) => {+ set(store.appliedSteerIdsByConvoId(CONVO_ID), ['srv-applied']);+ });+ act(() => {+ result.current.convert(CONVO_ID, [{ steerId: 'srv-queued', text: 'to queue' }]);+ });+ // Both the applied and converted steers are settled — an ACK arriving+ // after run end must not re-mint a pending chip for either.+ expect(result.current.applied).toEqual(['srv-applied', 'srv-queued']);+ });++ it('keeps interrupt front-inserts ahead of chronologically older steers', () => {+ const { result } = setup(({ set }) => {+ set(store.queuedMessagesByConvoId(CONVO_ID), [+ { id: 'urgent', text: 'interrupt message', createdAt: 100, priority: true },+ ]);+ });+ act(() => {+ // Older steer (createdAt 50) converts after the interrupt was queued.+ result.current.convert(CONVO_ID, [{ steerId: 'old', text: 'older steer', createdAt: 50 }]);+ });+ expect(result.current.queue.map((item) => item.id)).toEqual(['urgent', 'old']);+ });++ it('is idempotent across double delivery (abort response + final SSE event)', () => {+ const { result } = setup();+ const steers = [{ steerId: 'srv-2', text: 'delivered twice', createdAt: 5 }];+ act(() => {+ result.current.convert(CONVO_ID, steers);+ result.current.convert(CONVO_ID, steers);+ });+ expect(result.current.queue).toHaveLength(1);+ expect(result.current.applied).toEqual(['srv-2']);+ });++ describe('claimParked (clears the parked server copy of live-delivered steers)', () => {+ beforeEach(() => {+ mockFetchStreamStatus.mockReset();+ });++ it('fires exactly one status fetch per batch and dedupes the claimed steers', async () => {+ mockFetchStreamStatus.mockResolvedValue({+ active: false,+ unrecoveredSteers: [+ { steerId: 'live-1', text: 'delivered live', createdAt: 1 },+ { steerId: 'parked-1', text: 'parked only', createdAt: 2 },+ ],+ });+ const { result } = setup();+ await act(async () => {+ result.current.convert(+ CONVO_ID,+ [+ { steerId: 'live-1', text: 'delivered live', createdAt: 1 },+ { steerId: 'live-2', text: 'also live', createdAt: 3 },+ ],+ { claimParked: true },+ );+ });+ expect(mockFetchStreamStatus).toHaveBeenCalledTimes(1);+ expect(mockFetchStreamStatus).toHaveBeenCalledWith(CONVO_ID);+ // The claimed copy of live-1 re-ran the id-deduped conversion: no double-add.+ expect(result.current.queue.map((item) => item.id)).toEqual(['live-1', 'parked-1', 'live-2']);+ });++ it('tolerates a failed status fetch without breaking conversion', async () => {+ mockFetchStreamStatus.mockRejectedValue(new Error('offline'));+ const { result } = setup();+ await act(async () => {+ result.current.convert(CONVO_ID, [{ steerId: 'srv-3', text: 'kept', createdAt: 1 }], {+ claimParked: true,+ });+ });+ expect(mockFetchStreamStatus).toHaveBeenCalledTimes(1);+ expect(result.current.queue).toEqual([expect.objectContaining({ id: 'srv-3' })]);+ });++ it('claims under claimConversationId while chips land under the chip key', async () => {+ mockFetchStreamStatus.mockResolvedValue({+ active: false,+ unrecoveredSteers: [+ { steerId: 'parked-2', text: 'parked under resolved id', createdAt: 2 },+ ],+ });+ const { result } = setup();+ await act(async () => {+ result.current.convert(CONVO_ID, [{ steerId: 'live-3', text: 'live', createdAt: 1 }], {+ claimParked: true,+ claimConversationId: 'convo-resolved',+ });+ });+ expect(mockFetchStreamStatus).toHaveBeenCalledTimes(1);+ expect(mockFetchStreamStatus).toHaveBeenCalledWith('convo-resolved');+ // Claimed steers still convert under the conversation the chips live on.+ expect(result.current.queue.map((item) => item.id)).toEqual(['live-3', 'parked-2']);+ });++ it('skips the claim without the option or with an empty batch', async () => {+ const { result } = setup();+ await act(async () => {+ result.current.convert(CONVO_ID, [{ steerId: 'srv-4', text: 'plain', createdAt: 1 }]);+ result.current.convert(CONVO_ID, [], { claimParked: true });+ });+ expect(mockFetchStreamStatus).not.toHaveBeenCalled();+ expect(result.current.queue).toEqual([expect.objectContaining({ id: 'srv-4' })]);+ });+ });+});diff --git a/client/src/hooks/Chat/__tests__/useSteering.spec.tsx b/client/src/hooks/Chat/__tests__/useSteering.spec.tsxnew file mode 100644index 0000000000..12faedbdbc--- /dev/null+++ b/client/src/hooks/Chat/__tests__/useSteering.spec.tsx@@ -0,0 +1,808 @@+import React from 'react';+import { act, renderHook } from '@testing-library/react';+import { RecoilRoot, useRecoilValue, type MutableSnapshot } from 'recoil';+import { Constants, ContentTypes, EModelEndpoint } from 'librechat-data-provider';+import type { TConversation, TMessage } from 'librechat-data-provider';+import useSteering from '../useSteering';+import store from '~/store';++const CONVO_ID = 'convo-steer-ui';++const mockMutate = jest.fn();+const mockShowToast = jest.fn();+const mockMarkUsage = jest.fn();+let mockMessages: TMessage[] | undefined;++jest.mock('~/data-provider', () => ({+ useSteerMessageMutation: () => ({ mutate: mockMutate }),+ useGetMessagesByConvoId: () => ({ data: mockMessages }),+ useMarkFilesUsageMutation: () => ({ mutate: mockMarkUsage }),+}));++jest.mock('@librechat/client', () => ({+ useToastContext: () => ({ showToast: mockShowToast }),+}));++const agentsConversation = {+ conversationId: CONVO_ID,+ endpoint: EModelEndpoint.agents,+} as TConversation;++type HookParams = Partial<Parameters<typeof useSteering>[0]>;++function setup(params: HookParams = {}, initialize?: (snapshot: MutableSnapshot) => void) {+ const sendNow = jest.fn();+ const stopGenerating = jest.fn();+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot initializeState={initialize}>{children}</RecoilRoot>+ );+ const rendered = renderHook(+ () =>+ useSteering({+ index: 0,+ conversationId: CONVO_ID,+ conversation: agentsConversation,+ isSubmitting: true,+ answerModeActive: false,+ sendNow,+ stopGenerating,+ ...params,+ }),+ { wrapper },+ );+ return { ...rendered, sendNow, stopGenerating };+}++function useQueue(convoId: string) {+ return useRecoilValue(store.queuedMessagesByConvoId(convoId));+}++describe('useSteering', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ mockMessages = undefined;+ });++ describe('effectiveAction', () => {+ it('defaults to steer during an active agents run', () => {+ const { result } = setup();+ expect(result.current.duringRunActive).toBe(true);+ expect(result.current.effectiveAction).toBe('steer');+ });++ it('honors the queue preference while keeping the steer override available', () => {+ const { result } = setup({}, ({ set }) => {+ set(store.duringRunDefaultAction, 'queue');+ });+ expect(result.current.effectiveAction).toBe('queue');+ // The per-send menu can still override to steer — availability is+ // independent of the default action.+ expect(result.current.canSteer).toBe(true);+ });++ it('degrades to queue without a real conversation id', () => {+ const { result } = setup({ conversationId: Constants.NEW_CONVO as string });+ expect(result.current.effectiveAction).toBe('queue');+ });++ it('degrades to queue while paused on a tool approval', () => {+ mockMessages = [+ {+ messageId: 'resp-1',+ isCreatedByUser: false,+ content: [+ {+ type: ContentTypes.TOOL_CALL,+ tool_call: { id: 'call-1', name: 'shell', approval: { actionId: 'a1' }, output: '' },+ },+ ],+ } as unknown as TMessage,+ ];+ const { result } = setup();+ expect(result.current.pausedOnApproval).toBe(true);+ expect(result.current.effectiveAction).toBe('queue');+ expect(result.current.canSteer).toBe(false);+ });++ it('is inactive for assistants endpoints, secondary composers, and answer mode', () => {+ expect(+ setup({ conversation: { endpoint: EModelEndpoint.assistants } as TConversation }).result+ .current.duringRunActive,+ ).toBe(false);+ expect(setup({ index: 1 }).result.current.duringRunActive).toBe(false);+ expect(setup({ answerModeActive: true }).result.current.duringRunActive).toBe(false);+ });+ });++ describe('submitDuringRun', () => {+ it('routes to the steer POST with an optimistic sending chip', () => {+ const { result } = setup();+ let consumed = false;+ act(() => {+ consumed = result.current.submitDuringRun('steer this');+ });+ expect(consumed).toBe(true);+ expect(mockMutate).toHaveBeenCalledWith(+ { conversationId: CONVO_ID, text: 'steer this' },+ expect.anything(),+ );+ });++ it('routes to the client queue when the preference is queue', () => {+ const { result } = setup({}, ({ set }) => {+ set(store.duringRunDefaultAction, 'queue');+ });+ act(() => {+ result.current.submitDuringRun('after the run');+ });+ expect(mockMutate).not.toHaveBeenCalled();+ });++ it('ignores empty submissions', () => {+ const { result } = setup();+ let consumed = true;+ act(() => {+ consumed = result.current.submitDuringRun(' ');+ });+ expect(consumed).toBe(false);+ expect(mockMutate).not.toHaveBeenCalled();+ });+ });++ describe('steer POST outcomes', () => {+ it('queues on NO_ACTIVE_RUN while the final SSE is still settling', () => {+ // isSubmitting is still true: ask()'s in-flight guard would drop a+ // direct send, so the text must go to the queue for the run-end drain.+ mockMutate.mockImplementation((_params, { onError }) => {+ onError({ response: { data: { code: 'NO_ACTIVE_RUN' } } });+ });+ const { result, sendNow } = setup({ isSubmitting: true });+ act(() => {+ result.current.submitSteer('too late');+ });+ expect(sendNow).not.toHaveBeenCalled();+ });++ it('sends as a normal turn on NO_ACTIVE_RUN once submission has settled', () => {+ mockMutate.mockImplementation((_params, { onError }) => {+ onError({ response: { data: { code: 'NO_ACTIVE_RUN' } } });+ });+ const { result, sendNow } = setup({ isSubmitting: false });+ act(() => {+ result.current.submitSteer('too late');+ });+ expect(sendNow).toHaveBeenCalledWith('too late', [], undefined);+ });++ it('queues + toasts when the run is paused (RUN_PAUSED)', () => {+ mockMutate.mockImplementation((_params, { onError }) => {+ onError({ response: { data: { code: 'RUN_PAUSED' } } });+ });+ const { result } = setup();+ act(() => {+ result.current.submitSteer('paused steer');+ });+ expect(mockShowToast).toHaveBeenCalled();+ });+ });++ describe('interruptAndSend + queue helpers', () => {+ function setupWithState(+ params: HookParams = {},+ initialize?: (snapshot: MutableSnapshot) => void,+ ) {+ const sendNow = jest.fn();+ const stopGenerating = jest.fn();+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot initializeState={initialize}>{children}</RecoilRoot>+ );+ const rendered = renderHook(+ () => ({+ steering: useSteering({+ index: 0,+ conversationId: CONVO_ID,+ conversation: agentsConversation,+ isSubmitting: true,+ answerModeActive: false,+ sendNow,+ stopGenerating,+ ...params,+ }),+ queue: useQueue(CONVO_ID),+ chips: useRecoilValue(store.pendingSteersByConvoId(CONVO_ID)),+ drainFlag: useRecoilValue(store.drainAfterAbortByIndex(0)),+ }),+ { wrapper },+ );+ return { ...rendered, sendNow, stopGenerating };+ }++ it('drops the ACK chip when on_steer_applied already landed (SSE beat the 202)', () => {+ mockMutate.mockImplementation((_params, { onSuccess }) => {+ onSuccess({ steerId: 'srv-1', status: 'queued', position: 1, conversationId: CONVO_ID });+ });+ const { result } = setupWithState({}, ({ set }) => {+ set(store.appliedSteerIdsByConvoId(CONVO_ID), ['srv-1']);+ });+ act(() => {+ result.current.steering.submitSteer('already injected');+ });+ // No pending chip may survive — its only removal event already passed.+ expect(result.current.chips).toEqual([]);+ });++ it('converts the ACK chip to pending when the steer is not yet applied', () => {+ mockMutate.mockImplementation((_params, { onSuccess }) => {+ onSuccess({ steerId: 'srv-2', status: 'queued', position: 1, conversationId: CONVO_ID });+ });+ const { result } = setupWithState();+ act(() => {+ result.current.steering.submitSteer('awaiting boundary');+ });+ expect(result.current.chips).toEqual([+ expect.objectContaining({ steerId: 'srv-2', status: 'pending' }),+ ]);+ });++ it('does not duplicate a chip already reseeded under the server id (SSE reconnect)', () => {+ mockMutate.mockImplementation((_params, { onSuccess }) => {+ onSuccess({ steerId: 'srv-3', status: 'queued', position: 1, conversationId: CONVO_ID });+ });+ const { result } = setupWithState({}, ({ set }) => {+ // seedSteerChips already re-minted this chip from resumeState before+ // the 202 ACK landed — the ACK must upsert, not append.+ set(store.pendingSteersByConvoId(CONVO_ID), [+ { steerId: 'srv-3', text: 'reseeded', status: 'pending', createdAt: 1 },+ ]);+ });+ act(() => {+ result.current.steering.submitSteer('reseeded');+ });+ expect(result.current.chips.filter((chip) => chip.steerId === 'srv-3')).toHaveLength(1);+ });++ it('restores the queued item (same id, front) when sendNow refuses', () => {+ const refusingSendNow = jest.fn().mockReturnValue(false);+ const { result } = setupWithState({ isSubmitting: false, sendNow: refusingSendNow });+ act(() => {+ result.current.steering.enqueue('refused send');+ result.current.steering.enqueue('still behind');+ });+ const [first, second] = result.current.queue;+ act(() => {+ result.current.steering.sendQueuedNow(first);+ });+ expect(refusingSendNow).toHaveBeenCalledWith('refused send', [], {});+ // `ask` refused without sending — the ORIGINAL item returns to the front.+ expect(result.current.queue.map((item) => item.id)).toEqual([first.id, second.id]);+ expect(result.current.queue[0]).toEqual(first);+ });++ it('queues the steer text+files when a settled NO_ACTIVE_RUN send is refused', () => {+ const steerFiles = [+ { file_id: 'file-refused', filepath: '/uploads/file-refused.png', type: 'image/png' },+ ];+ mockMutate.mockImplementationOnce((_params, { onError }) => {+ onError({ response: { data: { code: 'NO_ACTIVE_RUN' } } });+ });+ const refusingSendNow = jest.fn().mockReturnValue(false);+ const { result } = setupWithState({ isSubmitting: false, sendNow: refusingSendNow });+ act(() => {+ result.current.steering.submitSteer('refused words', steerFiles);+ });+ expect(refusingSendNow).toHaveBeenCalledWith('refused words', steerFiles, undefined);+ // The chip is already gone — a refused send must land in the queue, not drop.+ expect(result.current.chips).toEqual([]);+ expect(result.current.queue).toEqual([+ expect.objectContaining({ text: 'refused words', files: steerFiles }),+ ]);+ });++ it('queues the steer text+files when a settled-run rejection send is refused', () => {+ const steerFiles = [+ { file_id: 'file-paused', filepath: '/uploads/file-paused.png', type: 'image/png' },+ ];+ mockMutate.mockImplementationOnce((_params, { onError }) => {+ onError({ response: { data: { code: 'STEER_UNSUPPORTED' } } });+ });+ const refusingSendNow = jest.fn().mockReturnValue(false);+ const { result } = setupWithState({ isSubmitting: false, sendNow: refusingSendNow });+ act(() => {+ result.current.steering.submitSteer('unsupported words', steerFiles);+ });+ expect(refusingSendNow).toHaveBeenCalledWith('unsupported words', steerFiles, undefined);+ expect(result.current.chips).toEqual([]);+ expect(result.current.queue).toEqual([+ expect.objectContaining({ text: 'unsupported words', files: steerFiles }),+ ]);+ });++ it('does not restore the queued item when sendNow accepts', () => {+ const acceptingSendNow = jest.fn().mockReturnValue(undefined);+ const { result } = setupWithState({ isSubmitting: false, sendNow: acceptingSendNow });+ act(() => {+ result.current.steering.enqueue('accepted send');+ });+ const queued = result.current.queue[0];+ act(() => {+ result.current.steering.sendQueuedNow(queued);+ });+ expect(acceptingSendNow).toHaveBeenCalledWith('accepted send', [], {});+ expect(result.current.queue).toEqual([]);+ });++ it('interruptAndSend queues at the front, arms the drain flag, and stops the run', () => {+ const { result, stopGenerating } = setupWithState();+ act(() => {+ result.current.steering.enqueue('already queued');+ });+ act(() => {+ result.current.steering.interruptAndSend('urgent redirect');+ });+ expect(result.current.queue.map((item) => item.text)).toEqual([+ 'urgent redirect',+ 'already queued',+ ]);+ expect(result.current.drainFlag).toBe(true);+ expect(stopGenerating).toHaveBeenCalledTimes(1);+ });++ it('enqueue appends and removeQueued deletes by id', () => {+ const { result } = setupWithState();+ act(() => {+ result.current.steering.enqueue('one');+ result.current.steering.enqueue('two');+ });+ expect(result.current.queue.map((item) => item.text)).toEqual(['one', 'two']);+ const firstId = result.current.queue[0].id;+ act(() => {+ result.current.steering.removeQueued(firstId);+ });+ expect(result.current.queue.map((item) => item.text)).toEqual(['two']);+ expect(mockMutate).not.toHaveBeenCalled();+ });++ it('sendQueuedNow steers whenever steering is available, even under the queue preference', () => {+ const { result } = setupWithState({}, ({ set }) => {+ set(store.duringRunDefaultAction, 'queue');+ });+ act(() => {+ result.current.steering.enqueue('send me now');+ });+ const queued = result.current.queue[0];+ act(() => {+ result.current.steering.sendQueuedNow(queued);+ });+ expect(result.current.queue).toEqual([]);+ expect(mockMutate).toHaveBeenCalledWith(+ { conversationId: CONVO_ID, text: 'send me now' },+ expect.anything(),+ );+ });+ });++ describe('attachments', () => {+ const composerFile = {+ file_id: 'file-1',+ filepath: '/uploads/file-1.png',+ type: 'image/png',+ height: 10,+ width: 10,+ };+ const queuedFiles = [{ file_id: 'file-1', filepath: '/uploads/file-1.png', type: 'image/png' }];++ function setupWithFiles(params: HookParams = {}) {+ const setFiles = jest.fn();+ const files = new Map([['file-1', composerFile]]) as unknown as NonNullable<+ Parameters<typeof useSteering>[0]['files']+ >;+ const sendNow = jest.fn();+ const stopGenerating = jest.fn();+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot>{children}</RecoilRoot>+ );+ const rendered = renderHook(+ () => ({+ steering: useSteering({+ index: 0,+ conversationId: CONVO_ID,+ conversation: agentsConversation,+ isSubmitting: true,+ answerModeActive: false,+ files,+ setFiles,+ sendNow,+ stopGenerating,+ ...params,+ }),+ queue: useQueue(CONVO_ID),+ }),+ { wrapper },+ );+ return { ...rendered, setFiles, sendNow, stopGenerating };+ }++ it('steers with the composer attachments as one unit', () => {+ const { result, setFiles } = setupWithFiles();+ let consumed = false;+ act(() => {+ consumed = result.current.steering.submitDuringRun('look at this image');+ });+ expect(consumed).toBe(true);+ expect(mockMutate).toHaveBeenCalledWith(+ {+ conversationId: CONVO_ID,+ text: 'look at this image',+ files: [expect.objectContaining({ file_id: 'file-1' })],+ },+ expect.anything(),+ );+ expect(result.current.queue).toEqual([]);+ expect(setFiles).toHaveBeenCalledWith(new Map());+ });++ it('holds during-run submits while uploads are in flight', () => {+ const { result } = setupWithFiles({ filesLoading: true });+ let consumed = true;+ act(() => {+ consumed = result.current.steering.submitDuringRun('too early');+ });+ expect(consumed).toBe(false);+ expect(result.current.queue).toEqual([]);+ expect(mockMutate).not.toHaveBeenCalled();+ });++ it('steers a queued media item with its own files during a live run', () => {+ const { result, sendNow } = setupWithFiles();+ act(() => {+ result.current.steering.sendQueuedNow({+ id: 'q-media',+ text: 'media message',+ createdAt: Date.now(),+ files: queuedFiles,+ });+ });+ expect(sendNow).not.toHaveBeenCalled();+ expect(mockMutate).toHaveBeenCalledWith(+ { conversationId: CONVO_ID, text: 'media message', files: queuedFiles },+ expect.anything(),+ );+ expect(result.current.queue).toEqual([]);+ });++ it('sends a media item as a normal turn with its own files when idle', () => {+ const { result, sendNow } = setupWithFiles({ isSubmitting: false });+ act(() => {+ result.current.steering.sendQueuedNow({+ id: 'q-media',+ text: 'media message',+ createdAt: Date.now(),+ files: queuedFiles,+ });+ });+ expect(sendNow).toHaveBeenCalledWith('media message', queuedFiles, {});+ });++ it('marks queued files used exactly once when queueing from the composer', () => {+ const { result } = setupWithFiles();+ act(() => {+ result.current.steering.queueFromComposer('queued with media');+ });+ expect(mockMarkUsage).toHaveBeenCalledTimes(1);+ expect(mockMarkUsage).toHaveBeenCalledWith({ file_ids: ['file-1'] });+ });++ it('marks queued files used on interrupt & send', () => {+ const { result } = setupWithFiles();+ act(() => {+ result.current.steering.interruptAndSend('urgent with media');+ });+ expect(mockMarkUsage).toHaveBeenCalledTimes(1);+ expect(mockMarkUsage).toHaveBeenCalledWith({ file_ids: ['file-1'] });+ });++ it('does not mark usage for text-only queueing', () => {+ const { result } = setupWithFiles({ files: new Map() });+ act(() => {+ result.current.steering.queueFromComposer('just text');+ });+ expect(mockMarkUsage).not.toHaveBeenCalled();+ });++ it('does not mark usage on the steer path (the 202 already marked)', () => {+ const { result } = setupWithFiles();+ act(() => {+ result.current.steering.submitDuringRun('steer with media');+ });+ expect(mockMutate).toHaveBeenCalledTimes(1);+ expect(mockMarkUsage).not.toHaveBeenCalled();+ });++ it('does not re-mark already-queued files on a send-now re-queue', () => {+ // Paused on approval → steering unavailable while the run is live, so+ // sendQueuedNow front-requeues the item — its files were already marked.+ mockMessages = [+ {+ messageId: 'resp-1',+ isCreatedByUser: false,+ content: [+ {+ type: ContentTypes.TOOL_CALL,+ tool_call: { id: 'call-1', name: 'shell', approval: { actionId: 'a1' }, output: '' },+ },+ ],+ } as unknown as TMessage,+ ];+ const { result } = setupWithFiles();+ act(() => {+ result.current.steering.sendQueuedNow({+ id: 'q-requeue',+ text: 'requeued media',+ createdAt: Date.now(),+ files: queuedFiles,+ });+ });+ expect(result.current.queue).toEqual([+ expect.objectContaining({ text: 'requeued media', files: queuedFiles, priority: true }),+ ]);+ expect(mockMarkUsage).not.toHaveBeenCalled();+ });+ });++ describe('composer quotes + manual skill capture', () => {+ function setupWithContext(+ params: HookParams = {},+ initialize?: (snapshot: MutableSnapshot) => void,+ ) {+ const sendNow = jest.fn();+ const stopGenerating = jest.fn();+ const wrapper = ({ children }: { children: React.ReactNode }) => (+ <RecoilRoot initializeState={initialize}>{children}</RecoilRoot>+ );+ const rendered = renderHook(+ () => ({+ steering: useSteering({+ index: 0,+ conversationId: CONVO_ID,+ conversation: agentsConversation,+ isSubmitting: true,+ answerModeActive: false,+ sendNow,+ stopGenerating,+ ...params,+ }),+ queue: useQueue(CONVO_ID),+ chips: useRecoilValue(store.pendingSteersByConvoId(CONVO_ID)),+ pendingQuotes: useRecoilValue(store.pendingQuotesByConvoId(CONVO_ID)),+ pendingSkills: useRecoilValue(store.pendingManualSkillsByConvoId(CONVO_ID)),+ }),+ { wrapper },+ );+ return { ...rendered, sendNow };+ }++ const stageContext = ({ set }: MutableSnapshot) => {+ set(store.pendingQuotesByConvoId(CONVO_ID), ['quoted excerpt']);+ set(store.pendingManualSkillsByConvoId(CONVO_ID), ['skill-1']);+ };++ it('queueFromComposer consumes staged quotes + skills into the queued item', () => {+ const { result } = setupWithContext({}, stageContext);+ act(() => {+ result.current.steering.queueFromComposer('with context');+ });+ expect(result.current.queue).toEqual([+ expect.objectContaining({+ text: 'with context',+ quotes: ['quoted excerpt'],+ manualSkills: ['skill-1'],+ }),+ ]);+ // Consumed, not copied: the composer chips must not ride the NEXT send.+ expect(result.current.pendingQuotes).toEqual([]);+ expect(result.current.pendingSkills).toEqual([]);+ });++ it('interruptAndSend captures the staged context on the front item', () => {+ const { result } = setupWithContext({}, stageContext);+ act(() => {+ result.current.steering.enqueue('already queued');+ });+ act(() => {+ result.current.steering.interruptAndSend('urgent redirect');+ });+ expect(result.current.queue[0]).toEqual(+ expect.objectContaining({+ text: 'urgent redirect',+ quotes: ['quoted excerpt'],+ manualSkills: ['skill-1'],+ }),+ );+ expect(result.current.queue[1].quotes).toBeUndefined();+ expect(result.current.pendingQuotes).toEqual([]);+ expect(result.current.pendingSkills).toEqual([]);+ });++ it('leaves staged context untouched on the steer path (steers do not carry it)', () => {+ const { result } = setupWithContext({}, stageContext);+ act(() => {+ result.current.steering.steerFromComposer('steer text');+ });+ expect(mockMutate).toHaveBeenCalledTimes(1);+ expect(result.current.pendingQuotes).toEqual(['quoted excerpt']);+ expect(result.current.pendingSkills).toEqual(['skill-1']);+ });++ it('queues without quotes/skills fields when nothing is staged', () => {+ const { result } = setupWithContext();+ act(() => {+ result.current.steering.queueFromComposer('plain text');+ });+ expect(result.current.queue[0].quotes).toBeUndefined();+ expect(result.current.queue[0].manualSkills).toBeUndefined();+ });++ it('sendQueuedNow passes the carried context to sendNow when idle', () => {+ const { result, sendNow } = setupWithContext({ isSubmitting: false });+ act(() => {+ result.current.steering.sendQueuedNow({+ id: 'q-ctx',+ text: 'context send',+ createdAt: Date.now(),+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });+ expect(sendNow).toHaveBeenCalledWith('context send', [], {+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });++ it('requeues a degraded queued-origin steer with its carried quotes + skills', () => {+ // The item left the queue before the POST settled; the 409 fallback+ // must restore its FULL context, not just text + files.+ mockMutate.mockImplementationOnce((_params, { onError }) => {+ onError({ response: { data: { code: 'RUN_PAUSED' } } });+ });+ const { result } = setupWithContext();+ act(() => {+ result.current.steering.sendQueuedNow({+ id: 'q-degraded',+ text: 'carried context',+ createdAt: Date.now(),+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });+ expect(result.current.queue).toEqual([+ expect.objectContaining({+ text: 'carried context',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ ]);+ });++ it('sends a settled NO_ACTIVE_RUN fallback with the carried context as overrides', () => {+ mockMutate.mockImplementationOnce((_params, { onError }) => {+ onError({ response: { data: { code: 'NO_ACTIVE_RUN' } } });+ });+ const { result, sendNow } = setupWithContext({ isSubmitting: false });+ act(() => {+ result.current.steering.submitSteer('late context', undefined, {+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });+ expect(sendNow).toHaveBeenCalledWith('late context', [], {+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });++ it('carries a queued-origin context onto the sending chip and the 202 ACK chip', () => {+ mockMutate.mockImplementationOnce((_params, { onSuccess }) => {+ onSuccess({ steerId: 'srv-ctx', status: 'queued', position: 1, conversationId: CONVO_ID });+ });+ const { result } = setupWithContext();+ act(() => {+ result.current.steering.submitSteer('carried steer', undefined, {+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });+ expect(result.current.chips).toEqual([+ expect.objectContaining({+ steerId: 'srv-ctx',+ status: 'pending',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ ]);+ });++ it('restores the carried context when a late ACK converts straight to queued', () => {+ // The run ended before the 202 landed: the ACK's queued conversion is+ // the only surviving copy of the steer, so it must keep quotes + skills.+ mockMutate.mockImplementationOnce((_params, { onSuccess }) => {+ onSuccess({ steerId: 'srv-late', status: 'queued', position: 1, conversationId: CONVO_ID });+ });+ const { result } = setupWithContext({ isSubmitting: false });+ act(() => {+ result.current.steering.submitSteer('late carried', undefined, {+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });+ expect(result.current.chips).toEqual([]);+ expect(result.current.queue).toEqual([+ expect.objectContaining({+ id: 'srv-late',+ text: 'late carried',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ ]);+ });++ it('keeps the carried context on a failed chip through retry', () => {+ mockMutate.mockImplementationOnce((_params, { onError }) => {+ onError({ response: { data: { code: 'SOME_ERROR' } } });+ });+ const { result } = setupWithContext();+ act(() => {+ result.current.steering.submitSteer('failed carried', undefined, {+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ });+ });+ const failed = result.current.chips[0];+ expect(failed).toEqual(+ expect.objectContaining({+ status: 'failed',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ );+ mockMutate.mockImplementationOnce((_params, { onSuccess }) => {+ onSuccess({+ steerId: 'srv-retry',+ status: 'queued',+ position: 1,+ conversationId: CONVO_ID,+ });+ });+ act(() => {+ result.current.steering.retrySteer(failed.steerId, failed.text, failed.files, {+ quotes: failed.quotes,+ manualSkills: failed.manualSkills,+ });+ });+ expect(result.current.chips).toEqual([+ expect.objectContaining({+ steerId: 'srv-retry',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ ]);+ });++ it('leaves composer atoms staged when a composer-origin steer degrades', () => {+ mockMutate.mockImplementationOnce((_params, { onError }) => {+ onError({ response: { data: { code: 'RUN_PAUSED' } } });+ });+ const { result } = setupWithContext({}, stageContext);+ act(() => {+ result.current.steering.steerFromComposer('degraded steer');+ });+ // Degrades to a text-only queued item; the staged chips stay put for+ // the user's next composer send.+ expect(result.current.queue).toEqual([expect.objectContaining({ text: 'degraded steer' })]);+ expect(result.current.queue[0].quotes).toBeUndefined();+ expect(result.current.queue[0].manualSkills).toBeUndefined();+ expect(result.current.pendingQuotes).toEqual(['quoted excerpt']);+ expect(result.current.pendingSkills).toEqual(['skill-1']);+ });+ });+});diff --git a/client/src/hooks/Chat/abort.ts b/client/src/hooks/Chat/abort.tsnew file mode 100644index 0000000000..0e6e2109fa--- /dev/null+++ b/client/src/hooks/Chat/abort.ts@@ -0,0 +1,36 @@+import { useRecoilCallback } from 'recoil';+import type { TSubmission } from 'librechat-data-provider';+import store from '~/store';++/**+ * Identity-guarded post-abort cleanup: the abort HTTP response can resolve+ * AFTER the aborted run's final SSE already fired the interrupt drain and+ * started the NEXT submission — clearing unconditionally at that point tears+ * down the new run's stream before it ever attaches, so its placeholder+ * finalizes empty. Capture the submission before the abort round-trip and+ * only clear when it is still the current one.+ */+export function useAbortCleanup(index: string | number) {+ const clearAllSubmissions = store.useClearSubmissionState();++ const captureSubmission = useRecoilCallback(+ ({ snapshot }) =>+ (): TSubmission | null =>+ snapshot.getLoadable(store.submissionByIndex(index)).getValue(),+ [index],+ );++ const clearSubmissionsUnlessReplaced = useRecoilCallback(+ ({ snapshot }) =>+ (captured: TSubmission | null) => {+ const current = snapshot.getLoadable(store.submissionByIndex(index)).getValue();+ if (current != null && current !== captured) {+ return;+ }+ clearAllSubmissions();+ },+ [clearAllSubmissions, index],+ );++ return { captureSubmission, clearSubmissionsUnlessReplaced };+}diff --git a/client/src/hooks/Chat/index.ts b/client/src/hooks/Chat/index.tsindex 9d9af790ce..cb10473ac5 100644--- a/client/src/hooks/Chat/index.ts+++ b/client/src/hooks/Chat/index.ts@@ -6,3 +6,6 @@ export { default as useChatFunctions } from './useChatFunctions';export { default as useGetAddedConvo } from './useGetAddedConvo';export { default as useIdChangeEffect } from './useIdChangeEffect';export { default as useFocusChatEffect } from './useFocusChatEffect';+export { default as useQueueDrain } from './useQueueDrain';+export { default as useSteering } from './useSteering';+export { default as useSteerConvert } from './useSteerConvert';diff --git a/client/src/hooks/Chat/useChatFunctions.ts b/client/src/hooks/Chat/useChatFunctions.tsindex 6fec07443b..2ab886db00 100644--- a/client/src/hooks/Chat/useChatFunctions.ts+++ b/client/src/hooks/Chat/useChatFunctions.ts@@ -496,9 +496,17 @@ export default function useChatFunctions({if (setFiles && reuseFiles === true) {currentMsg.files = [...submissionFiles];- setFiles(new Map());- setFilesToDelete({});- } else if (setFiles && files && files.size > 0) {+ // Caller-supplied overrideFiles were consumed elsewhere (queued+ // during-run messages take theirs out of the composer at queue time) —+ // clearing here would eat attachments staged for the user's NEXT send.+ if (isRegenerate) {+ setFiles(new Map());+ setFilesToDelete({});+ }+ } else if (setFiles && files && files.size > 0 && overrideFiles == null) {+ // `overrideFiles` (even empty) is authoritative for the submission:+ // auto-drained queued messages must never vacuum up attachments the+ // user has staged in the composer for their NEXT message.currentMsg.files = Array.from(files.values()).map((file) => ({file_id: file.file_id,filepath: file.filepath,diff --git a/client/src/hooks/Chat/useChatHelpers.ts b/client/src/hooks/Chat/useChatHelpers.tsindex 70bbbbc262..656e850a2d 100644--- a/client/src/hooks/Chat/useChatHelpers.ts+++ b/client/src/hooks/Chat/useChatHelpers.ts@@ -1,14 +1,17 @@import { useCallback, useMemo, useRef, useState } from 'react';import { useQueryClient } from '@tanstack/react-query';-import { useRecoilState, useSetRecoilState } from 'recoil';import { QueryKeys, isAssistantsEndpoint } from 'librechat-data-provider';+import { useRecoilState, useSetRecoilState, useRecoilCallback } from 'recoil';import type { TMessage } from 'librechat-data-provider';import type { ActiveJobsResponse } from '~/data-provider';import { useLatestMessage, useLatestMessageId } from '~/hooks/Messages/useLatestMessage';import useChatFunctions from '~/hooks/Chat/useChatFunctions';+import useSteerConvert from '~/hooks/Chat/useSteerConvert';import { useAbortStreamMutation } from '~/data-provider';+import { resolveAbortSteerTarget } from '~/utils';import useNewConvo from '~/hooks/useNewConvo';import { getMessageCacheIds } from './cache';+import { useAbortCleanup } from './abort';import store from '~/store';// this to be set somewhere else@@ -19,6 +22,34 @@ export default function useChatHelpers(index = 0, paramId?: string) {const queryClient = useQueryClient();const abortMutation = useAbortStreamMutation();+ const convertSteersToQueued = useSteerConvert();+ const { captureSubmission, clearSubmissionsUnlessReplaced } = useAbortCleanup(index);++ /**+ * Interrupt & send fallback: clearing submissions below can tear down the+ * SSE before its aborted-final event is processed, and only that event+ * writes the run-end signal the queue drain consumes. When the one-shot+ * interrupt flag is armed and no run-end has landed yet, write it here from+ * the abort response so the queued follow-up still auto-sends. If the SSE+ * final DOES arrive later, its signal finds the flag already consumed and+ * an `aborted` outcome drains nothing — no double fire.+ */+ const signalInterruptDrain = useRecoilCallback(+ ({ snapshot, set }) =>+ (convoId: string) => {+ const armed = snapshot.getLoadable(store.drainAfterAbortByIndex(index)).getValue();+ const runEnd = snapshot.getLoadable(store.runEndByIndex(index)).getValue();+ if (!armed || runEnd != null) {+ return;+ }+ set(store.runEndByIndex(index), {+ conversationId: convoId,+ outcome: 'aborted',+ endedAt: Date.now(),+ });+ },+ [index],+ );const { newConversation } = useNewConvo(index);const { useCreateConversationAtom } = store;@@ -150,24 +181,63 @@ export default function useChatHelpers(index = 0, paramId?: string) {activeJobIds: (old?.activeJobIds ?? []).filter((id) => id !== conversationId),}));+ // The aborted run's final SSE can land (and the interrupt drain can+ // start the NEXT submission) while the abort response is in flight —+ // the fallback clear below must not tear down that new run.+ const submissionAtAbort = captureSubmission();try {console.log('[useChatHelpers] Calling abort mutation for:', conversationId);- await abortMutation.mutateAsync({ conversationId });+ const response = await abortMutation.mutateAsync({ conversationId });console.log('[useChatHelpers] Abort mutation succeeded');+ // The response's `aborted` field is the RESOLVED job id — authoritative+ // when this turn still holds the `new` placeholder. Chips and the drain+ // signal land where the mounted composer's queue machinery looks, while+ // the parked-copy claim uses the resolved id the server keyed it under.+ const { chipConvoId, claimConvoId } = resolveAbortSteerTarget({+ conversationId,+ resolvedId: response?.aborted,+ });+ // Steers the run never injected ride the abort response. Consume them+ // here as well as on the SSE final event — clearing submissions below+ // can close the stream before that event lands, and conversion+ // dedupes by steer id so double delivery is a no-op. `claimParked`+ // clears the parked server copy so a reload can't re-mint the chips.+ if (Array.isArray(response?.pendingSteers)) {+ convertSteersToQueued(chipConvoId, response.pendingSteers, {+ claimParked: true,+ claimConversationId: claimConvoId,+ });+ }+ signalInterruptDrain(chipConvoId);// The SSE will receive a `done` event with `aborted: true` and clean up// We still clear submissions as a fallback- clearAllSubmissions();+ clearSubmissionsUnlessReplaced(submissionAtAbort);} catch (error) {console.error('[useChatHelpers] Abort failed:', error);+ // An abort that 404s (run completed first) still needs the interrupt+ // fallback: without a run-end signal the queued interrupt message+ // strands and the armed flag would leak onto a later run.+ signalInterruptDrain(conversationId);// Fall back to clearing submissions- clearAllSubmissions();+ clearSubmissionsUnlessReplaced(submissionAtAbort);}} else {// For assistants endpoints, just clear submissions (existing behavior)console.log('[useChatHelpers] Assistants endpoint, just clearing submissions');clearAllSubmissions();}- }, [conversationId, endpoint, endpointType, abortMutation, clearAllSubmissions, queryClient]);+ }, [+ conversationId,+ endpoint,+ endpointType,+ abortMutation,+ captureSubmission,+ convertSteersToQueued,+ signalInterruptDrain,+ clearSubmissionsUnlessReplaced,+ clearAllSubmissions,+ queryClient,+ ]);const handleStopGenerating = useCallback((e: React.MouseEvent<HTMLButtonElement>) => {diff --git a/client/src/hooks/Chat/useQueueDrain.ts b/client/src/hooks/Chat/useQueueDrain.tsnew file mode 100644index 0000000000..588038012e--- /dev/null+++ b/client/src/hooks/Chat/useQueueDrain.ts@@ -0,0 +1,161 @@+import { useEffect } from 'react';+import { Constants } from 'librechat-data-provider';+import { useRecoilValue, useRecoilCallback } from 'recoil';+import type { QueuedMessage } from '~/store/families';+import type { TAskFunction } from '~/common';+import store from '~/store';++/**+ * Auto-sends queued follow-up messages when a run finishes.+ *+ * Consumes the one-shot `runEndByIndex` signal written by the SSE handlers.+ * Rules:+ * - Drains only on a clean completion — a user Stop or an error leaves the+ * queued chips for manual send, EXCEPT when the one-shot+ * `drainAfterAbortByIndex` flag was armed by "interrupt & send".+ * - Waits for `isSubmitting` to be false so `ask()` isn't dropped by its+ * in-flight guard (`useChatFunctions.ask` early-returns while submitting).+ * - Dequeues ONE message per run end: the new turn's own final event drains+ * the next, so multi-message queues send FIFO in sequence.+ * - Migrates a queue keyed under `NEW_CONVO` to the real conversation id when+ * the finished run started as a new-conversation submission.+ */+export default function useQueueDrain(+ index: string | number,+ activeConversationId: string | undefined,+ ask: TAskFunction,+) {+ const runEnd = useRecoilValue(store.runEndByIndex(index));+ const parkedRunEnd = useRecoilValue(+ store.pendingRunEndByConvoId(activeConversationId ?? Constants.NEW_CONVO),+ );+ const isSubmitting = useRecoilValue(store.isSubmittingFamily(index));++ // Fully synchronous reads (getLoadable): a useRecoilCallback snapshot is+ // only guaranteed valid for the callback's synchronous execution, so no+ // awaits may interleave with the reads.+ const drainNext = useRecoilCallback(+ ({ snapshot, set }) =>+ (): { next: QueuedMessage; conversationId: string } | null => {+ let end = snapshot.getLoadable(store.runEndByIndex(index)).getValue();+ let fromParked = false;+ if (+ end != null &&+ end.conversationId != null &&+ end.conversationId !== activeConversationId+ ) {+ /**+ * `ask` is the MOUNTED view's sender — draining another+ * conversation's follow-up here would submit it into the wrong+ * chat. Park the signal under ITS conversation (freeing the shared+ * index slot so a later run cannot overwrite it) and drain when+ * the user returns. The armed interrupt flag travels WITH the+ * parked signal: leaving it on the index would let another run on+ * this pane consume it (or drain the wrong conversation).+ */+ const armedNow = snapshot.getLoadable(store.drainAfterAbortByIndex(index)).getValue();+ if (armedNow) {+ set(store.drainAfterAbortByIndex(index), false);+ }+ set(store.pendingRunEndByConvoId(end.conversationId), {+ ...end,+ ...(armedNow && { interruptArmed: true }),+ });+ set(store.runEndByIndex(index), null);+ end = null;+ }+ if (end == null && activeConversationId) {+ const parked = snapshot+ .getLoadable(store.pendingRunEndByConvoId(activeConversationId))+ .getValue();+ if (parked != null) {+ end = parked;+ fromParked = true;+ }+ }+ if (end == null) {+ return null;+ }+ // Consume the signal first — a hard double-fire guard even if the+ // effect re-runs before Recoil propagates.+ if (fromParked && activeConversationId) {+ set(store.pendingRunEndByConvoId(activeConversationId), null);+ } else {+ set(store.runEndByIndex(index), null);+ }++ const indexArmed = snapshot.getLoadable(store.drainAfterAbortByIndex(index)).getValue();+ if (indexArmed) {+ set(store.drainAfterAbortByIndex(index), false);+ }+ const interruptArmed = indexArmed || end.interruptArmed === true;++ const conversationId = end.conversationId;+ if (!conversationId) {+ return null;+ }++ const shouldMigrate =+ end.startedAsNewConvo === true && conversationId !== Constants.NEW_CONVO;+ const newConvoQueue = shouldMigrate+ ? snapshot.getLoadable(store.queuedMessagesByConvoId(Constants.NEW_CONVO)).getValue()+ : [];+ const ownQueue = snapshot+ .getLoadable(store.queuedMessagesByConvoId(conversationId))+ .getValue();+ const merged = [...newConvoQueue, ...ownQueue];++ const shouldDrain = end.outcome === 'completed' || interruptArmed;+ const next = shouldDrain ? (merged[0] ?? null) : null;+ const remainder = next ? merged.slice(1) : merged;++ if (shouldMigrate && newConvoQueue.length > 0) {+ set(store.queuedMessagesByConvoId(Constants.NEW_CONVO), []);+ }+ if (remainder.length !== ownQueue.length || shouldMigrate || next != null) {+ set(store.queuedMessagesByConvoId(conversationId), remainder);+ }+ return next ? { next, conversationId } : null;+ },+ [index, activeConversationId],+ );++ const restoreQueued = useRecoilCallback(+ ({ set }) =>+ (convoId: string, item: QueuedMessage) => {+ set(store.queuedMessagesByConvoId(convoId), (prev) =>+ prev.some((queued) => queued.id === item.id) ? prev : [item, ...prev],+ );+ },+ [],+ );++ useEffect(() => {+ if ((runEnd == null && parkedRunEnd == null) || isSubmitting) {+ return;+ }+ const drained = drainNext();+ if (drained == null) {+ return;+ }+ const { next, conversationId } = drained;+ // The queued item is the FULL submission context: explicit (possibly+ // empty) overrides stop `ask` from vacuuming up files, quotes, or skill+ // picks the user has staged in the composer for their NEXT message.+ const accepted = ask(+ { text: next.text },+ {+ overrideFiles: next.files ?? [],+ overrideQuotes: next.quotes ?? [],+ overrideManualSkills: next.manualSkills ?? [],+ },+ );+ if (accepted === false) {+ // `ask` refused without sending (e.g. the conversation history is not+ // in the query cache yet, right after navigating back). Restore the+ // item so the user's text is never silently dropped — the chip stays+ // available for manual send.+ restoreQueued(conversationId, next);+ }+ }, [runEnd, parkedRunEnd, isSubmitting, activeConversationId, drainNext, restoreQueued, ask]);+}diff --git a/client/src/hooks/Chat/useSteerConvert.ts b/client/src/hooks/Chat/useSteerConvert.tsnew file mode 100644index 0000000000..68a1a7901a--- /dev/null+++ b/client/src/hooks/Chat/useSteerConvert.ts@@ -0,0 +1,102 @@+import { useCallback } from 'react';+import { useRecoilCallback } from 'recoil';+import type { TPendingSteer } from 'librechat-data-provider';+import type { QueuedMessage } from '~/store/families';+import { appendAppliedSteerIds, carriedSteerContext } from '~/utils';+import { fetchStreamStatus } from '~/data-provider';+import store from '~/store';++interface SteerConvertOptions {+ /** Live-delivered terminal steers also have a parked server copy (the+ * terminal drain parks before knowing the final reached a subscriber);+ * set on final/abort/error surfaces to claim-and-clear it. */+ claimParked?: boolean;+ /** Server-side id the parked copy is keyed under when it differs from the+ * chip landing key (a `new`-held abort claims under the resolved job id). */+ claimConversationId?: string;+}++/**+ * Converts server-reported leftover steers into queued follow-up chips.+ * Converted ids join the applied set so a 202 ACK that lands after the run+ * ended drops its chip instead of re-minting a stranded `pending` one — the+ * set must survive run end for exactly that race, so it is capped, not+ * cleared. Safe to call from multiple delivery paths for the same steers+ * (final SSE event AND abort HTTP response): chip removal and queue+ * insertion both dedupe by steer id.+ *+ * `claimParked` fires ONE fire-and-forget /chat/status fetch per conversion+ * batch: its claim-on-read consumes the parked copy of steers just delivered+ * live, so a later reload cannot resurrect chips the user already dismissed.+ * Claimed steers re-run the same id-deduped conversion (no double-add).+ * Residual race: the claim no-ops if the job hasn't gone terminal by fetch+ * time — acceptable; the parked-copy TTL still bounds it.+ */+export default function useSteerConvert() {+ const convert = useRecoilCallback(+ ({ snapshot, set }) =>+ (conversationId: string, steers: TPendingSteer[]) => {+ if (steers.length === 0) {+ return;+ }+ // Quotes/skill picks never ride the server steer; restore them from+ // the local chip (matched by id) before the chips are dropped below.+ const localChips = snapshot+ .getLoadable(store.pendingSteersByConvoId(conversationId))+ .getValue();+ const chipById = new Map(localChips.map((chip) => [chip.steerId, chip]));+ const steerIds = new Set(steers.map((steer) => steer.steerId));+ set(store.appliedSteerIdsByConvoId(conversationId), (prev) =>+ appendAppliedSteerIds(+ prev,+ steers.map((steer) => steer.steerId),+ ),+ );+ set(store.pendingSteersByConvoId(conversationId), (prev) =>+ prev.filter((steer) => !steerIds.has(steer.steerId)),+ );+ set(store.queuedMessagesByConvoId(conversationId), (prev) => {+ const fresh = steers+ .filter((steer) => !prev.some((queued) => queued.id === steer.steerId))+ .map((steer) => ({+ id: steer.steerId,+ text: steer.text,+ createdAt: steer.createdAt ?? Date.now(),+ ...(steer.files && steer.files.length > 0 && { files: steer.files }),+ ...carriedSteerContext(chipById.get(steer.steerId)),+ }));+ if (fresh.length === 0) {+ return prev;+ }+ // Merge chronologically — a steer accepted BEFORE the user queued a+ // later follow-up must drain first — EXCEPT explicit front-inserts+ // ("Interrupt & send"), whose urgency outranks age.+ const merged: QueuedMessage[] = [...prev, ...fresh];+ return merged.sort(+ (a, b) =>+ Number(b.priority ?? false) - Number(a.priority ?? false) ||+ a.createdAt - b.createdAt,+ );+ });+ },+ [],+ );++ return useCallback(+ (conversationId: string, steers: TPendingSteer[], options?: SteerConvertOptions) => {+ convert(conversationId, steers);+ if (options?.claimParked !== true || steers.length === 0) {+ return;+ }+ fetchStreamStatus(options.claimConversationId ?? conversationId)+ .then((status) => {+ const unrecovered = status.unrecoveredSteers ?? [];+ if (unrecovered.length > 0) {+ convert(conversationId, unrecovered);+ }+ })+ .catch(() => undefined);+ },+ [convert],+ );+}diff --git a/client/src/hooks/Chat/useSteering.ts b/client/src/hooks/Chat/useSteering.tsnew file mode 100644index 0000000000..b319feb044--- /dev/null+++ b/client/src/hooks/Chat/useSteering.ts@@ -0,0 +1,650 @@+import { useCallback, useMemo, useRef } from 'react';+import { v4 } from 'uuid';+import { useToastContext } from '@librechat/client';+import { useRecoilValue, useSetRecoilState, useRecoilCallback } from 'recoil';+import { Constants, ContentTypes, isAssistantsEndpoint } from 'librechat-data-provider';+import type { TMessage, TConversation, TMessageContentParts } from 'librechat-data-provider';+import type { PendingSteer, QueuedMessage } from '~/store/families';+import type { ExtendedFile, FileSetter } from '~/common';+import {+ useGetMessagesByConvoId,+ useSteerMessageMutation,+ useMarkFilesUsageMutation,+} from '~/data-provider';+import { useSetFilesToDelete } from '~/hooks/Files';+import { carriedSteerContext } from '~/utils';+import useLocalize from '~/hooks/useLocalize';+import store from '~/store';++/** During-run submit routes: inject into the live run, or queue for after it. */+export type DuringRunAction = 'steer' | 'queue';++/** Composer state consumed into a queued item alongside the text. */+export interface QueuedMessageContext {+ quotes?: string[];+ manualSkills?: string[];+}++/** Server-side cap on a usage touch (mirrors `FILES_USAGE_MAX_IDS`). */+const QUEUE_USAGE_MAX_FILES = 10;++type SteerErrorCode =+ | 'NO_ACTIVE_RUN'+ | 'RUN_PAUSED'+ | 'STEER_QUEUE_FULL'+ | 'STEER_UNSUPPORTED'+ | string;++function getSteerErrorCode(error: unknown): SteerErrorCode | undefined {+ const response = (error as { response?: { data?: { code?: string } } } | undefined)?.response;+ return response?.data?.code;+}++/** True when the latest assistant message carries an unresolved tool approval —+ * the run is (or is about to be) paused, so a steer POST would 409. */+function hasLiveToolApproval(messages: TMessage[] | undefined): boolean {+ if (!messages || messages.length === 0) {+ return false;+ }+ for (let i = messages.length - 1; i >= 0; i--) {+ const message = messages[i];+ if (message.isCreatedByUser !== false) {+ continue;+ }+ const content = message.content;+ if (!Array.isArray(content)) {+ return false;+ }+ return content.some((part: TMessageContentParts | undefined) => {+ if (part?.type !== ContentTypes.TOOL_CALL) {+ return false;+ }+ const toolCall = part[ContentTypes.TOOL_CALL] as+ | { approval?: unknown; output?: string | null }+ | undefined;+ return toolCall?.approval != null && (toolCall.output?.length ?? 0) === 0;+ });+ }+ return false;+}++export interface UseSteeringParams {+ index: number;+ conversationId: string;+ conversation: TConversation | null;+ isSubmitting: boolean;+ answerModeActive: boolean;+ /** Composer attachments — consumed into queued items (steering is text-only). */+ files?: Map<string, ExtendedFile>;+ setFiles?: FileSetter;+ /** Uploads still in flight: during-run submits are held like the send button. */+ filesLoading?: boolean;+ /** Submits text (and optional attachments/quotes/skills) as a normal new+ * turn. Overrides are always explicit — a queued item is the FULL+ * submission context, so absent fields must send as empty, never vacuum+ * the composer. Returns `false` when `ask` refused without sending+ * (in-flight guard, history not cached yet) so callers can restore+ * instead of dropping. */+ sendNow: (+ text: string,+ files?: TMessage['files'],+ context?: QueuedMessageContext,+ ) => false | void;+ /** Stops the current generation (used by interrupt & send). */+ stopGenerating: () => void;+}++/**+ * The composer's during-run brain: decides what Enter does while a run is+ * generating (steer vs queue, per the user preference and run state), owns the+ * pending-steer / queued-message chip state, and implements the three actions+ * — steer (POST + optimistic chip), queue (client-side), and interrupt & send+ * (abort, then auto-send via the one-shot drain override).+ */+export default function useSteering({+ index,+ conversationId,+ conversation,+ isSubmitting,+ answerModeActive,+ files,+ setFiles,+ filesLoading = false,+ sendNow,+ stopGenerating,+}: UseSteeringParams) {+ const localize = useLocalize();+ const { showToast } = useToastContext();+ const setFilesToDelete = useSetFilesToDelete();+ const steerMutation = useSteerMessageMutation();+ const markFilesUsage = useMarkFilesUsageMutation();+ const defaultAction = useRecoilValue<DuringRunAction>(store.duringRunDefaultAction);+ const setDefaultAction = useSetRecoilState(store.duringRunDefaultAction);++ const endpoint = conversation?.endpointType ?? conversation?.endpoint;+ const steerable = !isAssistantsEndpoint(endpoint);+ const hasRealConvoId =+ conversationId != null && conversationId !== '' && conversationId !== Constants.NEW_CONVO;+ /** v1 gates the during-run UI to the primary composer, like the HITL popover. */+ const enabled = steerable && index === 0;+ const duringRunActive = enabled && isSubmitting && !answerModeActive;+ const queueKey = hasRealConvoId ? conversationId : Constants.NEW_CONVO;++ const { data: messages } = useGetMessagesByConvoId(hasRealConvoId ? conversationId : '', {+ enabled: hasRealConvoId,+ });+ const pausedOnApproval = useMemo(+ () => (duringRunActive ? hasLiveToolApproval(messages) : false),+ [duringRunActive, messages],+ );++ /** Whether a steer can reach the live run right now — independent of the+ * user's default action, so the per-send menu can always override to+ * steer when it's genuinely available. */+ const canSteer = hasRealConvoId && !pausedOnApproval;+ /** Steering needs a live server-side job; degrade to queue otherwise. */+ const effectiveAction: DuringRunAction = canSteer ? defaultAction : 'queue';++ /** Live submission state for POST callbacks — the closure value can be+ * stale by the time the steer response arrives. */+ const isSubmittingRef = useRef(isSubmitting);+ isSubmittingRef.current = isSubmitting;++ const upsertSteerChip = useRecoilCallback(+ ({ set }) =>+ (convoId: string, steer: PendingSteer) => {+ set(store.pendingSteersByConvoId(convoId), (prev) => {+ const existing = prev.findIndex((item) => item.steerId === steer.steerId);+ if (existing >= 0) {+ const next = [...prev];+ next[existing] = steer;+ return next;+ }+ return [...prev, steer];+ });+ },+ [],+ );++ const replaceSteerChip = useRecoilCallback(+ ({ set }) =>+ (convoId: string, localId: string, steer: PendingSteer | null) => {+ set(store.pendingSteersByConvoId(convoId), (prev) => {+ const next = prev.filter((item) => item.steerId !== localId);+ return steer ? [...next, steer] : next;+ });+ },+ [],+ );++ /**+ * Resolves the 202 ACK against the applied-id set: `on_steer_applied` rides+ * the SSE and can land BEFORE the HTTP response, in which case its removal+ * already passed — minting a `pending` chip here would strand it forever.+ * An ACK landing AFTER the run ended (final/abort/error already processed,+ * server queue drained or dropped) converts straight to a queued follow-up:+ * no later event will ever resolve a `pending` chip for a finished run.+ */+ const acknowledgeSteer = useRecoilCallback(+ ({ snapshot, set }) =>+ (convoId: string, localId: string, steer: PendingSteer) => {+ const applied = snapshot.getLoadable(store.appliedSteerIdsByConvoId(convoId)).getValue();+ const alreadyApplied = applied.includes(steer.steerId);+ const runOver = !isSubmittingRef.current;+ set(store.pendingSteersByConvoId(convoId), (prev) => {+ const next = prev.filter((item) => item.steerId !== localId);+ // Upsert: an SSE reconnect may have reseeded the chip under the+ // server id already — appending again would duplicate it.+ const alreadySeeded = next.some((item) => item.steerId === steer.steerId);+ return alreadyApplied || runOver || alreadySeeded ? next : [...next, steer];+ });+ if (alreadyApplied || !runOver) {+ return;+ }+ set(store.queuedMessagesByConvoId(convoId), (prev) =>+ prev.some((queued) => queued.id === steer.steerId)+ ? prev+ : [+ ...prev,+ {+ id: steer.steerId,+ text: steer.text,+ createdAt: steer.createdAt,+ ...(steer.files && steer.files.length > 0 && { files: steer.files }),+ ...carriedSteerContext(steer),+ },+ ],+ );+ },+ [],+ );++ /** Fire-and-forget TTL touch for uploads entering the client queue: a+ * queued message can outlive the upload window (long run, approval pause)+ * and send-time marking only happens at drain. Failure is tolerated —+ * the send-time marking remains the backstop. */+ const markQueuedFilesUsage = useCallback(+ (files?: TMessage['files']) => {+ if (files == null || files.length === 0) {+ return;+ }+ const file_ids: string[] = [];+ for (const file of files) {+ if (typeof file.file_id === 'string' && file.file_id.length > 0) {+ file_ids.push(file.file_id);+ }+ if (file_ids.length === QUEUE_USAGE_MAX_FILES) {+ break;+ }+ }+ if (file_ids.length > 0) {+ markFilesUsage.mutate({ file_ids });+ }+ },+ [markFilesUsage],+ );++ const enqueue = useRecoilCallback(+ ({ set }) =>+ (+ text: string,+ options?: {+ front?: boolean;+ files?: TMessage['files'];+ quotes?: string[];+ manualSkills?: string[];+ /** Set when the files were ALREADY queued/steered — their usage was+ * marked when they first entered the queue (or at the steer 202). */+ skipUsageMark?: boolean;+ },+ ) => {+ const trimmed = text.trim();+ if (trimmed.length === 0) {+ return;+ }+ const item = {+ id: v4(),+ text: trimmed,+ createdAt: Date.now(),+ ...(options?.files && options.files.length > 0 && { files: options.files }),+ ...(options?.quotes && options.quotes.length > 0 && { quotes: options.quotes }),+ ...(options?.manualSkills &&+ options.manualSkills.length > 0 && { manualSkills: options.manualSkills }),+ ...(options?.front && { priority: true }),+ };+ set(store.queuedMessagesByConvoId(queueKey), (prev) =>+ options?.front ? [item, ...prev] : [...prev, item],+ );+ if (options?.skipUsageMark !== true) {+ markQueuedFilesUsage(options?.files);+ }+ },+ [queueKey, markQueuedFilesUsage],+ );++ /** Consumes completed composer attachments into message file refs (clearing+ * the composer) so they pair with THIS queued message instead of gluing+ * onto whatever `ask` vacuums up next. */+ const takeComposerFiles = useCallback((): TMessage['files'] => {+ if (files == null || files.size === 0 || setFiles == null) {+ return undefined;+ }+ const taken = Array.from(files.values()).map((file) => ({+ file_id: file.file_id,+ filepath: file.filepath,+ type: file.type ?? '',+ height: file.height,+ width: file.width,+ // Retained beyond the submission shape so "Edit message" can restore+ // the attachment into the composer with its real name and size.+ filename: file.filename,+ bytes: file.size,+ }));+ setFiles(new Map());+ setFilesToDelete({});+ return taken;+ }, [files, setFiles, setFilesToDelete]);++ /** Consumes staged quote chips + manual skill picks (mirroring `ask()`'s+ * fresh-submit drain of the same atoms) so they pair with THIS queued+ * message instead of gluing onto whatever the user sends next. */+ const takeComposerContext = useRecoilCallback(+ ({ snapshot, reset }) =>+ (): QueuedMessageContext => {+ const quotes = snapshot+ .getLoadable(store.pendingQuotesByConvoId(conversationId))+ .getValue();+ const manualSkills = snapshot+ .getLoadable(store.pendingManualSkillsByConvoId(conversationId))+ .getValue();+ if (quotes.length > 0) {+ reset(store.pendingQuotesByConvoId(conversationId));+ }+ if (manualSkills.length > 0) {+ reset(store.pendingManualSkillsByConvoId(conversationId));+ }+ return {+ ...(quotes.length > 0 && { quotes }),+ ...(manualSkills.length > 0 && { manualSkills }),+ };+ },+ [conversationId],+ );++ const removeQueued = useRecoilCallback(+ ({ set }) =>+ (id: string) => {+ set(store.queuedMessagesByConvoId(queueKey), (prev) =>+ prev.filter((item) => item.id !== id),+ );+ },+ [queueKey],+ );++ /** Capture-then-remove, so a refused send can restore the ORIGINAL item. */+ const takeQueued = useRecoilCallback(+ ({ snapshot, set }) =>+ (id: string): QueuedMessage | undefined => {+ const queue = snapshot.getLoadable(store.queuedMessagesByConvoId(queueKey)).getValue();+ const taken = queue.find((item) => item.id === id);+ set(store.queuedMessagesByConvoId(queueKey), (prev) =>+ prev.filter((item) => item.id !== id),+ );+ return taken;+ },+ [queueKey],+ );++ /** Front restore mirroring useQueueDrain: same id, never duplicated. */+ const restoreQueued = useRecoilCallback(+ ({ set }) =>+ (item: QueuedMessage) => {+ set(store.queuedMessagesByConvoId(queueKey), (prev) =>+ prev.some((queued) => queued.id === item.id) ? prev : [item, ...prev],+ );+ },+ [queueKey],+ );++ const armDrainAfterAbort = useRecoilCallback(+ ({ set }) =>+ () => {+ set(store.drainAfterAbortByIndex(index), true);+ },+ [index],+ );++ /** POSTs a steer (text + files only; the server never carries quotes or+ * skill picks). `context` is the RESTORE payload for a queued-origin steer:+ * every degradation path threads it back into the requeue/send fallback so+ * the item's quotes and manual skills survive. Composer-origin steers pass+ * nothing, leaving their context staged in the composer atoms. */+ const submitSteer = useCallback(+ (text: string, steerFiles?: TMessage['files'], context?: QueuedMessageContext): boolean => {+ const trimmed = text.trim();+ if (trimmed.length === 0 || !hasRealConvoId) {+ return false;+ }+ const files = steerFiles && steerFiles.length > 0 ? steerFiles : undefined;+ /** Rides every chip state so a terminal conversion (late ACK, run-end+ * leftover report) can restore the queued item's full context. */+ const carried = carriedSteerContext(context);+ const localId = `local-${v4()}`;+ upsertSteerChip(conversationId, {+ steerId: localId,+ text: trimmed,+ status: 'sending',+ createdAt: Date.now(),+ ...(files && { files }),+ ...carried,+ });+ steerMutation.mutate(+ { conversationId, text: trimmed, ...(files && { files }) },+ {+ onSuccess: (response) => {+ acknowledgeSteer(conversationId, localId, {+ steerId: response.steerId,+ text: trimmed,+ status: 'pending',+ createdAt: Date.now(),+ ...(files && { files }),+ ...carried,+ });+ },+ onError: (error) => {+ const code = getSteerErrorCode(error);+ if (code === 'NO_ACTIVE_RUN') {+ // The run finished before the steer landed. While the final SSE+ // is still settling, `ask()`'s in-flight guard would drop a+ // direct send — queue it so the run-end drain fires it instead.+ // The explicit empty array stops `ask` from vacuuming composer+ // files staged for a DIFFERENT draft. A refused send (`false`)+ // falls back to the queue too — the chip is already gone, so+ // dropping the text here would lose it silently.+ replaceSteerChip(conversationId, localId, null);+ if (isSubmittingRef.current || sendNow(trimmed, files ?? [], context) === false) {+ enqueue(trimmed, { files, ...context });+ }+ return;+ }+ if (+ code === 'RUN_PAUSED' ||+ code === 'STEER_UNSUPPORTED' ||+ code === 'STEER_QUEUE_FULL'+ ) {+ replaceSteerChip(conversationId, localId, null);+ // The rejection can land AFTER the final SSE consumed the+ // run-end signal (common on an unsupported SDK near run end):+ // queueing then has nothing left to drain it, so mirror the+ // NO_ACTIVE_RUN fallback and send once submission settled —+ // queueing the refusal instead of dropping the text.+ if (!isSubmittingRef.current) {+ if (sendNow(trimmed, files ?? [], context) === false) {+ enqueue(trimmed, { files, ...context });+ }+ return;+ }+ enqueue(trimmed, { files, ...context });+ showToast({ message: localize('com_ui_steer_paused_queued'), status: 'info' });+ return;+ }+ upsertSteerChip(conversationId, {+ steerId: localId,+ text: trimmed,+ status: 'failed',+ createdAt: Date.now(),+ ...(files && { files }),+ ...carried,+ });+ },+ },+ );+ return true;+ },+ [+ hasRealConvoId,+ conversationId,+ upsertSteerChip,+ replaceSteerChip,+ acknowledgeSteer,+ steerMutation,+ sendNow,+ enqueue,+ showToast,+ localize,+ ],+ );++ /** Composer-originated steer: consumes the composer's attachments so they+ * ride the steer as one unit (the server re-fetches + encodes them at the+ * injection boundary). Files are taken only after the guards pass. */+ const steerFromComposer = useCallback(+ (text: string): boolean => {+ const trimmed = text.trim();+ if (trimmed.length === 0 || filesLoading || !hasRealConvoId) {+ return false;+ }+ return submitSteer(trimmed, takeComposerFiles());+ },+ [filesLoading, hasRealConvoId, takeComposerFiles, submitSteer],+ );++ /** Composer-originated queue: carries the composer's attachments, quote+ * chips, and manual skill picks as one unit. */+ const queueFromComposer = useCallback(+ (text: string): boolean => {+ const trimmed = text.trim();+ if (trimmed.length === 0 || filesLoading) {+ return false;+ }+ enqueue(trimmed, { files: takeComposerFiles(), ...takeComposerContext() });+ return true;+ },+ [filesLoading, enqueue, takeComposerFiles, takeComposerContext],+ );++ /** Retry a failed chip through the normal steer path. */+ const retrySteer = useCallback(+ (+ steerId: string,+ text: string,+ steerFiles?: TMessage['files'],+ context?: QueuedMessageContext,+ ) => {+ replaceSteerChip(conversationId, steerId, null);+ submitSteer(text, steerFiles, context);+ },+ [conversationId, replaceSteerChip, submitSteer],+ );++ const removeSteer = useCallback(+ (steerId: string) => {+ replaceSteerChip(conversationId, steerId, null);+ },+ [conversationId, replaceSteerChip],+ );++ /** Convert a failed/unsent steer chip into a queued follow-up. */+ const convertSteerToQueue = useCallback(+ (+ steerId: string,+ text: string,+ steerFiles?: TMessage['files'],+ context?: QueuedMessageContext,+ ) => {+ replaceSteerChip(conversationId, steerId, null);+ enqueue(text, { files: steerFiles, ...context });+ },+ [conversationId, replaceSteerChip, enqueue],+ );++ /** Chip action: send a queued message into the live run instead. Keys on+ * steer availability, not the default action — a queue-preferring user+ * clicking send-now explicitly asked to inject into the live run. The+ * item's attachments ride the steer; its quotes/skills travel as the+ * restore context so a degraded steer requeues/sends with them intact. */+ const sendQueuedNow = useCallback(+ (item: QueuedMessage) => {+ const taken = takeQueued(item.id) ?? item;+ if (duringRunActive && canSteer) {+ submitSteer(taken.text, taken.files, {+ quotes: taken.quotes,+ manualSkills: taken.manualSkills,+ });+ return;+ }+ if (!isSubmitting) {+ // Explicit (possibly empty) overrides: the queued item is the full+ // submission context, never the composer's staged files/quotes/picks.+ const accepted = sendNow(taken.text, taken.files ?? [], {+ quotes: taken.quotes,+ manualSkills: taken.manualSkills,+ });+ if (accepted === false) {+ // `ask` refused without sending — restore the chip so the user's+ // text is never silently dropped (mirrors useQueueDrain).+ restoreQueued(taken);+ }+ return;+ }+ // Files were already marked used when the item first entered the queue.+ enqueue(taken.text, {+ front: true,+ files: taken.files,+ quotes: taken.quotes,+ manualSkills: taken.manualSkills,+ skipUsageMark: true,+ });+ },+ [+ takeQueued,+ duringRunActive,+ canSteer,+ submitSteer,+ isSubmitting,+ sendNow,+ restoreQueued,+ enqueue,+ ],+ );++ /** Abort the current run and auto-send this text once the abort settles. */+ const interruptAndSend = useCallback(+ (text: string): boolean => {+ const trimmed = text.trim();+ if (trimmed.length === 0 || filesLoading) {+ return false;+ }+ enqueue(trimmed, { front: true, files: takeComposerFiles(), ...takeComposerContext() });+ armDrainAfterAbort();+ stopGenerating();+ return true;+ },+ [+ filesLoading,+ enqueue,+ takeComposerFiles,+ takeComposerContext,+ armDrainAfterAbort,+ stopGenerating,+ ],+ );++ /** Routes a during-run submit to the effective action. Returns true when consumed. */+ const submitDuringRun = useCallback(+ (text: string): boolean => {+ if (!duringRunActive) {+ return false;+ }+ if (effectiveAction === 'steer') {+ return steerFromComposer(text);+ }+ return queueFromComposer(text);+ },+ [duringRunActive, effectiveAction, steerFromComposer, queueFromComposer],+ );++ return {+ enabled,+ queueKey,+ canSteer,+ duringRunActive,+ effectiveAction,+ defaultAction,+ pausedOnApproval,+ setDefaultAction,+ submitDuringRun,+ steerFromComposer,+ queueFromComposer,+ submitSteer,+ retrySteer,+ removeSteer,+ convertSteerToQueue,+ enqueue,+ removeQueued,+ sendQueuedNow,+ interruptAndSend,+ };+}++export type SteeringControls = ReturnType<typeof useSteering>;diff --git a/client/src/hooks/Conversations/__tests__/format.test.ts b/client/src/hooks/Conversations/__tests__/format.test.tsindex a7b7ca4ff2..5f2dd75d15 100644--- a/client/src/hooks/Conversations/__tests__/format.test.ts+++ b/client/src/hooks/Conversations/__tests__/format.test.ts@@ -11,6 +11,7 @@ const translations: Record<string, string> = {com_ui_export_file_search: 'File Search',com_ui_export_image: 'Image',com_ui_export_retrieval: 'Retrieval',+ com_ui_export_steer: 'You (steered)',com_ui_export_summary: 'Summary',com_ui_export_tool: 'Tool',com_ui_export_video: 'Video',@@ -82,6 +83,11 @@ const contentByType: Record<ContentTypes, ExportableContentPart> = {type: ContentTypes.SUMMARY,content: [{ type: ContentTypes.TEXT, text: 'Summary text' }],},+ [ContentTypes.STEER]: {+ type: ContentTypes.STEER,+ steer: 'Focus on the tests',+ steerId: 'steer-1',+ },[ContentTypes.ERROR]: {type: ContentTypes.ERROR,error: 'Something failed',@@ -102,6 +108,7 @@ const expectedMarkdownByType: Record<ContentTypes, MessageContentExport> = {[ContentTypes.INPUT_AUDIO]: ['Audio', '{"data":"base64-audio","format":"wav"}'],[ContentTypes.AGENT_UPDATE]: ['Agent Update', '{"index":0,"runId":"run-1","agentId":"agent-1"}'],[ContentTypes.SUMMARY]: ['Summary', 'Summary text'],+ [ContentTypes.STEER]: ['You (steered)', 'Focus on the tests'],[ContentTypes.ERROR]: ['Assistant', 'Something failed'],};diff --git a/client/src/hooks/Conversations/format.ts b/client/src/hooks/Conversations/format.tsindex 0e872e5e87..be42392453 100644--- a/client/src/hooks/Conversations/format.ts+++ b/client/src/hooks/Conversations/format.ts@@ -34,6 +34,7 @@ export const handledExportContentTypes = [ContentTypes.INPUT_AUDIO,ContentTypes.AGENT_UPDATE,ContentTypes.SUMMARY,+ ContentTypes.STEER,ContentTypes.ERROR,] satisfies readonly ContentTypes[];@@ -55,6 +56,7 @@ const exportLabelKeys = {audio: 'com_ui_export_audio',video: 'com_ui_export_video',summary: 'com_ui_export_summary',+ steer: 'com_ui_export_steer',retrieval: 'com_ui_export_retrieval',fileSearch: 'com_ui_export_file_search',agentUpdate: 'com_ui_export_agent_update',@@ -188,6 +190,14 @@ export function formatMessageContent({return [localize(exportLabelKeys.summary), summary ?? stringify(content)];}+ if (content.type === ContentTypes.STEER) {+ const text = content.steer ?? '';+ if (text.trim().length === 0) {+ return [];+ }+ return [localize(exportLabelKeys.steer), text];+ }+return [sender, stringify(content)];}diff --git a/client/src/hooks/Input/useTextarea.ts b/client/src/hooks/Input/useTextarea.tsindex f48db60277..85043fa36e 100644--- a/client/src/hooks/Input/useTextarea.ts+++ b/client/src/hooks/Input/useTextarea.ts@@ -39,12 +39,19 @@ export default function useTextarea({setIsScrollable,disabled = false,placeholder,+ allowSubmitWhileGenerating = false,+ onDuringRunModifier,}: {textAreaRef: React.RefObject<HTMLTextAreaElement>;submitButtonRef: React.RefObject<HTMLButtonElement>;setIsScrollable: React.Dispatch<React.SetStateAction<boolean>>;disabled?: boolean;placeholder?: string;+ /** Lets Enter submit during a run (during-run steering/queuing routes it). */+ allowSubmitWhileGenerating?: boolean;+ /** During-run modifier chords: ⌘/Ctrl+Enter = the non-default action,+ * ⌥/Alt+Enter = interrupt & send. Enter itself submits the default. */+ onDuringRunModifier?: (kind: 'other' | 'interrupt') => void;}) {const localize = useLocalize();const getSender = useGetSender();@@ -181,7 +188,7 @@ export default function useTextarea({const scrollable = checkIfScrollable(textAreaRef.current);scrollable && setIsScrollable(scrollable);}- if (e.key === 'Enter' && isSubmitting) {+ if (e.key === 'Enter' && isSubmitting && !allowSubmitWhileGenerating) {return;}@@ -193,6 +200,28 @@ export default function useTextarea({// NOTE: isComposing and e.key behave differently in Safari compared to other browsers, forcing us to use e.keyCode insteadconst isComposingInput = isComposing.current || e.key === 'Process' || e.keyCode === 229;+ if (+ e.key === 'Enter' &&+ isSubmitting &&+ allowSubmitWhileGenerating &&+ onDuringRunModifier != null &&+ !isComposingInput+ ) {+ if (e.altKey) {+ e.preventDefault();+ onDuringRunModifier('interrupt');+ return;+ }+ // Only when plain Enter is the submit key — for Ctrl/Cmd+Enter+ // submitters (enterToSend off or a rebound chord) the chord must+ // keep meaning "submit the default action".+ if ((e.ctrlKey || e.metaKey) && enterToSend && submitOverride === undefined) {+ e.preventDefault();+ onDuringRunModifier('other');+ return;+ }+ }+const submitMessage = () => {const globalAudio = document.getElementById(globalAudioId) as HTMLAudioElement | undefined;if (globalAudio) {@@ -253,6 +282,8 @@ export default function useTextarea({},[isSubmitting,+ allowSubmitWhileGenerating,+ onDuringRunModifier,checkHealth,filesLoading,enterToSend,diff --git a/client/src/hooks/Messages/useSubmitMessage.ts b/client/src/hooks/Messages/useSubmitMessage.tsindex 7a683e80ad..b0e28c5718 100644--- a/client/src/hooks/Messages/useSubmitMessage.ts+++ b/client/src/hooks/Messages/useSubmitMessage.ts@@ -1,6 +1,7 @@import { useCallback } from 'react';import { useRecoilValue, useSetRecoilState } from 'recoil';import { replaceSpecialVars } from 'librechat-data-provider';+import type { TMessage } from 'librechat-data-provider';import { useChatContext, useChatFormContext, useAddedChatContext } from '~/Providers';import { useLatestMessage } from '~/hooks/Messages/useLatestMessage';import { useAuthContext } from '~/hooks/AuthContext';@@ -18,7 +19,12 @@ export default function useSubmitMessage() {const setActivePrompt = useSetRecoilState(store.activePromptByIndex(index));const submitMessage = useCallback(- (data?: { text: string }) => {+ (data?: {+ text: string;+ overrideFiles?: TMessage['files'];+ overrideQuotes?: string[];+ overrideManualSkills?: string[];+ }) => {if (!data) {return console.warn('No data provided to submitMessage');}@@ -36,6 +42,11 @@ export default function useSubmitMessage() {},{addedConvo: addedConvo ?? undefined,+ // Queued during-run messages carry their own consumed attachments,+ // quote chips, and manual skill picks (undefined = drain composer).+ overrideFiles: data.overrideFiles,+ overrideQuotes: data.overrideQuotes,+ overrideManualSkills: data.overrideManualSkills,},);if (submitted === false) {diff --git a/client/src/hooks/SSE/__tests__/useResumableSSE.spec.ts b/client/src/hooks/SSE/__tests__/useResumableSSE.spec.tsindex 3f0a37a803..73795d48ce 100644--- a/client/src/hooks/SSE/__tests__/useResumableSSE.spec.ts+++ b/client/src/hooks/SSE/__tests__/useResumableSSE.spec.ts@@ -58,10 +58,14 @@ const mockActiveRunAtom = { key: 'activeRun' };const mockAbortScrollAtom = { key: 'abortScroll' };const mockSubmissionAtom = { key: 'submission' };const mockShowStopButtonAtom = { key: 'showStopButton' };+const mockRunEndAtom = { key: 'runEnd' };+const mockPendingSteersAtom = { key: 'pendingSteers' };+const mockQueuedMessagesAtom = { key: 'queuedMessages' };const mockSetActiveRun = jest.fn();const mockSetAbortScroll = jest.fn();const mockSetSubmission = jest.fn();const mockSetShowStopButton = jest.fn();+const mockSetRunEnd = jest.fn();const mockUseSetRecoilStateMock = jest.fn((atom: unknown) => {if (atom === mockActiveRunAtom) {return mockSetActiveRun;@@ -75,6 +79,9 @@ const mockUseSetRecoilStateMock = jest.fn((atom: unknown) => {if (atom === mockShowStopButtonAtom) {return mockSetShowStopButton;}+ if (atom === mockRunEndAtom) {+ return mockSetRunEnd;+ }return jest.fn();});function mockUseSetRecoilState(atom: unknown) {@@ -89,6 +96,9 @@ jest.mock('@tanstack/react-query', () => ({jest.mock('recoil', () => ({...jest.requireActual('recoil'),useSetRecoilState: mockUseSetRecoilState,+ // The hook's steer-chip/queue callbacks need a RecoilRoot; these tests+ // render bare, so return inert callbacks (chip state is not under test here).+ useRecoilCallback: () => jest.fn(),}));jest.mock('~/store', () => ({@@ -98,6 +108,9 @@ jest.mock('~/store', () => ({abortScrollFamily: jest.fn(() => mockAbortScrollAtom),submissionByIndex: jest.fn(() => mockSubmissionAtom),showStopButtonByIndex: jest.fn(() => mockShowStopButtonAtom),+ runEndByIndex: jest.fn(() => mockRunEndAtom),+ pendingSteersByConvoId: jest.fn(() => mockPendingSteersAtom),+ queuedMessagesByConvoId: jest.fn(() => mockQueuedMessagesAtom),},}));@@ -105,11 +118,20 @@ jest.mock('~/hooks/AuthContext', () => ({useAuthContext: () => ({ token: 'test-token', isAuthenticated: true }),}));+const mockFetchStreamStatus = jest.fn();+const mockConvertSteersToQueued = jest.fn();+jest.mock('~/data-provider', () => ({useGetStartupConfig: () => ({ data: { balance: { enabled: false } } }),useGetUserBalance: () => ({ refetch: jest.fn() }),queueTitleGeneration: jest.fn(),streamStatusQueryKey: (conversationId: string) => ['streamStatus', conversationId],+ fetchStreamStatus: (conversationId: string) => mockFetchStreamStatus(conversationId),+}));++jest.mock('~/hooks/Chat/useSteerConvert', () => ({+ __esModule: true,+ default: () => mockConvertSteersToQueued,}));const mockErrorHandler = jest.fn();@@ -257,6 +279,10 @@ describe('useResumableSSE', () => {mockSetAbortScroll.mockClear();mockSetSubmission.mockClear();mockSetShowStopButton.mockClear();+ mockSetRunEnd.mockClear();+ mockConvertSteersToQueued.mockClear();+ mockFetchStreamStatus.mockReset();+ mockFetchStreamStatus.mockResolvedValue({ active: false });(request.post as jest.Mock).mockReset();(request.post as jest.Mock).mockResolvedValue({ streamId: 'stream-123' });});@@ -410,6 +436,55 @@ describe('useResumableSSE', () => {unmount();});+ it('claims parked steers and writes a non-completed run end on 404', async () => {+ const parked = [{ steerId: 'p1', text: 'parked words', createdAt: 1 }];+ mockFetchStreamStatus.mockResolvedValue({ active: false, unrecoveredSteers: parked });++ const { unmount } = await render404Scenario(CONV_ID);+ await act(async () => {+ await Promise.resolve();+ });++ expect(mockFetchStreamStatus).toHaveBeenCalledTimes(1);+ expect(mockFetchStreamStatus).toHaveBeenCalledWith(CONV_ID);+ expect(mockConvertSteersToQueued).toHaveBeenCalledWith(CONV_ID, parked);+ // The true outcome is unknown — the run-end signal must release parked+ // interrupt flags WITHOUT auto-sending queued messages.+ expect(mockSetRunEnd).toHaveBeenCalledWith(+ expect.objectContaining({ conversationId: CONV_ID, outcome: 'aborted' }),+ );+ expect(mockSetRunEnd).not.toHaveBeenCalledWith(+ expect.objectContaining({ outcome: 'completed' }),+ );+ unmount();+ });++ it('does not convert anything when the 404 status claim returns no parked steers', async () => {+ const { unmount } = await render404Scenario(CONV_ID);+ await act(async () => {+ await Promise.resolve();+ });++ expect(mockConvertSteersToQueued).not.toHaveBeenCalled();+ expect(mockSetRunEnd).toHaveBeenCalledWith(expect.objectContaining({ outcome: 'aborted' }));+ unmount();+ });++ it('still completes 404 cleanup when the status claim fails', async () => {+ mockFetchStreamStatus.mockRejectedValue(new Error('network down'));++ const { unmount } = await render404Scenario(CONV_ID);+ await act(async () => {+ await Promise.resolve();+ });++ expect(mockErrorHandler).not.toHaveBeenCalled();+ expect(mockConvertSteersToQueued).not.toHaveBeenCalled();+ expect(mockSetRunEnd).toHaveBeenCalledWith(expect.objectContaining({ outcome: 'aborted' }));+ expect(mockSetIsSubmitting).toHaveBeenCalledWith(false);+ unmount();+ });+it('seeds sidebar and message caches for a new conversation once the stream id is known', async () => {const submission = buildSubmission({conversation: {},diff --git a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsxindex 03a5a9b3d1..3f61f6f098 100644--- a/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx+++ b/client/src/hooks/SSE/__tests__/useResumeOnLoad.spec.tsx@@ -1,11 +1,10 @@import { RecoilRoot, useRecoilValue } from 'recoil';import { Constants } from 'librechat-data-provider';import { renderHook, act } from '@testing-library/react';-import type { TMessage, TConversation, TSubmission } from 'librechat-data-provider';import type { MutableSnapshot } from 'recoil';import type { ReactNode } from 'react';-+import type { PendingSteer, QueuedMessage } from '~/store/families';import useResumeOnLoad from '../useResumeOnLoad';import store from '~/store';@@ -69,6 +68,9 @@ function renderUseResumeOnLoad({onSubmission,siblingIndexParentId,onSiblingIndex,+ pendingSteers,+ onPendingSteers,+ onQueuedMessages,}: {messages?: TMessage[];getMessages?: () => TMessage[] | undefined;@@ -78,11 +80,17 @@ function renderUseResumeOnLoad({onSubmission?: (submission: TSubmission | null) => void;siblingIndexParentId?: string;onSiblingIndex?: (siblingIndex: number) => void;+ pendingSteers?: PendingSteer[];+ onPendingSteers?: (steers: PendingSteer[]) => void;+ onQueuedMessages?: (queued: QueuedMessage[]) => void;}) {const getMessages = jest.fn(getMessagesOverride ?? (() => messages));const initializeState = (snapshot: MutableSnapshot) => {snapshot.set(store.conversationByIndex(0), buildConversation(conversationId));snapshot.set(store.submissionByIndex(0), submission);+ if (pendingSteers) {+ snapshot.set(store.pendingSteersByConvoId(conversationId), pendingSteers);+ }};const SubmissionProbe = () => {@@ -90,6 +98,16 @@ function renderUseResumeOnLoad({onSubmission?.(currentSubmission);return null;};+ const PendingSteersProbe = () => {+ const steers = useRecoilValue(store.pendingSteersByConvoId(conversationId));+ onPendingSteers?.(steers);+ return null;+ };+ const QueuedMessagesProbe = () => {+ const queued = useRecoilValue(store.queuedMessagesByConvoId(conversationId));+ onQueuedMessages?.(queued);+ return null;+ };const SiblingIndexProbe = () => {const siblingIndex = useRecoilValue(store.messagesSiblingIdxFamily(siblingIndexParentId));if (siblingIndexParentId) {@@ -102,6 +120,8 @@ function renderUseResumeOnLoad({<RecoilRoot initializeState={initializeState}><SubmissionProbe /><SiblingIndexProbe />+ <PendingSteersProbe />+ <QueuedMessagesProbe />{children}</RecoilRoot>);@@ -433,4 +453,183 @@ describe('useResumeOnLoad', () => {expect(observedSiblingIndexes[observedSiblingIndexes.length - 1]).toBe(1);});++ describe('steer chip restore', () => {+ const staleChip: PendingSteer = {+ steerId: 'stale-1',+ text: 'applied while away',+ status: 'pending',+ createdAt: 1,+ };+ const failedChip: PendingSteer = {+ steerId: 'failed-1',+ text: 'recoverable words',+ status: 'failed',+ createdAt: 2,+ };++ function buildActiveStatus(pendingSteers?: Array<Record<string, unknown>>) {+ return {+ isSuccess: true,+ isFetching: false,+ data: {+ active: true,+ status: 'running',+ streamId: CONVERSATION_ID,+ resumeState: {+ runSteps: [],+ aggregatedContent: [],+ responseMessageId: RESPONSE_MESSAGE_ID,+ conversationId: CONVERSATION_ID,+ userMessage: {+ messageId: USER_MESSAGE_ID,+ parentMessageId: Constants.NO_PARENT,+ conversationId: CONVERSATION_ID,+ text: 'Hello',+ },+ ...(pendingSteers && { pendingSteers }),+ },+ },+ };+ }++ it('clears stale pending chips when the server reports no still-queued steers', async () => {+ const observedSteers: PendingSteer[][] = [];+ mockUseStreamStatus.mockReturnValue(buildActiveStatus());++ renderUseResumeOnLoad({+ messages: [buildUserMessage(CONVERSATION_ID)],+ pendingSteers: [staleChip, failedChip],+ onPendingSteers: (steers) => observedSteers.push(steers),+ });++ await act(async () => {+ await Promise.resolve();+ });++ // Only the failed chip survives — its text is client-local and recoverable.+ expect(observedSteers[observedSteers.length - 1]).toEqual([failedChip]);+ });++ it('restores still-queued steers (with files) and drops chips absent from the server list', async () => {+ const observedSteers: PendingSteer[][] = [];+ const files = [{ file_id: 'f1', filename: 'notes.pdf', type: 'application/pdf' }];+ mockUseStreamStatus.mockReturnValue(+ buildActiveStatus([{ steerId: 'queued-1', text: 'still queued', createdAt: 5, files }]),+ );++ renderUseResumeOnLoad({+ messages: [buildUserMessage(CONVERSATION_ID)],+ pendingSteers: [staleChip],+ onPendingSteers: (steers) => observedSteers.push(steers),+ });++ await act(async () => {+ await Promise.resolve();+ });++ expect(observedSteers[observedSteers.length - 1]).toEqual([+ { steerId: 'queued-1', text: 'still queued', status: 'pending', createdAt: 5, files },+ ]);+ });++ it('clears stale pending chips when the run finished while away (no active job)', async () => {+ const observedSteers: PendingSteer[][] = [];+ mockUseStreamStatus.mockReturnValue({+ isSuccess: true,+ isFetching: false,+ data: { active: false },+ });++ renderUseResumeOnLoad({+ messages: [buildUserMessage(CONVERSATION_ID)],+ pendingSteers: [staleChip, failedChip],+ onPendingSteers: (steers) => observedSteers.push(steers),+ });++ await act(async () => {+ await Promise.resolve();+ });++ expect(observedSteers[observedSteers.length - 1]).toEqual([failedChip]);+ });++ it('converts resumeState.pendingSteers to queued when inactive (expired action, unparked queue)', async () => {+ const observedSteers: PendingSteer[][] = [];+ const observedQueues: QueuedMessage[][] = [];+ mockUseStreamStatus.mockReturnValue({+ isSuccess: true,+ isFetching: false,+ data: {+ active: false,+ resumeState: {+ pendingSteers: [{ steerId: 'steer-unparked', text: 'still queued', createdAt: 5 }],+ },+ },+ });++ renderUseResumeOnLoad({+ messages: [buildUserMessage(CONVERSATION_ID)],+ // Local chip carries the client-only context the server list lacks.+ pendingSteers: [+ {+ steerId: 'steer-unparked',+ text: 'still queued',+ status: 'pending',+ createdAt: 5,+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ },+ ],+ onPendingSteers: (steers) => observedSteers.push(steers),+ onQueuedMessages: (queued) => observedQueues.push(queued),+ });++ await act(async () => {+ await Promise.resolve();+ });++ expect(observedQueues[observedQueues.length - 1]).toEqual([+ expect.objectContaining({+ id: 'steer-unparked',+ text: 'still queued',+ quotes: ['carried quote'],+ manualSkills: ['carried-skill'],+ }),+ ]);+ expect(observedSteers[observedSteers.length - 1]).toEqual([]);+ });++ it('dedupes unrecoveredSteers against resumeState.pendingSteers by steer id', async () => {+ const observedQueues: QueuedMessage[][] = [];+ mockUseStreamStatus.mockReturnValue({+ isSuccess: true,+ isFetching: false,+ data: {+ active: false,+ unrecoveredSteers: [{ steerId: 'steer-dup', text: 'delivered once', createdAt: 3 }],+ resumeState: {+ pendingSteers: [+ { steerId: 'steer-dup', text: 'delivered once', createdAt: 3 },+ { steerId: 'steer-extra', text: 'second words', createdAt: 4 },+ ],+ },+ },+ });++ renderUseResumeOnLoad({+ messages: [buildUserMessage(CONVERSATION_ID)],+ onQueuedMessages: (queued) => observedQueues.push(queued),+ });++ await act(async () => {+ await Promise.resolve();+ });++ expect(observedQueues[observedQueues.length - 1]).toEqual([+ expect.objectContaining({ id: 'steer-dup', text: 'delivered once' }),+ expect.objectContaining({ id: 'steer-extra', text: 'second words' }),+ ]);+ });+ });});diff --git a/client/src/hooks/SSE/useResumableSSE.ts b/client/src/hooks/SSE/useResumableSSE.tsindex 811907c77c..6891819454 100644--- a/client/src/hooks/SSE/useResumableSSE.ts+++ b/client/src/hooks/SSE/useResumableSSE.ts@@ -1,8 +1,8 @@import { useEffect, useState, useRef, useCallback } from 'react';import { v4 } from 'uuid';import { SSE } from 'sse.js';-import { useSetRecoilState } from 'recoil';import { useQueryClient } from '@tanstack/react-query';+import { useSetRecoilState, useRecoilCallback } from 'recoil';import {request,Constants,@@ -10,6 +10,7 @@ import {ErrorTypes,StepEvents,apiBaseUrl,+ SteerEvents,UsageEvents,createPayload,ApprovalEvents,@@ -22,7 +23,9 @@ import type {TPayload,TSubmission,TConversation,+ TPendingSteer,EventSubmission,+ TSteerAppliedEvent,} from 'librechat-data-provider';import type { EventHandlerParams } from './useEventHandlers';import type { ActiveJobsResponse } from '~/data-provider';@@ -30,7 +33,12 @@ import type { TResData } from '~/common';import {logger,clearAllDrafts,+ applySteerPart,applyPendingAction,+ carriedSteerContext,+ resolveRunEndTarget,+ findSteerMessageIndex,+ appendAppliedSteerIds,removeConvoFromAllQueries,upsertConvoInAllQueries,countTaggedApprovalParts,@@ -40,11 +48,13 @@ import {} from '~/utils';import {useGetUserBalance,+ fetchStreamStatus,useGetStartupConfig,queueTitleGeneration,streamStatusQueryKey,} from '~/data-provider';import useEventHandlers, { buildCreatedInitialResponse } from './useEventHandlers';+import useSteerConvert from '~/hooks/Chat/useSteerConvert';import { useAuthContext } from '~/hooks/AuthContext';import useUsageHandler from './useUsageHandler';import store from '~/store';@@ -525,6 +535,83 @@ export default function useResumableSSE(/** 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);+ /** Steer event whose target response message hasn't rendered yet — same+ * bounded next-frame retry as pending actions, on its own handle so the+ * two retries can't cancel each other. */+ const steerRetryRef = useRef<number | null>(null);++ /** Removes the pending chip once its steer is injected (the inline content+ * part becomes the durable record), and records the id so a 202 ACK that+ * arrives AFTER the applied event drops its chip instead of re-minting it. */+ const resolveSteerChip = useRecoilCallback(+ ({ set }) =>+ (conversationId: string, steerId: string) => {+ set(store.appliedSteerIdsByConvoId(conversationId), (prev) =>+ appendAppliedSteerIds(prev, [steerId]),+ );+ set(store.pendingSteersByConvoId(conversationId), (prev) =>+ prev.some((steer) => steer.steerId === steerId)+ ? prev.filter((steer) => steer.steerId !== steerId)+ : prev,+ );+ },+ [],+ );++ /** Replaces the chip list with the server's still-queued steers (reconnect).+ * Local `failed` entries are kept so their text stays recoverable, and a+ * reseeded chip keeps its client-only quotes/skill picks. */+ const seedSteerChips = useRecoilCallback(+ ({ set }) =>+ (conversationId: string, steers: TPendingSteer[]) => {+ set(store.pendingSteersByConvoId(conversationId), (prev) => {+ const chipById = new Map(prev.map((chip) => [chip.steerId, chip]));+ return [+ ...steers.map((steer) => ({+ steerId: steer.steerId,+ text: steer.text,+ status: 'pending' as const,+ createdAt: steer.createdAt ?? Date.now(),+ ...(steer.files && steer.files.length > 0 && { files: steer.files }),+ ...carriedSteerContext(chipById.get(steer.steerId)),+ })),+ ...prev.filter((steer) => steer.status === 'failed'),+ ];+ });+ },+ [],+ );++ /** Converts steers that never reached an injection boundary into queued+ * follow-up messages (reported on the run's final/abort event; the abort+ * HTTP response consumes the same data as a fallback in useChatHelpers). */+ const convertSteersToQueued = useSteerConvert();++ /** Error events carry no `pendingSteers` payload (the server drops its copy+ * on failure), but every acknowledged chip's text is local — convert them+ * to queued follow-ups so the user's words survive a failed run. `sending`+ * chips settle through their own POST callbacks (404 falls back to+ * queue/send) and `failed` chips keep their manual controls. */+ const convertLocalSteersToQueued = useRecoilCallback(+ ({ snapshot }) =>+ (conversationId: string, options?: { claimParked?: boolean }) => {+ const chips = snapshot.getLoadable(store.pendingSteersByConvoId(conversationId)).getValue();+ const settled = chips+ .filter((steer) => steer.status === 'pending')+ .map((steer) => ({+ steerId: steer.steerId,+ text: steer.text,+ createdAt: steer.createdAt,+ ...(steer.files && steer.files.length > 0 && { files: steer.files }),+ }));+ if (settled.length > 0) {+ convertSteersToQueued(conversationId, settled, options);+ }+ },+ [convertSteersToQueued],+ );++ const setRunEnd = useSetRecoilState(store.runEndByIndex(runIndex));const {stepHandler,@@ -640,6 +727,38 @@ export default function useResumableSSE(}};+ /**+ * Places an injected steer part on the in-flight response message and+ * resolves its pending chip. Same bounded next-frame retry as pending+ * actions for the inject-before-render race (the assistant placeholder+ * can land a few frames after the created event under load).+ */+ const applySteerToMessages = (event: TSteerAppliedEvent, attempt = 0) => {+ const retryNextFrame = () => {+ if (attempt < PENDING_ACTION_MAX_RETRY_FRAMES) {+ steerRetryRef.current = requestAnimationFrame(() =>+ applySteerToMessages(event, attempt + 1),+ );+ }+ };+ const messages = getMessages() ?? [];+ const index = findSteerMessageIndex(messages, event);+ if (index < 0) {+ retryNextFrame();+ return;+ }+ const updated = applySteerPart(messages[index], event);+ if (updated !== messages[index]) {+ const nextMessages = [...messages];+ nextMessages[index] = updated;+ setMessages(nextMessages);+ syncStepMessage(updated);+ }+ const chipConvoId =+ event.conversationId ?? currentSubmission.conversation?.conversationId ?? currentStreamId;+ resolveSteerChip(chipConvoId, event.steerId);+ };+const baseUrl = `${apiBaseUrl()}/api/agents/chat/stream/${encodeURIComponent(currentStreamId)}`;const url = isResume ? `${baseUrl}?resume=true` : baseUrl;logger.log('ResumableSSE', 'Subscribing to stream:', url, { isResume });@@ -679,6 +798,20 @@ export default function useResumableSSE(if (optimisticStreamIdsRef.current.has(currentStreamId)) {clearAllDrafts(Constants.NEW_CONVO);}+ const finalConvoId =+ data.conversation?.conversationId ??+ currentSubmission.conversation?.conversationId ??+ currentStreamId;+ // Steers the run never injected ride the final event; convert them+ // to queued follow-ups before the run-end signal fires the drain+ // (also resets the applied-id set for the finished run).+ // `claimParked` clears the parked server copy of the same steers so+ // a later reload can't resurrect chips dismissed after this batch.+ convertSteersToQueued(+ finalConvoId,+ Array.isArray(data.pendingSteers) ? (data.pendingSteers as TPendingSteer[]) : [],+ { claimParked: true },+ );try {finalHandler(data, currentSubmission as EventSubmission);finalizeUsage(data, { ...currentSubmission, userMessage });@@ -687,6 +820,28 @@ export default function useResumableSSE(setIsSubmitting(false);setShowStopButton(false);}+ // One-shot run-end signal for the queue drain. Written AFTER+ // finalHandler so `isSubmitting` has flipped false by the time the+ // drain effect observes it (both land in the same Recoil batch).+ // An early-aborted FIRST turn keys under NEW_CONVO: finalHandler+ // restored /c/new, so the optimistic id would strand the queue.+ const runEndTarget = resolveRunEndTarget({+ conversationId: finalConvoId,+ earlyAbort: data.earlyAbort === true,+ startedAsNewConvo: optimisticStreamIdsRef.current.has(currentStreamId),+ });+ setRunEnd({+ conversationId: runEndTarget.conversationId,+ // A Stop that lands before completion can arrive as a final with+ // `unfinished: true` and no `aborted` flag (request.js's+ // wasAbortedBeforeComplete branch) — it must not auto-drain.+ outcome:+ data.aborted === true || data.responseMessage?.unfinished === true+ ? 'aborted'+ : 'completed',+ startedAsNewConvo: runEndTarget.startedAsNewConvo,+ endedAt: Date.now(),+ });// Clear handler maps on stream completion to prevent memory leaksclearStepMaps();// Optimistically remove from active jobs@@ -757,6 +912,11 @@ export default function useResumableSSE(return;}+ if (data.event === SteerEvents.ON_STEER_APPLIED) {+ applySteerToMessages(data.data as TSteerAppliedEvent);+ return;+ }+if (data.event != null) {if (data.event === StepEvents.ON_MESSAGE_DELTA ||@@ -901,6 +1061,20 @@ export default function useResumableSSE(applyPendingActionToMessages(data.resumeState.pendingAction as Agents.PendingAction);}+ /**+ * Re-seed steer chips from the server's still-queued steers.+ * Injected steers are already inside `aggregatedContent`, so this+ * covers exactly the remainder a reloading client can't know about.+ */+ // Always reconcile against the server's still-queued list: a steer+ // applied while this client was disconnected is absent here (its+ // inline part rides aggregatedContent instead), so an EMPTY list+ // must clear stale local pending chips, not leave them stranded.+ seedSteerChips(+ currentSubmission.conversation?.conversationId ?? currentStreamId,+ (data.resumeState?.pendingSteers ?? []) as TPendingSteer[],+ );+if (data.resumeState?.titleEvent) {titleHandler(data.resumeState.titleEvent);}@@ -919,6 +1093,8 @@ export default function useResumableSSE(// 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 === SteerEvents.ON_STEER_APPLIED) {+ applySteerToMessages(replayEvent.data as TSteerAppliedEvent);} else if (replayEvent.event != null) {if (replayEvent.event === StepEvents.ON_MESSAGE_DELTA ||@@ -946,6 +1122,8 @@ export default function useResumableSSE(// 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 === SteerEvents.ON_STEER_APPLIED) {+ applySteerToMessages(pendingEvent.data as TSteerAppliedEvent);} else if (pendingEvent.event != null) {if (pendingEvent.event === StepEvents.ON_MESSAGE_DELTA ||@@ -1043,6 +1221,30 @@ export default function useResumableSSE(}setIsSubmitting(false);setShowStopButton(false);+ const recoveryConvoId = convoId ?? currentStreamId;+ // Terminal for this run: the job is gone, so no event will ever+ // resolve an acknowledged chip — convert them to queued chips.+ convertLocalSteersToQueued(recoveryConvoId);+ // A terminal drain may have parked steers no subscriber received —+ // the status route claims them exactly once (same recovery as+ // useResumeOnLoad). Best-effort: chips are already converted above.+ fetchStreamStatus(recoveryConvoId)+ .then((status) => {+ const unrecovered = status.unrecoveredSteers ?? [];+ if (unrecovered.length > 0) {+ convertSteersToQueued(recoveryConvoId, unrecovered);+ }+ })+ .catch(() => undefined);+ // The true outcome is unknown here (job record already cleaned up):+ // a non-'completed' outcome releases parked interrupt flags without+ // auto-sending queued messages the user may not want fired.+ setRunEnd({+ conversationId: recoveryConvoId,+ outcome: 'aborted',+ startedAsNewConvo: optimisticStreamIdsRef.current.has(currentStreamId),+ endedAt: Date.now(),+ });setStreamId(null);optimisticStreamIdsRef.current.delete(currentStreamId);createdStreamIdsRef.current.delete(currentStreamId);@@ -1125,6 +1327,17 @@ export default function useResumableSSE(setIsSubmitting(false);setShowStopButton(false);+ // The error terminal's backstop parks acked leftovers server-side;+ // claim it now so a reload can't resurrect the chips converted here.+ convertLocalSteersToQueued(+ currentSubmission.conversation?.conversationId ?? currentStreamId,+ { claimParked: true },+ );+ setRunEnd({+ conversationId: currentSubmission.conversation?.conversationId ?? currentStreamId,+ outcome: 'error',+ endedAt: Date.now(),+ });setStreamId(null);optimisticStreamIdsRef.current.delete(currentStreamId);createdStreamIdsRef.current.delete(currentStreamId);@@ -1178,6 +1391,15 @@ export default function useResumableSSE(}setIsSubmitting(false);setShowStopButton(false);+ convertLocalSteersToQueued(+ currentSubmission.conversation?.conversationId ?? currentStreamId,+ { claimParked: true },+ );+ setRunEnd({+ conversationId: currentSubmission.conversation?.conversationId ?? currentStreamId,+ outcome: 'error',+ endedAt: Date.now(),+ });setStreamId(null);optimisticStreamIdsRef.current.delete(currentStreamId);createdStreamIdsRef.current.delete(currentStreamId);@@ -1271,6 +1493,11 @@ export default function useResumableSSE(backfillUsage,resetLive,seedLive,+ setRunEnd,+ resolveSteerChip,+ seedSteerChips,+ convertSteersToQueued,+ convertLocalSteersToQueued,],);@@ -1468,6 +1695,10 @@ export default function useResumableSSE(cancelAnimationFrame(pendingActionRetryRef.current);pendingActionRetryRef.current = null;}+ if (steerRetryRef.current != null) {+ cancelAnimationFrame(steerRetryRef.current);+ steerRetryRef.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 abd7f748cf..131973ff21 100644--- a/client/src/hooks/SSE/useResumeOnLoad.ts+++ b/client/src/hooks/SSE/useResumeOnLoad.ts@@ -3,7 +3,13 @@ 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, applyPendingAction } from '~/utils';+import {+ dedupeSteersById,+ applyPendingAction,+ carriedSteerContext,+ getBranchSiblingIndexesForTarget,+} from '~/utils';+import useSteerConvert from '~/hooks/Chat/useSteerConvert';import { useStreamStatus } from '~/data-provider';import store from '~/store';@@ -225,6 +231,36 @@ export default function useResumeOnLoad([],);+ /** Restore pending-steer chips for steers the server still has queued+ * (injected ones already live inside the resumed aggregatedContent). */+ const convertSteersToQueued = useSteerConvert();++ const restoreSteerChips = useRecoilCallback(+ ({ set }) =>+ (activeConversationId: string, pendingSteers: Agents.ResumeState['pendingSteers']) => {+ // Always reconcile against the server's still-queued list (mirrors the+ // sync-path re-seed in useResumableSSE): a steer applied while this+ // client was away is absent here (its inline part rides+ // aggregatedContent instead), so an EMPTY list must clear stale local+ // pending chips, not leave them stranded beside the applied part.+ set(store.pendingSteersByConvoId(activeConversationId), (prev) => {+ const chipById = new Map(prev.map((chip) => [chip.steerId, chip]));+ return [+ ...(pendingSteers ?? []).map((steer) => ({+ steerId: steer.steerId,+ text: steer.text,+ status: 'pending' as const,+ createdAt: steer.createdAt ?? Date.now(),+ ...(steer.files && steer.files.length > 0 && { files: steer.files }),+ ...carriedSteerContext(chipById.get(steer.steerId)),+ })),+ ...prev.filter((steer) => steer.status === 'failed'),+ ];+ });+ },+ [],+ );+// Check for active stream when conversation changesconst submissionConvoId = currentSubmission?.conversation?.conversationId;const loadedMessages = messagesLoaded ? getMessages() : undefined;@@ -326,6 +362,23 @@ export default function useResumeOnLoad(if (!streamStatus.active || !streamStatus.streamId) {console.log('[ResumeOnLoad] No active job to resume for:', conversationId);+ // A terminal drain may have parked acknowledged steers no subscriber+ // received (tab closed / reload racing the final event) — the status+ // claim returns them exactly once; restore as queued follow-up chips.+ // An expired pendingAction can report inactive BEFORE the sweeper parks+ // the steer queue: those steers still ride resumeState.pendingSteers,+ // so convert both lists (id-deduped) before the empty seed clears chips.+ const leftoverSteers = dedupeSteersById(+ streamStatus.unrecoveredSteers,+ streamStatus.resumeState?.pendingSteers,+ );+ if (conversationId && leftoverSteers.length > 0) {+ convertSteersToQueued(conversationId, leftoverSteers);+ }+ // The run is terminal, so any remaining local pending chip is stale:+ // its steer either applied (inline part in the saved message) or rode+ // `unrecoveredSteers` above — same empty-list reconcile as the resume path.+ restoreSteerChips(conversationId, undefined);processedConvoRef.current = conversationId;return;}@@ -343,6 +396,7 @@ export default function useResumeOnLoad(// Build submission from resume state if availableif (streamStatus.resumeState) {restoreResumeBranch(streamStatus.resumeState, messages, conversationId);+ restoreSteerChips(conversationId, streamStatus.resumeState.pendingSteers);const submission = buildSubmissionFromResumeState(streamStatus.resumeState,streamStatus.streamId,@@ -386,6 +440,8 @@ export default function useResumeOnLoad(getMessages,setSubmission,restoreResumeBranch,+ restoreSteerChips,+ convertSteersToQueued,]);// Reset processedConvoRef when conversation changes to allow re-checkingdiff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.jsonindex ca7d59afb5..3a34eb2fde 100644--- a/client/src/locales/en/translation.json+++ b/client/src/locales/en/translation.json@@ -9,11 +9,11 @@"com_a11y_summarize_completed": "Context summarized.","com_a11y_summarize_failed": "Summarization failed, continuing with available context.","com_a11y_summarize_started": "Summarizing context.",- "com_agents_ask_user_info": "Lets the agent pause mid-run to ask you a clarifying question and wait for your answer.","com_agents_agent_card_label": "{{name}} agent. {{description}}","com_agents_all": "All Agents","com_agents_all_category": "All","com_agents_all_description": "Browse all shared agents across all categories",+ "com_agents_ask_user_info": "Lets the agent pause mid-run to ask you a clarifying question and wait for your answer.","com_agents_avatar_upload_error": "Failed to upload agent avatar","com_agents_category_aftersales": "After Sales","com_agents_category_aftersales_description": "Agents specialized in post-sale support, maintenance, and customer service",@@ -491,6 +491,9 @@"com_nav_delete_cache_storage": "Delete TTS cache storage","com_nav_delete_data_info": "All your data will be deleted.","com_nav_delete_warning": "WARNING: This will permanently delete your account.",+ "com_nav_during_run_action": "While generating, Enter will",+ "com_nav_during_run_action_queue": "Queue for after",+ "com_nav_during_run_action_steer": "Steer the response","com_nav_enable_cache_tts": "Enable cache TTS","com_nav_enable_cloud_browser_voice": "Use cloud-based voices","com_nav_engine": "Engine",@@ -889,6 +892,7 @@"com_ui_attach_error_type": "Unsupported file type for endpoint:","com_ui_attach_remove": "Remove file","com_ui_attach_warn_endpoint": "Non-Assistant files may be ignored without a compatible tool",+ "com_ui_attached_image": "Attached image","com_ui_attachment": "Attachment","com_ui_auth_apikey_desc": "Send a key or token with each request","com_ui_auth_format_hint": "This usually starts with \"{{0}}\"",@@ -1022,6 +1026,7 @@"com_ui_conversation_not_found": "Conversation not found","com_ui_conversation_summarized": "Conversation summarized","com_ui_conversations": "conversations",+ "com_ui_convert_to_queue": "Queue for after the response","com_ui_convo_archived": "Conversation archived","com_ui_convo_delete_error": "Failed to delete conversation","com_ui_convo_delete_success": "Conversation successfully deleted",@@ -1135,11 +1140,13 @@"com_ui_duplication_error": "There was an error duplicating the conversation","com_ui_duplication_processing": "Duplicating conversation...","com_ui_duplication_success": "Successfully duplicated conversation",+ "com_ui_during_run_actions": "More send options","com_ui_edit": "Edit","com_ui_edit_editing_image": "Editing image","com_ui_edit_mcp_server": "Edit MCP Server","com_ui_edit_mcp_server_dialog_description": "Unique Server Identifier: {{serverName}}","com_ui_edit_memory": "Edit Memory",+ "com_ui_edit_message": "Edit message","com_ui_edit_preset_title": "Edit Preset - {{title}}","com_ui_edit_prompt_page": "Edit Prompt Page","com_ui_edit_skill": "Edit Skill",@@ -1178,6 +1185,7 @@"com_ui_export_file_search": "File Search","com_ui_export_image": "Image","com_ui_export_retrieval": "Retrieval",+ "com_ui_export_steer": "You (steered)","com_ui_export_summary": "Summary","com_ui_export_tool": "Tool","com_ui_export_video": "Video",@@ -1281,6 +1289,7 @@"com_ui_include_shadcnui": "Include shadcn/ui components instructions","com_ui_input": "Input","com_ui_instructions": "Instructions",+ "com_ui_interrupt_send": "Interrupt & send","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",@@ -1376,12 +1385,12 @@"com_ui_mcp_url": "MCP Server URL","com_ui_medium": "Medium","com_ui_memories": "Memories",+ "com_ui_memories_all": "All memories","com_ui_memories_allow_create": "Allow creating Memories","com_ui_memories_allow_opt_out": "Allow users to opt out of Memories","com_ui_memories_allow_read": "Allow reading Memories","com_ui_memories_allow_update": "Allow updating Memories","com_ui_memories_allow_use": "Allow using Memories",- "com_ui_memories_all": "All memories","com_ui_memories_filter": "Filter memories...","com_ui_memories_partition_filter": "Filter memories by agent","com_ui_memories_personal": "Personal",@@ -1554,9 +1563,13 @@"com_ui_provider_api_keys_description": "Manage API keys for endpoints configured to use a user-provided key.","com_ui_provider_api_keys_not_set": "No key set","com_ui_quality": "Quality",+ "com_ui_question_unanswered": "No answer was given",+ "com_ui_queue": "Queue",+ "com_ui_queue_send": "Queue message for after the response",+ "com_ui_queued_attachment_count": "{{0}} attachments queued with this message",+ "com_ui_queued_messages": "Queued messages","com_ui_quote_selections": "{{0}} selections","com_ui_quotes_queued": "Quotes added for your next message",- "com_ui_question_unanswered": "No answer was given","com_ui_ran_n_agents": "Ran {{0}} agents","com_ui_read_aloud": "Read aloud","com_ui_read_file": "Read {{0}}",@@ -1593,6 +1606,7 @@"com_ui_remove_agent_from_chain": "Remove {{0}} from chain","com_ui_remove_all_quotes": "Remove all selections","com_ui_remove_from_project": "Remove from project",+ "com_ui_remove_queued": "Remove message","com_ui_remove_quote": "Remove quote","com_ui_remove_skill_var": "Remove {{0}}","com_ui_remove_user": "Remove {{0}}",@@ -1680,6 +1694,7 @@"com_ui_select_search_model": "Search model by name","com_ui_select_search_provider": "Search provider by name","com_ui_select_search_region": "Search region by name",+ "com_ui_send_now": "Send now","com_ui_set": "Set","com_ui_settings_label_2fa": "Two-factor authentication","com_ui_settings_label_agent_api_keys": "Agent API keys",@@ -1751,8 +1766,6 @@"com_ui_show_qr": "Show QR Code","com_ui_sign_in_to_domain": "Sign-in to {{0}}","com_ui_size": "Size",- "com_ui_skip": "Skip",- "com_ui_something_else": "Something else...","com_ui_size_sort": "Sort by Size","com_ui_skill": "Skill","com_ui_skill_content": "Skill Content",@@ -1827,6 +1840,8 @@"com_ui_skills_queued": "Skills queued for next submission","com_ui_skills_use_all": "Use all skills","com_ui_skills_use_all_hint": "The agent can use every skill available to you, including skills added in the future.",+ "com_ui_skip": "Skip",+ "com_ui_something_else": "Something else...","com_ui_sort_by": "Sort by","com_ui_sort_chats_by": "Sort chats by","com_ui_sort_created": "Created",@@ -1852,6 +1867,12 @@"com_ui_standard": "Standard","com_ui_stateful_sessions": "Stateful code sessions","com_ui_status_prefix": "Status:",+ "com_ui_steer": "Steer",+ "com_ui_steer_cancel": "Cancel steering message",+ "com_ui_steer_failed": "Steering failed",+ "com_ui_steer_paused_queued": "The agent is waiting for your review — your message was queued instead",+ "com_ui_steer_retry": "Retry steering",+ "com_ui_steer_send": "Steer the current response","com_ui_stop": "Stop","com_ui_storage": "Storage","com_ui_storage_filter_sort": "Filter and Sort by Storage",@@ -1948,6 +1969,8 @@"com_ui_travel": "Travel","com_ui_trust_app": "I trust this application","com_ui_try_adjusting_search": "Try adjusting your search terms",+ "com_ui_turn_on_queueing": "Turn on queueing",+ "com_ui_turn_on_steering": "Turn on steering","com_ui_ui_resource_error": "UI Resource Error ({{0}})","com_ui_ui_resource_not_found": "UI Resource not found (index: {{0}})","com_ui_unarchive": "Unarchive",@@ -2043,8 +2066,8 @@"com_ui_x_selected": "{{0}} selected","com_ui_xhigh": "Extra High","com_ui_yes": "Yes",- "com_ui_you_answered": "You answered:","com_ui_you": "You",+ "com_ui_you_answered": "You answered:","com_ui_your_answer": "Type your answer…","com_ui_your_api_key": "Your API Key","com_ui_your_projects": "Your projects",diff --git a/client/src/store/families.ts b/client/src/store/families.tsindex c4ad8221f5..5ae0e72565 100644--- a/client/src/store/families.ts+++ b/client/src/store/families.ts@@ -11,7 +11,13 @@ import {useSetRecoilState,useRecoilCallback,} from 'recoil';-import type { EModelEndpoint, TConversation, TSubmission, TPreset } from 'librechat-data-provider';+import type {+ EModelEndpoint,+ TConversation,+ TSubmission,+ TMessage,+ TPreset,+} from 'librechat-data-provider';import type { TOptionSettings, ExtendedFile } from '~/common';import {clearModelForNonEphemeralAgent,@@ -300,6 +306,124 @@ const pendingQuotesByConvoId = atomFamily<string[], string>({default: [],});+/**+ * A steer message submitted mid-run. Server truth: `sending` covers the POST+ * in flight, `pending` means the server queued it (awaiting a tool-batch+ * boundary), `failed` keeps the text recoverable after a rejected POST. The+ * chip disappears when `on_steer_applied` lands (the inline content part+ * becomes the durable record).+ */+export type PendingSteer = {+ steerId: string;+ text: string;+ status: 'sending' | 'pending' | 'failed';+ createdAt: number;+ /** Attachments steered with the message (refs; already uploaded). */+ files?: TMessage['files'];+ /** Quote chips carried by a queued-origin steer (client-only; never sent to+ * the server), restored onto the queued item if the run ends first. */+ quotes?: string[];+ /** Manual skill picks carried the same way as `quotes`. */+ manualSkills?: string[];+};++/**+ * Per-conversation steers awaiting injection. Reconciled against the server:+ * `on_steer_applied` removes its chip; `sync`/`resumeState.pendingSteers`+ * replaces the list on reconnect; run-end reports convert leftovers into+ * `queuedMessagesByConvoId` entries.+ */+const pendingSteersByConvoId = atomFamily<PendingSteer[], string>({+ key: 'pendingSteersByConvoId',+ default: [],+});++/** A message composed during a run, queued to send after it finishes.+ * Attachments ride the queued item (already uploaded at attach time) and are+ * passed to `ask` as `overrideFiles` on drain — steering itself is text-only,+ * so any during-run submit with media routes here as one unit. */+export type QueuedMessage = {+ id: string;+ text: string;+ createdAt: number;+ files?: TMessage['files'];+ /** Quote chips consumed from the composer at enqueue time; passed to `ask`+ * as `overrideQuotes` on drain so they pair with THIS message. */+ quotes?: string[];+ /** Manual skill picks consumed from the composer at enqueue time; passed+ * to `ask` as `overrideManualSkills` on drain. */+ manualSkills?: string[];+ /** Front-inserted by "Interrupt & send": stays ahead of chronologically+ * older items when leftover steers are merged back into the queue. */+ priority?: boolean;+};++/**+ * Per-conversation client-side queue of follow-up messages. Drained one per+ * run completion by `useQueueDrain` (each dequeued message starts a normal+ * turn whose own final event drains the next).+ */+const queuedMessagesByConvoId = atomFamily<QueuedMessage[], string>({+ key: 'queuedMessagesByConvoId',+ default: [],+});++/**+ * Run-end signals whose conversation was NOT active when they arrived —+ * parked here (keyed by conversation) so a later run finishing on the same+ * chat index cannot overwrite them; `useQueueDrain` consumes the parked+ * signal when the user returns to that conversation.+ */+const pendingRunEndByConvoId = atomFamily<RunEnd | null, string>({+ key: 'pendingRunEndByConvoId',+ default: null,+});++/**+ * One-shot run-termination signal written by the SSE final/error handlers and+ * consumed (reset to null) by `useQueueDrain`. Keyed by chat index like+ * `isSubmittingFamily`. Carrying the outcome lets the drain skip auto-send on+ * user aborts/errors while `startedAsNewConvo` migrates a queue keyed under+ * `Constants.NEW_CONVO` to the real conversation id.+ */+export type RunEnd = {+ conversationId: string | null;+ outcome: 'completed' | 'aborted' | 'error';+ startedAsNewConvo?: boolean;+ endedAt: number;+ /** Armed "Interrupt & send" flag traveling with a PARKED signal, so+ * another run on the same pane can neither consume nor clear it. */+ interruptArmed?: boolean;+};++const runEndByIndex = atomFamily<RunEnd | null, string | number>({+ key: 'runEndByIndex',+ default: null,+});++/**+ * One-shot override armed by "interrupt & send": the next `aborted` run-end+ * drains the queue exactly once (a plain Stop press leaves queued chips for+ * manual send).+ */+const drainAfterAbortByIndex = atomFamily<boolean, string | number>({+ key: 'drainAfterAbortByIndex',+ default: false,+});++/**+ * Server steer ids whose `on_steer_applied` event already landed. The 202 ACK+ * and the SSE ride different connections, so the applied event can arrive+ * FIRST — the ACK handler checks this set and drops its local chip instead of+ * minting a `pending` chip whose only removal event has already passed. A late+ * ACK can land after the run's final event, so the set is capped+ * (`appendAppliedSteerIds`), never cleared.+ */+const appliedSteerIdsByConvoId = atomFamily<string[], string>({+ key: 'appliedSteerIdsByConvoId',+ default: [],+});+const globalAudioURLFamily = atomFamily<string | null, string | number | null>({key: 'globalAudioURLByIndex',default: null,@@ -466,5 +590,11 @@ export default {showSkillsPopoverFamily,pendingManualSkillsByConvoId,pendingQuotesByConvoId,+ pendingSteersByConvoId,+ queuedMessagesByConvoId,+ runEndByIndex,+ pendingRunEndByConvoId,+ drainAfterAbortByIndex,+ appliedSteerIdsByConvoId,updateConversationSelector,};diff --git a/client/src/store/settings.ts b/client/src/store/settings.tsindex b0e2eef254..fbb0b37224 100644--- a/client/src/store/settings.ts+++ b/client/src/store/settings.ts@@ -1,7 +1,7 @@import { atom } from 'recoil';import { SettingsViews, LocalStorageKeys } from 'librechat-data-provider';-import { atomWithLocalStorage } from '~/store/utils';import type { TOptionSettings } from '~/common';+import { atomWithLocalStorage } from '~/store/utils';// Static atoms without localStorageconst staticAtoms = {@@ -30,6 +30,11 @@ const localStorageAtoms = {// Chat settingsenterToSend: atomWithLocalStorage('enterToSend', true),+ /** What Enter does while a run is generating: steer (inject mid-run) or queue (send after). */+ duringRunDefaultAction: atomWithLocalStorage<'steer' | 'queue'>(+ 'duringRunDefaultAction',+ 'steer',+ ),maximizeChatSpace: atomWithLocalStorage('maximizeChatSpace', false),chatDirection: atomWithLocalStorage('chatDirection', 'LTR'),autoExpandTools: atomWithLocalStorage(LocalStorageKeys.AUTO_EXPAND_TOOLS, false),diff --git a/client/src/utils/__tests__/steer.spec.ts b/client/src/utils/__tests__/steer.spec.tsnew file mode 100644index 0000000000..37c283d27d--- /dev/null+++ b/client/src/utils/__tests__/steer.spec.ts@@ -0,0 +1,190 @@+import { Constants, ContentTypes } from 'librechat-data-provider';+import type { TMessage, TSteerAppliedEvent } from 'librechat-data-provider';+import {+ getSteerPart,+ applySteerPart,+ resolveRunEndTarget,+ findSteerMessageIndex,+ appendAppliedSteerIds,+ resolveAbortSteerTarget,+} from '../steer';++const buildEvent = (overrides: Partial<TSteerAppliedEvent> = {}): TSteerAppliedEvent => ({+ steerId: 'steer-1',+ index: 2,+ part: {+ type: ContentTypes.STEER,+ [ContentTypes.STEER]: 'change course',+ steerId: 'steer-1',+ },+ ...overrides,+});++const assistantMessage = (overrides: Partial<TMessage> = {}): TMessage =>+ ({+ messageId: 'resp-1',+ conversationId: 'convo-1',+ isCreatedByUser: false,+ text: '',+ content: [+ { type: ContentTypes.TEXT, text: 'part 0' },+ { type: ContentTypes.TEXT, text: 'part 1' },+ ],+ ...overrides,+ }) as TMessage;++describe('applySteerPart', () => {+ it('places the part at its absolute index on a new message object', () => {+ const message = assistantMessage();+ const updated = applySteerPart(message, buildEvent());++ expect(updated).not.toBe(message);+ expect(updated.content).toHaveLength(3);+ expect(getSteerPart(updated.content?.[2])?.steer).toBe('change course');+ expect(message.content).toHaveLength(2);+ });++ it('writes by index even past the current end (holes preserved)', () => {+ const message = assistantMessage({ content: [{ type: ContentTypes.TEXT, text: 'only' }] });+ const updated = applySteerPart(message, buildEvent({ index: 3 }));++ expect(updated.content).toHaveLength(4);+ expect(getSteerPart(updated.content?.[3])?.steerId).toBe('steer-1');+ expect(updated.content?.[1]).toBeUndefined();+ });++ it('is idempotent for a replayed event (same reference back)', () => {+ const message = assistantMessage();+ const once = applySteerPart(message, buildEvent());+ const twice = applySteerPart(once, buildEvent());++ expect(twice).toBe(once);+ });++ it('handles a message without content', () => {+ const message = assistantMessage({ content: undefined });+ const updated = applySteerPart(message, buildEvent({ index: 0 }));++ expect(getSteerPart(updated.content?.[0])?.steer).toBe('change course');+ });++ it('ignores malformed events', () => {+ const message = assistantMessage();+ expect(applySteerPart(message, buildEvent({ index: -1 }))).toBe(message);+ expect(+ applySteerPart(message, { steerId: 's', index: 0 } as unknown as TSteerAppliedEvent),+ ).toBe(message);+ });+});++describe('findSteerMessageIndex', () => {+ const userMessage = {+ messageId: 'user-1',+ isCreatedByUser: true,+ } as TMessage;++ it('matches the exact assistant message by responseMessageId', () => {+ const messages = [userMessage, assistantMessage(), assistantMessage({ messageId: 'resp-2' })];+ expect(findSteerMessageIndex(messages, buildEvent({ responseMessageId: 'resp-2' }))).toBe(2);+ });++ it('returns -1 when the identified response has not rendered yet', () => {+ const messages = [userMessage, assistantMessage()];+ expect(findSteerMessageIndex(messages, buildEvent({ responseMessageId: 'resp-future' }))).toBe(+ -1,+ );+ });++ it('never matches a user message by id', () => {+ const messages = [userMessage];+ expect(findSteerMessageIndex(messages, buildEvent({ responseMessageId: 'user-1' }))).toBe(-1);+ });++ it('falls back to the last assistant message without an id', () => {+ const messages = [assistantMessage({ messageId: 'old' }), userMessage, assistantMessage()];+ expect(findSteerMessageIndex(messages, buildEvent())).toBe(2);+ });+});++describe('resolveRunEndTarget', () => {+ it('keys an early-aborted first turn under NEW_CONVO and drops the migration flag', () => {+ expect(+ resolveRunEndTarget({+ conversationId: 'optimistic-stream-id',+ earlyAbort: true,+ startedAsNewConvo: true,+ }),+ ).toEqual({ conversationId: String(Constants.NEW_CONVO), startedAsNewConvo: false });+ });++ it('keeps the real conversation id for an early abort of an existing conversation', () => {+ expect(+ resolveRunEndTarget({+ conversationId: 'convo-real',+ earlyAbort: true,+ startedAsNewConvo: false,+ }),+ ).toEqual({ conversationId: 'convo-real', startedAsNewConvo: false });+ });++ it('passes normal completions through untouched', () => {+ expect(+ resolveRunEndTarget({+ conversationId: 'convo-real',+ earlyAbort: false,+ startedAsNewConvo: true,+ }),+ ).toEqual({ conversationId: 'convo-real', startedAsNewConvo: true });+ });+});++describe('resolveAbortSteerTarget', () => {+ it('keeps chips under NEW_CONVO on a new-held first turn while claiming under the resolved id', () => {+ expect(+ resolveAbortSteerTarget({+ conversationId: String(Constants.NEW_CONVO),+ resolvedId: 'convo-resolved',+ }),+ ).toEqual({+ chipConvoId: String(Constants.NEW_CONVO),+ claimConvoId: 'convo-resolved',+ });+ });++ it('prefers the resolved id for both targets on an existing conversation', () => {+ expect(+ resolveAbortSteerTarget({ conversationId: 'convo-held', resolvedId: 'convo-resolved' }),+ ).toEqual({ chipConvoId: 'convo-resolved', claimConvoId: 'convo-resolved' });+ });++ it('falls back to the client-held id without a resolved id', () => {+ expect(resolveAbortSteerTarget({ conversationId: 'convo-held' })).toEqual({+ chipConvoId: 'convo-held',+ claimConvoId: 'convo-held',+ });+ expect(resolveAbortSteerTarget({ conversationId: String(Constants.NEW_CONVO) })).toEqual({+ chipConvoId: String(Constants.NEW_CONVO),+ claimConvoId: String(Constants.NEW_CONVO),+ });+ });+});++describe('appendAppliedSteerIds', () => {+ it('appends new ids and dedupes against the existing set', () => {+ expect(appendAppliedSteerIds(['a'], ['a', 'b', 'c'])).toEqual(['a', 'b', 'c']);+ });++ it('returns the same array reference when nothing new lands', () => {+ const prev = ['a', 'b'];+ expect(appendAppliedSteerIds(prev, ['a'])).toBe(prev);+ expect(appendAppliedSteerIds(prev, [])).toBe(prev);+ });++ it('caps the set at 100 ids, dropping the oldest', () => {+ const prev = Array.from({ length: 100 }, (_, i) => `id-${i}`);+ const next = appendAppliedSteerIds(prev, ['id-new']);+ expect(next).toHaveLength(100);+ expect(next[0]).toBe('id-1');+ expect(next[next.length - 1]).toBe('id-new');+ });+});diff --git a/client/src/utils/index.ts b/client/src/utils/index.tsindex 80454beab6..55734bf679 100644--- a/client/src/utils/index.ts+++ b/client/src/utils/index.ts@@ -39,6 +39,7 @@ export * from './groupToolCalls';export * from './toolLabels';export * from './favoritesError';export * from './approval';+export * from './steer';export * from './numbers';export { default as cn } from './cn';export { default as logger } from './logger';diff --git a/client/src/utils/steer.ts b/client/src/utils/steer.tsnew file mode 100644index 0000000000..8478195a1c--- /dev/null+++ b/client/src/utils/steer.ts@@ -0,0 +1,149 @@+import { Constants, ContentTypes } from 'librechat-data-provider';+import type {+ TMessage,+ TPendingSteer,+ TSteerAppliedEvent,+ TMessageContentParts,+} from 'librechat-data-provider';++type SteerPart = Extract<TMessageContentParts, { type: ContentTypes.STEER }>;++/** Returns the steer content part when `part` is one, else undefined. */+export function getSteerPart(part: TMessageContentParts | undefined): SteerPart | undefined {+ return part?.type === ContentTypes.STEER ? (part as SteerPart) : undefined;+}++/**+ * Places an injected steer part at its absolute content index on the target+ * response message. The server reserved that slot (subsequent SDK events were+ * emitted with already-shifted indices), so the write never collides with+ * streamed parts — the array is written by index, holes included, exactly like+ * the streaming content handler.+ *+ * Pure with a referential-stability contract shared with `applyPendingAction`:+ * returns the SAME message reference when the part is already present+ * (duplicate event replay), a new message otherwise.+ */+export function applySteerPart(message: TMessage, event: TSteerAppliedEvent): TMessage {+ const { index, part } = event;+ if (typeof index !== 'number' || index < 0 || part == null) {+ return message;+ }+ const content = Array.isArray(message.content) ? message.content : [];+ const existing = getSteerPart(content[index] as TMessageContentParts | undefined);+ if (existing != null && existing.steerId === part.steerId) {+ return message;+ }+ const nextContent = [...content] as TMessageContentParts[];+ nextContent[index] = part as TMessageContentParts;+ return { ...message, content: nextContent };+}++/**+ * Conversation key for the run-end queue signal. An early-aborted FIRST turn+ * has no server-side conversation (the client restores /c/new), so keying the+ * signal by the optimistic stream id would park queued follow-ups under an id+ * the user never sees again — key under NEW_CONVO (and drop the migration+ * flag) so `useQueueDrain` leaves the queue on the new-chat composer.+ */+export function resolveRunEndTarget(params: {+ conversationId: string;+ earlyAbort: boolean;+ startedAsNewConvo: boolean;+}): { conversationId: string; startedAsNewConvo: boolean } {+ const { conversationId, earlyAbort, startedAsNewConvo } = params;+ if (earlyAbort && startedAsNewConvo) {+ return { conversationId: String(Constants.NEW_CONVO), startedAsNewConvo: false };+ }+ return { conversationId, startedAsNewConvo };+}++/**+ * Targets for consuming an abort HTTP response's leftover steers. The server+ * echoes the RESOLVED job id (`aborted`), which is authoritative when the+ * client still holds the `new` placeholder on a just-started first turn.+ * Chips and the interrupt-drain signal land where the mounted composer's+ * queue/drain machinery looks: a `new`-held turn hasn't navigated, so they+ * stay keyed under NEW_CONVO (same rule as `resolveRunEndTarget`'s early-abort+ * case), while the parked-copy claim uses the resolved id the server keyed+ * the parked steers under.+ */+export function resolveAbortSteerTarget(params: { conversationId: string; resolvedId?: string }): {+ chipConvoId: string;+ claimConvoId: string;+} {+ const { conversationId, resolvedId } = params;+ const claimConvoId = resolvedId ?? conversationId;+ const chipConvoId =+ conversationId === String(Constants.NEW_CONVO) ? conversationId : claimConvoId;+ return { chipConvoId, claimConvoId };+}++/** Bounds the per-conversation applied-steer id set. A late 202 ACK can land+ * after the run's final event, so the set is capped rather than cleared. */+const APPLIED_STEER_IDS_CAP = 100;++/**+ * Appends steer ids to an applied-id set, deduped and capped. Returns the+ * same array when nothing new lands so Recoil writers keep referential+ * stability.+ */+export function appendAppliedSteerIds(prev: string[], steerIds: string[]): string[] {+ const fresh = steerIds.filter((id) => !prev.includes(id));+ if (fresh.length === 0) {+ return prev;+ }+ return [...prev, ...fresh].slice(-APPLIED_STEER_IDS_CAP);+}++type SteerCarriedContext = { quotes?: string[]; manualSkills?: string[] };++/** Quotes/skill picks are client-only (a steer never sends them to the+ * server); chip mints, reseeds, and queued conversions carry them from the+ * local source so the context survives a steer that never injects. */+export function carriedSteerContext(source?: SteerCarriedContext): SteerCarriedContext {+ const quotes = source?.quotes;+ const manualSkills = source?.manualSkills;+ return {+ ...(quotes && quotes.length > 0 && { quotes }),+ ...(manualSkills && manualSkills.length > 0 && { manualSkills }),+ };+}++/** Merges steer lists into one id-deduped conversion batch (first wins). */+export function dedupeSteersById(...lists: Array<TPendingSteer[] | undefined>): TPendingSteer[] {+ const seen = new Set<string>();+ const merged: TPendingSteer[] = [];+ for (const list of lists) {+ for (const steer of list ?? []) {+ if (seen.has(steer.steerId)) {+ continue;+ }+ seen.add(steer.steerId);+ merged.push(steer);+ }+ }+ return merged;+}++/**+ * Resolves the assistant response message a steer event targets. Exact-id+ * assistant match when `responseMessageId` is present (a miss returns -1 so+ * the caller retries next frame — same rationale as+ * `findPendingActionMessageIndex`); best-effort last assistant otherwise.+ */+export function findSteerMessageIndex(messages: TMessage[], event: TSteerAppliedEvent): number {+ const isAssistant = (message: TMessage | undefined) => message?.isCreatedByUser === false;+ const { responseMessageId } = event;+ if (responseMessageId) {+ return messages.findIndex(+ (message) => message.messageId === responseMessageId && isAssistant(message),+ );+ }+ for (let i = messages.length - 1; i >= 0; i--) {+ if (isAssistant(messages[i])) {+ return i;+ }+ }+ return -1;+}diff --git a/e2e/setup/fake-model.js b/e2e/setup/fake-model.jsindex 5c0f6b0b66..f008c79baf 100644--- a/e2e/setup/fake-model.js+++ b/e2e/setup/fake-model.js@@ -26,6 +26,7 @@ const REPLY_MARKER = 'E2E_REPLY:';const COUNTED_REPLY_MARKER = 'E2E_COUNTED_REPLY:';const SLOW_REPLY_MARKER = 'E2E_SLOW_REPLY:';const SLOW_COUNTED_REPLY_MARKER = 'E2E_SLOW_COUNTED_REPLY:';+const STEER_TOOL_REPLY_MARKER = 'E2E_STEER_TOOL_REPLY:';const RESUME_ICON_REPLY_MARKER = 'E2E_RESUME_ICON_REPLY:';const FORCED_ERROR_MARKER = 'E2E_FORCED_ERROR:';const MARKDOWN_REPLY_MARKER = 'E2E_MARKDOWN_REPLY';@@ -37,6 +38,8 @@ const MODEL_SPEC_SKILL_ASSERTION_FINAL_TEXT = 'E2E model spec skill assertion paconst PROVIDER_FILE_ASSERTION_FINAL_TEXT = 'E2E provider file assertion passed';const AGENT_CONTEXT_ASSERTION_FINAL_TEXT = 'E2E agent context assertion passed';const QUOTE_ASSERTION_FINAL_TEXT = 'E2E quote assertion passed';+const STEER_TOOL_FINAL_TEXT = 'E2E steer tool reply done';+const STEER_TOOL_NAME_PREFIX = 'remember_fact';const SLOW_CHUNK_DELAY_MS = Number(process.env.MOCK_LLM_SLOW_CHUNK_DELAY_MS) || 35;const SLOW_REPLY_CHUNKS = 160;const RESUME_ICON_CHUNK_DELAY_MS = Number(process.env.MOCK_LLM_RESUME_ICON_CHUNK_DELAY_MS) || 60;@@ -599,6 +602,38 @@ function fileAuthoringResponses(operation, toolNames) {};}+/**+ * Slow two-turn run with a real MCP tool boundary for the steering e2e: turn 1+ * streams a slow preamble then calls the advertised `remember_fact` MCP tool+ * (steers drain at the PostToolBatch boundary), turn 2 streams the final text.+ */+function steerToolReplyResponses(label, toolNames) {+ const toolName = Array.from(toolNames).find((name) => name.startsWith(STEER_TOOL_NAME_PREFIX));+ if (!toolName) {+ return {+ responses: [+ `E2E steer tool reply unavailable: no ${STEER_TOOL_NAME_PREFIX} tool advertised.`,+ ],+ };+ }+ const chunks = Array.from(+ { length: SLOW_REPLY_CHUNKS },+ (_, index) => `chunk-${String(index).padStart(3, '0')}`,+ ).join(' ');+ return {+ responses: [`E2E steer tool preamble ${label} ${chunks}`, `${STEER_TOOL_FINAL_TEXT} ${label}`],+ sleep: SLOW_CHUNK_DELAY_MS,+ toolCalls: [+ {+ id: `call_e2e_steer_${label}`,+ name: toolName,+ args: { fact: `steer boundary ${label}` },+ type: 'tool_call',+ },+ ],+ };+}+function findLastToolMessageText(messages, requiredToken) {for (let index = (messages ?? []).length - 1; index >= 0; index--) {const message = messages[index];@@ -711,6 +746,11 @@ function resolveResponses({ agents, messages, text, toolNames }) {return reply;}+ const steerToolLabel = getMarkerValue(text, STEER_TOOL_REPLY_MARKER);+ if (steerToolLabel) {+ return steerToolReplyResponses(steerToolLabel, toolNames);+ }+if (text.includes(ASSERT_AGENT_CONTEXT_MARKER)) {return {responses: [MOCK_REPLY],diff --git a/e2e/specs/mock/steering.spec.ts b/e2e/specs/mock/steering.spec.tsnew file mode 100644index 0000000000..6dd8395a08--- /dev/null+++ b/e2e/specs/mock/steering.spec.ts@@ -0,0 +1,199 @@+import { expect, test } from '@playwright/test';+import type { Page, Response } from '@playwright/test';+import {+ MOCK_ENDPOINTS,+ MOCK_REPLY_TEXT,+ NEW_CHAT_PATH,+ messagesView,+ replyPrompt,+ replyText,+ selectMockEndpoint,+ sendMessage,+} from './helpers';++/** Non-spec endpoint from e2e/config/librechat.e2e.yaml — the ephemeral MCP+ * selection rides the no-spec path, mirroring mcp-ephemeral.spec.ts. */+const PROVIDER_C = { label: 'Mock Provider C', model: 'mock-model-c' };+const MCP_SERVER_TITLE = 'E2E Memory';+/** Last chunk streamed by the fake model's slow replies (160 chunks, 0-indexed). */+const SLOW_REPLY_LAST_CHUNK = 'chunk-159';++const uniqueLabel = (prefix: string) =>+ `${prefix}-${Date.now()}-${Math.floor(Math.random() * 1e4)}`;++const messageInput = (page: Page) => page.getByRole('textbox', { name: 'Message input' });+const duringRunSendButton = (page: Page) => page.getByTestId('during-run-send-button');+const queuedRows = (page: Page) => page.getByTestId('queued-message-row');+const messageTurns = (page: Page) => messagesView(page).locator('.message-render');+const pendingSteerParts = (page: Page) =>+ messagesView(page).locator('[data-testid="steer-part"][data-steer-pending="true"]');+const appliedSteerParts = (page: Page) =>+ messagesView(page).locator('[data-testid="steer-part"]:not([data-steer-pending])');++function isSteerRequest(response: Response) {+ return (+ response.request().method() === 'POST' &&+ new URL(response.url()).pathname === '/api/agents/chat/steer'+ );+}++/** Select the MCP server from the composer's ephemeral MCP dropdown. */+async function selectEphemeralMCP(page: Page) {+ await page.getByRole('button', { name: 'MCP Servers', exact: true }).click();+ const serverItem = page.getByRole('menuitemcheckbox', { name: new RegExp(MCP_SERVER_TITLE) });+ await expect(serverItem).toBeVisible();+ await serverItem.click();+ await expect(serverItem).toHaveAttribute('aria-checked', 'true');+ await page.keyboard.press('Escape');+ await expect(page.getByRole('button', { name: new RegExp(MCP_SERVER_TITLE) })).toBeVisible();+}++/** Establish a real conversation with a fast first turn so during-run actions+ * target a persisted conversation id instead of racing new-convo creation. */+async function establishConversation(page: Page, label: string) {+ const setup = await sendMessage(page, replyPrompt(label));+ expect(setup.ok()).toBeTruthy();+ await expect(messagesView(page).getByText(replyText(label))).toBeVisible({ timeout: 30000 });+ await expect(page).toHaveURL(/\/c\/[0-9a-fA-F-]{36}$/, { timeout: 15000 });+}++/** Fill the composer mid-run: the during-run send button must take the+ * send/stop slot (it becomes the form submit target for Enter). */+async function typeDuringRun(page: Page, text: string) {+ const input = messageInput(page);+ await input.click();+ await input.fill(text);+ await expect(duringRunSendButton(page)).toBeVisible({ timeout: 5000 });+}++test.describe('mid-run steering and queuing', () => {+ /**+ * The applied-steer contract (requires @librechat/agents ≥ 3.2.63, where+ * top-level `PostToolBatch` hook inputs carry no subagent-scope `agentId`):+ * a steer submitted mid-run appears in-thread immediately as an optimistic+ * user message, is injected at the next tool-batch boundary — the pending+ * marker drops as `on_steer_applied` swaps in the persisted part — and+ * SURVIVES inside the response after run end, with no degradation to a+ * queued follow-up turn.+ */+ test('steers mid-run: pending part appears immediately and applies at the next tool boundary', async ({+ page,+ }) => {+ test.setTimeout(150000);+ const label = uniqueLabel('steer');+ const steerText = `Steer injection ${label}`;++ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });+ await selectMockEndpoint(page, PROVIDER_C);+ await selectEphemeralMCP(page);+ await establishConversation(page, `steer-setup-${label}`);++ // Slow tool run: turn 1 streams a ~11s preamble, then calls the MCP+ // fixture tool (the PostToolBatch boundary), turn 2 streams final text.+ const run = await sendMessage(page, `E2E_STEER_TOOL_REPLY:${label}`);+ expect(run.ok()).toBeTruthy();++ await typeDuringRun(page, steerText);+ await expect(duringRunSendButton(page)).toHaveAttribute('data-during-run-action', 'steer');++ const [steerResponse] = await Promise.all([+ page.waitForResponse(isSteerRequest, { timeout: 15000 }),+ messageInput(page).press('Enter'),+ ]);+ expect(steerResponse.status()).toBe(202);++ // The steer shows in-thread immediately as an optimistic user-style part.+ await expect(pendingSteerParts(page).filter({ hasText: steerText })).toHaveCount(1, {+ timeout: 10000,+ });++ // Injected at the tool-batch boundary: the optimistic entry becomes the+ // persisted part (pending marker drops) while the run is still going.+ await expect(appliedSteerParts(page).filter({ hasText: steerText })).toHaveCount(1, {+ timeout: 60000,+ });+ await expect(messagesView(page).getByRole('button', { name: /remember_fact/ })).toBeVisible({+ timeout: 60000,+ });+ await expect(messagesView(page).getByText(`E2E steer tool reply done ${label}`)).toBeVisible({+ timeout: 60000,+ });++ // The steer stays INSIDE the response after run end — a user message at+ // its injection point, not a queued follow-up turn (4 turns: the setup+ // pair plus this pair).+ await expect(messageTurns(page)).toHaveCount(4);+ await expect(pendingSteerParts(page)).toHaveCount(0);+ await expect(appliedSteerParts(page).filter({ hasText: steerText })).toHaveCount(1);+ await expect(queuedRows(page)).toHaveCount(0);+ });++ test('queues with Cmd/Ctrl+Enter during a run and auto-sends after clean completion', async ({+ page,+ }) => {+ test.setTimeout(120000);+ const label = uniqueLabel('queue');+ const queueText = `Queued follow-up ${label}`;++ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);+ await establishConversation(page, `queue-setup-${label}`);++ const run = await sendMessage(page, `E2E_SLOW_REPLY:${label}`);+ expect(run.ok()).toBeTruthy();++ await typeDuringRun(page, queueText);+ await messageInput(page).press('ControlOrMeta+Enter');++ const row = queuedRows(page).filter({ hasText: queueText });+ await expect(row).toBeVisible({ timeout: 10000 });+ // Queued means NOT injected into the live thread.+ await expect(pendingSteerParts(page)).toHaveCount(0);++ // Clean completion drains exactly one queued message as a new user turn.+ await expect(row).toHaveCount(0, { timeout: 60000 });+ await expect(messageTurns(page)).toHaveCount(6, { timeout: 30000 });+ const queuedTurn = messageTurns(page).nth(4);+ await expect(queuedTurn).toContainText(queueText);+ await expect(queuedTurn.locator('.user-turn')).toBeVisible();+ const followupReply = messageTurns(page).nth(5);+ await expect(followupReply).toContainText(MOCK_REPLY_TEXT, { timeout: 30000 });+ await expect(followupReply.locator('.agent-turn')).toBeVisible();+ });++ test('interrupt & send (Alt+Enter) stops the run and auto-sends the text as the next turn', async ({+ page,+ }) => {+ test.setTimeout(120000);+ const label = uniqueLabel('interrupt');+ const interruptText = `Interrupt follow-up ${label}`;++ await page.goto(NEW_CHAT_PATH, { timeout: 10000 });+ await selectMockEndpoint(page, MOCK_ENDPOINTS[0]);+ await establishConversation(page, `interrupt-setup-${label}`);++ const run = await sendMessage(page, `E2E_SLOW_REPLY:${label}`);+ expect(run.ok()).toBeTruthy();+ // Let the response visibly stream before interrupting (real-user timing;+ // also proves the run was genuinely mid-generation when stopped).+ await expect(messagesView(page).getByText('chunk-010')).toBeVisible({ timeout: 15000 });++ await typeDuringRun(page, interruptText);+ await messageInput(page).press('Alt+Enter');++ // The abort settles and the text auto-sends as the next user turn.+ await expect(messageTurns(page)).toHaveCount(6, { timeout: 60000 });+ const interruptTurn = messageTurns(page).nth(4);+ await expect(interruptTurn).toContainText(interruptText);+ await expect(interruptTurn.locator('.user-turn')).toBeVisible();++ // The follow-up run streams its response into the LIVE view — no reload.+ const freshReply = messageTurns(page).nth(5);+ await expect(freshReply).toContainText(MOCK_REPLY_TEXT, { timeout: 30000 });+ await expect(freshReply.locator('.agent-turn')).toBeVisible();++ // The interrupted response was stopped mid-stream: its final chunk never+ // arrived (an uninterrupted slow run always ends with it).+ await expect(messagesView(page).getByText(SLOW_REPLY_LAST_CHUNK)).toHaveCount(0);+ });+});diff --git a/package-lock.json b/package-lock.jsonindex c9913e0969..1784c15744 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.62",+ "@librechat/agents": "^3.2.63","@librechat/api": "*","@librechat/data-schemas": "*","@microsoft/microsoft-graph-client": "^3.0.7",@@ -9880,9 +9880,9 @@}},"node_modules/@librechat/agents": {- "version": "3.2.62",- "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.2.62.tgz",- "integrity": "sha512-nDGvC3yDM/uvnYEuriqswl3+qWVZuoIiMN7QiDt2b3E3VJsgvR29sOaV31zrHSgAVrxcTzH8zXAd0EsZqBAMUQ==",+ "version": "3.2.63",+ "resolved": "https://registry.npmjs.org/@librechat/agents/-/agents-3.2.63.tgz",+ "integrity": "sha512-m9sDJzSzpkKxzJR3RcqdJzuEIULR4Rv5wLbhXE7STp47UriIK5tZerpYT2aA4RI8Rriduc0OZ8IPlXB1lVDjSg==","license": "MIT","dependencies": {"@anthropic-ai/sdk": "^0.103.0",@@ -42982,7 +42982,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^2.8.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.2.62",+ "@librechat/agents": "^3.2.63","@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 5e52f86b4d..3016fda3c0 100644--- a/packages/api/package.json+++ b/packages/api/package.json@@ -116,7 +116,7 @@"@azure/storage-blob": "^12.30.0","@google/genai": "^2.8.0","@keyv/redis": "^4.3.3",- "@librechat/agents": "^3.2.62",+ "@librechat/agents": "^3.2.63","@librechat/data-schemas": "*","@modelcontextprotocol/sdk": "^1.29.0","@opentelemetry/api": "^1.9.0",diff --git a/packages/api/src/agents/index.ts b/packages/api/src/agents/index.tsindex 8865ef8762..6b35e014b3 100644--- a/packages/api/src/agents/index.ts+++ b/packages/api/src/agents/index.ts@@ -31,3 +31,4 @@ export * from './validation';export * from './added';export * from './load';export * from './hitl';+export * from './steering';diff --git a/packages/api/src/agents/run.ts b/packages/api/src/agents/run.tsindex b83003e806..d3264ee5d6 100644--- a/packages/api/src/agents/run.ts+++ b/packages/api/src/agents/run.ts@@ -1,5 +1,5 @@import { logger } from '@librechat/data-schemas';-import { Run, Providers, Constants } from '@librechat/agents';+import { Run, Providers, Constants, HookRegistry } from '@librechat/agents';import {KnownEndpoints,EModelEndpoint,@@ -17,6 +17,7 @@ import type {StandardGraphConfig,LCToolRegistry,SubagentConfig,+ HookCallback,AgentInputs,GenericTool,RunConfig,@@ -48,6 +49,7 @@ import { resolveToolApprovalPolicy, exemptAskUserQuestionFromApproval } from '~/import { getLLMConfig as getAnthropicLLMConfig } from '~/endpoints/anthropic/llm';import { CREATE_FILE_TOOL_NAME, EDIT_FILE_TOOL_NAME } from '~/agents/tools';import { getProviderConfig } from '~/endpoints/config/providers';+import { isSteeringSupported } from '~/agents/steering/runtime';import { extractDefaultParams } from '~/endpoints/openai/llm';import { resolveHeaders, createSafeUser } from '~/utils/env';import { getAgentCheckpointer } from '~/agents/checkpointer';@@ -1030,6 +1032,7 @@ export async function createRun({calibrationRatio,appConfig,subagentUsageSink,+ steering,hitlCapable = false,streaming = true,streamUsage = true,@@ -1078,6 +1081,15 @@ export async function createRun({* Switch to the `RunConfig` pick once the dependency is bumped.*/subagentUsageSink?: (event: SubagentUsageEvent) => void;+ /**+ * The run-scoped steer-drain hook (a `PostToolBatch` callback built via+ * `createSteerDrainHook`). Registered on the run's hook registry independent+ * of the tool-approval policy — steering needs neither HITL nor a+ * checkpointer (injection merges via the messages reducer inside the tool+ * node). Only the resumable agents controller passes this; the+ * OpenAI-compatible and Responses controllers have no job/SSE surface.+ */+ steering?: { hook: HookCallback<'PostToolBatch'> };/*** Whether the caller implements the HITL pause/resume lifecycle (inspects* `run.getInterrupt()`, persists a pending action, exposes a resume route). Gates the@@ -1422,6 +1434,20 @@ export async function createRun({graphConfig.compileOptions = { ...graphConfig.compileOptions, checkpointer };}+ /**+ * The run's hook registry: the HITL policy hooks (when approval is enabled)+ * plus the steer-drain PostToolBatch hook. Steering registers independently+ * of the approval policy and requires no checkpointer, but is hard-gated on+ * SDK support — draining on an SDK that ignores `injectedMessages` would+ * silently drop the user's words (the steer controller 501s in that case;+ * this guard is defense in depth).+ */+ let hooks = hitl?.hooks;+ if (steering != null && isSteeringSupported()) {+ hooks = hooks ?? new HookRegistry();+ hooks.register('PostToolBatch', { hooks: [steering.hook] });+ }+/*** Built as a variable (not an inline literal) so the extra* `subagentUsageSink` field passes assignability against SDK versions@@ -1500,7 +1526,11 @@ export async function createRun({// 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 }),+ // The steer-drain hook rides the same registry but independently of the approval+ // policy: a PostToolBatch-only registry keeps the SDK's eager execution fast paths+ // (it gates on result-altering hooks, not registry presence).+ ...(hitl && { humanInTheLoop: hitl.humanInTheLoop }),+ ...(hooks && { hooks }),};const run = await Run.create(runConfig);diff --git a/packages/api/src/agents/steering/__tests__/media.spec.ts b/packages/api/src/agents/steering/__tests__/media.spec.tsnew file mode 100644index 0000000000..d57a00ea81--- /dev/null+++ b/packages/api/src/agents/steering/__tests__/media.spec.ts@@ -0,0 +1,244 @@+import type { IMongoFile } from '@librechat/data-schemas';+import type { SteerMediaClient, SteerFileFetcher } from '../media';+import { buildSteerMedia, stampSteerPartMedia } from '../media';++jest.spyOn(console, 'log').mockImplementation();++/** Stand-in for AgentClient: the encode fan-out is stubbed at the same seam+ * BaseClient exposes (processAttachments populates media fields in place). */+function createClient({+ image_urls,+ documents,+ fileContext,+}: {+ image_urls?: Array<Record<string, unknown>>;+ documents?: Array<Record<string, unknown>>;+ fileContext?: string;+} = {}): SteerMediaClient & { processAttachments: jest.Mock } {+ return {+ addFileContextToMessage: jest.fn(async (pseudo: Record<string, unknown>) => {+ if (fileContext) {+ pseudo.fileContext = fileContext;+ }+ }),+ processAttachments: jest.fn(async (pseudo: Record<string, unknown>, files: IMongoFile[]) => {+ if (image_urls) {+ pseudo.image_urls = image_urls;+ }+ if (documents) {+ pseudo.documents = documents;+ }+ return files;+ }),+ };+}++const user = { id: 'user-1' };+const imagePart = {+ type: 'image_url',+ image_url: { url: 'data:image/png;base64,abc', detail: 'auto' },+};+const imageDoc = {+ file_id: 'f1',+ type: 'image/png',+ filepath: '/uploads/u1/f1.png',+ filename: 'shot.png',+ height: 10,+ width: 20,+ bytes: 1234,+ user: 'user-1',+} as unknown as IMongoFile;+const secondDoc = {+ file_id: 'f2',+ type: 'image/png',+ filepath: '/uploads/u1/f2.png',+ bytes: 99,+} as unknown as IMongoFile;++const steerItem = (files: Array<{ file_id: string }>, text = 'look at this') => ({+ steerId: 's1',+ text,+ userId: 'user-1',+ createdAt: Date.now(),+ files,+});++describe('buildSteerMedia', () => {+ it('fetches owner-scoped files and assembles text + media content', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => [imageDoc]);+ const client = createClient({ image_urls: [imagePart] });++ const result = await buildSteerMedia({+ client,+ user,+ item: steerItem([{ file_id: 'f1' }]),+ getFiles,+ });++ expect(getFiles).toHaveBeenCalledWith({ file_id: { $in: ['f1'] }, user: 'user-1' }, {}, {});+ expect(result?.content).toEqual([{ type: 'text', text: 'look at this' }, imagePart]);+ expect(result?.files).toEqual([+ {+ file_id: 'f1',+ type: 'image/png',+ filepath: '/uploads/u1/f1.png',+ filename: 'shot.png',+ height: 10,+ width: 20,+ bytes: 1234,+ },+ ]);+ });++ it('restores the composer ref order over the $in result', async () => {+ // DB returns f1 before f2; the user attached f2 first.+ const getFiles: SteerFileFetcher = jest.fn(async () => [imageDoc, secondDoc]);+ const client = createClient({ image_urls: [imagePart] });++ const result = await buildSteerMedia({+ client,+ user,+ item: steerItem([{ file_id: 'f2' }, { file_id: 'f1' }]),+ getFiles,+ });++ expect(client.processAttachments).toHaveBeenCalledWith(expect.anything(), [+ secondDoc,+ imageDoc,+ ]);+ expect(result?.files?.map((file) => file.file_id)).toEqual(['f2', 'f1']);+ });++ it('prepends extracted file context to the steer text', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => [+ { file_id: 'f2', type: 'text/plain' } as unknown as IMongoFile,+ ]);+ const client = createClient({ fileContext: 'Attached document(s): notes' });++ const result = await buildSteerMedia({+ client,+ user,+ item: steerItem([{ file_id: 'f2' }], 'summarize it'),+ getFiles,+ });++ expect(result?.content).toEqual([+ { type: 'text', text: 'Attached document(s): notes\nsummarize it' },+ ]);+ });++ it('returns undefined when no authorized files remain', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => []);+ const client = createClient({ image_urls: [imagePart] });++ const result = await buildSteerMedia({+ client,+ user,+ item: steerItem([{ file_id: 'not-yours' }]),+ getFiles,+ });++ expect(result).toBeUndefined();+ expect(client.processAttachments).not.toHaveBeenCalled();+ });++ it('scopes the fetch to the tenant when present', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => []);+ await buildSteerMedia({+ client: createClient(),+ user: { id: 'user-1', tenantId: 'ten-1' },+ item: steerItem([{ file_id: 'f1' }], 'x'),+ getFiles,+ });+ expect(getFiles).toHaveBeenCalledWith(+ { file_id: { $in: ['f1'] }, user: 'user-1', tenantId: 'ten-1' },+ {},+ {},+ );+ });+});++describe('stampSteerPartMedia', () => {+ it('stamps media onto steer parts immutably with one batched fetch', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => [imageDoc]);+ const client = createClient({ image_urls: [imagePart] });+ const steerPart = {+ type: 'steer',+ steer: 'inline steer',+ steerId: 's1',+ files: [{ file_id: 'f1' }],+ };+ const otherPart = { type: 'text', text: 'assistant text' };+ const originalContent = [otherPart, steerPart];+ const message: { role: string; content: unknown } = {+ role: 'assistant',+ content: originalContent,+ };+ const payload = [{ role: 'user', content: 'hi' }, message];++ const stamped = await stampSteerPartMedia({ client, user, payload, getFiles });++ expect(getFiles).toHaveBeenCalledTimes(1);+ const content = message.content as Array<Record<string, unknown>>;+ expect(content).not.toBe(originalContent);+ expect(content[0]).toBe(otherPart);+ expect(content[1]).not.toBe(steerPart);+ expect(content[1].media).toEqual([{ type: 'text', text: 'inline steer' }, imagePart]);+ expect(steerPart).not.toHaveProperty('media');+ expect(stamped).toEqual([+ {+ index: 1,+ media: [{ type: 'text', text: 'inline steer' }, imagePart],+ steerText: 'inline steer',+ },+ ]);+ });++ it('consumes prefetched docs without issuing a second query', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => []);+ const client = createClient({ image_urls: [imagePart] });+ const steerPart = {+ type: 'steer',+ steer: 'prefetched steer',+ steerId: 's2',+ files: [{ file_id: 'f1' }, { file_id: 'unauthorized' }],+ };+ const message = { role: 'assistant', content: [steerPart] };++ const stamped = await stampSteerPartMedia({+ client,+ user,+ payload: [message],+ docsById: new Map([['f1', imageDoc]]),+ getFiles,+ });++ expect(getFiles).not.toHaveBeenCalled();+ expect(stamped).toHaveLength(1);+ expect(stamped[0].index).toBe(0);+ expect(client.processAttachments).toHaveBeenCalledWith(expect.anything(), [imageDoc]);+ });++ it('does nothing when no steer part carries files', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => []);+ const payload = [{ role: 'assistant', content: [{ type: 'steer', steer: 'text only' }] }];+ await stampSteerPartMedia({ client: createClient(), user, payload, getFiles });+ expect(getFiles).not.toHaveBeenCalled();+ });++ it('leaves the part text-only when its files are no longer authorized', async () => {+ const getFiles: SteerFileFetcher = jest.fn(async () => []);+ const steerPart = {+ type: 'steer',+ steer: 'orphaned',+ steerId: 's9',+ files: [{ file_id: 'gone' }],+ };+ const message = { role: 'assistant', content: [steerPart] };++ await stampSteerPartMedia({ client: createClient(), user, payload: [message], getFiles });++ expect((message.content as unknown[])[0]).toBe(steerPart);+ expect(steerPart).not.toHaveProperty('media');+ });+});diff --git a/packages/api/src/agents/steering/__tests__/offset.spec.ts b/packages/api/src/agents/steering/__tests__/offset.spec.tsnew file mode 100644index 0000000000..f572f99b0c--- /dev/null+++ b/packages/api/src/agents/steering/__tests__/offset.spec.ts@@ -0,0 +1,109 @@+import { GraphEvents } from '@librechat/agents';+import type { EventHandler } from '@librechat/agents';+import { createContentIndexOffsetHandlers } from '~/agents/hitl/resume';+import { createSteerIndexOffsetHandlers } from '../offset';++type CapturedCall = { event: string; data: unknown };++function captureHandler(calls: CapturedCall[]): EventHandler {+ return {+ handle: (event, data) => {+ calls.push({ event: event as string, data });+ },+ };+}++describe('createSteerIndexOffsetHandlers', () => {+ it('returns undefined handlers untouched', () => {+ expect(createSteerIndexOffsetHandlers(undefined, { offset: 0 })).toBeUndefined();+ });++ it('passes indices through at offset 0 and shifts after increments (read at handle time)', () => {+ const calls: CapturedCall[] = [];+ const state = { offset: 0 };+ const wrapped = createSteerIndexOffsetHandlers(+ { [GraphEvents.ON_RUN_STEP]: captureHandler(calls) },+ state,+ );++ const handler = wrapped![GraphEvents.ON_RUN_STEP];+ handler.handle(GraphEvents.ON_RUN_STEP, { id: 'step-1', index: 0 }, undefined, undefined);+ state.offset = 1;+ handler.handle(GraphEvents.ON_RUN_STEP, { id: 'step-2', index: 1 }, undefined, undefined);+ state.offset = 2;+ handler.handle(GraphEvents.ON_RUN_STEP, { id: 'step-3', index: 2 }, undefined, undefined);++ expect(calls.map((c) => (c.data as { index: number }).index)).toEqual([0, 2, 4]);+ });++ it('shifts ON_AGENT_UPDATE inline indices by the live offset', () => {+ const calls: CapturedCall[] = [];+ const state = { offset: 0 };+ const wrapped = createSteerIndexOffsetHandlers(+ { [GraphEvents.ON_AGENT_UPDATE]: captureHandler(calls) },+ state,+ );++ const handler = wrapped![GraphEvents.ON_AGENT_UPDATE];+ handler.handle(+ GraphEvents.ON_AGENT_UPDATE,+ { agent_update: { index: 3, runId: 'run-1' } },+ undefined,+ undefined,+ );+ state.offset = 2;+ handler.handle(+ GraphEvents.ON_AGENT_UPDATE,+ { agent_update: { index: 4, runId: 'run-1' } },+ undefined,+ undefined,+ );++ expect(+ calls.map((c) => (c.data as { agent_update: { index: number } }).agent_update.index),+ ).toEqual([3, 6]);+ });++ it('leaves index-less payloads and other handlers untouched', () => {+ const calls: CapturedCall[] = [];+ const state = { offset: 5 };+ const passthrough = captureHandler(calls);+ const wrapped = createSteerIndexOffsetHandlers(+ {+ [GraphEvents.ON_RUN_STEP]: captureHandler(calls),+ [GraphEvents.ON_MESSAGE_DELTA]: passthrough,+ },+ state,+ );++ expect(wrapped![GraphEvents.ON_MESSAGE_DELTA]).toBe(passthrough);+ wrapped![GraphEvents.ON_RUN_STEP].handle(+ GraphEvents.ON_RUN_STEP,+ { id: 'step-x' },+ undefined,+ undefined,+ );+ expect(calls[0].data).toEqual({ id: 'step-x' });+ });++ it('composes over the resume offset wrapper: seed shift + live steer shift', () => {+ const calls: CapturedCall[] = [];+ const seedContent = [{ type: 'text' }, { type: 'text' }];+ const state = { offset: 0 };+ const wrapped = createSteerIndexOffsetHandlers(+ createContentIndexOffsetHandlers(+ { [GraphEvents.ON_RUN_STEP]: captureHandler(calls) },+ seedContent,+ ),+ state,+ );++ const handler = wrapped![GraphEvents.ON_RUN_STEP];+ handler.handle(GraphEvents.ON_RUN_STEP, { id: 'step-1', index: 0 }, undefined, undefined);+ state.offset = 1;+ handler.handle(GraphEvents.ON_RUN_STEP, { id: 'step-2', index: 1 }, undefined, undefined);++ // seed offset (2) applies inside; steer offset applies on top+ expect(calls.map((c) => (c.data as { index: number }).index)).toEqual([2, 4]);+ });+});diff --git a/packages/api/src/agents/steering/__tests__/request.spec.ts b/packages/api/src/agents/steering/__tests__/request.spec.tsnew file mode 100644index 0000000000..fd9ed846c5--- /dev/null+++ b/packages/api/src/agents/steering/__tests__/request.spec.ts@@ -0,0 +1,437 @@+import type { IMongoFile } from '@librechat/data-schemas';+import { InMemoryEventTransport } from '~/stream/implementations/InMemoryEventTransport';+import { buildPendingAction, buildToolApprovalPayload } from '~/agents/hitl/policy';+import { InMemoryJobStore } from '~/stream/implementations/InMemoryJobStore';+import { STEER_QUEUE_MAX_DEPTH } from '~/stream/interfaces/IJobStore';+import { GenerationJobManager } from '~/stream/GenerationJobManager';+import { handleSteerRequest, handleSteerCancel } from '../request';+import { isSteeringSupported } from '../runtime';++jest.mock('../runtime', () => ({+ ...jest.requireActual('../runtime'),+ isSteeringSupported: jest.fn(() => true),+}));++jest.spyOn(console, 'log').mockImplementation();++const mockIsSupported = isSteeringSupported as jest.Mock;+const user = { id: 'user-1' };++describe('handleSteerRequest (real in-memory job manager)', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ mockIsSupported.mockReturnValue(true);+ GenerationJobManager.configure({+ jobStore: new InMemoryJobStore({ ttlAfterComplete: 60000 }),+ eventTransport: new InMemoryEventTransport(),+ isRedis: false,+ cleanupOnComplete: false,+ });+ GenerationJobManager.initialize();+ });++ afterEach(async () => {+ await GenerationJobManager.destroy();+ });++ it('400s on a missing or placeholder conversationId', async () => {+ expect((await handleSteerRequest(user, { text: 'hello' })).status).toBe(400);+ const placeholder = await handleSteerRequest(user, { conversationId: 'new', text: 'hello' });+ expect(placeholder.status).toBe(400);+ expect(placeholder.body.code).toBe('INVALID_CONVERSATION');+ });++ it('400s on empty or whitespace-only text', async () => {+ const result = await handleSteerRequest(user, { conversationId: 'c1', text: ' ' });+ expect(result.status).toBe(400);+ expect(result.body.code).toBe('EMPTY_TEXT');+ });++ it('413s past the length cap', async () => {+ const result = await handleSteerRequest(user, {+ conversationId: 'c1',+ text: 'x'.repeat(16001),+ });+ expect(result.status).toBe(413);+ expect(result.body.code).toBe('STEER_TOO_LONG');+ });++ it('400s on malformed or oversized file lists', async () => {+ const malformed = await handleSteerRequest(user, {+ conversationId: 'c1',+ text: 'x',+ files: [{ nope: true }],+ });+ expect(malformed.status).toBe(400);+ expect(malformed.body.code).toBe('INVALID_FILES');++ const oversized = await handleSteerRequest(user, {+ conversationId: 'c1',+ text: 'x',+ files: Array.from({ length: 11 }, (_, i) => ({ file_id: `f${i}` })),+ });+ expect(oversized.status).toBe(400);+ expect(oversized.body.code).toBe('TOO_MANY_FILES');+ });++ it('501s when the installed SDK cannot inject hook messages (running job)', async () => {+ mockIsSupported.mockReturnValue(false);+ const streamId = 'steer-req-unsupported';+ await GenerationJobManager.createJob(streamId, user.id);+ const result = await handleSteerRequest(user, { conversationId: streamId, text: 'hello' });+ expect(result.status).toBe(501);+ expect(result.body.code).toBe('STEER_UNSUPPORTED');+ });++ it('404s before the capability gate when the run already finished', async () => {+ // A steer racing completion on an unsupported SDK must send-now (404),+ // not strand text in a queue with no run-end signal left to drain it.+ mockIsSupported.mockReturnValue(false);+ const result = await handleSteerRequest(user, { conversationId: 'finished', text: 'x' });+ expect(result.status).toBe(404);+ expect(result.body.code).toBe('NO_ACTIVE_RUN');+ });++ it('404s when the job is missing or terminal', async () => {+ const missing = await handleSteerRequest(user, { conversationId: 'gone', text: 'x' });+ expect(missing.status).toBe(404);+ expect(missing.body.code).toBe('NO_ACTIVE_RUN');++ const streamId = 'steer-req-terminal';+ await GenerationJobManager.createJob(streamId, user.id);+ await GenerationJobManager.completeJob(streamId);+ const terminal = await handleSteerRequest(user, { conversationId: streamId, text: 'x' });+ expect(terminal.status).toBe(404);+ });++ it('403s for another user', async () => {+ const streamId = 'steer-req-owner';+ await GenerationJobManager.createJob(streamId, 'someone-else');+ const result = await handleSteerRequest(user, { conversationId: streamId, text: 'x' });+ expect(result.status).toBe(403);+ expect(result.body.code).toBe('UNAUTHORIZED');+ });++ it('409s while the run is paused for human review', async () => {+ const streamId = 'steer-req-paused';+ await GenerationJobManager.createJob(streamId, user.id);+ const payload = buildToolApprovalPayload([+ { name: 'shell', arguments: { command: 'ls' }, tool_call_id: 'call_abc' },+ ]);+ const action = buildPendingAction(payload, {+ streamId,+ conversationId: streamId,+ runId: 'run-1',+ responseMessageId: 'msg-1',+ });+ expect(await GenerationJobManager.approvals.pause(streamId, action)).toBe(true);++ const result = await handleSteerRequest(user, { conversationId: streamId, text: 'x' });+ expect(result.status).toBe(409);+ expect(result.body.code).toBe('RUN_PAUSED');+ });++ it('429s when the queue is full', async () => {+ const streamId = 'steer-req-full';+ await GenerationJobManager.createJob(streamId, user.id);+ for (let i = 0; i < STEER_QUEUE_MAX_DEPTH; i++) {+ const accepted = await handleSteerRequest(user, {+ conversationId: streamId,+ text: `steer ${i}`,+ });+ expect(accepted.status).toBe(202);+ }+ const overflow = await handleSteerRequest(user, { conversationId: streamId, text: 'over' });+ expect(overflow.status).toBe(429);+ expect(overflow.body.code).toBe('STEER_QUEUE_FULL');+ });++ it('202s, sanitizes the text, and enqueues sanitized attachment refs', async () => {+ const streamId = 'steer-req-accept';+ await GenerationJobManager.createJob(streamId, user.id);++ const result = await handleSteerRequest(user, {+ conversationId: streamId,+ text: ' focus on tests\0 ',+ files: [+ {+ file_id: 'f1',+ type: 'image/png',+ filepath: '/uploads/f1.png',+ filename: 'shot.png',+ height: 10,+ width: 20,+ bytes: 999,+ user: 'someone-else',+ embedded: true,+ },+ ],+ });++ expect(result.status).toBe(202);+ expect(result.body).toMatchObject({+ status: 'queued',+ position: 1,+ conversationId: streamId,+ });+ expect(typeof result.body.steerId).toBe('string');++ const queued = await GenerationJobManager.steering.peek(streamId);+ expect(queued).toHaveLength(1);+ expect(queued[0].text).toBe('focus on tests');+ expect(queued[0].userId).toBe(user.id);+ expect(queued[0].files).toEqual([+ {+ file_id: 'f1',+ type: 'image/png',+ filepath: '/uploads/f1.png',+ filename: 'shot.png',+ height: 10,+ width: 20,+ bytes: 999,+ },+ ]);+ });++ describe('injected getFiles (owner-scoped resolve at enqueue)', () => {+ const dbDoc = {+ file_id: 'f1',+ type: 'image/png',+ filepath: '/uploads/u1/f1.png',+ filename: 'real.png',+ height: 4,+ width: 6,+ bytes: 111,+ user: 'user-1',+ } as unknown as IMongoFile;++ it('400s INVALID_FILES when any ref does not resolve to an owned doc, enqueuing nothing', async () => {+ const streamId = 'steer-req-file-foreign';+ await GenerationJobManager.createJob(streamId, user.id);+ const getFiles = jest.fn(async () => [dbDoc]);++ const result = await handleSteerRequest(+ user,+ {+ conversationId: streamId,+ text: 'x',+ files: [{ file_id: 'f1' }, { file_id: 'f-foreign' }],+ },+ { getFiles },+ );++ expect(result.status).toBe(400);+ expect(result.body.code).toBe('INVALID_FILES');+ expect(getFiles).toHaveBeenCalledWith(+ { file_id: { $in: ['f1', 'f-foreign'] }, user: user.id },+ {},+ {},+ );+ expect(await GenerationJobManager.steering.peek(streamId)).toEqual([]);+ });++ it('replaces client-supplied ref metadata with DB-derived shapes', async () => {+ const streamId = 'steer-req-file-trusted';+ await GenerationJobManager.createJob(streamId, user.id);+ const getFiles = jest.fn(async () => [dbDoc]);++ const result = await handleSteerRequest(+ user,+ {+ conversationId: streamId,+ text: 'trusted refs only',+ files: [+ {+ file_id: 'f1',+ type: 'text/html',+ filepath: 'https://evil.example/spoof',+ filename: 'spoof.html',+ bytes: 1,+ },+ ],+ },+ { getFiles },+ );++ expect(result.status).toBe(202);+ const queued = await GenerationJobManager.steering.peek(streamId);+ expect(queued[0].files).toEqual([+ {+ file_id: 'f1',+ type: 'image/png',+ filepath: '/uploads/u1/f1.png',+ filename: 'real.png',+ height: 4,+ width: 6,+ bytes: 111,+ },+ ]);+ });++ it('skips the resolve for text-only steers', async () => {+ const streamId = 'steer-req-file-none';+ await GenerationJobManager.createJob(streamId, user.id);+ const getFiles = jest.fn(async () => [dbDoc]);++ const result = await handleSteerRequest(+ user,+ { conversationId: streamId, text: 'no attachments' },+ { getFiles },+ );++ expect(result.status).toBe(202);+ expect(getFiles).not.toHaveBeenCalled();+ });+ });++ describe('injected updateFilesUsage (upload-window TTL parity)', () => {+ const dbDoc = { file_id: 'f1', type: 'image/png' } as unknown as IMongoFile;++ it('marks resolved uploads used after a successful enqueue', async () => {+ const streamId = 'steer-req-usage-ok';+ await GenerationJobManager.createJob(streamId, user.id);+ const getFiles = jest.fn(async () => [dbDoc]);+ const updateFilesUsage = jest.fn(async () => []);++ const result = await handleSteerRequest(+ user,+ { conversationId: streamId, text: 'x', files: [{ file_id: 'f1' }] },+ { getFiles, updateFilesUsage },+ );++ expect(result.status).toBe(202);+ expect(updateFilesUsage).toHaveBeenCalledWith([{ file_id: 'f1' }], undefined, {+ user: user.id,+ tenantId: undefined,+ });+ });++ it('does not mark usage on a rejected steer and never fails the 202', async () => {+ const streamId = 'steer-req-usage-deny';+ await GenerationJobManager.createJob(streamId, user.id);+ const getFiles = jest.fn(async () => [dbDoc]);+ const updateFilesUsage = jest.fn(async () => []);++ const denied = await handleSteerRequest(+ user,+ { conversationId: streamId, text: 'x', files: [{ file_id: 'f-unknown' }] },+ { getFiles, updateFilesUsage },+ );+ expect(denied.status).toBe(400);+ expect(updateFilesUsage).not.toHaveBeenCalled();++ const failing = jest.fn(async () => {+ throw new Error('usage write failed');+ });+ const accepted = await handleSteerRequest(+ user,+ { conversationId: streamId, text: 'x', files: [{ file_id: 'f1' }] },+ { getFiles, updateFilesUsage: failing },+ );+ expect(accepted.status).toBe(202);+ await new Promise(setImmediate);+ expect(failing).toHaveBeenCalledTimes(1);+ });+ });++ describe('injected checkAgentAccess (originating-run authorization)', () => {+ it('403s FORBIDDEN and enqueues nothing when the check denies', async () => {+ const streamId = 'steer-req-agent-denied';+ await GenerationJobManager.createJob(streamId, user.id);+ await GenerationJobManager.updateMetadata(streamId, {+ agent_id: 'agent_abc',+ endpoint: 'agents',+ });+ const checkAgentAccess = jest.fn(async () => false);+ const getFiles = jest.fn(async () => []);+ const updateFilesUsage = jest.fn(async () => []);++ const result = await handleSteerRequest(+ user,+ { conversationId: streamId, text: 'inject this', files: [{ file_id: 'f1' }] },+ { checkAgentAccess, getFiles, updateFilesUsage },+ );++ expect(result.status).toBe(403);+ expect(result.body.code).toBe('FORBIDDEN');+ expect(checkAgentAccess).toHaveBeenCalledWith({ agentId: 'agent_abc', endpoint: 'agents' });+ expect(getFiles).not.toHaveBeenCalled();+ expect(updateFilesUsage).not.toHaveBeenCalled();+ expect(await GenerationJobManager.steering.peek(streamId)).toEqual([]);+ });++ it('202s when the check allows, passing the job metadata identity', async () => {+ const streamId = 'steer-req-agent-allowed';+ await GenerationJobManager.createJob(streamId, user.id);+ const checkAgentAccess = jest.fn(async () => true);++ const result = await handleSteerRequest(+ user,+ { conversationId: streamId, text: 'go ahead' },+ { checkAgentAccess },+ );++ expect(result.status).toBe(202);+ // No metadata written yet — the callback still receives the (empty) identity.+ expect(checkAgentAccess).toHaveBeenCalledWith({ agentId: undefined, endpoint: undefined });+ expect(await GenerationJobManager.steering.peek(streamId)).toHaveLength(1);+ });+ });+});++describe('handleSteerCancel (real in-memory job manager)', () => {+ beforeEach(() => {+ jest.clearAllMocks();+ mockIsSupported.mockReturnValue(true);+ GenerationJobManager.configure({+ jobStore: new InMemoryJobStore({ ttlAfterComplete: 60000 }),+ eventTransport: new InMemoryEventTransport(),+ isRedis: false,+ cleanupOnComplete: false,+ });+ GenerationJobManager.initialize();+ });++ afterEach(async () => {+ await GenerationJobManager.destroy();+ });++ async function queueSteer(streamId: string): Promise<string> {+ await GenerationJobManager.createJob(streamId, 'user-1');+ const result = await handleSteerRequest(user, { conversationId: streamId, text: 'cancel me' });+ expect(result.status).toBe(202);+ return result.body.steerId as string;+ }++ it('400s on invalid input', async () => {+ expect((await handleSteerCancel(user, { steerId: 's1' })).status).toBe(400);+ const badId = await handleSteerCancel(user, { conversationId: 'c1', steerId: '' });+ expect(badId.status).toBe(400);+ expect(badId.body.code).toBe('INVALID_STEER_ID');+ });++ it('removes a queued steer and reports a lost race as removed:false', async () => {+ const steerId = await queueSteer('cancel-ok');+ const cancelled = await handleSteerCancel(user, { conversationId: 'cancel-ok', steerId });+ expect(cancelled).toEqual({ status: 200, body: { removed: true } });+ expect(await GenerationJobManager.steering.peek('cancel-ok')).toEqual([]);++ const again = await handleSteerCancel(user, { conversationId: 'cancel-ok', steerId });+ expect(again).toEqual({ status: 200, body: { removed: false } });+ });++ it('treats a missing job as a lost race, not an error', async () => {+ const result = await handleSteerCancel(user, { conversationId: 'gone', steerId: 's1' });+ expect(result).toEqual({ status: 200, body: { removed: false } });+ });++ it('403s another user and leaves the steer queued', async () => {+ const steerId = await queueSteer('cancel-foreign');+ const result = await handleSteerCancel(+ { id: 'intruder' },+ { conversationId: 'cancel-foreign', steerId },+ );+ expect(result.status).toBe(403);+ expect((await GenerationJobManager.steering.peek('cancel-foreign')).length).toBe(1);+ });+});diff --git a/packages/api/src/agents/steering/__tests__/runtime.spec.ts b/packages/api/src/agents/steering/__tests__/runtime.spec.tsnew file mode 100644index 0000000000..2a32d52e3b--- /dev/null+++ b/packages/api/src/agents/steering/__tests__/runtime.spec.ts@@ -0,0 +1,237 @@+import * as agentsSdk from '@librechat/agents';+import type { PostToolBatchHookInput, PostToolBatchHookOutput } from '@librechat/agents';+import type { SteerQueueItem } from '~/stream/interfaces/IJobStore';++/** Mirrors runtime.ts's local extension — the field predates the SDK pin bump. */+type SteerDrainOutput = PostToolBatchHookOutput & {+ injectedMessages?: Array<{ role: string; content: string; source: string }>;+};+import { InMemoryEventTransport } from '~/stream/implementations/InMemoryEventTransport';+import { InMemoryJobStore } from '~/stream/implementations/InMemoryJobStore';+import { GenerationJobManager } from '~/stream/GenerationJobManager';+import { createSteerDrainHook, isSteeringSupported } from '../runtime';++jest.spyOn(console, 'log').mockImplementation();++const abortSignal = new AbortController().signal;++function batchInput(overrides: Partial<PostToolBatchHookInput> = {}): PostToolBatchHookInput {+ return {+ hook_event_name: 'PostToolBatch',+ runId: 'run-1',+ entries: [],+ ...overrides,+ };+}++function buildSteer(steerId: string, text: string): SteerQueueItem {+ return { steerId, text, userId: 'user-1', createdAt: Date.now() };+}++describe('isSteeringSupported', () => {+ it('mirrors the installed SDK capability flag AND replay support', () => {+ // CI runs against the published SDK pin (possibly pre-injectedMessages);+ // local dev may run against a capability-bearing build. The probe must+ // track BOTH halves of the contract exactly in every world — false means+ // the steer route 501s and createRun skips the drain wiring. Requiring+ // ContentTypes.STEER guards the release window where injection shipped+ // without the formatAgentMessages replay branch: creating steer parts+ // there would leak them into provider-facing assistant content.+ const sdk = agentsSdk as {+ HOOK_INJECTED_MESSAGES_CAPABLE?: boolean;+ ContentTypes?: { STEER?: string };+ };+ const capable =+ sdk.HOOK_INJECTED_MESSAGES_CAPABLE === true && sdk.ContentTypes?.STEER === 'steer';+ expect(isSteeringSupported()).toBe(capable);+ });+});++describe('createSteerDrainHook', () => {+ beforeEach(() => {+ GenerationJobManager.configure({+ jobStore: new InMemoryJobStore({ ttlAfterComplete: 60000 }),+ eventTransport: new InMemoryEventTransport(),+ isRedis: false,+ cleanupOnComplete: false,+ });+ GenerationJobManager.initialize();+ });++ afterEach(async () => {+ await GenerationJobManager.destroy();+ });++ it('drains FIFO, applies each steer, and returns per-message injectedMessages', async () => {+ const streamId = `drain-${Date.now()}`;+ const job = await GenerationJobManager.createJob(streamId, 'user-1');+ await GenerationJobManager.steering.enqueue(streamId, buildSteer('s1', 'first'));+ await GenerationJobManager.steering.enqueue(streamId, buildSteer('s2', 'second'));++ const applied: string[] = [];+ const hook = createSteerDrainHook({+ streamId,+ jobCreatedAt: job.createdAt,+ applySteer: (item) => {+ applied.push(item.text);+ },+ });++ const output: SteerDrainOutput = await hook(batchInput(), abortSignal);+ expect(applied).toEqual(['first', 'second']);+ expect(output.injectedMessages).toEqual([+ { role: 'user', content: 'first', source: 'steer' },+ { role: 'user', content: 'second', source: 'steer' },+ ]);+ expect(await GenerationJobManager.steering.peek(streamId)).toEqual([]);+ });++ it('returns empty output when the queue is empty', async () => {+ const streamId = `drain-empty-${Date.now()}`;+ await GenerationJobManager.createJob(streamId, 'user-1');+ const hook = createSteerDrainHook({ streamId, applySteer: jest.fn() });++ expect(await hook(batchInput(), abortSignal)).toEqual({});+ });++ it('never drains inside a subagent scope', async () => {+ const streamId = `drain-subagent-${Date.now()}`;+ await GenerationJobManager.createJob(streamId, 'user-1');+ await GenerationJobManager.steering.enqueue(streamId, buildSteer('s1', 'kept'));++ const hook = createSteerDrainHook({ streamId, applySteer: jest.fn() });+ expect(await hook(batchInput({ agentId: 'child-agent' }), abortSignal)).toEqual({});+ expect((await GenerationJobManager.steering.peek(streamId)).map((s) => s.text)).toEqual([+ 'kept',+ ]);+ });++ it('refuses to drain when the job was replaced', async () => {+ const streamId = `drain-replaced-${Date.now()}`;+ const job = await GenerationJobManager.createJob(streamId, 'user-1');+ const hook = createSteerDrainHook({+ streamId,+ jobCreatedAt: job.createdAt - 1,+ applySteer: jest.fn(),+ });+ await GenerationJobManager.steering.enqueue(streamId, buildSteer('s1', 'new job steer'));++ expect(await hook(batchInput(), abortSignal)).toEqual({});+ expect((await GenerationJobManager.steering.peek(streamId)).map((s) => s.text)).toEqual([+ 'new job steer',+ ]);+ });++ it('still injects when applySteer throws', async () => {+ const streamId = `drain-apply-error-${Date.now()}`;+ const job = await GenerationJobManager.createJob(streamId, 'user-1');+ await GenerationJobManager.steering.enqueue(streamId, buildSteer('s1', 'survives'));++ const hook = createSteerDrainHook({+ streamId,+ jobCreatedAt: job.createdAt,+ applySteer: () => {+ throw new Error('emit failed');+ },+ });++ const output: SteerDrainOutput = await hook(batchInput(), abortSignal);+ expect(output.injectedMessages).toEqual([+ { role: 'user', content: 'survives', source: 'steer' },+ ]);+ });++ it('injects encoded media content for steers that carry files', async () => {+ const streamId = `drain-media-${Date.now()}`;+ const job = await GenerationJobManager.createJob(streamId, 'user-1');+ const files = [{ file_id: 'f1', type: 'image/png' }];+ await GenerationJobManager.steering.enqueue(streamId, {+ ...buildSteer('s1', 'see image'),+ files,+ });+ await GenerationJobManager.steering.enqueue(streamId, buildSteer('s2', 'text only'));++ const media = {+ content: [+ { type: 'text', text: 'see image' },+ { type: 'image_url', image_url: { url: 'data:image/png;base64,x', detail: 'auto' } },+ ],+ files,+ };+ const calls: string[] = [];+ const buildMedia = jest.fn(async (item: SteerQueueItem) => {+ calls.push(`media:${item.steerId}`);+ return media;+ });+ const hook = createSteerDrainHook({+ streamId,+ jobCreatedAt: job.createdAt,+ applySteer: (item) => {+ calls.push(`apply:${item.steerId}`);+ },+ buildMedia,+ });++ const output: SteerDrainOutput = await hook(batchInput(), abortSignal);+ // buildMedia is consulted only for items that carry files.+ expect(buildMedia).toHaveBeenCalledTimes(1);+ expect(calls).toEqual(['apply:s1', 'media:s1', 'apply:s2']);+ expect(output.injectedMessages).toEqual([+ { role: 'user', content: media.content, source: 'steer' },+ { role: 'user', content: 'text only', source: 'steer' },+ ]);+ });++ it('persists the steer part BEFORE media encoding (abort-safe ordering)', async () => {+ const streamId = `drain-apply-first-${Date.now()}`;+ const job = await GenerationJobManager.createJob(streamId, 'user-1');+ await GenerationJobManager.steering.enqueue(streamId, {+ ...buildSteer('s1', 'must land first'),+ files: [{ file_id: 'f1' }],+ });++ // Simulates an abort mid-encode: the part must already be applied.+ let appliedBeforeEncode = false;+ let partApplied = false;+ const hook = createSteerDrainHook({+ streamId,+ jobCreatedAt: job.createdAt,+ applySteer: () => {+ partApplied = true;+ },+ buildMedia: async () => {+ appliedBeforeEncode = partApplied;+ throw new Error('aborted mid-encode');+ },+ });++ const output: SteerDrainOutput = await hook(batchInput(), abortSignal);+ expect(appliedBeforeEncode).toBe(true);+ expect(output.injectedMessages).toEqual([+ { role: 'user', content: 'must land first', source: 'steer' },+ ]);+ });++ it('degrades to text-only injection when media encoding fails', async () => {+ const streamId = `drain-media-error-${Date.now()}`;+ const job = await GenerationJobManager.createJob(streamId, 'user-1');+ await GenerationJobManager.steering.enqueue(streamId, {+ ...buildSteer('s1', 'words survive'),+ files: [{ file_id: 'f-gone' }],+ });++ const hook = createSteerDrainHook({+ streamId,+ jobCreatedAt: job.createdAt,+ applySteer: jest.fn(),+ buildMedia: async () => {+ throw new Error('encode failed');+ },+ });++ const output: SteerDrainOutput = await hook(batchInput(), abortSignal);+ expect(output.injectedMessages).toEqual([+ { role: 'user', content: 'words survive', source: 'steer' },+ ]);+ });+});diff --git a/packages/api/src/agents/steering/index.ts b/packages/api/src/agents/steering/index.tsnew file mode 100644index 0000000000..a3a79c78f2--- /dev/null+++ b/packages/api/src/agents/steering/index.ts@@ -0,0 +1,21 @@+export { createSteerDrainHook, isSteeringSupported } from './runtime';+export type { SteerDrainHookOptions, SteerMediaResult } from './runtime';+export {+ handleSteerRequest,+ handleSteerCancel,+ getSteerMaxLength,+ STEER_MAX_FILES,+} from './request';+export type {+ SteerRequestUser,+ SteerRequestBody,+ SteerRequestDeps,+ SteerRunContext,+ SteerCancelBody,+ SteerRequestResult,+} from './request';+export { buildSteerMedia, stampSteerPartMedia } from './media';+export type { SteerMediaClient, SteerFileFetcher, StampedSteerMedia } from './media';+export { createSteerIndexOffsetHandlers } from './offset';+export type { SteerOffsetState } from './offset';+export { toSteerFileRef } from './refs';diff --git a/packages/api/src/agents/steering/media.ts b/packages/api/src/agents/steering/media.tsnew file mode 100644index 0000000000..0c9a98e975--- /dev/null+++ b/packages/api/src/agents/steering/media.ts@@ -0,0 +1,230 @@+import { logger } from '@librechat/data-schemas';+import { formatMessage } from '@librechat/agents';+import { ContentTypes } from 'librechat-data-provider';+import type { IMongoFile } from '@librechat/data-schemas';+import type { TFile } from 'librechat-data-provider';+import type { SteerQueueItem } from '~/stream/interfaces/IJobStore';+import type { SteerMediaResult } from './runtime';+import type { SteerRequestUser } from './request';+import { toSteerFileRef, collectFileIds, buildOwnerFilter } from './refs';+import { prependFileContext } from '../client';++/** The BaseClient encode surface the steer media pipeline reuses. */+export interface SteerMediaClient {+ addFileContextToMessage(message: Record<string, unknown>, files: IMongoFile[]): Promise<void>;+ processAttachments(+ message: Record<string, unknown>,+ files: IMongoFile[],+ ): Promise<IMongoFile[] | undefined>;+}++/** `db.getFiles`-shaped dependency (injected — this package has no DB access). */+export type SteerFileFetcher = (+ filter: Record<string, unknown>,+ sortOptions: Record<string, unknown>,+ selectFields: Record<string, unknown>,+) => Promise<IMongoFile[] | null | undefined>;++interface PseudoMessage {+ messageId: string;+ fileContext?: string;+ image_urls?: Array<Record<string, unknown>>;+ documents?: Array<Record<string, unknown>>;+ videos?: Array<Record<string, unknown>>;+ audios?: Array<Record<string, unknown>>;+ [key: string]: unknown;+}++interface SteerPart {+ type?: string;+ steerId?: string;+ files?: Partial<TFile>[];+ media?: Array<Record<string, unknown>>;+ [key: string]: unknown;+}++/** One stamped steer part: payload index + the stamped content array, so the+ * caller can fold the re-encoded media into its token accounting. */+export interface StampedSteerMedia {+ index: number;+ media: Array<Record<string, unknown>>;+ /** The bare steer body, so token accounting can subtract what the+ * assistant message already counted (file context must still count). */+ steerText: string;+}++/**+ * Encodes authorized file docs for one steer and assembles the multimodal+ * content array, reusing the exact pipeline regular user turns go through:+ * `addFileContextToMessage` + `processAttachments` (single-pass categorize ++ * encode images/documents/videos/audios) on a throwaway message, then the+ * SDK's `formatMessage` for part ordering (no `endpoint` arg — matching the+ * agents payload path, which formats without one).+ */+async function encodeSteerContent({+ client,+ text,+ steerId,+ fileDocs,+}: {+ client: SteerMediaClient;+ text: string;+ steerId: string;+ fileDocs: IMongoFile[];+}): Promise<SteerMediaResult> {+ const pseudo: PseudoMessage = { messageId: `steer:${steerId}` };+ await client.addFileContextToMessage(pseudo, fileDocs);+ const validated = await client.processAttachments(pseudo, fileDocs);+ const formatted = formatMessage({+ message: {+ role: 'user',+ content: text,+ image_urls: pseudo.image_urls,+ documents: pseudo.documents,+ videos: pseudo.videos,+ audios: pseudo.audios,+ } as Parameters<typeof formatMessage>[0]['message'],+ }) as { content: string | Array<Record<string, unknown>> };+ if (pseudo.fileContext) {+ prependFileContext(formatted, pseudo.fileContext);+ }+ const content = Array.isArray(formatted.content)+ ? formatted.content+ : [{ type: ContentTypes.TEXT, text: formatted.content ?? text }];+ const refSource = Array.isArray(validated) && validated.length > 0 ? validated : fileDocs;+ const files = refSource.map(toSteerFileRef).filter((ref): ref is Partial<TFile> => ref != null);+ return { content, files };+}++/**+ * Resolves a queued steer's attachment refs into encoded model content for+ * live mid-run injection. Only `file_id`s are trusted from the item — the+ * fetch is owner-scoped and every other field is re-derived from the DB docs,+ * restored to the composer's ref order (a `$in` result comes back in database+ * order). Returns `undefined` when nothing authorized remains (the drain hook+ * then injects text only, so the user's words always land).+ */+export async function buildSteerMedia({+ client,+ user,+ item,+ getFiles,+}: {+ client: SteerMediaClient;+ user: SteerRequestUser | undefined;+ item: SteerQueueItem;+ getFiles: SteerFileFetcher;+}): Promise<SteerMediaResult | undefined> {+ const ids = collectFileIds(item.files);+ const filter = buildOwnerFilter(ids, user);+ if (filter == null) {+ return undefined;+ }+ const rawDocs = await getFiles(filter, {}, {});+ if (!Array.isArray(rawDocs) || rawDocs.length === 0) {+ logger.warn(`[buildSteerMedia] No authorized files for steer=${item.steerId}`);+ return undefined;+ }+ const docsById = new Map(rawDocs.map((file) => [file.file_id, file]));+ const fileDocs = ids+ .map((id) => docsById.get(id))+ .filter((doc): doc is IMongoFile => doc != null);+ return encodeSteerContent({ client, text: item.text, steerId: item.steerId, fileDocs });+}++/**+ * Re-encodes attachments for persisted steer parts of PAST turns and stamps+ * the assembled content array as a transient `media` field, which the SDK's+ * `formatAgentMessages` prefers over the plain text when reconstructing the+ * steer's HumanMessage. Refs are re-encoded per turn — encoded data is never+ * persisted — and parts are replaced immutably so the stamp cannot leak into+ * a message save. Encodes run in parallel after doc resolution.+ *+ * `docsById` should be the owner-scoped doc map `addPreviousAttachments`+ * already fetched this turn (its single historical-files query collects+ * steer-part refs); when present, NO extra query is issued — an id missing+ * from the map is unauthorized or deleted, exactly as if the fallback query+ * had excluded it.+ */+export async function stampSteerPartMedia({+ client,+ user,+ payload,+ docsById,+ getFiles,+}: {+ client: SteerMediaClient;+ user: SteerRequestUser | undefined;+ payload: Array<{ role?: string; content?: unknown }>;+ docsById?: Map<string, IMongoFile>;+ getFiles: SteerFileFetcher;+}): Promise<StampedSteerMedia[]> {+ const stampTargets: Array<{+ message: { content?: unknown };+ part: SteerPart;+ index: number;+ }> = [];+ for (let index = 0; index < payload.length; index++) {+ const message = payload[index];+ if (message?.role !== 'assistant' || !Array.isArray(message.content)) {+ continue;+ }+ for (const part of message.content as SteerPart[]) {+ if (part?.type === ContentTypes.STEER && Array.isArray(part.files) && part.files.length > 0) {+ stampTargets.push({ message, part, index });+ }+ }+ }+ if (stampTargets.length === 0) {+ return [];+ }++ let resolvedDocsById = docsById;+ if (resolvedDocsById == null) {+ const allIds = collectFileIds(stampTargets.flatMap(({ part }) => part.files ?? []));+ const filter = buildOwnerFilter(allIds, user);+ if (filter == null) {+ return [];+ }+ const fileDocs = await getFiles(filter, {}, {});+ if (!Array.isArray(fileDocs) || fileDocs.length === 0) {+ return [];+ }+ resolvedDocsById = new Map(fileDocs.map((file) => [file.file_id, file]));+ }+ const docs = resolvedDocsById;++ const stamped = await Promise.all(+ stampTargets.map(async ({ message, part, index }) => {+ const partDocs = (part.files ?? [])+ .map((file) => (file?.file_id != null ? docs.get(file.file_id) : undefined))+ .filter((doc): doc is IMongoFile => doc != null);+ if (partDocs.length === 0) {+ return null;+ }+ try {+ const { content } = await encodeSteerContent({+ client,+ text: (part[ContentTypes.STEER] as string | undefined) ?? '',+ steerId: part.steerId ?? 'replay',+ fileDocs: partDocs,+ });+ message.content = (message.content as SteerPart[]).map((candidate) =>+ candidate === part ? { ...candidate, media: content } : candidate,+ );+ return {+ index,+ media: content,+ steerText: (part[ContentTypes.STEER] as string | undefined) ?? '',+ };+ } catch (error) {+ logger.warn(+ `[stampSteerPartMedia] Failed to re-encode steer media (steer=${part.steerId}); replaying text only`,+ error,+ );+ return null;+ }+ }),+ );+ return stamped.filter((entry): entry is StampedSteerMedia => entry != null);+}diff --git a/packages/api/src/agents/steering/offset.ts b/packages/api/src/agents/steering/offset.tsnew file mode 100644index 0000000000..91d67c1936--- /dev/null+++ b/packages/api/src/agents/steering/offset.ts@@ -0,0 +1,78 @@+import { GraphEvents } from '@librechat/agents';+import type { EventHandler } from '@librechat/agents';++/**+ * Shared mutable offset. The host increments `offset` each time a steer part+ * is spliced into the live content array; the wrapped handlers read it at+ * handle time so every SDK-emitted content index that arrives AFTER an+ * injection lands past the inserted part.+ */+export interface SteerOffsetState {+ offset: number;+}++/**+ * Wrap a run's event handlers so content indices shift by the CURRENT steer+ * offset. The mid-run analog of `createContentIndexOffsetHandlers` (HITL+ * resume): that wrapper closes over a fixed seed length, while this one reads+ * a mutable counter because steers arrive while the run is streaming.+ *+ * The index enters the pipeline at exactly one point: `ON_RUN_STEP`'s payload+ * (whose `index` every subsequent delta resolves through the aggregator's+ * step map). `ON_AGENT_UPDATE` carries its own inline index and is shifted+ * likewise. All other handlers pass through untouched. Installed even at+ * offset 0 — the first steer can arrive at any time. Steps the aggregator has+ * ALREADY indexed are unaffected (deltas/completions resolve by step id), so+ * injection at a tool-batch boundary never re-shifts the current batch.+ *+ * Composes with the resume wrapper: apply this OVER its output so a resumed+ * run shifts by seed + live steer offset.+ */+export function createSteerIndexOffsetHandlers(+ handlers: Record<string, EventHandler> | undefined,+ state: SteerOffsetState,+): Record<string, EventHandler> | undefined {+ if (handlers == null) {+ return handlers;+ }++ const wrapped: Record<string, EventHandler> = { ...handlers };++ const runStepHandler = handlers[GraphEvents.ON_RUN_STEP];+ if (runStepHandler) {+ wrapped[GraphEvents.ON_RUN_STEP] = {+ handle: (event, data, metadata, graph) => {+ const runStep = data as { index?: number } | undefined;+ if (runStep == null || typeof runStep.index !== 'number' || state.offset === 0) {+ return runStepHandler.handle(event, data, metadata, graph);+ }+ const shifted = { ...runStep, index: runStep.index + state.offset };+ return runStepHandler.handle(event, shifted as typeof data, metadata, graph);+ },+ };+ }++ const agentUpdateHandler = handlers[GraphEvents.ON_AGENT_UPDATE];+ if (agentUpdateHandler) {+ wrapped[GraphEvents.ON_AGENT_UPDATE] = {+ handle: (event, data, metadata, graph) => {+ const update = data as { agent_update?: { index?: number } } | undefined;+ const shifted =+ update?.agent_update != null &&+ typeof update.agent_update.index === 'number' &&+ state.offset > 0+ ? {+ ...update,+ agent_update: {+ ...update.agent_update,+ index: update.agent_update.index + state.offset,+ },+ }+ : data;+ return agentUpdateHandler.handle(event, shifted as typeof data, metadata, graph);+ },+ };+ }++ return wrapped;+}diff --git a/packages/api/src/agents/steering/refs.ts b/packages/api/src/agents/steering/refs.tsnew file mode 100644index 0000000000..3f8a31d347--- /dev/null+++ b/packages/api/src/agents/steering/refs.ts@@ -0,0 +1,59 @@+import type { TFile } from 'librechat-data-provider';+import type { SteerRequestUser } from './request';++/**+ * Copies the display-metadata fields a steer attachment ref may carry,+ * dropping everything else. The single source of truth for the ref shape —+ * used by the request sanitizer (untrusted client input) and the media+ * builder (trusted DB docs) alike; the per-field type checks are the+ * validation for the former and harmless for the latter. Only `file_id` is+ * ever meaningful server-side: the drain re-fetches owner-scoped and+ * re-derives everything else.+ *+ * Returns `null` when there is no usable `file_id`.+ */+export function toSteerFileRef(raw: unknown): Partial<TFile> | null {+ if (raw == null || typeof raw !== 'object') {+ return null;+ }+ const candidate = raw as Record<string, unknown>;+ if (typeof candidate.file_id !== 'string' || candidate.file_id.length === 0) {+ return null;+ }+ return {+ file_id: candidate.file_id,+ ...(typeof candidate.type === 'string' && { type: candidate.type }),+ ...(typeof candidate.filepath === 'string' && { filepath: candidate.filepath }),+ ...(typeof candidate.filename === 'string' && { filename: candidate.filename }),+ ...(typeof candidate.height === 'number' && { height: candidate.height }),+ ...(typeof candidate.width === 'number' && { width: candidate.width }),+ ...(typeof candidate.bytes === 'number' && { bytes: candidate.bytes }),+ };+}++/** Unique, order-preserving `file_id`s from a steer ref list. */+export function collectFileIds(files: Partial<TFile>[] | undefined): string[] {+ return [+ ...new Set(+ (files ?? [])+ .map((file) => file?.file_id)+ .filter((id): id is string => typeof id === 'string' && id.length > 0),+ ),+ ];+}++/** Owner-scoped `db.getFiles` filter shared by the enqueue-time resolve and+ * the injection/replay fetches; `null` when there is nothing to scope with. */+export function buildOwnerFilter(+ fileIds: string[],+ user: SteerRequestUser | undefined,+): Record<string, unknown> | null {+ if (!user?.id || fileIds.length === 0) {+ return null;+ }+ const filter: Record<string, unknown> = { file_id: { $in: fileIds }, user: user.id };+ if (user.tenantId) {+ filter.tenantId = user.tenantId;+ }+ return filter;+}diff --git a/packages/api/src/agents/steering/request.ts b/packages/api/src/agents/steering/request.tsnew file mode 100644index 0000000000..6acd9eaa33--- /dev/null+++ b/packages/api/src/agents/steering/request.ts@@ -0,0 +1,299 @@+import { randomUUID } from 'crypto';+import { logger } from '@librechat/data-schemas';+import type { TFile } from 'librechat-data-provider';+import type { SteerFileFetcher } from './media';+import { STEER_ENQUEUE_NOT_RUNNING, STEER_ENQUEUE_QUEUE_FULL } from '~/stream/interfaces/IJobStore';+import { toSteerFileRef, collectFileIds, buildOwnerFilter } from './refs';+import { GenerationJobManager } from '~/stream/GenerationJobManager';+import { isSteeringSupported } from './runtime';++/** Attachment cap per steer, mirroring the composer's practical limits. */+export const STEER_MAX_FILES = 10;++const DEFAULT_STEER_MAX_LENGTH = 16000;++/** Character cap for a single steer message (env-overridable). */+export function getSteerMaxLength(): number {+ return parseInt(process.env.STEER_MAX_LENGTH ?? '', 10) || DEFAULT_STEER_MAX_LENGTH;+}++export interface SteerRequestUser {+ id?: string;+ tenantId?: string;+}++export interface SteerRequestBody {+ conversationId?: unknown;+ text?: unknown;+ files?: unknown;+}++export interface SteerCancelBody {+ conversationId?: unknown;+ steerId?: unknown;+}++/** HTTP-shaped outcome the thin route wrapper serializes verbatim. */+export interface SteerRequestResult {+ status: number;+ body: Record<string, unknown>;+}++/** The originating run's identity, from job metadata (never the request). */+export interface SteerRunContext {+ agentId?: string;+ endpoint?: string;+}++/**+ * Host-injected dependencies for the steer guard ladder. All optional — a+ * host that omits them gets shape-level sanitization only (pre-round-13+ * behavior); the LibreChat route wires all three.+ */+export interface SteerRequestDeps {+ /** Owner-scoped file fetch (`db.getFiles`-shaped). When present, every+ * client-supplied ref must resolve to an owned DB doc at enqueue and the+ * queued refs are replaced with DB-derived ones. */+ getFiles?: SteerFileFetcher;+ /** Marks resolved uploads used so the upload-window TTL cannot reap a file+ * the persisted steer part references (parity with normal sends). */+ updateFilesUsage?: (+ files: Array<{ file_id: string }>,+ fileIds?: string[],+ options?: { user?: string; tenantId?: string | null },+ ) => Promise<unknown[]>;+ /** Agent authorization for the originating run (role + per-agent ACL),+ * mirroring the chat route's middlewares. `false` → 403 FORBIDDEN. */+ checkAgentAccess?: (run: SteerRunContext) => Promise<boolean>;+}++interface SanitizedFilesResult {+ files?: Partial<TFile>[];+ error?: 'TOO_MANY_FILES' | 'INVALID_FILES';+}++/** Sanitizes client-supplied attachment refs via the shared ref picker;+ * a single unusable entry rejects the whole list (fail-loud for the client). */+function sanitizeSteerFiles(rawFiles: unknown): SanitizedFilesResult {+ if (!Array.isArray(rawFiles) || rawFiles.length === 0) {+ return {};+ }+ if (rawFiles.length > STEER_MAX_FILES) {+ return { error: 'TOO_MANY_FILES' };+ }+ const files: Partial<TFile>[] = [];+ for (const raw of rawFiles) {+ const ref = toSteerFileRef(raw);+ if (ref == null) {+ return { error: 'INVALID_FILES' };+ }+ files.push(ref);+ }+ return { files };+}++interface ResolvedFilesResult {+ files?: Partial<TFile>[];+ fileIds?: string[];+ error?: 'INVALID_FILES';+}++/**+ * Resolves sanitized client refs against the DB owner-scoped (same scoping as+ * the injection-time fetch) and re-derives every ref from the owned doc, so+ * only trusted shapes are ever queued, persisted, and rendered. Any id that+ * does not resolve fails the whole list (fail-loud, matching sanitize).+ */+async function resolveSteerFiles(+ files: Partial<TFile>[],+ user: SteerRequestUser,+ getFiles: SteerFileFetcher,+): Promise<ResolvedFilesResult> {+ const ids = collectFileIds(files);+ const filter = buildOwnerFilter(ids, user);+ if (filter == null) {+ return { error: 'INVALID_FILES' };+ }+ const docs = await getFiles(filter, {}, {});+ const docsById = new Map((docs ?? []).map((doc) => [doc.file_id, doc]));+ const resolved: Partial<TFile>[] = [];+ for (const id of ids) {+ const doc = docsById.get(id);+ const ref = doc == null ? null : toSteerFileRef(doc);+ if (ref == null) {+ return { error: 'INVALID_FILES' };+ }+ resolved.push(ref);+ }+ return { files: resolved, fileIds: ids };+}++/** Untenanted jobs (pre-multi-tenancy) remain accessible if the userId check passes. */+function hasTenantMismatch(+ metadata: { tenantId?: string } | undefined,+ user: SteerRequestUser,+): boolean {+ return metadata?.tenantId != null && metadata.tenantId !== user.tenantId;+}++/**+ * The full steer-request guard ladder, typed and host-agnostic: validation,+ * capability gate, job ownership/state checks, and the status-guarded enqueue.+ * Returns the HTTP status + JSON body for the thin `/api` route wrapper.+ * Rejection codes tell the client how to degrade:+ * - 404 NO_ACTIVE_RUN → send as a normal message+ * - 409 RUN_PAUSED → run awaits human review; queue client-side instead+ * - 429 STEER_QUEUE_FULL → too many undrained steers+ * - 501 STEER_UNSUPPORTED → SDK cannot inject; queue client-side+ */+export async function handleSteerRequest(+ user: SteerRequestUser,+ body: SteerRequestBody,+ deps: SteerRequestDeps = {},+): Promise<SteerRequestResult> {+ const conversationId = body.conversationId;+ if (typeof conversationId !== 'string' || !conversationId || conversationId === 'new') {+ return { status: 400, body: { code: 'INVALID_CONVERSATION' } };+ }++ if (typeof body.text !== 'string') {+ return { status: 400, body: { code: 'EMPTY_TEXT' } };+ }+ const text = body.text.replace(/\0/g, '').trim();+ if (text.length === 0) {+ return { status: 400, body: { code: 'EMPTY_TEXT' } };+ }+ const maxLength = getSteerMaxLength();+ if (text.length > maxLength) {+ return { status: 413, body: { code: 'STEER_TOO_LONG', maxLength } };+ }++ const { files, error: filesError } = sanitizeSteerFiles(body.files);+ if (filesError) {+ return { status: 400, body: { code: filesError } };+ }++ /** streamId === conversationId for resumable agent jobs */+ const streamId = conversationId;+ const job = await GenerationJobManager.getJob(streamId);+ if (!job || job.status === 'complete' || job.status === 'error' || job.status === 'aborted') {+ return { status: 404, body: { code: 'NO_ACTIVE_RUN' } };+ }+ if (job.metadata?.userId && job.metadata.userId !== user.id) {+ logger.warn(`[handleSteerRequest] Unauthorized steer attempt for ${streamId} by ${user.id}`);+ return { status: 403, body: { code: 'UNAUTHORIZED' } };+ }+ if (hasTenantMismatch(job.metadata, user)) {+ return { status: 403, body: { code: 'UNAUTHORIZED' } };+ }++ /** A steer is model-bound instruction text for the ORIGINATING agent, so it+ * must clear the same role/ACL gates the chat path runs — revoked access+ * mid-run must not keep injecting. */+ if (deps.checkAgentAccess) {+ const allowed = await deps.checkAgentAccess({+ agentId: job.metadata?.agent_id,+ endpoint: job.metadata?.endpoint,+ });+ if (!allowed) {+ logger.warn(`[handleSteerRequest] Agent access denied for ${streamId} by ${user.id}`);+ return { status: 403, body: { code: 'FORBIDDEN' } };+ }+ }++ if (job.status === 'requires_action') {+ return { status: 409, body: { code: 'RUN_PAUSED' } };+ }++ /** AFTER the job checks: a steer racing run completion must get 404 (the+ * client sends immediately) — a 501 here would queue it client-side with+ * no remaining run-end signal to ever drain it. */+ if (!isSteeringSupported()) {+ return { status: 501, body: { code: 'STEER_UNSUPPORTED' } };+ }++ let queuedFiles = files;+ let resolvedFileIds: string[] | undefined;+ if (files && deps.getFiles) {+ const resolved = await resolveSteerFiles(files, user, deps.getFiles);+ if (resolved.error) {+ return { status: 400, body: { code: resolved.error } };+ }+ queuedFiles = resolved.files;+ resolvedFileIds = resolved.fileIds;+ }++ const item = {+ steerId: randomUUID(),+ text,+ userId: user.id ?? '',+ createdAt: Date.now(),+ ...(queuedFiles && { files: queuedFiles }),+ };+ const depth = await GenerationJobManager.steering.enqueue(streamId, item);+ if (depth === STEER_ENQUEUE_NOT_RUNNING) {+ return { status: 404, body: { code: 'NO_ACTIVE_RUN' } };+ }+ if (depth === STEER_ENQUEUE_QUEUE_FULL) {+ return { status: 429, body: { code: 'STEER_QUEUE_FULL' } };+ }++ /** Fire-and-forget: the persisted steer part references these uploads, so+ * mark them used (parity with `updateFilesUsage` on normal sends) or the+ * upload-window TTL could reap them before replay. Must not fail the 202. */+ if (resolvedFileIds?.length && deps.updateFilesUsage) {+ deps+ .updateFilesUsage(+ resolvedFileIds.map((file_id) => ({ file_id })),+ undefined,+ { user: user.id, tenantId: user.tenantId },+ )+ .catch((error) =>+ logger.warn(`[handleSteerRequest] Failed to mark steer files used: ${streamId}`, error),+ );+ }++ return {+ status: 202,+ body: { status: 'queued', steerId: item.steerId, position: depth, conversationId },+ };+}++/**+ * Cancel a queued steer before injection. `removed: false` is advisory, not+ * an error (200): the cancel lost its race — the steer already injected (the+ * inline part is authoritative) or the run reached a terminal path that owns+ * delivery — and the client should defer to the events it will receive. A+ * missing job reads the same way: nothing is left to cancel from.+ *+ * No `checkAgentAccess` dep here: a cancel injects nothing model-bound, so+ * job ownership/tenant checks suffice.+ */+export async function handleSteerCancel(+ user: SteerRequestUser,+ body: SteerCancelBody,+): Promise<SteerRequestResult> {+ const conversationId = body.conversationId;+ if (typeof conversationId !== 'string' || !conversationId || conversationId === 'new') {+ return { status: 400, body: { code: 'INVALID_CONVERSATION' } };+ }+ if (typeof body.steerId !== 'string' || body.steerId.length === 0) {+ return { status: 400, body: { code: 'INVALID_STEER_ID' } };+ }++ const streamId = conversationId;+ const job = await GenerationJobManager.getJob(streamId);+ if (!job) {+ return { status: 200, body: { removed: false } };+ }+ if (job.metadata?.userId && job.metadata.userId !== user.id) {+ logger.warn(`[handleSteerCancel] Unauthorized cancel attempt for ${streamId} by ${user.id}`);+ return { status: 403, body: { code: 'UNAUTHORIZED' } };+ }+ if (hasTenantMismatch(job.metadata, user)) {+ return { status: 403, body: { code: 'UNAUTHORIZED' } };+ }++ const removed = await GenerationJobManager.steering.cancel(streamId, body.steerId);+ return { status: 200, body: { removed } };+}diff --git a/packages/api/src/agents/steering/runtime.ts b/packages/api/src/agents/steering/runtime.tsnew file mode 100644index 0000000000..dbcdcf9367--- /dev/null+++ b/packages/api/src/agents/steering/runtime.ts@@ -0,0 +1,127 @@+import * as agentsSdk from '@librechat/agents';+import { logger } from '@librechat/data-schemas';+import type {+ HookCallback,+ HookInputByEvent,+ HookOutputByEvent,+ InjectedMessage,+} from '@librechat/agents';+import type { SteerQueueItem } from '~/stream/interfaces/IJobStore';+import { GenerationJobManager } from '~/stream/GenerationJobManager';++type SteerDrainOutput = HookOutputByEvent['PostToolBatch'];++/**+ * Whether the installed `@librechat/agents` supports the FULL steering+ * contract — both halves are required before any steer part may be created:+ * 1. `HOOK_INJECTED_MESSAGES_CAPABLE`: hook-returned `injectedMessages`+ * convert into graph-state HumanMessages at the PostToolBatch boundary+ * (draining the queue without this silently drops the user's words).+ * 2. `ContentTypes.STEER`: the SDK's `formatAgentMessages` replays persisted+ * steer parts as user turns on later prompts (the replay branch ships in+ * the same SDK commit as the enum member). Without it, a persisted steer+ * part would fall through the formatter's catch-all INTO the assistant's+ * provider content — so an SDK that can inject but not replay must still+ * 501 the steer route.+ * The pinned dependency (^3.2.62) carries both; the runtime probe stays (read+ * via the namespace so an older install yields `undefined` → false, not a+ * missing-binding failure) as the defensive gate for mismatched deployments.+ */+export function isSteeringSupported(): boolean {+ const sdk = agentsSdk as {+ HOOK_INJECTED_MESSAGES_CAPABLE?: boolean;+ ContentTypes?: { STEER?: string };+ };+ return sdk.HOOK_INJECTED_MESSAGES_CAPABLE === true && sdk.ContentTypes?.STEER === 'steer';+}++/** Encoded multimodal content for a steer that carried attachments. */+export interface SteerMediaResult {+ /** Full ordered content array for graph injection (text part included). */+ content: Array<Record<string, unknown>>;+ /** Validated file refs (from the DB, not the client). */+ files?: SteerQueueItem['files'];+}++export interface SteerDrainHookOptions {+ streamId: string;+ /**+ * The job's `createdAt` captured when this run was wired. A steer route can+ * only enqueue against the CURRENT job, so if the live job's `createdAt`+ * differs, this run was replaced — it must not consume the new job's steers.+ */+ jobCreatedAt?: number;+ /**+ * Applies one drained steer to host state — appends the steer content part+ * at the live content index, bumps the shared index offset, and emits the+ * `on_steer_applied` SSE event. Called FIFO, BEFORE the item's media encode:+ * once a steer leaves the durable queue, the part must be persisted before+ * any slow/abortable work, or an abort during the encode loses the user's+ * words (the terminal drain sees an empty queue and the content snapshot+ * lacks the part). Failures are logged per item and never block injection.+ */+ applySteer: (item: SteerQueueItem) => void | Promise<void>;+ /**+ * Resolves a steer's attachment refs into encoded model content (owner-scoped+ * fetch + provider encoding, host-side). Only consulted for items that carry+ * files. Any failure degrades that steer to text-only — the user's words are+ * never dropped because an attachment could not be encoded.+ */+ buildMedia?: (item: SteerQueueItem) => Promise<SteerMediaResult | undefined>;+}++/**+ * Build the run-scoped `PostToolBatch` hook that drains the job's steer queue+ * at each tool-batch boundary and injects each steer into graph state as its+ * own user message (`role: 'user'`, `source: 'steer'` — never consolidated+ * with hook context). Steers with attachments inject as multimodal content+ * arrays via `buildMedia`.+ *+ * Subagent scopes are skipped (`input.agentId` set): a steer targets the+ * top-level conversation, not a child agent's context. Hook errors are+ * swallowed by the SDK's `executeHooks`, so a broken drain can never kill the+ * run.+ */+export function createSteerDrainHook(opts: SteerDrainHookOptions): HookCallback<'PostToolBatch'> {+ const { streamId, jobCreatedAt, applySteer, buildMedia } = opts;+ return async (input: HookInputByEvent['PostToolBatch']): Promise<SteerDrainOutput> => {+ if (input.agentId != null) {+ return {};+ }+ // The replacement guard lives INSIDE the store's atomic drain: a separate+ // check-then-drain could still consume a replacement job's queue if+ // createJob landed between the two steps.+ const steers = await GenerationJobManager.steering.drain(streamId, jobCreatedAt);+ if (steers.length === 0) {+ return {};+ }+ const injectedMessages: InjectedMessage[] = [];+ for (const item of steers) {+ try {+ await applySteer(item);+ } catch (error) {+ logger.error(+ `[steering] Failed to apply steer part for ${streamId} steer=${item.steerId}:`,+ error,+ );+ }+ let media: SteerMediaResult | undefined;+ if (buildMedia != null && (item.files?.length ?? 0) > 0) {+ try {+ media = await buildMedia(item);+ } catch (error) {+ logger.error(+ `[steering] Failed to encode steer media for ${streamId} steer=${item.steerId}; injecting text only:`,+ error,+ );+ }+ }+ injectedMessages.push({+ role: 'user' as const,+ content: (media?.content ?? item.text) as InjectedMessage['content'],+ source: 'steer' as const,+ });+ }+ return { injectedMessages };+ };+}diff --git a/packages/api/src/files/index.ts b/packages/api/src/files/index.tsindex 0e9a23ff59..7cfc9aff13 100644--- a/packages/api/src/files/index.ts+++ b/packages/api/src/files/index.ts@@ -11,5 +11,6 @@ export * from './parse';export * from './rag';export * from './retention';export * from './sweep';+export * from './usage';export * from './validation';export * from './text';diff --git a/packages/api/src/files/usage.spec.ts b/packages/api/src/files/usage.spec.tsnew file mode 100644index 0000000000..59de9cbffd--- /dev/null+++ b/packages/api/src/files/usage.spec.ts@@ -0,0 +1,57 @@+import { handleFilesUsageRequest, FILES_USAGE_MAX_IDS } from './usage';++describe('handleFilesUsageRequest', () => {+ const user = { id: 'user-1', tenantId: 'tenant-1' };++ const createDeps = (marked: unknown[] = []) => ({+ updateFilesUsage: jest.fn().mockResolvedValue(marked),+ });++ it('rejects unauthenticated requests without touching the DB', async () => {+ const deps = createDeps();+ const result = await handleFilesUsageRequest({}, { file_ids: ['f1'] }, deps);+ expect(result).toEqual({ status: 401, body: { code: 'UNAUTHORIZED' } });+ expect(deps.updateFilesUsage).not.toHaveBeenCalled();+ });++ it.each([+ ['missing', {}],+ ['not an array', { file_ids: 'f1' }],+ ['empty', { file_ids: [] }],+ ['non-string entry', { file_ids: ['f1', 42] }],+ ['empty-string entry', { file_ids: [''] }],+ ])('rejects %s file_ids with 400', async (_label, body) => {+ const deps = createDeps();+ const result = await handleFilesUsageRequest(user, body, deps);+ expect(result.status).toBe(400);+ expect(result.body).toEqual({ code: 'INVALID_FILE_IDS' });+ expect(deps.updateFilesUsage).not.toHaveBeenCalled();+ });++ it('caps the list at FILES_USAGE_MAX_IDS', async () => {+ const deps = createDeps();+ const file_ids = Array.from({ length: FILES_USAGE_MAX_IDS + 1 }, (_, i) => `f${i}`);+ const result = await handleFilesUsageRequest(user, { file_ids }, deps);+ expect(result.status).toBe(400);+ expect(result.body).toEqual({ code: 'TOO_MANY_FILES', max: FILES_USAGE_MAX_IDS });+ expect(deps.updateFilesUsage).not.toHaveBeenCalled();+ });++ it('marks usage owner-scoped and returns best-effort 200', async () => {+ const deps = createDeps([{ file_id: 'f1' }]);+ const result = await handleFilesUsageRequest(user, { file_ids: ['f1', 'f2'] }, deps);+ expect(deps.updateFilesUsage).toHaveBeenCalledTimes(1);+ expect(deps.updateFilesUsage).toHaveBeenCalledWith(+ [{ file_id: 'f1' }, { file_id: 'f2' }],+ undefined,+ { user: 'user-1', tenantId: 'tenant-1' },+ );+ expect(result).toEqual({ status: 200, body: { marked: 1 } });+ });++ it('returns 200 with zero marked when no id resolves to an owned file', async () => {+ const deps = createDeps([]);+ const result = await handleFilesUsageRequest(user, { file_ids: ['not-owned'] }, deps);+ expect(result).toEqual({ status: 200, body: { marked: 0 } });+ });+});diff --git a/packages/api/src/files/usage.ts b/packages/api/src/files/usage.tsnew file mode 100644index 0000000000..fdb20127ed--- /dev/null+++ b/packages/api/src/files/usage.ts@@ -0,0 +1,62 @@+/** Cap per usage touch, mirroring the composer's practical attachment limit. */+export const FILES_USAGE_MAX_IDS: number = 10;++export interface FilesUsageUser {+ id?: string;+ tenantId?: string;+}++export interface FilesUsageBody {+ file_ids?: unknown;+}++/** HTTP-shaped outcome the thin route wrapper serializes verbatim. */+export interface FilesUsageResult {+ status: number;+ body: Record<string, unknown>;+}++export interface FilesUsageDeps {+ /** Owner-scoped usage marker (`db.updateFilesUsage`-shaped). */+ updateFilesUsage: (+ files: Array<{ file_id: string }>,+ fileIds?: string[],+ options?: { user?: string; tenantId?: string | null },+ ) => Promise<unknown[]>;+}++/**+ * Owner-scoped usage touch for attachments entering a client-side queue: a+ * queued message can outlive the upload window (long run, approval pause), so+ * marking at queue time stops the TTL from reaping files the drain will send.+ * Best-effort 200 — ids that do not resolve to an owned file are not errors+ * (send-time marking remains the backstop).+ */+export async function handleFilesUsageRequest(+ user: FilesUsageUser,+ body: FilesUsageBody,+ deps: FilesUsageDeps,+): Promise<FilesUsageResult> {+ if (!user.id) {+ return { status: 401, body: { code: 'UNAUTHORIZED' } };+ }+ const raw = body.file_ids;+ if (!Array.isArray(raw) || raw.length === 0) {+ return { status: 400, body: { code: 'INVALID_FILE_IDS' } };+ }+ if (raw.length > FILES_USAGE_MAX_IDS) {+ return { status: 400, body: { code: 'TOO_MANY_FILES', max: FILES_USAGE_MAX_IDS } };+ }+ const files: Array<{ file_id: string }> = [];+ for (const value of raw) {+ if (typeof value !== 'string' || value.length === 0) {+ return { status: 400, body: { code: 'INVALID_FILE_IDS' } };+ }+ files.push({ file_id: value });+ }+ const marked = await deps.updateFilesUsage(files, undefined, {+ user: user.id,+ tenantId: user.tenantId,+ });+ return { status: 200, body: { marked: marked.length } };+}diff --git a/packages/api/src/stream/GenerationJobManager.ts b/packages/api/src/stream/GenerationJobManager.tsindex d8005e8c6b..f6e304d989 100644--- a/packages/api/src/stream/GenerationJobManager.ts+++ b/packages/api/src/stream/GenerationJobManager.ts@@ -11,6 +11,7 @@ import type {TMessageContentParts,TContextUsageEvent,TTokenUsageEvent,+ TPendingSteer,Agents,} from 'librechat-data-provider';import type { StandardGraph } from '@librechat/agents';@@ -21,6 +22,7 @@ import type {AbortResult,IJobStore,} from './interfaces/IJobStore';+import type { SteerOwner, SteerContentView } from './SteeringLifecycle';import type { GenerationJobStore } from '~/app/metrics';import type * as t from '~/types';import {@@ -29,6 +31,11 @@ import {setGenerationJobsInFlight,recordGenerationJob,} from '~/app/metrics';+import {+ SteeringLifecycle,+ toPendingSteer,+ synthesizeAppliedSteerEvents,+} from './SteeringLifecycle';import { isPendingActionStale, isPendingActionExpired } from './interfaces/IJobStore';import { InMemoryEventTransport } from './implementations/InMemoryEventTransport';import { InMemoryJobStore } from './implementations/InMemoryJobStore';@@ -187,6 +194,8 @@ class GenerationJobManagerClass {private jobStore: IJobStore;/** Guarded human-review lifecycle (pause / resolve / expire) over the store. */private _approvals: ApprovalLifecycle;+ /** FIFO steering queue (enqueue / drain / peek / clear) over the store. */+ private _steering: SteeringLifecycle;/** Event pub/sub transport - swappable for Redis Pub/Sub, etc. */private eventTransport: IEventTransport;@@ -223,6 +232,7 @@ class GenerationJobManagerClass {this.jobStore =options?.jobStore ?? new InMemoryJobStore({ ttlAfterComplete: 0, maxJobs: 1000 });this._approvals = new ApprovalLifecycle(this.jobStore);+ this._steering = new SteeringLifecycle(this.jobStore);this.eventTransport = options?.eventTransport ?? new InMemoryEventTransport();this._cleanupOnComplete = options?.cleanupOnComplete ?? true;}@@ -282,6 +292,7 @@ class GenerationJobManagerClass {this.jobStore = services.jobStore;this._approvals = new ApprovalLifecycle(this.jobStore);+ this._steering = new SteeringLifecycle(this.jobStore);this.eventTransport = services.eventTransport;this._isRedis = services.isRedis ?? false;this._cleanupOnComplete = services.cleanupOnComplete ?? true;@@ -710,6 +721,28 @@ class GenerationJobManagerClass {this.runStepBuffers?.delete(streamId);this.replayEventWriteQueues.delete(streamId);this.tokenUsageWriteQueues.delete(streamId);+ // Backstop for direct terminal callers (init failures, unhandled errors)+ // that never ran the controllers' close-and-park: close the queue, then+ // park any 202-accepted leftovers for /chat/status claim-on-read instead+ // of silently clearing them. Paths that already drained find an empty+ // queue and no-op; the createdAt guard (re-checked inside the store's+ // atomic drain) keeps a stale completion off a replacement job's queue.+ // Runs BEFORE the terminal status write — the Redis terminal cleanup DELs+ // the queue key.+ try {+ const jobData = await this.jobStore.getJob(streamId);+ if (jobData) {+ const leftovers = (+ await this.jobStore.closeAndDrainSteers(streamId, jobData.createdAt)+ ).map(toPendingSteer);+ await this._steering.park(streamId, leftovers, {+ userId: jobData.userId,+ tenantId: jobData.tenantId,+ });+ }+ } catch (err) {+ logger.warn(`[GenerationJobManager] Failed to park leftover steers for ${streamId}:`, err);+ }// For error jobs, DON'T delete immediately - keep around so late-connecting// clients can receive the error. This handles the race condition where error@@ -803,6 +836,26 @@ class GenerationJobManagerClass {runtime.abortController.abort();}+ /** Steers that never reached an injection boundary — reported on the abort+ * final event (and the abort route's JSON) so the client can restore them+ * as queued chips instead of silently dropping the user's words. The+ * close-and-drain rejects any steer POST racing this finalization, and+ * the createdAt guard keeps it off a replacement job's queue. Runs+ * BEFORE the content snapshot below: a drain hook that already popped a+ * steer and applied its part gets captured by the snapshot, so the text+ * surfaces either here (pendingSteers) or there (inline part) — an+ * encode still in flight across the abort remains inherently racy+ * cross-instance, but the window no longer includes completed applies. */+ const pendingSteers = (+ await this.jobStore.closeAndDrainSteers(streamId, jobData.createdAt)+ ).map(toPendingSteer);+ // No-subscriber recovery: the abort response/final are transient, so park+ // the leftovers for /chat/status claim-on-read within the recovery TTL.+ await this.steering.park(streamId, pendingSteers, {+ userId: jobData.userId,+ tenantId: jobData.tenantId,+ });+/** Content before clearing state */const result = await this.jobStore.getContentParts(streamId);const content = result?.content ?? [];@@ -817,9 +870,10 @@ class GenerationJobManagerClass {/** Collected usage for all models */const collectedUsage = this.jobStore.getCollectedUsage(streamId);- /** Text from content parts for fallback token counting */+ /** Text from content parts for fallback token counting; the persisted+ * abort record keeps steered words (they reached the model context). */const text = shouldPersistAbortContent- ? parseTextParts(abortContent as TMessageContentParts[])+ ? parseTextParts(abortContent as TMessageContentParts[], false, { includeSteer: true }): '';/** Detect "early abort" - aborted before any generation happened (e.g., during tool loading)@@ -862,6 +916,7 @@ class GenerationJobManagerClass {aborted: true,// Flag for early abort - no messages saved, frontend should go to new chatearlyAbort: isEarlyAbort,+ ...(pendingSteers.length > 0 && { pendingSteers }),} satisfies t.FinalEvent as t.ServerSentEvent;if (runtime) {@@ -899,6 +954,7 @@ class GenerationJobManagerClass {finalEvent: abortFinalEvent,text,collectedUsage,+ ...(pendingSteers.length > 0 && { pendingSteers }),};}@@ -1113,8 +1169,8 @@ class GenerationJobManagerClass {// 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.+ const liveJob = await this.jobStore.getJob(streamId);if (!resumeState?.pendingAction) {- const liveJob = await this.jobStore.getJob(streamId);if (liveJob?.status === 'requires_action' &&liveJob.pendingAction != null &&@@ -1133,6 +1189,41 @@ class GenerationJobManagerClass {}}+ // Same snapshot→subscribe race for steers: a steer accepted (and possibly+ // applied) in the window is invisible to the snapshot, since the Redis+ // `on_steer_applied` publish is fire-and-forget and the sync payload has no+ // pendingSteers (in-memory covers it via the early buffer, where this+ // re-check is a cheap no-op). Always re-peek for still-active jobs,+ // treating a missing snapshot queue as empty; terminal jobs skip because+ // the final event owns steer delivery. The content re-read runs only when+ // the queue shows gap activity, and synthesis sources from the FRESH+ // content view so an applied steer with no snapshot id still surfaces.+ const jobActive = liveJob?.status === 'running' || liveJob?.status === 'requires_action';+ if (resumeState != null && jobActive) {+ const snapshotSteers = resumeState.pendingSteers ?? [];+ const liveQueue = await this.jobStore.peekSteers(streamId);+ const liveIds = new Set(liveQueue.map((item) => item.steerId));+ const queueChanged =+ liveQueue.length !== snapshotSteers.length ||+ snapshotSteers.some((steer) => !liveIds.has(steer.steerId));+ if (queueChanged) {+ const livePending = liveQueue.map(toPendingSteer);+ resumeState.pendingSteers = livePending.length > 0 ? livePending : undefined;+ }+ if (queueChanged || liveQueue.length > 0) {+ const contentResult = await this.jobStore.getContentParts(streamId);+ const gapEvents = synthesizeAppliedSteerEvents(+ (resumeState.aggregatedContent ?? []) as SteerContentView,+ liveQueue,+ (contentResult?.content ?? []) as SteerContentView,+ { conversationId: streamId, responseMessageId: resumeState.responseMessageId },+ );+ if (gapEvents.length > 0) {+ pendingEvents = [...pendingEvents, ...gapEvents];+ }+ }+ }+return { subscription, resumeState, pendingEvents };}@@ -1145,8 +1236,19 @@ class GenerationJobManagerClass {** In Redis mode, awaits the publish to guarantee event ordering.* This is critical for streaming deltas (tool args, message content) to arrive in order.+ *+ * `options.durable` additionally awaits the Redis chunk append BEFORE the+ * transport publish (still best-effort on failure): events whose durable+ * record is the recovery source (e.g. `on_steer_applied`) must be in the+ * chunk log before any subscriber can observe the publish, or a+ * cross-replica reconnect can reconstruct content without them. The default+ * stays fire-and-forget — no added latency on the per-delta hot path.*/- async emitChunk(streamId: string, event: t.ServerSentEvent): Promise<void> {+ async emitChunk(+ streamId: string,+ event: t.ServerSentEvent,+ options?: { durable?: boolean },+ ): Promise<void> {const runtime = this.runtimeState.get(streamId);if (!runtime || runtime.abortController.signal.aborted) {return;@@ -1173,14 +1275,20 @@ class GenerationJobManagerClass {if (eventType && eventData !== undefined) {// Store in format expected by aggregateContent: { event, data }- this.jobStore.appendChunk(streamId, { event: eventType, data: eventData }).catch((err) => {- logger.error(`[GenerationJobManager] Failed to append chunk:`, err);- });+ const appendPromise = this.jobStore+ .appendChunk(streamId, { event: eventType, data: eventData })+ .catch((err) => {+ logger.error(`[GenerationJobManager] Failed to append chunk:`, err);+ });// For run step events, also save to run steps key for quick retrievalif (eventType === 'on_run_step' || eventType === 'on_run_step_completed') {this.saveRunStepFromEvent(streamId, eventData as Record<string, unknown>);}++ if (options?.durable === true) {+ await appendPromise;+ }}}@@ -1561,6 +1669,19 @@ class GenerationJobManagerClass {return this._approvals;}+ /**+ * The FIFO steering queue for mid-run user messages:+ * `steering.enqueue()` / `drain()` / `peek()` / `clear()`.+ *+ * The steer route enqueues from any instance; the owning process's+ * run-scoped PostToolBatch hook drains at the next tool-batch boundary.+ * Finalization paths drain leftovers into the final/abort events so the+ * client can convert them to queued follow-ups.+ */+ get steering(): SteeringLifecycle {+ return this._steering;+ }+/*** Get resume state for reconnecting clients.*/@@ -1611,6 +1732,9 @@ class GenerationJobManagerClass {}}+ /** Steers still queued (not yet injected); injected ones are already in aggregatedContent. */+ const pendingSteers = (await this.jobStore.peekSteers(streamId)).map(toPendingSteer);+logger.debug(`[GenerationJobManager] getResumeState:`, {streamId,runStepsLength: runSteps.length,@@ -1638,6 +1762,7 @@ class GenerationJobManagerClass {jobData.status === 'requires_action' && !isPendingActionStale(jobData)? toClientPendingAction(jobData.pendingAction): undefined,+ pendingSteers: pendingSteers.length > 0 ? pendingSteers : undefined,};}@@ -1726,10 +1851,30 @@ class GenerationJobManagerClass {* if this call expired the action.*/async expireApproval(streamId: string, actionId?: string): Promise<boolean> {+ /** Steers accepted before the pause are frozen for its whole window+ * (enqueue rejects while `requires_action`), so this pre-CAS snapshot is+ * exactly what the expiry's terminal cleanup is about to delete. Read it+ * BEFORE the transition — the store drops the queue key inside it — and+ * park only if the CAS wins (a lost CAS means the run resumed and the+ * live queue must stay untouched). */+ let parkableSteers: TPendingSteer[] = [];+ let steerOwner: SteerOwner | undefined;+ try {+ const job = await this.jobStore.getJob(streamId);+ if (job) {+ steerOwner = { userId: job.userId, tenantId: job.tenantId };+ parkableSteers = (await this.jobStore.peekSteers(streamId)).map(toPendingSteer);+ }+ } catch (err) {+ logger.warn(`[GenerationJobManager] Failed to snapshot steers pre-expiry ${streamId}`, err);+ }const expired = await this._approvals.expire(streamId, actionId);if (!expired) {return false;}+ if (steerOwner && parkableSteers.length > 0) {+ await this.steering.park(streamId, parkableSteers, steerOwner);+ }try {await this.emitError(streamId, APPROVAL_EXPIRED_ERROR);} catch (err) {diff --git a/packages/api/src/stream/SteeringLifecycle.ts b/packages/api/src/stream/SteeringLifecycle.tsnew file mode 100644index 0000000000..7603f37bc7--- /dev/null+++ b/packages/api/src/stream/SteeringLifecycle.ts@@ -0,0 +1,213 @@+import { logger } from '@librechat/data-schemas';+import { ContentTypes, SteerEvents } from 'librechat-data-provider';+import type { TPendingSteer } from 'librechat-data-provider';+import type { IJobStore, SteerQueueItem } from '~/stream/interfaces/IJobStore';+import type { ServerSentEvent } from '~/types';++/** Client-safe projection of a queued steer (drops the server-only userId). */+export function toPendingSteer(item: SteerQueueItem): TPendingSteer {+ return {+ steerId: item.steerId,+ text: item.text,+ createdAt: item.createdAt,+ ...(item.files && item.files.length > 0 && { files: item.files }),+ };+}++/** Who a parked payload belongs to — the claim surface can outlive the job+ * record, so ownership must travel with the payload itself. */+export interface SteerOwner {+ userId: string;+ tenantId?: string;+}++interface ParkedSteers extends SteerOwner {+ steers: TPendingSteer[];+}++/** The exact JSON substring the stores gate the atomic claim on — matches the+ * `userId` member as {@link SteeringLifecycle.park} serializes it. */+export function toOwnerFragment(userId: string): string {+ return `"userId":${JSON.stringify(userId)}`;+}++/** Loosely-shaped content part for steer-id inspection across content views. */+export type SteerContentView = Array<{ type?: string; steerId?: string } | undefined>;++/**+ * Synthesize the `on_steer_applied` events a reconnecting subscriber missed in+ * the snapshot→subscribe window. Sourced from the FRESH content view, not the+ * snapshot queue: a steer accepted AND applied inside the gap never had a+ * snapshot id, so any steer part neither in the snapshot's applied set nor+ * still queued live was applied in the gap. Over-emitting a part the client+ * already holds is benign: re-delivery is idempotent client-side (applied-id+ * dedupe; the part is index-stable).+ */+export function synthesizeAppliedSteerEvents(+ snapshotContent: SteerContentView,+ liveQueue: SteerQueueItem[],+ freshContent: SteerContentView,+ meta: { conversationId: string; responseMessageId?: string },+): ServerSentEvent[] {+ const knownIds = new Set<string>();+ for (const part of snapshotContent) {+ if (part?.type === ContentTypes.STEER && part.steerId != null) {+ knownIds.add(part.steerId);+ }+ }+ for (const item of liveQueue) {+ knownIds.add(item.steerId);+ }+ const events: ServerSentEvent[] = [];+ for (let i = 0; i < freshContent.length; i++) {+ const part = freshContent[i];+ if (part?.type !== ContentTypes.STEER || part.steerId == null || knownIds.has(part.steerId)) {+ continue;+ }+ events.push({+ event: SteerEvents.ON_STEER_APPLIED,+ data: {+ steerId: part.steerId,+ index: i,+ part,+ conversationId: meta.conversationId,+ ...(meta.responseMessageId && { responseMessageId: meta.responseMessageId }),+ },+ } as ServerSentEvent);+ }+ return events;+}++/**+ * The FIFO queue of mid-run steering messages for a generation job.+ *+ * A steer is a user message submitted while a run is generating. The steer+ * route (any instance) enqueues it against the job; the owning process's+ * run-scoped `PostToolBatch` hook drains the queue at the next tool-batch+ * boundary and injects each entry into graph state as its own user message.+ *+ * Race-safety mirrors {@link ApprovalLifecycle}: enqueue is status-guarded in+ * the store (a steer can never land on a completed/aborted job — the caller+ * gets a rejection code instead), and drain is an atomic take-all so a steer+ * is delivered to exactly one drain. Steers left in the queue when the run+ * reaches a terminal state are drained by the finalization paths and reported+ * to the client, which converts them to queued follow-up turns.+ */+export class SteeringLifecycle {+ constructor(private readonly store: IJobStore) {}++ /**+ * Append a steer, guarded on the job being `running`. Returns the new queue+ * depth, or a rejection code ({@link STEER_ENQUEUE_NOT_RUNNING} /+ * {@link STEER_ENQUEUE_QUEUE_FULL}).+ */+ async enqueue(streamId: string, item: SteerQueueItem): Promise<number> {+ const depth = await this.store.enqueueSteer(streamId, item);+ if (depth > 0) {+ logger.debug(+ `[SteeringLifecycle] queued steer: ${streamId} steer=${item.steerId} depth=${depth}`,+ );+ }+ return depth;+ }++ /** Atomically take ALL queued steers, FIFO. `expectedCreatedAt` refuses the+ * drain inside the store when the job was replaced. */+ drain(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]> {+ return this.store.drainSteers(streamId, expectedCreatedAt);+ }++ /**+ * Terminal drain: atomically CLOSE the queue to new steers, then take all+ * queued items. Finalization paths use this so a steer POST racing the+ * final/abort event can never be ACKed after the last drain and then+ * silently cleared — once closed, enqueue rejects (the client falls back to+ * a normal send) until the next `createJob` reopens the stream id.+ * `expectedCreatedAt` keeps a stale run's finalization from closing or+ * stealing a replacement job's queue.+ */+ closeAndDrain(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]> {+ return this.store.closeAndDrainSteers(streamId, expectedCreatedAt);+ }++ /** Non-destructive FIFO read (status/resume surfaces). */+ peek(streamId: string): Promise<SteerQueueItem[]> {+ return this.store.peekSteers(streamId);+ }++ /**+ * User-cancelled before injection. Races with a drain settle inside the+ * store's atomic removal — `false` means the steer already injected (the+ * inline part is authoritative) or the run ended (the terminal paths own+ * delivery), and the cancel is simply too late.+ */+ cancel(streamId: string, steerId: string): Promise<boolean> {+ return this.store.removeSteer(streamId, steerId);+ }++ /** Drop any queued steers (terminal cleanup backstop). */+ clear(streamId: string): Promise<void> {+ return this.store.clearSteers(streamId);+ }++ /**+ * Parks terminally-drained leftovers under their own bounded-TTL store key+ * so a client with NO live subscriber (closed tab, reload racing the final+ * event) can still recover them via the status route — even after the+ * default `completeJob` path deletes the job record itself. The owner+ * identity travels WITH the payload for exactly that reason: the jobless+ * claim path has no job record left to authorize against. Live clients keep+ * using the final/abort event copy; recovery is idempotent (queued chips+ * dedupe by steer id).+ */+ async park(streamId: string, steers: TPendingSteer[], owner: SteerOwner): Promise<void> {+ if (steers.length === 0) {+ return;+ }+ const payload: ParkedSteers = {+ userId: owner.userId,+ ...(owner.tenantId != null && { tenantId: owner.tenantId }),+ steers,+ };+ try {+ await this.store.parkSteers(streamId, JSON.stringify(payload));+ } catch (error) {+ logger.warn(`[SteeringLifecycle] Failed to park leftover steers: ${streamId}`, error);+ }+ }++ /**+ * Claim-on-read: returns parked leftovers and clears them, so a second+ * reload cannot re-mint chips the user already dismissed. The user check+ * runs INSIDE the store's atomic claim (substring gate on the payload), so+ * a non-owner probe never deletes the payload — not even transiently. The+ * parse below stays authoritative (a steer text could embed the fragment);+ * a tenant mismatch re-parks so it cannot destroy the owner's recovery.+ */+ async claim(streamId: string, requester: SteerOwner): Promise<TPendingSteer[]> {+ let raw: string | undefined;+ try {+ raw = await this.store.claimParkedSteers(streamId, toOwnerFragment(requester.userId));+ } catch (error) {+ logger.warn(`[SteeringLifecycle] Failed to claim leftover steers: ${streamId}`, error);+ return [];+ }+ if (!raw) {+ return [];+ }+ try {+ const parsed = JSON.parse(raw) as ParkedSteers;+ const ownerMatch =+ parsed.userId === requester.userId &&+ (parsed.tenantId == null || parsed.tenantId === requester.tenantId);+ if (!ownerMatch) {+ await this.store.parkSteers(streamId, raw);+ return [];+ }+ return Array.isArray(parsed.steers) ? parsed.steers : [];+ } catch (error) {+ logger.warn(`[SteeringLifecycle] Failed to parse leftover steers: ${streamId}`, error);+ return [];+ }+ }+}diff --git a/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts b/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.tsindex 5dd3cfb164..99a43142f2 100644--- a/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts+++ b/packages/api/src/stream/__tests__/RedisJobStore.stream_integration.spec.ts@@ -1852,4 +1852,426 @@ describe('RedisJobStore Integration Tests', () => {await store.destroy();});});++ describe('Steering Queue', () => {+ function buildSteer(steerId: string, text: string) {+ return { steerId, text, userId: 'steer-user', createdAt: Date.now() };+ }++ test('enqueue is status-guarded and FIFO drain is atomic take-all', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const { STEER_ENQUEUE_NOT_RUNNING } = await import('../interfaces/IJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-fifo-${Date.now()}`;+ expect(await store.enqueueSteer(streamId, buildSteer('s0', 'no job'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );++ await store.createJob(streamId, 'steer-user', streamId);+ expect(await store.enqueueSteer(streamId, buildSteer('s1', 'first'))).toBe(1);+ expect(await store.enqueueSteer(streamId, buildSteer('s2', 'second'))).toBe(2);++ expect((await store.peekSteers(streamId)).map((s) => s.text)).toEqual(['first', 'second']);+ expect((await store.drainSteers(streamId)).map((s) => s.text)).toEqual(['first', 'second']);+ expect(await store.drainSteers(streamId)).toEqual([]);++ // Terminal job refuses new steers atomically (Lua status guard)+ await store.updateJob(streamId, { status: 'complete', completedAt: Date.now() });+ expect(await store.enqueueSteer(streamId, buildSteer('s3', 'late'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );++ await store.destroy();+ });++ test('enforces the queue depth cap', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const { STEER_ENQUEUE_QUEUE_FULL, STEER_QUEUE_MAX_DEPTH } = await import(+ '../interfaces/IJobStore'+ );+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-cap-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);++ for (let i = 0; i < STEER_QUEUE_MAX_DEPTH; i++) {+ expect(await store.enqueueSteer(streamId, buildSteer(`s${i}`, `text ${i}`))).toBe(i + 1);+ }+ expect(await store.enqueueSteer(streamId, buildSteer('overflow', 'too many'))).toBe(+ STEER_ENQUEUE_QUEUE_FULL,+ );++ await store.destroy();+ });++ test('closeAndDrain atomically closes the queue; createJob reopens and clears it', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const { STEER_ENQUEUE_NOT_RUNNING } = await import('../interfaces/IJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-close-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);+ await store.enqueueSteer(streamId, buildSteer('s1', 'drained'));++ const drained = await store.closeAndDrainSteers(streamId);+ expect(drained.map((s) => s.text)).toEqual(['drained']);++ // Job hash still says `running`, but the closed flag rejects the race.+ expect(await store.enqueueSteer(streamId, buildSteer('s2', 'raced'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );++ // Replacement reopens the channel and starts with an empty queue.+ await store.createJob(streamId, 'steer-user', streamId);+ expect(await store.peekSteers(streamId)).toEqual([]);+ expect(await store.enqueueSteer(streamId, buildSteer('s3', 'fresh'))).toBe(1);++ await store.destroy();+ });++ test('createJob clears steers inherited from a replaced job', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-replace-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);+ await store.enqueueSteer(streamId, buildSteer('s1', 'old run steer'));++ await store.createJob(streamId, 'steer-user', streamId);+ expect(await store.peekSteers(streamId)).toEqual([]);++ await store.destroy();+ });++ test('pausing for review extends the steers key TTL to the approval window', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-pause-ttl-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);+ await store.enqueueSteer(streamId, buildSteer('s1', 'kept across pause'));++ const paused = await store.transitionStatus(streamId, {+ from: 'running',+ to: 'requires_action',+ patch: { pendingAction: buildPendingAction(streamId) },+ });+ expect(paused).toBe(true);++ // Running TTL is 1200s; the paused window is >= the 24h backstop.+ const ttl = await ioredisClient.ttl(`stream:{${streamId}}:steers`);+ expect(ttl).toBeGreaterThan(1200);++ // The queued steer survives the pause for the resumed run to drain.+ expect((await store.peekSteers(streamId)).map((s) => s.text)).toEqual(['kept across pause']);++ await store.destroy();+ });++ test('terminal transitions and deleteJob remove the steers key', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-cleanup-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);+ await store.enqueueSteer(streamId, buildSteer('s1', 'leftover'));++ await store.updateJob(streamId, { status: 'aborted', completedAt: Date.now() });+ expect(await ioredisClient.exists(`stream:{${streamId}}:steers`)).toBe(0);++ // Recreate + enqueue, then hard delete+ await store.createJob(streamId, 'steer-user', streamId);+ await store.enqueueSteer(streamId, buildSteer('s2', 'leftover again'));+ await store.deleteJob(streamId);+ expect(await ioredisClient.exists(`stream:{${streamId}}:steers`)).toBe(0);++ await store.destroy();+ });++ test('removeSteer takes one item, keeps order, and preserves the list TTL', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-remove-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);+ await store.enqueueSteer(streamId, buildSteer('c1', 'keep me first'));+ await store.enqueueSteer(streamId, buildSteer('c2', 'cancel me'));+ await store.enqueueSteer(streamId, buildSteer('c3', 'keep me last'));++ expect(await store.removeSteer(streamId, 'c2')).toBe(true);+ expect(await store.removeSteer(streamId, 'c2')).toBe(false);+ expect((await store.peekSteers(streamId)).map((s) => s.steerId)).toEqual(['c1', 'c3']);+ expect(await ioredisClient.ttl(`stream:{${streamId}}:steers`)).toBeGreaterThan(0);++ await store.destroy();+ });++ test('parked steers survive deleteJob, claim exactly once, and reset on createJob', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-parked-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);+ const payload = JSON.stringify({+ userId: 'steer-user',+ steers: [{ steerId: 'p1', text: 'kept', createdAt: 1 }],+ });+ await store.parkSteers(streamId, payload);++ // Survives full job deletion (the default completeJob path)…+ await store.deleteJob(streamId);+ expect(await ioredisClient.exists(`stream:{${streamId}}:parked`)).toBe(1);+ // …under its own bounded TTL, not the job's lifecycle.+ expect(await ioredisClient.ttl(`stream:{${streamId}}:parked`)).toBeGreaterThan(0);++ // Claim-on-read: exactly once.+ expect(await store.claimParkedSteers(streamId, '"userId":"steer-user"')).toBe(payload);+ expect(await store.claimParkedSteers(streamId, '"userId":"steer-user"')).toBeUndefined();++ // A replacement run resets any parked payload atomically with creation.+ await store.parkSteers(streamId, payload);+ await store.createJob(streamId, 'steer-user', streamId);+ expect(await store.claimParkedSteers(streamId, '"userId":"steer-user"')).toBeUndefined();++ await store.destroy();+ });++ test('a non-owner claim leaves the parked payload untouched (atomic owner gate)', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-parked-owner-${Date.now()}`;+ const payload = JSON.stringify({+ userId: 'steer-user',+ steers: [{ steerId: 'p1', text: 'owner only', createdAt: 1 }],+ });+ await store.parkSteers(streamId, payload);++ // The Lua gate rejects WITHOUT deleting: no delete-then-re-park window+ // in which a concurrent owner claim would find nothing.+ expect(await store.claimParkedSteers(streamId, '"userId":"intruder"')).toBeUndefined();+ expect(await ioredisClient.get(`stream:{${streamId}}:parked`)).toBe(payload);++ // The owner still claims exactly once.+ expect(await store.claimParkedSteers(streamId, '"userId":"steer-user"')).toBe(payload);+ expect(await ioredisClient.exists(`stream:{${streamId}}:parked`)).toBe(0);++ await store.destroy();+ });++ test('expiry cleanup parks queued steers before the terminal transition drops the queue', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-expiry-park-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId, 'tenant-1');+ await store.enqueueSteer(streamId, buildSteer('s1', 'frozen across the pause'));++ // Pause on an ALREADY-expired action so the next cleanup pass reaps it+ // (mirrors how the requires_action index treats a lapsed approval).+ const expiredAction = { ...buildPendingAction(streamId), expiresAt: Date.now() - 1000 };+ const paused = await store.transitionStatus(streamId, {+ from: 'running',+ to: 'requires_action',+ patch: { pendingAction: expiredAction, pendingActionId: expiredAction.actionId },+ });+ expect(paused).toBe(true);++ await store.cleanup();++ // The job finalized (aborted) and the queue key is gone…+ const job = await store.getJob(streamId);+ expect(job?.status).toBe('aborted');+ expect(await ioredisClient.exists(`stream:{${streamId}}:steers`)).toBe(0);++ // …but the 202-accepted steer is claimable by its owner.+ const claimed = await store.claimParkedSteers(streamId, '"userId":"steer-user"');+ expect(claimed).toBeDefined();+ const parsed = JSON.parse(claimed as string) as {+ userId: string;+ tenantId?: string;+ steers: Array<{ steerId: string; text: string }>;+ };+ expect(parsed.userId).toBe('steer-user');+ expect(parsed.tenantId).toBe('tenant-1');+ expect(parsed.steers.map((s) => s.text)).toEqual(['frozen across the pause']);++ await store.destroy();+ });++ test('stale-running reap parks queued steers before deleting the job', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient, { runningTtl: 1 });+ await store.initialize();++ const streamId = `steer-stale-park-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId, 'tenant-1');+ await store.enqueueSteer(streamId, buildSteer('s1', 'crash survivor'));++ // Backdate creation past the running TTL so the next cleanup pass reaps+ // it via the stale-running branch (no finalization ever ran).+ await ioredisClient.hset(+ `stream:{${streamId}}:job`,+ 'createdAt',+ String(Date.now() - 10_000),+ );++ const cleaned = await store.cleanup();+ expect(cleaned).toBeGreaterThanOrEqual(1);+ expect(await store.getJob(streamId)).toBeNull();+ expect(await ioredisClient.exists(`stream:{${streamId}}:steers`)).toBe(0);++ const claimed = await store.claimParkedSteers(streamId, '"userId":"steer-user"');+ expect(claimed).toBeDefined();+ const parsed = JSON.parse(claimed as string) as {+ userId: string;+ tenantId?: string;+ steers: Array<{ steerId: string; text: string }>;+ };+ expect(parsed.userId).toBe('steer-user');+ expect(parsed.tenantId).toBe('tenant-1');+ expect(parsed.steers.map((s) => s.text)).toEqual(['crash survivor']);++ await store.destroy();+ });++ test('parkSteers falls back to a positive recovery TTL when completedTtl is 0', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient, { completedTtl: 0 });+ await store.initialize();++ const streamId = `steer-park-zero-ttl-${Date.now()}`;+ // `EX 0` would be rejected by Redis and silently kill recovery.+ await store.parkSteers(+ streamId,+ JSON.stringify({ userId: 'steer-user', steers: [{ steerId: 'p1', text: 'kept' }] }),+ );++ expect(await ioredisClient.exists(`stream:{${streamId}}:parked`)).toBe(1);+ expect(await ioredisClient.ttl(`stream:{${streamId}}:parked`)).toBeGreaterThan(0);++ await store.destroy();+ });++ test('getContentParts splices on_steer_applied chunks at their recorded index', async () => {+ if (!ioredisClient) {+ return;+ }++ const { RedisJobStore } = await import('../implementations/RedisJobStore');+ const store = new RedisJobStore(ioredisClient);+ await store.initialize();++ const streamId = `steer-recon-${Date.now()}`;+ await store.createJob(streamId, 'steer-user', streamId);++ const chunks = [+ {+ event: 'on_run_step',+ data: {+ id: 'step-1',+ index: 0,+ stepDetails: { type: 'message_creation', message_creation: {} },+ },+ },+ {+ event: 'on_message_delta',+ data: { id: 'step-1', delta: { content: { type: 'text', text: 'Before steer.' } } },+ },+ {+ event: 'on_steer_applied',+ data: {+ steerId: 'steer-1',+ index: 1,+ part: { type: 'steer', steer: 'change course', steerId: 'steer-1' },+ },+ },+ {+ event: 'on_run_step',+ data: {+ id: 'step-2',+ // Emitted with the already-shifted index (offset wrapper)+ index: 2,+ stepDetails: { type: 'message_creation', message_creation: {} },+ },+ },+ {+ event: 'on_message_delta',+ data: { id: 'step-2', delta: { content: { type: 'text', text: 'After steer.' } } },+ },+ ];+ for (const chunk of chunks) {+ await store.appendChunk(streamId, chunk);+ }++ const result = await store.getContentParts(streamId);+ expect(result).not.toBeNull();+ const parts = result!.content as Array<{ type?: string; steer?: string; text?: unknown }>;+ expect(parts).toHaveLength(3);+ expect(parts[1]).toMatchObject({ type: 'steer', steer: 'change course' });+ expect(parts[0]?.type).toBe('text');+ expect(parts[2]?.type).toBe('text');++ await store.destroy();+ });+ });});diff --git a/packages/api/src/stream/__tests__/staleJobReaping.spec.ts b/packages/api/src/stream/__tests__/staleJobReaping.spec.tsindex 003162af43..3b4b5b1d75 100644--- a/packages/api/src/stream/__tests__/staleJobReaping.spec.ts+++ b/packages/api/src/stream/__tests__/staleJobReaping.spec.ts@@ -124,6 +124,44 @@ describe('InMemoryJobStore - stale running-job failsafe', () => {await store.destroy();});+ it('parks 202-accepted steers before reaping a stale running job', async () => {+ const { InMemoryJobStore } = await import('../implementations/InMemoryJobStore');+ const store = new InMemoryJobStore({ ttlAfterComplete: 0, staleJobTimeout: 1000 });+ await store.initialize();++ await store.createJob('s1', 'u1', 's1', 'tenant-1');+ await store.enqueueSteer('s1', {+ steerId: 'sp1',+ text: 'crash survivor',+ userId: 'u1',+ createdAt: Date.now(),+ });++ const base = Date.now();+ const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(base + 5000);+ try {+ const removed = await store.cleanup();+ expect(removed).toBe(1);+ expect(await store.hasJob('s1')).toBe(false);++ // No finalization ever ran — the crashed run's queue must be claimable.+ const claimed = await store.claimParkedSteers('s1', '"userId":"u1"');+ expect(claimed).toBeDefined();+ const parsed = JSON.parse(claimed as string) as {+ userId: string;+ tenantId?: string;+ steers: Array<{ steerId: string; text: string }>;+ };+ expect(parsed.userId).toBe('u1');+ expect(parsed.tenantId).toBe('tenant-1');+ expect(parsed.steers.map((steer) => steer.text)).toEqual(['crash survivor']);+ } finally {+ nowSpy.mockRestore();+ }++ await store.destroy();+ });+it('reaps terminal jobs while leaving fresh running jobs intact', async () => {const { InMemoryJobStore } = await import('../implementations/InMemoryJobStore');const store = new InMemoryJobStore({ ttlAfterComplete: 0, staleJobTimeout: 60000 });diff --git a/packages/api/src/stream/__tests__/steering.spec.ts b/packages/api/src/stream/__tests__/steering.spec.tsnew file mode 100644index 0000000000..4f23e416d3--- /dev/null+++ b/packages/api/src/stream/__tests__/steering.spec.ts@@ -0,0 +1,692 @@+import { SteerEvents } from 'librechat-data-provider';+import type { TPendingSteer, Agents } from 'librechat-data-provider';+import type { SteerQueueItem } from '~/stream/interfaces/IJobStore';+import type { ResumeState, ServerSentEvent } from '~/types';+import {+ STEER_ENQUEUE_NOT_RUNNING,+ STEER_ENQUEUE_QUEUE_FULL,+ STEER_QUEUE_MAX_DEPTH,+} from '~/stream/interfaces/IJobStore';+import { PARKED_STEERS_TTL_MS, InMemoryJobStore } from '~/stream/implementations/InMemoryJobStore';+import { synthesizeAppliedSteerEvents, toPendingSteer } from '~/stream/SteeringLifecycle';+import { InMemoryEventTransport } from '~/stream/implementations/InMemoryEventTransport';+import { buildPendingAction, buildToolApprovalPayload } from '~/agents/hitl/policy';+import { GenerationJobManagerClass } from '~/stream/GenerationJobManager';++jest.spyOn(console, 'log').mockImplementation();++describe('SteeringLifecycle via GenerationJobManager.steering (in-memory)', () => {+ let manager: GenerationJobManagerClass;+ let jobStore: InMemoryJobStore;++ beforeEach(() => {+ manager = new GenerationJobManagerClass();+ jobStore = new InMemoryJobStore({ ttlAfterComplete: 60000 });+ manager.configure({+ jobStore,+ eventTransport: new InMemoryEventTransport(),+ isRedis: false,+ cleanupOnComplete: false,+ });+ manager.initialize();+ });++ afterEach(async () => {+ await manager.destroy();+ });++ let steerCounter = 0;+ function buildSteer(text: string, userId = 'user-1'): SteerQueueItem {+ steerCounter += 1;+ return {+ steerId: `steer-${steerCounter}`,+ text,+ userId,+ createdAt: Date.now(),+ };+ }++ describe('enqueue', () => {+ test('appends to a running job and returns the queue depth', async () => {+ const streamId = 'steer-enqueue';+ await manager.createJob(streamId, 'user-1');++ expect(await manager.steering.enqueue(streamId, buildSteer('one'))).toBe(1);+ expect(await manager.steering.enqueue(streamId, buildSteer('two'))).toBe(2);+ });++ test('rejects when the job does not exist', async () => {+ expect(await manager.steering.enqueue('nonexistent', buildSteer('x'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );+ });++ test('rejects when the job is paused for human review', async () => {+ const streamId = 'steer-paused';+ await manager.createJob(streamId, 'user-1');+ const payload = buildToolApprovalPayload([+ { name: 'shell', arguments: { command: 'ls' }, tool_call_id: 'call_abc' },+ ]);+ const action = buildPendingAction(payload, {+ streamId,+ conversationId: streamId,+ runId: 'run-1',+ responseMessageId: 'msg-1',+ });+ expect(await manager.approvals.pause(streamId, action)).toBe(true);++ expect(await manager.steering.enqueue(streamId, buildSteer('late'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );+ });++ test('rejects when the job is terminal', async () => {+ const streamId = 'steer-terminal';+ await manager.createJob(streamId, 'user-1');+ await manager.completeJob(streamId, 'boom');++ expect(await manager.steering.enqueue(streamId, buildSteer('late'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );+ });++ test('rejects past the max queue depth', async () => {+ const streamId = 'steer-full';+ await manager.createJob(streamId, 'user-1');++ for (let i = 0; i < STEER_QUEUE_MAX_DEPTH; i++) {+ expect(await manager.steering.enqueue(streamId, buildSteer(`s${i}`))).toBe(i + 1);+ }+ expect(await manager.steering.enqueue(streamId, buildSteer('overflow'))).toBe(+ STEER_ENQUEUE_QUEUE_FULL,+ );+ });+ });++ describe('drain / peek', () => {+ test('drain takes all items FIFO and empties the queue', async () => {+ const streamId = 'steer-drain';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('first'));+ await manager.steering.enqueue(streamId, buildSteer('second'));++ const drained = await manager.steering.drain(streamId);+ expect(drained.map((s) => s.text)).toEqual(['first', 'second']);+ expect(await manager.steering.drain(streamId)).toEqual([]);+ });++ test('peek is non-destructive', async () => {+ const streamId = 'steer-peek';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('kept'));++ expect((await manager.steering.peek(streamId)).map((s) => s.text)).toEqual(['kept']);+ expect((await manager.steering.peek(streamId)).map((s) => s.text)).toEqual(['kept']);+ expect((await manager.steering.drain(streamId)).map((s) => s.text)).toEqual(['kept']);+ });++ test('drain with a stale expectedCreatedAt refuses and preserves the queue', async () => {+ const streamId = 'steer-drain-stale';+ const job = await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('kept for the live run'));++ expect(await manager.steering.drain(streamId, job.createdAt - 1)).toEqual([]);+ expect((await manager.steering.peek(streamId)).map((s) => s.text)).toEqual([+ 'kept for the live run',+ ]);+ expect((await manager.steering.drain(streamId, job.createdAt)).map((s) => s.text)).toEqual([+ 'kept for the live run',+ ]);+ });+ });++ describe('cancel', () => {+ test('removes exactly the cancelled steer and preserves queue order', async () => {+ const streamId = 'steer-cancel';+ await manager.createJob(streamId, 'user-1');+ const first = buildSteer('first');+ const second = buildSteer('second');+ await manager.steering.enqueue(streamId, first);+ await manager.steering.enqueue(streamId, second);++ expect(await manager.steering.cancel(streamId, first.steerId)).toBe(true);+ expect((await manager.steering.peek(streamId)).map((s) => s.text)).toEqual(['second']);+ });++ test('returns false when the steer already left the queue', async () => {+ const streamId = 'steer-cancel-late';+ await manager.createJob(streamId, 'user-1');+ const steer = buildSteer('drained before cancel');+ await manager.steering.enqueue(streamId, steer);+ await manager.steering.drain(streamId);++ expect(await manager.steering.cancel(streamId, steer.steerId)).toBe(false);+ expect(await manager.steering.cancel('nonexistent', steer.steerId)).toBe(false);+ });+ });++ describe('closeAndDrain', () => {+ test('takes all items and rejects later enqueues until the stream id is reused', async () => {+ const streamId = 'steer-close';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('drained'));++ const drained = await manager.steering.closeAndDrain(streamId);+ expect(drained.map((s) => s.text)).toEqual(['drained']);++ // The job is still `running`, but the queue is closed — a steer racing+ // finalization must be rejected, not ACKed and then silently cleared.+ expect(await manager.steering.enqueue(streamId, buildSteer('raced'))).toBe(+ STEER_ENQUEUE_NOT_RUNNING,+ );++ // A replacement job on the same stream id reopens the channel.+ await manager.createJob(streamId, 'user-1');+ expect(await manager.steering.enqueue(streamId, buildSteer('fresh'))).toBe(1);+ });++ test('createJob clears steers inherited from a replaced job', async () => {+ const streamId = 'steer-replace';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('old run steer'));++ await manager.createJob(streamId, 'user-1');+ expect(await manager.steering.peek(streamId)).toEqual([]);+ });++ test('a stale run cannot close or steal a replacement queue', async () => {+ const streamId = 'steer-close-stale';+ const oldJob = await manager.createJob(streamId, 'user-1');+ // Distinct createdAt: replacement in the same millisecond is+ // indistinguishable by design (the guard keys on creation time).+ await new Promise((resolve) => setTimeout(resolve, 2));+ const newJob = await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('belongs to the new run'));++ // Old run finalizes late: guarded close must neither drain nor close.+ expect(await manager.steering.closeAndDrain(streamId, oldJob.createdAt)).toEqual([]);+ expect((await manager.steering.peek(streamId)).map((s) => s.text)).toEqual([+ 'belongs to the new run',+ ]);+ expect(await manager.steering.enqueue(streamId, buildSteer('still open'))).toBe(2);++ expect(+ (await manager.steering.closeAndDrain(streamId, newJob.createdAt)).map((s) => s.text),+ ).toEqual(['belongs to the new run', 'still open']);+ });+ });++ describe('park / claim (no-subscriber recovery)', () => {+ const owner = { userId: 'user-1' };++ test('parked leftovers are claimable exactly once', async () => {+ const streamId = 'steer-park';+ await manager.createJob(streamId, 'user-1');+ const leftovers: TPendingSteer[] = [+ { steerId: 'p1', text: 'unreceived words', createdAt: Date.now() },+ ];+ await manager.steering.park(streamId, leftovers, owner);++ expect(await manager.steering.claim(streamId, owner)).toEqual(leftovers);+ // Claim-on-read: a second reload cannot re-mint dismissed chips.+ expect(await manager.steering.claim(streamId, owner)).toEqual([]);+ });++ test('parked leftovers survive completeJob within the terminal TTL', async () => {+ const streamId = 'steer-park-terminal';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.park(+ streamId,+ [{ steerId: 'p2', text: 'post-terminal recovery', createdAt: Date.now() }],+ owner,+ );+ await manager.completeJob(streamId);++ expect((await manager.steering.claim(streamId, owner)).map((s) => s.steerId)).toEqual(['p2']);+ });++ test('parked leftovers survive the DEFAULT completeJob cleanup (job record deleted)', async () => {+ // Production default: cleanupOnComplete deletes the job record the+ // moment the run succeeds — recovery must not depend on it existing.+ const defaultManager = new GenerationJobManagerClass();+ defaultManager.configure({+ jobStore: new InMemoryJobStore({ ttlAfterComplete: 0 }),+ eventTransport: new InMemoryEventTransport(),+ isRedis: false,+ cleanupOnComplete: true,+ });+ defaultManager.initialize();+ try {+ const streamId = 'steer-park-deleted-job';+ await defaultManager.createJob(streamId, 'user-1');+ await defaultManager.steering.park(+ streamId,+ [{ steerId: 'p4', text: 'survives job deletion', createdAt: Date.now() }],+ owner,+ );+ await defaultManager.completeJob(streamId);++ expect(await defaultManager.getJob(streamId)).toBeFalsy();+ expect(+ (await defaultManager.steering.claim(streamId, owner)).map((s) => s.steerId),+ ).toEqual(['p4']);+ } finally {+ await defaultManager.destroy();+ }+ });++ test('a non-owner claim returns nothing and preserves the payload for the owner', async () => {+ const streamId = 'steer-park-foreign';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.park(+ streamId,+ [{ steerId: 'p5', text: 'not yours', createdAt: Date.now() }],+ owner,+ );++ expect(await manager.steering.claim(streamId, { userId: 'intruder' })).toEqual([]);+ expect((await manager.steering.claim(streamId, owner)).map((s) => s.steerId)).toEqual(['p5']);+ });++ test('a non-owner claim never deletes the payload, even transiently (no re-park)', async () => {+ const streamId = 'steer-park-atomic';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.park(+ streamId,+ [{ steerId: 'p6', text: 'owner only', createdAt: Date.now() }],+ owner,+ );++ // The owner gate runs INSIDE the store's atomic claim: a rejected probe+ // must not go through the old delete-then-re-park path, which briefly+ // left nothing for a concurrent owner claim.+ const parkSpy = jest.spyOn(manager.getJobStore(), 'parkSteers');+ expect(await manager.steering.claim(streamId, { userId: 'intruder' })).toEqual([]);+ expect(parkSpy).not.toHaveBeenCalled();+ expect((await manager.steering.claim(streamId, owner)).map((s) => s.steerId)).toEqual(['p6']);+ parkSpy.mockRestore();+ });++ test('periodic store cleanup sweeps expired parked steers', async () => {+ const store = new InMemoryJobStore({ ttlAfterComplete: 60000 });+ const base = Date.now();+ const nowSpy = jest.spyOn(Date, 'now').mockReturnValue(base);+ try {+ await store.parkSteers(+ 'steer-park-sweep',+ JSON.stringify({ userId: 'user-1', steers: [{ steerId: 'p7', text: 'stale' }] }),+ );+ nowSpy.mockReturnValue(base + PARKED_STEERS_TTL_MS + 1);+ await store.cleanup();+ // Back inside the window: had the sweep NOT removed the entry, this+ // claim would return it (expiry is otherwise only checked at read).+ nowSpy.mockReturnValue(base);+ expect(await store.claimParkedSteers('steer-park-sweep', '"userId":"user-1"')).toBe(+ undefined,+ );+ } finally {+ nowSpy.mockRestore();+ await store.destroy();+ }+ });++ test('a replacement run clears parked leftovers', async () => {+ const streamId = 'steer-park-replaced';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.park(+ streamId,+ [{ steerId: 'p3', text: 'stale', createdAt: Date.now() }],+ owner,+ );+ await manager.createJob(streamId, 'user-1');++ expect(await manager.steering.claim(streamId, owner)).toEqual([]);+ });++ test('approval expiry parks queued steers instead of deleting them', async () => {+ const streamId = 'steer-expire-park';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('frozen across the pause'));++ const payload = buildToolApprovalPayload([+ { name: 'shell', arguments: { command: 'ls' }, tool_call_id: 'call_exp' },+ ]);+ const action = buildPendingAction(payload, {+ streamId,+ conversationId: streamId,+ runId: 'run-exp',+ responseMessageId: 'msg-exp',+ });+ expect(await manager.approvals.pause(streamId, action)).toBe(true);++ expect(await manager.expireApproval(streamId, action.actionId)).toBe(true);+ expect((await manager.steering.claim(streamId, owner)).map((s) => s.text)).toEqual([+ 'frozen across the pause',+ ]);+ });+ });++ describe('terminal cleanup', () => {+ test('completeJob clears any leftover steers', async () => {+ const streamId = 'steer-complete';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('leftover'));++ await manager.completeJob(streamId);+ expect(await manager.steering.peek(streamId)).toEqual([]);+ });++ test('completeJob backstop parks 202-accepted steers instead of dropping them', async () => {+ // Direct error-path callers (init failures, unhandled generation errors)+ // reach completeJob WITHOUT the controllers' close-and-park — the+ // backstop itself must leave the words claimable via /chat/status.+ const streamId = 'steer-complete-error';+ await manager.createJob(streamId, 'user-1');+ const steer = buildSteer('survives the boom');+ await manager.steering.enqueue(streamId, steer);++ await manager.completeJob(streamId, 'boom');++ expect(await manager.steering.peek(streamId)).toEqual([]);+ expect(+ (await manager.steering.claim(streamId, { userId: 'user-1' })).map((s) => s.steerId),+ ).toEqual([steer.steerId]);+ });++ test('abortJob drains leftovers into pendingSteers on the result and final event', async () => {+ const streamId = 'steer-abort';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('unsent one'));+ await manager.steering.enqueue(streamId, buildSteer('unsent two'));++ const result = await manager.abortJob(streamId);+ expect(result.success).toBe(true);+ const steers = result.pendingSteers as TPendingSteer[];+ expect(steers.map((s) => s.text)).toEqual(['unsent one', 'unsent two']);+ expect(steers.every((s) => !('userId' in s))).toBe(true);+ expect(+ (result.finalEvent as { pendingSteers?: TPendingSteer[] }).pendingSteers?.map(+ (s) => s.text,+ ),+ ).toEqual(['unsent one', 'unsent two']);+ expect(await manager.steering.peek(streamId)).toEqual([]);+ });+ });++ describe('synthesizeAppliedSteerEvents (snapshot→subscribe gap)', () => {+ const meta = { conversationId: 'convo-gap', responseMessageId: 'msg-gap' };+ const queued = (steerId: string): SteerQueueItem => ({+ steerId,+ text: 'still queued',+ userId: 'user-1',+ createdAt: Date.now(),+ });++ test('re-surfaces the applied part for a steer that left the queue in the gap', () => {+ const appliedPart = { type: 'steer', steerId: 'g1', steer: 'applied in gap' };+ const fresh = [{ type: 'text' }, appliedPart, { type: 'text' }];++ const events = synthesizeAppliedSteerEvents([], [queued('g2')], fresh, meta);++ expect(events).toHaveLength(1);+ const event = events[0] as { event: string; data: Record<string, unknown> };+ expect(event.event).toBe(SteerEvents.ON_STEER_APPLIED);+ expect(event.data.steerId).toBe('g1');+ expect(event.data.index).toBe(1);+ expect(event.data.part).toBe(appliedPart);+ expect(event.data.conversationId).toBe('convo-gap');+ expect(event.data.responseMessageId).toBe('msg-gap');+ });++ test('synthesizes a steer accepted AND applied in the gap (no snapshot id at all)', () => {+ const appliedPart = { type: 'steer', steerId: 'g5', steer: 'gap only' };++ const events = synthesizeAppliedSteerEvents([], [], [appliedPart], meta);++ expect(events).toHaveLength(1);+ const event = events[0] as { event: string; data: Record<string, unknown> };+ expect(event.data.steerId).toBe('g5');+ expect(event.data.index).toBe(0);+ });++ test('emits nothing when no steer part landed in the gap (terminally drained instead)', () => {+ expect(synthesizeAppliedSteerEvents([], [], [{ type: 'text' }], meta)).toEqual([]);+ });++ test('skips a part already in the snapshot applied set (it rode the sync payload)', () => {+ const part = { type: 'steer', steerId: 'g6' };++ expect(synthesizeAppliedSteerEvents([part], [], [{ type: 'text' }, part], meta)).toEqual([]);+ });++ test('skips a steer still in the live queue', () => {+ const fresh = [{ type: 'steer', steerId: 'g4' }];++ expect(synthesizeAppliedSteerEvents([], [queued('g4')], fresh, meta)).toEqual([]);+ });+ });++ describe('subscribeWithResume steer-gap reconciliation', () => {+ function staleSnapshot(streamId: string, pendingSteers?: TPendingSteer[]): ResumeState {+ return {+ runSteps: [],+ aggregatedContent: [],+ conversationId: streamId,+ responseMessageId: 'msg-gap',+ ...(pendingSteers && { pendingSteers }),+ };+ }++ test('refreshes the snapshot when a steer was ADDED in the gap', async () => {+ const streamId = 'steer-gap-added';+ await manager.createJob(streamId, 'user-1');+ const kept = buildSteer('kept');+ const added = buildSteer('added in gap');+ await manager.steering.enqueue(streamId, kept);+ await manager.steering.enqueue(streamId, added);++ jest+ .spyOn(manager, 'getResumeState')+ .mockResolvedValue(staleSnapshot(streamId, [toPendingSteer(kept)]));++ const result = await manager.subscribeWithResume(streamId, jest.fn());+ expect(result.resumeState?.pendingSteers?.map((s) => s.steerId)).toEqual([+ kept.steerId,+ added.steerId,+ ]);+ expect(result.pendingEvents).toEqual([]);+ });++ test('reconciles an equal-length id swap (one drained + one added)', async () => {+ const streamId = 'steer-gap-swap';+ await manager.createJob(streamId, 'user-1');+ const drained = buildSteer('drained in gap');+ const added = buildSteer('added in gap');+ await manager.steering.enqueue(streamId, added);++ const appliedPart = {+ type: 'steer',+ steer: drained.text,+ steerId: drained.steerId,+ };+ manager.setContentParts(streamId, [appliedPart] as unknown as Agents.MessageContentComplex[]);++ jest+ .spyOn(manager, 'getResumeState')+ .mockResolvedValue(staleSnapshot(streamId, [toPendingSteer(drained)]));++ const result = await manager.subscribeWithResume(streamId, jest.fn());+ // Same length, different ids: the live projection must win…+ expect(result.resumeState?.pendingSteers?.map((s) => s.steerId)).toEqual([added.steerId]);+ // …and the drained steer's applied part is re-surfaced as a gap event.+ expect(result.pendingEvents).toHaveLength(1);+ const event = result.pendingEvents[0] as { event: string; data: Record<string, unknown> };+ expect(event.event).toBe(SteerEvents.ON_STEER_APPLIED);+ expect(event.data.steerId).toBe(drained.steerId);+ expect(event.data.index).toBe(0);+ });++ test('refreshes an EMPTY snapshot when a steer was accepted in the gap', async () => {+ const streamId = 'steer-gap-empty-accept';+ await manager.createJob(streamId, 'user-1');+ const accepted = buildSteer('accepted in gap');+ await manager.steering.enqueue(streamId, accepted);++ jest.spyOn(manager, 'getResumeState').mockResolvedValue(staleSnapshot(streamId));++ const result = await manager.subscribeWithResume(streamId, jest.fn());+ expect(result.resumeState?.pendingSteers?.map((s) => s.steerId)).toEqual([accepted.steerId]);+ expect(result.pendingEvents).toEqual([]);+ });++ test('synthesizes the applied part for a gap steer the snapshot never saw', async () => {+ const streamId = 'steer-gap-empty-applied';+ await manager.createJob(streamId, 'user-1');+ // Gap activity on an empty snapshot: the take-all drain applied one+ // steer, then another was accepted. The queue delta triggers the+ // content re-read that surfaces the never-snapshotted applied part.+ const applied = buildSteer('accepted and applied in gap');+ const queuedAfter = buildSteer('accepted after the drain');+ await manager.steering.enqueue(streamId, queuedAfter);+ manager.setContentParts(streamId, [+ { type: 'steer', steer: applied.text, steerId: applied.steerId },+ ] as unknown as Agents.MessageContentComplex[]);++ jest.spyOn(manager, 'getResumeState').mockResolvedValue(staleSnapshot(streamId));++ const result = await manager.subscribeWithResume(streamId, jest.fn());+ expect(result.resumeState?.pendingSteers?.map((s) => s.steerId)).toEqual([+ queuedAfter.steerId,+ ]);+ expect(result.pendingEvents).toHaveLength(1);+ const event = result.pendingEvents[0] as { event: string; data: Record<string, unknown> };+ expect(event.event).toBe(SteerEvents.ON_STEER_APPLIED);+ expect(event.data.steerId).toBe(applied.steerId);+ expect(event.data.index).toBe(0);+ });++ test('an unchanged empty queue skips the content re-read', async () => {+ const streamId = 'steer-gap-quiet';+ await manager.createJob(streamId, 'user-1');++ jest.spyOn(manager, 'getResumeState').mockResolvedValue(staleSnapshot(streamId));+ const readSpy = jest.spyOn(jobStore, 'getContentParts');++ const result = await manager.subscribeWithResume(streamId, jest.fn());+ expect(readSpy).not.toHaveBeenCalled();+ expect(result.resumeState?.pendingSteers).toBeUndefined();+ expect(result.pendingEvents).toEqual([]);+ });++ test('a terminal job skips steer reconciliation (the final event owns delivery)', async () => {+ const streamId = 'steer-gap-terminal';+ await manager.createJob(streamId, 'user-1');+ await manager.completeJob(streamId, 'done');++ jest.spyOn(manager, 'getResumeState').mockResolvedValue(staleSnapshot(streamId));+ const peekSpy = jest.spyOn(jobStore, 'peekSteers');++ const result = await manager.subscribeWithResume(streamId, jest.fn());+ expect(peekSpy).not.toHaveBeenCalled();+ expect(result.resumeState?.pendingSteers).toBeUndefined();+ expect(result.pendingEvents).toEqual([]);+ });+ });++ describe('resume state', () => {+ test('getResumeState carries still-queued steers as a client-safe projection', async () => {+ const streamId = 'steer-resume';+ await manager.createJob(streamId, 'user-1');+ await manager.steering.enqueue(streamId, buildSteer('pending on reconnect'));++ const state = await manager.getResumeState(streamId);+ expect(state?.pendingSteers?.map((s) => s.text)).toEqual(['pending on reconnect']);+ expect(state?.pendingSteers?.every((s) => !('userId' in s))).toBe(true);+ });++ test('getResumeState omits pendingSteers when the queue is empty', async () => {+ const streamId = 'steer-resume-empty';+ await manager.createJob(streamId, 'user-1');++ const state = await manager.getResumeState(streamId);+ expect(state?.pendingSteers).toBeUndefined();+ });+ });+});++describe('emitChunk durability (Redis-mode chunk log)', () => {+ const steerEvent: ServerSentEvent = {+ event: SteerEvents.ON_STEER_APPLIED,+ data: { steerId: 'durable-1', index: 0, part: { type: 'steer', steer: 'now' } },+ };++ function buildRedisModeManager(store: InMemoryJobStore, transport: InMemoryEventTransport) {+ const redisModeManager = new GenerationJobManagerClass();+ redisModeManager.configure({+ jobStore: store,+ eventTransport: transport,+ isRedis: true,+ cleanupOnComplete: false,+ });+ redisModeManager.initialize();+ return redisModeManager;+ }++ async function flushMicrotasks(times = 20): Promise<void> {+ for (let i = 0; i < times; i++) {+ await Promise.resolve();+ }+ }++ test('durable: true resolves only after the chunk append committed, before the publish', async () => {+ const store = new InMemoryJobStore({ ttlAfterComplete: 60000 });+ const transport = new InMemoryEventTransport();+ const redisModeManager = buildRedisModeManager(store, transport);+ try {+ const streamId = 'steer-durable';+ await redisModeManager.createJob(streamId, 'user-1');++ let resolveAppend!: () => void;+ const appendGate = new Promise<void>((resolve) => {+ resolveAppend = resolve;+ });+ jest.spyOn(store, 'appendChunk').mockReturnValue(appendGate);+ const publishSpy = jest.spyOn(transport, 'emitChunk');++ let settled = false;+ const emit = redisModeManager.emitChunk(streamId, steerEvent, { durable: true }).then(() => {+ settled = true;+ });++ await flushMicrotasks();+ expect(settled).toBe(false);+ expect(publishSpy).not.toHaveBeenCalled();++ resolveAppend();+ await emit;+ expect(settled).toBe(true);+ expect(publishSpy).toHaveBeenCalledWith(streamId, steerEvent);+ } finally {+ await redisModeManager.destroy();+ }+ });++ test('default emitChunk stays fire-and-forget (publishes without awaiting the append)', async () => {+ const store = new InMemoryJobStore({ ttlAfterComplete: 60000 });+ const transport = new InMemoryEventTransport();+ const redisModeManager = buildRedisModeManager(store, transport);+ try {+ const streamId = 'steer-fire-and-forget';+ await redisModeManager.createJob(streamId, 'user-1');++ // Never resolves: the per-delta hot path must not gate on durability.+ jest.spyOn(store, 'appendChunk').mockReturnValue(new Promise<void>(() => undefined));+ const publishSpy = jest.spyOn(transport, 'emitChunk');++ await redisModeManager.emitChunk(streamId, steerEvent);+ expect(publishSpy).toHaveBeenCalledWith(streamId, steerEvent);+ } finally {+ await redisModeManager.destroy();+ }+ });+});diff --git a/packages/api/src/stream/implementations/InMemoryJobStore.ts b/packages/api/src/stream/implementations/InMemoryJobStore.tsindex f8caf2b9ed..a56e4c6de3 100644--- a/packages/api/src/stream/implementations/InMemoryJobStore.ts+++ b/packages/api/src/stream/implementations/InMemoryJobStore.ts@@ -3,12 +3,22 @@ import type { StandardGraph } from '@librechat/agents';import type { Agents } from 'librechat-data-provider';import type {SerializableJobData,+ SteerQueueItem,UsageMetadata,IJobStore,JobStatus,JobStatusTransition,} from '~/stream/interfaces/IJobStore';-import { isPendingActionStale } from '~/stream/interfaces/IJobStore';+import {+ STEER_ENQUEUE_NOT_RUNNING,+ STEER_ENQUEUE_QUEUE_FULL,+ STEER_QUEUE_MAX_DEPTH,+ isPendingActionStale,+} from '~/stream/interfaces/IJobStore';+import { toPendingSteer } from '~/stream/SteeringLifecycle';++/** Recovery window for parked steers (mirrors Redis's completed-job TTL). */+export const PARKED_STEERS_TTL_MS: number = 5 * 60 * 1000;/*** Content state for a job - volatile, in-memory only.@@ -44,6 +54,16 @@ export class InMemoryJobStore implements IJobStore {*/private lastActivity = new Map<string, number>();+ /** Maps streamId -> FIFO queue of pending steer messages. */+ private steerQueues = new Map<string, SteerQueueItem[]>();++ /** Stream ids whose steer queue was closed by a terminal drain. Reopened by createJob. */+ private closedSteerQueues = new Set<string>();++ /** Parked terminally-drained steers — lifecycle-independent of `jobs` (the+ * default completeJob path deletes the job record immediately). */+ private parkedSteers = new Map<string, { payload: string; expiresAt: number }>();+/** Time to keep completed jobs before cleanup (0 = immediate) */private ttlAfterComplete = 0;@@ -112,6 +132,12 @@ export class InMemoryJobStore implements IJobStore {// (the controller handles job replacement) falls back to the fresh createdAt// and isn't reaped on the previous generation's stale last-activity time.this.lastActivity.delete(streamId);+ // Steer queues are keyed by streamId only, so a replacement must not+ // inherit the replaced run's undrained steers (or its closed flag), and+ // parked recovery belongs to the replaced run (a live client started this).+ this.steerQueues.delete(streamId);+ this.closedSteerQueues.delete(streamId);+ this.parkedSteers.delete(streamId);// Track job by userId (tenant-qualified when available) for efficient user-scoped queriesconst userKey = tenantId ? `${tenantId}:${userId}` : userId;@@ -169,6 +195,8 @@ export class InMemoryJobStore implements IJobStore {this.jobs.delete(streamId);this.contentState.delete(streamId);this.lastActivity.delete(streamId);+ this.steerQueues.delete(streamId);+ this.closedSteerQueues.delete(streamId);logger.debug(`[InMemoryJobStore] Deleted job: ${streamId}`);}@@ -202,6 +230,13 @@ export class InMemoryJobStore implements IJobStore {const toDelete: string[] = [];let staleRunning = 0;+ // Expired parked steers are otherwise only purged by a claim.+ for (const [streamId, parked] of this.parkedSteers) {+ if (parked.expiresAt <= now) {+ this.parkedSteers.delete(streamId);+ }+ }+for (const [streamId, job] of this.jobs) {const isFinished = ['complete', 'error', 'aborted'].includes(job.status);if (isFinished && job.completedAt) {@@ -214,6 +249,9 @@ export class InMemoryJobStore implements IJobStore {// finalize it (aborted) so it stops occupying the user slot and its// content state is reclaimed, mirroring ApprovalLifecycle.expire().// Skipping it (active-list filter) alone would leave it resident.+ // 202-accepted steers frozen across the pause are parked first —+ // deleting the job would silently drop them otherwise.+ this.parkQueuedSteers(streamId, job, now);job.status = 'aborted';job.completedAt = now;job.error = 'Approval expired before a decision was made';@@ -236,6 +274,9 @@ export class InMemoryJobStore implements IJobStore {job.createdAt,);if (now - lastActive > this.staleJobTimeout) {+ // A crashed/hung run never reached a finalization drain — park the+ // 202-accepted queue before the delete drops it.+ this.parkQueuedSteers(streamId, job, now);toDelete.push(streamId);staleRunning++;}@@ -322,6 +363,9 @@ export class InMemoryJobStore implements IJobStore {this.jobs.clear();this.contentState.clear();this.userJobMap.clear();+ this.steerQueues.clear();+ this.closedSteerQueues.clear();+ this.parkedSteers.clear();logger.debug('[InMemoryJobStore] Destroyed');}@@ -459,4 +503,103 @@ export class InMemoryJobStore implements IJobStore {clearContentState(streamId: string): void {this.contentState.delete(streamId);}++ // ===== Steering Queue Methods =====+ // Single-threaded event loop makes each read-check-write indivisible, so+ // the status guard and depth cap are exact without extra locking.++ async enqueueSteer(streamId: string, item: SteerQueueItem): Promise<number> {+ const job = this.jobs.get(streamId);+ if (!job || job.status !== 'running' || this.closedSteerQueues.has(streamId)) {+ return STEER_ENQUEUE_NOT_RUNNING;+ }+ let queue = this.steerQueues.get(streamId);+ if (!queue) {+ queue = [];+ this.steerQueues.set(streamId, queue);+ }+ if (queue.length >= STEER_QUEUE_MAX_DEPTH) {+ return STEER_ENQUEUE_QUEUE_FULL;+ }+ queue.push(item);+ return queue.length;+ }++ /** With `expectedCreatedAt`, refuses when the job was replaced — a stale+ * run's drain must never consume (or close) a replacement job's queue. */+ async drainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]> {+ if (expectedCreatedAt != null && this.jobs.get(streamId)?.createdAt !== expectedCreatedAt) {+ return [];+ }+ const queue = this.steerQueues.get(streamId);+ if (!queue || queue.length === 0) {+ return [];+ }+ return queue.splice(0);+ }++ async closeAndDrainSteers(+ streamId: string,+ expectedCreatedAt?: number,+ ): Promise<SteerQueueItem[]> {+ if (expectedCreatedAt != null && this.jobs.get(streamId)?.createdAt !== expectedCreatedAt) {+ return [];+ }+ this.closedSteerQueues.add(streamId);+ return this.drainSteers(streamId);+ }++ async peekSteers(streamId: string): Promise<SteerQueueItem[]> {+ const queue = this.steerQueues.get(streamId);+ return queue ? [...queue] : [];+ }++ async clearSteers(streamId: string): Promise<void> {+ this.steerQueues.delete(streamId);+ }++ async removeSteer(streamId: string, steerId: string): Promise<boolean> {+ const queue = this.steerQueues.get(streamId);+ const index = queue?.findIndex((item) => item.steerId === steerId) ?? -1;+ if (queue == null || index < 0) {+ return false;+ }+ queue.splice(index, 1);+ return true;+ }++ async parkSteers(streamId: string, payload: string): Promise<void> {+ this.parkedSteers.set(streamId, {+ payload,+ expiresAt: Date.now() + PARKED_STEERS_TTL_MS,+ });+ }++ /** Non-owner fragments leave the payload untouched (mirrors the Redis Lua gate). */+ async claimParkedSteers(streamId: string, ownerFragment: string): Promise<string | undefined> {+ const parked = this.parkedSteers.get(streamId);+ if (!parked || !parked.payload.includes(ownerFragment)) {+ return undefined;+ }+ this.parkedSteers.delete(streamId);+ return parked.expiresAt > Date.now() ? parked.payload : undefined;+ }++ /** Terminal cleanup (approval expiry, stale-running reap) must not drop+ * 202-accepted steers with the job. */+ private parkQueuedSteers(streamId: string, job: SerializableJobData, now: number): void {+ const queue = this.steerQueues.get(streamId);+ if (!queue || queue.length === 0) {+ return;+ }+ this.parkedSteers.set(streamId, {+ payload: JSON.stringify({+ userId: job.userId,+ ...(job.tenantId != null && { tenantId: job.tenantId }),+ steers: queue.map(toPendingSteer),+ }),+ expiresAt: now + PARKED_STEERS_TTL_MS,+ });+ this.steerQueues.delete(streamId);+ }}diff --git a/packages/api/src/stream/implementations/RedisJobStore.ts b/packages/api/src/stream/implementations/RedisJobStore.tsindex 6453ab4dcb..2d84f207ba 100644--- a/packages/api/src/stream/implementations/RedisJobStore.ts+++ b/packages/api/src/stream/implementations/RedisJobStore.ts@@ -1,16 +1,22 @@import { logger } from '@librechat/data-schemas';import { createContentAggregator } from '@librechat/agents';+import type { Agents, TPendingSteer } from 'librechat-data-provider';import type { StandardGraph } from '@librechat/agents';-import type { Agents } from 'librechat-data-provider';import type { Redis, Cluster } from 'ioredis';import type {SerializableJobData,+ SteerQueueItem,UsageMetadata,IJobStore,JobStatus,JobStatusTransition,} from '~/stream/interfaces/IJobStore';-import { isPendingActionStale } from '~/stream/interfaces/IJobStore';+import {+ STEER_ENQUEUE_NOT_RUNNING,+ STEER_QUEUE_MAX_DEPTH,+ isPendingActionStale,+} from '~/stream/interfaces/IJobStore';+import { toPendingSteer } from '~/stream/SteeringLifecycle';/*** Atomic compare-and-set on the job hash — the single-winner decision for a@@ -39,6 +45,30 @@ const JOB_CAS_LUA ='redis.call("EXPIRE", KEYS[1], ttl) ' +'return 1';+/**+ * Atomic job (re)creation for the two same-slot keys: reset the steer queue+ * and write the job hash in ONE script. A `/chat/steer` request can then+ * never interleave between the queue reset and the hash write — the enqueue+ * script observes either the old hash (its status guards apply and its list+ * dies with it) or the fully initialized replacement with an empty queue, so+ * a steer accepted against one run can never be drained into another.+ *+ * KEYS: [job, steers, parkedSteers]+ * ARGV: [ttl, hdelCount, ...hdelFields, ...hsetPairs]+ */+const JOB_CREATE_LUA =+ 'redis.call("DEL", KEYS[2]) ' ++ 'redis.call("DEL", KEYS[3]) ' ++ 'local ttl = tonumber(ARGV[1]) ' ++ 'local hdelCount = tonumber(ARGV[2]) ' ++ 'local idx = 3 ' ++ 'for i = 1, hdelCount do redis.call("HDEL", KEYS[1], ARGV[idx]) idx = idx + 1 end ' ++ 'local hset = {} ' ++ 'for i = idx, #ARGV do hset[#hset + 1] = ARGV[i] end ' ++ 'redis.call("HSET", KEYS[1], unpack(hset)) ' ++ 'redis.call("EXPIRE", KEYS[1], ttl) ' ++ 'return 1';+/*** XADD a chunk + set the chunk-stream TTL to the right window WITHOUT ever shrinking it.*@@ -104,9 +134,122 @@ const RUNSTEPS_SAVE_LUA ='redis.call("EXPIRE", KEYS[1], target) ' +'return 1';+/**+ * Atomically append a steer, guarded on the job hash still being `running`+ * AND the queue not being closed by a terminal drain (`steersClosed` field,+ * set by {@link STEER_CLOSE_DRAIN_LUA}, cleared on createJob). Both keys share+ * the {streamId} hash tag (single slot), so the script is atomic on cluster+ * too — a steer can never land on a completed/aborted/finalizing job, and the+ * depth cap can't be raced past by concurrent enqueues.+ *+ * KEYS: [job, steers]+ * ARGV: [itemJson, ttl, maxDepth]+ * Returns: new depth, -1 (not running / closed), or -2 (queue full)+ */+const STEER_ENQUEUE_LUA =+ 'if redis.call("HGET", KEYS[1], "status") ~= "running" then return -1 end ' ++ 'if redis.call("HGET", KEYS[1], "steersClosed") == "1" then return -1 end ' ++ 'if redis.call("LLEN", KEYS[2]) >= tonumber(ARGV[3]) then return -2 end ' ++ 'redis.call("RPUSH", KEYS[2], ARGV[1]) ' ++ 'redis.call("EXPIRE", KEYS[2], tonumber(ARGV[2])) ' ++ 'return redis.call("LLEN", KEYS[2])';++/**+ * Atomic take-all: read the whole queue FIFO and delete the key in one step,+ * so two concurrent drains can never both deliver the same steer. When an+ * expected `createdAt` is supplied, the drain is additionally guarded against+ * job replacement INSIDE the script — a stale run's hook can never consume a+ * replacement job's queue (the check-then-drain would otherwise race+ * `createJob`).+ *+ * KEYS: [job, steers]+ * ARGV: [expectedCreatedAt or ""]+ * Returns: array of item JSON strings (possibly empty)+ */+const STEER_DRAIN_LUA =+ 'if ARGV[1] ~= "" and redis.call("HGET", KEYS[1], "createdAt") ~= ARGV[1] then return {} end ' ++ 'local items = redis.call("LRANGE", KEYS[2], 0, -1) ' ++ 'redis.call("DEL", KEYS[2]) ' ++ 'return items';++/**+ * Remove ONE queued steer by id without disturbing the rest: the list is+ * rebuilt atomically, so a concurrent drain either delivers the steer or the+ * cancel wins — never a torn queue. ARGV[1] is the JSON fragment+ * `"steerId":"<id>"` matched as a plain substring against each serialized+ * item (ids are server-generated UUIDs, no escaping ambiguity). The list TTL+ * survives the rebuild.+ *+ * KEYS: [steers]+ * ARGV: [steerIdFragment]+ * Returns: 1 when removed, 0 when not found+ */+const STEER_REMOVE_LUA =+ 'local items = redis.call("LRANGE", KEYS[1], 0, -1) ' ++ 'if #items == 0 then return 0 end ' ++ 'local kept = {} ' ++ 'local removed = 0 ' ++ 'for i = 1, #items do ' ++ 'if removed == 0 and string.find(items[i], ARGV[1], 1, true) then removed = 1 ' ++ 'else kept[#kept + 1] = items[i] end ' ++ 'end ' ++ 'if removed == 0 then return 0 end ' ++ 'local ttl = redis.call("PTTL", KEYS[1]) ' ++ 'redis.call("DEL", KEYS[1]) ' ++ 'if #kept > 0 then ' ++ 'redis.call("RPUSH", KEYS[1], unpack(kept)) ' ++ 'if ttl > 0 then redis.call("PEXPIRE", KEYS[1], ttl) end ' ++ 'end ' ++ 'return 1';++/**+ * Claim-on-read for parked steers: return AND delete in one atomic step so a+ * second reload cannot re-mint chips the user already dismissed. The owner+ * gate runs INSIDE the same step — a payload not containing the requester's+ * `"userId":"…"` fragment (ARGV[1], plain-substring match) returns the empty+ * sentinel WITHOUT deleting, so a non-owner probe can never destroy the+ * owner's recovery, even transiently. Single key (cluster-safe); GETDEL is+ * avoided only for older-Redis compatibility.+ *+ * KEYS: [parkedSteers]+ * ARGV: [ownerFragment]+ * Returns: the parked payload JSON, '' when not the owner, or nil+ */+const CLAIM_PARKED_LUA =+ 'local v = redis.call("GET", KEYS[1]) ' ++ 'if not v then return v end ' ++ 'if not string.find(v, ARGV[1], 1, true) then return "" end ' ++ 'redis.call("DEL", KEYS[1]) ' ++ 'return v';++/**+ * Terminal close-then-drain in one atomic step: mark the queue closed on the+ * job hash (only when the hash still exists — a bare HSET would resurrect a+ * deleted job as a stray hash), then take the whole queue. Once closed,+ * {@link STEER_ENQUEUE_LUA} rejects, so a steer POST racing finalization can+ * never be ACKed after the last drain and then silently cleared. The same+ * expected-`createdAt` guard as {@link STEER_DRAIN_LUA} keeps a stale run's+ * finalization from closing (and stealing) a replacement job's queue.+ *+ * KEYS: [job, steers]+ * ARGV: [expectedCreatedAt or ""]+ * Returns: array of item JSON strings (possibly empty)+ */+const STEER_CLOSE_DRAIN_LUA =+ 'if ARGV[1] ~= "" and redis.call("HGET", KEYS[1], "createdAt") ~= ARGV[1] then return {} end ' ++ 'if redis.call("EXISTS", KEYS[1]) == 1 then redis.call("HSET", KEYS[1], "steersClosed", "1") end ' ++ 'local items = redis.call("LRANGE", KEYS[2], 0, -1) ' ++ 'redis.call("DEL", KEYS[2]) ' ++ 'return items';+/** Decision kinds the SDK can emit, used to sanity-check persisted records. */const KNOWN_INTERRUPT_TYPES = new Set(['tool_approval', 'ask_user_question']);+/** Recovery window (seconds) for parked steers when `completedTtl` is+ * configured to 0 — Redis rejects `EX 0`, which would silently kill+ * park-based recovery. */+const PARKED_RECOVERY_TTL_S: number = 300;+/*** Key prefixes for Redis storage.* All keys include the streamId for easy cleanup.@@ -124,6 +267,11 @@ const KEYS = {chunks: (streamId: string) => `stream:{${streamId}}:chunks`,/** Run steps: stream:{streamId}:runsteps */runSteps: (streamId: string) => `stream:{${streamId}}:runsteps`,+ /** Pending steer messages (FIFO list): stream:{streamId}:steers */+ steers: (streamId: string) => `stream:{${streamId}}:steers`,+ /** Parked terminally-drained steers (own TTL — must outlive the job hash,+ * which the default completeJob path deletes immediately) */+ parkedSteers: (streamId: string) => `stream:{${streamId}}:parked`,/** Running jobs set for cleanup (global set - single slot) */runningJobs: 'stream:running',/** Jobs paused for human review (global set - single slot) */@@ -215,6 +363,10 @@ export class RedisJobStore implements IJobStore {* For cross-replica abort, the abort handler falls back to text-based token counting.*/private localCollectedUsageCache = new Map<string, UsageMetadata[]>();+ /** Same-instance HOST content view (includes host-authored parts like+ * steers, which the SDK graph never sees). Preferred over the graph cache+ * on local reads; cross-instance reads reconstruct from chunks. */+ private localContentParts = new Map<string, WeakRef<Agents.MessageContentComplex[]>>();/** Cleanup interval in ms (1 minute) */private cleanupIntervalMs = 60000;@@ -292,14 +444,32 @@ export class RedisJobStore implements IJobStore {// its own discovery would otherwise inherit the prior run's tool names and force-load// deferred tools it never discovered on resume.'discoveredTools',+ // A replacement must start with an open steer channel — the closed flag+ // belongs to the finalized run this hash is being reused from.+ 'steersClosed',];// For cluster mode, we can't pipeline keys on different slots// The job key uses hash tag {streamId}, runningJobs and userJobs are on different slots+ // Steer-queue reset + job-hash write happen ATOMICALLY (same-slot Lua):+ // a steer POST can never land between them, so a replacement can neither+ // inherit the replaced run's undrained steers nor lose/steal a steer+ // 202-accepted against either run (see JOB_CREATE_LUA).+ const hsetPairs = Object.entries(this.serializeJob(job)).flat();+ await this.redis.eval(+ JOB_CREATE_LUA,+ 3,+ key,+ KEYS.steers(streamId),+ KEYS.parkedSteers(streamId),+ String(this.ttl.running),+ String(staleHitlFields.length),+ ...staleHitlFields,+ ...hsetPairs,+ );+ // Set-membership bookkeeping lives on other slots; ordering after the+ // atomic hash write is safe (scanners tolerate momentary lag).if (this.isCluster) {- await this.redis.hset(key, this.serializeJob(job));- await this.redis.hdel(key, ...staleHitlFields);- await this.redis.expire(key, this.ttl.running);await this.redis.sadd(KEYS.runningJobs, streamId);await this.redis.srem(KEYS.requiresActionJobs, streamId);await this.redis.sadd(userJobsKey, streamId);@@ -308,9 +478,6 @@ export class RedisJobStore implements IJobStore {}} else {const pipeline = this.redis.pipeline();- pipeline.hset(key, this.serializeJob(job));- pipeline.hdel(key, ...staleHitlFields);- pipeline.expire(key, this.ttl.running);pipeline.sadd(KEYS.runningJobs, streamId);pipeline.srem(KEYS.requiresActionJobs, streamId);pipeline.sadd(userJobsKey, streamId);@@ -373,6 +540,7 @@ export class RedisJobStore implements IJobStore {await this.redis.expire(key, this.ttl.completed);await this.redis.srem(KEYS.runningJobs, streamId);await this.redis.srem(KEYS.requiresActionJobs, streamId);+ await this.redis.del(KEYS.steers(streamId));if (this.ttl.chunksAfterComplete === 0) {await this.redis.del(KEYS.chunks(streamId));@@ -394,6 +562,7 @@ export class RedisJobStore implements IJobStore {pipeline.expire(key, this.ttl.completed);pipeline.srem(KEYS.runningJobs, streamId);pipeline.srem(KEYS.requiresActionJobs, streamId);+ pipeline.del(KEYS.steers(streamId));if (this.ttl.chunksAfterComplete === 0) {pipeline.del(KEYS.chunks(streamId));@@ -501,6 +670,10 @@ export class RedisJobStore implements IJobStore {}await this.redis.expire(KEYS.chunks(streamId), ttl);await this.redis.expire(KEYS.runSteps(streamId), ttl);+ // Steers queued before a pause must survive the whole approval window+ // (they inject at the first tool boundary after resume). EXPIRE on a+ // missing key is a no-op.+ await this.redis.expire(KEYS.steers(streamId), ttl);} else {const pipeline = this.redis.pipeline();if (remSet) {@@ -511,6 +684,7 @@ export class RedisJobStore implements IJobStore {}pipeline.expire(KEYS.chunks(streamId), ttl);pipeline.expire(KEYS.runSteps(streamId), ttl);+ pipeline.expire(KEYS.steers(streamId), ttl);await pipeline.exec();}return true;@@ -528,6 +702,7 @@ export class RedisJobStore implements IJobStore {async deleteJob(streamId: string): Promise<void> {this.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);const job = await this.getJob(streamId);const userJobsKey = job?.userId ? KEYS.userJobs(job.userId, job.tenantId) : null;@@ -536,6 +711,7 @@ export class RedisJobStore implements IJobStore {private async deleteJobInternal(streamId: string, userJobsKey: string | null): Promise<void> {this.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);if (this.isCluster) {@@ -543,6 +719,7 @@ export class RedisJobStore implements IJobStore {pipeline.del(KEYS.job(streamId));pipeline.del(KEYS.chunks(streamId));pipeline.del(KEYS.runSteps(streamId));+ pipeline.del(KEYS.steers(streamId));await pipeline.exec();await this.redis.srem(KEYS.runningJobs, streamId);await this.redis.srem(KEYS.requiresActionJobs, streamId);@@ -554,6 +731,7 @@ export class RedisJobStore implements IJobStore {pipeline.del(KEYS.job(streamId));pipeline.del(KEYS.chunks(streamId));pipeline.del(KEYS.runSteps(streamId));+ pipeline.del(KEYS.steers(streamId));pipeline.srem(KEYS.runningJobs, streamId);pipeline.srem(KEYS.requiresActionJobs, streamId);if (userJobsKey) {@@ -610,6 +788,7 @@ export class RedisJobStore implements IJobStore {await this.redis.srem(KEYS.runningJobs, streamId);await this.redis.srem(KEYS.requiresActionJobs, streamId);this.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);return 1;}@@ -618,6 +797,7 @@ export class RedisJobStore implements IJobStore {await this.redis.srem(KEYS.runningJobs, streamId);await this.redis.sadd(KEYS.requiresActionJobs, streamId);this.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);return 1;}@@ -632,6 +812,7 @@ export class RedisJobStore implements IJobStore {await this.redis.srem(KEYS.userJobs(job.userId, job.tenantId), streamId);}this.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);return 1;}@@ -642,6 +823,14 @@ export class RedisJobStore implements IJobStore {const liveSince = job.lastActiveAt ?? job.createdAt;if (now - liveSince > this.ttl.running * 1000) {logger.warn(`[RedisJobStore] Cleaning up stale job: ${streamId}`);+ // A crashed/hung run never reached a finalization drain — park the+ // 202-accepted queue before the delete drops it, so the owner can+ // still recover the words via /chat/status.+ await this.parkSteerSnapshot(+ streamId,+ job,+ await this.snapshotParkableSteers(streamId),+ );const userJobsKey = job.userId ? KEYS.userJobs(job.userId, job.tenantId) : null;await this.deleteJobInternal(streamId, userJobsKey);return 1;@@ -682,6 +871,7 @@ export class RedisJobStore implements IJobStore {if (!job) {await this.redis.srem(KEYS.requiresActionJobs, streamId);this.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);return 1;}@@ -700,7 +890,12 @@ export class RedisJobStore implements IJobStore {// transitionStatus runs the terminal content cleanup (sets, chunks,// run-steps, userJobs, completed TTL).if (isPendingActionStale(job)) {- await this.transitionStatus(streamId, {+ // Snapshot 202-accepted steers BEFORE the terminal cleanup DELs the+ // queue key; enqueue is frozen while paused, so this is exact.+ // Parked only if the CAS wins — a lost CAS means the run resumed+ // and the live queue must stay untouched.+ const parkableSteers = await this.snapshotParkableSteers(streamId);+ const expired = await this.transitionStatus(streamId, {from: 'requires_action',to: 'aborted',clear: ['pendingAction', 'pendingActionId'],@@ -715,6 +910,9 @@ export class RedisJobStore implements IJobStore {// to protect — so it falls back to the status-only check.)expectActionId: job.pendingAction?.actionId,});+ if (expired) {+ await this.parkSteerSnapshot(streamId, job, parkableSteers);+ }return 1;}@@ -853,13 +1051,47 @@ export class RedisJobStore implements IJobStore {this.localGraphCache.set(streamId, new WeakRef(graph));}+ /** Splice-inserts host-authored steer parts (from `on_steer_applied`+ * chunks) into an SDK-graph content view, ascending by recorded index so+ * each host-view position lands exactly where live clients saw it. */+ private async overlayHostSteerParts(+ streamId: string,+ parts: Agents.MessageContentComplex[],+ ): Promise<Agents.MessageContentComplex[]> {+ const chunks = await this.getChunks(streamId);+ if (chunks.length === 0) {+ return parts;+ }+ const steers: Array<{ index: number; part: Agents.MessageContentComplex }> = [];+ for (const chunk of chunks) {+ const event = chunk as { event?: string; data?: unknown };+ if (event.event !== 'on_steer_applied') {+ continue;+ }+ const steerData = event.data as { index?: number; part?: Agents.MessageContentComplex };+ if (typeof steerData.index === 'number' && steerData.part != null) {+ steers.push({ index: steerData.index, part: steerData.part });+ }+ }+ if (steers.length === 0) {+ return parts;+ }+ steers.sort((a, b) => a.index - b.index);+ const merged = [...parts];+ for (const steer of steers) {+ merged.splice(Math.min(steer.index, merged.length), 0, steer.part);+ }+ return merged;+ }+/**- * No-op for Redis - content parts are reconstructed from chunks.- * Metadata (agentId, groupId) is embedded directly on content parts by the agent runtime.+ * Cache the HOST-authored content array (WeakRef; owned by the run closure).+ * This is the authoritative same-instance view: host-only parts (steers)+ * live here but never inside the SDK graph, so preferring it over the graph+ * cache keeps same-instance reconnect/abort/status reads steer-complete.*/- setContentParts(): void {- // Content parts are reconstructed from chunks during getContentParts- // No separate storage needed+ setContentParts(streamId: string, contentParts: Agents.MessageContentComplex[]): void {+ this.localContentParts.set(streamId, new WeakRef(contentParts));}/**@@ -892,7 +1124,23 @@ export class RedisJobStore implements IJobStore {async getContentParts(streamId: string): Promise<{content: Agents.MessageContentComplex[];} | null> {- // 1. Try local graph cache first (fast path for same-instance reconnect)+ // 1. Prefer the HOST content array (same-instance fast path): it already+ // contains host-authored steer parts the SDK graph never sees.+ const hostRef = this.localContentParts.get(streamId);+ if (hostRef) {+ const hostParts = hostRef.deref();+ if (hostParts && hostParts.length > 0) {+ return { content: hostParts };+ }+ if (!hostParts) {+ this.localContentParts.delete(streamId);+ }+ }++ // 2. Local graph cache (runs wired before setContentParts): the SDK view+ // lacks host-authored steer parts, so overlay them from the chunk log —+ // insert (not assign): the graph array is UNSHIFTED, while recorded steer+ // indices are host-view positions that already account for prior steers.const graphRef = this.localGraphCache.get(streamId);if (graphRef) {const graph = graphRef.deref();@@ -900,7 +1148,7 @@ export class RedisJobStore implements IJobStore {const localParts = graph.getContentParts();if (localParts && localParts.length > 0) {return {- content: localParts,+ content: await this.overlayHostSteerParts(streamId, localParts),};}} else {@@ -930,7 +1178,23 @@ export class RedisJobStore implements IJobStore {for (const chunk of chunks) {const event = chunk as { event?: string; data?: unknown };- if (!event.event || !event.data || !validEvents.has(event.event)) {+ if (!event.event || !event.data) {+ continue;+ }++ // Steer parts are host-authored (the SDK aggregator doesn't know the+ // event), so splice them at their recorded index — SDK events after the+ // injection were emitted with already-shifted indices, so both sources+ // land disjoint.+ if (event.event === 'on_steer_applied') {+ const steerData = event.data as { index?: number; part?: Agents.MessageContentComplex };+ if (typeof steerData.index === 'number' && steerData.part != null) {+ contentParts[steerData.index] = steerData.part;+ }+ continue;+ }++ if (!validEvents.has(event.event)) {continue;}@@ -996,6 +1260,7 @@ export class RedisJobStore implements IJobStore {clearContentState(streamId: string): void {// Clear local caches immediatelythis.localGraphCache.delete(streamId);+ this.localContentParts.delete(streamId);this.localCollectedUsageCache.delete(streamId);// Fire and forget - async cleanup for Redis@@ -1014,6 +1279,140 @@ export class RedisJobStore implements IJobStore {await pipeline.exec();}+ // ===== Steering Queue Methods =====++ async enqueueSteer(streamId: string, item: SteerQueueItem): Promise<number> {+ const result = await this.redis.eval(+ STEER_ENQUEUE_LUA,+ 2,+ KEYS.job(streamId),+ KEYS.steers(streamId),+ JSON.stringify(item),+ String(this.ttl.running),+ String(STEER_QUEUE_MAX_DEPTH),+ );+ if (typeof result !== 'number') {+ return STEER_ENQUEUE_NOT_RUNNING;+ }+ return result;+ }++ async drainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]> {+ const raw = await this.redis.eval(+ STEER_DRAIN_LUA,+ 2,+ KEYS.job(streamId),+ KEYS.steers(streamId),+ expectedCreatedAt != null ? String(expectedCreatedAt) : '',+ );+ return this.parseSteerItems(raw);+ }++ async closeAndDrainSteers(+ streamId: string,+ expectedCreatedAt?: number,+ ): Promise<SteerQueueItem[]> {+ const raw = await this.redis.eval(+ STEER_CLOSE_DRAIN_LUA,+ 2,+ KEYS.job(streamId),+ KEYS.steers(streamId),+ expectedCreatedAt != null ? String(expectedCreatedAt) : '',+ );+ return this.parseSteerItems(raw);+ }++ async peekSteers(streamId: string): Promise<SteerQueueItem[]> {+ const raw = await this.redis.lrange(KEYS.steers(streamId), 0, -1);+ return this.parseSteerItems(raw);+ }++ async clearSteers(streamId: string): Promise<void> {+ await this.redis.del(KEYS.steers(streamId));+ }++ async removeSteer(streamId: string, steerId: string): Promise<boolean> {+ const removed = (await this.redis.eval(+ STEER_REMOVE_LUA,+ 1,+ KEYS.steers(streamId),+ `"steerId":"${steerId}"`,+ )) as number;+ return removed === 1;+ }++ async parkSteers(streamId: string, payload: string): Promise<void> {+ const ttl = this.ttl.completed > 0 ? this.ttl.completed : PARKED_RECOVERY_TTL_S;+ await this.redis.set(KEYS.parkedSteers(streamId), payload, 'EX', ttl);+ }++ /** Best-effort FIFO snapshot of the queued steers as client projections. */+ private async snapshotParkableSteers(streamId: string): Promise<TPendingSteer[]> {+ try {+ return (await this.peekSteers(streamId)).map(toPendingSteer);+ } catch (err) {+ logger.warn(`[RedisJobStore] Failed to snapshot steers for parking ${streamId}:`, err);+ return [];+ }+ }++ /**+ * Parks an owner-carrying snapshot so /chat/status can recover 202-accepted+ * steers after the job record is gone (approval expiry, stale-running reap).+ * Best-effort: a park failure must not block the cleanup path that called it.+ */+ private async parkSteerSnapshot(+ streamId: string,+ job: SerializableJobData,+ steers: TPendingSteer[],+ ): Promise<void> {+ if (steers.length === 0) {+ return;+ }+ try {+ await this.parkSteers(+ streamId,+ JSON.stringify({+ userId: job.userId,+ ...(job.tenantId != null && { tenantId: job.tenantId }),+ steers,+ }),+ );+ } catch (err) {+ logger.warn(`[RedisJobStore] Failed to park steers ${streamId}:`, err);+ }+ }++ async claimParkedSteers(streamId: string, ownerFragment: string): Promise<string | undefined> {+ const claimed = (await this.redis.eval(+ CLAIM_PARKED_LUA,+ 1,+ KEYS.parkedSteers(streamId),+ ownerFragment,+ )) as string | null;+ // '' is the non-owner sentinel (payload left in place) — reads as "nothing".+ return claimed ? claimed : undefined;+ }++ /** A malformed entry is dropped (logged) rather than poisoning the drain. */+ private parseSteerItems(raw: unknown): SteerQueueItem[] {+ if (!Array.isArray(raw)) {+ return [];+ }+ const items: SteerQueueItem[] = [];+ for (const entry of raw) {+ if (typeof entry !== 'string') {+ continue;+ }+ try {+ items.push(JSON.parse(entry) as SteerQueueItem);+ } catch {+ logger.warn('[RedisJobStore] Dropping malformed steer queue entry');+ }+ }+ return items;+ }+/*** Append a streaming chunk to Redis Stream.* Uses XADD for efficient append-only storage.diff --git a/packages/api/src/stream/index.ts b/packages/api/src/stream/index.tsindex ef63f20d82..722fce66fe 100644--- a/packages/api/src/stream/index.ts+++ b/packages/api/src/stream/index.ts@@ -6,6 +6,7 @@ export {export type {SerializableJobData,+ SteerQueueItem,IEventTransport,UsageMetadata,AbortResult,@@ -15,6 +16,12 @@ export type {// Canonical "is this approval live?" predicate — one definition shared by the// stores, the approval lifecycle, and the status route / message middleware.export { isPendingActionExpired, isPendingActionStale } from './interfaces/IJobStore';+export {+ STEER_ENQUEUE_NOT_RUNNING,+ STEER_ENQUEUE_QUEUE_FULL,+ STEER_QUEUE_MAX_DEPTH,+} from './interfaces/IJobStore';+export { SteeringLifecycle, toPendingSteer } from './SteeringLifecycle';export { createStreamServices } from './createStreamServices';export type { StreamServicesConfig, StreamServices } from './createStreamServices';diff --git a/packages/api/src/stream/interfaces/IJobStore.ts b/packages/api/src/stream/interfaces/IJobStore.tsindex 7edb555dc3..1e4de99cc4 100644--- a/packages/api/src/stream/interfaces/IJobStore.ts+++ b/packages/api/src/stream/interfaces/IJobStore.ts@@ -1,5 +1,5 @@+import type { Agents, TFile, TPendingSteer } from 'librechat-data-provider';import type { StandardGraph } from '@librechat/agents';-import type { Agents } from 'librechat-data-provider';/*** Job status enum.@@ -116,6 +116,14 @@ export interface SerializableJobData {* next tick right after resuming. Falls back to `createdAt` when unset.*/lastActiveAt?: number;++ /**+ * Flat flag set by the terminal close-and-drain (Redis: raw hash field the+ * enqueue Lua guards on; in-memory: a parallel set). Once set, new steers+ * are rejected until `createJob` reuses the stream id. Never written through+ * `updateJob` — listed here so cleanup paths can reference the key name.+ */+ steersClosed?: boolean;}/**@@ -138,6 +146,31 @@ export function isPendingActionStale(job: Pick<SerializableJobData, 'pendingActireturn !job.pendingAction || isPendingActionExpired(job);}+/**+ * A user steering message queued for mid-run injection. Enqueued by the steer+ * route on any instance; drained FIFO by the owning process's run-scoped+ * PostToolBatch hook at the next tool-batch boundary.+ */+export interface SteerQueueItem {+ steerId: string;+ text: string;+ userId: string;+ createdAt: number;+ /** Attachment refs steered with the message. Display metadata only — the+ * drain re-fetches each file by id scoped to the run's user and encodes+ * fresh, so nothing here is trusted beyond identifying the file. */+ files?: Partial<TFile>[];+}++/** Maximum steers a single run can have queued at once. */+export const STEER_QUEUE_MAX_DEPTH = 10;++/** `enqueueSteer` rejection: the job is missing or not `running`. */+export const STEER_ENQUEUE_NOT_RUNNING = -1;++/** `enqueueSteer` rejection: the queue is at {@link STEER_QUEUE_MAX_DEPTH}. */+export const STEER_ENQUEUE_QUEUE_FULL = -2;+/*** Arguments for an atomic {@link IJobStore.transitionStatus} compare-and-set.*/@@ -250,6 +283,8 @@ export interface AbortResult {text: string;/** Collected usage metadata from all models for token spending */collectedUsage: UsageMetadata[];+ /** Steers drained at abort time (never injected); surfaced to the client for restore */+ pendingSteers?: TPendingSteer[];}/**@@ -468,6 +503,68 @@ export interface IJobStore {* @returns Array of usage metadata or empty array*/getCollectedUsage(streamId: string): UsageMetadata[];++ // ===== Steering Queue Methods =====+ // FIFO queue of mid-run user messages, keyed by streamId. Writable from any+ // instance (the steer route), drained only by the run's owning process.++ /**+ * Atomically append a steer, guarded on the job being `running` AND the+ * queue not being closed by a terminal drain. Returns the new queue depth,+ * {@link STEER_ENQUEUE_NOT_RUNNING} when the job is missing, not running,+ * or closed, or {@link STEER_ENQUEUE_QUEUE_FULL} at max depth.+ */+ enqueueSteer(streamId: string, item: SteerQueueItem): Promise<number>;++ /**+ * Atomically take ALL queued steers, FIFO. Empty array when none. With+ * `expectedCreatedAt`, the drain is refused (atomically, inside the store)+ * when the live job's `createdAt` differs — a stale run's drain must never+ * consume a replacement job's queue.+ */+ drainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;++ /**+ * Atomically CLOSE the queue to new steers, then take all queued items+ * FIFO. Used by the terminal paths (final event, abort) so a steer POST+ * racing finalization can never be 202-ACKed after the last drain and then+ * silently cleared — once closed, `enqueueSteer` rejects until the next+ * `createJob` reopens the stream id. `expectedCreatedAt` guards exactly+ * like {@link drainSteers}: a stale run's finalization can neither close+ * nor steal a replacement job's queue.+ */+ closeAndDrainSteers(streamId: string, expectedCreatedAt?: number): Promise<SteerQueueItem[]>;++ /** Non-destructive FIFO read of the queued steers (status/resume surfaces). */+ peekSteers(streamId: string): Promise<SteerQueueItem[]>;++ /** Remove ONE queued steer by id (user-cancelled before injection).+ * False when it was no longer queued — already drained or run ended. */+ removeSteer(streamId: string, steerId: string): Promise<boolean>;++ /**+ * Persist terminally-drained steers under their OWN bounded-TTL key so a+ * client with no live subscriber can recover them via the status route.+ * Deliberately independent of the job record — the default `completeJob`+ * path deletes the job immediately, and recovery must survive that.+ * Overwrites any prior payload; cleared by `createJob` (a replacement run+ * invalidates recovery — a live client had to start it).+ */+ parkSteers(streamId: string, payload: string): Promise<void>;++ /**+ * Claim-on-read: atomically return AND remove the parked payload, so a+ * second reload cannot re-mint chips the user already dismissed. The+ * removal is gated on `ownerFragment` (an opaque substring of the+ * serialized payload, e.g. `"userId":"u1"`) INSIDE the same atomic step —+ * a non-owner probe returns nothing and leaves the payload untouched+ * instead of deleting it ahead of the owner check. Stores stay+ * schema-free: the caller parses and authorizes the returned payload.+ */+ claimParkedSteers(streamId: string, ownerFragment: string): Promise<string | undefined>;++ /** Drop any queued steers (terminal cleanup backstop). */+ clearSteers(streamId: string): Promise<void>;}/**diff --git a/packages/api/src/types/events.ts b/packages/api/src/types/events.tsindex 360929d034..c1e724ea75 100644--- a/packages/api/src/types/events.ts+++ b/packages/api/src/types/events.ts@@ -1,3 +1,5 @@+import type { TPendingSteer } from 'librechat-data-provider';+/** SSE streaming event (on_run_step, on_message_delta, etc.) */export type StreamEvent = {event: string;@@ -45,6 +47,9 @@ export type FinalEvent = {aborted?: boolean;earlyAbort?: boolean;runMessages?: FinalMessageFields[];+ /** Steers that never reached an injection boundary; the client converts+ * them to queued follow-up messages instead of dropping them. */+ pendingSteers?: TPendingSteer[];/** Top-level event error (abort-during-completion edge case) */error?: { message: string };};diff --git a/packages/data-provider/specs/parsers.spec.ts b/packages/data-provider/specs/parsers.spec.tsindex b67b77a79d..e88eab64ab 100644--- a/packages/data-provider/specs/parsers.spec.ts+++ b/packages/data-provider/specs/parsers.spec.ts@@ -670,4 +670,34 @@ describe('parseTextParts', () => {];expect(parseTextParts(parts)).toBe('Hello World');});++ test('should exclude steer parts by default (generic extraction must not speak user words)', () => {+ const parts: TMessageContentParts[] = [+ { type: ContentTypes.TEXT, text: 'assistant output' },+ { type: ContentTypes.STEER, steer: 'user mid-run words' },+ { type: ContentTypes.TEXT, text: 'more output' },+ ];+ expect(parseTextParts(parts)).toBe('assistant output more output');+ });++ test('should include steer parts when includeSteer is set', () => {+ const parts: TMessageContentParts[] = [+ { type: ContentTypes.TEXT, text: 'assistant output' },+ { type: ContentTypes.STEER, steer: 'user mid-run words' },+ ];+ expect(parseTextParts(parts, false, { includeSteer: true })).toBe(+ 'assistant output user mid-run words',+ );+ });++ test('should combine includeSteer with skipReasoning', () => {+ const parts: TMessageContentParts[] = [+ { type: ContentTypes.THINK, think: 'internal reasoning' },+ { type: ContentTypes.TEXT, text: 'visible answer' },+ { type: ContentTypes.STEER, steer: 'steered words' },+ ];+ expect(parseTextParts(parts, true, { includeSteer: true })).toBe(+ 'visible answer steered words',+ );+ });});diff --git a/packages/data-provider/src/api-endpoints.ts b/packages/data-provider/src/api-endpoints.tsindex 374a377f19..ba786340d6 100644--- a/packages/data-provider/src/api-endpoints.ts+++ b/packages/data-provider/src/api-endpoints.ts@@ -314,6 +314,8 @@ export const fileDownload = (userId: string, fileId: string) =>export const filePreview = (fileId: string) =>`${BASE_URL}/api/files/${encodeURIComponent(fileId)}/preview`;export const fileConfig = () => `${BASE_URL}/api/files/config`;+/** Owner-scoped usage touch so queued attachments outlive the upload-window TTL. */+export const fileUsage = () => `${BASE_URL}/api/files/usage`;export const agentFiles = (agentId: string) => `${BASE_URL}/api/files/agent/${agentId}`;export const images = () => `${files()}/images`;diff --git a/packages/data-provider/src/data-service.ts b/packages/data-provider/src/data-service.tsindex 4d5fa37fa2..756351368d 100644--- a/packages/data-provider/src/data-service.ts+++ b/packages/data-provider/src/data-service.ts@@ -465,6 +465,15 @@ export const uploadFile = (data: FormData, signal?: AbortSignal | null): Promisereturn request.postMultiPart(endpoints.files(), data, requestConfig);};+/**+ * Marks uploaded files as used (owner-scoped TTL touch) so the upload-window+ * TTL cannot reap attachments held in a client-side queue during a long run.+ * Best-effort: callers fire-and-forget — send-time marking is the backstop.+ */+export const markFilesUsage = (body: f.TFilesUsageBody): Promise<f.TFilesUsageResponse> => {+ return request.post(endpoints.fileUsage(), body);+};+/* actions */export const updateAction = (data: m.UpdateActionVariables): Promise<m.UpdateActionResponse> => {diff --git a/packages/data-provider/src/keys.ts b/packages/data-provider/src/keys.tsindex 22b9ee959a..e30484d1ed 100644--- a/packages/data-provider/src/keys.ts+++ b/packages/data-provider/src/keys.ts@@ -97,6 +97,7 @@ export enum MutationKeys {deleteAgentApiKey = 'deleteAgentApiKey',fileUpload = 'fileUpload',fileDelete = 'fileDelete',+ fileUsage = 'fileUsage',updatePreset = 'updatePreset',deletePreset = 'deletePreset',loginUser = 'loginUser',diff --git a/packages/data-provider/src/parsers.ts b/packages/data-provider/src/parsers.tsindex c30297f581..261ad9031d 100644--- a/packages/data-provider/src/parsers.ts+++ b/packages/data-provider/src/parsers.ts@@ -380,36 +380,34 @@ export const parseCompactConvo = ({export function parseTextParts(contentParts: Array<a.TMessageContentParts | undefined>,skipReasoning: boolean = false,+ options?: { includeSteer?: boolean },): string {let result = '';+ const append = (textValue: string) => {+ if (+ result.length > 0 &&+ textValue.length > 0 &&+ result[result.length - 1] !== ' ' &&+ textValue[0] !== ' '+ ) {+ result += ' ';+ }+ result += textValue;+ };for (const part of contentParts) {if (!part?.type) {continue;}if (part.type === ContentTypes.TEXT) {- const textValue = (typeof part.text === 'string' ? part.text : part.text?.value) || '';-- if (- result.length > 0 &&- textValue.length > 0 &&- result[result.length - 1] !== ' ' &&- textValue[0] !== ' '- ) {- result += ' ';- }- result += textValue;+ append((typeof part.text === 'string' ? part.text : part.text?.value) || '');+ } else if (part.type === ContentTypes.STEER && options?.includeSteer === true) {+ /** Mid-run user speech: excluded by default so generic extraction (TTS+ * reading assistant output) never speaks the user's own words — the+ * full-record surfaces (search indexing, persisted abort text) opt in. */+ append(typeof part.steer === 'string' ? part.steer : '');} else if (part.type === ContentTypes.THINK && !skipReasoning) {- const textValue = typeof part.think === 'string' ? part.think : '';- if (- result.length > 0 &&- textValue.length > 0 &&- result[result.length - 1] !== ' ' &&- textValue[0] !== ' '- ) {- result += ' ';- }- result += textValue;+ append(typeof part.think === 'string' ? part.think : '');}}diff --git a/packages/data-provider/src/types/agents.ts b/packages/data-provider/src/types/agents.tsindex eebcf80e0a..97d51b9c7c 100644--- a/packages/data-provider/src/types/agents.ts+++ b/packages/data-provider/src/types/agents.ts@@ -1,6 +1,6 @@/* eslint-disable @typescript-eslint/no-namespace */+import type { TTokenUsageEvent, TContextUsageEvent, TPendingSteer } from './runs';import type { FunctionToolCall, SummaryContentPart } from './assistants';-import type { TTokenUsageEvent, TContextUsageEvent } from './runs';import type { TAttachment, TPlugin } from 'src/schemas';import { StepTypes, ContentTypes, ToolCallTypes } from './runs';@@ -257,6 +257,12 @@ export namespace Agents {* cross-replica client can rebuild and render the prompt from `resumeState`.*/pendingAction?: PendingAction;+ /**+ * Steers queued server-side but not yet injected into the run. Injected+ * steers already live inside `aggregatedContent`; these are the remainder,+ * so a reconnecting client can rebuild its pending-steer chips.+ */+ pendingSteers?: TPendingSteer[];}/*** Represents a run step delta i.e. any changed fields on a run step duringdiff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.tsindex 2882ac96d1..2b03a5b4ee 100644--- a/packages/data-provider/src/types/assistants.ts+++ b/packages/data-provider/src/types/assistants.ts@@ -586,6 +586,22 @@ export type SummaryContentPart = {};};+/**+ * A user steering message injected mid-run at a tool-batch boundary.+ * Persisted inline in the response message's content array (keyed by the+ * type name like `text`/`think` so token counting reads it for free);+ * replayed as a user message on subsequent turns by `formatAgentMessages`.+ */+export type SteerContentPart = {+ type: ContentTypes.STEER;+ steer: string;+ steerId?: string;+ createdAt?: number;+ /** Attachments steered with the message; re-encoded per turn on replay+ * like any other user-message media (refs only, never encoded data). */+ files?: Partial<TFile>[];+};+export type TMessageContentParts =| ({type: ContentTypes.ERROR;@@ -593,6 +609,7 @@ export type TMessageContentParts =error?: string;} & ContentMetadata)| ({ type: ContentTypes.THINK; think?: string | TextData } & ContentMetadata)+ | (SteerContentPart & ContentMetadata)| ({type: ContentTypes.TEXT;text?: string | TextData;diff --git a/packages/data-provider/src/types/files.ts b/packages/data-provider/src/types/files.tsindex d977b1eb99..4d1210cd7d 100644--- a/packages/data-provider/src/types/files.ts+++ b/packages/data-provider/src/types/files.ts@@ -1,5 +1,5 @@-import { EToolResources } from './assistants';import type { CodeEnvRef } from '../codeEnvRef';+import { EToolResources } from './assistants';export enum FileSources {local = 'local',@@ -237,6 +237,14 @@ export type VoiceOptions = {onError?: (error: unknown, variables: unknown, context?: unknown) => void;};+export type TFilesUsageBody = {+ file_ids: string[];+};++export type TFilesUsageResponse = {+ marked: number;+};+export type DeleteFilesResponse = {message: string;result: Record<string, unknown>;diff --git a/packages/data-provider/src/types/runs.ts b/packages/data-provider/src/types/runs.tsindex da386ac5f4..b01017e32f 100644--- a/packages/data-provider/src/types/runs.ts+++ b/packages/data-provider/src/types/runs.ts@@ -1,3 +1,4 @@+import type { TFile } from './files';import { inputTokensIncludesCache } from '../schemas';export enum ContentTypes {@@ -11,6 +12,7 @@ export enum ContentTypes {INPUT_AUDIO = 'input_audio',AGENT_UPDATE = 'agent_update',SUMMARY = 'summary',+ STEER = 'steer',ERROR = 'error',}@@ -57,6 +59,41 @@ export enum ApprovalEvents {ON_PENDING_ACTION = 'on_pending_action',}+/**+ * Steering event names. `on_steer_applied` streams to live clients when a+ * queued steer message is injected at a tool-batch boundary; reconnecting+ * clients recover injected steers from `aggregatedContent` and still-queued+ * ones from `resumeState.pendingSteers`. Steers that never reach a boundary+ * ride the final/abort events as `pendingSteers`.+ */+export enum SteerEvents {+ ON_STEER_APPLIED = 'on_steer_applied',+}++/** A steer message queued server-side but not yet injected into the run. */+export type TPendingSteer = {+ steerId: string;+ text: string;+ createdAt?: number;+ files?: Partial<TFile>[];+};++/** Payload of the `on_steer_applied` SSE event. */+export type TSteerAppliedEvent = {+ steerId: string;+ /** Absolute content index the steer part was injected at. */+ index: number;+ part: {+ type: ContentTypes.STEER;+ [ContentTypes.STEER]: string;+ steerId?: string;+ createdAt?: number;+ files?: Partial<TFile>[];+ };+ responseMessageId?: string;+ conversationId?: string;+};+/** Mirrors TokenBudgetBreakdown from @librechat/agents (data-provider cannot import it). */export type TTokenBudgetBreakdown = {maxContextTokens: number;diff --git a/packages/data-schemas/src/methods/share.test.ts b/packages/data-schemas/src/methods/share.test.tsindex 5f092fc26a..70e4b2bd44 100644--- a/packages/data-schemas/src/methods/share.test.ts+++ b/packages/data-schemas/src/methods/share.test.ts@@ -4,7 +4,7 @@ import { Constants } from 'librechat-data-provider';import { MongoMemoryServer } from 'mongodb-memory-server';import type { SchemaWithMeiliMethods } from '~/models/plugins/mongoMeili';import type * as t from '~/types';-import { createShareMethods, type ShareMethods } from './share';+import { createShareMethods, anonymizeSharedContent, type ShareMethods } from './share';describe('Share Methods', () => {let mongoServer: MongoMemoryServer;@@ -543,6 +543,145 @@ describe('Share Methods', () => {expect(attachment).not.toHaveProperty('storageKey');expect(attachment).not.toHaveProperty('metadata');});++ test('strips steer-part files from content when the link excludes files', async () => {+ const userId = new mongoose.Types.ObjectId().toString();+ const conversationId = `conv_${nanoid()}`;+ const shareId = `share_${nanoid()}`;++ const message = await Message.create({+ messageId: `msg_${nanoid()}`,+ conversationId,+ user: userId,+ text: '',+ isCreatedByUser: false,+ content: [+ { type: 'text', text: 'partial answer' },+ {+ type: 'steer',+ steer: 'use the attached notes',+ steerId: 'steer-1',+ files: [+ {+ file_id: 'steer-file-1',+ filename: 'notes.pdf',+ type: 'application/pdf',+ filepath: '/uploads/owner/notes.pdf',+ bytes: 1234,+ },+ ],+ },+ ],+ });++ await SharedLink.create({+ shareId,+ conversationId,+ user: userId,+ messages: [message._id],+ snapshotFiles: false,+ });++ const result = await shareMethods.getSharedMessages(shareId);+ const content = result?.messages[0]?.content as Array<Record<string, unknown>>;++ expect(content[0]).toMatchObject({ type: 'text', text: 'partial answer' });+ expect(content[1]).toMatchObject({ type: 'steer', steer: 'use the attached notes' });+ expect(content[1]).not.toHaveProperty('files');+ });++ test('rewrites steer-part file refs to the share route when files are included', async () => {+ const userId = new mongoose.Types.ObjectId().toString();+ const conversationId = `conv_${nanoid()}`;+ const shareId = `share_${nanoid()}`;++ await File.create({+ user: userId,+ file_id: 'steer-file-2',+ filename: 'steer.png',+ filepath: '/uploads/owner/steer.png',+ storageKey: 'private/steer.png',+ source: 'local',+ type: 'image/png',+ bytes: 2048,+ });++ const message = await Message.create({+ messageId: `msg_${nanoid()}`,+ conversationId,+ user: userId,+ text: '',+ isCreatedByUser: false,+ content: [+ {+ type: 'steer',+ steer: 'look at this screenshot',+ steerId: 'steer-2',+ files: [+ {+ file_id: 'steer-file-2',+ filename: 'steer.png',+ type: 'image/png',+ filepath: '/uploads/owner/steer.png',+ storageKey: 'private/steer.png',+ user: userId,+ conversationId,+ width: 640,+ height: 480,+ },+ ],+ },+ ],+ });++ await SharedLink.create({+ shareId,+ conversationId,+ user: userId,+ messages: [message._id],+ });++ const result = await shareMethods.getSharedMessages(shareId);+ const content = result?.messages[0]?.content as Array<Record<string, unknown>>;+ const steerFile = (content[0].files as Array<Record<string, unknown>>)[0];++ // Snapshotted through the same pipeline as top-level files: served via the+ // share-scoped route, storage/identity internals stripped, ids anonymized.+ expect(steerFile.filepath).toBe(`/api/share/${shareId}/files/steer-file-2`);+ expect(steerFile).toMatchObject({ filename: 'steer.png', type: 'image/png' });+ expect(steerFile).not.toHaveProperty('storageKey');+ expect(steerFile).not.toHaveProperty('user');+ expect(steerFile.conversationId).toBe(result?.conversationId);+ expect(steerFile.conversationId).not.toBe(conversationId);++ const share = await SharedLink.findOne({ shareId }).lean();+ expect(share?.fileSnapshots?.map((snapshot) => snapshot.file_id)).toContain('steer-file-2');+ });++ test('leaves non-steer content untouched (same array reference when no steer part)', () => {+ const plainContent = [+ { type: 'text', text: 'no steers here' },+ { type: 'tool_call', tool_call: { id: 'call_1' } },+ ];+ const params = {+ newConvoId: 'convo_anon',+ newMessageId: 'msg_anon',+ shareId: 'share_ref',+ snapshotIds: new Set<string>(),+ includeFiles: true,+ };++ expect(anonymizeSharedContent(plainContent, params)).toBe(plainContent);+ expect(anonymizeSharedContent(undefined, params)).toBeUndefined();++ const withSteer = [...plainContent, { type: 'steer', steer: 'go', files: [] }];+ const sanitized = anonymizeSharedContent(withSteer, params) as Array<Record<string, unknown>>;+ expect(sanitized).not.toBe(withSteer);+ // Non-steer parts are carried over by reference, not copied.+ expect(sanitized[0]).toBe(plainContent[0]);+ expect(sanitized[1]).toBe(plainContent[1]);+ expect(sanitized[2]).not.toHaveProperty('files');+ });});describe('getSharedLinks', () => {diff --git a/packages/data-schemas/src/methods/share.ts b/packages/data-schemas/src/methods/share.tsindex f76cc0e29f..3bf46e8688 100644--- a/packages/data-schemas/src/methods/share.ts+++ b/packages/data-schemas/src/methods/share.ts@@ -1,5 +1,5 @@import { nanoid } from 'nanoid';-import { Constants, FileSources } from 'librechat-data-provider';+import { Constants, ContentTypes, FileSources } from 'librechat-data-provider';import type { FilterQuery, Model } from 'mongoose';import type { SchemaWithMeiliMethods } from '~/models/plugins/mongoMeili';import type * as t from '~/types';@@ -129,6 +129,29 @@ function collectFileIds(items: unknown, target: Set<string>): void {}}+type SteerLikePart = { type?: unknown; files?: unknown };++function isSteerPartWithFiles(part: unknown): part is SteerLikePart {+ return (+ part != null &&+ typeof part === 'object' &&+ (part as SteerLikePart).type === ContentTypes.STEER &&+ (part as SteerLikePart).files !== undefined+ );+}++/** Collect `file_id`s carried by steer parts inside a message's content array. */+function collectSteerFileIds(content: unknown, target: Set<string>): void {+ if (!Array.isArray(content)) {+ return;+ }+ for (const part of content) {+ if (isSteerPartWithFiles(part)) {+ collectFileIds(part.files, target);+ }+ }+}+/*** Build the per-share file snapshot from the messages being shared. Captures only* the metadata the share-scoped routes need to stream each file; references the@@ -150,6 +173,7 @@ async function buildFileSnapshots(for (const message of messages) {collectFileIds(message.files, fileIds);collectFileIds(message.attachments, fileIds);+ collectSteerFileIds(message.content, fileIds);}if (fileIds.size === 0) {@@ -214,6 +238,55 @@ function applyShareFileRoute(return next;}+/**+ * Steer parts persisted inline in `message.content` carry the same user file+ * refs as a message's top-level `files`, so they follow the identical share+ * policy: dropped entirely when files are excluded from the link, sanitized and+ * rewritten to the share-scoped route (with anonymized ids) when included.+ * Returns the original array untouched when no steer part carries files.+ */+export function anonymizeSharedContent(+ content: unknown[] | undefined,+ params: {+ newConvoId: string;+ newMessageId: string;+ shareId: string;+ snapshotIds: Set<string>;+ includeFiles: boolean;+ },+): unknown[] | undefined {+ if (!Array.isArray(content)) {+ return content;+ }++ let result: unknown[] | null = null;+ for (let i = 0; i < content.length; i++) {+ const part = content[i];+ if (!isSteerPartWithFiles(part)) {+ continue;+ }+ const { files: rawFiles, ...rest } = part as Record<string, unknown>;+ const files = params.includeFiles+ ? sanitizeSharedFiles(rawFiles)?.map((file) =>+ applyShareFileRoute(+ {+ ...file,+ ...(file.conversationId !== undefined && { conversationId: params.newConvoId }),+ ...(file.messageId !== undefined && { messageId: params.newMessageId }),+ },+ params.shareId,+ params.snapshotIds,+ ),+ )+ : undefined;+ if (result == null) {+ result = [...content];+ }+ result[i] = files ? { ...rest, files } : rest;+ }+ return result ?? content;+}+/*** Only surface a model name when it is an (already-anonymized) assistant id;* otherwise omit it so the underlying provider/model is not disclosed.@@ -289,7 +362,13 @@ function anonymizeMessages(conversationId: newConvoId,sender: message.sender,text: message.text,- content: message.content,+ content: anonymizeSharedContent(message.content, {+ newConvoId,+ newMessageId,+ shareId,+ snapshotIds,+ includeFiles,+ }),...(message.iconURL && { iconURL: message.iconURL }),...(model && { model }),isCreatedByUser: message.isCreatedByUser,diff --git a/packages/data-schemas/src/models/plugins/mongoMeili.ts b/packages/data-schemas/src/models/plugins/mongoMeili.tsindex 7d9a52399d..405d32268f 100644--- a/packages/data-schemas/src/models/plugins/mongoMeili.ts+++ b/packages/data-schemas/src/models/plugins/mongoMeili.ts@@ -452,7 +452,8 @@ const createMeiliMongooseModel = ({}if (object.content && Array.isArray(object.content)) {- object.text = parseTextParts(object.content);+ /** Search indexes the full conversational record, steered words included. */+ object.text = parseTextParts(object.content, false, { includeSteer: true });delete object.content;}