@vc-shell/framework 1.2.2 → 1.2.3-beta.0

package/core/plugins/ai-agent/components/_internal/VcAiAgentHeader.vue

@@ -0,0 +1,182 @@
+<template>
+  <div class="vc-ai-agent-header">
+    <div class="vc-ai-agent-header__icon">
+      <svg
+        width="22"
+        height="24"
+        viewBox="0 0 22 24"
+        fill="none"
+        xmlns="http://www.w3.org/2000/svg"
+      >
+        <path
+          d="M8.92406 0.537357C10.165 -0.179119 11.6939 -0.179119 12.9349 0.537357L19.8535 4.5319C21.0945 5.24838 21.8589 6.57248 21.8589 8.00543V15.9945C21.8589 17.4275 21.0945 18.7516 19.8535 19.4681L12.9349 23.4626C11.6939 24.1791 10.165 24.1791 8.92406 23.4626L2.00541 19.4681C0.764459 18.7516 0 17.4275 0 15.9945V8.00543C0 6.57248 0.764459 5.24838 2.00541 4.5319L8.92406 0.537357Z"
+          fill="white"
+        />
+        <g
+          clip-path="url(#paint0_angular_1004_8813_clip_path)"
+          data-figma-skip-parse="true"
+        >
+          <g transform="matrix(0 -0.0359275 0.0356829 0 10.9297 12.0001)">
+            <foreignObject
+              x="-334.01"
+              y="-334.01"
+              width="668.02"
+              height="668.02"
+              ><div
+                xmlns="http://www.w3.org/1999/xhtml"
+                style="
+                  background: conic-gradient(
+                    from 90deg,
+                    rgba(255, 149, 51, 1) 0deg,
+                    rgba(255, 79, 187, 1) 43.2deg,
+                    rgba(155, 255, 79, 1) 143.654deg,
+                    rgba(28, 145, 252, 1) 252.692deg,
+                    rgba(154, 45, 248, 1) 316.8deg,
+                    rgba(255, 149, 51, 1) 360deg
+                  );
+                  height: 100%;
+                  width: 100%;
+                  opacity: 1;
+                "
+              ></div
+            ></foreignObject>
+          </g>
+        </g>
+        <path
+          fill-rule="evenodd"
+          clip-rule="evenodd"
+          d="M16.4395 10.6925C17.4389 12.4342 17.5855 14.7605 17.0781 17.0412C16.5847 19.2587 15.479 21.3907 14.002 22.8459L12.9346 23.463C11.6937 24.1793 10.1647 24.1794 8.92383 23.463L4.81641 21.091C6.48014 21.2357 8.24755 21.0003 9.87402 20.4474C12.1457 19.6751 14.1798 18.2734 15.2773 16.3839C16.7064 13.9237 16.7787 11.8621 16.2246 10.339C16.296 10.4538 16.3694 10.5705 16.4395 10.6925ZM12.5723 6.5646C14.5851 6.56993 16.7106 7.56255 18.4668 9.09488C20.0162 10.4468 21.2529 12.1974 21.8594 14.0041V15.9943C21.8594 17.4272 21.0944 18.7514 19.8535 19.4679L15.4492 22.0109C16.4736 20.6151 17.2295 18.9083 17.6182 17.1613C18.1443 14.7966 18.0091 12.3169 16.9189 10.4171C15.5014 7.94691 13.7497 6.85357 12.1523 6.57339C12.2894 6.56875 12.4294 6.56423 12.5723 6.5646ZM0 11.2697C0.704632 12.7816 1.7891 14.1898 3.0791 15.3166C4.87894 16.8885 7.10461 17.9397 9.28906 17.9455C12.1367 17.9529 13.9586 16.9824 15 15.7394C14.9357 15.8599 14.8712 15.9836 14.7998 16.1066C13.7886 17.8473 11.8825 19.1804 9.69531 19.924C7.65984 20.6159 5.41309 20.7847 3.47656 20.3175L2.00586 19.4679C0.764906 18.7514 0 17.4272 0 15.9943V11.2697ZM5.95215 2.2521C5.01991 3.60523 4.37186 5.22291 4.0625 6.87613C3.62624 9.20794 3.85535 11.6456 4.94141 13.5382C6.36156 16.013 8.11707 17.1052 9.7168 17.383C9.57761 17.3878 9.43521 17.3931 9.29004 17.3927C7.27637 17.3873 5.17407 16.4121 3.44238 14.8996C1.82788 13.4893 0.56156 11.633 0 9.71988V8.00601C0 6.57306 0.764906 5.24885 2.00586 4.53238L5.95215 2.2521ZM11.3975 7.05093C12.0141 7.06601 12.6881 7.21751 13.376 7.5607C13.0837 7.49777 12.8006 7.49218 12.5459 7.55679L12.6816 8.09292C13.0083 8.00995 13.4967 8.1005 14.0215 8.41421C14.538 8.72301 15.057 9.23022 15.4326 9.91909C15.7285 10.4617 15.9343 11.1225 15.9805 11.8918C15.8889 11.6052 15.7517 11.3555 15.5674 11.1662L15.1709 11.5519C15.406 11.7933 15.5727 12.2611 15.5635 12.8722C15.5543 13.4739 15.3736 14.1772 14.9648 14.8468C14.642 15.3757 14.171 15.8854 13.5254 16.3107C13.73 16.0867 13.8799 15.8413 13.9521 15.5851L13.4189 15.4347C13.3275 15.7591 13.0058 16.1381 12.4717 16.4357C11.9461 16.7285 11.2471 16.9236 10.4629 16.9044C9.84516 16.8893 9.1696 16.7382 8.48047 16.3937C8.77503 16.4579 9.06081 16.4638 9.31738 16.3986L9.18066 15.8625C8.85403 15.9453 8.36539 15.8557 7.84082 15.5421C7.32436 15.2334 6.80623 14.7251 6.43066 14.0363C6.13467 13.4934 5.92691 12.8324 5.88086 12.0626C5.97253 12.3504 6.11088 12.6013 6.2959 12.7912L6.69141 12.4044C6.45639 12.163 6.28955 11.6951 6.29883 11.0841C6.30799 10.4824 6.48868 9.77922 6.89746 9.10952C7.21926 8.58233 7.68762 8.07306 8.33008 7.64859C8.12755 7.87138 7.97995 8.11577 7.9082 8.37027L8.44141 8.52066C8.53286 8.19625 8.8546 7.81729 9.38867 7.51968C9.91427 7.22684 10.6133 7.0318 11.3975 7.05093ZM8.92383 0.537258C10.1647 -0.179152 11.6937 -0.17902 12.9346 0.537258L16.832 2.78726C15.2289 2.68408 13.5406 2.93545 11.9824 3.47671C9.71315 4.26504 7.68197 5.68288 6.58496 7.57144C5.15353 10.0358 5.08346 12.1004 5.64062 13.6242C5.56755 13.507 5.49251 13.3876 5.4209 13.2628C4.41748 11.5142 4.18713 9.21872 4.60645 6.97769C4.99237 4.91536 5.92418 2.92968 7.26758 1.49331L8.92383 0.537258ZM12.1641 4.00015C14.0959 3.32907 16.2174 3.13043 18.084 3.51089L19.8535 4.53238C21.0944 5.24887 21.8594 6.57311 21.8594 8.00601V12.5626C21.1452 11.1171 20.0805 9.7689 18.8301 8.67788C17.0078 7.08795 14.7586 6.01663 12.5732 6.01089C9.72539 6.00349 7.90267 6.97374 6.86133 8.21695C6.92577 8.09606 6.9918 7.97218 7.06348 7.84878C8.07528 6.10725 9.97945 4.75906 12.1641 4.00015Z"
+          data-figma-gradient-fill="{&#34;type&#34;:&#34;GRADIENT_ANGULAR&#34;,&#34;stops&#34;:[{&#34;color&#34;:{&#34;r&#34;:1.0,&#34;g&#34;:0.58431375026702881,&#34;b&#34;:0.20000000298023224,&#34;a&#34;:1.0},&#34;position&#34;:0.0},{&#34;color&#34;:{&#34;r&#34;:1.0,&#34;g&#34;:0.30980393290519714,&#34;b&#34;:0.73333334922790527,&#34;a&#34;:1.0},&#34;position&#34;:0.11999999731779099},{&#34;color&#34;:{&#34;r&#34;:0.60888892412185669,&#34;g&#34;:1.0,&#34;b&#34;:0.30980393290519714,&#34;a&#34;:1.0},&#34;position&#34;:0.39903846383094788},{&#34;color&#34;:{&#34;r&#34;:0.10980392247438431,&#34;g&#34;:0.56862747669219971,&#34;b&#34;:0.98823529481887817,&#34;a&#34;:1.0},&#34;position&#34;:0.70192307233810425},{&#34;color&#34;:{&#34;r&#34;:0.60392159223556519,&#34;g&#34;:0.17647059261798859,&#34;b&#34;:0.97254902124404907,&#34;a&#34;:1.0},&#34;position&#34;:0.87999999523162842},{&#34;color&#34;:{&#34;r&#34;:1.0,&#34;g&#34;:0.58431375026702881,&#34;b&#34;:0.20000000298023224,&#34;a&#34;:1.0},&#34;position&#34;:1.0}],&#34;stopsVar&#34;:[{&#34;color&#34;:{&#34;r&#34;:1.0,&#34;g&#34;:0.58431375026702881,&#34;b&#34;:0.20000000298023224,&#34;a&#34;:1.0},&#34;position&#34;:0.0},{&#34;color&#34;:{&#34;r&#34;:1.0,&#34;g&#34;:0.30980393290519714,&#34;b&#34;:0.73333334922790527,&#34;a&#34;:1.0},&#34;position&#34;:0.11999999731779099},{&#34;color&#34;:{&#34;r&#34;:0.60888892412185669,&#34;g&#34;:1.0,&#34;b&#34;:0.30980393290519714,&#34;a&#34;:1.0},&#34;position&#34;:0.39903846383094788},{&#34;color&#34;:{&#34;r&#34;:0.10980392247438431,&#34;g&#34;:0.56862747669219971,&#34;b&#34;:0.98823529481887817,&#34;a&#34;:1.0},&#34;position&#34;:0.70192307233810425},{&#34;color&#34;:{&#34;r&#34;:0.60392159223556519,&#34;g&#34;:0.17647059261798859,&#34;b&#34;:0.97254902124404907,&#34;a&#34;:1.0},&#34;position&#34;:0.87999999523162842},{&#34;color&#34;:{&#34;r&#34;:1.0,&#34;g&#34;:0.58431375026702881,&#34;b&#34;:0.20000000298023224,&#34;a&#34;:1.0},&#34;position&#34;:1.0}],&#34;transform&#34;:{&#34;m00&#34;:3.8149642949888984e-13,&#34;m01&#34;:71.365898132324219,&#34;m02&#34;:-24.753261566162109,&#34;m10&#34;:-71.855010986328125,&#34;m11&#34;:-5.4860135260525328e-14,&#34;m12&#34;:47.927650451660156},&#34;opacity&#34;:1.0,&#34;blendMode&#34;:&#34;NORMAL&#34;,&#34;visible&#34;:true}"
+        />
+        <path
+          d="M16.0431 12.0324C16.0431 13.3654 16.5272 15.8012 13.4845 18.4291C14.5218 16.2507 12.419 17.1497 10.9259 17.1497C8.09967 17.1497 5.80859 14.8586 5.80859 12.0324C5.80859 9.20615 8.09967 6.91504 10.9259 6.91504C13.752 6.91504 16.0431 9.20615 16.0431 12.0324Z"
+          fill="white"
+        />
+        <ellipse
+          cx="10.9283"
+          cy="12.0328"
+          rx="0.898978"
+          ry="0.898992"
+          fill="#6C6C6C"
+        />
+        <ellipse
+          cx="13.4849"
+          cy="12.0328"
+          rx="0.898978"
+          ry="0.898992"
+          fill="#6C6C6C"
+        />
+        <ellipse
+          cx="8.36968"
+          cy="12.0328"
+          rx="0.898978"
+          ry="0.898992"
+          fill="#6C6C6C"
+        />
+        <defs>
+          <clipPath id="paint0_angular_1004_8813_clip_path">
+            <path
+              fill-rule="evenodd"
+              clip-rule="evenodd"
+              d="M16.4395 10.6925C17.4389 12.4342 17.5855 14.7605 17.0781 17.0412C16.5847 19.2587 15.479 21.3907 14.002 22.8459L12.9346 23.463C11.6937 24.1793 10.1647 24.1794 8.92383 23.463L4.81641 21.091C6.48014 21.2357 8.24755 21.0003 9.87402 20.4474C12.1457 19.6751 14.1798 18.2734 15.2773 16.3839C16.7064 13.9237 16.7787 11.8621 16.2246 10.339C16.296 10.4538 16.3694 10.5705 16.4395 10.6925ZM12.5723 6.5646C14.5851 6.56993 16.7106 7.56255 18.4668 9.09488C20.0162 10.4468 21.2529 12.1974 21.8594 14.0041V15.9943C21.8594 17.4272 21.0944 18.7514 19.8535 19.4679L15.4492 22.0109C16.4736 20.6151 17.2295 18.9083 17.6182 17.1613C18.1443 14.7966 18.0091 12.3169 16.9189 10.4171C15.5014 7.94691 13.7497 6.85357 12.1523 6.57339C12.2894 6.56875 12.4294 6.56423 12.5723 6.5646ZM0 11.2697C0.704632 12.7816 1.7891 14.1898 3.0791 15.3166C4.87894 16.8885 7.10461 17.9397 9.28906 17.9455C12.1367 17.9529 13.9586 16.9824 15 15.7394C14.9357 15.8599 14.8712 15.9836 14.7998 16.1066C13.7886 17.8473 11.8825 19.1804 9.69531 19.924C7.65984 20.6159 5.41309 20.7847 3.47656 20.3175L2.00586 19.4679C0.764906 18.7514 0 17.4272 0 15.9943V11.2697ZM5.95215 2.2521C5.01991 3.60523 4.37186 5.22291 4.0625 6.87613C3.62624 9.20794 3.85535 11.6456 4.94141 13.5382C6.36156 16.013 8.11707 17.1052 9.7168 17.383C9.57761 17.3878 9.43521 17.3931 9.29004 17.3927C7.27637 17.3873 5.17407 16.4121 3.44238 14.8996C1.82788 13.4893 0.56156 11.633 0 9.71988V8.00601C0 6.57306 0.764906 5.24885 2.00586 4.53238L5.95215 2.2521ZM11.3975 7.05093C12.0141 7.06601 12.6881 7.21751 13.376 7.5607C13.0837 7.49777 12.8006 7.49218 12.5459 7.55679L12.6816 8.09292C13.0083 8.00995 13.4967 8.1005 14.0215 8.41421C14.538 8.72301 15.057 9.23022 15.4326 9.91909C15.7285 10.4617 15.9343 11.1225 15.9805 11.8918C15.8889 11.6052 15.7517 11.3555 15.5674 11.1662L15.1709 11.5519C15.406 11.7933 15.5727 12.2611 15.5635 12.8722C15.5543 13.4739 15.3736 14.1772 14.9648 14.8468C14.642 15.3757 14.171 15.8854 13.5254 16.3107C13.73 16.0867 13.8799 15.8413 13.9521 15.5851L13.4189 15.4347C13.3275 15.7591 13.0058 16.1381 12.4717 16.4357C11.9461 16.7285 11.2471 16.9236 10.4629 16.9044C9.84516 16.8893 9.1696 16.7382 8.48047 16.3937C8.77503 16.4579 9.06081 16.4638 9.31738 16.3986L9.18066 15.8625C8.85403 15.9453 8.36539 15.8557 7.84082 15.5421C7.32436 15.2334 6.80623 14.7251 6.43066 14.0363C6.13467 13.4934 5.92691 12.8324 5.88086 12.0626C5.97253 12.3504 6.11088 12.6013 6.2959 12.7912L6.69141 12.4044C6.45639 12.163 6.28955 11.6951 6.29883 11.0841C6.30799 10.4824 6.48868 9.77922 6.89746 9.10952C7.21926 8.58233 7.68762 8.07306 8.33008 7.64859C8.12755 7.87138 7.97995 8.11577 7.9082 8.37027L8.44141 8.52066C8.53286 8.19625 8.8546 7.81729 9.38867 7.51968C9.91427 7.22684 10.6133 7.0318 11.3975 7.05093ZM8.92383 0.537258C10.1647 -0.179152 11.6937 -0.17902 12.9346 0.537258L16.832 2.78726C15.2289 2.68408 13.5406 2.93545 11.9824 3.47671C9.71315 4.26504 7.68197 5.68288 6.58496 7.57144C5.15353 10.0358 5.08346 12.1004 5.64062 13.6242C5.56755 13.507 5.49251 13.3876 5.4209 13.2628C4.41748 11.5142 4.18713 9.21872 4.60645 6.97769C4.99237 4.91536 5.92418 2.92968 7.26758 1.49331L8.92383 0.537258ZM12.1641 4.00015C14.0959 3.32907 16.2174 3.13043 18.084 3.51089L19.8535 4.53238C21.0944 5.24887 21.8594 6.57311 21.8594 8.00601V12.5626C21.1452 11.1171 20.0805 9.7689 18.8301 8.67788C17.0078 7.08795 14.7586 6.01663 12.5732 6.01089C9.72539 6.00349 7.90267 6.97374 6.86133 8.21695C6.92577 8.09606 6.9918 7.97218 7.06348 7.84878C8.07528 6.10725 9.97945 4.75906 12.1641 4.00015Z"
+            />
+          </clipPath>
+        </defs>
+      </svg>
+    </div>
+
+    <div class="vc-ai-agent-header__wrapper">
+      <div class="vc-ai-agent-header__content">
+        <div class="vc-ai-agent-header__title">
+          {{ title }}
+        </div>
+      </div>
+    </div>
+
+    <div class="vc-ai-agent-header__controls">
+      <div
+        v-if="isExpanded"
+        class="vc-ai-agent-header__button"
+        title="Collapse"
+        @click="$emit('collapse')"
+      >
+        <VcIcon icon="material-minimize" />
+      </div>
+      <div
+        v-else
+        class="vc-ai-agent-header__button"
+        title="Expand"
+        @click="$emit('expand')"
+      >
+        <VcIcon icon="material-toolbar" />
+      </div>
+      <div
+        class="vc-ai-agent-header__button"
+        title="Close"
+        @click="$emit('close')"
+      >
+        <VcIcon icon="material-close" />
+      </div>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { VcIcon } from "../../../../../ui/components";
+
+defineProps<{
+  title?: string;
+  isExpanded: boolean;
+}>();
+
+defineEmits<{
+  (e: "close"): void;
+  (e: "expand"): void;
+  (e: "collapse"): void;
+}>();
+</script>
+
+<style lang="scss">
+.vc-ai-agent-header {
+  @apply tw-shrink-0 tw-flex tw-items-center tw-py-0 tw-px-6 tw-border-solid tw-border-b;
+  height: var(--blade-header-height, 70px);
+  background-color: var(--blade-header-background-color, var(--additional-50));
+  border-color: var(--blade-header-border-color, var(--neutrals-200));
+
+  &__left {
+    @apply tw-flex tw-flex-row tw-items-center;
+  }
+
+  &__icon {
+    @apply tw-mr-3;
+    color: var(--primary-500);
+  }
+
+  &__wrapper {
+    @apply tw-flex tw-items-center tw-justify-between tw-grow tw-basis-0 tw-overflow-hidden;
+  }
+
+  &__content {
+    @apply tw-overflow-hidden;
+  }
+
+  &__title {
+    @apply tw-truncate tw-font-semibold;
+    color: var(--blade-header-title-color, var(--neutrals-950));
+    font-size: var(--blade-header-title-font-size, 19px);
+  }
+
+  &__controls {
+    @apply tw-flex tw-items-center;
+  }
+
+  &__button {
+    @apply tw-ml-2.5 tw-cursor-pointer;
+    color: var(--blade-header-button-color, var(--neutrals-400));
+
+    &:hover {
+      color: var(--blade-header-button-color-hover, var(--neutrals-500));
+    }
+  }
+}
+</style>

package/core/plugins/ai-agent/components/_internal/VcAiAgentIframe.vue

@@ -0,0 +1,77 @@
+<template>
+  <div class="vc-ai-agent-iframe">
+    <iframe
+      v-if="url"
+      ref="iframeRef"
+      :src="url"
+      class="vc-ai-agent-iframe__frame"
+      sandbox="allow-scripts allow-same-origin allow-forms allow-popups allow-popups-to-escape-sandbox"
+      allow="clipboard-read; clipboard-write"
+      @load="onLoad"
+    />
+    <div v-else class="vc-ai-agent-iframe__placeholder">
+      <VcIcon icon="lucide-sparkles" size="xl" class="vc-ai-agent-iframe__placeholder-icon" />
+      <p class="vc-ai-agent-iframe__placeholder-text">AI Agent URL not configured</p>
+    </div>
+  </div>
+</template>
+
+<script lang="ts" setup>
+import { ref, onMounted, watch } from "vue";
+import { VcIcon } from "../../../../../ui/components";
+
+const props = defineProps<{
+  url: string;
+}>();
+
+const emit = defineEmits<{
+  (e: "iframe-ready", iframe: HTMLIFrameElement): void;
+}>();
+
+const iframeRef = ref<HTMLIFrameElement | null>(null);
+
+// Emit iframe ref as soon as it's available in the DOM (before @load)
+// This is critical because chatbot sends CHAT_READY before @load fires
+watch(iframeRef, (iframe) => {
+  if (iframe) {
+    emit("iframe-ready", iframe);
+  }
+}, { immediate: true });
+
+const onLoad = () => {
+  // onLoad is now just for logging/debugging, ref is already emitted
+  console.debug("[VcAiAgentIframe] Iframe loaded");
+};
+
+onMounted(() => {
+  // Emit again on mount in case watch didn't catch it
+  if (iframeRef.value) {
+    emit("iframe-ready", iframeRef.value);
+  }
+});
+</script>
+
+<style lang="scss">
+.vc-ai-agent-iframe {
+  @apply tw-w-full tw-h-full tw-flex tw-flex-col;
+
+  &__frame {
+    @apply tw-w-full tw-h-full tw-border-0 tw-flex-1;
+    background-color: var(--ai-panel-iframe-bg, var(--additional-50));
+  }
+
+  &__placeholder {
+    @apply tw-w-full tw-h-full tw-flex tw-flex-col tw-items-center tw-justify-center tw-gap-4;
+    background-color: var(--ai-panel-placeholder-bg, var(--neutrals-50));
+  }
+
+  &__placeholder-icon {
+    color: var(--ai-panel-placeholder-icon-color, var(--neutrals-300));
+  }
+
+  &__placeholder-text {
+    @apply tw-text-sm tw-m-0;
+    color: var(--ai-panel-placeholder-text-color, var(--neutrals-500));
+  }
+}
+</style>

package/core/plugins/ai-agent/components/index.ts

@@ -0,0 +1 @@
+export { default as VcAiAgentPanel } from "./VcAiAgentPanel.vue";

package/core/plugins/ai-agent/composables/index.ts

@@ -0,0 +1,4 @@
+export { useAiAgent, provideAiAgentService, createAiAgentToolbarButton } from "./useAiAgent";
+export type { UseAiAgentReturn, ProvideAiAgentServiceOptions } from "./useAiAgent";
+
+export { useAiAgentContext, clearPreviewState } from "./useAiAgentContext";

package/core/plugins/ai-agent/composables/useAiAgent.ts

@@ -0,0 +1,231 @@
+import { inject, provide } from "vue";
+import { createAiAgentService, type IAiAgentServiceInternal } from "../services/ai-agent-service";
+import { AiAgentServiceKey, LanguageServiceKey, ToolbarServiceKey } from "../../../../injection-keys";
+import type {
+  IAiAgentService,
+  IAiAgentConfig,
+  IAiAgentMessage,
+  IAiAgentBladeContext,
+} from "../types";
+import { createLogger, InjectionError } from "../../../utilities";
+import { useUser } from "../../../composables/useUser";
+import { useBladeNavigation } from "../../../../shared/components/blade-navigation/composables";
+import { AI_AGENT_TOOLBAR_BUTTON_ID, AI_AGENT_TOOLBAR_BUTTON_ICON, AI_AGENT_TOOLBAR_BUTTON_TITLE } from "../constants";
+import type { IToolbarService } from "../../../services/toolbar-service";
+
+const logger = createLogger("use-ai-agent");
+
+/**
+ * Options for providing the AI agent service
+ */
+export interface ProvideAiAgentServiceOptions {
+  /** Initial configuration for the AI agent */
+  config?: Partial<IAiAgentConfig>;
+  /**
+   * Whether to add the AI button to all blade toolbars automatically.
+   * Default: true
+   */
+  addGlobalToolbarButton?: boolean;
+}
+
+/**
+ * Provides the AI agent service at the current component level.
+ * Should be called once at the app level (in VcApp or plugin install).
+ *
+ * @param options - Configuration options
+ */
+export function provideAiAgentService(options?: ProvideAiAgentServiceOptions): IAiAgentServiceInternal {
+  const languageService = inject(LanguageServiceKey);
+  const { user, getAccessToken } = useUser();
+  const { blades, openBlade, resolveBladeByName } = useBladeNavigation();
+
+  // Create the service
+  const service = createAiAgentService({
+    userGetter: () => {
+      if (!user.value) return undefined;
+      return {
+        id: user.value.id,
+        userName: user.value.userName,
+        isAdministrator: user.value.isAdministrator,
+        permissions: user.value.permissions,
+      };
+    },
+    bladeGetter: (): IAiAgentBladeContext | null => {
+      // Get the last (most recent) blade
+      const lastBlade = blades.value[blades.value.length - 1];
+      if (!lastBlade) return null;
+
+      return {
+        id: lastBlade.type?.name?.toLowerCase() ?? "unknown",
+        name: lastBlade.type?.name ?? "Unknown",
+        title: lastBlade.props?.navigation?.instance?.title,
+        param: lastBlade.props?.param,
+        options: lastBlade.props?.options,
+      };
+    },
+    localeGetter: () => languageService?.currentLocale.value ?? "en",
+    tokenGetter: getAccessToken,
+    navigateToBlade: (bladeName: string, param?: string, bladeOptions?: Record<string, unknown>) => {
+      const blade = resolveBladeByName(bladeName);
+      if (blade) {
+        openBlade({ blade, param, options: bladeOptions });
+        logger.debug(`Navigated to blade: ${bladeName}`);
+      } else {
+        logger.warn(`Blade not found: ${bladeName}`);
+      }
+    },
+    reloadBlade: () => {
+      // Emit reload on current blade if available (last blade in the list)
+      const lastBlade = blades.value[blades.value.length - 1];
+      if (lastBlade?.props?.navigation?.instance?.reload) {
+        lastBlade.props.navigation.instance.reload();
+        logger.debug("Current blade reloaded");
+      }
+    },
+    initialConfig: options?.config,
+  });
+
+  provide(AiAgentServiceKey, service);
+  logger.debug("AiAgentService provided");
+
+  // Register global toolbar button with wildcard "*" if enabled
+  const addGlobalToolbarButton = options?.addGlobalToolbarButton ?? true;
+  if (addGlobalToolbarButton) {
+    // Get toolbar service from injection (already created by VcShell plugin)
+    const toolbarService = inject<IToolbarService | null>(ToolbarServiceKey, null);
+    if (toolbarService) {
+      toolbarService.registerToolbarItem(
+        {
+          id: AI_AGENT_TOOLBAR_BUTTON_ID,
+          icon: AI_AGENT_TOOLBAR_BUTTON_ICON,
+          title: AI_AGENT_TOOLBAR_BUTTON_TITLE,
+          clickHandler: () => {
+            service.togglePanel();
+          },
+        },
+        "*", // Wildcard for all blades
+      );
+      logger.debug("Global AI toolbar button registered with wildcard '*'");
+    } else {
+      logger.warn("Toolbar service not available, AI button not registered");
+    }
+  }
+
+  return service;
+}
+
+/**
+ * Return type for useAiAgent composable
+ */
+export interface UseAiAgentReturn {
+  /** Current panel state ("closed" | "open" | "expanded") */
+  panelState: IAiAgentService["panelState"];
+  /** Panel configuration */
+  config: IAiAgentService["config"];
+  /** Current context (reactive) */
+  context: IAiAgentService["context"];
+  /** Whether panel is open (not closed) */
+  isOpen: IAiAgentService["isOpen"];
+  /** Whether panel is in expanded state */
+  isExpanded: IAiAgentService["isExpanded"];
+  /** Total count of items in current context */
+  totalItemsCount: IAiAgentService["totalItemsCount"];
+  /** Open the AI panel */
+  openPanel: () => void;
+  /** Close the AI panel */
+  closePanel: () => void;
+  /** Toggle panel open/close */
+  togglePanel: () => void;
+  /** Expand the panel to larger width */
+  expandPanel: () => void;
+  /** Collapse panel to normal width */
+  collapsePanel: () => void;
+  /** Update configuration */
+  setConfig: (config: Partial<IAiAgentConfig>) => void;
+  /** Send message to AI agent iframe */
+  sendMessage: IAiAgentService["sendMessage"];
+  /** Register message handler, returns unsubscribe function */
+  onMessage: (handler: (event: IAiAgentMessage) => void) => () => void;
+}
+
+/**
+ * Composable for interacting with the AI agent panel.
+ *
+ * @example
+ * ```typescript
+ * const { togglePanel, isOpen, onMessage } = useAiAgent();
+ *
+ * // Toggle AI panel
+ * const handleAiClick = () => togglePanel();
+ *
+ * // Listen for messages from AI agent
+ * onMessage((message) => {
+ *   if (message.type === 'PREVIEW_CHANGES') {
+ *     // Handle preview changes
+ *   }
+ * });
+ * ```
+ */
+export function useAiAgent(): UseAiAgentReturn {
+  const service = inject(AiAgentServiceKey);
+  if (!service) {
+    logger.error("AiAgentService not found. Did you forget to call provideAiAgentService()?");
+    throw new InjectionError("AiAgentService");
+  }
+
+  return {
+    // State
+    panelState: service.panelState,
+    config: service.config,
+    context: service.context,
+    isOpen: service.isOpen,
+    isExpanded: service.isExpanded,
+    totalItemsCount: service.totalItemsCount,
+
+    // Panel control
+    openPanel: service.openPanel,
+    closePanel: service.closePanel,
+    togglePanel: service.togglePanel,
+    expandPanel: service.expandPanel,
+    collapsePanel: service.collapsePanel,
+
+    // Configuration
+    setConfig: service.setConfig,
+
+    // Communication
+    sendMessage: service.sendMessage,
+    onMessage: service.onMessage,
+  };
+}
+
+/**
+ * Creates a toolbar button configuration for opening the AI agent.
+ * Can be used directly in blade toolbar definitions.
+ *
+ * @example
+ * ```typescript
+ * const bladeToolbar = [
+ *   createAiAgentToolbarButton(),
+ *   // ... other toolbar items
+ * ];
+ * ```
+ */
+export function createAiAgentToolbarButton(options?: { title?: string; icon?: string }) {
+  return {
+    id: "ai-agent-toggle",
+    icon: options?.icon ?? "lucide-sparkles",
+    title: options?.title ?? "AI Assistant",
+    clickHandler: () => {
+      try {
+        const service = inject(AiAgentServiceKey);
+        if (service) {
+          service.togglePanel();
+        } else {
+          logger.warn("AiAgentService not available for toolbar button");
+        }
+      } catch (e) {
+        logger.error("Failed to toggle AI panel:", e);
+      }
+    },
+  };
+}