Skip to content
Merged
Show file tree
Hide file tree
Changes from 14 commits
Commits
Show all changes
18 commits
Select commit Hold shift + click to select a range
1e7f411
🫀 feat: Let a Job Owner Keep a Silent Run Alive
danny-avila Nov 14, 2026
a43ec02
🧶 refactor: Share One Fold From Child Frames to Content Parts
danny-avila Nov 14, 2026
c9b618f
🏷️ feat: Mark the Generation Job of a Background Subagent Task
danny-avila Nov 14, 2026
1a754b6
🧵 feat: Run a Background Child as a Resumable Generation Job
danny-avila Nov 14, 2026
7cc8b3f
🪢 feat: Stream a Background Child Through Its Own Generation Job
danny-avila Nov 14, 2026
a9a9b3d
🔌 feat: Give the Server's Task Store Its Child Stream
danny-avila Nov 14, 2026
80db8e6
🚧 fix: Refuse Chat Abort and Steer on a Background Child's Job
danny-avila Nov 14, 2026
2a8dae4
🧹 fix: Evict a Finished Job Before a Live One at Capacity
danny-avila Nov 14, 2026
e232a12
🛰️ test: Read a Background Child's Stream From Another Replica
danny-avila Nov 14, 2026
baa75b5
🧽 chore: Sort Imports in the Child Stream Files
danny-avila Nov 14, 2026
4e031c5
🧪 test: Expect the Child Stream Lever in the Activity Defaults
danny-avila Nov 14, 2026
5420227
📜 feat: Store What a Background Child Streamed as Standard Content (#…
danny-avila Nov 14, 2026
f265873
🛟 fix: Keep a Stalled or Failing Child Stream From Touching Its Child
danny-avila Nov 14, 2026
65173f3
🧯 fix: Let a Child Stream Observe Its Run Without Ever Stopping It
danny-avila Nov 14, 2026
5b52e4a
♻️ fix: Replace a Dead Background Child's Job on Its Thread
danny-avila Nov 14, 2026
c7a21e4
🧱 fix: Fail the Abort Guard Closed and Budget Content Against the Who…
danny-avila Nov 14, 2026
cd6b424
🪶 refactor: Settle a Child Stream Once and Fold a Frame It Cannot Copy
danny-avila Nov 14, 2026
1611161
🧪 test: Cover the Child Stream's Failure Branches and the Content Fold
danny-avila Nov 15, 2026
File filter

Filter by extension

Filter by extension

Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
35 changes: 35 additions & 0 deletions api/server/routes/agents/__tests__/abort.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -181,6 +181,41 @@ describe('Agent Abort Endpoint', () => {
);
});

it('should refuse to abort a background child job, which its task store owns', async () => {
const jobStreamId = 'child-thread-123';

mockGenerationJobManager.getJob.mockResolvedValue({
metadata: {
userId: 'test-user-123',
subagentTaskId: 'task-1',
subagentParentConversationId: 'parent-1',
},
});

const response = await request(app)
.post('/api/agents/chat/abort')
.send({ conversationId: jobStreamId });

expect(response.status).toBe(409);
expect(response.body).toMatchObject({ code: 'CHILD_THREAD_READ_ONLY' });
expect(mockGenerationJobManager.abortJob).not.toHaveBeenCalled();
expect(mockSaveMessage).not.toHaveBeenCalled();
expect(mockSaveConvo).not.toHaveBeenCalled();
});

it("should answer 403, not 409, for another user's background child job", async () => {
mockGenerationJobManager.getJob.mockResolvedValue({
metadata: { userId: 'other-user-456', subagentTaskId: 'task-1' },
});

const response = await request(app)
.post('/api/agents/chat/abort')
.send({ conversationId: 'child-thread-123' });

expect(response.status).toBe(403);
expect(mockGenerationJobManager.abortJob).not.toHaveBeenCalled();
});

it('should fail closed when job has no userId metadata', async () => {
const jobStreamId = 'test-stream-123';

Expand Down
7 changes: 7 additions & 0 deletions api/server/routes/agents/index.js
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ const {
reportLocatorTraversalFailure,
isEnabled,
GenerationJobManager,
createBackgroundChildAbortGuard,
TERMINAL_PUBLICATION_RECONNECT_ERROR,
hasPersistableAbortContent,
announceStoppedReply,
Expand Down Expand Up @@ -622,6 +623,12 @@ router.get('/chat/status/:conversationId', async (req, res) => {
* @access Private
* @description Mounted before chatRouter to bypass buildEndpointOption middleware
*/
router.post(
'/chat/abort',
createBackgroundChildAbortGuard({
getJob: (streamId) => GenerationJobManager.getJob(streamId),
}),
);
router.post('/chat/abort', chatConfigMiddleware, async (req, res, next) => {
logger.debug(`[AgentStream] ========== ABORT ENDPOINT HIT ==========`);
logger.debug(`[AgentStream] Method: ${req.method}, Path: ${req.path}`);
Expand Down
2 changes: 2 additions & 0 deletions api/server/services/Endpoints/agents/subagentThreadStore.js
Original file line number Diff line number Diff line change
Expand Up @@ -5,6 +5,7 @@ const {
duplicateIoRedisClient,
createIoRedisSubscriber,
createSubagentThreadTaskStore,
createChildGenerationHost,
createSubagentCompletionWakeupHandler,
GenerationJobManager,
RedisSubagentTaskControlTransport,
Expand Down Expand Up @@ -80,6 +81,7 @@ const subagentThreadTaskStore = createSubagentThreadTaskStore(
renewOwnerAdmission: db.renewSubagentAdmission,
releaseOwnerAdmission: db.releaseSubagentAdmission,
cancelUnroutedTask: cancelUnroutedGeneration,
childGenerations: createChildGenerationHost(GenerationJobManager),
onTaskPrepared: completionWakeupHandler,
onTaskSettled: (userId, conversationId, taskIds) =>
expediteCompletionWakeups({ user: userId, conversationId, taskIds }),
Expand Down
11 changes: 11 additions & 0 deletions api/server/services/Endpoints/agents/subagentThreadStore.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -7,6 +7,8 @@ const mockTaskStore = {
destroyActivityStream: jest.fn(),
};
const mockCompletionWakeupHandler = jest.fn().mockResolvedValue(undefined);
const mockChildGenerations = { open: jest.fn() };
const mockGenerationJobManager = { getJob: jest.fn(), abortJob: jest.fn() };

jest.mock('@librechat/api', () => ({
cacheConfig: { USE_REDIS: true, REDIS_KEY_PREFIX: 'test:' },
Expand All @@ -15,6 +17,8 @@ jest.mock('@librechat/api', () => ({
duplicateIoRedisClient: jest.fn(),
createIoRedisSubscriber: jest.fn(),
createSubagentThreadTaskStore: jest.fn(() => mockTaskStore),
createChildGenerationHost: jest.fn(() => mockChildGenerations),
GenerationJobManager: mockGenerationJobManager,
createSubagentCompletionWakeupHandler: jest.fn(() => mockCompletionWakeupHandler),
RedisSubagentTaskControlTransport: jest.fn(),
RedisEventTransport: jest.fn(),
Expand Down Expand Up @@ -54,12 +58,14 @@ const {
registerShutdownTask,
duplicateIoRedisClient,
createIoRedisSubscriber,
createChildGenerationHost,
createSubagentThreadTaskStore,
} = require('@librechat/api');
const subagentThreadTaskStore = require('./subagentThreadStore');
const { configureSubagentTaskRouting } = subagentThreadTaskStore;
const taskStoreOptions = createSubagentThreadTaskStore.mock.calls[0][1];
const taskStoreMethods = createSubagentThreadTaskStore.mock.calls[0][0];
const childGenerationHostArgs = createChildGenerationHost.mock.calls[0];
const db = require('~/models');
const activityPrepareRegistration = registerShutdownTask.mock.calls.find(
([name]) => name === 'subagent activity streams prepare',
Expand All @@ -76,6 +82,11 @@ describe('subagent thread Redis lifecycle', () => {
expect(taskStoreMethods.getSubagentTaskControlReplay).toBe(db.getSubagentTaskControlReplay);
});

it('gives the host store a child stream backed by the generation job manager', () => {
expect(childGenerationHostArgs).toEqual([mockGenerationJobManager]);
expect(taskStoreOptions.childGenerations).toBe(mockChildGenerations);
});

it('pre-registers completion wakeups for every prepared task', async () => {
await taskStoreOptions.onTaskPrepared({ taskId: 'task-1' });

Expand Down
94 changes: 94 additions & 0 deletions packages/api/src/agents/guard.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -3,6 +3,7 @@ import request from 'supertest';
import type { AllMethods, IConversation } from '@librechat/data-schemas';
import {
CHILD_THREAD_READ_ONLY_ERROR,
createBackgroundChildAbortGuard,
createSubagentThreadTurnGuard,
isSubagentThreadWriteBlocked,
} from './guard';
Expand Down Expand Up @@ -354,3 +355,96 @@ describe('subagent child-thread write policy', () => {
expect(getConvo).toHaveBeenCalledWith('owner', 'child-conversation');
});
});

describe('background child abort guard', () => {
const childJob = { metadata: { userId: 'owner', subagentTaskId: 'task-1' } };

function abortApp(
getJob: (streamId: string) => Promise<unknown>,
user: { id?: string; tenantId?: string } = { id: 'owner' },
) {
const app = express();
app.use(express.json());
app.use((req, _res, next) => {
(req as express.Request & { user?: typeof user }).user = user;
next();
});
app.post(
'/abort',
createBackgroundChildAbortGuard({
getJob: getJob as Parameters<typeof createBackgroundChildAbortGuard>[0]['getJob'],
}),
(_req, res) => {
res.status(200).json({ reached: 'route' });
},
);
return app;
}

it("answers 409 for the owner's background child job without reaching the route", async () => {
const getJob = jest.fn(async () => childJob);

const response = await request(abortApp(getJob)).post('/abort').send({ streamId: 'thread-1' });

expect(response.status).toBe(409);
expect(response.body).toEqual({
code: 'CHILD_THREAD_READ_ONLY',
error: CHILD_THREAD_READ_ONLY_ERROR,
});
expect(getJob).toHaveBeenCalledWith('thread-1');
});

it.each([
['conversationId', { conversationId: 'thread-1' }],
['abortKey', { abortKey: 'thread-1:suffix' }],
['the first concrete id after a placeholder', { streamId: 'new', conversationId: 'thread-1' }],
])('reads the target from %s', async (_name, body) => {
const getJob = jest.fn(async () => childJob);

const response = await request(abortApp(getJob)).post('/abort').send(body);

expect(response.status).toBe(409);
expect(getJob).toHaveBeenCalledWith('thread-1');
});

it.each([
['an ordinary chat job', { metadata: { userId: 'owner' } }],
["another user's child job", { metadata: { userId: 'someone-else', subagentTaskId: 't' } }],
[
"another tenant's child job",
{ metadata: { userId: 'owner', tenantId: 'tenant-b', subagentTaskId: 't' } },
],
['a job with no owner', { metadata: { subagentTaskId: 't' } }],
['no job', undefined],
])('falls through to the route for %s', async (_name, job) => {
const response = await request(abortApp(async () => job, { id: 'owner', tenantId: 'tenant-a' }))
.post('/abort')
.send({ streamId: 'thread-1' });

expect(response.body).toEqual({ reached: 'route' });
});

it('falls through without reading a job for a placeholder, a missing id or no user', async () => {
const getJob = jest.fn(async () => childJob);

for (const body of [{ streamId: 'new' }, {}, { streamId: 42 }, { streamId: 'x'.repeat(513) }]) {
const response = await request(abortApp(getJob)).post('/abort').send(body);
expect(response.body).toEqual({ reached: 'route' });
}
const anonymous = await request(abortApp(getJob, {})).post('/abort').send({ streamId: 't' });
expect(anonymous.body).toEqual({ reached: 'route' });
expect(getJob).not.toHaveBeenCalled();
});

it('leaves a job store failure to the route', async () => {
const response = await request(
abortApp(async () => {
throw new Error('store down');
}),
)
.post('/abort')
.send({ streamId: 'thread-1' });

expect(response.body).toEqual({ reached: 'route' });
});
});
85 changes: 85 additions & 0 deletions packages/api/src/agents/guard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,91 @@ import { isAgentEventRetentionActive } from './eventRetention';
export const CHILD_THREAD_READ_ONLY_ERROR =
'This subagent thread is view-only. Continue it from its parent agent or create a separate chat.';

export const CHILD_THREAD_READ_ONLY_CODE = 'CHILD_THREAD_READ_ONLY';

export type BackgroundChildJobRefusal = {
status: 409;
body: { code: typeof CHILD_THREAD_READ_ONLY_CODE; error: string };
};

/**
* The answer for a chat route asked to end or steer a background child's job. The subagent
* task store owns that run: it stops and steers the child through its own control endpoint
* and writes the child's rows itself, so a chat route acting on the job would write a second,
* chat-shaped history into a view-only thread. Null for every other job.
*/
type AbortGuardJob = {
metadata?: { userId?: string; tenantId?: string; subagentTaskId?: string };
};

const MAX_ABORT_TARGET_LENGTH = 512;

/** The concrete stream id an abort request names, in the route's own order. The `new`
* placeholder names none: its fallback reads the active chat list, which holds no child. */
function abortTargetId(body: unknown): string | null {
if (body == null || typeof body !== 'object') return null;
const { streamId, conversationId, abortKey } = body as Record<string, unknown>;
const prefix = typeof abortKey === 'string' ? abortKey.split(':')[0] : undefined;
for (const value of [streamId, conversationId, prefix]) {
if (
typeof value === 'string' &&
value !== '' &&
value !== 'new' &&
value.length <= MAX_ABORT_TARGET_LENGTH
) {
return value;
}
}
return null;
}

/**
* Runs ahead of the chat abort route and answers for a background child's job, so the
* route's chat-shaped abort never reaches it. Every other request falls through untouched,
* including one for a job the caller does not own, which the route refuses itself.
*/
export function createBackgroundChildAbortGuard(deps: {
getJob: (streamId: string) => Promise<AbortGuardJob | null | undefined>;
}): RequestHandler {
return async (req, res, next) => {
const streamId = abortTargetId(req.body);
const user = (req as Request & { user?: { id?: string; tenantId?: string } }).user;
if (streamId == null || user?.id == null) {
next();
return;
}
let job: AbortGuardJob | null | undefined;
try {
job = await deps.getJob(streamId);
} catch {
/** The route reads the same job and owns the answer for a store failure. */
next();
return;

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

P2 Badge Fail closed when the child-job guard lookup fails

If this lookup encounters a transient store error but the subsequent lookup succeeds, calling next() bypasses the background-child refusal entirely. The downstream /chat/abort handler in api/server/routes/agents/index.js independently reads the job and no longer checks backgroundChildJobRefusal, so it can abort the child's stream and execute its chat-shaped partial-message persistence while the child continues running. Forward the lookup error to the request error boundary, or ensure any retried lookup passes through the refusal check before abort processing.

Useful? React with 👍 / 👎.

Copy link
Copy Markdown
Collaborator Author

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Fixed in c7a21e4. A failed lookup now calls next(error), so the request ends at the error boundary and the route's chat-shaped abort never runs on a job the guard could not read. guard.spec.ts: "fails closed, without reaching the route, when the job lookup fails" asserts a 500 and that the route handler is not reached.

}
const metadata = job?.metadata;
const owned =
metadata?.userId === user.id &&
(metadata.tenantId == null || metadata.tenantId === user.tenantId);
const refusal = owned ? backgroundChildJobRefusal(job) : null;
if (refusal == null) {
next();
return;
}
res.status(refusal.status).json(refusal.body);
};
}

export function backgroundChildJobRefusal(
job: { metadata?: { subagentTaskId?: string } } | null | undefined,
): BackgroundChildJobRefusal | null {
const taskId = job?.metadata?.subagentTaskId;
if (taskId == null || taskId === '') return null;
return {
status: 409,
body: { code: CHILD_THREAD_READ_ONLY_CODE, error: CHILD_THREAD_READ_ONLY_ERROR },
};
}

interface SubagentTurnBody {
conversationId?: unknown;
arg?: { conversationId?: unknown };
Expand Down
1 change: 1 addition & 0 deletions packages/api/src/agents/index.ts
Original file line number Diff line number Diff line change
Expand Up @@ -65,6 +65,7 @@ export * from './subagentThreads';
export * from './subagentActivity';
export * from './aggregation';
export * from './subagentContent';
export * from './subagentGeneration';
export * from './subagentIdentity';
export * from './subagentCompletionWakeup';
export * from './subagentTaskRouting';
Expand Down
24 changes: 24 additions & 0 deletions packages/api/src/agents/steering/__tests__/request.spec.ts
Original file line number Diff line number Diff line change
Expand Up @@ -183,6 +183,30 @@ describe('handleSteerRequest (real in-memory job manager)', () => {
await expect(GenerationJobManager.steering.peek(streamId)).resolves.toEqual([]);
});

it('409s for a background child job and queues nothing', async () => {
const streamId = 'steer-req-background-child';
await GenerationJobManager.createJob(streamId, user.id, streamId, {
initialMetadata: { subagentTaskId: 'task-1', subagentParentConversationId: 'parent' },
});

const result = await handleSteerRequest(user, { conversationId: streamId, text: 'x' });

expect(result).toEqual({ status: 409, body: { code: 'CHILD_THREAD_READ_ONLY' } });
await expect(GenerationJobManager.steering.peek(streamId)).resolves.toEqual([]);
});

it('403s for another user on a background child job before any other answer', async () => {
const streamId = 'steer-req-background-child-owner';
await GenerationJobManager.createJob(streamId, 'someone-else', streamId, {
initialMetadata: { subagentTaskId: 'task-1', subagentParentConversationId: 'parent' },
});

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);
Expand Down
6 changes: 6 additions & 0 deletions packages/api/src/agents/steering/request.ts
Original file line number Diff line number Diff line change
Expand Up @@ -20,6 +20,7 @@ import {
STEER_ENQUEUE_QUEUE_FULL,
STEER_ENQUEUE_RECEIPT_FULL,
} from '~/stream/interfaces/IJobStore';
import { backgroundChildJobRefusal, CHILD_THREAD_READ_ONLY_CODE } from '~/agents/guard';
import { toSteerFileRef, collectFileIds, buildOwnerFilter } from './refs';
import { GenerationJobManager } from '~/stream/GenerationJobManager';
import { sanitizeFileForTransmit } from '../../utils/message';
Expand Down Expand Up @@ -544,6 +545,11 @@ async function handleSteerRequestInternal(
if (expectedGeneration.value != null && job.createdAt !== expectedGeneration.value) {
return { status: 409, body: { code: 'RUN_REPLACED' } };
}
/** The subagent task store runs a background child and injects guidance through its
* own control path; a steer queued here would be accepted and never drained. */
if (backgroundChildJobRefusal(job) != null) {
return { status: 409, body: { code: CHILD_THREAD_READ_ONLY_CODE } };
}

/** 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
Expand Down
Loading
Loading