@xpert-ai/chatkit-types 0.2.3 → 0.3.1

package/dist/index.cjs.map

@@ -0,0 +1 @@
+{"version":3,"file":"index.cjs","sources":["../src/interrupt.ts","../src/pet.ts"],"sourcesContent":["import { type ToolCall } from '@langchain/core/messages/tool';\n\nexport const REQUEST_USER_INPUT_TOOL_NAME = 'request_user_input';\nexport type RequestUserInputToolName = typeof REQUEST_USER_INPUT_TOOL_NAME;\nexport const REQUEST_USER_INPUT_RESULT_TYPE = 'request_user_input_result';\nexport type RequestUserInputResultType = typeof REQUEST_USER_INPUT_RESULT_TYPE;\nexport const REQUEST_USER_INPUT_RESULT_PURPOSE_PLAN_CLARIFICATION =\n  'plan_clarification';\nexport const REQUEST_USER_INPUT_RESULT_PURPOSE_IMPLEMENTATION_CONFIRMATION =\n  'implementation_confirmation';\nexport type RequestUserInputResultPurpose =\n  | typeof REQUEST_USER_INPUT_RESULT_PURPOSE_PLAN_CLARIFICATION\n  | typeof REQUEST_USER_INPUT_RESULT_PURPOSE_IMPLEMENTATION_CONFIRMATION;\n\nexport interface RequestUserInputOption {\n  label: string;\n  description: string;\n}\n\nexport interface RequestUserInputQuestion {\n  id: string;\n  header: string;\n  question: string;\n  options: RequestUserInputOption[];\n}\n\nexport interface RequestUserInputParams {\n  questions: RequestUserInputQuestion[];\n}\n\nexport type RequestUserInputToolArgs = RequestUserInputParams;\n\nexport type RequestUserInputAnswerType = 'option' | 'other';\n\nexport interface RequestUserInputAnswer {\n  id: string;\n  question: string;\n  value: string;\n  type: RequestUserInputAnswerType;\n  label?: string;\n  description?: string;\n}\n\nexport interface RequestUserInputResult {\n  type: RequestUserInputResultType;\n  purpose: RequestUserInputResultPurpose;\n  answers: RequestUserInputAnswer[];\n}\n\nexport type RequestUserInputToolCall = ToolCall & {\n  name: RequestUserInputToolName;\n  args: RequestUserInputToolArgs;\n  id: string;\n  type?: 'tool_call';\n};\n\nexport interface ClientToolRequest {\n  clientToolCalls: ToolCall[];\n}\n\nexport interface ToolCallRequest {\n  toolCalls: ToolCall[];\n}\n\nexport const HITL_DECISION_TYPES = [\n  'approve',\n  'edit',\n  'reject',\n  'respond',\n] as const;\n\nexport type HITLDecisionType = (typeof HITL_DECISION_TYPES)[number];\n\nexport interface HITLAction {\n  name: string;\n  args: Record<string, unknown>;\n}\n\nexport interface HITLActionRequest extends HITLAction {\n  description?: string;\n}\n\nexport interface HITLReviewConfig {\n  actionName: string;\n  allowedDecisions: HITLDecisionType[];\n  argsSchema?: Record<string, unknown>;\n}\n\nexport interface HITLRequest {\n  actionRequests: HITLActionRequest[];\n  reviewConfigs: HITLReviewConfig[];\n}\n\nexport interface HITLApproveDecision {\n  type: 'approve';\n}\n\nexport interface HITLEditDecision {\n  type: 'edit';\n  editedAction: HITLAction;\n}\n\nexport interface HITLRejectDecision {\n  type: 'reject';\n  message?: string;\n}\n\nexport interface HITLRespondDecision {\n  type: 'respond';\n  message: string;\n}\n\nexport type HITLDecision =\n  | HITLApproveDecision\n  | HITLEditDecision\n  | HITLRejectDecision\n  | HITLRespondDecision;\n\nexport interface HITLResponse {\n  decisions: HITLDecision[];\n}\n\nexport type InterruptRequest =\n  | ToolCallRequest\n  | ClientToolRequest\n  | HITLRequest;\n\nexport interface LangGraphInterrupt<TValue = unknown> {\n  id: string;\n  value: TValue;\n  when?: string;\n  resumable?: boolean;\n  ns?: string[];\n}\n\nexport interface LangGraphInterruptTask<TValue = unknown> {\n  id: string;\n  name: string;\n  path: Array<string | number>;\n  interrupts: Array<LangGraphInterrupt<TValue>>;\n}\n\nexport interface LangGraphInterruptPayload<TValue = unknown> {\n  tasks: Array<LangGraphInterruptTask<TValue>>;\n}\n\nexport type ClientToolInterrupt<\n  TRequest extends ClientToolRequest = ClientToolRequest,\n> = LangGraphInterrupt<TRequest>;\n\nexport type ClientToolInterruptTask<\n  TRequest extends ClientToolRequest = ClientToolRequest,\n> = LangGraphInterruptTask<TRequest>;\n\nexport type ClientToolInterruptPayload<\n  TRequest extends ClientToolRequest = ClientToolRequest,\n> = LangGraphInterruptPayload<TRequest>;\n\nexport type ToolCallInterrupt<\n  TRequest extends ToolCallRequest = ToolCallRequest,\n> = LangGraphInterrupt<TRequest>;\n\nexport type ToolCallInterruptTask<\n  TRequest extends ToolCallRequest = ToolCallRequest,\n> = LangGraphInterruptTask<TRequest>;\n\nexport type ToolCallInterruptPayload<\n  TRequest extends ToolCallRequest = ToolCallRequest,\n> = LangGraphInterruptPayload<TRequest>;\n\nexport type HITLInterrupt<TRequest extends HITLRequest = HITLRequest> =\n  LangGraphInterrupt<TRequest>;\n\nexport type HITLInterruptTask<TRequest extends HITLRequest = HITLRequest> =\n  LangGraphInterruptTask<TRequest>;\n\nexport type HITLInterruptPayload<TRequest extends HITLRequest = HITLRequest> =\n  LangGraphInterruptPayload<TRequest>;\n\n/**\n * When an interrupt occurs during task execution, the system generates an InterruptPayload.\n *\n * Ordinary tool-call interrupts use `toolCalls`; ChatKit client-tool middleware\n * uses `clientToolCalls` so the UI can route those calls to the client.\n * Human-in-the-loop interrupts use `actionRequests` and `reviewConfigs` so\n * ChatKit can collect reviewer decisions and resume with `{ decisions }`.\n```json\n{\n  \"type\": \"event\",\n  \"event\": \"on_interrupt\",\n  \"data\": {\n    \"tasks\": [\n      {\n        \"id\": \"9c4d2ac5-8808-5b6f-855c-4d48aa3d77a7\",\n        \"name\": \"Middleware_wPzR2bIXqE_after_model\",\n        \"path\": [\"__pregel_pull\", \"Middleware_wPzR2bIXqE_after_model\"],\n        \"interrupts\": [\n          {\n            \"id\": \"b42f7887d65e57ed11cf08b8927763db\",\n            \"value\": {\n              \"toolCalls\": [\n                {\n                  \"name\": \"getUserStation\",\n                  \"args\": {\n                    \"input\": \"Query the site selected by the user\"\n                  },\n                  \"id\": \"call_00_swcaUjIaACXOHHaZyNmQB3Vm\",\n                  \"type\": \"tool_call\"\n                }\n              ]\n            }\n          }\n        ]\n      }\n    ]\n  }\n}\n```\n */\nexport interface InterruptPayload extends LangGraphInterruptPayload<InterruptRequest> {}\n\nexport interface ClientToolMessageInput {\n  content: unknown;\n  name?: string;\n  tool_call_id?: string;\n  status?: 'success' | 'error';\n  artifact?: unknown;\n}\n\nexport interface ClientToolResponse {\n  toolMessages: ClientToolMessageInput[];\n}\n\nfunction isRecord(value: unknown): value is Record<string, unknown> {\n  return Boolean(value) && typeof value === 'object' && !Array.isArray(value);\n}\n\nfunction readRecordField(\n  value: Record<string, unknown>,\n  ...keys: string[]\n): Record<string, unknown> | null {\n  for (const key of keys) {\n    const field = value[key];\n    if (isRecord(field)) return field;\n  }\n\n  return null;\n}\n\nfunction readArrayField(value: Record<string, unknown>, ...keys: string[]) {\n  for (const key of keys) {\n    const field = value[key];\n    if (Array.isArray(field)) return field;\n  }\n\n  return null;\n}\n\nfunction readStringField(\n  value: Record<string, unknown>,\n  ...keys: string[]\n): string | null {\n  for (const key of keys) {\n    const field = value[key];\n    if (typeof field === 'string' && field.trim()) return field;\n  }\n\n  return null;\n}\n\nexport function isHITLDecisionType(\n  value: unknown,\n): value is HITLDecisionType {\n  return (\n    typeof value === 'string' &&\n    (HITL_DECISION_TYPES as readonly string[]).includes(value)\n  );\n}\n\nfunction normalizeHITLActionRequest(\n  value: unknown,\n): HITLActionRequest | null {\n  if (!isRecord(value)) return null;\n\n  const name = readStringField(value, 'name');\n  const args = readRecordField(value, 'args', 'arguments');\n  if (!name || !args) return null;\n\n  const description =\n    typeof value.description === 'string' ? value.description : undefined;\n\n  return {\n    name,\n    args,\n    ...(description !== undefined ? { description } : {}),\n  };\n}\n\nfunction normalizeHITLReviewConfig(\n  value: unknown,\n): HITLReviewConfig | null {\n  if (!isRecord(value)) return null;\n\n  const actionName = readStringField(value, 'actionName', 'action_name');\n  const allowedDecisions = readArrayField(\n    value,\n    'allowedDecisions',\n    'allowed_decisions',\n  );\n  if (!actionName || !allowedDecisions) return null;\n\n  const normalizedDecisions = allowedDecisions.filter(isHITLDecisionType);\n  if (normalizedDecisions.length !== allowedDecisions.length) return null;\n\n  const argsSchema = readRecordField(value, 'argsSchema', 'args_schema');\n\n  return {\n    actionName,\n    allowedDecisions: normalizedDecisions,\n    ...(argsSchema ? { argsSchema } : {}),\n  };\n}\n\nexport function normalizeHITLRequest(value: unknown): HITLRequest | null {\n  if (!isRecord(value)) return null;\n\n  const actionRequests = readArrayField(\n    value,\n    'actionRequests',\n    'action_requests',\n  );\n  const reviewConfigs = readArrayField(\n    value,\n    'reviewConfigs',\n    'review_configs',\n  );\n  if (\n    !actionRequests ||\n    !reviewConfigs ||\n    actionRequests.length === 0 ||\n    reviewConfigs.length === 0\n  ) {\n    return null;\n  }\n\n  const normalizedActionRequests = actionRequests.map(\n    normalizeHITLActionRequest,\n  );\n  const normalizedReviewConfigs = reviewConfigs.map(\n    normalizeHITLReviewConfig,\n  );\n  if (\n    normalizedActionRequests.some((request) => request === null) ||\n    normalizedReviewConfigs.some((config) => config === null)\n  ) {\n    return null;\n  }\n\n  return {\n    actionRequests: normalizedActionRequests as HITLActionRequest[],\n    reviewConfigs: normalizedReviewConfigs as HITLReviewConfig[],\n  };\n}\n\nexport function isClientToolRequest(\n  value: unknown,\n): value is ClientToolRequest {\n  return isRecord(value) && Array.isArray(value.clientToolCalls);\n}\n\nexport function isToolCallRequest(value: unknown): value is ToolCallRequest {\n  return isRecord(value) && Array.isArray(value.toolCalls);\n}\n\nexport function isHITLRequest(value: unknown): value is HITLRequest {\n  if (!isRecord(value)) return false;\n  if (\n    !Array.isArray(value.actionRequests) ||\n    !Array.isArray(value.reviewConfigs)\n  ) {\n    return false;\n  }\n\n  return normalizeHITLRequest(value) !== null;\n}\n\nexport function isInterruptRequest(value: unknown): value is InterruptRequest {\n  return (\n    isToolCallRequest(value) ||\n    isClientToolRequest(value) ||\n    isHITLRequest(value)\n  );\n}\n\nexport function isLangGraphInterrupt(\n  value: unknown,\n): value is LangGraphInterrupt {\n  return (\n    isRecord(value) &&\n    typeof value.id === 'string' &&\n    Object.prototype.hasOwnProperty.call(value, 'value')\n  );\n}\n\nexport function isLangGraphInterruptTask(\n  value: unknown,\n): value is LangGraphInterruptTask {\n  if (\n    !isRecord(value) ||\n    typeof value.id !== 'string' ||\n    typeof value.name !== 'string' ||\n    !Array.isArray(value.path) ||\n    !Array.isArray(value.interrupts)\n  ) {\n    return false;\n  }\n\n  return (\n    value.path.every(\n      (item) => typeof item === 'string' || typeof item === 'number',\n    ) && value.interrupts.every(isLangGraphInterrupt)\n  );\n}\n\nexport function isLangGraphInterruptPayload(\n  value: unknown,\n): value is LangGraphInterruptPayload {\n  return (\n    isRecord(value) &&\n    Array.isArray(value.tasks) &&\n    value.tasks.every(isLangGraphInterruptTask)\n  );\n}\n\nexport function isClientToolInterrupt(\n  value: unknown,\n): value is ClientToolInterrupt {\n  return isLangGraphInterrupt(value) && isClientToolRequest(value.value);\n}\n\nexport function isClientToolInterruptTask(\n  value: unknown,\n): value is ClientToolInterruptTask {\n  return (\n    isLangGraphInterruptTask(value) &&\n    value.interrupts.every(isClientToolInterrupt)\n  );\n}\n\nexport function isClientToolInterruptPayload(\n  value: unknown,\n): value is ClientToolInterruptPayload {\n  return (\n    isLangGraphInterruptPayload(value) &&\n    value.tasks.every(isClientToolInterruptTask)\n  );\n}\n\nexport function isToolCallInterrupt(\n  value: unknown,\n): value is ToolCallInterrupt {\n  return isLangGraphInterrupt(value) && isToolCallRequest(value.value);\n}\n\nexport function isToolCallInterruptTask(\n  value: unknown,\n): value is ToolCallInterruptTask {\n  return (\n    isLangGraphInterruptTask(value) &&\n    value.interrupts.every(isToolCallInterrupt)\n  );\n}\n\nexport function isToolCallInterruptPayload(\n  value: unknown,\n): value is ToolCallInterruptPayload {\n  return (\n    isLangGraphInterruptPayload(value) &&\n    value.tasks.every(isToolCallInterruptTask)\n  );\n}\n\nexport function isHITLInterrupt(value: unknown): value is HITLInterrupt {\n  return isLangGraphInterrupt(value) && isHITLRequest(value.value);\n}\n\nexport function isHITLInterruptTask(\n  value: unknown,\n): value is HITLInterruptTask {\n  return (\n    isLangGraphInterruptTask(value) && value.interrupts.every(isHITLInterrupt)\n  );\n}\n\nexport function isHITLInterruptPayload(\n  value: unknown,\n): value is HITLInterruptPayload {\n  return (\n    isLangGraphInterruptPayload(value) && value.tasks.every(isHITLInterruptTask)\n  );\n}\n","import type {\n  ChatKitOptions,\n  ChatKitPetAnimationName,\n  ChatKitPetBoundsPadding,\n  ChatKitPetCharacter,\n  ChatKitPetFrameAnimation,\n  ChatKitPetOptions,\n  ChatKitPetPin,\n  ChatKitPetSpriteAtlas,\n} from './options.js';\n\nexport type PetFrameAnimationDefinition = {\n  row: number;\n  frames: number;\n  frameDurations: readonly number[];\n};\n\nexport type PetSpriteAtlasDefinition = {\n  columns: number;\n  rows: number;\n  cellWidth: number;\n  cellHeight: number;\n  animations: Record<ChatKitPetAnimationName, PetFrameAnimationDefinition>;\n};\n\nexport type NormalizedPetOptions = {\n  character: ChatKitPetCharacter;\n  position: Required<\n    Pick<\n      NonNullable<ChatKitPetOptions['position']>,\n      'draggable' | 'persist' | 'scale' | 'zIndex'\n    >\n  > &\n    Pick<NonNullable<ChatKitPetOptions['position']>, 'pin' | 'boundsPadding'>;\n  behavior: NonNullable<ChatKitPetOptions['behavior']>;\n  ariaLabel: string;\n  imageRendering: NonNullable<ChatKitPetOptions['imageRendering']>;\n};\n\nexport type ResolvedPetCharacter =\n  {\n    kind: 'atlas';\n    src: string;\n    atlas: PetSpriteAtlasDefinition;\n  };\n\nexport type PetPosition = {\n  x: number;\n  y: number;\n};\n\nexport type PetSize = {\n  width: number;\n  height: number;\n};\n\nexport type PetViewport = {\n  width: number;\n  height: number;\n};\n\nexport const PET_ANIMATION_NAMES = [\n  'idle',\n  'running-right',\n  'running-left',\n  'waving',\n  'jumping',\n  'failed',\n  'waiting',\n  'running',\n  'review',\n] as const satisfies readonly ChatKitPetAnimationName[];\n\nexport const petSpriteAtlas = {\n  columns: 8,\n  rows: 9,\n  cellWidth: 192,\n  cellHeight: 208,\n  animations: {\n    idle: {\n      row: 0,\n      frames: 6,\n      frameDurations: [280, 110, 110, 140, 140, 320],\n    },\n    'running-right': {\n      row: 1,\n      frames: 8,\n      frameDurations: [120, 120, 120, 120, 120, 120, 120, 220],\n    },\n    'running-left': {\n      row: 2,\n      frames: 8,\n      frameDurations: [120, 120, 120, 120, 120, 120, 120, 220],\n    },\n    waving: {\n      row: 3,\n      frames: 4,\n      frameDurations: [140, 140, 140, 280],\n    },\n    jumping: {\n      row: 4,\n      frames: 5,\n      frameDurations: [140, 140, 140, 140, 280],\n    },\n    failed: {\n      row: 5,\n      frames: 8,\n      frameDurations: [140, 140, 140, 140, 140, 140, 140, 240],\n    },\n    waiting: {\n      row: 6,\n      frames: 6,\n      frameDurations: [150, 150, 150, 150, 150, 260],\n    },\n    running: {\n      row: 7,\n      frames: 6,\n      frameDurations: [120, 120, 120, 120, 120, 220],\n    },\n    review: {\n      row: 8,\n      frames: 6,\n      frameDurations: [150, 150, 150, 150, 150, 280],\n    },\n  },\n} as const satisfies PetSpriteAtlasDefinition;\n\nexport const DEFAULT_PET_SIZE = {\n  width: petSpriteAtlas.cellWidth,\n  height: petSpriteAtlas.cellHeight,\n};\n\nexport const DEFAULT_PET_BOUNDS_PADDING: ChatKitPetBoundsPadding = {\n  top: 0,\n  right: 0,\n  bottom: 0,\n  left: 0,\n};\n\nexport const DEFAULT_PET_STORAGE_KEY = 'chatkit:pet:position:v1';\n\nexport const DEFAULT_PET_SPRITESHEET_URL = '/pets/boba/spritesheet.webp';\n\nconst DEFAULT_PET_CHARACTER = {\n  type: 'sprite-atlas',\n  src: DEFAULT_PET_SPRITESHEET_URL,\n} as const satisfies ChatKitPetCharacter;\n\nconst DEFAULT_POSITION = {\n  pin: 'bottom-right',\n  draggable: true,\n  scale: 0.25,\n  persist: true,\n  zIndex: 40,\n} as const satisfies NormalizedPetOptions['position'];\n\nfunction mergeFrameAnimation(\n  base: PetFrameAnimationDefinition,\n  override?: ChatKitPetFrameAnimation,\n): PetFrameAnimationDefinition {\n  return {\n    row: override?.row ?? base.row,\n    frames: override?.frames ?? base.frames,\n    frameDurations:\n      override?.frameDurations && override.frameDurations.length > 0\n        ? override.frameDurations\n        : base.frameDurations,\n  };\n}\n\nexport function mergePetSpriteAtlas(\n  override?: ChatKitPetSpriteAtlas,\n): PetSpriteAtlasDefinition {\n  const animations = {} as Record<\n    ChatKitPetAnimationName,\n    PetFrameAnimationDefinition\n  >;\n\n  for (const name of PET_ANIMATION_NAMES) {\n    animations[name] = mergeFrameAnimation(\n      petSpriteAtlas.animations[name],\n      override?.animations?.[name],\n    );\n  }\n\n  return {\n    columns: override?.columns ?? petSpriteAtlas.columns,\n    rows: override?.rows ?? petSpriteAtlas.rows,\n    cellWidth: override?.cellWidth ?? petSpriteAtlas.cellWidth,\n    cellHeight: override?.cellHeight ?? petSpriteAtlas.cellHeight,\n    animations,\n  };\n}\n\nfunction normalizeCharacter(\n  character: ChatKitPetCharacter | undefined,\n): ChatKitPetCharacter {\n  if (!character) {\n    return DEFAULT_PET_CHARACTER;\n  }\n\n  if (character.src) {\n    return character;\n  }\n\n  return DEFAULT_PET_CHARACTER;\n}\n\nexport function normalizePetOptions(\n  pet: ChatKitOptions['pet'] | null,\n): NormalizedPetOptions | null {\n  if (!pet) {\n    return null;\n  }\n\n  if (pet === true) {\n    return {\n      character: DEFAULT_PET_CHARACTER,\n      position: DEFAULT_POSITION,\n      behavior: 'auto',\n      ariaLabel: 'Animated pet',\n      imageRendering: 'auto',\n    };\n  }\n\n  if (pet.enabled === false) {\n    return null;\n  }\n\n  return {\n    character: normalizeCharacter(pet.character),\n    position: {\n      ...DEFAULT_POSITION,\n      ...pet.position,\n    },\n    behavior: pet.behavior ?? 'auto',\n    ariaLabel: pet.ariaLabel ?? 'Animated pet',\n    imageRendering: pet.imageRendering ?? 'auto',\n  };\n}\n\nexport function resolvePetCharacter(\n  character: ChatKitPetCharacter,\n): ResolvedPetCharacter | null {\n  if (!character.src) {\n    return null;\n  }\n\n  return {\n    kind: 'atlas',\n    src: character.src,\n    atlas: mergePetSpriteAtlas(character.atlas),\n  };\n}\n\nexport function normalizeBoundsPadding(\n  value?: number | Partial<ChatKitPetBoundsPadding>,\n): ChatKitPetBoundsPadding {\n  if (typeof value === 'number') {\n    return {\n      top: value,\n      right: value,\n      bottom: value,\n      left: value,\n    };\n  }\n\n  return {\n    top: value?.top ?? DEFAULT_PET_BOUNDS_PADDING.top,\n    right: value?.right ?? DEFAULT_PET_BOUNDS_PADDING.right,\n    bottom: value?.bottom ?? DEFAULT_PET_BOUNDS_PADDING.bottom,\n    left: value?.left ?? DEFAULT_PET_BOUNDS_PADDING.left,\n  };\n}\n\nexport function clampPetPosition(\n  position: PetPosition,\n  size: PetSize,\n  viewport: PetViewport,\n  padding: ChatKitPetBoundsPadding,\n): PetPosition {\n  const minX = padding.left;\n  const minY = padding.top;\n  const maxX = Math.max(minX, viewport.width - size.width - padding.right);\n  const maxY = Math.max(minY, viewport.height - size.height - padding.bottom);\n\n  return {\n    x: Math.min(maxX, Math.max(minX, position.x)),\n    y: Math.min(maxY, Math.max(minY, position.y)),\n  };\n}\n\nexport function getPinnedPetPosition(\n  pin: ChatKitPetPin,\n  size: PetSize,\n  viewport: PetViewport,\n  padding: ChatKitPetBoundsPadding,\n): PetPosition {\n  const horizontalCenter = (viewport.width - size.width) / 2;\n  const verticalCenter = (viewport.height - size.height) / 2;\n  const right = viewport.width - size.width - padding.right;\n  const bottom = viewport.height - size.height - padding.bottom;\n\n  switch (pin) {\n    case 'top-left':\n      return clampPetPosition(\n        { x: padding.left, y: padding.top },\n        size,\n        viewport,\n        padding,\n      );\n    case 'top':\n      return clampPetPosition(\n        { x: horizontalCenter, y: padding.top },\n        size,\n        viewport,\n        padding,\n      );\n    case 'top-right':\n      return clampPetPosition(\n        { x: right, y: padding.top },\n        size,\n        viewport,\n        padding,\n      );\n    case 'left':\n      return clampPetPosition(\n        { x: padding.left, y: verticalCenter },\n        size,\n        viewport,\n        padding,\n      );\n    case 'center':\n      return clampPetPosition(\n        { x: horizontalCenter, y: verticalCenter },\n        size,\n        viewport,\n        padding,\n      );\n    case 'right':\n      return clampPetPosition(\n        { x: right, y: verticalCenter },\n        size,\n        viewport,\n        padding,\n      );\n    case 'bottom-left':\n      return clampPetPosition(\n        { x: padding.left, y: bottom },\n        size,\n        viewport,\n        padding,\n      );\n    case 'bottom':\n      return clampPetPosition(\n        { x: horizontalCenter, y: bottom },\n        size,\n        viewport,\n        padding,\n      );\n    case 'bottom-right':\n    default:\n      return clampPetPosition({ x: right, y: bottom }, size, viewport, padding);\n  }\n}\n"],"names":[],"mappings":"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"}

package/dist/index.d.ts

@@ -197,6 +197,15 @@ export declare type ChatKitCodeReference = ChatKitReferenceBase & {
     taskId?: string;
 };
 
+export declare type ChatKitCommandSource = {
+    type: 'slash_command';
+    name: string;
+    source: 'builtin' | 'host' | 'runtime';
+    executionType: ChatKitSlashCommandExecutionType;
+    kind?: ChatKitSlashCommandKind;
+    workflow?: ChatKitPromptWorkflow;
+};
+
 export declare interface ChatKitElementEventMap {
     'chatkit.error': CustomEvent<{
         error: Error;
@@ -278,6 +287,14 @@ export declare type ChatKitOptions = {
      * ChatKit iframe URL for web component integrations.
      */
     frameUrl?: string;
+    /**
+     * Controls how the ChatKit web component is presented.
+     * - `chat`: render the ChatKit iframe in the host layout.
+     * - `pet`: render only the pet launcher until the user clicks the pet.
+     *
+     * @default "chat"
+     */
+    displayMode?: 'chat' | 'pet';
     api: CustomApiConfig | HostedApiConfig;
     /**
      * Default request values that should be injected into every user message sent
@@ -296,6 +313,14 @@ export declare type ChatKitOptions = {
      * * @default "light"
      */
     theme?: ColorScheme | ChatKitTheme;
+    /**
+     * Optional animated pet companion rendered by the ChatKit web component over
+     * the host page viewport.
+     * Passing `true` enables the default built-in pet.
+     *
+     * @default false
+     */
+    pet?: boolean | ChatKitPetOptions;
     /**
      * The ID of the thread to show when ChatKit is mounted or opened for the first time.
      * Passing `null` will show the new thread view.
@@ -434,6 +459,11 @@ export declare type ChatKitOptions = {
         tools?: ToolOption[];
         /** A list of models that users can choose from before sending a message. */
         models?: ModelOption[];
+        /**
+         * Slash commands shown when users type `/` at the start of the composer.
+         * Command names should not include the leading slash.
+         */
+        slashCommands?: ChatKitSlashCommand[];
     };
     /**
      * Disclaimer text to display below the composer. Supports links with markdown formatting.
@@ -464,6 +494,65 @@ export declare type ChatKitOptions = {
     };
 };
 
+export declare type ChatKitPetAnimationMode = 'loop' | 'once';
+
+export declare type ChatKitPetAnimationName = 'idle' | 'running-right' | 'running-left' | 'waving' | 'jumping' | 'failed' | 'waiting' | 'running' | 'review';
+
+export declare type ChatKitPetBoundsPadding = {
+    top: number;
+    right: number;
+    bottom: number;
+    left: number;
+};
+
+export declare type ChatKitPetCharacter = {
+    type: 'sprite-atlas';
+    src: string;
+    atlas?: ChatKitPetSpriteAtlas;
+};
+
+export declare type ChatKitPetFrameAnimation = {
+    row?: number;
+    frames?: number;
+    frameDurations?: readonly number[];
+};
+
+export declare type ChatKitPetOptions = {
+    enabled?: boolean;
+    character?: ChatKitPetCharacter;
+    position?: ChatKitPetPositionOptions;
+    behavior?: 'auto' | 'manual';
+    ariaLabel?: string;
+    imageRendering?: 'auto' | 'pixelated' | 'crisp-edges';
+};
+
+export declare type ChatKitPetPin = 'top-left' | 'top' | 'top-right' | 'left' | 'center' | 'right' | 'bottom-left' | 'bottom' | 'bottom-right';
+
+export declare type ChatKitPetPositionOptions = {
+    pin?: ChatKitPetPin | null;
+    draggable?: boolean;
+    scale?: number;
+    persist?: boolean;
+    boundsPadding?: number | Partial<ChatKitPetBoundsPadding>;
+    zIndex?: number;
+};
+
+export declare type ChatKitPetSpriteAtlas = {
+    columns?: number;
+    rows?: number;
+    cellWidth?: number;
+    cellHeight?: number;
+    animations?: Partial<Record<ChatKitPetAnimationName, ChatKitPetFrameAnimation>>;
+};
+
+export declare type ChatKitPromptWorkflow = {
+    type: 'prompt_workflow';
+    name?: string;
+    label?: string;
+    description?: string;
+    tags?: string[];
+};
+
 export declare type ChatKitQuoteReference = ChatKitReferenceBase & {
     type: 'quote';
     messageId?: string;
@@ -512,6 +601,70 @@ export declare type ChatKitRequestOptions<TState = Record<string, any>, TContext
     config?: TConfig;
 };
 
+export declare type ChatKitSlashCommand = {
+    /**
+     * Command name without the leading slash.
+     * Valid names use lowercase letters, digits, hyphens, and underscores.
+     */
+    name: string;
+    label?: string;
+    description?: string;
+    icon?: string | Record<string, unknown>;
+    category?: string;
+    aliases?: string[];
+    argsHint?: string;
+    availability?: ChatKitSlashCommandAvailability;
+    kind?: ChatKitSlashCommandKind;
+    workflow?: ChatKitPromptWorkflow;
+    action: ChatKitSlashCommandAction;
+    source?: Record<string, unknown>;
+    meta?: Record<string, unknown>;
+};
+
+export declare type ChatKitSlashCommandAction = {
+    type: 'insert_text';
+    template: string;
+    runtimeCapabilities?: unknown;
+} | {
+    type: 'insert_invocation';
+    template: string;
+    runtimeCapabilities?: unknown;
+} | {
+    type: 'submit_prompt';
+    template: string;
+    runtimeCapabilities?: unknown;
+} | {
+    type: 'client_action';
+    action: {
+        type: string;
+        payload?: Record<string, unknown>;
+    };
+} | {
+    type: 'select_capability';
+    capability: ChatKitSlashCommandCapability;
+};
+
+export declare type ChatKitSlashCommandAvailability = {
+    disabled?: boolean;
+    reason?: string;
+    [key: string]: unknown;
+};
+
+export declare type ChatKitSlashCommandCapability = {
+    type: 'skill';
+    id: string;
+} | {
+    type: 'plugin';
+    id: string;
+} | {
+    type: 'subAgent';
+    id: string;
+};
+
+export declare type ChatKitSlashCommandExecutionType = 'insert_text' | 'insert_invocation' | 'submit_prompt' | 'client_action' | 'select_capability';
+
+export declare type ChatKitSlashCommandKind = 'command' | 'prompt_workflow';
+
 export declare type ChatKitTheme = {
     /**
      * The color scheme to use for the ChatKit UI.
@@ -629,6 +782,8 @@ export declare type Checkbox = {
     required?: boolean;
 };
 
+export declare function clampPetPosition(position: PetPosition, size: PetSize, viewport: PetViewport, padding: ChatKitPetBoundsPadding): PetPosition;
+
 export declare type ClientToolInterrupt<TRequest extends ClientToolRequest = ClientToolRequest> = LangGraphInterrupt<TRequest>;
 
 export declare type ClientToolInterruptPayload<TRequest extends ClientToolRequest = ClientToolRequest> = LangGraphInterruptPayload<TRequest>;
@@ -717,6 +872,17 @@ export declare type DatePicker = {
     disabled?: boolean;
 };
 
+export declare const DEFAULT_PET_BOUNDS_PADDING: ChatKitPetBoundsPadding;
+
+export declare const DEFAULT_PET_SIZE: {
+    width: 192;
+    height: 208;
+};
+
+export declare const DEFAULT_PET_SPRITESHEET_URL = "/pets/boba/spritesheet.webp";
+
+export declare const DEFAULT_PET_STORAGE_KEY = "chatkit:pet:position:v1";
+
 export declare type Divider = {
     type: 'Divider';
     key?: string;
@@ -788,6 +954,8 @@ export declare type Form = {
     direction?: 'row' | 'col';
 } & BoxBaseProps;
 
+export declare function getPinnedPetPosition(pin: ChatKitPetPin, size: PetSize, viewport: PetViewport, padding: ChatKitPetBoundsPadding): PetPosition;
+
 export declare type GrayscaleOptions = {
     hue: number;
     tint: 0 | 1 | 2 | 3 | 4 | 5 | 6 | 7 | 8 | 9;
@@ -796,6 +964,61 @@ export declare type GrayscaleOptions = {
 
 export declare type HeaderIcon = 'sidebar-left' | 'sidebar-right' | 'sidebar-open-left' | 'sidebar-open-right' | 'sidebar-open-left-alt' | 'sidebar-open-right-alt' | 'sidebar-floating-left' | 'sidebar-floating-right' | 'sidebar-floating-open-left' | 'sidebar-floating-open-right' | 'sidebar-collapse-left' | 'sidebar-collapse-right' | 'collapse-left' | 'collapse-right' | 'open-left' | 'open-right' | 'double-chevron-left' | 'double-chevron-right' | 'home' | 'home-alt' | 'back-small' | 'back-large' | 'expand-large' | 'collapse-large' | 'expand-small' | 'collapse-small' | 'star' | 'star-filled' | 'chat-temporary' | 'settings-cog' | 'grid' | 'dots-horizontal' | 'dots-vertical' | 'dots-horizontal-circle' | 'dots-vertical-circle' | 'menu' | 'menu-inverted' | 'hamburger' | 'compose' | 'light-mode' | 'dark-mode' | 'close';
 
+export declare const HITL_DECISION_TYPES: readonly ["approve", "edit", "reject", "respond"];
+
+export declare interface HITLAction {
+    name: string;
+    args: Record<string, unknown>;
+}
+
+export declare interface HITLActionRequest extends HITLAction {
+    description?: string;
+}
+
+export declare interface HITLApproveDecision {
+    type: 'approve';
+}
+
+export declare type HITLDecision = HITLApproveDecision | HITLEditDecision | HITLRejectDecision | HITLRespondDecision;
+
+export declare type HITLDecisionType = (typeof HITL_DECISION_TYPES)[number];
+
+export declare interface HITLEditDecision {
+    type: 'edit';
+    editedAction: HITLAction;
+}
+
+export declare type HITLInterrupt<TRequest extends HITLRequest = HITLRequest> = LangGraphInterrupt<TRequest>;
+
+export declare type HITLInterruptPayload<TRequest extends HITLRequest = HITLRequest> = LangGraphInterruptPayload<TRequest>;
+
+export declare type HITLInterruptTask<TRequest extends HITLRequest = HITLRequest> = LangGraphInterruptTask<TRequest>;
+
+export declare interface HITLRejectDecision {
+    type: 'reject';
+    message?: string;
+}
+
+export declare interface HITLRequest {
+    actionRequests: HITLActionRequest[];
+    reviewConfigs: HITLReviewConfig[];
+}
+
+export declare interface HITLRespondDecision {
+    type: 'respond';
+    message: string;
+}
+
+export declare interface HITLResponse {
+    decisions: HITLDecision[];
+}
+
+export declare interface HITLReviewConfig {
+    actionName: string;
+    allowedDecisions: HITLDecisionType[];
+    argsSchema?: Record<string, unknown>;
+}
+
 declare type HostedApiConfig = {
     /**
      * Function to get a client token or refresh if the current token is expired.
@@ -864,6 +1087,8 @@ export declare type Input = {
  *
  * Ordinary tool-call interrupts use `toolCalls`; ChatKit client-tool middleware
  * uses `clientToolCalls` so the UI can route those calls to the client.
+ * Human-in-the-loop interrupts use `actionRequests` and `reviewConfigs` so
+ * ChatKit can collect reviewer decisions and resume with `{ decisions }`.
  ```json
  {
  "type": "event",
@@ -900,7 +1125,7 @@ export declare type Input = {
 export declare interface InterruptPayload extends LangGraphInterruptPayload<InterruptRequest> {
 }
 
-export declare type InterruptRequest = ToolCallRequest | ClientToolRequest;
+export declare type InterruptRequest = ToolCallRequest | ClientToolRequest | HITLRequest;
 
 export declare function isClientToolInterrupt(value: unknown): value is ClientToolInterrupt;
 
@@ -910,6 +1135,16 @@ export declare function isClientToolInterruptTask(value: unknown): value is Clie
 
 export declare function isClientToolRequest(value: unknown): value is ClientToolRequest;
 
+export declare function isHITLDecisionType(value: unknown): value is HITLDecisionType;
+
+export declare function isHITLInterrupt(value: unknown): value is HITLInterrupt;
+
+export declare function isHITLInterruptPayload(value: unknown): value is HITLInterruptPayload;
+
+export declare function isHITLInterruptTask(value: unknown): value is HITLInterruptTask;
+
+export declare function isHITLRequest(value: unknown): value is HITLRequest;
+
 export declare function isInterruptRequest(value: unknown): value is InterruptRequest;
 
 export declare function isLangGraphInterrupt(value: unknown): value is LangGraphInterrupt;
@@ -987,6 +1222,8 @@ export declare type Markdown = {
     streaming?: boolean;
 };
 
+export declare function mergePetSpriteAtlas(override?: ChatKitPetSpriteAtlas): PetSpriteAtlasDefinition;
+
 export declare type MessageContentImageUrl = {
     type: 'image_url';
     image_url: string | {
@@ -1013,6 +1250,105 @@ export declare type ModelOption = {
     default?: boolean;
 };
 
+export declare function normalizeBoundsPadding(value?: number | Partial<ChatKitPetBoundsPadding>): ChatKitPetBoundsPadding;
+
+export declare type NormalizedPetOptions = {
+    character: ChatKitPetCharacter;
+    position: Required<Pick<NonNullable<ChatKitPetOptions['position']>, 'draggable' | 'persist' | 'scale' | 'zIndex'>> & Pick<NonNullable<ChatKitPetOptions['position']>, 'pin' | 'boundsPadding'>;
+    behavior: NonNullable<ChatKitPetOptions['behavior']>;
+    ariaLabel: string;
+    imageRendering: NonNullable<ChatKitPetOptions['imageRendering']>;
+};
+
+export declare function normalizeHITLRequest(value: unknown): HITLRequest | null;
+
+export declare function normalizePetOptions(pet: ChatKitOptions['pet'] | null): NormalizedPetOptions | null;
+
+export declare const PET_ANIMATION_NAMES: readonly ["idle", "running-right", "running-left", "waving", "jumping", "failed", "waiting", "running", "review"];
+
+export declare type PetFrameAnimationDefinition = {
+    row: number;
+    frames: number;
+    frameDurations: readonly number[];
+};
+
+export declare type PetPosition = {
+    x: number;
+    y: number;
+};
+
+export declare type PetSize = {
+    width: number;
+    height: number;
+};
+
+export declare const petSpriteAtlas: {
+    readonly columns: 8;
+    readonly rows: 9;
+    readonly cellWidth: 192;
+    readonly cellHeight: 208;
+    readonly animations: {
+        readonly idle: {
+            readonly row: 0;
+            readonly frames: 6;
+            readonly frameDurations: readonly [280, 110, 110, 140, 140, 320];
+        };
+        readonly 'running-right': {
+            readonly row: 1;
+            readonly frames: 8;
+            readonly frameDurations: readonly [120, 120, 120, 120, 120, 120, 120, 220];
+        };
+        readonly 'running-left': {
+            readonly row: 2;
+            readonly frames: 8;
+            readonly frameDurations: readonly [120, 120, 120, 120, 120, 120, 120, 220];
+        };
+        readonly waving: {
+            readonly row: 3;
+            readonly frames: 4;
+            readonly frameDurations: readonly [140, 140, 140, 280];
+        };
+        readonly jumping: {
+            readonly row: 4;
+            readonly frames: 5;
+            readonly frameDurations: readonly [140, 140, 140, 140, 280];
+        };
+        readonly failed: {
+            readonly row: 5;
+            readonly frames: 8;
+            readonly frameDurations: readonly [140, 140, 140, 140, 140, 140, 140, 240];
+        };
+        readonly waiting: {
+            readonly row: 6;
+            readonly frames: 6;
+            readonly frameDurations: readonly [150, 150, 150, 150, 150, 260];
+        };
+        readonly running: {
+            readonly row: 7;
+            readonly frames: 6;
+            readonly frameDurations: readonly [120, 120, 120, 120, 120, 220];
+        };
+        readonly review: {
+            readonly row: 8;
+            readonly frames: 6;
+            readonly frameDurations: readonly [150, 150, 150, 150, 150, 280];
+        };
+    };
+};
+
+export declare type PetSpriteAtlasDefinition = {
+    columns: number;
+    rows: number;
+    cellWidth: number;
+    cellHeight: number;
+    animations: Record<ChatKitPetAnimationName, PetFrameAnimationDefinition>;
+};
+
+export declare type PetViewport = {
+    width: number;
+    height: number;
+};
+
 export declare type RadioGroup = {
     type: 'RadioGroup';
     key?: string;
@@ -1089,6 +1425,14 @@ export declare type RequestUserInputToolCall = ToolCall & {
 
 export declare type RequestUserInputToolName = typeof REQUEST_USER_INPUT_TOOL_NAME;
 
+export declare type ResolvedPetCharacter = {
+    kind: 'atlas';
+    src: string;
+    atlas: PetSpriteAtlasDefinition;
+};
+
+export declare function resolvePetCharacter(character: ChatKitPetCharacter): ResolvedPetCharacter | null;
+
 export declare type Row = {
     type: 'Row';
     key?: string;
@@ -1207,9 +1551,7 @@ export declare type TChatRequest = {
     /**
      * Custom graph state
      */
-    state?: {
-        [STATE_VARIABLE_HUMAN]: TChatRequestHuman;
-    } & Record<string, any>;
+    state?: TXpertChatState;
     agentKey?: string;
     projectId?: string;
     conversationId?: string;
@@ -1237,6 +1579,7 @@ export declare type TChatRequestHuman = {
     referenceComposition?: ChatKitReferenceCompositionMode;
     planMode?: boolean;
     runtimeCapabilities?: RuntimeCapabilitiesSelection;
+    commandSource?: ChatKitCommandSource;
     [key: string]: unknown;
 };
 
@@ -1505,6 +1848,31 @@ export declare type TThreadContextUsageMetrics = {
     currency?: string | null;
 };
 
+export declare type TXpertChatInterruptPatch = Pick<TInterruptCommand, 'agentKey' | 'toolCalls' | 'update'>;
+
+export declare type TXpertChatResumeDecision = {
+    type: 'confirm' | 'reject';
+    payload?: unknown;
+};
+
+export declare type TXpertChatResumeRequest = {
+    action: 'resume';
+    conversationId: string;
+    target: TXpertChatTarget;
+    decision: TXpertChatResumeDecision;
+    patch?: TXpertChatInterruptPatch;
+    state?: TXpertChatState;
+};
+
+export declare type TXpertChatState = {
+    [STATE_VARIABLE_HUMAN]?: TChatRequestHuman;
+} & Record<string, any>;
+
+export declare type TXpertChatTarget = {
+    aiMessageId?: string;
+    executionId?: string;
+};
+
 export declare type UserMessageContent = unknown;
 
 export declare type WidgetComponent = TextComponent | Title | Caption | Badge | Markdown | Box | Row | Col | Divider | Icon | Image_2 | Button | Checkbox | Spacer | Select | DatePicker | Form | Input | Label | RadioGroup | Textarea | Transition;