@aleph-alpha/chat-kit 6.5.0 → 6.7.0

package/src/components/base/CkToolApproval/CkToolApproval.vue

@@ -0,0 +1,240 @@
+<script setup lang="ts">
+import {
+  computed,
+  nextTick,
+  ref,
+  toRaw,
+  useId,
+  useTemplateRef,
+  watch,
+} from 'vue';
+import { UiButton, UiSeparator } from '@aleph-alpha/ui-library';
+import {
+  defaultChatKitLabels,
+  useChatKitLabels,
+  type ChatKitLabels,
+} from '../../../handlers/useChatKitLabels';
+import ApprovalCard from './ApprovalCard.vue';
+import ArgumentsJson from './ArgumentsJson.vue';
+import BodyBoundary from './BodyBoundary.vue';
+import CardHeading from './CardHeading.vue';
+import ResultRow from './ResultRow.vue';
+import {
+  isDecidedStatus,
+  resultLineOf,
+  toolApprovalOutcome,
+  type CkToolApprovalOutcome,
+} from './outcomes';
+import { serializeArguments } from './serializeArguments';
+import { toolTitleFromName } from './toolTitle';
+import type {
+  CkToolApprovalEmits,
+  CkToolApprovalExposed,
+  CkToolApprovalProps,
+  CkToolApprovalSlots,
+} from './types';
+
+defineOptions({
+  name: 'CkToolApproval',
+  // The root is a fragment (card or row, plus the announcer); attrs go to the card or row.
+  inheritAttrs: false,
+});
+
+const DEFAULT_CONNECTOR_ICON = 'app-window';
+
+const props = defineProps<CkToolApprovalProps>();
+const emit = defineEmits<CkToolApprovalEmits>();
+defineSlots<CkToolApprovalSlots>();
+
+// useChatKitLabels types every label as optional; fill the gaps once so the
+// buttons and the result row read the same, complete set.
+const providedLabels = useChatKitLabels();
+const labels = computed(() => ({
+  ...defaultChatKitLabels,
+  ...definedOnly(providedLabels.value),
+}));
+
+// A label set to undefined falls back to the default instead of blanking the text.
+function definedOnly(provided: ChatKitLabels): Partial<ChatKitLabels> {
+  return Object.fromEntries(
+    Object.entries(provided).filter(([, text]) => text !== undefined),
+  );
+}
+
+const headingId = useId();
+const pendingCard =
+  useTemplateRef<InstanceType<typeof ApprovalCard>>('pendingCard');
+const resultRow = useTemplateRef<InstanceType<typeof ResultRow>>('resultRow');
+
+// Locks both buttons after the first click, so a double click cannot send two
+// answers. Released by a new request, any status change, or the host calling
+// unlock() after a failed send.
+const locked = ref(false);
+
+function unlock(): void {
+  locked.value = false;
+}
+
+// Separate sources: a fresh request object with the same id must not unlock.
+watch([() => props.request.id, () => props.status], unlock);
+
+function allow(): void {
+  lock();
+  emit('allow', props.request.id);
+}
+
+function deny(): void {
+  lock();
+  emit('deny', props.request.id);
+}
+
+function lock(): void {
+  // Browsers drop focus from a button once it is disabled; park it on the card
+  // so it can move on to the result row when the status arrives.
+  if (pendingCard.value?.containsFocus()) pendingCard.value.focus();
+  locked.value = true;
+}
+
+// Read aloud when a decision lands while focus is elsewhere in the page.
+const announcement = ref('');
+
+watch(
+  () => props.request.id,
+  () => {
+    announcement.value = '';
+  },
+);
+
+// The clicked button disappears when the card collapses; move focus to the
+// result so keyboard and screen-reader users land on the outcome. Without
+// focus in the card, announce the outcome instead of taking focus.
+watch(
+  () => props.status,
+  (status, previous) => {
+    if (previous !== 'pending' || status === 'pending') return;
+    if (pendingCard.value?.containsFocus()) {
+      void nextTick(() => resultRow.value?.focus());
+    } else {
+      announcement.value = resultLineOf(outcome.value);
+    }
+  },
+);
+
+defineExpose<CkToolApprovalExposed>({ unlock });
+
+const title = computed(
+  () => props.request.toolTitle ?? toolTitleFromName(props.request.toolName),
+);
+
+const connectorIcon = computed(
+  () => props.request.connectorIcon ?? DEFAULT_CONNECTOR_ICON,
+);
+
+// toRaw: a component map passed in reactive state would otherwise be rendered
+// as a reactive object, which Vue warns about.
+const customBody = computed(() => {
+  const toolBodies = ownEntry(props.bodyComponents, props.request.connector);
+  const body = ownEntry(toolBodies, props.request.toolName);
+  return body && toRaw(body);
+});
+
+// hasOwn: a tool named `constructor` must not resolve to Object.prototype's.
+function ownEntry<T>(
+  record: Readonly<Record<string, T>> | undefined,
+  key: string,
+): T | undefined {
+  return record && Object.hasOwn(record, key) ? record[key] : undefined;
+}
+
+const serializedArguments = computed(() =>
+  serializeArguments(props.request.arguments),
+);
+
+const outcome = computed((): CkToolApprovalOutcome => {
+  if (isDecidedStatus(props.status)) {
+    return toolApprovalOutcome(props.status, labels.value, props.summary);
+  }
+  // eslint-disable-next-line no-console
+  console.warn(
+    `[CkToolApproval] Unknown status "${props.status}", showing it as failed.`,
+  );
+  return toolApprovalOutcome('failed', labels.value, props.summary);
+});
+</script>
+
+<template>
+  <ApprovalCard
+    v-if="status === 'pending'"
+    v-bind="$attrs"
+    ref="pendingCard"
+    :heading-id="headingId"
+    class="flex flex-col gap-3 py-4"
+  >
+    <CardHeading
+      :id="headingId"
+      class="px-6"
+      size="card"
+      :title="title"
+      :connector-label="request.connectorLabel"
+      :connector-icon="connectorIcon"
+    >
+      <template v-if="$slots['connector-icon']" #icon>
+        <slot name="connector-icon" />
+      </template>
+    </CardHeading>
+
+    <UiSeparator />
+
+    <div class="px-6 py-3">
+      <BodyBoundary v-if="customBody" :key="request.id">
+        <component :is="customBody" :request="request" />
+        <template #fallback>
+          <ArgumentsJson :serialized="serializedArguments" :labels="labels" />
+        </template>
+      </BodyBoundary>
+      <ArgumentsJson
+        v-else
+        :serialized="serializedArguments"
+        :labels="labels"
+      />
+    </div>
+
+    <UiSeparator />
+
+    <div class="flex items-center justify-end gap-2 px-6">
+      <UiButton variant="secondary" :disabled="locked" @click="deny">
+        {{ labels.toolApprovalDeny }}
+      </UiButton>
+      <!-- Nobody should allow arguments they cannot see. -->
+      <UiButton
+        :disabled="locked || !serializedArguments.readable"
+        @click="allow"
+      >
+        {{ labels.toolApprovalAllow }}
+      </UiButton>
+    </div>
+  </ApprovalCard>
+
+  <ResultRow
+    v-else
+    v-bind="$attrs"
+    ref="resultRow"
+    :outcome="outcome"
+    :heading-id="headingId"
+  >
+    <template #heading>
+      <CardHeading
+        :id="headingId"
+        size="row"
+        :title="title"
+        :connector-label="request.connectorLabel"
+        :connector-icon="connectorIcon"
+      >
+        <template v-if="$slots['connector-icon']" #icon>
+          <slot name="connector-icon" />
+        </template>
+      </CardHeading>
+    </template>
+  </ResultRow>
+  <span class="sr-only" aria-live="polite">{{ announcement }}</span>
+</template>

package/src/components/base/CkToolApproval/ResultRow.vue

@@ -0,0 +1,52 @@
+<script setup lang="ts">
+import { computed, useId, useTemplateRef } from 'vue';
+import { UiBadge, UiIcon } from '@aleph-alpha/ui-library';
+import ApprovalCard from './ApprovalCard.vue';
+import { BADGE_ICON_SIZE } from './badge';
+import { resultLineOf, type CkToolApprovalOutcome } from './outcomes';
+
+const props = defineProps<{
+  outcome: CkToolApprovalOutcome;
+  headingId: string;
+}>();
+
+defineSlots<{
+  heading: () => unknown;
+}>();
+
+const descriptionId = useId();
+const card = useTemplateRef<InstanceType<typeof ApprovalCard>>('card');
+
+const resultLine = computed(() => resultLineOf(props.outcome));
+
+defineExpose({
+  focus: (): void => card.value?.focus(),
+});
+</script>
+
+<template>
+  <ApprovalCard
+    ref="card"
+    :heading-id="headingId"
+    :description-id="descriptionId"
+    class="flex items-center gap-3 px-5 py-4"
+  >
+    <div class="flex min-w-0 flex-1 flex-col gap-0.5">
+      <slot name="heading" />
+      <p
+        :id="descriptionId"
+        class="truncate text-xs leading-[14px] text-content-on-surface-muted"
+      >
+        {{ resultLine }}
+      </p>
+    </div>
+    <UiBadge :variant="outcome.badge.variant" size="small" class="shrink-0">
+      <UiIcon
+        :name="outcome.badge.icon"
+        :size="BADGE_ICON_SIZE"
+        aria-hidden="true"
+      />
+      {{ outcome.badge.text }}
+    </UiBadge>
+  </ApprovalCard>
+</template>

package/src/components/base/CkToolApproval/badge.ts

@@ -0,0 +1,2 @@
+/** Icon size inside the small badges (connector chip and status pill). */
+export const BADGE_ICON_SIZE = 12;

package/src/components/base/CkToolApproval/exports.spec.ts

@@ -0,0 +1,22 @@
+import CkToolApproval from './CkToolApproval.vue';
+import * as components from '../../index';
+import * as packageRoot from '../../../index';
+import type {
+  CkToolApprovalBodyProps,
+  CkToolApprovalExposed,
+} from '../../../index';
+
+describe('CkToolApproval exports', () => {
+  it('is part of the public components entry', () => {
+    expect(components.CkToolApproval).toBe(CkToolApproval);
+  });
+
+  it('is part of the package entry consumers import from', () => {
+    expect(packageRoot.CkToolApproval).toBe(CkToolApproval);
+  });
+
+  it('exports the types a host needs for a custom body and for unlock()', () => {
+    expectTypeOf<CkToolApprovalBodyProps>().toHaveProperty('request');
+    expectTypeOf<CkToolApprovalExposed>().toHaveProperty('unlock');
+  });
+});

package/src/components/base/CkToolApproval/index.ts

@@ -0,0 +1,2 @@
+export { default as CkToolApproval } from './CkToolApproval.vue';
+export type * from './types';

package/src/components/base/CkToolApproval/outcomes.ts

@@ -0,0 +1,95 @@
+import type { UiBadgeVariants } from '@aleph-alpha/ui-library';
+import type { ChatKitLabels } from '../../../handlers/useChatKitLabels';
+import { ckToolApprovalStatuses, type CkToolApprovalStatus } from './types';
+
+/** A status the user has already decided, shown as the collapsed result row. */
+export type CkToolApprovalDecidedStatus = Exclude<
+  CkToolApprovalStatus,
+  'pending'
+>;
+
+/** Guards against statuses a JavaScript host may pass that the type does not allow. */
+export function isDecidedStatus(
+  status: string,
+): status is CkToolApprovalDecidedStatus {
+  return (
+    status !== 'pending' &&
+    ckToolApprovalStatuses.some((known) => known === status)
+  );
+}
+
+/** The status pill on the right of the result row. */
+export interface CkToolApprovalBadge {
+  variant: Extract<UiBadgeVariants, 'verified' | 'secondary' | 'destructive'>;
+  icon: string;
+  text: string;
+}
+
+export interface CkToolApprovalOutcome {
+  /** The outcome half of the result line, e.g. "Denied by you". */
+  result: string;
+  /** Detail after the outcome, e.g. "Nothing was updated". Empty to omit. */
+  detail: string;
+  badge: CkToolApprovalBadge;
+}
+
+const RESULT_SEPARATOR = ' · ';
+
+/** The one-line outcome, e.g. "Denied by you · Nothing was updated". */
+export function resultLineOf(outcome: CkToolApprovalOutcome): string {
+  return [outcome.result, outcome.detail]
+    .filter(Boolean)
+    .join(RESULT_SEPARATOR);
+}
+
+/**
+ * The result line and badge for each decided status, from the design's
+ * "HITL Request" component and its Skipped variant.
+ */
+export function toolApprovalOutcome(
+  status: CkToolApprovalDecidedStatus,
+  labels: Required<ChatKitLabels>,
+  summary?: string,
+): CkToolApprovalOutcome {
+  // Every status where the call never ran shares the same fallback detail.
+  const notRunDetail = summary ?? labels.toolApprovalNothingChanged;
+  const outcomes: Record<CkToolApprovalDecidedStatus, CkToolApprovalOutcome> = {
+    allowed: {
+      result: labels.toolApprovalAllowedResult,
+      detail: summary ?? '',
+      badge: {
+        variant: 'verified',
+        icon: 'check',
+        text: labels.toolApprovalAllowedBadge,
+      },
+    },
+    denied: {
+      result: labels.toolApprovalDeniedResult,
+      detail: notRunDetail,
+      badge: {
+        variant: 'secondary',
+        icon: 'ban',
+        text: labels.toolApprovalDeniedBadge,
+      },
+    },
+    failed: {
+      result: labels.toolApprovalFailedResult,
+      detail: notRunDetail,
+      badge: {
+        variant: 'destructive',
+        icon: 'triangle-alert',
+        text: labels.toolApprovalFailedBadge,
+      },
+    },
+    skipped: {
+      result: labels.toolApprovalSkippedResult,
+      detail: notRunDetail,
+      badge: {
+        variant: 'secondary',
+        icon: 'skip-forward',
+        text: labels.toolApprovalSkippedBadge,
+      },
+    },
+  };
+  return outcomes[status];
+}

package/src/components/base/CkToolApproval/serializeArguments.ts

@@ -0,0 +1,18 @@
+/** The arguments as JSON text, or the fact that they cannot be shown. */
+export type SerializedArguments =
+  | { readable: true; json: string }
+  | { readable: false };
+
+/**
+ * Turns the arguments into indented JSON. Values JSON cannot hold, such as a
+ * bigint or a circular reference, make them unreadable instead of throwing.
+ */
+export function serializeArguments(args: unknown): SerializedArguments {
+  try {
+    return { readable: true, json: JSON.stringify(args, null, 2) };
+  } catch (error) {
+    // eslint-disable-next-line no-console
+    console.error('[CkToolApproval] Arguments cannot be shown as JSON:', error);
+    return { readable: false };
+  }
+}

package/src/components/base/CkToolApproval/toolTitle.spec.ts

@@ -0,0 +1,23 @@
+import { toolTitleFromName } from './toolTitle';
+
+describe('toolTitleFromName', () => {
+  it.each([
+    ['update_work_items', 'Update work items'],
+    ['createJiraIssue', 'Create jira issue'],
+    ['send-message', 'Send message'],
+    ['GetDocument', 'Get document'],
+    ['list__projects', 'List projects'],
+    ['search', 'Search'],
+    ['upload_file_v2', 'Upload file v2'],
+    ['getHTTPResponse', 'Get HTTP response'],
+    ['getPDF', 'Get PDF'],
+    ['listMCPServers', 'List MCP servers'],
+    ['admin.tools.list', 'Admin tools list'],
+  ])('turns %s into %s', (name, title) => {
+    expect(toolTitleFromName(name)).toBe(title);
+  });
+
+  it('keeps an empty name empty instead of inventing a title', () => {
+    expect(toolTitleFromName('')).toBe('');
+  });
+});

package/src/components/base/CkToolApproval/toolTitle.ts

@@ -0,0 +1,19 @@
+/**
+ * Turns a machine tool name into a readable action, for tools whose server
+ * gives no human title: `update_work_items` and `getPDF` become
+ * "Update work items" and "Get PDF".
+ */
+export function toolTitleFromName(toolName: string): string {
+  const words = toolName
+    .replace(/([a-z0-9])([A-Z])/g, '$1 $2')
+    .replace(/([A-Z])(?=[A-Z][a-z])/g, '$1 ')
+    .split(/[\s_.-]+/)
+    .filter(Boolean)
+    .map((word) => (isAcronym(word) ? word : word.toLowerCase()));
+  const sentence = words.join(' ');
+  return sentence.charAt(0).toUpperCase() + sentence.slice(1);
+}
+
+function isAcronym(word: string): boolean {
+  return /^[A-Z]{2,}$/.test(word);
+}

package/src/components/base/CkToolApproval/types.ts

@@ -0,0 +1,118 @@
+import type { Component } from 'vue';
+
+/**
+ * Where an approval stands: waiting for the user, or decided.
+ * `failed` means the user allowed the call but the tool errored.
+ * `skipped` means the user sent a new message instead of answering.
+ */
+export const ckToolApprovalStatuses = [
+  'pending',
+  'allowed',
+  'denied',
+  'failed',
+  'skipped',
+] as const;
+
+export type CkToolApprovalStatus = (typeof ckToolApprovalStatuses)[number];
+
+/**
+ * A tool call the agent wants to run and is waiting on the user for.
+ * Transport-neutral: the host converts its own wire format (a Responses API
+ * `mcp_approval_request`, an agent interrupt, ...) into this shape.
+ */
+export interface CkToolApprovalRequest {
+  /** Id the host needs to answer the request, emitted back with the decision. */
+  id: string;
+  /** Machine name of the connector the tool belongs to, e.g. `polarion`. */
+  connector: string;
+  /**
+   * Display name of the connector, shown as a chip next to the header, e.g.
+   * `"Polarion"`. Omit to hide the chip, for example when the chat is
+   * embedded in the connector's own app.
+   */
+  connectorLabel?: string;
+  /**
+   * Lucide icon shown in the connector chip, e.g. `"mail"`. Defaults to
+   * `"app-window"`. For a brand logo, use the `connector-icon` slot instead.
+   */
+  connectorIcon?: string;
+  /** Machine name of the tool, e.g. `update_work_items`. */
+  toolName: string;
+  /**
+   * Human title of the tool, shown as the header, e.g. `"Update work items"`.
+   * MCP servers provide one per tool. When omitted, the header is derived
+   * from `toolName`.
+   */
+  toolTitle?: string;
+  /** The arguments the agent wants to call the tool with, already parsed. */
+  arguments: Readonly<Record<string, unknown>>;
+}
+
+/**
+ * Custom approval bodies, keyed by connector, then by tool name. A request
+ * with no entry falls back to the JSON view. Each component receives the
+ * request as its `request` prop.
+ *
+ * @example
+ * { polarion: { update_work_items: PolarionWorkItemsBody } }
+ */
+export type CkToolApprovalBodyComponents = Readonly<
+  Record<string, Readonly<Record<string, Component<CkToolApprovalBodyProps>>>>
+>;
+
+/** Props every custom approval body receives. */
+export interface CkToolApprovalBodyProps {
+  request: CkToolApprovalRequest;
+}
+
+/**
+ * Asks the user to allow or deny a tool call the agent paused on, then
+ * collapses to a one-line result once decided. Shows the call's arguments as
+ * JSON unless the host registers a custom body for that connector and tool.
+ *
+ * Purely presentational: the host owns the request, sends the decision to its
+ * backend and passes the resulting `status` back in. Emits `allow` or `deny`
+ * with the request id, then locks both buttons until `status` changes or the
+ * host calls the exposed `unlock()`.
+ *
+ * @category Feedback
+ * @useCases human in the loop approval, confirm a tool call before it runs, show the outcome of a tool call
+ * @keywords approval, hitl, human in the loop, tool call, confirm, allow, deny, permission, mcp
+ * @related CkAgentMessage, CkConversation
+ */
+export interface CkToolApprovalProps {
+  /** The tool call waiting for a decision. */
+  request: CkToolApprovalRequest;
+  /** Current state. `pending` shows the full card with Deny and Allow. */
+  status: CkToolApprovalStatus;
+  /**
+   * Outcome detail after the result, for any decided status, e.g.
+   * `"2 work items updated"` or `"Nothing was sent"`. Pass a fully formatted,
+   * localized string. When omitted, allowed shows no detail and the other
+   * statuses fall back to `toolApprovalNothingChanged` ("Nothing was updated").
+   * Pass an empty string to show no detail.
+   */
+  summary?: string;
+  /** Custom bodies per connector and tool, replacing the JSON view. */
+  bodyComponents?: CkToolApprovalBodyComponents;
+}
+
+export interface CkToolApprovalSlots {
+  /** Replaces the connector chip's icon, e.g. with a brand logo image. */
+  'connector-icon'?: () => unknown;
+}
+
+export interface CkToolApprovalEmits {
+  /** The user allowed the call. Payload is `request.id`. */
+  (e: 'allow', id: string): void;
+  /** The user denied the call. Payload is `request.id`. */
+  (e: 'deny', id: string): void;
+}
+
+export interface CkToolApprovalExposed {
+  /**
+   * Re-enables Allow and Deny after a click. Call it when sending the
+   * decision failed and the request stays pending, so the user can retry.
+   */
+  unlock: () => void;
+}

package/src/components/base/index.ts

@@ -73,6 +73,17 @@ export { CkPromptStopButton } from './CkPromptStopButton';
 export { CkPromptInput } from './CkPromptInput';
 export { CkPromptInputDisclaimer } from './CkPromptInputDisclaimer';
 export { CkRegenerateMessageButton } from './CkRegenerateMessageButton';
+export { CkToolApproval } from './CkToolApproval';
+export type {
+  CkToolApprovalProps,
+  CkToolApprovalEmits,
+  CkToolApprovalSlots,
+  CkToolApprovalRequest,
+  CkToolApprovalStatus,
+  CkToolApprovalBodyComponents,
+  CkToolApprovalBodyProps,
+  CkToolApprovalExposed,
+} from './CkToolApproval';
 export { CkUserMessage } from './CkUserMessage';
 export type { CkUserMessageProps } from './CkUserMessage';
 export { CkEditableUserMessage } from './CkEditableUserMessage';

package/src/components/index.ts

@@ -25,6 +25,7 @@ export {
   CkRegenerateMessageButton,
   CkSendIcon,
   CkStopIcon,
+  CkToolApproval,
   CkUserMessage,
   CkEditableUserMessage,
   CkMilkdownEditor,
@@ -66,6 +67,14 @@ export type {
   CkModelSelectorProps,
   CkModelSelectorEmits,
   CkPromptMenuButtonProps,
+  CkToolApprovalProps,
+  CkToolApprovalEmits,
+  CkToolApprovalSlots,
+  CkToolApprovalRequest,
+  CkToolApprovalStatus,
+  CkToolApprovalBodyComponents,
+  CkToolApprovalBodyProps,
+  CkToolApprovalExposed,
   CkUserMessageProps,
   CkEditableUserMessageProps,
   CkEditableUserMessageEmits,