@inkeep/agents-core 0.0.0-dev-20260113131806 → 0.0.0-dev-20260114183157

package/dist/auth/auth.d.ts

@@ -2,7 +2,7 @@ import { DatabaseClient } from "../db/client.js";
 import * as _better_auth_sso0 from "@better-auth/sso";
 import * as better_auth0 from "better-auth";
 import { BetterAuthAdvancedOptions } from "better-auth";
-import * as better_auth_plugins20 from "better-auth/plugins";
+import * as better_auth_plugins0 from "better-auth/plugins";
 import * as zod0 from "zod";
 import { GoogleOptions } from "better-auth/social-providers";
 
@@ -81,6 +81,34 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
     requireEmailVerification: false;
     autoSignIn: true;
   };
+  databaseHooks: {
+    session: {
+      create: {
+        before: (session: {
+          id: string;
+          createdAt: Date;
+          updatedAt: Date;
+          userId: string;
+          expiresAt: Date;
+          token: string;
+          ipAddress?: string | null | undefined;
+          userAgent?: string | null | undefined;
+        } & Record<string, unknown>) => Promise<{
+          data: {
+            activeOrganizationId: string | null;
+            id: string;
+            createdAt: Date;
+            updatedAt: Date;
+            userId: string;
+            expiresAt: Date;
+            token: string;
+            ipAddress?: string | null | undefined;
+            userAgent?: string | null | undefined;
+          };
+        }>;
+      };
+    };
+  };
   socialProviders: {
     google: {
       redirectURI?: string | undefined;
@@ -185,7 +213,7 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
         handler: (inputContext: better_auth0.MiddlewareInputContext<better_auth0.MiddlewareOptions>) => Promise<void>;
       }[];
     };
-    options: better_auth_plugins20.BearerOptions | undefined;
+    options: better_auth_plugins0.BearerOptions | undefined;
   }, {
     id: "sso";
     endpoints: {
@@ -813,30 +841,30 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
     };
   }, {
     id: "organization";
-    endpoints: better_auth_plugins20.OrganizationEndpoints<{
+    endpoints: better_auth_plugins0.OrganizationEndpoints<{
       allowUserToCreateOrganization: true;
-      ac: better_auth_plugins20.AccessControl;
+      ac: better_auth_plugins0.AccessControl;
       roles: {
         member: {
-          authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key] | {
-            actions: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key];
+          authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key] | {
+            actions: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key];
             connector: "OR" | "AND";
-          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins20.AuthorizeResponse;
-          statements: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>;
+          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
+          statements: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>;
         };
         admin: {
-          authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key] | {
-            actions: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key];
+          authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key] | {
+            actions: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key];
             connector: "OR" | "AND";
-          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins20.AuthorizeResponse;
-          statements: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>;
+          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
+          statements: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>;
         };
         owner: {
-          authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key] | {
-            actions: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key];
+          authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key] | {
+            actions: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key];
             connector: "OR" | "AND";
-          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins20.AuthorizeResponse;
-          statements: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>;
+          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
+          statements: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>;
         };
       };
       membershipLimit: number;
@@ -846,9 +874,9 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
         id: string;
         role: string;
         email: string;
-        organization: better_auth_plugins20.Organization;
-        invitation: better_auth_plugins20.Invitation;
-        inviter: better_auth_plugins20.Member & {
+        organization: better_auth_plugins0.Organization;
+        invitation: better_auth_plugins0.Invitation;
+        inviter: better_auth_plugins0.Member & {
           user: better_auth0.User;
         };
       }): Promise<void>;
@@ -981,7 +1009,7 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
         organizationId: string;
         email: string;
         role: "member" | "admin" | "owner";
-        status: better_auth_plugins20.InvitationStatus;
+        status: better_auth_plugins0.InvitationStatus;
         inviterId: string;
         expiresAt: Date;
         createdAt: Date;
@@ -1020,7 +1048,7 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
           organizationId: string;
           email: string;
           role: "member" | "admin" | "owner";
-          status: better_auth_plugins20.InvitationStatus;
+          status: better_auth_plugins0.InvitationStatus;
           inviterId: string;
           expiresAt: Date;
           createdAt: Date;
@@ -1094,28 +1122,28 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
     };
     options: NoInfer<{
       allowUserToCreateOrganization: true;
-      ac: better_auth_plugins20.AccessControl;
+      ac: better_auth_plugins0.AccessControl;
       roles: {
         member: {
-          authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key] | {
-            actions: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key];
+          authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key] | {
+            actions: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key];
             connector: "OR" | "AND";
-          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins20.AuthorizeResponse;
-          statements: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>;
+          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
+          statements: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>;
         };
         admin: {
-          authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key] | {
-            actions: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key];
+          authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key] | {
+            actions: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key];
             connector: "OR" | "AND";
-          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins20.AuthorizeResponse;
-          statements: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>;
+          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
+          statements: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>;
         };
         owner: {
-          authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key] | {
-            actions: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>[key];
+          authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key] | {
+            actions: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>[key];
             connector: "OR" | "AND";
-          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins20.AuthorizeResponse;
-          statements: better_auth_plugins20.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins20.Statements>;
+          } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
+          statements: better_auth_plugins0.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins0.Statements>;
         };
       };
       membershipLimit: number;
@@ -1125,9 +1153,9 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
         id: string;
         role: string;
         email: string;
-        organization: better_auth_plugins20.Organization;
-        invitation: better_auth_plugins20.Invitation;
-        inviter: better_auth_plugins20.Member & {
+        organization: better_auth_plugins0.Organization;
+        invitation: better_auth_plugins0.Invitation;
+        inviter: better_auth_plugins0.Member & {
           user: better_auth0.User;
         };
       }): Promise<void>;
@@ -1465,8 +1493,8 @@ declare function createAuth(config: BetterAuthConfig): better_auth0.Auth<{
       readonly AUTHENTICATION_REQUIRED: "Authentication required";
     };
     options: Partial<{
-      expiresIn: better_auth_plugins20.TimeString;
-      interval: better_auth_plugins20.TimeString;
+      expiresIn: better_auth_plugins0.TimeString;
+      interval: better_auth_plugins0.TimeString;
       deviceCodeLength: number;
       userCodeLength: number;
       schema: {

package/dist/auth/auth.js

@@ -1,4 +1,4 @@
-import { ssoProvider } from "./auth-schema.js";
+import { member, ssoProvider } from "./auth-schema.js";
 import { env } from "../env.js";
 import { generateId } from "../utils/conversations.js";
 import "../utils/index.js";
@@ -11,6 +11,15 @@ import { bearer, deviceAuthorization, oAuthProxy, organization } from "better-au
 
 //#region src/auth/auth.ts
 /**
+* Get the user's initial organization for a new session.
+* Returns the oldest organization the user is a member of.
+* See: https://www.better-auth.com/docs/plugins/organization#active-organization
+*/
+async function getInitialOrganization(dbClient, userId) {
+	const [membership] = await dbClient.select({ organizationId: member.organizationId }).from(member).where(eq(member.userId, userId)).orderBy(member.createdAt).limit(1);
+	return membership ? { id: membership.organizationId } : null;
+}
+/**
 * Extracts the root domain from a URL for cross-subdomain cookie sharing.
 * For example:
 * - https://manage-api.pilot.inkeep.com -> .pilot.inkeep.com
@@ -67,6 +76,13 @@ function createAuth(config) {
 			requireEmailVerification: false,
 			autoSignIn: true
 		},
+		databaseHooks: { session: { create: { before: async (session) => {
+			const organization$1 = await getInitialOrganization(config.dbClient, session.userId);
+			return { data: {
+				...session,
+				activeOrganizationId: organization$1?.id ?? null
+			} };
+		} } } },
 		socialProviders: config.socialProviders?.google && { google: {
 			...config.socialProviders.google,
 			...env.OAUTH_PROXY_PRODUCTION_URL && { redirectURI: `${env.OAUTH_PROXY_PRODUCTION_URL}/api/auth/callback/google` }

package/dist/auth/permissions.d.ts

@@ -1,29 +1,29 @@
-import * as better_auth_plugins0 from "better-auth/plugins";
+import * as better_auth_plugins55 from "better-auth/plugins";
 import { AccessControl } from "better-auth/plugins/access";
 import { organizationClient } from "better-auth/client/plugins";
 
 //#region src/auth/permissions.d.ts
 declare const ac: AccessControl;
 declare const memberRole: {
-  authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>[key] | {
-    actions: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>[key];
+  authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>[key] | {
+    actions: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>[key];
     connector: "OR" | "AND";
-  } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
-  statements: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>;
+  } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins55.AuthorizeResponse;
+  statements: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>;
 };
 declare const adminRole: {
-  authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>[key] | {
-    actions: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>[key];
+  authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>[key] | {
+    actions: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>[key];
     connector: "OR" | "AND";
-  } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
-  statements: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>;
+  } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins55.AuthorizeResponse;
+  statements: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>;
 };
 declare const ownerRole: {
-  authorize<K_1 extends "function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>[key] | {
-    actions: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>[key];
+  authorize<K_1 extends "function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team">(request: K_1 extends infer T extends K ? { [key in T]?: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>[key] | {
+    actions: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>[key];
     connector: "OR" | "AND";
-  } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins0.AuthorizeResponse;
-  statements: better_auth_plugins0.Subset<"function" | "organization" | "agent" | "invitation" | "member" | "project" | "tool" | "credential" | "sub_agent" | "api_key" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team" | "ac", better_auth_plugins0.Statements>;
+  } | undefined } : never, connector?: "OR" | "AND"): better_auth_plugins55.AuthorizeResponse;
+  statements: better_auth_plugins55.Subset<"function" | "organization" | "member" | "invitation" | "ac" | "project" | "agent" | "sub_agent" | "tool" | "api_key" | "credential" | "data_component" | "artifact_component" | "external_agent" | "context_config" | "team", better_auth_plugins55.Statements>;
 };
 //#endregion
 export { ac, adminRole, memberRole, organizationClient, ownerRole };

package/dist/client-exports.d.ts

@@ -1,3 +1,4 @@
+import { BreakdownComponentDef, CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE, ContextBreakdown, V1_BREAKDOWN_SCHEMA, calculateBreakdownTotal, createEmptyBreakdown, parseContextBreakdownFromSpan } from "./constants/context-breakdown.js";
 import { ACTIVITY_NAMES, ACTIVITY_STATUS, ACTIVITY_TYPES, AGENT_IDS, AI_OPERATIONS, AI_TOOL_TYPES, DELEGATION_FROM_SUB_AGENT_ID, DELEGATION_ID, DELEGATION_TO_SUB_AGENT_ID, SPAN_KEYS, SPAN_NAMES, TRANSFER_FROM_SUB_AGENT_ID, TRANSFER_TO_SUB_AGENT_ID, UNKNOWN_VALUE } from "./constants/otel-attributes.js";
 import { AGGREGATE_OPERATORS, DATA_SOURCES, DATA_TYPES, FIELD_TYPES, OPERATORS, ORDER_DIRECTIONS, PANEL_TYPES, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_FIELD_CONFIGS, QUERY_TYPES, REDUCE_OPERATIONS } from "./constants/signoz-queries.js";
 import { AgentStopWhen, AgentStopWhenSchema, ApiKeyApiUpdateSchema, FullAgentAgentInsertSchema, FunctionApiInsertSchema, FunctionApiSelectSchema, FunctionApiUpdateSchema, ModelSettings, ModelSettingsSchema, StopWhen, StopWhenSchema, SubAgentStopWhen, SubAgentStopWhenSchema } from "./validation/schemas.js";
@@ -5,7 +6,6 @@ import "./types/index.js";
 import { DEFAULT_NANGO_STORE_ID } from "./credential-stores/default-constants.js";
 import { detectAuthenticationRequired } from "./utils/auth-detection.js";
 import { validatePropsAsJsonSchema } from "./validation/props-validation.js";
-import "./index.js";
 import { ConversationHistoryConfig, CredentialStoreType, MCPTransportType } from "./types/utility.js";
 import { z } from "@hono/zod-openapi";
 
@@ -64,8 +64,8 @@ declare const AgentApiInsertSchema: z.ZodObject<{
   canTransferTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
   canDelegateTo: z.ZodOptional<z.ZodArray<z.ZodString>>;
   type: z.ZodOptional<z.ZodEnum<{
-    internal: "internal";
     external: "external";
+    internal: "internal";
   }>>;
 }, z.core.$strip>;
 declare const ToolApiInsertSchema: z.ZodObject<{
@@ -192,9 +192,9 @@ declare const FullAgentDefinitionSchema: z.ZodObject<{
   subAgents: z.ZodRecord<z.ZodString, z.ZodUnion<readonly [z.ZodObject<{
     id: z.ZodString;
     name: z.ZodString;
-    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     createdAt: z.ZodOptional<z.ZodString>;
     updatedAt: z.ZodOptional<z.ZodString>;
+    description: z.ZodOptional<z.ZodNullable<z.ZodString>>;
     models: z.ZodOptional<z.ZodObject<{
       base: z.ZodOptional<z.ZodObject<{
         model: z.ZodOptional<z.ZodString>;
@@ -309,4 +309,4 @@ declare function generateIdFromName(name: string): string;
 type ToolInsert = ToolApiInsert;
 type AgentAgentInsert = AgentAgentApiInsert;
 //#endregion
-export { ACTIVITY_NAMES, ACTIVITY_STATUS, ACTIVITY_TYPES, AGENT_IDS, AGGREGATE_OPERATORS, AI_OPERATIONS, AI_TOOL_TYPES, AgentAgentApiInsert, AgentAgentApiInsertSchema, AgentAgentInsert, AgentApiInsert, AgentApiInsertSchema, type AgentStopWhen, AgentStopWhenSchema, ApiKeyApiCreationResponse, ApiKeyApiCreationResponseSchema, ApiKeyApiSelect, ApiKeyApiSelectSchema, ApiKeyApiUpdateResponse, ArtifactComponentApiInsert, ArtifactComponentApiInsertSchema, ContextConfigApiInsert, ContextConfigApiInsertSchema, CredentialReferenceApiInsert, CredentialReferenceApiInsertSchema, CredentialStoreType, DATA_SOURCES, DATA_TYPES, DEFAULT_NANGO_STORE_ID, DELEGATION_FROM_SUB_AGENT_ID, DELEGATION_ID, DELEGATION_TO_SUB_AGENT_ID, DataComponentApiInsert, DataComponentApiInsertSchema, ErrorResponse, ErrorResponseSchema, ExternalAgentApiInsert, ExternalAgentApiInsertSchema, ExternalAgentDefinition, FIELD_TYPES, FullAgentDefinition, FullAgentDefinitionSchema, FunctionApiInsert, FunctionApiInsertSchema, FunctionApiSelectSchema, FunctionApiUpdateSchema, IdParamsSchema, InternalAgentDefinition, ListResponseSchema, MAX_ID_LENGTH, MCPTransportType, MIN_ID_LENGTH, type ModelSettings, ModelSettingsSchema, OPERATORS, ORDER_DIRECTIONS, PANEL_TYPES, PaginationSchema, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_FIELD_CONFIGS, QUERY_TYPES, REDUCE_OPERATIONS, SPAN_KEYS, SPAN_NAMES, SingleResponseSchema, type StopWhen, StopWhenSchema, type SubAgentStopWhen, SubAgentStopWhenSchema, TRANSFER_FROM_SUB_AGENT_ID, TRANSFER_TO_SUB_AGENT_ID, TenantParams, TenantParamsSchema, TenantProjectIdParamsSchema, TenantProjectParamsSchema, ToolApiInsert, ToolApiInsertSchema, ToolInsert, UNKNOWN_VALUE, URL_SAFE_ID_PATTERN, detectAuthenticationRequired, generateIdFromName, resourceIdSchema, validatePropsAsJsonSchema };
+export { ACTIVITY_NAMES, ACTIVITY_STATUS, ACTIVITY_TYPES, AGENT_IDS, AGGREGATE_OPERATORS, AI_OPERATIONS, AI_TOOL_TYPES, AgentAgentApiInsert, AgentAgentApiInsertSchema, AgentAgentInsert, AgentApiInsert, AgentApiInsertSchema, type AgentStopWhen, AgentStopWhenSchema, ApiKeyApiCreationResponse, ApiKeyApiCreationResponseSchema, ApiKeyApiSelect, ApiKeyApiSelectSchema, ApiKeyApiUpdateResponse, ArtifactComponentApiInsert, ArtifactComponentApiInsertSchema, BreakdownComponentDef, CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE, ContextBreakdown, ContextConfigApiInsert, ContextConfigApiInsertSchema, CredentialReferenceApiInsert, CredentialReferenceApiInsertSchema, CredentialStoreType, DATA_SOURCES, DATA_TYPES, DEFAULT_NANGO_STORE_ID, DELEGATION_FROM_SUB_AGENT_ID, DELEGATION_ID, DELEGATION_TO_SUB_AGENT_ID, DataComponentApiInsert, DataComponentApiInsertSchema, ErrorResponse, ErrorResponseSchema, ExternalAgentApiInsert, ExternalAgentApiInsertSchema, ExternalAgentDefinition, FIELD_TYPES, FullAgentDefinition, FullAgentDefinitionSchema, FunctionApiInsert, FunctionApiInsertSchema, FunctionApiSelectSchema, FunctionApiUpdateSchema, IdParamsSchema, InternalAgentDefinition, ListResponseSchema, MAX_ID_LENGTH, MCPTransportType, MIN_ID_LENGTH, type ModelSettings, ModelSettingsSchema, OPERATORS, ORDER_DIRECTIONS, PANEL_TYPES, PaginationSchema, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_FIELD_CONFIGS, QUERY_TYPES, REDUCE_OPERATIONS, SPAN_KEYS, SPAN_NAMES, SingleResponseSchema, type StopWhen, StopWhenSchema, type SubAgentStopWhen, SubAgentStopWhenSchema, TRANSFER_FROM_SUB_AGENT_ID, TRANSFER_TO_SUB_AGENT_ID, TenantParams, TenantParamsSchema, TenantProjectIdParamsSchema, TenantProjectParamsSchema, ToolApiInsert, ToolApiInsertSchema, ToolInsert, UNKNOWN_VALUE, URL_SAFE_ID_PATTERN, V1_BREAKDOWN_SCHEMA, calculateBreakdownTotal, createEmptyBreakdown, detectAuthenticationRequired, generateIdFromName, parseContextBreakdownFromSpan, resourceIdSchema, validatePropsAsJsonSchema };

package/dist/client-exports.js

@@ -3,6 +3,7 @@ import { CredentialStoreType, MCPTransportType } from "./types/utility.js";
 import { AgentStopWhenSchema, ArtifactComponentApiInsertSchema as ArtifactComponentApiInsertSchema$1, FullAgentAgentInsertSchema, FunctionApiInsertSchema, FunctionApiSelectSchema, FunctionApiUpdateSchema, ModelSettingsSchema, StopWhenSchema, SubAgentStopWhenSchema } from "./validation/schemas.js";
 import { DEFAULT_NANGO_STORE_ID } from "./credential-stores/default-constants.js";
 import { validatePropsAsJsonSchema } from "./validation/props-validation.js";
+import { CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE, V1_BREAKDOWN_SCHEMA, calculateBreakdownTotal, createEmptyBreakdown, parseContextBreakdownFromSpan } from "./constants/context-breakdown.js";
 import { ACTIVITY_NAMES, ACTIVITY_STATUS, ACTIVITY_TYPES, AGENT_IDS, AI_OPERATIONS, AI_TOOL_TYPES, DELEGATION_FROM_SUB_AGENT_ID, DELEGATION_ID, DELEGATION_TO_SUB_AGENT_ID, SPAN_KEYS, SPAN_NAMES, TRANSFER_FROM_SUB_AGENT_ID, TRANSFER_TO_SUB_AGENT_ID, UNKNOWN_VALUE } from "./constants/otel-attributes.js";
 import { AGGREGATE_OPERATORS, DATA_SOURCES, DATA_TYPES, FIELD_TYPES, OPERATORS, ORDER_DIRECTIONS, PANEL_TYPES, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_FIELD_CONFIGS, QUERY_TYPES, REDUCE_OPERATIONS } from "./constants/signoz-queries.js";
 import { detectAuthenticationRequired } from "./utils/auth-detection.js";
@@ -167,4 +168,4 @@ function generateIdFromName(name) {
 }
 
 //#endregion
-export { ACTIVITY_NAMES, ACTIVITY_STATUS, ACTIVITY_TYPES, AGENT_IDS, AGGREGATE_OPERATORS, AI_OPERATIONS, AI_TOOL_TYPES, AgentAgentApiInsertSchema, AgentApiInsertSchema, AgentStopWhenSchema, ApiKeyApiCreationResponseSchema, ApiKeyApiSelectSchema, ArtifactComponentApiInsertSchema, ContextConfigApiInsertSchema, CredentialReferenceApiInsertSchema, CredentialStoreType, DATA_SOURCES, DATA_TYPES, DEFAULT_NANGO_STORE_ID, DELEGATION_FROM_SUB_AGENT_ID, DELEGATION_ID, DELEGATION_TO_SUB_AGENT_ID, DataComponentApiInsertSchema, ErrorResponseSchema, ExternalAgentApiInsertSchema, FIELD_TYPES, FullAgentDefinitionSchema, FunctionApiInsertSchema, FunctionApiSelectSchema, FunctionApiUpdateSchema, IdParamsSchema, ListResponseSchema, MAX_ID_LENGTH, MCPTransportType, MIN_ID_LENGTH, ModelSettingsSchema, OPERATORS, ORDER_DIRECTIONS, PANEL_TYPES, PaginationSchema, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_FIELD_CONFIGS, QUERY_TYPES, REDUCE_OPERATIONS, SPAN_KEYS, SPAN_NAMES, SingleResponseSchema, StopWhenSchema, SubAgentStopWhenSchema, TRANSFER_FROM_SUB_AGENT_ID, TRANSFER_TO_SUB_AGENT_ID, TenantParamsSchema, TenantProjectIdParamsSchema, TenantProjectParamsSchema, ToolApiInsertSchema, UNKNOWN_VALUE, URL_SAFE_ID_PATTERN, detectAuthenticationRequired, generateIdFromName, resourceIdSchema, validatePropsAsJsonSchema };
+export { ACTIVITY_NAMES, ACTIVITY_STATUS, ACTIVITY_TYPES, AGENT_IDS, AGGREGATE_OPERATORS, AI_OPERATIONS, AI_TOOL_TYPES, AgentAgentApiInsertSchema, AgentApiInsertSchema, AgentStopWhenSchema, ApiKeyApiCreationResponseSchema, ApiKeyApiSelectSchema, ArtifactComponentApiInsertSchema, CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE, ContextConfigApiInsertSchema, CredentialReferenceApiInsertSchema, CredentialStoreType, DATA_SOURCES, DATA_TYPES, DEFAULT_NANGO_STORE_ID, DELEGATION_FROM_SUB_AGENT_ID, DELEGATION_ID, DELEGATION_TO_SUB_AGENT_ID, DataComponentApiInsertSchema, ErrorResponseSchema, ExternalAgentApiInsertSchema, FIELD_TYPES, FullAgentDefinitionSchema, FunctionApiInsertSchema, FunctionApiSelectSchema, FunctionApiUpdateSchema, IdParamsSchema, ListResponseSchema, MAX_ID_LENGTH, MCPTransportType, MIN_ID_LENGTH, ModelSettingsSchema, OPERATORS, ORDER_DIRECTIONS, PANEL_TYPES, PaginationSchema, QUERY_DEFAULTS, QUERY_EXPRESSIONS, QUERY_FIELD_CONFIGS, QUERY_TYPES, REDUCE_OPERATIONS, SPAN_KEYS, SPAN_NAMES, SingleResponseSchema, StopWhenSchema, SubAgentStopWhenSchema, TRANSFER_FROM_SUB_AGENT_ID, TRANSFER_TO_SUB_AGENT_ID, TenantParamsSchema, TenantProjectIdParamsSchema, TenantProjectParamsSchema, ToolApiInsertSchema, UNKNOWN_VALUE, URL_SAFE_ID_PATTERN, V1_BREAKDOWN_SCHEMA, calculateBreakdownTotal, createEmptyBreakdown, detectAuthenticationRequired, generateIdFromName, parseContextBreakdownFromSpan, resourceIdSchema, validatePropsAsJsonSchema };

package/dist/constants/context-breakdown.d.ts

@@ -0,0 +1,61 @@
+//#region src/constants/context-breakdown.d.ts
+/**
+ * Context breakdown schema definitions.
+ *
+ * This module defines the breakdown components tracked for each system prompt version.
+ * It serves as the single source of truth for:
+ * - Component keys and labels
+ * - OpenTelemetry span attribute keys
+ * - UI visualization colors (auto-generated)
+ */
+/**
+ * Defines a single breakdown component for a system prompt version.
+ * Each version can define its own set of components.
+ */
+interface BreakdownComponentDef {
+  /** Unique key for this component (used in breakdown.components map) */
+  key: string;
+  /** Human-readable label for UI display */
+  label: string;
+  /** OpenTelemetry span attribute key for this component */
+  spanAttribute: string;
+  /** Hex color for UI visualization (auto-generated) */
+  color: string;
+}
+/**
+ * V1 Breakdown Schema - defines all context components tracked for V1 system prompts.
+ * Colors are automatically generated for visual distinction.
+ */
+declare const V1_BREAKDOWN_SCHEMA: BreakdownComponentDef[];
+/** Span attribute key for total tokens */
+declare const CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE = "context.breakdown.total_tokens";
+/**
+ * Dynamic context breakdown interface.
+ * Uses a components map to support different system prompt versions.
+ */
+interface ContextBreakdown {
+  /** Token counts by component key (version-specific) */
+  components: Record<string, number>;
+  /** Total estimated tokens */
+  total: number;
+}
+/**
+ * Creates an empty context breakdown from a schema definition.
+ * @param schema - Array of breakdown component definitions
+ */
+declare function createEmptyBreakdown(schema: BreakdownComponentDef[]): ContextBreakdown;
+/**
+ * Calculates the total from all breakdown components and updates the total field.
+ * @param breakdown - The context breakdown to calculate total for
+ * @returns The breakdown with updated total
+ */
+declare function calculateBreakdownTotal(breakdown: ContextBreakdown): ContextBreakdown;
+/**
+ * Parses a context breakdown from span attributes using a schema.
+ * @param data - Span attribute data record
+ * @param schema - Breakdown schema to use for parsing
+ * @returns Parsed context breakdown
+ */
+declare function parseContextBreakdownFromSpan(data: Record<string, unknown>, schema?: BreakdownComponentDef[]): ContextBreakdown;
+//#endregion
+export { BreakdownComponentDef, CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE, ContextBreakdown, V1_BREAKDOWN_SCHEMA, calculateBreakdownTotal, createEmptyBreakdown, parseContextBreakdownFromSpan };

package/dist/constants/context-breakdown.js

@@ -0,0 +1,124 @@
+import { generateDistinctColors } from "../utils/colors.js";
+
+//#region src/constants/context-breakdown.ts
+/**
+* Context breakdown schema definitions.
+*
+* This module defines the breakdown components tracked for each system prompt version.
+* It serves as the single source of truth for:
+* - Component keys and labels
+* - OpenTelemetry span attribute keys
+* - UI visualization colors (auto-generated)
+*/
+/**
+* Base schema without colors - colors are auto-generated based on index
+*/
+const V1_BREAKDOWN_SCHEMA_BASE = [
+	{
+		key: "systemPromptTemplate",
+		label: "System Prompt Template",
+		spanAttribute: "context.breakdown.system_template_tokens"
+	},
+	{
+		key: "coreInstructions",
+		label: "Core Instructions",
+		spanAttribute: "context.breakdown.core_instructions_tokens"
+	},
+	{
+		key: "agentPrompt",
+		label: "Agent Prompt",
+		spanAttribute: "context.breakdown.agent_prompt_tokens"
+	},
+	{
+		key: "toolsSection",
+		label: "Tools (MCP/Function/Relation)",
+		spanAttribute: "context.breakdown.tools_tokens"
+	},
+	{
+		key: "artifactsSection",
+		label: "Artifacts",
+		spanAttribute: "context.breakdown.artifacts_tokens"
+	},
+	{
+		key: "dataComponents",
+		label: "Data Components",
+		spanAttribute: "context.breakdown.data_components_tokens"
+	},
+	{
+		key: "artifactComponents",
+		label: "Artifact Components",
+		spanAttribute: "context.breakdown.artifact_components_tokens"
+	},
+	{
+		key: "transferInstructions",
+		label: "Transfer Instructions",
+		spanAttribute: "context.breakdown.transfer_instructions_tokens"
+	},
+	{
+		key: "delegationInstructions",
+		label: "Delegation Instructions",
+		spanAttribute: "context.breakdown.delegation_instructions_tokens"
+	},
+	{
+		key: "thinkingPreparation",
+		label: "Thinking Preparation",
+		spanAttribute: "context.breakdown.thinking_preparation_tokens"
+	},
+	{
+		key: "conversationHistory",
+		label: "Conversation History",
+		spanAttribute: "context.breakdown.conversation_history_tokens"
+	}
+];
+/** Pre-generated distinct colors for the schema */
+const SCHEMA_COLORS = generateDistinctColors(V1_BREAKDOWN_SCHEMA_BASE.length);
+/**
+* V1 Breakdown Schema - defines all context components tracked for V1 system prompts.
+* Colors are automatically generated for visual distinction.
+*/
+const V1_BREAKDOWN_SCHEMA = V1_BREAKDOWN_SCHEMA_BASE.map((def, index) => ({
+	...def,
+	color: SCHEMA_COLORS[index]
+}));
+/** Span attribute key for total tokens */
+const CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE = "context.breakdown.total_tokens";
+/**
+* Creates an empty context breakdown from a schema definition.
+* @param schema - Array of breakdown component definitions
+*/
+function createEmptyBreakdown(schema) {
+	const components = {};
+	for (const def of schema) components[def.key] = 0;
+	return {
+		components,
+		total: 0
+	};
+}
+/**
+* Calculates the total from all breakdown components and updates the total field.
+* @param breakdown - The context breakdown to calculate total for
+* @returns The breakdown with updated total
+*/
+function calculateBreakdownTotal(breakdown) {
+	breakdown.total = Object.values(breakdown.components).reduce((sum, val) => sum + val, 0);
+	return breakdown;
+}
+/**
+* Parses a context breakdown from span attributes using a schema.
+* @param data - Span attribute data record
+* @param schema - Breakdown schema to use for parsing
+* @returns Parsed context breakdown
+*/
+function parseContextBreakdownFromSpan(data, schema = V1_BREAKDOWN_SCHEMA) {
+	const breakdown = createEmptyBreakdown(schema);
+	for (const def of schema) {
+		const value = data[def.spanAttribute];
+		breakdown.components[def.key] = typeof value === "number" ? value : Number(value) || 0;
+	}
+	const totalValue = data[CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE];
+	breakdown.total = typeof totalValue === "number" ? totalValue : Number(totalValue) || 0;
+	return breakdown;
+}
+
+//#endregion
+export { CONTEXT_BREAKDOWN_TOTAL_SPAN_ATTRIBUTE, V1_BREAKDOWN_SCHEMA, calculateBreakdownTotal, createEmptyBreakdown, parseContextBreakdownFromSpan };