Skip to content

Enhanced ChatGPT Clone: Features Agents, MCP, Skills, DeepSeek, Anthropic, AWS, OpenAI, Responses API, Azure, Groq, o1, GPT-5, Mistral, OpenRouter, Vertex AI, Gemini, Artifacts, AI model switching, message search, Code Interpreter, langchain, DALL-E-3, OpenAPI Actions, Functions, Secure Multi-User Auth, Presets, open-source for self-hosting. Active

🧭 feat: 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.js
index 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.js
index 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.js
index 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.json
index 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.js
new file mode 100644
index 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.js
index 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-pause
diff --git a/api/server/controllers/agents/request.js b/api/server/controllers/agents/request.js
index 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, addTit
await 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, addTit
title: 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, addTit
title: 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.js
index 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.js
new file mode 100644
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.js
index 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.tsx
index 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 condition
useResumeOnLoad(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.tsx
index 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 */}
<EditBadges
isEditingChatBadges={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; placehold
setFilesLoading,
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 (
<ChatForm
index={index}
@@ -524,6 +668,7 @@ function ChatFormWrapper({ index = 0, placeholder }: { index?: number; placehold
setFilesLoading={setFilesLoading}
newConversation={stableNewConversation}
handleStopGenerating={stableHandleStop}
+ stopGenerating={stableStop}
/>
);
}
diff --git a/client/src/components/Chat/Input/DuringRunSendButton.tsx b/client/src/components/Chat/Input/DuringRunSendButton.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
index 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.tsx
index 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 (
<ErrorMessage
diff --git a/client/src/components/Chat/Messages/Content/Parts/SteerPart.tsx b/client/src/components/Chat/Messages/Content/Parts/SteerPart.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
index 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<HTMLDivE
messagesByIdRef.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<HTMLDivE
const 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.tsx
index 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.tsx
index 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.tsx
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.tsx
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
index 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 instead
const 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.ts
index 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.ts
index 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.tsx
index 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.ts
index 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 leaks
clearStepMaps();
// 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.ts
index 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 changes
const 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 available
if (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-checking
diff --git a/client/src/locales/en/translation.json b/client/src/locales/en/translation.json
index 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.ts
index 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.ts
index 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 localStorage
const staticAtoms = {
@@ -30,6 +30,11 @@ const localStorageAtoms = {
// Chat settings
enterToSend: 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.js
index 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 pa
const 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.ts
new file mode 100644
index 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.json
index 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.json
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
new file mode 100644
index 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.ts
index 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 chat
earlyAbort: 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 retrieval
if (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.ts
new file mode 100644
index 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.ts
index 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.ts
index 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.ts
new file mode 100644
index 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.ts
index 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 queries
const 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.ts
index 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 immediately
this.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.ts
index 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.ts
index 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, 'pendingActi
return !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.ts
index 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.ts
index 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.ts
index 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.ts
index 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): Promise
return 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.ts
index 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.ts
index 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.ts
index 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 during
diff --git a/packages/data-provider/src/types/assistants.ts b/packages/data-provider/src/types/assistants.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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.ts
index 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;
}