@copilotkit/runtime 2.0.0-next.1 → 2.0.0-rc.0

package/dist/runtime/core/fetch-router.cjs

@@ -0,0 +1,141 @@
+
+//#region src/runtime/core/fetch-router.ts
+/**
+* Match a request URL against known CopilotKit route patterns.
+*
+* @param pathname - The URL pathname to match
+* @param basePath - Optional base path prefix to strip first
+* @returns RouteInfo if matched, null otherwise
+*/
+function matchRoute(pathname, basePath) {
+	let remainder;
+	if (basePath) {
+		const normalizedBase = basePath.length > 1 && basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+		if (normalizedBase === "/") remainder = pathname;
+		else {
+			if (!pathname.startsWith(normalizedBase)) return null;
+			const afterBase = pathname.slice(normalizedBase.length);
+			if (afterBase.length > 0 && !afterBase.startsWith("/")) return null;
+			remainder = afterBase || "/";
+		}
+	} else remainder = pathname;
+	return matchSegments(remainder);
+}
+function safeDecodeURIComponent(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return null;
+	}
+}
+function matchSegments(path) {
+	const segments = path.split("/").filter(Boolean);
+	const len = segments.length;
+	if (len >= 1 && segments[len - 1] === "info") return { method: "info" };
+	if (len >= 1 && segments[len - 1] === "inspector-metadata") return { method: "inspector/metadata" };
+	if (len >= 1 && segments[len - 1] === "inspector-learning") return { method: "inspector/learning" };
+	if (len >= 1 && segments[len - 1] === "transcribe") return { method: "transcribe" };
+	if (len >= 1 && segments[len - 1] === "cpk-debug-events") return { method: "cpk-debug-events" };
+	if (len >= 3 && segments[len - 3] === "agent" && segments[len - 1] === "run") {
+		const agentId = safeDecodeURIComponent(segments[len - 2]);
+		if (!agentId) return null;
+		return {
+			method: "agent/run",
+			agentId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "agent" && segments[len - 1] === "suggest") {
+		const agentId = safeDecodeURIComponent(segments[len - 2]);
+		if (!agentId) return null;
+		return {
+			method: "agent/suggest",
+			agentId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "agent" && segments[len - 1] === "connect") {
+		const agentId = safeDecodeURIComponent(segments[len - 2]);
+		if (!agentId) return null;
+		return {
+			method: "agent/connect",
+			agentId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "trajectory" && segments[len - 1] === "connect") {
+		const trajectoryId = safeDecodeURIComponent(segments[len - 2]);
+		if (!trajectoryId) return null;
+		return {
+			method: "trajectory/connect",
+			trajectoryId
+		};
+	}
+	if (len >= 4 && segments[len - 4] === "agent" && segments[len - 2] === "stop") {
+		const agentId = safeDecodeURIComponent(segments[len - 3]);
+		const threadId = safeDecodeURIComponent(segments[len - 1]);
+		if (!agentId || !threadId) return null;
+		return {
+			method: "agent/stop",
+			agentId,
+			threadId
+		};
+	}
+	if (len >= 2 && segments[len - 2] === "threads" && segments[len - 1] === "subscribe") return { method: "threads/subscribe" };
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "messages") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/messages",
+			threadId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "events") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/events",
+			threadId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "state") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/state",
+			threadId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "archive") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/archive",
+			threadId
+		};
+	}
+	if (len >= 2 && segments[len - 2] === "threads" && segments[len - 1] === "clear") return { method: "threads/clear" };
+	if (len >= 2 && segments[len - 2] === "threads" && segments[len - 1] !== "subscribe" && segments[len - 1] !== "clear") {
+		const threadId = safeDecodeURIComponent(segments[len - 1]);
+		if (!threadId) return null;
+		return {
+			method: "threads/update",
+			threadId
+		};
+	}
+	if (len >= 1 && segments[len - 1] === "threads") return { method: "threads/list" };
+	if (len >= 2 && segments[len - 2] === "memories" && segments[len - 1] === "recall") return { method: "memories/recall" };
+	if (len >= 2 && segments[len - 2] === "memories" && segments[len - 1] === "subscribe") return { method: "memories/subscribe" };
+	if (len >= 2 && segments[len - 2] === "memories" && segments[len - 1] !== "subscribe") {
+		const memoryId = safeDecodeURIComponent(segments[len - 1]);
+		if (!memoryId) return null;
+		return {
+			method: "memories/mutate",
+			memoryId
+		};
+	}
+	if (len >= 1 && segments[len - 1] === "memories") return { method: "memories/list" };
+	if (len >= 1 && segments[len - 1] === "annotate") return { method: "annotate" };
+	return null;
+}
+
+//#endregion
+exports.matchRoute = matchRoute;
+//# sourceMappingURL=fetch-router.cjs.map

package/dist/runtime/core/fetch-router.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-router.cjs","names":[],"sources":["../../../src/runtime/core/fetch-router.ts"],"sourcesContent":["/**\n * Lightweight URL router for framework-agnostic CopilotKit runtime handler.\n *\n * Two strategies:\n * - With `basePath`: strict prefix strip → match remainder\n * - Without `basePath`: suffix matching on known patterns\n *\n * Single-route mode: delegates to `parseMethodCall` for JSON envelope dispatch.\n */\n\nimport type { RouteInfo } from \"./hooks\";\n\n/**\n * Match a request URL against known CopilotKit route patterns.\n *\n * @param pathname - The URL pathname to match\n * @param basePath - Optional base path prefix to strip first\n * @returns RouteInfo if matched, null otherwise\n */\nexport function matchRoute(\n  pathname: string,\n  basePath?: string,\n): RouteInfo | null {\n  let remainder: string;\n\n  if (basePath) {\n    // Normalize: ensure basePath doesn't end with /\n    const normalizedBase =\n      basePath.length > 1 && basePath.endsWith(\"/\")\n        ? basePath.slice(0, -1)\n        : basePath;\n\n    // Special case: basePath === \"/\" matches everything\n    if (normalizedBase === \"/\") {\n      remainder = pathname;\n    } else {\n      if (!pathname.startsWith(normalizedBase)) return null;\n\n      // The character after basePath must be \"/\" or end of string\n      const afterBase = pathname.slice(normalizedBase.length);\n      if (afterBase.length > 0 && !afterBase.startsWith(\"/\")) return null;\n\n      remainder = afterBase || \"/\";\n    }\n  } else {\n    // Suffix matching: find known patterns at the end of the pathname\n    remainder = pathname;\n  }\n\n  return matchSegments(remainder);\n}\n\nfunction safeDecodeURIComponent(value: string): string | null {\n  try {\n    return decodeURIComponent(value);\n  } catch {\n    return null;\n  }\n}\n\nfunction matchSegments(path: string): RouteInfo | null {\n  const segments = path.split(\"/\").filter(Boolean);\n  const len = segments.length;\n\n  // Try suffix matching — scan from the end for known patterns\n\n  // /info (1 segment)\n  if (len >= 1 && segments[len - 1] === \"info\") {\n    return { method: \"info\" };\n  }\n\n  // /inspector-metadata (1 segment)\n  if (len >= 1 && segments[len - 1] === \"inspector-metadata\") {\n    return { method: \"inspector/metadata\" };\n  }\n\n  // /inspector-learning (1 segment)\n  if (len >= 1 && segments[len - 1] === \"inspector-learning\") {\n    return { method: \"inspector/learning\" };\n  }\n\n  // /transcribe (1 segment)\n  if (len >= 1 && segments[len - 1] === \"transcribe\") {\n    return { method: \"transcribe\" };\n  }\n\n  // /cpk-debug-events (1 segment)\n  // Reserved route name: the `cpk-` prefix makes collision with a\n  // user-named agent essentially impossible (the router only treats\n  // `agent/:agentId/...` patterns as agent lookups, so a bare\n  // `cpk-debug-events` segment would never fall through to one —\n  // the prefix is the real guard, not this branch's position).\n  // Handler returns 404 in production.\n  if (len >= 1 && segments[len - 1] === \"cpk-debug-events\") {\n    return { method: \"cpk-debug-events\" };\n  }\n\n  // /agent/:agentId/run (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"agent\" &&\n    segments[len - 1] === \"run\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!agentId) return null;\n    return { method: \"agent/run\", agentId };\n  }\n\n  // /agent/:agentId/suggest (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"agent\" &&\n    segments[len - 1] === \"suggest\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!agentId) return null;\n    return { method: \"agent/suggest\", agentId };\n  }\n\n  // /agent/:agentId/connect (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"agent\" &&\n    segments[len - 1] === \"connect\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!agentId) return null;\n    return { method: \"agent/connect\", agentId };\n  }\n\n  // /trajectory/:trajectoryId/connect (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"trajectory\" &&\n    segments[len - 1] === \"connect\"\n  ) {\n    const trajectoryId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!trajectoryId) return null;\n    return { method: \"trajectory/connect\", trajectoryId };\n  }\n\n  // /agent/:agentId/stop/:threadId (4 segments)\n  if (\n    len >= 4 &&\n    segments[len - 4] === \"agent\" &&\n    segments[len - 2] === \"stop\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 3]!);\n    const threadId = safeDecodeURIComponent(segments[len - 1]!);\n    if (!agentId || !threadId) return null;\n    return { method: \"agent/stop\", agentId, threadId };\n  }\n\n  // /threads/subscribe (2 segments)\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"threads\" &&\n    segments[len - 1] === \"subscribe\"\n  ) {\n    return { method: \"threads/subscribe\" };\n  }\n\n  // /threads/:threadId/messages (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"messages\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/messages\", threadId };\n  }\n\n  // /threads/:threadId/events (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"events\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/events\", threadId };\n  }\n\n  // /threads/:threadId/state (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"state\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/state\", threadId };\n  }\n\n  // /threads/:threadId/archive (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"archive\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/archive\", threadId };\n  }\n\n  // /threads/clear (2 segments) — wipe in-memory thread history\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"threads\" &&\n    segments[len - 1] === \"clear\"\n  ) {\n    return { method: \"threads/clear\" };\n  }\n\n  // /threads/:threadId (2 segments) — update or delete\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"threads\" &&\n    segments[len - 1] !== \"subscribe\" &&\n    segments[len - 1] !== \"clear\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 1]!);\n    if (!threadId) return null;\n    // Disambiguated by HTTP method in the handler\n    return { method: \"threads/update\", threadId };\n  }\n\n  // /threads (1 segment) — list\n  if (len >= 1 && segments[len - 1] === \"threads\") {\n    return { method: \"threads/list\" };\n  }\n\n  // /memories/recall (2 segments) — semantic recall (POST). Must precede the\n  // /memories/:id mutate rule below, which would otherwise capture \"recall\".\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"memories\" &&\n    segments[len - 1] === \"recall\"\n  ) {\n    return { method: \"memories/recall\" };\n  }\n\n  // /memories/subscribe (2 segments) — mint memory-realtime join credentials.\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"memories\" &&\n    segments[len - 1] === \"subscribe\"\n  ) {\n    return { method: \"memories/subscribe\" };\n  }\n\n  // /memories/:id (2 segments) — supersede (PATCH) or retire (DELETE).\n  // Disambiguated by HTTP method in the handler.\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"memories\" &&\n    segments[len - 1] !== \"subscribe\"\n  ) {\n    const memoryId = safeDecodeURIComponent(segments[len - 1]!);\n    if (!memoryId) return null;\n    return { method: \"memories/mutate\", memoryId };\n  }\n\n  // /memories (1 segment) — GET lists; POST creates.\n  if (len >= 1 && segments[len - 1] === \"memories\") {\n    return { method: \"memories/list\" };\n  }\n\n  // /annotate (1 segment) — annotate a thread event\n  if (len >= 1 && segments[len - 1] === \"annotate\") {\n    return { method: \"annotate\" };\n  }\n\n  return null;\n}\n"],"mappings":";;;;;;;;;AAmBA,SAAgB,WACd,UACA,UACkB;CAClB,IAAI;AAEJ,KAAI,UAAU;EAEZ,MAAM,iBACJ,SAAS,SAAS,KAAK,SAAS,SAAS,IAAI,GACzC,SAAS,MAAM,GAAG,GAAG,GACrB;AAGN,MAAI,mBAAmB,IACrB,aAAY;OACP;AACL,OAAI,CAAC,SAAS,WAAW,eAAe,CAAE,QAAO;GAGjD,MAAM,YAAY,SAAS,MAAM,eAAe,OAAO;AACvD,OAAI,UAAU,SAAS,KAAK,CAAC,UAAU,WAAW,IAAI,CAAE,QAAO;AAE/D,eAAY,aAAa;;OAI3B,aAAY;AAGd,QAAO,cAAc,UAAU;;AAGjC,SAAS,uBAAuB,OAA8B;AAC5D,KAAI;AACF,SAAO,mBAAmB,MAAM;SAC1B;AACN,SAAO;;;AAIX,SAAS,cAAc,MAAgC;CACrD,MAAM,WAAW,KAAK,MAAM,IAAI,CAAC,OAAO,QAAQ;CAChD,MAAM,MAAM,SAAS;AAKrB,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,OACpC,QAAO,EAAE,QAAQ,QAAQ;AAI3B,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,qBACpC,QAAO,EAAE,QAAQ,sBAAsB;AAIzC,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,qBACpC,QAAO,EAAE,QAAQ,sBAAsB;AAIzC,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,aACpC,QAAO,EAAE,QAAQ,cAAc;AAUjC,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,mBACpC,QAAO,EAAE,QAAQ,oBAAoB;AAIvC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,WACtB,SAAS,MAAM,OAAO,OACtB;EACA,MAAM,UAAU,uBAAuB,SAAS,MAAM,GAAI;AAC1D,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO;GAAE,QAAQ;GAAa;GAAS;;AAIzC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,WACtB,SAAS,MAAM,OAAO,WACtB;EACA,MAAM,UAAU,uBAAuB,SAAS,MAAM,GAAI;AAC1D,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO;GAAE,QAAQ;GAAiB;GAAS;;AAI7C,KACE,OAAO,KACP,SAAS,MAAM,OAAO,WACtB,SAAS,MAAM,OAAO,WACtB;EACA,MAAM,UAAU,uBAAuB,SAAS,MAAM,GAAI;AAC1D,MAAI,CAAC,QAAS,QAAO;AACrB,SAAO;GAAE,QAAQ;GAAiB;GAAS;;AAI7C,KACE,OAAO,KACP,SAAS,MAAM,OAAO,gBACtB,SAAS,MAAM,OAAO,WACtB;EACA,MAAM,eAAe,uBAAuB,SAAS,MAAM,GAAI;AAC/D,MAAI,CAAC,aAAc,QAAO;AAC1B,SAAO;GAAE,QAAQ;GAAsB;GAAc;;AAIvD,KACE,OAAO,KACP,SAAS,MAAM,OAAO,WACtB,SAAS,MAAM,OAAO,QACtB;EACA,MAAM,UAAU,uBAAuB,SAAS,MAAM,GAAI;EAC1D,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,WAAW,CAAC,SAAU,QAAO;AAClC,SAAO;GAAE,QAAQ;GAAc;GAAS;GAAU;;AAIpD,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,YAEtB,QAAO,EAAE,QAAQ,qBAAqB;AAIxC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,YACtB;EACA,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO;GAAE,QAAQ;GAAoB;GAAU;;AAIjD,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,UACtB;EACA,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO;GAAE,QAAQ;GAAkB;GAAU;;AAI/C,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,SACtB;EACA,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO;GAAE,QAAQ;GAAiB;GAAU;;AAI9C,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,WACtB;EACA,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO;GAAE,QAAQ;GAAmB;GAAU;;AAIhD,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,QAEtB,QAAO,EAAE,QAAQ,iBAAiB;AAIpC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,aACtB,SAAS,MAAM,OAAO,eACtB,SAAS,MAAM,OAAO,SACtB;EACA,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,SAAU,QAAO;AAEtB,SAAO;GAAE,QAAQ;GAAkB;GAAU;;AAI/C,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,UACpC,QAAO,EAAE,QAAQ,gBAAgB;AAKnC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,cACtB,SAAS,MAAM,OAAO,SAEtB,QAAO,EAAE,QAAQ,mBAAmB;AAItC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,cACtB,SAAS,MAAM,OAAO,YAEtB,QAAO,EAAE,QAAQ,sBAAsB;AAKzC,KACE,OAAO,KACP,SAAS,MAAM,OAAO,cACtB,SAAS,MAAM,OAAO,aACtB;EACA,MAAM,WAAW,uBAAuB,SAAS,MAAM,GAAI;AAC3D,MAAI,CAAC,SAAU,QAAO;AACtB,SAAO;GAAE,QAAQ;GAAmB;GAAU;;AAIhD,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,WACpC,QAAO,EAAE,QAAQ,iBAAiB;AAIpC,KAAI,OAAO,KAAK,SAAS,MAAM,OAAO,WACpC,QAAO,EAAE,QAAQ,YAAY;AAG/B,QAAO"}

package/dist/runtime/core/fetch-router.mjs

@@ -0,0 +1,140 @@
+//#region src/runtime/core/fetch-router.ts
+/**
+* Match a request URL against known CopilotKit route patterns.
+*
+* @param pathname - The URL pathname to match
+* @param basePath - Optional base path prefix to strip first
+* @returns RouteInfo if matched, null otherwise
+*/
+function matchRoute(pathname, basePath) {
+	let remainder;
+	if (basePath) {
+		const normalizedBase = basePath.length > 1 && basePath.endsWith("/") ? basePath.slice(0, -1) : basePath;
+		if (normalizedBase === "/") remainder = pathname;
+		else {
+			if (!pathname.startsWith(normalizedBase)) return null;
+			const afterBase = pathname.slice(normalizedBase.length);
+			if (afterBase.length > 0 && !afterBase.startsWith("/")) return null;
+			remainder = afterBase || "/";
+		}
+	} else remainder = pathname;
+	return matchSegments(remainder);
+}
+function safeDecodeURIComponent(value) {
+	try {
+		return decodeURIComponent(value);
+	} catch {
+		return null;
+	}
+}
+function matchSegments(path) {
+	const segments = path.split("/").filter(Boolean);
+	const len = segments.length;
+	if (len >= 1 && segments[len - 1] === "info") return { method: "info" };
+	if (len >= 1 && segments[len - 1] === "inspector-metadata") return { method: "inspector/metadata" };
+	if (len >= 1 && segments[len - 1] === "inspector-learning") return { method: "inspector/learning" };
+	if (len >= 1 && segments[len - 1] === "transcribe") return { method: "transcribe" };
+	if (len >= 1 && segments[len - 1] === "cpk-debug-events") return { method: "cpk-debug-events" };
+	if (len >= 3 && segments[len - 3] === "agent" && segments[len - 1] === "run") {
+		const agentId = safeDecodeURIComponent(segments[len - 2]);
+		if (!agentId) return null;
+		return {
+			method: "agent/run",
+			agentId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "agent" && segments[len - 1] === "suggest") {
+		const agentId = safeDecodeURIComponent(segments[len - 2]);
+		if (!agentId) return null;
+		return {
+			method: "agent/suggest",
+			agentId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "agent" && segments[len - 1] === "connect") {
+		const agentId = safeDecodeURIComponent(segments[len - 2]);
+		if (!agentId) return null;
+		return {
+			method: "agent/connect",
+			agentId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "trajectory" && segments[len - 1] === "connect") {
+		const trajectoryId = safeDecodeURIComponent(segments[len - 2]);
+		if (!trajectoryId) return null;
+		return {
+			method: "trajectory/connect",
+			trajectoryId
+		};
+	}
+	if (len >= 4 && segments[len - 4] === "agent" && segments[len - 2] === "stop") {
+		const agentId = safeDecodeURIComponent(segments[len - 3]);
+		const threadId = safeDecodeURIComponent(segments[len - 1]);
+		if (!agentId || !threadId) return null;
+		return {
+			method: "agent/stop",
+			agentId,
+			threadId
+		};
+	}
+	if (len >= 2 && segments[len - 2] === "threads" && segments[len - 1] === "subscribe") return { method: "threads/subscribe" };
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "messages") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/messages",
+			threadId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "events") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/events",
+			threadId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "state") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/state",
+			threadId
+		};
+	}
+	if (len >= 3 && segments[len - 3] === "threads" && segments[len - 1] === "archive") {
+		const threadId = safeDecodeURIComponent(segments[len - 2]);
+		if (!threadId) return null;
+		return {
+			method: "threads/archive",
+			threadId
+		};
+	}
+	if (len >= 2 && segments[len - 2] === "threads" && segments[len - 1] === "clear") return { method: "threads/clear" };
+	if (len >= 2 && segments[len - 2] === "threads" && segments[len - 1] !== "subscribe" && segments[len - 1] !== "clear") {
+		const threadId = safeDecodeURIComponent(segments[len - 1]);
+		if (!threadId) return null;
+		return {
+			method: "threads/update",
+			threadId
+		};
+	}
+	if (len >= 1 && segments[len - 1] === "threads") return { method: "threads/list" };
+	if (len >= 2 && segments[len - 2] === "memories" && segments[len - 1] === "recall") return { method: "memories/recall" };
+	if (len >= 2 && segments[len - 2] === "memories" && segments[len - 1] === "subscribe") return { method: "memories/subscribe" };
+	if (len >= 2 && segments[len - 2] === "memories" && segments[len - 1] !== "subscribe") {
+		const memoryId = safeDecodeURIComponent(segments[len - 1]);
+		if (!memoryId) return null;
+		return {
+			method: "memories/mutate",
+			memoryId
+		};
+	}
+	if (len >= 1 && segments[len - 1] === "memories") return { method: "memories/list" };
+	if (len >= 1 && segments[len - 1] === "annotate") return { method: "annotate" };
+	return null;
+}
+
+//#endregion
+export { matchRoute };
+//# sourceMappingURL=fetch-router.mjs.map

package/dist/runtime/core/fetch-router.mjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"fetch-router.mjs","names":[],"sources":["../../../src/runtime/core/fetch-router.ts"],"sourcesContent":["/**\n * Lightweight URL router for framework-agnostic CopilotKit runtime handler.\n *\n * Two strategies:\n * - With `basePath`: strict prefix strip → match remainder\n * - Without `basePath`: suffix matching on known patterns\n *\n * Single-route mode: delegates to `parseMethodCall` for JSON envelope dispatch.\n */\n\nimport type { RouteInfo } from \"./hooks\";\n\n/**\n * Match a request URL against known CopilotKit route patterns.\n *\n * @param pathname - The URL pathname to match\n * @param basePath - Optional base path prefix to strip first\n * @returns RouteInfo if matched, null otherwise\n */\nexport function matchRoute(\n  pathname: string,\n  basePath?: string,\n): RouteInfo | null {\n  let remainder: string;\n\n  if (basePath) {\n    // Normalize: ensure basePath doesn't end with /\n    const normalizedBase =\n      basePath.length > 1 && basePath.endsWith(\"/\")\n        ? basePath.slice(0, -1)\n        : basePath;\n\n    // Special case: basePath === \"/\" matches everything\n    if (normalizedBase === \"/\") {\n      remainder = pathname;\n    } else {\n      if (!pathname.startsWith(normalizedBase)) return null;\n\n      // The character after basePath must be \"/\" or end of string\n      const afterBase = pathname.slice(normalizedBase.length);\n      if (afterBase.length > 0 && !afterBase.startsWith(\"/\")) return null;\n\n      remainder = afterBase || \"/\";\n    }\n  } else {\n    // Suffix matching: find known patterns at the end of the pathname\n    remainder = pathname;\n  }\n\n  return matchSegments(remainder);\n}\n\nfunction safeDecodeURIComponent(value: string): string | null {\n  try {\n    return decodeURIComponent(value);\n  } catch {\n    return null;\n  }\n}\n\nfunction matchSegments(path: string): RouteInfo | null {\n  const segments = path.split(\"/\").filter(Boolean);\n  const len = segments.length;\n\n  // Try suffix matching — scan from the end for known patterns\n\n  // /info (1 segment)\n  if (len >= 1 && segments[len - 1] === \"info\") {\n    return { method: \"info\" };\n  }\n\n  // /inspector-metadata (1 segment)\n  if (len >= 1 && segments[len - 1] === \"inspector-metadata\") {\n    return { method: \"inspector/metadata\" };\n  }\n\n  // /inspector-learning (1 segment)\n  if (len >= 1 && segments[len - 1] === \"inspector-learning\") {\n    return { method: \"inspector/learning\" };\n  }\n\n  // /transcribe (1 segment)\n  if (len >= 1 && segments[len - 1] === \"transcribe\") {\n    return { method: \"transcribe\" };\n  }\n\n  // /cpk-debug-events (1 segment)\n  // Reserved route name: the `cpk-` prefix makes collision with a\n  // user-named agent essentially impossible (the router only treats\n  // `agent/:agentId/...` patterns as agent lookups, so a bare\n  // `cpk-debug-events` segment would never fall through to one —\n  // the prefix is the real guard, not this branch's position).\n  // Handler returns 404 in production.\n  if (len >= 1 && segments[len - 1] === \"cpk-debug-events\") {\n    return { method: \"cpk-debug-events\" };\n  }\n\n  // /agent/:agentId/run (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"agent\" &&\n    segments[len - 1] === \"run\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!agentId) return null;\n    return { method: \"agent/run\", agentId };\n  }\n\n  // /agent/:agentId/suggest (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"agent\" &&\n    segments[len - 1] === \"suggest\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!agentId) return null;\n    return { method: \"agent/suggest\", agentId };\n  }\n\n  // /agent/:agentId/connect (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"agent\" &&\n    segments[len - 1] === \"connect\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!agentId) return null;\n    return { method: \"agent/connect\", agentId };\n  }\n\n  // /trajectory/:trajectoryId/connect (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"trajectory\" &&\n    segments[len - 1] === \"connect\"\n  ) {\n    const trajectoryId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!trajectoryId) return null;\n    return { method: \"trajectory/connect\", trajectoryId };\n  }\n\n  // /agent/:agentId/stop/:threadId (4 segments)\n  if (\n    len >= 4 &&\n    segments[len - 4] === \"agent\" &&\n    segments[len - 2] === \"stop\"\n  ) {\n    const agentId = safeDecodeURIComponent(segments[len - 3]!);\n    const threadId = safeDecodeURIComponent(segments[len - 1]!);\n    if (!agentId || !threadId) return null;\n    return { method: \"agent/stop\", agentId, threadId };\n  }\n\n  // /threads/subscribe (2 segments)\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"threads\" &&\n    segments[len - 1] === \"subscribe\"\n  ) {\n    return { method: \"threads/subscribe\" };\n  }\n\n  // /threads/:threadId/messages (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"messages\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/messages\", threadId };\n  }\n\n  // /threads/:threadId/events (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"events\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/events\", threadId };\n  }\n\n  // /threads/:threadId/state (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"state\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/state\", threadId };\n  }\n\n  // /threads/:threadId/archive (3 segments)\n  if (\n    len >= 3 &&\n    segments[len - 3] === \"threads\" &&\n    segments[len - 1] === \"archive\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 2]!);\n    if (!threadId) return null;\n    return { method: \"threads/archive\", threadId };\n  }\n\n  // /threads/clear (2 segments) — wipe in-memory thread history\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"threads\" &&\n    segments[len - 1] === \"clear\"\n  ) {\n    return { method: \"threads/clear\" };\n  }\n\n  // /threads/:threadId (2 segments) — update or delete\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"threads\" &&\n    segments[len - 1] !== \"subscribe\" &&\n    segments[len - 1] !== \"clear\"\n  ) {\n    const threadId = safeDecodeURIComponent(segments[len - 1]!);\n    if (!threadId) return null;\n    // Disambiguated by HTTP method in the handler\n    return { method: \"threads/update\", threadId };\n  }\n\n  // /threads (1 segment) — list\n  if (len >= 1 && segments[len - 1] === \"threads\") {\n    return { method: \"threads/list\" };\n  }\n\n  // /memories/recall (2 segments) — semantic recall (POST). Must precede the\n  // /memories/:id mutate rule below, which would otherwise capture \"recall\".\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"memories\" &&\n    segments[len - 1] === \"recall\"\n  ) {\n    return { method: \"memories/recall\" };\n  }\n\n  // /memories/subscribe (2 segments) — mint memory-realtime join credentials.\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"memories\" &&\n    segments[len - 1] === \"subscribe\"\n  ) {\n    return { method: \"memories/subscribe\" };\n  }\n\n  // /memories/:id (2 segments) — supersede (PATCH) or retire (DELETE).\n  // Disambiguated by HTTP method in the handler.\n  if (\n    len >= 2 &&\n    segments[len - 2] === \"memories\" &&\n    segments[len - 1] !== \"subscribe\"\n  ) {\n    const memoryId = safeDecodeURIComponent(segments[len - 1]!);\n    if (!memoryId) return null;\n    return { method: \"memories/mutate\", memoryId };\n  }\n\n  // /memories (1 segment) — GET lists; POST creates.\n  if (len >= 1 && segments[len - 1] === \"memories\") {\n    return { method: \"memories/list\" };\n  }\n\n  // /annotate (1 segment) — annotate a thread event\n  if (len >= 1 && segments[len - 1] === \"annotate\") {\n    return { method: \"annotate\" };\n  }\n\n  return null;\n}\n"],"mappings":"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"}

package/dist/runtime/core/hooks.cjs

@@ -0,0 +1,28 @@
+
+//#region src/runtime/core/hooks.ts
+async function runOnRequest(hooks, ctx) {
+	if (!hooks?.onRequest) return ctx.request;
+	const result = await hooks.onRequest(ctx);
+	return result instanceof Request ? result : ctx.request;
+}
+async function runOnBeforeHandler(hooks, ctx) {
+	if (!hooks?.onBeforeHandler) return ctx.request;
+	const result = await hooks.onBeforeHandler(ctx);
+	return result instanceof Request ? result : ctx.request;
+}
+async function runOnResponse(hooks, ctx) {
+	if (!hooks?.onResponse) return ctx.response;
+	const result = await hooks.onResponse(ctx);
+	return result instanceof Response ? result : ctx.response;
+}
+async function runOnError(hooks, ctx) {
+	if (!hooks?.onError) return;
+	return hooks.onError(ctx);
+}
+
+//#endregion
+exports.runOnBeforeHandler = runOnBeforeHandler;
+exports.runOnError = runOnError;
+exports.runOnRequest = runOnRequest;
+exports.runOnResponse = runOnResponse;
+//# sourceMappingURL=hooks.cjs.map

package/dist/runtime/core/hooks.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.cjs","names":[],"sources":["../../../src/runtime/core/hooks.ts"],"sourcesContent":["/**\n * Lifecycle hooks for CopilotKit runtime request processing.\n *\n * Hooks let you intercept requests at various stages of the pipeline:\n * - `onRequest`: Before routing — auth, correlation IDs, header injection\n * - `onBeforeHandler`: After routing — route-specific authorization\n * - `onResponse`: After handler — add headers, log, set cookies\n * - `onError`: On error — custom error responses\n *\n * @example\n * ```typescript\n * const handler = createCopilotRuntimeHandler({\n *   runtime,\n *   hooks: {\n *     onRequest: async ({ request }) => {\n *       const token = request.headers.get(\"authorization\");\n *       if (!token) throw new Response(\"Unauthorized\", { status: 401 });\n *     },\n *     onResponse: async ({ response }) => {\n *       const headers = new Headers(response.headers);\n *       headers.set(\"x-copilot-version\", \"2.0\");\n *       return new Response(response.body, { ...response, headers });\n *     },\n *   },\n * });\n * ```\n */\n\nimport type { MaybePromise } from \"@copilotkit/shared\";\nimport type { CopilotRuntimeLike } from \"./runtime\";\n\n/* ------------------------------------------------------------------------------------------------\n * Route info\n * --------------------------------------------------------------------------------------------- */\n\nexport type RouteInfo =\n  | { method: \"agent/run\"; agentId: string }\n  | { method: \"agent/suggest\"; agentId: string }\n  | { method: \"agent/connect\"; agentId: string }\n  | { method: \"trajectory/connect\"; trajectoryId: string }\n  | { method: \"agent/stop\"; agentId: string; threadId: string }\n  | { method: \"info\" }\n  | { method: \"inspector/metadata\" }\n  | { method: \"inspector/learning\" }\n  | { method: \"transcribe\" }\n  | { method: \"threads/list\" }\n  | { method: \"threads/subscribe\" }\n  | { method: \"threads/update\"; threadId: string }\n  | { method: \"threads/archive\"; threadId: string }\n  | { method: \"threads/messages\"; threadId: string }\n  | { method: \"threads/events\"; threadId: string }\n  | { method: \"threads/state\"; threadId: string }\n  | { method: \"threads/clear\" }\n  | { method: \"memories/list\" }\n  | { method: \"memories/recall\" }\n  | { method: \"memories/subscribe\" }\n  | { method: \"memories/mutate\"; memoryId: string }\n  | { method: \"annotate\" }\n  | { method: \"cpk-debug-events\" };\n\n/* ------------------------------------------------------------------------------------------------\n * Hook contexts\n * --------------------------------------------------------------------------------------------- */\n\nexport interface HookContext {\n  /** The incoming Fetch Request (possibly modified by prior hooks). */\n  request: Request;\n  /** The resolved URL pathname. */\n  path: string;\n  /** The CopilotRuntimeLike instance. */\n  runtime: CopilotRuntimeLike;\n}\n\nexport interface HandlerHookContext extends HookContext {\n  /** The resolved route information. */\n  route: RouteInfo;\n}\n\nexport interface ResponseHookContext extends HookContext {\n  /** The Response produced by the handler. */\n  response: Response;\n  /** The resolved route information. */\n  route: RouteInfo;\n}\n\nexport interface ErrorHookContext extends HookContext {\n  /** The error that occurred. */\n  error: unknown;\n  /** The route info, if routing had already succeeded. */\n  route?: RouteInfo;\n}\n\n/* ------------------------------------------------------------------------------------------------\n * Hooks interface\n * --------------------------------------------------------------------------------------------- */\n\nexport interface CopilotRuntimeHooks {\n  /**\n   * Called at the start of every request, before routing.\n   * Use to validate auth, attach headers, initialize correlation IDs, etc.\n   *\n   * Return a modified Request to replace the original, or void to continue.\n   * Throw a Response to short-circuit with an early response.\n   */\n  onRequest?: (ctx: HookContext) => MaybePromise<Request | void>;\n\n  /**\n   * Called after routing is resolved but before the handler executes.\n   * Receives the resolved route info (method, agentId, threadId).\n   *\n   * Use to do route-specific authorization, attach headers for agent calls, etc.\n   * Return a modified Request or void.\n   * Throw a Response to short-circuit.\n   */\n  onBeforeHandler?: (ctx: HandlerHookContext) => MaybePromise<Request | void>;\n\n  /**\n   * Called after the handler produces a Response, before it's sent to the client.\n   * Use to set cookies, add debugging headers, log, etc.\n   *\n   * Return a modified Response to replace the original, or void.\n   */\n  onResponse?: (ctx: ResponseHookContext) => MaybePromise<Response | void>;\n\n  /**\n   * Called when an error occurs during request processing.\n   * Return a Response to override the default error response, or void to use the default.\n   */\n  onError?: (ctx: ErrorHookContext) => MaybePromise<Response | void>;\n}\n\n/* ------------------------------------------------------------------------------------------------\n * Internal hook runners\n * --------------------------------------------------------------------------------------------- */\n\nexport async function runOnRequest(\n  hooks: CopilotRuntimeHooks | undefined,\n  ctx: HookContext,\n): Promise<Request> {\n  if (!hooks?.onRequest) return ctx.request;\n  const result = await hooks.onRequest(ctx);\n  return result instanceof Request ? result : ctx.request;\n}\n\nexport async function runOnBeforeHandler(\n  hooks: CopilotRuntimeHooks | undefined,\n  ctx: HandlerHookContext,\n): Promise<Request> {\n  if (!hooks?.onBeforeHandler) return ctx.request;\n  const result = await hooks.onBeforeHandler(ctx);\n  return result instanceof Request ? result : ctx.request;\n}\n\nexport async function runOnResponse(\n  hooks: CopilotRuntimeHooks | undefined,\n  ctx: ResponseHookContext,\n): Promise<Response> {\n  if (!hooks?.onResponse) return ctx.response;\n  const result = await hooks.onResponse(ctx);\n  return result instanceof Response ? result : ctx.response;\n}\n\nexport async function runOnError(\n  hooks: CopilotRuntimeHooks | undefined,\n  ctx: ErrorHookContext,\n): Promise<Response | void> {\n  if (!hooks?.onError) return;\n  return hooks.onError(ctx);\n}\n"],"mappings":";;AAuIA,eAAsB,aACpB,OACA,KACkB;AAClB,KAAI,CAAC,OAAO,UAAW,QAAO,IAAI;CAClC,MAAM,SAAS,MAAM,MAAM,UAAU,IAAI;AACzC,QAAO,kBAAkB,UAAU,SAAS,IAAI;;AAGlD,eAAsB,mBACpB,OACA,KACkB;AAClB,KAAI,CAAC,OAAO,gBAAiB,QAAO,IAAI;CACxC,MAAM,SAAS,MAAM,MAAM,gBAAgB,IAAI;AAC/C,QAAO,kBAAkB,UAAU,SAAS,IAAI;;AAGlD,eAAsB,cACpB,OACA,KACmB;AACnB,KAAI,CAAC,OAAO,WAAY,QAAO,IAAI;CACnC,MAAM,SAAS,MAAM,MAAM,WAAW,IAAI;AAC1C,QAAO,kBAAkB,WAAW,SAAS,IAAI;;AAGnD,eAAsB,WACpB,OACA,KAC0B;AAC1B,KAAI,CAAC,OAAO,QAAS;AACrB,QAAO,MAAM,QAAQ,IAAI"}

package/dist/runtime/core/hooks.d.cts

@@ -0,0 +1,121 @@
+import { CopilotRuntimeLike } from "./runtime.cjs";
+import { MaybePromise } from "@copilotkit/shared";
+
+//#region src/runtime/core/hooks.d.ts
+type RouteInfo = {
+  method: "agent/run";
+  agentId: string;
+} | {
+  method: "agent/suggest";
+  agentId: string;
+} | {
+  method: "agent/connect";
+  agentId: string;
+} | {
+  method: "trajectory/connect";
+  trajectoryId: string;
+} | {
+  method: "agent/stop";
+  agentId: string;
+  threadId: string;
+} | {
+  method: "info";
+} | {
+  method: "inspector/metadata";
+} | {
+  method: "inspector/learning";
+} | {
+  method: "transcribe";
+} | {
+  method: "threads/list";
+} | {
+  method: "threads/subscribe";
+} | {
+  method: "threads/update";
+  threadId: string;
+} | {
+  method: "threads/archive";
+  threadId: string;
+} | {
+  method: "threads/messages";
+  threadId: string;
+} | {
+  method: "threads/events";
+  threadId: string;
+} | {
+  method: "threads/state";
+  threadId: string;
+} | {
+  method: "threads/clear";
+} | {
+  method: "memories/list";
+} | {
+  method: "memories/recall";
+} | {
+  method: "memories/subscribe";
+} | {
+  method: "memories/mutate";
+  memoryId: string;
+} | {
+  method: "annotate";
+} | {
+  method: "cpk-debug-events";
+};
+interface HookContext {
+  /** The incoming Fetch Request (possibly modified by prior hooks). */
+  request: Request;
+  /** The resolved URL pathname. */
+  path: string;
+  /** The CopilotRuntimeLike instance. */
+  runtime: CopilotRuntimeLike;
+}
+interface HandlerHookContext extends HookContext {
+  /** The resolved route information. */
+  route: RouteInfo;
+}
+interface ResponseHookContext extends HookContext {
+  /** The Response produced by the handler. */
+  response: Response;
+  /** The resolved route information. */
+  route: RouteInfo;
+}
+interface ErrorHookContext extends HookContext {
+  /** The error that occurred. */
+  error: unknown;
+  /** The route info, if routing had already succeeded. */
+  route?: RouteInfo;
+}
+interface CopilotRuntimeHooks {
+  /**
+   * Called at the start of every request, before routing.
+   * Use to validate auth, attach headers, initialize correlation IDs, etc.
+   *
+   * Return a modified Request to replace the original, or void to continue.
+   * Throw a Response to short-circuit with an early response.
+   */
+  onRequest?: (ctx: HookContext) => MaybePromise<Request | void>;
+  /**
+   * Called after routing is resolved but before the handler executes.
+   * Receives the resolved route info (method, agentId, threadId).
+   *
+   * Use to do route-specific authorization, attach headers for agent calls, etc.
+   * Return a modified Request or void.
+   * Throw a Response to short-circuit.
+   */
+  onBeforeHandler?: (ctx: HandlerHookContext) => MaybePromise<Request | void>;
+  /**
+   * Called after the handler produces a Response, before it's sent to the client.
+   * Use to set cookies, add debugging headers, log, etc.
+   *
+   * Return a modified Response to replace the original, or void.
+   */
+  onResponse?: (ctx: ResponseHookContext) => MaybePromise<Response | void>;
+  /**
+   * Called when an error occurs during request processing.
+   * Return a Response to override the default error response, or void to use the default.
+   */
+  onError?: (ctx: ErrorHookContext) => MaybePromise<Response | void>;
+}
+//#endregion
+export { CopilotRuntimeHooks, ErrorHookContext, HandlerHookContext, HookContext, ResponseHookContext, RouteInfo };
+//# sourceMappingURL=hooks.d.cts.map

package/dist/runtime/core/hooks.d.cts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.cts","names":[],"sources":["../../../src/runtime/core/hooks.ts"],"mappings":";;;;KAmCY,SAAA;EACN,MAAA;EAAqB,OAAA;AAAA;EACrB,MAAA;EAAyB,OAAA;AAAA;EACzB,MAAA;EAAyB,OAAA;AAAA;EACzB,MAAA;EAA8B,YAAA;AAAA;EAC9B,MAAA;EAAsB,OAAA;EAAiB,QAAA;AAAA;EACvC,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;EAA0B,QAAA;AAAA;EAC1B,MAAA;EAA2B,QAAA;AAAA;EAC3B,MAAA;EAA4B,QAAA;AAAA;EAC5B,MAAA;EAA0B,QAAA;AAAA;EAC1B,MAAA;EAAyB,QAAA;AAAA;EACzB,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;EAA2B,QAAA;AAAA;EAC3B,MAAA;AAAA;EACA,MAAA;AAAA;AAAA,UAMW,WAAA;EAyBE;EAvBjB,OAAA,EAAS,OAAA;EA8ByB;EA5BlC,IAAA;EAoCkB;EAlClB,OAAA,EAAS,kBAAA;AAAA;AAAA,UAGM,kBAAA,SAA2B,WAAA;EAyCkB;EAvC5D,KAAA,EAAO,SAAA;AAAA;AAAA,UAGQ,mBAAA,SAA4B,WAAA;EA4CA;EA1C3C,QAAA,EAAU,QAAA;EAgDwC;EA9ClD,KAAA,EAAO,SAAA;AAAA;AAAA,UAGQ,gBAAA,SAAyB,WAAA;EAmBxC;EAjBA,KAAA;EAiBa;EAfb,KAAA,GAAQ,SAAA;AAAA;AAAA,UAOO,mBAAA;EAkBS;;;;;;;EAVxB,SAAA,IAAa,GAAA,EAAK,WAAA,KAAgB,YAAA,CAAa,OAAA;EAkBS;;;;;;;;EARxD,eAAA,IAAmB,GAAA,EAAK,kBAAA,KAAuB,YAAA,CAAa,OAAA;;;;;;;EAQ5D,UAAA,IAAc,GAAA,EAAK,mBAAA,KAAwB,YAAA,CAAa,QAAA;;;;;EAMxD,OAAA,IAAW,GAAA,EAAK,gBAAA,KAAqB,YAAA,CAAa,QAAA;AAAA"}

package/dist/runtime/core/hooks.d.mts

@@ -0,0 +1,121 @@
+import { CopilotRuntimeLike } from "./runtime.mjs";
+import { MaybePromise } from "@copilotkit/shared";
+
+//#region src/runtime/core/hooks.d.ts
+type RouteInfo = {
+  method: "agent/run";
+  agentId: string;
+} | {
+  method: "agent/suggest";
+  agentId: string;
+} | {
+  method: "agent/connect";
+  agentId: string;
+} | {
+  method: "trajectory/connect";
+  trajectoryId: string;
+} | {
+  method: "agent/stop";
+  agentId: string;
+  threadId: string;
+} | {
+  method: "info";
+} | {
+  method: "inspector/metadata";
+} | {
+  method: "inspector/learning";
+} | {
+  method: "transcribe";
+} | {
+  method: "threads/list";
+} | {
+  method: "threads/subscribe";
+} | {
+  method: "threads/update";
+  threadId: string;
+} | {
+  method: "threads/archive";
+  threadId: string;
+} | {
+  method: "threads/messages";
+  threadId: string;
+} | {
+  method: "threads/events";
+  threadId: string;
+} | {
+  method: "threads/state";
+  threadId: string;
+} | {
+  method: "threads/clear";
+} | {
+  method: "memories/list";
+} | {
+  method: "memories/recall";
+} | {
+  method: "memories/subscribe";
+} | {
+  method: "memories/mutate";
+  memoryId: string;
+} | {
+  method: "annotate";
+} | {
+  method: "cpk-debug-events";
+};
+interface HookContext {
+  /** The incoming Fetch Request (possibly modified by prior hooks). */
+  request: Request;
+  /** The resolved URL pathname. */
+  path: string;
+  /** The CopilotRuntimeLike instance. */
+  runtime: CopilotRuntimeLike;
+}
+interface HandlerHookContext extends HookContext {
+  /** The resolved route information. */
+  route: RouteInfo;
+}
+interface ResponseHookContext extends HookContext {
+  /** The Response produced by the handler. */
+  response: Response;
+  /** The resolved route information. */
+  route: RouteInfo;
+}
+interface ErrorHookContext extends HookContext {
+  /** The error that occurred. */
+  error: unknown;
+  /** The route info, if routing had already succeeded. */
+  route?: RouteInfo;
+}
+interface CopilotRuntimeHooks {
+  /**
+   * Called at the start of every request, before routing.
+   * Use to validate auth, attach headers, initialize correlation IDs, etc.
+   *
+   * Return a modified Request to replace the original, or void to continue.
+   * Throw a Response to short-circuit with an early response.
+   */
+  onRequest?: (ctx: HookContext) => MaybePromise<Request | void>;
+  /**
+   * Called after routing is resolved but before the handler executes.
+   * Receives the resolved route info (method, agentId, threadId).
+   *
+   * Use to do route-specific authorization, attach headers for agent calls, etc.
+   * Return a modified Request or void.
+   * Throw a Response to short-circuit.
+   */
+  onBeforeHandler?: (ctx: HandlerHookContext) => MaybePromise<Request | void>;
+  /**
+   * Called after the handler produces a Response, before it's sent to the client.
+   * Use to set cookies, add debugging headers, log, etc.
+   *
+   * Return a modified Response to replace the original, or void.
+   */
+  onResponse?: (ctx: ResponseHookContext) => MaybePromise<Response | void>;
+  /**
+   * Called when an error occurs during request processing.
+   * Return a Response to override the default error response, or void to use the default.
+   */
+  onError?: (ctx: ErrorHookContext) => MaybePromise<Response | void>;
+}
+//#endregion
+export { CopilotRuntimeHooks, ErrorHookContext, HandlerHookContext, HookContext, ResponseHookContext, RouteInfo };
+//# sourceMappingURL=hooks.d.mts.map

package/dist/runtime/core/hooks.d.mts.map

@@ -0,0 +1 @@
+{"version":3,"file":"hooks.d.mts","names":[],"sources":["../../../src/runtime/core/hooks.ts"],"mappings":";;;;KAmCY,SAAA;EACN,MAAA;EAAqB,OAAA;AAAA;EACrB,MAAA;EAAyB,OAAA;AAAA;EACzB,MAAA;EAAyB,OAAA;AAAA;EACzB,MAAA;EAA8B,YAAA;AAAA;EAC9B,MAAA;EAAsB,OAAA;EAAiB,QAAA;AAAA;EACvC,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;EAA0B,QAAA;AAAA;EAC1B,MAAA;EAA2B,QAAA;AAAA;EAC3B,MAAA;EAA4B,QAAA;AAAA;EAC5B,MAAA;EAA0B,QAAA;AAAA;EAC1B,MAAA;EAAyB,QAAA;AAAA;EACzB,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;AAAA;EACA,MAAA;EAA2B,QAAA;AAAA;EAC3B,MAAA;AAAA;EACA,MAAA;AAAA;AAAA,UAMW,WAAA;EAyBE;EAvBjB,OAAA,EAAS,OAAA;EA8ByB;EA5BlC,IAAA;EAoCkB;EAlClB,OAAA,EAAS,kBAAA;AAAA;AAAA,UAGM,kBAAA,SAA2B,WAAA;EAyCkB;EAvC5D,KAAA,EAAO,SAAA;AAAA;AAAA,UAGQ,mBAAA,SAA4B,WAAA;EA4CA;EA1C3C,QAAA,EAAU,QAAA;EAgDwC;EA9ClD,KAAA,EAAO,SAAA;AAAA;AAAA,UAGQ,gBAAA,SAAyB,WAAA;EAmBxC;EAjBA,KAAA;EAiBa;EAfb,KAAA,GAAQ,SAAA;AAAA;AAAA,UAOO,mBAAA;EAkBS;;;;;;;EAVxB,SAAA,IAAa,GAAA,EAAK,WAAA,KAAgB,YAAA,CAAa,OAAA;EAkBS;;;;;;;;EARxD,eAAA,IAAmB,GAAA,EAAK,kBAAA,KAAuB,YAAA,CAAa,OAAA;;;;;;;EAQ5D,UAAA,IAAc,GAAA,EAAK,mBAAA,KAAwB,YAAA,CAAa,QAAA;;;;;EAMxD,OAAA,IAAW,GAAA,EAAK,gBAAA,KAAqB,YAAA,CAAa,QAAA;AAAA"}

package/dist/runtime/core/hooks.mjs

@@ -0,0 +1,24 @@
+//#region src/runtime/core/hooks.ts
+async function runOnRequest(hooks, ctx) {
+	if (!hooks?.onRequest) return ctx.request;
+	const result = await hooks.onRequest(ctx);
+	return result instanceof Request ? result : ctx.request;
+}
+async function runOnBeforeHandler(hooks, ctx) {
+	if (!hooks?.onBeforeHandler) return ctx.request;
+	const result = await hooks.onBeforeHandler(ctx);
+	return result instanceof Request ? result : ctx.request;
+}
+async function runOnResponse(hooks, ctx) {
+	if (!hooks?.onResponse) return ctx.response;
+	const result = await hooks.onResponse(ctx);
+	return result instanceof Response ? result : ctx.response;
+}
+async function runOnError(hooks, ctx) {
+	if (!hooks?.onError) return;
+	return hooks.onError(ctx);
+}
+
+//#endregion
+export { runOnBeforeHandler, runOnError, runOnRequest, runOnResponse };
+//# sourceMappingURL=hooks.mjs.map