Skip to content
Merged
Show file tree
Hide file tree
Changes from all 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
Original file line number Diff line number Diff line change
Expand Up @@ -33,6 +33,7 @@ jest.mock('@librechat/data-schemas', () => ({

jest.mock('@librechat/api', () => ({
isEnabled: jest.fn(() => true),
createBackgroundChildAbortGuard: jest.fn(() => (_req, _res, next) => next()),
detectGenerationRetry: async (req, _res, next) => {
req._isConfirmedGenerationRetry = await mockHasGenerationClaim(
req.user?.id,
Expand Down
12 changes: 12 additions & 0 deletions api/server/routes/agents/__tests__/streamTenant.spec.js
Original file line number Diff line number Diff line change
Expand Up @@ -959,12 +959,18 @@ describe('SSE stream tenant isolation', () => {
});

it('reports an already-settled generation when natural completion wins the abort CAS', async () => {
/** Read by the child-job guard, by the route, and again after the abort lost its CAS. */
mockGenerationJobManager.getJob
.mockResolvedValueOnce({
metadata: { userId: 'user-123', generationProtocolVersion: 2 },
status: 'running',
createdAt: 1000,
})
.mockResolvedValueOnce({
metadata: { userId: 'user-123', generationProtocolVersion: 2 },
status: 'running',
createdAt: 1000,
})
.mockResolvedValueOnce({
metadata: { userId: 'user-123', generationProtocolVersion: 2 },
status: 'complete',
Expand Down Expand Up @@ -996,12 +1002,18 @@ describe('SSE stream tenant isolation', () => {
});

it('keeps the legacy abort ACK shape when natural completion wins for protocol v1', async () => {
/** Read by the child-job guard, by the route, and again after the abort lost its CAS. */
mockGenerationJobManager.getJob
.mockResolvedValueOnce({
metadata: { userId: 'user-123', generationProtocolVersion: 1 },
status: 'running',
createdAt: 1000,
})
.mockResolvedValueOnce({
metadata: { userId: 'user-123', generationProtocolVersion: 1 },
status: 'running',
createdAt: 1000,
})
.mockResolvedValueOnce({
metadata: { userId: 'user-123', generationProtocolVersion: 1 },
status: 'complete',
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
100 changes: 100 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,102 @@ 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('fails closed, without reaching the route, when the job lookup fails', async () => {
const consoleError = jest.spyOn(console, 'error').mockImplementation();
try {
const response = await request(
abortApp(async () => {
throw new Error('store down');
}),
)
.post('/abort')
.send({ streamId: 'thread-1' });

expect(response.status).toBe(500);
expect(response.body).not.toEqual({ reached: 'route' });
} finally {
consoleError.mockRestore();
}
});
});
87 changes: 87 additions & 0 deletions packages/api/src/agents/guard.ts
Original file line number Diff line number Diff line change
Expand Up @@ -9,6 +9,93 @@ 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. A job
* lookup that fails ends the request at the error boundary.
*/
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 (error) {
/** Fail closed: the route reads the job again, and a read that then succeeds would
* run its chat-shaped abort on a child this guard never got to see. */
next(error);
return;
}
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
Loading
Loading