Skip to content

armgit / macro

Public Imported from GitHub
0

Macro is a unified workspace for teams: email, chat, docs, tasks, agents, calls, and CRM — @-linked together with shared AI memory.

feat(agents): restore warm sessions and bounded MCP reuse (#7580)

Wolf Mermelsteinf381296fde59
diff --git a/.sqlx/query-486f15bfd292acec985998d529e538b0e4805c9390b6a2c09e89921df3293f97.json b/.sqlx/query-486f15bfd292acec985998d529e538b0e4805c9390b6a2c09e89921df3293f97.json
new file mode 100644
index 0000000000..5dd276aa74
--- /dev/null
+++ b/.sqlx/query-486f15bfd292acec985998d529e538b0e4805c9390b6a2c09e89921df3293f97.json
@@ -0,0 +1,14 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "UPDATE agent_session SET created_at = NOW() - INTERVAL '11 minutes' WHERE id = $1",
+ "describe": {
+ "columns": [],
+ "parameters": {
+ "Left": [
+ "Uuid"
+ ]
+ },
+ "nullable": []
+ },
+ "hash": "486f15bfd292acec985998d529e538b0e4805c9390b6a2c09e89921df3293f97"
+}
diff --git a/.sqlx/query-7b29542761b4999a6e3525de2a86047f8612c24d28aeb03e777c024dd9a95938.json b/.sqlx/query-7b29542761b4999a6e3525de2a86047f8612c24d28aeb03e777c024dd9a95938.json
new file mode 100644
index 0000000000..eb76391d9a
--- /dev/null
+++ b/.sqlx/query-7b29542761b4999a6e3525de2a86047f8612c24d28aeb03e777c024dd9a95938.json
@@ -0,0 +1,18 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n UPDATE agent_session SET list_hidden = false\n WHERE id = $1 AND owner_id = $2 AND bot_id = $3 AND model = $4\n AND instructions IS NOT DISTINCT FROM $5\n AND list_hidden AND thread_id IS NULL\n AND status != 'disconnected'\n AND NOT (status = 'event' AND status_event_name = 'disconnected')\n AND created_at > NOW() - INTERVAL '10 minutes'\n ",
+ "describe": {
+ "columns": [],
+ "parameters": {
+ "Left": [
+ "Uuid",
+ "Text",
+ "Uuid",
+ "Text",
+ "Text"
+ ]
+ },
+ "nullable": []
+ },
+ "hash": "7b29542761b4999a6e3525de2a86047f8612c24d28aeb03e777c024dd9a95938"
+}
diff --git a/.sqlx/query-96f3b7e2076b357e4d6da82fe8f63dab87467d1890dac888c860bd7584db1e03.json b/.sqlx/query-c796786824c01c944b84a2afc7204b7e87b307499db387ed3796cc74b41dc4cf.json
similarity index 95%
rename from .sqlx/query-96f3b7e2076b357e4d6da82fe8f63dab87467d1890dac888c860bd7584db1e03.json
rename to .sqlx/query-c796786824c01c944b84a2afc7204b7e87b307499db387ed3796cc74b41dc4cf.json
index c99fc7f1ff..0a2efb3b1c 100644
--- a/.sqlx/query-96f3b7e2076b357e4d6da82fe8f63dab87467d1890dac888c860bd7584db1e03.json
+++ b/.sqlx/query-c796786824c01c944b84a2afc7204b7e87b307499db387ed3796cc74b41dc4cf.json
@@ -1,6 +1,6 @@
{
"db_name": "PostgreSQL",
- "query": "\n SELECT\n id, name, is_archived, owner_id, thread_id, originating_message_id, bot_id,\n model, harness, repo_url, repo_branch, pull_request_url, workspace, sandbox_size, instructions,\n mcp_scope, mcp_servers, acp_session_id, status,\n status_event_name, agent_session.created_at, modified_at,\n (SELECT jsonb_build_object('type', parent_entity_type, 'id', parent_entity_id)\n FROM comms_messages WHERE id = agent_session.thread_id)\n AS \"thread_parent?: Json<MessageParent>\",\n ext.provider AS \"external_provider?\", ext.external_id AS \"external_id?\",\n ext.external_name AS \"external_name?\", ext.external_url AS \"external_url?\",\n ext.last_run_id AS \"external_last_run_id?\"\n FROM agent_session\n LEFT JOIN external_agent_session AS ext ON ext.agent_session_id = agent_session.id\n WHERE owner_id = $1\n ORDER BY agent_session.created_at DESC, id DESC\n LIMIT $2\n ",
+ "query": "\n SELECT\n id, name, is_archived, owner_id, thread_id, originating_message_id, bot_id,\n model, harness, repo_url, repo_branch, pull_request_url, workspace, sandbox_size, instructions,\n mcp_scope, mcp_servers, acp_session_id, status,\n status_event_name, agent_session.created_at, modified_at,\n (SELECT jsonb_build_object('type', parent_entity_type, 'id', parent_entity_id)\n FROM comms_messages WHERE id = agent_session.thread_id)\n AS \"thread_parent?: Json<MessageParent>\",\n ext.provider AS \"external_provider?\", ext.external_id AS \"external_id?\",\n ext.external_name AS \"external_name?\", ext.external_url AS \"external_url?\",\n ext.last_run_id AS \"external_last_run_id?\"\n FROM agent_session\n LEFT JOIN external_agent_session AS ext ON ext.agent_session_id = agent_session.id\n WHERE owner_id = $1 AND NOT list_hidden\n ORDER BY agent_session.created_at DESC, id DESC\n LIMIT $2\n ",
"describe": {
"columns": [
{
@@ -181,5 +181,5 @@
true
]
},
- "hash": "96f3b7e2076b357e4d6da82fe8f63dab87467d1890dac888c860bd7584db1e03"
+ "hash": "c796786824c01c944b84a2afc7204b7e87b307499db387ed3796cc74b41dc4cf"
}
diff --git a/.sqlx/query-f72b19d4ac7b804f3a816e55582dbec391bb4e1de853474cf6642ed8319c0276.json b/.sqlx/query-f72b19d4ac7b804f3a816e55582dbec391bb4e1de853474cf6642ed8319c0276.json
new file mode 100644
index 0000000000..298262b74d
--- /dev/null
+++ b/.sqlx/query-f72b19d4ac7b804f3a816e55582dbec391bb4e1de853474cf6642ed8319c0276.json
@@ -0,0 +1,20 @@
+{
+ "db_name": "PostgreSQL",
+ "query": "\n UPDATE agent_session SET status = 'disconnected'\n WHERE id IN (\n SELECT id FROM agent_session\n WHERE list_hidden AND thread_id IS NULL\n AND created_at <= NOW() - INTERVAL '10 minutes'\n ORDER BY created_at LIMIT 64 FOR UPDATE SKIP LOCKED\n ) RETURNING id\n ",
+ "describe": {
+ "columns": [
+ {
+ "ordinal": 0,
+ "name": "id",
+ "type_info": "Uuid"
+ }
+ ],
+ "parameters": {
+ "Left": []
+ },
+ "nullable": [
+ false
+ ]
+ },
+ "hash": "f72b19d4ac7b804f3a816e55582dbec391bb4e1de853474cf6642ed8319c0276"
+}
diff --git a/apps/web/src/features/agents-view/views/AgentsView.tsx b/apps/web/src/features/agents-view/views/AgentsView.tsx
index 7b923e936a..2182f3a110 100644
--- a/apps/web/src/features/agents-view/views/AgentsView.tsx
+++ b/apps/web/src/features/agents-view/views/AgentsView.tsx
@@ -22,6 +22,7 @@ import { useUserId } from '@core/context/user';
import { isTouchDevice } from '@core/mobile/isTouchDevice';
import { ListEntityMetadataQueryProvider } from '@entity';
import SpinnerIcon from '@phosphor/spinner.svg';
+import { useWarmAgentSessionQuery } from '@queries/agent-session/warm';
import { useSoupItemsQuery } from '@queries/soup/items';
import {
createEffect,
@@ -78,6 +79,7 @@ function AgentsWorkspace(props: { initialRoute?: AgentsRoute }) {
const layout = useSplitLayout();
const orchestrator = useGlobalBlockOrchestrator();
const userId = useUserId();
+ useWarmAgentSessionQuery(userId);
const notifications = useGlobalNotificationSource();
const mode = (): AgentsMode => props.initialRoute?.mode ?? 'chat';
const dataMode = () => dataModeFor(mode());
diff --git a/apps/web/src/features/block-agent/context/pending-session.ts b/apps/web/src/features/block-agent/context/pending-session.ts
index 954834e5e3..daf548c976 100644
--- a/apps/web/src/features/block-agent/context/pending-session.ts
+++ b/apps/web/src/features/block-agent/context/pending-session.ts
@@ -23,6 +23,7 @@
import { handleAiUsageLimitError } from '@app/features/paywall/ai-usage-limit-handling';
import { AgentSession } from '@core/agent-session/AgentSession';
import { PromptTrace } from '@core/agent-session/prompt-telemetry';
+import { takeWarmAgentSession } from '@queries/agent-session/warm';
import { refetchSoupEntity } from '@queries/soup/normalized-cache';
import { agentHarnessServiceClient } from '@service-agent-harness/client';
import type {
@@ -93,7 +94,8 @@ export type StartPendingSessionOptions = {
export function startPendingSession(
options: StartPendingSessionOptions = {}
): string {
- const id = uuidv7();
+ const warmId = takeWarmAgentSession(options);
+ const id = warmId ?? uuidv7();
const prompt = options.prompt?.trim() ?? '';
// Started before the create so the whole wait up to the first output,
// and every request on the way, lands in one trace.
@@ -118,17 +120,25 @@ export function startPendingSession(
const traced = <T>(operation: () => T): T =>
trace ? trace.run(operation) : operation();
+ const create = (sessionId: string) =>
+ agentHarnessServiceClient.create({
+ id: sessionId,
+ ...(options.botId ? { botId: options.botId } : {}),
+ ...(options.modelOverride ? { model: options.modelOverride } : {}),
+ ...(options.instructions ? { instructions: options.instructions } : {}),
+ ...(options.repoUrl
+ ? { repoUrl: options.repoUrl, repoBranch: options.repoBranch }
+ : {}),
+ } satisfies CreateAgentSessionRequest);
+
+ // An expired or failed reservation must not prevent ordinary creation.
+ const createWithFallback = async () => {
+ const result = await create(id);
+ return warmId && result.isErr() ? await create(uuidv7()) : result;
+ };
+
void traced(() =>
- agentHarnessServiceClient
- .create({
- id,
- ...(options.botId ? { botId: options.botId } : {}),
- ...(options.modelOverride ? { model: options.modelOverride } : {}),
- ...(options.instructions ? { instructions: options.instructions } : {}),
- ...(options.repoUrl
- ? { repoUrl: options.repoUrl, repoBranch: options.repoBranch }
- : {}),
- } satisfies CreateAgentSessionRequest)
+ createWithFallback()
.then(async (result) => {
if (result.isErr()) {
handleAiUsageLimitError(result.error);
diff --git a/apps/web/src/features/block-agent/context/resolve-session-id.test.ts b/apps/web/src/features/block-agent/context/resolve-session-id.test.ts
index affe5076d4..c1e68f41cc 100644
--- a/apps/web/src/features/block-agent/context/resolve-session-id.test.ts
+++ b/apps/web/src/features/block-agent/context/resolve-session-id.test.ts
@@ -9,6 +9,11 @@ import type { AgentAction } from '@service-agent-harness/generated/schemas';
import { createRoot } from 'solid-js';
import { beforeEach, describe, expect, it, vi } from 'vitest';
+const takeWarm = vi.hoisted(() => vi.fn<() => string | undefined>());
+vi.mock('@queries/agent-session/warm', () => ({
+ takeWarmAgentSession: takeWarm,
+}));
+
const refetchSoupEntity = vi.hoisted(() => vi.fn(async () => {}));
// Session creation refreshes Soup in the background. Keep this unit test at
// the query boundary so real auth/network work cannot outlive its environment.
@@ -124,6 +129,7 @@ const { resolveSessionId } = await import('./resolve-session-id');
const flush = () => new Promise((resolve) => setTimeout(resolve, 0));
beforeEach(() => {
+ takeWarm.mockReset();
refetchSoupEntity.mockClear();
create.control.mockReset();
create.release.mockReset();
@@ -489,3 +495,21 @@ it.each([undefined, 'explicit-user'])(
});
}
);
+
+it('falls back to a cold session when claiming a warm session fails', async () => {
+ takeWarm.mockReturnValueOnce('stale-warm');
+ const placeholder = startPendingSession();
+ expect(placeholder).toBe('stale-warm');
+ create.reject?.();
+ await vi.waitFor(() => {
+ const request = vi.mocked(agentHarnessServiceClient.create).mock
+ .lastCall?.[0];
+ expect(request?.id).not.toBe('stale-warm');
+ });
+ create.resolve?.();
+ const { pendingSession } = await import('./pending-session');
+ await vi.waitFor(() =>
+ expect(pendingSession(placeholder)?.sessionId()).toBeTruthy()
+ );
+ expect(pendingSession(placeholder)?.failed()).toBe(false);
+});
diff --git a/apps/web/src/features/home/home-agent-composer.test.tsx b/apps/web/src/features/home/home-agent-composer.test.tsx
index a4be0e4dc7..7f2838db75 100644
--- a/apps/web/src/features/home/home-agent-composer.test.tsx
+++ b/apps/web/src/features/home/home-agent-composer.test.tsx
@@ -171,3 +171,7 @@ it('ignores suggested context that finishes after leaving Home', async () => {
'Newer Home draft'
);
});
+
+vi.mock('@queries/agent-session/warm', () => ({
+ useWarmAgentSessionQuery: vi.fn(),
+}));
diff --git a/apps/web/src/features/home/home-agent-composer.tsx b/apps/web/src/features/home/home-agent-composer.tsx
index d8081a7703..95fa999fcc 100644
--- a/apps/web/src/features/home/home-agent-composer.tsx
+++ b/apps/web/src/features/home/home-agent-composer.tsx
@@ -6,6 +6,7 @@ import { useSettingsState } from '@core/constant/SettingsState';
import { useUserId } from '@core/context/user';
import { registerHotkey } from '@core/hotkey/hotkeys';
import { TOKENS } from '@core/hotkey/tokens';
+import { useWarmAgentSessionQuery } from '@queries/agent-session/warm';
import { createEffect, onCleanup } from 'solid-js';
import '../agents-view/agents-view.css';
import { modeForKind } from '../agents-view/core/agent-kind';
@@ -29,6 +30,7 @@ export function HomeAgentComposer(props: { autoFocus?: boolean }) {
const roster = createAgentRosterSource();
const settings = useSettingsState();
const userId = useUserId();
+ useWarmAgentSessionQuery(userId);
const { draft, setDraft } = createPersistedComposerDraft(
HOME_CONVERSATION_DRAFT_KEY
);
diff --git a/apps/web/src/lib/queries/agent-session/keys.ts b/apps/web/src/lib/queries/agent-session/keys.ts
index a7461b12cf..f040b10ff6 100644
--- a/apps/web/src/lib/queries/agent-session/keys.ts
+++ b/apps/web/src/lib/queries/agent-session/keys.ts
@@ -25,3 +25,8 @@ export const agentSessionPullRequestKeys = createQueryKeys(
forSession: (sessionId: string) => ({ queryKey: [sessionId] }),
}
);
+
+/** Speculative, hidden sessions prepared for the signed-in owner. */
+export const agentSessionWarmKeys = createQueryKeys('agentSessionWarm', {
+ owner: (userId: string | undefined) => ({ queryKey: [userId] }),
+});
diff --git a/apps/web/src/lib/queries/agent-session/warm.test.tsx b/apps/web/src/lib/queries/agent-session/warm.test.tsx
new file mode 100644
index 0000000000..c2cbebe2c8
--- /dev/null
+++ b/apps/web/src/lib/queries/agent-session/warm.test.tsx
@@ -0,0 +1,69 @@
+/** @vitest-environment jsdom */
+import { MACRO_NEW_BOT_ID } from '@core/constant/macroNew';
+import { agentHarnessServiceClient } from '@service-agent-harness/client';
+import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';
+import { ok } from 'neverthrow';
+import { render } from 'solid-js/web';
+import { afterEach, expect, it, vi } from 'vitest';
+import { takeWarmAgentSession, useWarmAgentSessionQuery } from './warm';
+
+vi.mock('@service-agent-harness/client', () => ({
+ agentHarnessServiceClient: { warm: vi.fn() },
+}));
+const disposers: (() => void)[] = [];
+afterEach(() => {
+ for (const dispose of disposers.splice(0)) dispose();
+ vi.clearAllMocks();
+});
+
+it('deduplicates page mounts and claims only the same owner and configuration once', async () => {
+ vi.mocked(agentHarnessServiceClient.warm).mockResolvedValue(
+ ok({
+ session: { id: 'warm-id', model: 'model-a', instructions: null },
+ } as never)
+ );
+ const client = new QueryClient();
+ const take = (options: Parameters<typeof takeWarmAgentSession>[0]) =>
+ takeWarmAgentSession(options, client);
+ const Hook = () => {
+ useWarmAgentSessionQuery(() => 'warm-test-user');
+ return null;
+ };
+ for (let i = 0; i < 2; i++) {
+ const host = document.createElement('div');
+ disposers.push(
+ render(
+ () => (
+ <QueryClientProvider client={client}>
+ <Hook />
+ </QueryClientProvider>
+ ),
+ host
+ )
+ );
+ }
+ await vi.waitFor(() =>
+ expect(agentHarnessServiceClient.warm).toHaveBeenCalledTimes(1)
+ );
+ await vi.waitFor(() => expect(client.isFetching()).toBe(0));
+ expect(take({ userId: 'other', botId: MACRO_NEW_BOT_ID })).toBeUndefined();
+ expect(
+ take({
+ userId: 'warm-test-user',
+ botId: MACRO_NEW_BOT_ID,
+ modelOverride: 'different',
+ })
+ ).toBeUndefined();
+ expect(
+ take({
+ userId: 'warm-test-user',
+ botId: MACRO_NEW_BOT_ID,
+ instructions: 'different',
+ })
+ ).toBeUndefined();
+ expect(take({ userId: 'warm-test-user' })).toBe('warm-id');
+ expect(
+ take({ userId: 'warm-test-user', botId: MACRO_NEW_BOT_ID })
+ ).toBeUndefined();
+ client.clear();
+});
diff --git a/apps/web/src/lib/queries/agent-session/warm.ts b/apps/web/src/lib/queries/agent-session/warm.ts
new file mode 100644
index 0000000000..bdb6389da9
--- /dev/null
+++ b/apps/web/src/lib/queries/agent-session/warm.ts
@@ -0,0 +1,79 @@
+import { MACRO_NEW_BOT_ID } from '@core/constant/macroNew';
+import { throwOnErr } from '@core/util/result';
+import { agentHarnessServiceClient } from '@service-agent-harness/client';
+import { type QueryClient, useQuery } from '@tanstack/solid-query';
+import type { Accessor } from 'solid-js';
+import { v7 as uuidv7 } from 'uuid';
+import { queryClient } from '../client';
+import { agentSessionWarmKeys } from './keys';
+
+const CLIENT_WARM_TTL_MS = 5 * 60 * 1000;
+type WarmSession = {
+ id: string;
+ model: string;
+ instructions?: string | null;
+ expires: number;
+};
+
+/** Best-effort speculation; never read its data into a Suspense boundary. */
+export function useWarmAgentSessionQuery(userId: Accessor<string | undefined>) {
+ return useQuery(() => {
+ const owner = userId();
+ return {
+ queryKey: agentSessionWarmKeys.owner(owner).queryKey,
+ enabled: !!owner,
+ staleTime: CLIENT_WARM_TTL_MS,
+ gcTime: CLIENT_WARM_TTL_MS,
+ retry: false,
+ refetchOnWindowFocus: false,
+ queryFn: async ({ signal }: { signal: AbortSignal }) => {
+ if (!owner) return null;
+ const result = await throwOnErr(() =>
+ agentHarnessServiceClient.warm(uuidv7(), signal)
+ );
+ if (result.session) {
+ return {
+ id: result.session.id,
+ model: result.session.model,
+ instructions: result.session.instructions,
+ expires: Date.now() + CLIENT_WARM_TTL_MS,
+ } satisfies WarmSession;
+ }
+ return null;
+ },
+ };
+ });
+}
+
+/** Consume once, only for the owner and exact default-agent configuration. */
+export function takeWarmAgentSession(
+ options: {
+ userId?: string;
+ botId?: string;
+ modelOverride?: string;
+ instructions?: string;
+ repoUrl?: string;
+ },
+ client: QueryClient = queryClient
+): string | undefined {
+ if (
+ !options.userId ||
+ (options.botId && options.botId !== MACRO_NEW_BOT_ID) ||
+ options.repoUrl
+ )
+ return;
+ const key = agentSessionWarmKeys.owner(options.userId).queryKey;
+ const entry = client.getQueryData<WarmSession | null>(key);
+ if (!entry) return;
+ if (entry.expires <= Date.now()) {
+ client.setQueryData(key, null);
+ return;
+ }
+ if (options.modelOverride && options.modelOverride !== entry.model) return;
+ if (
+ (options.instructions?.trim() || '') !== (entry.instructions?.trim() || '')
+ )
+ return;
+ client.setQueryData(key, null);
+ return entry.id;
+}
diff --git a/apps/web/src/lib/queries/agents/models.test.tsx b/apps/web/src/lib/queries/agents/models.test.tsx
index f7286b6ef0..862728fef1 100644
--- a/apps/web/src/lib/queries/agents/models.test.tsx
+++ b/apps/web/src/lib/queries/agents/models.test.tsx
@@ -4,6 +4,7 @@
import { agentHarnessServiceClient } from '@service-agent-harness/client';
import { QueryClient, QueryClientProvider } from '@tanstack/solid-query';
+import { ok } from 'neverthrow';
import type { JSX } from 'solid-js';
import { render } from 'solid-js/web';
import { afterEach, beforeEach, describe, expect, it, vi } from 'vitest';
@@ -85,6 +86,50 @@ describe('agent model discovery', () => {
]);
});
+ it('keeps a loaded catalog across remounts', async () => {
+ vi.mocked(agentHarnessServiceClient.loadAgentModels).mockResolvedValue(
+ ok({
+ status: 'available',
+ models: [],
+ })
+ );
+
+ renderHook(() =>
+ useAgentModelsQueries(() => [
+ { harness: 'in-memory' },
+ { harness: 'cursor' },
+ ])
+ );
+ await vi.waitFor(() => {
+ expect(agentHarnessServiceClient.loadAgentModels).toHaveBeenCalledTimes(
+ 2
+ );
+ expect(
+ queryClient
+ .getQueryCache()
+ .getAll()
+ .every((query) => query.state.status === 'success')
+ ).toBe(true);
+ });
+
+ dispose?.();
+ renderHook(() =>
+ useAgentModelsQueries(() => [
+ { harness: 'in-memory' },
+ { harness: 'cursor' },
+ ])
+ );
+ await vi.waitFor(() => {
+ expect(
+ queryClient
+ .getQueryCache()
+ .getAll()
+ .every((query) => query.state.status === 'success')
+ ).toBe(true);
+ });
+ expect(agentHarnessServiceClient.loadAgentModels).toHaveBeenCalledTimes(2);
+ });
+
it('does not query Claude when its feature flag is off', async () => {
vi.mocked(agentHarnessServiceClient.loadAgentModels).mockReturnValue(
new Promise<never>(() => {})
diff --git a/apps/web/src/lib/queries/agents/models.ts b/apps/web/src/lib/queries/agents/models.ts
index 7c14c533ad..c8550e1e80 100644
--- a/apps/web/src/lib/queries/agents/models.ts
+++ b/apps/web/src/lib/queries/agents/models.ts
@@ -29,7 +29,23 @@ export function buildAgentModelTargets(
return targets;
}
+/** In-memory models are compiled into the harness and do not change at runtime. */
+const IN_MEMORY_MODELS_STALE_TIME = Number.POSITIVE_INFINITY;
+
+/**
+ * Cursor and macrod catalogs can change, but not between two mounts of the
+ * composer. Refetching on every mount put `agent-models/load` on the same
+ * service as the prompt.
+ */
+const REMOTE_MODELS_STALE_TIME = 5 * 60 * 1000;
+
+const MODELS_GC_TIME = 30 * 60 * 1000;
+
export function agentModelsQueryOptions(target: AgentModelTarget) {
+ const staleTime =
+ target.harness === 'in-memory'
+ ? IN_MEMORY_MODELS_STALE_TIME
+ : REMOTE_MODELS_STALE_TIME;
return {
queryKey: [
'agent-models',
@@ -45,8 +61,8 @@ export function agentModelsQueryOptions(target: AgentModelTarget) {
await throwOnErr(() =>
agentHarnessServiceClient.loadAgentModels(target, signal)
),
- gcTime: 0,
- staleTime: 0,
+ gcTime: MODELS_GC_TIME,
+ staleTime,
retry: false,
};
}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/client.ts b/apps/web/src/lib/service-clients/service-agent-harness/client.ts
index 507f733337..b58e68f811 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/client.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/client.ts
@@ -30,6 +30,7 @@ import type {
SharePermissionV2,
ToolApprovalAnswerDto,
UpdateSharePermissionRequestV2,
+ WarmAgentSessionResponse,
} from './generated/schemas';
export type { SandboxSize, SandboxSizeBody };
@@ -95,6 +96,19 @@ export const agentHarnessServiceClient = {
);
},
+ /** Prepare a hidden, unprompted in-memory session for this browser. */
+ warm(id: string, signal?: AbortSignal) {
+ return fetchWithToken<WarmAgentSessionResponse>(
+ `${agentHarnessHost}/agent-sessions/warm`,
+ {
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json' },
+ body: JSON.stringify({ id }),
+ signal,
+ }
+ );
+ },
+
create(request: CreateAgentSessionRequest) {
return fetchWithToken<
CreateAgentSessionResponse,
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts
index 7f89554690..7bc17977fe 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/client.ts
@@ -40,6 +40,8 @@ import type {
StatusResponse,
UnlinkAgentSessionPullRequestParams,
UpdateSharePermissionRequestV2,
+ WarmAgentSessionRequest,
+ WarmAgentSessionResponse,
} from './schemas';
/**
@@ -697,6 +699,49 @@ export const previewAgentSessions = async (
} as previewAgentSessionsResponse;
};
+/**
+ * @summary Prepare MCP connections without sending a prompt or creating a visible list row.
+ */
+export type warmAgentSessionHandlerResponse200 = {
+ data: WarmAgentSessionResponse;
+ status: 200;
+};
+
+export type warmAgentSessionHandlerResponseSuccess =
+ warmAgentSessionHandlerResponse200 & {
+ headers: Headers;
+ };
+
+export type warmAgentSessionHandlerResponse =
+ warmAgentSessionHandlerResponseSuccess;
+
+export const getWarmAgentSessionHandlerUrl = () => {
+ return `/agent-sessions/warm`;
+};
+
+export const warmAgentSessionHandler = async (
+ warmAgentSessionRequest: WarmAgentSessionRequest,
+ options?: RequestInit
+): Promise<warmAgentSessionHandlerResponse> => {
+ const res = await fetch(getWarmAgentSessionHandlerUrl(), {
+ ...options,
+ method: 'POST',
+ headers: { 'Content-Type': 'application/json', ...options?.headers },
+ body: JSON.stringify(warmAgentSessionRequest),
+ });
+
+ const body = [204, 205, 304].includes(res.status) ? null : await res.text();
+
+ const data: warmAgentSessionHandlerResponse['data'] = body
+ ? JSON.parse(body)
+ : {};
+ return {
+ data,
+ status: res.status,
+ headers: res.headers,
+ } as warmAgentSessionHandlerResponse;
+};
+
/**
* @summary Get an agent session by id.
*/
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts
index ed8e087241..ec881a8615 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/index.ts
@@ -220,4 +220,7 @@ export * from './updateSharePermissionRequestV2ChannelSharePermissions';
export * from './updateSharePermissionRequestV2LinkShare';
export * from './updateSharePermissionRequestV2LinkShareAccessLevel';
export * from './updateSharePermissionRequestV2TeamShareAccessLevel';
+export * from './warmAgentSessionRequest';
+export * from './warmAgentSessionResponse';
+export * from './warmAgentSessionResponseSession';
export * from './withAgentSessionId';
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionRequest.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionRequest.ts
new file mode 100644
index 0000000000..95f7795fb2
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionRequest.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+
+/**
+ * A client-minted id deduplicates warm calls without creating a conversation.
+ */
+export interface WarmAgentSessionRequest {
+ /** Id reserved by this browser for its next in-memory conversation. */
+ id: string;
+}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionResponse.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionResponse.ts
new file mode 100644
index 0000000000..60fb83748a
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionResponse.ts
@@ -0,0 +1,14 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { WarmAgentSessionResponseSession } from './warmAgentSessionResponseSession';
+
+/**
+ * A bounded best-effort warm attempt; absence means normal creation should proceed.
+ */
+export interface WarmAgentSessionResponse {
+ session?: WarmAgentSessionResponseSession;
+}
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionResponseSession.ts b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionResponseSession.ts
new file mode 100644
index 0000000000..09914fa60c
--- /dev/null
+++ b/apps/web/src/lib/service-clients/service-agent-harness/generated/schemas/warmAgentSessionResponseSession.ts
@@ -0,0 +1,9 @@
+/**
+ * Generated by orval v7.21.0 🍺
+ * Do not edit manually.
+ * agent_harness_service
+ * OpenAPI spec version: 0.1.0
+ */
+import type { AgentSessionResponse } from './agentSessionResponse';
+
+export type WarmAgentSessionResponseSession = null | AgentSessionResponse;
diff --git a/apps/web/src/lib/service-clients/service-agent-harness/openapi.json b/apps/web/src/lib/service-clients/service-agent-harness/openapi.json
index 739bea72b5..84f162abbd 100644
--- a/apps/web/src/lib/service-clients/service-agent-harness/openapi.json
+++ b/apps/web/src/lib/service-clients/service-agent-harness/openapi.json
@@ -496,6 +496,35 @@
}
}
},
+ "/agent-sessions/warm": {
+ "post": {
+ "tags": ["agent-sessions"],
+ "summary": "Prepare MCP connections without sending a prompt or creating a visible list row.",
+ "operationId": "warm_agent_session_handler",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WarmAgentSessionRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WarmAgentSessionResponse"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"/agent-sessions/{session_id}": {
"get": {
"tags": ["agent-sessions"],
@@ -4016,6 +4045,35 @@
}
}
},
+ "WarmAgentSessionRequest": {
+ "type": "object",
+ "description": "A client-minted id deduplicates warm calls without creating a conversation.",
+ "required": ["id"],
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "Id reserved by this browser for its next in-memory conversation."
+ }
+ }
+ },
+ "WarmAgentSessionResponse": {
+ "type": "object",
+ "description": "A bounded best-effort warm attempt; absence means normal creation should proceed.",
+ "properties": {
+ "session": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/AgentSessionResponse",
+ "description": "Prepared session, hidden until explicitly claimed through create."
+ }
+ ]
+ }
+ }
+ },
"WithAgentSessionId": {
"type": "object",
"description": "Just a session id, for the preview variants that carry nothing else.\n\nClients deserialize this, so both derives are used.",
diff --git a/crates/agent_harness/src/domain/claude/test.rs b/crates/agent_harness/src/domain/claude/test.rs
index 42e370eb52..a874c49e54 100644
--- a/crates/agent_harness/src/domain/claude/test.rs
+++ b/crates/agent_harness/src/domain/claude/test.rs
@@ -150,6 +150,7 @@ async fn seed(
) -> AgentSessionId {
let id = AgentSessionId::new();
repo.create(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
bot_id: bot,
diff --git a/crates/agent_harness/src/domain/ports/test.rs b/crates/agent_harness/src/domain/ports/test.rs
index 167c47a2aa..c9d8e97b1e 100644
--- a/crates/agent_harness/src/domain/ports/test.rs
+++ b/crates/agent_harness/src/domain/ports/test.rs
@@ -30,6 +30,7 @@ fn owner() -> MacroUserIdStr<'static> {
fn params(id: AgentSessionId) -> CreateAgentSessionParams {
CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: model_owner::Owner::User(owner()),
diff --git a/crates/agent_harness/src/domain/service.rs b/crates/agent_harness/src/domain/service.rs
index 781a8cc161..f917e7c276 100644
--- a/crates/agent_harness/src/domain/service.rs
+++ b/crates/agent_harness/src/domain/service.rs
@@ -22,6 +22,7 @@ mod lifecycle;
mod lifecycle_events;
mod open;
mod queue;
+mod warm;
use std::sync::Arc;
@@ -219,6 +220,9 @@ pub struct AgentHarnessService<
>,
workers: Arc<SessionWorkers>,
repositories: Option<Arc<dyn crate::domain::ports::ReachableRepositories>>,
+ warm_lifecycle: Option<Arc<dyn agent_session::domain::warm::WarmSessionLifecycle>>,
+ warm_tools: Arc<dyn agent_session::domain::ports::SessionToolCatalog>,
+ warm_reservations: Arc<tokio::sync::Mutex<warm::WarmReservations>>,
}
// Manual Clone impl so the port types don't need to be Clone (both fields
@@ -255,6 +259,9 @@ impl<
inner: Arc::clone(&self.inner),
workers: Arc::clone(&self.workers),
repositories: self.repositories.clone(),
+ warm_lifecycle: self.warm_lifecycle.clone(),
+ warm_tools: Arc::clone(&self.warm_tools),
+ warm_reservations: Arc::clone(&self.warm_reservations),
}
}
}
@@ -340,6 +347,9 @@ where
}),
workers: Arc::new(DashMap::new()),
repositories: None,
+ warm_lifecycle: None,
+ warm_tools: Arc::new(agent_session::domain::ports::NoOpToolCatalog),
+ warm_reservations: Arc::default(),
}
}
diff --git a/crates/agent_harness/src/domain/service/open.rs b/crates/agent_harness/src/domain/service/open.rs
index f55614b115..00054d9a95 100644
--- a/crates/agent_harness/src/domain/service/open.rs
+++ b/crates/agent_harness/src/domain/service/open.rs
@@ -3,12 +3,10 @@
//! where there is a sandbox to give it to, and attaches the runtime.
use agent_session::domain::model::session_owner_user;
-use agent_session::domain::ports::SelectedManagedPersona;
use agent_session::domain::repository_branch::RepositoryBranch;
use model_owner::Owner;
use super::*;
-use crate::domain::model::SessionRepository;
/// External sessions create the row and announce - the magic-chip message
/// the session's bot posts into the mention's thread, which is where the
@@ -95,6 +93,7 @@ where
.inner
.sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id: request.id.unwrap_or_else(AgentSessionId::new),
owner_id: request.owner,
@@ -155,233 +154,19 @@ where
/// originating mention and no thread to answer back into. The runtime is
/// spawned before the session is attached because there is nothing to
/// attach to until it exists.
- #[tracing::instrument(skip_all, err, fields(agent.session.id = tracing::field::Empty, agent.harness = tracing::field::Empty))]
async fn open_managed_session(
&self,
request: agent_session::domain::ports::OpenManagedSession,
) -> agent_session::domain::error::Result<AgentSession> {
- let managed_defaults = self.inner.defaults.managed();
- let (bot_id, model, harness, instructions, mut mcp_servers) = match request.profile {
- Some(SelectedManagedPersona {
- bot_id,
- profile: Some(profile),
- }) => (
- bot_id,
- profile.model,
- profile.harness,
- Some(profile.instructions).filter(|value| !value.trim().is_empty()),
- profile.mcp_servers,
- ),
- // A fixed system bot picked by name runs on the deployment's
- // defaults for it, the same way a channel mention would open it.
- Some(SelectedManagedPersona {
- bot_id,
- profile: None,
- }) => {
- let defaults = self.inner.defaults.for_bot(bot_id);
- (
- bot_id,
- defaults.model.clone(),
- defaults.harness.clone(),
- request.instructions,
- AgentMcpServers::OwnerConnections,
- )
- }
- None => (
- managed_defaults.bot_id,
- managed_defaults.model.clone(),
- managed_defaults.harness.clone(),
- request.instructions,
- AgentMcpServers::OwnerConnections,
- ),
- };
- // A caller's pick outranks the persona's: choosing a model on the way
- // in is choosing what this session runs on, for its whole life.
- let model = request.model.unwrap_or(model);
- let kind = AgentKind::for_session(bot_id, &harness);
- let harness = kind.harness_slug().map_or(harness, str::to_owned);
- tracing::Span::current().record("agent.harness", &harness);
- if kind == AgentKind::CodexCloud {
- mcp_servers = AgentMcpServers::Selected {
- servers: Vec::new(),
- };
- }
- let owner_user = session_owner_user(&request.owner)?;
- let session_id = request.id.unwrap_or_else(AgentSessionId::new);
- tracing::Span::current().record("agent.session.id", tracing::field::display(session_id));
- // Explicit source choices are a domain decision, before any session or egress grant exists.
- let selected_repo = if let Some(url) = request.repo_url.as_deref() {
- if kind != AgentKind::Cursor {
- return Err(
- agent_session::domain::error::AgentSessionError::InvalidRepositorySelection(
- "repository selection is supported for Cursor coding agents",
- ),
- );
- }
- let repo = SessionRepository::parse(url).ok_or(
- agent_session::domain::error::AgentSessionError::InvalidRepositorySelection(
- "select a valid GitHub repository",
- ),
- )?;
- let repositories = self
- .repositories
- .as_ref()
- .ok_or(agent_session::domain::error::AgentSessionError::Forbidden)?;
- let reachable = repositories
- .for_user(&owner_user)
- .await
- .map_err(into_session_error)?;
- let listed = reachable
- .iter()
- .find(|allowed| allowed.url.eq_ignore_ascii_case(repo.as_str()))
- .ok_or(agent_session::domain::error::AgentSessionError::Forbidden)?;
- // The caller's branch, or the one the repository's own clones start on.
- let branch = request
- .repo_branch
- .clone()
- .unwrap_or_else(|| starting_branch(listed.default_branch.as_deref()));
- Some((repo, branch))
- } else {
- if request.repo_branch.is_some() {
- return Err(
- agent_session::domain::error::AgentSessionError::InvalidRepositorySelection(
- "select a repository before choosing a branch",
- ),
- );
- }
- None
- };
- self.inner
- .admit_open(bot_id, &harness, &owner_user)
- .instrument(tracing::info_span!("agent.init.admission", agent.session.id = %session_id))
- .await
- .map_err(into_session_error)?;
- let defaults = self.inner.defaults.for_bot(bot_id);
- let sandbox_size = self
- .inner
- .sessions
- .user_sandbox_size(&owner_user)
- .instrument(
- tracing::info_span!("agent.init.preferences", agent.session.id = %session_id),
- )
- .await?;
- // Same ordering as the trigger path's open: the token has to be minted
- // before the row, because the row is what carries the hash that makes
- // it mean anything.
- let egress = self
- .inner
- .egress
- .provision(session_id, &owner_user, &mcp_servers)
- .instrument(tracing::info_span!("agent.init.egress", agent.session.id = %session_id))
- .await
- .map_err(into_session_error)?;
- let session = self
- .inner
- .sessions
- .create_session(CreateAgentSessionParams {
- repo_branch: selected_repo.as_ref().map(|(_, branch)| branch.clone()),
- id: session_id,
- owner_id: request.owner,
- bot_id,
- thread_id: None,
- originating_message_id: None,
- model,
- harness,
- // Whatever this bot's sessions work in: the deployment's
- // repository, or nothing for a bot whose sessions work
- // somewhere this deployment does not name.
- repo_url: selected_repo
- .as_ref()
- .map(|(repo, _)| repo)
- .or(defaults.repo_url.as_ref())
- .map(|repo| repo.as_str().to_owned()),
- // Managed sandboxes run in the path baked into their image.
- workspace: agent_session::MANAGED_CONTAINER_WORKSPACE.to_owned(),
- sandbox_size,
- instructions,
- mcp_servers,
- egress_token_hash: Some(egress.session_token_hash),
- })
- .instrument(tracing::info_span!("agent.init.persist", agent.session.id = %session_id))
- .await?;
- self.inner
- .publish_opened(&session)
- .instrument(tracing::info_span!("agent.init.publish", agent.session.id = %session_id))
- .await;
-
- let mcp_servers = if kind == AgentKind::CodexCloud {
- Vec::new()
- } else {
- egress.sandbox.acp_servers()
- };
- let container = match self
- .inner
- .containers
- .spawn(SpawnContainer {
- session_id: session.id,
- kind: AgentKind::for_session(session.bot_id, &session.harness),
- size: sandbox_size,
- egress: egress.sandbox,
- })
- .instrument(tracing::info_span!("agent.init.runtime", agent.session.id = %session_id))
- .await
- {
- Ok(container) => container,
- // The row is already persisted, so a sandbox that never arrived
- // would otherwise leave a session claiming to be live. Same
- // handling as the trigger path's open.
- Err(error) => {
- let _ = self
- .inner
- .sessions
- .mark_disconnected(session.id)
- .await
- .inspect_err(|status_error| {
- tracing::error!(
- error = ?status_error,
- session_id = %session.id,
- "failed to mark an unprovisioned session disconnected"
- );
- });
- return Err(into_session_error(error));
- }
- };
- let permission_policy = self
- .inner
- .permission_policy_for(session.bot_id)
- .instrument(
- tracing::info_span!("agent.init.permissions", agent.session.id = %session_id),
- )
- .await;
- self.inner
- .sessions
- .attach_session(
- session.id,
- container
- .mcp_servers(mcp_servers)
- .permission_policy(permission_policy),
- )
- .instrument(tracing::info_span!("agent.init.attach", agent.session.id = %session_id))
- .await?;
-
- // Raw, through the session's own command worker: dispatch is where a
- // prompt is composed, and the worker is what serializes this first
- // prompt against any control prompt racing the session's birth.
- if let Some(raw_prompt) = request.prompt {
- self.execute_here(
- session.id,
- HarnessCommand::Deliver(DeliverAction {
- id: AgentActionId::mint(),
- action: AgentAction::prompt(raw_prompt),
- actor: Some(owner_user),
- announce: None,
- }),
- )
- .await
- .map_err(into_session_error)?;
- }
+ self.open_managed_session_inner(request, false).await
+ }
- Ok(session)
+ async fn warm_session(
+ &self,
+ owner: Owner,
+ id: AgentSessionId,
+ ) -> agent_session::domain::error::Result<Option<AgentSession>> {
+ self.prepare_warm(owner, id).await
}
async fn find_thread_session(
@@ -522,6 +307,7 @@ where
let session = self
.sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id: session_id,
owner_id: Owner::User(actor.clone()),
diff --git a/crates/agent_harness/src/domain/service/test.rs b/crates/agent_harness/src/domain/service/test.rs
index 532c0cb21a..b0cb90cd39 100644
--- a/crates/agent_harness/src/domain/service/test.rs
+++ b/crates/agent_harness/src/domain/service/test.rs
@@ -5,6 +5,7 @@
mod chat_reply;
mod quota;
mod user_cleanup;
+mod warm;
use agent_session::domain::service::AgentSessionService as _;
use messages::domain::models::MessageParent;
@@ -675,6 +676,7 @@ async fn disconnected_session_owned_by(
agent_session::domain::ports::AgentSessionRepo::create(
repo,
CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: owner,
diff --git a/crates/agent_harness/src/domain/service/test/quota.rs b/crates/agent_harness/src/domain/service/test/quota.rs
index 5bb9bdd6ff..934099e554 100644
--- a/crates/agent_harness/src/domain/service/test/quota.rs
+++ b/crates/agent_harness/src/domain/service/test/quota.rs
@@ -53,6 +53,7 @@ async fn session(
agent_session::domain::ports::AgentSessionRepo::create(
repo,
CreateAgentSessionParams {
+ warm: false,
id,
owner_id: owner,
bot_id: bot,
diff --git a/crates/agent_harness/src/domain/service/test/reopen.rs b/crates/agent_harness/src/domain/service/test/reopen.rs
index f31c100794..46c6bac31b 100644
--- a/crates/agent_harness/src/domain/service/test/reopen.rs
+++ b/crates/agent_harness/src/domain/service/test/reopen.rs
@@ -8,6 +8,7 @@ async fn codex_session(
agent_session::domain::ports::AgentSessionRepo::create(
repo,
CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: model_owner::Owner::User(sender()),
diff --git a/crates/agent_harness/src/domain/service/test/warm.rs b/crates/agent_harness/src/domain/service/test/warm.rs
new file mode 100644
index 0000000000..0c028541f2
--- /dev/null
+++ b/crates/agent_harness/src/domain/service/test/warm.rs
@@ -0,0 +1,154 @@
+use super::*;
+
+struct WarmLifecycleStub {
+ claim: bool,
+}
+impl agent_session::domain::warm::WarmSessionLifecycle for WarmLifecycleStub {
+ fn claim<'a>(
+ &'a self,
+ _id: AgentSessionId,
+ _owner: &'a model_owner::Owner,
+ _bot: BotId,
+ _model: &'a str,
+ _instructions: Option<&'a str>,
+ ) -> std::pin::Pin<
+ Box<
+ dyn std::future::Future<Output = agent_session::domain::error::Result<bool>>
+ + Send
+ + 'a,
+ >,
+ > {
+ Box::pin(async { Ok(self.claim) })
+ }
+ fn expire(
+ &self,
+ ) -> std::pin::Pin<
+ Box<
+ dyn std::future::Future<
+ Output = agent_session::domain::error::Result<Vec<AgentSessionId>>,
+ > + Send
+ + '_,
+ >,
+ > {
+ Box::pin(async { Ok(Vec::new()) })
+ }
+}
+
+#[tokio::test]
+async fn warming_rejects_bot_owners_and_bounds_speculation_per_user() {
+ let (service, _, containers, _, _) = harness();
+ let service = service.with_warm_sessions(
+ Arc::new(WarmLifecycleStub { claim: false }),
+ Arc::new(agent_session::domain::ports::NoOpToolCatalog),
+ );
+ assert!(matches!(
+ service
+ .warm_session(
+ model_owner::Owner::Bot(BotId::TEST_A),
+ AgentSessionId::new()
+ )
+ .await,
+ Err(AgentSessionError::OwnerNotUser(_))
+ ));
+ let owner = model_owner::Owner::User(sender());
+ {
+ let mut reservations = service.warm_reservations.lock().await;
+ for _ in 0..2 {
+ reservations.insert(
+ AgentSessionId::new(),
+ (owner.clone(), std::time::Instant::now()),
+ );
+ }
+ }
+ assert!(
+ service
+ .warm_session(owner, AgentSessionId::new())
+ .await
+ .unwrap()
+ .is_none()
+ );
+ assert_eq!(containers.spawned(), 0);
+}
+
+struct GatedWarmTools(tokio::sync::Semaphore);
+
+impl agent_session::domain::ports::SessionToolCatalog for GatedWarmTools {
+ fn tool_definitions(
+ &self,
+ _servers: Vec<agent_client_protocol::schema::v1::McpServer>,
+ ) -> std::pin::Pin<
+ Box<
+ dyn Future<Output = Vec<agent_session::domain::ports::SessionToolDefinition>>
+ + Send
+ + '_,
+ >,
+ > {
+ Box::pin(async {
+ self.0.acquire().await.expect("test gate is open").forget();
+ Vec::new()
+ })
+ }
+}
+
+#[tokio::test]
+async fn warming_initializes_without_a_prompt_or_visible_created_event() {
+ let ((service, repo, containers, _, _), signals) =
+ harness_with_signals(PromptContextMock::default(), PromptComposerMock::default());
+ let tools = Arc::new(GatedWarmTools(tokio::sync::Semaphore::new(0)));
+ let service =
+ service.with_warm_sessions(Arc::new(WarmLifecycleStub { claim: true }), tools.clone());
+ let id = AgentSessionId::new();
+ let mut warm = Box::pin(service.warm_session(model_owner::Owner::User(sender()), id));
+ let drive = async {
+ loop {
+ if containers.spawned() == 1 {
+ break;
+ }
+ tokio::task::yield_now().await;
+ }
+ let container = containers.container(id).expect("warm runtime");
+ complete_session_handshake(&container).await;
+ assert!(prompts(&container.agent()).is_empty());
+ };
+ tokio::select! {
+ result = &mut warm => panic!("warm returned before MCP readiness: {result:?}"),
+ () = drive => {},
+ }
+ assert!(
+ tokio::time::timeout(std::time::Duration::from_millis(20), &mut warm)
+ .await
+ .is_err()
+ );
+ tools.0.add_permits(1);
+ assert_eq!(warm.await.unwrap().unwrap().id, id);
+ assert!(repo.get(id).await.is_ok());
+ assert!(signals.lifecycle.published().is_empty());
+ let claimed = service
+ .open_managed_session(OpenManagedSession {
+ id: Some(id),
+ owner: model_owner::Owner::User(sender()),
+ prompt: None,
+ repo_url: None,
+ repo_branch: None,
+ instructions: None,
+ model: None,
+ profile: Some(agent_session::domain::ports::SelectedManagedPersona {
+ bot_id: bot_id::MACRO_NEW_BOT_ID,
+ profile: None,
+ }),
+ })
+ .await
+ .expect("claim prepared session");
+ assert_eq!(claimed.id, id);
+ assert!(service.warm_reservations.lock().await.is_empty());
+ assert_eq!(
+ containers.spawned(),
+ 1,
+ "claim must reuse the prepared runtime"
+ );
+ assert_eq!(
+ signals.lifecycle.published().len(),
+ 1,
+ "claim reveals the conversation"
+ );
+}
diff --git a/crates/agent_harness/src/domain/service/warm.rs b/crates/agent_harness/src/domain/service/warm.rs
new file mode 100644
index 0000000000..7a5da22e5b
--- /dev/null
+++ b/crates/agent_harness/src/domain/service/warm.rs
@@ -0,0 +1,431 @@
+//! Speculative in-memory sessions. No model or tool is invoked during warming.
+use super::open::starting_branch;
+use super::*;
+use crate::domain::model::SessionRepository;
+use agent_session::domain::model::session_owner_user;
+use agent_session::domain::ports::{OpenManagedSession, SelectedManagedPersona};
+use model_owner::Owner;
+use std::time::{Duration, Instant};
+
+const WARM_RESERVATION_TTL: Duration = Duration::from_secs(600);
+const WARM_PREPARATION_TIMEOUT: Duration = Duration::from_secs(30);
+const ACP_READY_POLL_INTERVAL: Duration = Duration::from_millis(10);
+const MAX_WARM_RESERVATIONS: usize = 64;
+const MAX_WARM_RESERVATIONS_PER_OWNER: usize = 2;
+
+pub(super) type WarmReservations = std::collections::HashMap<AgentSessionId, (Owner, Instant)>;
+
+impl<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+ Lifecycle,
+ Mentions,
+ Notifier,
+>
+ AgentHarnessService<
+ Sessions,
+ Containers,
+ Announcer,
+ Runtimes,
+ PromptContext,
+ PromptComposer,
+ Egress,
+ Lifecycle,
+ Mentions,
+ Notifier,
+ >
+where
+ Sessions: AgentSessionService,
+ Containers: ContainerManager,
+ Announcer: SessionAnnouncer,
+ Runtimes: RuntimeConnections,
+ PromptContext: MessagePromptContext,
+ PromptComposer: AgentPromptComposer,
+ Egress: SandboxEgressProvisioner,
+ Lifecycle: AgentSessionLifecyclePublisher,
+ Mentions: PromptMentions,
+ Notifier: AgentSessionNotifier,
+{
+ #[tracing::instrument(skip_all, err, fields(agent.session.id = tracing::field::Empty, agent.harness = tracing::field::Empty, agent.session.warm = warm, agent.session.warm_hit = false))]
+ pub(super) async fn open_managed_session_inner(
+ &self,
+ request: agent_session::domain::ports::OpenManagedSession,
+ warm: bool,
+ ) -> agent_session::domain::error::Result<AgentSession> {
+ let managed_defaults = self.inner.defaults.managed();
+ let (bot_id, model, harness, instructions, mut mcp_servers) = match request.profile {
+ Some(SelectedManagedPersona {
+ bot_id,
+ profile: Some(profile),
+ }) => (
+ bot_id,
+ profile.model,
+ profile.harness,
+ Some(profile.instructions).filter(|value| !value.trim().is_empty()),
+ profile.mcp_servers,
+ ),
+ // A fixed system bot picked by name runs on the deployment's
+ // defaults for it, the same way a channel mention would open it.
+ Some(SelectedManagedPersona {
+ bot_id,
+ profile: None,
+ }) => {
+ let defaults = self.inner.defaults.for_bot(bot_id);
+ (
+ bot_id,
+ defaults.model.clone(),
+ defaults.harness.clone(),
+ request.instructions,
+ AgentMcpServers::OwnerConnections,
+ )
+ }
+ None => (
+ managed_defaults.bot_id,
+ managed_defaults.model.clone(),
+ managed_defaults.harness.clone(),
+ request.instructions,
+ AgentMcpServers::OwnerConnections,
+ ),
+ };
+ // A caller's pick outranks the persona's: choosing a model on the way
+ // in is choosing what this session runs on, for its whole life.
+ let model = request.model.unwrap_or(model);
+ let kind = AgentKind::for_session(bot_id, &harness);
+ let harness = kind.harness_slug().map_or(harness, str::to_owned);
+ tracing::Span::current().record("agent.harness", &harness);
+ if kind == AgentKind::CodexCloud {
+ mcp_servers = AgentMcpServers::Selected {
+ servers: Vec::new(),
+ };
+ }
+ let owner_user = session_owner_user(&request.owner)?;
+ let session_id = request.id.unwrap_or_else(AgentSessionId::new);
+ tracing::Span::current().record("agent.session.id", tracing::field::display(session_id));
+ // Explicit source choices are a domain decision, before any session or egress grant exists.
+ let selected_repo = if let Some(url) = request.repo_url.as_deref() {
+ if kind != AgentKind::Cursor {
+ return Err(
+ agent_session::domain::error::AgentSessionError::InvalidRepositorySelection(
+ "repository selection is supported for Cursor coding agents",
+ ),
+ );
+ }
+ let repo = SessionRepository::parse(url).ok_or(
+ agent_session::domain::error::AgentSessionError::InvalidRepositorySelection(
+ "select a valid GitHub repository",
+ ),
+ )?;
+ let repositories = self
+ .repositories
+ .as_ref()
+ .ok_or(agent_session::domain::error::AgentSessionError::Forbidden)?;
+ let reachable = repositories
+ .for_user(&owner_user)
+ .await
+ .map_err(into_session_error)?;
+ let listed = reachable
+ .iter()
+ .find(|allowed| allowed.url.eq_ignore_ascii_case(repo.as_str()))
+ .ok_or(agent_session::domain::error::AgentSessionError::Forbidden)?;
+ // The caller's branch, or the one the repository's own clones start on.
+ let branch = request
+ .repo_branch
+ .clone()
+ .unwrap_or_else(|| starting_branch(listed.default_branch.as_deref()));
+ Some((repo, branch))
+ } else {
+ if request.repo_branch.is_some() {
+ return Err(
+ agent_session::domain::error::AgentSessionError::InvalidRepositorySelection(
+ "select a repository before choosing a branch",
+ ),
+ );
+ }
+ None
+ };
+ self.inner
+ .admit_open(bot_id, &harness, &owner_user)
+ .instrument(tracing::info_span!("agent.init.admission", agent.session.id = %session_id))
+ .await
+ .map_err(into_session_error)?;
+ if !warm
+ && kind == AgentKind::InMemory
+ && bot_id == bot_id::MACRO_NEW_BOT_ID
+ && matches!(mcp_servers, AgentMcpServers::OwnerConnections)
+ && request.repo_url.is_none()
+ && let Some(lifecycle) = &self.warm_lifecycle
+ && lifecycle
+ .claim(
+ session_id,
+ &request.owner,
+ bot_id,
+ &model,
+ instructions.as_deref(),
+ )
+ .await?
+ {
+ self.warm_reservations.lock().await.remove(&session_id);
+ tracing::Span::current().record("agent.session.warm_hit", true);
+ let session = self.inner.sessions.get_session(session_id).await?;
+ self.inner
+ .publish_opened(&session)
+ .instrument(
+ tracing::info_span!("agent.init.publish", agent.session.id = %session_id),
+ )
+ .await;
+ if let Some(prompt) = request.prompt {
+ self.execute(
+ session_id,
+ HarnessCommand::Deliver(DeliverAction {
+ id: AgentActionId::mint(),
+ action: AgentAction::prompt(prompt),
+ actor: Some(owner_user),
+ announce: None,
+ }),
+ )
+ .await
+ .map_err(into_session_error)?;
+ }
+ return Ok(session);
+ }
+ let defaults = self.inner.defaults.for_bot(bot_id);
+ let sandbox_size = self
+ .inner
+ .sessions
+ .user_sandbox_size(&owner_user)
+ .instrument(
+ tracing::info_span!("agent.init.preferences", agent.session.id = %session_id),
+ )
+ .await?;
+ // Same ordering as the trigger path's open: the token has to be minted
+ // before the row, because the row is what carries the hash that makes
+ // it mean anything.
+ let egress = self
+ .inner
+ .egress
+ .provision(session_id, &owner_user, &mcp_servers)
+ .instrument(tracing::info_span!("agent.init.egress", agent.session.id = %session_id))
+ .await
+ .map_err(into_session_error)?;
+ let session = self
+ .inner
+ .sessions
+ .create_session(CreateAgentSessionParams {
+ warm,
+ repo_branch: selected_repo.as_ref().map(|(_, branch)| branch.clone()),
+ id: session_id,
+ owner_id: request.owner,
+ bot_id,
+ thread_id: None,
+ originating_message_id: None,
+ model,
+ harness,
+ // Whatever this bot's sessions work in: the deployment's
+ // repository, or nothing for a bot whose sessions work
+ // somewhere this deployment does not name.
+ repo_url: selected_repo
+ .as_ref()
+ .map(|(repo, _)| repo)
+ .or(defaults.repo_url.as_ref())
+ .map(|repo| repo.as_str().to_owned()),
+ // Managed sandboxes run in the path baked into their image.
+ workspace: agent_session::MANAGED_CONTAINER_WORKSPACE.to_owned(),
+ sandbox_size,
+ instructions,
+ mcp_servers,
+ egress_token_hash: Some(egress.session_token_hash),
+ })
+ .instrument(tracing::info_span!("agent.init.persist", agent.session.id = %session_id))
+ .await?;
+ if !warm {
+ self.inner
+ .publish_opened(&session)
+ .instrument(
+ tracing::info_span!("agent.init.publish", agent.session.id = %session_id),
+ )
+ .await;
+ }
+
+ let mcp_servers = if kind == AgentKind::CodexCloud {
+ Vec::new()
+ } else {
+ egress.sandbox.acp_servers()
+ };
+ let container = match self
+ .inner
+ .containers
+ .spawn(SpawnContainer {
+ session_id: session.id,
+ kind: AgentKind::for_session(session.bot_id, &session.harness),
+ size: sandbox_size,
+ egress: egress.sandbox,
+ })
+ .instrument(tracing::info_span!("agent.init.runtime", agent.session.id = %session_id))
+ .await
+ {
+ Ok(container) => container,
+ // The row is already persisted, so a sandbox that never arrived
+ // would otherwise leave a session claiming to be live. Same
+ // handling as the trigger path's open.
+ Err(error) => {
+ let _ = self
+ .inner
+ .sessions
+ .mark_disconnected(session.id)
+ .await
+ .inspect_err(|status_error| {
+ tracing::error!(
+ error = ?status_error,
+ session_id = %session.id,
+ "failed to mark an unprovisioned session disconnected"
+ );
+ });
+ return Err(into_session_error(error));
+ }
+ };
+ let permission_policy = self
+ .inner
+ .permission_policy_for(session.bot_id)
+ .instrument(
+ tracing::info_span!("agent.init.permissions", agent.session.id = %session_id),
+ )
+ .await;
+ self.inner
+ .sessions
+ .attach_session(
+ session.id,
+ container
+ .mcp_servers(mcp_servers.clone())
+ .permission_policy(permission_policy),
+ )
+ .instrument(tracing::info_span!("agent.init.attach", agent.session.id = %session_id))
+ .await?;
+
+ if warm {
+ // Ordinary session/new returns while MCP initializes in the background.
+ // Speculation is only ready after the same shared connector pool has
+ // finished listing and the runtime has answered its handshake.
+ self.warm_tools.tool_definitions(mcp_servers).await;
+ while self
+ .inner
+ .sessions
+ .get_session(session.id)
+ .await?
+ .acp_session_id
+ .is_none()
+ {
+ tokio::time::sleep(ACP_READY_POLL_INTERVAL).await;
+ }
+ }
+
+ // Raw, through the session's own command worker: dispatch is where a
+ // prompt is composed, and the worker is what serializes this first
+ // prompt against any control prompt racing the session's birth.
+ if let Some(raw_prompt) = request.prompt {
+ self.execute_here(
+ session.id,
+ HarnessCommand::Deliver(DeliverAction {
+ id: AgentActionId::mint(),
+ action: AgentAction::prompt(raw_prompt),
+ actor: Some(owner_user),
+ announce: None,
+ }),
+ )
+ .await
+ .map_err(into_session_error)?;
+ }
+
+ Ok(session)
+ }
+
+ /// Configure the owning session domain's atomic claim and expiry port.
+ pub fn with_warm_sessions(
+ mut self,
+ lifecycle: Arc<dyn agent_session::domain::warm::WarmSessionLifecycle>,
+ tools: Arc<dyn agent_session::domain::ports::SessionToolCatalog>,
+ ) -> Self {
+ self.warm_lifecycle = Some(lifecycle);
+ self.warm_tools = tools;
+ self
+ }
+
+ pub(super) async fn prepare_warm(
+ &self,
+ owner: Owner,
+ id: AgentSessionId,
+ ) -> agent_session::domain::error::Result<Option<AgentSession>> {
+ session_owner_user(&owner)?;
+ if self.warm_lifecycle.is_none() {
+ return Ok(None);
+ }
+ {
+ let mut reservations = self.warm_reservations.lock().await;
+ reservations.retain(|_, (_, started)| started.elapsed() < WARM_RESERVATION_TTL);
+ if reservations.contains_key(&id) {
+ return Ok(None);
+ }
+ if reservations.len() >= MAX_WARM_RESERVATIONS
+ || reservations
+ .values()
+ .filter(|(user, _)| user == &owner)
+ .count()
+ >= MAX_WARM_RESERVATIONS_PER_OWNER
+ {
+ return Ok(None);
+ }
+ reservations.insert(id, (owner.clone(), Instant::now()));
+ }
+ let request = OpenManagedSession {
+ id: Some(id),
+ owner,
+ prompt: None,
+ repo_url: None,
+ repo_branch: None,
+ profile: Some(SelectedManagedPersona {
+ bot_id: bot_id::MACRO_NEW_BOT_ID,
+ profile: None,
+ }),
+ instructions: None,
+ model: None,
+ };
+ match tokio::time::timeout(
+ WARM_PREPARATION_TIMEOUT,
+ self.open_managed_session_inner(request, true),
+ )
+ .await
+ {
+ Ok(Ok(session)) => Ok(Some(session)),
+ Ok(Err(error)) => {
+ tracing::warn!(error = ?error, "warm session preparation failed");
+ Ok(None)
+ }
+ Err(_) => {
+ tracing::warn!("warm session preparation timed out");
+ Ok(None)
+ }
+ }
+ }
+
+ /// Periodic bounded cleanup, including reservations left by a previous process.
+ pub async fn reap_warm_sessions(&self) {
+ let Some(lifecycle) = &self.warm_lifecycle else {
+ return;
+ };
+ match lifecycle.expire().await {
+ Ok(ids) => {
+ for id in ids {
+ self.warm_reservations.lock().await.remove(&id);
+ if let Err(error) = self.execute(id, HarnessCommand::Delete).await {
+ tracing::warn!(error = ?error, session_id = %id, "warm session cleanup failed");
+ }
+ }
+ }
+ Err(error) => tracing::warn!(error = ?error, "warm session expiry failed"),
+ }
+ }
+}
diff --git a/crates/agent_inmem/src/domain/mcp.rs b/crates/agent_inmem/src/domain/mcp.rs
index 8569349b4e..a37f732ffd 100644
--- a/crates/agent_inmem/src/domain/mcp.rs
+++ b/crates/agent_inmem/src/domain/mcp.rs
@@ -51,10 +51,21 @@ pub fn dialable_servers(servers: Vec<AcpMcpServer>) -> Vec<McpServerHttp> {
pub trait McpToolConnector: Send + Sync + 'static {
/// Connect to every server, skipping any that fail, and return the tools
/// found. `None` when no server yielded any tool.
+ ///
+ /// A connector may return sessions it already has open. Callers still
+ /// await this before the first turn that needs the tools, and a hit
+ /// returns without dialing.
fn connect(
&self,
servers: Vec<McpServerHttp>,
) -> impl Future<Output = Option<RemoteMcpToolSet>> + Send;
+
+ /// Drop pooled sessions authenticated with `token`.
+ ///
+ /// Connectors that do not keep sessions across [`connect`](Self::connect)
+ /// calls do nothing. Called when a session is torn down, so a token that
+ /// will never be presented again does not leave its upstream sessions open.
+ fn release(&self, _token: &str) {}
}
/// Erased form of [`McpToolConnector`] for storage on the agent state.
@@ -64,6 +75,9 @@ pub trait DynMcpToolConnector: Send + Sync + 'static {
&self,
servers: Vec<McpServerHttp>,
) -> std::pin::Pin<Box<dyn Future<Output = Option<RemoteMcpToolSet>> + Send + '_>>;
+
+ /// See [`McpToolConnector::release`].
+ fn release_dyn(&self, token: &str);
}
impl<C: McpToolConnector> DynMcpToolConnector for C {
@@ -73,6 +87,10 @@ impl<C: McpToolConnector> DynMcpToolConnector for C {
) -> std::pin::Pin<Box<dyn Future<Output = Option<RemoteMcpToolSet>> + Send + '_>> {
Box::pin(self.connect(servers))
}
+
+ fn release_dyn(&self, token: &str) {
+ self.release(token);
+ }
}
/// A connector for deployments and tests that hand the runtime no servers.
diff --git a/crates/agent_inmem/src/outbound/acp_mcp.rs b/crates/agent_inmem/src/outbound/acp_mcp.rs
index 29c721b53f..1fffcb1d4e 100644
--- a/crates/agent_inmem/src/outbound/acp_mcp.rs
+++ b/crates/agent_inmem/src/outbound/acp_mcp.rs
@@ -1,16 +1,26 @@
//! Dialing the HTTP MCP servers a session was handed over ACP.
+//!
+//! Sessions are pooled by server name, URL, and credential. A later turn, a
+//! replaced agent task, and the telemetry catalog all reuse the open session
+//! and the tool list it already returned, instead of handshaking again. The
+//! pool drops a session when its bearer token is released at teardown, or
+//! when the session itself has closed.
use std::collections::HashMap;
+use std::sync::{Arc, Mutex};
+use std::time::{Duration, Instant};
use agent_client_protocol::schema::v1::McpServerHttp;
+use futures::FutureExt as _;
+use futures::future::BoxFuture;
use http::header::{AUTHORIZATION, HeaderName, HeaderValue};
-use mcp_toolset::{ConnectedServer, RemoteMcpToolSet, client_info};
+use mcp_toolset::{ListedServer, McpServer, RemoteMcpToolSet, client_info};
use rmcp::ServiceExt as _;
+use rmcp::model::Tool;
use rmcp::transport::StreamableHttpClientTransport;
use rmcp::transport::streamable_http_client::{
StreamableHttpClient, StreamableHttpClientTransportConfig,
};
-
use tracing::Instrument as _;
use crate::domain::mcp::McpToolConnector;
@@ -53,94 +63,398 @@ fn place_header(name: &str, value: &str) -> Option<HeaderPlacement> {
/// request is the `Client` - in production
/// [`EgressMcpClient`](super::egress_mcp::EgressMcpClient), which hands it
/// to the proxy's service without a socket.
+///
+/// Open sessions live in [`ServerPool`], shared by every clone. Replacing the
+/// agent task drops the toolset it held, not the session.
#[derive(Clone)]
pub struct AcpMcpConnector<Client> {
client: Client,
+ pool: Arc<ServerPool>,
}
impl<Client> AcpMcpConnector<Client>
where
Client: StreamableHttpClient + Send + Sync,
{
- /// A connector sharing one client across every server it dials.
+ /// A connector sharing one client, and one session pool, across every
+ /// server it dials.
pub fn new(client: Client) -> Self {
- Self { client }
+ let pool = Arc::new(ServerPool::default());
+ let weak = Arc::downgrade(&pool);
+ if let Ok(runtime) = tokio::runtime::Handle::try_current() {
+ runtime.spawn(async move {
+ loop {
+ tokio::time::sleep(POOL_REAP_INTERVAL).await;
+ let Some(pool) = weak.upgrade() else {
+ break;
+ };
+ pool.lock().entries.retain(|_, entry| !entry.expired());
+ }
+ });
+ }
+ Self { client, pool }
}
- #[tracing::instrument(skip_all, fields(server = %server.name))]
- async fn connect_one(&self, server: McpServerHttp) -> Option<ConnectedServer> {
- let mut config = StreamableHttpClientTransportConfig::with_uri(server.url.clone());
- let mut custom = HashMap::new();
- for header in &server.headers {
- match place_header(&header.name, &header.value) {
- Some(HeaderPlacement::BearerToken(token)) => {
- config = config.auth_header(token);
- }
- Some(HeaderPlacement::Custom(name, value)) => {
- custom.insert(name, value);
+ /// The pooled session for `server`, dialing it only when this connector
+ /// does not already have a live one.
+ ///
+ /// A hit is the tool list from the last handshake, so the caller can
+ /// start the model without another round trip. Concurrent callers for
+ /// the same server share one dial.
+ async fn cached_server(&self, server: McpServerHttp) -> Lookup {
+ let (key, config) = prepare(&server);
+ let client = self.client.clone();
+ let pool = Arc::clone(&self.pool);
+ let wait = {
+ let mut state = pool.lock();
+ state.entries.retain(|_, entry| !entry.expired());
+ if let Some(listed) = take_ready(&mut state, &key) {
+ return Lookup::Pooled(listed);
+ }
+ if let Some(Entry::Pending { fut, .. }) = state.entries.get(&key) {
+ fut.clone()
+ } else {
+ if state.entries.len() >= MAX_POOLED_SERVERS {
+ let oldest = state
+ .entries
+ .iter()
+ .filter_map(|(key, entry)| match entry {
+ Entry::Ready { touched, .. } => Some((key.clone(), *touched)),
+ Entry::Pending { .. } => None,
+ })
+ .min_by_key(|(_, touched)| *touched)
+ .map(|(key, _)| key);
+ let Some(oldest) = oldest else {
+ return Lookup::Failed;
+ };
+ state.entries.remove(&oldest);
}
- None => {
- tracing::warn!(server = %server.name, header = %header.name, "dropping an invalid header");
+ let generation = state.generation;
+ state.generation = state.generation.wrapping_add(1);
+ let name = key.name.clone();
+ let key_for_dial = key.clone();
+ let pool_for_dial = Arc::clone(&pool);
+ let fut = async move {
+ let outcome = tokio::time::timeout(HANDSHAKE_TIMEOUT, async {
+ let _permit = pool_for_dial.handshakes.acquire().await.ok()?;
+ open_server(&client, &name, config).await
+ })
+ .await
+ .ok()
+ .flatten();
+ pool_for_dial.finish(&key_for_dial, generation, outcome.clone());
+ outcome
}
+ .boxed()
+ .shared();
+ state.entries.insert(
+ key,
+ Entry::Pending {
+ generation,
+ started: Instant::now(),
+ fut: fut.clone(),
+ },
+ );
+ fut
}
- }
- config.custom_headers = custom;
-
- let transport = StreamableHttpClientTransport::with_client(self.client.clone(), config);
- match client_info()
- .serve(transport)
- .instrument(tracing::info_span!("agent.mcp.initialize", server = %server.name))
- .await
- {
- Ok(client) => Some(ConnectedServer {
- name: server.name,
- client,
- }),
- Err(error) => {
- // One server that will not answer must not cost the session
- // the others, nor the session itself.
- tracing::warn!(server = %server.name, error = ?error, "failed to connect to an MCP server; skipping it");
- None
- }
+ };
+ match wait.await {
+ Some(cached) => Lookup::Dialed(listed_from(&cached)),
+ None => Lookup::Failed,
}
}
}
+/// How one server's session was obtained, so a connect can say how much of
+/// its time went to handshakes rather than the pool.
+enum Lookup {
+ Pooled(ListedServer),
+ Dialed(ListedServer),
+ Failed,
+}
+
impl<Client> McpToolConnector for AcpMcpConnector<Client>
where
Client: StreamableHttpClient + Send + Sync,
{
- #[tracing::instrument(skip_all, fields(servers = servers.len(), dialed = tracing::field::Empty, failed = tracing::field::Empty, elapsed_ms = tracing::field::Empty))]
+ #[tracing::instrument(
+ skip_all,
+ fields(
+ servers = servers.len(),
+ pooled = tracing::field::Empty,
+ dialed = tracing::field::Empty,
+ failed = tracing::field::Empty,
+ elapsed_ms = tracing::field::Empty,
+ )
+ )]
async fn connect(&self, servers: Vec<McpServerHttp>) -> Option<RemoteMcpToolSet> {
if servers.is_empty() {
return None;
}
let started = std::time::Instant::now();
- let requested = servers.len();
- let connected: Vec<ConnectedServer> =
- futures::future::join_all(servers.into_iter().map(|server| self.connect_one(server)))
+ let mut pooled = 0usize;
+ let mut dialed = 0usize;
+ let mut failed = 0usize;
+ let mut listed = Vec::with_capacity(servers.len());
+ for lookup in
+ futures::future::join_all(servers.into_iter().map(|server| self.cached_server(server)))
.await
- .into_iter()
- .flatten()
- .collect();
+ {
+ match lookup {
+ Lookup::Pooled(server) => {
+ pooled += 1;
+ listed.push(server);
+ }
+ Lookup::Dialed(server) => {
+ dialed += 1;
+ listed.push(server);
+ }
+ Lookup::Failed => failed += 1,
+ }
+ }
+ let elapsed_ms = u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX);
let span = tracing::Span::current();
- span.record("dialed", connected.len());
- span.record("failed", requested - connected.len());
- if connected.is_empty() {
- span.record(
- "elapsed_ms",
- u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX),
- );
+ span.record("pooled", pooled);
+ span.record("dialed", dialed);
+ span.record("failed", failed);
+ span.record("elapsed_ms", elapsed_ms);
+ tracing::info!(pooled, dialed, failed, elapsed_ms, "resolved MCP sessions");
+ if listed.is_empty() {
return None;
}
- let tools = RemoteMcpToolSet::from_connected(connected, None).await;
- span.record(
- "elapsed_ms",
- u64::try_from(started.elapsed().as_millis()).unwrap_or(u64::MAX),
+ let tools = RemoteMcpToolSet::from_listed(listed, None);
+ if tools.is_empty() { None } else { Some(tools) }
+ }
+
+ fn release(&self, token: &str) {
+ self.pool.release_bearer(token);
+ }
+}
+
+/// One dial shared by every caller waiting on it.
+type DialFut = futures::future::Shared<BoxFuture<'static, Option<Arc<CachedServer>>>>;
+
+/// An open session and the tools it listed, reused until it closes.
+struct CachedServer {
+ name: String,
+ client: Arc<McpServer>,
+ tools: Vec<Tool>,
+}
+
+/// What distinguishes one pooled session from another.
+///
+/// The bearer is the session token. Two sessions never share a client, and
+/// releasing the token drops every server that presented it.
+#[derive(Clone, PartialEq, Eq, Hash)]
+struct ServerKey {
+ name: String,
+ url: String,
+ bearer: Option<String>,
+ headers: Vec<(String, String)>,
+}
+
+const MAX_POOLED_SERVERS: usize = 256;
+const MAX_CONCURRENT_HANDSHAKES: usize = 16;
+const HANDSHAKE_TIMEOUT: Duration = Duration::from_secs(30);
+const POOL_REAP_INTERVAL: Duration = Duration::from_secs(60);
+const POOL_IDLE_TTL: Duration = Duration::from_secs(600);
+
+enum Entry {
+ Ready {
+ cached: Arc<CachedServer>,
+ touched: Instant,
+ },
+ Pending {
+ generation: u64,
+ started: Instant,
+ fut: DialFut,
+ },
+}
+
+impl Entry {
+ fn expired(&self) -> bool {
+ match self {
+ Self::Ready { cached, touched } => {
+ touched.elapsed() >= POOL_IDLE_TTL || session_closed(cached)
+ }
+ Self::Pending { started, .. } => started.elapsed() >= HANDSHAKE_TIMEOUT,
+ }
+ }
+}
+
+struct PoolState {
+ generation: u64,
+ entries: HashMap<ServerKey, Entry>,
+}
+
+/// Live MCP sessions, keyed so a second `connect` with the same server does
+/// not handshake.
+struct ServerPool {
+ handshakes: tokio::sync::Semaphore,
+ state: Mutex<PoolState>,
+}
+
+impl Default for ServerPool {
+ fn default() -> Self {
+ Self {
+ handshakes: tokio::sync::Semaphore::new(MAX_CONCURRENT_HANDSHAKES),
+ state: Mutex::new(PoolState {
+ generation: 0,
+ entries: HashMap::new(),
+ }),
+ }
+ }
+}
+
+impl ServerPool {
+ fn lock(&self) -> std::sync::MutexGuard<'_, PoolState> {
+ self.state.lock().expect("mcp client pool lock")
+ }
+
+ fn finish(&self, key: &ServerKey, generation: u64, outcome: Option<Arc<CachedServer>>) {
+ let mut state = self.lock();
+ let still_ours = matches!(
+ state.entries.get(key),
+ Some(Entry::Pending {
+ generation: current,
+ ..
+ }) if *current == generation
);
- if tools.is_empty() {
+ if !still_ours {
+ return;
+ }
+ match outcome {
+ Some(cached) => {
+ state.entries.insert(
+ key.clone(),
+ Entry::Ready {
+ cached,
+ touched: Instant::now(),
+ },
+ );
+ }
+ None => {
+ state.entries.remove(key);
+ }
+ }
+ }
+
+ fn release_bearer(&self, token: &str) {
+ self.lock()
+ .entries
+ .retain(|key, _| key.bearer.as_deref() != Some(token));
+ }
+}
+
+/// Build the pool key and the transport config from the same header placement,
+/// so a cache hit is a session that would have been dialed identically.
+fn prepare(server: &McpServerHttp) -> (ServerKey, StreamableHttpClientTransportConfig) {
+ let mut config = StreamableHttpClientTransportConfig::with_uri(server.url.clone());
+ let mut bearer = None;
+ let mut custom = HashMap::new();
+ for header in &server.headers {
+ match place_header(&header.name, &header.value) {
+ Some(HeaderPlacement::BearerToken(token)) => {
+ bearer = Some(token.clone());
+ config = config.auth_header(token);
+ }
+ Some(HeaderPlacement::Custom(name, value)) => {
+ custom.insert(name, value);
+ }
+ None => {
+ tracing::warn!(server = %server.name, header = %header.name, "dropping an invalid header");
+ }
+ }
+ }
+ let mut headers: Vec<(String, String)> = custom
+ .iter()
+ .map(|(name, value)| {
+ (
+ name.as_str().to_owned(),
+ String::from_utf8_lossy(value.as_bytes()).into_owned(),
+ )
+ })
+ .collect();
+ headers.sort();
+ config.custom_headers = custom;
+ (
+ ServerKey {
+ name: server.name.clone(),
+ url: server.url.clone(),
+ bearer,
+ headers,
+ },
+ config,
+ )
+}
+
+fn session_closed(cached: &CachedServer) -> bool {
+ cached.client.is_closed() || cached.client.is_transport_closed()
+}
+
+fn listed_from(cached: &CachedServer) -> ListedServer {
+ ListedServer {
+ name: cached.name.clone(),
+ client: Arc::clone(&cached.client),
+ tools: cached.tools.clone(),
+ }
+}
+
+/// A ready entry whose session is still up, or `None` when it must be dialed.
+fn take_ready(state: &mut PoolState, key: &ServerKey) -> Option<ListedServer> {
+ let closed = matches!(
+ state.entries.get(key),
+ Some(Entry::Ready { cached, .. }) if session_closed(cached)
+ );
+ if closed {
+ tracing::debug!(server = %key.name, "pooled MCP client is closed; dialing again");
+ state.entries.remove(key);
+ return None;
+ }
+ let Some(Entry::Ready { cached, touched }) = state.entries.get_mut(key) else {
+ return None;
+ };
+ *touched = Instant::now();
+ Some(listed_from(cached))
+}
+
+#[tracing::instrument(skip_all, fields(server = %name))]
+async fn open_server<Client>(
+ client: &Client,
+ name: &str,
+ config: StreamableHttpClientTransportConfig,
+) -> Option<Arc<CachedServer>>
+where
+ Client: StreamableHttpClient + Send + Sync,
+{
+ let transport = StreamableHttpClientTransport::with_client(client.clone(), config);
+ let running = match client_info()
+ .serve(transport)
+ .instrument(tracing::info_span!("agent.mcp.initialize", server = %name))
+ .await
+ {
+ Ok(running) => running,
+ Err(error) => {
+ // One server that will not answer must not cost the session
+ // the others, nor the session itself.
+ tracing::warn!(server = %name, error = ?error, "failed to connect to an MCP server; skipping it");
return None;
}
- Some(tools)
+ };
+ match running
+ .list_all_tools()
+ .instrument(tracing::info_span!("agent.mcp.list_tools", server = %name))
+ .await
+ {
+ Ok(tools) => Some(Arc::new(CachedServer {
+ name: name.to_owned(),
+ client: Arc::new(running),
+ tools,
+ })),
+ Err(error) => {
+ tracing::warn!(server = %name, error = ?error, "failed to list tools; skipping the server");
+ let _ = running.cancel().await;
+ None
+ }
}
}
diff --git a/crates/agent_inmem/src/outbound/acp_mcp/test.rs b/crates/agent_inmem/src/outbound/acp_mcp/test.rs
index c152dc3a38..763fc95c60 100644
--- a/crates/agent_inmem/src/outbound/acp_mcp/test.rs
+++ b/crates/agent_inmem/src/outbound/acp_mcp/test.rs
@@ -1,4 +1,150 @@
+use std::sync::atomic::{AtomicUsize, Ordering};
+
+use agent_egress::domain::error::EgressError;
+use agent_egress::domain::model::{EgressTarget, ProxyRequest, ProxyResponse, SessionToken};
+use agent_egress::domain::service::EgressService;
+use bytes::Bytes;
+use http::StatusCode;
+use http_body_util::{BodyExt, Empty, Full};
+use rmcp::transport::common::http_header::{HEADER_SESSION_ID, JSON_MIME_TYPE};
+use serde_json::{Value, json};
+
+use super::super::egress_mcp::EgressMcpClient;
use super::*;
+use crate::domain::mcp::McpToolConnector;
+
+/// The proxy's address, matching the path-prefix the in-process client strips.
+const BASE_URL: &str = "https://gateway.example/agent-harness-egress";
+
+fn empty_body() -> agent_egress::domain::model::ProxyBody {
+ Empty::new().map_err(|never| match never {}).boxed_unsync()
+}
+
+fn full_body(bytes: Vec<u8>) -> agent_egress::domain::model::ProxyBody {
+ Full::new(Bytes::from(bytes))
+ .map_err(|never| match never {})
+ .boxed_unsync()
+}
+
+fn json_response(status: StatusCode, body: Value) -> ProxyResponse {
+ let mut response = http::Response::new(full_body(body.to_string().into_bytes()));
+ *response.status_mut() = status;
+ response.headers_mut().insert(
+ http::header::CONTENT_TYPE,
+ HeaderValue::from_static(JSON_MIME_TYPE),
+ );
+ response
+ .headers_mut()
+ .insert(HEADER_SESSION_ID, HeaderValue::from_static("stub-session"));
+ response
+}
+
+/// Speaks just enough MCP to finish a handshake, and can hold `initialize`
+/// open so two callers overlap.
+struct StubEgress {
+ initializes: AtomicUsize,
+ /// When set, `initialize` waits until the sender publishes `true`.
+ hold: Option<tokio::sync::watch::Receiver<bool>>,
+ started: tokio::sync::Notify,
+}
+
+impl StubEgress {
+ fn open() -> Arc<Self> {
+ Arc::new(Self {
+ initializes: AtomicUsize::new(0),
+ hold: None,
+ started: tokio::sync::Notify::new(),
+ })
+ }
+
+ fn held(hold: tokio::sync::watch::Receiver<bool>) -> Arc<Self> {
+ Arc::new(Self {
+ initializes: AtomicUsize::new(0),
+ hold: Some(hold),
+ started: tokio::sync::Notify::new(),
+ })
+ }
+
+ fn initializes(&self) -> usize {
+ self.initializes.load(Ordering::SeqCst)
+ }
+}
+
+impl EgressService for StubEgress {
+ async fn proxy(
+ &self,
+ _token: &SessionToken,
+ _target: EgressTarget,
+ request: ProxyRequest,
+ ) -> Result<ProxyResponse, EgressError> {
+ if *request.method() != http::Method::POST {
+ let mut response = http::Response::new(empty_body());
+ *response.status_mut() = StatusCode::METHOD_NOT_ALLOWED;
+ return Ok(response);
+ }
+ let body = request
+ .into_body()
+ .collect()
+ .await
+ .expect("body")
+ .to_bytes();
+ let call: Value = serde_json::from_slice(&body).expect("json-rpc");
+ let id = call.get("id").cloned();
+ let result = match call["method"].as_str() {
+ Some("initialize") => {
+ self.initializes.fetch_add(1, Ordering::SeqCst);
+ self.started.notify_one();
+ if let Some(hold) = &self.hold {
+ let mut hold = hold.clone();
+ while !*hold.borrow() {
+ if hold.changed().await.is_err() {
+ break;
+ }
+ }
+ }
+ json!({
+ "protocolVersion": "2025-03-26",
+ "capabilities": {"tools": {}},
+ "serverInfo": {"name": "stub", "version": "0"},
+ })
+ }
+ Some("tools/list") => json!({
+ "tools": [{
+ "name": "echo",
+ "description": "Echoes",
+ "inputSchema": {"type": "object"},
+ }],
+ }),
+ _ if id.is_none() => {
+ let mut response = http::Response::new(empty_body());
+ *response.status_mut() = StatusCode::ACCEPTED;
+ return Ok(response);
+ }
+ _ => {
+ return Ok(json_response(
+ StatusCode::NOT_FOUND,
+ json!({"jsonrpc": "2.0", "id": id, "error": {"code": -32601, "message": "no such method"}}),
+ ));
+ }
+ };
+ Ok(json_response(
+ StatusCode::OK,
+ json!({"jsonrpc": "2.0", "id": id, "result": result}),
+ ))
+ }
+}
+
+fn server(name: &str, token: &str) -> agent_client_protocol::schema::v1::McpServerHttp {
+ agent_client_protocol::schema::v1::McpServerHttp::new(name, format!("{BASE_URL}/mcp/{name}"))
+ .headers(vec![agent_client_protocol::schema::v1::HttpHeader::new(
+ "Authorization",
+ format!("Bearer {token}"),
+ )])
+}
+
+fn connector(egress: Arc<StubEgress>) -> AcpMcpConnector<EgressMcpClient<StubEgress>> {
+ AcpMcpConnector::new(EgressMcpClient::new(egress, BASE_URL))
+}
/// The harness advertises `Authorization: Bearer <session token>`; rmcp wants
/// the bare token and adds the scheme itself.
@@ -38,3 +184,157 @@ fn invalid_headers_are_dropped() {
assert_eq!(place_header("not a header", "x"), None);
assert_eq!(place_header("X-Custom", "line\nbreak"), None);
}
+
+/// Dropping the toolset must not drop the session: the next connect is the
+/// same handshake, including when the bearer scheme differs only in case.
+#[tokio::test]
+async fn a_second_connect_reuses_the_open_session_and_its_tool_list() {
+ let egress = StubEgress::open();
+ let connector = connector(Arc::clone(&egress));
+
+ let first = connector
+ .connect(vec![server("hubspot", "session-token")])
+ .await
+ .expect("tools");
+ assert_eq!(
+ first
+ .searchable_catalog()
+ .iter()
+ .map(|tool| tool.name.as_str())
+ .collect::<Vec<_>>(),
+ ["mcp__hubspot__echo"]
+ );
+ let handshakes = egress.initializes();
+ assert_eq!(handshakes, 1);
+
+ drop(first);
+ let second = connector
+ .connect(vec![server("hubspot", "session-token")])
+ .await
+ .expect("pooled tools");
+ assert_eq!(egress.initializes(), handshakes);
+ assert!(!second.searchable_catalog().is_empty());
+
+ // `bearer` and `Bearer` are the same session token.
+ let _third = connector
+ .connect(vec![
+ agent_client_protocol::schema::v1::McpServerHttp::new(
+ "hubspot",
+ format!("{BASE_URL}/mcp/hubspot"),
+ )
+ .headers(vec![agent_client_protocol::schema::v1::HttpHeader::new(
+ "authorization",
+ "bearer session-token",
+ )]),
+ ])
+ .await
+ .expect("same token");
+ assert_eq!(egress.initializes(), handshakes);
+}
+
+/// The agent and the catalog dial the same server at once; one handshake
+/// serves both.
+#[tokio::test]
+async fn overlapping_connects_share_one_handshake() {
+ let (release, hold) = tokio::sync::watch::channel(false);
+ let egress = StubEgress::held(hold);
+ let connector = connector(Arc::clone(&egress));
+
+ let first = tokio::spawn({
+ let connector = connector.clone();
+ async move {
+ connector
+ .connect(vec![server("linear", "session-token")])
+ .await
+ }
+ });
+ egress.started.notified().await;
+
+ let second = tokio::spawn({
+ let connector = connector.clone();
+ async move {
+ connector
+ .connect(vec![server("linear", "session-token")])
+ .await
+ }
+ });
+ tokio::time::sleep(std::time::Duration::from_millis(50)).await;
+ assert_eq!(egress.initializes(), 1, "the second caller joined the dial");
+
+ release.send(true).expect("the hold is open");
+ let (first, second) = tokio::join!(first, second);
+ assert!(first.expect("task").is_some());
+ assert!(second.expect("task").is_some());
+ assert_eq!(egress.initializes(), 1);
+}
+
+/// Teardown forgets the token's sessions. A different token never shared them.
+#[tokio::test]
+async fn release_and_a_different_token_each_dial_again() {
+ let egress = StubEgress::open();
+ let connector = connector(Arc::clone(&egress));
+
+ let tools = connector
+ .connect(vec![server("hubspot", "session-token")])
+ .await
+ .expect("tools");
+ drop(tools);
+ assert_eq!(egress.initializes(), 1);
+
+ connector.release("session-token");
+ let _redialed = connector
+ .connect(vec![server("hubspot", "session-token")])
+ .await
+ .expect("redialed after release");
+ assert_eq!(egress.initializes(), 2);
+
+ let _other = connector
+ .connect(vec![server("hubspot", "other-token")])
+ .await
+ .expect("a different session");
+ assert_eq!(egress.initializes(), 3);
+}
+
+#[tokio::test]
+async fn idle_pool_entries_are_redialed_without_invalidating_active_toolsets() {
+ let egress = StubEgress::open();
+ let connector = connector(Arc::clone(&egress));
+ let active = connector
+ .connect(vec![server("idle", "token")])
+ .await
+ .expect("tools");
+ {
+ let mut pool = connector.pool.lock();
+ for entry in pool.entries.values_mut() {
+ if let Entry::Ready { touched, .. } = entry {
+ *touched = Instant::now() - POOL_IDLE_TTL;
+ }
+ }
+ }
+ let _next = connector
+ .connect(vec![server("idle", "token")])
+ .await
+ .expect("fresh tools");
+ assert_eq!(egress.initializes(), 2);
+ assert!(!active.searchable_catalog().is_empty());
+}
+
+#[tokio::test]
+async fn pool_evicts_oldest_when_at_capacity() {
+ let egress = StubEgress::open();
+ let connector = connector(Arc::clone(&egress));
+ for index in 0..=MAX_POOLED_SERVERS {
+ connector
+ .connect(vec![server("bounded", &format!("token-{index}"))])
+ .await
+ .expect("tools");
+ }
+ assert_eq!(connector.pool.lock().entries.len(), MAX_POOLED_SERVERS);
+ assert!(
+ !connector
+ .pool
+ .lock()
+ .entries
+ .contains_key(&prepare(&server("bounded", "token-0")).0)
+ );
+}
diff --git a/crates/agent_inmem/src/outbound/manager.rs b/crates/agent_inmem/src/outbound/manager.rs
index 31fb477359..9e96b7d9af 100644
--- a/crates/agent_inmem/src/outbound/manager.rs
+++ b/crates/agent_inmem/src/outbound/manager.rs
@@ -206,11 +206,13 @@ impl InMemAgentManager {
server_half
}
- /// End the session for good: kill its agent task and drop its
- /// conversation.
+ /// End the session for good: kill its agent task, drop its conversation,
+ /// and close the MCP sessions its token was holding open.
pub fn teardown(&self, session: AgentSessionId) {
self.live.remove(&session);
self.store.remove(&session);
- self.tokens.remove(&session);
+ if let Some((_, token)) = self.tokens.remove(&session) {
+ self.mcp.release_dyn(&token);
+ }
}
}
diff --git a/crates/agent_inmem/src/outbound/manager/test.rs b/crates/agent_inmem/src/outbound/manager/test.rs
index 8c0e13025c..c3bef63c90 100644
--- a/crates/agent_inmem/src/outbound/manager/test.rs
+++ b/crates/agent_inmem/src/outbound/manager/test.rs
@@ -169,6 +169,7 @@ async fn a_prompt_runs_end_to_end_through_the_real_session_machine() {
let id = AgentSessionId::new();
sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: Owner::User(owner()),
@@ -308,6 +309,7 @@ async fn manager_admission_rejects_turns_without_wedging_the_session() {
let id = AgentSessionId::new();
sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: Owner::User(owner()),
@@ -400,6 +402,7 @@ async fn a_restarted_manager_rebuilds_the_conversation_from_the_log() {
let id = AgentSessionId::new();
sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: Owner::User(owner()),
@@ -547,6 +550,7 @@ async fn instructions_reach_every_turn_including_after_a_reattach() {
let id = AgentSessionId::new();
sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: Owner::User(owner()),
@@ -622,6 +626,7 @@ async fn a_session_without_instructions_hands_the_engine_none() {
let id = AgentSessionId::new();
sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: Owner::User(owner()),
@@ -682,6 +687,7 @@ async fn identity_reaches_every_turn_including_after_a_reattach() {
let id = AgentSessionId::new();
sessions
.create_session(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id,
owner_id: Owner::User(owner()),
@@ -764,3 +770,47 @@ async fn the_manager_remembers_the_egress_token_from_spawn_until_teardown() {
manager.teardown(id);
assert_eq!(manager.session_token(id), None);
}
+
+/// Teardown is what ends the session, so it also drops the MCP sessions the
+/// egress token was holding. A connector that pools them learns the token.
+#[tokio::test]
+async fn teardown_releases_pooled_mcp_sessions_for_the_egress_token() {
+ let repo = InMemoryAgentSessionRepo::new();
+ let mcp = Arc::new(RecordingRelease {
+ released: std::sync::Mutex::new(Vec::new()),
+ });
+ let manager = InMemAgentManager::new(
+ Arc::new(ScriptedEngine::new(Vec::new())),
+ Arc::new(LogFrameSource::new(repo.clone())),
+ mcp.clone(),
+ );
+ let id = AgentSessionId::new();
+ let _spawned = manager
+ .attach(facts(id), Some("session-token".to_owned()))
+ .await;
+
+ manager.teardown(id);
+
+ assert_eq!(
+ mcp.released.lock().expect("lock").as_slice(),
+ ["session-token"]
+ );
+}
+
+/// Records [`McpToolConnector::release`] so teardown can be seen doing it.
+struct RecordingRelease {
+ released: std::sync::Mutex<Vec<String>>,
+}
+
+impl crate::domain::mcp::McpToolConnector for RecordingRelease {
+ async fn connect(
+ &self,
+ _servers: Vec<agent_client_protocol::schema::v1::McpServerHttp>,
+ ) -> Option<mcp_toolset::RemoteMcpToolSet> {
+ None
+ }
+
+ fn release(&self, token: &str) {
+ self.released.lock().expect("lock").push(token.to_owned());
+ }
+}
diff --git a/crates/agent_session/README.md b/crates/agent_session/README.md
index 8e939a3150..ce27318d97 100644
--- a/crates/agent_session/README.md
+++ b/crates/agent_session/README.md
@@ -70,7 +70,7 @@ attachment alone is not a readiness measurement.
The in-memory connector exposes `agent.mcp.initialize` and
`agent.mcp.list_tools` durations per `server`, alongside the aggregate connector
-`dialed`, `failed`, and `elapsed_ms` fields. Servers initialize in
+`pooled`, `dialed`, `failed`, and `elapsed_ms` fields. Servers initialize in
parallel: compare the critical path, not the sum of their durations. In-memory
prompt spans also split `agent.turn.lock_wait_ms`, `agent.turn.admission_wait_ms`,
and `agent.turn.first_text_ms`; their legacy `ttft_ms` can include reasoning or
@@ -104,7 +104,26 @@ answering spends that time between the first model chunk and the first text:
`macro.genai.chat.first_chunk_kind` says what each call streamed first.
To investigate a slow first session in Datadog, correlate by `agent.session.id`,
-report sample counts and
+compare cold and pooled connects separately, and report sample counts and
p50/p95 for initialization and first text by harness/model. Include the fraction
of turns with no text rather than silently counting them as fast answers. None
of these new fields supplies historical measurements before its deployment.
+
+Home and Agents can prepare an unprompted session through
+`POST /agent-sessions/warm`. It stays hidden until normal creation claims the
+same id for the same owner, bot, model and instructions. Reusing the session
+also reuses its egress token, which is part of the MCP pool key; creating and
+immediately deleting a throwaway session would release those cached clients.
+The warm response waits for ACP initialization and the shared MCP listing, so
+background initialization is finished before a ready reservation is offered.
+No model invocation or tool execution occurs during warming.
+
+The browser consumes a result once within five minutes. Unclaimed rows expire
+after ten minutes and are deleted through the managing replica. Each replica
+keeps at most 64 outstanding warm reservations, with at most two per user.
+Reservations age out after ten minutes; claims and expiry handled by the
+preparing replica free its capacity sooner.
+The MCP pool holds at most 256 entries, evicts entries idle for ten minutes,
+and limits handshakes to 16 concurrent attempts with a 30-second timeout.
+`agent.session.warm` and `agent.session.warm_hit` on the open span distinguish
+preparation, successful reuse and ordinary creation for latency comparisons.
diff --git a/crates/agent_session/src/bin/seed_jsonl.rs b/crates/agent_session/src/bin/seed_jsonl.rs
index abb5dd0436..1d42d850c6 100644
--- a/crates/agent_session/src/bin/seed_jsonl.rs
+++ b/crates/agent_session/src/bin/seed_jsonl.rs
@@ -245,6 +245,7 @@ async fn seed(args: &Args) -> Result<(), SeedError> {
let session = AgentSessionRepo::create(
&repo,
CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id: session_id,
owner_id: model_owner::Owner::User(owner),
diff --git a/crates/agent_session/src/domain/mod.rs b/crates/agent_session/src/domain/mod.rs
index 671005ce15..12e32f15b9 100644
--- a/crates/agent_session/src/domain/mod.rs
+++ b/crates/agent_session/src/domain/mod.rs
@@ -35,3 +35,6 @@ pub mod working_branch;
/// Recovery of sessions abandoned by crashed replicas.
pub mod recovery;
+
+/// Warm session promotion and expiry.
+pub mod warm;
diff --git a/crates/agent_session/src/domain/model.rs b/crates/agent_session/src/domain/model.rs
index 0c586837e8..c7ac60b389 100644
--- a/crates/agent_session/src/domain/model.rs
+++ b/crates/agent_session/src/domain/model.rs
@@ -187,6 +187,8 @@ pub use bots::domain::models::{AgentMcpServer, AgentMcpServers};
/// Caller-provided values required to create an agent session.
#[derive(Debug, Clone)]
pub struct CreateAgentSessionParams {
+ /// An unclaimed warm session, hidden from lists and history.
+ pub warm: bool,
/// Caller-minted session id, available before persistence.
pub id: AgentSessionId,
/// Who created and owns the session.
diff --git a/crates/agent_session/src/domain/ports.rs b/crates/agent_session/src/domain/ports.rs
index ca8be2556a..bddcd4688a 100644
--- a/crates/agent_session/src/domain/ports.rs
+++ b/crates/agent_session/src/domain/ports.rs
@@ -332,6 +332,13 @@ pub struct OpenManagedSession {
/// its own schedule, while a managed session's sandbox is provisioned here.
/// That difference is why only one of them takes a workspace.
pub trait SessionOpener: Send + Sync + 'static {
+ /// Prepare an unprompted hidden in-memory session for an authenticated user.
+ fn warm_session(
+ &self,
+ owner: Owner,
+ id: AgentSessionId,
+ ) -> impl Future<Output = Result<Option<AgentSession>>> + Send;
+
/// Open a session and return the persisted row.
fn open_external_session(
&self,
diff --git a/crates/agent_session/src/domain/routines/service/test.rs b/crates/agent_session/src/domain/routines/service/test.rs
index c35766b981..43a0274e6e 100644
--- a/crates/agent_session/src/domain/routines/service/test.rs
+++ b/crates/agent_session/src/domain/routines/service/test.rs
@@ -62,6 +62,14 @@ struct Openings {
}
impl SessionOpener for Openings {
+ async fn warm_session(
+ &self,
+ _owner: model_owner::Owner,
+ _id: AgentSessionId,
+ ) -> crate::domain::error::Result<Option<crate::domain::model::AgentSession>> {
+ Ok(None)
+ }
+
async fn open_managed_session(
&self,
request: OpenManagedSession,
diff --git a/crates/agent_session/src/domain/warm.rs b/crates/agent_session/src/domain/warm.rs
new file mode 100644
index 0000000000..ae5901e89a
--- /dev/null
+++ b/crates/agent_session/src/domain/warm.rs
@@ -0,0 +1,23 @@
+//! Atomic promotion and expiry of unprompted, hidden warm sessions.
+
+use super::{error::Result, model::AgentSessionId};
+use bot_id::BotId;
+use model_owner::Owner;
+use std::future::Future;
+use std::pin::Pin;
+
+/// Persistence operations whose claim and expiry must serialize across replicas.
+pub trait WarmSessionLifecycle: Send + Sync {
+ /// Reveal only a fresh warm session belonging to this owner and exact persona.
+ fn claim<'a>(
+ &'a self,
+ id: AgentSessionId,
+ owner: &'a Owner,
+ bot: BotId,
+ model: &'a str,
+ instructions: Option<&'a str>,
+ ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'a>>;
+ /// Mark expired hidden sessions disconnected, returning ids for routed deletion.
+ /// Claimed sessions are never selected. Work is bounded per sweep.
+ fn expire(&self) -> Pin<Box<dyn Future<Output = Result<Vec<AgentSessionId>>> + Send + '_>>;
+}
diff --git a/crates/agent_session/src/inbound/axum_router.rs b/crates/agent_session/src/inbound/axum_router.rs
index 42181d6423..212e636b56 100644
--- a/crates/agent_session/src/inbound/axum_router.rs
+++ b/crates/agent_session/src/inbound/axum_router.rs
@@ -39,7 +39,7 @@ use entity_registry::{NonUserOwners, resolve_creation_principal};
use macro_authorization::{
ActingUser, InternalOnly, MacroAuthorization, MacroAuthorizationExtractor,
MacroAuthorizationService, MacroAuthorizationState, UserBotOrHarness,
- UserBotOrHarnessAuthorization,
+ UserBotOrHarnessAuthorization, UserOnly,
};
use macro_user_id::user_id::MacroUserIdStr;
use macro_uuid::Uuid;
@@ -1598,6 +1598,10 @@ where
"/",
post(create_agent_session_handler::<Opener, Bots, Requests, Auth>),
)
+ .route(
+ "/warm",
+ post(warm_agent_session_handler::<Opener, Bots, Requests, Auth>),
+ )
.with_state(state)
}
@@ -2218,3 +2222,42 @@ pub async fn create_agent_session_handler<
}),
))
}
+
+/// A client-minted id deduplicates warm calls without creating a conversation.
+#[derive(serde::Deserialize, utoipa::ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct WarmAgentSessionRequest {
+ /// Id reserved by this browser for its next in-memory conversation.
+ pub id: Uuid,
+}
+
+/// A bounded best-effort warm attempt; absence means normal creation should proceed.
+#[derive(serde::Serialize, utoipa::ToSchema)]
+#[serde(rename_all = "camelCase")]
+pub struct WarmAgentSessionResponse {
+ /// Prepared session, hidden until explicitly claimed through create.
+ pub session: Option<AgentSessionResponse>,
+}
+
+/// Prepare MCP connections without sending a prompt or creating a visible list row.
+#[utoipa::path(post, path = "/agent-sessions/warm", request_body = WarmAgentSessionRequest,
+ responses((status = 200, body = WarmAgentSessionResponse)), tag = "agent-sessions")]
+pub async fn warm_agent_session_handler<
+ Opener: SessionOpener,
+ Bots: BotDirectory,
+ Requests: ExternalSessionRequester,
+ Auth: MacroAuthorizationService,
+>(
+ State(state): State<CreateSessionState<Opener, Bots, Requests, Auth>>,
+ caller: MacroAuthorizationExtractor<Auth, UserOnly>,
+ Json(request): Json<WarmAgentSessionRequest>,
+) -> Result<Json<WarmAgentSessionResponse>, CreateSessionApiError> {
+ let owner = Owner::User(caller.authorization.macro_user_id.clone());
+ let session = state
+ .opener
+ .warm_session(owner, AgentSessionId::new_from_uuid(request.id))
+ .await?;
+ Ok(Json(WarmAgentSessionResponse {
+ session: session.map(|session| AgentSessionResponse::new(session, true)),
+ }))
+}
diff --git a/crates/agent_session/src/inbound/axum_router/test.rs b/crates/agent_session/src/inbound/axum_router/test.rs
index 34dc2700af..21e6a7e3c1 100644
--- a/crates/agent_session/src/inbound/axum_router/test.rs
+++ b/crates/agent_session/src/inbound/axum_router/test.rs
@@ -178,6 +178,14 @@ struct RecordingOpener {
}
impl SessionOpener for RecordingOpener {
+ async fn warm_session(
+ &self,
+ _owner: model_owner::Owner,
+ _id: AgentSessionId,
+ ) -> crate::domain::error::Result<Option<crate::domain::model::AgentSession>> {
+ Ok(None)
+ }
+
async fn open_external_session(
&self,
request: OpenExternalAgentSession,
diff --git a/crates/agent_session/src/inbound/axum_router/test/read.rs b/crates/agent_session/src/inbound/axum_router/test/read.rs
index 7178f6b5ed..60adea11e9 100644
--- a/crates/agent_session/src/inbound/axum_router/test/read.rs
+++ b/crates/agent_session/src/inbound/axum_router/test/read.rs
@@ -9,6 +9,7 @@ use crate::testing::InMemoryAgentSessionRepo;
async fn view_router() -> Router {
let repo = InMemoryAgentSessionRepo::new();
repo.create(CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id: AgentSessionId::TEST_A,
owner_id: Owner::User(MacroUserIdStr::try_from(OWNER.to_owned()).unwrap()),
diff --git a/crates/agent_session/src/outbound/postgres.rs b/crates/agent_session/src/outbound/postgres.rs
index ff2c510e4d..e3a2b54b3c 100644
--- a/crates/agent_session/src/outbound/postgres.rs
+++ b/crates/agent_session/src/outbound/postgres.rs
@@ -296,6 +296,7 @@ impl TryFrom<AgentSessionRow> for AgentSession {
impl<B: BotFacts + 'static> AgentSessionRepo for PgAgentSessionRepo<B> {
async fn create(&self, params: CreateAgentSessionParams) -> Result<AgentSession> {
let CreateAgentSessionParams {
+ warm,
id,
owner_id,
bot_id,
@@ -342,7 +343,7 @@ impl<B: BotFacts + 'static> AgentSessionRepo for PgAgentSessionRepo<B> {
// An inline @macro mention is a one-shot on the message. It stays out
// of the agents list and search. Every other session — the agents
// composer, coding agents — is a list row.
- let list_hidden = bot_id == MACRO_NEW_BOT_ID && thread_id.is_some();
+ let list_hidden = warm || (bot_id == MACRO_NEW_BOT_ID && thread_id.is_some());
let row = sqlx::query_as!(
AgentSessionRow,
r#"
@@ -461,9 +462,11 @@ impl<B: BotFacts + 'static> AgentSessionRepo for PgAgentSessionRepo<B> {
// row is what Soup's `viewed_at` and the frecency ranking read, so
// without it a brand-new session would rank below everything the
// owner has ever opened.
- upsert_user_history(&mut transaction, owner_user.as_ref(), &id.as_uuid())
- .await
- .context("failed to record the agent session in the owner's history")?;
+ if !warm {
+ upsert_user_history(&mut transaction, owner_user.as_ref(), &id.as_uuid())
+ .await
+ .context("failed to record the agent session in the owner's history")?;
+ }
transaction
.commit()
@@ -709,7 +712,7 @@ impl<B: BotFacts + 'static> AgentSessionRepo for PgAgentSessionRepo<B> {
ext.last_run_id AS "external_last_run_id?"
FROM agent_session
LEFT JOIN external_agent_session AS ext ON ext.agent_session_id = agent_session.id
- WHERE owner_id = $1
+ WHERE owner_id = $1 AND NOT list_hidden
ORDER BY agent_session.created_at DESC, id DESC
LIMIT $2
"#,
@@ -1799,3 +1802,5 @@ impl<B: BotFacts + 'static> SessionAudience for PgAgentSessionRepo<B> {
Ok(viewers)
}
}
+
+mod warm;
diff --git a/crates/agent_session/src/outbound/postgres/test.rs b/crates/agent_session/src/outbound/postgres/test.rs
index 17d98b71b8..3b5f307203 100644
--- a/crates/agent_session/src/outbound/postgres/test.rs
+++ b/crates/agent_session/src/outbound/postgres/test.rs
@@ -90,6 +90,7 @@ pub(super) fn new_session(
originating_message_id: Option<Uuid>,
) -> CreateAgentSessionParams {
CreateAgentSessionParams {
+ warm: false,
repo_branch: None,
id: AgentSessionId::new(),
owner_id: Owner::User(user_id(OWNER)),
@@ -260,6 +261,7 @@ async fn create_refuses_an_owner_that_is_not_a_user(pool: PgPool) {
let repo = test_repo(&pool);
let bot_id = create_test_bot(&pool).await;
let params = CreateAgentSessionParams {
+ warm: false,
owner_id: Owner::Bot(bot_id),
..new_session(bot_id, None, None)
};
@@ -317,6 +319,7 @@ async fn create_rejects_an_unknown_user_owner(pool: PgPool) {
let repo = test_repo(&pool);
let bot_id = create_test_bot(&pool).await;
let params = CreateAgentSessionParams {
+ warm: false,
owner_id: Owner::User(user_id("macro|[email protected]")),
..new_session(bot_id, None, None)
};
@@ -414,6 +417,7 @@ async fn instructions_round_trip_on_every_read_path(pool: PgPool) {
let (_channel_id, thread_id, originating_message_id) =
insert_originating_thread_fixture(&pool).await;
let params = CreateAgentSessionParams {
+ warm: false,
instructions: Some(INSTRUCTIONS.to_owned()),
egress_token_hash: Some("token-hash".to_owned()),
..new_session(bot_id, Some(thread_id), Some(originating_message_id))
@@ -468,6 +472,7 @@ async fn mcp_server_selection_round_trips_on_every_read_path(pool: PgPool) {
],
};
let params = CreateAgentSessionParams {
+ warm: false,
mcp_servers: selection.clone(),
egress_token_hash: Some("mcp-token-hash".to_owned()),
..new_session(bot_id, Some(thread_id), Some(originating_message_id))
@@ -994,6 +999,7 @@ async fn recent_for_owner_returns_the_owners_newest_sessions(pool: PgPool) {
let someone_else = create_session(
&repo,
CreateAgentSessionParams {
+ warm: false,
owner_id: Owner::User(user_id(OTHER_OWNER)),
..new_session(bot_id, None, None)
},
@@ -2938,3 +2944,110 @@ async fn the_originating_channel_steers_only_shared_agents_sessions(pool: PgPool
);
}
}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn warm_sessions_are_hidden_and_claimed_only_once_by_the_owner(pool: PgPool) {
+ use crate::domain::warm::WarmSessionLifecycle;
+ let bot = create_test_bot(&pool).await;
+ let repo = test_repo(&pool);
+ let mut params = new_session(bot, None, None);
+ params.warm = true;
+ let session = AgentSessionRepo::create(&repo, params)
+ .await
+ .expect("warm session");
+ assert!(
+ repo.recent_for_owner(&user_id(OWNER), NonZeroUsize::new(10).unwrap())
+ .await
+ .unwrap()
+ .is_empty()
+ );
+ let other = Owner::User(user_id("macro|[email protected]"));
+ assert!(
+ !WarmSessionLifecycle::claim(&repo, session.id, &other, bot, &session.model, None)
+ .await
+ .unwrap()
+ );
+ assert!(
+ !WarmSessionLifecycle::claim(
+ &repo,
+ session.id,
+ &session.owner_id,
+ bot,
+ "wrong-model",
+ None
+ )
+ .await
+ .unwrap()
+ );
+ assert!(
+ !WarmSessionLifecycle::claim(
+ &repo,
+ session.id,
+ &session.owner_id,
+ bot,
+ &session.model,
+ Some("different instructions")
+ )
+ .await
+ .unwrap()
+ );
+ let (left, right) = tokio::join!(
+ WarmSessionLifecycle::claim(
+ &repo,
+ session.id,
+ &session.owner_id,
+ bot,
+ &session.model,
+ None
+ ),
+ WarmSessionLifecycle::claim(
+ &repo,
+ session.id,
+ &session.owner_id,
+ bot,
+ &session.model,
+ None
+ ),
+ );
+ assert_ne!(left.unwrap(), right.unwrap());
+ assert_eq!(
+ repo.recent_for_owner(&user_id(OWNER), NonZeroUsize::new(10).unwrap())
+ .await
+ .unwrap()
+ .len(),
+ 1
+ );
+ assert!(repo.expire().await.unwrap().is_empty());
+}
+
+#[sqlx::test(migrator = "MACRO_DB_MIGRATIONS")]
+async fn expired_warm_sessions_cannot_be_claimed(pool: PgPool) {
+ use crate::domain::warm::WarmSessionLifecycle;
+ let bot = create_test_bot(&pool).await;
+ let repo = test_repo(&pool);
+ let mut params = new_session(bot, None, None);
+ params.warm = true;
+ let session = AgentSessionRepo::create(&repo, params).await.unwrap();
+ sqlx::query!(
+ "UPDATE agent_session SET created_at = NOW() - INTERVAL '11 minutes' WHERE id = $1",
+ session.id.as_uuid()
+ )
+ .execute(&pool)
+ .await
+ .unwrap();
+ assert_eq!(repo.expire().await.unwrap(), vec![session.id]);
+ assert!(
+ !WarmSessionLifecycle::claim(
+ &repo,
+ session.id,
+ &session.owner_id,
+ bot,
+ &session.model,
+ None
+ )
+ .await
+ .unwrap()
+ );
+ AgentSessionRepo::delete(&repo, session.id).await.unwrap();
+ assert!(repo.expire().await.unwrap().is_empty());
+}
diff --git a/crates/agent_session/src/outbound/postgres/test/user_cleanup.rs b/crates/agent_session/src/outbound/postgres/test/user_cleanup.rs
index 70eb192c5d..a275609b56 100644
--- a/crates/agent_session/src/outbound/postgres/test/user_cleanup.rs
+++ b/crates/agent_session/src/outbound/postgres/test/user_cleanup.rs
@@ -20,6 +20,7 @@ async fn cleanup_batches_remove_all_session_rows_without_a_user_cascade(pool: Pg
let other = create_session(
&repo,
CreateAgentSessionParams {
+ warm: false,
owner_id: Owner::User(user_id(OTHER)),
..new_session(bot, None, None)
},
diff --git a/crates/agent_session/src/outbound/postgres/warm.rs b/crates/agent_session/src/outbound/postgres/warm.rs
new file mode 100644
index 0000000000..3e891fb8f9
--- /dev/null
+++ b/crates/agent_session/src/outbound/postgres/warm.rs
@@ -0,0 +1,74 @@
+//! Warm sessions use list_hidden without a thread; hidden mentions always have a thread.
+use super::*;
+use crate::domain::warm::WarmSessionLifecycle;
+use std::{future::Future, pin::Pin};
+
+impl<B: BotFacts + 'static> WarmSessionLifecycle for PgAgentSessionRepo<B> {
+ fn claim<'a>(
+ &'a self,
+ id: AgentSessionId,
+ owner: &'a Owner,
+ bot: BotId,
+ model: &'a str,
+ instructions: Option<&'a str>,
+ ) -> Pin<Box<dyn Future<Output = Result<bool>> + Send + 'a>> {
+ Box::pin(async move {
+ let user = session_owner_user(owner)?;
+ let mut transaction = self.pool.begin().await.context("begin warm claim")?;
+ let changed = sqlx::query!(
+ r#"
+ UPDATE agent_session SET list_hidden = false
+ WHERE id = $1 AND owner_id = $2 AND bot_id = $3 AND model = $4
+ AND instructions IS NOT DISTINCT FROM $5
+ AND list_hidden AND thread_id IS NULL
+ AND status != 'disconnected'
+ AND NOT (status = 'event' AND status_event_name = 'disconnected')
+ AND created_at > NOW() - INTERVAL '10 minutes'
+ "#,
+ id.as_uuid(),
+ user.as_ref(),
+ bot.as_uuid(),
+ model,
+ instructions
+ )
+ .execute(&mut *transaction)
+ .await
+ .context("claim warm session")?
+ .rows_affected()
+ == 1;
+ if changed {
+ upsert_user_history(&mut transaction, user.as_ref(), &id.as_uuid())
+ .await
+ .context("record claimed warm session history")?;
+ }
+ transaction.commit().await.context("commit warm claim")?;
+ Ok(changed)
+ })
+ }
+ fn expire(&self) -> Pin<Box<dyn Future<Output = Result<Vec<AgentSessionId>>> + Send + '_>> {
+ Box::pin(async move {
+ // Mark under row locks before deleting: a concurrent claim cannot win
+ // after this operation, and a crash leaves a retryable expired row.
+ let rows = sqlx::query!(
+ r#"
+ UPDATE agent_session SET status = 'disconnected'
+ WHERE id IN (
+ SELECT id FROM agent_session
+ WHERE list_hidden AND thread_id IS NULL
+ AND created_at <= NOW() - INTERVAL '10 minutes'
+ ORDER BY created_at LIMIT 64 FOR UPDATE SKIP LOCKED
+ ) RETURNING id
+ "#
+ )
+ .fetch_all(&self.pool)
+ .await
+ .context("expire warm sessions")?;
+ let mut expired = Vec::new();
+ for row in rows {
+ let id = AgentSessionId::new_from_uuid(row.id);
+ expired.push(id);
+ }
+ Ok(expired)
+ })
+ }
+}
diff --git a/crates/mcp_toolset/src/lib.rs b/crates/mcp_toolset/src/lib.rs
index 2b41e282b1..49bce3ca99 100644
--- a/crates/mcp_toolset/src/lib.rs
+++ b/crates/mcp_toolset/src/lib.rs
@@ -15,7 +15,7 @@ mod mangle;
mod toolset;
pub use call_tool_result::CallToolResultExt;
-pub use toolset::{ConnectedServer, Error, RemoteMcpToolSet};
+pub use toolset::{ConnectedServer, Error, ListedServer, RemoteMcpToolSet};
use rmcp::RoleClient;
use rmcp::model::{ClientInfo, Implementation};
diff --git a/crates/mcp_toolset/src/toolset.rs b/crates/mcp_toolset/src/toolset.rs
index 25369e89cc..46a5616b51 100644
--- a/crates/mcp_toolset/src/toolset.rs
+++ b/crates/mcp_toolset/src/toolset.rs
@@ -32,10 +32,24 @@ pub enum Error {
pub struct ConnectedServer {
/// The server segment of every mangled name, e.g. `Linear`.
pub name: String,
- /// The open session, kept alive for as long as the toolset is.
+ /// The open session. Listing its tools is this toolset's job.
pub client: McpServer,
}
+/// A server whose tools are already listed, sharing its session with whoever
+/// else holds the `Arc`.
+///
+/// Dropping the toolset built from these does not close the session while
+/// another owner, such as a pool, still holds it.
+pub struct ListedServer {
+ /// The server segment of every mangled name, e.g. `Linear`.
+ pub name: String,
+ /// The open session.
+ pub client: Arc<McpServer>,
+ /// Tools `tools/list` already returned for `client`.
+ pub tools: Vec<Tool>,
+}
+
struct RegisteredTool {
peer: Peer<RoleClient>,
tool: Tool,
@@ -55,7 +69,10 @@ pub struct RemoteMcpToolSet(Arc<Registered>);
struct Registered {
tools: BTreeMap<MangledName, RegisteredTool>,
/// Kept alive so the background transport tasks aren't cancelled.
- _connections: Vec<McpServer>,
+ ///
+ /// Shared with any pool that handed the sessions in, so this toolset
+ /// dropping is not what closes them.
+ _connections: Vec<Arc<McpServer>>,
/// Who the servers belong to, for correlating tool-call failures in logs.
subject: Option<String>,
}
@@ -92,42 +109,14 @@ impl RemoteMcpToolSet {
let mut tools = BTreeMap::new();
let mut connections = Vec::new();
for (server_name, client, server_tools) in listings.into_iter().flatten() {
- for tool in server_tools {
- let Mangled {
- name: mangled,
- sanitized,
- } = Mangled::new(&server_name, &tool.name);
-
- if sanitized {
- tracing::warn!(
- subject = ?subject,
- server = %server_name,
- tool = %tool.name,
- %mangled,
- "sanitized tool name to satisfy the provider tool-name pattern"
- );
- }
-
- if tools.contains_key(&mangled) {
- tracing::warn!(
- subject = ?subject,
- server = %server_name,
- tool = %tool.name,
- %mangled,
- "skipping duplicate tool"
- );
- continue;
- }
-
- tools.insert(
- mangled,
- RegisteredTool {
- peer: client.peer().clone(),
- tool,
- },
- );
- }
- connections.push(client);
+ register_server(
+ &mut tools,
+ &mut connections,
+ &server_name,
+ Arc::new(client),
+ server_tools,
+ &subject,
+ );
}
Self(Arc::new(Registered {
@@ -137,9 +126,30 @@ impl RemoteMcpToolSet {
}))
}
- /// How many tools were discovered across every connected server.
- pub fn len(&self) -> usize {
- self.0.tools.len()
+ /// Register tools that were already listed on `servers`.
+ ///
+ /// `subject` names whose servers these are, for logs only. The sessions
+ /// stay open until the last `Arc` drops, so a pool can hand the same
+ /// session to every turn without another handshake.
+ pub fn from_listed(servers: Vec<ListedServer>, subject: Option<String>) -> Self {
+ let mut tools = BTreeMap::new();
+ let mut connections = Vec::new();
+ for server in servers {
+ register_server(
+ &mut tools,
+ &mut connections,
+ &server.name,
+ server.client,
+ server.tools,
+ &subject,
+ );
+ }
+
+ Self(Arc::new(Registered {
+ tools,
+ _connections: connections,
+ subject,
+ }))
}
/// Returns `true` when no tools were discovered.
@@ -147,6 +157,11 @@ impl RemoteMcpToolSet {
self.0.tools.is_empty()
}
+ /// How many tools were discovered across every connected server.
+ pub fn len(&self) -> usize {
+ self.0.tools.len()
+ }
+
/// The full catalog of MCP tools (mangled name + description + input
/// schema) for on-demand loading via tool search.
pub fn searchable_catalog(&self) -> Vec<SearchableTool> {
@@ -205,6 +220,52 @@ impl RemoteMcpToolSet {
}
}
+fn register_server(
+ tools: &mut BTreeMap<MangledName, RegisteredTool>,
+ connections: &mut Vec<Arc<McpServer>>,
+ server_name: &str,
+ client: Arc<McpServer>,
+ server_tools: Vec<Tool>,
+ subject: &Option<String>,
+) {
+ for tool in server_tools {
+ let Mangled {
+ name: mangled,
+ sanitized,
+ } = Mangled::new(server_name, &tool.name);
+
+ if sanitized {
+ tracing::warn!(
+ subject = ?subject,
+ server = %server_name,
+ tool = %tool.name,
+ %mangled,
+ "sanitized tool name to satisfy the provider tool-name pattern"
+ );
+ }
+
+ if tools.contains_key(&mangled) {
+ tracing::warn!(
+ subject = ?subject,
+ server = %server_name,
+ tool = %tool.name,
+ %mangled,
+ "skipping duplicate tool"
+ );
+ continue;
+ }
+
+ tools.insert(
+ mangled,
+ RegisteredTool {
+ peer: client.peer().clone(),
+ tool,
+ },
+ );
+ }
+ connections.push(client);
+}
+
impl<Context: Send + Sync + 'static> ToolSet<Context> for RemoteMcpToolSet {
fn dispatch_tool_call<'a>(
&'a self,
diff --git a/docs/AGENT_GUIDE/ai-chat.md b/docs/AGENT_GUIDE/ai-chat.md
index 007608e83e..f14c6a6cfe 100644
--- a/docs/AGENT_GUIDE/ai-chat.md
+++ b/docs/AGENT_GUIDE/ai-chat.md
@@ -1408,3 +1408,15 @@ The chat's **Read skill** tool row expands to show the full instructions. When
verifying this flow, invoke a saved skill by name, confirm the agent reads it,
and expand the row to inspect the returned content. Document access permissions
apply; ordinary documents and deleted skills cannot be read as skills.
+
+### Agent warm-up
+
+Home's agent composer and the Agents page issue a best-effort authenticated
+`POST /agent-sessions/warm`. It starts an unprompted in-memory session, hidden
+from history and lists. Opening either page must not add an empty conversation
+or execute a model/tool call. A warm response waits until ACP initialization
+and the shared MCP listing have finished. On first send, the default agent can claim the
+prepared session only when the user, model, and instructions match. Other
+personas and changed settings use normal creation. Warm failures must not block
+sending. Unclaimed sessions expire after ten minutes; a claimed conversation
+must remain visible and usable after that deadline.
diff --git a/packages/sdk/generated/agent-harness/index.ts b/packages/sdk/generated/agent-harness/index.ts
index 034081a792..7cfb93718a 100644
--- a/packages/sdk/generated/agent-harness/index.ts
+++ b/packages/sdk/generated/agent-harness/index.ts
@@ -1,4 +1,4 @@
// This file is auto-generated by @hey-api/openapi-ts
export { type Options, Sdk } from './sdk.gen';
-export type { AccessLevel, AgentAction, AgentActionId, AgentConfigKindDto, AgentConfigOptionDto, AgentConfigSelectOptionDto, AgentModelDto, AgentModelsStatusDto, AgentPermissionAction, AgentPromptAction, AgentRepositoriesResponse, AgentRepositoryBranchesResponse, AgentRepositoryDto, AgentRespondElicitationAction, AgentSessionChangesPatchResponse, AgentSessionChangesResponse, AgentSessionLogEntryDto, AgentSessionLogResponse, AgentSessionPreviewData, AgentSessionPreviewDto, AgentSessionQueueResponse, AgentSessionResponse, AgentSessionsForPullRequestData, AgentSessionsForPullRequestError, AgentSessionsForPullRequestErrors, AgentSessionsForPullRequestResponse, AgentSessionsForPullRequestResponses, AgentSetConfigOptionAction, AgentSetModelAction, AiAdmissionErrorBody, AnswerAgentSessionToolApprovalData, AnswerAgentSessionToolApprovalError, AnswerAgentSessionToolApprovalErrors, AnswerAgentSessionToolApprovalResponse, AnswerAgentSessionToolApprovalResponses, AnswerToolApprovalRequest, AnswerToolApprovalResponse, BotId, CapabilityHarnessDto, CaptureAttemptDto, CaptureOutcomeDto, ChangedFileDto, ChangesetDto, ChangesetSourceDto, ChannelSharePermission, ClientOptions, CompleteData, CompleteErrors, CompleteRequest, CompleteResponse, CompleteResponses, ControlAgentSessionData, ControlAgentSessionError, ControlAgentSessionErrors, ControlAgentSessionResponse, ControlAgentSessionResponses, ControlRequest, ControlResponse, ControlStatusDto, CreateAgentSessionData, CreateAgentSessionError, CreateAgentSessionErrors, CreateAgentSessionRequest, CreateAgentSessionResponse, CreateAgentSessionResponse2, CreateAgentSessionResponses, CreateSessionThread, DeleteAgentSessionData, DeleteAgentSessionError, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponse, DisconnectResponses, DiscoverAgentCapabilitiesHandlerData, DiscoverAgentCapabilitiesHandlerErrors, DiscoverAgentCapabilitiesHandlerResponse, DiscoverAgentCapabilitiesHandlerResponses, DiscoverAgentCapabilitiesRequest, DiscoverAgentCapabilitiesResponse, DocumentId, EditQueuedActionData, EditQueuedActionError, EditQueuedActionErrors, EditQueuedActionRequest, EditQueuedActionResponse, EditQueuedActionResponses, ElicitationAnswer, ElicitationContentValue, ElicitationRequestId, EmptyRequest, ExternalSessionResponse, FileChangeKindDto, GetAgentSandboxSizeData, GetAgentSandboxSizeError, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponse, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesError, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchError, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponse, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponse, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionError, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogError, GetAgentSessionLogErrors, GetAgentSessionLogResponse, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsError, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponse, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueError, GetAgentSessionQueueErrors, GetAgentSessionQueueResponse, GetAgentSessionQueueResponses, GetAgentSessionResponse, GetAgentSessionResponses, GitRefDto, LinkAgentSessionPullRequestData, LinkAgentSessionPullRequestError, LinkAgentSessionPullRequestErrors, LinkAgentSessionPullRequestResponse, LinkAgentSessionPullRequestResponses, LinkShare, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponse, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponse, ListAgentRepositoryBranchesResponses, ListAgentSessionPullRequestsData, ListAgentSessionPullRequestsError, ListAgentSessionPullRequestsErrors, ListAgentSessionPullRequestsResponse, ListAgentSessionPullRequestsResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponse, LoadAgentModelsHandlerResponses, LoadAgentModelsRequest, LoadAgentModelsResponse, LogDirectionDto, LogFrameDto, MessageParent, ModelHarnessDto, PermissionAnswer, PreviewAgentSessionsData, PreviewAgentSessionsError, PreviewAgentSessionsErrors, PreviewAgentSessionsRequest, PreviewAgentSessionsResponse, PreviewAgentSessionsResponse2, PreviewAgentSessionsResponses, PromptAttachment, PullRequestLinkSource, PullRequestSessionsResponse, PullRequestUrl, PutAgentSandboxSizeData, PutAgentSandboxSizeError, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponse, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeError, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponse, PutAgentSessionSandboxSizeResponses, QueuedActionDto, RefreshAgentSessionChangesData, RefreshAgentSessionChangesError, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponse, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionError, RemoveQueuedActionErrors, RemoveQueuedActionResponse, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionError, RenameAgentSessionErrors, RenameAgentSessionRequest, RenameAgentSessionResponse, RenameAgentSessionResponses, SandboxSize, SandboxSizeBody, SessionBot, SessionPullRequestLink, SessionPullRequestsResponse, SessionStatusDto, SetAgentSessionArchivedData, SetAgentSessionArchivedError, SetAgentSessionArchivedErrors, SetAgentSessionArchivedRequest, SetAgentSessionArchivedResponse, SetAgentSessionArchivedResponses, SharePermissionV2, StartData, StartErrors, StartResponse, StartResponse2, StartResponses, StatusData, StatusErrors, StatusResponse, StatusResponse2, StatusResponses, SteerQueuedActionData, SteerQueuedActionError, SteerQueuedActionErrors, SteerQueuedActionResponse, SteerQueuedActionResponses, ToolApprovalAnswerDto, ToolApprovalStatusDto, UnlinkAgentSessionPullRequestData, UnlinkAgentSessionPullRequestError, UnlinkAgentSessionPullRequestErrors, UnlinkAgentSessionPullRequestResponse, UnlinkAgentSessionPullRequestResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsError, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponse, UpdateAgentSessionPermissionsResponses, UpdateChannelSharePermission, UpdateOperation, UpdateSharePermissionRequestV2, WithAgentSessionId } from './types.gen';
+export type { AccessLevel, AgentAction, AgentActionId, AgentConfigKindDto, AgentConfigOptionDto, AgentConfigSelectOptionDto, AgentModelDto, AgentModelsStatusDto, AgentPermissionAction, AgentPromptAction, AgentRepositoriesResponse, AgentRepositoryBranchesResponse, AgentRepositoryDto, AgentRespondElicitationAction, AgentSessionChangesPatchResponse, AgentSessionChangesResponse, AgentSessionLogEntryDto, AgentSessionLogResponse, AgentSessionPreviewData, AgentSessionPreviewDto, AgentSessionQueueResponse, AgentSessionResponse, AgentSessionsForPullRequestData, AgentSessionsForPullRequestError, AgentSessionsForPullRequestErrors, AgentSessionsForPullRequestResponse, AgentSessionsForPullRequestResponses, AgentSetConfigOptionAction, AgentSetModelAction, AiAdmissionErrorBody, AnswerAgentSessionToolApprovalData, AnswerAgentSessionToolApprovalError, AnswerAgentSessionToolApprovalErrors, AnswerAgentSessionToolApprovalResponse, AnswerAgentSessionToolApprovalResponses, AnswerToolApprovalRequest, AnswerToolApprovalResponse, BotId, CapabilityHarnessDto, CaptureAttemptDto, CaptureOutcomeDto, ChangedFileDto, ChangesetDto, ChangesetSourceDto, ChannelSharePermission, ClientOptions, CompleteData, CompleteErrors, CompleteRequest, CompleteResponse, CompleteResponses, ControlAgentSessionData, ControlAgentSessionError, ControlAgentSessionErrors, ControlAgentSessionResponse, ControlAgentSessionResponses, ControlRequest, ControlResponse, ControlStatusDto, CreateAgentSessionData, CreateAgentSessionError, CreateAgentSessionErrors, CreateAgentSessionRequest, CreateAgentSessionResponse, CreateAgentSessionResponse2, CreateAgentSessionResponses, CreateSessionThread, DeleteAgentSessionData, DeleteAgentSessionError, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponse, DisconnectResponses, DiscoverAgentCapabilitiesHandlerData, DiscoverAgentCapabilitiesHandlerErrors, DiscoverAgentCapabilitiesHandlerResponse, DiscoverAgentCapabilitiesHandlerResponses, DiscoverAgentCapabilitiesRequest, DiscoverAgentCapabilitiesResponse, DocumentId, EditQueuedActionData, EditQueuedActionError, EditQueuedActionErrors, EditQueuedActionRequest, EditQueuedActionResponse, EditQueuedActionResponses, ElicitationAnswer, ElicitationContentValue, ElicitationRequestId, EmptyRequest, ExternalSessionResponse, FileChangeKindDto, GetAgentSandboxSizeData, GetAgentSandboxSizeError, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponse, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesError, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchError, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponse, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponse, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionError, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogError, GetAgentSessionLogErrors, GetAgentSessionLogResponse, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsError, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponse, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueError, GetAgentSessionQueueErrors, GetAgentSessionQueueResponse, GetAgentSessionQueueResponses, GetAgentSessionResponse, GetAgentSessionResponses, GitRefDto, LinkAgentSessionPullRequestData, LinkAgentSessionPullRequestError, LinkAgentSessionPullRequestErrors, LinkAgentSessionPullRequestResponse, LinkAgentSessionPullRequestResponses, LinkShare, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponse, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponse, ListAgentRepositoryBranchesResponses, ListAgentSessionPullRequestsData, ListAgentSessionPullRequestsError, ListAgentSessionPullRequestsErrors, ListAgentSessionPullRequestsResponse, ListAgentSessionPullRequestsResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponse, LoadAgentModelsHandlerResponses, LoadAgentModelsRequest, LoadAgentModelsResponse, LogDirectionDto, LogFrameDto, MessageParent, ModelHarnessDto, PermissionAnswer, PreviewAgentSessionsData, PreviewAgentSessionsError, PreviewAgentSessionsErrors, PreviewAgentSessionsRequest, PreviewAgentSessionsResponse, PreviewAgentSessionsResponse2, PreviewAgentSessionsResponses, PromptAttachment, PullRequestLinkSource, PullRequestSessionsResponse, PullRequestUrl, PutAgentSandboxSizeData, PutAgentSandboxSizeError, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponse, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeError, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponse, PutAgentSessionSandboxSizeResponses, QueuedActionDto, RefreshAgentSessionChangesData, RefreshAgentSessionChangesError, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponse, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionError, RemoveQueuedActionErrors, RemoveQueuedActionResponse, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionError, RenameAgentSessionErrors, RenameAgentSessionRequest, RenameAgentSessionResponse, RenameAgentSessionResponses, SandboxSize, SandboxSizeBody, SessionBot, SessionPullRequestLink, SessionPullRequestsResponse, SessionStatusDto, SetAgentSessionArchivedData, SetAgentSessionArchivedError, SetAgentSessionArchivedErrors, SetAgentSessionArchivedRequest, SetAgentSessionArchivedResponse, SetAgentSessionArchivedResponses, SharePermissionV2, StartData, StartErrors, StartResponse, StartResponse2, StartResponses, StatusData, StatusErrors, StatusResponse, StatusResponse2, StatusResponses, SteerQueuedActionData, SteerQueuedActionError, SteerQueuedActionErrors, SteerQueuedActionResponse, SteerQueuedActionResponses, ToolApprovalAnswerDto, ToolApprovalStatusDto, UnlinkAgentSessionPullRequestData, UnlinkAgentSessionPullRequestError, UnlinkAgentSessionPullRequestErrors, UnlinkAgentSessionPullRequestResponse, UnlinkAgentSessionPullRequestResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsError, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponse, UpdateAgentSessionPermissionsResponses, UpdateChannelSharePermission, UpdateOperation, UpdateSharePermissionRequestV2, WarmAgentSessionHandlerData, WarmAgentSessionHandlerResponse, WarmAgentSessionHandlerResponses, WarmAgentSessionRequest, WarmAgentSessionResponse, WithAgentSessionId } from './types.gen';
diff --git a/packages/sdk/generated/agent-harness/sdk.gen.ts b/packages/sdk/generated/agent-harness/sdk.gen.ts
index 34beadddaf..9e585e954c 100644
--- a/packages/sdk/generated/agent-harness/sdk.gen.ts
+++ b/packages/sdk/generated/agent-harness/sdk.gen.ts
@@ -2,7 +2,7 @@
import type { Client, ClientMeta, Options as Options2, RequestResult, TDataShape } from './client';
import { client } from './client.gen';
-import type { AgentSessionsForPullRequestData, AgentSessionsForPullRequestErrors, AgentSessionsForPullRequestResponses, AnswerAgentSessionToolApprovalData, AnswerAgentSessionToolApprovalErrors, AnswerAgentSessionToolApprovalResponses, CompleteData, CompleteErrors, CompleteResponses, ControlAgentSessionData, ControlAgentSessionErrors, ControlAgentSessionResponses, CreateAgentSessionData, CreateAgentSessionErrors, CreateAgentSessionResponses, DeleteAgentSessionData, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponses, DiscoverAgentCapabilitiesHandlerData, DiscoverAgentCapabilitiesHandlerErrors, DiscoverAgentCapabilitiesHandlerResponses, EditQueuedActionData, EditQueuedActionErrors, EditQueuedActionResponses, GetAgentSandboxSizeData, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogErrors, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueErrors, GetAgentSessionQueueResponses, GetAgentSessionResponses, LinkAgentSessionPullRequestData, LinkAgentSessionPullRequestErrors, LinkAgentSessionPullRequestResponses, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponses, ListAgentSessionPullRequestsData, ListAgentSessionPullRequestsErrors, ListAgentSessionPullRequestsResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponses, PreviewAgentSessionsData, PreviewAgentSessionsErrors, PreviewAgentSessionsResponses, PutAgentSandboxSizeData, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponses, RefreshAgentSessionChangesData, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionErrors, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionErrors, RenameAgentSessionResponses, SetAgentSessionArchivedData, SetAgentSessionArchivedErrors, SetAgentSessionArchivedResponses, StartData, StartErrors, StartResponses, StatusData, StatusErrors, StatusResponses, SteerQueuedActionData, SteerQueuedActionErrors, SteerQueuedActionResponses, UnlinkAgentSessionPullRequestData, UnlinkAgentSessionPullRequestErrors, UnlinkAgentSessionPullRequestResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponses } from './types.gen';
+import type { AgentSessionsForPullRequestData, AgentSessionsForPullRequestErrors, AgentSessionsForPullRequestResponses, AnswerAgentSessionToolApprovalData, AnswerAgentSessionToolApprovalErrors, AnswerAgentSessionToolApprovalResponses, CompleteData, CompleteErrors, CompleteResponses, ControlAgentSessionData, ControlAgentSessionErrors, ControlAgentSessionResponses, CreateAgentSessionData, CreateAgentSessionErrors, CreateAgentSessionResponses, DeleteAgentSessionData, DeleteAgentSessionErrors, DeleteAgentSessionResponses, DisconnectData, DisconnectErrors, DisconnectResponses, DiscoverAgentCapabilitiesHandlerData, DiscoverAgentCapabilitiesHandlerErrors, DiscoverAgentCapabilitiesHandlerResponses, EditQueuedActionData, EditQueuedActionErrors, EditQueuedActionResponses, GetAgentSandboxSizeData, GetAgentSandboxSizeErrors, GetAgentSandboxSizeResponses, GetAgentSessionChangesData, GetAgentSessionChangesErrors, GetAgentSessionChangesPatchData, GetAgentSessionChangesPatchErrors, GetAgentSessionChangesPatchResponses, GetAgentSessionChangesResponses, GetAgentSessionData, GetAgentSessionErrors, GetAgentSessionLogData, GetAgentSessionLogErrors, GetAgentSessionLogResponses, GetAgentSessionPermissionsData, GetAgentSessionPermissionsErrors, GetAgentSessionPermissionsResponses, GetAgentSessionQueueData, GetAgentSessionQueueErrors, GetAgentSessionQueueResponses, GetAgentSessionResponses, LinkAgentSessionPullRequestData, LinkAgentSessionPullRequestErrors, LinkAgentSessionPullRequestResponses, ListAgentRepositoriesData, ListAgentRepositoriesErrors, ListAgentRepositoriesResponses, ListAgentRepositoryBranchesData, ListAgentRepositoryBranchesErrors, ListAgentRepositoryBranchesResponses, ListAgentSessionPullRequestsData, ListAgentSessionPullRequestsErrors, ListAgentSessionPullRequestsResponses, LoadAgentModelsHandlerData, LoadAgentModelsHandlerErrors, LoadAgentModelsHandlerResponses, PreviewAgentSessionsData, PreviewAgentSessionsErrors, PreviewAgentSessionsResponses, PutAgentSandboxSizeData, PutAgentSandboxSizeErrors, PutAgentSandboxSizeResponses, PutAgentSessionSandboxSizeData, PutAgentSessionSandboxSizeErrors, PutAgentSessionSandboxSizeResponses, RefreshAgentSessionChangesData, RefreshAgentSessionChangesErrors, RefreshAgentSessionChangesResponses, RemoveQueuedActionData, RemoveQueuedActionErrors, RemoveQueuedActionResponses, RenameAgentSessionData, RenameAgentSessionErrors, RenameAgentSessionResponses, SetAgentSessionArchivedData, SetAgentSessionArchivedErrors, SetAgentSessionArchivedResponses, StartData, StartErrors, StartResponses, StatusData, StatusErrors, StatusResponses, SteerQueuedActionData, SteerQueuedActionErrors, SteerQueuedActionResponses, UnlinkAgentSessionPullRequestData, UnlinkAgentSessionPullRequestErrors, UnlinkAgentSessionPullRequestResponses, UpdateAgentSessionPermissionsData, UpdateAgentSessionPermissionsErrors, UpdateAgentSessionPermissionsResponses, WarmAgentSessionHandlerData, WarmAgentSessionHandlerResponses } from './types.gen';
export type Options<TData extends TDataShape = TDataShape, ThrowOnError extends boolean = boolean, TResponse = unknown> = Options2<TData, ThrowOnError, TResponse> & {
/**
@@ -183,6 +183,20 @@ export class Sdk extends HeyApiClient {
});
}
+ /**
+ * Prepare MCP connections without sending a prompt or creating a visible list row.
+ */
+ public warmAgentSessionHandler<ThrowOnError extends boolean = false>(options: Options<WarmAgentSessionHandlerData, ThrowOnError>): RequestResult<WarmAgentSessionHandlerResponses, unknown, ThrowOnError> {
+ return (options.client ?? this.client).post<WarmAgentSessionHandlerResponses, unknown, ThrowOnError>({
+ url: '/agent-sessions/warm',
+ ...options,
+ headers: {
+ 'Content-Type': 'application/json',
+ ...options.headers
+ }
+ });
+ }
+
/**
* Delete an agent session and its live resources.
*/
diff --git a/packages/sdk/generated/agent-harness/types.gen.ts b/packages/sdk/generated/agent-harness/types.gen.ts
index 8e5709417a..220a745db6 100644
--- a/packages/sdk/generated/agent-harness/types.gen.ts
+++ b/packages/sdk/generated/agent-harness/types.gen.ts
@@ -1425,6 +1425,23 @@ export type UpdateSharePermissionRequestV2 = {
teamShareAccessLevel?: null | AccessLevel;
};
+/**
+ * A client-minted id deduplicates warm calls without creating a conversation.
+ */
+export type WarmAgentSessionRequest = {
+ /**
+ * Id reserved by this browser for its next in-memory conversation.
+ */
+ id: string;
+};
+
+/**
+ * A bounded best-effort warm attempt; absence means normal creation should proceed.
+ */
+export type WarmAgentSessionResponse = {
+ session?: null | AgentSessionResponse;
+};
+
/**
* Just a session id, for the preview variants that carry nothing else.
*
@@ -1706,6 +1723,19 @@ export type PreviewAgentSessionsResponses = {
export type PreviewAgentSessionsResponse2 = PreviewAgentSessionsResponses[keyof PreviewAgentSessionsResponses];
+export type WarmAgentSessionHandlerData = {
+ body: WarmAgentSessionRequest;
+ path?: never;
+ query?: never;
+ url: '/agent-sessions/warm';
+};
+
+export type WarmAgentSessionHandlerResponses = {
+ 200: WarmAgentSessionResponse;
+};
+
+export type WarmAgentSessionHandlerResponse = WarmAgentSessionHandlerResponses[keyof WarmAgentSessionHandlerResponses];
+
export type DeleteAgentSessionData = {
body?: never;
path: {
diff --git a/packages/sdk/specs/agent-harness.json b/packages/sdk/specs/agent-harness.json
index 739bea72b5..84f162abbd 100644
--- a/packages/sdk/specs/agent-harness.json
+++ b/packages/sdk/specs/agent-harness.json
@@ -496,6 +496,35 @@
}
}
},
+ "/agent-sessions/warm": {
+ "post": {
+ "tags": ["agent-sessions"],
+ "summary": "Prepare MCP connections without sending a prompt or creating a visible list row.",
+ "operationId": "warm_agent_session_handler",
+ "requestBody": {
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WarmAgentSessionRequest"
+ }
+ }
+ },
+ "required": true
+ },
+ "responses": {
+ "200": {
+ "description": "",
+ "content": {
+ "application/json": {
+ "schema": {
+ "$ref": "#/components/schemas/WarmAgentSessionResponse"
+ }
+ }
+ }
+ }
+ }
+ }
+ },
"/agent-sessions/{session_id}": {
"get": {
"tags": ["agent-sessions"],
@@ -4016,6 +4045,35 @@
}
}
},
+ "WarmAgentSessionRequest": {
+ "type": "object",
+ "description": "A client-minted id deduplicates warm calls without creating a conversation.",
+ "required": ["id"],
+ "properties": {
+ "id": {
+ "type": "string",
+ "format": "uuid",
+ "description": "Id reserved by this browser for its next in-memory conversation."
+ }
+ }
+ },
+ "WarmAgentSessionResponse": {
+ "type": "object",
+ "description": "A bounded best-effort warm attempt; absence means normal creation should proceed.",
+ "properties": {
+ "session": {
+ "oneOf": [
+ {
+ "type": "null"
+ },
+ {
+ "$ref": "#/components/schemas/AgentSessionResponse",
+ "description": "Prepared session, hidden until explicitly claimed through create."
+ }
+ ]
+ }
+ }
+ },
"WithAgentSessionId": {
"type": "object",
"description": "Just a session id, for the preview variants that carry nothing else.\n\nClients deserialize this, so both derives are used.",
diff --git a/packages/sdk/src/coverage/skipped.ts b/packages/sdk/src/coverage/skipped.ts
index 8916a21130..542170ffc9 100644
--- a/packages/sdk/src/coverage/skipped.ts
+++ b/packages/sdk/src/coverage/skipped.ts
@@ -33,6 +33,8 @@ export const agentHarnessExcluded = [
'loadAgentModelsHandler',
'discoverAgentCapabilitiesHandler',
'previewAgentSessions',
+ // Speculative page warm-up requires a signed-in user and is app-internal.
+ 'warmAgentSessionHandler',
] as const satisfies readonly (keyof AgentHarnessSdk)[];
export const agentHarnessBacklog = [
diff --git a/services/agent_harness_service/src/api/swagger.rs b/services/agent_harness_service/src/api/swagger.rs
index 26b4147621..96e0af749a 100644
--- a/services/agent_harness_service/src/api/swagger.rs
+++ b/services/agent_harness_service/src/api/swagger.rs
@@ -61,6 +61,7 @@ impl Modify for SecurityAddon {
claude_auth::complete,
claude_auth::disconnect,
axum_router::create_agent_session_handler,
+ axum_router::warm_agent_session_handler,
axum_router::get_agent_session_handler,
axum_router::preview_agent_sessions_handler,
axum_router::rename_agent_session_handler,
diff --git a/services/agent_harness_service/src/main.rs b/services/agent_harness_service/src/main.rs
index 3ea4014f52..a1588290f0 100644
--- a/services/agent_harness_service/src/main.rs
+++ b/services/agent_harness_service/src/main.rs
@@ -497,12 +497,16 @@ async fn run() -> anyhow::Result<()> {
// against it, so the two must be the same string.
let egress_base_url = AgentHarnessEgressUrl::new()?.to_string();
- // Every session's MCP tools, listed for its telemetry the way the harness
- // itself lists them: through the egress proxy, in process.
+ // One connector for the agent and the telemetry catalog. It pools each
+ // server's session for the life of the egress token, so a replaced agent
+ // task and the catalog's listing reuse the handshake instead of opening
+ // a second set of clients and dropping them when the listing ends.
+ let mcp_connector = Arc::new(AcpMcpConnector::new(EgressMcpClient::new(
+ Arc::clone(&egress),
+ &egress_base_url,
+ )));
let tool_catalog: Arc<dyn agent_session::domain::ports::SessionToolCatalog> =
- Arc::new(McpToolCatalog::new(Arc::new(AcpMcpConnector::new(
- EgressMcpClient::new(Arc::clone(&egress), &egress_base_url),
- ))));
+ Arc::new(McpToolCatalog::new(Arc::clone(&mcp_connector)));
let sessions = sessions.with_tool_catalog(Arc::clone(&tool_catalog));
let tool_context = ai_tools::build_tool_service_context_from_env(
@@ -550,16 +554,9 @@ async fn run() -> anyhow::Result<()> {
// their model context from the same log every frame lands in.
let frames = Arc::new(LogFrameSource::new(session_repo.clone()));
let inmem = InMemRuntime {
- manager: InMemAgentManager::new(
- Arc::clone(&inmem_model_engine),
- frames,
- Arc::new(AcpMcpConnector::new(EgressMcpClient::new(
- Arc::clone(&egress),
- &egress_base_url,
- ))),
- )
- .with_admission(admission.clone())
- .with_dev_commands(enable_dev_commands),
+ manager: InMemAgentManager::new(Arc::clone(&inmem_model_engine), frames, mcp_connector)
+ .with_admission(admission.clone())
+ .with_dev_commands(enable_dev_commands),
};
// The sandbox provider serves every bot but the in-memory one, which the
// router pulls out by bot id before the provider ever sees it.
@@ -572,7 +569,7 @@ async fn run() -> anyhow::Result<()> {
lifecycle_publisher.clone(),
replica,
)
- .with_tool_catalog(tool_catalog);
+ .with_tool_catalog(Arc::clone(&tool_catalog));
let sandbox_and_inmem = RoutedContainers::new(sandbox, Some(inmem), inmem_sessions);
// Cursor sessions run on their owner's own Cursor account, so there is no
@@ -1014,8 +1011,17 @@ async fn run() -> anyhow::Result<()> {
IngressAgentSessionNotifier::new(Arc::clone(&notifications)),
)
.with_admission(admission.clone())
- .with_repositories(open_repositories),
+ .with_repositories(open_repositories)
+ .with_warm_sessions(Arc::new(session_repo.clone()), tool_catalog),
);
+ let warm_cleanup = Arc::clone(&harness);
+ tokio::spawn(async move {
+ let mut ticks = tokio::time::interval(std::time::Duration::from_secs(60));
+ loop {
+ ticks.tick().await;
+ warm_cleanup.reap_warm_sessions().await;
+ }
+ });
let model_probe_timeout = std::time::Duration::from_secs(10);
let macrod_models =
MacrodModels::new(Arc::clone(&runtimes), redis.clone(), model_probe_timeout);