@copilotkit/runtime 1.72.1-canary.sp-longthread-perf → 1.73.1

package/dist/v2/runtime/handlers/handle-stop.mjs

@@ -6,29 +6,33 @@ import { resolveIntelligenceUser } from "./shared/resolve-intelligence-user.mjs"
 import { EventType } from "@ag-ui/client";
 
 //#region src/v2/runtime/handlers/handle-stop.ts
+/** Read `{ runId? }` from a stop request body; a 400 Response when the body is not a valid scope. */
+async function parseStopScope(request) {
+	try {
+		const raw = await request.text();
+		const body = raw.trim() ? JSON.parse(raw) : {};
+		if (typeof body !== "object" || body === null || Array.isArray(body)) return Response.json({ error: "Invalid stop request" }, { status: 400 });
+		if (Object.keys(body).some((key) => key !== "runId")) return Response.json({ error: "Invalid stop request" }, { status: 400 });
+		if (!("runId" in body)) return {};
+		if (typeof body.runId !== "string" || !body.runId.trim()) return Response.json({ error: "Invalid runId" }, { status: 400 });
+		return { runId: body.runId };
+	} catch {
+		return Response.json({ error: "Invalid stop request" }, { status: 400 });
+	}
+}
 /** Stop an active run after applying the runtime's application identity policy. */
 async function handleStopAgent({ runtime, request, agentId, threadId }) {
 	try {
+		const scope = await parseStopScope(request.clone());
+		if (isHandlerResponse(scope)) return scope;
+		const { runId } = scope;
 		let stopThreadId = threadId;
-		let runId;
 		if (isIntelligenceRuntime(runtime)) {
-			const bodyRequest = request.clone();
 			const user = await resolveIntelligenceUser({
 				runtime,
 				request
 			});
 			if (isHandlerResponse(user)) return user;
-			try {
-				const raw = await bodyRequest.text();
-				const body = raw.trim() ? JSON.parse(raw) : {};
-				if (typeof body !== "object" || body === null || Array.isArray(body)) return Response.json({ error: "Invalid stop request" }, { status: 400 });
-				if ("runId" in body) {
-					if (typeof body.runId !== "string" || !body.runId.trim()) return Response.json({ error: "Invalid runId" }, { status: 400 });
-					runId = body.runId;
-				}
-			} catch {
-				return Response.json({ error: "Invalid stop request" }, { status: 400 });
-			}
 			try {
 				const thread = await runtime.intelligence.getThread({
 					threadId,
@@ -54,7 +58,7 @@ async function handleStopAgent({ runtime, request, agentId, threadId }) {
 			...runId === void 0 ? {} : { runId }
 		})) return new Response(JSON.stringify({
 			stopped: false,
-			message: `No active run for thread '${threadId}'.`
+			message: runId === void 0 ? `No active run for thread '${threadId}'.` : `Run '${runId}' is not the active run for thread '${threadId}'.`
 		}), {
 			status: 200,
 			headers: { "Content-Type": "application/json" }

package/dist/v2/runtime/handlers/handle-stop.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"handle-stop.mjs","names":[],"sources":["../../../../src/v2/runtime/handlers/handle-stop.ts"],"sourcesContent":["import type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { isIntelligenceRuntime, resolveAgents } from \"../core/runtime\";\nimport { EventType } from \"@ag-ui/client\";\nimport { resolveIntelligenceUser } from \"./shared/resolve-intelligence-user\";\nimport { isHandlerResponse } from \"./shared/json-response\";\nimport { getPlatformErrorStatus } from \"./shared/intelligence-utils\";\n\ninterface StopAgentParameters {\n  request: Request;\n  runtime: CopilotRuntimeLike;\n  agentId: string;\n  threadId: string;\n}\n\n/** Stop an active run after applying the runtime's application identity policy. */\nexport async function handleStopAgent({\n  runtime,\n  request,\n  agentId,\n  threadId,\n}: StopAgentParameters): Promise<Response> {\n  try {\n    let stopThreadId = threadId;\n    let runId: string | undefined;\n    if (isIntelligenceRuntime(runtime)) {\n      const bodyRequest = request.clone();\n      const user = await resolveIntelligenceUser({ runtime, request });\n      if (isHandlerResponse(user)) return user;\n      try {\n        const raw = await bodyRequest.text();\n        const body: unknown = raw.trim() ? JSON.parse(raw) : {};\n        if (typeof body !== \"object\" || body === null || Array.isArray(body)) {\n          return Response.json(\n            { error: \"Invalid stop request\" },\n            { status: 400 },\n          );\n        }\n        if (\"runId\" in body) {\n          if (typeof body.runId !== \"string\" || !body.runId.trim()) {\n            return Response.json({ error: \"Invalid runId\" }, { status: 400 });\n          }\n          runId = body.runId;\n        }\n      } catch {\n        return Response.json(\n          { error: \"Invalid stop request\" },\n          { status: 400 },\n        );\n      }\n      try {\n        const thread = await runtime.intelligence.getThread({\n          threadId,\n          userId: user.id,\n        });\n        if (!thread || typeof thread.id !== \"string\" || !thread.id.trim()) {\n          return Response.json(\n            { error: \"Invalid thread response\" },\n            { status: 502 },\n          );\n        }\n        if (thread.agentId !== undefined && thread.agentId !== agentId) {\n          return Response.json(\n            { error: \"Thread access denied\" },\n            { status: 403 },\n          );\n        }\n        stopThreadId = thread.id;\n      } catch (error) {\n        const status = getPlatformErrorStatus(error);\n        return Response.json(\n          { error: \"Thread access denied\" },\n          { status: status && status >= 400 && status < 500 ? status : 502 },\n        );\n      }\n    }\n    const agents = await resolveAgents(runtime.agents, request);\n\n    if (!agents[agentId]) {\n      return new Response(\n        JSON.stringify({\n          error: \"Agent not found\",\n          message: `Agent '${agentId}' does not exist`,\n        }),\n        {\n          status: 404,\n          headers: { \"Content-Type\": \"application/json\" },\n        },\n      );\n    }\n\n    const stopped = await runtime.runner.stop({\n      threadId: stopThreadId,\n      ...(runId === undefined ? {} : { runId }),\n    });\n\n    if (!stopped) {\n      return new Response(\n        JSON.stringify({\n          stopped: false,\n          message: `No active run for thread '${threadId}'.`,\n        }),\n        {\n          status: 200,\n          headers: { \"Content-Type\": \"application/json\" },\n        },\n      );\n    }\n\n    return new Response(\n      JSON.stringify({\n        stopped: true,\n        interrupt: {\n          type: EventType.RUN_ERROR,\n          message: \"Run stopped by user\",\n          code: \"STOPPED\",\n        },\n      }),\n      {\n        status: 200,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  } catch (error) {\n    console.error(\"Error stopping agent run:\", error);\n\n    return new Response(\n      JSON.stringify({\n        error: \"Failed to stop agent\",\n        message: error instanceof Error ? error.message : \"Unknown error\",\n      }),\n      {\n        status: 500,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n"],"mappings":";;;;;;;;;AAeA,eAAsB,gBAAgB,EACpC,SACA,SACA,SACA,YACyC;AACzC,KAAI;EACF,IAAI,eAAe;EACnB,IAAI;AACJ,MAAI,sBAAsB,QAAQ,EAAE;GAClC,MAAM,cAAc,QAAQ,OAAO;GACnC,MAAM,OAAO,MAAM,wBAAwB;IAAE;IAAS;IAAS,CAAC;AAChE,OAAI,kBAAkB,KAAK,CAAE,QAAO;AACpC,OAAI;IACF,MAAM,MAAM,MAAM,YAAY,MAAM;IACpC,MAAM,OAAgB,IAAI,MAAM,GAAG,KAAK,MAAM,IAAI,GAAG,EAAE;AACvD,QAAI,OAAO,SAAS,YAAY,SAAS,QAAQ,MAAM,QAAQ,KAAK,CAClE,QAAO,SAAS,KACd,EAAE,OAAO,wBAAwB,EACjC,EAAE,QAAQ,KAAK,CAChB;AAEH,QAAI,WAAW,MAAM;AACnB,SAAI,OAAO,KAAK,UAAU,YAAY,CAAC,KAAK,MAAM,MAAM,CACtD,QAAO,SAAS,KAAK,EAAE,OAAO,iBAAiB,EAAE,EAAE,QAAQ,KAAK,CAAC;AAEnE,aAAQ,KAAK;;WAET;AACN,WAAO,SAAS,KACd,EAAE,OAAO,wBAAwB,EACjC,EAAE,QAAQ,KAAK,CAChB;;AAEH,OAAI;IACF,MAAM,SAAS,MAAM,QAAQ,aAAa,UAAU;KAClD;KACA,QAAQ,KAAK;KACd,CAAC;AACF,QAAI,CAAC,UAAU,OAAO,OAAO,OAAO,YAAY,CAAC,OAAO,GAAG,MAAM,CAC/D,QAAO,SAAS,KACd,EAAE,OAAO,2BAA2B,EACpC,EAAE,QAAQ,KAAK,CAChB;AAEH,QAAI,OAAO,YAAY,UAAa,OAAO,YAAY,QACrD,QAAO,SAAS,KACd,EAAE,OAAO,wBAAwB,EACjC,EAAE,QAAQ,KAAK,CAChB;AAEH,mBAAe,OAAO;YACf,OAAO;IACd,MAAM,SAAS,uBAAuB,MAAM;AAC5C,WAAO,SAAS,KACd,EAAE,OAAO,wBAAwB,EACjC,EAAE,QAAQ,UAAU,UAAU,OAAO,SAAS,MAAM,SAAS,KAAK,CACnE;;;AAKL,MAAI,EAFW,MAAM,cAAc,QAAQ,QAAQ,QAAQ,EAE/C,SACV,QAAO,IAAI,SACT,KAAK,UAAU;GACb,OAAO;GACP,SAAS,UAAU,QAAQ;GAC5B,CAAC,EACF;GACE,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CACF;AAQH,MAAI,CALY,MAAM,QAAQ,OAAO,KAAK;GACxC,UAAU;GACV,GAAI,UAAU,SAAY,EAAE,GAAG,EAAE,OAAO;GACzC,CAAC,CAGA,QAAO,IAAI,SACT,KAAK,UAAU;GACb,SAAS;GACT,SAAS,6BAA6B,SAAS;GAChD,CAAC,EACF;GACE,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CACF;AAGH,SAAO,IAAI,SACT,KAAK,UAAU;GACb,SAAS;GACT,WAAW;IACT,MAAM,UAAU;IAChB,SAAS;IACT,MAAM;IACP;GACF,CAAC,EACF;GACE,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CACF;UACM,OAAO;AACd,UAAQ,MAAM,6BAA6B,MAAM;AAEjD,SAAO,IAAI,SACT,KAAK,UAAU;GACb,OAAO;GACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU;GACnD,CAAC,EACF;GACE,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CACF"}
+{"version":3,"file":"handle-stop.mjs","names":[],"sources":["../../../../src/v2/runtime/handlers/handle-stop.ts"],"sourcesContent":["import type { CopilotRuntimeLike } from \"../core/runtime\";\nimport { isIntelligenceRuntime, resolveAgents } from \"../core/runtime\";\nimport { EventType } from \"@ag-ui/client\";\nimport { resolveIntelligenceUser } from \"./shared/resolve-intelligence-user\";\nimport { isHandlerResponse } from \"./shared/json-response\";\nimport { getPlatformErrorStatus } from \"./shared/intelligence-utils\";\n\ninterface StopAgentParameters {\n  request: Request;\n  runtime: CopilotRuntimeLike;\n  agentId: string;\n  threadId: string;\n}\n\n/** Read `{ runId? }` from a stop request body; a 400 Response when the body is not a valid scope. */\nasync function parseStopScope(\n  request: Request,\n): Promise<{ runId?: string } | Response> {\n  try {\n    const raw = await request.text();\n    const body: unknown = raw.trim() ? JSON.parse(raw) : {};\n    if (typeof body !== \"object\" || body === null || Array.isArray(body)) {\n      return Response.json({ error: \"Invalid stop request\" }, { status: 400 });\n    }\n    // Only `runId` is allowed. A misspelt key must not fall through to a\n    // thread-wide stop, because a stop cannot be undone.\n    if (Object.keys(body).some((key) => key !== \"runId\")) {\n      return Response.json({ error: \"Invalid stop request\" }, { status: 400 });\n    }\n    if (!(\"runId\" in body)) return {};\n    if (typeof body.runId !== \"string\" || !body.runId.trim()) {\n      return Response.json({ error: \"Invalid runId\" }, { status: 400 });\n    }\n    return { runId: body.runId };\n  } catch {\n    return Response.json({ error: \"Invalid stop request\" }, { status: 400 });\n  }\n}\n\n/** Stop an active run after applying the runtime's application identity policy. */\nexport async function handleStopAgent({\n  runtime,\n  request,\n  agentId,\n  threadId,\n}: StopAgentParameters): Promise<Response> {\n  try {\n    // Parse the optional run scope for every runtime kind, from a clone so an\n    // identity callback can still read the original body. No body or `{}`\n    // keeps the thread-wide stop existing clients rely on.\n    const scope = await parseStopScope(request.clone());\n    if (isHandlerResponse(scope)) return scope;\n    const { runId } = scope;\n    let stopThreadId = threadId;\n    if (isIntelligenceRuntime(runtime)) {\n      const user = await resolveIntelligenceUser({ runtime, request });\n      if (isHandlerResponse(user)) return user;\n      try {\n        const thread = await runtime.intelligence.getThread({\n          threadId,\n          userId: user.id,\n        });\n        if (!thread || typeof thread.id !== \"string\" || !thread.id.trim()) {\n          return Response.json(\n            { error: \"Invalid thread response\" },\n            { status: 502 },\n          );\n        }\n        if (thread.agentId !== undefined && thread.agentId !== agentId) {\n          return Response.json(\n            { error: \"Thread access denied\" },\n            { status: 403 },\n          );\n        }\n        stopThreadId = thread.id;\n      } catch (error) {\n        const status = getPlatformErrorStatus(error);\n        return Response.json(\n          { error: \"Thread access denied\" },\n          { status: status && status >= 400 && status < 500 ? status : 502 },\n        );\n      }\n    }\n    const agents = await resolveAgents(runtime.agents, request);\n\n    if (!agents[agentId]) {\n      return new Response(\n        JSON.stringify({\n          error: \"Agent not found\",\n          message: `Agent '${agentId}' does not exist`,\n        }),\n        {\n          status: 404,\n          headers: { \"Content-Type\": \"application/json\" },\n        },\n      );\n    }\n\n    const stopped = await runtime.runner.stop({\n      threadId: stopThreadId,\n      ...(runId === undefined ? {} : { runId }),\n    });\n\n    if (!stopped) {\n      return new Response(\n        JSON.stringify({\n          stopped: false,\n          message:\n            runId === undefined\n              ? `No active run for thread '${threadId}'.`\n              : `Run '${runId}' is not the active run for thread '${threadId}'.`,\n        }),\n        {\n          status: 200,\n          headers: { \"Content-Type\": \"application/json\" },\n        },\n      );\n    }\n\n    return new Response(\n      JSON.stringify({\n        stopped: true,\n        interrupt: {\n          type: EventType.RUN_ERROR,\n          message: \"Run stopped by user\",\n          code: \"STOPPED\",\n        },\n      }),\n      {\n        status: 200,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  } catch (error) {\n    console.error(\"Error stopping agent run:\", error);\n\n    return new Response(\n      JSON.stringify({\n        error: \"Failed to stop agent\",\n        message: error instanceof Error ? error.message : \"Unknown error\",\n      }),\n      {\n        status: 500,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/v2/runtime/handlers/handle-suggest.cjs

@@ -55,14 +55,15 @@ async function handleSuggestAgent({ runtime, request, agentId }) {
 		request,
 		agentId,
 		captureTelemetry: false,
+		keepAliveIntervalSeconds: runtime.sseKeepAliveIntervalSeconds,
 		observableFactory: () => new rxjs.Observable((subscriber) => {
-			const collected = [];
+			const finalizer = (0, _copilotkit_shared.createRunEventFinalizer)();
 			let settled = false;
 			agent.runAgent(input, { onEvent: ({ event }) => {
-				collected.push(event);
+				finalizer.observe(event);
 				subscriber.next(event);
 			} }).then(() => {
-				for (const event of (0, _copilotkit_shared.finalizeRunEvents)(collected, { stopRequested: false })) subscriber.next(event);
+				for (const event of finalizer.finalize({ stopRequested: false })) subscriber.next(event);
 				settled = true;
 				subscriber.complete();
 			}).catch((error) => {

package/dist/v2/runtime/handlers/handle-suggest.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"handle-suggest.cjs","names":["cloneAgentForRequest","parseRunRequest","mergeForwardableHeaders","resolveForwardHeadersPolicy","createSseEventResponse","Observable"],"sources":["../../../../src/v2/runtime/handlers/handle-suggest.ts"],"sourcesContent":["import type { AbstractAgent, BaseEvent } from \"@ag-ui/client\";\nimport { finalizeRunEvents } from \"@copilotkit/shared\";\nimport { Observable } from \"rxjs\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"./header-utils\";\nimport { cloneAgentForRequest, parseRunRequest } from \"./shared/agent-utils\";\nimport { createSseEventResponse } from \"./shared/sse-response\";\n\n/**\n * Parameters for {@link handleSuggestAgent}.\n */\ninterface SuggestAgentParameters {\n  /** The runtime whose registry the agent is resolved from. */\n  runtime: CopilotRuntimeLike;\n  /** The incoming `POST /agent/:agentId/suggest` request. */\n  request: Request;\n  /** The route-resolved agent id to run. */\n  agentId: string;\n}\n\n/**\n * Stateless suggestion run.\n *\n * Executes the provider agent **directly** and streams its AG-UI events back as\n * SSE — the same wire format as `/agent/:id/run`, so the client consumes it with\n * the stock `HttpAgent` transport and chips fill in as the provider emits them.\n * It deliberately does not go through `runtime.runner`: the runner's\n * `run()` writes to a module-level store keyed by threadId (backing the SSE\n * runtime's local thread endpoints), which would leak the throwaway suggestion\n * thread. This handler runs the agent's event pipeline **without** that\n * persistence — no thread, lock, gateway, name-gen, or run telemetry — so\n * dynamic suggestions are side-effect-free in every runtime mode.\n *\n * The only per-request configuration it applies is forwarding the request's\n * allowlisted headers (`authorization` + `x-*`) onto the agent clone. It does\n * **not** attach any request middleware — no A2UI, no MCPApps, no\n * OpenGenerativeUI, no Intelligence enterprise-learning tools. The **client**\n * (the core suggestion engine) forces `toolChoice: copilotkitSuggest` in the\n * request body; this handler does not set tool choice itself and relies on it\n * being present in the incoming `input`. Given that forced tool choice, any\n * middleware-injected tools are dead weight, and MCPApps setup can incur a\n * `listTools` network round-trip per suggestion under `available: \"always\"` — a\n * side effect this path must never pay.\n *\n * When the client aborts the HTTP request (via its `AbortController`), the\n * server-side run is cancelled best-effort so an aborted suggestion does not\n * keep running a provider call to completion.\n *\n * @param params - The runtime, request, and resolved agent id.\n * @returns A `text/event-stream` `Response` of the provider agent's AG-UI events\n *   on success, or the resolution `Response` (e.g. 404/400) when agent/body\n *   resolution fails before streaming begins.\n */\nexport async function handleSuggestAgent({\n  runtime,\n  request,\n  agentId,\n}: SuggestAgentParameters): Promise<Response> {\n  const agent = await cloneAgentForRequest(runtime, agentId, request);\n  if (agent instanceof Response) {\n    return agent;\n  }\n\n  // Carry the registry key onto the clone so any framework relying on it during\n  // the run sees the correct agentId.\n  agent.agentId = agentId;\n\n  const input = await parseRunRequest(request);\n  if (input instanceof Response) {\n    return input;\n  }\n\n  // Forward eligible inbound headers onto the clone under the runtime's resolved\n  // forwarding policy (same helper the run handler uses: `authorization` /\n  // custom `x-*`, infra/proxy/platform headers denylisted, server-set headers\n  // winning on collision — #5712). Unlike a full agent run, the suggest path\n  // intentionally attaches no middleware (see the handler docblock): the forced\n  // `copilotkitSuggest` tool choice makes any middleware-injected tools dead\n  // weight, and MCPApps setup can trigger a `listTools` network round-trip we\n  // must never incur per suggestion.\n  //\n  // `AbstractAgent` doesn't declare `headers` on its base type (concrete\n  // framework agents add it), so narrow to the header-carrying shape rather\n  // than casting to `any`.\n  const headerCarryingAgent = agent as AbstractAgent & {\n    headers?: Record<string, string>;\n  };\n  headerCarryingAgent.headers = mergeForwardableHeaders(\n    headerCarryingAgent.headers,\n    request,\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n\n  agent.setMessages(input.messages);\n  agent.setState(input.state);\n  agent.threadId = input.threadId;\n\n  // Stream the provider agent's events over SSE without persistence. This is\n  // the runner's event pipeline (`agent.runAgent({ onEvent })` + terminal-event\n  // finalization) minus the `GLOBAL_STORE` writes that would leak a thread.\n  // `captureTelemetry: false` keeps suggestions out of run telemetry; omitting\n  // `debugEventBus` keeps them out of the inspector's run trace.\n  return createSseEventResponse({\n    request,\n    agentId,\n    captureTelemetry: false,\n    observableFactory: () =>\n      new Observable<BaseEvent>((subscriber) => {\n        // Collected so `finalizeRunEvents` can append any missing terminal\n        // events (e.g. an unclosed message/tool call, or a `RUN_FINISHED`) —\n        // the same closure the runner applies — so the client sees a\n        // well-formed AG-UI sequence.\n        const collected: BaseEvent[] = [];\n        let settled = false;\n\n        void agent\n          .runAgent(input, {\n            onEvent: ({ event }) => {\n              collected.push(event);\n              subscriber.next(event);\n            },\n          })\n          .then(() => {\n            for (const event of finalizeRunEvents(collected, {\n              stopRequested: false,\n            })) {\n              subscriber.next(event);\n            }\n            settled = true;\n            subscriber.complete();\n          })\n          .catch((error: unknown) => {\n            settled = true;\n            subscriber.error(error);\n          });\n\n        // Teardown fires when the response stream is torn down (client abort /\n        // disconnect). Cancel the still-running provider call best-effort.\n        return () => {\n          if (!settled && typeof agent.abortRun === \"function\") {\n            try {\n              agent.abortRun();\n            } catch {\n              // best-effort — nothing actionable if aborting the run fails.\n            }\n          }\n        };\n      }),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,eAAsB,mBAAmB,EACvC,SACA,SACA,WAC4C;CAC5C,MAAM,QAAQ,MAAMA,yCAAqB,SAAS,SAAS,QAAQ;AACnE,KAAI,iBAAiB,SACnB,QAAO;AAKT,OAAM,UAAU;CAEhB,MAAM,QAAQ,MAAMC,oCAAgB,QAAQ;AAC5C,KAAI,iBAAiB,SACnB,QAAO;CAeT,MAAM,sBAAsB;AAG5B,qBAAoB,UAAUC,6CAC5B,oBAAoB,SACpB,SACA,QAAQ,wBAAwBC,iDAA4B,OAAU,CACvE;AAED,OAAM,YAAY,MAAM,SAAS;AACjC,OAAM,SAAS,MAAM,MAAM;AAC3B,OAAM,WAAW,MAAM;AAOvB,QAAOC,4CAAuB;EAC5B;EACA;EACA,kBAAkB;EAClB,yBACE,IAAIC,iBAAuB,eAAe;GAKxC,MAAM,YAAyB,EAAE;GACjC,IAAI,UAAU;AAEd,GAAK,MACF,SAAS,OAAO,EACf,UAAU,EAAE,YAAY;AACtB,cAAU,KAAK,MAAM;AACrB,eAAW,KAAK,MAAM;MAEzB,CAAC,CACD,WAAW;AACV,SAAK,MAAM,mDAA2B,WAAW,EAC/C,eAAe,OAChB,CAAC,CACA,YAAW,KAAK,MAAM;AAExB,cAAU;AACV,eAAW,UAAU;KACrB,CACD,OAAO,UAAmB;AACzB,cAAU;AACV,eAAW,MAAM,MAAM;KACvB;AAIJ,gBAAa;AACX,QAAI,CAAC,WAAW,OAAO,MAAM,aAAa,WACxC,KAAI;AACF,WAAM,UAAU;YACV;;IAKZ;EACL,CAAC"}
+{"version":3,"file":"handle-suggest.cjs","names":["cloneAgentForRequest","parseRunRequest","mergeForwardableHeaders","resolveForwardHeadersPolicy","createSseEventResponse","Observable"],"sources":["../../../../src/v2/runtime/handlers/handle-suggest.ts"],"sourcesContent":["import type { AbstractAgent, BaseEvent } from \"@ag-ui/client\";\nimport { createRunEventFinalizer } from \"@copilotkit/shared\";\nimport { Observable } from \"rxjs\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"./header-utils\";\nimport { cloneAgentForRequest, parseRunRequest } from \"./shared/agent-utils\";\nimport { createSseEventResponse } from \"./shared/sse-response\";\n\n/**\n * Parameters for {@link handleSuggestAgent}.\n */\ninterface SuggestAgentParameters {\n  /** The runtime whose registry the agent is resolved from. */\n  runtime: CopilotRuntimeLike;\n  /** The incoming `POST /agent/:agentId/suggest` request. */\n  request: Request;\n  /** The route-resolved agent id to run. */\n  agentId: string;\n}\n\n/**\n * Stateless suggestion run.\n *\n * Executes the provider agent **directly** and streams its AG-UI events back as\n * SSE — the same wire format as `/agent/:id/run`, so the client consumes it with\n * the stock `HttpAgent` transport and chips fill in as the provider emits them.\n * It deliberately does not go through `runtime.runner`: the runner's\n * `run()` writes to a module-level store keyed by threadId (backing the SSE\n * runtime's local thread endpoints), which would leak the throwaway suggestion\n * thread. This handler runs the agent's event pipeline **without** that\n * persistence — no thread, lock, gateway, name-gen, or run telemetry — so\n * dynamic suggestions are side-effect-free in every runtime mode.\n *\n * The only per-request configuration it applies is forwarding the request's\n * allowlisted headers (`authorization` + `x-*`) onto the agent clone. It does\n * **not** attach any request middleware — no A2UI, no MCPApps, no\n * OpenGenerativeUI, no Intelligence enterprise-learning tools. The **client**\n * (the core suggestion engine) forces `toolChoice: copilotkitSuggest` in the\n * request body; this handler does not set tool choice itself and relies on it\n * being present in the incoming `input`. Given that forced tool choice, any\n * middleware-injected tools are dead weight, and MCPApps setup can incur a\n * `listTools` network round-trip per suggestion under `available: \"always\"` — a\n * side effect this path must never pay.\n *\n * When the client aborts the HTTP request (via its `AbortController`), the\n * server-side run is cancelled best-effort so an aborted suggestion does not\n * keep running a provider call to completion.\n *\n * @param params - The runtime, request, and resolved agent id.\n * @returns A `text/event-stream` `Response` of the provider agent's AG-UI events\n *   on success, or the resolution `Response` (e.g. 404/400) when agent/body\n *   resolution fails before streaming begins.\n */\nexport async function handleSuggestAgent({\n  runtime,\n  request,\n  agentId,\n}: SuggestAgentParameters): Promise<Response> {\n  const agent = await cloneAgentForRequest(runtime, agentId, request);\n  if (agent instanceof Response) {\n    return agent;\n  }\n\n  // Carry the registry key onto the clone so any framework relying on it during\n  // the run sees the correct agentId.\n  agent.agentId = agentId;\n\n  const input = await parseRunRequest(request);\n  if (input instanceof Response) {\n    return input;\n  }\n\n  // Forward eligible inbound headers onto the clone under the runtime's resolved\n  // forwarding policy (same helper the run handler uses: `authorization` /\n  // custom `x-*`, infra/proxy/platform headers denylisted, server-set headers\n  // winning on collision — #5712). Unlike a full agent run, the suggest path\n  // intentionally attaches no middleware (see the handler docblock): the forced\n  // `copilotkitSuggest` tool choice makes any middleware-injected tools dead\n  // weight, and MCPApps setup can trigger a `listTools` network round-trip we\n  // must never incur per suggestion.\n  //\n  // `AbstractAgent` doesn't declare `headers` on its base type (concrete\n  // framework agents add it), so narrow to the header-carrying shape rather\n  // than casting to `any`.\n  const headerCarryingAgent = agent as AbstractAgent & {\n    headers?: Record<string, string>;\n  };\n  headerCarryingAgent.headers = mergeForwardableHeaders(\n    headerCarryingAgent.headers,\n    request,\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n\n  agent.setMessages(input.messages);\n  agent.setState(input.state);\n  agent.threadId = input.threadId;\n\n  // Stream the provider agent's events over SSE without persistence. This is\n  // the runner's event pipeline (`agent.runAgent({ onEvent })` + terminal-event\n  // finalization) minus the `GLOBAL_STORE` writes that would leak a thread.\n  // `captureTelemetry: false` keeps suggestions out of run telemetry; omitting\n  // `debugEventBus` keeps them out of the inspector's run trace.\n  return createSseEventResponse({\n    request,\n    agentId,\n    captureTelemetry: false,\n    keepAliveIntervalSeconds: runtime.sseKeepAliveIntervalSeconds,\n    observableFactory: () =>\n      new Observable<BaseEvent>((subscriber) => {\n        // Tracks open message/tool lifecycles so the missing terminal events\n        // (an unclosed message/tool call, or a `RUN_FINISHED`) can be appended\n        // — the same closure the runner applies — so the client sees a\n        // well-formed AG-UI sequence. Nothing is persisted here, so only the\n        // open ids are kept, never the streamed events themselves.\n        const finalizer = createRunEventFinalizer();\n        let settled = false;\n\n        void agent\n          .runAgent(input, {\n            onEvent: ({ event }) => {\n              finalizer.observe(event);\n              subscriber.next(event);\n            },\n          })\n          .then(() => {\n            for (const event of finalizer.finalize({ stopRequested: false })) {\n              subscriber.next(event);\n            }\n            settled = true;\n            subscriber.complete();\n          })\n          .catch((error: unknown) => {\n            settled = true;\n            subscriber.error(error);\n          });\n\n        // Teardown fires when the response stream is torn down (client abort /\n        // disconnect). Cancel the still-running provider call best-effort.\n        return () => {\n          if (!settled && typeof agent.abortRun === \"function\") {\n            try {\n              agent.abortRun();\n            } catch {\n              // best-effort — nothing actionable if aborting the run fails.\n            }\n          }\n        };\n      }),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,eAAsB,mBAAmB,EACvC,SACA,SACA,WAC4C;CAC5C,MAAM,QAAQ,MAAMA,yCAAqB,SAAS,SAAS,QAAQ;AACnE,KAAI,iBAAiB,SACnB,QAAO;AAKT,OAAM,UAAU;CAEhB,MAAM,QAAQ,MAAMC,oCAAgB,QAAQ;AAC5C,KAAI,iBAAiB,SACnB,QAAO;CAeT,MAAM,sBAAsB;AAG5B,qBAAoB,UAAUC,6CAC5B,oBAAoB,SACpB,SACA,QAAQ,wBAAwBC,iDAA4B,OAAU,CACvE;AAED,OAAM,YAAY,MAAM,SAAS;AACjC,OAAM,SAAS,MAAM,MAAM;AAC3B,OAAM,WAAW,MAAM;AAOvB,QAAOC,4CAAuB;EAC5B;EACA;EACA,kBAAkB;EAClB,0BAA0B,QAAQ;EAClC,yBACE,IAAIC,iBAAuB,eAAe;GAMxC,MAAM,6DAAqC;GAC3C,IAAI,UAAU;AAEd,GAAK,MACF,SAAS,OAAO,EACf,UAAU,EAAE,YAAY;AACtB,cAAU,QAAQ,MAAM;AACxB,eAAW,KAAK,MAAM;MAEzB,CAAC,CACD,WAAW;AACV,SAAK,MAAM,SAAS,UAAU,SAAS,EAAE,eAAe,OAAO,CAAC,CAC9D,YAAW,KAAK,MAAM;AAExB,cAAU;AACV,eAAW,UAAU;KACrB,CACD,OAAO,UAAmB;AACzB,cAAU;AACV,eAAW,MAAM,MAAM;KACvB;AAIJ,gBAAa;AACX,QAAI,CAAC,WAAW,OAAO,MAAM,aAAa,WACxC,KAAI;AACF,WAAM,UAAU;YACV;;IAKZ;EACL,CAAC"}

package/dist/v2/runtime/handlers/handle-suggest.mjs

@@ -2,7 +2,7 @@ import "reflect-metadata";
 import { mergeForwardableHeaders, resolveForwardHeadersPolicy } from "./header-utils.mjs";
 import { cloneAgentForRequest, parseRunRequest } from "./shared/agent-utils.mjs";
 import { createSseEventResponse } from "./shared/sse-response.mjs";
-import { finalizeRunEvents } from "@copilotkit/shared";
+import { createRunEventFinalizer } from "@copilotkit/shared";
 import { Observable } from "rxjs";
 
 //#region src/v2/runtime/handlers/handle-suggest.ts
@@ -54,14 +54,15 @@ async function handleSuggestAgent({ runtime, request, agentId }) {
 		request,
 		agentId,
 		captureTelemetry: false,
+		keepAliveIntervalSeconds: runtime.sseKeepAliveIntervalSeconds,
 		observableFactory: () => new Observable((subscriber) => {
-			const collected = [];
+			const finalizer = createRunEventFinalizer();
 			let settled = false;
 			agent.runAgent(input, { onEvent: ({ event }) => {
-				collected.push(event);
+				finalizer.observe(event);
 				subscriber.next(event);
 			} }).then(() => {
-				for (const event of finalizeRunEvents(collected, { stopRequested: false })) subscriber.next(event);
+				for (const event of finalizer.finalize({ stopRequested: false })) subscriber.next(event);
 				settled = true;
 				subscriber.complete();
 			}).catch((error) => {

package/dist/v2/runtime/handlers/handle-suggest.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"handle-suggest.mjs","names":[],"sources":["../../../../src/v2/runtime/handlers/handle-suggest.ts"],"sourcesContent":["import type { AbstractAgent, BaseEvent } from \"@ag-ui/client\";\nimport { finalizeRunEvents } from \"@copilotkit/shared\";\nimport { Observable } from \"rxjs\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"./header-utils\";\nimport { cloneAgentForRequest, parseRunRequest } from \"./shared/agent-utils\";\nimport { createSseEventResponse } from \"./shared/sse-response\";\n\n/**\n * Parameters for {@link handleSuggestAgent}.\n */\ninterface SuggestAgentParameters {\n  /** The runtime whose registry the agent is resolved from. */\n  runtime: CopilotRuntimeLike;\n  /** The incoming `POST /agent/:agentId/suggest` request. */\n  request: Request;\n  /** The route-resolved agent id to run. */\n  agentId: string;\n}\n\n/**\n * Stateless suggestion run.\n *\n * Executes the provider agent **directly** and streams its AG-UI events back as\n * SSE — the same wire format as `/agent/:id/run`, so the client consumes it with\n * the stock `HttpAgent` transport and chips fill in as the provider emits them.\n * It deliberately does not go through `runtime.runner`: the runner's\n * `run()` writes to a module-level store keyed by threadId (backing the SSE\n * runtime's local thread endpoints), which would leak the throwaway suggestion\n * thread. This handler runs the agent's event pipeline **without** that\n * persistence — no thread, lock, gateway, name-gen, or run telemetry — so\n * dynamic suggestions are side-effect-free in every runtime mode.\n *\n * The only per-request configuration it applies is forwarding the request's\n * allowlisted headers (`authorization` + `x-*`) onto the agent clone. It does\n * **not** attach any request middleware — no A2UI, no MCPApps, no\n * OpenGenerativeUI, no Intelligence enterprise-learning tools. The **client**\n * (the core suggestion engine) forces `toolChoice: copilotkitSuggest` in the\n * request body; this handler does not set tool choice itself and relies on it\n * being present in the incoming `input`. Given that forced tool choice, any\n * middleware-injected tools are dead weight, and MCPApps setup can incur a\n * `listTools` network round-trip per suggestion under `available: \"always\"` — a\n * side effect this path must never pay.\n *\n * When the client aborts the HTTP request (via its `AbortController`), the\n * server-side run is cancelled best-effort so an aborted suggestion does not\n * keep running a provider call to completion.\n *\n * @param params - The runtime, request, and resolved agent id.\n * @returns A `text/event-stream` `Response` of the provider agent's AG-UI events\n *   on success, or the resolution `Response` (e.g. 404/400) when agent/body\n *   resolution fails before streaming begins.\n */\nexport async function handleSuggestAgent({\n  runtime,\n  request,\n  agentId,\n}: SuggestAgentParameters): Promise<Response> {\n  const agent = await cloneAgentForRequest(runtime, agentId, request);\n  if (agent instanceof Response) {\n    return agent;\n  }\n\n  // Carry the registry key onto the clone so any framework relying on it during\n  // the run sees the correct agentId.\n  agent.agentId = agentId;\n\n  const input = await parseRunRequest(request);\n  if (input instanceof Response) {\n    return input;\n  }\n\n  // Forward eligible inbound headers onto the clone under the runtime's resolved\n  // forwarding policy (same helper the run handler uses: `authorization` /\n  // custom `x-*`, infra/proxy/platform headers denylisted, server-set headers\n  // winning on collision — #5712). Unlike a full agent run, the suggest path\n  // intentionally attaches no middleware (see the handler docblock): the forced\n  // `copilotkitSuggest` tool choice makes any middleware-injected tools dead\n  // weight, and MCPApps setup can trigger a `listTools` network round-trip we\n  // must never incur per suggestion.\n  //\n  // `AbstractAgent` doesn't declare `headers` on its base type (concrete\n  // framework agents add it), so narrow to the header-carrying shape rather\n  // than casting to `any`.\n  const headerCarryingAgent = agent as AbstractAgent & {\n    headers?: Record<string, string>;\n  };\n  headerCarryingAgent.headers = mergeForwardableHeaders(\n    headerCarryingAgent.headers,\n    request,\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n\n  agent.setMessages(input.messages);\n  agent.setState(input.state);\n  agent.threadId = input.threadId;\n\n  // Stream the provider agent's events over SSE without persistence. This is\n  // the runner's event pipeline (`agent.runAgent({ onEvent })` + terminal-event\n  // finalization) minus the `GLOBAL_STORE` writes that would leak a thread.\n  // `captureTelemetry: false` keeps suggestions out of run telemetry; omitting\n  // `debugEventBus` keeps them out of the inspector's run trace.\n  return createSseEventResponse({\n    request,\n    agentId,\n    captureTelemetry: false,\n    observableFactory: () =>\n      new Observable<BaseEvent>((subscriber) => {\n        // Collected so `finalizeRunEvents` can append any missing terminal\n        // events (e.g. an unclosed message/tool call, or a `RUN_FINISHED`) —\n        // the same closure the runner applies — so the client sees a\n        // well-formed AG-UI sequence.\n        const collected: BaseEvent[] = [];\n        let settled = false;\n\n        void agent\n          .runAgent(input, {\n            onEvent: ({ event }) => {\n              collected.push(event);\n              subscriber.next(event);\n            },\n          })\n          .then(() => {\n            for (const event of finalizeRunEvents(collected, {\n              stopRequested: false,\n            })) {\n              subscriber.next(event);\n            }\n            settled = true;\n            subscriber.complete();\n          })\n          .catch((error: unknown) => {\n            settled = true;\n            subscriber.error(error);\n          });\n\n        // Teardown fires when the response stream is torn down (client abort /\n        // disconnect). Cancel the still-running provider call best-effort.\n        return () => {\n          if (!settled && typeof agent.abortRun === \"function\") {\n            try {\n              agent.abortRun();\n            } catch {\n              // best-effort — nothing actionable if aborting the run fails.\n            }\n          }\n        };\n      }),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,eAAsB,mBAAmB,EACvC,SACA,SACA,WAC4C;CAC5C,MAAM,QAAQ,MAAM,qBAAqB,SAAS,SAAS,QAAQ;AACnE,KAAI,iBAAiB,SACnB,QAAO;AAKT,OAAM,UAAU;CAEhB,MAAM,QAAQ,MAAM,gBAAgB,QAAQ;AAC5C,KAAI,iBAAiB,SACnB,QAAO;CAeT,MAAM,sBAAsB;AAG5B,qBAAoB,UAAU,wBAC5B,oBAAoB,SACpB,SACA,QAAQ,wBAAwB,4BAA4B,OAAU,CACvE;AAED,OAAM,YAAY,MAAM,SAAS;AACjC,OAAM,SAAS,MAAM,MAAM;AAC3B,OAAM,WAAW,MAAM;AAOvB,QAAO,uBAAuB;EAC5B;EACA;EACA,kBAAkB;EAClB,yBACE,IAAI,YAAuB,eAAe;GAKxC,MAAM,YAAyB,EAAE;GACjC,IAAI,UAAU;AAEd,GAAK,MACF,SAAS,OAAO,EACf,UAAU,EAAE,YAAY;AACtB,cAAU,KAAK,MAAM;AACrB,eAAW,KAAK,MAAM;MAEzB,CAAC,CACD,WAAW;AACV,SAAK,MAAM,SAAS,kBAAkB,WAAW,EAC/C,eAAe,OAChB,CAAC,CACA,YAAW,KAAK,MAAM;AAExB,cAAU;AACV,eAAW,UAAU;KACrB,CACD,OAAO,UAAmB;AACzB,cAAU;AACV,eAAW,MAAM,MAAM;KACvB;AAIJ,gBAAa;AACX,QAAI,CAAC,WAAW,OAAO,MAAM,aAAa,WACxC,KAAI;AACF,WAAM,UAAU;YACV;;IAKZ;EACL,CAAC"}
+{"version":3,"file":"handle-suggest.mjs","names":[],"sources":["../../../../src/v2/runtime/handlers/handle-suggest.ts"],"sourcesContent":["import type { AbstractAgent, BaseEvent } from \"@ag-ui/client\";\nimport { createRunEventFinalizer } from \"@copilotkit/shared\";\nimport { Observable } from \"rxjs\";\nimport type { CopilotRuntimeLike } from \"../core/runtime\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"./header-utils\";\nimport { cloneAgentForRequest, parseRunRequest } from \"./shared/agent-utils\";\nimport { createSseEventResponse } from \"./shared/sse-response\";\n\n/**\n * Parameters for {@link handleSuggestAgent}.\n */\ninterface SuggestAgentParameters {\n  /** The runtime whose registry the agent is resolved from. */\n  runtime: CopilotRuntimeLike;\n  /** The incoming `POST /agent/:agentId/suggest` request. */\n  request: Request;\n  /** The route-resolved agent id to run. */\n  agentId: string;\n}\n\n/**\n * Stateless suggestion run.\n *\n * Executes the provider agent **directly** and streams its AG-UI events back as\n * SSE — the same wire format as `/agent/:id/run`, so the client consumes it with\n * the stock `HttpAgent` transport and chips fill in as the provider emits them.\n * It deliberately does not go through `runtime.runner`: the runner's\n * `run()` writes to a module-level store keyed by threadId (backing the SSE\n * runtime's local thread endpoints), which would leak the throwaway suggestion\n * thread. This handler runs the agent's event pipeline **without** that\n * persistence — no thread, lock, gateway, name-gen, or run telemetry — so\n * dynamic suggestions are side-effect-free in every runtime mode.\n *\n * The only per-request configuration it applies is forwarding the request's\n * allowlisted headers (`authorization` + `x-*`) onto the agent clone. It does\n * **not** attach any request middleware — no A2UI, no MCPApps, no\n * OpenGenerativeUI, no Intelligence enterprise-learning tools. The **client**\n * (the core suggestion engine) forces `toolChoice: copilotkitSuggest` in the\n * request body; this handler does not set tool choice itself and relies on it\n * being present in the incoming `input`. Given that forced tool choice, any\n * middleware-injected tools are dead weight, and MCPApps setup can incur a\n * `listTools` network round-trip per suggestion under `available: \"always\"` — a\n * side effect this path must never pay.\n *\n * When the client aborts the HTTP request (via its `AbortController`), the\n * server-side run is cancelled best-effort so an aborted suggestion does not\n * keep running a provider call to completion.\n *\n * @param params - The runtime, request, and resolved agent id.\n * @returns A `text/event-stream` `Response` of the provider agent's AG-UI events\n *   on success, or the resolution `Response` (e.g. 404/400) when agent/body\n *   resolution fails before streaming begins.\n */\nexport async function handleSuggestAgent({\n  runtime,\n  request,\n  agentId,\n}: SuggestAgentParameters): Promise<Response> {\n  const agent = await cloneAgentForRequest(runtime, agentId, request);\n  if (agent instanceof Response) {\n    return agent;\n  }\n\n  // Carry the registry key onto the clone so any framework relying on it during\n  // the run sees the correct agentId.\n  agent.agentId = agentId;\n\n  const input = await parseRunRequest(request);\n  if (input instanceof Response) {\n    return input;\n  }\n\n  // Forward eligible inbound headers onto the clone under the runtime's resolved\n  // forwarding policy (same helper the run handler uses: `authorization` /\n  // custom `x-*`, infra/proxy/platform headers denylisted, server-set headers\n  // winning on collision — #5712). Unlike a full agent run, the suggest path\n  // intentionally attaches no middleware (see the handler docblock): the forced\n  // `copilotkitSuggest` tool choice makes any middleware-injected tools dead\n  // weight, and MCPApps setup can trigger a `listTools` network round-trip we\n  // must never incur per suggestion.\n  //\n  // `AbstractAgent` doesn't declare `headers` on its base type (concrete\n  // framework agents add it), so narrow to the header-carrying shape rather\n  // than casting to `any`.\n  const headerCarryingAgent = agent as AbstractAgent & {\n    headers?: Record<string, string>;\n  };\n  headerCarryingAgent.headers = mergeForwardableHeaders(\n    headerCarryingAgent.headers,\n    request,\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n\n  agent.setMessages(input.messages);\n  agent.setState(input.state);\n  agent.threadId = input.threadId;\n\n  // Stream the provider agent's events over SSE without persistence. This is\n  // the runner's event pipeline (`agent.runAgent({ onEvent })` + terminal-event\n  // finalization) minus the `GLOBAL_STORE` writes that would leak a thread.\n  // `captureTelemetry: false` keeps suggestions out of run telemetry; omitting\n  // `debugEventBus` keeps them out of the inspector's run trace.\n  return createSseEventResponse({\n    request,\n    agentId,\n    captureTelemetry: false,\n    keepAliveIntervalSeconds: runtime.sseKeepAliveIntervalSeconds,\n    observableFactory: () =>\n      new Observable<BaseEvent>((subscriber) => {\n        // Tracks open message/tool lifecycles so the missing terminal events\n        // (an unclosed message/tool call, or a `RUN_FINISHED`) can be appended\n        // — the same closure the runner applies — so the client sees a\n        // well-formed AG-UI sequence. Nothing is persisted here, so only the\n        // open ids are kept, never the streamed events themselves.\n        const finalizer = createRunEventFinalizer();\n        let settled = false;\n\n        void agent\n          .runAgent(input, {\n            onEvent: ({ event }) => {\n              finalizer.observe(event);\n              subscriber.next(event);\n            },\n          })\n          .then(() => {\n            for (const event of finalizer.finalize({ stopRequested: false })) {\n              subscriber.next(event);\n            }\n            settled = true;\n            subscriber.complete();\n          })\n          .catch((error: unknown) => {\n            settled = true;\n            subscriber.error(error);\n          });\n\n        // Teardown fires when the response stream is torn down (client abort /\n        // disconnect). Cancel the still-running provider call best-effort.\n        return () => {\n          if (!settled && typeof agent.abortRun === \"function\") {\n            try {\n              agent.abortRun();\n            } catch {\n              // best-effort — nothing actionable if aborting the run fails.\n            }\n          }\n        };\n      }),\n  });\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAwDA,eAAsB,mBAAmB,EACvC,SACA,SACA,WAC4C;CAC5C,MAAM,QAAQ,MAAM,qBAAqB,SAAS,SAAS,QAAQ;AACnE,KAAI,iBAAiB,SACnB,QAAO;AAKT,OAAM,UAAU;CAEhB,MAAM,QAAQ,MAAM,gBAAgB,QAAQ;AAC5C,KAAI,iBAAiB,SACnB,QAAO;CAeT,MAAM,sBAAsB;AAG5B,qBAAoB,UAAU,wBAC5B,oBAAoB,SACpB,SACA,QAAQ,wBAAwB,4BAA4B,OAAU,CACvE;AAED,OAAM,YAAY,MAAM,SAAS;AACjC,OAAM,SAAS,MAAM,MAAM;AAC3B,OAAM,WAAW,MAAM;AAOvB,QAAO,uBAAuB;EAC5B;EACA;EACA,kBAAkB;EAClB,0BAA0B,QAAQ;EAClC,yBACE,IAAI,YAAuB,eAAe;GAMxC,MAAM,YAAY,yBAAyB;GAC3C,IAAI,UAAU;AAEd,GAAK,MACF,SAAS,OAAO,EACf,UAAU,EAAE,YAAY;AACtB,cAAU,QAAQ,MAAM;AACxB,eAAW,KAAK,MAAM;MAEzB,CAAC,CACD,WAAW;AACV,SAAK,MAAM,SAAS,UAAU,SAAS,EAAE,eAAe,OAAO,CAAC,CAC9D,YAAW,KAAK,MAAM;AAExB,cAAU;AACV,eAAW,UAAU;KACrB,CACD,OAAO,UAAmB;AACzB,cAAU;AACV,eAAW,MAAM,MAAM;KACvB;AAIJ,gBAAa;AACX,QAAI,CAAC,WAAW,OAAO,MAAM,aAAa,WACxC,KAAI;AACF,WAAM,UAAU;YACV;;IAKZ;EACL,CAAC"}

package/dist/v2/runtime/handlers/shared/agent-utils.cjs

@@ -3,7 +3,6 @@ const require_runtime = require('../../../../_virtual/_rolldown/runtime.cjs');
 const require_header_utils = require('../header-utils.cjs');
 const require_runtime$1 = require('../../core/runtime.cjs');
 const require_client = require('../../intelligence-platform/client.cjs');
-const require_open_generative_ui_middleware = require('../../open-generative-ui-middleware.cjs');
 const require_mcp_apps_servers = require('./mcp-apps-servers.cjs');
 const require_json_response = require('./json-response.cjs');
 const require_resolve_intelligence_user = require('./resolve-intelligence-user.cjs');
@@ -11,7 +10,7 @@ const require_memory_policy = require('./memory-policy.cjs');
 let _copilotkit_shared = require("@copilotkit/shared");
 let _ag_ui_client = require("@ag-ui/client");
 let _ag_ui_mcp_middleware = require("@ag-ui/mcp-middleware");
-let _ag_ui_a2ui_middleware = require("@ag-ui/a2ui-middleware");
+let _copilotkit_shared_event_transforms = require("@copilotkit/shared/event-transforms");
 let _ag_ui_mcp_apps_middleware = require("@ag-ui/mcp-apps-middleware");
 
 //#region src/v2/runtime/handlers/shared/agent-utils.ts
@@ -48,7 +47,7 @@ function configureAgentForRequest(params) {
 	const a2uiEnabledByCatalog = !!providerA2UIHasCatalog && runtime.a2ui?.enabled !== false;
 	if (require_runtime$1.isA2UIEnabled(runtime.a2ui) || a2uiEnabledByCatalog) {
 		const { agents: targetAgents, enabled: _enabled, injectA2UITool, ...a2uiOptions } = runtime.a2ui ?? {};
-		if ((!targetAgents || targetAgents.includes(agentId)) && typeof agent.use === "function") agent.use(new _ag_ui_a2ui_middleware.A2UIMiddleware({
+		if ((!targetAgents || targetAgents.includes(agentId)) && typeof agent.use === "function") agent.use(new _copilotkit_shared_event_transforms.A2UIMiddleware({
 			...a2uiOptions,
 			injectA2UITool: injectA2UITool ?? (providerA2UIHasCatalog ? true : void 0)
 		}));
@@ -66,7 +65,7 @@ function configureAgentForRequest(params) {
 	if (runtime.openGenerativeUI) {
 		const config = runtime.openGenerativeUI;
 		const targetAgents = typeof config === "object" ? config.agents : void 0;
-		if ((!targetAgents || targetAgents.includes(agentId)) && typeof agent.use === "function") agent.use(new require_open_generative_ui_middleware.OpenGenerativeUIMiddleware());
+		if ((!targetAgents || targetAgents.includes(agentId)) && typeof agent.use === "function") agent.use(new _copilotkit_shared_event_transforms.OpenGenerativeUIMiddleware());
 	}
 	agent.headers = require_header_utils.mergeForwardableHeaders(agent.headers, request, runtime.forwardHeadersPolicy ?? require_header_utils.resolveForwardHeadersPolicy(void 0));
 }

package/dist/v2/runtime/handlers/shared/agent-utils.cjs.map

@@ -1 +1 @@
-{"version":3,"file":"agent-utils.cjs","names":["resolveAgents","isA2UIEnabled","A2UIMiddleware","isIntelligenceRuntime","resolveMcpAppsServers","MCPAppsMiddleware","OpenGenerativeUIMiddleware","mergeForwardableHeaders","resolveForwardHeadersPolicy","errorResponse","resolveIntelligenceUser","resolveWebMemory","MCPMiddleware","INTELLIGENCE_USER_ID_HEADER","INTELLIGENCE_MEMORY_GRANT_HEADER","RunAgentInputSchema"],"sources":["../../../../../src/v2/runtime/handlers/shared/agent-utils.ts"],"sourcesContent":["import type { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { RunAgentInputSchema } from \"@ag-ui/client\";\nimport { A2UIMiddleware } from \"@ag-ui/a2ui-middleware\";\nimport { MCPAppsMiddleware } from \"@ag-ui/mcp-apps-middleware\";\nimport { MCPMiddleware } from \"@ag-ui/mcp-middleware\";\nimport type { CopilotRuntimeLike } from \"../../core/runtime\";\nimport {\n  isA2UIEnabled,\n  isIntelligenceRuntime,\n  resolveAgents,\n} from \"../../core/runtime\";\nimport { OpenGenerativeUIMiddleware } from \"../../open-generative-ui-middleware\";\nimport {\n  INTELLIGENCE_MEMORY_GRANT_HEADER,\n  INTELLIGENCE_USER_ID_HEADER,\n} from \"../../intelligence-platform/client\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"../header-utils\";\nimport { resolveMcpAppsServers } from \"./mcp-apps-servers\";\nimport { resolveIntelligenceUser } from \"./resolve-intelligence-user\";\nimport { resolveWebMemory } from \"./memory-policy\";\nimport { errorResponse } from \"./json-response\";\nimport { logger } from \"@copilotkit/shared\";\n\ntype MiddlewareCapableAgent = AbstractAgent & {\n  use?: (middleware: unknown) => void;\n  headers?: Record<string, string>;\n};\n\nexport interface RunAgentParameters {\n  request: Request;\n  runtime: CopilotRuntimeLike;\n  agentId: string;\n}\n\nexport interface ConnectRequestBody extends RunAgentInput {\n  lastSeenEventId?: string | null;\n}\n\n/**\n * Resolve `agentId` against the runtime's agents and return a per-request\n * clone of the matching agent.\n *\n * Dual return contract — both callers (`handle-run.ts`, `handle-connect.ts`)\n * depend on it:\n * - Returns a cloned `AbstractAgent` when the agent exists.\n * - Returns a 404 `Response` (`{ error: \"Agent not found\", ... }`) when the\n *   agent is unknown. Callers MUST `instanceof Response`-check the result and\n *   return it directly; this doubles as the connect/run path's agent-existence\n *   guard, so skipping the check would let unknown agent ids slip through.\n *\n * The clone is what subsequent per-request mutation (middleware attach,\n * `agent.headers` merge) operates on, leaving the shared agent registration\n * untouched.\n */\nexport async function cloneAgentForRequest(\n  runtime: CopilotRuntimeLike,\n  agentId: string,\n  request?: Request,\n): Promise<AbstractAgent | Response> {\n  const agents = await resolveAgents(runtime.agents, request);\n\n  if (!agents[agentId]) {\n    return new Response(\n      JSON.stringify({\n        error: \"Agent not found\",\n        message: `Agent '${agentId}' does not exist`,\n      }),\n      {\n        status: 404,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n\n  return (agents[agentId] as AbstractAgent).clone() as AbstractAgent;\n}\n\nexport function configureAgentForRequest(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agentId: string;\n  agent: AbstractAgent;\n  /**\n   * True when the React provider was given an A2UI catalog\n   * (`<CopilotKit a2ui={{ catalog }}>`), forwarded per-run. A catalog alone is\n   * enough to enable A2UI and inject the render tool — the developer no longer\n   * has to also set `a2ui.injectA2UITool` on the runtime.\n   */\n  providerA2UIHasCatalog?: boolean;\n  /** Retain proxy rejection even when no server is available to this agent. */\n  isMcpProxyRequest?: boolean;\n}): void {\n  const {\n    runtime,\n    request,\n    agentId,\n    providerA2UIHasCatalog,\n    isMcpProxyRequest,\n  } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  // A2UI is on when the runtime explicitly enables it, OR when the provider\n  // forwarded a catalog — but an explicit `enabled: false` always wins (we\n  // provide a quick default, never override a deeper opt-out).\n  const a2uiEnabledByCatalog =\n    !!providerA2UIHasCatalog && runtime.a2ui?.enabled !== false;\n\n  if (isA2UIEnabled(runtime.a2ui) || a2uiEnabledByCatalog) {\n    // `enabled` is a CopilotKit-level switch, not an A2UIMiddleware option —\n    // drop it (alongside the agent filter) before forwarding to the middleware.\n    const {\n      agents: targetAgents,\n      enabled: _enabled,\n      injectA2UITool,\n      ...a2uiOptions\n    } = runtime.a2ui ?? {};\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(\n        new A2UIMiddleware({\n          ...a2uiOptions,\n          // Default render-tool injection on when a catalog is present and the\n          // developer hasn't set it explicitly. `??` means an explicit value\n          // (including `false`) is always respected.\n          injectA2UITool:\n            injectA2UITool ?? (providerA2UIHasCatalog ? true : undefined),\n        }),\n      );\n    }\n  }\n\n  if (isIntelligenceRuntime(runtime) && typeof agent.use === \"function\") {\n    // Ordinary runs need no middleware without selected servers. Proxy requests\n    // still need the upstream guard so they cannot fall through to the model.\n    const mcpServers = resolveMcpAppsServers(\n      runtime.mcpApps?.servers ?? [],\n      agentId,\n    );\n    if (mcpServers.length > 0 || isMcpProxyRequest) {\n      agent.use(\n        new MCPAppsMiddleware({ mcpServers, discoveryFailureMode: \"throw\" }),\n      );\n    }\n  } else if (runtime.mcpApps?.servers?.length) {\n    const mcpServers = resolveMcpAppsServers(runtime.mcpApps.servers, agentId);\n\n    if (mcpServers.length > 0 && typeof agent.use === \"function\") {\n      agent.use(new MCPAppsMiddleware({ mcpServers }));\n    }\n  }\n\n  if (runtime.openGenerativeUI) {\n    const config = runtime.openGenerativeUI;\n    const targetAgents = typeof config === \"object\" ? config.agents : undefined;\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(new OpenGenerativeUIMiddleware());\n    }\n  }\n\n  // Forward eligible inbound headers onto the outgoing agent call under the\n  // runtime's resolved forwarding policy (`authorization` / custom `x-*`, with\n  // known infra/proxy/platform headers stripped by the default denylist —\n  // #5712), but let headers the server explicitly configured on the agent WIN\n  // on collision (case-insensitively): a server-set service-to-service token\n  // (e.g. an IAM bearer) must never be silently overridden by a\n  // browser/edge/platform-injected inbound header. See `mergeForwardableHeaders`\n  // for the casing/duplicate-key rationale and `shouldForwardHeader` for breadth.\n  agent.headers = mergeForwardableHeaders(\n    agent.headers,\n    request,\n    // `forwardHeadersPolicy` is optional on the published `CopilotRuntimeLike`\n    // interface (non-breaking minor release). Concrete runtimes always set it;\n    // a policy-less external implementor falls back to the default resolved\n    // policy (default-on denylist) so behavior stays identical and never derefs\n    // undefined.\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n}\n\n/**\n * Attach CopilotKit Intelligence's MCP tools to the agent run when\n * `CopilotKitIntelligence` was constructed with\n * `enableEnterpriseLearning: true`. Uses `@ag-ui/mcp-middleware`, so the\n * tools are available uniformly across agent frameworks (not just\n * `BuiltInAgent`).\n *\n * The middleware sits on a per-request agent clone, so the per-request\n * auth (Bearer apiKey + resolved user-id) is baked into the transport\n * headers at attach time. If user resolution fails, attachment is\n * skipped silently — the intelligence run handler will reject the\n * request with the same error. Note this means `identifyUser` is\n * resolved twice per learning-enabled run (here and in the run handler);\n * the callback is expected to be idempotent and side-effect-free.\n *\n * Intentionally split out from `configureAgentForRequest`: this is only\n * relevant to actual agent runs, not auxiliary flows like thread-name\n * generation (which has no need for MCP tools and shouldn't pay the\n * `listTools` round-trip).\n */\nexport async function attachIntelligenceEnterpriseLearning(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n}): Promise<void | Response> {\n  const { runtime, request } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  if (\n    !isIntelligenceRuntime(runtime) ||\n    (runtime.memory === undefined &&\n      !runtime.intelligence?.ɵisEnterpriseLearningEnabled?.())\n  ) {\n    return;\n  }\n\n  // Enterprise learning is enabled, but this agent's framework can't take\n  // middleware — surface it rather than silently shipping a run with none\n  // of the tools the operator opted into.\n  if (typeof agent.use !== \"function\") {\n    if (runtime.memory) {\n      return errorResponse(\n        \"Memory is configured, but this agent does not support middleware\",\n        500,\n      );\n    }\n    logger.warn(\n      \"CopilotKitIntelligence.enableEnterpriseLearning is enabled, but the agent \" +\n        \"does not support middleware (no `.use()` method); Intelligence tools were \" +\n        \"not attached for this run.\",\n    );\n    return;\n  }\n\n  const userResult = await resolveIntelligenceUser({ runtime, request });\n  if (userResult instanceof Response) return userResult;\n  const access = await resolveWebMemory(runtime, request, userResult, \"agent\");\n  if (access instanceof Response) return access;\n\n  agent.use(\n    new MCPMiddleware([\n      {\n        type: \"http\",\n        url: `${runtime.intelligence.ɵgetApiUrl()}/mcp`,\n        serverId: \"intelligence\",\n        headers: {\n          Authorization: `Bearer ${runtime.intelligence.ɵgetApiKey()}`,\n          [INTELLIGENCE_USER_ID_HEADER]: userResult.id,\n          ...(runtime.memory\n            ? {\n                [INTELLIGENCE_MEMORY_GRANT_HEADER]: JSON.stringify(\n                  access.grant,\n                ),\n              }\n            : {}),\n        },\n      },\n    ]),\n  );\n}\n\nexport async function parseRunRequest(\n  request: Request,\n): Promise<RunAgentInput | Response> {\n  try {\n    const requestBody = await request.json();\n    return RunAgentInputSchema.parse(requestBody);\n  } catch (error) {\n    logger.error(\"Invalid run request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n\nexport async function parseConnectRequest(request: Request): Promise<\n  | Response\n  | {\n      input: RunAgentInput;\n      lastSeenEventId: string | null;\n    }\n> {\n  try {\n    const requestBody = await request.json();\n    const input = RunAgentInputSchema.parse(requestBody);\n    let lastSeenEventId: string | null = null;\n\n    if (\n      \"lastSeenEventId\" in (requestBody as Record<string, unknown>) &&\n      (typeof (requestBody as Record<string, unknown>).lastSeenEventId ===\n        \"string\" ||\n        (requestBody as Record<string, unknown>).lastSeenEventId === null)\n    ) {\n      lastSeenEventId =\n        (requestBody as ConnectRequestBody).lastSeenEventId ?? null;\n    }\n\n    return { input, lastSeenEventId };\n  } catch (error) {\n    logger.error(\"Invalid connect request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n"],"mappings":"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"}
+{"version":3,"file":"agent-utils.cjs","names":["resolveAgents","isA2UIEnabled","A2UIMiddleware","isIntelligenceRuntime","resolveMcpAppsServers","MCPAppsMiddleware","OpenGenerativeUIMiddleware","mergeForwardableHeaders","resolveForwardHeadersPolicy","errorResponse","resolveIntelligenceUser","resolveWebMemory","MCPMiddleware","INTELLIGENCE_USER_ID_HEADER","INTELLIGENCE_MEMORY_GRANT_HEADER","RunAgentInputSchema"],"sources":["../../../../../src/v2/runtime/handlers/shared/agent-utils.ts"],"sourcesContent":["import type { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { RunAgentInputSchema } from \"@ag-ui/client\";\nimport {\n  A2UIMiddleware,\n  OpenGenerativeUIMiddleware,\n} from \"@copilotkit/shared/event-transforms\";\nimport { MCPAppsMiddleware } from \"@ag-ui/mcp-apps-middleware\";\nimport { MCPMiddleware } from \"@ag-ui/mcp-middleware\";\nimport type { CopilotRuntimeLike } from \"../../core/runtime\";\nimport {\n  isA2UIEnabled,\n  isIntelligenceRuntime,\n  resolveAgents,\n} from \"../../core/runtime\";\nimport {\n  INTELLIGENCE_MEMORY_GRANT_HEADER,\n  INTELLIGENCE_USER_ID_HEADER,\n} from \"../../intelligence-platform/client\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"../header-utils\";\nimport { resolveMcpAppsServers } from \"./mcp-apps-servers\";\nimport { resolveIntelligenceUser } from \"./resolve-intelligence-user\";\nimport { resolveWebMemory } from \"./memory-policy\";\nimport { errorResponse } from \"./json-response\";\nimport { logger } from \"@copilotkit/shared\";\n\ntype MiddlewareCapableAgent = AbstractAgent & {\n  use?: (middleware: unknown) => void;\n  headers?: Record<string, string>;\n};\n\nexport interface RunAgentParameters {\n  request: Request;\n  runtime: CopilotRuntimeLike;\n  agentId: string;\n}\n\nexport interface ConnectRequestBody extends RunAgentInput {\n  lastSeenEventId?: string | null;\n}\n\n/**\n * Resolve `agentId` against the runtime's agents and return a per-request\n * clone of the matching agent.\n *\n * Dual return contract — both callers (`handle-run.ts`, `handle-connect.ts`)\n * depend on it:\n * - Returns a cloned `AbstractAgent` when the agent exists.\n * - Returns a 404 `Response` (`{ error: \"Agent not found\", ... }`) when the\n *   agent is unknown. Callers MUST `instanceof Response`-check the result and\n *   return it directly; this doubles as the connect/run path's agent-existence\n *   guard, so skipping the check would let unknown agent ids slip through.\n *\n * The clone is what subsequent per-request mutation (middleware attach,\n * `agent.headers` merge) operates on, leaving the shared agent registration\n * untouched.\n */\nexport async function cloneAgentForRequest(\n  runtime: CopilotRuntimeLike,\n  agentId: string,\n  request?: Request,\n): Promise<AbstractAgent | Response> {\n  const agents = await resolveAgents(runtime.agents, request);\n\n  if (!agents[agentId]) {\n    return new Response(\n      JSON.stringify({\n        error: \"Agent not found\",\n        message: `Agent '${agentId}' does not exist`,\n      }),\n      {\n        status: 404,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n\n  return (agents[agentId] as AbstractAgent).clone() as AbstractAgent;\n}\n\nexport function configureAgentForRequest(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agentId: string;\n  agent: AbstractAgent;\n  /**\n   * True when the React provider was given an A2UI catalog\n   * (`<CopilotKit a2ui={{ catalog }}>`), forwarded per-run. A catalog alone is\n   * enough to enable A2UI and inject the render tool — the developer no longer\n   * has to also set `a2ui.injectA2UITool` on the runtime.\n   */\n  providerA2UIHasCatalog?: boolean;\n  /** Retain proxy rejection even when no server is available to this agent. */\n  isMcpProxyRequest?: boolean;\n}): void {\n  const {\n    runtime,\n    request,\n    agentId,\n    providerA2UIHasCatalog,\n    isMcpProxyRequest,\n  } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  // A2UI is on when the runtime explicitly enables it, OR when the provider\n  // forwarded a catalog — but an explicit `enabled: false` always wins (we\n  // provide a quick default, never override a deeper opt-out).\n  const a2uiEnabledByCatalog =\n    !!providerA2UIHasCatalog && runtime.a2ui?.enabled !== false;\n\n  if (isA2UIEnabled(runtime.a2ui) || a2uiEnabledByCatalog) {\n    // `enabled` is a CopilotKit-level switch, not an A2UIMiddleware option —\n    // drop it (alongside the agent filter) before forwarding to the middleware.\n    const {\n      agents: targetAgents,\n      enabled: _enabled,\n      injectA2UITool,\n      ...a2uiOptions\n    } = runtime.a2ui ?? {};\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(\n        new A2UIMiddleware({\n          ...a2uiOptions,\n          // Default render-tool injection on when a catalog is present and the\n          // developer hasn't set it explicitly. `??` means an explicit value\n          // (including `false`) is always respected.\n          injectA2UITool:\n            injectA2UITool ?? (providerA2UIHasCatalog ? true : undefined),\n        }),\n      );\n    }\n  }\n\n  if (isIntelligenceRuntime(runtime) && typeof agent.use === \"function\") {\n    // Ordinary runs need no middleware without selected servers. Proxy requests\n    // still need the upstream guard so they cannot fall through to the model.\n    const mcpServers = resolveMcpAppsServers(\n      runtime.mcpApps?.servers ?? [],\n      agentId,\n    );\n    if (mcpServers.length > 0 || isMcpProxyRequest) {\n      agent.use(\n        new MCPAppsMiddleware({ mcpServers, discoveryFailureMode: \"throw\" }),\n      );\n    }\n  } else if (runtime.mcpApps?.servers?.length) {\n    const mcpServers = resolveMcpAppsServers(runtime.mcpApps.servers, agentId);\n\n    if (mcpServers.length > 0 && typeof agent.use === \"function\") {\n      agent.use(new MCPAppsMiddleware({ mcpServers }));\n    }\n  }\n\n  if (runtime.openGenerativeUI) {\n    const config = runtime.openGenerativeUI;\n    const targetAgents = typeof config === \"object\" ? config.agents : undefined;\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(new OpenGenerativeUIMiddleware());\n    }\n  }\n\n  // Forward eligible inbound headers onto the outgoing agent call under the\n  // runtime's resolved forwarding policy (`authorization` / custom `x-*`, with\n  // known infra/proxy/platform headers stripped by the default denylist —\n  // #5712), but let headers the server explicitly configured on the agent WIN\n  // on collision (case-insensitively): a server-set service-to-service token\n  // (e.g. an IAM bearer) must never be silently overridden by a\n  // browser/edge/platform-injected inbound header. See `mergeForwardableHeaders`\n  // for the casing/duplicate-key rationale and `shouldForwardHeader` for breadth.\n  agent.headers = mergeForwardableHeaders(\n    agent.headers,\n    request,\n    // `forwardHeadersPolicy` is optional on the published `CopilotRuntimeLike`\n    // interface (non-breaking minor release). Concrete runtimes always set it;\n    // a policy-less external implementor falls back to the default resolved\n    // policy (default-on denylist) so behavior stays identical and never derefs\n    // undefined.\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n}\n\n/**\n * Attach CopilotKit Intelligence's MCP tools to the agent run when\n * `CopilotKitIntelligence` was constructed with\n * `enableEnterpriseLearning: true`. Uses `@ag-ui/mcp-middleware`, so the\n * tools are available uniformly across agent frameworks (not just\n * `BuiltInAgent`).\n *\n * The middleware sits on a per-request agent clone, so the per-request\n * auth (Bearer apiKey + resolved user-id) is baked into the transport\n * headers at attach time. If user resolution fails, attachment is\n * skipped silently — the intelligence run handler will reject the\n * request with the same error. Note this means `identifyUser` is\n * resolved twice per learning-enabled run (here and in the run handler);\n * the callback is expected to be idempotent and side-effect-free.\n *\n * Intentionally split out from `configureAgentForRequest`: this is only\n * relevant to actual agent runs, not auxiliary flows like thread-name\n * generation (which has no need for MCP tools and shouldn't pay the\n * `listTools` round-trip).\n */\nexport async function attachIntelligenceEnterpriseLearning(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n}): Promise<void | Response> {\n  const { runtime, request } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  if (\n    !isIntelligenceRuntime(runtime) ||\n    (runtime.memory === undefined &&\n      !runtime.intelligence?.ɵisEnterpriseLearningEnabled?.())\n  ) {\n    return;\n  }\n\n  // Enterprise learning is enabled, but this agent's framework can't take\n  // middleware — surface it rather than silently shipping a run with none\n  // of the tools the operator opted into.\n  if (typeof agent.use !== \"function\") {\n    if (runtime.memory) {\n      return errorResponse(\n        \"Memory is configured, but this agent does not support middleware\",\n        500,\n      );\n    }\n    logger.warn(\n      \"CopilotKitIntelligence.enableEnterpriseLearning is enabled, but the agent \" +\n        \"does not support middleware (no `.use()` method); Intelligence tools were \" +\n        \"not attached for this run.\",\n    );\n    return;\n  }\n\n  const userResult = await resolveIntelligenceUser({ runtime, request });\n  if (userResult instanceof Response) return userResult;\n  const access = await resolveWebMemory(runtime, request, userResult, \"agent\");\n  if (access instanceof Response) return access;\n\n  agent.use(\n    new MCPMiddleware([\n      {\n        type: \"http\",\n        url: `${runtime.intelligence.ɵgetApiUrl()}/mcp`,\n        serverId: \"intelligence\",\n        headers: {\n          Authorization: `Bearer ${runtime.intelligence.ɵgetApiKey()}`,\n          [INTELLIGENCE_USER_ID_HEADER]: userResult.id,\n          ...(runtime.memory\n            ? {\n                [INTELLIGENCE_MEMORY_GRANT_HEADER]: JSON.stringify(\n                  access.grant,\n                ),\n              }\n            : {}),\n        },\n      },\n    ]),\n  );\n}\n\nexport async function parseRunRequest(\n  request: Request,\n): Promise<RunAgentInput | Response> {\n  try {\n    const requestBody = await request.json();\n    return RunAgentInputSchema.parse(requestBody);\n  } catch (error) {\n    logger.error(\"Invalid run request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n\nexport async function parseConnectRequest(request: Request): Promise<\n  | Response\n  | {\n      input: RunAgentInput;\n      lastSeenEventId: string | null;\n    }\n> {\n  try {\n    const requestBody = await request.json();\n    const input = RunAgentInputSchema.parse(requestBody);\n    let lastSeenEventId: string | null = null;\n\n    if (\n      \"lastSeenEventId\" in (requestBody as Record<string, unknown>) &&\n      (typeof (requestBody as Record<string, unknown>).lastSeenEventId ===\n        \"string\" ||\n        (requestBody as Record<string, unknown>).lastSeenEventId === null)\n    ) {\n      lastSeenEventId =\n        (requestBody as ConnectRequestBody).lastSeenEventId ?? null;\n    }\n\n    return { input, lastSeenEventId };\n  } catch (error) {\n    logger.error(\"Invalid connect request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/v2/runtime/handlers/shared/agent-utils.mjs

@@ -2,7 +2,6 @@ import "reflect-metadata";
 import { mergeForwardableHeaders, resolveForwardHeadersPolicy } from "../header-utils.mjs";
 import { isA2UIEnabled, isIntelligenceRuntime, resolveAgents } from "../../core/runtime.mjs";
 import { INTELLIGENCE_MEMORY_GRANT_HEADER, INTELLIGENCE_USER_ID_HEADER } from "../../intelligence-platform/client.mjs";
-import { OpenGenerativeUIMiddleware } from "../../open-generative-ui-middleware.mjs";
 import { resolveMcpAppsServers } from "./mcp-apps-servers.mjs";
 import { errorResponse } from "./json-response.mjs";
 import { resolveIntelligenceUser } from "./resolve-intelligence-user.mjs";
@@ -10,7 +9,7 @@ import { resolveWebMemory } from "./memory-policy.mjs";
 import { logger } from "@copilotkit/shared";
 import { RunAgentInputSchema } from "@ag-ui/client";
 import { MCPMiddleware } from "@ag-ui/mcp-middleware";
-import { A2UIMiddleware } from "@ag-ui/a2ui-middleware";
+import { A2UIMiddleware, OpenGenerativeUIMiddleware } from "@copilotkit/shared/event-transforms";
 import { MCPAppsMiddleware } from "@ag-ui/mcp-apps-middleware";
 
 //#region src/v2/runtime/handlers/shared/agent-utils.ts

package/dist/v2/runtime/handlers/shared/agent-utils.mjs.map

@@ -1 +1 @@
-{"version":3,"file":"agent-utils.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/shared/agent-utils.ts"],"sourcesContent":["import type { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { RunAgentInputSchema } from \"@ag-ui/client\";\nimport { A2UIMiddleware } from \"@ag-ui/a2ui-middleware\";\nimport { MCPAppsMiddleware } from \"@ag-ui/mcp-apps-middleware\";\nimport { MCPMiddleware } from \"@ag-ui/mcp-middleware\";\nimport type { CopilotRuntimeLike } from \"../../core/runtime\";\nimport {\n  isA2UIEnabled,\n  isIntelligenceRuntime,\n  resolveAgents,\n} from \"../../core/runtime\";\nimport { OpenGenerativeUIMiddleware } from \"../../open-generative-ui-middleware\";\nimport {\n  INTELLIGENCE_MEMORY_GRANT_HEADER,\n  INTELLIGENCE_USER_ID_HEADER,\n} from \"../../intelligence-platform/client\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"../header-utils\";\nimport { resolveMcpAppsServers } from \"./mcp-apps-servers\";\nimport { resolveIntelligenceUser } from \"./resolve-intelligence-user\";\nimport { resolveWebMemory } from \"./memory-policy\";\nimport { errorResponse } from \"./json-response\";\nimport { logger } from \"@copilotkit/shared\";\n\ntype MiddlewareCapableAgent = AbstractAgent & {\n  use?: (middleware: unknown) => void;\n  headers?: Record<string, string>;\n};\n\nexport interface RunAgentParameters {\n  request: Request;\n  runtime: CopilotRuntimeLike;\n  agentId: string;\n}\n\nexport interface ConnectRequestBody extends RunAgentInput {\n  lastSeenEventId?: string | null;\n}\n\n/**\n * Resolve `agentId` against the runtime's agents and return a per-request\n * clone of the matching agent.\n *\n * Dual return contract — both callers (`handle-run.ts`, `handle-connect.ts`)\n * depend on it:\n * - Returns a cloned `AbstractAgent` when the agent exists.\n * - Returns a 404 `Response` (`{ error: \"Agent not found\", ... }`) when the\n *   agent is unknown. Callers MUST `instanceof Response`-check the result and\n *   return it directly; this doubles as the connect/run path's agent-existence\n *   guard, so skipping the check would let unknown agent ids slip through.\n *\n * The clone is what subsequent per-request mutation (middleware attach,\n * `agent.headers` merge) operates on, leaving the shared agent registration\n * untouched.\n */\nexport async function cloneAgentForRequest(\n  runtime: CopilotRuntimeLike,\n  agentId: string,\n  request?: Request,\n): Promise<AbstractAgent | Response> {\n  const agents = await resolveAgents(runtime.agents, request);\n\n  if (!agents[agentId]) {\n    return new Response(\n      JSON.stringify({\n        error: \"Agent not found\",\n        message: `Agent '${agentId}' does not exist`,\n      }),\n      {\n        status: 404,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n\n  return (agents[agentId] as AbstractAgent).clone() as AbstractAgent;\n}\n\nexport function configureAgentForRequest(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agentId: string;\n  agent: AbstractAgent;\n  /**\n   * True when the React provider was given an A2UI catalog\n   * (`<CopilotKit a2ui={{ catalog }}>`), forwarded per-run. A catalog alone is\n   * enough to enable A2UI and inject the render tool — the developer no longer\n   * has to also set `a2ui.injectA2UITool` on the runtime.\n   */\n  providerA2UIHasCatalog?: boolean;\n  /** Retain proxy rejection even when no server is available to this agent. */\n  isMcpProxyRequest?: boolean;\n}): void {\n  const {\n    runtime,\n    request,\n    agentId,\n    providerA2UIHasCatalog,\n    isMcpProxyRequest,\n  } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  // A2UI is on when the runtime explicitly enables it, OR when the provider\n  // forwarded a catalog — but an explicit `enabled: false` always wins (we\n  // provide a quick default, never override a deeper opt-out).\n  const a2uiEnabledByCatalog =\n    !!providerA2UIHasCatalog && runtime.a2ui?.enabled !== false;\n\n  if (isA2UIEnabled(runtime.a2ui) || a2uiEnabledByCatalog) {\n    // `enabled` is a CopilotKit-level switch, not an A2UIMiddleware option —\n    // drop it (alongside the agent filter) before forwarding to the middleware.\n    const {\n      agents: targetAgents,\n      enabled: _enabled,\n      injectA2UITool,\n      ...a2uiOptions\n    } = runtime.a2ui ?? {};\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(\n        new A2UIMiddleware({\n          ...a2uiOptions,\n          // Default render-tool injection on when a catalog is present and the\n          // developer hasn't set it explicitly. `??` means an explicit value\n          // (including `false`) is always respected.\n          injectA2UITool:\n            injectA2UITool ?? (providerA2UIHasCatalog ? true : undefined),\n        }),\n      );\n    }\n  }\n\n  if (isIntelligenceRuntime(runtime) && typeof agent.use === \"function\") {\n    // Ordinary runs need no middleware without selected servers. Proxy requests\n    // still need the upstream guard so they cannot fall through to the model.\n    const mcpServers = resolveMcpAppsServers(\n      runtime.mcpApps?.servers ?? [],\n      agentId,\n    );\n    if (mcpServers.length > 0 || isMcpProxyRequest) {\n      agent.use(\n        new MCPAppsMiddleware({ mcpServers, discoveryFailureMode: \"throw\" }),\n      );\n    }\n  } else if (runtime.mcpApps?.servers?.length) {\n    const mcpServers = resolveMcpAppsServers(runtime.mcpApps.servers, agentId);\n\n    if (mcpServers.length > 0 && typeof agent.use === \"function\") {\n      agent.use(new MCPAppsMiddleware({ mcpServers }));\n    }\n  }\n\n  if (runtime.openGenerativeUI) {\n    const config = runtime.openGenerativeUI;\n    const targetAgents = typeof config === \"object\" ? config.agents : undefined;\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(new OpenGenerativeUIMiddleware());\n    }\n  }\n\n  // Forward eligible inbound headers onto the outgoing agent call under the\n  // runtime's resolved forwarding policy (`authorization` / custom `x-*`, with\n  // known infra/proxy/platform headers stripped by the default denylist —\n  // #5712), but let headers the server explicitly configured on the agent WIN\n  // on collision (case-insensitively): a server-set service-to-service token\n  // (e.g. an IAM bearer) must never be silently overridden by a\n  // browser/edge/platform-injected inbound header. See `mergeForwardableHeaders`\n  // for the casing/duplicate-key rationale and `shouldForwardHeader` for breadth.\n  agent.headers = mergeForwardableHeaders(\n    agent.headers,\n    request,\n    // `forwardHeadersPolicy` is optional on the published `CopilotRuntimeLike`\n    // interface (non-breaking minor release). Concrete runtimes always set it;\n    // a policy-less external implementor falls back to the default resolved\n    // policy (default-on denylist) so behavior stays identical and never derefs\n    // undefined.\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n}\n\n/**\n * Attach CopilotKit Intelligence's MCP tools to the agent run when\n * `CopilotKitIntelligence` was constructed with\n * `enableEnterpriseLearning: true`. Uses `@ag-ui/mcp-middleware`, so the\n * tools are available uniformly across agent frameworks (not just\n * `BuiltInAgent`).\n *\n * The middleware sits on a per-request agent clone, so the per-request\n * auth (Bearer apiKey + resolved user-id) is baked into the transport\n * headers at attach time. If user resolution fails, attachment is\n * skipped silently — the intelligence run handler will reject the\n * request with the same error. Note this means `identifyUser` is\n * resolved twice per learning-enabled run (here and in the run handler);\n * the callback is expected to be idempotent and side-effect-free.\n *\n * Intentionally split out from `configureAgentForRequest`: this is only\n * relevant to actual agent runs, not auxiliary flows like thread-name\n * generation (which has no need for MCP tools and shouldn't pay the\n * `listTools` round-trip).\n */\nexport async function attachIntelligenceEnterpriseLearning(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n}): Promise<void | Response> {\n  const { runtime, request } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  if (\n    !isIntelligenceRuntime(runtime) ||\n    (runtime.memory === undefined &&\n      !runtime.intelligence?.ɵisEnterpriseLearningEnabled?.())\n  ) {\n    return;\n  }\n\n  // Enterprise learning is enabled, but this agent's framework can't take\n  // middleware — surface it rather than silently shipping a run with none\n  // of the tools the operator opted into.\n  if (typeof agent.use !== \"function\") {\n    if (runtime.memory) {\n      return errorResponse(\n        \"Memory is configured, but this agent does not support middleware\",\n        500,\n      );\n    }\n    logger.warn(\n      \"CopilotKitIntelligence.enableEnterpriseLearning is enabled, but the agent \" +\n        \"does not support middleware (no `.use()` method); Intelligence tools were \" +\n        \"not attached for this run.\",\n    );\n    return;\n  }\n\n  const userResult = await resolveIntelligenceUser({ runtime, request });\n  if (userResult instanceof Response) return userResult;\n  const access = await resolveWebMemory(runtime, request, userResult, \"agent\");\n  if (access instanceof Response) return access;\n\n  agent.use(\n    new MCPMiddleware([\n      {\n        type: \"http\",\n        url: `${runtime.intelligence.ɵgetApiUrl()}/mcp`,\n        serverId: \"intelligence\",\n        headers: {\n          Authorization: `Bearer ${runtime.intelligence.ɵgetApiKey()}`,\n          [INTELLIGENCE_USER_ID_HEADER]: userResult.id,\n          ...(runtime.memory\n            ? {\n                [INTELLIGENCE_MEMORY_GRANT_HEADER]: JSON.stringify(\n                  access.grant,\n                ),\n              }\n            : {}),\n        },\n      },\n    ]),\n  );\n}\n\nexport async function parseRunRequest(\n  request: Request,\n): Promise<RunAgentInput | Response> {\n  try {\n    const requestBody = await request.json();\n    return RunAgentInputSchema.parse(requestBody);\n  } catch (error) {\n    logger.error(\"Invalid run request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n\nexport async function parseConnectRequest(request: Request): Promise<\n  | Response\n  | {\n      input: RunAgentInput;\n      lastSeenEventId: string | null;\n    }\n> {\n  try {\n    const requestBody = await request.json();\n    const input = RunAgentInputSchema.parse(requestBody);\n    let lastSeenEventId: string | null = null;\n\n    if (\n      \"lastSeenEventId\" in (requestBody as Record<string, unknown>) &&\n      (typeof (requestBody as Record<string, unknown>).lastSeenEventId ===\n        \"string\" ||\n        (requestBody as Record<string, unknown>).lastSeenEventId === null)\n    ) {\n      lastSeenEventId =\n        (requestBody as ConnectRequestBody).lastSeenEventId ?? null;\n    }\n\n    return { input, lastSeenEventId };\n  } catch (error) {\n    logger.error(\"Invalid connect request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n"],"mappings":";;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;;AAyDA,eAAsB,qBACpB,SACA,SACA,SACmC;CACnC,MAAM,SAAS,MAAM,cAAc,QAAQ,QAAQ,QAAQ;AAE3D,KAAI,CAAC,OAAO,SACV,QAAO,IAAI,SACT,KAAK,UAAU;EACb,OAAO;EACP,SAAS,UAAU,QAAQ;EAC5B,CAAC,EACF;EACE,QAAQ;EACR,SAAS,EAAE,gBAAgB,oBAAoB;EAChD,CACF;AAGH,QAAQ,OAAO,SAA2B,OAAO;;AAGnD,SAAgB,yBAAyB,QAchC;CACP,MAAM,EACJ,SACA,SACA,SACA,wBACA,sBACE;CACJ,MAAM,QAAQ,OAAO;CAKrB,MAAM,uBACJ,CAAC,CAAC,0BAA0B,QAAQ,MAAM,YAAY;AAExD,KAAI,cAAc,QAAQ,KAAK,IAAI,sBAAsB;EAGvD,MAAM,EACJ,QAAQ,cACR,SAAS,UACT,gBACA,GAAG,gBACD,QAAQ,QAAQ,EAAE;AAEtB,OADoB,CAAC,gBAAgB,aAAa,SAAS,QAAQ,KAChD,OAAO,MAAM,QAAQ,WACtC,OAAM,IACJ,IAAI,eAAe;GACjB,GAAG;GAIH,gBACE,mBAAmB,yBAAyB,OAAO;GACtD,CAAC,CACH;;AAIL,KAAI,sBAAsB,QAAQ,IAAI,OAAO,MAAM,QAAQ,YAAY;EAGrE,MAAM,aAAa,sBACjB,QAAQ,SAAS,WAAW,EAAE,EAC9B,QACD;AACD,MAAI,WAAW,SAAS,KAAK,kBAC3B,OAAM,IACJ,IAAI,kBAAkB;GAAE;GAAY,sBAAsB;GAAS,CAAC,CACrE;YAEM,QAAQ,SAAS,SAAS,QAAQ;EAC3C,MAAM,aAAa,sBAAsB,QAAQ,QAAQ,SAAS,QAAQ;AAE1E,MAAI,WAAW,SAAS,KAAK,OAAO,MAAM,QAAQ,WAChD,OAAM,IAAI,IAAI,kBAAkB,EAAE,YAAY,CAAC,CAAC;;AAIpD,KAAI,QAAQ,kBAAkB;EAC5B,MAAM,SAAS,QAAQ;EACvB,MAAM,eAAe,OAAO,WAAW,WAAW,OAAO,SAAS;AAElE,OADoB,CAAC,gBAAgB,aAAa,SAAS,QAAQ,KAChD,OAAO,MAAM,QAAQ,WACtC,OAAM,IAAI,IAAI,4BAA4B,CAAC;;AAY/C,OAAM,UAAU,wBACd,MAAM,SACN,SAMA,QAAQ,wBAAwB,4BAA4B,OAAU,CACvE;;;;;;;;;;;;;;;;;;;;;;AAuBH,eAAsB,qCAAqC,QAI9B;CAC3B,MAAM,EAAE,SAAS,YAAY;CAC7B,MAAM,QAAQ,OAAO;AAErB,KACE,CAAC,sBAAsB,QAAQ,IAC9B,QAAQ,WAAW,UAClB,CAAC,QAAQ,cAAc,gCAAgC,CAEzD;AAMF,KAAI,OAAO,MAAM,QAAQ,YAAY;AACnC,MAAI,QAAQ,OACV,QAAO,cACL,oEACA,IACD;AAEH,SAAO,KACL,iLAGD;AACD;;CAGF,MAAM,aAAa,MAAM,wBAAwB;EAAE;EAAS;EAAS,CAAC;AACtE,KAAI,sBAAsB,SAAU,QAAO;CAC3C,MAAM,SAAS,MAAM,iBAAiB,SAAS,SAAS,YAAY,QAAQ;AAC5E,KAAI,kBAAkB,SAAU,QAAO;AAEvC,OAAM,IACJ,IAAI,cAAc,CAChB;EACE,MAAM;EACN,KAAK,GAAG,QAAQ,aAAa,YAAY,CAAC;EAC1C,UAAU;EACV,SAAS;GACP,eAAe,UAAU,QAAQ,aAAa,YAAY;IACzD,8BAA8B,WAAW;GAC1C,GAAI,QAAQ,SACR,GACG,mCAAmC,KAAK,UACvC,OAAO,MACR,EACF,GACD,EAAE;GACP;EACF,CACF,CAAC,CACH;;AAGH,eAAsB,gBACpB,SACmC;AACnC,KAAI;EACF,MAAM,cAAc,MAAM,QAAQ,MAAM;AACxC,SAAO,oBAAoB,MAAM,YAAY;UACtC,OAAO;AACd,SAAO,MAAM,6BAA6B,MAAM;AAChD,SAAO,IAAI,SACT,KAAK,UAAU;GACb,OAAO;GACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;GAChE,CAAC,EACF;GACE,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CACF;;;AAIL,eAAsB,oBAAoB,SAMxC;AACA,KAAI;EACF,MAAM,cAAc,MAAM,QAAQ,MAAM;EACxC,MAAM,QAAQ,oBAAoB,MAAM,YAAY;EACpD,IAAI,kBAAiC;AAErC,MACE,qBAAsB,gBACrB,OAAQ,YAAwC,oBAC/C,YACC,YAAwC,oBAAoB,MAE/D,mBACG,YAAmC,mBAAmB;AAG3D,SAAO;GAAE;GAAO;GAAiB;UAC1B,OAAO;AACd,SAAO,MAAM,iCAAiC,MAAM;AACpD,SAAO,IAAI,SACT,KAAK,UAAU;GACb,OAAO;GACP,SAAS,iBAAiB,QAAQ,MAAM,UAAU,OAAO,MAAM;GAChE,CAAC,EACF;GACE,QAAQ;GACR,SAAS,EAAE,gBAAgB,oBAAoB;GAChD,CACF"}
+{"version":3,"file":"agent-utils.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/shared/agent-utils.ts"],"sourcesContent":["import type { AbstractAgent, RunAgentInput } from \"@ag-ui/client\";\nimport { RunAgentInputSchema } from \"@ag-ui/client\";\nimport {\n  A2UIMiddleware,\n  OpenGenerativeUIMiddleware,\n} from \"@copilotkit/shared/event-transforms\";\nimport { MCPAppsMiddleware } from \"@ag-ui/mcp-apps-middleware\";\nimport { MCPMiddleware } from \"@ag-ui/mcp-middleware\";\nimport type { CopilotRuntimeLike } from \"../../core/runtime\";\nimport {\n  isA2UIEnabled,\n  isIntelligenceRuntime,\n  resolveAgents,\n} from \"../../core/runtime\";\nimport {\n  INTELLIGENCE_MEMORY_GRANT_HEADER,\n  INTELLIGENCE_USER_ID_HEADER,\n} from \"../../intelligence-platform/client\";\nimport {\n  mergeForwardableHeaders,\n  resolveForwardHeadersPolicy,\n} from \"../header-utils\";\nimport { resolveMcpAppsServers } from \"./mcp-apps-servers\";\nimport { resolveIntelligenceUser } from \"./resolve-intelligence-user\";\nimport { resolveWebMemory } from \"./memory-policy\";\nimport { errorResponse } from \"./json-response\";\nimport { logger } from \"@copilotkit/shared\";\n\ntype MiddlewareCapableAgent = AbstractAgent & {\n  use?: (middleware: unknown) => void;\n  headers?: Record<string, string>;\n};\n\nexport interface RunAgentParameters {\n  request: Request;\n  runtime: CopilotRuntimeLike;\n  agentId: string;\n}\n\nexport interface ConnectRequestBody extends RunAgentInput {\n  lastSeenEventId?: string | null;\n}\n\n/**\n * Resolve `agentId` against the runtime's agents and return a per-request\n * clone of the matching agent.\n *\n * Dual return contract — both callers (`handle-run.ts`, `handle-connect.ts`)\n * depend on it:\n * - Returns a cloned `AbstractAgent` when the agent exists.\n * - Returns a 404 `Response` (`{ error: \"Agent not found\", ... }`) when the\n *   agent is unknown. Callers MUST `instanceof Response`-check the result and\n *   return it directly; this doubles as the connect/run path's agent-existence\n *   guard, so skipping the check would let unknown agent ids slip through.\n *\n * The clone is what subsequent per-request mutation (middleware attach,\n * `agent.headers` merge) operates on, leaving the shared agent registration\n * untouched.\n */\nexport async function cloneAgentForRequest(\n  runtime: CopilotRuntimeLike,\n  agentId: string,\n  request?: Request,\n): Promise<AbstractAgent | Response> {\n  const agents = await resolveAgents(runtime.agents, request);\n\n  if (!agents[agentId]) {\n    return new Response(\n      JSON.stringify({\n        error: \"Agent not found\",\n        message: `Agent '${agentId}' does not exist`,\n      }),\n      {\n        status: 404,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n\n  return (agents[agentId] as AbstractAgent).clone() as AbstractAgent;\n}\n\nexport function configureAgentForRequest(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agentId: string;\n  agent: AbstractAgent;\n  /**\n   * True when the React provider was given an A2UI catalog\n   * (`<CopilotKit a2ui={{ catalog }}>`), forwarded per-run. A catalog alone is\n   * enough to enable A2UI and inject the render tool — the developer no longer\n   * has to also set `a2ui.injectA2UITool` on the runtime.\n   */\n  providerA2UIHasCatalog?: boolean;\n  /** Retain proxy rejection even when no server is available to this agent. */\n  isMcpProxyRequest?: boolean;\n}): void {\n  const {\n    runtime,\n    request,\n    agentId,\n    providerA2UIHasCatalog,\n    isMcpProxyRequest,\n  } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  // A2UI is on when the runtime explicitly enables it, OR when the provider\n  // forwarded a catalog — but an explicit `enabled: false` always wins (we\n  // provide a quick default, never override a deeper opt-out).\n  const a2uiEnabledByCatalog =\n    !!providerA2UIHasCatalog && runtime.a2ui?.enabled !== false;\n\n  if (isA2UIEnabled(runtime.a2ui) || a2uiEnabledByCatalog) {\n    // `enabled` is a CopilotKit-level switch, not an A2UIMiddleware option —\n    // drop it (alongside the agent filter) before forwarding to the middleware.\n    const {\n      agents: targetAgents,\n      enabled: _enabled,\n      injectA2UITool,\n      ...a2uiOptions\n    } = runtime.a2ui ?? {};\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(\n        new A2UIMiddleware({\n          ...a2uiOptions,\n          // Default render-tool injection on when a catalog is present and the\n          // developer hasn't set it explicitly. `??` means an explicit value\n          // (including `false`) is always respected.\n          injectA2UITool:\n            injectA2UITool ?? (providerA2UIHasCatalog ? true : undefined),\n        }),\n      );\n    }\n  }\n\n  if (isIntelligenceRuntime(runtime) && typeof agent.use === \"function\") {\n    // Ordinary runs need no middleware without selected servers. Proxy requests\n    // still need the upstream guard so they cannot fall through to the model.\n    const mcpServers = resolveMcpAppsServers(\n      runtime.mcpApps?.servers ?? [],\n      agentId,\n    );\n    if (mcpServers.length > 0 || isMcpProxyRequest) {\n      agent.use(\n        new MCPAppsMiddleware({ mcpServers, discoveryFailureMode: \"throw\" }),\n      );\n    }\n  } else if (runtime.mcpApps?.servers?.length) {\n    const mcpServers = resolveMcpAppsServers(runtime.mcpApps.servers, agentId);\n\n    if (mcpServers.length > 0 && typeof agent.use === \"function\") {\n      agent.use(new MCPAppsMiddleware({ mcpServers }));\n    }\n  }\n\n  if (runtime.openGenerativeUI) {\n    const config = runtime.openGenerativeUI;\n    const targetAgents = typeof config === \"object\" ? config.agents : undefined;\n    const shouldApply = !targetAgents || targetAgents.includes(agentId);\n    if (shouldApply && typeof agent.use === \"function\") {\n      agent.use(new OpenGenerativeUIMiddleware());\n    }\n  }\n\n  // Forward eligible inbound headers onto the outgoing agent call under the\n  // runtime's resolved forwarding policy (`authorization` / custom `x-*`, with\n  // known infra/proxy/platform headers stripped by the default denylist —\n  // #5712), but let headers the server explicitly configured on the agent WIN\n  // on collision (case-insensitively): a server-set service-to-service token\n  // (e.g. an IAM bearer) must never be silently overridden by a\n  // browser/edge/platform-injected inbound header. See `mergeForwardableHeaders`\n  // for the casing/duplicate-key rationale and `shouldForwardHeader` for breadth.\n  agent.headers = mergeForwardableHeaders(\n    agent.headers,\n    request,\n    // `forwardHeadersPolicy` is optional on the published `CopilotRuntimeLike`\n    // interface (non-breaking minor release). Concrete runtimes always set it;\n    // a policy-less external implementor falls back to the default resolved\n    // policy (default-on denylist) so behavior stays identical and never derefs\n    // undefined.\n    runtime.forwardHeadersPolicy ?? resolveForwardHeadersPolicy(undefined),\n  );\n}\n\n/**\n * Attach CopilotKit Intelligence's MCP tools to the agent run when\n * `CopilotKitIntelligence` was constructed with\n * `enableEnterpriseLearning: true`. Uses `@ag-ui/mcp-middleware`, so the\n * tools are available uniformly across agent frameworks (not just\n * `BuiltInAgent`).\n *\n * The middleware sits on a per-request agent clone, so the per-request\n * auth (Bearer apiKey + resolved user-id) is baked into the transport\n * headers at attach time. If user resolution fails, attachment is\n * skipped silently — the intelligence run handler will reject the\n * request with the same error. Note this means `identifyUser` is\n * resolved twice per learning-enabled run (here and in the run handler);\n * the callback is expected to be idempotent and side-effect-free.\n *\n * Intentionally split out from `configureAgentForRequest`: this is only\n * relevant to actual agent runs, not auxiliary flows like thread-name\n * generation (which has no need for MCP tools and shouldn't pay the\n * `listTools` round-trip).\n */\nexport async function attachIntelligenceEnterpriseLearning(params: {\n  runtime: CopilotRuntimeLike;\n  request: Request;\n  agent: AbstractAgent;\n}): Promise<void | Response> {\n  const { runtime, request } = params;\n  const agent = params.agent as MiddlewareCapableAgent;\n\n  if (\n    !isIntelligenceRuntime(runtime) ||\n    (runtime.memory === undefined &&\n      !runtime.intelligence?.ɵisEnterpriseLearningEnabled?.())\n  ) {\n    return;\n  }\n\n  // Enterprise learning is enabled, but this agent's framework can't take\n  // middleware — surface it rather than silently shipping a run with none\n  // of the tools the operator opted into.\n  if (typeof agent.use !== \"function\") {\n    if (runtime.memory) {\n      return errorResponse(\n        \"Memory is configured, but this agent does not support middleware\",\n        500,\n      );\n    }\n    logger.warn(\n      \"CopilotKitIntelligence.enableEnterpriseLearning is enabled, but the agent \" +\n        \"does not support middleware (no `.use()` method); Intelligence tools were \" +\n        \"not attached for this run.\",\n    );\n    return;\n  }\n\n  const userResult = await resolveIntelligenceUser({ runtime, request });\n  if (userResult instanceof Response) return userResult;\n  const access = await resolveWebMemory(runtime, request, userResult, \"agent\");\n  if (access instanceof Response) return access;\n\n  agent.use(\n    new MCPMiddleware([\n      {\n        type: \"http\",\n        url: `${runtime.intelligence.ɵgetApiUrl()}/mcp`,\n        serverId: \"intelligence\",\n        headers: {\n          Authorization: `Bearer ${runtime.intelligence.ɵgetApiKey()}`,\n          [INTELLIGENCE_USER_ID_HEADER]: userResult.id,\n          ...(runtime.memory\n            ? {\n                [INTELLIGENCE_MEMORY_GRANT_HEADER]: JSON.stringify(\n                  access.grant,\n                ),\n              }\n            : {}),\n        },\n      },\n    ]),\n  );\n}\n\nexport async function parseRunRequest(\n  request: Request,\n): Promise<RunAgentInput | Response> {\n  try {\n    const requestBody = await request.json();\n    return RunAgentInputSchema.parse(requestBody);\n  } catch (error) {\n    logger.error(\"Invalid run request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n\nexport async function parseConnectRequest(request: Request): Promise<\n  | Response\n  | {\n      input: RunAgentInput;\n      lastSeenEventId: string | null;\n    }\n> {\n  try {\n    const requestBody = await request.json();\n    const input = RunAgentInputSchema.parse(requestBody);\n    let lastSeenEventId: string | null = null;\n\n    if (\n      \"lastSeenEventId\" in (requestBody as Record<string, unknown>) &&\n      (typeof (requestBody as Record<string, unknown>).lastSeenEventId ===\n        \"string\" ||\n        (requestBody as Record<string, unknown>).lastSeenEventId === null)\n    ) {\n      lastSeenEventId =\n        (requestBody as ConnectRequestBody).lastSeenEventId ?? null;\n    }\n\n    return { input, lastSeenEventId };\n  } catch (error) {\n    logger.error(\"Invalid connect request body:\", error);\n    return new Response(\n      JSON.stringify({\n        error: \"Invalid request body\",\n        details: error instanceof Error ? error.message : String(error),\n      }),\n      {\n        status: 400,\n        headers: { \"Content-Type\": \"application/json\" },\n      },\n    );\n  }\n}\n"],"mappings":"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"}

package/dist/v2/runtime/handlers/shared/sse-keep-alive.cjs

@@ -0,0 +1,69 @@
+require("reflect-metadata");
+
+//#region src/v2/runtime/handlers/shared/sse-keep-alive.ts
+/**
+* Default silence, in seconds, before an SSE response carries a keep-alive
+* comment. Sits under the tightest common proxy idle timeouts (55–60 s) and
+* beside `lockHeartbeatIntervalSeconds`, which shares the unit and default.
+*/
+const DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS = 15;
+/**
+* Longest interval the timer can honour. Timers take a signed 32-bit
+* millisecond delay; Node silently replaces anything larger with 1 ms, which
+* would turn a keep-alive into a flood.
+*/
+const MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS = (2 ** 31 - 1) / 1e3;
+/**
+* Resolves the `sseKeepAliveIntervalSeconds` runtime option once, at
+* construction, so every SSE call site reads one validated value.
+* `undefined` takes the default; `0` disables the keep-alive.
+*/
+function resolveSseKeepAliveIntervalSeconds(value) {
+	const seconds = value ?? DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS;
+	if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS) throw new RangeError(`sseKeepAliveIntervalSeconds must be between 0 and ${MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS}, got ${String(value)}`);
+	return seconds;
+}
+/**
+* SSE comment frame. Parsers drop comment lines, so no AG-UI event is
+* invented and the verifier, history and middleware never see it.
+* @see https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes
+*/
+const KEEP_ALIVE_FRAME = new TextEncoder().encode(": keep-alive\n\n");
+/**
+* Keeps a quiet SSE body open by writing a comment after `idleMs` of silence.
+*
+* Any byte from `source` resets the clock, so an active stream adds nothing
+* to the wire. A back-pressured reader skips the tick instead of queueing
+* frames. The timer stops when the pipe settles, which covers both the source
+* completing and the reader cancelling, on every supported Node version.
+*/
+function keepAliveSse(source, idleMs) {
+	let timer;
+	const stop = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+	};
+	const arm = (controller) => {
+		stop();
+		timer = setTimeout(() => {
+			if (controller.desiredSize === 1) controller.enqueue(KEEP_ALIVE_FRAME);
+			arm(controller);
+		}, idleMs);
+		timer.unref?.();
+	};
+	const transform = new TransformStream({
+		start: arm,
+		transform(chunk, controller) {
+			controller.enqueue(chunk);
+			arm(controller);
+		},
+		flush: stop
+	}, void 0, { highWaterMark: 1 });
+	source.pipeTo(transform.writable).catch(() => {}).finally(stop);
+	return transform.readable;
+}
+
+//#endregion
+exports.keepAliveSse = keepAliveSse;
+exports.resolveSseKeepAliveIntervalSeconds = resolveSseKeepAliveIntervalSeconds;
+//# sourceMappingURL=sse-keep-alive.cjs.map

package/dist/v2/runtime/handlers/shared/sse-keep-alive.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-keep-alive.cjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/shared/sse-keep-alive.ts"],"sourcesContent":["/**\n * Default silence, in seconds, before an SSE response carries a keep-alive\n * comment. Sits under the tightest common proxy idle timeouts (55–60 s) and\n * beside `lockHeartbeatIntervalSeconds`, which shares the unit and default.\n */\nexport const DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS = 15;\n\n/**\n * Longest interval the timer can honour. Timers take a signed 32-bit\n * millisecond delay; Node silently replaces anything larger with 1 ms, which\n * would turn a keep-alive into a flood.\n */\nexport const MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS = (2 ** 31 - 1) / 1000;\n\n/**\n * Resolves the `sseKeepAliveIntervalSeconds` runtime option once, at\n * construction, so every SSE call site reads one validated value.\n * `undefined` takes the default; `0` disables the keep-alive.\n */\nexport function resolveSseKeepAliveIntervalSeconds(\n  value: number | undefined,\n): number {\n  const seconds = value ?? DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS;\n  if (\n    !Number.isFinite(seconds) ||\n    seconds < 0 ||\n    seconds > MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS\n  ) {\n    throw new RangeError(\n      `sseKeepAliveIntervalSeconds must be between 0 and ${MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS}, got ${String(value)}`,\n    );\n  }\n  return seconds;\n}\n\n/**\n * SSE comment frame. Parsers drop comment lines, so no AG-UI event is\n * invented and the verifier, history and middleware never see it.\n * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes\n */\nconst KEEP_ALIVE_FRAME = new TextEncoder().encode(\": keep-alive\\n\\n\");\n\n/**\n * Keeps a quiet SSE body open by writing a comment after `idleMs` of silence.\n *\n * Any byte from `source` resets the clock, so an active stream adds nothing\n * to the wire. A back-pressured reader skips the tick instead of queueing\n * frames. The timer stops when the pipe settles, which covers both the source\n * completing and the reader cancelling, on every supported Node version.\n */\nexport function keepAliveSse(\n  source: ReadableStream<Uint8Array>,\n  idleMs: number,\n): ReadableStream<Uint8Array> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const stop = () => {\n    if (timer !== undefined) clearTimeout(timer);\n    timer = undefined;\n  };\n  const arm = (controller: TransformStreamDefaultController<Uint8Array>) => {\n    stop();\n    timer = setTimeout(() => {\n      // `desiredSize` is 1 only while the readable queue is empty; 0 means a\n      // slow reader still holds the previous chunk, null means it went away.\n      if (controller.desiredSize === 1) controller.enqueue(KEEP_ALIVE_FRAME);\n      arm(controller);\n    }, idleMs);\n    timer.unref?.();\n  };\n  const transform = new TransformStream<Uint8Array, Uint8Array>(\n    {\n      start: arm,\n      transform(chunk, controller) {\n        controller.enqueue(chunk);\n        arm(controller);\n      },\n      flush: stop,\n    },\n    undefined,\n    { highWaterMark: 1 },\n  );\n  // `flush` stops the timer when the source completes. The pipe settling\n  // covers the reader cancelling, on every supported Node version; the source\n  // writer surfaces that cancellation to the caller.\n  void source\n    .pipeTo(transform.writable)\n    .catch(() => {})\n    .finally(stop);\n  return transform.readable;\n}\n"],"mappings":";;;;;;;;AAKA,MAAa,0CAA0C;;;;;;AAOvD,MAAa,uCAAuC,KAAK,KAAK,KAAK;;;;;;AAOnE,SAAgB,mCACd,OACQ;CACR,MAAM,UAAU,SAAS;AACzB,KACE,CAAC,OAAO,SAAS,QAAQ,IACzB,UAAU,KACV,UAAU,oCAEV,OAAM,IAAI,WACR,qDAAqD,oCAAoC,QAAQ,OAAO,MAAM,GAC/G;AAEH,QAAO;;;;;;;AAQT,MAAM,mBAAmB,IAAI,aAAa,CAAC,OAAO,mBAAmB;;;;;;;;;AAUrE,SAAgB,aACd,QACA,QAC4B;CAC5B,IAAI;CACJ,MAAM,aAAa;AACjB,MAAI,UAAU,OAAW,cAAa,MAAM;AAC5C,UAAQ;;CAEV,MAAM,OAAO,eAA6D;AACxE,QAAM;AACN,UAAQ,iBAAiB;AAGvB,OAAI,WAAW,gBAAgB,EAAG,YAAW,QAAQ,iBAAiB;AACtE,OAAI,WAAW;KACd,OAAO;AACV,QAAM,SAAS;;CAEjB,MAAM,YAAY,IAAI,gBACpB;EACE,OAAO;EACP,UAAU,OAAO,YAAY;AAC3B,cAAW,QAAQ,MAAM;AACzB,OAAI,WAAW;;EAEjB,OAAO;EACR,EACD,QACA,EAAE,eAAe,GAAG,CACrB;AAID,CAAK,OACF,OAAO,UAAU,SAAS,CAC1B,YAAY,GAAG,CACf,QAAQ,KAAK;AAChB,QAAO,UAAU"}

package/dist/v2/runtime/handlers/shared/sse-keep-alive.mjs

@@ -0,0 +1,67 @@
+import "reflect-metadata";
+//#region src/v2/runtime/handlers/shared/sse-keep-alive.ts
+/**
+* Default silence, in seconds, before an SSE response carries a keep-alive
+* comment. Sits under the tightest common proxy idle timeouts (55–60 s) and
+* beside `lockHeartbeatIntervalSeconds`, which shares the unit and default.
+*/
+const DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS = 15;
+/**
+* Longest interval the timer can honour. Timers take a signed 32-bit
+* millisecond delay; Node silently replaces anything larger with 1 ms, which
+* would turn a keep-alive into a flood.
+*/
+const MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS = (2 ** 31 - 1) / 1e3;
+/**
+* Resolves the `sseKeepAliveIntervalSeconds` runtime option once, at
+* construction, so every SSE call site reads one validated value.
+* `undefined` takes the default; `0` disables the keep-alive.
+*/
+function resolveSseKeepAliveIntervalSeconds(value) {
+	const seconds = value ?? DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS;
+	if (!Number.isFinite(seconds) || seconds < 0 || seconds > MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS) throw new RangeError(`sseKeepAliveIntervalSeconds must be between 0 and ${MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS}, got ${String(value)}`);
+	return seconds;
+}
+/**
+* SSE comment frame. Parsers drop comment lines, so no AG-UI event is
+* invented and the verifier, history and middleware never see it.
+* @see https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes
+*/
+const KEEP_ALIVE_FRAME = new TextEncoder().encode(": keep-alive\n\n");
+/**
+* Keeps a quiet SSE body open by writing a comment after `idleMs` of silence.
+*
+* Any byte from `source` resets the clock, so an active stream adds nothing
+* to the wire. A back-pressured reader skips the tick instead of queueing
+* frames. The timer stops when the pipe settles, which covers both the source
+* completing and the reader cancelling, on every supported Node version.
+*/
+function keepAliveSse(source, idleMs) {
+	let timer;
+	const stop = () => {
+		if (timer !== void 0) clearTimeout(timer);
+		timer = void 0;
+	};
+	const arm = (controller) => {
+		stop();
+		timer = setTimeout(() => {
+			if (controller.desiredSize === 1) controller.enqueue(KEEP_ALIVE_FRAME);
+			arm(controller);
+		}, idleMs);
+		timer.unref?.();
+	};
+	const transform = new TransformStream({
+		start: arm,
+		transform(chunk, controller) {
+			controller.enqueue(chunk);
+			arm(controller);
+		},
+		flush: stop
+	}, void 0, { highWaterMark: 1 });
+	source.pipeTo(transform.writable).catch(() => {}).finally(stop);
+	return transform.readable;
+}
+
+//#endregion
+export { keepAliveSse, resolveSseKeepAliveIntervalSeconds };
+//# sourceMappingURL=sse-keep-alive.mjs.map

package/dist/v2/runtime/handlers/shared/sse-keep-alive.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"sse-keep-alive.mjs","names":[],"sources":["../../../../../src/v2/runtime/handlers/shared/sse-keep-alive.ts"],"sourcesContent":["/**\n * Default silence, in seconds, before an SSE response carries a keep-alive\n * comment. Sits under the tightest common proxy idle timeouts (55–60 s) and\n * beside `lockHeartbeatIntervalSeconds`, which shares the unit and default.\n */\nexport const DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS = 15;\n\n/**\n * Longest interval the timer can honour. Timers take a signed 32-bit\n * millisecond delay; Node silently replaces anything larger with 1 ms, which\n * would turn a keep-alive into a flood.\n */\nexport const MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS = (2 ** 31 - 1) / 1000;\n\n/**\n * Resolves the `sseKeepAliveIntervalSeconds` runtime option once, at\n * construction, so every SSE call site reads one validated value.\n * `undefined` takes the default; `0` disables the keep-alive.\n */\nexport function resolveSseKeepAliveIntervalSeconds(\n  value: number | undefined,\n): number {\n  const seconds = value ?? DEFAULT_SSE_KEEP_ALIVE_INTERVAL_SECONDS;\n  if (\n    !Number.isFinite(seconds) ||\n    seconds < 0 ||\n    seconds > MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS\n  ) {\n    throw new RangeError(\n      `sseKeepAliveIntervalSeconds must be between 0 and ${MAX_SSE_KEEP_ALIVE_INTERVAL_SECONDS}, got ${String(value)}`,\n    );\n  }\n  return seconds;\n}\n\n/**\n * SSE comment frame. Parsers drop comment lines, so no AG-UI event is\n * invented and the verifier, history and middleware never see it.\n * @see https://html.spec.whatwg.org/multipage/server-sent-events.html#authoring-notes\n */\nconst KEEP_ALIVE_FRAME = new TextEncoder().encode(\": keep-alive\\n\\n\");\n\n/**\n * Keeps a quiet SSE body open by writing a comment after `idleMs` of silence.\n *\n * Any byte from `source` resets the clock, so an active stream adds nothing\n * to the wire. A back-pressured reader skips the tick instead of queueing\n * frames. The timer stops when the pipe settles, which covers both the source\n * completing and the reader cancelling, on every supported Node version.\n */\nexport function keepAliveSse(\n  source: ReadableStream<Uint8Array>,\n  idleMs: number,\n): ReadableStream<Uint8Array> {\n  let timer: ReturnType<typeof setTimeout> | undefined;\n  const stop = () => {\n    if (timer !== undefined) clearTimeout(timer);\n    timer = undefined;\n  };\n  const arm = (controller: TransformStreamDefaultController<Uint8Array>) => {\n    stop();\n    timer = setTimeout(() => {\n      // `desiredSize` is 1 only while the readable queue is empty; 0 means a\n      // slow reader still holds the previous chunk, null means it went away.\n      if (controller.desiredSize === 1) controller.enqueue(KEEP_ALIVE_FRAME);\n      arm(controller);\n    }, idleMs);\n    timer.unref?.();\n  };\n  const transform = new TransformStream<Uint8Array, Uint8Array>(\n    {\n      start: arm,\n      transform(chunk, controller) {\n        controller.enqueue(chunk);\n        arm(controller);\n      },\n      flush: stop,\n    },\n    undefined,\n    { highWaterMark: 1 },\n  );\n  // `flush` stops the timer when the source completes. The pipe settling\n  // covers the reader cancelling, on every supported Node version; the source\n  // writer surfaces that cancellation to the caller.\n  void source\n    .pipeTo(transform.writable)\n    .catch(() => {})\n    .finally(stop);\n  return transform.readable;\n}\n"],"mappings":";;;;;;;AAKA,MAAa,0CAA0C;;;;;;AAOvD,MAAa,uCAAuC,KAAK,KAAK,KAAK;;;;;;AAOnE,SAAgB,mCACd,OACQ;CACR,MAAM,UAAU,SAAS;AACzB,KACE,CAAC,OAAO,SAAS,QAAQ,IACzB,UAAU,KACV,UAAU,oCAEV,OAAM,IAAI,WACR,qDAAqD,oCAAoC,QAAQ,OAAO,MAAM,GAC/G;AAEH,QAAO;;;;;;;AAQT,MAAM,mBAAmB,IAAI,aAAa,CAAC,OAAO,mBAAmB;;;;;;;;;AAUrE,SAAgB,aACd,QACA,QAC4B;CAC5B,IAAI;CACJ,MAAM,aAAa;AACjB,MAAI,UAAU,OAAW,cAAa,MAAM;AAC5C,UAAQ;;CAEV,MAAM,OAAO,eAA6D;AACxE,QAAM;AACN,UAAQ,iBAAiB;AAGvB,OAAI,WAAW,gBAAgB,EAAG,YAAW,QAAQ,iBAAiB;AACtE,OAAI,WAAW;KACd,OAAO;AACV,QAAM,SAAS;;CAEjB,MAAM,YAAY,IAAI,gBACpB;EACE,OAAO;EACP,UAAU,OAAO,YAAY;AAC3B,cAAW,QAAQ,MAAM;AACzB,OAAI,WAAW;;EAEjB,OAAO;EACR,EACD,QACA,EAAE,eAAe,GAAG,CACrB;AAID,CAAK,OACF,OAAO,UAAU,SAAS,CAC1B,YAAY,GAAG,CACf,QAAQ,KAAK;AAChB,QAAO,UAAU"}